summaryrefslogtreecommitdiff
path: root/src/grp-system/systemd/systemd.mount.xml
diff options
context:
space:
mode:
Diffstat (limited to 'src/grp-system/systemd/systemd.mount.xml')
-rw-r--r--src/grp-system/systemd/systemd.mount.xml406
1 files changed, 406 insertions, 0 deletions
diff --git a/src/grp-system/systemd/systemd.mount.xml b/src/grp-system/systemd/systemd.mount.xml
new file mode 100644
index 0000000000..66cddd72e0
--- /dev/null
+++ b/src/grp-system/systemd/systemd.mount.xml
@@ -0,0 +1,406 @@
+<?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">
+
+<!--
+ This file is part of systemd.
+
+ Copyright 2010 Lennart Poettering
+
+ systemd is free software; you can redistribute it and/or modify it
+ under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation; either version 2.1 of the License, or
+ (at your option) any later version.
+
+ systemd is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public License
+ along with systemd; If not, see <http://www.gnu.org/licenses/>.
+-->
+
+<refentry id="systemd.mount">
+ <refentryinfo>
+ <title>systemd.mount</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </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>
+ binary 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. Note that the User= and Group= options are not
+ particularly useful for mount units specifying a
+ <literal>Type=</literal> option or using configuration not
+ specified in <filename>/etc/fstab</filename>;
+ <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ 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>. 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="http://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> in the <literal>[Unit]</literal> section (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>
+ </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><refentrytitle>nfs</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ is not supported in <filename>/etc/fstab</filename> entries. The systemd mount option <option>nofail</option>
+ provides similar functionality and should be used instead.</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.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.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>
+ <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>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>
+ </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>. This means that the
+ boot will continue even if this mount point is not 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.</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
+ 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.</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>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 the manager configuration file's
+ <varname>DefaultTimeoutStart=</varname>
+ variable.</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.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>