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>--image=<replaceable>path</replaceable></option></term>
 103         <listitem><para>Takes a path to a disk image file or block device node. If specified all operations
 104         are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
 105         but operates on file systems stored in disk images or block devices. The disk image should either
 106         contain just a file system or a set of file systems within a GPT partition table, following the
 107         <ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
 108         Specification</ulink>. For further information on supported disk images, see
 109         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 110         switch of the same name.</para></listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
 115         <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
 116
 117         <listitem><para>Sets the system locale, more specifically the
 118         <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
 119         settings. The argument should be a valid locale identifier,
 120         such as <literal>de_DE.UTF-8</literal>. This controls the
 121         <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 122         configuration file.</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>
 127
 128         <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
 129         such as <literal>de-latin1</literal>. This controls the <literal>KEYMAP</literal> entry in the
 130         <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 131         configuration file.</para></listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
 136
 137         <listitem><para>Sets the system time zone. The argument should
 138         be a valid time zone identifier, such as
 139         <literal>Europe/Berlin</literal>. This controls the
 140         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 141         symlink.</para></listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
 146
 147         <listitem><para>Sets the system hostname. The argument should
 148         be a hostname, compatible with DNS. This controls the
 149         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 150         configuration file.</para></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
 155
 156         <listitem><para>Sets the system's machine ID. This controls
 157         the
 158         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 159         file.</para></listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
 164         <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
 165         <term><option>--root-password-hashed=<replaceable>HASHED_PASSWORD</replaceable></option></term>
 166
 167         <listitem><para>Sets the password of the system's root user. This creates/modifies the
 168         <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
 169         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 170         files. This setting exists in three forms: <option>--root-password=</option> accepts the password to
 171         set directly on the command line, <option>--root-password-file=</option> reads it from a file and
 172         <option>--root-password-hashed=</option> accepts an already hashed password on the command line. See
 173         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 174         for more information on the format of the hashed password. Note that it is not recommended to specify
 175         plaintext passwords on the command line, as other users might be able to see them simply by invoking
 176         <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 177         </para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--root-shell=<replaceable>SHELL</replaceable></option></term>
 182
 183         <listitem><para>Sets the shell of the system's root user. This creates/modifies the
 184         <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 185         file.</para></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term><option>--kernel-command-line=<replaceable>CMDLINE</replaceable></option></term>
 190
 191         <listitem><para>Sets the system's kernel command line. This controls the
 192         <filename>/etc/kernel/cmdline</filename> file which is used by
 193         <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 194         </para></listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><option>--prompt-locale</option></term>
 199         <term><option>--prompt-keymap</option></term>
 200         <term><option>--prompt-timezone</option></term>
 201         <term><option>--prompt-hostname</option></term>
 202         <term><option>--prompt-root-password</option></term>
 203         <term><option>--prompt-root-shell</option></term>
 204
 205         <listitem><para>Prompt the user interactively for a specific
 206         basic setting. Note that any explicit configuration settings
 207         specified on the command line take precedence, and the user is
 208         not prompted for it.</para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><option>--prompt</option></term>
 213
 214         <listitem><para>Query the user for locale, keymap, timezone, hostname
 215         and root password. This is equivalent to specifying
 216         <option>--prompt-locale</option>,
 217         <option>--prompt-keymap</option>,
 218         <option>--prompt-timezone</option>,
 219         <option>--prompt-hostname</option>,
 220         <option>--prompt-root-password</option>,
 221         <option>--prompt-root-shell</option> in combination.</para>
 222         </listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><option>--copy-locale</option></term>
 227         <term><option>--copy-keymap</option></term>
 228         <term><option>--copy-timezone</option></term>
 229         <term><option>--copy-root-password</option></term>
 230         <term><option>--copy-root-shell</option></term>
 231
 232         <listitem><para>Copy a specific basic setting from the host.
 233         This only works in combination with <option>--root=</option>
 234         (see above).</para></listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><option>--copy</option></term>
 239
 240         <listitem><para>Copy locale, keymap, time zone and root password from
 241         the host. This is equivalent to specifying
 242         <option>--copy-locale</option>,
 243         <option>--copy-keymap</option>,
 244         <option>--copy-timezone</option>,
 245         <option>--copy-root-password</option>,
 246         <option>--copy-root-shell</option> in combination.</para>
 247         </listitem>
 248       </varlistentry>
 249
 250       <varlistentry>
 251         <term><option>--setup-machine-id</option></term>
 252
 253         <listitem><para>Initialize the system's machine ID to a random
 254         ID. This only works in combination with
 255         <option>--root=</option>.</para></listitem>
 256       </varlistentry>
 257
 258       <varlistentry>
 259         <term><option>--force</option></term>
 260
 261         <listitem><para>systemd-firstboot doesn't modify existing files unless <option>--force</option>
 262         is specified. For modifications to <filename>/etc/passwd</filename> and
 263         <filename>/etc/shadow</filename>, systemd-firstboot only modifies the entry of the
 264         <literal>root</literal> user instead of overwriting the entire file.</para></listitem>
 265       </varlistentry>
 266
 267       <varlistentry>
 268         <term><option>--delete-root-password</option></term>
 269
 270         <listitem><para>Removes the password of the system's root user, enabling login as root without a
 271         password unless the root account is locked. Note that this is extremely insecure and hence this
 272         option should not be used lightly.</para></listitem>
 273       </varlistentry>
 274
 275       <varlistentry>
 276         <term><option>--welcome=</option></term>
 277
 278         <listitem><para>Takes a boolean argument. By default when prompting the user for configuration
 279         options a brief welcome text is shown before the first question is asked. Pass false to this option
 280         to turn off the welcome text.</para></listitem>
 281       </varlistentry>
 282
 283       <xi:include href="standard-options.xml" xpointer="help" />
 284       <xi:include href="standard-options.xml" xpointer="version" />
 285     </variablelist>
 286
 287   </refsect1>
 288
 289   <refsect1>
 290     <title>Exit status</title>
 291
 292     <para>On success, 0 is returned, a non-zero failure code
 293     otherwise.</para>
 294   </refsect1>
 295
 296   <refsect1>
 297     <title>Kernel Command Line</title>
 298
 299     <variablelist class='kernel-commandline-options'>
 300       <varlistentry>
 301         <term><varname>systemd.firstboot=</varname></term>
 302
 303         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 304         won't interactively query the user for basic settings at first boot, even if those settings are not
 305         initialized yet.</para></listitem>
 306       </varlistentry>
 307     </variablelist>
 308   </refsect1>
 309
 310   <refsect1>
 311     <title>See Also</title>
 312     <para>
 313       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 314       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 315       <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 316       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 317       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 318       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 319       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 320       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 321       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 322       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 323       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 324     </para>
 325   </refsect1>
 326
 327 </refentry>