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 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   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 machined 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
  59       environment and a UUID is configured for the container, this is
  60       used to initialize the machine ID. For details, see the
  61       documentation of the <ulink
  62       url="https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
  63       Interface</ulink>.</para></listitem>
  64
  65       <listitem><para>Otherwise, a new ID is randomly
  66       generated.</para></listitem>
  67     </orderedlist>
  68
  69     <para>The <option>--commit</option> switch may be used to commit a
  70     transient machined ID to disk, making it persistent. For details,
  71     see below.</para>
  72
  73     <para>Use
  74     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  75     to initialize the machine ID on mounted (but not booted) system
  76     images.</para>
  77
  78   </refsect1>
  79
  80   <refsect1>
  81     <title>Options</title>
  82
  83     <para>The following options are understood:</para>
  84
  85     <variablelist>
  86
  87       <varlistentry>
  88         <term><option>--root=<replaceable>root</replaceable></option></term>
  89         <listitem><para>Takes a directory path as argument. All paths
  90         operated will be prefixed with the given alternate
  91         <replaceable>root</replaceable> path, including the path for
  92         <filename>/etc/machine-id</filename> itself.</para></listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term><option>--commit</option></term>
  97         <listitem><para>Commit a transient machine ID to disk. This
  98         command may be used to convert a transient machine ID into a
  99         persistent one. A transient machine ID file is one that was
 100         bind mounted from a memory file system (usually
 101         <literal>tmpfs</literal>) to
 102         <filename>/etc/machine-id</filename> during the early phase of
 103         the boot process. This may happen because
 104         <filename>/etc</filename> is initially read-only and was
 105         missing a valid machine ID file at that point.</para>
 106
 107         <para>This command will execute no operation if
 108         <filename>/etc/machine-id</filename> is not mounted from a
 109         memory file system, or if <filename>/etc</filename> is
 110         read-only. The command will write the current transient
 111         machine ID to disk and unmount the
 112         <filename>/etc/machine-id</filename> mount point in a
 113         race-free manner to ensure that this file is always valid and
 114         accessible for other processes.</para>
 115
 116         <para>This command is primarily used by the
 117         <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 118         early boot service.</para></listitem>
 119       </varlistentry>
 120
 121       <varlistentry>
 122         <term><option>--print</option></term>
 123
 124         <listitem><para>Print the machine ID generated or committed after the operation is complete.</para></listitem>
 125       </varlistentry>
 126
 127       <xi:include href="standard-options.xml" xpointer="help" />
 128       <xi:include href="standard-options.xml" xpointer="version" />
 129     </variablelist>
 130
 131   </refsect1>
 132
 133   <refsect1>
 134     <title>Exit status</title>
 135
 136     <para>On success, 0 is returned, a non-zero failure code
 137     otherwise.</para>
 138   </refsect1>
 139
 140   <refsect1>
 141     <title>See Also</title>
 142     <para>
 143       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 144       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 145       <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 146       <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 147       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 148     </para>
 149   </refsect1>
 150
 151 </refentry>