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 host name</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 host name, 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
 154         <listitem><para>Sets the password of the system's root user.
 155         This creates a
 156         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 157         file. This setting exists in two forms:
 158         <option>--root-password=</option> accepts the password to set
 159         directly on the command line, and
 160         <option>--root-password-file=</option> reads it from a file.
 161         Note that it is not recommended to specify passwords on the
 162         command line, as other users might be able to see them simply
 163         by invoking
 164         <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><option>--prompt-locale</option></term>
 169         <term><option>--prompt-keymap</option></term>
 170         <term><option>--prompt-timezone</option></term>
 171         <term><option>--prompt-hostname</option></term>
 172         <term><option>--prompt-root-password</option></term>
 173
 174         <listitem><para>Prompt the user interactively for a specific
 175         basic setting. Note that any explicit configuration settings
 176         specified on the command line take precedence, and the user is
 177         not prompted for it.</para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--prompt</option></term>
 182
 183         <listitem><para>Query the user for locale, keymap, timezone, hostname
 184         and root password. This is equivalent to specifying
 185         <option>--prompt-locale</option>,
 186         <option>--prompt-keymap</option>,
 187         <option>--prompt-timezone</option>,
 188         <option>--prompt-hostname</option>,
 189         <option>--prompt-root-password</option> in combination.</para>
 190         </listitem>
 191       </varlistentry>
 192
 193       <varlistentry>
 194         <term><option>--copy-locale</option></term>
 195         <term><option>--copy-keymap</option></term>
 196         <term><option>--copy-timezone</option></term>
 197         <term><option>--copy-root-password</option></term>
 198
 199         <listitem><para>Copy a specific basic setting from the host.
 200         This only works in combination with <option>--root=</option>
 201         (see above).</para></listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><option>--copy</option></term>
 206
 207         <listitem><para>Copy locale, keymap, time zone and root password from
 208         the host. This is equivalent to specifying
 209         <option>--copy-locale</option>,
 210         <option>--copy-keymap</option>,
 211         <option>--copy-timezone</option>,
 212         <option>--copy-root-password</option> in combination.</para>
 213         </listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><option>--setup-machine-id</option></term>
 218
 219         <listitem><para>Initialize the system's machine ID to a random
 220         ID. This only works in combination with
 221         <option>--root=</option>.</para></listitem>
 222       </varlistentry>
 223
 224       <xi:include href="standard-options.xml" xpointer="help" />
 225       <xi:include href="standard-options.xml" xpointer="version" />
 226     </variablelist>
 227
 228   </refsect1>
 229
 230   <refsect1>
 231     <title>Exit status</title>
 232
 233     <para>On success, 0 is returned, a non-zero failure code
 234     otherwise.</para>
 235   </refsect1>
 236
 237   <refsect1>
 238     <title>Kernel Command Line</title>
 239
 240     <variablelist class='kernel-commandline-options'>
 241       <varlistentry>
 242         <term><varname>systemd.firstboot=</varname></term>
 243
 244         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 245         won't interactively query the user for basic settings at first boot, even if those settings are not
 246         initialized yet.</para></listitem>
 247       </varlistentry>
 248     </variablelist>
 249   </refsect1>
 250
 251   <refsect1>
 252     <title>See Also</title>
 253     <para>
 254       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 255       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 256       <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 257       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 258       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 260       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 261       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 262       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 263       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 264       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 265     </para>
 266   </refsect1>
 267
 268 </refentry>