diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/machine-id.xml | 2 | ||||
| -rw-r--r-- | man/systemd-machine-id-commit.service.xml | 57 | ||||
| -rw-r--r-- | man/systemd-machine-id-commit.xml | 123 | ||||
| -rw-r--r-- | man/systemd-machine-id-setup.xml | 100 |
4 files changed, 101 insertions, 181 deletions
diff --git a/man/machine-id.xml b/man/machine-id.xml index 92d67a3869..8ce9c46ff1 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -63,7 +63,7 @@ <para>The machine ID is usually generated from a random source during system installation and stays constant for all subsequent boots. Optionally, for stateless systems, it is generated during - runtime at boot if it is found to be empty.</para> + runtime at early boot if it is found to be empty.</para> <para>The machine ID does not change based on user configuration or when hardware is replaced.</para> diff --git a/man/systemd-machine-id-commit.service.xml b/man/systemd-machine-id-commit.service.xml index 7c8fc0874e..10f36b3008 100644 --- a/man/systemd-machine-id-commit.service.xml +++ b/man/systemd-machine-id-commit.service.xml @@ -42,55 +42,50 @@ <refnamediv> <refname>systemd-machine-id-commit.service</refname> - <refpurpose>Commit transient machine-id to disk</refpurpose> + <refpurpose>Commit a transient machine-id to disk</refpurpose> </refnamediv> <refsynopsisdiv> <para><filename>systemd-machine-id-commit.service</filename></para> - <para><filename>/usr/lib/systemd/systemd-machine-id-commit</filename></para> </refsynopsisdiv> <refsect1> <title>Description</title> - <para><filename>systemd-machine-id-commit.service</filename> is a - service responsible for committing any transient - <filename>/etc/machine-id</filename> file to a writable file + <para><filename>systemd-machine-id-commit.service</filename> is an + early-boot service responsible for committing transient + <filename>/etc/machine-id</filename> files to a writable disk file system. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This service is started shortly after - <filename>local-fs.target</filename> if - <filename>/etc/machine-id</filename> is an independent mount point - (probably a tmpfs one) and /etc is writable. - <command>systemd-machine-id-commit</command> will then write - current machine ID to disk and unmount the transient + for more information about machine IDs.</para> + + <para>This service is started after + <filename>local-fs.target</filename> in case + <filename>/etc/machine-id</filename> is a mount point of its own + (usually from a memory file system such as + <literal>tmpfs</literal>) and /etc is writable. The service will + invoke <command>systemd-machine-id-setup --commit</command>, which + writes the current transient machine ID to disk and unmount the <filename>/etc/machine-id</filename> file in a race-free manner to - ensure that file is always valid for other processes.</para> - - <para>Note that the traditional way to initialize the machine ID - in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system installer - tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images. The main use case for that service is - <filename>/etc/machine-id</filename> being an empty file at boot - and initrd chaining to systemd giving it a read only file system - that will be turned read-write later during the boot - process.</para> - - <para>There is no consequence if that service fails other than a - newer machine-id will be generated during next system boot. - </para> + ensure that file is always valid and accessible for other + processes. See + <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for details.</para> + + <para>The main use case of this service are systems where + <filename>/etc/machine-id</filename> is read-only and initially + not initialized. In this case the system manager will generate a + transient machine ID file on a memory file system, and mount it + over <filename>/etc/machine-id</filename>, during the early boot + phase. This service is then invoked in a later boot phase, as soon + as <filename>/etc</filename> has been remounted writable and the + ID may thus be committed to disk to make it permanent.</para> </refsect1> <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/systemd-machine-id-commit.xml b/man/systemd-machine-id-commit.xml deleted file mode 100644 index d216aa0745..0000000000 --- a/man/systemd-machine-id-commit.xml +++ /dev/null @@ -1,123 +0,0 @@ -<?xml version='1.0'?> <!--*-nxml-*--> -<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<!-- - This file is part of systemd. - - Copyright 2014 Didier Roche - - systemd is free software; you can redistribute it and/or modify it - under the terms of the GNU Lesser General Public License as published by - the Free Software Foundation; either version 2.1 of the License, or - (at your option) any later version. - - systemd is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - Lesser General Public License for more details. - - You should have received a copy of the GNU Lesser General Public License - along with systemd; If not, see <http://www.gnu.org/licenses/>. ---> - -<refentry id="systemd-machine-id-commit" - xmlns:xi="http://www.w3.org/2001/XInclude"> - - <refentryinfo> - <title>systemd-machine-id-commit</title> - <productname>systemd</productname> - - <authorgroup> - <author> - <contrib>Developer</contrib> - <firstname>Didier</firstname> - <surname>Roche</surname> - <email>didrocks@ubuntu.com</email> - </author> - </authorgroup> - </refentryinfo> - - <refmeta> - <refentrytitle>systemd-machine-id-commit</refentrytitle> - <manvolnum>1</manvolnum> - </refmeta> - - <refnamediv> - <refname>systemd-machine-id-commit</refname> - <refpurpose>Commit transient machine ID to /etc/machine-id</refpurpose> - </refnamediv> - - <refsynopsisdiv> - <cmdsynopsis> - <command>systemd-machine-id-commit</command> - </cmdsynopsis> - </refsynopsisdiv> - - <refsect1> - <title>Description</title> - - <para><command>systemd-machine-id-commit</command> may be used to - write on disk any transient machine ID mounted as a temporary file - system in <filename>/etc/machine-id</filename> at boot time. See - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for more information about this file.</para> - - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> doesn't contain any valid - machine ID, isn't mounted as an independent temporary file system, - or <filename>/etc</filename> is read-only. If those conditions are - met, it will then write current machine ID to disk and unmount the - transient <filename>/etc/machine-id</filename> file in a race-free - manner to ensure that this file is always valid for other - processes.</para> - - <para>Note that the traditional way to initialize the machine ID - in <filename>/etc/machine-id</filename> is to use - <command>systemd-machine-id-setup</command> by system installer - tools. You can also use - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to initialize the machine ID on mounted (but not booted) system - images.</para> - </refsect1> - - <refsect1> - <title>Options</title> - - <para>The following options are understood:</para> - - <variablelist> - <varlistentry> - <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path - as an argument. All paths will be - prefixed with the given alternate - <replaceable>root</replaceable> path, - including config search paths. - </para></listitem> - </varlistentry> - <xi:include href="standard-options.xml" xpointer="help" /> - <xi:include href="standard-options.xml" xpointer="version" /> - </variablelist> - - </refsect1> - - <refsect1> - <title>Exit status</title> - - <para>On success, 0 is returned, a non-zero failure code - otherwise.</para> - </refsect1> - - <refsect1> - <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> - </para> - </refsect1> - -</refentry> diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index 182717f524..efcf408332 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -1,4 +1,4 @@ -<?xml version='1.0'?> <!--*-nxml-*--> +<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> @@ -35,6 +35,12 @@ <surname>Poettering</surname> <email>lennart@poettering.net</email> </author> + <author> + <contrib>Developer</contrib> + <firstname>Didier</firstname> + <surname>Roche</surname> + <email>didrocks@ubuntu.com</email> + </author> </authorgroup> </refentryinfo> @@ -59,30 +65,43 @@ <para><command>systemd-machine-id-setup</command> may be used by system installer tools to initialize the machine ID stored in - <filename>/etc/machine-id</filename> at install time with a - randomly generated ID. See + <filename>/etc/machine-id</filename> at install time, with a + provisioned or randomly generated ID. See <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more information about this file.</para> - <para>This tool will execute no operation if - <filename>/etc/machine-id</filename> is already - initialized.</para> - - <para>If a valid D-Bus machine ID is already configured for the - system, the D-Bus machine ID is copied and used to initialize the - machine ID in <filename>/etc/machine-id</filename>.</para> - - <para>If run inside a KVM virtual machine and a UUID is passed via - the <option>-uuid</option> option, this UUID is used to initialize - the machine ID instead of a randomly generated one. The caller - must ensure that the UUID passed is sufficiently unique and is - different for every booted instanced of the VM.</para> - - <para>Similar, if run inside a Linux container environment and a - UUID is set for the container this is used to initialize the - machine ID. For details see the documentation of the <ulink - url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container - Interface</ulink>.</para> + <para>If the tool is invoked without the <option>--commit</option> + switch <filename>/etc/machine-id</filename> is initialized with a + valid, new machined ID if it is missing or empty. The new machine + ID will be acquired in the following fashion:</para> + + <orderedlist> + <listitem><para>If a valid D-Bus machine ID is already + configured for the system, the D-Bus machine ID is copied and + used to initialize the machine ID in + <filename>/etc/machine-id</filename>.</para></listitem> + + <listitem><para>If run inside a KVM virtual machine and a UUID + is was configured (via the <option>-uuid</option> + option), this UUID is used to initialize the machine ID. The + caller must ensure that the UUID passed is sufficiently unique + and is different for every booted instance of the + VM.</para></listitem> + + <listitem><para>Similar, if run inside a Linux container + environment and a UUID is configured for the container this is + used to initialize the machine ID. For details see the + documentation of the <ulink + url="http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface">Container + Interface</ulink>.</para></listitem> + + <listitem><para>Otherwise a new ID is randomly + generated.</para></listitem> + </orderedlist> + + <para>The <option>--commit</option> switch may be used to commit a + transient machined ID to disk, making it persistent. For details, + see below.</para> <para>Use <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> @@ -97,13 +116,41 @@ <para>The following options are understood:</para> <variablelist> + <varlistentry> <term><option>--root=<replaceable>root</replaceable></option></term> - <listitem><para>Takes a directory path as an argument. All - paths will be prefixed with the given alternate - <replaceable>root</replaceable> path, including config search - paths. </para></listitem> + <listitem><para>Takes a directory path as argument. All paths + operated will be prefixed with the given alternate + <replaceable>root</replaceable> path, including the path for + <filename>/etc/machine-id</filename> itself.</para></listitem> </varlistentry> + + <varlistentry> + <term><option>--commit</option></term> + <listitem><para>Commit a transient machine ID to disk. This + command may be used to convert a transient machine ID into a + persistent one. A transient machine ID file is one that was + bind mounted from a memory file system (usually + <literal>tmpfs</literal>) to + <filename>/etc/machine-id</filename> during the early phase of + the boot process. This may happen because + <filename>/etc</filename> is initially read-only and was + missing a valid machine ID file at that point.</para> + + <para>This command will execute no operation if + <filename>/etc/machine-id</filename> is not mounted from a + memory file system, or if <filename>/etc</filename> is + read-only. The command will write the current transient + machine ID to disk and unmount the + <filename>/etc/machine-id</filename> mount point in a + race-free manner to ensure that this file is always valid and + accessible for other processes.</para> + + <para>This command is primarily used by the + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + early-boot service.</para></listitem> + </varlistentry> + <xi:include href="standard-options.xml" xpointer="help" /> <xi:include href="standard-options.xml" xpointer="version" /> </variablelist> @@ -122,6 +169,7 @@ <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-machine-id-commit.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry project='dbus'><refentrytitle>dbus-uuidgen</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-firstboot</refentrytitle><manvolnum>1</manvolnum></citerefentry> </para> |