Debian Codegraph @

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

raw
1 '\" t
2 .TH "SYSTEMD\-IMDS" "1" "" "systemd 261~rc3" "systemd-imds"
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-imds, systemd-imds-import.service \- Cloud IMDS (Instance Metadata Service) tool
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-imds\-import\&.service
27 .HP \w'\fBsystemd\-imds\fR\ 'u
28 \fBsystemd\-imds\fR [OPTIONS...] [KEY]
29 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-imds\fR
32 is a tool for acquiring data from IMDS (Instance Metadata Service), as provided in many cloud environments\&. It is a client to
33 \[email protected]\fR(8), and provides access to IMDS data from shell environments\&.
34 .PP
35 The tool can operate in one of five modes:
36 .sp
37 .RS 4
38 .ie n \{\
39 \h'-04'\(bu\h'+03'\c
40 .\}
41 .el \{\
42 .sp -1
43 .IP \(bu 2.3
44 .\}
45 Without positional arguments (and without the
46 \fB\-\-well\-known=\fR
47 switch) general IMDS service data and a few well known fields are displayed in human friendly form\&.
48 .RE
49 .sp
50 .RS 4
51 .ie n \{\
52 \h'-04'\(bu\h'+03'\c
53 .\}
54 .el \{\
55 .sp -1
56 .IP \(bu 2.3
57 .\}
58 With a positional argument (and without
59 \fB\-\-well\-known=\fR) the IMDS data referenced by the specified key is acquired and written to standard output, in unprocessed form\&. IMDS keys are the part of the IMDS acquisition URL that are suffixed to the base URL\&. IMDS keys must begin with a slash ("/")\&. Note that IMDS keys are typically implementation\-specific\&.
60 .RE
61 .sp
62 .RS 4
63 .ie n \{\
64 \h'-04'\(bu\h'+03'\c
65 .\}
66 .el \{\
67 .sp -1
68 .IP \(bu 2.3
69 .\}
70 With the
71 \fB\-\-well\-known=\fR
72 option specified (see below), the indicated well\-known field is written to standard output, in unprocessed form\&. The concept of well\-known fields abstracts IMDS implementation differences to some level, exposing a unified interface for IMDS fields that typically exist on many different implementations, but under implementation\-specific keys\&.
73 .RE
74 .sp
75 .RS 4
76 .ie n \{\
77 \h'-04'\(bu\h'+03'\c
78 .\}
79 .el \{\
80 .sp -1
81 .IP \(bu 2.3
82 .\}
83 With the
84 \fB\-\-userdata\fR
85 option specified (see below) the "userdata" provided via IMDS is written to standard output\&. Under the hood this is similar to
86 \fB\-\-well\-known=userdata\-base\fR,
87 \fB\-\-well\-known=userdata\fR
88 or
89 \fB\-\-well\-known=userdata\-base64\fR\&. Each of the three is tried in turn (in this order), and the first available is returned\&. For
90 \fB\-\-well\-known=userdata\-base\fR
91 the
92 "systemd\-userdata"
93 userdata item is requested\&. For
94 \fB\-\-well\-known=userdata\-base64\fR
95 the returned data is automatically Base64\-decoded\&.
96 .RE
97 .sp
98 .RS 4
99 .ie n \{\
100 \h'-04'\(bu\h'+03'\c
101 .\}
102 .el \{\
103 .sp -1
104 .IP \(bu 2.3
105 .\}
106 With the
107 \fB\-\-import\fR
108 option specified, various well known and userdata fields are imported into the local credential store, where they are used to configure and parameterize the system\&. For details see below\&.
109 .RE
110 .SH "OPTIONS AND COMMANDS"
111 .PP
112 \fB\-\-well\-known=\fR, \fB\-K\fR
113 .RS 4
114 Takes one of
115 "hostname",
116 "region",
117 "zone",
118 "ipv4\-public",
119 "ipv6\-public",
120 "ssh\-key",
121 "userdata",
122 "userdata\-base",
123 "userdata\-base64"\&. Acquires a specific "well\-known" field from IMDS\&. Many of these fields are commonly supported by various IMDS implementations, but typically some fields are not\&. Note that if
124 \fB\-\-well\-known=userdata\-base\fR
125 is used an additional subkey should be specified as positional argument, which encodes the specific userdata item to acquire\&.
126 .sp
127 Added in version 261\&.
128 .RE
129 .PP
130 \fB\-\-refresh=\fR
131 .RS 4
132 Takes a time in seconds as argument, and indicates the required "freshness" of the data, in case cached data is used\&.
133 .sp
134 Added in version 261\&.
135 .RE
136 .PP
137 \fB\-\-cache=\fR
138 .RS 4
139 Takes a boolean\&. If set to false local caching of IMDS is disabled, and the data is always acquired fresh from the IMDS endpoint\&.
140 .sp
141 Added in version 261\&.
142 .RE
143 .PP
144 \fB\-\-userdata\fR, \fB\-u\fR
145 .RS 4
146 Acquire this instance\*(Aqs IMDS user data, if available\&. See above for details\&.
147 .sp
148 Added in version 261\&.
149 .RE
150 .PP
151 \fB\-\-import\fR
152 .RS 4
153 Acquires IMDS data and writes relevant fields as credentials to
154 /run/credstore/\&. This currently covers:
155 .sp
156 .RS 4
157 .ie n \{\
158 \h'-04'\(bu\h'+03'\c
159 .\}
160 .el \{\
161 .sp -1
162 .IP \(bu 2.3
163 .\}
164 If the IMDS user data is a valid JSON object containing a field
165 \fIsystemd\&.credentials\fR
166 (with a JSON array as value) it is processed, importing arbitrary credentials listed in the array\&. Each array item must have a
167 \fIname\fR
168 field indicating the credential name\&. It may have one
169 \fItext\fR,
170 \fIdata\fR
171 or
172 \fIencrypted\fR
173 field, containing the credential data\&. If
174 \fItext\fR
175 is used the value shall be a literal string of the credential value\&. If
176 \fIdata\fR
177 is used the value may be arbitrary binary data encoded in a Base64 string\&. If
178 \fIencrypted\fR
179 is used the value shall be a Base64 encoded encrypted credential\&. See
180 \fBsystemd.system-credentials\fR(7)
181 for information about credentials that may be imported this way\&.
182 .RE
183 .sp
184 .RS 4
185 .ie n \{\
186 \h'-04'\(bu\h'+03'\c
187 .\}
188 .el \{\
189 .sp -1
190 .IP \(bu 2.3
191 .\}
192 If the well\-known
193 \fIssh\-key\fR
194 field is available, its value will be imported into the
195 \fIssh\&.authorized_keys\&.root\fR
196 credential\&.
197 .RE
198 .sp
199 .RS 4
200 .ie n \{\
201 \h'-04'\(bu\h'+03'\c
202 .\}
203 .el \{\
204 .sp -1
205 .IP \(bu 2.3
206 .\}
207 If the well\-known
208 \fIhostname\fR
209 field is available, its value will be imported into the
210 \fIfirstboot\&.hostname\fR
211 credential\&.
212 .RE
213 .sp
214 This command is invoked by the
215 systemd\-imds\-import\&.service
216 run at boot\&.
217 .sp
218 Added in version 261\&.
219 .RE
220 .PP
221 \fB\-h\fR, \fB\-\-help\fR
222 .RS 4
223 Print a short help text and exit\&.
224 .RE
225 .PP
226 \fB\-\-version\fR
227 .RS 4
228 Print a short version string and exit\&.
229 .RE
230 .SH "EXIT STATUS"
231 .PP
232 On success, 0 is returned, a non\-zero failure code otherwise\&.
233 .SH "SEE ALSO"
234 .PP
235 \fBsystemd\fR(1), \[email protected]\fR(8), \fBsystemd-imds-generator\fR(8), \fBsystemd.system-credentials\fR(7)