man/systemd-firstboot.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2014 Lennart Poettering
   9 -->
  10
  11 <refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
  12     xmlns:xi="http://www.w3.org/2001/XInclude">
  13
  14   <refentryinfo>
  15     <title>systemd-firstboot</title>
  16     <productname>systemd</productname>
  17
  18     <authorgroup>
  19       <author>
  20         <contrib>Developer</contrib>
  21         <firstname>Lennart</firstname>
  22         <surname>Poettering</surname>
  23         <email>lennart@poettering.net</email>
  24       </author>
  25     </authorgroup>
  26   </refentryinfo>
  27
  28   <refmeta>
  29     <refentrytitle>systemd-firstboot</refentrytitle>
  30     <manvolnum>1</manvolnum>
  31   </refmeta>
  32
  33   <refnamediv>
  34     <refname>systemd-firstboot</refname>
  35     <refname>systemd-firstboot.service</refname>
  36     <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose>
  37   </refnamediv>
  38
  39   <refsynopsisdiv>
  40     <cmdsynopsis>
  41       <command>systemd-firstboot</command>
  42       <arg choice="opt" rep="repeat">OPTIONS</arg>
  43     </cmdsynopsis>
  44
  45     <para><filename>systemd-firstboot.service</filename></para>
  46   </refsynopsisdiv>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para><command>systemd-firstboot</command> initializes the most
  52     basic system settings interactively on the first boot, or
  53     optionally non-interactively when a system image is created.
  54     The service is started if <varname>ConditionFirstBoot=yes</varname>
  55     is satisfied. This essentially means that <filename>/etc</filename>
  56     is empty, see
  57     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  58     for details.</para>
  59
  60     <para>The following settings may be set up:</para>
  61
  62     <itemizedlist>
  63       <listitem><para>The system locale, more specifically the two
  64       locale variables <varname>LANG=</varname> and
  65       <varname>LC_MESSAGES</varname></para></listitem>
  66
  67       <listitem><para>The system keyboard map</para></listitem>
  68
  69       <listitem><para>The system time zone</para></listitem>
  70
  71       <listitem><para>The system host name</para></listitem>
  72
  73       <listitem><para>The machine ID of the system</para></listitem>
  74
  75       <listitem><para>The root user's password</para></listitem>
  76     </itemizedlist>
  77
  78     <para>Each of the fields may either be queried interactively by
  79     users, set non-interactively on the tool's command line, or be
  80     copied from a host system that is used to set up the system
  81     image.</para>
  82
  83     <para>If a setting is already initialized, it will not be
  84     overwritten and the user will not be prompted for the
  85     setting.</para>
  86
  87     <para>Note that this tool operates directly on the file system and
  88     does not involve any running system services, unlike
  89     <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  90     <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  91     or
  92     <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  93     This allows <command>systemd-firstboot</command> to operate on
  94     mounted but not booted disk images and in early boot. It is not
  95     recommended to use <command>systemd-firstboot</command> on the
  96     running system while it is up.</para>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title>Options</title>
 101
 102     <para>The following options are understood:</para>
 103
 104     <variablelist>
 105       <varlistentry>
 106         <term><option>--root=<replaceable>root</replaceable></option></term>
 107         <listitem><para>Takes a directory path as an argument. All
 108         paths will be prefixed with the given alternate
 109         <replaceable>root</replaceable> path, including config search
 110         paths. This is useful to operate on a system image mounted to
 111         the specified directory instead of the host system itself.
 112         </para></listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
 117         <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
 118
 119         <listitem><para>Sets the system locale, more specifically the
 120         <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
 121         settings. The argument should be a valid locale identifier,
 122         such as <literal>de_DE.UTF-8</literal>. This controls the
 123         <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 124         configuration file.</para></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><option>--keymap=<replaceable>KEYMAP</replaceable></option></term>
 129
 130         <listitem><para>Sets the system keyboard layout. The argument should be a valid keyboard map,
 131         such as <literal>de-latin1</literal>. This controls the <literal>KEYMAP</literal> entry in the
 132         <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 133         configuration file.</para></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
 138
 139         <listitem><para>Sets the system time zone. The argument should
 140         be a valid time zone identifier, such as
 141         <literal>Europe/Berlin</literal>. This controls the
 142         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 143         symlink.</para></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
 148
 149         <listitem><para>Sets the system hostname. The argument should
 150         be a host name, compatible with DNS. This controls the
 151         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 152         configuration file.</para></listitem>
 153       </varlistentry>
 154
 155       <varlistentry>
 156         <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
 157
 158         <listitem><para>Sets the system's machine ID. This controls
 159         the
 160         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 161         file.</para></listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
 166         <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
 167
 168         <listitem><para>Sets the password of the system's root user.
 169         This creates a
 170         <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 171         file. This setting exists in two forms:
 172         <option>--root-password=</option> accepts the password to set
 173         directly on the command line, and
 174         <option>--root-password-file=</option> reads it from a file.
 175         Note that it is not recommended to specify passwords on the
 176         command line, as other users might be able to see them simply
 177         by invoking
 178         <citerefentry project='die-net'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><option>--prompt-locale</option></term>
 183         <term><option>--prompt-keymap</option></term>
 184         <term><option>--prompt-timezone</option></term>
 185         <term><option>--prompt-hostname</option></term>
 186         <term><option>--prompt-root-password</option></term>
 187
 188         <listitem><para>Prompt the user interactively for a specific
 189         basic setting. Note that any explicit configuration settings
 190         specified on the command line take precedence, and the user is
 191         not prompted for it.</para></listitem>
 192       </varlistentry>
 193
 194       <varlistentry>
 195         <term><option>--prompt</option></term>
 196
 197         <listitem><para>Query the user for locale, keymap, timezone, hostname
 198         and root password. This is equivalent to specifying
 199         <option>--prompt-locale</option>,
 200         <option>--prompt-keymap</option>,
 201         <option>--prompt-timezone</option>,
 202         <option>--prompt-hostname</option>,
 203         <option>--prompt-root-password</option> in combination.</para>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry>
 208         <term><option>--copy-locale</option></term>
 209         <term><option>--copy-keymap</option></term>
 210         <term><option>--copy-timezone</option></term>
 211         <term><option>--copy-root-password</option></term>
 212
 213         <listitem><para>Copy a specific basic setting from the host.
 214         This only works in combination with <option>--root=</option>
 215         (see above).</para></listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><option>--copy</option></term>
 220
 221         <listitem><para>Copy locale, keymap, time zone and root password from
 222         the host. This is equivalent to specifying
 223         <option>--copy-locale</option>,
 224         <option>--copy-keymap</option>,
 225         <option>--copy-timezone</option>,
 226         <option>--copy-root-password</option> in combination.</para>
 227         </listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><option>--setup-machine-id</option></term>
 232
 233         <listitem><para>Initialize the system's machine ID to a random
 234         ID. This only works in combination with
 235         <option>--root=</option>.</para></listitem>
 236       </varlistentry>
 237
 238       <xi:include href="standard-options.xml" xpointer="help" />
 239       <xi:include href="standard-options.xml" xpointer="version" />
 240     </variablelist>
 241
 242   </refsect1>
 243
 244   <refsect1>
 245     <title>Exit status</title>
 246
 247     <para>On success, 0 is returned, a non-zero failure code
 248     otherwise.</para>
 249   </refsect1>
 250
 251   <refsect1>
 252     <title>Kernel Command Line</title>
 253
 254     <variablelist class='kernel-commandline-options'>
 255       <varlistentry>
 256         <term><varname>systemd.firstboot=</varname></term>
 257
 258         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 259         won't interactively query the user for basic settings at first boot, even if those settings are not
 260         initialized yet.</para></listitem>
 261       </varlistentry>
 262     </variablelist>
 263   </refsect1>
 264
 265   <refsect1>
 266     <title>See Also</title>
 267     <para>
 268       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 269       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 270       <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 271       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 272       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 273       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 274       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 275       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 276       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 277       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 278       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 279     </para>
 280   </refsect1>
 281
 282 </refentry>