chiark / gitweb /
f319cf7ce9d36f8921f23e724ced28efc9437764
[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>systemd.mount</filename></para>
52         </refsynopsisdiv>
53
54         <refsect1>
55                 <title>Description</title>
56
57                 <para>A unit configuration file whose name ends in
58                 <filename>.mount</filename> 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
78                 terminated. Note that the User= and Group= options are
79                 not particularly useful for mount units specifying a
80                 <literal>Type=</literal> option or using configuration
81                 not specified in <filename>/etc/fstab</filename>;
82                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
83                 will refuse options that aren't listed in
84                 <filename>/etc/fstab</filename> if it is not run as
85                 UID 0.</para>
86
87                 <para>Mount units must be named after the mount point
88                 directories they control. Example: the mount point
89                 <filename>/home/lennart</filename> must be configured
90                 in a unit file
91                 <filename>home-lennart.mount</filename>. For details
92                 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>
95
96                 <para>Optionally, a mount unit may be accompanied by
97                 an automount unit, to allow on-demand or parallelized
98                 mounting. See
99                 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
100
101                 <para>If a mount point is beneath another mount point
102                 in the file system hierarchy, a dependency between both
103                 units is created automatically.</para>
104
105                 <para>Mount points created at runtime (independently of
106                 unit files or <filename>/etc/fstab</filename>) will be
107                 monitored by systemd and appear like any other mount
108                 unit in systemd.
109                 See <filename>/proc/self/mountinfo</filename> description
110                 in <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
111                 </para>
112
113                 <para>Some file systems have special semantics as API
114                 file systems for kernel-to-userspace and
115                 userspace-to-userpace interfaces. Some of them may not
116                 be changed via mount units, and cannot be disabled.
117                 For a longer discussion see <ulink
118                 url="http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems">API
119                 File Systems</ulink>.</para>
120         </refsect1>
121
122         <refsect1>
123                 <title><filename>/etc/fstab</filename></title>
124
125                 <para>Mount units may either be configured via unit
126                 files, or via <filename>/etc/fstab</filename> (see
127                 <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
128                 for details). Mounts listed in
129                 <filename>/etc/fstab</filename> will be converted into
130                 native units dynamically at boot and when the
131                 configuration of the system manager is reloaded. See
132                 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
133                 for details about the conversion.</para>
134
135                 <para>When reading <filename>/etc/fstab</filename> a
136                 few special mount options are understood by systemd
137                 which influence how dependencies are created for mount
138                 points from <filename>/etc/fstab</filename>. systemd
139                 will create a dependency of type
140                 <option>Wants</option> from either
141                 <filename>local-fs.target</filename> or
142                 <filename>remote-fs.target</filename>, depending
143                 whether the file system is local or remote. If
144                 <option>x-systemd.automount</option> is set, an
145                 automount unit will be created for the file
146                 system. See
147                 <citerefentry><refentrytitle>systemd.automount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
148                 for details. If
149                 <option>x-systemd.device-timeout=</option> is
150                 specified it may be used to configure how long systemd
151                 should wait for a device to show up before giving up
152                 on an entry from
153                 <filename>/etc/fstab</filename>. Specify a time in
154                 seconds or explicitly specify a unit as
155                 <literal>s</literal>, <literal>min</literal>,
156                 <literal>h</literal>, <literal>ms</literal>.</para>
157
158                 <para>If a mount point is configured in both
159                 <filename>/etc/fstab</filename> and a unit file that
160                 is stored below <filename>/usr</filename> the former
161                 will take precedence. If the unit file is stored below
162                 <filename>/etc</filename> it will take
163                 precedence. This means: native unit files take
164                 precedence over traditional configuration files, but
165                 this is superseded by the rule that configuration in
166                 <filename>/etc</filename> will always take precedence
167                 over configuration in
168                 <filename>/usr</filename>.</para>
169         </refsect1>
170
171         <refsect1>
172                 <title>Options</title>
173
174                 <para>Mount files must include a [Mount] section,
175                 which carries information about the file system mount points it
176                 supervises. A number of options that may be used in
177                 this section are shared with other unit types. These
178                 options are documented in
179                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
180                 and
181                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
182                 options specific to the [Mount] section of mount
183                 units are the following:</para>
184
185                 <variablelist>
186
187                         <varlistentry>
188                                 <term><varname>What=</varname></term>
189                                 <listitem><para>Takes an absolute path
190                                 of a device node, file or other
191                                 resource to mount. See
192                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
193                                 for details. If this refers to a
194                                 device node, a dependency on the
195                                 respective device unit is
196                                 automatically created. (See
197                                 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information.)
198                                 This option is
199                                 mandatory.</para></listitem>
200                         </varlistentry>
201
202                         <varlistentry>
203                                 <term><varname>Where=</varname></term>
204                                 <listitem><para>Takes an absolute path
205                                 of a directory of the mount point. If
206                                 the mount point does not exist at the
207                                 time of mounting, it is created. This
208                                 string must be reflected in the unit
209                                 file name. (See above.) This option is
210                                 mandatory.</para></listitem>
211                         </varlistentry>
212
213                         <varlistentry>
214                                 <term><varname>Type=</varname></term>
215                                 <listitem><para>Takes a string for the
216                                 filesystem type. See
217                                 <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>
218                                 for details. This setting is
219                                 optional.</para></listitem>
220                         </varlistentry>
221
222                         <varlistentry>
223                                 <term><varname>Options=</varname></term>
224
225                                 <listitem><para>Mount options to use
226                                 when mounting. This takes a comma
227                                 separated list of options. This
228                                 setting is optional.</para></listitem>
229                         </varlistentry>
230
231                         <varlistentry>
232                                 <term><varname>DirectoryMode=</varname></term>
233                                 <listitem><para>Directories of mount
234                                 points (and any parent directories)
235                                 are automatically created if
236                                 needed. This option specifies the file
237                                 system access mode used when creating
238                                 these directories. Takes an access
239                                 mode in octal notation. Defaults to
240                                 0755.</para></listitem>
241                         </varlistentry>
242
243                         <varlistentry>
244                                 <term><varname>TimeoutSec=</varname></term>
245                                 <listitem><para>Configures the time to
246                                 wait for the mount command to
247                                 finish. If a command does not exit
248                                 within the configured time the mount
249                                 will be considered failed and be shut
250                                 down again. All commands still running
251                                 will be terminated forcibly via
252                                 SIGTERM, and after another delay of
253                                 this time with SIGKILL. (See
254                                 <option>KillMode=</option> in
255                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
256                                 Takes a unit-less value in seconds, or
257                                 a time span value such as "5min
258                                 20s". Pass 0 to disable the timeout
259                                 logic. Defaults to
260                                 90s.</para></listitem>
261                         </varlistentry>
262                 </variablelist>
263
264                 <para>Check
265                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
266                 and
267                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
268                 for more settings.</para>
269         </refsect1>
270
271         <refsect1>
272                 <title>Compatibility Options</title>
273
274                 <para>The following option is also available in the
275                 <literal>[Mount]</literal> section, but exists purely
276                 for compatibility reasons and should not be used in
277                 newly written mount files.</para>
278
279                 <variablelist>
280                         <varlistentry>
281                                 <term><varname>FsckPassNo=</varname></term>
282
283                                 <listitem><para>The pass number for
284                                 the file system checking service for
285                                 this mount. See
286                                 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
287                                 for more information on this setting.
288                                 </para></listitem>
289                         </varlistentry>
290                 </variablelist>
291         </refsect1>
292
293         <refsect1>
294                   <title>See Also</title>
295                   <para>
296                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
297                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
298                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
299                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
300                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
301                           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
302                           <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
303                           <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
304                           <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
305                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
306                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
307                   </para>
308         </refsect1>
309
310 </refentry>