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" [
4 <!ENTITY % entities SYSTEM
"custom-entities.ent" >
9 This file is part of systemd.
11 Copyright 2010 Lennart Poettering
13 systemd is free software; you can redistribute it and/or modify it
14 under the terms of the GNU Lesser General Public License as published by
15 the Free Software Foundation; either version 2.1 of the License, or
16 (at your option) any later version.
18 systemd is distributed in the hope that it will be useful, but
19 WITHOUT ANY WARRANTY; without even the implied warranty of
20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 Lesser General Public License for more details.
23 You should have received a copy of the GNU Lesser General Public License
24 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 <refentry id=
"systemd.mount">
29 <title>systemd.mount
</title>
30 <productname>systemd
</productname>
34 <contrib>Developer
</contrib>
35 <firstname>Lennart
</firstname>
36 <surname>Poettering
</surname>
37 <email>lennart@poettering.net
</email>
43 <refentrytitle>systemd.mount
</refentrytitle>
44 <manvolnum>5</manvolnum>
48 <refname>systemd.mount
</refname>
49 <refpurpose>Mount unit configuration
</refpurpose>
53 <para><filename><replaceable>mount
</replaceable>.mount
</filename></para>
57 <title>Description
</title>
59 <para>A unit configuration file whose name ends in
60 <literal>.mount
</literal> encodes information about a file system
61 mount point controlled and supervised by systemd.
</para>
63 <para>This man page lists the configuration options specific to
65 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
66 for the common options of all unit configuration files. The common
67 configuration items are configured in the generic [Unit] and
68 [Install] sections. The mount specific configuration options are
69 configured in the [Mount] section.
</para>
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 project='man-pages'
><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 in
78 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
79 which configure resource control settings for the processes of the
80 service. Note that the User= and Group= options are not
81 particularly useful for mount units specifying a
82 <literal>Type=
</literal> option or using configuration not
83 specified in
<filename>/etc/fstab
</filename>;
84 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
85 will refuse options that are not listed in
86 <filename>/etc/fstab
</filename> if it is not run as UID
0.
</para>
88 <para>Mount units must be named after the mount point directories
89 they control. Example: the mount point
90 <filename noindex='true'
>/home/lennart
</filename> must be
91 configured in a unit file
<filename>home-lennart.mount
</filename>.
92 For details 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>
96 <para>Optionally, a mount unit may be accompanied by an automount
97 unit, to allow on-demand or parallelized mounting. See
98 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
100 <para>If a mount point is beneath another mount point in the file
101 system hierarchy, a dependency between both units is created
102 automatically.
</para>
104 <para>Mount points created at runtime (independently of unit files
105 or
<filename>/etc/fstab
</filename>) will be monitored by systemd
106 and appear like any other mount unit in systemd. See
107 <filename>/proc/self/mountinfo
</filename> description in
108 <citerefentry project='man-pages'
><refentrytitle>proc
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
111 <para>Some file systems have special semantics as API file systems
112 for kernel-to-userspace and userspace-to-userspace interfaces. Some
113 of them may not be changed via mount units, and cannot be
114 disabled. For a longer discussion see
<ulink
115 url=
"http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
116 File Systems
</ulink>.
</para>
120 <title><filename>fstab
</filename></title>
122 <para>Mount units may either be configured via unit files, or via
123 <filename>/etc/fstab
</filename> (see
124 <citerefentry project='man-pages'
><refentrytitle>fstab
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
125 for details). Mounts listed in
<filename>/etc/fstab
</filename>
126 will be converted into native units dynamically at boot and when
127 the configuration of the system manager is reloaded. In general,
128 configuring mount points through
<filename>/etc/fstab
</filename>
129 is the preferred approach. See
130 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
131 for details about the conversion.
</para>
133 <para>When reading
<filename>/etc/fstab
</filename> a few special
134 mount options are understood by systemd which influence how
135 dependencies are created for mount points. systemd will create a
136 dependency of type
<option>Wants
</option> or
137 <option>Requires
</option> (see option
<option>nofail
</option>
138 below), from either
<filename>local-fs.target
</filename> or
139 <filename>remote-fs.target
</filename>, depending whether the file
140 system is local or remote.
</para>
142 <variablelist class='fstab-options'
>
145 <term><option>x-systemd.requires=
</option></term>
147 <listitem><para>Configures a
<varname>Requires=
</varname> and
148 an
<varname>After=
</varname> dependency between the created
149 mount unit and another systemd unit, such as a device or mount
150 unit. The argument should be a unit name, or an absolute path
151 to a device node or mount point. This option may be specified
152 more than once. This option is particularly useful for mount
153 point declarations that need an additional device to be around
154 (such as an external journal device for journal file systems)
155 or an additional mount to be in place (such as an overlay file
156 system that merges multiple mount points). See
157 <varname>After=
</varname> and
<varname>Requires=
</varname> in
158 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
159 for details.
</para></listitem>
163 <term><option>x-systemd.requires-mounts-for=
</option></term>
165 <listitem><para>Configures a
166 <varname>RequiresMountsFor=
</varname> dependency between the
167 created mount unit and other mount units. The argument must be
168 an absolute path. This option may be specified more than once.
169 See
<varname>RequiresMountsFor=
</varname> in
170 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
171 for details.
</para></listitem>
175 <term><option>x-systemd.automount
</option></term>
177 <listitem><para>An automount unit will be created for the file
179 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
180 for details.
</para></listitem>
184 <term><option>x-systemd.idle-timeout=
</option></term>
186 <listitem><para>Configures the idleness timeout of the
187 automount unit. See
<varname>TimeoutIdleSec=
</varname> in
188 <citerefentry><refentrytitle>systemd.automount
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
189 for details.
</para></listitem>
193 <term><option>x-systemd.device-timeout=
</option></term>
195 <listitem><para>Configure how long systemd should wait for a
196 device to show up before giving up on an entry from
197 <filename>/etc/fstab
</filename>. Specify a time in seconds or
198 explicitly append a unit as
<literal>s
</literal>,
199 <literal>min
</literal>,
<literal>h
</literal>,
200 <literal>ms
</literal>.
</para>
202 <para>Note that this option can only be used in
203 <filename>/etc/fstab
</filename>, and will be
204 ignored when part of
<varname>Options=
</varname>
205 setting in a unit file.
</para>
210 <term><option>noauto
</option></term>
211 <term><option>auto
</option></term>
213 <listitem><para>With
<option>noauto
</option>, this mount will
214 not be added as a dependency for
215 <filename>local-fs.target
</filename> or
216 <filename>remote-fs.target
</filename>. This means that it will
217 not be mounted automatically during boot, unless it is pulled
218 in by some other unit. Option
<option>auto
</option> has the
219 opposite meaning and is the default.
</para>
224 <term><option>nofail
</option></term>
226 <listitem><para>With
<option>nofail
</option> this mount will
227 be only wanted, not required, by
228 <filename>local-fs.target
</filename> or
229 <filename>remote-fs.target
</filename>. This means that the
230 boot will continue even if this mount point is not mounted
236 <term><option>x-initrd.mount
</option></term>
238 <listitem><para>An additional filesystem to be mounted in the
239 initramfs. See
<filename>initrd-fs.target
</filename>
241 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
246 <para>If a mount point is configured in both
247 <filename>/etc/fstab
</filename> and a unit file that is stored
248 below
<filename>/usr
</filename>, the former will take precedence.
249 If the unit file is stored below
<filename>/etc
</filename>, it
250 will take precedence. This means: native unit files take
251 precedence over traditional configuration files, but this is
252 superseded by the rule that configuration in
253 <filename>/etc
</filename> will always take precedence over
254 configuration in
<filename>/usr
</filename>.
</para>
258 <title>Options
</title>
260 <para>Mount files must include a [Mount] section, which carries
261 information about the file system mount points it supervises. A
262 number of options that may be used in this section are shared with
263 other unit types. These options are documented in
264 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
266 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
267 The options specific to the [Mount] section of mount units are the
270 <variablelist class='unit-directives'
>
273 <term><varname>What=
</varname></term>
274 <listitem><para>Takes an absolute path of a device node, file
275 or other resource to mount. See
276 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
277 for details. If this refers to a device node, a dependency on
278 the respective device unit is automatically created. (See
279 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
280 for more information.) This option is
281 mandatory.
</para></listitem>
285 <term><varname>Where=
</varname></term>
286 <listitem><para>Takes an absolute path of a directory of the
287 mount point. If the mount point does not exist at the time of
288 mounting, it is created. This string must be reflected in the
289 unit filename. (See above.) This option is
290 mandatory.
</para></listitem>
294 <term><varname>Type=
</varname></term>
295 <listitem><para>Takes a string for the file system type. See
296 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
297 for details. This setting is optional.
</para></listitem>
301 <term><varname>Options=
</varname></term>
303 <listitem><para>Mount options to use when mounting. This takes
304 a comma-separated list of options. This setting is
305 optional.
</para></listitem>
309 <term><varname>SloppyOptions=
</varname></term>
311 <listitem><para>Takes a boolean argument. If true, parsing of
312 the options specified in
<varname>Options=
</varname> is
313 relaxed, and unknown mount options are tolerated. This
315 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
316 <parameter>-s
</parameter> switch. Defaults to
317 off.
</para></listitem>
321 <term><varname>DirectoryMode=
</varname></term>
322 <listitem><para>Directories of mount points (and any parent
323 directories) are automatically created if needed. This option
324 specifies the file system access mode used when creating these
325 directories. Takes an access mode in octal notation. Defaults
326 to
0755.
</para></listitem>
330 <term><varname>TimeoutSec=
</varname></term>
331 <listitem><para>Configures the time to wait for the mount
332 command to finish. If a command does not exit within the
333 configured time, the mount will be considered failed and be
334 shut down again. All commands still running will be terminated
335 forcibly via
<constant>SIGTERM
</constant>, and after another
336 delay of this time with
<constant>SIGKILL
</constant>. (See
337 <option>KillMode=
</option> in
338 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
339 Takes a unit-less value in seconds, or a time span value such
340 as
"5min 20s". Pass
0 to disable the timeout logic. The
341 default value is set from the manager configuration file's
342 <varname>DefaultTimeoutStart=
</varname>
343 variable.
</para></listitem>
348 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
350 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
351 for more settings.
</para>
355 <title>See Also
</title>
357 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
358 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
361 <citerefentry><refentrytitle>systemd.kill
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
362 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
363 <citerefentry><refentrytitle>systemd.service
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
364 <citerefentry><refentrytitle>systemd.device
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
365 <citerefentry project='man-pages'
><refentrytitle>proc
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
366 <citerefentry project='man-pages'
><refentrytitle>mount
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
367 <citerefentry><refentrytitle>systemd-fstab-generator
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
368 <citerefentry><refentrytitle>systemd.directives
</refentrytitle><manvolnum>7</manvolnum></citerefentry>