Debian Codegraph @

upstream/fedora-44/man8/systemd-fstab-generator.8

raw
1 '\" t
2 .TH "SYSTEMD\-FSTAB\-GENERATOR" "8" "" "systemd 259.5" "systemd-fstab-generator"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-fstab-generator \- Unit generator for /etc/fstab
24 .SH "SYNOPSIS"
25 .PP
26 /usr/lib/systemd/system\-generators/systemd\-fstab\-generator
27 .SH "DESCRIPTION"
28 .PP
29 systemd\-fstab\-generator
30 is a generator that translates
31 /etc/fstab
32 (see
33 \fBfstab\fR(5)
34 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\&.
35 .PP
36 The
37 \fIpassno\fR
38 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\&.
39 .PP
40 See
41 \fBsystemd.mount\fR(5)
42 and
43 \fBsystemd.swap\fR(5)
44 for more information about special
45 /etc/fstab
46 mount options this generator understands\&.
47 .PP
48 One special topic is handling of symbolic links\&. Historical init implementations supported symlinks in
49 /etc/fstab\&. 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
50 /etc/fstab
51 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\&.
52 .PP
53 systemd\-fstab\-generator
54 implements
55 \fBsystemd.generator\fR(7)\&.
56 .SH "KERNEL COMMAND LINE"
57 .PP
58 systemd\-fstab\-generator
59 understands the following kernel command line parameters:
60 .PP
61 \fIfstab=\fR, \fIrd\&.fstab=\fR
62 .RS 4
63 Takes a boolean argument\&. Defaults to
64 "yes"\&. If
65 "no", causes the generator to ignore any mounts or swap devices configured in
66 /etc/fstab\&.
67 \fIrd\&.fstab=\fR
68 is honored only in the initrd, while
69 \fIfstab=\fR
70 is honored by both the main system and the initrd\&.
71 .sp
72 Added in version 186\&.
73 .RE
74 .PP
75 \fIroot=\fR
76 .RS 4
77 Configures the operating system\*(Aqs root filesystem to mount when running in the initrd\&. This accepts a device node path (usually
78 /dev/disk/by\-uuid/\&...
79 or
80 /dev/disk/by\-label/\&...
81 or similar), or the special values
82 "gpt\-auto",
83 "gpt\-auto\-force",
84 "dissect",
85 "dissect\-force",
86 "fstab",
87 "tmpfs",
88 "bind:\&...", and
89 "off"\&.
90 .sp
91 Set to
92 "gpt\-auto",
93 "gpt\-auto\-force",
94 "dissect",
95 "dissect\-force"
96 to explicitly request automatic root file system discovery, implemented in
97 \fBsystemd-gpt-auto-generator\fR(8)\&.
98 .sp
99 Use
100 "fstab"
101 to explicitly request automatic root file system discovery via the initrd
102 /etc/fstab
103 rather than via kernel command line\&.
104 .sp
105 Use
106 "tmpfs"
107 in order to mount a
108 \fBtmpfs\fR(5)
109 file system as root file system of the OS\&. This is useful in combination with
110 \fImount\&.usr=\fR
111 (see below) in order to combine a volatile root file system with a separate, immutable
112 /usr/
113 file system\&. Also see
114 \fIsystemd\&.volatile=\fR
115 below\&.
116 .sp
117 Use
118 "bind:\&..."
119 to bind mount another directory as operating system root filesystems (added in v258)\&. Expects an absolute path name referencing an existing directory within the initrd\*(Aqs file hierarchy to boot into\&.
120 .sp
121 Set to
122 "off"
123 to turn off mounting of a root file system\&.
124 .sp
125 Note that further
126 \fIroot=\fR
127 values may be supported, implemented in additional packages\&.
128 .sp
129 Added in version 217\&.
130 .RE
131 .PP
132 \fIrootfstype=\fR
133 .RS 4
134 Takes the root filesystem type that will be passed to the mount command\&.
135 \fIrootfstype=\fR
136 is honored by the initrd\&.
137 .sp
138 Added in version 217\&.
139 .RE
140 .PP
141 \fIrootflags=\fR
142 .RS 4
143 Takes the root filesystem mount options to use\&.
144 \fIrootflags=\fR
145 is honored by the initrd\&.
146 .sp
147 Note that unlike most kernel command line options this setting does not override settings made in configuration files (specifically: the mount option string in
148 /etc/fstab)\&. See
149 \fBsystemd-remount-fs.service\fR(8)\&.
150 .sp
151 Added in version 217\&.
152 .RE
153 .PP
154 \fImount\&.usr=\fR
155 .RS 4
156 Takes the
157 /usr/
158 filesystem to be mounted by the initrd\&. If
159 \fImount\&.usrfstype=\fR
160 or
161 \fImount\&.usrflags=\fR
162 is set, then the mount configured via
163 \fImount\&.usr=\fR
164 will default to the the same value set in
165 \fIroot=\fR\&.
166 .sp
167 Set to
168 "dissect"
169 to explicitly request automatic
170 /usr/
171 file system discovery, implemented in
172 \fBsystemd-gpt-auto-generator\fR(8)\&.
173 .sp
174 Set to
175 "off"
176 to turn off mounting of a separate
177 /usr/
178 file system\&.
179 .sp
180 \fImount\&.usr=\fR
181 is honored by the initrd\&.
182 .sp
183 Added in version 217\&.
184 .RE
185 .PP
186 \fImount\&.usrfstype=\fR
187 .RS 4
188 Takes the
189 /usr/
190 filesystem type that will be passed to the mount command\&. If
191 \fImount\&.usr=\fR
192 or
193 \fImount\&.usrflags=\fR
194 is set, then
195 \fImount\&.usrfstype=\fR
196 will default to the value set in
197 \fIrootfstype=\fR\&.
198 .sp
199 Otherwise, this value will be read from the
200 /usr/
201 entry in
202 /etc/fstab
203 on the root filesystem\&.
204 .sp
205 \fImount\&.usrfstype=\fR
206 is honored by the initrd\&.
207 .sp
208 Added in version 217\&.
209 .RE
210 .PP
211 \fImount\&.usrflags=\fR
212 .RS 4
213 Takes the
214 /usr/
215 filesystem mount options to use\&. If
216 \fImount\&.usr=\fR
217 or
218 \fImount\&.usrfstype=\fR
219 is set, then
220 \fImount\&.usrflags=\fR
221 will default to the value set in
222 \fIrootflags=\fR\&.
223 .sp
224 Otherwise, this value will be read from the
225 /usr/
226 entry in
227 /etc/fstab
228 on the root filesystem\&.
229 .sp
230 \fImount\&.usrflags=\fR
231 is honored by the initrd\&.
232 .sp
233 Added in version 217\&.
234 .RE
235 .PP
236 \fIroothash=\fR, \fIusrhash=\fR
237 .RS 4
238 These options are primarily read by
239 \fBsystemd-veritysetup-generator\fR(8)\&. When set this indicates that the root file system (or
240 /usr/) shall be mounted from Verity volumes with the specified hashes\&. If these kernel command line options are set the root (or
241 /usr/) file system is thus mounted from a device mapper volume
242 /dev/mapper/root
243 (or
244 /dev/mapper/usr)\&.
245 .sp
246 Added in version 251\&.
247 .RE
248 .PP
249 \fIsystemd\&.volatile=\fR
250 .RS 4
251 Controls whether the system shall boot up in volatile mode\&. Takes a boolean argument or the special value
252 \fBstate\fR\&.
253 .sp
254 If false (the default), this generator makes no changes to the mount tree and the system is booted up in normal mode\&.
255 .sp
256 If true the generator ensures
257 \fBsystemd-volatile-root.service\fR(8)
258 is run in the initrd\&. This service changes the mount table before transitioning to the host system, so that a volatile memory file system ("tmpfs") is used as root directory, with only
259 /usr/
260 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
261 /etc/
262 and
263 /var/
264 will be served from the (initially unpopulated) volatile memory file system\&.
265 .sp
266 If set to
267 \fBstate\fR
268 the generator will leave the root directory mount point unaltered, however will mount a
269 "tmpfs"
270 file system to
271 /var/\&. In this mode the normal system configuration (i\&.e\&. the contents of
272 "/etc/") is in effect (and may be modified during system runtime), however the system state (i\&.e\&. the contents of
273 "/var/") is reset at boot and lost at shutdown\&.
274 .sp
275 If this setting is set to
276 "overlay"
277 the root file system is set up as
278 "overlayfs"
279 mount combining the read\-only root directory with a writable
280 "tmpfs", so that no modifications are made to disk, but the file system may be modified nonetheless with all changes being lost at reboot\&.
281 .sp
282 Note that in none of these modes the root directory,
283 /etc/,
284 /var/
285 or any other resources stored in the root file system are physically removed\&. It\*(Aqs thus safe to boot a system that is normally operated in non\-volatile mode temporarily into volatile mode, without losing data\&.
286 .sp
287 Note that with the exception of
288 "overlay"
289 mode, enabling this setting will only work correctly on operating systems that can boot up with only
290 /usr/
291 mounted, and are able to automatically populate
292 /etc/, and also
293 /var/
294 in case of
295 "systemd\&.volatile=yes"\&.
296 .sp
297 Also see
298 \fIroot=tmpfs\fR
299 above, for a method to combine a
300 "tmpfs"
301 file system with a regular
302 /usr/
303 file system (as configured via
304 \fImount\&.usr=\fR)\&. The main distinction between
305 \fIsystemd\&.volatile=yes\fR, and
306 \fIroot=tmpfs\fR
307 in combination
308 \fImount\&.usr=\fR
309 is that the former operates on top of a regular root file system and temporarily obstructs the files and directories above its
310 /usr/
311 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
312 /usr/
313 file system\&.
314 .sp
315 Added in version 233\&.
316 .RE
317 .PP
318 \fIsystemd\&.swap=\fR
319 .RS 4
320 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
321 /etc/fstab\&. Defaults to enabled\&.
322 .sp
323 Added in version 246\&.
324 .RE
325 .PP
326 \fIsystemd\&.mount\-extra=\fR\fI\fIWHAT\fR\fR\fI:\fR\fI\fIWHERE\fR\fR\fI[:\fR\fI\fIFSTYPE\fR\fR\fI[:\fR\fI\fIOPTIONS\fR\fR\fI]]\fR, \fIrd\&.systemd\&.mount\-extra=\fR\fI\fIWHAT\fR\fR\fI:\fR\fI\fIWHERE\fR\fR\fI[:\fR\fI\fIFSTYPE\fR\fR\fI[:\fR\fI\fIOPTIONS\fR\fR\fI]]\fR
327 .RS 4
328 Specifies the mount unit\&. Takes at least two and at most four fields separated with a colon (":")\&. Each field is handled as the corresponding fstab field\&. This option can be specified multiple times\&.
329 \fIrd\&.systemd\&.mount\-extra=\fR
330 is honored only in the initrd, while
331 \fIsystemd\&.mount\-extra=\fR
332 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
333 \fIsystemd\&.mount\-extra=\fR
334 is prefixed with
335 /sysroot/\&.
336 .sp
337 Example:
338 .sp
339 .if n \{\
340 .RS 4
341 .\}
342 .nf
343 systemd\&.mount\-extra=/dev/sda1:/mount\-point:ext4:rw,noatime
344 .fi
345 .if n \{\
346 .RE
347 .\}
348 .sp
349 Added in version 254\&.
350 .RE
351 .PP
352 \fIsystemd\&.swap\-extra=\fR\fI\fIWHAT\fR\fR\fI[:\fR\fI\fIOPTIONS\fR\fR\fI]\fR, \fIrd\&.systemd\&.swap\-extra=\fR\fI\fIWHAT\fR\fR\fI[:\fR\fI\fIOPTIONS\fR\fR\fI]\fR
353 .RS 4
354 Specifies the swap unit\&. Takes the block device to be used as a swap device, and optionally takes mount options followed by a colon (":")\&. This option can be specified multiple times\&.
355 \fIrd\&.systemd\&.swap\-extra=\fR
356 is honored only in the initrd, while
357 \fIsystemd\&.swap\-extra=\fR
358 is honored by both the main system and the initrd\&.
359 .sp
360 Example:
361 .sp
362 .if n \{\
363 .RS 4
364 .\}
365 .nf
366 systemd\&.swap\-extra=/dev/sda2:x\-systemd\&.makefs
367 .fi
368 .if n \{\
369 .RE
370 .\}
371 .sp
372 Added in version 254\&.
373 .RE
374 .SH "SYSTEM CREDENTIALS"
375 .PP
376 \fIfstab\&.extra\fR
377 .RS 4
378 This credential may contain addition mounts to establish, in the same format as
379 \fBfstab\fR(5), with one mount per line\&. It is read in addition to
380 /etc/fstab\&.
381 .sp
382 Added in version 254\&.
383 .RE
384 .SH "SEE ALSO"
385 .PP
386 \fBsystemd\fR(1), \fBfstab\fR(5), \fBsystemd.mount\fR(5), \fBsystemd.swap\fR(5), \fBsystemd-cryptsetup-generator\fR(8), \fBsystemd-gpt-auto-generator\fR(8), \fBkernel-command-line\fR(7), \m[blue]\fBKnown Environment Variables\fR\m[]\&\s-2\u[1]\d\s+2
387 .SH "NOTES"
388 .IP " 1." 4
389 Known Environment Variables
390 .RS 4
391 \%https://systemd.io/ENVIRONMENT/
392 .RE