diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 6d1c4e0528..d54648a966 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -2154,11 +2154,13 @@ SystemCallErrorNumber=EPERM project='man-pages'>environ7 for details about environment variables. - Note that environment variables are not suitable for passing secrets (such as passwords, key material, …) - to service processes. Environment variables set for a unit are exposed to unprivileged clients via D-Bus IPC, - and generally not understood as being data that requires protection. Moreover, environment variables are - propagated down the process tree, including across security boundaries (such as setuid/setgid executables), and - hence might leak to processes that should not have access to the secret data. + Note that environment variables are not suitable for passing secrets (such as passwords, key + material, …) to service processes. Environment variables set for a unit are exposed to unprivileged + clients via D-Bus IPC, and generally not understood as being data that requires protection. Moreover, + environment variables are propagated down the process tree, including across security boundaries + (such as setuid/setgid executables), and hence might leak to processes that should not have access to + the secret data. Use LoadCredential= (see below) to pass data to unit processes + securely. @@ -2624,6 +2626,73 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy + + Credentials + + + + + LoadCredential=ID:PATH + + Pass a credential to the unit. Credentials are limited-size binary or textual objects + that may be passed to unit processes. They are primarily used for passing cryptographic keys (both + public and private) or certificates, user account information or identity information from host to + services. The data is accessible from the unit's processes via the file system, at a read-only + location that (if possible and permitted) is backed by non-swappable memory. The data is only + accessible to the user associated with the unit, via the + User=/DynamicUser= settings (as well as the superuser). When + available, the location of credentials is exported as the $CREDENTIALS_DIRECTORY + environment variable to the unit's processes. + + The LoadCredential= setting takes a textual ID to use as name for a + credential plus a file system path. The ID must be a short ASCII string suitable as filename in the + filesystem, and may be chosen freely by the user. If the specified path 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 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. This option may be used multiple times, each time + defining an additional credential to pass to the unit. + + The credential files/IPC sockets must be accessible to the service manager, but don't have to + be directly accessible to the unit's processes: the credential data is read and copied into separate, + read-only copies for the unit that are accessible to appropriately privileged processes. This is + particularly useful in combination with DynamicUser= as this way privileged data + can be made available to processes running under a dynamic UID (i.e. not a previously known one) + without having to open up access to all users. + + 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. + + Currently, an accumulated credential size limit of 1M bytes per unit is + enforced. + + + + SetCredential=ID:VALUE + + The SetCredential= setting is similar to + LoadCredential= but accepts a literal value to use as data for the credential, + instead of a file system path to read the data from. Do not use this option for data that is supposed + to be secret, as it is accessible to unprivileged processes via IPC. It's only safe to use this for + user IDs, public key material and similar non-sensitive data. For everything else use + LoadCredential=. In order to embed binary data into the credential data use + C-style escaping (i.e. \n to embed a newline, or \x00 to embed + a NUL byte). + + If a credential of the same ID is listed in both LoadCredential= and + SetCredential=, the latter will act as default if the former cannot be + retrieved. In this case not being able to retrieve the credential from the path specified in + LoadCredential= is not considered fatal. + + + + System V Compatibility @@ -2779,6 +2848,16 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy + + $CREDENTIALS_DIRECTORY + + An absolute path to the per-unit directory with credentials configured via + LoadCredential=/SetCredential=. The directory is marked + read-only and is placed in unswappable memory (if supported and permitted), and is only accessible to + the UID associated with the unit via User= or DynamicUser= (and + the superuser). + + $MAINPID @@ -3380,7 +3459,11 @@ StandardInputData=SWNrIHNpdHplIGRhIHVuJyBlc3NlIEtsb3BzLAp1ZmYgZWVtYWwga2xvcHAncy EXIT_NUMA_POLICY Failed to set up unit's NUMA memory policy. See NUMAPolicy= and NUMAMask= above. - + + 243 + EXIT_CREDENTIALS + Failed to set up unit's credentials. See LoadCredential= and SetCredential= above. +