credentials: document that their path is stable for system services

diff --git a/docs/CREDENTIALS.md b/docs/CREDENTIALS.md
index 0ae04690648a915f72dc3774cecd4e9298aae5a4..f508c84f4c6a41c597026bcf69f97ec457e2db17 100644 (file)
--- a/docs/CREDENTIALS.md
+++ b/docs/CREDENTIALS.md
@@ -468,7 +468,12 @@ READY=1
 ## Relevant Paths
 
 From *service* perspective the runtime path to find loaded credentials in is
-provided in the `$CREDENTIALS_DIRECTORY` environment variable.
+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

diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml
index 79d56a5d0f1f7f9f96879bb70dc9530f5f166db2..a82868aeb123da1df8719b037afe5438c538b743 100644 (file)
--- a/man/systemd.exec.xml
+++ b/man/systemd.exec.xml
@@ -3430,7 +3430,12 @@ StandardInputData=V2XigLJyZSBubyBzdHJhbmdlcnMgdG8gbG92ZQpZb3Uga25vdyB0aGUgcnVsZX
         <varname>ExecStart=</varname> command line use <literal>${CREDENTIALS_DIRECTORY}/mycred</literal>,
         e.g. <literal>ExecStart=cat ${CREDENTIALS_DIRECTORY}/mycred</literal>. In order to reference the path
         a credential may be read from within a <varname>Environment=</varname> line use
-        <literal>%d/mycred</literal>, e.g. <literal>Environment=MYCREDPATH=%d/mycred</literal>.</para>
+        <literal>%d/mycred</literal>, e.g. <literal>Environment=MYCREDPATH=%d/mycred</literal>. For system
+        services the path may also be referenced as
+        <literal>/run/credentials/<replaceable>UNITNAME</replaceable></literal> in cases where no
+        interpolation is possible, e.g. configuration files of software that does not yet support credentials
+        natively. <varname>$CREDENTIALS_DIRECTORY</varname> is considered the primary interface to look for
+        credentials, though, since it also works for user services.</para>
 
         <para>Currently, an accumulated credential size limit of 1 MB per unit is enforced.</para>