1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
|
<?xml version="1.0"?>
<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-fstab-generator" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-fstab-generator</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-fstab-generator</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-fstab-generator</refname>
<refpurpose>Unit generator for /etc/fstab</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename>/usr/lib/systemd/system-generators/systemd-fstab-generator</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><filename>systemd-fstab-generator</filename> is a generator
that translates <filename>/etc/fstab</filename> (see
<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details) into native systemd units early at boot and when
configuration of the system manager is reloaded. This will
instantiate mount and swap units as necessary.</para>
<para>The <varname>passno</varname> field is treated like a simple
boolean, and the ordering information is discarded. However, if
the root file system is checked, it is checked before all the
other file systems.</para>
<para>See
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for more information about special <filename>/etc/fstab</filename>
mount options this generator understands.</para>
<para>One special topic is handling of symbolic links. Historical init
implementations supported symlinks in <filename>/etc/fstab</filename>.
Because mount units will refuse mounts where the target is a symbolic link,
this generator will resolve any symlinks as far as possible when processing
<filename>/etc/fstab</filename> in order to enhance backwards compatibility.
If a symlink target does not exist at the time that this generator runs, it
is assumed that the symlink target is the final target of the mount.</para>
<para><filename>systemd-fstab-generator</filename> implements
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
</refsect1>
<refsect1>
<title>Kernel Command Line</title>
<para><filename>systemd-fstab-generator</filename> understands the
following kernel command line parameters:</para>
<variablelist class='kernel-commandline-options'>
<varlistentry>
<term><varname>fstab=</varname></term>
<term><varname>rd.fstab=</varname></term>
<listitem><para>Takes a boolean argument. Defaults to <literal>yes</literal>. If
<literal>no</literal>, causes the generator to ignore any mounts or swap devices configured in
<filename>/etc/fstab</filename>. <varname>rd.fstab=</varname> is honored only in the initrd, while
<varname>fstab=</varname> is honored by both the main system and the initrd.</para>
<xi:include href="version-info.xml" xpointer="v186"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>root=</varname></term>
<listitem><para>Configures the operating system's root filesystem to mount when running in the
initrd. This accepts a device node path (usually <filename>/dev/disk/by-uuid/…</filename> or
<filename>/dev/disk/by-label/…</filename> or similar), or the special values <literal>gpt-auto</literal>,
<literal>fstab</literal>, and <literal>tmpfs</literal>.</para>
<para>Use <literal>gpt-auto</literal> to explicitly request automatic root file system discovery via
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<para>Use <literal>fstab</literal> to explicitly request automatic root file system discovery via
the initrd <filename>/etc/fstab</filename> rather than via kernel command line.</para>
<para>Use <literal>tmpfs</literal> in order to mount a <citerefentry
project='man-pages'><refentrytitle>tmpfs</refentrytitle><manvolnum>5</manvolnum></citerefentry> file
system as root file system of the OS. This is useful in combination with
<varname>mount.usr=</varname> (see below) in order to combine a volatile root file system with a
separate, immutable <filename>/usr/</filename> file system. Also see
<varname>systemd.volatile=</varname> below.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>rootfstype=</varname></term>
<listitem><para>Takes the root filesystem type that will be
passed to the mount command. <varname>rootfstype=</varname> is
honored by the initrd.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>rootflags=</varname></term>
<listitem><para>Takes the root filesystem mount options to use. <varname>rootflags=</varname> is
honored by the initrd.</para>
<para>Note that unlike most kernel command line options this setting does not override settings made
in configuration files (specifically: the mount option string in
<filename>/etc/fstab</filename>). See
<citerefentry><refentrytitle>systemd-remount-fs.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>mount.usr=</varname></term>
<listitem><para>Takes the <filename>/usr/</filename> filesystem
to be mounted by the initrd. If
<varname>mount.usrfstype=</varname> or
<varname>mount.usrflags=</varname> is set, then
<varname>mount.usr=</varname> will default to the value set in
<varname>root=</varname>.</para>
<para>Otherwise, this parameter defaults to the
<filename>/usr/</filename> entry found in
<filename>/etc/fstab</filename> on the root filesystem.</para>
<para><varname>mount.usr=</varname> is honored by the initrd.
</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>mount.usrfstype=</varname></term>
<listitem><para>Takes the <filename>/usr/</filename> filesystem
type that will be passed to the mount command. If
<varname>mount.usr=</varname> or
<varname>mount.usrflags=</varname> is set, then
<varname>mount.usrfstype=</varname> will default to the value
set in <varname>rootfstype=</varname>.</para>
<para>Otherwise, this value will be read from the
<filename>/usr/</filename> entry in
<filename>/etc/fstab</filename> on the root filesystem.</para>
<para><varname>mount.usrfstype=</varname> is honored by the
initrd.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>mount.usrflags=</varname></term>
<listitem><para>Takes the <filename>/usr/</filename> filesystem
mount options to use. If <varname>mount.usr=</varname> or
<varname>mount.usrfstype=</varname> is set, then
<varname>mount.usrflags=</varname> will default to the value
set in <varname>rootflags=</varname>.</para>
<para>Otherwise, this value will be read from the
<filename>/usr/</filename> entry in
<filename>/etc/fstab</filename> on the root filesystem.</para>
<para><varname>mount.usrflags=</varname> is honored by the
initrd.</para>
<xi:include href="version-info.xml" xpointer="v217"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>roothash=</varname></term>
<term><varname>usrhash=</varname></term>
<listitem><para>These options are primarily read by
<citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. When
set this indicates that the root file system (or <filename>/usr/</filename>) shall be mounted from
Verity volumes with the specified hashes. If these kernel command line options are set the root (or
<filename>/usr/</filename>) file system is thus mounted from a device mapper volume
<filename>/dev/mapper/root</filename> (or <filename>/dev/mapper/usr</filename>).</para>
<xi:include href="version-info.xml" xpointer="v251"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.volatile=</varname></term>
<listitem><para>Controls whether the system shall boot up in volatile mode. Takes a boolean argument or the
special value <option>state</option>.</para>
<para>If false (the default), this generator makes no changes to the mount tree and the system is booted up in
normal mode.</para>
<para>If true the generator ensures
<citerefentry><refentrytitle>systemd-volatile-root.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is run in the initrd. This service changes the mount table before transitioning to the host system,
so that a volatile memory file system (<literal>tmpfs</literal>) is used as root directory, with only
<filename>/usr/</filename> mounted into it from the configured root file system, in read-only mode.
This way the system operates in fully stateless mode, with all configuration and state reset at boot
and lost at shutdown, as <filename>/etc/</filename> and <filename>/var/</filename> will be served
from the (initially unpopulated) volatile memory file system.</para>
<para>If set to <option>state</option> the generator will leave the root directory mount point unaltered,
however will mount a <literal>tmpfs</literal> file system to <filename>/var/</filename>. In this mode the normal
system configuration (i.e. the contents of <literal>/etc/</literal>) is in effect (and may be modified during
system runtime), however the system state (i.e. the contents of <literal>/var/</literal>) is reset at boot and
lost at shutdown.</para>
<para>If this setting is set to <literal>overlay</literal> the root file system is set up as
<literal>overlayfs</literal> mount combining the read-only root directory with a writable
<literal>tmpfs</literal>, so that no modifications are made to disk, but the file system may be modified
nonetheless with all changes being lost at reboot.</para>
<para>Note that in none of these modes the root directory, <filename>/etc/</filename>, <filename>/var/</filename>
or any other resources stored in the root file system are physically removed. It's thus safe to boot a system
that is normally operated in non-volatile mode temporarily into volatile mode, without losing data.</para>
<para>Note that with the exception of <literal>overlay</literal> mode, enabling this setting will
only work correctly on operating systems that can boot up with only <filename>/usr/</filename>
mounted, and are able to automatically populate <filename>/etc/</filename>, and also
<filename>/var/</filename> in case of <literal>systemd.volatile=yes</literal>.</para>
<para>Also see <varname>root=tmpfs</varname> above, for a method to combine a
<literal>tmpfs</literal> file system with a regular <filename>/usr/</filename> file system (as
configured via <varname>mount.usr=</varname>). The main distinction between
<varname>systemd.volatile=yes</varname>, and <varname>root=tmpfs</varname> in combination
<varname>mount.usr=</varname> is that the former operates on top of a regular root file system and
temporarily obstructs the files and directories above its <filename>/usr/</filename> subdirectory,
while the latter does not hide any files, but simply mounts a unpopulated tmpfs as root file system
and combines it with a user picked <filename>/usr/</filename> file system.</para>
<xi:include href="version-info.xml" xpointer="v233"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.swap=</varname></term>
<listitem><para>Takes a boolean argument or enables the option if specified
without an argument. If disabled, causes the generator to ignore
any swap devices configured in <filename>/etc/fstab</filename>.
Defaults to enabled.</para>
<xi:include href="version-info.xml" xpointer="v246"/></listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.mount-extra=<replaceable>WHAT</replaceable>:<replaceable>WHERE</replaceable>[:<replaceable>FSTYPE</replaceable>[:<replaceable>OPTIONS</replaceable>]]</varname></term>
<term><varname>rd.systemd.mount-extra=<replaceable>WHAT</replaceable>:<replaceable>WHERE</replaceable>[:<replaceable>FSTYPE</replaceable>[:<replaceable>OPTIONS</replaceable>]]</varname></term>
<listitem>
<para>Specifies the mount unit. Takes at least two and at most four fields separated with a colon
(<literal>:</literal>). Each field is handled as the corresponding fstab field. This option can be
specified multiple times. <varname>rd.systemd.mount-extra=</varname> is honored only in the initrd,
while <varname>systemd.mount-extra=</varname> is honored by both the main system and the initrd.
In the initrd, the mount point (and also source path if the mount is bind mount) specified in
<varname>systemd.mount-extra=</varname> is prefixed with <filename>/sysroot/</filename>.</para>
<para>Example:
<programlisting>
systemd.mount-extra=/dev/sda1:/mount-point:ext4:rw,noatime</programlisting>
</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>systemd.swap-extra=<replaceable>WHAT</replaceable>[:<replaceable>OPTIONS</replaceable>]</varname></term>
<term><varname>rd.systemd.swap-extra=<replaceable>WHAT</replaceable>[:<replaceable>OPTIONS</replaceable>]</varname></term>
<listitem>
<para>Specifies the swap unit. Takes the block device to be used as a swap device, and optionally
takes mount options followed by a colon (<literal>:</literal>). This option can be specified
multiple times. <varname>rd.systemd.swap-extra=</varname> is honored only in the initrd, while
<varname>systemd.swap-extra=</varname> is honored by both the main system and the initrd.</para>
<para>Example:
<programlisting>
systemd.swap-extra=/dev/sda2:x-systemd.makefs</programlisting>
</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>System Credentials</title>
<variablelist class='system-credentials'>
<varlistentry>
<term><varname>fstab.extra</varname></term>
<listitem><para>This credential may contain addition mounts to establish, in the same format as
<citerefentry
project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, with
one mount per line. It is read in addition to <filename>/etc/fstab</filename>.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.swap</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-cryptsetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>kernel-command-line</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
<ulink url="https://systemd.io/ENVIRONMENT/">Known Environment Variables</ulink>
</para>
</refsect1>
</refentry>
|
