Debian Codegraph @

upstream/opensuse-tumbleweed/man1/systemd-firstboot.1

raw
1 '\" t
2 .TH "SYSTEMD\-FIRSTBOOT" "1" "" "systemd 260.1" "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]\fBUAPI\&.2 Discoverable 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\-\-prompt\-keymap\-auto\fR
303 .RS 4
304 If invoked from a virtual terminal TTY equivalent to
305 \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\&.
306 .sp
307 Added in version 259\&.
308 .RE
309 .PP
310 \fB\-\-copy\-locale\fR, \fB\-\-copy\-keymap\fR, \fB\-\-copy\-timezone\fR, \fB\-\-copy\-root\-password\fR, \fB\-\-copy\-root\-shell\fR
311 .RS 4
312 Copy a specific basic setting from the host\&. This only works in combination with
313 \fB\-\-root=\fR
314 or
315 \fB\-\-image=\fR\&.
316 .sp
317 Added in version 216\&.
318 .RE
319 .PP
320 \fB\-\-copy\fR
321 .RS 4
322 Copy locale, keymap, time zone, root password and shell from the host\&. This is equivalent to specifying
323 \fB\-\-copy\-locale\fR,
324 \fB\-\-copy\-keymap\fR,
325 \fB\-\-copy\-timezone\fR,
326 \fB\-\-copy\-root\-password\fR,
327 \fB\-\-copy\-root\-shell\fR
328 in combination\&.
329 .sp
330 Added in version 216\&.
331 .RE
332 .PP
333 \fB\-\-force\fR
334 .RS 4
335 Write configuration even if the relevant files already exist\&. Without this option,
336 \fBsystemd\-firstboot\fR
337 does not modify or replace existing files\&. Note that when configuring the root account, even with this option,
338 \fBsystemd\-firstboot\fR
339 only modifies the entry of the
340 "root"
341 user, leaving other entries in
342 /etc/passwd
343 and
344 /etc/shadow
345 intact\&.
346 .sp
347 Added in version 246\&.
348 .RE
349 .PP
350 \fB\-\-reset\fR
351 .RS 4
352 If specified, all existing files that are configured by
353 \fBsystemd\-firstboot\fR
354 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
355 \fBsystemd\-firstboot\fR
356 will prompt again to configure each of the removed files\&.
357 .sp
358 Added in version 254\&.
359 .RE
360 .PP
361 \fB\-\-delete\-root\-password\fR
362 .RS 4
363 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\&.
364 .sp
365 Added in version 246\&.
366 .RE
367 .PP
368 \fB\-\-welcome=\fR
369 .RS 4
370 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\&.
371 .sp
372 Added in version 246\&.
373 .RE
374 .PP
375 \fB\-\-chrome=\fR
376 .RS 4
377 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\&.
378 .sp
379 Added in version 259\&.
380 .RE
381 .PP
382 \fB\-\-mute\-console=\fR
383 .RS 4
384 Takes a boolean argument\&. If true kernel log output and service manager status output to the system console is temporarily disabled while
385 \fBsystemd\-firstboot\fR
386 is running, so that its own output is not interrupted\&. Defaults to false\&.
387 .sp
388 Added in version 259\&.
389 .RE
390 .PP
391 \fB\-h\fR, \fB\-\-help\fR
392 .RS 4
393 Print a short help text and exit\&.
394 .RE
395 .PP
396 \fB\-\-version\fR
397 .RS 4
398 Print a short version string and exit\&.
399 .RE
400 .SH "CREDENTIALS"
401 .PP
402 \fBsystemd\-firstboot\fR
403 supports the service credentials logic as implemented by
404 \fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
405 (see
406 \fBsystemd.exec\fR(5)
407 for details)\&. The following credentials are used when passed in:
408 .PP
409 \fIpasswd\&.hashed\-password\&.root\fR, \fIpasswd\&.plaintext\-password\&.root\fR
410 .RS 4
411 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
412 \fBsystemd-sysusers.service\fR(8)
413 service\&.
414 .sp
415 Added in version 249\&.
416 .RE
417 .PP
418 \fIpasswd\&.shell\&.root\fR
419 .RS 4
420 Specifies the shell binary to use for the specified account\&. Equivalent to the credential of the same name defined for the
421 \fBsystemd-sysusers.service\fR(8)
422 service\&.
423 .sp
424 Added in version 249\&.
425 .RE
426 .PP
427 \fIfirstboot\&.locale\fR, \fIfirstboot\&.locale\-messages\fR
428 .RS 4
429 These credentials specify the locale settings to set during first boot, in place of prompting the user\&.
430 .sp
431 Added in version 249\&.
432 .RE
433 .PP
434 \fIfirstboot\&.keymap\fR
435 .RS 4
436 This credential specifies the keyboard setting to set during first boot, in place of prompting the user\&.
437 .sp
438 Note the relationship to the
439 \fIvconsole\&.keymap\fR
440 credential understood by
441 \fBsystemd-vconsole-setup.service\fR(8): both ultimately affect the same setting, but
442 \fIfirstboot\&.keymap\fR
443 is written into
444 /etc/vconsole\&.conf
445 on first boot (if not already configured), and then read from there by
446 \fBsystemd\-vconsole\-setup\fR, while
447 \fIvconsole\&.keymap\fR
448 is read on every boot, and is not persisted to disk (but any configuration in
449 vconsole\&.conf
450 will take precedence if present)\&.
451 .sp
452 Added in version 249\&.
453 .RE
454 .PP
455 \fIfirstboot\&.timezone\fR
456 .RS 4
457 This credential specifies the system timezone setting to set during first boot, in place of prompting the user\&.
458 .sp
459 Added in version 249\&.
460 .RE
461 .PP
462 Note that by default the
463 systemd\-firstboot\&.service
464 unit file is set up to inherit the listed credentials from the service manager\&. Thus, when invoking a container with an unpopulated
465 /etc/
466 for the first time it is possible to configure the root user\*(Aqs password to be
467 "systemd"
468 like this:
469 .PP
470 .if n \{\
471 .RS 4
472 .\}
473 .nf
474 # systemd\-nspawn \-\-image=\&... \-\-set\-credential=firstboot\&.locale:de_DE\&.UTF\-8 \&...
475 .fi
476 .if n \{\
477 .RE
478 .\}
479 .PP
480 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\&.
481 .SH "EXIT STATUS"
482 .PP
483 On success, 0 is returned, a non\-zero failure code otherwise\&.
484 .SH "KERNEL COMMAND LINE"
485 .PP
486 \fIsystemd\&.firstboot=\fR
487 .RS 4
488 Takes a boolean argument, defaults to on\&. If off,
489 systemd\-firstboot\&.service
490 will not interactively query the user for basic settings at first boot, even if those settings are not initialized yet\&.
491 .sp
492 Added in version 233\&.
493 .RE
494 .SH "SEE ALSO"
495 .PP
496 \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)
497 .SH "NOTES"
498 .IP " 1." 4
499 UAPI.2 Discoverable Partitions Specification
500 .RS 4
501 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
502 .RE