man/systemd.mount.xml

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