man/systemd.mount.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd.mount">
  25   <refentryinfo>
  26     <title>systemd.mount</title>
  27     <productname>systemd</productname>
  28
  29     <authorgroup>
  30       <author>
  31         <contrib>Developer</contrib>
  32         <firstname>Lennart</firstname>
  33         <surname>Poettering</surname>
  34         <email>lennart@poettering.net</email>
  35       </author>
  36     </authorgroup>
  37   </refentryinfo>
  38
  39   <refmeta>
  40     <refentrytitle>systemd.mount</refentrytitle>
  41     <manvolnum>5</manvolnum>
  42   </refmeta>
  43
  44   <refnamediv>
  45     <refname>systemd.mount</refname>
  46     <refpurpose>Mount unit configuration</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <para><filename><replaceable>mount</replaceable>.mount</filename></para>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para>A unit configuration file whose name ends in
  57     <literal>.mount</literal> encodes information about a file system
  58     mount point controlled and supervised by systemd.</para>
  59
  60     <para>This man page lists the configuration options specific to
  61     this unit type. See
  62     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  63     for the common options of all unit configuration files. The common
  64     configuration items are configured in the generic [Unit] and
  65     [Install] sections. The mount specific configuration options are
  66     configured in the [Mount] section.</para>
  67
  68     <para>Additional options are listed in
  69     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  70     which define the execution environment the
  71     <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  72     binary is executed in, and in
  73     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  74     which define the way the processes are terminated, and in
  75     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  76     which configure resource control settings for the processes of the
  77     service. Note that the User= and Group= options are not
  78     particularly useful for mount units specifying a
  79     <literal>Type=</literal> option or using configuration not
  80     specified in <filename>/etc/fstab</filename>;
  81     <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  82     will refuse options that are not listed in
  83     <filename>/etc/fstab</filename> if it is not run as UID 0.</para>
  84
  85     <para>Mount units must be named after the mount point directories
  86     they control. Example: the mount point
  87     <filename noindex='true'>/home/lennart</filename> must be
  88     configured in a unit file <filename>home-lennart.mount</filename>.
  89     For details about the escaping logic used to convert a file system
  90     path to a unit name, see
  91     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  92
  93     <para>Optionally, a mount unit may be accompanied by an automount
  94     unit, to allow on-demand or parallelized mounting. See
  95     <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  96
  97     <para>Mount points created at runtime (independently of unit files
  98     or <filename>/etc/fstab</filename>) will be monitored by systemd
  99     and appear like any other mount unit in systemd. See
 100     <filename>/proc/self/mountinfo</filename> description in
 101     <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 102     </para>
 103
 104     <para>Some file systems have special semantics as API file systems
 105     for kernel-to-userspace and userspace-to-userspace interfaces. Some
 106     of them may not be changed via mount units, and cannot be
 107     disabled. For a longer discussion see <ulink
 108     url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
 109     File Systems</ulink>.</para>
 110   </refsect1>
 111
 112   <refsect1>
 113     <title>Automatic Dependencies</title>
 114
 115     <para>If a mount unit is beneath another mount unit in the file
 116     system hierarchy, both a requirement dependency and an ordering
 117     dependency between both units are created automatically.</para>
 118
 119     <para>Block device backed file systems automatically gain
 120     <varname>BindsTo=</varname> and <varname>After=</varname> type
 121     dependencies on the device unit encapsulating the block
 122     device (see below).</para>
 123
 124     <para>If traditional file system quota is enabled for a mount
 125     unit, automatic <varname>Wants=</varname> and
 126     <varname>Before=</varname> dependencies on
 127     <filename>systemd-quotacheck.service</filename> and
 128     <filename>quotaon.service</filename> are added.</para>
 129
 130     <para>For mount units with
 131     <varname>DefaultDependencies=yes</varname> (the default) a couple
 132     additional dependencies are added. Mount units referring to local
 133     file systems automatically gain an <varname>After=</varname>
 134     dependency on <filename>local-fs-pre.target</filename>. Network
 135     mount units automatically acquire <varname>After=</varname>
 136     dependencies on <filename>remote-fs-pre.target</filename>,
 137     <filename>network.target</filename> and
 138     <filename>network-online.target</filename>. Towards the latter a
 139     <varname>Wants=</varname> unit is added as well. Mount units
 140     referring to local and network file systems are distinguished by
 141     their file system type specification. In some cases this is not
 142     sufficient (for example network block device based mounts, such as
 143     iSCSI), in which case <option>_netdev</option> may be added to the
 144     mount option string of the unit, which forces systemd to consider the
 145     mount unit a network mount. Mount units (regardless if local or
 146     network) also acquire automatic <varname>Before=</varname> and
 147     <varname>Conflicts=</varname> on
 148     <filename>umount.target</filename> in order to be stopped
 149     during shutdown.</para>
 150
 151     <para>Additional implicit dependencies may be added as result of
 152     execution and resource control parameters as documented in
 153     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 154     and
 155     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title><filename>fstab</filename></title>
 160
 161     <para>Mount units may either be configured via unit files, or via
 162     <filename>/etc/fstab</filename> (see
 163     <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 164     for details). Mounts listed in <filename>/etc/fstab</filename>
 165     will be converted into native units dynamically at boot and when
 166     the configuration of the system manager is reloaded. In general,
 167     configuring mount points through <filename>/etc/fstab</filename>
 168     is the preferred approach. See
 169     <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 170     for details about the conversion.</para>
 171
 172     <para>When reading <filename>/etc/fstab</filename> a few special
 173     mount options are understood by systemd which influence how
 174     dependencies are created for mount points. systemd will create a
 175     dependency of type <varname>Wants=</varname> or
 176     <option>Requires</option> (see option <option>nofail</option>
 177     below), from either <filename>local-fs.target</filename> or
 178     <filename>remote-fs.target</filename>, depending whether the file
 179     system is local or remote.</para>
 180
 181     <variablelist class='fstab-options'>
 182
 183       <varlistentry>
 184         <term><option>x-systemd.requires=</option></term>
 185
 186         <listitem><para>Configures a <varname>Requires=</varname> and
 187         an <varname>After=</varname> dependency between the created
 188         mount unit and another systemd unit, such as a device or mount
 189         unit. The argument should be a unit name, or an absolute path
 190         to a device node or mount point.  This option may be specified
 191         more than once. This option is particularly useful for mount
 192         point declarations that need an additional device to be around
 193         (such as an external journal device for journal file systems)
 194         or an additional mount to be in place (such as an overlay file
 195         system that merges multiple mount points). See
 196         <varname>After=</varname> and <varname>Requires=</varname> in
 197         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 198         for details.</para></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>x-systemd.requires-mounts-for=</option></term>
 203
 204         <listitem><para>Configures a
 205         <varname>RequiresMountsFor=</varname> dependency between the
 206         created mount unit and other mount units. The argument must be
 207         an absolute path. This option may be specified more than once.
 208         See <varname>RequiresMountsFor=</varname> in
 209         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 210         for details.</para></listitem>
 211        </varlistentry>
 212
 213       <varlistentry>
 214         <term><option>x-systemd.automount</option></term>
 215
 216         <listitem><para>An automount unit will be created for the file
 217         system. See
 218         <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 219         for details.</para></listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>x-systemd.idle-timeout=</option></term>
 224
 225         <listitem><para>Configures the idle timeout of the
 226         automount unit. See <varname>TimeoutIdleSec=</varname> in
 227         <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 228         for details.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><option>x-systemd.device-timeout=</option></term>
 233
 234         <listitem><para>Configure how long systemd should wait for a
 235         device to show up before giving up on an entry from
 236         <filename>/etc/fstab</filename>. Specify a time in seconds or
 237         explicitly append a unit such as <literal>s</literal>,
 238         <literal>min</literal>, <literal>h</literal>,
 239         <literal>ms</literal>.</para>
 240
 241         <para>Note that this option can only be used in
 242         <filename>/etc/fstab</filename>, and will be
 243         ignored when part of the <varname>Options=</varname>
 244         setting in a unit file.</para>
 245         </listitem>
 246       </varlistentry>
 247
 248       <varlistentry>
 249         <term><option>noauto</option></term>
 250         <term><option>auto</option></term>
 251
 252         <listitem><para>With <option>noauto</option>, this mount will
 253         not be added as a dependency for
 254         <filename>local-fs.target</filename> or
 255         <filename>remote-fs.target</filename>. This means that it will
 256         not be mounted automatically during boot, unless it is pulled
 257         in by some other unit. The <option>auto</option> option has the
 258         opposite meaning and is the default.</para>
 259         </listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><option>nofail</option></term>
 264
 265         <listitem><para>With <option>nofail</option>, this mount will
 266         be only wanted, not required, by
 267         <filename>local-fs.target</filename> or
 268         <filename>remote-fs.target</filename>. This means that the
 269         boot will continue even if this mount point is not mounted
 270         successfully.</para>
 271         </listitem>
 272       </varlistentry>
 273
 274       <varlistentry>
 275         <term><option>x-initrd.mount</option></term>
 276
 277         <listitem><para>An additional filesystem to be mounted in the
 278         initramfs. See <filename>initrd-fs.target</filename>
 279         description in
 280         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 281         </para></listitem>
 282       </varlistentry>
 283     </variablelist>
 284
 285     <para>If a mount point is configured in both
 286     <filename>/etc/fstab</filename> and a unit file that is stored
 287     below <filename>/usr</filename>, the former will take precedence.
 288     If the unit file is stored below <filename>/etc</filename>, it
 289     will take precedence. This means: native unit files take
 290     precedence over traditional configuration files, but this is
 291     superseded by the rule that configuration in
 292     <filename>/etc</filename> will always take precedence over
 293     configuration in <filename>/usr</filename>.</para>
 294   </refsect1>
 295
 296   <refsect1>
 297     <title>Options</title>
 298
 299     <para>Mount files must include a [Mount] section, which carries
 300     information about the file system mount points it supervises. A
 301     number of options that may be used in this section are shared with
 302     other unit types. These options are documented in
 303     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 304     and
 305     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 306     The options specific to the [Mount] section of mount units are the
 307     following:</para>
 308
 309     <variablelist class='unit-directives'>
 310
 311       <varlistentry>
 312         <term><varname>What=</varname></term>
 313         <listitem><para>Takes an absolute path of a device node, file
 314         or other resource to mount. See
 315         <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 316         for details. If this refers to a device node, a dependency on
 317         the respective device unit is automatically created. (See
 318         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 319         for more information.) This option is
 320         mandatory.</para></listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><varname>Where=</varname></term>
 325         <listitem><para>Takes an absolute path of a directory of the
 326         mount point. If the mount point does not exist at the time of
 327         mounting, it is created. This string must be reflected in the
 328         unit filename. (See above.) This option is
 329         mandatory.</para></listitem>
 330       </varlistentry>
 331
 332       <varlistentry>
 333         <term><varname>Type=</varname></term>
 334         <listitem><para>Takes a string for the file system type. See
 335         <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 336         for details. This setting is optional.</para></listitem>
 337       </varlistentry>
 338
 339       <varlistentry>
 340         <term><varname>Options=</varname></term>
 341
 342         <listitem><para>Mount options to use when mounting. This takes
 343         a comma-separated list of options. This setting is
 344         optional.</para></listitem>
 345       </varlistentry>
 346
 347       <varlistentry>
 348         <term><varname>SloppyOptions=</varname></term>
 349
 350         <listitem><para>Takes a boolean argument. If true, parsing of
 351         the options specified in <varname>Options=</varname> is
 352         relaxed, and unknown mount options are tolerated. This
 353         corresponds with
 354         <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
 355         <parameter>-s</parameter> switch. Defaults to
 356         off.</para></listitem>
 357       </varlistentry>
 358
 359       <varlistentry>
 360         <term><varname>DirectoryMode=</varname></term>
 361         <listitem><para>Directories of mount points (and any parent
 362         directories) are automatically created if needed. This option
 363         specifies the file system access mode used when creating these
 364         directories. Takes an access mode in octal notation. Defaults
 365         to 0755.</para></listitem>
 366       </varlistentry>
 367
 368       <varlistentry>
 369         <term><varname>TimeoutSec=</varname></term>
 370         <listitem><para>Configures the time to wait for the mount
 371         command to finish. If a command does not exit within the
 372         configured time, the mount will be considered failed and be
 373         shut down again. All commands still running will be terminated
 374         forcibly via <constant>SIGTERM</constant>, and after another
 375         delay of this time with <constant>SIGKILL</constant>. (See
 376         <option>KillMode=</option> in
 377         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 378         Takes a unit-less value in seconds, or a time span value such
 379         as "5min 20s". Pass 0 to disable the timeout logic. The
 380         default value is set from the manager configuration file's
 381         <varname>DefaultTimeoutStart=</varname>
 382         variable.</para></listitem>
 383       </varlistentry>
 384     </variablelist>
 385
 386     <para>Check
 387     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 388     and
 389     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 390     for more settings.</para>
 391   </refsect1>
 392
 393   <refsect1>
 394       <title>See Also</title>
 395       <para>
 396         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 397         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 398         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 399         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 400         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 401         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 402         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 403         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 404         <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 405         <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 406         <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 407         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 408       </para>
 409   </refsect1>
 410
 411 </refentry>