chiark / gitweb /
28352e357f9faa987a358e61a6831def0429742e
[elogind.git] / systemd-machine-id-setup.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
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                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>systemd-machine-id-setup</refentrytitle>
43                 <manvolnum>1</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>systemd-machine-id-setup</refname>
48                 <refpurpose>Initialize the machine ID in /etc/machine-id</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <cmdsynopsis>
53                         <command>systemd-machine-id-setup</command>
54                 </cmdsynopsis>
55         </refsynopsisdiv>
56
57         <refsect1>
58                 <title>Description</title>
59
60                 <para><command>systemd-machine-id-setup</command> may
61                 be used by system installer tools to initialize the
62                 machine ID stored in
63                 <filename>/etc/machine-id</filename> at install time
64                 with a randomly generated ID. See
65                 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
66                 for more information about this file.</para>
67
68                 <para>This tool will execute no operation if
69                 <filename>/etc/machine-id</filename> is already
70                 initialized.</para>
71
72                 <para>If a valid D-Bus machine ID is already
73                 configured for the system, the D-Bus machine ID is
74                 copied and used to initialize the machine ID in
75                 <filename>/etc/machine-id</filename>.</para>
76
77                 <para>If run inside a KVM virtual machine and a UUID
78                 is passed via the <option>-uuid</option> option, this
79                 UUID is used to initialize the machine ID instead of a
80                 randomly generated one. The caller must ensure that the
81                 UUID passed is sufficiently unique and is different
82                 for every booted instanced of the VM.</para>
83
84                 <para>Similar, if run inside a Linux container
85                 environment and a UUID is set for the container this
86                 is used to initialize the machine ID. For details see
87                 the documentation of the <ulink
88                 url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container
89                 Interface</ulink>.</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
94                 booted) system 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                         <varlistentry>
105                                 <term><option>--root=<replaceable>root</replaceable></option></term>
106                                 <listitem><para>Takes a directory path
107                                 as an argument. All paths will be
108                                 prefixed with the given alternate
109                                 <replaceable>root</replaceable> path,
110                                 including config search paths.
111                                 </para></listitem>
112                         </varlistentry>
113                         <xi:include href="standard-options.xml" xpointer="help" />
114                         <xi:include href="standard-options.xml" xpointer="version" />
115                 </variablelist>
116
117         </refsect1>
118
119         <refsect1>
120                 <title>Exit status</title>
121
122                 <para>On success, 0 is returned, a non-zero failure
123                 code otherwise.</para>
124         </refsect1>
125
126         <refsect1>
127                 <title>See Also</title>
128                 <para>
129                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
130                         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
131                         <citerefentry><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
132                         <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
133                 </para>
134         </refsect1>
135
136 </refentry>