summaryrefslogtreecommitdiffstats
path: root/man/systemd.automount.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/systemd.automount.xml')
-rw-r--r--man/systemd.automount.xml194
1 files changed, 194 insertions, 0 deletions
diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml
new file mode 100644
index 0000000..0bbd4e8
--- /dev/null
+++ b/man/systemd.automount.xml
@@ -0,0 +1,194 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd.automount" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <refentryinfo>
+ <title>systemd.automount</title>
+ <productname>systemd</productname>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>systemd.automount</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>systemd.automount</refname>
+ <refpurpose>Automount unit configuration</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename><replaceable>automount</replaceable>.automount</filename></para>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para>A unit configuration file whose name ends in <literal>.automount</literal> encodes information
+ about a file system automount point controlled and supervised by systemd. Automount units may be used to
+ implement on-demand mounting as well as parallelized mounting of file systems.</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 automount specific configuration options
+ are configured in the [Automount] section.</para>
+
+ <para>Automount units must be named after the automount directories they control. Example: the automount
+ point <filename index="false">/home/lennart</filename> must be configured in a unit file
+ <filename>home-lennart.automount</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 automount units cannot be templated, nor is it possible to add multiple names to an automount unit
+ by creating symlinks to its unit file.</para>
+
+ <para>For each automount unit file a matching mount unit file (see
+ <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ for details) must exist which is activated when the automount path
+ is accessed. Example: if an automount unit
+ <filename>home-lennart.automount</filename> is active and the user
+ accesses <filename>/home/lennart</filename> the mount unit
+ <filename>home-lennart.mount</filename> will be activated.</para>
+
+ <para>Note that automount units are separate from the mount itself, so you
+ should not set <varname>After=</varname> or <varname>Requires=</varname>
+ for mount dependencies here. For example, you should not set
+ <varname>After=network-online.target</varname> or similar on network
+ filesystems. Doing so may result in an ordering cycle.</para>
+
+ <para>Note that automount support on Linux is privileged, automount units are hence only available in the
+ system service manager (and root's user service manager), but not in unprivileged users' service
+ managers.</para>
+
+ <para>Note that automount units should not be nested. (The establishment of the inner automount point
+ would unconditionally pin the outer mount point, defeating its purpose.)</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Automatic Dependencies</title>
+
+ <refsect2>
+ <title>Implicit Dependencies</title>
+
+ <para>The following dependencies are implicitly added:</para>
+
+ <itemizedlist>
+ <listitem><para>If an automount unit is beneath another mount unit in the file system hierarchy, a
+ requirement and ordering dependencies are created to the on the unit higher in the hierarchy.
+ </para></listitem>
+
+ <listitem><para>An implicit <varname>Before=</varname> dependency is created between an automount
+ unit and the mount unit it activates.</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>Automount 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>Automount units 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>.</para></listitem>
+ </itemizedlist>
+ </refsect2>
+ </refsect1>
+
+ <refsect1>
+ <title><filename>fstab</filename></title>
+
+ <para>Automount 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).</para>
+
+ <para>For details how systemd parses
+ <filename>/etc/fstab</filename> see
+ <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
+
+ <para>If an automount point is configured in both
+ <filename>/etc/fstab</filename> and a unit file, the configuration
+ in the latter takes precedence.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Options</title>
+
+ <para>Automount unit files may include [Unit] and [Install] sections, which are described in
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+ </para>
+
+ <para>Automount unit files must include an [Automount] section, which
+ carries information about the file system automount points it
+ supervises. The options specific to the [Automount] section of
+ automount units are the following:</para>
+
+ <variablelist class='unit-directives'>
+
+ <varlistentry>
+ <term><varname>Where=</varname></term>
+ <listitem><para>Takes an absolute path of a directory of the
+ automount point. If the automount point does not exist at time
+ that the automount point is installed, it is created. This
+ string must be reflected in the unit filename. (See above.)
+ This option is mandatory.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>ExtraOptions=</varname></term>
+ <listitem><para>Extra mount options to use when creating the autofs
+ mountpoint. 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 class='specifiers'>%%</literal>.</para>
+
+ <xi:include href="version-info.xml" xpointer="v250"/></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>DirectoryMode=</varname></term>
+ <listitem><para>Directories of automount 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>TimeoutIdleSec=</varname></term>
+ <listitem><para>Configures an idle timeout. Once the mount has been
+ idle for the specified time, systemd will attempt to unmount. Takes a
+ unit-less value in seconds, or a time span value such as "5min 20s".
+ Pass 0 to disable the timeout logic. The timeout is disabled by
+ default.</para>
+
+ <xi:include href="version-info.xml" xpointer="v220"/></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
+ </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.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>automount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>