man/systemd-machine-id-setup.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-machine-id-setup"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-machine-id-setup</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>systemd-machine-id-setup</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>systemd-machine-id-setup</refname>
  24     <refpurpose>Initialize the machine ID in /etc/machine-id</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  29       <command>systemd-machine-id-setup</command>
  30     </cmdsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Description</title>
  35
  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>
  42
  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>
  47
  48     <orderedlist>
  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>
  53
  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
  59       VM.</para></listitem>
  60
  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>
  67
  68       <listitem><para>Otherwise, a new ID is randomly
  69       generated.</para></listitem>
  70     </orderedlist>
  71
  72     <para>The <option>--commit</option> switch may be used to commit a
  73     transient machined ID to disk, making it persistent. For details,
  74     see below.</para>
  75
  76     <para>Use
  77     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  78     to initialize the machine ID on mounted (but not booted) system
  79     images.</para>
  80
  81   </refsect1>
  82
  83   <refsect1>
  84     <title>Options</title>
  85
  86     <para>The following options are understood:</para>
  87
  88     <variablelist>
  89
  90       <varlistentry>
  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>
  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>