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-or-later -->
   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 basic system settings interactively during the
  38     first boot, or non-interactively on an offline system image. The service is started during boot if
  39     <varname>ConditionFirstBoot=yes</varname> is met, which essentially means that <filename>/etc/</filename>
  40     is empty, see
  41     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
  42     details.</para>
  43
  44     <para>The following settings may be configured:</para>
  45
  46     <itemizedlist>
  47       <listitem><para>The machine ID of the system</para></listitem>
  48
  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 kernel command line used when installing kernel images</para></listitem>
  60
  61       <listitem><para>The root user's password and shell</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 after it has been set 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>
  99
 100         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term><option>--image=<replaceable>path</replaceable></option></term>
 105         <listitem><para>Takes a path to a disk image file or block device node. If specified all operations
 106         are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
 107         but operates on file systems stored in disk images or block devices. The disk image should either
 108         contain just a file system or a set of file systems within a GPT partition table, following the
 109         <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
 110         Specification</ulink>. For further information on supported disk images, see
 111         <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 112         switch of the same name.</para>
 113
 114         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
 119         <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
 120
 121         <listitem><para>Sets the system locale, more specifically the
 122         <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
 123         settings. The argument should be a valid locale identifier,
 124         such as <literal>de_DE.UTF-8</literal>. This controls the
 125         <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 126         configuration file.</para>
 127
 128         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 129       </varlistentry>
 130
 131       <varlistentry>
 132         <term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>
 133
 134         <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
 135         such as <literal>de-latin1</literal>. This controls the <literal>KEYMAP</literal> entry in the
 136         <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 137         configuration file.</para>
 138
 139         <xi:include href="version-info.xml" xpointer="v236"/></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
 144
 145         <listitem><para>Sets the system time zone. The argument should
 146         be a valid time zone identifier, such as
 147         <literal>Europe/Berlin</literal>. This controls the
 148         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 149         symlink.</para>
 150
 151         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
 156
 157         <listitem><para>Sets the system hostname. The argument should
 158         be a hostname, compatible with DNS. This controls the
 159         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 160         configuration file.</para>
 161
 162         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 163       </varlistentry>
 164
 165       <varlistentry>
 166         <term><option>--setup-machine-id</option></term>
 167
 168         <listitem><para>Initialize the system's machine ID to a random ID. This controls the
 169         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> file.
 170         </para>
 171
 172         <para>This option only works in combination with <option>--root=</option> or
 173         <option>--image=</option>. On a running system, <filename>machine-id</filename> is written by the
 174         manager with help from
 175         <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 176         </para>
 177
 178         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
 183
 184         <listitem><para>Set the system's machine ID to the specified value. The same restrictions apply
 185         as to <option>--setup-machine-id</option>.</para>
 186
 187         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
 192         <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
 193         <term><option>--root-password-hashed=<replaceable>HASHED_PASSWORD</replaceable></option></term>
 194
 195         <listitem><para>Sets the password of the system's root user. This creates/modifies the
 196         <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
 197         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 198         files. This setting exists in three forms: <option>--root-password=</option> accepts the password to
 199         set directly on the command line, <option>--root-password-file=</option> reads it from a file and
 200         <option>--root-password-hashed=</option> accepts an already hashed password on the command line. See
 201         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 202         for more information on the format of the hashed password. Note that it is not recommended to specify
 203         plaintext passwords on the command line, as other users might be able to see them simply by invoking
 204         <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 205         </para>
 206
 207         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>--root-shell=<replaceable>SHELL</replaceable></option></term>
 212
 213         <listitem><para>Sets the shell of the system's root user. This creates/modifies the
 214         <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 215         file.</para>
 216
 217         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term><option>--kernel-command-line=<replaceable>CMDLINE</replaceable></option></term>
 222
 223         <listitem><para>Sets the system's kernel command line. This controls the
 224         <filename>/etc/kernel/cmdline</filename> file which is used by
 225         <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 226         </para>
 227
 228         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><option>--prompt-locale</option></term>
 233         <term><option>--prompt-keymap</option></term>
 234         <term><option>--prompt-timezone</option></term>
 235         <term><option>--prompt-hostname</option></term>
 236         <term><option>--prompt-root-password</option></term>
 237         <term><option>--prompt-root-shell</option></term>
 238
 239         <listitem><para>Prompt the user interactively for a specific
 240         basic setting. Note that any explicit configuration settings
 241         specified on the command line take precedence, and the user is
 242         not prompted for it.</para>
 243
 244         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><option>--prompt</option></term>
 249
 250         <listitem><para>Query the user for locale, keymap, timezone, hostname,
 251         root's password, and root's shell. This is equivalent to specifying
 252         <option>--prompt-locale</option>,
 253         <option>--prompt-keymap</option>,
 254         <option>--prompt-timezone</option>,
 255         <option>--prompt-hostname</option>,
 256         <option>--prompt-root-password</option>,
 257         <option>--prompt-root-shell</option> in combination.</para>
 258
 259         <xi:include href="version-info.xml" xpointer="v216"/>
 260         </listitem>
 261       </varlistentry>
 262
 263       <varlistentry>
 264         <term><option>--copy-locale</option></term>
 265         <term><option>--copy-keymap</option></term>
 266         <term><option>--copy-timezone</option></term>
 267         <term><option>--copy-root-password</option></term>
 268         <term><option>--copy-root-shell</option></term>
 269
 270         <listitem><para>Copy a specific basic setting from the host.
 271         This only works in combination with <option>--root=</option> or <option>--image=</option>.
 272         </para>
 273
 274         <xi:include href="version-info.xml" xpointer="v216"/></listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term><option>--copy</option></term>
 279
 280         <listitem><para>Copy locale, keymap, time zone, root password and shell from the host. This is
 281         equivalent to specifying
 282         <option>--copy-locale</option>,
 283         <option>--copy-keymap</option>,
 284         <option>--copy-timezone</option>,
 285         <option>--copy-root-password</option>,
 286         <option>--copy-root-shell</option> in combination.</para>
 287
 288         <xi:include href="version-info.xml" xpointer="v216"/>
 289         </listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><option>--force</option></term>
 294
 295         <listitem><para>Write configuration even if the relevant files already exist. Without this option,
 296         <filename>systemd-firstboot</filename> doesn't modify or replace existing files. Note that when
 297         configuring the root account, even with this option, <filename>systemd-firstboot</filename> only
 298         modifies the entry of the <literal>root</literal> user, leaving other entries in
 299         <filename>/etc/passwd</filename> and <filename>/etc/shadow</filename> intact.</para>
 300
 301         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term><option>--reset</option></term>
 306
 307         <listitem><para>If specified, all existing files that are configured by
 308         <command>systemd-firstboot</command> are removed. Note that the files are removed regardless of
 309         whether they'll be configured with a new value or not. This operation ensures that the next boot of
 310         the image will be considered a first boot, and <command>systemd-firstboot</command> will prompt again
 311         to configure each of the removed files.</para>
 312
 313         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 314       </varlistentry>
 315
 316       <varlistentry>
 317         <term><option>--delete-root-password</option></term>
 318
 319         <listitem><para>Removes the password of the system's root user, enabling login as root without a
 320         password unless the root account is locked. Note that this is extremely insecure and hence this
 321         option should not be used lightly.</para>
 322
 323         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 324       </varlistentry>
 325
 326       <varlistentry>
 327         <term><option>--welcome=</option></term>
 328
 329         <listitem><para>Takes a boolean argument. By default when prompting the user for configuration
 330         options a brief welcome text is shown before the first question is asked. Pass false to this option
 331         to turn off the welcome text.</para>
 332
 333         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 334       </varlistentry>
 335
 336       <xi:include href="standard-options.xml" xpointer="help" />
 337       <xi:include href="standard-options.xml" xpointer="version" />
 338     </variablelist>
 339   </refsect1>
 340
 341   <refsect1>
 342     <title>Credentials</title>
 343
 344     <para><command>systemd-firstboot</command> supports the service credentials logic as implemented by
 345     <varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>
 346     (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 347     details). The following credentials are used when passed in:</para>
 348
 349     <variablelist class='system-credentials'>
 350       <varlistentry>
 351         <term><varname>passwd.hashed-password.root</varname></term>
 352         <term><varname>passwd.plaintext-password.root</varname></term>
 353
 354         <listitem><para>A hashed or plaintext version of the root password to use, in place of prompting the
 355         user. These credentials are equivalent to the same ones defined for the
 356         <citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 357         service.</para>
 358
 359         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 360       </varlistentry>
 361
 362       <varlistentry>
 363         <term><varname>passwd.shell.root</varname></term>
 364
 365         <listitem><para>Specifies the shell binary to use for the specified account.
 366         Equivalent to the credential of the same name defined for the
 367         <citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 368         service.</para>
 369
 370         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 371       </varlistentry>
 372
 373       <varlistentry>
 374         <term><varname>firstboot.locale</varname></term>
 375         <term><varname>firstboot.locale-messages</varname></term>
 376
 377         <listitem><para>These credentials specify the locale settings to set during first boot, in place of
 378         prompting the user.</para>
 379
 380         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 381       </varlistentry>
 382
 383       <varlistentry>
 384         <term><varname>firstboot.keymap</varname></term>
 385
 386         <listitem><para>This credential specifies the keyboard setting to set during first boot, in place of
 387         prompting the user.</para>
 388
 389         <para>Note the relationship to the <varname>vconsole.keymap</varname> credential understood by
 390         <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
 391         both ultimately affect the same setting, but <varname>firstboot.keymap</varname> is written into
 392         <filename>/etc/vconsole.conf</filename> on first boot (if not already configured), and then read from
 393         there by <command>systemd-vconsole-setup</command>, while <varname>vconsole.keymap</varname> is read
 394         on every boot, and is not persisted to disk (but any configuration in
 395         <filename>vconsole.conf</filename> will take precedence if present).</para>
 396
 397         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 398       </varlistentry>
 399
 400       <varlistentry>
 401         <term><varname>firstboot.timezone</varname></term>
 402
 403         <listitem><para>This credential specifies the system timezone setting to set during first boot, in
 404         place of prompting the user.</para>
 405
 406         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 407       </varlistentry>
 408     </variablelist>
 409
 410     <para>Note that by default the <filename>systemd-firstboot.service</filename> unit file is set up to
 411     inherit the listed credentials
 412     from the service manager. Thus, when invoking a container with an unpopulated <filename>/etc/</filename>
 413     for the first time it is possible to configure the root user's password to be <literal>systemd</literal>
 414     like this:</para>
 415
 416     <para><programlisting># systemd-nspawn --image=… --set-credential=firstboot.locale:de_DE.UTF-8 …</programlisting></para>
 417
 418     <para>Note that these credentials are only read and applied during the first boot process. Once they are
 419     applied they remain applied for subsequent boots, and the credentials are not considered anymore.</para>
 420   </refsect1>
 421
 422   <refsect1>
 423     <title>Exit status</title>
 424
 425     <para>On success, 0 is returned, a non-zero failure code
 426     otherwise.</para>
 427   </refsect1>
 428
 429   <refsect1>
 430     <title>Kernel Command Line</title>
 431
 432     <variablelist class='kernel-commandline-options'>
 433       <varlistentry>
 434         <term><varname>systemd.firstboot=</varname></term>
 435
 436         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 437         won't interactively query the user for basic settings at first boot, even if those settings are not
 438         initialized yet.</para>
 439
 440         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 441       </varlistentry>
 442     </variablelist>
 443   </refsect1>
 444
 445   <refsect1>
 446     <title>See Also</title>
 447     <para>
 448       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 449       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 450       <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 451       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 452       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 453       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 454       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 455       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 456       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 457       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 458       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 459     </para>
 460   </refsect1>
 461
 462 </refentry>