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