]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/systemd-firstboot.xml
verify: use manager_load_startable_unit_or_warn() to load units for verification
[thirdparty/systemd.git] / man / systemd-firstboot.xml
CommitLineData
30f10abf
LP
1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
30f10abf
LP
4
5<!--
572eb058
ZJS
6 SPDX-License-Identifier: LGPL-2.1+
7
30f10abf
LP
8 This file is part of systemd.
9
10 Copyright 2014 Lennart Poettering
11
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.
16
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.
21
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/>.
24-->
25
efd51554 26<refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
798d3a52
ZJS
27 xmlns:xi="http://www.w3.org/2001/XInclude">
28
29 <refentryinfo>
30 <title>systemd-firstboot</title>
31 <productname>systemd</productname>
32
33 <authorgroup>
34 <author>
35 <contrib>Developer</contrib>
36 <firstname>Lennart</firstname>
37 <surname>Poettering</surname>
38 <email>lennart@poettering.net</email>
39 </author>
40 </authorgroup>
41 </refentryinfo>
42
43 <refmeta>
44 <refentrytitle>systemd-firstboot</refentrytitle>
45 <manvolnum>1</manvolnum>
46 </refmeta>
47
48 <refnamediv>
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>
52 </refnamediv>
53
54 <refsynopsisdiv>
55 <cmdsynopsis>
56 <command>systemd-firstboot</command>
57 <arg choice="opt" rep="repeat">OPTIONS</arg>
58 </cmdsynopsis>
59
60 <para><filename>systemd-firstboot.service</filename></para>
61 </refsynopsisdiv>
62
63 <refsect1>
64 <title>Description</title>
65
66 <para><command>systemd-firstboot</command> initializes the most
67 basic system settings interactively on the first boot, or
c954f332
ZJS
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>
71 is empty, see
72 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
73 for details.</para>
74
75 <para>The following settings may be set up:</para>
798d3a52
ZJS
76
77 <itemizedlist>
78 <listitem><para>The system locale, more specifically the two
79 locale variables <varname>LANG=</varname> and
80 <varname>LC_MESSAGES</varname></para></listitem>
81
ed457f13
TB
82 <listitem><para>The system keyboard map</para></listitem>
83
798d3a52
ZJS
84 <listitem><para>The system time zone</para></listitem>
85
86 <listitem><para>The system host name</para></listitem>
87
88 <listitem><para>The machine ID of the system</para></listitem>
89
90 <listitem><para>The root user's password</para></listitem>
91 </itemizedlist>
92
a8eaaee7
JE
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
798d3a52
ZJS
95 copied from a host system that is used to set up the system
96 image.</para>
97
b938cb90 98 <para>If a setting is already initialized, it will not be
798d3a52
ZJS
99 overwritten and the user will not be prompted for the
100 setting.</para>
101
102 <para>Note that this tool operates directly on the file system and
103 does not involve any running system services, unlike
3ba3a79d 104 <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52
ZJS
105 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
106 or
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>
112 </refsect1>
113
114 <refsect1>
115 <title>Options</title>
116
117 <para>The following options are understood:</para>
118
119 <variablelist>
120 <varlistentry>
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.
127 </para></listitem>
128 </varlistentry>
129
130 <varlistentry>
131 <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
132 <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
133
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
3ba3a79d 138 <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a52
ZJS
139 configuration file.</para></listitem>
140 </varlistentry>
141
ed457f13
TB
142 <varlistentry>
143 <term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>
144
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>
149 </varlistentry>
150
798d3a52
ZJS
151 <varlistentry>
152 <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
153
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>
159 </varlistentry>
160
161 <varlistentry>
162 <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
163
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>
168 </varlistentry>
169
170 <varlistentry>
171 <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
172
173 <listitem><para>Sets the system's machine ID. This controls
174 the
175 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
176 file.</para></listitem>
177 </varlistentry>
178
179 <varlistentry>
180 <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
181 <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
182
183 <listitem><para>Sets the password of the system's root user.
184 This creates a
3ba3a79d 185 <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a52
ZJS
186 file. This setting exists in two forms:
187 <option>--root-password=</option> accepts the password to set
a8eaaee7 188 directly on the command line, and
798d3a52 189 <option>--root-password-file=</option> reads it from a file.
a8eaaee7 190 Note that it is not recommended to specify passwords on the
b938cb90 191 command line, as other users might be able to see them simply
798d3a52 192 by invoking
3ba3a79d 193 <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
798d3a52
ZJS
194 </varlistentry>
195
196 <varlistentry>
197 <term><option>--prompt-locale</option></term>
ed457f13 198 <term><option>--prompt-keymap</option></term>
798d3a52
ZJS
199 <term><option>--prompt-timezone</option></term>
200 <term><option>--prompt-hostname</option></term>
201 <term><option>--prompt-root-password</option></term>
202
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>
207 </varlistentry>
208
209 <varlistentry>
210 <term><option>--prompt</option></term>
211
ed457f13 212 <listitem><para>Query the user for locale, keymap, timezone, hostname
798d3a52
ZJS
213 and root password. This is equivalent to specifying
214 <option>--prompt-locale</option>,
ed457f13 215 <option>--prompt-keymap</option>,
798d3a52
ZJS
216 <option>--prompt-timezone</option>,
217 <option>--prompt-hostname</option>,
218 <option>--prompt-root-password</option> in combination.</para>
219 </listitem>
220 </varlistentry>
221
222 <varlistentry>
223 <term><option>--copy-locale</option></term>
ed457f13 224 <term><option>--copy-keymap</option></term>
798d3a52
ZJS
225 <term><option>--copy-timezone</option></term>
226 <term><option>--copy-root-password</option></term>
227
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>
231 </varlistentry>
232
233 <varlistentry>
234 <term><option>--copy</option></term>
235
ed457f13 236 <listitem><para>Copy locale, keymap, time zone and root password from
798d3a52
ZJS
237 the host. This is equivalent to specifying
238 <option>--copy-locale</option>,
ed457f13 239 <option>--copy-keymap</option>,
798d3a52
ZJS
240 <option>--copy-timezone</option>,
241 <option>--copy-root-password</option> in combination.</para>
242 </listitem>
243 </varlistentry>
244
245 <varlistentry>
246 <term><option>--setup-machine-id</option></term>
247
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>
251 </varlistentry>
252
253 <xi:include href="standard-options.xml" xpointer="help" />
254 <xi:include href="standard-options.xml" xpointer="version" />
255 </variablelist>
256
257 </refsect1>
258
259 <refsect1>
260 <title>Exit status</title>
261
262 <para>On success, 0 is returned, a non-zero failure code
263 otherwise.</para>
264 </refsect1>
265
f582cbca
LP
266 <refsect1>
267 <title>Kernel Command Line</title>
268
269 <variablelist class='kernel-commandline-options'>
270 <varlistentry>
271 <term><varname>systemd.firstboot=</varname></term>
272
6b3d3783
ZJS
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
f582cbca
LP
275 initialized yet.</para></listitem>
276 </varlistentry>
277 </variablelist>
278 </refsect1>
279
798d3a52
ZJS
280 <refsect1>
281 <title>See Also</title>
282 <para>
283 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79d 284 <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
ed457f13 285 <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a52
ZJS
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>,
3ba3a79d 289 <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a52 290 <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79d 291 <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52
ZJS
292 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
293 <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
294 </para>
295 </refsect1>
30f10abf
LP
296
297</refentry>