Debian Codegraph @

upstream/debian-unstable/man1/systemd-id128.1

raw
1 '\" t
2 .TH "SYSTEMD\-ID128" "1" "" "systemd 261~rc3" "systemd-id128"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-id128 \- Generate and print sd\-128 identifiers
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-id128\fR\ 'u
26 \fBsystemd\-id128\fR [OPTIONS...] new
27 .HP \w'\fBsystemd\-id128\fR\ 'u
28 \fBsystemd\-id128\fR [OPTIONS...] machine\-id
29 .HP \w'\fBsystemd\-id128\fR\ 'u
30 \fBsystemd\-id128\fR [OPTIONS...] boot\-id
31 .HP \w'\fBsystemd\-id128\fR\ 'u
32 \fBsystemd\-id128\fR [OPTIONS...] invocation\-id
33 .HP \w'\fBsystemd\-id128\fR\ 'u
34 \fBsystemd\-id128\fR [OPTIONS...] var\-partition\-uuid
35 .HP \w'\fBsystemd\-id128\fR\ 'u
36 \fBsystemd\-id128\fR [OPTIONS...] show [NAME|UUID...]
37 .SH "DESCRIPTION"
38 .PP
39 \fBid128\fR
40 may be used to conveniently print
41 \fBsd-id128\fR(3)
42 UUIDs\&. What identifier is printed depends on the specific verb\&.
43 .PP
44 With
45 \fBnew\fR, a new random identifier will be generated\&.
46 .PP
47 With
48 \fBmachine\-id\fR, the identifier of the current machine will be printed\&. See
49 \fBmachine-id\fR(5)\&.
50 .PP
51 With
52 \fBboot\-id\fR, the identifier of the current boot will be printed\&.
53 .PP
54 With
55 \fBinvocation\-id\fR, the identifier of the current service invocation will be printed\&. This is available in systemd services\&. See
56 \fBsystemd.exec\fR(5)\&.
57 .PP
58 With
59 \fBshow\fR, well\-known IDs are printed (for now, only GPT partition type UUIDs), along with brief identifier strings\&. When no arguments are specified, all known IDs are shown\&. When arguments are specified, they may be the identifiers or ID values of one or more known IDs, which are then printed with their name, or arbitrary IDs, which are then printed with a placeholder name\&. Combine with
60 \fB\-\-uuid\fR
61 to list the IDs in UUID style, i\&.e\&. the way GPT partition type UUIDs are usually shown\&.
62 .PP
63 \fBmachine\-id\fR,
64 \fBboot\-id\fR, and
65 \fBshow\fR
66 may be combined with the
67 \fB\-\-app\-specific=\fR\fB\fIapp\-id\fR\fR
68 switch to generate application\-specific IDs\&. See
69 \fBsd_id128_get_machine\fR(3)
70 for the discussion when this is useful\&. Support for
71 \fBshow \-\-app\-specific=\fR
72 was added in version 255\&.
73 .PP
74 \fBvar\-partition\-uuid\fR
75 prints a UUID which, following the
76 \m[blue]\fBUAPI\&.2 Discoverable Partitions Specification\fR\m[]\&\s-2\u[1]\d\s+2, should be used as the GPT partition UUID for
77 /var/, being derived from the GPT partition type, keyed by the local
78 /etc/machine\-id\&. Added in version 257\&.
79 .SH "OPTIONS"
80 .PP
81 The following options are understood:
82 .PP
83 \fB\-p\fR, \fB\-\-pretty\fR
84 .RS 4
85 Generate output as programming language snippets\&.
86 .sp
87 Added in version 240\&.
88 .RE
89 .PP
90 \fB\-P\fR, \fB\-\-value\fR
91 .RS 4
92 Only print the value\&. May be combined with
93 \fB\-u\fR/\fB\-\-uuid\fR\&.
94 .sp
95 Added in version 255\&.
96 .RE
97 .PP
98 \fB\-a \fR\fB\fIapp\-id\fR\fR, \fB\-\-app\-specific=\fR\fB\fIapp\-id\fR\fR
99 .RS 4
100 With this option, identifiers will be printed that are the result of hashing the application identifier
101 \fIapp\-id\fR
102 and another ID\&. The
103 \fIapp\-id\fR
104 argument must be a valid sd\-id128 string identifying the application\&. When used with
105 \fBmachine\-id\fR, the other ID will be the machine ID as described in
106 \fBmachine-id\fR(5), when used with
107 \fBboot\-id\fR, the other ID will be the boot ID, and when used with
108 \fBshow\fR, the other ID or IDs should be specified via the positional arguments\&.
109 .sp
110 Added in version 240\&.
111 .RE
112 .PP
113 \fB\-u\fR, \fB\-\-uuid\fR
114 .RS 4
115 Generate output as a UUID formatted in the "canonical representation", with five groups of digits separated by hyphens\&. See the Wikipedia entry for
116 \m[blue]\fBUniversally Unique Identifiers\fR\m[]\&\s-2\u[2]\d\s+2
117 for more discussion\&.
118 .sp
119 Added in version 244\&.
120 .RE
121 .PP
122 \fB\-\-no\-pager\fR
123 .RS 4
124 Do not pipe output into a pager\&.
125 .RE
126 .PP
127 \fB\-\-no\-legend\fR
128 .RS 4
129 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
130 .RE
131 .PP
132 \fB\-\-json=\fR\fB\fIMODE\fR\fR
133 .RS 4
134 Shows output formatted as JSON\&. Expects one of
135 "short"
136 (for the shortest possible output without any redundant whitespace or line breaks),
137 "pretty"
138 (for a pretty version of the same, with indentation and line breaks) or
139 "off"
140 (to turn off JSON output, the default)\&.
141 .RE
142 .PP
143 \fB\-j\fR
144 .RS 4
145 Equivalent to
146 \fB\-\-json=pretty\fR
147 if running on a terminal, and
148 \fB\-\-json=short\fR
149 otherwise\&.
150 .RE
151 .PP
152 \fB\-h\fR, \fB\-\-help\fR
153 .RS 4
154 Print a short help text and exit\&.
155 .RE
156 .PP
157 \fB\-\-version\fR
158 .RS 4
159 Print a short version string and exit\&.
160 .RE
161 .SH "EXIT STATUS"
162 .PP
163 On success 0 is returned, and a non\-zero failure code otherwise\&.
164 .SH "EXAMPLES"
165 .PP
166 \fBExample\ \&1.\ \&Show a well\-known UUID\fR
167 .sp
168 .if n \{\
169 .RS 4
170 .\}
171 .nf
172 $ systemd\-id128 show \-\-value user\-home
173 773f91ef66d449b5bd83d683bf40ad16
174
175 $ systemd\-id128 show \-\-value \-\-uuid user\-home
176 773f91ef\-66d4\-49b5\-bd83\-d683bf40ad16
177
178 $ systemd\-id128 show 773f91ef\-66d4\-49b5\-bd83\-d683bf40ad16
179 NAME ID
180 user\-home 773f91ef66d449b5bd83d683bf40ad16
181 .fi
182 .if n \{\
183 .RE
184 .\}
185 .PP
186 \fBExample\ \&2.\ \&Generate an application\-specific UUID\fR
187 .sp
188 .if n \{\
189 .RS 4
190 .\}
191 .nf
192 $ systemd\-id128 machine\-id \-u
193 3a9d668b\-4db7\-4939\-8a4a\-5e78a03bffb7
194
195 $ systemd\-id128 new \-u
196 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a
197
198 $ systemd\-id128 machine\-id \-u \-a 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a
199 47b82cb1\-5339\-43da\-b2a6\-1c350aef1bd1
200
201 $ systemd\-id128 \-Pu show 3a9d668b\-4db7\-4939\-8a4a\-5e78a03bffb7 \e
202 \-a 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a
203 47b82cb1\-5339\-43da\-b2a6\-1c350aef1bd1
204 .fi
205 .if n \{\
206 .RE
207 .\}
208 .PP
209 On a given machine with the ID 3a9d668b\-4db7\-4939\-8a4a\-5e78a03bffb7, for the application 1fb8f24b\-02df\-458d\-9659\-cc8ace68e28a, we generate an application\-specific machine ID (47b82cb1\-5339\-43da\-b2a6\-1c350aef1bd1)\&. If we want to later recreate the same calculation on a different machine, we need to specify both IDs explicitly as parameters to
210 \fBshow\fR\&.
211 .SH "SEE ALSO"
212 .PP
213 \fBsystemd\fR(1), \fBsd-id128\fR(3), \fBsd_id128_get_machine\fR(3)
214 .SH "NOTES"
215 .IP " 1." 4
216 UAPI.2 Discoverable Partitions Specification
217 .RS 4
218 \%https://uapi-group.org/specifications/specs/discoverable_partitions_specification
219 .RE
220 .IP " 2." 4
221 Universally Unique Identifiers
222 .RS 4
223 \%https://en.wikipedia.org/wiki/Universally_unique_identifier#Format
224 .RE