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 time zone</para></listitem>
  81
  82       <listitem><para>The system host name</para></listitem>
  83
  84       <listitem><para>The machine ID of the system</para></listitem>
  85
  86       <listitem><para>The root user's password</para></listitem>
  87     </itemizedlist>
  88
  89     <para>Each of the fields may either be queried interactively by
  90     users, set non-interactively on the tool's command line, or be
  91     copied from a host system that is used to set up the system
  92     image.</para>
  93
  94     <para>If a setting is already initialized, it will not be
  95     overwritten and the user will not be prompted for the
  96     setting.</para>
  97
  98     <para>Note that this tool operates directly on the file system and
  99     does not involve any running system services, unlike
 100     <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 101     <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 102     or
 103     <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 104     This allows <command>systemd-firstboot</command> to operate on
 105     mounted but not booted disk images and in early boot. It is not
 106     recommended to use <command>systemd-firstboot</command> on the
 107     running system while it is up.</para>
 108   </refsect1>
 109
 110   <refsect1>
 111     <title>Options</title>
 112
 113     <para>The following options are understood:</para>
 114
 115     <variablelist>
 116       <varlistentry>
 117         <term><option>--root=<replaceable>root</replaceable></option></term>
 118         <listitem><para>Takes a directory path as an argument. All
 119         paths will be prefixed with the given alternate
 120         <replaceable>root</replaceable> path, including config search
 121         paths. This is useful to operate on a system image mounted to
 122         the specified directory instead of the host system itself.
 123         </para></listitem>
 124       </varlistentry>
 125
 126       <varlistentry>
 127         <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
 128         <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
 129
 130         <listitem><para>Sets the system locale, more specifically the
 131         <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
 132         settings. The argument should be a valid locale identifier,
 133         such as <literal>de_DE.UTF-8</literal>. This controls the
 134         <citerefentry project='man-pages'><refentrytitle>locale.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-timezone</option></term>
 186         <term><option>--prompt-hostname</option></term>
 187         <term><option>--prompt-root-password</option></term>
 188
 189         <listitem><para>Prompt the user interactively for a specific
 190         basic setting. Note that any explicit configuration settings
 191         specified on the command line take precedence, and the user is
 192         not prompted for it.</para></listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term><option>--prompt</option></term>
 197
 198         <listitem><para>Query the user for locale, timezone, hostname
 199         and root password. This is equivalent to specifying
 200         <option>--prompt-locale</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-timezone</option></term>
 210         <term><option>--copy-root-password</option></term>
 211
 212         <listitem><para>Copy a specific basic setting from the host.
 213         This only works in combination with <option>--root=</option>
 214         (see above).</para></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term><option>--copy</option></term>
 219
 220         <listitem><para>Copy locale, time zone and root password from
 221         the host. This is equivalent to specifying
 222         <option>--copy-locale</option>,
 223         <option>--copy-timezone</option>,
 224         <option>--copy-root-password</option> in combination.</para>
 225         </listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><option>--setup-machine-id</option></term>
 230
 231         <listitem><para>Initialize the system's machine ID to a random
 232         ID. This only works in combination with
 233         <option>--root=</option>.</para></listitem>
 234       </varlistentry>
 235
 236       <xi:include href="standard-options.xml" xpointer="help" />
 237       <xi:include href="standard-options.xml" xpointer="version" />
 238     </variablelist>
 239
 240   </refsect1>
 241
 242   <refsect1>
 243     <title>Exit status</title>
 244
 245     <para>On success, 0 is returned, a non-zero failure code
 246     otherwise.</para>
 247   </refsect1>
 248
 249   <refsect1>
 250     <title>Kernel Command Line</title>
 251
 252     <variablelist class='kernel-commandline-options'>
 253       <varlistentry>
 254         <term><varname>systemd.firstboot=</varname></term>
 255
 256         <listitem><para>Takes a boolean argument, defaults to on. If off, <filename>systemd-firstboot.service</filename>
 257         won't interactively query the user for basic settings at first boot, even if those settings are not
 258         initialized yet.</para></listitem>
 259       </varlistentry>
 260     </variablelist>
 261   </refsect1>
 262
 263   <refsect1>
 264     <title>See Also</title>
 265     <para>
 266       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 267       <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 268       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 269       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 270       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 271       <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 272       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 273       <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 274       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 275       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 276     </para>
 277   </refsect1>
 278
 279 </refentry>