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
  59                 a file system mount point controlled and supervised by
  60                 systemd.</para>
  61
  62                 <para>This man page lists the configuration options
  63                 specific to this unit type. See
  64                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  65                 for the common options of all unit configuration
  66                 files. The common configuration items are configured
  67                 in the generic [Unit] and [Install] sections. The
  68                 mount specific configuration options are configured
  69                 in the [Mount] section.</para>
  70
  71                 <para>Additional options are listed in
  72                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  73                 which define the execution environment the
  74                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  75                 binary is executed in, and in
  76                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  77                 which define the way the processes are terminated, and
  78                 in
  79                 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  80                 which configure resource control settings for the
  81                 processes of the service. Note that the User= and
  82                 Group= options are not particularly useful for mount
  83                 units specifying a <literal>Type=</literal> option or
  84                 using configuration not specified in
  85                 <filename>/etc/fstab</filename>;
  86                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  87                 will refuse options that are not listed in
  88                 <filename>/etc/fstab</filename> if it is not run as
  89                 UID 0.</para>
  90
  91                 <para>Mount units must be named after the mount point
  92                 directories they control. Example: the mount point
  93                 <filename noindex='true'>/home/lennart</filename> must be configured
  94                 in a unit file
  95                 <filename>home-lennart.mount</filename>. For details
  96                 about the escaping logic used to convert a file system
  97                 path to a unit name, see
  98                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  99
 100                 <para>Optionally, a mount unit may be accompanied by
 101                 an automount unit, to allow on-demand or parallelized
 102                 mounting. See
 103                 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 104
 105                 <para>If a mount point is beneath another mount point
 106                 in the file system hierarchy, a dependency between both
 107                 units is created automatically.</para>
 108
 109                 <para>Mount points created at runtime (independently of
 110                 unit files or <filename>/etc/fstab</filename>) will be
 111                 monitored by systemd and appear like any other mount
 112                 unit in systemd.
 113                 See <filename>/proc/self/mountinfo</filename> description
 114                 in <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 115                 </para>
 116
 117                 <para>Some file systems have special semantics as API
 118                 file systems for kernel-to-userspace and
 119                 userspace-to-userpace interfaces. Some of them may not
 120                 be changed via mount units, and cannot be disabled.
 121                 For a longer discussion see <ulink
 122                 url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
 123                 File Systems</ulink>.</para>
 124         </refsect1>
 125
 126         <refsect1>
 127                 <title><filename>fstab</filename></title>
 128
 129                 <para>Mount units may either be configured via unit
 130                 files, or via <filename>/etc/fstab</filename> (see
 131                 <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 132                 for details). Mounts listed in
 133                 <filename>/etc/fstab</filename> will be converted into
 134                 native units dynamically at boot and when the
 135                 configuration of the system manager is reloaded. In
 136                 general, configuring mount points through
 137                 <filename>/etc/fstab</filename> is the preferred
 138                 approach. See
 139                 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 140                 for details about the conversion.</para>
 141
 142                 <para>When reading <filename>/etc/fstab</filename> a
 143                 few special mount options are understood by systemd
 144                 which influence how dependencies are created for mount
 145                 points. systemd will create a dependency of type
 146                 <option>Wants</option> or <option>Requires</option>
 147                 (see option <option>nofail</option> below), from
 148                 either <filename>local-fs.target</filename> or
 149                 <filename>remote-fs.target</filename>, depending
 150                 whether the file system is local or remote.</para>
 151
 152                 <variablelist class='fstab-options'>
 153
 154                   <varlistentry>
 155                     <term><option>x-systemd.automount</option></term>
 156
 157                     <listitem><para>An automount unit will be created
 158                     for the file system. See
 159                     <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 160                     for details.</para></listitem>
 161                   </varlistentry>
 162
 163                   <varlistentry>
 164                     <term><option>x-systemd.device-timeout=</option></term>
 165
 166                     <listitem><para>Configure how long systemd should
 167                     wait for a device to show up before giving up on
 168                     an entry from
 169                     <filename>/etc/fstab</filename>. Specify a time in
 170                     seconds or explicitly append a unit as
 171                     <literal>s</literal>, <literal>min</literal>,
 172                     <literal>h</literal>,
 173                     <literal>ms</literal>.</para>
 174
 175                     <para>Note that this option can only be used in
 176                     <filename>/etc/fstab</filename>, and will be
 177                     ignored when part of <varname>Options=</varname>
 178                     setting in a unit file.</para>
 179                     </listitem>
 180                   </varlistentry>
 181
 182                   <varlistentry>
 183                     <term><option>noauto</option></term>
 184                     <term><option>auto</option></term>
 185
 186                     <listitem><para>With <option>noauto</option>, this
 187                     mount will not be added as a dependency for
 188                     <filename>local-fs.target</filename> or
 189                     <filename>remote-fs.target</filename>. This means
 190                     that it will not be mounted automatically during
 191                     boot, unless it is pulled in by some other
 192                     unit. Option <option>auto</option> has the
 193                     opposite meaning and is the default.</para>
 194                     </listitem>
 195                   </varlistentry>
 196
 197                   <varlistentry>
 198                     <term><option>nofail</option></term>
 199                     <term><option>fail</option></term>
 200
 201                     <listitem><para>With <option>nofail</option> this
 202                     mount will be only wanted, not required, by
 203                     <filename>local-fs.target</filename> or
 204                     <filename>remote-fs.target</filename>. This means
 205                     that the boot will continue even if this mount
 206                     point is not mounted successfully. Option
 207                     <option>fail</option> has the opposite meaning and
 208                     is the default.</para>
 209                     </listitem>
 210                   </varlistentry>
 211
 212                   <varlistentry>
 213                     <term><option>x-initrd.mount</option></term>
 214
 215                     <listitem><para>An additional filesystem to be
 216                     mounted in the initramfs. See
 217                     <filename>initrd-fs.target</filename> description
 218                     in
 219                     <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 220                     </para></listitem>
 221                   </varlistentry>
 222                 </variablelist>
 223
 224                 <para>If a mount point is configured in both
 225                 <filename>/etc/fstab</filename> and a unit file that
 226                 is stored below <filename>/usr</filename>, the former
 227                 will take precedence. If the unit file is stored below
 228                 <filename>/etc</filename>, it will take
 229                 precedence. This means: native unit files take
 230                 precedence over traditional configuration files, but
 231                 this is superseded by the rule that configuration in
 232                 <filename>/etc</filename> will always take precedence
 233                 over configuration in
 234                 <filename>/usr</filename>.</para>
 235         </refsect1>
 236
 237         <refsect1>
 238                 <title>Options</title>
 239
 240                 <para>Mount files must include a [Mount] section,
 241                 which carries information about the file system mount points it
 242                 supervises. A number of options that may be used in
 243                 this section are shared with other unit types. These
 244                 options are documented in
 245                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 246                 and
 247                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 248                 options specific to the [Mount] section of mount
 249                 units are the following:</para>
 250
 251                 <variablelist class='unit-directives'>
 252
 253                         <varlistentry>
 254                                 <term><varname>What=</varname></term>
 255                                 <listitem><para>Takes an absolute path
 256                                 of a device node, file or other
 257                                 resource to mount. See
 258                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 259                                 for details. If this refers to a
 260                                 device node, a dependency on the
 261                                 respective device unit is
 262                                 automatically created. (See
 263                                 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.)
 264                                 This option is
 265                                 mandatory.</para></listitem>
 266                         </varlistentry>
 267
 268                         <varlistentry>
 269                                 <term><varname>Where=</varname></term>
 270                                 <listitem><para>Takes an absolute path
 271                                 of a directory of the mount point. If
 272                                 the mount point does not exist at the
 273                                 time of mounting, it is created. This
 274                                 string must be reflected in the unit
 275                                 filename. (See above.) This option is
 276                                 mandatory.</para></listitem>
 277                         </varlistentry>
 278
 279                         <varlistentry>
 280                                 <term><varname>Type=</varname></term>
 281                                 <listitem><para>Takes a string for the
 282                                 file system type. See
 283                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 284                                 for details. This setting is
 285                                 optional.</para></listitem>
 286                         </varlistentry>
 287
 288                         <varlistentry>
 289                                 <term><varname>Options=</varname></term>
 290
 291                                 <listitem><para>Mount options to use
 292                                 when mounting. This takes a
 293                                 comma-separated list of options. This
 294                                 setting is optional.</para></listitem>
 295                         </varlistentry>
 296
 297                         <varlistentry>
 298                                 <term><varname>SloppyOptions=</varname></term>
 299
 300                                 <listitem><para>Takes a boolean
 301                                 argument. If true, parsing of the
 302                                 options specified in
 303                                 <varname>Options=</varname> is
 304                                 relaxed, and unknown mount options are
 305                                 tolerated. This corresponds with
 306                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
 307                                 <parameter>-s</parameter>
 308                                 switch. Defaults to
 309                                 off.</para></listitem>
 310                         </varlistentry>
 311
 312                         <varlistentry>
 313                                 <term><varname>DirectoryMode=</varname></term>
 314                                 <listitem><para>Directories of mount
 315                                 points (and any parent directories)
 316                                 are automatically created if
 317                                 needed. This option specifies the file
 318                                 system access mode used when creating
 319                                 these directories. Takes an access
 320                                 mode in octal notation. Defaults to
 321                                 0755.</para></listitem>
 322                         </varlistentry>
 323
 324                         <varlistentry>
 325                                 <term><varname>TimeoutSec=</varname></term>
 326                                 <listitem><para>Configures the time to
 327                                 wait for the mount command to
 328                                 finish. If a command does not exit
 329                                 within the configured time, the mount
 330                                 will be considered failed and be shut
 331                                 down again. All commands still running
 332                                 will be terminated forcibly via
 333                                 <constant>SIGTERM</constant>, and after another delay of
 334                                 this time with <constant>SIGKILL</constant>. (See
 335                                 <option>KillMode=</option> in
 336                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 337                                 Takes a unit-less value in seconds, or
 338                                 a time span value such as "5min
 339                                 20s". Pass 0 to disable the timeout
 340                                 logic. The default value is set from the manager configuration
 341                                 file's <varname>DefaultTimeoutStart=</varname> variable.</para></listitem>
 342                         </varlistentry>
 343                 </variablelist>
 344
 345                 <para>Check
 346                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 347                 and
 348                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 349                 for more settings.</para>
 350         </refsect1>
 351
 352         <refsect1>
 353                   <title>See Also</title>
 354                   <para>
 355                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 356                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 357                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 358                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 359                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 360                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 361                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 362                           <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 363                           <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 364                           <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 365                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 366                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 367                   </para>
 368         </refsect1>
 369
 370 </refentry>