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></listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><option>--root-shell=<replaceable>SHELL</replaceable></option></term>
 210
 211         <listitem><para>Sets the shell of the system's root user. This creates/modifies the
 212         <citerefentry project='die-net'><refentrytitle>passwd</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 213         file.</para>
 214
 215         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><option>--kernel-command-line=<replaceable>CMDLINE</replaceable></option></term>
 220
 221         <listitem><para>Sets the system's kernel command line. This controls the
 222         <filename>/etc/kernel/cmdline</filename> file which is used by
 223         <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 224         </para>
 225
 226         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 227       </varlistentry>
 228
 229       <varlistentry>
 230         <term><option>--prompt-locale</option></term>
 231         <term><option>--prompt-keymap</option></term>
 232         <term><option>--prompt-timezone</option></term>
 233         <term><option>--prompt-hostname</option></term>
 234         <term><option>--prompt-root-password</option></term>
 235         <term><option>--prompt-root-shell</option></term>
 236
 237         <listitem><para>Prompt the user interactively for a specific
 238         basic setting. Note that any explicit configuration settings
 239         specified on the command line take precedence, and the user is
 240         not prompted for it.</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><option>--prompt</option></term>
 245
 246         <listitem><para>Query the user for locale, keymap, timezone, hostname,
 247         root's password, and root's shell. This is equivalent to specifying
 248         <option>--prompt-locale</option>,
 249         <option>--prompt-keymap</option>,
 250         <option>--prompt-timezone</option>,
 251         <option>--prompt-hostname</option>,
 252         <option>--prompt-root-password</option>,
 253         <option>--prompt-root-shell</option> in combination.</para>
 254
 255         <xi:include href="version-info.xml" xpointer="v216"/>
 256         </listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term><option>--copy-locale</option></term>
 261         <term><option>--copy-keymap</option></term>
 262         <term><option>--copy-timezone</option></term>
 263         <term><option>--copy-root-password</option></term>
 264         <term><option>--copy-root-shell</option></term>
 265
 266         <listitem><para>Copy a specific basic setting from the host.
 267         This only works in combination with <option>--root=</option> or <option>--image=</option>.
 268         </para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><option>--copy</option></term>
 273
 274         <listitem><para>Copy locale, keymap, time zone, root password and shell from the host. This is
 275         equivalent to specifying
 276         <option>--copy-locale</option>,
 277         <option>--copy-keymap</option>,
 278         <option>--copy-timezone</option>,
 279         <option>--copy-root-password</option>,
 280         <option>--copy-root-shell</option> in combination.</para>
 281
 282         <xi:include href="version-info.xml" xpointer="v216"/>
 283         </listitem>
 284       </varlistentry>
 285
 286       <varlistentry>
 287         <term><option>--force</option></term>
 288
 289         <listitem><para>Write configuration even if the relevant files already exist. Without this option,
 290         <filename>systemd-firstboot</filename> doesn't modify or replace existing files. Note that when
 291         configuring the root account, even with this option, <filename>systemd-firstboot</filename> only
 292         modifies the entry of the <literal>root</literal> user, leaving other entries in
 293         <filename>/etc/passwd</filename> and <filename>/etc/shadow</filename> intact.</para>
 294
 295         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 296       </varlistentry>
 297
 298       <varlistentry>
 299         <term><option>--reset</option></term>
 300
 301         <listitem><para>If specified, all existing files that are configured by
 302         <command>systemd-firstboot</command> are removed. Note that the files are removed regardless of
 303         whether they'll be configured with a new value or not. This operation ensures that the next boot of
 304         the image will be considered a first boot, and <command>systemd-firstboot</command> will prompt again
 305         to configure each of the removed files.</para>
 306
 307         <xi:include href="version-info.xml" xpointer="v254"/></listitem>
 308       </varlistentry>
 309
 310       <varlistentry>
 311         <term><option>--delete-root-password</option></term>
 312
 313         <listitem><para>Removes the password of the system's root user, enabling login as root without a
 314         password unless the root account is locked. Note that this is extremely insecure and hence this
 315         option should not be used lightly.</para>
 316
 317         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 318       </varlistentry>
 319
 320       <varlistentry>
 321         <term><option>--welcome=</option></term>
 322
 323         <listitem><para>Takes a boolean argument. By default when prompting the user for configuration
 324         options a brief welcome text is shown before the first question is asked. Pass false to this option
 325         to turn off the welcome text.</para>
 326
 327         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 328       </varlistentry>
 329
 330       <xi:include href="standard-options.xml" xpointer="help" />
 331       <xi:include href="standard-options.xml" xpointer="version" />
 332     </variablelist>
 333   </refsect1>
 334
 335   <refsect1>
 336     <title>Credentials</title>
 337
 338     <para><command>systemd-firstboot</command> supports the service credentials logic as implemented by
 339     <varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>
 340     (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
 341     details). The following credentials are used when passed in:</para>
 342
 343     <variablelist class='system-credentials'>
 344       <varlistentry>
 345         <term><varname>passwd.hashed-password.root</varname></term>
 346         <term><varname>passwd.plaintext-password.root</varname></term>
 347
 348         <listitem><para>A hashed or plaintext version of the root password to use, in place of prompting the
 349         user. These credentials are equivalent to the same ones defined for the
 350         <citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 351         service.</para>
 352
 353         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 354       </varlistentry>
 355
 356       <varlistentry>
 357         <term><varname>passwd.shell.root</varname></term>
 358
 359         <listitem><para>Specifies the shell binary to use for the specified account.
 360         Equivalent to the credential of the same name defined for the
 361         <citerefentry><refentrytitle>systemd-sysusers.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 362         service.</para>
 363
 364         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 365       </varlistentry>
 366
 367       <varlistentry>
 368         <term><varname>firstboot.locale</varname></term>
 369         <term><varname>firstboot.locale-messages</varname></term>
 370
 371         <listitem><para>These credentials specify the locale settings to set during first boot, in place of
 372         prompting the user.</para>
 373
 374         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><varname>firstboot.keymap</varname></term>
 379
 380         <listitem><para>This credential specifies the keyboard setting to set during first boot, in place of
 381         prompting the user.</para>
 382
 383         <para>Note the relationship to the <varname>vconsole.keymap</varname> credential understood by
 384         <citerefentry><refentrytitle>systemd-vconsole-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>:
 385         both ultimately affect the same setting, but <varname>firstboot.keymap</varname> is written into
 386         <filename>/etc/vconsole.conf</filename> on first boot (if not already configured), and then read from
 387         there by <command>systemd-vconsole-setup</command>, while <varname>vconsole.keymap</varname> is read
 388         on every boot, and is not persisted to disk (but any configuration in
 389         <filename>vconsole.conf</filename> will take precedence if present).</para>
 390
 391         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 392       </varlistentry>
 393
 394       <varlistentry>
 395         <term><varname>firstboot.timezone</varname></term>
 396
 397         <listitem><para>This credential specifies the system timezone setting to set during first boot, in
 398         place of prompting the user.</para>
 399
 400         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 401       </varlistentry>
 402     </variablelist>
 403
 404     <para>Note that by default the <filename>systemd-firstboot.service</filename> unit file is set up to
 405     inherit the listed credentials
 406     from the service manager. Thus, when invoking a container with an unpopulated <filename>/etc/</filename>
 407     for the first time it is possible to configure the root user's password to be <literal>systemd</literal>
 408     like this:</para>
 409
 410     <para><programlisting># systemd-nspawn --image=… --set-credential=firstboot.locale:de_DE.UTF-8 …</programlisting></para>
 411
 412     <para>Note that these credentials are only read and applied during the first boot process. Once they are
 413     applied they remain applied for subsequent boots, and the credentials are not considered anymore.</para>
 414   </refsect1>
 415
 416   <refsect1>
 417     <title>Exit status</title>
 418
 419     <para>On success, 0 is returned, a non-zero failure code
 420     otherwise.</para>
 421   </refsect1>
 422
 423   <refsect1>
 424     <title>Kernel Command Line</title>
 425
 426     <variablelist class='kernel-commandline-options'>
 427       <varlistentry>
 428         <term><varname>systemd.firstboot=</varname></term>
 429
 430         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 431         won't interactively query the user for basic settings at first boot, even if those settings are not
 432         initialized yet.</para>
 433
 434         <xi:include href="version-info.xml" xpointer="v233"/></listitem>
 435       </varlistentry>
 436     </variablelist>
 437   </refsect1>
 438
 439   <refsect1>
 440     <title>See Also</title>
 441     <para>
 442       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 443       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 444       <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 445       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 446       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 447       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 448       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 449       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 450       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 451       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 452       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 453     </para>
 454   </refsect1>
 455
 456 </refentry>