diff options
Diffstat (limited to 'man/systemd.mount.xml')
| -rw-r--r-- | man/systemd.mount.xml | 545 |
1 files changed, 545 insertions, 0 deletions
diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml new file mode 100644 index 0000000..61e97b1 --- /dev/null +++ b/man/systemd.mount.xml @@ -0,0 +1,545 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + +<!-- + SPDX-License-Identifier: LGPL-2.1+ +--> + +<refentry id="systemd.mount"> + <refentryinfo> + <title>systemd.mount</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd.mount</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd.mount</refname> + <refpurpose>Mount unit configuration</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename><replaceable>mount</replaceable>.mount</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>A unit configuration file whose name ends in + <literal>.mount</literal> encodes information about a file system + mount point controlled and supervised by systemd.</para> + + <para>This man page lists the configuration options specific to + this unit type. See + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for the common options of all unit configuration files. The common + configuration items are configured in the generic [Unit] and + [Install] sections. The mount specific configuration options are + configured in the [Mount] section.</para> + + <para>Additional options are listed in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the execution environment the + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + program is executed in, and in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which define the way the processes are terminated, and in + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which configure resource control settings for the processes of the + service.</para> + + <para>Note that the options <varname>User=</varname> and + <varname>Group=</varname> are not useful for mount units. + systemd passes two parameters to + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>; + the values of <varname>What=</varname> and <varname>Where=</varname>. + When invoked in this way, + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + does not read any options from <filename>/etc/fstab</filename>, and + must be run as UID 0.</para> + + <para>Mount units must be named after the mount point directories they control. Example: the mount point <filename + noindex='true'>/home/lennart</filename> must be configured in a unit file <filename>home-lennart.mount</filename>. + For details about the escaping logic used to convert a file system path to a unit name, see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount + units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to + it.</para> + + <para>Optionally, a mount unit may be accompanied by an automount + unit, to allow on-demand or parallelized mounting. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> + + <para>Mount points created at runtime (independently of unit files + or <filename>/etc/fstab</filename>) will be monitored by systemd + and appear like any other mount unit in systemd. See + <filename>/proc/self/mountinfo</filename> description in + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>Some file systems have special semantics as API file systems + for kernel-to-userspace and userspace-to-userspace interfaces. Some + of them may not be changed via mount units, and cannot be + disabled. For a longer discussion see <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API + File Systems</ulink>.</para> + </refsect1> + + <refsect1> + <title>Automatic Dependencies</title> + + <refsect2> + <title>Implicit Dependencies</title> + + <para>The following dependencies are implicitly added:</para> + + <itemizedlist> + <listitem><para>If a mount unit is beneath another mount unit in the file + system hierarchy, both a requirement dependency and an ordering + dependency between both units are created automatically.</para></listitem> + + <listitem><para>Block device backed file systems automatically gain + <varname>BindsTo=</varname> and <varname>After=</varname> type + dependencies on the device unit encapsulating the block + device (see below).</para></listitem> + + <listitem><para>If traditional file system quota is enabled for a mount + unit, automatic <varname>Wants=</varname> and + <varname>Before=</varname> dependencies on + <filename>systemd-quotacheck.service</filename> and + <filename>quotaon.service</filename> are added.</para></listitem> + + <listitem><para>Additional implicit dependencies may be added as result of + execution and resource control parameters as documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </itemizedlist> + </refsect2> + + <refsect2> + <title>Default Dependencies</title> + + <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para> + + <itemizedlist> + <listitem><para>All mount units acquire automatic <varname>Before=</varname> and <varname>Conflicts=</varname> on + <filename>umount.target</filename> in order to be stopped during shutdown.</para></listitem> + + <listitem><para>Mount units referring to local file systems automatically gain + an <varname>After=</varname> dependency on <filename>local-fs-pre.target</filename>, and a + <varname>Before=</varname> dependency on <filename>local-fs.target</filename> unless + <option>nofail</option> mount option is set.</para></listitem> + + <listitem><para>Network mount units + automatically acquire <varname>After=</varname> dependencies on <filename>remote-fs-pre.target</filename>, + <filename>network.target</filename> and <filename>network-online.target</filename>, and gain a + <varname>Before=</varname> dependency on <filename>remote-fs.target</filename> unless + <option>nofail</option> mount option is set. Towards the latter a + <varname>Wants=</varname> unit is added as well.</para></listitem> + </itemizedlist> + + <para>Mount units referring to local and network file systems are distinguished by their file system type + specification. In some cases this is not sufficient (for example network block device based mounts, such as + iSCSI), in which case <option>_netdev</option> may be added to the mount option string of the unit, which forces + systemd to consider the mount unit a network mount.</para> + </refsect2> + </refsect1> + + <refsect1> + <title><filename>fstab</filename></title> + + <para>Mount units may either be configured via unit files, or via + <filename>/etc/fstab</filename> (see + <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details). Mounts listed in <filename>/etc/fstab</filename> + will be converted into native units dynamically at boot and when + the configuration of the system manager is reloaded. In general, + configuring mount points through <filename>/etc/fstab</filename> + is the preferred approach. See + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details about the conversion.</para> + + <para>The NFS mount option <option>bg</option> for NFS background mounts + as documented in <citerefentry project='man-pages'><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> + is detected by <command>systemd-fstab-generator</command> and the options + are transformed so that systemd fulfills the job-control implications of + that option. Specifically <command>systemd-fstab-generator</command> acts + as though <literal>x-systemd.mount-timeout=infinity,retry=10000</literal> was + prepended to the option list, and <literal>fg,nofail</literal> was appended. + Depending on specific requirements, it may be appropriate to provide some of + these options explicitly, or to make use of the + <literal>x-systemd.automount</literal> option described below instead + of using <literal>bg</literal>.</para> + + <para>When reading <filename>/etc/fstab</filename> a few special + mount options are understood by systemd which influence how + dependencies are created for mount points. systemd will create a + dependency of type <varname>Wants=</varname> or + <option>Requires</option> (see option <option>nofail</option> + below), from either <filename>local-fs.target</filename> or + <filename>remote-fs.target</filename>, depending whether the file + system is local or remote.</para> + + <variablelist class='fstab-options'> + + <varlistentry> + <term><option>x-systemd.requires=</option></term> + + <listitem><para>Configures a <varname>Requires=</varname> and + an <varname>After=</varname> dependency between the created + mount unit and another systemd unit, such as a device or mount + unit. The argument should be a unit name, or an absolute path + to a device node or mount point. This option may be specified + more than once. This option is particularly useful for mount + point declarations that need an additional device to be around + (such as an external journal device for journal file systems) + or an additional mount to be in place (such as an overlay file + system that merges multiple mount points). See + <varname>After=</varname> and <varname>Requires=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.before=</option></term> + <term><option>x-systemd.after=</option></term> + + <listitem><para>Configures a <varname>Before=</varname> + dependency or <varname>After=</varname> between the created + mount unit and another systemd unit, such as a mount unit. + The argument should be a unit name or an absolute path + to a mount point. This option may be specified more than once. + This option is particularly useful for mount point declarations + with <option>nofail</option> option that are mounted + asynchronously but need to be mounted before or after some unit + start, for example, before <filename>local-fs.target</filename> + unit. + See <varname>Before=</varname> and <varname>After=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.requires-mounts-for=</option></term> + + <listitem><para>Configures a + <varname>RequiresMountsFor=</varname> dependency between the + created mount unit and other mount units. The argument must be + an absolute path. This option may be specified more than once. + See <varname>RequiresMountsFor=</varname> in + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.device-bound</option></term> + + <listitem><para>The block device backed file system will be upgraded + to <varname>BindsTo=</varname> dependency. This option is only useful + when mounting file systems manually with + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + as the default dependency in this case is <varname>Requires=</varname>. + This option is already implied by entries in <filename>/etc/fstab</filename> + or by mount units. + </para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.automount</option></term> + + <listitem><para>An automount unit will be created for the file + system. See + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.idle-timeout=</option></term> + + <listitem><para>Configures the idle timeout of the + automount unit. See <varname>TimeoutIdleSec=</varname> in + <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for details.</para></listitem> + </varlistentry> + + <varlistentry id='device-timeout'> + <term><option>x-systemd.device-timeout=</option></term> + + <listitem><para>Configure how long systemd should wait for a + device to show up before giving up on an entry from + <filename>/etc/fstab</filename>. Specify a time in seconds or + explicitly append a unit such as <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>ms</literal>.</para> + + <para>Note that this option can only be used in + <filename>/etc/fstab</filename>, and will be + ignored when part of the <varname>Options=</varname> + setting in a unit file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.mount-timeout=</option></term> + + <listitem><para>Configure how long systemd should wait for the + mount command to finish before giving up on an entry from + <filename>/etc/fstab</filename>. Specify a time in seconds or + explicitly append a unit such as <literal>s</literal>, + <literal>min</literal>, <literal>h</literal>, + <literal>ms</literal>.</para> + + <para>Note that this option can only be used in + <filename>/etc/fstab</filename>, and will be + ignored when part of the <varname>Options=</varname> + setting in a unit file.</para> + + <para>See <varname>TimeoutSec=</varname> below for + details.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.makefs</option></term> + + <listitem><para>The file system will be initialized + on the device. If the device is not "empty", i.e. it contains any signature, + the operation will be skipped. It is hence expected that this option + remains set even after the device has been initalized.</para> + + <para>Note that this option can only be used in + <filename>/etc/fstab</filename>, and will be ignored when part of the + <varname>Options=</varname> setting in a unit file.</para> + + <para>See + <citerefentry><refentrytitle>systemd-makefs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + </para> + + <para><citerefentry project='man-pages'><refentrytitle>wipefs</refentrytitle><manvolnum>8</manvolnum></citerefentry> + may be used to remove any signatures from a block device to force + <option>x-systemd.makefs</option> to reinitialize the device.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>x-systemd.growfs</option></term> + + <listitem><para>The file system will be grown to occupy the full block + device. If the file system is already at maximum size, no action will + be performed. It is hence expected that this option remains set even after + the file system has been grown. Only certain file system types are supported, + see + <citerefentry><refentrytitle>systemd-makefs@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para> + + <para>Note that this option can only be used in + <filename>/etc/fstab</filename>, and will be ignored when part of the + <varname>Options=</varname> setting in a unit file.</para></listitem> + </varlistentry> + + <varlistentry> + <term><option>_netdev</option></term> + + <listitem><para>Normally the file system type is used to determine if a + mount is a "network mount", i.e. if it should only be started after the + network is available. Using this option overrides this detection and + specifies that the mount requires network.</para> + + <para>Network mount units are ordered between <filename>remote-fs-pre.target</filename> + and <filename>remote-fs.target</filename>, instead of + <filename>local-fs-pre.target</filename> and <filename>local-fs.target</filename>. + They also pull in <filename>network-online.target</filename> and are ordered after + it and <filename>network.target</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>noauto</option></term> + <term><option>auto</option></term> + + <listitem><para>With <option>noauto</option>, the mount unit will not be added as a dependency for + <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. This means that it will not be + mounted automatically during boot, unless it is pulled in by some other unit. The <option>auto</option> option + has the opposite meaning and is the default. Note that the <option>noauto</option> option has an effect on the + mount unit itself only — if <option>x-systemd.automount</option> is used (see above), then the matching + automount unit will still be pulled in by these targets.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>nofail</option></term> + + <listitem><para>With <option>nofail</option>, this mount will be only wanted, not required, by + <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. Moreover the mount unit is not + ordered before these target units. This means that the boot will continue without waiting for the mount unit + and regardless whether the mount point can be mounted successfully.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>x-initrd.mount</option></term> + + <listitem><para>An additional filesystem to be mounted in the + initramfs. See <filename>initrd-fs.target</filename> + description in + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>If a mount point is configured in both + <filename>/etc/fstab</filename> and a unit file that is stored + below <filename>/usr</filename>, the former will take precedence. + If the unit file is stored below <filename>/etc</filename>, it + will take precedence. This means: native unit files take + precedence over traditional configuration files, but this is + superseded by the rule that configuration in + <filename>/etc</filename> will always take precedence over + configuration in <filename>/usr</filename>.</para> + </refsect1> + + <refsect1> + <title>Options</title> + + <para>Mount files must include a [Mount] section, which carries + information about the file system mount points it supervises. A + number of options that may be used in this section are shared with + other unit types. These options are documented in + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + The options specific to the [Mount] section of mount units are the + following:</para> + + <variablelist class='unit-directives'> + + <varlistentry> + <term><varname>What=</varname></term> + <listitem><para>Takes an absolute path of a device node, file or other resource to mount. See <citerefentry + project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details. If + this refers to a device node, a dependency on the respective device unit is automatically created. (See + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more + information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting, + literal percent characters should hence be written as <literal>%%</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Where=</varname></term> + <listitem><para>Takes an absolute path of a directory for the + mount point; in particular, the destination cannot be a symbolic + link. If the mount point does not exist at the time of + mounting, it is created. This string must be reflected in the + unit filename. (See above.) This option is + mandatory.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Type=</varname></term> + <listitem><para>Takes a string for the file system type. See + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details. This setting is optional.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>Options=</varname></term> + + <listitem><para>Mount options to use when mounting. This takes a comma-separated list of options. This setting + is optional. Note that the usual specifier expansion is applied to this setting, literal percent characters + should hence be written as <literal>%%</literal>.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>SloppyOptions=</varname></term> + + <listitem><para>Takes a boolean argument. If true, parsing of + the options specified in <varname>Options=</varname> is + relaxed, and unknown mount options are tolerated. This + corresponds with + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-s</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LazyUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, detach the + filesystem from the filesystem hierarchy at time of the unmount + operation, and clean up all references to the filesystem as + soon as they are not busy anymore. + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-l</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ForceUnmount=</varname></term> + + <listitem><para>Takes a boolean argument. If true, force an + unmount (in case of an unreachable NFS system). + This corresponds with + <citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s + <parameter>-f</parameter> switch. Defaults to + off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>DirectoryMode=</varname></term> + <listitem><para>Directories of mount points (and any parent + directories) are automatically created if needed. This option + specifies the file system access mode used when creating these + directories. Takes an access mode in octal notation. Defaults + to 0755.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>TimeoutSec=</varname></term> + <listitem><para>Configures the time to wait for the mount + command to finish. If a command does not exit within the + configured time, the mount will be considered failed and be + shut down again. All commands still running will be terminated + forcibly via <constant>SIGTERM</constant>, and after another + delay of this time with <constant>SIGKILL</constant>. (See + <option>KillMode=</option> in + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.) + Takes a unit-less value in seconds, or a time span value such + as "5min 20s". Pass 0 to disable the timeout logic. The + default value is set from <varname>DefaultTimeoutStartSec=</varname> option in + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para></listitem> + </varlistentry> + </variablelist> + + <para>Check + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry> + for more settings.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |