diff options
Diffstat (limited to 'man/machine-id.xml')
| -rw-r--r-- | man/machine-id.xml | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/man/machine-id.xml b/man/machine-id.xml new file mode 100644 index 0000000..f61634f --- /dev/null +++ b/man/machine-id.xml @@ -0,0 +1,198 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="machine-id"> + <refentryinfo> + <title>machine-id</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>machine-id</refentrytitle> + <manvolnum>5</manvolnum> + </refmeta> + + <refnamediv> + <refname>machine-id</refname> + <refpurpose>Local machine ID configuration file</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>/etc/machine-id</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <filename>/etc/machine-id</filename> 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.</para> + + <para>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. + </para> + + <para>The machine ID may be set, for example when network booting, with the + <varname>systemd.machine_id=</varname> kernel command line parameter or by passing the + option <option>--machine-id=</option> to systemd. An ID specified in this manner + has higher priority and will be used instead of the ID stored in + <filename>/etc/machine-id</filename>.</para> + + <para>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 + <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call that POSIX specifies.</para> + + <para>This machine ID adheres to the same format and logic as the + D-Bus machine ID.</para> + + <para>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 + <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry> + API provides an implementation of such an algorithm.</para> + </refsect1> + + <refsect1> + <title>Initialization</title> + + <para>Each machine should have a non-empty ID in normal operation. The ID of each + machine should be unique. To achieve those objectives, + <filename>/etc/machine-id</filename> can be initialized in a few different ways. + </para> + + <para>For normal operating system installations, where a custom image is created for a + specific machine, <filename>/etc/machine-id</filename> should be populated during + installation.</para> + + <para> + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + may be used by installer tools to initialize the machine ID at install time, but + <filename>/etc/machine-id</filename> may also be written using any other means. + </para> + + <para>For operating system images which are created once and used on multiple + machines, for example for containers or in the cloud, + <filename>/etc/machine-id</filename> 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 + useful because it allows a temporary file to be bind-mounted over the real file, in case the image is + used read-only.</para> + + <para><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + may be used to initialize <filename>/etc/machine-id</filename> on mounted (but not + booted) system images.</para> + + <para>When a machine is booted with + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + the ID of the machine will be established. If <varname>systemd.machine_id=</varname> + or <option>--machine-id=</option> options (see first section) are specified, this + value will be used. Otherwise, the value in <filename>/etc/machine-id</filename> will + be used. If this file is empty or missing, <filename>systemd</filename> will attempt + to use the D-Bus machine ID from <filename>/var/lib/dbus/machine-id</filename>, the + value of the kernel command line option <varname>container_uuid</varname>, the KVM DMI + <filename>product_uuid</filename> or the devicetree <filename>vm,uuid</filename> + (on KVM systems), and finally a randomly generated UUID.</para> + + <para>After the machine ID is established, + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> + will attempt to save it to <filename>/etc/machine-id</filename>. If this fails, it + will attempt to bind-mount a temporary file over <filename>/etc/machine-id</filename>. + It is an error if the file system is read-only and does not contain a (possibly empty) + <filename>/etc/machine-id</filename> file.</para> + + <para><citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + will attempt to write the machine ID to the file system if + <filename>/etc/machine-id</filename> or <filename>/etc/</filename> are read-only during + early boot but become writable later on.</para> + </refsect1> + + <refsect1> + <title>First Boot Semantics</title> + + <para><filename>/etc/machine-id</filename> is used to decide whether a boot is the first one. The rules + are as follows:</para> + + <orderedlist> + <listitem><para>If <filename>/etc/machine-id</filename> does not exist, this is a first boot. During + early boot, <command>systemd</command> will write <literal>uninitialized\n</literal> to this file and overmount + a temporary file which contains the actual machine ID. Later (after <filename>first-boot-complete.target</filename> + has been reached), the real machine ID will be written to disk.</para></listitem> + + <listitem><para>If <filename>/etc/machine-id</filename> contains the string <literal>uninitialized</literal>, + a boot is also considered the first boot. The same mechanism as above applies.</para></listitem> + + <listitem><para>If <filename>/etc/machine-id</filename> exists and is empty, a boot is + <emphasis>not</emphasis> considered the first boot. <command>systemd</command> will still bind-mount a file + containing the actual machine-id over it and later try to commit it to disk (if <filename>/etc/</filename> is + writable).</para></listitem> + + <listitem><para>If <filename>/etc/machine-id</filename> already contains a valid machine-id, this is + not a first boot.</para></listitem> + </orderedlist> + + <para>If by any of the above rules, a first boot is detected, units with <varname>ConditionFirstBoot=yes</varname> + will be run.</para> + </refsect1> + + <refsect1> + <title>Relation to OSF UUIDs</title> + + <para>Note that the machine ID historically is not an OSF UUID as + defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC + 4122</ulink>, nor a Microsoft GUID; however, starting with systemd + v30, newly generated machine IDs do qualify as v4 UUIDs.</para> + + <para>In order to maintain compatibility with existing + installations, an application requiring a UUID should decode the + machine ID, and then apply the following operations to turn it + into a valid OSF v4 UUID. With <literal>id</literal> being an + unsigned character array:</para> + + <programlisting>/* Set UUID version to 4 --- truly random generation */ +id[6] = (id[6] & 0x0F) | 0x40; +/* Set the UUID variant to DCE */ +id[8] = (id[8] & 0x3F) | 0x80;</programlisting> + + <para>(This code is inspired by + <literal>generate_random_uuid()</literal> of + <filename>drivers/char/random.c</filename> from the Linux kernel + sources.)</para> + + </refsect1> + + <refsect1> + <title>History</title> + + <para>The simple configuration file format of + <filename>/etc/machine-id</filename> originates in the + <filename>/var/lib/dbus/machine-id</filename> file introduced by + D-Bus. In fact, this latter file might be a symlink to + <filename>/etc/machine-id</filename>.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |