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                 <filename>.mount</filename> 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
  78                 terminated. Note that the User= and Group= options are
  79                 not particularly useful for mount units specifying a
  80                 <literal>Type=</literal> option or using configuration
  81                 not specified in <filename>/etc/fstab</filename>;
  82                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  83                 will refuse options that aren't listed in
  84                 <filename>/etc/fstab</filename> if it is not run as
  85                 UID 0.</para>
  86
  87                 <para>Mount units must be named after the mount point
  88                 directories they control. Example: the mount point
  89                 <filename noindex='true'>/home/lennart</filename> must be configured
  90                 in a unit file
  91                 <filename>home-lennart.mount</filename>. For details
  92                 about the escaping logic used to convert a file system
  93                 path to a unit name see
  94                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  95
  96                 <para>Optionally, a mount unit may be accompanied by
  97                 an automount unit, to allow on-demand or parallelized
  98                 mounting. See
  99                 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
 100
 101                 <para>If a mount point is beneath another mount point
 102                 in the file system hierarchy, a dependency between both
 103                 units is created automatically.</para>
 104
 105                 <para>Mount points created at runtime (independently of
 106                 unit files or <filename>/etc/fstab</filename>) will be
 107                 monitored by systemd and appear like any other mount
 108                 unit in systemd.
 109                 See <filename>/proc/self/mountinfo</filename> description
 110                 in <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 111                 </para>
 112
 113                 <para>Some file systems have special semantics as API
 114                 file systems for kernel-to-userspace and
 115                 userspace-to-userpace interfaces. Some of them may not
 116                 be changed via mount units, and cannot be disabled.
 117                 For a longer discussion see <ulink
 118                 url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
 119                 File Systems</ulink>.</para>
 120         </refsect1>
 121
 122         <refsect1>
 123                 <title><filename>/etc/fstab</filename></title>
 124
 125                 <para>Mount units may either be configured via unit
 126                 files, or via <filename>/etc/fstab</filename> (see
 127                 <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 128                 for details). Mounts listed in
 129                 <filename>/etc/fstab</filename> will be converted into
 130                 native units dynamically at boot and when the
 131                 configuration of the system manager is reloaded. See
 132                 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 133                 for details about the conversion.</para>
 134
 135                 <para>When reading <filename>/etc/fstab</filename> a
 136                 few special mount options are understood by systemd
 137                 which influence how dependencies are created for mount
 138                 points from <filename>/etc/fstab</filename>. systemd
 139                 will create a dependency of type
 140                 <option>Wants</option> from either
 141                 <filename>local-fs.target</filename> or
 142                 <filename>remote-fs.target</filename>, depending
 143                 whether the file system is local or remote. If
 144                 <option>x-systemd.automount</option> is set, an
 145                 automount unit will be created for the file
 146                 system. See
 147                 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 148                 for details. If
 149                 <option>x-systemd.device-timeout=</option> is
 150                 specified it may be used to configure how long systemd
 151                 should wait for a device to show up before giving up
 152                 on an entry from
 153                 <filename>/etc/fstab</filename>. Specify a time in
 154                 seconds or explicitly specify a unit as
 155                 <literal>s</literal>, <literal>min</literal>,
 156                 <literal>h</literal>, <literal>ms</literal>.</para>
 157
 158                 <para>If a mount point is configured in both
 159                 <filename>/etc/fstab</filename> and a unit file that
 160                 is stored below <filename>/usr</filename> the former
 161                 will take precedence. If the unit file is stored below
 162                 <filename>/etc</filename> it will take
 163                 precedence. This means: native unit files take
 164                 precedence over traditional configuration files, but
 165                 this is superseded by the rule that configuration in
 166                 <filename>/etc</filename> will always take precedence
 167                 over configuration in
 168                 <filename>/usr</filename>.</para>
 169         </refsect1>
 170
 171         <refsect1>
 172                 <title>Options</title>
 173
 174                 <para>Mount files must include a [Mount] section,
 175                 which carries information about the file system mount points it
 176                 supervises. A number of options that may be used in
 177                 this section are shared with other unit types. These
 178                 options are documented in
 179                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 180                 and
 181                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 182                 options specific to the [Mount] section of mount
 183                 units are the following:</para>
 184
 185                 <variablelist class='unit-directives'>
 186
 187                         <varlistentry>
 188                                 <term><varname>What=</varname></term>
 189                                 <listitem><para>Takes an absolute path
 190                                 of a device node, file or other
 191                                 resource to mount. See
 192                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 193                                 for details. If this refers to a
 194                                 device node, a dependency on the
 195                                 respective device unit is
 196                                 automatically created. (See
 197                                 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.)
 198                                 This option is
 199                                 mandatory.</para></listitem>
 200                         </varlistentry>
 201
 202                         <varlistentry>
 203                                 <term><varname>Where=</varname></term>
 204                                 <listitem><para>Takes an absolute path
 205                                 of a directory of the mount point. If
 206                                 the mount point does not exist at the
 207                                 time of mounting, it is created. This
 208                                 string must be reflected in the unit
 209                                 filename. (See above.) This option is
 210                                 mandatory.</para></listitem>
 211                         </varlistentry>
 212
 213                         <varlistentry>
 214                                 <term><varname>Type=</varname></term>
 215                                 <listitem><para>Takes a string for the
 216                                 file system type. See
 217                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 218                                 for details. This setting is
 219                                 optional.</para></listitem>
 220                         </varlistentry>
 221
 222                         <varlistentry>
 223                                 <term><varname>Options=</varname></term>
 224
 225                                 <listitem><para>Mount options to use
 226                                 when mounting. This takes a
 227                                 comma-separated list of options. This
 228                                 setting is optional.</para></listitem>
 229                         </varlistentry>
 230
 231                         <varlistentry>
 232                                 <term><varname>DirectoryMode=</varname></term>
 233                                 <listitem><para>Directories of mount
 234                                 points (and any parent directories)
 235                                 are automatically created if
 236                                 needed. This option specifies the file
 237                                 system access mode used when creating
 238                                 these directories. Takes an access
 239                                 mode in octal notation. Defaults to
 240                                 0755.</para></listitem>
 241                         </varlistentry>
 242
 243                         <varlistentry>
 244                                 <term><varname>TimeoutSec=</varname></term>
 245                                 <listitem><para>Configures the time to
 246                                 wait for the mount command to
 247                                 finish. If a command does not exit
 248                                 within the configured time, the mount
 249                                 will be considered failed and be shut
 250                                 down again. All commands still running
 251                                 will be terminated forcibly via
 252                                 <constant>SIGTERM</constant>, and after another delay of
 253                                 this time with <constant>SIGKILL</constant>. (See
 254                                 <option>KillMode=</option> in
 255                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 256                                 Takes a unit-less value in seconds, or
 257                                 a time span value such as "5min
 258                                 20s". Pass 0 to disable the timeout
 259                                 logic. Defaults to
 260                                 90s.</para></listitem>
 261                         </varlistentry>
 262                 </variablelist>
 263
 264                 <para>Check
 265                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 266                 and
 267                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 268                 for more settings.</para>
 269         </refsect1>
 270
 271         <refsect1>
 272                 <title>Compatibility Options</title>
 273
 274                 <para>The following option is also available in the
 275                 <literal>[Mount]</literal> section, but exists purely
 276                 for compatibility reasons and should not be used in
 277                 newly written mount files.</para>
 278
 279                 <variablelist class='unit-directives'>
 280                         <varlistentry>
 281                                 <term><varname>FsckPassNo=</varname></term>
 282
 283                                 <listitem><para>The pass number for
 284                                 the file system checking service for
 285                                 this mount. See
 286                                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 287                                 for more information on this setting.
 288                                 </para></listitem>
 289                         </varlistentry>
 290                 </variablelist>
 291         </refsect1>
 292
 293         <refsect1>
 294                   <title>See Also</title>
 295                   <para>
 296                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 297                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 298                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 299                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 300                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 301                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 302                           <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 303                           <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 304                           <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 305                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 306                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 307                   </para>
 308         </refsect1>
 309
 310 </refentry>