Debian Codegraph @

upstream/debian-unstable/man8/[email protected]

raw
1 '\" t
2 .TH "SYSTEMD\-IMDSD@\&.SERVICE" "8" "" "systemd 261~rc3" "[email protected]"
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 [email protected], systemd-imdsd, systemd-imdsd.socket, systemd-imdsd-early-network.service \- Cloud IMDS (Instance Metadata Service) client
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-imdsd@\&.service
27 .PP
28 systemd\-imdsd\&.socket
29 .PP
30 systemd\-imdsd\-early\-network\&.service
31 .PP
32 /usr/lib/systemd/systemd\-imdsd
33 .SH "DESCRIPTION"
34 .PP
35 \fBsystemd\-imdsd@\&.service\fR
36 is a system service that provides local access to IMDS (Instance Metadata Service; or equivalent) functionality, as provided by many public clouds\&.
37 .PP
38 The service provides a Varlink IPC interface via
39 /run/systemd/io\&.systemd\&.InstanceMetadata
40 to query IMDS fields\&.
41 .PP
42 systemd\-imdsd\-early\-network\&.service
43 is a system service that generates a
44 \fBsystemd-networkd.service\fR(8)
45 compatible
46 \fBsystemd.network\fR(5)
47 file for configuring the early\-boot network in order to be able to contact the IMDS endpoint\&.
48 .PP
49 The
50 \fBsystemd-imds\fR(1)
51 tool may be used to query information from this service\&.
52 .SH "KERNEL COMMAND LINE OPTIONS"
53 .PP
54 The IMDS endpoint is typically determined automatically via
55 \fBhwdb\fR(7)
56 records, but can also be configured explicitly via the kernel command line, via the following options:
57 .PP
58 \fIsystemd\&.imds\&.network=\fR
59 .RS 4
60 Takes one of
61 "off",
62 "locked",
63 "unlocked"\&. Controls whether and how to set up networking for IMDS endpoint access\&. Unless set to
64 "off"
65 early boot networking is enabled, ensuring that the IMDS endpoint can be reached\&. If set to
66 "locked"
67 (the default) direct access to the IMDS endpoint by regular unprivileged processes is disabled via a "prohibit" route, so that any access must be done through
68 systemd\-imdsd@\&.service
69 or its associated tools\&. If set to
70 "unlocked"
71 this "prohibit" route is not created, and regular unprivileged processes can directly contact IMDS\&.
72 .sp
73 Added in version 261\&.
74 .RE
75 .PP
76 \fIsystemd\&.imds\&.vendor=\fR
77 .RS 4
78 A short string identifying the cloud vendor\&.
79 .sp
80 Example:
81 .sp
82 .if n \{\
83 .RS 4
84 .\}
85 .nf
86 systemd\&.imds\&.vendor=foobarcloud
87 .fi
88 .if n \{\
89 .RE
90 .\}
91 .sp
92 Added in version 261\&.
93 .RE
94 .PP
95 \fIsystemd\&.imds\&.token_url=\fR
96 .RS 4
97 If a bearer token must be acquired to talk to the IMDS service, this is the URL to acquire it from\&.
98 .sp
99 Added in version 261\&.
100 .RE
101 .PP
102 \fIsystemd\&.imds\&.refresh_header_name=\fR
103 .RS 4
104 Takes a HTTP header field name (excluding the
105 ":") that declares the header field for passing the TTL value (in seconds) to the HTTP server when acquiring a token\&. Only applies if
106 \fIsystemd\&.imds\&.token_url=\fR
107 is set too\&.
108 .sp
109 Added in version 261\&.
110 .RE
111 .PP
112 \fIsystemd\&.imds\&.data_url=\fR
113 .RS 4
114 Takes the base URL to acquire the IMDS data from (the IMDS "endpoint")\&. All data fields are acquired from below this URL\&. This URL should typically not end in
115 "/"\&.
116 .sp
117 The data URLs are concatenated from this base URL, the IMDS "key" and the suffix configured via
118 \fIsystemd\&.imds\&.data_url_suffix=\fR
119 below\&. Well\-known IMDS "keys" can be configured via the
120 \fIsystemd\&.imds\&.key=*\fR
121 options below\&.
122 .sp
123 Example:
124 .sp
125 .if n \{\
126 .RS 4
127 .\}
128 .nf
129 systemd\&.imds\&.data_url=http://169\&.254\&.169\&.254/metadata
130 .fi
131 .if n \{\
132 .RE
133 .\}
134 .sp
135 Added in version 261\&.
136 .RE
137 .PP
138 \fIsystemd\&.imds\&.data_url_suffix=\fR
139 .RS 4
140 If specified, this field is appended to the end of the data URL (after appending the IMDS "key" to the data base URL), see above\&.
141 .sp
142 Example:
143 .sp
144 .if n \{\
145 .RS 4
146 .\}
147 .nf
148 systemd\&.imds\&.data_url_suffix=?api\-version=2025\-04\-07&format=text
149 .fi
150 .if n \{\
151 .RE
152 .\}
153 .sp
154 Added in version 261\&.
155 .RE
156 .PP
157 \fIsystemd\&.imds\&.token_header_name=\fR
158 .RS 4
159 Takes a HTTP header field name (excluding the
160 ":") that declares the header field to pass the bearer token acquired from the token URL (see above) in\&. Only applies if
161 \fIsystemd\&.imds\&.token_url=\fR
162 is set too\&.
163 .sp
164 Added in version 261\&.
165 .RE
166 .PP
167 \fIsystemd\&.imds\&.extra_header=\fR
168 .RS 4
169 Takes a full HTTP header expression (both field name and value, separated by a colon
170 ":") to pass to the HTTP server when requesting data\&. May be used multiple times to set multiple headers\&.
171 .sp
172 Example:
173 .sp
174 .if n \{\
175 .RS 4
176 .\}
177 .nf
178 systemd\&.imds\&.extra_header=Metadata:true
179 .fi
180 .if n \{\
181 .RE
182 .\}
183 .sp
184 Added in version 261\&.
185 .RE
186 .PP
187 \fIsystemd\&.imds\&.address_ipv4=\fR
188 .RS 4
189 Configures the IPv4 address the IMDS endpoint is contacted on\&. This should typically be the IP address also configured via
190 \fIsystemd\&.imds\&.data_url=\fR
191 (if IPv4 is used) and is used to set up IP routing\&.
192 .sp
193 Example:
194 .sp
195 .if n \{\
196 .RS 4
197 .\}
198 .nf
199 systemd\&.imds\&.address_ipv4=169\&.254\&.169\&.254
200 .fi
201 .if n \{\
202 .RE
203 .\}
204 .sp
205 Added in version 261\&.
206 .RE
207 .PP
208 \fIsystemd\&.imds\&.address_ipv6=\fR
209 .RS 4
210 Configures the IPv6 address the IMDS endpoint is contacted on\&. This should typically be the IP address also configured via
211 \fIsystemd\&.imds\&.data_url=\fR
212 (if IPv6 is used) and is used to set up IP routing\&.
213 .sp
214 Added in version 261\&.
215 .RE
216 .PP
217 \fIsystemd\&.imds\&.key\&.hostname=\fR, \fIsystemd\&.imds\&.key\&.region=\fR, \fIsystemd\&.imds\&.key\&.zone=\fR, \fIsystemd\&.imds\&.key\&.ipv4_public=\fR, \fIsystemd\&.imds\&.key\&.ipv6_public=\fR, \fIsystemd\&.imds\&.key\&.ssh_key=\fR, \fIsystemd\&.imds\&.key\&.userdata=\fR, \fIsystemd\&.imds\&.key\&.userdata_base=\fR, \fIsystemd\&.imds\&.key\&.userdata_base64=\fR
218 .RS 4
219 Configures strings to concatenate to the data base URL (see above) to acquire data for various "well\-known" fields\&. These strings must begin with a
220 "/"\&. They should return the relevant data in plain text\&.
221 .sp
222 A special case are the three "userdata" keys: the option
223 \fIsystemd\&.imds\&.key\&.userdata_base=\fR
224 should be used if the IMDS service knows a concept of multiple userdata fields, and a field identifier thus still needs to be appended to the userdata base URL\&. The option
225 \fIsystemd\&.imds\&.key\&.userdata=\fR
226 should be used if only a single userdata field is supported\&. The option
227 \fIsystemd\&.imds\&.key\&.userdata_base64=\fR
228 should be used in the same case, but only if the userdata field is encoded in Base64\&.
229 .sp
230 Example:
231 .sp
232 .if n \{\
233 .RS 4
234 .\}
235 .nf
236 systemd\&.imds\&.key\&.hostname=/instance/compute/osProfile/computerName
237 .fi
238 .if n \{\
239 .RE
240 .\}
241 .sp
242 Added in version 261\&.
243 .RE
244 .SH "CREDENTIALS"
245 .PP
246 systemd\-imdsd@\&.service
247 supports the service credentials logic as implemented by
248 \fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
249 (see
250 \fBsystemd.exec\fR(5)
251 for details)\&. The following credentials are used when passed in:
252 .PP
253 \fIimds\&.vendor\fR, \fIimds\&.vendor_token\fR, \fIimds\&.refresh_header_name\fR, \fIimds\&.data_url\fR, \fIimds\&.data_url_suffix\fR, \fIimds\&.token_header_name\fR, \fIimds\&.extra_header\fR, \fIimds\&.extra_header2\fR, \fIimds\&.extra_header3\fR, \fIimds\&.extra_header\&...\fR, \fIimds\&.address_ipv4\fR, \fIimds\&.address_ipv6\fR, \fIimds\&.key_hostname\fR, \fIimds\&.key_region\fR, \fIimds\&.key_zone\fR, \fIimds\&.key_ipv4_public\fR, \fIimds\&.key_ipv6_public\fR, \fIimds\&.key_ssh_key\fR, \fIimds\&.key_userdata\fR, \fIimds\&.key_userdata_base\fR, \fIimds\&.key_userdata_base64\fR
254 .RS 4
255 The various IMDS endpoint parameters\&. The semantics are very close to those configurable via kernel command line, see above for the matching list\&.
256 .sp
257 Added in version 261\&.
258 .RE
259 .SH "SEE ALSO"
260 .PP
261 \fBsystemd\fR(1), \fBsystemd-imds\fR(1), \fBsystemd-imds-generator\fR(8), \fBsystemd-networkd.service\fR(8)