man/systemd-firstboot.xml

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