'\" t
.TH "SYSTEMD\-IMDSD@\&.SERVICE" "8" "" "systemd 261" "systemd-imdsd@.service"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-imdsd@.service, systemd-imdsd, systemd-imdsd.socket, systemd-imdsd-early-network.service \- Cloud IMDS (Instance Metadata Service) client
.SH "SYNOPSIS"
.PP
systemd\-imdsd@\&.service
.PP
systemd\-imdsd\&.socket
.PP
systemd\-imdsd\-early\-network\&.service
.PP
/usr/lib/systemd/systemd\-imdsd
.SH "DESCRIPTION"
.PP
\fBsystemd\-imdsd@\&.service\fR
is a system service that provides local access to IMDS (Instance Metadata Service; or equivalent) functionality, as provided by many public clouds\&.
.PP
The service provides a Varlink IPC interface via
/run/systemd/io\&.systemd\&.InstanceMetadata
to query IMDS fields\&.
.PP
systemd\-imdsd\-early\-network\&.service
is a system service that generates a
\fBsystemd-networkd.service\fR(8)
compatible
\fBsystemd.network\fR(5)
file for configuring the early\-boot network in order to be able to contact the IMDS endpoint\&.
.PP
The
\fBsystemd-imds\fR(1)
tool may be used to query information from this service\&.
.SH "KERNEL COMMAND LINE OPTIONS"
.PP
The IMDS endpoint is typically determined automatically via
\fBhwdb\fR(7)
records, but can also be configured explicitly via the kernel command line, via the following options:
.PP
\fIsystemd\&.imds\&.network=\fR
.RS 4
Takes one of
"off",
"locked",
"unlocked"\&. Controls whether and how to set up networking for IMDS endpoint access\&. Unless set to
"off"
early boot networking is enabled, ensuring that the IMDS endpoint can be reached\&. If set to
"locked"
(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
systemd\-imdsd@\&.service
or its associated tools\&. If set to
"unlocked"
this "prohibit" route is not created, and regular unprivileged processes can directly contact IMDS\&.
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.vendor=\fR
.RS 4
A short string identifying the cloud vendor\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\&.imds\&.vendor=foobarcloud
.fi
.if n \{\
.RE
.\}
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.token_url=\fR
.RS 4
If a bearer token must be acquired to talk to the IMDS service, this is the URL to acquire it from\&.
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.refresh_header_name=\fR
.RS 4
Takes a HTTP header field name (excluding the
":") that declares the header field for passing the TTL value (in seconds) to the HTTP server when acquiring a token\&. Only applies if
\fIsystemd\&.imds\&.token_url=\fR
is set too\&.
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.data_url=\fR
.RS 4
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
"/"\&.
.sp
The data URLs are concatenated from this base URL, the IMDS "key" and the suffix configured via
\fIsystemd\&.imds\&.data_url_suffix=\fR
below\&. Well\-known IMDS "keys" can be configured via the
\fIsystemd\&.imds\&.key=*\fR
options below\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\&.imds\&.data_url=http://169\&.254\&.169\&.254/metadata
.fi
.if n \{\
.RE
.\}
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.data_url_suffix=\fR
.RS 4
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\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\&.imds\&.data_url_suffix=?api\-version=2025\-04\-07&format=text
.fi
.if n \{\
.RE
.\}
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.token_header_name=\fR
.RS 4
Takes a HTTP header field name (excluding the
":") that declares the header field to pass the bearer token acquired from the token URL (see above) in\&. Only applies if
\fIsystemd\&.imds\&.token_url=\fR
is set too\&.
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.extra_header=\fR
.RS 4
Takes a full HTTP header expression (both field name and value, separated by a colon
":") to pass to the HTTP server when requesting data\&. May be used multiple times to set multiple headers\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\&.imds\&.extra_header=Metadata:true
.fi
.if n \{\
.RE
.\}
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.address_ipv4=\fR
.RS 4
Configures the IPv4 address the IMDS endpoint is contacted on\&. This should typically be the IP address also configured via
\fIsystemd\&.imds\&.data_url=\fR
(if IPv4 is used) and is used to set up IP routing\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\&.imds\&.address_ipv4=169\&.254\&.169\&.254
.fi
.if n \{\
.RE
.\}
.sp
Added in version 261\&.
.RE
.PP
\fIsystemd\&.imds\&.address_ipv6=\fR
.RS 4
Configures the IPv6 address the IMDS endpoint is contacted on\&. This should typically be the IP address also configured via
\fIsystemd\&.imds\&.data_url=\fR
(if IPv6 is used) and is used to set up IP routing\&.
.sp
Added in version 261\&.
.RE
.PP
\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
.RS 4
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
"/"\&. They should return the relevant data in plain text\&.
.sp
A special case are the three "userdata" keys: the option
\fIsystemd\&.imds\&.key\&.userdata_base=\fR
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
\fIsystemd\&.imds\&.key\&.userdata=\fR
should be used if only a single userdata field is supported\&. The option
\fIsystemd\&.imds\&.key\&.userdata_base64=\fR
should be used in the same case, but only if the userdata field is encoded in Base64\&.
.sp
Example:
.sp
.if n \{\
.RS 4
.\}
.nf
systemd\&.imds\&.key\&.hostname=/instance/compute/osProfile/computerName
.fi
.if n \{\
.RE
.\}
.sp
Added in version 261\&.
.RE
.SH "CREDENTIALS"
.PP
systemd\-imdsd@\&.service
supports the service credentials logic as implemented by
\fIImportCredential=\fR/\fILoadCredential=\fR/\fISetCredential=\fR
(see
\fBsystemd.exec\fR(5)
for details)\&. The following credentials are used when passed in:
.PP
\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
.RS 4
The various IMDS endpoint parameters\&. The semantics are very close to those configurable via kernel command line, see above for the matching list\&.
.sp
Added in version 261\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd-imds\fR(1), \fBsystemd-imds-generator\fR(8), \fBsystemd-networkd.service\fR(8)