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
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
26 <refentry id=
"systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
27 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
30 <title>systemd-firstboot
</title>
31 <productname>systemd
</productname>
35 <contrib>Developer
</contrib>
36 <firstname>Lennart
</firstname>
37 <surname>Poettering
</surname>
38 <email>lennart@poettering.net
</email>
44 <refentrytitle>systemd-firstboot
</refentrytitle>
45 <manvolnum>1</manvolnum>
49 <refname>systemd-firstboot
</refname>
50 <refname>systemd-firstboot.service
</refname>
51 <refpurpose>Initialize basic system settings on or before the first boot-up of a system
</refpurpose>
56 <command>systemd-firstboot
</command>
57 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
60 <para><filename>systemd-firstboot.service
</filename></para>
64 <title>Description
</title>
66 <para><command>systemd-firstboot
</command> initializes the most
67 basic system settings interactively on the first boot, or
68 optionally non-interactively when a system image is created.
69 The service is started if
<varname>ConditionFirstBoot=yes
</varname>
70 is satisfied. This essentially means that
<filename>/etc
</filename>
72 <citerefentry><refentrytitle>systemd.unit
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
75 <para>The following settings may be set up:
</para>
78 <listitem><para>The system locale, more specifically the two
79 locale variables
<varname>LANG=
</varname> and
80 <varname>LC_MESSAGES
</varname></para></listitem>
82 <listitem><para>The system keyboard map
</para></listitem>
84 <listitem><para>The system time zone
</para></listitem>
86 <listitem><para>The system host name
</para></listitem>
88 <listitem><para>The machine ID of the system
</para></listitem>
90 <listitem><para>The root user's password
</para></listitem>
93 <para>Each of the fields may either be queried interactively by
94 users, set non-interactively on the tool's command line, or be
95 copied from a host system that is used to set up the system
98 <para>If a setting is already initialized, it will not be
99 overwritten and the user will not be prompted for the
102 <para>Note that this tool operates directly on the file system and
103 does not involve any running system services, unlike
104 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
105 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
107 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
108 This allows
<command>systemd-firstboot
</command> to operate on
109 mounted but not booted disk images and in early boot. It is not
110 recommended to use
<command>systemd-firstboot
</command> on the
111 running system while it is up.
</para>
115 <title>Options
</title>
117 <para>The following options are understood:
</para>
121 <term><option>--root=
<replaceable>root
</replaceable></option></term>
122 <listitem><para>Takes a directory path as an argument. All
123 paths will be prefixed with the given alternate
124 <replaceable>root
</replaceable> path, including config search
125 paths. This is useful to operate on a system image mounted to
126 the specified directory instead of the host system itself.
131 <term><option>--locale=
<replaceable>LOCALE
</replaceable></option></term>
132 <term><option>--locale-messages=
<replaceable>LOCALE
</replaceable></option></term>
134 <listitem><para>Sets the system locale, more specifically the
135 <varname>LANG=
</varname> and
<varname>LC_MESSAGES
</varname>
136 settings. The argument should be a valid locale identifier,
137 such as
<literal>de_DE.UTF-
8</literal>. This controls the
138 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
139 configuration file.
</para></listitem>
143 <term><option>--keymap=
<replaceable>KEYMAP
</replaceable></option></term>
145 <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
146 such as
<literal>de-latin1
</literal>. This controls the
<literal>KEYMAP
</literal> entry in the
147 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
148 configuration file.
</para></listitem>
152 <term><option>--timezone=
<replaceable>TIMEZONE
</replaceable></option></term>
154 <listitem><para>Sets the system time zone. The argument should
155 be a valid time zone identifier, such as
156 <literal>Europe/Berlin
</literal>. This controls the
157 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
158 symlink.
</para></listitem>
162 <term><option>--hostname=
<replaceable>HOSTNAME
</replaceable></option></term>
164 <listitem><para>Sets the system hostname. The argument should
165 be a host name, compatible with DNS. This controls the
166 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
167 configuration file.
</para></listitem>
171 <term><option>--machine-id=
<replaceable>ID
</replaceable></option></term>
173 <listitem><para>Sets the system's machine ID. This controls
175 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
176 file.
</para></listitem>
180 <term><option>--root-password=
<replaceable>PASSWORD
</replaceable></option></term>
181 <term><option>--root-password-file=
<replaceable>PATH
</replaceable></option></term>
183 <listitem><para>Sets the password of the system's root user.
185 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
186 file. This setting exists in two forms:
187 <option>--root-password=
</option> accepts the password to set
188 directly on the command line, and
189 <option>--root-password-file=
</option> reads it from a file.
190 Note that it is not recommended to specify passwords on the
191 command line, as other users might be able to see them simply
193 <citerefentry project='die-net'
><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para></listitem>
197 <term><option>--prompt-locale
</option></term>
198 <term><option>--prompt-keymap
</option></term>
199 <term><option>--prompt-timezone
</option></term>
200 <term><option>--prompt-hostname
</option></term>
201 <term><option>--prompt-root-password
</option></term>
203 <listitem><para>Prompt the user interactively for a specific
204 basic setting. Note that any explicit configuration settings
205 specified on the command line take precedence, and the user is
206 not prompted for it.
</para></listitem>
210 <term><option>--prompt
</option></term>
212 <listitem><para>Query the user for locale, keymap, timezone, hostname
213 and root password. This is equivalent to specifying
214 <option>--prompt-locale
</option>,
215 <option>--prompt-keymap
</option>,
216 <option>--prompt-timezone
</option>,
217 <option>--prompt-hostname
</option>,
218 <option>--prompt-root-password
</option> in combination.
</para>
223 <term><option>--copy-locale
</option></term>
224 <term><option>--copy-keymap
</option></term>
225 <term><option>--copy-timezone
</option></term>
226 <term><option>--copy-root-password
</option></term>
228 <listitem><para>Copy a specific basic setting from the host.
229 This only works in combination with
<option>--root=
</option>
230 (see above).
</para></listitem>
234 <term><option>--copy
</option></term>
236 <listitem><para>Copy locale, keymap, time zone and root password from
237 the host. This is equivalent to specifying
238 <option>--copy-locale
</option>,
239 <option>--copy-keymap
</option>,
240 <option>--copy-timezone
</option>,
241 <option>--copy-root-password
</option> in combination.
</para>
246 <term><option>--setup-machine-id
</option></term>
248 <listitem><para>Initialize the system's machine ID to a random
249 ID. This only works in combination with
250 <option>--root=
</option>.
</para></listitem>
253 <xi:include href=
"standard-options.xml" xpointer=
"help" />
254 <xi:include href=
"standard-options.xml" xpointer=
"version" />
260 <title>Exit status
</title>
262 <para>On success,
0 is returned, a non-zero failure code
267 <title>Kernel Command Line
</title>
269 <variablelist class='kernel-commandline-options'
>
271 <term><varname>systemd.firstboot=
</varname></term>
273 <listitem><para>Takes a boolean argument, defaults to on. If off,
<filename>systemd-firstboot.service
</filename>
274 won't interactively query the user for basic settings at first boot, even if those settings are not
275 initialized yet.
</para></listitem>
281 <title>See Also
</title>
283 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
284 <citerefentry project='man-pages'
><refentrytitle>locale.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
285 <citerefentry project='man-pages'
><refentrytitle>vconsole.conf
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>localtime
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
287 <citerefentry><refentrytitle>hostname
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
288 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
289 <citerefentry project='die-net'
><refentrytitle>shadow
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
290 <citerefentry><refentrytitle>systemd-machine-id-setup
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
291 <citerefentry project='man-pages'
><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
292 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
293 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>