diff --git a/man/machine-id.xml b/man/machine-id.xml
index 3c261bffcc..e434c89de9 100644
--- a/man/machine-id.xml
+++ b/man/machine-id.xml
@@ -53,18 +53,26 @@
Description
- The /etc/machine-id file contains the unique machine ID of the local
- system that is set during installation. The machine ID is a single newline-terminated,
- hexadecimal, 32-character, lowercase ID. When decoded from hexadecimal, this corresponds to a
- 16-byte/128-bit value.
+ The /etc/machine-id file contains the unique machine ID of
+ the local system that is set during installation or boot. The machine ID is a single
+ newline-terminated, hexadecimal, 32-character, lowercase ID. When decoded from
+ hexadecimal, this corresponds to a 16-byte/128-bit value. This ID may not be all
+ zeros.
- The machine ID is usually generated from a random source
- during system installation and stays constant for all subsequent
- boots. Optionally, for stateless systems, it is generated during
- runtime at early boot if it is found to be empty.
+ The machine ID is usually generated from a random source during system
+ installation or first boot and stays constant for all subsequent boots. Optionally,
+ for stateless systems, it is generated during runtime during early boot if necessary.
+
- The machine ID does not change based on local or network configuration or when hardware is
- replaced. Due to this and its greater length, it is a more useful replacement for the
+ The machine ID may be set, for example when network booting, with the
+ systemd.machine_id= kernel command line parameter or by passing the
+ option to systemd. An ID is specified in this manner
+ has higher priority and will be used instead of the ID stored in
+ /etc/machine-id.
+
+ The machine ID does not change based on local or network configuration or when
+ hardware is replaced. Due to this and its greater length, it is a more useful
+ replacement for the
gethostid3
call that POSIX specifies.
@@ -79,19 +87,59 @@
the original machine ID from the application-specific one. The
sd_id128_get_machine_app_specific3
API provides an implementation of such an algorithm.
+
- The
+
+ Initialization
+
+ Each machine should have a non-empty ID in normal operation. The ID of each
+ machine should be unique. To achive those objectives,
+ /etc/machine-id can be initialized in a few different ways.
+
+
+ For normal operating system installations, where a custom image is created for a
+ specific machine, /etc/machine-id should be populated during
+ installation.
+
+ systemd-machine-id-setup1
- tool may be used by installer tools to initialize the machine ID
- at install time. Use
- systemd-firstboot1
- to initialize it on mounted (but not booted) system images.
+ may be used by installer tools to initialize the machine ID at install time, but
+ /etc/machine-id may also be written using any other means.
+
- The machine-id may also be set, for example when network
- booting, by setting the systemd.machine_id=
- kernel command line parameter or passing the option
- to systemd. A machine-id may not
- be set to all zeros.
+ 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.
+
+ systemd-firstboot1
+ may be used to to initialize /etc/machine-id on mounted (but not
+ booted) system images.
+
+ When a machine is booted with
+ systemd1
+ the ID of the machine will be established. If systemd.machine_id=
+ or options (see first section) are specified, this
+ value will be used. Otherwise, the value in /etc/machine-id will
+ be used. If this file is empty or missing, systemd will attempt
+ to use the D-Bus machine ID from /var/lib/dbus/machine-id, the
+ value of the kernel command line option container_uuid, the KVM DMI
+ product_uuid (on KVM systems), and finally a randomly generated
+ UUID.
+
+ After the machine ID is established,
+ systemd1
+ will attempt to save it to /etc/machine-id. If this fails, it
+ will attempt to bind-mount a temporary file over /etc/machine-id.
+ It is an error if the file system is read-only and does not contain a (possibly empty)
+ /etc/machine-id file.
+
+ systemd-machine-id-commit.service8
+ will attempt to write the machine ID to the file system if
+ /etc/machine-id or /etc are read-only during
+ early boot but become writable later on.