From: Lennart Poettering Date: Fri, 22 Apr 2022 13:41:53 +0000 (+0200) Subject: man: document the new credentials features X-Git-Tag: v251-rc2~38^2~3 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=72267a55a1adc3798257dc7ff0ce4a6e7594e146;p=thirdparty%2Fsystemd.git man: document the new credentials features --- diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml index 79bd90b340f..96bdc722529 100644 --- a/man/kernel-command-line.xml +++ b/man/kernel-command-line.xml @@ -73,6 +73,8 @@ systemd.machine_id= systemd.unified_cgroup_hierarchy systemd.legacy_systemd_cgroup_controller + systemd.set_credential= + systemd.import_credentials= Parameters understood by the system and service manager to control system behavior. For details, see diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 0042432efb1..1ff079e1c70 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -3039,20 +3039,31 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy is absolute it is opened as regular file and the credential data is read from it. If the absolute path refers to an AF_UNIX stream socket in the file system a connection is made to it (only once at unit start-up) and the credential data read from the connection, providing an - easy IPC integration point for dynamically providing credentials from other services. If the - specified path is not absolute and itself qualifies as valid credential identifier it is understood - to refer to a credential that the service manager itself received via the - $CREDENTIALS_DIRECTORY environment variable, which may be used to propagate - credentials from an invoking environment (e.g. a container manager that invoked the service manager) - into a service. The contents of the file/socket may be arbitrary binary or textual data, including - newline characters and NUL bytes. If the file system path is omitted it is - chosen identical to the credential name, i.e. this is a terse way do declare credentials to inherit - from the service manager into a service. This option may be used multiple times, each time defining - an additional credential to pass to the unit. Alternatively, if the path is a directory, every file - in that directory will be loaded as a separate credential. The ID for each credential will be the + easy IPC integration point for dynamically transferring credentials from other services. + + If the specified path is not absolute and itself qualifies as valid credential identifier it is + attempted to find a credential that the service manager itself received under the specified name — + which may be used to propagate credentials from an invoking environment (e.g. a container manager + that invoked the service manager) into a service. If no matching system credential is found, the + directories /etc/credstore/, /run/credstore/ and + /usr/lib/credstore/ are searched for files under the credential's name — which + hence are recommended locations for credential data on disk. If + LoadCredentialEncrypted= is used /run/credstore.encrypted/, + /etc/credstore.encrypted/, and + /usr/lib/credstore.encrypted/ are searched as well. + + If the file system path is omitted it is chosen identical to the credential name, i.e. this is + a terse way to declare credentials to inherit from the service manager into a service. This option + may be used multiple times, each time defining an additional credential to pass to the unit. + + If an absolute path referring to a directory is specified, every file in that directory + (recursively) will be loaded as a separate credential. The ID for each credential will be the provided ID suffixed with _$FILENAME (e.g., Key_file1). When loading from a directory, symlinks will be ignored. + The contents of the file/socket may be arbitrary binary or textual data, including newline + characters and NUL bytes. + The LoadCredentialEncrypted= setting is identical to LoadCredential=, except that the credential data is decrypted and authenticated before being passed on to the executed processes. Specifically, the referenced path should refer to a @@ -3077,10 +3088,23 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy In order to reference the path a credential may be read from within a ExecStart= command line use ${CREDENTIALS_DIRECTORY}/mycred, - e.g. ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred. + e.g. ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred. In order to reference the path + a credential may be read from within a Environment= line use + %d/mycred, e.g. Environment=MYCREDPATH=%d/mycred. Currently, an accumulated credential size limit of 1 MB per unit is enforced. + The service manager itself may receive system credentials that can be propagated to services + from a hosting container manager or VM hypervisor. See the Container Interface documentation for details + about the former. For the latter, use the qemu fw_cfg node + opt/io.systemd.credentials/. Example qemu switch: -fw_cfg + name=opt/io.systemd.credentials/mycred,string=supersecret. They may also be specified on + the kernel command line using the systemd.set_credential= switch (see + systemd1) + and from the UEFI firmware environment via + systemd-stub7. + If referencing an AF_UNIX stream socket to connect to, the connection will originate from an abstract namespace socket, that includes information about the unit and the credential ID in its socket name. Use + + systemd.set_credential= + + Sets a system credential, which can then be propagated to system services using the + LoadCredential= setting, see + systemd.exec5 for + details. Takes a pair of credential name and value, separated by a colon. Note that the kernel + command line is typically accessible by unprivileged programs in + /proc/cmdline. Thus, this mechanism is not suitable for transferring sensitive + data. Use it only for data that is not sensitive (e.g. public keys/certificates, rather than private + keys), or in testing/debugging environments. + + + + systemd.import_credentials= + + Takes a boolean argument. If false disables importing credentials from the kernel + command line, qemu_fw_cfg subsystem or the kernel command line. + + quiet