machine-id.xml revision 5430f7f2bc7330f3088b894166bf3524a067e3d8
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering This file is part of systemd.
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering Copyright 2010 Lennart Poettering
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering systemd is free software; you can redistribute it and/or modify it
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering (at your option) any later version.
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering systemd is distributed in the hope that it will be useful, but
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <refentryinfo>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering </authorgroup>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering </refentryinfo>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <refentrytitle>machine-id</refentrytitle>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <refpurpose>local machine ID configuration file</refpurpose>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <refsynopsisdiv>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <para><filename>/etc/machine-id</filename></para>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering </refsynopsisdiv>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <para>The <filename>/etc/machine-id</filename> file
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering contains the unique machine id of the local system
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering that is set during installation. The machine ID is a
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering single newline-terminated, hexadecimal, lowercase 32
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering character machine ID string. (When decoded from
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering hexadecimal this corresponds with a 16 byte/128 bit
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering string.)</para>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <para>The machine ID is usually generated from a
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering random source during system installation and stays
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering constant for all subsequent boots. Optionally, for
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering stateless systems it is generated during runtime at
811ad2b3a4f0a53c22ac26a19d1b3e93afcbd32fLennart Poettering boot if it is found to be empty.</para>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <para>The machine ID does not change based on user
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering configuration, or when hardware is replaced.</para>
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <para>This machine ID adheres to the same format and
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering logic as the D-Bus machine ID.</para>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <para>Programs may use this ID to identify the host
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering with a globally unique ID in the network, that does
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering not change even if the local network configuration
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering changes. Due to this and its greater length it is
7640a5de1b3ffe6547200ad204d14e4f067caf4fLennart Poettering a more useful replacement for the
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering call POSIX specifies.</para>
44f44a29cc1346c0783d679374ce98d81bf6400cLennart Poettering <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>
44f44a29cc1346c0783d679374ce98d81bf6400cLennart Poettering tool may be used by installer tools to initialize the
44f44a29cc1346c0783d679374ce98d81bf6400cLennart Poettering machine ID at install time.</para>
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <para>Note that the machine ID historically is not an
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering OSF UUID as defined by <ulink
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering url="http://tools.ietf.org/html/rfc4122">RFC
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering 4122</ulink>, nor a Microsoft GUID. Starting with
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering systemd v30 newly generated machine IDs however do
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering qualify as v4 UUIDs.</para>
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <para>In order to maintain compatibility with existing
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering installations, an application requiring a UUID should
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering decode the machine ID, and then apply the following
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering operations to turn it into a valid OSF v4 UUID. With
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <literal>id</literal> being an unsigned character
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <programlisting>/* Set UUID version to 4 --- truly random generation */
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poetteringid[6] = (id[6] & 0x0F) | 0x40;
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering/* Set the UUID variant to DCE */
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poetteringid[8] = (id[8] & 0x3F) | 0x80;</programlisting>
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <para>(This code is inspired by
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <literal>generate_random_uuid()</literal> of
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering <filename>drivers/char/random.c</filename> from the
8d41a963d66e54807e8b0fa69700107e39cf485aLennart Poettering kernel sources.)</para>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <para>The simple configuration file format of
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <filename>/etc/machine-id</filename> originates in the
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <filename>/var/lib/dbus/machine-id</filename> file
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering introduced by D-Bus. In fact this latter file might be a
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <varname>/etc/machine-id</varname>.</para>
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
44f44a29cc1346c0783d679374ce98d81bf6400cLennart Poettering <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
d7ccca2e3f86feb81a48e243d8bad78814659a74Lennart Poettering <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
7640a5de1b3ffe6547200ad204d14e4f067caf4fLennart Poettering <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
7640a5de1b3ffe6547200ad204d14e4f067caf4fLennart Poettering <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
7640a5de1b3ffe6547200ad204d14e4f067caf4fLennart Poettering <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>