From 07ba9da0bc0d4e3309e766d3734ac56683d3298d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Wed, 18 Oct 2017 18:47:34 +0200
Subject: [PATCH] man: describe how machine-id should be initialized (#7051)

(cherry picked from commit 74a79c657e17fc43172a59f1f158d4a26aec2be1)
---
 man/machine-id.xml | 90 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 69 insertions(+), 21 deletions(-)

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 @@
   <refsect1>
     <title>Description</title>
 
-    <para>The <filename>/etc/machine-id</filename> 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.</para>
+    <para>The <filename>/etc/machine-id</filename> 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.</para>
 
-    <para>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.</para>
+    <para>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.
+    </para>
 
-    <para>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
+    <para>The machine ID may be set, for example when network booting, with the
+    <varname>systemd.machine_id=</varname> kernel command line parameter or by passing the
+    option <option>--machine-id=</option> to systemd. An ID is specified in this manner
+    has higher priority and will be used instead of the ID stored in
+    <filename>/etc/machine-id</filename>.</para>
+
+    <para>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
     <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     call that POSIX specifies.</para>
 
@@ -79,19 +87,59 @@
     the original machine ID from the application-specific one. The
     <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry>
     API provides an implementation of such an algorithm.</para>
+  </refsect1>
 
-    <para>The
+  <refsect1>
+    <title>Initialization</title>
+
+    <para>Each machine should have a non-empty ID in normal operation. The ID of each
+    machine should be unique. To achive those objectives,
+    <filename>/etc/machine-id</filename> can be initialized in a few different ways.
+    </para>
+
+    <para>For normal operating system installations, where a custom image is created for a
+    specific machine, <filename>/etc/machine-id</filename> should be populated during
+    installation.</para>
+
+    <para>
     <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    tool may be used by installer tools to initialize the machine ID
-    at install time. Use
-    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    to initialize it on mounted (but not booted) system images.</para>
-
-    <para>The machine-id may also be set, for example when network
-    booting, by setting the <varname>systemd.machine_id=</varname>
-    kernel command line parameter or passing the option
-    <option>--machine-id=</option> to systemd. A machine-id may not
-    be set to all zeros.</para>
+    may be used by installer tools to initialize the machine ID at install time, but
+    <filename>/etc/machine-id</filename> may also be written using any other means.
+    </para>
+
+    <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>
+
+    <para><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    may be used to to initialize <filename>/etc/machine-id</filename> on mounted (but not
+    booted) system images.</para>
+
+    <para>When a machine is booted with
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    the ID of the machine will be established. If <varname>systemd.machine_id=</varname>
+    or <option>--machine-id=</option> options (see first section) are specified, this
+    value will be used. Otherwise, the value in <filename>/etc/machine-id</filename> will
+    be used. If this file is empty or missing, <filename>systemd</filename> will attempt
+    to use the D-Bus machine ID from <filename>/var/lib/dbus/machine-id</filename>, the
+    value of the kernel command line option <varname>container_uuid</varname>, the KVM DMI
+    <filename>product_uuid</filename> (on KVM systems), and finally a randomly generated
+    UUID.</para>
+
+    <para>After the machine ID is established,
+    <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+    will attempt to save it to <filename>/etc/machine-id</filename>. If this fails, it
+    will attempt to bind-mount a temporary file over <filename>/etc/machine-id</filename>.
+    It is an error if the file system is read-only and does not contain a (possibly empty)
+    <filename>/etc/machine-id</filename> file.</para>
+
+    <para><citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    will attempt to write the machine ID to the file system if
+    <filename>/etc/machine-id</filename> or <filename>/etc</filename> are read-only during
+    early boot but become writable later on.</para>
   </refsect1>
 
   <refsect1>