Name
systemd-imds, systemd-imds-import.service — Cloud IMDS (Instance Metadata Service) tool
Synopsis
systemd-imds-import.service
systemd-imds [OPTIONS...] [KEY]
Description¶
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
--userdataoption 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=userdataor--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-basethe "systemd-userdata" userdata item is requested. For--well-known=userdata-base64the returned data is automatically Base64-decoded.With the
--importoption 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.
In addition, when 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.
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. Note that if--well-known=userdata-baseis 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 anamefield indicating the credential name. It may have onetext,dataorencryptedfield, containing the credential data. Iftextis used the value shall be a literal string of the credential value. Ifdatais used the value may be arbitrary binary data encoded in a Base64 string. Ifencryptedis 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-keyfield is available, its value will be imported into thessh.authorized_keys.rootcredential.If the well-known
hostnamefield is available, its value will be imported into thefirstboot.hostnamecredential.
This command is invoked by the
systemd-imds-import.servicerun at boot.-h,--help¶--version¶Print a short version string and exit.