1 <?xml version='
1.0'
?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>systemd-firstboot
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>systemd-firstboot
</refentrytitle>
16 <manvolnum>1</manvolnum>
20 <refname>systemd-firstboot
</refname>
21 <refname>systemd-firstboot.service
</refname>
22 <refpurpose>Initialize basic system settings on or before the first boot-up of a system
</refpurpose>
27 <command>systemd-firstboot
</command>
28 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
31 <para><filename>systemd-firstboot.service
</filename></para>
35 <title>Description
</title>
37 <para><command>systemd-firstboot
</command> initializes the most
38 basic system settings interactively on the first boot, or
39 optionally non-interactively when a system image is created.
40 The service is started if
<varname>ConditionFirstBoot=yes
</varname>
41 is satisfied. This essentially means that
<filename>/etc
</filename>
43 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
46 <para>The following settings may be set up:
</para>
49 <listitem><para>The system locale, more specifically the two
50 locale variables
<varname>LANG=
</varname> and
51 <varname>LC_MESSAGES
</varname></para></listitem>
53 <listitem><para>The system keyboard map
</para></listitem>
55 <listitem><para>The system time zone
</para></listitem>
57 <listitem><para>The system host name
</para></listitem>
59 <listitem><para>The machine ID of the system
</para></listitem>
61 <listitem><para>The root user's password
</para></listitem>
64 <para>Each of the fields may either be queried interactively by
65 users, set non-interactively on the tool's command line, or be
66 copied from a host system that is used to set up the system
69 <para>If a setting is already initialized, it will not be
70 overwritten and the user will not be prompted for the
73 <para>Note that this tool operates directly on the file system and
74 does not involve any running system services, unlike
75 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
76 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
78 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
79 This allows
<command>systemd-firstboot
</command> to operate on
80 mounted but not booted disk images and in early boot. It is not
81 recommended to use
<command>systemd-firstboot
</command> on the
82 running system while it is up.
</para>
86 <title>Options
</title>
88 <para>The following options are understood:
</para>
92 <term><option>--root=
<replaceable>root
</replaceable></option></term>
93 <listitem><para>Takes a directory path as an argument. All
94 paths will be prefixed with the given alternate
95 <replaceable>root
</replaceable> path, including config search
96 paths. This is useful to operate on a system image mounted to
97 the specified directory instead of the host system itself.
102 <term><option>--locale=
<replaceable>LOCALE
</replaceable></option></term>
103 <term><option>--locale-messages=
<replaceable>LOCALE
</replaceable></option></term>
105 <listitem><para>Sets the system locale, more specifically the
106 <varname>LANG=
</varname> and
<varname>LC_MESSAGES
</varname>
107 settings. The argument should be a valid locale identifier,
108 such as
<literal>de_DE.UTF-
8</literal>. This controls the
109 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
110 configuration file.
</para></listitem>
114 <term><option>--keymap=
<replaceable>KEYMAP
</replaceable></option></term>
116 <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
117 such as
<literal>de-latin1
</literal>. This controls the
<literal>KEYMAP
</literal> entry in the
118 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
119 configuration file.
</para></listitem>
123 <term><option>--timezone=
<replaceable>TIMEZONE
</replaceable></option></term>
125 <listitem><para>Sets the system time zone. The argument should
126 be a valid time zone identifier, such as
127 <literal>Europe/Berlin
</literal>. This controls the
128 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
129 symlink.
</para></listitem>
133 <term><option>--hostname=
<replaceable>HOSTNAME
</replaceable></option></term>
135 <listitem><para>Sets the system hostname. The argument should
136 be a host name, compatible with DNS. This controls the
137 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
138 configuration file.
</para></listitem>
142 <term><option>--machine-id=
<replaceable>ID
</replaceable></option></term>
144 <listitem><para>Sets the system's machine ID. This controls
146 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
147 file.
</para></listitem>
151 <term><option>--root-password=
<replaceable>PASSWORD
</replaceable></option></term>
152 <term><option>--root-password-file=
<replaceable>PATH
</replaceable></option></term>
154 <listitem><para>Sets the password of the system's root user.
156 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
157 file. This setting exists in two forms:
158 <option>--root-password=
</option> accepts the password to set
159 directly on the command line, and
160 <option>--root-password-file=
</option> reads it from a file.
161 Note that it is not recommended to specify passwords on the
162 command line, as other users might be able to see them simply
164 <citerefentry project='die-net'
><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
168 <term><option>--prompt-locale
</option></term>
169 <term><option>--prompt-keymap
</option></term>
170 <term><option>--prompt-timezone
</option></term>
171 <term><option>--prompt-hostname
</option></term>
172 <term><option>--prompt-root-password
</option></term>
174 <listitem><para>Prompt the user interactively for a specific
175 basic setting. Note that any explicit configuration settings
176 specified on the command line take precedence, and the user is
177 not prompted for it.
</para></listitem>
181 <term><option>--prompt
</option></term>
183 <listitem><para>Query the user for locale, keymap, timezone, hostname
184 and root password. This is equivalent to specifying
185 <option>--prompt-locale
</option>,
186 <option>--prompt-keymap
</option>,
187 <option>--prompt-timezone
</option>,
188 <option>--prompt-hostname
</option>,
189 <option>--prompt-root-password
</option> in combination.
</para>
194 <term><option>--copy-locale
</option></term>
195 <term><option>--copy-keymap
</option></term>
196 <term><option>--copy-timezone
</option></term>
197 <term><option>--copy-root-password
</option></term>
199 <listitem><para>Copy a specific basic setting from the host.
200 This only works in combination with
<option>--root=
</option>
201 (see above).
</para></listitem>
205 <term><option>--copy
</option></term>
207 <listitem><para>Copy locale, keymap, time zone and root password from
208 the host. This is equivalent to specifying
209 <option>--copy-locale
</option>,
210 <option>--copy-keymap
</option>,
211 <option>--copy-timezone
</option>,
212 <option>--copy-root-password
</option> in combination.
</para>
217 <term><option>--setup-machine-id
</option></term>
219 <listitem><para>Initialize the system's machine ID to a random
220 ID. This only works in combination with
221 <option>--root=
</option>.
</para></listitem>
224 <xi:include href=
"standard-options.xml" xpointer=
"help" />
225 <xi:include href=
"standard-options.xml" xpointer=
"version" />
231 <title>Exit status
</title>
233 <para>On success,
0 is returned, a non-zero failure code
238 <title>Kernel Command Line
</title>
240 <variablelist class='kernel-commandline-options'
>
242 <term><varname>systemd.firstboot=
</varname></term>
244 <listitem><para>Takes a boolean argument, defaults to on. If off,
<filename>systemd-firstboot.service
</filename>
245 won't interactively query the user for basic settings at first boot, even if those settings are not
246 initialized yet.
</para></listitem>
252 <title>See Also
</title>
254 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
255 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
256 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
257 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
258 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
259 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
260 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
261 <citerefentry><refentrytitle>systemd-machine-id-setup
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
262 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
263 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>