man/systemd-machine-id-setup.xml

   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+ -->
   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 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>root</replaceable></option></term>
  86         <listitem><para>Takes a directory path as argument. All paths
  87         operated will be prefixed with the given alternate
  88         <replaceable>root</replaceable> path, including the path for
  89         <filename>/etc/machine-id</filename> itself.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><option>--commit</option></term>
  94         <listitem><para>Commit a transient machine ID to disk. This
  95         command may be used to convert a transient machine ID into a
  96         persistent one. A transient machine ID file is one that was
  97         bind mounted from a memory file system (usually
  98         <literal>tmpfs</literal>) to
  99         <filename>/etc/machine-id</filename> during the early phase of
 100         the boot process. This may happen because
 101         <filename>/etc</filename> is initially read-only and was
 102         missing a valid machine ID file at that point.</para>
 103
 104         <para>This command will execute no operation if
 105         <filename>/etc/machine-id</filename> is not mounted from a
 106         memory file system, or if <filename>/etc</filename> is
 107         read-only. The command will write the current transient
 108         machine ID to disk and unmount the
 109         <filename>/etc/machine-id</filename> mount point in a
 110         race-free manner to ensure that this file is always valid and
 111         accessible for other processes.</para>
 112
 113         <para>This command is primarily used by the
 114         <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 115         early boot service.</para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>--print</option></term>
 120
 121         <listitem><para>Print the machine ID generated or committed after the operation is complete.</para></listitem>
 122       </varlistentry>
 123
 124       <xi:include href="standard-options.xml" xpointer="help" />
 125       <xi:include href="standard-options.xml" xpointer="version" />
 126     </variablelist>
 127
 128   </refsect1>
 129
 130   <refsect1>
 131     <title>Exit status</title>
 132
 133     <para>On success, 0 is returned, a non-zero failure code
 134     otherwise.</para>
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>See Also</title>
 139     <para>
 140       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 143       <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 144       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 145     </para>
 146   </refsect1>
 147
 148 </refentry>