diff options
Diffstat (limited to 'man/machine-id.xml')
| -rw-r--r-- | man/machine-id.xml | 94 |
1 files changed, 71 insertions, 23 deletions
diff --git a/man/machine-id.xml b/man/machine-id.xml index 3c261bffcc..e434c89de9 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -53,18 +53,26 @@ <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. 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.</para> - - <para>The machine ID is usually generated from a random source - during system installation and stays constant for all subsequent - boots. Optionally, for stateless systems, it is generated during - runtime at early boot if it is found to be empty.</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 + <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 is 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> @@ -79,19 +87,59 @@ 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 achive 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>The + <para> <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool may be used by installer tools to initialize the machine ID - at install time. Use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize it on mounted (but not booted) system images.</para> - - <para>The machine-id may also be set, for example when network - booting, by setting the <varname>systemd.machine_id=</varname> - kernel command line parameter or passing the option - <option>--machine-id=</option> to systemd. A machine-id may not - be set to all zeros.</para> + 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 an empty file in the generic file + system image. 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 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> (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> |