<?xml version='1.0'?> <!--*-nxml-*-->

<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="machine-id">

<refentryinfo>

<title>/etc/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, lowercase 32

character machine ID string. (When decoded from

hexadecimal this corresponds with a 16 byte/128 bit

string.)</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

boot if it is found to be empty.</para>

<para>The machine ID does not change based on user

configuration, or when hardware is replaced.</para>

<para>This machine ID adheres to the same format and

logic as the D-Bus machine ID.</para>

<para>Programs may use this ID to identify the host

with a globally unique ID in the network, that does

not change even if the local network configuration

changes. Due to this and its greater length it is

a more useful replacement for the

<citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>

call POSIX specifies.</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="http://tools.ietf.org/html/rfc4122">RFC

4122</ulink>, nor a Microsoft GUID. Starting with

systemd v30 newly generated machine IDs however 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] &amp; 0x0F) | 0x40;

/* Set the UUID variant to DCE */

id[8] = (id[8] &amp; 0x3F) | 0x80;</programlisting>

<para>(This code is inspired by

<literal>generate_random_uuid()</literal> of

<filename>drivers/char/random.c</filename> from the

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

<varname>/etc/machine-id</varname>.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><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>

</para>

</refsect1>

</refentry>