picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: describe how machine-id should be initialized (#7051)

Browse source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2017-10-18 18:47:34 +02:00 committed by Lennart Poettering
parent b5487fa0b6
commit 74a79c657e
1 changed files with 68 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

88
man/machine-id.xml
View file

@ -53,18 +53,26 @@
<refsect1> <refsect1>
<title>Description</title> <title>Description</title>
<para>The <filename>/etc/machine-id</filename> file contains the unique machine ID of the local <para>The <filename>/etc/machine-id</filename> file contains the unique machine ID of
system that is set during installation. The machine ID is a single newline-terminated, the local system that is set during installation or boot. The machine ID is a single
hexadecimal, 32-character, lowercase ID. When decoded from hexadecimal, this corresponds to a newline-terminated, hexadecimal, 32-character, lowercase ID. When decoded from
16-byte/128-bit value.</para> 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 <para>The machine ID is usually generated from a random source during system
during system installation and stays constant for all subsequent installation or first boot and stays constant for all subsequent boots. Optionally,
boots. Optionally, for stateless systems, it is generated during for stateless systems, it is generated during runtime during early boot if necessary.
runtime at early boot if it is found to be empty.</para> </para>
<para>The machine ID does not change based on local or network configuration or when hardware is <para>The machine ID may be set, for example when network booting, with the
replaced. Due to this and its greater length, it is a more useful replacement for 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> <citerefentry project='man-pages'><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
call that POSIX specifies.</para> call that POSIX specifies.</para>
@ -79,19 +87,59 @@
the original machine ID from the application-specific one. The the original machine ID from the application-specific one. The
<citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry> <citerefentry><refentrytitle>sd_id128_get_machine_app_specific</refentrytitle><manvolnum>3</manvolnum></citerefentry>
API provides an implementation of such an algorithm.</para> API provides an implementation of such an algorithm.</para>
</refsect1>
<para>The <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>
<citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool may be used by installer tools to initialize the machine ID may be used by installer tools to initialize the machine ID at install time, but
at install time. Use <filename>/etc/machine-id</filename> may also be written using any other means.
<citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para>
to initialize it on mounted (but not booted) system images.</para>
<para>The machine-id may also be set, for example when network <para>For operating system images which are created once and used on multiple
booting, by setting the <varname>systemd.machine_id=</varname> machines, for example for containers or in the cloud,
kernel command line parameter or passing the option <filename>/etc/machine-id</filename> should be an empty file in the generic file
<option>--machine-id=</option> to systemd. A machine-id may not system image. An ID will be generated during boot and saved to this file if
be set to all zeros.</para> 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>
<refsect1> <refsect1>