]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/systemd-firstboot.xml
systemd-firstboot: add vconsole keymap support (#7035)
[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<!--
6 This file is part of systemd.
7
8 Copyright 2014 Lennart Poettering
9
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
14
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22-->
23
efd51554 24<refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
798d3a52
ZJS
25 xmlns:xi="http://www.w3.org/2001/XInclude">
26
27 <refentryinfo>
28 <title>systemd-firstboot</title>
29 <productname>systemd</productname>
30
31 <authorgroup>
32 <author>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
37 </author>
38 </authorgroup>
39 </refentryinfo>
40
41 <refmeta>
42 <refentrytitle>systemd-firstboot</refentrytitle>
43 <manvolnum>1</manvolnum>
44 </refmeta>
45
46 <refnamediv>
47 <refname>systemd-firstboot</refname>
48 <refname>systemd-firstboot.service</refname>
49 <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose>
50 </refnamediv>
51
52 <refsynopsisdiv>
53 <cmdsynopsis>
54 <command>systemd-firstboot</command>
55 <arg choice="opt" rep="repeat">OPTIONS</arg>
56 </cmdsynopsis>
57
58 <para><filename>systemd-firstboot.service</filename></para>
59 </refsynopsisdiv>
60
61 <refsect1>
62 <title>Description</title>
63
64 <para><command>systemd-firstboot</command> initializes the most
65 basic system settings interactively on the first boot, or
c954f332
ZJS
66 optionally non-interactively when a system image is created.
67 The service is started if <varname>ConditionFirstBoot=yes</varname>
68 is satisfied. This essentially means that <filename>/etc</filename>
69 is empty, see
70 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
71 for details.</para>
72
73 <para>The following settings may be set up:</para>
798d3a52
ZJS
74
75 <itemizedlist>
76 <listitem><para>The system locale, more specifically the two
77 locale variables <varname>LANG=</varname> and
78 <varname>LC_MESSAGES</varname></para></listitem>
79
ed457f13
TB
80 <listitem><para>The system keyboard map</para></listitem>
81
798d3a52
ZJS
82 <listitem><para>The system time zone</para></listitem>
83
84 <listitem><para>The system host name</para></listitem>
85
86 <listitem><para>The machine ID of the system</para></listitem>
87
88 <listitem><para>The root user's password</para></listitem>
89 </itemizedlist>
90
a8eaaee7
JE
91 <para>Each of the fields may either be queried interactively by
92 users, set non-interactively on the tool's command line, or be
798d3a52
ZJS
93 copied from a host system that is used to set up the system
94 image.</para>
95
b938cb90 96 <para>If a setting is already initialized, it will not be
798d3a52
ZJS
97 overwritten and the user will not be prompted for the
98 setting.</para>
99
100 <para>Note that this tool operates directly on the file system and
101 does not involve any running system services, unlike
3ba3a79d 102 <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52
ZJS
103 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
104 or
105 <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
106 This allows <command>systemd-firstboot</command> to operate on
107 mounted but not booted disk images and in early boot. It is not
108 recommended to use <command>systemd-firstboot</command> on the
109 running system while it is up.</para>
110 </refsect1>
111
112 <refsect1>
113 <title>Options</title>
114
115 <para>The following options are understood:</para>
116
117 <variablelist>
118 <varlistentry>
119 <term><option>--root=<replaceable>root</replaceable></option></term>
120 <listitem><para>Takes a directory path as an argument. All
121 paths will be prefixed with the given alternate
122 <replaceable>root</replaceable> path, including config search
123 paths. This is useful to operate on a system image mounted to
124 the specified directory instead of the host system itself.
125 </para></listitem>
126 </varlistentry>
127
128 <varlistentry>
129 <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
130 <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
131
132 <listitem><para>Sets the system locale, more specifically the
133 <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
134 settings. The argument should be a valid locale identifier,
135 such as <literal>de_DE.UTF-8</literal>. This controls the
3ba3a79d 136 <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a52
ZJS
137 configuration file.</para></listitem>
138 </varlistentry>
139
ed457f13
TB
140 <varlistentry>
141 <term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>
142
143 <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
144 such as <literal>de-latin1</literal>. This controls the <literal>KEYMAP</literal> entry in the
145 <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
146 configuration file.</para></listitem>
147 </varlistentry>
148
798d3a52
ZJS
149 <varlistentry>
150 <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
151
152 <listitem><para>Sets the system time zone. The argument should
153 be a valid time zone identifier, such as
154 <literal>Europe/Berlin</literal>. This controls the
155 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
156 symlink.</para></listitem>
157 </varlistentry>
158
159 <varlistentry>
160 <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
161
162 <listitem><para>Sets the system hostname. The argument should
163 be a host name, compatible with DNS. This controls the
164 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
165 configuration file.</para></listitem>
166 </varlistentry>
167
168 <varlistentry>
169 <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
170
171 <listitem><para>Sets the system's machine ID. This controls
172 the
173 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
174 file.</para></listitem>
175 </varlistentry>
176
177 <varlistentry>
178 <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
179 <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
180
181 <listitem><para>Sets the password of the system's root user.
182 This creates a
3ba3a79d 183 <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
798d3a52
ZJS
184 file. This setting exists in two forms:
185 <option>--root-password=</option> accepts the password to set
a8eaaee7 186 directly on the command line, and
798d3a52 187 <option>--root-password-file=</option> reads it from a file.
a8eaaee7 188 Note that it is not recommended to specify passwords on the
b938cb90 189 command line, as other users might be able to see them simply
798d3a52 190 by invoking
3ba3a79d 191 <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
798d3a52
ZJS
192 </varlistentry>
193
194 <varlistentry>
195 <term><option>--prompt-locale</option></term>
ed457f13 196 <term><option>--prompt-keymap</option></term>
798d3a52
ZJS
197 <term><option>--prompt-timezone</option></term>
198 <term><option>--prompt-hostname</option></term>
199 <term><option>--prompt-root-password</option></term>
200
201 <listitem><para>Prompt the user interactively for a specific
202 basic setting. Note that any explicit configuration settings
203 specified on the command line take precedence, and the user is
204 not prompted for it.</para></listitem>
205 </varlistentry>
206
207 <varlistentry>
208 <term><option>--prompt</option></term>
209
ed457f13 210 <listitem><para>Query the user for locale, keymap, timezone, hostname
798d3a52
ZJS
211 and root password. This is equivalent to specifying
212 <option>--prompt-locale</option>,
ed457f13 213 <option>--prompt-keymap</option>,
798d3a52
ZJS
214 <option>--prompt-timezone</option>,
215 <option>--prompt-hostname</option>,
216 <option>--prompt-root-password</option> in combination.</para>
217 </listitem>
218 </varlistentry>
219
220 <varlistentry>
221 <term><option>--copy-locale</option></term>
ed457f13 222 <term><option>--copy-keymap</option></term>
798d3a52
ZJS
223 <term><option>--copy-timezone</option></term>
224 <term><option>--copy-root-password</option></term>
225
226 <listitem><para>Copy a specific basic setting from the host.
227 This only works in combination with <option>--root=</option>
228 (see above).</para></listitem>
229 </varlistentry>
230
231 <varlistentry>
232 <term><option>--copy</option></term>
233
ed457f13 234 <listitem><para>Copy locale, keymap, time zone and root password from
798d3a52
ZJS
235 the host. This is equivalent to specifying
236 <option>--copy-locale</option>,
ed457f13 237 <option>--copy-keymap</option>,
798d3a52
ZJS
238 <option>--copy-timezone</option>,
239 <option>--copy-root-password</option> in combination.</para>
240 </listitem>
241 </varlistentry>
242
243 <varlistentry>
244 <term><option>--setup-machine-id</option></term>
245
246 <listitem><para>Initialize the system's machine ID to a random
247 ID. This only works in combination with
248 <option>--root=</option>.</para></listitem>
249 </varlistentry>
250
251 <xi:include href="standard-options.xml" xpointer="help" />
252 <xi:include href="standard-options.xml" xpointer="version" />
253 </variablelist>
254
255 </refsect1>
256
257 <refsect1>
258 <title>Exit status</title>
259
260 <para>On success, 0 is returned, a non-zero failure code
261 otherwise.</para>
262 </refsect1>
263
f582cbca
LP
264 <refsect1>
265 <title>Kernel Command Line</title>
266
267 <variablelist class='kernel-commandline-options'>
268 <varlistentry>
269 <term><varname>systemd.firstboot=</varname></term>
270
6b3d3783
ZJS
271 <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
272 won't interactively query the user for basic settings at first boot, even if those settings are not
f582cbca
LP
273 initialized yet.</para></listitem>
274 </varlistentry>
275 </variablelist>
276 </refsect1>
277
798d3a52
ZJS
278 <refsect1>
279 <title>See Also</title>
280 <para>
281 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79d 282 <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
ed457f13 283 <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a52
ZJS
284 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
285 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
286 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
3ba3a79d 287 <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
798d3a52 288 <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
3ba3a79d 289 <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a52
ZJS
290 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
291 <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
292 </para>
293 </refsect1>
30f10abf
LP
294
295</refentry>