man/machine-id.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="machine-id">
  10   <refentryinfo>
  11     <title>machine-id</title>
  12     <productname>systemd</productname>
  13
  14     <authorgroup>
  15       <author>
  16         <contrib>Developer</contrib>
  17         <firstname>Lennart</firstname>
  18         <surname>Poettering</surname>
  19         <email>lennart@poettering.net</email>
  20       </author>
  21     </authorgroup>
  22   </refentryinfo>
  23
  24   <refmeta>
  25     <refentrytitle>machine-id</refentrytitle>
  26     <manvolnum>5</manvolnum>
  27   </refmeta>
  28
  29   <refnamediv>
  30     <refname>machine-id</refname>
  31     <refpurpose>Local machine ID configuration file</refpurpose>
  32   </refnamediv>
  33
  34   <refsynopsisdiv>
  35     <para><filename>/etc/machine-id</filename></para>
  36   </refsynopsisdiv>
  37
  38   <refsect1>
  39     <title>Description</title>
  40
  41     <para>The <filename>/etc/machine-id</filename> file contains the unique machine ID of
  42     the local system that is set during installation or boot. The machine ID is a single
  43     newline-terminated, hexadecimal, 32-character, lowercase ID. When decoded from
  44     hexadecimal, this corresponds to a 16-byte/128-bit value. This ID may not be all
  45     zeros.</para>
  46
  47     <para>The machine ID is usually generated from a random source during system
  48     installation or first boot and stays constant for all subsequent boots. Optionally,
  49     for stateless systems, it is generated during runtime during early boot if necessary.
  50     </para>
  51
  52     <para>The machine ID may be set, for example when network booting, with the
  53     <varname>systemd.machine_id=</varname> kernel command line parameter or by passing the
  54     option <option>--machine-id=</option> to systemd. An ID is specified in this manner
  55     has higher priority and will be used instead of the ID stored in
  56     <filename>/etc/machine-id</filename>.</para>
  57
  58     <para>The machine ID does not change based on local or network configuration or when
  59     hardware is replaced. Due to this and its greater length, it is a more useful
  60     replacement for the
  61     <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  62     call that POSIX specifies.</para>
  63
  64     <para>This machine ID adheres to the same format and logic as the
  65     D-Bus machine ID.</para>
  66
  67     <para>This ID uniquely identifies the host. It should be considered "confidential", and must not be exposed in
  68     untrusted environments, in particular on the network. If a stable unique identifier that is tied to the machine is
  69     needed for some application, the machine ID or any part of it must not be used directly. Instead the machine ID
  70     should be hashed with a cryptographic, keyed hash function, using a fixed, application-specific key. That way the
  71     ID will be properly unique, and derived in a constant way from the machine ID but there will be no way to retrieve
  72     the original machine ID from the application-specific one. The
  73     <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  74     API provides an implementation of such an algorithm.</para>
  75   </refsect1>
  76
  77   <refsect1>
  78     <title>Initialization</title>
  79
  80     <para>Each machine should have a non-empty ID in normal operation. The ID of each
  81     machine should be unique. To achieve those objectives,
  82     <filename>/etc/machine-id</filename> can be initialized in a few different ways.
  83     </para>
  84
  85     <para>For normal operating system installations, where a custom image is created for a
  86     specific machine, <filename>/etc/machine-id</filename> should be populated during
  87     installation.</para>
  88
  89     <para>
  90     <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  91     may be used by installer tools to initialize the machine ID at install time, but
  92     <filename>/etc/machine-id</filename> may also be written using any other means.
  93     </para>
  94
  95     <para>For operating system images which are created once and used on multiple
  96     machines, for example for containers or in the cloud,
  97     <filename>/etc/machine-id</filename> should be an empty file in the generic file
  98     system image. An ID will be generated during boot and saved to this file if
  99     possible. Having an empty file in place is useful because it allows a temporary file
 100     to be bind-mounted over the real file, in case the image is used read-only.</para>
 101
 102     <para><citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 103     may be used to initialize <filename>/etc/machine-id</filename> on mounted (but not
 104     booted) system images.</para>
 105
 106     <para>When a machine is booted with
 107     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 108     the ID of the machine will be established. If <varname>systemd.machine_id=</varname>
 109     or <option>--machine-id=</option> options (see first section) are specified, this
 110     value will be used. Otherwise, the value in <filename>/etc/machine-id</filename> will
 111     be used. If this file is empty or missing, <filename>systemd</filename> will attempt
 112     to use the D-Bus machine ID from <filename>/var/lib/dbus/machine-id</filename>, the
 113     value of the kernel command line option <varname>container_uuid</varname>, the KVM DMI
 114     <filename>product_uuid</filename> (on KVM systems), and finally a randomly generated
 115     UUID.</para>
 116
 117     <para>After the machine ID is established,
 118     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 119     will attempt to save it to <filename>/etc/machine-id</filename>. If this fails, it
 120     will attempt to bind-mount a temporary file over <filename>/etc/machine-id</filename>.
 121     It is an error if the file system is read-only and does not contain a (possibly empty)
 122     <filename>/etc/machine-id</filename> file.</para>
 123
 124     <para><citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 125     will attempt to write the machine ID to the file system if
 126     <filename>/etc/machine-id</filename> or <filename>/etc</filename> are read-only during
 127     early boot but become writable later on.</para>
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Relation to OSF UUIDs</title>
 132
 133     <para>Note that the machine ID historically is not an OSF UUID as
 134     defined by <ulink url="https://tools.ietf.org/html/rfc4122">RFC
 135     4122</ulink>, nor a Microsoft GUID; however, starting with systemd
 136     v30, newly generated machine IDs do qualify as v4 UUIDs.</para>
 137
 138     <para>In order to maintain compatibility with existing
 139     installations, an application requiring a UUID should decode the
 140     machine ID, and then apply the following operations to turn it
 141     into a valid OSF v4 UUID. With <literal>id</literal> being an
 142     unsigned character array:</para>
 143
 144     <programlisting>/* Set UUID version to 4 --- truly random generation */
 145 id[6] = (id[6] &amp; 0x0F) | 0x40;
 146 /* Set the UUID variant to DCE */
 147 id[8] = (id[8] &amp; 0x3F) | 0x80;</programlisting>
 148
 149     <para>(This code is inspired by
 150     <literal>generate_random_uuid()</literal> of
 151     <filename>drivers/char/random.c</filename> from the Linux kernel
 152     sources.)</para>
 153
 154   </refsect1>
 155
 156   <refsect1>
 157     <title>History</title>
 158
 159     <para>The simple configuration file format of
 160     <filename>/etc/machine-id</filename> originates in the
 161     <filename>/var/lib/dbus/machine-id</filename> file introduced by
 162     D-Bus. In fact, this latter file might be a symlink to
 163     <filename>/etc/machine-id</filename>.</para>
 164   </refsect1>
 165
 166   <refsect1>
 167       <title>See Also</title>
 168       <para>
 169         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 170         <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 171         <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172         <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 173         <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 174         <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 175         <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 176         <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 177         <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 178       </para>
 179   </refsect1>
 180
 181 </refentry>