1MACHINE-ID(5) machine-id MACHINE-ID(5)
2
3
4
6 machine-id - Local machine ID configuration file
7
9 /etc/machine-id
10
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
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. Also see Safely Building
70 Images[1].
71
72 systemd-firstboot(1) may be used to initialize /etc/machine-id on
73 mounted (but not booted) system images.
74
75 When a machine is booted with systemd(1) the ID of the machine will be
76 established. If systemd.machine_id= or --machine-id= options (see first
77 section) are specified, this value will be used. Otherwise, the value
78 in /etc/machine-id will be used. If this file is empty or missing,
79 systemd will attempt to use the D-Bus machine ID from
80 /var/lib/dbus/machine-id, the value of the kernel command line option
81 container_uuid, the KVM DMI product_uuid or the devicetree vm,uuid (on
82 KVM systems), and finally a randomly generated UUID.
83
84 After the machine ID is established, systemd(1) will attempt to save it
85 to /etc/machine-id. If this fails, it will attempt to bind-mount a
86 temporary file over /etc/machine-id. It is an error if the file system
87 is read-only and does not contain a (possibly empty) /etc/machine-id
88 file.
89
90 systemd-machine-id-commit.service(8) will attempt to write the machine
91 ID to the file system if /etc/machine-id or /etc/ are read-only during
92 early boot but become writable later on.
93
95 /etc/machine-id is used to decide whether a boot is the first one. The
96 rules are as follows:
97
98 1. If /etc/machine-id does not exist, this is a first boot. During
99 early boot, systemd will write "uninitialized\n" to this file and
100 overmount a temporary file which contains the actual machine ID.
101 Later (after first-boot-complete.target has been reached), the real
102 machine ID will be written to disk.
103
104 2. If /etc/machine-id contains the string "uninitialized", a boot is
105 also considered the first boot. The same mechanism as above
106 applies.
107
108 3. If /etc/machine-id exists and is empty, a boot is not considered
109 the first boot. systemd will still bind-mount a file containing
110 the actual machine-id over it and later try to commit it to disk
111 (if /etc/ is writable).
112
113 4. If /etc/machine-id already contains a valid machine-id, this is not
114 a first boot.
115
116 If by any of the above rules, a first boot is detected, units with
117 ConditionFirstBoot=yes will be run.
118
120 Note that the machine ID historically is not an OSF UUID as defined by
121 RFC 4122[2], nor a Microsoft GUID; however, starting with systemd v30,
122 newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as
123 per RFC 4122.
124
125 In order to maintain compatibility with existing installations, an
126 application requiring a strictly RFC 4122 compliant UUID should decode
127 the machine ID, and then (non-reversibly) apply the following
128 operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID.
129 With "id" being an unsigned character array:
130
131 /* Set UUID version to 4 --- truly random generation */
132 id[6] = (id[6] & 0x0F) | 0x40;
133 /* Set the UUID variant to DCE */
134 id[8] = (id[8] & 0x3F) | 0x80;
135
136 (This code is inspired by "generate_random_uuid()" of
137 drivers/char/random.c from the Linux kernel sources.)
138
140 The simple configuration file format of /etc/machine-id originates in
141 the /var/lib/dbus/machine-id file introduced by D-Bus. In fact, this
142 latter file might be a symlink to /etc/machine-id.
143
145 systemd(1), systemd-machine-id-setup(1), gethostid(3), hostname(5),
146 machine-info(5), os-release(5), sd-id128(3), sd_id128_get_machine(3),
147 systemd-firstboot(1)
148
150 1. Safely Building Images
151 https://systemd.io/BUILDING_IMAGES
152
153 2. RFC 4122
154 https://tools.ietf.org/html/rfc4122
155
156
157
158systemd 251 MACHINE-ID(5)