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 This file is part of systemd.
10 Copyright 2014 Lennart Poettering
13 <refentry id=
"systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
14 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
17 <title>systemd-firstboot
</title>
18 <productname>systemd
</productname>
22 <contrib>Developer
</contrib>
23 <firstname>Lennart
</firstname>
24 <surname>Poettering
</surname>
25 <email>lennart@poettering.net
</email>
31 <refentrytitle>systemd-firstboot
</refentrytitle>
32 <manvolnum>1</manvolnum>
36 <refname>systemd-firstboot
</refname>
37 <refname>systemd-firstboot.service
</refname>
38 <refpurpose>Initialize basic system settings on or before the first boot-up of a system
</refpurpose>
43 <command>systemd-firstboot
</command>
44 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
47 <para><filename>systemd-firstboot.service
</filename></para>
51 <title>Description
</title>
53 <para><command>systemd-firstboot
</command> initializes the most
54 basic system settings interactively on the first boot, or
55 optionally non-interactively when a system image is created.
56 The service is started if
<varname>ConditionFirstBoot=yes
</varname>
57 is satisfied. This essentially means that
<filename>/etc
</filename>
59 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
62 <para>The following settings may be set up:
</para>
65 <listitem><para>The system locale, more specifically the two
66 locale variables
<varname>LANG=
</varname> and
67 <varname>LC_MESSAGES
</varname></para></listitem>
69 <listitem><para>The system keyboard map
</para></listitem>
71 <listitem><para>The system time zone
</para></listitem>
73 <listitem><para>The system host name
</para></listitem>
75 <listitem><para>The machine ID of the system
</para></listitem>
77 <listitem><para>The root user's password
</para></listitem>
80 <para>Each of the fields may either be queried interactively by
81 users, set non-interactively on the tool's command line, or be
82 copied from a host system that is used to set up the system
85 <para>If a setting is already initialized, it will not be
86 overwritten and the user will not be prompted for the
89 <para>Note that this tool operates directly on the file system and
90 does not involve any running system services, unlike
91 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
92 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
94 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
95 This allows
<command>systemd-firstboot
</command> to operate on
96 mounted but not booted disk images and in early boot. It is not
97 recommended to use
<command>systemd-firstboot
</command> on the
98 running system while it is up.
</para>
102 <title>Options
</title>
104 <para>The following options are understood:
</para>
108 <term><option>--root=
<replaceable>root
</replaceable></option></term>
109 <listitem><para>Takes a directory path as an argument. All
110 paths will be prefixed with the given alternate
111 <replaceable>root
</replaceable> path, including config search
112 paths. This is useful to operate on a system image mounted to
113 the specified directory instead of the host system itself.
118 <term><option>--locale=
<replaceable>LOCALE
</replaceable></option></term>
119 <term><option>--locale-messages=
<replaceable>LOCALE
</replaceable></option></term>
121 <listitem><para>Sets the system locale, more specifically the
122 <varname>LANG=
</varname> and
<varname>LC_MESSAGES
</varname>
123 settings. The argument should be a valid locale identifier,
124 such as
<literal>de_DE.UTF-
8</literal>. This controls the
125 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
126 configuration file.
</para></listitem>
130 <term><option>--keymap=
<replaceable>KEYMAP
</replaceable></option></term>
132 <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
133 such as
<literal>de-latin1
</literal>. This controls the
<literal>KEYMAP
</literal> entry in the
134 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
135 configuration file.
</para></listitem>
139 <term><option>--timezone=
<replaceable>TIMEZONE
</replaceable></option></term>
141 <listitem><para>Sets the system time zone. The argument should
142 be a valid time zone identifier, such as
143 <literal>Europe/Berlin
</literal>. This controls the
144 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
145 symlink.
</para></listitem>
149 <term><option>--hostname=
<replaceable>HOSTNAME
</replaceable></option></term>
151 <listitem><para>Sets the system hostname. The argument should
152 be a host name, compatible with DNS. This controls the
153 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
154 configuration file.
</para></listitem>
158 <term><option>--machine-id=
<replaceable>ID
</replaceable></option></term>
160 <listitem><para>Sets the system's machine ID. This controls
162 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
163 file.
</para></listitem>
167 <term><option>--root-password=
<replaceable>PASSWORD
</replaceable></option></term>
168 <term><option>--root-password-file=
<replaceable>PATH
</replaceable></option></term>
170 <listitem><para>Sets the password of the system's root user.
172 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
173 file. This setting exists in two forms:
174 <option>--root-password=
</option> accepts the password to set
175 directly on the command line, and
176 <option>--root-password-file=
</option> reads it from a file.
177 Note that it is not recommended to specify passwords on the
178 command line, as other users might be able to see them simply
180 <citerefentry project='die-net'
><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
184 <term><option>--prompt-locale
</option></term>
185 <term><option>--prompt-keymap
</option></term>
186 <term><option>--prompt-timezone
</option></term>
187 <term><option>--prompt-hostname
</option></term>
188 <term><option>--prompt-root-password
</option></term>
190 <listitem><para>Prompt the user interactively for a specific
191 basic setting. Note that any explicit configuration settings
192 specified on the command line take precedence, and the user is
193 not prompted for it.
</para></listitem>
197 <term><option>--prompt
</option></term>
199 <listitem><para>Query the user for locale, keymap, timezone, hostname
200 and root password. This is equivalent to specifying
201 <option>--prompt-locale
</option>,
202 <option>--prompt-keymap
</option>,
203 <option>--prompt-timezone
</option>,
204 <option>--prompt-hostname
</option>,
205 <option>--prompt-root-password
</option> in combination.
</para>
210 <term><option>--copy-locale
</option></term>
211 <term><option>--copy-keymap
</option></term>
212 <term><option>--copy-timezone
</option></term>
213 <term><option>--copy-root-password
</option></term>
215 <listitem><para>Copy a specific basic setting from the host.
216 This only works in combination with
<option>--root=
</option>
217 (see above).
</para></listitem>
221 <term><option>--copy
</option></term>
223 <listitem><para>Copy locale, keymap, time zone and root password from
224 the host. This is equivalent to specifying
225 <option>--copy-locale
</option>,
226 <option>--copy-keymap
</option>,
227 <option>--copy-timezone
</option>,
228 <option>--copy-root-password
</option> in combination.
</para>
233 <term><option>--setup-machine-id
</option></term>
235 <listitem><para>Initialize the system's machine ID to a random
236 ID. This only works in combination with
237 <option>--root=
</option>.
</para></listitem>
240 <xi:include href=
"standard-options.xml" xpointer=
"help" />
241 <xi:include href=
"standard-options.xml" xpointer=
"version" />
247 <title>Exit status
</title>
249 <para>On success,
0 is returned, a non-zero failure code
254 <title>Kernel Command Line
</title>
256 <variablelist class='kernel-commandline-options'
>
258 <term><varname>systemd.firstboot=
</varname></term>
260 <listitem><para>Takes a boolean argument, defaults to on. If off,
<filename>systemd-firstboot.service
</filename>
261 won't interactively query the user for basic settings at first boot, even if those settings are not
262 initialized yet.
</para></listitem>
268 <title>See Also
</title>
270 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
271 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
272 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
273 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
274 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
275 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
276 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
277 <citerefentry><refentrytitle>systemd-machine-id-setup
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
278 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
279 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
280 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>