Debian Codegraph @

upstream/debian-unstable/man5/machine-id.5

raw
1 '\" t
2 .TH "MACHINE\-ID" "5" "" "systemd 261~rc3" "machine-id"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 machine-id \- Local machine ID configuration file
24 .SH "SYNOPSIS"
25 .PP
26 /etc/machine\-id
27 .SH "DESCRIPTION"
28 .PP
29 The
30 /etc/machine\-id
31 file contains the unique machine ID of the local system that is set during installation or boot\&. The machine ID is a single newline\-terminated, hexadecimal, 32\-character, lowercase ID\&. When decoded from hexadecimal, this corresponds to a 16\-byte/128\-bit value\&. This ID may not be all zeros\&.
32 .PP
33 The machine ID is usually generated from a random source during system installation or first boot and stays constant for all subsequent boots\&. Optionally, for stateless systems, it is generated during runtime during early boot if necessary\&.
34 .PP
35 The machine ID may be set, for example when network booting, with the
36 \fIsystemd\&.machine_id=\fR
37 kernel command line parameter or by passing the option
38 \fB\-\-machine\-id=\fR
39 to systemd\&. An ID specified in this manner has higher priority and will be used instead of the ID stored in
40 /etc/machine\-id\&.
41 .PP
42 The machine ID does not change based on local or network configuration or when hardware is replaced\&. Due to this and its greater length, it is a more useful replacement for the
43 \fBgethostid\fR(3)
44 call that POSIX specifies\&.
45 .PP
46 This machine ID adheres to the same format and logic as the D\-Bus machine ID\&.
47 .PP
48 This ID uniquely identifies the host\&. It should be considered "confidential", and must not be exposed in untrusted environments, in particular on the network\&. If a stable unique identifier that is tied to the machine is needed for some application, the machine ID or any part of it must not be used directly\&. Instead the machine ID should be hashed with a cryptographic, keyed hash function, using a fixed, application\-specific key\&. That way the ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve the original machine ID from the application\-specific one\&. The
49 \fBsd_id128_get_machine_app_specific\fR(3)
50 API provides an implementation of such an algorithm\&.
51 .SH "INITIALIZATION"
52 .PP
53 Each machine should have a non\-empty ID in normal operation\&. The ID of each machine should be unique\&. To achieve those objectives,
54 /etc/machine\-id
55 can be initialized in a few different ways\&.
56 .PP
57 For normal operating system installations, where a custom image is created for a specific machine,
58 /etc/machine\-id
59 should be populated during installation\&.
60 .PP
61 \fBsystemd-machine-id-setup\fR(1)
62 may be used by installer tools to initialize the machine ID at install time, but
63 /etc/machine\-id
64 may also be written using any other means\&.
65 .PP
66 For operating system images which are created once and used on multiple machines, for example for containers or in the cloud,
67 /etc/machine\-id
68 should be either missing or an empty file in the generic file system image (the difference between the two options is described under "First Boot Semantics" below)\&. An ID will be generated during boot and saved to this file if possible\&. Having an empty file in place is recommended because it allows a temporary file to be bind\-mounted over the real file, in case the image is used read\-only and when
69 /etc
70 is mounted read\-only in the early boot\&. Also see
71 \m[blue]\fBSafely Building Images\fR\m[]\&\s-2\u[1]\d\s+2\&.
72 .PP
73 \fBsystemd-firstboot\fR(1)
74 may be used to initialize
75 /etc/machine\-id
76 on mounted (but not booted) system images\&.
77 .PP
78 When a machine is booted with
79 \fBsystemd\fR(1)
80 the ID of the machine will be established\&. If
81 \fIsystemd\&.machine_id=\fR
82 or
83 \fB\-\-machine\-id=\fR
84 options (see first section) are specified, this value will be used\&. Otherwise, the value in
85 /etc/machine\-id
86 will be used\&. If this file is empty or missing,
87 systemd
88 will attempt to use the D\-Bus machine ID from
89 /var/lib/dbus/machine\-id, the value of the kernel command line option
90 \fIcontainer_uuid\fR, the KVM DMI
91 product_uuid
92 or the devicetree
93 vm,uuid
94 (on KVM systems), the Xen hypervisor
95 uuid, and finally a randomly generated UUID\&.
96 \fIsystemd\&.machine_id=firmware\fR
97 can be set to generate the machine ID from the firmware\&.
98 .PP
99 After the machine ID is established,
100 \fBsystemd\fR(1)
101 will attempt to save it to
102 /etc/machine\-id\&. If this fails, it will attempt to bind\-mount a temporary file over
103 /etc/machine\-id\&. It is an error if the file system is read\-only and does not contain a (possibly empty)
104 /etc/machine\-id
105 file\&.
106 .PP
107 \fBsystemd-machine-id-commit.service\fR(8)
108 will attempt to write the machine ID to the file system if
109 /etc/machine\-id
110 or
111 /etc/
112 are read\-only during early boot but become writable later on\&.
113 .SH "FIRST BOOT SEMANTICS"
114 .PP
115 /etc/machine\-id
116 is used to decide whether a boot is the first one\&. The rules are as follows:
117 .sp
118 .RS 4
119 .ie n \{\
120 \h'-04' 1.\h'+01'\c
121 .\}
122 .el \{\
123 .sp -1
124 .IP " 1." 4.2
125 .\}
126 The kernel command argument
127 \fIsystemd\&.condition_first_boot=\fR
128 may be used to override the autodetection logic, see
129 \fBkernel-command-line\fR(7)\&.
130 .RE
131 .sp
132 .RS 4
133 .ie n \{\
134 \h'-04' 2.\h'+01'\c
135 .\}
136 .el \{\
137 .sp -1
138 .IP " 2." 4.2
139 .\}
140 Otherwise, if
141 /etc/machine\-id
142 does not exist, this is a first boot\&. During early boot,
143 \fBsystemd\fR
144 will write
145 "uninitialized\en"
146 to this file and overmount a temporary file which contains the actual machine ID\&. Later (after
147 first\-boot\-complete\&.target
148 has been reached), the real machine ID will be written to disk\&.
149 .RE
150 .sp
151 .RS 4
152 .ie n \{\
153 \h'-04' 3.\h'+01'\c
154 .\}
155 .el \{\
156 .sp -1
157 .IP " 3." 4.2
158 .\}
159 If
160 /etc/machine\-id
161 contains the string
162 "uninitialized", a boot is also considered the first boot\&. The same mechanism as above applies\&.
163 .RE
164 .sp
165 .RS 4
166 .ie n \{\
167 \h'-04' 4.\h'+01'\c
168 .\}
169 .el \{\
170 .sp -1
171 .IP " 4." 4.2
172 .\}
173 If
174 /etc/machine\-id
175 exists and is empty, a boot is
176 \fInot\fR
177 considered the first boot\&.
178 \fBsystemd\fR
179 will still bind\-mount a file containing the actual machine\-id over it and later try to commit it to disk (if
180 /etc/
181 is writable)\&.
182 .RE
183 .sp
184 .RS 4
185 .ie n \{\
186 \h'-04' 5.\h'+01'\c
187 .\}
188 .el \{\
189 .sp -1
190 .IP " 5." 4.2
191 .\}
192 If
193 /etc/machine\-id
194 already contains a valid machine\-id, this is not a first boot\&.
195 .RE
196 .PP
197 If according to the above rules a first boot is detected, units with
198 \fIConditionFirstBoot=yes\fR
199 will be run and
200 \fBsystemd\fR
201 will perform additional initialization steps, in particular presetting units\&.
202 .SH "RELATION TO OSF UUIDS"
203 .PP
204 Note that the machine ID historically is not an OSF UUID as defined by
205 \m[blue]\fBRFC 4122\fR\m[]\&\s-2\u[2]\d\s+2, nor a Microsoft GUID; however, starting with systemd v30, newly generated machine IDs do qualify as Variant 1 Version 4 UUIDs, as per RFC 4122\&.
206 .PP
207 In order to maintain compatibility with existing installations, an application requiring a strictly RFC 4122 compliant UUID should decode the machine ID, and then (non\-reversibly) apply the following operations to turn it into a valid RFC 4122 Variant 1 Version 4 UUID\&. With
208 "id"
209 being an unsigned character array:
210 .sp
211 .if n \{\
212 .RS 4
213 .\}
214 .nf
215 /* Set UUID version to 4 \-\-\- truly random generation */
216 id[6] = (id[6] & 0x0F) | 0x40;
217 /* Set the UUID variant to DCE */
218 id[8] = (id[8] & 0x3F) | 0x80;
219 .fi
220 .if n \{\
221 .RE
222 .\}
223 .PP
224 (This code is inspired by
225 "generate_random_uuid()"
226 of
227 drivers/char/random\&.c
228 from the Linux kernel sources\&.)
229 .SH "HISTORY"
230 .PP
231 The simple configuration file format of
232 /etc/machine\-id
233 originates in the
234 /var/lib/dbus/machine\-id
235 file introduced by D\-Bus\&. In fact, this latter file might be a symlink to
236 /etc/machine\-id\&.
237 .SH "SEE ALSO"
238 .PP
239 \fBsystemd\fR(1), \fBsystemd-machine-id-setup\fR(1), \fBgethostid\fR(3), \fBhostname\fR(5), \fBmachine-info\fR(5), \fBos-release\fR(5), \fBsd-id128\fR(3), \fBsd_id128_get_machine\fR(3), \fBsystemd-firstboot\fR(1)
240 .SH "NOTES"
241 .IP " 1." 4
242 Safely Building Images
243 .RS 4
244 \%https://systemd.io/BUILDING_IMAGES
245 .RE
246 .IP " 2." 4
247 RFC 4122
248 .RS 4
249 \%https://tools.ietf.org/html/rfc4122
250 .RE