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>