chiark / gitweb /
include <poll.h> instead of <sys/poll.h>
[elogind.git] / man / systemd.mount.xml
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
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd.mount">
25   <refentryinfo>
26     <title>systemd.mount</title>
27     <productname>systemd</productname>
28
29     <authorgroup>
30       <author>
31         <contrib>Developer</contrib>
32         <firstname>Lennart</firstname>
33         <surname>Poettering</surname>
34         <email>lennart@poettering.net</email>
35       </author>
36     </authorgroup>
37   </refentryinfo>
38
39   <refmeta>
40     <refentrytitle>systemd.mount</refentrytitle>
41     <manvolnum>5</manvolnum>
42   </refmeta>
43
44   <refnamediv>
45     <refname>systemd.mount</refname>
46     <refpurpose>Mount unit configuration</refpurpose>
47   </refnamediv>
48
49   <refsynopsisdiv>
50     <para><filename><replaceable>mount</replaceable>.mount</filename></para>
51   </refsynopsisdiv>
52
53   <refsect1>
54     <title>Description</title>
55
56     <para>A unit configuration file whose name ends in
57     <literal>.mount</literal> encodes information about a file system
58     mount point controlled and supervised by systemd.</para>
59
60     <para>This man page lists the configuration options specific to
61     this unit type. See
62     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
63     for the common options of all unit configuration files. The common
64     configuration items are configured in the generic [Unit] and
65     [Install] sections. The mount specific configuration options are
66     configured in the [Mount] section.</para>
67
68     <para>Additional options are listed in
69     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
70     which define the execution environment the
71     <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
72     binary is executed in, and in
73     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
74     which define the way the processes are terminated, and in
75     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
76     which configure resource control settings for the processes of the
77     service. Note that the User= and Group= options are not
78     particularly useful for mount units specifying a
79     <literal>Type=</literal> option or using configuration not
80     specified in <filename>/etc/fstab</filename>;
81     <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
82     will refuse options that are not listed in
83     <filename>/etc/fstab</filename> if it is not run as UID 0.</para>
84
85     <para>Mount units must be named after the mount point directories
86     they control. Example: the mount point
87     <filename noindex='true'>/home/lennart</filename> must be
88     configured in a unit file <filename>home-lennart.mount</filename>.
89     For details about the escaping logic used to convert a file system
90     path to a unit name, see
91     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
92
93     <para>Optionally, a mount unit may be accompanied by an automount
94     unit, to allow on-demand or parallelized mounting. See
95     <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
96
97     <para>If a mount point is beneath another mount point in the file
98     system hierarchy, a dependency between both units is created
99     automatically.</para>
100
101     <para>Mount points created at runtime (independently of unit files
102     or <filename>/etc/fstab</filename>) will be monitored by systemd
103     and appear like any other mount unit in systemd. See
104     <filename>/proc/self/mountinfo</filename> description in
105     <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
106     </para>
107
108     <para>Some file systems have special semantics as API file systems
109     for kernel-to-userspace and userspace-to-userpace interfaces. Some
110     of them may not be changed via mount units, and cannot be
111     disabled. For a longer discussion see <ulink
112     url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
113     File Systems</ulink>.</para>
114   </refsect1>
115
116   <refsect1>
117     <title><filename>fstab</filename></title>
118
119     <para>Mount units may either be configured via unit files, or via
120     <filename>/etc/fstab</filename> (see
121     <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
122     for details). Mounts listed in <filename>/etc/fstab</filename>
123     will be converted into native units dynamically at boot and when
124     the configuration of the system manager is reloaded. In general,
125     configuring mount points through <filename>/etc/fstab</filename>
126     is the preferred approach. See
127     <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
128     for details about the conversion.</para>
129
130     <para>When reading <filename>/etc/fstab</filename> a few special
131     mount options are understood by systemd which influence how
132     dependencies are created for mount points. systemd will create a
133     dependency of type <option>Wants</option> or
134     <option>Requires</option> (see option <option>nofail</option>
135     below), from either <filename>local-fs.target</filename> or
136     <filename>remote-fs.target</filename>, depending whether the file
137     system is local or remote.</para>
138
139     <variablelist class='fstab-options'>
140
141       <varlistentry>
142         <term><option>x-systemd.automount</option></term>
143
144         <listitem><para>An automount unit will be created for the file
145         system. See
146         <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
147         for details.</para></listitem>
148       </varlistentry>
149
150       <varlistentry>
151         <term><option>x-systemd.device-timeout=</option></term>
152
153         <listitem><para>Configure how long systemd should wait for a
154         device to show up before giving up on an entry from
155         <filename>/etc/fstab</filename>. Specify a time in seconds or
156         explicitly append a unit as <literal>s</literal>,
157         <literal>min</literal>, <literal>h</literal>,
158         <literal>ms</literal>.</para>
159
160         <para>Note that this option can only be used in
161         <filename>/etc/fstab</filename>, and will be
162         ignored when part of <varname>Options=</varname>
163         setting in a unit file.</para>
164         </listitem>
165       </varlistentry>
166
167       <varlistentry>
168         <term><option>noauto</option></term>
169         <term><option>auto</option></term>
170
171         <listitem><para>With <option>noauto</option>, this mount will
172         not be added as a dependency for
173         <filename>local-fs.target</filename> or
174         <filename>remote-fs.target</filename>. This means that it will
175         not be mounted automatically during boot, unless it is pulled
176         in by some other unit. Option <option>auto</option> has the
177         opposite meaning and is the default.</para>
178         </listitem>
179       </varlistentry>
180
181       <varlistentry>
182         <term><option>nofail</option></term>
183
184         <listitem><para>With <option>nofail</option> this mount will
185         be only wanted, not required, by
186         <filename>local-fs.target</filename> or
187         <filename>remote-fs.target</filename>. This means that the
188         boot will continue even if this mount point is not mounted
189         successfully.</para>
190         </listitem>
191       </varlistentry>
192
193       <varlistentry>
194         <term><option>x-initrd.mount</option></term>
195
196         <listitem><para>An additional filesystem to be mounted in the
197         initramfs. See <filename>initrd-fs.target</filename>
198         description in
199         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
200         </para></listitem>
201       </varlistentry>
202     </variablelist>
203
204     <para>If a mount point is configured in both
205     <filename>/etc/fstab</filename> and a unit file that is stored
206     below <filename>/usr</filename>, the former will take precedence.
207     If the unit file is stored below <filename>/etc</filename>, it
208     will take precedence. This means: native unit files take
209     precedence over traditional configuration files, but this is
210     superseded by the rule that configuration in
211     <filename>/etc</filename> will always take precedence over
212     configuration in <filename>/usr</filename>.</para>
213   </refsect1>
214
215   <refsect1>
216     <title>Options</title>
217
218     <para>Mount files must include a [Mount] section, which carries
219     information about the file system mount points it supervises. A
220     number of options that may be used in this section are shared with
221     other unit types. These options are documented in
222     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
223     and
224     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
225     The options specific to the [Mount] section of mount units are the
226     following:</para>
227
228     <variablelist class='unit-directives'>
229
230       <varlistentry>
231         <term><varname>What=</varname></term>
232         <listitem><para>Takes an absolute path of a device node, file
233         or other resource to mount. See
234         <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
235         for details. If this refers to a device node, a dependency on
236         the respective device unit is automatically created. (See
237         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
238         for more information.) This option is
239         mandatory.</para></listitem>
240       </varlistentry>
241
242       <varlistentry>
243         <term><varname>Where=</varname></term>
244         <listitem><para>Takes an absolute path of a directory of the
245         mount point. If the mount point does not exist at the time of
246         mounting, it is created. This string must be reflected in the
247         unit filename. (See above.) This option is
248         mandatory.</para></listitem>
249       </varlistentry>
250
251       <varlistentry>
252         <term><varname>Type=</varname></term>
253         <listitem><para>Takes a string for the file system type. See
254         <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
255         for details. This setting is optional.</para></listitem>
256       </varlistentry>
257
258       <varlistentry>
259         <term><varname>Options=</varname></term>
260
261         <listitem><para>Mount options to use when mounting. This takes
262         a comma-separated list of options. This setting is
263         optional.</para></listitem>
264       </varlistentry>
265
266       <varlistentry>
267         <term><varname>SloppyOptions=</varname></term>
268
269         <listitem><para>Takes a boolean argument. If true, parsing of
270         the options specified in <varname>Options=</varname> is
271         relaxed, and unknown mount options are tolerated. This
272         corresponds with
273         <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
274         <parameter>-s</parameter> switch. Defaults to
275         off.</para></listitem>
276       </varlistentry>
277
278       <varlistentry>
279         <term><varname>DirectoryMode=</varname></term>
280         <listitem><para>Directories of mount points (and any parent
281         directories) are automatically created if needed. This option
282         specifies the file system access mode used when creating these
283         directories. Takes an access mode in octal notation. Defaults
284         to 0755.</para></listitem>
285       </varlistentry>
286
287       <varlistentry>
288         <term><varname>TimeoutSec=</varname></term>
289         <listitem><para>Configures the time to wait for the mount
290         command to finish. If a command does not exit within the
291         configured time, the mount will be considered failed and be
292         shut down again. All commands still running will be terminated
293         forcibly via <constant>SIGTERM</constant>, and after another
294         delay of this time with <constant>SIGKILL</constant>. (See
295         <option>KillMode=</option> in
296         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
297         Takes a unit-less value in seconds, or a time span value such
298         as "5min 20s". Pass 0 to disable the timeout logic. The
299         default value is set from the manager configuration file's
300         <varname>DefaultTimeoutStart=</varname>
301         variable.</para></listitem>
302       </varlistentry>
303     </variablelist>
304
305     <para>Check
306     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
307     and
308     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
309     for more settings.</para>
310   </refsect1>
311
312   <refsect1>
313       <title>See Also</title>
314       <para>
315         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
316         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
317         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
318         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
319         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
320         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
321         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
322         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
323         <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
324         <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
325         <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
326         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
327       </para>
328   </refsect1>
329
330 </refentry>