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. The
  67     following settings may be set up:</para>
  68
  69     <itemizedlist>
  70       <listitem><para>The system locale, more specifically the two
  71       locale variables <varname>LANG=</varname> and
  72       <varname>LC_MESSAGES</varname></para></listitem>
  73
  74       <listitem><para>The system time zone</para></listitem>
  75
  76       <listitem><para>The system host name</para></listitem>
  77
  78       <listitem><para>The machine ID of the system</para></listitem>
  79
  80       <listitem><para>The root user's password</para></listitem>
  81     </itemizedlist>
  82
  83     <para>Each of the fields may either be queried interactively from
  84     the users, set non-interactively on the tool's command line, or be
  85     copied from a host system that is used to set up the system
  86     image.</para>
  87
  88     <para>If a setting is already initialized it will not be
  89     overwritten and the user will not be prompted for the
  90     setting.</para>
  91
  92     <para>Note that this tool operates directly on the file system and
  93     does not involve any running system services, unlike
  94     <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  95     <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  96     or
  97     <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  98     This allows <command>systemd-firstboot</command> to operate on
  99     mounted but not booted disk images and in early boot. It is not
 100     recommended to use <command>systemd-firstboot</command> on the
 101     running system while it is up.</para>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Options</title>
 106
 107     <para>The following options are understood:</para>
 108
 109     <variablelist>
 110       <varlistentry>
 111         <term><option>--root=<replaceable>root</replaceable></option></term>
 112         <listitem><para>Takes a directory path as an argument. All
 113         paths will be prefixed with the given alternate
 114         <replaceable>root</replaceable> path, including config search
 115         paths. This is useful to operate on a system image mounted to
 116         the specified directory instead of the host system itself.
 117         </para></listitem>
 118       </varlistentry>
 119
 120       <varlistentry>
 121         <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
 122         <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
 123
 124         <listitem><para>Sets the system locale, more specifically the
 125         <varname>LANG=</varname> and <varname>LC_MESSAGES</varname>
 126         settings. The argument should be a valid locale identifier,
 127         such as <literal>de_DE.UTF-8</literal>. This controls the
 128         <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 129         configuration file.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
 134
 135         <listitem><para>Sets the system time zone. The argument should
 136         be a valid time zone identifier, such as
 137         <literal>Europe/Berlin</literal>. This controls the
 138         <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 139         symlink.</para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
 144
 145         <listitem><para>Sets the system hostname. The argument should
 146         be a host name, compatible with DNS. This controls the
 147         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 148         configuration file.</para></listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
 153
 154         <listitem><para>Sets the system's machine ID. This controls
 155         the
 156         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 157         file.</para></listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
 162         <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
 163
 164         <listitem><para>Sets the password of the system's root user.
 165         This creates a
 166         <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 167         file. This setting exists in two forms:
 168         <option>--root-password=</option> accepts the password to set
 169         directly on the command line,
 170         <option>--root-password-file=</option> reads it from a file.
 171         Note that it is not recommended specifying passwords on the
 172         command line as other users might be able to see them simply
 173         by invoking
 174         <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term><option>--prompt-locale</option></term>
 179         <term><option>--prompt-timezone</option></term>
 180         <term><option>--prompt-hostname</option></term>
 181         <term><option>--prompt-root-password</option></term>
 182
 183         <listitem><para>Prompt the user interactively for a specific
 184         basic setting. Note that any explicit configuration settings
 185         specified on the command line take precedence, and the user is
 186         not prompted for it.</para></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><option>--prompt</option></term>
 191
 192         <listitem><para>Query the user for locale, timezone, hostname
 193         and root password. This is equivalent to specifying
 194         <option>--prompt-locale</option>,
 195         <option>--prompt-timezone</option>,
 196         <option>--prompt-hostname</option>,
 197         <option>--prompt-root-password</option> in combination.</para>
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><option>--copy-locale</option></term>
 203         <term><option>--copy-timezone</option></term>
 204         <term><option>--copy-root-password</option></term>
 205
 206         <listitem><para>Copy a specific basic setting from the host.
 207         This only works in combination with <option>--root=</option>
 208         (see above).</para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><option>--copy</option></term>
 213
 214         <listitem><para>Copy locale, time zone and root password from
 215         the host. This is equivalent to specifying
 216         <option>--copy-locale</option>,
 217         <option>--copy-timezone</option>,
 218         <option>--copy-root-password</option> in combination.</para>
 219         </listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>--setup-machine-id</option></term>
 224
 225         <listitem><para>Initialize the system's machine ID to a random
 226         ID. This only works in combination with
 227         <option>--root=</option>.</para></listitem>
 228       </varlistentry>
 229
 230       <xi:include href="standard-options.xml" xpointer="help" />
 231       <xi:include href="standard-options.xml" xpointer="version" />
 232     </variablelist>
 233
 234   </refsect1>
 235
 236   <refsect1>
 237     <title>Exit status</title>
 238
 239     <para>On success, 0 is returned, a non-zero failure code
 240     otherwise.</para>
 241   </refsect1>
 242
 243   <refsect1>
 244     <title>See Also</title>
 245     <para>
 246       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 247       <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 248       <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 249       <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 250       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 251       <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 252       <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 253       <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 254       <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 255       <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 256     </para>
 257   </refsect1>
 258
 259 </refentry>