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