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