systemd-imds, systemd-imds-import.service — Cloud IMDS (Instance Metadata Service) tool
systemd-imds-import.service
systemd-imds [OPTIONS...] [KEY]
systemd-imds is a tool for acquiring data from IMDS (Instance Metadata Service), as provided in many cloud environments. It is a client to systemd-imdsd@.service(8), and provides access to IMDS data from shell environments.
The tool can operate in one of five modes:
Without positional arguments (and without the --well-known= switch)
general IMDS service data and a few well known fields are displayed in human friendly
form.
With a positional argument (and without --well-known=) 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.
With the --well-known= 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.
With the --userdata option 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 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.
With the --import 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.
--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. Note that if --well-known=userdata-base is used an additional subkey should be
specified as positional argument, which encodes the specific userdata item to acquire.
--refresh=¶Takes a time in seconds as argument, and indicates the required "freshness" of the data, in case cached data is used.
--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.
--userdata, -u¶Acquire this instance's IMDS user data, if available. See above for details.
--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.
-h, --help¶--version¶