Debian Codegraph @

upstream/debian-trixie/man1/systemd-firstboot.1

raw
1 '\" t
2 .TH "SYSTEMD\-FIRSTBOOT" "1" "" "systemd 257.13" "systemd-firstboot"
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-firstboot, systemd-firstboot.service \- Initialize basic system settings on or before the first boot\-up of a system
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-firstboot\fR\ 'u
26 \fBsystemd\-firstboot\fR [OPTIONS...]
27 .PP
28 systemd\-firstboot\&.service
29 .SH "DESCRIPTION"
30 .PP
31 The
32 \fBsystemd\-firstboot\&.service\fR
33 unit is one of the units which are used to initialize the machine configuration during "First Boot", i\&.e\&. when the system is freshly installed or after a factory reset\&. The
34 \fBsystemd\fR(1)
35 manager itself will initialize
36 \fBmachine-id\fR(5)
37 and preset all units, enabling or disabling them according to the
38 \fBsystemd.preset\fR(5)
39 settings\&.
40 systemd\-firstboot\&.service
41 is started later to interactively initialize basic system configuration\&. It is started only if
42 \fIConditionFirstBoot=yes\fR
43 is met, which essentially means that
44 /etc/
45 is unpopulated, see
46 \fBsystemd.unit\fR(5)
47 for details\&. System credentials may be used to inject configuration; those settings are not queried interactively\&.
48 .PP
49 The
50 \fBsystemd\-firstboot\fR
51 command can also be used to non\-interactively initialize an offline system image\&.
52 .PP
53 The following settings may be configured:
54 .sp
55 .RS 4
56 .ie n \{\
57 \h'-04'\(bu\h'+03'\c
58 .\}
59 .el \{\
60 .sp -1
61 .IP \(bu 2.3
62 .\}
63 The machine ID of the system
64 .RE
65 .sp
66 .RS 4
67 .ie n \{\
68 \h'-04'\(bu\h'+03'\c
69 .\}
70 .el \{\
71 .sp -1
72 .IP \(bu 2.3
73 .\}
74 The system locale, more specifically the two locale variables
75 \fILANG=\fR
76 and
77 \fILC_MESSAGES\fR
78 .RE
79 .sp
80 .RS 4
81 .ie n \{\
82 \h'-04'\(bu\h'+03'\c
83 .\}
84 .el \{\
85 .sp -1
86 .IP \(bu 2.3
87 .\}
88 The system keyboard map
89 .RE
90 .sp
91 .RS 4
92 .ie n \{\
93 \h'-04'\(bu\h'+03'\c
94 .\}
95 .el \{\
96 .sp -1
97 .IP \(bu 2.3
98 .\}
99 The system time zone
100 .RE
101 .sp
102 .RS 4
103 .ie n \{\
104 \h'-04'\(bu\h'+03'\c
105 .\}
106 .el \{\
107 .sp -1
108 .IP \(bu 2.3
109 .\}
110 The system hostname
111 .RE
112 .sp
113 .RS 4
114 .ie n \{\
115 \h'-04'\(bu\h'+03'\c
116 .\}
117 .el \{\
118 .sp -1
119 .IP \(bu 2.3
120 .\}
121 The kernel command line used when installing kernel images
122 .RE
123 .sp
124 .RS 4
125 .ie n \{\
126 \h'-04'\(bu\h'+03'\c
127 .\}
128 .el \{\
129 .sp -1
130 .IP \(bu 2.3
131 .\}
132 The root user\*(Aqs password and shell
133 .RE
134 .PP
135 Each of the fields may either be queried interactively by users, set non\-interactively on the tool\*(Aqs command line, or be copied from a host system that is used to set up the system image\&.
136 .PP
137 If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting\&.
138 .PP
139 Note that this tool operates directly on the file system and does not involve any running system services, unlike
140 \fBlocalectl\fR(1),
141 \fBtimedatectl\fR(1)
142 or
143 \fBhostnamectl\fR(1)\&. This allows
144 \fBsystemd\-firstboot\fR
145 to operate on mounted but not booted disk images and in early boot\&. It is not recommended to use
146 \fBsystemd\-firstboot\fR
147 on the running system after it has been set up\&.
148 .SH "OPTIONS"
149 .PP
150 The following options are understood:
151 .PP
152 \fB\-\-root=\fR\fB\fIroot\fR\fR
153 .RS 4
154 Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
155 \fIroot\fR
156 path, including config search paths\&. This is useful to operate on a system image mounted to the specified directory instead of the host system itself\&.
157 .sp
158 Added in version 216\&.
159 .RE
160 .PP
161 \fB\-\-image=\fR\fB\fIpath\fR\fR
162 .RS 4
163 Takes a path to a disk image file or block device node\&. If specified all operations are applied to file system in the indicated disk image\&. This is similar to
164 \fB\-\-root=\fR
165 but operates on file systems stored in disk images or block devices\&. The disk image should either contain just a file system or a set of file systems within a GPT partition table, following the
166 \m[blue]\fBDiscoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see
167 \fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
168 .sp
169 Added in version 246\&.
170 .RE
171 .PP
172 \fB\-\-locale=\fR\fB\fILOCALE\fR\fR, \fB\-\-locale\-messages=\fR\fB\fILOCALE\fR\fR
173 .RS 4
174 Sets the system locale, more specifically the
175 \fILANG=\fR
176 and
177 \fILC_MESSAGES\fR
178 settings\&. The argument should be a valid locale identifier, such as
179 "de_DE\&.UTF\-8"\&. This controls the
180 \fBlocale.conf\fR(5)
181 configuration file\&.
182 .sp
183 Added in version 216\&.
184 .RE
185 .PP
186 \fB\-\-keymap=\fR\fB\fIKEYMAP\fR\fR
187 .RS 4
188 Sets the system keyboard layout\&. The argument should be a valid keyboard map, such as
189 "de\-latin1"\&. This controls the
190 "KEYMAP"
191 entry in the
192 \fBvconsole.conf\fR(5)
193 configuration file\&.
194 .sp
195 Added in version 236\&.
196 .RE
197 .PP
198 \fB\-\-timezone=\fR\fB\fITIMEZONE\fR\fR
199 .RS 4
200 Sets the system time zone\&. The argument should be a valid time zone identifier, such as
201 "Europe/Berlin"\&. This controls the
202 \fBlocaltime\fR(5)
203 symlink\&.
204 .sp
205 Added in version 216\&.
206 .RE
207 .PP
208 \fB\-\-hostname=\fR\fB\fIHOSTNAME\fR\fR
209 .RS 4
210 Sets the system hostname\&. The argument should be a hostname, compatible with DNS\&. This controls the
211 \fBhostname\fR(5)
212 configuration file\&.
213 .sp
214 Added in version 216\&.
215 .RE
216 .PP
217 \fB\-\-setup\-machine\-id\fR
218 .RS 4
219 Initialize the system\*(Aqs machine ID to a random ID\&. This controls the
220 \fBmachine-id\fR(5)
221 file\&.
222 .sp
223 This option only works in combination with
224 \fB\-\-root=\fR
225 or
226 \fB\-\-image=\fR\&. On a running system,
227 machine\-id
228 is written by the manager with help from
229 \fBsystemd-machine-id-commit.service\fR(8)\&.
230 .sp
231 Added in version 216\&.
232 .RE
233 .PP
234 \fB\-\-machine\-id=\fR\fB\fIID\fR\fR
235 .RS 4
236 Set the system\*(Aqs machine ID to the specified value\&. The same restrictions apply as to
237 \fB\-\-setup\-machine\-id\fR\&.
238 .sp
239 Added in version 216\&.
240 .RE
241 .PP
242 \fB\-\-root\-password=\fR\fB\fIPASSWORD\fR\fR, \fB\-\-root\-password\-file=\fR\fB\fIPATH\fR\fR, \fB\-\-root\-password\-hashed=\fR\fB\fIHASHED_PASSWORD\fR\fR
243 .RS 4
244 Sets the password of the system\*(Aqs root user\&. This creates/modifies the
245 \fBpasswd\fR(5)
246 and
247 \fBshadow\fR(5)
248 files\&. This setting exists in three forms:
249 \fB\-\-root\-password=\fR
250 accepts the password to set directly on the command line,
251 \fB\-\-root\-password\-file=\fR
252 reads it from a file and
253 \fB\-\-root\-password\-hashed=\fR
254 accepts an already hashed password on the command line\&. See
255 \fBshadow\fR(5)
256 for more information on the format of the hashed password\&. Note that it is not recommended to specify plaintext passwords on the command line, as other users might be able to see them simply by invoking
257 \fBps\fR(1)\&.
258 .sp
259 Added in version 216\&.
260 .RE
261 .PP
262 \fB\-\-root\-shell=\fR\fB\fISHELL\fR\fR
263 .RS 4
264 Sets the shell of the system\*(Aqs root user\&. This creates/modifies the
265 \fBpasswd\fR(5)
266 file\&.
267 .sp
268 Added in version 246\&.
269 .RE
270 .PP
271 \fB\-\-kernel\-command\-line=\fR\fB\fICMDLINE\fR\fR
272 .RS 4
273 Sets the system\*(Aqs kernel command line\&. This controls the
274 /etc/kernel/cmdline
275 file which is used by
276 \fBkernel-install\fR(8)\&.
277 .sp
278 Added in version 246\&.
279 .RE
280 .PP
281 \fB\-\-prompt\-locale\fR, \fB\-\-prompt\-keymap\fR, \fB\-\-prompt\-timezone\fR, \fB\-\-prompt\-hostname\fR, \fB\-\-prompt\-root\-password\fR, \fB\-\-prompt\-root\-shell\fR
282 .RS 4
283 Prompt the user interactively for a specific basic setting\&. Note that any explicit configuration settings specified on the command line take precedence, and the user is not prompted for it\&.
284 .sp
285 Added in version 216\&.
286 .RE
287 .PP
288 \fB\-\-prompt\fR
289 .RS 4
290 Query the user for locale, keymap, timezone, hostname, root\*(Aqs password, and root\*(Aqs shell\&. This is equivalent to specifying
291 \fB\-\-prompt\-locale\fR,
292 \fB\-\-prompt\-keymap\fR,
293 \fB\-\-prompt\-timezone\fR,
294 \fB\-\-prompt\-hostname\fR,
295 \fB\-\-prompt\-root\-password\fR,
296 \fB\-\-prompt\-root\-shell\fR
297 in combination\&.
298 .sp
299 Added in version 216\&.
300 .RE
301 .PP
302 \fB\-\-copy\-locale\fR, \fB\-\-copy\-keymap\fR, \fB\-\-copy\-timezone\fR, \fB\-\-copy\-root\-password\fR, \fB\-\-copy\-root\-shell\fR
303 .RS 4
304 Copy a specific basic setting from the host\&. This only works in combination with
305 \fB\-\-root=\fR
306 or
307 \fB\-\-image=\fR\&.
308 .sp
309 Added in version 216\&.
310 .RE
311 .PP
312 \fB\-\-copy\fR
313 .RS 4
314 Copy locale, keymap, time zone, root password and shell from the host\&. This is equivalent to specifying
315 \fB\-\-copy\-locale\fR,
316 \fB\-\-copy\-keymap\fR,
317 \fB\-\-copy\-timezone\fR,
318 \fB\-\-copy\-root\-password\fR,
319 \fB\-\-copy\-root\-shell\fR
320 in combination\&.
321 .sp
322 Added in version 216\&.
323 .RE
324 .PP
325 \fB\-\-force\fR
326 .RS 4
327 Write configuration even if the relevant files already exist\&. Without this option,
328 \fBsystemd\-firstboot\fR
329 does not modify or replace existing files\&. Note that when configuring the root account, even with this option,
330 \fBsystemd\-firstboot\fR
331 only modifies the entry of the
332 "root"
333 user, leaving other entries in
334 /etc/passwd
335 and
336 /etc/shadow
337 intact\&.
338 .sp
339 Added in version 246\&.
340 .RE
341 .PP
342 \fB\-\-reset\fR
343 .RS 4
344 If specified, all existing files that are configured by
345 \fBsystemd\-firstboot\fR
346 are removed\&. Note that the files are removed regardless of whether they\*(Aqll be configured with a new value or not\&. This operation ensures that the next boot of the image will be considered a first boot, and
347 \fBsystemd\-firstboot\fR
348 will prompt again to configure each of the removed files\&.
349 .sp
350 Added in version 254\&.
351 .RE
352 .PP
353 \fB\-\-delete\-root\-password\fR
354 .RS 4
355 Removes the password of the system\*(Aqs root user, enabling login as root without a password unless the root account is locked\&. Note that this is extremely insecure and hence this option should not be used lightly\&.
356 .sp
357 Added in version 246\&.
358 .RE
359 .PP
360 \fB\-\-welcome=\fR
361 .RS 4
362 Takes a boolean argument\&. By default, when prompting the user for configuration options a brief welcome text is shown before the first question is asked\&. Pass false to this option to turn off the welcome text\&.
363 .sp
364 Added in version 246\&.
365 .RE
366 .PP
367 \fB\-h\fR, \fB\-\-help\fR
368 .RS 4
369 Print a short help text and exit\&.
370 .RE
371 .PP
372 \fB\-\-version\fR
373 .RS 4
374 Print a short version string and exit\&.
375 .RE
376 .SH "CREDENTIALS"
377 .PP
378 \fBsystemd\-firstboot\fR
379 supports the service credentials logic as implemented by
380 \fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
381 (see
382 \fBsystemd.exec\fR(5)
383 for details)\&. The following credentials are used when passed in:
384 .PP
385 \fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR
386 .RS 4
387 A hashed or plaintext version of the root password to use, in place of prompting the user\&. These credentials are equivalent to the same ones defined for the
388 \fBsystemd-sysusers.service\fR(8)
389 service\&.
390 .sp
391 Added in version 249\&.
392 .RE
393 .PP
394 \fIpasswd\&.shell\&.root\fR
395 .RS 4
396 Specifies the shell binary to use for the specified account\&. Equivalent to the credential of the same name defined for the
397 \fBsystemd-sysusers.service\fR(8)
398 service\&.
399 .sp
400 Added in version 249\&.
401 .RE
402 .PP
403 \fIfirstboot\&.locale\fR, \fIfirstboot\&.locale\-messages\fR
404 .RS 4
405 These credentials specify the locale settings to set during first boot, in place of prompting the user\&.
406 .sp
407 Added in version 249\&.
408 .RE
409 .PP
410 \fIfirstboot\&.keymap\fR
411 .RS 4
412 This credential specifies the keyboard setting to set during first boot, in place of prompting the user\&.
413 .sp
414 Note the relationship to the
415 \fIvconsole\&.keymap\fR
416 credential understood by
417 \fBsystemd-vconsole-setup.service\fR(8): both ultimately affect the same setting, but
418 \fIfirstboot\&.keymap\fR
419 is written into
420 /etc/vconsole\&.conf
421 on first boot (if not already configured), and then read from there by
422 \fBsystemd\-vconsole\-setup\fR, while
423 \fIvconsole\&.keymap\fR
424 is read on every boot, and is not persisted to disk (but any configuration in
425 vconsole\&.conf
426 will take precedence if present)\&.
427 .sp
428 Added in version 249\&.
429 .RE
430 .PP
431 \fIfirstboot\&.timezone\fR
432 .RS 4
433 This credential specifies the system timezone setting to set during first boot, in place of prompting the user\&.
434 .sp
435 Added in version 249\&.
436 .RE
437 .PP
438 Note that by default the
439 systemd\-firstboot\&.service
440 unit file is set up to inherit the listed credentials from the service manager\&. Thus, when invoking a container with an unpopulated
441 /etc/
442 for the first time it is possible to configure the root user\*(Aqs password to be
443 "systemd"
444 like this:
445 .PP
446 .if n \{\
447 .RS 4
448 .\}
449 .nf
450 # systemd\-nspawn \-\-image=\&... \-\-set\-credential=firstboot\&.locale:de_DE\&.UTF\-8 \&...
451 .fi
452 .if n \{\
453 .RE
454 .\}
455 .PP
456 Note that these credentials are only read and applied during the first boot\&. Once they are applied they remain applied for subsequent boots, and the credentials are not considered anymore\&.
457 .SH "EXIT STATUS"
458 .PP
459 On success, 0 is returned, a non\-zero failure code otherwise\&.
460 .SH "KERNEL COMMAND LINE"
461 .PP
462 \fIsystemd\&.firstboot=\fR
463 .RS 4
464 Takes a boolean argument, defaults to on\&. If off,
465 systemd\-firstboot\&.service
466 will not interactively query the user for basic settings at first boot, even if those settings are not initialized yet\&.
467 .sp
468 Added in version 233\&.
469 .RE
470 .SH "SEE ALSO"
471 .PP
472 \fBsystemd\fR(1), \fBlocale.conf\fR(5), \fBvconsole.conf\fR(5), \fBlocaltime\fR(5), \fBhostname\fR(5), \fBmachine-id\fR(5), \fBshadow\fR(5), \fBsystemd-machine-id-setup\fR(1), \fBlocalectl\fR(1), \fBtimedatectl\fR(1), \fBhostnamectl\fR(1)
473 .SH "NOTES"
474 .IP " 1." 4
475 Discoverable Partitions Specification
476 .RS 4
477 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
478 .RE