diff --git a/man/machine-id.xml b/man/machine-id.xml
index cf759f2a0e..7e889ca47a 100644
--- a/man/machine-id.xml
+++ b/man/machine-id.xml
@@ -82,10 +82,11 @@
For operating system images which are created once and used on multiple
machines, for example for containers or in the cloud,
- /etc/machine-id 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.
+ /etc/machine-id 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.
systemd-firstboot1
may be used to initialize /etc/machine-id on mounted (but not
@@ -115,6 +116,34 @@
early boot but become writable later on.
+
+ First Boot Semantics
+
+ /etc/machine-id is used to decide whether a boot is the first one. The rules
+ are as follows:
+
+
+ If /etc/machine-id does not exist, this is a first boot. During
+ early boot, systemd will write unitialized\n to this file and overmount
+ a temporary file which contains the actual machine ID. Later (after first-boot-complete.target
+ has been reached), the real machine ID will be written to disk.
+
+ If /etc/machine-id contains the string uninitialized,
+ a boot is also considered the first boot. The same mechanism as above applies.
+
+ If /etc/machine-id exists and is empty, a boot is
+ not considered the first boot. systemd will still bind-mount a file
+ containing the actual machine-id over it and later try to commit it to disk (if /etc/ is
+ writable).
+
+ If /etc/machine-id already contains a valid machine-id, this is
+ not a first boot.
+
+
+ If by any of the above rules, a first boot is detected, units with ConditionFirstBoot=yes
+ will be run.
+
+
Relation to OSF UUIDs
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 27035798bc..4b8e515fe2 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1315,10 +1315,16 @@
ConditionFirstBoot=
Takes a boolean argument. This condition may be used to conditionalize units on
- whether the system is booting up with an unpopulated /etc/ directory
- (specifically: an /etc/ with no /etc/machine-id). This may
- be used to populate /etc/ on the first boot after factory reset, or when a new
- system instance boots up for the first time.
+ whether the system is booting up for the first time. This roughly means that /etc/
+ is unpopulated (for details, see "First Boot Semantics" in
+ machine-id5).
+ This may be used to populate /etc/ on the first boot after factory reset, or
+ when a new system instance boots up for the first time.
+
+ For robustness, units with ConditionFirstBoot=yes should order themselves
+ before first-boot-complete.target and pull in this passive target with
+ Wants=. This ensures that in a case of an aborted first boot, these units will
+ be re-run during the next system startup.
If the systemd.condition-first-boot= option is specified on the kernel
command line (taking a boolean), it will override the result of this condition check, taking