shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2025-01-07 17:17:44 +03:00
Code

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

Browse Source 
(cherry picked from commit 74a79c657e)
(cherry picked from commit 07ba9da0bc)
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2017-10-18 18:47:34 +02:00
parent a33807a581
commit 3a5ffde667
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>
<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 <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 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 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 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 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>
<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>
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>
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>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>
<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>