man: document credentials passing in the container interface

poettering · poettering · commit b0d29bfdfd50 · 2020-08-25T19:46:32.000+02:00
diff --git a/docs/CONTAINER_INTERFACE.md b/docs/CONTAINER_INTERFACE.md
@@ -131,6 +131,17 @@ manager, please consider supporting the following interfaces.
    `$container_host_variant_id=server`
    `$container_host_version_id=10`
 
+5. systemd supports passing immutable binary data blobs with limited size and
+   restricted access to services via the `LoadCredential=` and `SetCredential=`
+   settings. The same protocol may be used to pass credentials from the
+   container manager to systemd itself. The credential data should be placed in
+   some location (ideally a read-only and non-swappable file system, like
+   'ramfs'), and the absolute path to this directory exported in the
+   `$CREDENTIALS_DIRECTORY` environment variable. If the container managers
+   does this, the credentials passed to the service manager can be propagated
+   to services via `LoadCredential=` (see ...). The container manager can
+   choose any path, but `/run/host/credentials` is recommended."
+
 ## Advanced Integration
 
 1. Consider syncing `/etc/localtime` from the host file system into the
@@ -228,7 +239,7 @@ care should be taken to avoid naming conflicts. `systemd` (and in particular
    inaccessible. Note that systemd when run as PID 1 in the container payload
    will create these nodes on its own if not passed in by the container
    manager. However, in that case it likely lacks the privileges to create the
-   character and block devices nodes (there all fallbacks for this case).
+   character and block devices nodes (there are fallbacks for this case).
 
 3. The `/run/host/notify` path is a good choice to place the `sd_notify()`
    socket in, that may be used for the container's PID 1 to report to the
@@ -252,6 +263,9 @@ care should be taken to avoid naming conflicts. `systemd` (and in particular
    as the `$container_uuid` environment variable (see above). This file should
    be newline terminated.
 
+7. The `/run/host/credentials/` directory is a good place to pass credentials
+   into the container, using the `$CREDENTIALS_DIRECTORY` protocol, see above.
+
 ## What You Shouldn't Do
 
 1. Do not drop `CAP_MKNOD` from the container. `PrivateDevices=` is a commonly
