mirror of
https://github.com/systemd/systemd.git
synced 2024-11-24 10:43:35 +08:00
148 lines
6.3 KiB
XML
148 lines
6.3 KiB
XML
<?xml version='1.0'?> <!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<!--
|
|
This file is part of systemd.
|
|
|
|
Copyright 2010 Lennart Poettering
|
|
|
|
systemd is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or
|
|
(at your option) any later version.
|
|
|
|
systemd is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
|
-->
|
|
|
|
<refentry id="machine-id">
|
|
<refentryinfo>
|
|
<title>machine-id</title>
|
|
<productname>systemd</productname>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<contrib>Developer</contrib>
|
|
<firstname>Lennart</firstname>
|
|
<surname>Poettering</surname>
|
|
<email>lennart@poettering.net</email>
|
|
</author>
|
|
</authorgroup>
|
|
</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. 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
|
|
<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.</para>
|
|
|
|
<para>The
|
|
<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>
|
|
</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>
|