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