man/systemd-id128.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd-id128" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>systemd-id128</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-id128</refentrytitle>
  15     <manvolnum>1</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-id128</refname>
  20     <refpurpose>Generate and print sd-128 identifiers</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <cmdsynopsis>
  25       <command>systemd-id128</command>
  26       <arg choice="opt" rep="repeat">OPTIONS</arg>
  27       <arg choice="plain">new</arg>
  28     </cmdsynopsis>
  29
  30     <cmdsynopsis>
  31       <command>systemd-id128</command>
  32       <arg choice="opt" rep="repeat">OPTIONS</arg>
  33       <arg choice="plain">machine-id</arg>
  34     </cmdsynopsis>
  35
  36     <cmdsynopsis>
  37       <command>systemd-id128</command>
  38       <arg choice="opt" rep="repeat">OPTIONS</arg>
  39       <arg choice="plain">boot-id</arg>
  40     </cmdsynopsis>
  41
  42     <cmdsynopsis>
  43       <command>systemd-id128</command>
  44       <arg choice="opt" rep="repeat">OPTIONS</arg>
  45       <arg choice="plain">invocation-id</arg>
  46     </cmdsynopsis>
  47
  48     <cmdsynopsis>
  49       <command>systemd-id128</command>
  50       <arg choice="opt" rep="repeat">OPTIONS</arg>
  51       <arg choice="plain">show</arg>
  52       <arg choice="opt" rep="repeat">NAME|UUID</arg>
  53     </cmdsynopsis>
  54   </refsynopsisdiv>
  55
  56   <refsect1>
  57     <title>Description</title>
  58
  59     <para><command>id128</command> may be used to conveniently print
  60     <citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  61     UUIDs. What identifier is printed depends on the specific verb.</para>
  62
  63     <para>With <command>new</command>, a new random identifier will be generated.</para>
  64
  65     <para>With <command>machine-id</command>, the identifier of the current machine will be
  66     printed. See
  67     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  68     </para>
  69
  70     <para>With <command>boot-id</command>, the identifier of the current boot will be
  71     printed.</para>
  72
  73     <para>With <command>invocation-id</command>, the identifier of the current service invocation
  74     will be printed. This is available in systemd services. See
  75     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  76     </para>
  77
  78     <para>With <command>show</command>, well-known IDs are printed (for now, only GPT partition type UUIDs),
  79     along with brief identifier strings. When no arguments are specified, all known IDs are shown. When
  80     arguments are specified, they may be the identifiers or ID values of one or more known IDs, which are
  81     then printed with their name, or arbitrary IDs, which are then printed with a placeholder name. Combine
  82     with <option>--uuid</option> to list the IDs in UUID style, i.e. the way GPT partition type UUIDs are
  83     usually shown.</para>
  84
  85     <para><command>machine-id</command>, <command>boot-id</command>, and <command>show</command> may be
  86     combined with the <option>--app-specific=<replaceable>app-id</replaceable></option> switch to generate
  87     application-specific IDs. See
  88     <citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  89     for the discussion when this is useful. Support for <command>show --app-specific=</command> was added in
  90     version 255.</para>
  91   </refsect1>
  92
  93   <refsect1>
  94     <title>Options</title>
  95
  96     <para>The following options are understood:</para>
  97
  98     <variablelist>
  99       <varlistentry>
 100         <term><option>-p</option></term>
 101         <term><option>--pretty</option></term>
 102
 103         <listitem><para>Generate output as programming language snippets.</para>
 104
 105         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><option>-P</option></term>
 110         <term><option>--value</option></term>
 111
 112         <listitem><para>Only print the value. May be combined with
 113         <option>-u</option>/<option>--uuid</option>.</para>
 114
 115         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>-a <replaceable>app-id</replaceable></option></term>
 120         <term><option>--app-specific=<replaceable>app-id</replaceable></option></term>
 121
 122         <listitem><para>With this option, identifiers will be printed that are the result of hashing the
 123         application identifier <replaceable>app-id</replaceable> and another ID. The
 124         <replaceable>app-id</replaceable> argument must be a valid sd-id128 string identifying the
 125         application. When used with <command>machine-id</command>, the other ID will be the machine ID as
 126         described in
 127         <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>, when
 128         used with <command>boot-id</command>, the other ID will be the boot ID, and when used with
 129         <command>show</command>, the other ID or IDs should be specified via the positional arguments.</para>
 130
 131         <xi:include href="version-info.xml" xpointer="v240"/>
 132         </listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><option>-u</option></term>
 137         <term><option>--uuid</option></term>
 138
 139         <listitem><para>Generate output as a UUID formatted in the "canonical representation", with five
 140         groups of digits separated by hyphens. See the Wikipedia entry for
 141         <ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">Universally Unique Identifiers</ulink>
 142         for more discussion.</para>
 143
 144         <xi:include href="version-info.xml" xpointer="v244"/></listitem>
 145       </varlistentry>
 146
 147       <xi:include href="standard-options.xml" xpointer="help" />
 148       <xi:include href="standard-options.xml" xpointer="version" />
 149     </variablelist>
 150   </refsect1>
 151
 152   <refsect1>
 153     <title>Exit status</title>
 154
 155     <para>On success 0 is returned, and a non-zero failure code otherwise.</para>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>Examples</title>
 160
 161     <example>
 162       <title>Show a well-known UUID</title>
 163       <programlisting>
 164 $ systemd-id128 show --value user-home
 165 773f91ef66d449b5bd83d683bf40ad16
 166
 167 $ systemd-id128 show --value --uuid user-home
 168 773f91ef-66d4-49b5-bd83-d683bf40ad16
 169
 170 $ systemd-id128 show 773f91ef-66d4-49b5-bd83-d683bf40ad16
 171 NAME      ID
 172 user-home 773f91ef66d449b5bd83d683bf40ad16
 173       </programlisting>
 174     </example>
 175
 176     <example>
 177       <title>Generate an application-specific UUID</title>
 178
 179       <programlisting>
 180 $ systemd-id128 machine-id -u
 181 3a9d668b-4db7-4939-8a4a-5e78a03bffb7
 182
 183 $ systemd-id128 new -u
 184 1fb8f24b-02df-458d-9659-cc8ace68e28a
 185
 186 $ systemd-id128 machine-id -u -a 1fb8f24b-02df-458d-9659-cc8ace68e28a
 187 47b82cb1-5339-43da-b2a6-1c350aef1bd1
 188
 189 $ systemd-id128 -Pu show 3a9d668b-4db7-4939-8a4a-5e78a03bffb7 \
 190     -a 1fb8f24b-02df-458d-9659-cc8ace68e28a
 191 47b82cb1-5339-43da-b2a6-1c350aef1bd1
 192       </programlisting>
 193
 194       <para>On a given machine with the ID 3a9d668b-4db7-4939-8a4a-5e78a03bffb7, for the application
 195       1fb8f24b-02df-458d-9659-cc8ace68e28a, we generate an application-specific machine ID
 196       (47b82cb1-5339-43da-b2a6-1c350aef1bd1). If we want to later recreate the same calculation on a
 197       different machine, we need to specify both IDs explicitly as parameters to <command>show</command>.
 198       </para>
 199     </example>
 200   </refsect1>
 201
 202   <refsect1>
 203     <title>See Also</title>
 204     <para><simplelist type="inline">
 205       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 206       <member><citerefentry><refentrytitle>sd-id128</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 207       <member><citerefentry><refentrytitle>sd_id128_get_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
 208     </simplelist></para>
 209   </refsect1>
 210
 211 </refentry>