]>
Commit | Line | Data |
---|---|---|
fe672fe5 LP |
1 | --- |
2 | title: Credentials | |
3 | category: Concepts | |
4 | layout: default | |
5 | SPDX-License-Identifier: LGPL-2.1-or-later | |
6 | --- | |
7 | ||
8 | # System and Service Credentials | |
9 | ||
10 | The `systemd` service manager supports a "credential" concept for securely | |
11 | acquiring and passing credential data to systems and services. The precise | |
12 | nature of the credential data is up to applications, but the concept is | |
13 | intended to provide systems and services with potentially security sensitive | |
14 | cryptographic keys, certificates, passwords, identity information and similar | |
15 | types of information. It may also be used as generic infrastructure for | |
16 | parameterizing systems and services. | |
17 | ||
18 | Traditionally, data of this nature has often been provided to services via | |
19 | environment variables (which is problematic because by default they are | |
20 | inherited down the process tree, have size limitations, and issues with binary | |
21 | data) or simple, unencrypted files on disk. `systemd`'s system and service | |
22 | credentials are supposed to provide a better alternative for this | |
23 | purpose. Specifically, the following features are provided: | |
24 | ||
25 | 1. Service credentials are acquired at the moment of service activation, and | |
26 | released on service deactivation. They are immutable during the service | |
27 | runtime. | |
28 | ||
29 | 2. Service credentials are accessible to service code as regular files, the | |
30 | path to access them is derived from the environment variable | |
31 | `$CREDENTIALS_DIRECTORY`. | |
32 | ||
33 | 3. Access to credentials is restricted to the service's user. Unlike | |
34 | environment variables the credential data is not propagated down the process | |
35 | tree. Instead each time a credential is accessed an access check is enforced | |
36 | by the kernel. If the service is using file system namespacing the loaded | |
30fd9a2d | 37 | credential data is invisible to all other services. |
fe672fe5 LP |
38 | |
39 | 4. Service credentials may be acquired from files on disk, specified as literal | |
40 | strings in unit files, acquired from another service dynamically via an | |
41 | `AF_UNIX` socket, or inherited from the system credentials the system itself | |
42 | received. | |
43 | ||
44 | 5. Credentials may optionally be encrypted and authenticated, either with a key | |
45 | derived from a local TPM2 chip, or one stored in `/var/`, or both. This | |
46 | encryption is supposed to *just* *work*, and requires no manual setup. (That | |
47 | is besides first encrypting relevant credentials with one simple command, | |
48 | see below.) | |
49 | ||
50 | 6. Service credentials are placed in non-swappable memory. (If permissions | |
51 | allow it, via `ramfs`.) | |
52 | ||
8de7de46 | 53 | 7. Credentials may be acquired from a hosting VM hypervisor (SMBIOS OEM strings |
df5f51c3 LP |
54 | or qemu `fw_cfg`), a hosting container manager, the kernel command line, |
55 | from the initrd, or from the UEFI environment via the EFI System Partition | |
56 | (via `systemd-stub`). Such system credentials may then be propagated into | |
8de7de46 | 57 | individual services as needed. |
fe672fe5 LP |
58 | |
59 | 8. Credentials are an effective way to pass parameters into services that run | |
60 | with `RootImage=` or `RootDirectory=` and thus cannot read these resources | |
5c90c67a BF |
61 | directly from the host directory tree. |
62 | Specifically, [Portable Services](PORTABLE_SERVICES.md) may be | |
63 | parameterized this way securely and robustly. | |
fe672fe5 LP |
64 | |
65 | 9. Credentials can be binary and relatively large (though currently an overall | |
66 | size limit of 1M per service is enforced). | |
67 | ||
68 | ## Configuring per-Service Credentials | |
69 | ||
70 | Within unit files, there are four settings to configure service credentials. | |
71 | ||
72 | 1. `LoadCredential=` may be used to load a credential from disk, from an | |
73 | `AF_UNIX` socket, or propagate them from a system credential. | |
74 | ||
df5f51c3 LP |
75 | 2. `ImportCredential=` may be used to load one or more (optionally encrypted) |
76 | credentials from disk or from the credential stores. | |
bbfb25f4 | 77 | |
df5f51c3 | 78 | 3. `SetCredential=` may be used to set a credential to a literal string encoded |
fe672fe5 LP |
79 | in the unit file. Because unit files are world-readable (both on disk and |
80 | via D-Bus), this should only be used for credentials that aren't sensitive, | |
5811490a | 81 | e.g. public keys or certificates, but not private keys. |
fe672fe5 | 82 | |
df5f51c3 | 83 | 4. `LoadCredentialEncrypted=` is similar to `LoadCredential=` but will load an |
fe672fe5 LP |
84 | encrypted credential, and decrypt it before passing it to the service. For |
85 | details on credential encryption, see below. | |
86 | ||
df5f51c3 | 87 | 5. `SetCredentialEncrypted=` is similar to `SetCredential=` but expects an |
fe672fe5 LP |
88 | encrypted credential to be specified literally. Unlike `SetCredential=` it |
89 | is thus safe to be used even for sensitive information, because even though | |
90 | unit files are world readable, the ciphertext included in them cannot be | |
91 | decoded unless access to TPM2/encryption key is available. | |
92 | ||
93 | Each credential configured with these options carries a short name (suitable | |
94 | for inclusion in a filename) in the unit file, under which the invoked service | |
95 | code can then retrieve it. Each name should only be specified once. | |
96 | ||
97 | For details about these four settings [see the man | |
98 | page](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Credentials). | |
99 | ||
100 | It is a good idea to also enable mount namespacing for services that process | |
101 | credentials configured this way. If so, the runtime credential directory of the | |
102 | specific service is not visible to any other service. Use `PrivateMounts=` as | |
103 | minimal option to enable such namespacing. Note that many other sandboxing | |
104 | settings (e.g. `ProtectSystem=`, `ReadOnlyPaths=` and similar) imply | |
105 | `PrivateMounts=`, hence oftentimes it's not necessary to set this option | |
106 | explicitly. | |
107 | ||
108 | ## Programming Interface from Service Code | |
109 | ||
110 | When a service is invoked with one or more credentials set it will have an | |
111 | environment variable `$CREDENTIALS_DIRECTORY` set. It contains an absolute path | |
112 | to a directory the credentials are placed in. In this directory for each | |
113 | configured credential one file is placed. In addition to the | |
114 | `$CREDENTIALS_DIRECTORY` environment variable passed to the service processes | |
115 | the `%d` specifier in unit files resolves to the service's credential | |
116 | directory. | |
117 | ||
118 | Example unit file: | |
119 | ||
120 | ``` | |
121 | … | |
122 | [Service] | |
123 | ExecStart=/usr/bin/myservice.sh | |
124 | LoadCredential=foobar:/etc/myfoobarcredential.txt | |
125 | Environment=FOOBARPATH=%d/foobar | |
126 | … | |
127 | ``` | |
128 | ||
129 | Associated service shell script `/usr/bin/myservice.sh`: | |
130 | ||
131 | ```sh | |
132 | #!/bin/sh | |
133 | ||
c0a18932 | 134 | sha256sum $CREDENTIALS_DIRECTORY/foobar |
fe672fe5 LP |
135 | sha256sum $FOOBARPATH |
136 | ||
137 | ``` | |
138 | ||
139 | A service defined like this will get the contents of the file | |
140 | `/etc/myfoobarcredential.txt` passed as credential `foobar`, which is hence | |
141 | accessible under `$CREDENTIALS_DIRECTORY/foobar`. Since we additionally pass | |
142 | the path to it as environment variable `$FOOBARPATH` the credential is also | |
143 | accessible as the path in that environment variable. When invoked, the service | |
144 | will hence show the same SHA256 hash value of `/etc/myfoobarcredential.txt` | |
145 | twice. | |
146 | ||
147 | In an ideal world, well-behaved service code would directly support credentials | |
148 | passed this way, i.e. look for `$CREDENTIALS_DIRECTORY` and load the credential | |
149 | data it needs from there. For daemons that do not support this but allow | |
150 | passing credentials via a path supplied over the command line use | |
c0a18932 | 151 | `${CREDENTIALS_DIRECTORY}` in the `ExecStart=` command line to reference the |
fe672fe5 | 152 | credentials directory. For daemons that allow passing credentials via a path |
77f081f3 | 153 | supplied as environment variable, use the `%d` specifier in the `Environment=` |
fe672fe5 LP |
154 | setting to build valid paths to specific credentials. |
155 | ||
df5f51c3 LP |
156 | Encrypted credentials are automatically decrypted/authenticated during service |
157 | activation, so that service code only receives plaintext credentials. | |
158 | ||
159 | ## Programming Interface from Generator Code | |
160 | ||
161 | [Generators](https://www.freedesktop.org/software/systemd/man/systemd.generator.html) | |
162 | may generate native unit files from external configuration or system | |
163 | parameters, such as system credentials. Note that they run outside of service | |
164 | context, and hence will not receive encrypted credentials in plaintext | |
165 | form. Specifically, credentials passed into the system in encrypted form will | |
166 | be placed as they are in a directory referenced by the | |
167 | `$ENCRYPTED_CREDENTIALS_DIRECTORY` environment variable, and those passed in | |
168 | plaintext form will be placed in `$CREDENTIALS_DIRECTORY`. Use a command such | |
169 | as `systemd-creds --system cat …` to access both forms of credentials, and | |
170 | decrypt them if needed (see | |
171 | [systemd-creds(1)](https://www.freedesktop.org/software/systemd/man/systemd-creds.html) | |
172 | for details. | |
173 | ||
174 | Note that generators typically run very early during boot (similar to initrd | |
175 | code), earlier than the `/var/` file system is necessarily mounted (which is | |
176 | where the system's credential encryption secret is located). Thus it's a good | |
177 | idea to encrypt credentials with `systemd-creds encrypt --with-key=auto-initrd` | |
178 | if they shall be consumed by a generator, to ensure they are locked to the TPM2 | |
179 | only, not the credentials secret stored below `/var/`. | |
180 | ||
181 | For further details about encrypted credentials, see below. | |
182 | ||
fe672fe5 LP |
183 | ## Tools |
184 | ||
185 | The | |
186 | [`systemd-creds`](https://www.freedesktop.org/software/systemd/man/systemd-creds.html) | |
187 | tool is provided to work with system and service credentials. It may be used to | |
188 | access and enumerate system and service credentials, or to encrypt/decrypt credentials | |
189 | (for details about the latter, see below). | |
190 | ||
191 | When invoked from service context, `systemd-creds` passed without further | |
192 | parameters will list passed credentials. The `systemd-creds cat xyz` command | |
193 | may be used to write the contents of credential `xyz` to standard output. If | |
194 | these calls are combined with the `--system` switch credentials passed to the | |
e347d53a | 195 | system as a whole are shown, instead of those passed to the service the |
fe672fe5 LP |
196 | command is invoked from. |
197 | ||
198 | Example use: | |
199 | ||
200 | ```sh | |
201 | systemd-run -P --wait -p LoadCredential=abc:/etc/hosts systemd-creds cat abc | |
202 | ``` | |
203 | ||
204 | This will invoke a transient service with a credential `abc` sourced from the | |
205 | system's `/etc/hosts` file. This credential is then written to standard output | |
206 | via `systemd-creds cat`. | |
207 | ||
208 | ## Encryption | |
209 | ||
210 | Credentials are supposed to be useful for carrying sensitive information, such | |
211 | as cryptographic key material. For this kind of data (symmetric) encryption and | |
e347d53a | 212 | authentication are provided to make storage of the data at rest safer. The data |
fe672fe5 LP |
213 | may be encrypted and authenticated with AES256-GCM. The encryption key can |
214 | either be one derived from the local TPM2 device, or one stored in | |
215 | `/var/lib/systemd/credential.secret`, or a combination of both. If a TPM2 | |
e347d53a | 216 | device is available and `/var/` resides on a persistent storage, the default |
fe672fe5 LP |
217 | behaviour is to use the combination of both for encryption, thus ensuring that |
218 | credentials protected this way can only be decrypted and validated on the | |
219 | local hardware and OS installation. Encrypted credentials stored on disk thus | |
220 | cannot be decrypted without access to the TPM2 chip and the aforementioned key | |
221 | file `/var/lib/systemd/credential.secret`. Moreover, credentials cannot be | |
e347d53a | 222 | prepared on a machine other than the local one. |
fe672fe5 | 223 | |
df5f51c3 LP |
224 | Decryption generally takes place at the moment of service activation. This |
225 | means credentials passed to the system can be either encrypted or plaintext and | |
226 | remain that way all the way while they are propagated to their consumers, until | |
227 | the moment of service activation when they are decrypted and authenticated, so | |
228 | that the service only sees plaintext credentials. | |
229 | ||
fe672fe5 LP |
230 | The `systemd-creds` tool provides the commands `encrypt` and `decrypt` to |
231 | encrypt and decrypt/authenticate credentials. Example: | |
232 | ||
233 | ```sh | |
08b61b40 | 234 | systemd-creds encrypt --name=foobar plaintext.txt ciphertext.cred |
026d48ba | 235 | shred -u plaintext.txt |
fe672fe5 LP |
236 | systemd-run -P --wait -p LoadCredentialEncrypted=foobar:$(pwd)/ciphertext.cred systemd-creds cat foobar |
237 | ``` | |
238 | ||
239 | This will first create an encrypted copy of the file `plaintext.txt` in the | |
240 | encrypted credential file `ciphertext.cred`. It then securely removes the | |
241 | source file. It then runs a transient service, that reads the encrypted file | |
242 | and passes it as decrypted credential `foobar` to the invoked service binary | |
243 | (which here is the `systemd-creds` tool, which just writes the data | |
244 | it received to standard output). | |
245 | ||
246 | Instead of storing the encrypted credential as a separate file on disk, it can | |
247 | also be embedded in the unit file. Example: | |
248 | ||
249 | ``` | |
250 | systemd-creds encrypt -p --name=foobar plaintext.txt - | |
251 | ``` | |
252 | ||
253 | This will output a `SetCredentialEncrypted=` line that can directly be used in | |
254 | a unit file. e.g.: | |
255 | ||
256 | ``` | |
257 | … | |
258 | [Service] | |
259 | ExecStart=/usr/bin/systemd-creds cat foobar | |
260 | SetCredentialEncrypted=foobar: \ | |
261 | k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAC1lFmbWAqWZ8dCCQkAAAAAgAAAA \ | |
262 | AAAAAALACMA0AAAACAAAAAAfgAg9uNpGmj8LL2nHE0ixcycvM3XkpOCaf+9rwGscwmqRJ \ | |
263 | cAEO24kB08FMtd/hfkZBX8PqoHd/yPTzRxJQBoBsvo9VqolKdy9Wkvih0HQnQ6NkTKEdP \ | |
264 | HQ08+x8sv5sr+Mkv4ubp3YT1Jvv7CIPCbNhFtag1n5y9J7bTOKt2SQwBOAAgACwAAABIA \ | |
265 | ID8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciABAAII6LvrmL60uEZcp5qnEkx \ | |
266 | SuhUjsDoXrJs0rfSWX4QAx5PwfdFuxPusgEfTYIiCb8a/W6RJc7cMweZVCQMbTARyIAAA \ | |
267 | AAJt7Q9F/Gz0pBv1Lc4Dpn1WpebyBBm+vQ5N/lSKW2XSm8cONwCopxpDc7wJjXg7OTR6r \ | |
268 | xGCpIvGXLt3ibwJl81woLya2RRjIvc/R2zNm/yWzZAjiOLPih4SuHthqiX98ey8PUmZJB \ | |
269 | VGXglCZFjBx+d7eCqTIdghtp5pkDGwMJT6pjw4FfyFK2nJPawFKPAqzw9DK2iYttFeXi5 \ | |
270 | 19xCfLBH9NKS/idlYXrhp+XIEtsr26s4lx5y10Goyc3qDOR3RD2cuZj0gHwV35hhhhcCz \ | |
271 | JaYytef1X/YL+7fYH5kuE4rxSksoUuA/LhtjszBeGbcbIT+O8SuvBJHLKTSHxPL8FTyk3 \ | |
272 | L4FSkEHs0rYwUIkKmnGohDdsYrMJ2fjH3yDNBP16aD1+f/Nuh75cjhUnGsDLt9K4hGg== \ | |
273 | … | |
274 | ``` | |
275 | ||
276 | ## Inheritance from Container Managers, Hypervisors, Kernel Command Line, or the UEFI Boot Environment | |
277 | ||
278 | Sometimes it is useful to parameterize whole systems the same way as services, | |
279 | via `systemd` credentials. In particular, it might make sense to boot a | |
280 | system with a set of credentials that are then propagated to individual | |
281 | services where they are ultimately consumed. | |
282 | ||
df5f51c3 | 283 | `systemd` supports five ways to pass credentials to systems: |
fe672fe5 LP |
284 | |
285 | 1. A container manager may set the `$CREDENTIALS_DIRECTORY` environment | |
286 | variable for systemd running as PID 1 in the container, the same way as | |
287 | systemd would set it for a service it | |
288 | invokes. [`systemd-nspawn(1)`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#Credentials)'s | |
289 | `--set-credential=` and `--load-credential=` switches implement this, in | |
290 | order to pass arbitrary credentials from host to container payload. Also see | |
df5f51c3 | 291 | the [Container Interface](CONTAINER_INTERFACE.md) documentation. |
fe672fe5 | 292 | |
8de7de46 LP |
293 | 2. Quite similar, VMs can be passed credentials via SMBIOS OEM strings (example |
294 | qemu command line switch `-smbios | |
295 | type=11,value=io.systemd.credential:foo=bar` or `-smbios | |
296 | type=11,value=io.systemd.credential.binary:foo=YmFyCg==`, the latter taking | |
297 | a Base64 encoded argument to permit binary credentials being passed | |
298 | in). Alternatively, qemu VMs can be invoked with `-fw_cfg | |
fe672fe5 | 299 | name=opt/io.systemd.credentials/foo,string=bar` to pass credentials from |
8de7de46 LP |
300 | host through the hypervisor into the VM via qemu's `fw_cfg` mechanism. (All |
301 | three of these specific switches would set credential `foo` to `bar`.) | |
302 | Passing credentials via the SMBIOS mechanism is typically preferable over | |
303 | `fw_cfg` since it is faster and less specific to the chosen VMM | |
df5f51c3 LP |
304 | implementation. Moreover, `fw_cfg` has a 55 character limitation on names |
305 | passed that way. So some settings may not fit. | |
fe672fe5 | 306 | |
df5f51c3 LP |
307 | 3. Credentials may be passed from the initrd to the host during the initrd → |
308 | host transition. Provisioning systems that run in the initrd may use this to | |
309 | install credentials on the system. All files placed in | |
310 | `/run/credentials/@initrd/` are imported into the set of file system | |
311 | credentials during the transition. The files (and their directory) are | |
312 | removed once this is completed. | |
fe672fe5 | 313 | |
85fe60b9 | 314 | 4. Credentials may also be passed from the UEFI environment to userspace, if |
fe672fe5 LP |
315 | the |
316 | [`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html) | |
317 | UEFI kernel stub is used. This allows placing encrypted credentials in the | |
318 | EFI System Partition, which are then picked up by `systemd-stub` and passed | |
77f081f3 | 319 | to the kernel and ultimately userspace where systemd receives them. This is |
fe672fe5 | 320 | useful to implement secure parameterization of vendor-built and signed |
55c041b4 LP |
321 | initrds, as userspace can place credentials next to these EFI kernels, and |
322 | be sure they can be accessed securely from initrd context. | |
fe672fe5 | 323 | |
85fe60b9 | 324 | 5. Credentials can also be passed into a system via the kernel command line, |
de70ecb3 LP |
325 | via the `systemd.set_credential=` and `systemd.set_credential_binary=` |
326 | kernel command line options (the latter takes Base64 encoded binary | |
327 | data). Note though that any data specified here is visible to all userspace | |
328 | applications (even unprivileged ones) via `/proc/cmdline`. Typically, this | |
329 | is hence not useful to pass sensitive information, and should be avoided. | |
df5f51c3 | 330 | |
fe672fe5 LP |
331 | Credentials passed to the system may be enumerated/displayed via `systemd-creds |
332 | --system`. They may also be propagated down to services, via the | |
333 | `LoadCredential=` setting. Example: | |
334 | ||
335 | ``` | |
336 | systemd-nspawn --set-credential=mycred:supersecret -i test.raw -b | |
337 | ``` | |
338 | ||
339 | or | |
340 | ||
341 | ``` | |
342 | qemu-system-x86_64 \ | |
343 | -machine type=q35,accel=kvm,smm=on \ | |
344 | -smp 2 \ | |
345 | -m 1G \ | |
346 | -cpu host \ | |
347 | -nographic \ | |
348 | -nodefaults \ | |
349 | -serial mon:stdio \ | |
350 | -drive if=none,id=hd,file=test.raw,format=raw \ | |
351 | -device virtio-scsi-pci,id=scsi \ | |
352 | -device scsi-hd,drive=hd,bootindex=1 \ | |
8de7de46 | 353 | -smbios type=11,value=io.systemd.credential:mycred=supersecret |
fe672fe5 LP |
354 | ``` |
355 | ||
356 | Either of these lines will boot a disk image `test.raw`, once as container via | |
357 | `systemd-nspawn`, and once as VM via `qemu`. In each case the credential | |
358 | `mycred` is set to `supersecret`. | |
359 | ||
360 | Inside of the system invoked that way the credential may then be viewed: | |
361 | ||
362 | ```sh | |
363 | systemd-creds --system cat mycred | |
364 | ``` | |
365 | ||
366 | Or propagated to services further down: | |
367 | ||
368 | ``` | |
bbfb25f4 | 369 | systemd-run -p ImportCredential=mycred -P --wait systemd-creds cat mycred |
fe672fe5 LP |
370 | ``` |
371 | ||
372 | ## Well-Known Credentials | |
373 | ||
374 | Various services shipped with `systemd` consume credentials for tweaking behaviour: | |
375 | ||
4a91ace5 LB |
376 | * [`systemd(1)`](https://www.freedesktop.org/software/systemd/man/systemd.html) |
377 | (I.E.: PID1, the system manager) will look for the credential `vmm.notify_socket` | |
378 | and will use it to send a `READY=1` datagram when the system has finished | |
379 | booting. This is useful for hypervisors/VMMs or other processes on the host | |
380 | to receive a notification via VSOCK when a virtual machine has finished booting. | |
381 | Note that in case the hypervisor does not support `SOCK_DGRAM` over `AF_VSOCK`, | |
382 | `SOCK_SEQPACKET` will be tried instead. The credential payload should be in the | |
f86d0376 LB |
383 | form: `vsock:<CID>:<PORT>`. Also note that this requires support for VHOST to be |
384 | built-in both the guest and the host kernels, and the kernel modules to be loaded. | |
4a91ace5 | 385 | |
fe672fe5 LP |
386 | * [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html) |
387 | will look for the credentials `passwd.hashed-password.<username>`, | |
388 | `passwd.plaintext-password.<username>` and `passwd.shell.<username>` to | |
389 | configure the password (either in UNIX hashed form, or plaintext) or shell of | |
390 | system users created. Replace `<username>` with the system user of your | |
e347d53a | 391 | choice, for example, `root`. |
fe672fe5 LP |
392 | |
393 | * [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html) | |
394 | will look for the credentials `firstboot.locale`, `firstboot.locale-messages`, | |
395 | `firstboot.keymap`, `firstboot.timezone`, that configure locale, keymap or | |
396 | timezone settings in case the data is not yet set in `/etc/`. | |
397 | ||
b60d3016 LB |
398 | * [`tmpfiles.d(5)`](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html) |
399 | will look for the credentials `tmpfiles.extra` with arbitrary tmpfiles.d lines. | |
400 | Can be encoded in base64 to allow easily passing it on the command line. | |
401 | ||
df5f51c3 LP |
402 | * Further well-known credentials are documented in |
403 | [`systemd.system-credentials(7)`](https://www.freedesktop.org/software/systemd/man/systemd.system-credentials.html). | |
404 | ||
fe672fe5 LP |
405 | In future more services are likely to gain support for consuming credentials. |
406 | ||
407 | Example: | |
408 | ||
409 | ``` | |
410 | systemd-nspawn -i test.raw \ | |
411 | --set-credential=passwd.hashed-password.root:$(mkpasswd mysecret) \ | |
412 | --set-credential=firstboot.locale:C.UTF-8 \ | |
413 | -b | |
414 | ``` | |
415 | ||
416 | This boots the specified disk image as `systemd-nspawn` container, and passes | |
417 | the root password `mysecret`and default locale `C.UTF-8` to use to it. This | |
418 | data is then propagated by default to `systemd-sysusers.service` and | |
419 | `systemd-firstboot.service`, where it is applied. (Note that these services | |
420 | will only do so if these settings in `/etc/` are so far unset, i.e. they only | |
421 | have an effect on *unprovisioned* systems, and will never override data already | |
422 | established in `/etc/`.) A similar line for qemu is: | |
423 | ||
424 | ``` | |
425 | qemu-system-x86_64 \ | |
426 | -machine type=q35,accel=kvm,smm=on \ | |
427 | -smp 2 \ | |
428 | -m 1G \ | |
429 | -cpu host \ | |
430 | -nographic \ | |
431 | -nodefaults \ | |
432 | -serial mon:stdio \ | |
433 | -drive if=none,id=hd,file=test.raw,format=raw \ | |
434 | -device virtio-scsi-pci,id=scsi \ | |
435 | -device scsi-hd,drive=hd,bootindex=1 \ | |
8de7de46 LP |
436 | -smbios type=11,value=io.systemd.credential:passwd.hashed-password.root=$(mkpasswd mysecret) \ |
437 | -smbios type=11,value=io.systemd.credential:firstboot.locale=C.UTF-8 | |
fe672fe5 LP |
438 | ``` |
439 | ||
b60d3016 | 440 | This boots the specified disk image via qemu, provisioning public key SSH access |
4a91ace5 LB |
441 | for the root user from the caller's key, and sends a notification when booting |
442 | has finished to a process on the host: | |
b60d3016 LB |
443 | |
444 | ``` | |
445 | qemu-system-x86_64 \ | |
446 | -machine type=q35,accel=kvm,smm=on \ | |
447 | -smp 2 \ | |
448 | -m 1G \ | |
449 | -cpu host \ | |
450 | -nographic \ | |
451 | -nodefaults \ | |
452 | -serial mon:stdio \ | |
453 | -drive if=none,id=hd,file=test.raw,format=raw \ | |
454 | -device virtio-scsi-pci,id=scsi \ | |
455 | -device scsi-hd,drive=hd,bootindex=1 \ | |
4a91ace5 LB |
456 | -device vhost-vsock-pci,id=vhost-vsock-pci0,guest-cid=42 \ |
457 | -smbios type=11,value=io.systemd.credential:vmm.notify_socket=vsock:2:1234 \ | |
47374e06 | 458 | -smbios type=11,value=io.systemd.credential.binary:tmpfiles.extra=$(echo "f~ /root/.ssh/authorized_keys 600 root root - $(ssh-add -L | base64 -w 0)" | base64 -w 0) |
b60d3016 | 459 | ``` |
4a91ace5 LB |
460 | |
461 | A process on the host can listen for the notification, for example: | |
462 | ||
463 | ``` | |
464 | $ socat - VSOCK-LISTEN:1234,socktype=5 | |
465 | READY=1 | |
466 | ``` | |
467 | ||
fe672fe5 LP |
468 | ## Relevant Paths |
469 | ||
470 | From *service* perspective the runtime path to find loaded credentials in is | |
cf371718 JB |
471 | provided in the `$CREDENTIALS_DIRECTORY` environment variable. For *system |
472 | services* the credential directory will be `/run/credentials/<unit name>`, but | |
473 | hardcoding this path is discouraged, because it does not work for *user | |
474 | services*. Packagers and system administrators may hardcode the credential path | |
475 | as a last resort for software that does not yet search for credentials relative | |
476 | to `$CREDENTIALS_DIRECTORY`. | |
fe672fe5 | 477 | |
df5f51c3 LP |
478 | From *generator* perspective the runtime path to find credentials passed into |
479 | the system in plaintext form in is provided in `$CREDENTIALS_DIRECTORY`, and | |
480 | those passed into the system in encrypted form is provided in | |
481 | `$ENCRYPTED_CREDENTIALS_DIRECTORY`. | |
482 | ||
fe672fe5 LP |
483 | At runtime, credentials passed to the *system* are placed in |
484 | `/run/credentials/@system/` (for regular credentials, such as those passed from | |
485 | a container manager or via qemu) and `/run/credentials/@encrypted/` (for | |
486 | credentials that must be decrypted/validated before use, such as those from | |
487 | `systemd-stub`). | |
488 | ||
bbfb25f4 | 489 | The `ImportCredential=` setting (and the `LoadCredential=` and |
df5f51c3 LP |
490 | `LoadCredentialEncrypted=` settings when configured with a relative source |
491 | path) will search for the source file to read the credential from | |
492 | automatically. Primarily, these credentials are searched among the credentials | |
493 | passed into the system. If not found there, they are searched in | |
494 | `/etc/credstore/`, `/run/credstore/`, | |
fe672fe5 | 495 | `/usr/lib/credstore/`. `LoadCredentialEncrypted=` will also search |
df5f51c3 LP |
496 | `/etc/credstore.encrypted/` and similar directories. `ImportCredential=` will |
497 | search both the non-encrypted and encrypted directories. These directories are | |
fe672fe5 | 498 | hence a great place to store credentials to load on the system. |
4f80cfca LP |
499 | |
500 | ## Conditionalizing Services | |
501 | ||
502 | Sometimes it makes sense to conditionalize system services and invoke them only | |
d8b67e05 | 503 | if the right system credential is passed to the system. Use the |
4f80cfca | 504 | `ConditionCredential=` and `AssertCredential=` unit file settings for that. |