From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/machine-id.xml | 204 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 man/machine-id.xml (limited to 'man/machine-id.xml') diff --git a/man/machine-id.xml b/man/machine-id.xml new file mode 100644 index 0000000..e57a7c1 --- /dev/null +++ b/man/machine-id.xml @@ -0,0 +1,204 @@ + + + + + + + machine-id + systemd + + + + machine-id + 5 + + + + machine-id + Local machine ID configuration file + + + + /etc/machine-id + + + + Description + + 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 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 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 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. + + This machine ID adheres to the same format and logic as the + D-Bus machine ID. + + This ID uniquely identifies the host. It should be considered "confidential", and must not be exposed in + untrusted environments, in particular on the network. If a stable unique identifier that is tied to the machine is + needed for some application, the machine ID or any part of it must not be used directly. Instead the machine ID + should be hashed with a cryptographic, keyed hash function, using a fixed, application-specific key. That way the + ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve + the original machine ID from the application-specific one. The + sd_id128_get_machine_app_specific3 + API provides an implementation of such an algorithm. + + + + Initialization + + Each machine should have a non-empty ID in normal operation. The ID of each + machine should be unique. To achieve 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 + 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. + + + 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 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. Also see Safely + Building Images. + + systemd-firstboot1 + may be used 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 or the devicetree vm,uuid + (on KVM systems), the Xen hypervisor uuid, 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. + + + + First Boot Semantics + + /etc/machine-id is used to decide whether a boot is the first one. The rules + are as follows: + + + The kernel command argument systemd.condition-first-boot= may be + used to override the autodetection logic, see + kernel-command-line7. + + + Otherwise, if /etc/machine-id does not exist, this is a first + boot. During early boot, systemd will write uninitialized\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 according to the above rules a first boot is detected, units with + ConditionFirstBoot=yes will be run and systemd will perform + additional initialization steps, in particular presetting units. + + + + Relation to OSF UUIDs + + Note that the machine ID historically is not an OSF UUID as defined by RFC 4122, nor a Microsoft GUID; however, starting with + systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122. + + In order to maintain compatibility with existing installations, an application requiring a strictly + RFC 4122 compliant UUID should decode the machine ID, and then (non-reversibly) apply the following + operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID. With id being an + unsigned character array: + + /* Set UUID version to 4 --- truly random generation */ +id[6] = (id[6] & 0x0F) | 0x40; +/* Set the UUID variant to DCE */ +id[8] = (id[8] & 0x3F) | 0x80; + + (This code is inspired by + generate_random_uuid() of + drivers/char/random.c from the Linux kernel + sources.) + + + + + History + + The simple configuration file format of + /etc/machine-id originates in the + /var/lib/dbus/machine-id file introduced by + D-Bus. In fact, this latter file might be a symlink to + /etc/machine-id. + + + + See Also + + systemd1, + systemd-machine-id-setup1, + gethostid3, + hostname5, + machine-info5, + os-release5, + sd-id1283, + sd_id128_get_machine3, + systemd-firstboot1 + + + + -- cgit v1.2.3