chiark / gitweb /
util: make http url validity checks more generic, and move them to util.c
[elogind.git] / man / systemd-firstboot.xml
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">
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
24 <refentry id="systemd-firstboot"
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
65                 the most basic system settings interactively on the
66                 first boot, or optionally non-interactively when a
67                 system image is created. The following settings may be
68                 set up:</para>
69
70                 <itemizedlist>
71                         <listitem><para>The system locale, more
72                         specifically the two locale variables
73                         <varname>LANG=</varname> and
74                         <varname>LC_MESSAGES</varname></para></listitem>
75
76                         <listitem><para>The system time zone</para></listitem>
77
78                         <listitem><para>The system host name</para></listitem>
79
80                         <listitem><para>The machine ID of the system</para></listitem>
81
82                         <listitem><para>The root user's password</para></listitem>
83                 </itemizedlist>
84
85                 <para>Each of the fields may either be queried
86                 interactively from the users, set non-interactively on
87                 the tool's command line, or be copied from a host
88                 system that is used to set up the system image.</para>
89
90                 <para>If a setting is already initialized it will not
91                 be overwritten and the user will not be prompted for
92                 the setting.</para>
93
94                 <para>Note that this tool operates directly on the
95                 file system and does not involve any running system
96                 services, unlike
97                 <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
98                 <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
99                 or
100                 <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
101                 allows <command>systemd-firstboot</command> to operate
102                 on mounted but not booted disk images and in early
103                 boot. It is not recommended to use
104                 <command>systemd-firstboot</command> on the running
105                 system while it is up.</para>
106         </refsect1>
107
108         <refsect1>
109                 <title>Options</title>
110
111                 <para>The following options are understood:</para>
112
113                 <variablelist>
114                         <varlistentry>
115                                 <term><option>--root=<replaceable>root</replaceable></option></term>
116                                 <listitem><para>Takes a directory path
117                                 as an argument. All paths will be
118                                 prefixed with the given alternate
119                                 <replaceable>root</replaceable> path,
120                                 including config search paths. This is
121                                 useful to operate on a system image
122                                 mounted to the specified directory
123                                 instead of the host system itself.
124                                 </para></listitem>
125                         </varlistentry>
126
127                         <varlistentry>
128                                 <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
129                                 <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
130
131                                 <listitem><para>Sets the system
132                                 locale, more specifically the
133                                 <varname>LANG=</varname> and
134                                 <varname>LC_MESSAGES</varname>
135                                 settings. The argument should be a
136                                 valid locale identifier, such as
137                                 <literal>de_DE.UTF-8</literal>. This
138                                 controls the
139                                 <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
140                                 configuration file.</para></listitem>
141                         </varlistentry>
142
143                         <varlistentry>
144                                 <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
145
146                                 <listitem><para>Sets the system time
147                                 zone. The argument should be a valid
148                                 time zone identifier, such as
149                                 <literal>Europe/Berlin</literal>. This
150                                 controls the
151                                 <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
152                                 symlink.</para></listitem>
153                         </varlistentry>
154
155                         <varlistentry>
156                                 <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
157
158                                 <listitem><para>Sets the system
159                                 hostname. The argument should be a
160                                 host name, compatible with DNS. This
161                                 controls the
162                                 <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
163                                 configuration file.</para></listitem>
164                         </varlistentry>
165
166                         <varlistentry>
167                                 <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
168
169                                 <listitem><para>Sets the system's machine ID. This
170                                 controls the
171                                 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
172                                 file.</para></listitem>
173                         </varlistentry>
174
175                         <varlistentry>
176                                 <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
177                                 <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
178
179                                 <listitem><para>Sets the password of
180                                 the system's root user. This creates a
181                                 <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
182                                 file. This setting exists in two
183                                 forms:
184                                 <option>--root-password=</option>
185                                 accepts the password to set directly
186                                 on the command line,
187                                 <option>--root-password-file=</option>
188                                 reads it from a file. Note that
189                                 it is not recommended specifying
190                                 passwords on the command line as other
191                                 users might be able to see them
192                                 simply by invoking
193                                 <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
194                         </varlistentry>
195
196                         <varlistentry>
197                                 <term><option>--prompt-locale</option></term>
198                                 <term><option>--prompt-timezone</option></term>
199                                 <term><option>--prompt-hostname</option></term>
200                                 <term><option>--prompt-root-password</option></term>
201
202                                 <para>Prompt the user interactively
203                                 for a specific basic setting. Note
204                                 that any explicit configuration
205                                 settings specified on the command line
206                                 take precedence, and the user is not
207                                 prompted for it.</para>
208                         </varlistentry>
209
210                         <varlistentry>
211                                 <term><option>--prompt</option></term>
212
213                                 <para>Query the user for locale,
214                                 timezone, hostname and root
215                                 password. This is equivalent to
216                                 specifying
217                                 <option>--prompt-locale</option>,
218                                 <option>--prompt-timezone</option>,
219                                 <option>--prompt-hostname</option>,
220                                 <option>--prompt-root-password</option>
221                                 in combination.</para>
222                         </varlistentry>
223
224                         <varlistentry>
225                                 <term><option>--copy-locale</option></term>
226                                 <term><option>--copy-timezone</option></term>
227                                 <term><option>--copy-root-password</option></term>
228
229                                 <para>Copy a specific basic setting
230                                 from the host. This only works in
231                                 combination with
232                                 <option>--root=</option> (see
233                                 above).</para>
234                         </varlistentry>
235
236                         <varlistentry>
237                                 <term><option>--copy</option></term>
238
239                                 <para>Copy locale, time zone and root
240                                 password from the host. This is
241                                 equivalent to specifying
242                                 <option>--copy-locale</option>,
243                                 <option>--copy-timezone</option>,
244                                 <option>--copy-root-password</option>
245                                 in combination.</para>
246                         </varlistentry>
247
248                         <varlistentry>
249                                 <term><option>--setup-machine-id</option></term>
250
251                                 <para>Initialize the system's machine
252                                 ID to a random ID. This only works in
253                                 combination with
254                                 <option>--root=</option>.</para>
255                         </varlistentry>
256
257                         <xi:include href="standard-options.xml" xpointer="help" />
258                         <xi:include href="standard-options.xml" xpointer="version" />
259                 </variablelist>
260
261         </refsect1>
262
263         <refsect1>
264                 <title>Exit status</title>
265
266                 <para>On success, 0 is returned, a non-zero failure
267                 code otherwise.</para>
268         </refsect1>
269
270         <refsect1>
271                 <title>See Also</title>
272                 <para>
273                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
274                         <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
275                         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
276                         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
277                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
278                         <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
279                         <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
280                         <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
281                         <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
282                         <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
283                 </para>
284         </refsect1>
285
286 </refentry>