1SYSTEMD-FIRSTBOOT(1) systemd-firstboot SYSTEMD-FIRSTBOOT(1)
2
6 systemd-firstboot, systemd-firstboot.service - Initialize basic system
7 settings on or before the first boot-up of a system
8
10 systemd-firstboot [OPTIONS...]
11 systemd-firstboot.service
13
15 systemd-firstboot initializes basic system settings interactively
16 during the first boot, or non-interactively on an offline system image.
17 The service is started during boot if ConditionFirstBoot=yes is met,
18 which essentially means that /etc/ is empty, see systemd.unit(5) for
19 details.
20 The following settings may be configured:
22 • The machine ID of the system
24 • The system locale, more specifically the two locale variables LANG=
26 and LC_MESSAGES
27 • The system keyboard map
29 • The system time zone
31 • The system hostname
33 • The kernel command line used when installing kernel images
35 • The root user's password and shell
37 Each of the fields may either be queried interactively by users, set
39 non-interactively on the tool's command line, or be copied from a host
40 system that is used to set up the system image.
41 If a setting is already initialized, it will not be overwritten and the
43 user will not be prompted for the setting.
44 Note that this tool operates directly on the file system and does not
46 involve any running system services, unlike localectl(1),
47 timedatectl(1) or hostnamectl(1). This allows systemd-firstboot to
48 operate on mounted but not booted disk images and in early boot. It is
49 not recommended to use systemd-firstboot on the running system after it
50 has been set up.
51
53 The following options are understood:
54 --root=root
56 Takes a directory path as an argument. All paths will be prefixed
57 with the given alternate root path, including config search paths.
58 This is useful to operate on a system image mounted to the
59 specified directory instead of the host system itself.
60 --image=path
62 Takes a path to a disk image file or block device node. If
63 specified all operations are applied to file system in the
64 indicated disk image. This is similar to --root= but operates on
65 file systems stored in disk images or block devices. The disk image
66 should either contain just a file system or a set of file systems
67 within a GPT partition table, following the Discoverable Partitions
68 Specification[1]. For further information on supported disk images,
69 see systemd-nspawn(1)'s switch of the same name.
70 --locale=LOCALE, --locale-messages=LOCALE
72 Sets the system locale, more specifically the LANG= and LC_MESSAGES
73 settings. The argument should be a valid locale identifier, such as
74 "de_DE.UTF-8". This controls the locale.conf(5) configuration file.
75 --keymap=KEYMAP
77 Sets the system keyboard layout. The argument should be a valid
78 keyboard map, such as "de-latin1". This controls the "KEYMAP" entry
79 in the vconsole.conf(5) configuration file.
80 --timezone=TIMEZONE
82 Sets the system time zone. The argument should be a valid time zone
83 identifier, such as "Europe/Berlin". This controls the localtime(5)
84 symlink.
85 --hostname=HOSTNAME
87 Sets the system hostname. The argument should be a hostname,
88 compatible with DNS. This controls the hostname(5) configuration
89 file.
90 --setup-machine-id
92 Initialize the system's machine ID to a random ID. This controls
93 the machine-id(5) file.
94 This option only works in combination with --root= or --image=. On
96 a running system, machine-id is written by the manager with help
97 from systemd-machine-id-commit.service(8).
98 --machine-id=ID
100 Set the system's machine ID to the specified value. The same
101 restrictions apply as to --setup-machine-id.
102 --root-password=PASSWORD, --root-password-file=PATH,
104 --root-password-hashed=HASHED_PASSWORD
105 Sets the password of the system's root user. This creates/modifies
106 the passwd(5) and shadow(5) files. This setting exists in three
107 forms: --root-password= accepts the password to set directly on the
108 command line, --root-password-file= reads it from a file and
109 --root-password-hashed= accepts an already hashed password on the
110 command line. See shadow(5) for more information on the format of
111 the hashed password. Note that it is not recommended to specify
112 plaintext passwords on the command line, as other users might be
113 able to see them simply by invoking ps(1).
114 --root-shell=SHELL
116 Sets the shell of the system's root user. This creates/modifies the
117 passwd(5) file.
118 --kernel-command-line=CMDLINE
120 Sets the system's kernel command line. This controls the
121 /etc/kernel/cmdline file which is used by kernel-install(8).
122 --prompt-locale, --prompt-keymap, --prompt-timezone, --prompt-hostname,
124 --prompt-root-password, --prompt-root-shell
125 Prompt the user interactively for a specific basic setting. Note
126 that any explicit configuration settings specified on the command
127 line take precedence, and the user is not prompted for it.
128 --prompt
130 Query the user for locale, keymap, timezone, hostname, root's
131 password, and root's shell. This is equivalent to specifying
132 --prompt-locale, --prompt-keymap, --prompt-timezone,
133 --prompt-hostname, --prompt-root-password, --prompt-root-shell in
134 combination.
135 --copy-locale, --copy-keymap, --copy-timezone, --copy-root-password,
137 --copy-root-shell
138 Copy a specific basic setting from the host. This only works in
139 combination with --root= or --image=.
140 --copy
142 Copy locale, keymap, time zone, root password and shell from the
143 host. This is equivalent to specifying --copy-locale,
144 --copy-keymap, --copy-timezone, --copy-root-password,
145 --copy-root-shell in combination.
146 --force
148 Write configuration even if the relevant files already exist.
149 Without this option, systemd-firstboot doesn't modify or replace
150 existing files. Note that when configuring the root account, even
151 with this option, systemd-firstboot only modifies the entry of the
152 "root" user, leaving other entries in /etc/passwd and /etc/shadow
153 intact.
154 --reset
156 If specified, all existing files that are configured by
157 systemd-firstboot are removed. Note that the files are removed
158 regardless of whether they'll be configured with a new value or
159 not. This operation ensures that the next boot of the image will be
160 considered a first boot, and systemd-firstboot will prompt again to
161 configure each of the removed files.
162 --delete-root-password
164 Removes the password of the system's root user, enabling login as
165 root without a password unless the root account is locked. Note
166 that this is extremely insecure and hence this option should not be
167 used lightly.
168 --welcome=
170 Takes a boolean argument. By default when prompting the user for
171 configuration options a brief welcome text is shown before the
172 first question is asked. Pass false to this option to turn off the
173 welcome text.
174 -h, --help
176 Print a short help text and exit.
177 --version
179 Print a short version string and exit.
180
182 systemd-firstboot supports the service credentials logic as implemented
183 by ImportCredential=/LoadCredential=/SetCredential= (see
184 systemd.exec(1) for details). The following credentials are used when
185 passed in:
186 passwd.hashed-password.root, passwd.plaintext-password.root
188 A hashed or plaintext version of the root password to use, in place
189 of prompting the user. These credentials are equivalent to the same
190 ones defined for the systemd-sysusers.service(8) service.
191 passwd.shell.root
193 Specifies the shell binary to use for the specified account.
194 Equivalent to the credential of the same name defined for the
195 systemd-sysusers.service(8) service.
196 firstboot.locale, firstboot.locale-messages
198 These credentials specify the locale settings to set during first
199 boot, in place of prompting the user.
200 firstboot.keymap
202 This credential specifies the keyboard setting to set during first
203 boot, in place of prompting the user.
204 Note the relationship to the vconsole.keymap credential understood
206 by systemd-vconsole-setup.service(8): both ultimately affect the
207 same setting, but firstboot.keymap is written into
208 /etc/vconsole.conf on first boot (if not already configured), and
209 then read from there by systemd-vconsole-setup, while
210 vconsole.keymap is read on every boot, and is not persisted to disk
211 (but any configuration in vconsole.conf will take precedence if
212 present).
213 firstboot.timezone
215 This credential specifies the system timezone setting to set during
216 first boot, in place of prompting the user.
217 Note that by default the systemd-firstboot.service unit file is set up
219 to inherit the listed credentials from the service manager. Thus, when
220 invoking a container with an unpopulated /etc/ for the first time it is
221 possible to configure the root user's password to be "systemd" like
222 this:
223 # systemd-nspawn --image=... --set-credential=firstboot.locale:de_DE.UTF-8 ...
225 Note that these credentials are only read and applied during the first
227 boot process. Once they are applied they remain applied for subsequent
228 boots, and the credentials are not considered anymore.
229
231 On success, 0 is returned, a non-zero failure code otherwise.
232
234 systemd.firstboot=
235 Takes a boolean argument, defaults to on. If off,
236 systemd-firstboot.service won't interactively query the user for
237 basic settings at first boot, even if those settings are not
238 initialized yet.
239
241 systemd(1), locale.conf(5), vconsole.conf(5), localtime(5),
242 hostname(5), machine-id(5), shadow(5), systemd-machine-id-setup(1),
243 localectl(1), timedatectl(1), hostnamectl(1)
244
246 1. Discoverable Partitions Specification
247 https://uapi-group.org/specifications/specs/discoverable_partitions_specification
248systemd 254 SYSTEMD-FIRSTBOOT(1)