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