From cf37171890bdaec1dc0cd56828047f4eb899fc3a Mon Sep 17 00:00:00 2001
From: Joerg Behrmann <behrmann@physik.fu-berlin.de>
Date: Fri, 20 Oct 2023 11:35:04 +0200
Subject: [PATCH] credentials: document that their path is stable for system
 services

---
 docs/CREDENTIALS.md  | 7 ++++++-
 man/systemd.exec.xml | 7 ++++++-
 2 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/docs/CREDENTIALS.md b/docs/CREDENTIALS.md
index 0ae04690648..f508c84f4c6 100644
--- 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 79d56a5d0f1..a82868aeb12 100644
--- 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>