man/systemd-machine-id-setup.xml

   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">
   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
  16     <authorgroup>
  17       <author>
  18         <contrib>Developer</contrib>
  19         <firstname>Lennart</firstname>
  20         <surname>Poettering</surname>
  21         <email>lennart@poettering.net</email>
  22       </author>
  23       <author>
  24         <contrib>Developer</contrib>
  25         <firstname>Didier</firstname>
  26         <surname>Roche</surname>
  27         <email>didrocks@ubuntu.com</email>
  28       </author>
  29     </authorgroup>
  30   </refentryinfo>
  31
  32   <refmeta>
  33     <refentrytitle>systemd-machine-id-setup</refentrytitle>
  34     <manvolnum>1</manvolnum>
  35   </refmeta>
  36
  37   <refnamediv>
  38     <refname>systemd-machine-id-setup</refname>
  39     <refpurpose>Initialize the machine ID in /etc/machine-id</refpurpose>
  40   </refnamediv>
  41
  42   <refsynopsisdiv>
  43     <cmdsynopsis>
  44       <command>systemd-machine-id-setup</command>
  45     </cmdsynopsis>
  46   </refsynopsisdiv>
  47
  48   <refsect1>
  49     <title>Description</title>
  50
  51     <para><command>systemd-machine-id-setup</command> may be used by
  52     system installer tools to initialize the machine ID stored in
  53     <filename>/etc/machine-id</filename> at install time, with a
  54     provisioned or randomly generated ID. See
  55     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  56     for more information about this file.</para>
  57
  58     <para>If the tool is invoked without the <option>--commit</option>
  59     switch, <filename>/etc/machine-id</filename> is initialized with a
  60     valid, new machined ID if it is missing or empty. The new machine
  61     ID will be acquired in the following fashion:</para>
  62
  63     <orderedlist>
  64       <listitem><para>If a valid D-Bus machine ID is already
  65       configured for the system, the D-Bus machine ID is copied and
  66       used to initialize the machine ID in
  67       <filename>/etc/machine-id</filename>.</para></listitem>
  68
  69       <listitem><para>If run inside a KVM virtual machine and a UUID
  70       is configured (via the <option>-uuid</option>
  71       option), this UUID is used to initialize the machine ID. The
  72       caller must ensure that the UUID passed is sufficiently unique
  73       and is different for every booted instance of the
  74       VM.</para></listitem>
  75
  76       <listitem><para>Similarly, if run inside a Linux container
  77       environment and a UUID is configured for the container, this is
  78       used to initialize the machine ID. For details, see the
  79       documentation of the <ulink
  80       url="https://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
  81       Interface</ulink>.</para></listitem>
  82
  83       <listitem><para>Otherwise, a new ID is randomly
  84       generated.</para></listitem>
  85     </orderedlist>
  86
  87     <para>The <option>--commit</option> switch may be used to commit a
  88     transient machined ID to disk, making it persistent. For details,
  89     see below.</para>
  90
  91     <para>Use
  92     <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  93     to initialize the machine ID on mounted (but not booted) system
  94     images.</para>
  95
  96   </refsect1>
  97
  98   <refsect1>
  99     <title>Options</title>
 100
 101     <para>The following options are understood:</para>
 102
 103     <variablelist>
 104
 105       <varlistentry>
 106         <term><option>--root=<replaceable>root</replaceable></option></term>
 107         <listitem><para>Takes a directory path as argument. All paths
 108         operated will be prefixed with the given alternate
 109         <replaceable>root</replaceable> path, including the path for
 110         <filename>/etc/machine-id</filename> itself.</para></listitem>
 111       </varlistentry>
 112
 113       <varlistentry>
 114         <term><option>--commit</option></term>
 115         <listitem><para>Commit a transient machine ID to disk. This
 116         command may be used to convert a transient machine ID into a
 117         persistent one. A transient machine ID file is one that was
 118         bind mounted from a memory file system (usually
 119         <literal>tmpfs</literal>) to
 120         <filename>/etc/machine-id</filename> during the early phase of
 121         the boot process. This may happen because
 122         <filename>/etc</filename> is initially read-only and was
 123         missing a valid machine ID file at that point.</para>
 124
 125         <para>This command will execute no operation if
 126         <filename>/etc/machine-id</filename> is not mounted from a
 127         memory file system, or if <filename>/etc</filename> is
 128         read-only. The command will write the current transient
 129         machine ID to disk and unmount the
 130         <filename>/etc/machine-id</filename> mount point in a
 131         race-free manner to ensure that this file is always valid and
 132         accessible for other processes.</para>
 133
 134         <para>This command is primarily used by the
 135         <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 136         early boot service.</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><option>--print</option></term>
 141
 142         <listitem><para>Print the machine ID generated or committed after the operation is complete.</para></listitem>
 143       </varlistentry>
 144
 145       <xi:include href="standard-options.xml" xpointer="help" />
 146       <xi:include href="standard-options.xml" xpointer="version" />
 147     </variablelist>
 148
 149   </refsect1>
 150
 151   <refsect1>
 152     <title>Exit status</title>
 153
 154     <para>On success, 0 is returned, a non-zero failure code
 155     otherwise.</para>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>See Also</title>
 160     <para>
 161       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 162       <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 163       <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 164       <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 165       <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 166     </para>
 167   </refsect1>
 168
 169 </refentry>