| 1 |
'\" t |
| 2 |
.TH "SYSTEMD\-IMDS" "1" "" "systemd 261~rc3" "systemd-imds" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
systemd-imds, systemd-imds-import.service \- Cloud IMDS (Instance Metadata Service) tool |
| 24 |
.SH "SYNOPSIS" |
| 25 |
.PP |
| 26 |
systemd\-imds\-import\&.service |
| 27 |
.HP \w'\fBsystemd\-imds\fR\ 'u |
| 28 |
\fBsystemd\-imds\fR [OPTIONS...] [KEY] |
| 29 |
.SH "DESCRIPTION" |
| 30 |
.PP |
| 31 |
\fBsystemd\-imds\fR |
| 32 |
is a tool for acquiring data from IMDS (Instance Metadata Service), as provided in many cloud environments\&. It is a client to |
| 33 |
\[email protected]\fR(8), and provides access to IMDS data from shell environments\&. |
| 34 |
.PP |
| 35 |
The tool can operate in one of five modes: |
| 36 |
.sp |
| 37 |
.RS 4 |
| 38 |
.ie n \{\ |
| 39 |
\h'-04'\(bu\h'+03'\c |
| 40 |
.\} |
| 41 |
.el \{\ |
| 42 |
.sp -1 |
| 43 |
.IP \(bu 2.3 |
| 44 |
.\} |
| 45 |
Without positional arguments (and without the |
| 46 |
\fB\-\-well\-known=\fR |
| 47 |
switch) general IMDS service data and a few well known fields are displayed in human friendly form\&. |
| 48 |
.RE |
| 49 |
.sp |
| 50 |
.RS 4 |
| 51 |
.ie n \{\ |
| 52 |
\h'-04'\(bu\h'+03'\c |
| 53 |
.\} |
| 54 |
.el \{\ |
| 55 |
.sp -1 |
| 56 |
.IP \(bu 2.3 |
| 57 |
.\} |
| 58 |
With a positional argument (and without |
| 59 |
\fB\-\-well\-known=\fR) 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\&. |
| 60 |
.RE |
| 61 |
.sp |
| 62 |
.RS 4 |
| 63 |
.ie n \{\ |
| 64 |
\h'-04'\(bu\h'+03'\c |
| 65 |
.\} |
| 66 |
.el \{\ |
| 67 |
.sp -1 |
| 68 |
.IP \(bu 2.3 |
| 69 |
.\} |
| 70 |
With the |
| 71 |
\fB\-\-well\-known=\fR |
| 72 |
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\&. |
| 73 |
.RE |
| 74 |
.sp |
| 75 |
.RS 4 |
| 76 |
.ie n \{\ |
| 77 |
\h'-04'\(bu\h'+03'\c |
| 78 |
.\} |
| 79 |
.el \{\ |
| 80 |
.sp -1 |
| 81 |
.IP \(bu 2.3 |
| 82 |
.\} |
| 83 |
With the |
| 84 |
\fB\-\-userdata\fR |
| 85 |
option specified (see below) the "userdata" provided via IMDS is written to standard output\&. Under the hood this is similar to |
| 86 |
\fB\-\-well\-known=userdata\-base\fR, |
| 87 |
\fB\-\-well\-known=userdata\fR |
| 88 |
or |
| 89 |
\fB\-\-well\-known=userdata\-base64\fR\&. Each of the three is tried in turn (in this order), and the first available is returned\&. For |
| 90 |
\fB\-\-well\-known=userdata\-base\fR |
| 91 |
the |
| 92 |
"systemd\-userdata" |
| 93 |
userdata item is requested\&. For |
| 94 |
\fB\-\-well\-known=userdata\-base64\fR |
| 95 |
the returned data is automatically Base64\-decoded\&. |
| 96 |
.RE |
| 97 |
.sp |
| 98 |
.RS 4 |
| 99 |
.ie n \{\ |
| 100 |
\h'-04'\(bu\h'+03'\c |
| 101 |
.\} |
| 102 |
.el \{\ |
| 103 |
.sp -1 |
| 104 |
.IP \(bu 2.3 |
| 105 |
.\} |
| 106 |
With the |
| 107 |
\fB\-\-import\fR |
| 108 |
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\&. |
| 109 |
.RE |
| 110 |
.SH "OPTIONS AND COMMANDS" |
| 111 |
.PP |
| 112 |
\fB\-\-well\-known=\fR, \fB\-K\fR |
| 113 |
.RS 4 |
| 114 |
Takes one of |
| 115 |
"hostname", |
| 116 |
"region", |
| 117 |
"zone", |
| 118 |
"ipv4\-public", |
| 119 |
"ipv6\-public", |
| 120 |
"ssh\-key", |
| 121 |
"userdata", |
| 122 |
"userdata\-base", |
| 123 |
"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 |
| 124 |
\fB\-\-well\-known=userdata\-base\fR |
| 125 |
is used an additional subkey should be specified as positional argument, which encodes the specific userdata item to acquire\&. |
| 126 |
.sp |
| 127 |
Added in version 261\&. |
| 128 |
.RE |
| 129 |
.PP |
| 130 |
\fB\-\-refresh=\fR |
| 131 |
.RS 4 |
| 132 |
Takes a time in seconds as argument, and indicates the required "freshness" of the data, in case cached data is used\&. |
| 133 |
.sp |
| 134 |
Added in version 261\&. |
| 135 |
.RE |
| 136 |
.PP |
| 137 |
\fB\-\-cache=\fR |
| 138 |
.RS 4 |
| 139 |
Takes a boolean\&. If set to false local caching of IMDS is disabled, and the data is always acquired fresh from the IMDS endpoint\&. |
| 140 |
.sp |
| 141 |
Added in version 261\&. |
| 142 |
.RE |
| 143 |
.PP |
| 144 |
\fB\-\-userdata\fR, \fB\-u\fR |
| 145 |
.RS 4 |
| 146 |
Acquire this instance\*(Aqs IMDS user data, if available\&. See above for details\&. |
| 147 |
.sp |
| 148 |
Added in version 261\&. |
| 149 |
.RE |
| 150 |
.PP |
| 151 |
\fB\-\-import\fR |
| 152 |
.RS 4 |
| 153 |
Acquires IMDS data and writes relevant fields as credentials to |
| 154 |
/run/credstore/\&. This currently covers: |
| 155 |
.sp |
| 156 |
.RS 4 |
| 157 |
.ie n \{\ |
| 158 |
\h'-04'\(bu\h'+03'\c |
| 159 |
.\} |
| 160 |
.el \{\ |
| 161 |
.sp -1 |
| 162 |
.IP \(bu 2.3 |
| 163 |
.\} |
| 164 |
If the IMDS user data is a valid JSON object containing a field |
| 165 |
\fIsystemd\&.credentials\fR |
| 166 |
(with a JSON array as value) it is processed, importing arbitrary credentials listed in the array\&. Each array item must have a |
| 167 |
\fIname\fR |
| 168 |
field indicating the credential name\&. It may have one |
| 169 |
\fItext\fR, |
| 170 |
\fIdata\fR |
| 171 |
or |
| 172 |
\fIencrypted\fR |
| 173 |
field, containing the credential data\&. If |
| 174 |
\fItext\fR |
| 175 |
is used the value shall be a literal string of the credential value\&. If |
| 176 |
\fIdata\fR |
| 177 |
is used the value may be arbitrary binary data encoded in a Base64 string\&. If |
| 178 |
\fIencrypted\fR |
| 179 |
is used the value shall be a Base64 encoded encrypted credential\&. See |
| 180 |
\fBsystemd.system-credentials\fR(7) |
| 181 |
for information about credentials that may be imported this way\&. |
| 182 |
.RE |
| 183 |
.sp |
| 184 |
.RS 4 |
| 185 |
.ie n \{\ |
| 186 |
\h'-04'\(bu\h'+03'\c |
| 187 |
.\} |
| 188 |
.el \{\ |
| 189 |
.sp -1 |
| 190 |
.IP \(bu 2.3 |
| 191 |
.\} |
| 192 |
If the well\-known |
| 193 |
\fIssh\-key\fR |
| 194 |
field is available, its value will be imported into the |
| 195 |
\fIssh\&.authorized_keys\&.root\fR |
| 196 |
credential\&. |
| 197 |
.RE |
| 198 |
.sp |
| 199 |
.RS 4 |
| 200 |
.ie n \{\ |
| 201 |
\h'-04'\(bu\h'+03'\c |
| 202 |
.\} |
| 203 |
.el \{\ |
| 204 |
.sp -1 |
| 205 |
.IP \(bu 2.3 |
| 206 |
.\} |
| 207 |
If the well\-known |
| 208 |
\fIhostname\fR |
| 209 |
field is available, its value will be imported into the |
| 210 |
\fIfirstboot\&.hostname\fR |
| 211 |
credential\&. |
| 212 |
.RE |
| 213 |
.sp |
| 214 |
This command is invoked by the |
| 215 |
systemd\-imds\-import\&.service |
| 216 |
run at boot\&. |
| 217 |
.sp |
| 218 |
Added in version 261\&. |
| 219 |
.RE |
| 220 |
.PP |
| 221 |
\fB\-h\fR, \fB\-\-help\fR |
| 222 |
.RS 4 |
| 223 |
Print a short help text and exit\&. |
| 224 |
.RE |
| 225 |
.PP |
| 226 |
\fB\-\-version\fR |
| 227 |
.RS 4 |
| 228 |
Print a short version string and exit\&. |
| 229 |
.RE |
| 230 |
.SH "EXIT STATUS" |
| 231 |
.PP |
| 232 |
On success, 0 is returned, a non\-zero failure code otherwise\&. |
| 233 |
.SH "SEE ALSO" |
| 234 |
.PP |
| 235 |
\fBsystemd\fR(1), \[email protected]\fR(8), \fBsystemd-imds-generator\fR(8), \fBsystemd.system-credentials\fR(7) |