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 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 either missing or an empty file in the generic file system
65       image (the difference between the two options is described under "First
66       Boot Semantics" below). An ID will be generated during boot and saved
67       to this file if possible. Having an empty file in place is useful
68       because it allows a temporary file to be bind-mounted over the real
69       file, in case the image is used read-only.
70
71       systemd-firstboot(1) may be used to initialize /etc/machine-id on
72       mounted (but not booted) system images.
73
74       When a machine is booted with systemd(1) the ID of the machine will be
75       established. If systemd.machine_id= or --machine-id= options (see first
76       section) are specified, this value will be used. Otherwise, the value
77       in /etc/machine-id will be used. If this file is empty or missing,
78       systemd will attempt to use the D-Bus machine ID from
79       /var/lib/dbus/machine-id, the value of the kernel command line option
80       container_uuid, the KVM DMI product_uuid or the devicetree vm,uuid (on
81       KVM systems), and finally a randomly generated UUID.
82
83       After the machine ID is established, systemd(1) will attempt to save it
84       to /etc/machine-id. If this fails, it will attempt to bind-mount a
85       temporary file over /etc/machine-id. It is an error if the file system
86       is read-only and does not contain a (possibly empty) /etc/machine-id
87       file.
88
89       systemd-machine-id-commit.service(8) will attempt to write the machine
90       ID to the file system if /etc/machine-id or /etc/ are read-only during
91       early boot but become writable later on.
92

FIRST BOOT SEMANTICS

94       /etc/machine-id is used to decide whether a boot is the first one. The
95       rules are as follows:
96
97        1. If /etc/machine-id does not exist, this is a first boot. During
98           early boot, systemd will write "uninitialized\n" to this file and
99           overmount a temporary file which contains the actual machine ID.
100           Later (after first-boot-complete.target has been reached), the real
101           machine ID will be written to disk.
102
103        2. If /etc/machine-id contains the string "uninitialized", a boot is
104           also considered the first boot. The same mechanism as above
105           applies.
106
107        3. If /etc/machine-id exists and is empty, a boot is not considered
108           the first boot.  systemd will still bind-mount a file containing
109           the actual machine-id over it and later try to commit it to disk
110           (if /etc/ is writable).
111
112        4. If /etc/machine-id already contains a valid machine-id, this is not
113           a first boot.
114
115       If by any of the above rules, a first boot is detected, units with
116       ConditionFirstBoot=yes will be run.
117

RELATION TO OSF UUIDS

119       Note that the machine ID historically is not an OSF UUID as defined by
120       RFC 4122[1], nor a Microsoft GUID; however, starting with systemd v30,
121       newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as
122       per RFC 4122.
123
124       In order to maintain compatibility with existing installations, an
125       application requiring a strictly RFC 4122 compliant UUID should decode
126       the machine ID, and then (non-reversibly) apply the following
127       operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID.
128       With "id" being an unsigned character array:
129
130           /* Set UUID version to 4 --- truly random generation */
131           id[6] = (id[6] & 0x0F) | 0x40;
132           /* Set the UUID variant to DCE */
133           id[8] = (id[8] & 0x3F) | 0x80;
134
135       (This code is inspired by "generate_random_uuid()" of
136       drivers/char/random.c from the Linux kernel sources.)
137

HISTORY

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

NOTES

149        1. RFC 4122
150           https://tools.ietf.org/html/rfc4122
151
152
153
154systemd 249                                                      MACHINE-ID(5)