From a48627ef87e855db7a18400a4f2a63c90f6e60fe Mon Sep 17 00:00:00 2001
From: Harald Seiler <hws@denx.de>
Date: Sun, 6 Sep 2020 22:57:59 +0200
Subject: [PATCH] man: Document new machine-id and first boot behavior

---
 man/machine-id.xml   | 37 +++++++++++++++++++++++++++++++++----
 man/systemd.unit.xml | 14 ++++++++++----
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/man/machine-id.xml b/man/machine-id.xml
index cf759f2a0e7..7e889ca47a9 100644
--- a/man/machine-id.xml
+++ b/man/machine-id.xml
@@ -82,10 +82,11 @@
 
     <para>For operating system images which are created once and used on multiple
     machines, for example for containers or in the cloud,
-    <filename>/etc/machine-id</filename> should be an empty file in the generic file
-    system image. An ID will be generated during boot and saved to this file if
-    possible. Having an empty file in place is useful because it allows a temporary file
-    to be bind-mounted over the real file, in case the image is used read-only.</para>
+    <filename>/etc/machine-id</filename> should be either missing or an empty file in the generic file
+    system image (the difference between the two options is described under "First Boot Semantics" below). An
+    ID will be generated during boot and saved to this file if possible. Having an empty file in place is
+    useful because it allows a temporary file to be bind-mounted over the real file, in case the image is
+    used read-only.</para>
 
     <para><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     may be used to initialize <filename>/etc/machine-id</filename> on mounted (but not
@@ -115,6 +116,34 @@
     early boot but become writable later on.</para>
   </refsect1>
 
+  <refsect1>
+    <title>First Boot Semantics</title>
+
+    <para><filename>/etc/machine-id</filename> is used to decide whether a boot is the first one.  The rules
+    are as follows:</para>
+
+    <orderedlist>
+      <listitem><para>If <filename>/etc/machine-id</filename> does not exist, this is a first boot.  During
+      early boot, <command>systemd</command> will write <literal>unitialized\n</literal> to this file and overmount
+      a temporary file which contains the actual machine ID.  Later (after <filename>first-boot-complete.target</filename>
+      has been reached), the real machine ID will be written to disk.</para></listitem>
+
+      <listitem><para>If <filename>/etc/machine-id</filename> contains the string <literal>uninitialized</literal>,
+      a boot is also considered the first boot.  The same mechanism as above applies.</para></listitem>
+
+      <listitem><para>If <filename>/etc/machine-id</filename> exists and is empty, a boot is
+      <emphasis>not</emphasis> considered the first boot.  <command>systemd</command> will still bind-mount a file
+      containing the actual machine-id over it and later try to commit it to disk (if <filename>/etc/</filename> is
+      writable).</para></listitem>
+
+      <listitem><para>If <filename>/etc/machine-id</filename> already contains a valid machine-id, this is
+      not a first boot.</para></listitem>
+    </orderedlist>
+
+    <para>If by any of the above rules, a first boot is detected, units with <varname>ConditionFirstBoot=yes</varname>
+    will be run.</para>
+  </refsect1>
+
   <refsect1>
     <title>Relation to OSF UUIDs</title>
 
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 27035798bc2..4b8e515fe2a 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1315,10 +1315,16 @@
           <term><varname>ConditionFirstBoot=</varname></term>
 
           <listitem><para>Takes a boolean argument. This condition may be used to conditionalize units on
-          whether the system is booting up with an unpopulated <filename>/etc/</filename> directory
-          (specifically: an <filename>/etc/</filename> with no <filename>/etc/machine-id</filename>). This 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>
+          whether the system is booting up for the first time.  This roughly means that <filename>/etc/</filename>
+          is unpopulated (for details, see "First Boot Semantics" in
+          <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+          This 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>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
+          be re-run during the next system startup.</para>
 
           <para>If the <varname>systemd.condition-first-boot=</varname> option is specified on the kernel
           command line (taking a boolean), it will override the result of this condition check, taking
-- 
2.47.3