1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
8 Copyright 2014 Lennart Poettering
11 <refentry id=
"systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
12 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
15 <title>systemd-firstboot
</title>
16 <productname>systemd
</productname>
20 <contrib>Developer
</contrib>
21 <firstname>Lennart
</firstname>
22 <surname>Poettering
</surname>
23 <email>lennart@poettering.net
</email>
29 <refentrytitle>systemd-firstboot
</refentrytitle>
30 <manvolnum>1</manvolnum>
34 <refname>systemd-firstboot
</refname>
35 <refname>systemd-firstboot.service
</refname>
36 <refpurpose>Initialize basic system settings on or before the first boot-up of a system
</refpurpose>
41 <command>systemd-firstboot
</command>
42 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
45 <para><filename>systemd-firstboot.service
</filename></para>
49 <title>Description
</title>
51 <para><command>systemd-firstboot
</command> initializes the most
52 basic system settings interactively on the first boot, or
53 optionally non-interactively when a system image is created.
54 The service is started if
<varname>ConditionFirstBoot=yes
</varname>
55 is satisfied. This essentially means that
<filename>/etc
</filename>
57 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
60 <para>The following settings may be set up:
</para>
63 <listitem><para>The system locale, more specifically the two
64 locale variables
<varname>LANG=
</varname> and
65 <varname>LC_MESSAGES
</varname></para></listitem>
67 <listitem><para>The system keyboard map
</para></listitem>
69 <listitem><para>The system time zone
</para></listitem>
71 <listitem><para>The system host name
</para></listitem>
73 <listitem><para>The machine ID of the system
</para></listitem>
75 <listitem><para>The root user's password
</para></listitem>
78 <para>Each of the fields may either be queried interactively by
79 users, set non-interactively on the tool's command line, or be
80 copied from a host system that is used to set up the system
83 <para>If a setting is already initialized, it will not be
84 overwritten and the user will not be prompted for the
87 <para>Note that this tool operates directly on the file system and
88 does not involve any running system services, unlike
89 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
90 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
92 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
93 This allows
<command>systemd-firstboot
</command> to operate on
94 mounted but not booted disk images and in early boot. It is not
95 recommended to use
<command>systemd-firstboot
</command> on the
96 running system while it is up.
</para>
100 <title>Options
</title>
102 <para>The following options are understood:
</para>
106 <term><option>--root=
<replaceable>root
</replaceable></option></term>
107 <listitem><para>Takes a directory path as an argument. All
108 paths will be prefixed with the given alternate
109 <replaceable>root
</replaceable> path, including config search
110 paths. This is useful to operate on a system image mounted to
111 the specified directory instead of the host system itself.
116 <term><option>--locale=
<replaceable>LOCALE
</replaceable></option></term>
117 <term><option>--locale-messages=
<replaceable>LOCALE
</replaceable></option></term>
119 <listitem><para>Sets the system locale, more specifically the
120 <varname>LANG=
</varname> and
<varname>LC_MESSAGES
</varname>
121 settings. The argument should be a valid locale identifier,
122 such as
<literal>de_DE.UTF-
8</literal>. This controls the
123 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
124 configuration file.
</para></listitem>
128 <term><option>--keymap=
<replaceable>KEYMAP
</replaceable></option></term>
130 <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
131 such as
<literal>de-latin1
</literal>. This controls the
<literal>KEYMAP
</literal> entry in the
132 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
133 configuration file.
</para></listitem>
137 <term><option>--timezone=
<replaceable>TIMEZONE
</replaceable></option></term>
139 <listitem><para>Sets the system time zone. The argument should
140 be a valid time zone identifier, such as
141 <literal>Europe/Berlin
</literal>. This controls the
142 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
143 symlink.
</para></listitem>
147 <term><option>--hostname=
<replaceable>HOSTNAME
</replaceable></option></term>
149 <listitem><para>Sets the system hostname. The argument should
150 be a host name, compatible with DNS. This controls the
151 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
152 configuration file.
</para></listitem>
156 <term><option>--machine-id=
<replaceable>ID
</replaceable></option></term>
158 <listitem><para>Sets the system's machine ID. This controls
160 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
161 file.
</para></listitem>
165 <term><option>--root-password=
<replaceable>PASSWORD
</replaceable></option></term>
166 <term><option>--root-password-file=
<replaceable>PATH
</replaceable></option></term>
168 <listitem><para>Sets the password of the system's root user.
170 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
171 file. This setting exists in two forms:
172 <option>--root-password=
</option> accepts the password to set
173 directly on the command line, and
174 <option>--root-password-file=
</option> reads it from a file.
175 Note that it is not recommended to specify passwords on the
176 command line, as other users might be able to see them simply
178 <citerefentry project='die-net'
><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
182 <term><option>--prompt-locale
</option></term>
183 <term><option>--prompt-keymap
</option></term>
184 <term><option>--prompt-timezone
</option></term>
185 <term><option>--prompt-hostname
</option></term>
186 <term><option>--prompt-root-password
</option></term>
188 <listitem><para>Prompt the user interactively for a specific
189 basic setting. Note that any explicit configuration settings
190 specified on the command line take precedence, and the user is
191 not prompted for it.
</para></listitem>
195 <term><option>--prompt
</option></term>
197 <listitem><para>Query the user for locale, keymap, timezone, hostname
198 and root password. This is equivalent to specifying
199 <option>--prompt-locale
</option>,
200 <option>--prompt-keymap
</option>,
201 <option>--prompt-timezone
</option>,
202 <option>--prompt-hostname
</option>,
203 <option>--prompt-root-password
</option> in combination.
</para>
208 <term><option>--copy-locale
</option></term>
209 <term><option>--copy-keymap
</option></term>
210 <term><option>--copy-timezone
</option></term>
211 <term><option>--copy-root-password
</option></term>
213 <listitem><para>Copy a specific basic setting from the host.
214 This only works in combination with
<option>--root=
</option>
215 (see above).
</para></listitem>
219 <term><option>--copy
</option></term>
221 <listitem><para>Copy locale, keymap, time zone and root password from
222 the host. This is equivalent to specifying
223 <option>--copy-locale
</option>,
224 <option>--copy-keymap
</option>,
225 <option>--copy-timezone
</option>,
226 <option>--copy-root-password
</option> in combination.
</para>
231 <term><option>--setup-machine-id
</option></term>
233 <listitem><para>Initialize the system's machine ID to a random
234 ID. This only works in combination with
235 <option>--root=
</option>.
</para></listitem>
238 <xi:include href=
"standard-options.xml" xpointer=
"help" />
239 <xi:include href=
"standard-options.xml" xpointer=
"version" />
245 <title>Exit status
</title>
247 <para>On success,
0 is returned, a non-zero failure code
252 <title>Kernel Command Line
</title>
254 <variablelist class='kernel-commandline-options'
>
256 <term><varname>systemd.firstboot=
</varname></term>
258 <listitem><para>Takes a boolean argument, defaults to on. If off,
<filename>systemd-firstboot.service
</filename>
259 won't interactively query the user for basic settings at first boot, even if those settings are not
260 initialized yet.
</para></listitem>
266 <title>See Also
</title>
268 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
269 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
270 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
271 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
272 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
273 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
274 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
275 <citerefentry><refentrytitle>systemd-machine-id-setup
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
276 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
277 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
278 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>