Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-FSTAB\-GENERATOR" "8" "" "systemd 257.13" "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 "fstab", and
84 "tmpfs"\&.
85 .sp
86 Use
87 "gpt\-auto"
88 to explicitly request automatic root file system discovery via
89 \fBsystemd-gpt-auto-generator\fR(8)\&.
90 .sp
91 Use
92 "fstab"
93 to explicitly request automatic root file system discovery via the initrd
94 /etc/fstab
95 rather than via kernel command line\&.
96 .sp
97 Use
98 "tmpfs"
99 in order to mount a
100 \fBtmpfs\fR(5)
101 file system as root file system of the OS\&. This is useful in combination with
102 \fImount\&.usr=\fR
103 (see below) in order to combine a volatile root file system with a separate, immutable
104 /usr/
105 file system\&. Also see
106 \fIsystemd\&.volatile=\fR
107 below\&.
108 .sp
109 Added in version 217\&.
110 .RE
111 .PP
112 \fIrootfstype=\fR
113 .RS 4
114 Takes the root filesystem type that will be passed to the mount command\&.
115 \fIrootfstype=\fR
116 is honored by the initrd\&.
117 .sp
118 Added in version 217\&.
119 .RE
120 .PP
121 \fIrootflags=\fR
122 .RS 4
123 Takes the root filesystem mount options to use\&.
124 \fIrootflags=\fR
125 is honored by the initrd\&.
126 .sp
127 Note that unlike most kernel command line options this setting does not override settings made in configuration files (specifically: the mount option string in
128 /etc/fstab)\&. See
129 \fBsystemd-remount-fs.service\fR(8)\&.
130 .sp
131 Added in version 217\&.
132 .RE
133 .PP
134 \fImount\&.usr=\fR
135 .RS 4
136 Takes the
137 /usr/
138 filesystem to be mounted by the initrd\&. If
139 \fImount\&.usrfstype=\fR
140 or
141 \fImount\&.usrflags=\fR
142 is set, then
143 \fImount\&.usr=\fR
144 will default to the value set in
145 \fIroot=\fR\&.
146 .sp
147 Otherwise, this parameter defaults to the
148 /usr/
149 entry found in
150 /etc/fstab
151 on the root filesystem\&.
152 .sp
153 \fImount\&.usr=\fR
154 is honored by the initrd\&.
155 .sp
156 Added in version 217\&.
157 .RE
158 .PP
159 \fImount\&.usrfstype=\fR
160 .RS 4
161 Takes the
162 /usr/
163 filesystem type that will be passed to the mount command\&. If
164 \fImount\&.usr=\fR
165 or
166 \fImount\&.usrflags=\fR
167 is set, then
168 \fImount\&.usrfstype=\fR
169 will default to the value set in
170 \fIrootfstype=\fR\&.
171 .sp
172 Otherwise, this value will be read from the
173 /usr/
174 entry in
175 /etc/fstab
176 on the root filesystem\&.
177 .sp
178 \fImount\&.usrfstype=\fR
179 is honored by the initrd\&.
180 .sp
181 Added in version 217\&.
182 .RE
183 .PP
184 \fImount\&.usrflags=\fR
185 .RS 4
186 Takes the
187 /usr/
188 filesystem mount options to use\&. If
189 \fImount\&.usr=\fR
190 or
191 \fImount\&.usrfstype=\fR
192 is set, then
193 \fImount\&.usrflags=\fR
194 will default to the value set in
195 \fIrootflags=\fR\&.
196 .sp
197 Otherwise, this value will be read from the
198 /usr/
199 entry in
200 /etc/fstab
201 on the root filesystem\&.
202 .sp
203 \fImount\&.usrflags=\fR
204 is honored by the initrd\&.
205 .sp
206 Added in version 217\&.
207 .RE
208 .PP
209 \fIroothash=\fR, \fIusrhash=\fR
210 .RS 4
211 These options are primarily read by
212 \fBsystemd-veritysetup-generator\fR(8)\&. When set this indicates that the root file system (or
213 /usr/) shall be mounted from Verity volumes with the specified hashes\&. If these kernel command line options are set the root (or
214 /usr/) file system is thus mounted from a device mapper volume
215 /dev/mapper/root
216 (or
217 /dev/mapper/usr)\&.
218 .sp
219 Added in version 251\&.
220 .RE
221 .PP
222 \fIsystemd\&.volatile=\fR
223 .RS 4
224 Controls whether the system shall boot up in volatile mode\&. Takes a boolean argument or the special value
225 \fBstate\fR\&.
226 .sp
227 If false (the default), this generator makes no changes to the mount tree and the system is booted up in normal mode\&.
228 .sp
229 If true the generator ensures
230 \fBsystemd-volatile-root.service\fR(8)
231 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
232 /usr/
233 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
234 /etc/
235 and
236 /var/
237 will be served from the (initially unpopulated) volatile memory file system\&.
238 .sp
239 If set to
240 \fBstate\fR
241 the generator will leave the root directory mount point unaltered, however will mount a
242 "tmpfs"
243 file system to
244 /var/\&. In this mode the normal system configuration (i\&.e\&. the contents of
245 "/etc/") is in effect (and may be modified during system runtime), however the system state (i\&.e\&. the contents of
246 "/var/") is reset at boot and lost at shutdown\&.
247 .sp
248 If this setting is set to
249 "overlay"
250 the root file system is set up as
251 "overlayfs"
252 mount combining the read\-only root directory with a writable
253 "tmpfs", so that no modifications are made to disk, but the file system may be modified nonetheless with all changes being lost at reboot\&.
254 .sp
255 Note that in none of these modes the root directory,
256 /etc/,
257 /var/
258 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\&.
259 .sp
260 Note that with the exception of
261 "overlay"
262 mode, enabling this setting will only work correctly on operating systems that can boot up with only
263 /usr/
264 mounted, and are able to automatically populate
265 /etc/, and also
266 /var/
267 in case of
268 "systemd\&.volatile=yes"\&.
269 .sp
270 Also see
271 \fIroot=tmpfs\fR
272 above, for a method to combine a
273 "tmpfs"
274 file system with a regular
275 /usr/
276 file system (as configured via
277 \fImount\&.usr=\fR)\&. The main distinction between
278 \fIsystemd\&.volatile=yes\fR, and
279 \fIroot=tmpfs\fR
280 in combination
281 \fImount\&.usr=\fR
282 is that the former operates on top of a regular root file system and temporarily obstructs the files and directories above its
283 /usr/
284 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
285 /usr/
286 file system\&.
287 .sp
288 Added in version 233\&.
289 .RE
290 .PP
291 \fIsystemd\&.swap=\fR
292 .RS 4
293 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
294 /etc/fstab\&. Defaults to enabled\&.
295 .sp
296 Added in version 246\&.
297 .RE
298 .PP
299 \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
300 .RS 4
301 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\&.
302 \fIrd\&.systemd\&.mount\-extra=\fR
303 is honored only in the initrd, while
304 \fIsystemd\&.mount\-extra=\fR
305 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
306 \fIsystemd\&.mount\-extra=\fR
307 is prefixed with
308 /sysroot/\&.
309 .sp
310 Example:
311 .sp
312 .if n \{\
313 .RS 4
314 .\}
315 .nf
316 systemd\&.mount\-extra=/dev/sda1:/mount\-point:ext4:rw,noatime
317 .fi
318 .if n \{\
319 .RE
320 .\}
321 .sp
322 Added in version 254\&.
323 .RE
324 .PP
325 \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
326 .RS 4
327 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\&.
328 \fIrd\&.systemd\&.swap\-extra=\fR
329 is honored only in the initrd, while
330 \fIsystemd\&.swap\-extra=\fR
331 is honored by both the main system and the initrd\&.
332 .sp
333 Example:
334 .sp
335 .if n \{\
336 .RS 4
337 .\}
338 .nf
339 systemd\&.swap\-extra=/dev/sda2:x\-systemd\&.makefs
340 .fi
341 .if n \{\
342 .RE
343 .\}
344 .sp
345 Added in version 254\&.
346 .RE
347 .SH "SYSTEM CREDENTIALS"
348 .PP
349 \fIfstab\&.extra\fR
350 .RS 4
351 This credential may contain addition mounts to establish, in the same format as
352 \fBfstab\fR(5), with one mount per line\&. It is read in addition to
353 /etc/fstab\&.
354 .sp
355 Added in version 254\&.
356 .RE
357 .SH "SEE ALSO"
358 .PP
359 \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
360 .SH "NOTES"
361 .IP " 1." 4
362 Known Environment Variables
363 .RS 4
364 \%https://systemd.io/ENVIRONMENT/
365 .RE