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+
8 This file is part of systemd.
10 Copyright 2012 Lennart Poettering
13 <refentry id=
"systemd-machine-id-setup"
14 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
17 <title>systemd-machine-id-setup
</title>
18 <productname>systemd
</productname>
22 <contrib>Developer
</contrib>
23 <firstname>Lennart
</firstname>
24 <surname>Poettering
</surname>
25 <email>lennart@poettering.net
</email>
28 <contrib>Developer
</contrib>
29 <firstname>Didier
</firstname>
30 <surname>Roche
</surname>
31 <email>didrocks@ubuntu.com
</email>
37 <refentrytitle>systemd-machine-id-setup
</refentrytitle>
38 <manvolnum>1</manvolnum>
42 <refname>systemd-machine-id-setup
</refname>
43 <refpurpose>Initialize the machine ID in /etc/machine-id
</refpurpose>
48 <command>systemd-machine-id-setup
</command>
53 <title>Description
</title>
55 <para><command>systemd-machine-id-setup
</command> may be used by
56 system installer tools to initialize the machine ID stored in
57 <filename>/etc/machine-id
</filename> at install time, with a
58 provisioned or randomly generated ID. See
59 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
60 for more information about this file.
</para>
62 <para>If the tool is invoked without the
<option>--commit
</option>
63 switch,
<filename>/etc/machine-id
</filename> is initialized with a
64 valid, new machined ID if it is missing or empty. The new machine
65 ID will be acquired in the following fashion:
</para>
68 <listitem><para>If a valid D-Bus machine ID is already
69 configured for the system, the D-Bus machine ID is copied and
70 used to initialize the machine ID in
71 <filename>/etc/machine-id
</filename>.
</para></listitem>
73 <listitem><para>If run inside a KVM virtual machine and a UUID
74 is configured (via the
<option>-uuid
</option>
75 option), this UUID is used to initialize the machine ID. The
76 caller must ensure that the UUID passed is sufficiently unique
77 and is different for every booted instance of the
80 <listitem><para>Similarly, if run inside a Linux container
81 environment and a UUID is configured for the container, this is
82 used to initialize the machine ID. For details, see the
83 documentation of the
<ulink
84 url=
"https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
85 Interface
</ulink>.
</para></listitem>
87 <listitem><para>Otherwise, a new ID is randomly
88 generated.
</para></listitem>
91 <para>The
<option>--commit
</option> switch may be used to commit a
92 transient machined ID to disk, making it persistent. For details,
96 <citerefentry><refentrytitle>systemd-firstboot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
97 to initialize the machine ID on mounted (but not booted) system
103 <title>Options
</title>
105 <para>The following options are understood:
</para>
110 <term><option>--root=
<replaceable>root
</replaceable></option></term>
111 <listitem><para>Takes a directory path as argument. All paths
112 operated will be prefixed with the given alternate
113 <replaceable>root
</replaceable> path, including the path for
114 <filename>/etc/machine-id
</filename> itself.
</para></listitem>
118 <term><option>--commit
</option></term>
119 <listitem><para>Commit a transient machine ID to disk. This
120 command may be used to convert a transient machine ID into a
121 persistent one. A transient machine ID file is one that was
122 bind mounted from a memory file system (usually
123 <literal>tmpfs
</literal>) to
124 <filename>/etc/machine-id
</filename> during the early phase of
125 the boot process. This may happen because
126 <filename>/etc
</filename> is initially read-only and was
127 missing a valid machine ID file at that point.
</para>
129 <para>This command will execute no operation if
130 <filename>/etc/machine-id
</filename> is not mounted from a
131 memory file system, or if
<filename>/etc
</filename> is
132 read-only. The command will write the current transient
133 machine ID to disk and unmount the
134 <filename>/etc/machine-id
</filename> mount point in a
135 race-free manner to ensure that this file is always valid and
136 accessible for other processes.
</para>
138 <para>This command is primarily used by the
139 <citerefentry><refentrytitle>systemd-machine-id-commit.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
140 early boot service.
</para></listitem>
144 <term><option>--print
</option></term>
146 <listitem><para>Print the machine ID generated or committed after the operation is complete.
</para></listitem>
149 <xi:include href=
"standard-options.xml" xpointer=
"help" />
150 <xi:include href=
"standard-options.xml" xpointer=
"version" />
156 <title>Exit status
</title>
158 <para>On success,
0 is returned, a non-zero failure code
163 <title>See Also
</title>
165 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
166 <citerefentry><refentrytitle>machine-id
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
167 <citerefentry><refentrytitle>systemd-machine-id-commit.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
168 <citerefentry project='dbus'
><refentrytitle>dbus-uuidgen
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
169 <citerefentry><refentrytitle>systemd-firstboot
</refentrytitle><manvolnum>1</manvolnum></citerefentry>