X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=man%2Fmachine-id.xml;h=f4d94e880097b751ac36f63e1c2751c6f19a6eb9;hb=f789e0b4f891800557c74c385d0f61a0164cb16f;hp=d318ec54eca78335b06e5a1cc582866db7b2508b;hpb=afd806fc480dc8d17b6a7837e474b2caa8a5c850;p=thirdparty%2Fsystemd.git diff --git a/man/machine-id.xml b/man/machine-id.xml index d318ec54eca..f4d94e88009 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -1,39 +1,12 @@ - - - + machine-id systemd - - - - Developer - Lennart - Poettering - lennart@poettering.net - - @@ -53,43 +26,93 @@ 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 machine ID string. When - decoded from hexadecimal, this corresponds with a 16-byte/128-bit - string. - - 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 /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 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 user configuration - or when hardware is replaced. + 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. - Programs may use this ID to identify the host with a - globally unique ID in the network, which does not change even if - the local network configuration changes. Due to this and its - greater length, it is a more useful replacement for the - gethostid3 - call that POSIX specifies. + 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. - The + 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. - - 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. + 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 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 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.