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>