chiark / gitweb /
networkd: support vxlan parameters
[elogind.git] / 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>