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 This file is part of systemd.
8 Copyright 2014 Lennart Poettering
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.
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.
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/>.
24 <refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>systemd-firstboot</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
42 <refentrytitle>systemd-firstboot</refentrytitle>
43 <manvolnum>1</manvolnum>
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>
54 <command>systemd-firstboot</command>
55 <arg choice="opt" rep="repeat">OPTIONS</arg>
58 <para><filename>systemd-firstboot.service</filename></para>
62 <title>Description</title>
64 <para><command>systemd-firstboot</command> initializes the most
65 basic system settings interactively on the first boot, or
66 optionally non-interactively when a system image is created. The
67 following settings may be set up:</para>
70 <listitem><para>The system locale, more specifically the two
71 locale variables <varname>LANG=</varname> and
72 <varname>LC_MESSAGES</varname></para></listitem>
74 <listitem><para>The system time zone</para></listitem>
76 <listitem><para>The system host name</para></listitem>
78 <listitem><para>The machine ID of the system</para></listitem>
80 <listitem><para>The root user's password</para></listitem>
83 <para>Each of the fields may either be queried interactively from
84 the users, set non-interactively on the tool's command line, or be
85 copied from a host system that is used to set up the system
88 <para>If a setting is already initialized it will not be
89 overwritten and the user will not be prompted for the
92 <para>Note that this tool operates directly on the file system and
93 does not involve any running system services, unlike
94 <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
95 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
97 <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
98 This allows <command>systemd-firstboot</command> to operate on
99 mounted but not booted disk images and in early boot. It is not
100 recommended to use <command>systemd-firstboot</command> on the
101 running system while it is up.</para>
105 <title>Options</title>
107 <para>The following options are understood:</para>
111 <term><option>--root=<replaceable>root</replaceable></option></term>
112 <listitem><para>Takes a directory path as an argument. All
113 paths will be prefixed with the given alternate
114 <replaceable>root</replaceable> path, including config search
115 paths. This is useful to operate on a system image mounted to
116 the specified directory instead of the host system itself.
121 <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
122 <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
124 <listitem><para>Sets the system locale, more specifically the
125 <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
126 settings. The argument should be a valid locale identifier,
127 such as <literal>de_DE.UTF-8</literal>. This controls the
128 <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
129 configuration file.</para></listitem>
133 <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
135 <listitem><para>Sets the system time zone. The argument should
136 be a valid time zone identifier, such as
137 <literal>Europe/Berlin</literal>. This controls the
138 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
139 symlink.</para></listitem>
143 <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
145 <listitem><para>Sets the system hostname. The argument should
146 be a host name, compatible with DNS. This controls the
147 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
148 configuration file.</para></listitem>
152 <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
154 <listitem><para>Sets the system's machine ID. This controls
156 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
157 file.</para></listitem>
161 <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
162 <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
164 <listitem><para>Sets the password of the system's root user.
166 <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
167 file. This setting exists in two forms:
168 <option>--root-password=</option> accepts the password to set
169 directly on the command line,
170 <option>--root-password-file=</option> reads it from a file.
171 Note that it is not recommended specifying passwords on the
172 command line as other users might be able to see them simply
174 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
178 <term><option>--prompt-locale</option></term>
179 <term><option>--prompt-timezone</option></term>
180 <term><option>--prompt-hostname</option></term>
181 <term><option>--prompt-root-password</option></term>
183 <listitem><para>Prompt the user interactively for a specific
184 basic setting. Note that any explicit configuration settings
185 specified on the command line take precedence, and the user is
186 not prompted for it.</para></listitem>
190 <term><option>--prompt</option></term>
192 <listitem><para>Query the user for locale, timezone, hostname
193 and root password. This is equivalent to specifying
194 <option>--prompt-locale</option>,
195 <option>--prompt-timezone</option>,
196 <option>--prompt-hostname</option>,
197 <option>--prompt-root-password</option> in combination.</para>
202 <term><option>--copy-locale</option></term>
203 <term><option>--copy-timezone</option></term>
204 <term><option>--copy-root-password</option></term>
206 <listitem><para>Copy a specific basic setting from the host.
207 This only works in combination with <option>--root=</option>
208 (see above).</para></listitem>
212 <term><option>--copy</option></term>
214 <listitem><para>Copy locale, time zone and root password from
215 the host. This is equivalent to specifying
216 <option>--copy-locale</option>,
217 <option>--copy-timezone</option>,
218 <option>--copy-root-password</option> in combination.</para>
223 <term><option>--setup-machine-id</option></term>
225 <listitem><para>Initialize the system's machine ID to a random
226 ID. This only works in combination with
227 <option>--root=</option>.</para></listitem>
230 <xi:include href="standard-options.xml" xpointer="help" />
231 <xi:include href="standard-options.xml" xpointer="version" />
237 <title>Exit status</title>
239 <para>On success, 0 is returned, a non-zero failure code
244 <title>See Also</title>
246 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
247 <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
248 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
249 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
250 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
251 <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
253 <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
254 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
255 <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>