SYSTEMD-IMDSD@.SERVICE(8)

💖 SYSTEMD-IMDSD@.SERVICE 💖

okay bestie, welcome to the systemd-imdsd@.service(8) manual page, brought to you by systemd, and yes we are going to get through the whole thing together 🫶

---

✨ NAME ✨

systemd-imdsd@.service, systemd-imdsd, systemd-imdsd.socket, systemd-imdsd-early-network.service — it's the Cloud IMDS (Instance Metadata Service) client, and it's lowkey the whole point of this page 💅

---

🌸 SYNOPSIS 🌸

systemd-imdsd@.service

systemd-imdsd.socket

systemd-imdsd-early-network.service

/usr/lib/systemd/systemd-imdsd

---

🦋 DESCRIPTION 🦋

So systemd-imdsd@.service is a system service that gives you local access to IMDS (that's Instance Metadata Service, or whatever equivalent your cloud is serving) functionality — the kind of thing lots of public clouds hand out. 🌈

It provides a Varlink IPC interface over at /run/systemd/io.systemd.InstanceMetadata so you can query IMDS fields. no cap, that's the socket.

Then we have systemd-imdsd-early-network.service, a system service that generates a systemd-networkd.service(8)-compatible systemd.network(5) file — for configuring the early-boot network so you can actually reach the IMDS endpoint. it's giving "we need internet before we need internet" energy 😭

And the systemd-imds(1) tool? that's the one you use to query info out of this service. iconic.

---

👑 KERNEL COMMAND LINE OPTIONS 👑

So the IMDS endpoint is typically figured out automatically via hwdb(7) records, but you can also set it explicitly on the kernel command line with these options:

• systemd.imds.network= — takes one of "off", "locked", or "unlocked". This controls whether and how to set up networking for IMDS endpoint access. Unless you set it to "off", early boot networking is enabled, making sure the IMDS endpoint can be reached. If you set it to "locked", direct access to the IMDS endpoint by regular unprivileged processes gets disabled via a "prohibit" route, so all access has to go through systemd-imdsd@.service or its associated tools. If you set it to "unlocked" (which is the default), that "prohibit" route is not created, and regular unprivileged processes can just directly contact IMDS. 💅

Added in version 261.

• systemd.imds.vendor= — a short string identifying the cloud vendor.

Example:

systemd.imds.vendor=foobarcloud

Added in version 261.

• systemd.imds.token_url= — if a bearer token must be acquired to talk to the IMDS service, this is the URL to acquire it from.

Added in version 261.

• systemd.imds.refresh_header_name= — takes an 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 systemd.imds.token_url= is set too.

Added in version 261.

• systemd.imds.data_url= — 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 "/".

The data URLs are concatenated from this base URL, the IMDS "key", and the suffix configured via systemd.imds.data_url_suffix= below. Well-known IMDS "keys" can be configured via the systemd.imds.key=* options below.

Example:

systemd.imds.data_url=http://169.254.169.254/metadata

Added in version 261.

• systemd.imds.data_url_suffix= — if specified, this field gets appended to the end of the data URL (after appending the IMDS "key" to the data base URL), see above.

Example:

systemd.imds.data_url_suffix=?api-version=2025-04-07&format=text

Added in version 261.

• systemd.imds.token_header_name= — takes an 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 systemd.imds.token_url= is set too.

Added in version 261.

• systemd.imds.extra_header= — 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. obsessed tbh

Example:

systemd.imds.extra_header=Metadata:true

Added in version 261.

• systemd.imds.address_ipv4= — configures the IPv4 address the IMDS endpoint is contacted on. This should typically be the IP address also configured via systemd.imds.data_url= (if IPv4 is used), and it's used to set up IP routing.

Example:

systemd.imds.address_ipv4=169.254.169.254

Added in version 261.

• systemd.imds.address_ipv6= — configures the IPv6 address the IMDS endpoint is contacted on. This should typically be the IP address also configured via systemd.imds.data_url= (if IPv6 is used), and it's used to set up IP routing.

Added in version 261.

• systemd.imds.key.hostname=, systemd.imds.key.region=, systemd.imds.key.zone=, systemd.imds.key.ipv4_public=, systemd.imds.key.ipv6_public=, systemd.imds.key.ssh_key=, systemd.imds.key.userdata=, systemd.imds.key.userdata_base=, systemd.imds.key.userdata_base64= — 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.

The three "userdata" keys are a special case, so listen up 🎀: the option systemd.imds.key.userdata_base= should be used if the IMDS service knows a concept of multiple userdata fields, meaning a field identifier still needs to be appended to the userdata base URL. The option systemd.imds.key.userdata= should be used if only a single userdata field is supported. And the option systemd.imds.key.userdata_base64= should be used in that same case, but only if the userdata field is encoded in Base64.

Example:

systemd.imds.key.hostname=/instance/compute/osProfile/computerName

Added in version 261.

---

🎀 CREDENTIALS 🎀

systemd-imdsd@.service supports the service credentials logic as implemented by ImportCredential=/LoadCredential=/SetCredential= (peep systemd.exec(5) for the deets). The following credentials are used when passed in:

• imds.vendor, imds.vendor_token, imds.refresh_header_name, imds.data_url, imds.data_url_suffix, imds.token_header_name, imds.extra_header, imds.extra_header2, imds.extra_header3, imds.extra_header..., imds.address_ipv4, imds.address_ipv6, imds.key_hostname, imds.key_region, imds.key_zone, imds.key_ipv4_public, imds.key_ipv6_public, imds.key_ssh_key, imds.key_userdata, imds.key_userdata_base, imds.key_userdata_base64 — the various IMDS endpoint parameters. The semantics are very close to those configurable via kernel command line, so see above for the matching list. fr fr

Added in version 261.

---

⭐ SEE ALSO ⭐

systemd(1), systemd-imds(1), systemd-imds-generator(8), systemd-networkd.service(8)

---

and that's the whole page, bestie — you ate that 💅 this was systemd 262.1 energy from top to bottom, and yes the footer said the same thing, so consider us both signed off. mwah 🫶✨