Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-FIRSTBOOT" "1" "" "systemd 261~rc3" "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 machine tags
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 kernel command line used when installing kernel images
133 .RE
134 .sp
135 .RS 4
136 .ie n \{\
137 \h'-04'\(bu\h'+03'\c
138 .\}
139 .el \{\
140 .sp -1
141 .IP \(bu 2.3
142 .\}
143 The root user\*(Aqs password and shell
144 .RE
145 .PP
146 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\&.
147 .PP
148 If a setting is already initialized, it will not be overwritten and the user will not be prompted for the setting\&.
149 .PP
150 Note that this tool operates directly on the file system and does not involve any running system services, unlike
151 \fBlocalectl\fR(1),
152 \fBtimedatectl\fR(1)
153 or
154 \fBhostnamectl\fR(1)\&. This allows
155 \fBsystemd\-firstboot\fR
156 to operate on mounted but not booted disk images and in early boot\&. It is not recommended to use
157 \fBsystemd\-firstboot\fR
158 on the running system after it has been set up\&.
159 .SH "OPTIONS"
160 .PP
161 The following options are understood:
162 .PP
163 \fB\-\-root=\fR\fB\fIroot\fR\fR
164 .RS 4
165 Takes a directory path as an argument\&. All paths will be prefixed with the given alternate
166 \fIroot\fR
167 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\&.
168 .sp
169 Added in version 216\&.
170 .RE
171 .PP
172 \fB\-\-image=\fR\fB\fIpath\fR\fR
173 .RS 4
174 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
175 \fB\-\-root=\fR
176 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
177 \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2\&. For further information on supported disk images, see
178 \fBsystemd-nspawn\fR(1)\*(Aqs switch of the same name\&.
179 .sp
180 Added in version 246\&.
181 .RE
182 .PP
183 \fB\-\-locale=\fR\fB\fILOCALE\fR\fR, \fB\-\-locale\-messages=\fR\fB\fILOCALE\fR\fR
184 .RS 4
185 Sets the system locale, more specifically the
186 \fILANG=\fR
187 and
188 \fILC_MESSAGES\fR
189 settings\&. The argument should be a valid locale identifier, such as
190 "de_DE\&.UTF\-8"\&. This controls the
191 \fBlocale.conf\fR(5)
192 configuration file\&.
193 .sp
194 Added in version 216\&.
195 .RE
196 .PP
197 \fB\-\-keymap=\fR\fB\fIKEYMAP\fR\fR
198 .RS 4
199 Sets the system keyboard layout\&. The argument should be a valid keyboard map, such as
200 "de\-latin1"\&. This controls the
201 "KEYMAP"
202 entry in the
203 \fBvconsole.conf\fR(5)
204 configuration file\&.
205 .sp
206 Added in version 236\&.
207 .RE
208 .PP
209 \fB\-\-timezone=\fR\fB\fITIMEZONE\fR\fR
210 .RS 4
211 Sets the system time zone\&. The argument should be a valid time zone identifier, such as
212 "Europe/Berlin"\&. This controls the
213 \fBlocaltime\fR(5)
214 symlink\&.
215 .sp
216 Added in version 216\&.
217 .RE
218 .PP
219 \fB\-\-hostname=\fR\fB\fIHOSTNAME\fR\fR
220 .RS 4
221 Sets the system hostname\&. The argument should be a hostname, compatible with DNS\&. This controls the
222 \fBhostname\fR(5)
223 configuration file\&.
224 .sp
225 Added in version 216\&.
226 .RE
227 .PP
228 \fB\-\-setup\-machine\-id\fR
229 .RS 4
230 Initialize the system\*(Aqs machine ID to a random ID\&. This controls the
231 \fBmachine-id\fR(5)
232 file\&.
233 .sp
234 This option only works in combination with
235 \fB\-\-root=\fR
236 or
237 \fB\-\-image=\fR\&. On a running system,
238 machine\-id
239 is written by the manager with help from
240 \fBsystemd-machine-id-commit.service\fR(8)\&.
241 .sp
242 Added in version 216\&.
243 .RE
244 .PP
245 \fB\-\-machine\-id=\fR\fB\fIID\fR\fR
246 .RS 4
247 Set the system\*(Aqs machine ID to the specified value\&. The same restrictions apply as to
248 \fB\-\-setup\-machine\-id\fR\&.
249 .sp
250 Added in version 216\&.
251 .RE
252 .PP
253 \fB\-\-machine\-tags=\fR\fB\fITAG\fR\fR\fB[:\fITAG\fR\&...]\fR
254 .RS 4
255 Set the machine tags to the specified colon\-separated list\&. Machine tags are short labels that may be used to classify and group machines for management purposes, for example to identify the role a machine plays in a deployment, the fleet or organizational unit it belongs to, or any other administrator\-defined attribute\&. Each individual tag must be 1\&...255 characters long and consist only of ASCII alphanumeric characters,
256 "\-"
257 and
258 "\&."\&. This controls the
259 \fITAGS=\fR
260 field of
261 \fBmachine-info\fR(5)\&. The tags may later be queried and changed with the
262 \fBtags\fR
263 command of
264 \fBhostnamectl\fR(1), and matched against with the
265 \fIConditionMachineTag=\fR/\fIAssertMachineTag=\fR
266 unit settings, see
267 \fBsystemd.unit\fR(5)\&.
268 .sp
269 Unlike most other settings, machine tags are not prompted for interactively\&.
270 .sp
271 Added in version 261\&.
272 .RE
273 .PP
274 \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
275 .RS 4
276 Sets the password of the system\*(Aqs root user\&. This creates/modifies the
277 \fBpasswd\fR(5)
278 and
279 \fBshadow\fR(5)
280 files\&. This setting exists in three forms:
281 \fB\-\-root\-password=\fR
282 accepts the password to set directly on the command line,
283 \fB\-\-root\-password\-file=\fR
284 reads it from a file and
285 \fB\-\-root\-password\-hashed=\fR
286 accepts an already hashed password on the command line\&. See
287 \fBshadow\fR(5)
288 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
289 \fBps\fR(1)\&.
290 .sp
291 Added in version 216\&.
292 .RE
293 .PP
294 \fB\-\-root\-shell=\fR\fB\fISHELL\fR\fR
295 .RS 4
296 Sets the shell of the system\*(Aqs root user\&. This creates/modifies the
297 \fBpasswd\fR(5)
298 file\&.
299 .sp
300 Added in version 246\&.
301 .RE
302 .PP
303 \fB\-\-kernel\-command\-line=\fR\fB\fICMDLINE\fR\fR
304 .RS 4
305 Sets the system\*(Aqs kernel command line\&. This controls the
306 /etc/kernel/cmdline
307 file which is used by
308 \fBkernel-install\fR(8)\&.
309 .sp
310 Added in version 246\&.
311 .RE
312 .PP
313 \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
314 .RS 4
315 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\&.
316 .sp
317 Added in version 216\&.
318 .RE
319 .PP
320 \fB\-\-prompt\fR
321 .RS 4
322 Query the user for locale, keymap, timezone, hostname, root\*(Aqs password, and root\*(Aqs shell\&. This is equivalent to specifying
323 \fB\-\-prompt\-locale\fR,
324 \fB\-\-prompt\-keymap\fR,
325 \fB\-\-prompt\-timezone\fR,
326 \fB\-\-prompt\-hostname\fR,
327 \fB\-\-prompt\-root\-password\fR,
328 \fB\-\-prompt\-root\-shell\fR
329 in combination\&.
330 .sp
331 Added in version 216\&.
332 .RE
333 .PP
334 \fB\-\-prompt\-keymap\-auto\fR
335 .RS 4
336 If invoked from a virtual terminal TTY equivalent to
337 \fB\-\-prompt\-keymap\fR, otherwise has no effect\&. Or in other words, only prompts interactively for a keymap if a local keyboard is used for interactivity that requires it\&.
338 .sp
339 Added in version 259\&.
340 .RE
341 .PP
342 \fB\-\-copy\-locale\fR, \fB\-\-copy\-keymap\fR, \fB\-\-copy\-timezone\fR, \fB\-\-copy\-root\-password\fR, \fB\-\-copy\-root\-shell\fR
343 .RS 4
344 Copy a specific basic setting from the host\&. This only works in combination with
345 \fB\-\-root=\fR
346 or
347 \fB\-\-image=\fR\&.
348 .sp
349 Added in version 216\&.
350 .RE
351 .PP
352 \fB\-\-copy\fR
353 .RS 4
354 Copy locale, keymap, time zone, root password and shell from the host\&. This is equivalent to specifying
355 \fB\-\-copy\-locale\fR,
356 \fB\-\-copy\-keymap\fR,
357 \fB\-\-copy\-timezone\fR,
358 \fB\-\-copy\-root\-password\fR,
359 \fB\-\-copy\-root\-shell\fR
360 in combination\&.
361 .sp
362 Added in version 216\&.
363 .RE
364 .PP
365 \fB\-\-force\fR
366 .RS 4
367 Write configuration even if the relevant files already exist\&. Without this option,
368 \fBsystemd\-firstboot\fR
369 does not modify or replace existing files\&. Note that when configuring the root account, even with this option,
370 \fBsystemd\-firstboot\fR
371 only modifies the entry of the
372 "root"
373 user, leaving other entries in
374 /etc/passwd
375 and
376 /etc/shadow
377 intact\&.
378 .sp
379 Added in version 246\&.
380 .RE
381 .PP
382 \fB\-\-reset\fR
383 .RS 4
384 If specified, all existing files that are configured by
385 \fBsystemd\-firstboot\fR
386 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
387 \fBsystemd\-firstboot\fR
388 will prompt again to configure each of the removed files\&.
389 .sp
390 Added in version 254\&.
391 .RE
392 .PP
393 \fB\-\-delete\-root\-password\fR
394 .RS 4
395 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\&.
396 .sp
397 Added in version 246\&.
398 .RE
399 .PP
400 \fB\-\-welcome=\fR
401 .RS 4
402 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\&.
403 .sp
404 Added in version 246\&.
405 .RE
406 .PP
407 \fB\-\-chrome=\fR
408 .RS 4
409 Takes a boolean argument\&. By default the initial setup screen will show reverse color "chrome" bars at the top and and the bottom of the terminal screen, which may be disabled by setting this option to false\&.
410 .sp
411 Added in version 259\&.
412 .RE
413 .PP
414 \fB\-\-mute\-console=\fR
415 .RS 4
416 Takes a boolean argument\&. If true kernel log output and service manager status output to the system console is temporarily disabled while
417 \fBsystemd\-firstboot\fR
418 is running, so that its own output is not interrupted\&. Defaults to false\&.
419 .sp
420 Added in version 259\&.
421 .RE
422 .PP
423 \fB\-h\fR, \fB\-\-help\fR
424 .RS 4
425 Print a short help text and exit\&.
426 .RE
427 .PP
428 \fB\-\-version\fR
429 .RS 4
430 Print a short version string and exit\&.
431 .RE
432 .SH "CREDENTIALS"
433 .PP
434 \fBsystemd\-firstboot\fR
435 supports the service credentials logic as implemented by
436 \fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
437 (see
438 \fBsystemd.exec\fR(5)
439 for details)\&. The following credentials are used when passed in:
440 .PP
441 \fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR
442 .RS 4
443 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
444 \fBsystemd-sysusers.service\fR(8)
445 service\&.
446 .sp
447 Added in version 249\&.
448 .RE
449 .PP
450 \fIpasswd\&.shell\&.root\fR
451 .RS 4
452 Specifies the shell binary to use for the specified account\&. Equivalent to the credential of the same name defined for the
453 \fBsystemd-sysusers.service\fR(8)
454 service\&.
455 .sp
456 Added in version 249\&.
457 .RE
458 .PP
459 \fIfirstboot\&.locale\fR, \fIfirstboot\&.locale\-messages\fR
460 .RS 4
461 These credentials specify the locale settings to set during first boot, in place of prompting the user\&.
462 .sp
463 Added in version 249\&.
464 .RE
465 .PP
466 \fIfirstboot\&.keymap\fR
467 .RS 4
468 This credential specifies the keyboard setting to set during first boot, in place of prompting the user\&.
469 .sp
470 Note the relationship to the
471 \fIvconsole\&.keymap\fR
472 credential understood by
473 \fBsystemd-vconsole-setup.service\fR(8): both ultimately affect the same setting, but
474 \fIfirstboot\&.keymap\fR
475 is written into
476 /etc/vconsole\&.conf
477 on first boot (if not already configured), and then read from there by
478 \fBsystemd\-vconsole\-setup\fR, while
479 \fIvconsole\&.keymap\fR
480 is read on every boot, and is not persisted to disk (but any configuration in
481 vconsole\&.conf
482 will take precedence if present)\&.
483 .sp
484 Added in version 249\&.
485 .RE
486 .PP
487 \fIfirstboot\&.timezone\fR
488 .RS 4
489 This credential specifies the system timezone setting to set during first boot, in place of prompting the user\&.
490 .sp
491 Added in version 249\&.
492 .RE
493 .PP
494 \fIfirstboot\&.hostname\fR
495 .RS 4
496 This credential specifies the static system hostname to set during first boot\&. The user will not be prompted for the hostname\&. Note that this controls the static hostname, not the transient hostname, and only has an effect on first boot, unlike
497 \fIsystem\&.hostname\fR\&.
498 .sp
499 Added in version 261\&.
500 .RE
501 .PP
502 \fIfirstboot\&.machine\-tags\fR
503 .RS 4
504 This credential specifies the machine tags to set during first boot, as a colon\-separated list, equivalent to the
505 \fB\-\-machine\-tags=\fR
506 switch described above\&. The tags are written into the
507 \fITAGS=\fR
508 field of
509 /etc/machine\-info
510 (if that file is not already present), and only have an effect on first boot\&. If the list contains invalid tags it is ignored in its entirety\&.
511 .sp
512 Added in version 261\&.
513 .RE
514 .PP
515 Note that by default the
516 systemd\-firstboot\&.service
517 unit file is set up to inherit the listed credentials from the service manager\&. Thus, when invoking a container with an unpopulated
518 /etc/
519 for the first time it is possible to configure the root user\*(Aqs password to be
520 "systemd"
521 like this:
522 .PP
523 .if n \{\
524 .RS 4
525 .\}
526 .nf
527 # systemd\-nspawn \-\-image=\&... \-\-set\-credential=firstboot\&.locale:de_DE\&.UTF\-8 \&...
528 .fi
529 .if n \{\
530 .RE
531 .\}
532 .PP
533 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\&.
534 .SH "EXIT STATUS"
535 .PP
536 On success, 0 is returned, a non\-zero failure code otherwise\&.
537 .SH "KERNEL COMMAND LINE"
538 .PP
539 \fIsystemd\&.firstboot=\fR
540 .RS 4
541 Takes a boolean argument, defaults to on\&. If off,
542 systemd\-firstboot\&.service
543 will not interactively query the user for basic settings at first boot, even if those settings are not initialized yet\&.
544 .sp
545 Added in version 233\&.
546 .RE
547 .SH "SEE ALSO"
548 .PP
549 \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)
550 .SH "NOTES"
551 .IP " 1." 4
552 UAPI.2 Discoverable Partitions Specification
553 .RS 4
554 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
555 .RE