mirror of
https://github.com/systemd/systemd.git
synced 2024-12-23 21:35:11 +03:00
498 lines
23 KiB
Markdown
498 lines
23 KiB
Markdown
---
|
|
title: Credentials
|
|
category: Concepts
|
|
layout: default
|
|
SPDX-License-Identifier: LGPL-2.1-or-later
|
|
---
|
|
|
|
# System and Service Credentials
|
|
|
|
The `systemd` service manager supports a "credential" concept for securely
|
|
acquiring and passing credential data to systems and services. The precise
|
|
nature of the credential data is up to applications, but the concept is
|
|
intended to provide systems and services with potentially security sensitive
|
|
cryptographic keys, certificates, passwords, identity information and similar
|
|
types of information. It may also be used as generic infrastructure for
|
|
parameterizing systems and services.
|
|
|
|
Traditionally, data of this nature has often been provided to services via
|
|
environment variables (which is problematic because by default they are
|
|
inherited down the process tree, have size limitations, and issues with binary
|
|
data) or simple, unencrypted files on disk. `systemd`'s system and service
|
|
credentials are supposed to provide a better alternative for this
|
|
purpose. Specifically, the following features are provided:
|
|
|
|
1. Service credentials are acquired at the moment of service activation, and
|
|
released on service deactivation. They are immutable during the service
|
|
runtime.
|
|
|
|
2. Service credentials are accessible to service code as regular files, the
|
|
path to access them is derived from the environment variable
|
|
`$CREDENTIALS_DIRECTORY`.
|
|
|
|
3. Access to credentials is restricted to the service's user. Unlike
|
|
environment variables the credential data is not propagated down the process
|
|
tree. Instead each time a credential is accessed an access check is enforced
|
|
by the kernel. If the service is using file system namespacing the loaded
|
|
credential data is invisible to all other services.
|
|
|
|
4. Service credentials may be acquired from files on disk, specified as literal
|
|
strings in unit files, acquired from another service dynamically via an
|
|
`AF_UNIX` socket, or inherited from the system credentials the system itself
|
|
received.
|
|
|
|
5. Credentials may optionally be encrypted and authenticated, either with a key
|
|
derived from a local TPM2 chip, or one stored in `/var/`, or both. This
|
|
encryption is supposed to *just* *work*, and requires no manual setup. (That
|
|
is besides first encrypting relevant credentials with one simple command,
|
|
see below.)
|
|
|
|
6. Service credentials are placed in non-swappable memory. (If permissions
|
|
allow it, via `ramfs`.)
|
|
|
|
7. Credentials may be acquired from a hosting VM hypervisor (SMBIOS OEM strings
|
|
or qemu `fw_cfg`), a hosting container manager, the kernel command line,
|
|
from the initrd, or from the UEFI environment via the EFI System Partition
|
|
(via `systemd-stub`). Such system credentials may then be propagated into
|
|
individual services as needed.
|
|
|
|
8. Credentials are an effective way to pass parameters into services that run
|
|
with `RootImage=` or `RootDirectory=` and thus cannot read these resources
|
|
directly from the host directory tree.
|
|
Specifically, [Portable Services](PORTABLE_SERVICES) may be
|
|
parameterized this way securely and robustly.
|
|
|
|
9. Credentials can be binary and relatively large (though currently an overall
|
|
size limit of 1M per service is enforced).
|
|
|
|
## Configuring per-Service Credentials
|
|
|
|
Within unit files, there are four settings to configure service credentials.
|
|
|
|
1. `LoadCredential=` may be used to load a credential from disk, from an
|
|
`AF_UNIX` socket, or propagate them from a system credential.
|
|
|
|
2. `ImportCredential=` may be used to load one or more (optionally encrypted)
|
|
credentials from disk or from the credential stores.
|
|
|
|
3. `SetCredential=` may be used to set a credential to a literal string encoded
|
|
in the unit file. Because unit files are world-readable (both on disk and
|
|
via D-Bus), this should only be used for credentials that aren't sensitive,
|
|
e.g. public keys or certificates, but not private keys.
|
|
|
|
4. `LoadCredentialEncrypted=` is similar to `LoadCredential=` but will load an
|
|
encrypted credential, and decrypt it before passing it to the service. For
|
|
details on credential encryption, see below.
|
|
|
|
5. `SetCredentialEncrypted=` is similar to `SetCredential=` but expects an
|
|
encrypted credential to be specified literally. Unlike `SetCredential=` it
|
|
is thus safe to be used even for sensitive information, because even though
|
|
unit files are world readable, the ciphertext included in them cannot be
|
|
decoded unless access to TPM2/encryption key is available.
|
|
|
|
Each credential configured with these options carries a short name (suitable
|
|
for inclusion in a filename) in the unit file, under which the invoked service
|
|
code can then retrieve it. Each name should only be specified once.
|
|
|
|
For details about these four settings [see the man
|
|
page](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Credentials).
|
|
|
|
It is a good idea to also enable mount namespacing for services that process
|
|
credentials configured this way. If so, the runtime credential directory of the
|
|
specific service is not visible to any other service. Use `PrivateMounts=` as
|
|
minimal option to enable such namespacing. Note that many other sandboxing
|
|
settings (e.g. `ProtectSystem=`, `ReadOnlyPaths=` and similar) imply
|
|
`PrivateMounts=`, hence oftentimes it's not necessary to set this option
|
|
explicitly.
|
|
|
|
## Programming Interface from Service Code
|
|
|
|
When a service is invoked with one or more credentials set it will have an
|
|
environment variable `$CREDENTIALS_DIRECTORY` set. It contains an absolute path
|
|
to a directory the credentials are placed in. In this directory for each
|
|
configured credential one file is placed. In addition to the
|
|
`$CREDENTIALS_DIRECTORY` environment variable passed to the service processes
|
|
the `%d` specifier in unit files resolves to the service's credential
|
|
directory.
|
|
|
|
Example unit file:
|
|
|
|
```
|
|
…
|
|
[Service]
|
|
ExecStart=/usr/bin/myservice.sh
|
|
LoadCredential=foobar:/etc/myfoobarcredential.txt
|
|
Environment=FOOBARPATH=%d/foobar
|
|
…
|
|
```
|
|
|
|
Associated service shell script `/usr/bin/myservice.sh`:
|
|
|
|
```sh
|
|
#!/bin/sh
|
|
|
|
sha256sum $CREDENTIALS_DIRECTORY/foobar
|
|
sha256sum $FOOBARPATH
|
|
|
|
```
|
|
|
|
A service defined like this will get the contents of the file
|
|
`/etc/myfoobarcredential.txt` passed as credential `foobar`, which is hence
|
|
accessible under `$CREDENTIALS_DIRECTORY/foobar`. Since we additionally pass
|
|
the path to it as environment variable `$FOOBARPATH` the credential is also
|
|
accessible as the path in that environment variable. When invoked, the service
|
|
will hence show the same SHA256 hash value of `/etc/myfoobarcredential.txt`
|
|
twice.
|
|
|
|
In an ideal world, well-behaved service code would directly support credentials
|
|
passed this way, i.e. look for `$CREDENTIALS_DIRECTORY` and load the credential
|
|
data it needs from there. For daemons that do not support this but allow
|
|
passing credentials via a path supplied over the command line use
|
|
`${CREDENTIALS_DIRECTORY}` in the `ExecStart=` command line to reference the
|
|
credentials directory. For daemons that allow passing credentials via a path
|
|
supplied as environment variable, use the `%d` specifier in the `Environment=`
|
|
setting to build valid paths to specific credentials.
|
|
|
|
Encrypted credentials are automatically decrypted/authenticated during service
|
|
activation, so that service code only receives plaintext credentials.
|
|
|
|
## Programming Interface from Generator Code
|
|
|
|
[Generators](https://www.freedesktop.org/software/systemd/man/systemd.generator.html)
|
|
may generate native unit files from external configuration or system
|
|
parameters, such as system credentials. Note that they run outside of service
|
|
context, and hence will not receive encrypted credentials in plaintext
|
|
form. Specifically, credentials passed into the system in encrypted form will
|
|
be placed as they are in a directory referenced by the
|
|
`$ENCRYPTED_CREDENTIALS_DIRECTORY` environment variable, and those passed in
|
|
plaintext form will be placed in `$CREDENTIALS_DIRECTORY`. Use a command such
|
|
as `systemd-creds --system cat …` to access both forms of credentials, and
|
|
decrypt them if needed (see
|
|
[systemd-creds(1)](https://www.freedesktop.org/software/systemd/man/systemd-creds.html)
|
|
for details.
|
|
|
|
Note that generators typically run very early during boot (similar to initrd
|
|
code), earlier than the `/var/` file system is necessarily mounted (which is
|
|
where the system's credential encryption secret is located). Thus it's a good
|
|
idea to encrypt credentials with `systemd-creds encrypt --with-key=auto-initrd`
|
|
if they shall be consumed by a generator, to ensure they are locked to the TPM2
|
|
only, not the credentials secret stored below `/var/`.
|
|
|
|
For further details about encrypted credentials, see below.
|
|
|
|
## Tools
|
|
|
|
The
|
|
[`systemd-creds`](https://www.freedesktop.org/software/systemd/man/systemd-creds.html)
|
|
tool is provided to work with system and service credentials. It may be used to
|
|
access and enumerate system and service credentials, or to encrypt/decrypt credentials
|
|
(for details about the latter, see below).
|
|
|
|
When invoked from service context, `systemd-creds` passed without further
|
|
parameters will list passed credentials. The `systemd-creds cat xyz` command
|
|
may be used to write the contents of credential `xyz` to standard output. If
|
|
these calls are combined with the `--system` switch credentials passed to the
|
|
system as a whole are shown, instead of those passed to the service the
|
|
command is invoked from.
|
|
|
|
Example use:
|
|
|
|
```sh
|
|
systemd-run -P --wait -p LoadCredential=abc:/etc/hosts systemd-creds cat abc
|
|
```
|
|
|
|
This will invoke a transient service with a credential `abc` sourced from the
|
|
system's `/etc/hosts` file. This credential is then written to standard output
|
|
via `systemd-creds cat`.
|
|
|
|
## Encryption
|
|
|
|
Credentials are supposed to be useful for carrying sensitive information, such
|
|
as cryptographic key material. For this kind of data (symmetric) encryption and
|
|
authentication are provided to make storage of the data at rest safer. The data
|
|
may be encrypted and authenticated with AES256-GCM. The encryption key can
|
|
either be one derived from the local TPM2 device, or one stored in
|
|
`/var/lib/systemd/credential.secret`, or a combination of both. If a TPM2
|
|
device is available and `/var/` resides on a persistent storage, the default
|
|
behaviour is to use the combination of both for encryption, thus ensuring that
|
|
credentials protected this way can only be decrypted and validated on the
|
|
local hardware and OS installation. Encrypted credentials stored on disk thus
|
|
cannot be decrypted without access to the TPM2 chip and the aforementioned key
|
|
file `/var/lib/systemd/credential.secret`. Moreover, credentials cannot be
|
|
prepared on a machine other than the local one.
|
|
|
|
Decryption generally takes place at the moment of service activation. This
|
|
means credentials passed to the system can be either encrypted or plaintext and
|
|
remain that way all the way while they are propagated to their consumers, until
|
|
the moment of service activation when they are decrypted and authenticated, so
|
|
that the service only sees plaintext credentials.
|
|
|
|
The `systemd-creds` tool provides the commands `encrypt` and `decrypt` to
|
|
encrypt and decrypt/authenticate credentials. Example:
|
|
|
|
```sh
|
|
systemd-creds encrypt --name=foobar plaintext.txt ciphertext.cred
|
|
shred -u plaintext.txt
|
|
systemd-run -P --wait -p LoadCredentialEncrypted=foobar:$(pwd)/ciphertext.cred systemd-creds cat foobar
|
|
```
|
|
|
|
This will first create an encrypted copy of the file `plaintext.txt` in the
|
|
encrypted credential file `ciphertext.cred`. It then securely removes the
|
|
source file. It then runs a transient service, that reads the encrypted file
|
|
and passes it as decrypted credential `foobar` to the invoked service binary
|
|
(which here is the `systemd-creds` tool, which just writes the data
|
|
it received to standard output).
|
|
|
|
Instead of storing the encrypted credential as a separate file on disk, it can
|
|
also be embedded in the unit file. Example:
|
|
|
|
```
|
|
systemd-creds encrypt -p --name=foobar plaintext.txt -
|
|
```
|
|
|
|
This will output a `SetCredentialEncrypted=` line that can directly be used in
|
|
a unit file. e.g.:
|
|
|
|
```
|
|
…
|
|
[Service]
|
|
ExecStart=/usr/bin/systemd-creds cat foobar
|
|
SetCredentialEncrypted=foobar: \
|
|
k6iUCUh0RJCQyvL8k8q1UyAAAAABAAAADAAAABAAAAC1lFmbWAqWZ8dCCQkAAAAAgAAAA \
|
|
AAAAAALACMA0AAAACAAAAAAfgAg9uNpGmj8LL2nHE0ixcycvM3XkpOCaf+9rwGscwmqRJ \
|
|
cAEO24kB08FMtd/hfkZBX8PqoHd/yPTzRxJQBoBsvo9VqolKdy9Wkvih0HQnQ6NkTKEdP \
|
|
HQ08+x8sv5sr+Mkv4ubp3YT1Jvv7CIPCbNhFtag1n5y9J7bTOKt2SQwBOAAgACwAAABIA \
|
|
ID8H3RbsT7rIBH02CIgm/Gv1ukSXO3DMHmVQkDG0wEciABAAII6LvrmL60uEZcp5qnEkx \
|
|
SuhUjsDoXrJs0rfSWX4QAx5PwfdFuxPusgEfTYIiCb8a/W6RJc7cMweZVCQMbTARyIAAA \
|
|
AAJt7Q9F/Gz0pBv1Lc4Dpn1WpebyBBm+vQ5N/lSKW2XSm8cONwCopxpDc7wJjXg7OTR6r \
|
|
xGCpIvGXLt3ibwJl81woLya2RRjIvc/R2zNm/yWzZAjiOLPih4SuHthqiX98ey8PUmZJB \
|
|
VGXglCZFjBx+d7eCqTIdghtp5pkDGwMJT6pjw4FfyFK2nJPawFKPAqzw9DK2iYttFeXi5 \
|
|
19xCfLBH9NKS/idlYXrhp+XIEtsr26s4lx5y10Goyc3qDOR3RD2cuZj0gHwV35hhhhcCz \
|
|
JaYytef1X/YL+7fYH5kuE4rxSksoUuA/LhtjszBeGbcbIT+O8SuvBJHLKTSHxPL8FTyk3 \
|
|
L4FSkEHs0rYwUIkKmnGohDdsYrMJ2fjH3yDNBP16aD1+f/Nuh75cjhUnGsDLt9K4hGg== \
|
|
…
|
|
```
|
|
|
|
## Inheritance from Container Managers, Hypervisors, Kernel Command Line, or the UEFI Boot Environment
|
|
|
|
Sometimes it is useful to parameterize whole systems the same way as services,
|
|
via `systemd` credentials. In particular, it might make sense to boot a
|
|
system with a set of credentials that are then propagated to individual
|
|
services where they are ultimately consumed.
|
|
|
|
`systemd` supports five ways to pass credentials to systems:
|
|
|
|
1. A container manager may set the `$CREDENTIALS_DIRECTORY` environment
|
|
variable for systemd running as PID 1 in the container, the same way as
|
|
systemd would set it for a service it invokes.
|
|
[`systemd-nspawn(1)`](https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html#Credentials)'s
|
|
`--set-credential=` and `--load-credential=` switches implement this, in
|
|
order to pass arbitrary credentials from host to container payload. Also see
|
|
the [Container Interface](CONTAINER_INTERFACE) documentation.
|
|
|
|
2. Quite similar, VMs can be passed credentials via SMBIOS OEM strings (example
|
|
qemu command line switch `-smbios
|
|
type=11,value=io.systemd.credential:foo=bar` or `-smbios
|
|
type=11,value=io.systemd.credential.binary:foo=YmFyCg==`, the latter taking
|
|
a Base64 encoded argument to permit binary credentials being passed
|
|
in). Alternatively, qemu VMs can be invoked with `-fw_cfg
|
|
name=opt/io.systemd.credentials/foo,string=bar` to pass credentials from
|
|
host through the hypervisor into the VM via qemu's `fw_cfg` mechanism. (All
|
|
three of these specific switches would set credential `foo` to `bar`.)
|
|
Passing credentials via the SMBIOS mechanism is typically preferable over
|
|
`fw_cfg` since it is faster and less specific to the chosen VMM implementation.
|
|
Moreover, `fw_cfg` has a 55 character limitation on names passed that way. So some settings may not fit.
|
|
|
|
3. Credentials may be passed from the initrd to the host during the initrd → host transition.
|
|
Provisioning systems that run in the initrd may use this to install credentials on the system.
|
|
All files placed in `/run/credentials/@initrd/` are imported into the set of file system credentials during the transition.
|
|
The files (and their directory) are removed once this is completed.
|
|
|
|
4. Credentials may also be passed from the UEFI environment to userspace, if
|
|
the
|
|
[`systemd-stub`](https://www.freedesktop.org/software/systemd/man/systemd-stub.html)
|
|
UEFI kernel stub is used.
|
|
This allows placing encrypted credentials in the EFI System Partition, which are then picked up by `systemd-stub` and passed to the kernel and ultimately userspace where systemd receives them.
|
|
This is useful to implement secure parameterization of vendor-built and signed
|
|
initrds, as userspace can place credentials next to these EFI kernels, and
|
|
be sure they can be accessed securely from initrd context.
|
|
|
|
5. Credentials can also be passed into a system via the kernel command line,
|
|
via the `systemd.set_credential=` and `systemd.set_credential_binary=`
|
|
kernel command line options (the latter takes Base64 encoded binary data).
|
|
Note though that any data specified here is visible to all userspace
|
|
applications (even unprivileged ones) via `/proc/cmdline`. Typically, this
|
|
is hence not useful to pass sensitive information, and should be avoided.
|
|
|
|
Credentials passed to the system may be enumerated/displayed via `systemd-creds
|
|
--system`. They may also be propagated down to services, via the
|
|
`LoadCredential=` setting. Example:
|
|
|
|
```
|
|
systemd-nspawn --set-credential=mycred:supersecret -i test.raw -b
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
qemu-system-x86_64 \
|
|
-machine type=q35,accel=kvm,smm=on \
|
|
-smp 2 \
|
|
-m 1G \
|
|
-cpu host \
|
|
-nographic \
|
|
-nodefaults \
|
|
-serial mon:stdio \
|
|
-drive if=none,id=hd,file=test.raw,format=raw \
|
|
-device virtio-scsi-pci,id=scsi \
|
|
-device scsi-hd,drive=hd,bootindex=1 \
|
|
-smbios type=11,value=io.systemd.credential:mycred=supersecret
|
|
```
|
|
|
|
Either of these lines will boot a disk image `test.raw`, once as container via
|
|
`systemd-nspawn`, and once as VM via `qemu`. In each case the credential
|
|
`mycred` is set to `supersecret`.
|
|
|
|
Inside of the system invoked that way the credential may then be viewed:
|
|
|
|
```sh
|
|
systemd-creds --system cat mycred
|
|
```
|
|
|
|
Or propagated to services further down:
|
|
|
|
```
|
|
systemd-run -p ImportCredential=mycred -P --wait systemd-creds cat mycred
|
|
```
|
|
|
|
## Well-Known Credentials
|
|
|
|
Various services shipped with `systemd` consume credentials for tweaking behaviour:
|
|
|
|
* [`systemd(1)`](https://www.freedesktop.org/software/systemd/man/systemd.html)
|
|
(I.E.: PID1, the system manager) will look for the credential `vmm.notify_socket`
|
|
and will use it to send a `READY=1` datagram when the system has finished
|
|
booting.
|
|
This is useful for hypervisors/VMMs or other processes on the host to receive a notification via VSOCK when a virtual machine has finished booting.
|
|
Note that in case the hypervisor does not support `SOCK_DGRAM` over `AF_VSOCK`,
|
|
`SOCK_SEQPACKET` will be tried instead.
|
|
The credential payload should be in the form: `vsock:<CID>:<PORT>`.
|
|
Also note that this requires support for VHOST to be built-in both the guest and the host kernels, and the kernel modules to be loaded.
|
|
|
|
* [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.html)
|
|
will look for the credentials `passwd.hashed-password.<username>`,
|
|
`passwd.plaintext-password.<username>` and `passwd.shell.<username>` to
|
|
configure the password (either in UNIX hashed form, or plaintext) or shell of
|
|
system users created.
|
|
Replace `<username>` with the system user of your choice, for example, `root`.
|
|
|
|
* [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
|
|
will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
|
|
`firstboot.keymap`, `firstboot.timezone`, that configure locale, keymap or
|
|
timezone settings in case the data is not yet set in `/etc/`.
|
|
|
|
* [`tmpfiles.d(5)`](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html)
|
|
will look for the credentials `tmpfiles.extra` with arbitrary tmpfiles.d lines.
|
|
Can be encoded in base64 to allow easily passing it on the command line.
|
|
|
|
* Further well-known credentials are documented in
|
|
[`systemd.system-credentials(7)`](https://www.freedesktop.org/software/systemd/man/systemd.system-credentials.html).
|
|
|
|
In future more services are likely to gain support for consuming credentials.
|
|
|
|
Example:
|
|
|
|
```
|
|
systemd-nspawn -i test.raw \
|
|
--set-credential=passwd.hashed-password.root:$(mkpasswd mysecret) \
|
|
--set-credential=firstboot.locale:C.UTF-8 \
|
|
-b
|
|
```
|
|
|
|
This boots the specified disk image as `systemd-nspawn` container, and passes
|
|
the root password `mysecret`and default locale `C.UTF-8` to use to it. This
|
|
data is then propagated by default to `systemd-sysusers.service` and
|
|
`systemd-firstboot.service`, where it is applied. (Note that these services
|
|
will only do so if these settings in `/etc/` are so far unset, i.e. they only
|
|
have an effect on *unprovisioned* systems, and will never override data already
|
|
established in `/etc/`.) A similar line for qemu is:
|
|
|
|
```
|
|
qemu-system-x86_64 \
|
|
-machine type=q35,accel=kvm,smm=on \
|
|
-smp 2 \
|
|
-m 1G \
|
|
-cpu host \
|
|
-nographic \
|
|
-nodefaults \
|
|
-serial mon:stdio \
|
|
-drive if=none,id=hd,file=test.raw,format=raw \
|
|
-device virtio-scsi-pci,id=scsi \
|
|
-device scsi-hd,drive=hd,bootindex=1 \
|
|
-smbios type=11,value=io.systemd.credential:passwd.hashed-password.root=$(mkpasswd mysecret) \
|
|
-smbios type=11,value=io.systemd.credential:firstboot.locale=C.UTF-8
|
|
```
|
|
|
|
This boots the specified disk image via qemu, provisioning public key SSH access
|
|
for the root user from the caller's key, and sends a notification when booting
|
|
has finished to a process on the host:
|
|
|
|
```
|
|
qemu-system-x86_64 \
|
|
-machine type=q35,accel=kvm,smm=on \
|
|
-smp 2 \
|
|
-m 1G \
|
|
-cpu host \
|
|
-nographic \
|
|
-nodefaults \
|
|
-serial mon:stdio \
|
|
-drive if=none,id=hd,file=test.raw,format=raw \
|
|
-device virtio-scsi-pci,id=scsi \
|
|
-device scsi-hd,drive=hd,bootindex=1 \
|
|
-device vhost-vsock-pci,id=vhost-vsock-pci0,guest-cid=42 \
|
|
-smbios type=11,value=io.systemd.credential:vmm.notify_socket=vsock:2:1234 \
|
|
-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)
|
|
```
|
|
|
|
A process on the host can listen for the notification, for example:
|
|
|
|
```
|
|
$ socat - VSOCK-LISTEN:1234,socktype=5
|
|
READY=1
|
|
```
|
|
|
|
## Relevant Paths
|
|
|
|
From *service* perspective the runtime path to find loaded credentials in is
|
|
provided in the `$CREDENTIALS_DIRECTORY` environment variable. For *system
|
|
services* the credential directory will be `/run/credentials/<unit name>`, but
|
|
hardcoding this path is discouraged, because it does not work for *user
|
|
services*. Packagers and system administrators may hardcode the credential path
|
|
as a last resort for software that does not yet search for credentials relative
|
|
to `$CREDENTIALS_DIRECTORY`.
|
|
|
|
From *generator* perspective the runtime path to find credentials passed into
|
|
the system in plaintext form in is provided in `$CREDENTIALS_DIRECTORY`, and
|
|
those passed into the system in encrypted form is provided in
|
|
`$ENCRYPTED_CREDENTIALS_DIRECTORY`.
|
|
|
|
At runtime, credentials passed to the *system* are placed in
|
|
`/run/credentials/@system/` (for regular credentials, such as those passed from
|
|
a container manager or via qemu) and `/run/credentials/@encrypted/` (for
|
|
credentials that must be decrypted/validated before use, such as those from
|
|
`systemd-stub`).
|
|
|
|
The `ImportCredential=` setting (and the `LoadCredential=` and
|
|
`LoadCredentialEncrypted=` settings when configured with a relative source
|
|
path) will search for the source file to read the credential from automatically.
|
|
Primarily, these credentials are searched among the credentials passed into the system. If not found there, they are searched in `/etc/credstore/`, `/run/credstore/`, `/usr/lib/credstore/`. `LoadCredentialEncrypted=` will also search
|
|
`/etc/credstore.encrypted/` and similar directories.
|
|
`ImportCredential=` will search both the non-encrypted and encrypted directories.
|
|
These directories are hence a great place to store credentials to load on the system.
|
|
|
|
## Conditionalizing Services
|
|
|
|
Sometimes it makes sense to conditionalize system services and invoke them only
|
|
if the right system credential is passed to the system.
|
|
Use the `ConditionCredential=` and `AssertCredential=` unit file settings for that.
|