Debian Codegraph @

upstream/debian-unstable/man8/systemd-fstab-generator.8

raw
1 '\" t
2 .TH "SYSTEMD\-FSTAB\-GENERATOR" "8" "" "systemd 261~rc3" "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\&. Since the resulting root file system is supposed to behave like a regular OS root, the bind mount is established with the
120 \fBdev\fR,
121 \fBsuid\fR
122 and
123 \fBexec\fR
124 options (i\&.e\&. the
125 \fBnodev\fR,
126 \fBnosuid\fR
127 and
128 \fBnoexec\fR
129 flags that would otherwise be inherited from the file system the source directory resides on, such as
130 /run/, are cleared), unless overridden via
131 \fIrootflags=\fR\&.
132 .sp
133 Set to
134 "off"
135 to turn off mounting of a root file system\&.
136 .sp
137 Note that further
138 \fIroot=\fR
139 values may be supported, implemented in additional packages\&.
140 .sp
141 Added in version 217\&.
142 .RE
143 .PP
144 \fIrootfstype=\fR
145 .RS 4
146 Takes the root filesystem type that will be passed to the mount command\&.
147 \fIrootfstype=\fR
148 is honored by the initrd\&.
149 .sp
150 Added in version 217\&.
151 .RE
152 .PP
153 \fIrootflags=\fR
154 .RS 4
155 Takes the root filesystem mount options to use\&.
156 \fIrootflags=\fR
157 is honored by the initrd\&.
158 .sp
159 Note that unlike most kernel command line options this setting does not override settings made in configuration files (specifically: the mount option string in
160 /etc/fstab)\&. See
161 \fBsystemd-remount-fs.service\fR(8)\&.
162 .sp
163 Added in version 217\&.
164 .RE
165 .PP
166 \fImount\&.usr=\fR
167 .RS 4
168 Takes the
169 /usr/
170 filesystem to be mounted by the initrd\&. If
171 \fImount\&.usrfstype=\fR
172 or
173 \fImount\&.usrflags=\fR
174 is set, then the mount configured via
175 \fImount\&.usr=\fR
176 will default to the the same value set in
177 \fIroot=\fR\&.
178 .sp
179 Set to
180 "dissect"
181 to explicitly request automatic
182 /usr/
183 file system discovery, implemented in
184 \fBsystemd-gpt-auto-generator\fR(8)\&.
185 .sp
186 Set to
187 "off"
188 to turn off mounting of a separate
189 /usr/
190 file system\&.
191 .sp
192 \fImount\&.usr=\fR
193 is honored by the initrd\&.
194 .sp
195 Added in version 217\&.
196 .RE
197 .PP
198 \fImount\&.usrfstype=\fR
199 .RS 4
200 Takes the
201 /usr/
202 filesystem type that will be passed to the mount command\&. If
203 \fImount\&.usr=\fR
204 or
205 \fImount\&.usrflags=\fR
206 is set, then
207 \fImount\&.usrfstype=\fR
208 will default to the value set in
209 \fIrootfstype=\fR\&.
210 .sp
211 Otherwise, this value will be read from the
212 /usr/
213 entry in
214 /etc/fstab
215 on the root filesystem\&.
216 .sp
217 \fImount\&.usrfstype=\fR
218 is honored by the initrd\&.
219 .sp
220 Added in version 217\&.
221 .RE
222 .PP
223 \fImount\&.usrflags=\fR
224 .RS 4
225 Takes the
226 /usr/
227 filesystem mount options to use\&. If
228 \fImount\&.usr=\fR
229 or
230 \fImount\&.usrfstype=\fR
231 is set, then
232 \fImount\&.usrflags=\fR
233 will default to the value set in
234 \fIrootflags=\fR\&.
235 .sp
236 Otherwise, this value will be read from the
237 /usr/
238 entry in
239 /etc/fstab
240 on the root filesystem\&.
241 .sp
242 \fImount\&.usrflags=\fR
243 is honored by the initrd\&.
244 .sp
245 Added in version 217\&.
246 .RE
247 .PP
248 \fIroothash=\fR, \fIusrhash=\fR
249 .RS 4
250 These options are primarily read by
251 \fBsystemd-veritysetup-generator\fR(8)\&. When set this indicates that the root file system (or
252 /usr/) shall be mounted from Verity volumes with the specified hashes\&. If these kernel command line options are set the root (or
253 /usr/) file system is thus mounted from a device mapper volume
254 /dev/mapper/root
255 (or
256 /dev/mapper/usr)\&.
257 .sp
258 Added in version 251\&.
259 .RE
260 .PP
261 \fIsystemd\&.volatile=\fR
262 .RS 4
263 Controls whether the system shall boot up in volatile mode\&. Takes a boolean argument or the special values
264 "state"
265 and
266 "overlay"\&.
267 .sp
268 If
269 "no"
270 (the default), this generator makes no changes to the mount tree and the system is booted up in normal mode\&.
271 .sp
272 If
273 "yes"
274 the generator ensures
275 \fBsystemd-volatile-root.service\fR(8)
276 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
277 /usr/
278 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
279 /etc/
280 and
281 /var/
282 will be served from the (initially unpopulated) volatile memory file system\&.
283 .sp
284 If set to
285 "state"
286 the generator will leave the root directory mount point unaltered, however will mount a
287 "tmpfs"
288 file system to
289 /var/\&. In this mode the normal system configuration (i\&.e\&. the contents of
290 "/etc/") is in effect (and may be modified during system runtime), however the system state (i\&.e\&. the contents of
291 "/var/") is reset at boot and lost at shutdown\&.
292 .sp
293 If this setting is set to
294 "overlay"
295 the root file system is set up as
296 "overlayfs"
297 mount combining the read\-only root directory with a writable
298 "tmpfs", so that no modifications are made to disk, but the file system may be modified nonetheless with all changes being lost at reboot\&.
299 .sp
300 Note that in none of these modes the root directory,
301 /etc/,
302 /var/
303 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\&.
304 .sp
305 Note that with the exception of
306 "overlay"
307 mode, enabling this setting will only work correctly on operating systems that can boot up with only
308 /usr/
309 mounted, and are able to automatically populate
310 /etc/, and also
311 /var/
312 in case of
313 "systemd\&.volatile=yes"\&.
314 .sp
315 Also see
316 \fIroot=tmpfs\fR
317 above, for a method to combine a
318 "tmpfs"
319 file system with a regular
320 /usr/
321 file system (as configured via
322 \fImount\&.usr=\fR)\&. The main distinction between
323 \fIsystemd\&.volatile=yes\fR, and
324 \fIroot=tmpfs\fR
325 in combination
326 \fImount\&.usr=\fR
327 is that the former operates on top of a regular root file system and temporarily obstructs the files and directories above its
328 /usr/
329 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
330 /usr/
331 file system\&.
332 .sp
333 Added in version 233\&.
334 .RE
335 .PP
336 \fIsystemd\&.swap=\fR
337 .RS 4
338 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
339 /etc/fstab\&. Defaults to enabled\&.
340 .sp
341 Added in version 246\&.
342 .RE
343 .PP
344 \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
345 .RS 4
346 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\&.
347 \fIrd\&.systemd\&.mount\-extra=\fR
348 is honored only in the initrd, while
349 \fIsystemd\&.mount\-extra=\fR
350 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
351 \fIsystemd\&.mount\-extra=\fR
352 is prefixed with
353 /sysroot/\&.
354 .sp
355 Example:
356 .sp
357 .if n \{\
358 .RS 4
359 .\}
360 .nf
361 systemd\&.mount\-extra=/dev/sda1:/mount\-point:ext4:rw,noatime
362 .fi
363 .if n \{\
364 .RE
365 .\}
366 .sp
367 Added in version 254\&.
368 .RE
369 .PP
370 \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
371 .RS 4
372 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\&.
373 \fIrd\&.systemd\&.swap\-extra=\fR
374 is honored only in the initrd, while
375 \fIsystemd\&.swap\-extra=\fR
376 is honored by both the main system and the initrd\&.
377 .sp
378 Example:
379 .sp
380 .if n \{\
381 .RS 4
382 .\}
383 .nf
384 systemd\&.swap\-extra=/dev/sda2:x\-systemd\&.makefs
385 .fi
386 .if n \{\
387 .RE
388 .\}
389 .sp
390 Added in version 254\&.
391 .RE
392 .SH "SYSTEM CREDENTIALS"
393 .PP
394 \fIfstab\&.extra\fR
395 .RS 4
396 This credential may contain addition mounts to establish, in the same format as
397 \fBfstab\fR(5), with one mount per line\&. It is read in addition to
398 /etc/fstab\&.
399 .sp
400 Added in version 254\&.
401 .RE
402 .SH "SEE ALSO"
403 .PP
404 \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
405 .SH "NOTES"
406 .IP " 1." 4
407 Known Environment Variables
408 .RS 4
409 \%https://systemd.io/ENVIRONMENT/
410 .RE