From 74a79c657e17fc43172a59f1f158d4a26aec2be1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Wed, 18 Oct 2017 18:47:34 +0200 Subject: [PATCH] man: describe how machine-id should be initialized (#7051) --- man/machine-id.xml | 88 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 20 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 @@ 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.