1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="systemd-machine-id-setup"
7    xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>systemd-machine-id-setup</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>systemd-machine-id-setup</refentrytitle>
16    <manvolnum>1</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>systemd-machine-id-setup</refname>
21    <refpurpose>Initialize the machine ID in /etc/machine-id</refpurpose>
22  </refnamediv>
23
24  <refsynopsisdiv>
25    <cmdsynopsis>
26      <command>systemd-machine-id-setup</command>
27    </cmdsynopsis>
28  </refsynopsisdiv>
29
30  <refsect1>
31    <title>Description</title>
32
33    <para><command>systemd-machine-id-setup</command> may be used by
34    system installer tools to initialize the machine ID stored in
35    <filename>/etc/machine-id</filename> at install time, with a
36    provisioned or randomly generated ID. See
37    <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
38    for more information about this file.</para>
39
40    <para>If the tool is invoked without the <option>--commit</option>
41    switch, <filename>/etc/machine-id</filename> is initialized with a
42    valid, new machine ID if it is missing or empty. The new machine
43    ID will be acquired in the following fashion:</para>
44
45    <orderedlist>
46      <listitem><para>If a valid D-Bus machine ID is already
47      configured for the system, the D-Bus machine ID is copied and
48      used to initialize the machine ID in
49      <filename>/etc/machine-id</filename>.</para></listitem>
50
51      <listitem><para>If run inside a KVM virtual machine and a UUID
52      is configured (via the <option>-uuid</option>
53      option), this UUID is used to initialize the machine ID. The
54      caller must ensure that the UUID passed is sufficiently unique
55      and is different for every booted instance of the
56      VM.</para></listitem>
57
58      <listitem><para>Similarly, if run inside a Linux container environment and a UUID is configured for the
59      container, this is used to initialize the machine ID. For details, see the documentation of the <ulink
60      url="https://systemd.io/CONTAINER_INTERFACE">Container Interface</ulink>.</para></listitem>
61
62      <listitem><para>Otherwise, a new ID is randomly
63      generated.</para></listitem>
64    </orderedlist>
65
66    <para>The <option>--commit</option> switch may be used to commit a
67    transient machined ID to disk, making it persistent. For details,
68    see below.</para>
69
70    <para>Use
71    <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
72    to initialize the machine ID on mounted (but not booted) system
73    images.</para>
74
75  </refsect1>
76
77  <refsect1>
78    <title>Options</title>
79
80    <para>The following options are understood:</para>
81
82    <variablelist>
83
84      <varlistentry>
85        <term><option>--root=<replaceable>path</replaceable></option></term>
86        <listitem><para>Takes a directory path as argument. All paths operated on will be prefixed with the
87        given alternate <replaceable>root</replaceable> path, including the path for
88        <filename>/etc/machine-id</filename> itself.</para></listitem>
89      </varlistentry>
90
91      <varlistentry>
92        <term><option>--image=<replaceable>path</replaceable></option></term>
93        <listitem><para>Takes a path to a device node or regular file as argument. This is similar to
94        <option>--root=</option> as described above, but operates on a disk image instead of a directory
95        tree.</para></listitem>
96      </varlistentry>
97
98      <varlistentry>
99        <term><option>--commit</option></term>
100        <listitem><para>Commit a transient machine ID to disk. This
101        command may be used to convert a transient machine ID into a
102        persistent one. A transient machine ID file is one that was
103        bind mounted from a memory file system (usually
104        <literal>tmpfs</literal>) to
105        <filename>/etc/machine-id</filename> during the early phase of
106        the boot process. This may happen because
107        <filename>/etc/</filename> is initially read-only and was
108        missing a valid machine ID file at that point.</para>
109
110        <para>This command will execute no operation if
111        <filename>/etc/machine-id</filename> is not mounted from a
112        memory file system, or if <filename>/etc/</filename> is
113        read-only. The command will write the current transient
114        machine ID to disk and unmount the
115        <filename>/etc/machine-id</filename> mount point in a
116        race-free manner to ensure that this file is always valid and
117        accessible for other processes.</para>
118
119        <para>This command is primarily used by the
120        <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
121        early boot service.</para></listitem>
122      </varlistentry>
123
124      <varlistentry>
125        <term><option>--print</option></term>
126
127        <listitem><para>Print the machine ID generated or committed after the operation is complete.</para></listitem>
128      </varlistentry>
129
130      <xi:include href="standard-options.xml" xpointer="help" />
131      <xi:include href="standard-options.xml" xpointer="version" />
132    </variablelist>
133
134  </refsect1>
135
136  <refsect1>
137    <title>Exit status</title>
138
139    <para>On success, 0 is returned, a non-zero failure code
140    otherwise.</para>
141  </refsect1>
142
143  <refsect1>
144    <title>See Also</title>
145    <para>
146      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
147      <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
148      <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
149      <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
150      <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
151    </para>
152  </refsect1>
153
154</refentry>
155