man: mention that preset-all is performed during early boot

The intro of systemd-firstboot is rewritten to make it clearer how it fits into
the big picture. Systemd does some machine-id and presets and
systemd-firstboot.service is used to interactively fill in the blanks.

Closes #22225.

diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml
index a6ba07a3a8c2d8d7068565cb4884c09856e988ff..ded7048792cebc80447a6041edbd22d1bbd8f6f5 100644 (file)
--- a/man/systemd-firstboot.xml
+++ b/man/systemd-firstboot.xml
@@ -34,12 +34,23 @@
   <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 unpopulated, 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>
 
@@ -415,8 +426,8 @@
 
     <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>

diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml
index f84a053548765220711e50d165e1cd5332cd0521..b1e796a16a972d9da851aa350fbc628eeeacc950 100644 (file)
--- a/man/systemd.preset.xml
+++ b/man/systemd.preset.xml
@@ -41,7 +41,7 @@
 
     <command>systemctl preset</command> is used by the post install scriptlets of rpm packages (or other OS
     package formats), to enable/disable specific units by default on package installation, enforcing
-    distribution, spin or administrator preset policy. This allows choosing a certain set of units to be
+    distribution, spin, or administrator preset policy. This allows choosing a certain set of units to be
     enabled/disabled even before installing the actual package. For more information, see
     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
 
@@ -56,7 +56,9 @@
     <para>When the machine is booted for the first time,
     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will
     enable/disable all units according to preset policy, similarly to <command>systemctl
-    preset-all</command>. Also see "First Boot Semantics" in
+    preset-all</command>. Also see <varname>ConditionFirstBoot=</varname> in
+    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
+    "First Boot Semantics" in
     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
     </para>
   </refsect1>

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index f7a6af70597048ad1a8abdc0c9b51b707141d0b0..46184f5b7e76e38867aa5634c9ff70cd2c594d5b 100644 (file)
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1654,12 +1654,20 @@
           whether the system is booting up for the first time. This roughly means that <filename>/etc/</filename>
           was unpopulated when the system started booting (for details, see "First Boot Semantics" in
           <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
-          First boot is considered finished (this condition will evaluate as false) after the manager
+          First Boot is considered finished (this condition will evaluate as false) after the manager
           has finished the startup phase.</para>
 
           <para>This condition may be used to populate <filename>/etc/</filename> on the first boot after
           factory reset, or when a new system instance boots up for the first time.</para>
 
+          <para>Note that the service manager itself will perform setup steps during First Boot: it 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. Additional setup may be performed via units with
+          <varname>ConditionFirstBoot=yes</varname>.</para>
+
           <para>For robustness, units with <varname>ConditionFirstBoot=yes</varname> should order themselves
           before <filename>first-boot-complete.target</filename> and pull in this passive target with
           <varname>Wants=</varname>. This ensures that in a case of an aborted first boot, these units will