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">
6 SPDX-License-Identifier: LGPL-2.1+
8 This file is part of systemd.
10 Copyright 2010 Lennart Poettering
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"systemd.mount">
28 <title>systemd.mount
</title>
29 <productname>systemd
</productname>
33 <contrib>Developer
</contrib>
34 <firstname>Lennart
</firstname>
35 <surname>Poettering
</surname>
36 <email>lennart@poettering.net
</email>
42 <refentrytitle>systemd.mount
</refentrytitle>
43 <manvolnum>5</manvolnum>
47 <refname>systemd.mount
</refname>
48 <refpurpose>Mount unit configuration
</refpurpose>
52 <para><filename><replaceable>mount
</replaceable>.mount
</filename></para>
56 <title>Description
</title>
58 <para>A unit configuration file whose name ends in
59 <literal>.mount
</literal> encodes information about a file system
60 mount point controlled and supervised by systemd.
</para>
62 <para>This man page lists the configuration options specific to
64 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
65 for the common options of all unit configuration files. The common
66 configuration items are configured in the generic [Unit] and
67 [Install] sections. The mount specific configuration options are
68 configured in the [Mount] section.
</para>
70 <para>Additional options are listed in
71 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
72 which define the execution environment the
73 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
74 binary is executed in, and in
75 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
76 which define the way the processes are terminated, and in
77 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
78 which configure resource control settings for the processes of the
79 service. Note that the User= and Group= options are not
80 particularly useful for mount units specifying a
81 <literal>Type=
</literal> option or using configuration not
82 specified in
<filename>/etc/fstab
</filename>;
83 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
84 will refuse options that are not listed in
85 <filename>/etc/fstab
</filename> if it is not run as UID
0.
</para>
87 <para>Mount units must be named after the mount point directories they control. Example: the mount point
<filename
88 noindex='true'
>/home/lennart
</filename> must be configured in a unit file
<filename>home-lennart.mount
</filename>.
89 For details about the escaping logic used to convert a file system path to a unit name, see
90 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount
91 units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to
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>
98 <para>Mount points created at runtime (independently of unit files
99 or
<filename>/etc/fstab
</filename>) will be monitored by systemd
100 and appear like any other mount unit in systemd. See
101 <filename>/proc/self/mountinfo
</filename> description in
102 <citerefentry project='man-pages'
><refentrytitle>proc
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
105 <para>Some file systems have special semantics as API file systems
106 for kernel-to-userspace and userspace-to-userspace interfaces. Some
107 of them may not be changed via mount units, and cannot be
108 disabled. For a longer discussion see
<ulink
109 url=
"https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
110 File Systems
</ulink>.
</para>
114 <title>Implicit Dependencies
</title>
116 <para>The following dependencies are implicitly added:
</para>
119 <listitem><para>If a mount unit is beneath another mount unit in the file
120 system hierarchy, both a requirement dependency and an ordering
121 dependency between both units are created automatically.
</para></listitem>
123 <listitem><para>Block device backed file systems automatically gain
124 <varname>BindsTo=
</varname> and
<varname>After=
</varname> type
125 dependencies on the device unit encapsulating the block
126 device (see below).
</para></listitem>
128 <listitem><para>If traditional file system quota is enabled for a mount
129 unit, automatic
<varname>Wants=
</varname> and
130 <varname>Before=
</varname> dependencies on
131 <filename>systemd-quotacheck.service
</filename> and
132 <filename>quotaon.service
</filename> are added.
</para></listitem>
134 <listitem><para>Additional implicit dependencies may be added as result of
135 execution and resource control parameters as documented in
136 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
138 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
144 <title>Default Dependencies
</title>
146 <para>The following dependencies are added unless
<varname>DefaultDependencies=no
</varname> is set:
</para>
149 <listitem><para>All mount units acquire automatic
<varname>Before=
</varname> and
<varname>Conflicts=
</varname> on
150 <filename>umount.target
</filename> in order to be stopped during shutdown.
</para></listitem>
152 <listitem><para>Mount units referring to local file systems automatically gain
153 an
<varname>After=
</varname> dependency on
<filename>local-fs-pre.target
</filename>.
</para></listitem>
155 <listitem><para>Network mount units
156 automatically acquire
<varname>After=
</varname> dependencies on
<filename>remote-fs-pre.target
</filename>,
157 <filename>network.target
</filename> and
<filename>network-online.target
</filename>. Towards the latter a
158 <varname>Wants=
</varname> unit is added as well.
</para></listitem>
161 <para>Mount units referring to local and network file systems are
162 distinguished by their file system type specification. In some cases this is not sufficient (for example network
163 block device based mounts, such as iSCSI), in which case
<option>_netdev
</option> may be added to the mount option
164 string of the unit, which forces systemd to consider the mount unit a network mount.
</para>
168 <title><filename>fstab
</filename></title>
170 <para>Mount units may either be configured via unit files, or via
171 <filename>/etc/fstab
</filename> (see
172 <citerefentry project='man-pages'
><refentrytitle>fstab
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
173 for details). Mounts listed in
<filename>/etc/fstab
</filename>
174 will be converted into native units dynamically at boot and when
175 the configuration of the system manager is reloaded. In general,
176 configuring mount points through
<filename>/etc/fstab
</filename>
177 is the preferred approach. See
178 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
179 for details about the conversion.
</para>
181 <para>The NFS mount option
<option>bg
</option> for NFS background mounts
182 as documented in
<citerefentry project='man-pages'
><refentrytitle>nfs
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
183 is detected by
<command>systemd-fstab-generator
</command> and the options
184 are transformed so that systemd fulfills the job-control implications of
185 that option. Specifically
<command>systemd-fstab-generator
</command> acts
186 as though
<literal>x-systemd.mount-timout=infinity,retry=
10000</literal> was
187 prepended to the option list, and
<literal>fg,nofail
</literal> was appended.
188 Depending on specific requirements, it may be appropriate to provide some of
189 these options explicitly, or to make use of the
190 <literal>x-systemd.automount
</literal> option described below instead
191 of using
<literal>bg
</literal>.
</para>
193 <para>When reading
<filename>/etc/fstab
</filename> a few special
194 mount options are understood by systemd which influence how
195 dependencies are created for mount points. systemd will create a
196 dependency of type
<varname>Wants=
</varname> or
197 <option>Requires
</option> (see option
<option>nofail
</option>
198 below), from either
<filename>local-fs.target
</filename> or
199 <filename>remote-fs.target
</filename>, depending whether the file
200 system is local or remote.
</para>
202 <variablelist class='fstab-options'
>
205 <term><option>x-systemd.requires=
</option></term>
207 <listitem><para>Configures a
<varname>Requires=
</varname> and
208 an
<varname>After=
</varname> dependency between the created
209 mount unit and another systemd unit, such as a device or mount
210 unit. The argument should be a unit name, or an absolute path
211 to a device node or mount point. This option may be specified
212 more than once. This option is particularly useful for mount
213 point declarations that need an additional device to be around
214 (such as an external journal device for journal file systems)
215 or an additional mount to be in place (such as an overlay file
216 system that merges multiple mount points). See
217 <varname>After=
</varname> and
<varname>Requires=
</varname> in
218 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
219 for details.
</para></listitem>
223 <term><option>x-systemd.before=
</option></term>
224 <term><option>x-systemd.after=
</option></term>
226 <listitem><para>Configures a
<varname>Before=
</varname>
227 dependency or
<varname>After=
</varname> between the created
228 mount unit and another systemd unit, such as a mount unit.
229 The argument should be a unit name or an absolute path
230 to a mount point. This option may be specified more than once.
231 This option is particularly useful for mount point declarations
232 with
<option>nofail
</option> option that are mounted
233 asynchronously but need to be mounted before or after some unit
234 start, for example, before
<filename>local-fs.target
</filename>
236 See
<varname>Before=
</varname> and
<varname>After=
</varname> in
237 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
238 for details.
</para></listitem>
242 <term><option>x-systemd.requires-mounts-for=
</option></term>
244 <listitem><para>Configures a
245 <varname>RequiresMountsFor=
</varname> dependency between the
246 created mount unit and other mount units. The argument must be
247 an absolute path. This option may be specified more than once.
248 See
<varname>RequiresMountsFor=
</varname> in
249 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
250 for details.
</para></listitem>
254 <term><option>x-systemd.device-bound
</option></term>
256 <listitem><para>The block device backed file system will be upgraded
257 to
<varname>BindsTo=
</varname> dependency. This option is only useful
258 when mounting file systems manually with
259 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
260 as the default dependency in this case is
<varname>Requires=
</varname>.
261 This option is already implied by entries in
<filename>/etc/fstab
</filename>
267 <term><option>x-systemd.automount
</option></term>
269 <listitem><para>An automount unit will be created for the file
271 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
272 for details.
</para></listitem>
276 <term><option>x-systemd.idle-timeout=
</option></term>
278 <listitem><para>Configures the idle timeout of the
279 automount unit. See
<varname>TimeoutIdleSec=
</varname> in
280 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
281 for details.
</para></listitem>
285 <term><option>x-systemd.device-timeout=
</option></term>
287 <listitem><para>Configure how long systemd should wait for a
288 device to show up before giving up on an entry from
289 <filename>/etc/fstab
</filename>. Specify a time in seconds or
290 explicitly append a unit such as
<literal>s
</literal>,
291 <literal>min
</literal>,
<literal>h
</literal>,
292 <literal>ms
</literal>.
</para>
294 <para>Note that this option can only be used in
295 <filename>/etc/fstab
</filename>, and will be
296 ignored when part of the
<varname>Options=
</varname>
297 setting in a unit file.
</para>
302 <term><option>x-systemd.mount-timeout=
</option></term>
304 <listitem><para>Configure how long systemd should wait for the
305 mount command to finish before giving up on an entry from
306 <filename>/etc/fstab
</filename>. Specify a time in seconds or
307 explicitly append a unit such as
<literal>s
</literal>,
308 <literal>min
</literal>,
<literal>h
</literal>,
309 <literal>ms
</literal>.
</para>
311 <para>Note that this option can only be used in
312 <filename>/etc/fstab
</filename>, and will be
313 ignored when part of the
<varname>Options=
</varname>
314 setting in a unit file.
</para>
316 <para>See
<varname>TimeoutSec=
</varname> below for
322 <term><option>_netdev
</option></term>
324 <listitem><para>Normally the file system type is used to determine if a
325 mount is a
"network mount", i.e. if it should only be started after the
326 network is available. Using this option overrides this detection and
327 specifies that the mount requires network.
</para>
329 <para>Network mount units are ordered between
<filename>remote-fs-pre.target
</filename>
330 and
<filename>remote-fs.target
</filename>, instead of
331 <filename>local-fs-pre.target
</filename> and
<filename>local-fs.target
</filename>.
332 They also pull in
<filename>network-online.target
</filename> and are ordered after
333 it and
<filename>network.target
</filename>.
</para>
338 <term><option>noauto
</option></term>
339 <term><option>auto
</option></term>
341 <listitem><para>With
<option>noauto
</option>, the mount unit will not be added as a dependency for
342 <filename>local-fs.target
</filename> or
<filename>remote-fs.target
</filename>. This means that it will not be
343 mounted automatically during boot, unless it is pulled in by some other unit. The
<option>auto
</option> option
344 has the opposite meaning and is the default. Note that the
<option>noauto
</option> option has an effect on the
345 mount unit itself only — if
<option>x-systemd.automount
</option> is used (see above), then the matching
346 automount unit will still be pulled in by these targets.
</para>
351 <term><option>nofail
</option></term>
353 <listitem><para>With
<option>nofail
</option>, this mount will
354 be only wanted, not required, by
355 <filename>local-fs.target
</filename> or
356 <filename>remote-fs.target
</filename>. This means that the
357 boot will continue even if this mount point is not mounted
363 <term><option>x-initrd.mount
</option></term>
365 <listitem><para>An additional filesystem to be mounted in the
366 initramfs. See
<filename>initrd-fs.target
</filename>
368 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
373 <para>If a mount point is configured in both
374 <filename>/etc/fstab
</filename> and a unit file that is stored
375 below
<filename>/usr
</filename>, the former will take precedence.
376 If the unit file is stored below
<filename>/etc
</filename>, it
377 will take precedence. This means: native unit files take
378 precedence over traditional configuration files, but this is
379 superseded by the rule that configuration in
380 <filename>/etc
</filename> will always take precedence over
381 configuration in
<filename>/usr
</filename>.
</para>
385 <title>Options
</title>
387 <para>Mount files must include a [Mount] section, which carries
388 information about the file system mount points it supervises. A
389 number of options that may be used in this section are shared with
390 other unit types. These options are documented in
391 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
393 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
394 The options specific to the [Mount] section of mount units are the
397 <variablelist class='unit-directives'
>
400 <term><varname>What=
</varname></term>
401 <listitem><para>Takes an absolute path of a device node, file or other resource to mount. See
<citerefentry
402 project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details. If
403 this refers to a device node, a dependency on the respective device unit is automatically created. (See
404 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
405 information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting,
406 literal percent characters should hence be written as
<literal>%%
</literal>.
</para></listitem>
410 <term><varname>Where=
</varname></term>
411 <listitem><para>Takes an absolute path of a directory for the
412 mount point; in particular, the destination cannot be a symbolic
413 link. If the mount point does not exist at the time of
414 mounting, it is created. This string must be reflected in the
415 unit filename. (See above.) This option is
416 mandatory.
</para></listitem>
420 <term><varname>Type=
</varname></term>
421 <listitem><para>Takes a string for the file system type. See
422 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
423 for details. This setting is optional.
</para></listitem>
427 <term><varname>Options=
</varname></term>
429 <listitem><para>Mount options to use when mounting. This takes a comma-separated list of options. This setting
430 is optional. Note that the usual specifier expansion is applied to this setting, literal percent characters
431 should hence be written as
<literal>%%
</literal>.
</para></listitem>
435 <term><varname>SloppyOptions=
</varname></term>
437 <listitem><para>Takes a boolean argument. If true, parsing of
438 the options specified in
<varname>Options=
</varname> is
439 relaxed, and unknown mount options are tolerated. This
441 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
442 <parameter>-s
</parameter> switch. Defaults to
443 off.
</para></listitem>
447 <term><varname>LazyUnmount=
</varname></term>
449 <listitem><para>Takes a boolean argument. If true, detach the
450 filesystem from the filesystem hierarchy at time of the unmount
451 operation, and clean up all references to the filesystem as
452 soon as they are not busy anymore.
453 This corresponds with
454 <citerefentry project='man-pages'
><refentrytitle>umount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
455 <parameter>-l
</parameter> switch. Defaults to
456 off.
</para></listitem>
460 <term><varname>ForceUnmount=
</varname></term>
462 <listitem><para>Takes a boolean argument. If true, force an
463 unmount (in case of an unreachable NFS system).
464 This corresponds with
465 <citerefentry project='man-pages'
><refentrytitle>umount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
466 <parameter>-f
</parameter> switch. Defaults to
467 off.
</para></listitem>
471 <term><varname>DirectoryMode=
</varname></term>
472 <listitem><para>Directories of mount points (and any parent
473 directories) are automatically created if needed. This option
474 specifies the file system access mode used when creating these
475 directories. Takes an access mode in octal notation. Defaults
476 to
0755.
</para></listitem>
480 <term><varname>TimeoutSec=
</varname></term>
481 <listitem><para>Configures the time to wait for the mount
482 command to finish. If a command does not exit within the
483 configured time, the mount will be considered failed and be
484 shut down again. All commands still running will be terminated
485 forcibly via
<constant>SIGTERM
</constant>, and after another
486 delay of this time with
<constant>SIGKILL
</constant>. (See
487 <option>KillMode=
</option> in
488 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
489 Takes a unit-less value in seconds, or a time span value such
490 as
"5min 20s". Pass
0 to disable the timeout logic. The
491 default value is set from the manager configuration file's
492 <varname>DefaultTimeoutStartSec=
</varname>
493 variable.
</para></listitem>
498 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
500 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
501 for more settings.
</para>
505 <title>See Also
</title>
507 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
508 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
509 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
510 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
511 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
512 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
513 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
514 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
515 <citerefentry project='man-pages'
><refentrytitle>proc
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
516 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
517 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
518 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>