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