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