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 program 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
81 <para>Note that the options
<varname>User=
</varname> and
82 <varname>Group=
</varname> are not useful for mount units.
83 systemd passes two parameters to
84 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>;
85 the values of
<varname>What=
</varname> and
<varname>Where=
</varname>.
86 When invoked in this way,
87 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
88 does not read any options from
<filename>/etc/fstab
</filename>, and
89 must be run as UID
0.
</para>
91 <para>Mount units must be named after the mount point directories they control. Example: the mount point
<filename
92 noindex='true'
>/home/lennart
</filename> must be configured in a unit file
<filename>home-lennart.mount
</filename>.
93 For details about the escaping logic used to convert a file system path to a unit name, see
94 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that mount
95 units cannot be templated, nor is possible to add multiple names to a mount unit by creating additional symlinks to
98 <para>Optionally, a mount unit may be accompanied by an automount
99 unit, to allow on-demand or parallelized mounting. See
100 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
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>.
109 <para>Some file systems have special semantics as API file systems
110 for kernel-to-userspace and userspace-to-userspace 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=
"https://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
114 File Systems
</ulink>.
</para>
118 <title>Implicit Dependencies
</title>
120 <para>The following dependencies are implicitly added:
</para>
123 <listitem><para>If a mount unit is beneath another mount unit in the file
124 system hierarchy, both a requirement dependency and an ordering
125 dependency between both units are created automatically.
</para></listitem>
127 <listitem><para>Block device backed file systems automatically gain
128 <varname>BindsTo=
</varname> and
<varname>After=
</varname> type
129 dependencies on the device unit encapsulating the block
130 device (see below).
</para></listitem>
132 <listitem><para>If traditional file system quota is enabled for a mount
133 unit, automatic
<varname>Wants=
</varname> and
134 <varname>Before=
</varname> dependencies on
135 <filename>systemd-quotacheck.service
</filename> and
136 <filename>quotaon.service
</filename> are added.
</para></listitem>
138 <listitem><para>Additional implicit dependencies may be added as result of
139 execution and resource control parameters as documented in
140 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
142 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
148 <title>Default Dependencies
</title>
150 <para>The following dependencies are added unless
<varname>DefaultDependencies=no
</varname> is set:
</para>
153 <listitem><para>All mount units acquire automatic
<varname>Before=
</varname> and
<varname>Conflicts=
</varname> on
154 <filename>umount.target
</filename> in order to be stopped during shutdown.
</para></listitem>
156 <listitem><para>Mount units referring to local file systems automatically gain
157 an
<varname>After=
</varname> dependency on
<filename>local-fs-pre.target
</filename>.
</para></listitem>
159 <listitem><para>Network mount units
160 automatically acquire
<varname>After=
</varname> dependencies on
<filename>remote-fs-pre.target
</filename>,
161 <filename>network.target
</filename> and
<filename>network-online.target
</filename>. Towards the latter a
162 <varname>Wants=
</varname> unit is added as well.
</para></listitem>
165 <para>Mount units referring to local and network file systems are
166 distinguished by their file system type specification. In some cases this is not sufficient (for example network
167 block device based mounts, such as iSCSI), in which case
<option>_netdev
</option> may be added to the mount option
168 string of the unit, which forces systemd to consider the mount unit a network mount.
</para>
172 <title><filename>fstab
</filename></title>
174 <para>Mount units may either be configured via unit files, or via
175 <filename>/etc/fstab
</filename> (see
176 <citerefentry project='man-pages'
><refentrytitle>fstab
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
177 for details). Mounts listed in
<filename>/etc/fstab
</filename>
178 will be converted into native units dynamically at boot and when
179 the configuration of the system manager is reloaded. In general,
180 configuring mount points through
<filename>/etc/fstab
</filename>
181 is the preferred approach. See
182 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
183 for details about the conversion.
</para>
185 <para>The NFS mount option
<option>bg
</option> for NFS background mounts
186 as documented in
<citerefentry project='man-pages'
><refentrytitle>nfs
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
187 is detected by
<command>systemd-fstab-generator
</command> and the options
188 are transformed so that systemd fulfills the job-control implications of
189 that option. Specifically
<command>systemd-fstab-generator
</command> acts
190 as though
<literal>x-systemd.mount-timout=infinity,retry=
10000</literal> was
191 prepended to the option list, and
<literal>fg,nofail
</literal> was appended.
192 Depending on specific requirements, it may be appropriate to provide some of
193 these options explicitly, or to make use of the
194 <literal>x-systemd.automount
</literal> option described below instead
195 of using
<literal>bg
</literal>.
</para>
197 <para>When reading
<filename>/etc/fstab
</filename> a few special
198 mount options are understood by systemd which influence how
199 dependencies are created for mount points. systemd will create a
200 dependency of type
<varname>Wants=
</varname> or
201 <option>Requires
</option> (see option
<option>nofail
</option>
202 below), from either
<filename>local-fs.target
</filename> or
203 <filename>remote-fs.target
</filename>, depending whether the file
204 system is local or remote.
</para>
206 <variablelist class='fstab-options'
>
209 <term><option>x-systemd.requires=
</option></term>
211 <listitem><para>Configures a
<varname>Requires=
</varname> and
212 an
<varname>After=
</varname> dependency between the created
213 mount unit and another systemd unit, such as a device or mount
214 unit. The argument should be a unit name, or an absolute path
215 to a device node or mount point. This option may be specified
216 more than once. This option is particularly useful for mount
217 point declarations that need an additional device to be around
218 (such as an external journal device for journal file systems)
219 or an additional mount to be in place (such as an overlay file
220 system that merges multiple mount points). See
221 <varname>After=
</varname> and
<varname>Requires=
</varname> in
222 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
223 for details.
</para></listitem>
227 <term><option>x-systemd.before=
</option></term>
228 <term><option>x-systemd.after=
</option></term>
230 <listitem><para>Configures a
<varname>Before=
</varname>
231 dependency or
<varname>After=
</varname> between the created
232 mount unit and another systemd unit, such as a mount unit.
233 The argument should be a unit name or an absolute path
234 to a mount point. This option may be specified more than once.
235 This option is particularly useful for mount point declarations
236 with
<option>nofail
</option> option that are mounted
237 asynchronously but need to be mounted before or after some unit
238 start, for example, before
<filename>local-fs.target
</filename>
240 See
<varname>Before=
</varname> and
<varname>After=
</varname> in
241 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
242 for details.
</para></listitem>
246 <term><option>x-systemd.requires-mounts-for=
</option></term>
248 <listitem><para>Configures a
249 <varname>RequiresMountsFor=
</varname> dependency between the
250 created mount unit and other mount units. The argument must be
251 an absolute path. This option may be specified more than once.
252 See
<varname>RequiresMountsFor=
</varname> in
253 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
254 for details.
</para></listitem>
258 <term><option>x-systemd.device-bound
</option></term>
260 <listitem><para>The block device backed file system will be upgraded
261 to
<varname>BindsTo=
</varname> dependency. This option is only useful
262 when mounting file systems manually with
263 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
264 as the default dependency in this case is
<varname>Requires=
</varname>.
265 This option is already implied by entries in
<filename>/etc/fstab
</filename>
271 <term><option>x-systemd.automount
</option></term>
273 <listitem><para>An automount unit will be created for the file
275 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
276 for details.
</para></listitem>
280 <term><option>x-systemd.idle-timeout=
</option></term>
282 <listitem><para>Configures the idle timeout of the
283 automount unit. See
<varname>TimeoutIdleSec=
</varname> in
284 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
285 for details.
</para></listitem>
289 <term><option>x-systemd.device-timeout=
</option></term>
291 <listitem><para>Configure how long systemd should wait for a
292 device to show up before giving up on an entry from
293 <filename>/etc/fstab
</filename>. Specify a time in seconds or
294 explicitly append a unit such as
<literal>s
</literal>,
295 <literal>min
</literal>,
<literal>h
</literal>,
296 <literal>ms
</literal>.
</para>
298 <para>Note that this option can only be used in
299 <filename>/etc/fstab
</filename>, and will be
300 ignored when part of the
<varname>Options=
</varname>
301 setting in a unit file.
</para>
306 <term><option>x-systemd.mount-timeout=
</option></term>
308 <listitem><para>Configure how long systemd should wait for the
309 mount command to finish before giving up on an entry from
310 <filename>/etc/fstab
</filename>. Specify a time in seconds or
311 explicitly append a unit such as
<literal>s
</literal>,
312 <literal>min
</literal>,
<literal>h
</literal>,
313 <literal>ms
</literal>.
</para>
315 <para>Note that this option can only be used in
316 <filename>/etc/fstab
</filename>, and will be
317 ignored when part of the
<varname>Options=
</varname>
318 setting in a unit file.
</para>
320 <para>See
<varname>TimeoutSec=
</varname> below for
326 <term><option>x-systemd.makefs
</option></term>
328 <listitem><para>The file system or swap structure will be intialized
329 on the device. If the device is not
"empty", i.e. it contains any signature,
330 the operation will be skipped. It is hence expected that this option
331 remains set even after the device has been initalized.
</para>
333 <para>Note that this option can only be used in
334 <filename>/etc/fstab
</filename>, and will be ignored when part of the
335 <varname>Options=
</varname> setting in a unit file.
</para>
338 <citerefentry><refentrytitle>systemd-makefs@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
341 <para><citerefentry project='man-pages'
><refentrytitle>wipefs
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
342 may be used to remove any signatures from a block device to force
343 <option>x-systemd.makefs
</option> to reinitialize the device.
</para>
348 <term><option>x-systemd.growfs
</option></term>
350 <listitem><para>The file system will be grown to occupy the full block
351 device. If the file system is already at maximum size, no action will
352 be performed. It is hence expected that this option remains set even after
353 the file system has been grown. Only certain file system types are supported,
355 <citerefentry><refentrytitle>systemd-makefs@.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
358 <para>Note that this option can only be used in
359 <filename>/etc/fstab
</filename>, and will be ignored when part of the
360 <varname>Options=
</varname> setting in a unit file.
</para></listitem>
364 <term><option>_netdev
</option></term>
366 <listitem><para>Normally the file system type is used to determine if a
367 mount is a
"network mount", i.e. if it should only be started after the
368 network is available. Using this option overrides this detection and
369 specifies that the mount requires network.
</para>
371 <para>Network mount units are ordered between
<filename>remote-fs-pre.target
</filename>
372 and
<filename>remote-fs.target
</filename>, instead of
373 <filename>local-fs-pre.target
</filename> and
<filename>local-fs.target
</filename>.
374 They also pull in
<filename>network-online.target
</filename> and are ordered after
375 it and
<filename>network.target
</filename>.
</para>
380 <term><option>noauto
</option></term>
381 <term><option>auto
</option></term>
383 <listitem><para>With
<option>noauto
</option>, the mount unit will not be added as a dependency for
384 <filename>local-fs.target
</filename> or
<filename>remote-fs.target
</filename>. This means that it will not be
385 mounted automatically during boot, unless it is pulled in by some other unit. The
<option>auto
</option> option
386 has the opposite meaning and is the default. Note that the
<option>noauto
</option> option has an effect on the
387 mount unit itself only — if
<option>x-systemd.automount
</option> is used (see above), then the matching
388 automount unit will still be pulled in by these targets.
</para>
393 <term><option>nofail
</option></term>
395 <listitem><para>With
<option>nofail
</option>, this mount will
396 be only wanted, not required, by
397 <filename>local-fs.target
</filename> or
398 <filename>remote-fs.target
</filename>. This means that the
399 boot will continue even if this mount point is not mounted
405 <term><option>x-initrd.mount
</option></term>
407 <listitem><para>An additional filesystem to be mounted in the
408 initramfs. See
<filename>initrd-fs.target
</filename>
410 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
415 <para>If a mount point is configured in both
416 <filename>/etc/fstab
</filename> and a unit file that is stored
417 below
<filename>/usr
</filename>, the former will take precedence.
418 If the unit file is stored below
<filename>/etc
</filename>, it
419 will take precedence. This means: native unit files take
420 precedence over traditional configuration files, but this is
421 superseded by the rule that configuration in
422 <filename>/etc
</filename> will always take precedence over
423 configuration in
<filename>/usr
</filename>.
</para>
427 <title>Options
</title>
429 <para>Mount files must include a [Mount] section, which carries
430 information about the file system mount points it supervises. A
431 number of options that may be used in this section are shared with
432 other unit types. These options are documented in
433 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
435 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
436 The options specific to the [Mount] section of mount units are the
439 <variablelist class='unit-directives'
>
442 <term><varname>What=
</varname></term>
443 <listitem><para>Takes an absolute path of a device node, file or other resource to mount. See
<citerefentry
444 project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry> for details. If
445 this refers to a device node, a dependency on the respective device unit is automatically created. (See
446 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
447 information.) This option is mandatory. Note that the usual specifier expansion is applied to this setting,
448 literal percent characters should hence be written as
<literal>%%
</literal>.
</para></listitem>
452 <term><varname>Where=
</varname></term>
453 <listitem><para>Takes an absolute path of a directory for the
454 mount point; in particular, the destination cannot be a symbolic
455 link. If the mount point does not exist at the time of
456 mounting, it is created. This string must be reflected in the
457 unit filename. (See above.) This option is
458 mandatory.
</para></listitem>
462 <term><varname>Type=
</varname></term>
463 <listitem><para>Takes a string for the file system type. See
464 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
465 for details. This setting is optional.
</para></listitem>
469 <term><varname>Options=
</varname></term>
471 <listitem><para>Mount options to use when mounting. This takes a comma-separated list of options. This setting
472 is optional. Note that the usual specifier expansion is applied to this setting, literal percent characters
473 should hence be written as
<literal>%%
</literal>.
</para></listitem>
477 <term><varname>SloppyOptions=
</varname></term>
479 <listitem><para>Takes a boolean argument. If true, parsing of
480 the options specified in
<varname>Options=
</varname> is
481 relaxed, and unknown mount options are tolerated. This
483 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
484 <parameter>-s
</parameter> switch. Defaults to
485 off.
</para></listitem>
489 <term><varname>LazyUnmount=
</varname></term>
491 <listitem><para>Takes a boolean argument. If true, detach the
492 filesystem from the filesystem hierarchy at time of the unmount
493 operation, and clean up all references to the filesystem as
494 soon as they are not busy anymore.
495 This corresponds with
496 <citerefentry project='man-pages'
><refentrytitle>umount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
497 <parameter>-l
</parameter> switch. Defaults to
498 off.
</para></listitem>
502 <term><varname>ForceUnmount=
</varname></term>
504 <listitem><para>Takes a boolean argument. If true, force an
505 unmount (in case of an unreachable NFS system).
506 This corresponds with
507 <citerefentry project='man-pages'
><refentrytitle>umount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
508 <parameter>-f
</parameter> switch. Defaults to
509 off.
</para></listitem>
513 <term><varname>DirectoryMode=
</varname></term>
514 <listitem><para>Directories of mount points (and any parent
515 directories) are automatically created if needed. This option
516 specifies the file system access mode used when creating these
517 directories. Takes an access mode in octal notation. Defaults
518 to
0755.
</para></listitem>
522 <term><varname>TimeoutSec=
</varname></term>
523 <listitem><para>Configures the time to wait for the mount
524 command to finish. If a command does not exit within the
525 configured time, the mount will be considered failed and be
526 shut down again. All commands still running will be terminated
527 forcibly via
<constant>SIGTERM
</constant>, and after another
528 delay of this time with
<constant>SIGKILL
</constant>. (See
529 <option>KillMode=
</option> in
530 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
531 Takes a unit-less value in seconds, or a time span value such
532 as
"5min 20s". Pass
0 to disable the timeout logic. The
533 default value is set from the manager configuration file's
534 <varname>DefaultTimeoutStartSec=
</varname>
535 variable.
</para></listitem>
540 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
542 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
543 for more settings.
</para>
547 <title>See Also
</title>
549 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
550 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
551 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
552 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
553 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
554 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
555 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
556 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
557 <citerefentry project='man-pages'
><refentrytitle>proc
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
558 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
559 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
560 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>