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