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 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
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
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
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
115 systemd(1), systemd-machine-id-setup(1), gethostid(3), hostname(5),
116 machine-info(5), os-release(5), sd-id128(3), sd_id128_get_machine(3),
117 systemd-firstboot(1)
118
120 1. RFC 4122
121 https://tools.ietf.org/html/rfc4122
122
123
124
125systemd 239 MACHINE-ID(5)