machine-id(5)

1MACHINE-ID(5)                     machine-id                     MACHINE-ID(5)
2
3
4

NAME

6       machine-id - Local machine ID configuration file
7

SYNOPSIS

9       /etc/machine-id
10

DESCRIPTION

12       The /etc/machine-id file contains the unique machine ID of the local
13       system that is set during installation or boot. The machine ID is a
14       single newline-terminated, hexadecimal, 32-character, lowercase ID.
15       When decoded from hexadecimal, this corresponds to a 16-byte/128-bit
16       value. This ID may not be all zeros.
17
18       The machine ID is usually generated from a random source during system
19       installation or first boot and stays constant for all subsequent boots.
20       Optionally, for stateless systems, it is generated during runtime
21       during early boot if necessary.
22
23       The machine ID may be set, for example when network booting, with the
24       systemd.machine_id= kernel command line parameter or by passing the
25       option --machine-id= to systemd. An ID is specified in this manner has
26       higher priority and will be used instead of the ID stored in
27       /etc/machine-id.
28
29       The machine ID does not change based on local or network configuration
30       or when hardware is replaced. Due to this and its greater length, it is
31       a more useful replacement for the gethostid(3) call that POSIX
32       specifies.
33
34       This machine ID adheres to the same format and logic as the D-Bus
35       machine ID.
36
37       This ID uniquely identifies the host. It should be considered
38       "confidential", and must not be exposed in untrusted environments, in
39       particular on the network. If a stable unique identifier that is tied
40       to the machine is needed for some application, the machine ID or any
41       part of it must not be used directly. Instead the machine ID should be
42       hashed with a cryptographic, keyed hash function, using a fixed,
43       application-specific key. That way the ID will be properly unique, and
44       derived in a constant way from the machine ID but there will be no way
45       to retrieve the original machine ID from the application-specific one.
46       The sd_id128_get_machine_app_specific(3) API provides an implementation
47       of such an algorithm.
48

INITIALIZATION

50       Each machine should have a non-empty ID in normal operation. The ID of
51       each machine should be unique. To achieve those objectives,
52       /etc/machine-id can be initialized in a few different ways.
53
54       For normal operating system installations, where a custom image is
55       created for a specific machine, /etc/machine-id should be populated
56       during installation.
57
58       systemd-machine-id-setup(1) may be used by installer tools to
59       initialize the machine ID at install time, but /etc/machine-id may also
60       be written using any other means.
61
62       For operating system images which are created once and used on multiple
63       machines, for example for containers or in the cloud, /etc/machine-id
64       should be an empty file in the generic file system image. An ID will be
65       generated during boot and saved to this file if possible. Having an
66       empty file in place is useful because it allows a temporary file to be
67       bind-mounted over the real file, in case the image is used read-only.
68
69       systemd-firstboot(1) may be used to initialize /etc/machine-id on
70       mounted (but not booted) system images.
71
72       When a machine is booted with systemd(1) the ID of the machine will be
73       established. If systemd.machine_id= or --machine-id= options (see first
74       section) are specified, this value will be used. Otherwise, the value
75       in /etc/machine-id will be used. If this file is empty or missing,
76       systemd will attempt to use the D-Bus machine ID from
77       /var/lib/dbus/machine-id, the value of the kernel command line option
78       container_uuid, the KVM DMI product_uuid (on KVM systems), and finally
79       a randomly generated UUID.
80
81       After the machine ID is established, systemd(1) will attempt to save it
82       to /etc/machine-id. If this fails, it will attempt to bind-mount a
83       temporary file over /etc/machine-id. It is an error if the file system
84       is read-only and does not contain a (possibly empty) /etc/machine-id
85       file.
86
87       systemd-machine-id-commit.service(8) will attempt to write the machine
88       ID to the file system if /etc/machine-id or /etc are read-only during
89       early boot but become writable later on.
90

RELATION TO OSF UUIDS

92       Note that the machine ID historically is not an OSF UUID as defined by
93       RFC 4122[1], nor a Microsoft GUID; however, starting with systemd v30,
94       newly generated machine IDs do qualify as v4 UUIDs.
95
96       In order to maintain compatibility with existing installations, an
97       application requiring a UUID should decode the machine ID, and then
98       apply the following operations to turn it into a valid OSF v4 UUID.
99       With "id" being an unsigned character array:
100
101           /* Set UUID version to 4 --- truly random generation */
102           id[6] = (id[6] & 0x0F) | 0x40;
103           /* Set the UUID variant to DCE */
104           id[8] = (id[8] & 0x3F) | 0x80;
105
106       (This code is inspired by "generate_random_uuid()" of
107       drivers/char/random.c from the Linux kernel sources.)
108

HISTORY

110       The simple configuration file format of /etc/machine-id originates in
111       the /var/lib/dbus/machine-id file introduced by D-Bus. In fact, this
112       latter file might be a symlink to /etc/machine-id.
113

NOTES

120        1. RFC 4122
121           https://tools.ietf.org/html/rfc4122
122
123
124
125systemd 241                                                      MACHINE-ID(5)