systemd-firstboot.xml revision 30f10abf42f9e4d251a0b45b07812aafdef6be7c
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering This file is part of systemd.
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering Copyright 2014 Lennart Poettering
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering systemd is free software; you can redistribute it and/or modify it
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering under the terms of the GNU Lesser General Public License as published by
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering (at your option) any later version.
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering systemd is distributed in the hope that it will be useful, but
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering Lesser General Public License for more details.
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering You should have received a copy of the GNU Lesser General Public License
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering xmlns:xi="http://www.w3.org/2001/XInclude">
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <refentryinfo>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </authorgroup>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </refentryinfo>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <refentrytitle>systemd-firstboot</refentrytitle>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <refname>systemd-firstboot.service</refname>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <refpurpose>Initialize basic system settings on or before the first boot-up of a system</refpurpose>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <refsynopsisdiv>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <arg choice="opt" rep="repeat">OPTIONS</arg>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </cmdsynopsis>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para><filename>systemd-firstboot.service</filename></para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </refsynopsisdiv>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para><command>systemd-firstboot</command> initializes
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering the most basic system settings interactively on the
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering first boot, or optionally non-interactively when a
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering system image is created. The following settings may be
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering set up:</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <itemizedlist>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering specifically the two locale variables
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varname>LC_MESSAGES</varname></para></listitem>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <listitem><para>The system time zone</para></listitem>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <listitem><para>The system host name</para></listitem>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <listitem><para>The machine ID of the system</para></listitem>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <listitem><para>The root user's password</para></listitem>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </itemizedlist>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Each of the fields may either be queried
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering interactively from the users, set non-interactively on
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering the tool's command line, or be copied from a host
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering system that is used to set up the system image.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>If a setting is already initialized it will not
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering be overwritten and the user will not be prompted for
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering the setting.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Note that this tool operates directly on the
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering file system and does not involve any running system
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering services, unlike
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering allows <command>systemd-firstboot</command> to operate
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering on mounted but not booted disk images and in early
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering boot. It is not recommended to use
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <command>systemd-firsboot</command> on the running
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering system while it is up.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>The following options are understood:</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <variablelist>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--root=<replaceable>root</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering as an argument. All paths will be
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering prefixed with the given alternate
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering including config search paths. This is
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering useful to operate on a system image
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering mounted to the specified directory
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering instead of the host system itself.
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--locale=<replaceable>LOCALE</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--locale-messages=<replaceable>LOCALE</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering locale, more specifically the
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering settings. The argument should be a
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering valid locale identifier, such as
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--timezone=<replaceable>TIMEZONE</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering zone. The argument should be a valid
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering time zone identifier, such as
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--hostname=<replaceable>HOSTNAME</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering hostname. The argument should be a
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering host name, compatible with DNS. This
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--machine-id=<replaceable>ID</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <listitem><para>Sets the system's machine ID. This
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--root-password=<replaceable>PASSWORD</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--root-password-file=<replaceable>PATH</replaceable></option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering the system's root user. This creates a
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering file. This setting exists in two
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering accepts the password to set directly
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering on the command line,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering reads it from a file. Note that
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering it is not recommended specifying
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering passwords on the command line as other
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering users might be able to see them
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering simply by invoking
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--prompt-locale</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--prompt-timezone</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--prompt-hostname</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--prompt-root-password</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Prompt the user interactively
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering for a specific basic setting. Note
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering that any explicit configuration
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering settings specified on the command line
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering take precedence, and the user is not
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering prompted for it.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Query the user for locale,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering timezone, hostname and root
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering password. This is equivalent to
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering in combination.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--copy-locale</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--copy-timezone</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--copy-root-password</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Copy a specific basic setting
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering from the host. This only works in
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering combination with
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering above).</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Copy locale, time zone and root
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering password from the host. This is
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering equivalent to specifiying
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering in combination.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <term><option>--setup-machine-id</option></term>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>Initialize the system's machine
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering ID to a random ID. This only works
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering combination with
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </varlistentry>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <xi:include href="standard-options.xml" xpointer="help" />
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <xi:include href="standard-options.xml" xpointer="version" />
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering </variablelist>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <para>On success, 0 is returned, a non-zero failure
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering code otherwise.</para>
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
30f10abf42f9e4d251a0b45b07812aafdef6be7cLennart Poettering <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>