util: Add _sentinel_ to strextend()

[elogind.git] / man / machine-id.xml

diff --git a/man/machine-id.xml b/man/machine-id.xml
index fefeb66fd683ef92ba25f85d8a0b86545b14918e..1e558a61783402e2afc2558adf3f5179706d9212 100644 (file)
--- a/man/machine-id.xml
+++ b/man/machine-id.xml
@@ -9,22 +9,22 @@
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it
   Copyright 2010 Lennart Poettering
 
   systemd is free software; you can redistribute it and/or modify it

-  under the terms of the GNU General Public License as published by
-  the Free Software Foundation; either version 2 of the License, or
+  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
   (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

-  General Public License for more details.
+  Lesser General Public License for more details.

 
 

-  You should have received a copy of the GNU General Public License
+  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="machine-id">
         <refentryinfo>
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 -->
 
 <refentry id="machine-id">
         <refentryinfo>

-                <title>/etc/machine-id</title>
+                <title>machine-id</title>

                 <productname>systemd</productname>
 
                 <authorgroup>
                 <productname>systemd</productname>
 
                 <authorgroup>


@@ -44,7 +44,7 @@
 
         <refnamediv>
                 <refname>machine-id</refname>
 
         <refnamediv>
                 <refname>machine-id</refname>

-                <refpurpose>local machine ID configuration file</refpurpose>
+                <refpurpose>Local machine ID configuration file</refpurpose>

         </refnamediv>
 
         <refsynopsisdiv>
         </refnamediv>
 
         <refsynopsisdiv>


@@ -55,30 +55,66 @@
                 <title>Description</title>
 
                 <para>The <filename>/etc/machine-id</filename> file
                 <title>Description</title>
 
                 <para>The <filename>/etc/machine-id</filename> file

-                configures the unique machine id of the local system
-                that is set during installation. It should contain a
-                single newline-terminated, hexadecimal, lowercase 16
-                character machine ID string.</para>
+                contains the unique machine id of the local system
+                that is set during installation. The machine ID is a
+                single newline-terminated, hexadecimal, lowercase 32
+                character machine ID string. (When decoded from
+                hexadecimal this corresponds with a 16 byte/128 bit
+                string.)</para>

 
                 <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
 
                 <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.</para>
+                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>
 
 
                 <para>The machine ID does not change based on user
                 configuration, or when hardware is replaced.</para>
 

-                <para>This machine id follows the same format and
+                <para>This machine ID adheres to the same format and

                 logic as the D-Bus machine ID.</para>
 
                 <para>Programs may use this ID to identify the host
                 logic as the D-Bus machine ID.</para>
 
                 <para>Programs may use this ID to identify the host

-                with a globally unique ID in the network, that does
+                with a globally unique ID in the network, which does

                 not change even if the local network configuration
                 changes. Due to this and its greater length it is
                 not change even if the local network configuration
                 changes. Due to this and its greater length it is

-                a more useful replacement than the
+                a more useful replacement for the

                 <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 call POSIX specifies.</para>
                 <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>
                 call POSIX specifies.</para>

+
+                <para>The
+                <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                tool may be used by installer tools to initialize the
+                machine ID at install time.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Relation to OSF UUIDs</title>
+
+                <para>Note that the machine ID historically is not an
+                OSF UUID as defined by <ulink
+                url="http://tools.ietf.org/html/rfc4122">RFC
+                4122</ulink>, nor a Microsoft GUID. Starting with
+                systemd v30 newly generated machine IDs however do
+                qualify as v4 UUIDs.</para>
+
+                <para>In order to maintain compatibility with existing
+                installations, an application requiring a UUID should
+                decode the machine ID, and then apply the following
+                operations to turn it into a valid OSF v4 UUID. With
+                <literal>id</literal> being an unsigned character
+                array:</para>
+
+                <programlisting>/* Set UUID version to 4 --- truly random generation */
+id[6] = (id[6] &amp; 0x0F) | 0x40;
+/* Set the UUID variant to DCE */
+id[8] = (id[8] &amp; 0x3F) | 0x80;</programlisting>
+
+                <para>(This code is inspired by
+                <literal>generate_random_uuid()</literal> of
+                <filename>drivers/char/random.c</filename> from the
+                kernel sources.)</para>
+

         </refsect1>
 
         <refsect1>
         </refsect1>
 
         <refsect1>


@@ -88,7 +124,7 @@
                 <filename>/etc/machine-id</filename> originates in the
                 <filename>/var/lib/dbus/machine-id</filename> file
                 introduced by D-Bus. In fact this latter file might be a
                 <filename>/etc/machine-id</filename> originates in the
                 <filename>/var/lib/dbus/machine-id</filename> file
                 introduced by D-Bus. In fact this latter file might be a

-                symlink to the
+                symlink to

                 <varname>/etc/machine-id</varname>.</para>
         </refsect1>
 
                 <varname>/etc/machine-id</varname>.</para>
         </refsect1>
 


@@ -96,8 +132,13 @@
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                   <title>See Also</title>
                   <para>
                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

+                          <citerefentry><refentrytitle>systemd-machine-id-setup</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

                           <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                           <citerefentry><refentrytitle>gethostid</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

-                          <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                          <citerefentry><refentrytitle>hostname</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>machine-info</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+                          <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>

                   </para>
         </refsect1>
 
                   </para>
         </refsect1>