SYSTEMD-IMDS(1)

💖 SYSTEMD-IMDS 💖

okay bestie, sit down, hydrate, because we're talking about systemd-imds — the Cloud IMDS (Instance Metadata Service) tool, plus its lil service sidekick systemd-imds-import.service. this is the systemd-imds manual, and yes it's giving very "the cloud knows everything about me and honestly same" 💅

---

✨ SYNOPSIS ✨

systemd-imds-import.service

systemd-imds [OPTIONS...] [KEY]

---

🌸 DESCRIPTION 🌸

so systemd-imds is the tool you use to grab data from IMDS (Instance Metadata Service) — that's the thing basically every cloud environment has lurking behind a link-local address, serving up facts about your instance. it's a client to systemd-imdsd@.service(8), and its whole job is making IMDS data reachable from your shell. no cap. 🦋

the tool can operate in one of five modes:

• no positional args, and no --well-known= switch → you get general IMDS service data plus a few well known fields, all displayed in a human friendly form. ✨
• a positional argument, and no --well-known= → the IMDS data referenced by that key gets acquired and written to standard output, in unprocessed form. IMDS keys are the part of the IMDS acquisition URL that gets suffixed to the base URL. IMDS keys must begin with a slash ("/"). and heads up: IMDS keys are typically implementation-specific, so don't expect them to travel well between clouds 🫶
• --well-known= specified (see below) → the indicated well-known field is written to standard output, in unprocessed form. the whole concept of well-known fields exists to abstract 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. it's giving "universal translator" 💫
• --userdata specified (see below) → the "userdata" provided via IMDS is written to standard output. under the hood this is similar to --well-known=userdata-base, --well-known=userdata or --well-known=userdata-base64. each of the three is tried in turn (in this order), and the first available one is returned. for --well-known=userdata-base the "systemd-userdata" userdata item is requested. for --well-known=userdata-base64 the returned data is automatically Base64-decoded. okay that's actually so clever of it 😭
• --import specified → various well known and userdata fields are imported into the local credential store, where they get used to configure and parameterize the system. details below, keep scrolling bestie 👑

and ALSO — plot twist — when it's invoked as a Varlink service (i.e. via socket activation through systemd-imds-metrics.socket), systemd-imds acts as an io.systemd.Metrics provider for systemd-report(1). it exposes the detected cloud vendor and the well-known "hostname", "region", "zone", "ipv4-public" and "ipv6-public" fields as metrics in the "io.systemd.InstanceMetadata." namespace. the data is acquired on demand from systemd-imdsd@.service(8), benefiting from its local cache. main character energy fr fr 🔥

---

🎀 OPTIONS AND COMMANDS 🎀

• --well-known=, -K — takes one of "hostname", "region", "zone", "ipv4-public", "ipv6-public", "ssh-key", "userdata", "userdata-base", "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 — so vibe check your cloud first. note that if --well-known=userdata-base is used, an additional subkey should be specified as a positional argument, which encodes the specific userdata item to acquire. 💖

Added in version 261.

• --refresh= — takes a time in seconds as argument, and indicates the required "freshness" of the data, in case cached data is used. yes it's literally a freshness check, like produce at the farmer's market 🍓

Added in version 261.

• --cache= — takes a boolean. if set to false, local caching of IMDS is disabled, and the data is always acquired fresh from the IMDS endpoint. no leftovers, periodt.

Added in version 261.

• --userdata, -u — acquire this instance's IMDS user data, if available. see above for details, bestie, i already explained it up there ⬆️

Added in version 261.

• --import — acquires IMDS data and writes relevant fields as credentials to /run/credstore/. this currently covers:
  • if the IMDS user data is a valid JSON object containing a field systemd.credentials (with a JSON array as value) it is processed, importing arbitrary credentials listed in the array. each array item must have a name field indicating the credential name. it may have one text, data or encrypted field, containing the credential data. if text is used the value shall be a literal string of the credential value. if data is used the value may be arbitrary binary data encoded in a Base64 string. if encrypted is used the value shall be a Base64 encoded encrypted credential. see systemd.system-credentials(7) for information about credentials that may be imported this way. 🔐
  • if the well-known ssh-key field is available, its value will be imported into the ssh.authorized_keys.root credential. 🗝️
  • if the well-known hostname field is available, its value will be imported into the firstboot.hostname credential. 🏷️

this command is invoked by the systemd-imds-import.service run at boot. iconic behaviour, honestly.

Added in version 261.

• -h, --help — print a short help text and exit. the "hey what was that flag again" button 🫶
• --version — print a short version string and exit. 🎀

---

💀 EXIT STATUS 💀

on success, 0 is returned, a non-zero failure code otherwise. that's it. that's the whole status report. slay.

---

🌈 SEE ALSO 🌈

systemd(1), systemd-imdsd@.service(8), systemd-imds-generator(8), systemd-report(1), systemd.system-credentials(7)

---

and that's the tea ☕ this whole page comes to you from systemd 262.1, so go forth, read your instance metadata, and remember: you're the main character of your own cloud 💜✨ no cap, fr fr.