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