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 a
 168         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 169         file. This setting exists in three forms: <option>--root-password=</option> accepts the password to
 170         set directly on the command line, <option>--root-password-file=</option> reads it from a file and
 171         <option>--root-password-hashed=</option> accepts an already hashed password on the command line. See
 172         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 173         for more information on the format of the hashed password. Note that it is not recommended to specify
 174         plaintext passwords on the command line, as other users might be able to see them simply by invoking
 175         <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 176         </para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><option>--kernel-command-line=<replaceable>CMDLINE</replaceable></option></term>
 181
 182         <listitem><para>Sets the system's kernel command line. This controls the
 183         <filename>/etc/kernel/cmdline</filename> file which is used by
 184         <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 185         </para></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term><option>--prompt-locale</option></term>
 190         <term><option>--prompt-keymap</option></term>
 191         <term><option>--prompt-timezone</option></term>
 192         <term><option>--prompt-hostname</option></term>
 193         <term><option>--prompt-root-password</option></term>
 194
 195         <listitem><para>Prompt the user interactively for a specific
 196         basic setting. Note that any explicit configuration settings
 197         specified on the command line take precedence, and the user is
 198         not prompted for it.</para></listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>--prompt</option></term>
 203
 204         <listitem><para>Query the user for locale, keymap, timezone, hostname
 205         and root password. This is equivalent to specifying
 206         <option>--prompt-locale</option>,
 207         <option>--prompt-keymap</option>,
 208         <option>--prompt-timezone</option>,
 209         <option>--prompt-hostname</option>,
 210         <option>--prompt-root-password</option> in combination.</para>
 211         </listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>--copy-locale</option></term>
 216         <term><option>--copy-keymap</option></term>
 217         <term><option>--copy-timezone</option></term>
 218         <term><option>--copy-root-password</option></term>
 219
 220         <listitem><para>Copy a specific basic setting from the host.
 221         This only works in combination with <option>--root=</option>
 222         (see above).</para></listitem>
 223       </varlistentry>
 224
 225       <varlistentry>
 226         <term><option>--copy</option></term>
 227
 228         <listitem><para>Copy locale, keymap, time zone and root password from
 229         the host. This is equivalent to specifying
 230         <option>--copy-locale</option>,
 231         <option>--copy-keymap</option>,
 232         <option>--copy-timezone</option>,
 233         <option>--copy-root-password</option> in combination.</para>
 234         </listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><option>--setup-machine-id</option></term>
 239
 240         <listitem><para>Initialize the system's machine ID to a random
 241         ID. This only works in combination with
 242         <option>--root=</option>.</para></listitem>
 243       </varlistentry>
 244
 245       <varlistentry>
 246         <term><option>--force</option></term>
 247
 248         <listitem><para>systemd-firstboot doesn't modify existing files unless <option>--force</option>
 249         is specified. For modifications to <filename>/etc/passwd</filename> and
 250         <filename>/etc/shadow</filename>, systemd-firstboot only modifies the entry of the
 251         <literal>root</literal> user instead of overwriting the entire file.</para></listitem>
 252       </varlistentry>
 253
 254       <varlistentry>
 255         <term><option>--delete-root-password</option></term>
 256
 257         <listitem><para>Removes the password of the system's root user, enabling login as root without a
 258         password unless the root account is locked. Note that this is extremely insecure and hence this
 259         option should not be used lightly.</para></listitem>
 260       </varlistentry>
 261
 262       <varlistentry>
 263         <term><option>--welcome=</option></term>
 264
 265         <listitem><para>Takes a boolean argument. By default when prompting the user for configuration
 266         options a brief welcome text is shown before the first question is asked. Pass false to this option
 267         to turn off the welcome text.</para></listitem>
 268       </varlistentry>
 269
 270       <xi:include href="standard-options.xml" xpointer="help" />
 271       <xi:include href="standard-options.xml" xpointer="version" />
 272     </variablelist>
 273
 274   </refsect1>
 275
 276   <refsect1>
 277     <title>Exit status</title>
 278
 279     <para>On success, 0 is returned, a non-zero failure code
 280     otherwise.</para>
 281   </refsect1>
 282
 283   <refsect1>
 284     <title>Kernel Command Line</title>
 285
 286     <variablelist class='kernel-commandline-options'>
 287       <varlistentry>
 288         <term><varname>systemd.firstboot=</varname></term>
 289
 290         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 291         won't interactively query the user for basic settings at first boot, even if those settings are not
 292         initialized yet.</para></listitem>
 293       </varlistentry>
 294     </variablelist>
 295   </refsect1>
 296
 297   <refsect1>
 298     <title>See Also</title>
 299     <para>
 300       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 301       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 302       <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 303       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 304       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 305       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 306       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 307       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 308       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 311     </para>
 312   </refsect1>
 313
 314 </refentry>