"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
will refuse options that are not listed in
<filename>/etc/fstab</filename> if it is not 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>.</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
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="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
+ url="https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
File Systems</ulink>.</para>
</refsect1>
<refsect1>
- <title>Automatic Dependencies</title>
-
- <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>
-
- <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>
-
- <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>
-
- <para>For mount units with
- <varname>DefaultDependencies=yes</varname> (the default) a couple
- additional dependencies are added. Mount units referring to local
- file systems automatically gain an <varname>After=</varname>
- dependency on <filename>local-fs-pre.target</filename>. 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>. Towards the latter a
- <varname>Wants=</varname> unit is added as well. 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. Mount units (regardless if local or
- network) also acquire automatic <varname>Before=</varname> and
- <varname>Conflicts=</varname> on
- <filename>umount.target</filename> in order to be stopped
- during shutdown.</para>
-
- <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>
+ <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>
+ </refsect1>
+
+ <refsect1>
+ <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>.</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>. 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>
</refsect1>
<refsect1>
<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-timout=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
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>
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>
</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>_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>, this mount 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.</para>
+ <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><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.</para></listitem>
+ <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 of the
- mount point. If the mount point does not exist at the time of
+ <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>
<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.</para></listitem>
+ <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>
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
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 the manager configuration file's
- <varname>DefaultTimeoutStart=</varname>
+ <varname>DefaultTimeoutStartSec=</varname>
variable.</para></listitem>
</varlistentry>
</variablelist>
projects / thirdparty / systemd.git / blobdiff