1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"systemd-machine-id-setup"
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
13 <title>systemd-machine-id-setup
</title>
14 <productname>systemd
</productname>
18 <refentrytitle>systemd-machine-id-setup
</refentrytitle>
19 <manvolnum>1</manvolnum>
23 <refname>systemd-machine-id-setup
</refname>
24 <refpurpose>Initialize the machine ID in /etc/machine-id
</refpurpose>
29 <command>systemd-machine-id-setup
</command>
34 <title>Description
</title>
36 <para><command>systemd-machine-id-setup
</command> may be used by
37 system installer tools to initialize the machine ID stored in
38 <filename>/etc/machine-id
</filename> at install time, with a
39 provisioned or randomly generated ID. See
40 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
41 for more information about this file.
</para>
43 <para>If the tool is invoked without the
<option>--commit
</option>
44 switch,
<filename>/etc/machine-id
</filename> is initialized with a
45 valid, new machined ID if it is missing or empty. The new machine
46 ID will be acquired in the following fashion:
</para>
49 <listitem><para>If a valid D-Bus machine ID is already
50 configured for the system, the D-Bus machine ID is copied and
51 used to initialize the machine ID in
52 <filename>/etc/machine-id
</filename>.
</para></listitem>
54 <listitem><para>If run inside a KVM virtual machine and a UUID
55 is configured (via the
<option>-uuid
</option>
56 option), this UUID is used to initialize the machine ID. The
57 caller must ensure that the UUID passed is sufficiently unique
58 and is different for every booted instance of the
61 <listitem><para>Similarly, if run inside a Linux container
62 environment and a UUID is configured for the container, this is
63 used to initialize the machine ID. For details, see the
64 documentation of the
<ulink
65 url=
"https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
66 Interface
</ulink>.
</para></listitem>
68 <listitem><para>Otherwise, a new ID is randomly
69 generated.
</para></listitem>
72 <para>The
<option>--commit
</option> switch may be used to commit a
73 transient machined ID to disk, making it persistent. For details,
77 <citerefentry><refentrytitle>systemd-firstboot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
78 to initialize the machine ID on mounted (but not booted) system
84 <title>Options
</title>
86 <para>The following options are understood:
</para>
91 <term><option>--root=
<replaceable>root
</replaceable></option></term>
92 <listitem><para>Takes a directory path as argument. All paths
93 operated will be prefixed with the given alternate
94 <replaceable>root
</replaceable> path, including the path for
95 <filename>/etc/machine-id
</filename> itself.
</para></listitem>
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>
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>
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>
125 <term><option>--print
</option></term>
127 <listitem><para>Print the machine ID generated or committed after the operation is complete.
</para></listitem>
130 <xi:include href=
"standard-options.xml" xpointer=
"help" />
131 <xi:include href=
"standard-options.xml" xpointer=
"version" />
137 <title>Exit status
</title>
139 <para>On success,
0 is returned, a non-zero failure code
144 <title>See Also
</title>
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>