<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="systemd-firstboot" conditional='ENABLE_FIRSTBOOT'
<refsect1>
<title>Description</title>
- <para><command>systemd-firstboot</command> initializes basic system settings interactively during the
- first boot, or non-interactively on an offline system image. The service is started during boot if
- <varname>ConditionFirstBoot=yes</varname> is met, which essentially means that <filename>/etc/</filename>
- is empty, see
+ <para>The <command>systemd-firstboot.service</command> unit is one of the units which are used to
+ initialize the machine configuration during "First Boot", i.e. when the system is freshly installed or
+ after a factory reset. The
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> manager
+ itself will initialize
+ <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> and preset
+ all units, enabling or disabling them according to the
+ <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+ settings. <filename>systemd-firstboot.service</filename> is started later to interactively initialize
+ basic system configuration. It is started only if <varname>ConditionFirstBoot=yes</varname> is met, which
+ essentially means that <filename>/etc/</filename> is unpopulated, see
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
- details.</para>
+ details. System credentials may be used to inject configuration; those settings are not queried
+ interactively.</para>
+
+ <para>The <command>systemd-firstboot</command> command can also be used to non-interactively initialize
+ an offline system image.</para>
<para>The following settings may be configured:</para>
<term><option>--force</option></term>
<listitem><para>Write configuration even if the relevant files already exist. Without this option,
- <filename>systemd-firstboot</filename> doesn't modify or replace existing files. Note that when
- configuring the root account, even with this option, <filename>systemd-firstboot</filename> only
+ <command>systemd-firstboot</command> doesn't modify or replace existing files. Note that when
+ configuring the root account, even with this option, <command>systemd-firstboot</command> only
modifies the entry of the <literal>root</literal> user, leaving other entries in
<filename>/etc/passwd</filename> and <filename>/etc/shadow</filename> intact.</para>
<para><command>systemd-firstboot</command> supports the service credentials logic as implemented by
<varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname>
- (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
+ (see <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details). The following credentials are used when passed in:</para>
<variablelist class='system-credentials'>
<para><programlisting># systemd-nspawn --image=… --set-credential=firstboot.locale:de_DE.UTF-8 …</programlisting></para>
- <para>Note that these credentials are only read and applied during the first boot process. Once they are
- applied they remain applied for subsequent boots, and the credentials are not considered anymore.</para>
+ <para>Note that these credentials are only read and applied during the first boot. Once they are applied
+ they remain applied for subsequent boots, and the credentials are not considered anymore.</para>
</refsect1>
<refsect1>
<refsect1>
<title>See Also</title>
- <para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- </para>
+ <para><simplelist type="inline">
+ <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>locale.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>vconsole.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>localtime</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry project='die-net'><refentrytitle>shadow</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry project='man-pages'><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ <member><citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+ </simplelist></para>
</refsect1>
</refentry>