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+
9 <refentry id=
"systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>systemd-firstboot
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>systemd-firstboot
</refentrytitle>
19 <manvolnum>1</manvolnum>
23 <refname>systemd-firstboot
</refname>
24 <refname>systemd-firstboot.service
</refname>
25 <refpurpose>Initialize basic system settings on or before the first boot-up of a system
</refpurpose>
30 <command>systemd-firstboot
</command>
31 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
34 <para><filename>systemd-firstboot.service
</filename></para>
38 <title>Description
</title>
40 <para><command>systemd-firstboot
</command> initializes the most
41 basic system settings interactively on the first boot, or
42 optionally non-interactively when a system image is created.
43 The service is started if
<varname>ConditionFirstBoot=yes
</varname>
44 is satisfied. This essentially means that
<filename>/etc
</filename>
46 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
49 <para>The following settings may be set up:
</para>
52 <listitem><para>The system locale, more specifically the two
53 locale variables
<varname>LANG=
</varname> and
54 <varname>LC_MESSAGES
</varname></para></listitem>
56 <listitem><para>The system keyboard map
</para></listitem>
58 <listitem><para>The system time zone
</para></listitem>
60 <listitem><para>The system host name
</para></listitem>
62 <listitem><para>The machine ID of the system
</para></listitem>
64 <listitem><para>The root user's password
</para></listitem>
67 <para>Each of the fields may either be queried interactively by
68 users, set non-interactively on the tool's command line, or be
69 copied from a host system that is used to set up the system
72 <para>If a setting is already initialized, it will not be
73 overwritten and the user will not be prompted for the
76 <para>Note that this tool operates directly on the file system and
77 does not involve any running system services, unlike
78 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
79 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
81 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
82 This allows
<command>systemd-firstboot
</command> to operate on
83 mounted but not booted disk images and in early boot. It is not
84 recommended to use
<command>systemd-firstboot
</command> on the
85 running system while it is up.
</para>
89 <title>Options
</title>
91 <para>The following options are understood:
</para>
95 <term><option>--root=
<replaceable>root
</replaceable></option></term>
96 <listitem><para>Takes a directory path as an argument. All
97 paths will be prefixed with the given alternate
98 <replaceable>root
</replaceable> path, including config search
99 paths. This is useful to operate on a system image mounted to
100 the specified directory instead of the host system itself.
105 <term><option>--locale=
<replaceable>LOCALE
</replaceable></option></term>
106 <term><option>--locale-messages=
<replaceable>LOCALE
</replaceable></option></term>
108 <listitem><para>Sets the system locale, more specifically the
109 <varname>LANG=
</varname> and
<varname>LC_MESSAGES
</varname>
110 settings. The argument should be a valid locale identifier,
111 such as
<literal>de_DE.UTF-
8</literal>. This controls the
112 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
113 configuration file.
</para></listitem>
117 <term><option>--keymap=
<replaceable>KEYMAP
</replaceable></option></term>
119 <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
120 such as
<literal>de-latin1
</literal>. This controls the
<literal>KEYMAP
</literal> entry in the
121 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
122 configuration file.
</para></listitem>
126 <term><option>--timezone=
<replaceable>TIMEZONE
</replaceable></option></term>
128 <listitem><para>Sets the system time zone. The argument should
129 be a valid time zone identifier, such as
130 <literal>Europe/Berlin
</literal>. This controls the
131 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
132 symlink.
</para></listitem>
136 <term><option>--hostname=
<replaceable>HOSTNAME
</replaceable></option></term>
138 <listitem><para>Sets the system hostname. The argument should
139 be a host name, compatible with DNS. This controls the
140 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
141 configuration file.
</para></listitem>
145 <term><option>--machine-id=
<replaceable>ID
</replaceable></option></term>
147 <listitem><para>Sets the system's machine ID. This controls
149 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
150 file.
</para></listitem>
154 <term><option>--root-password=
<replaceable>PASSWORD
</replaceable></option></term>
155 <term><option>--root-password-file=
<replaceable>PATH
</replaceable></option></term>
157 <listitem><para>Sets the password of the system's root user.
159 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
160 file. This setting exists in two forms:
161 <option>--root-password=
</option> accepts the password to set
162 directly on the command line, and
163 <option>--root-password-file=
</option> reads it from a file.
164 Note that it is not recommended to specify passwords on the
165 command line, as other users might be able to see them simply
167 <citerefentry project='die-net'
><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
171 <term><option>--prompt-locale
</option></term>
172 <term><option>--prompt-keymap
</option></term>
173 <term><option>--prompt-timezone
</option></term>
174 <term><option>--prompt-hostname
</option></term>
175 <term><option>--prompt-root-password
</option></term>
177 <listitem><para>Prompt the user interactively for a specific
178 basic setting. Note that any explicit configuration settings
179 specified on the command line take precedence, and the user is
180 not prompted for it.
</para></listitem>
184 <term><option>--prompt
</option></term>
186 <listitem><para>Query the user for locale, keymap, timezone, hostname
187 and root password. This is equivalent to specifying
188 <option>--prompt-locale
</option>,
189 <option>--prompt-keymap
</option>,
190 <option>--prompt-timezone
</option>,
191 <option>--prompt-hostname
</option>,
192 <option>--prompt-root-password
</option> in combination.
</para>
197 <term><option>--copy-locale
</option></term>
198 <term><option>--copy-keymap
</option></term>
199 <term><option>--copy-timezone
</option></term>
200 <term><option>--copy-root-password
</option></term>
202 <listitem><para>Copy a specific basic setting from the host.
203 This only works in combination with
<option>--root=
</option>
204 (see above).
</para></listitem>
208 <term><option>--copy
</option></term>
210 <listitem><para>Copy locale, keymap, time zone and root password from
211 the host. This is equivalent to specifying
212 <option>--copy-locale
</option>,
213 <option>--copy-keymap
</option>,
214 <option>--copy-timezone
</option>,
215 <option>--copy-root-password
</option> in combination.
</para>
220 <term><option>--setup-machine-id
</option></term>
222 <listitem><para>Initialize the system's machine ID to a random
223 ID. This only works in combination with
224 <option>--root=
</option>.
</para></listitem>
227 <xi:include href=
"standard-options.xml" xpointer=
"help" />
228 <xi:include href=
"standard-options.xml" xpointer=
"version" />
234 <title>Exit status
</title>
236 <para>On success,
0 is returned, a non-zero failure code
241 <title>Kernel Command Line
</title>
243 <variablelist class='kernel-commandline-options'
>
245 <term><varname>systemd.firstboot=
</varname></term>
247 <listitem><para>Takes a boolean argument, defaults to on. If off,
<filename>systemd-firstboot.service
</filename>
248 won't interactively query the user for basic settings at first boot, even if those settings are not
249 initialized yet.
</para></listitem>
255 <title>See Also
</title>
257 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
258 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
259 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
260 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
261 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
262 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
263 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>systemd-machine-id-setup
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
265 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
266 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
267 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>