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. 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

FIRST BOOT SEMANTICS

95       /etc/machine-id is used to decide whether a boot is the first one. The
96       rules are as follows:
97
98        1. The kernel command argument systemd.condition-first-boot= may be
99           used to override the autodetection logic, see kernel-command-
100           line(7).
101
102        2. Otherwise, if /etc/machine-id does not exist, this is a first boot.
103           During early boot, systemd will write "uninitialized\n" to this
104           file and overmount a temporary file which contains the actual
105           machine ID. Later (after first-boot-complete.target has been
106           reached), the real machine ID will be written to disk.
107
108        3. If /etc/machine-id contains the string "uninitialized", a boot is
109           also considered the first boot. The same mechanism as above
110           applies.
111
112        4. If /etc/machine-id exists and is empty, a boot is not considered
113           the first boot.  systemd will still bind-mount a file containing
114           the actual machine-id over it and later try to commit it to disk
115           (if /etc/ is writable).
116
117        5. If /etc/machine-id already contains a valid machine-id, this is not
118           a first boot.
119
120       If according to the above rules a first boot is detected, units with
121       ConditionFirstBoot=yes will be run and systemd will perform additional
122       initialization steps, in particular presetting units.
123

RELATION TO OSF UUIDS

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

HISTORY

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

NOTES

155        1. Safely Building Images
156           https://systemd.io/BUILDING_IMAGES
157
158        2. RFC 4122
159           https://tools.ietf.org/html/rfc4122
160
161
162
163systemd 253                                                      MACHINE-ID(5)