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