[pbs-devel] [PATCH backup v3 7/7] docs: client: add section about system credentials

[Maximiliano Sandoval]

Signed-off-by: Maximiliano Sandoval <m.sandoval at proxmox.com>
---
 docs/backup-client.rst | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/backup-client.rst b/docs/backup-client.rst
index e11c0142a..bc80525be 100644
--- a/docs/backup-client.rst
+++ b/docs/backup-client.rst
@@ -44,6 +44,9 @@ user\@pbs!token at host:store       ``user at pbs!token`` host:8007          store
 [ff80::51]:1234:mydatastore      ``root at pam``       [ff80::51]:1234    mydatastore
 ================================ ================== ================== ===========
 
+
+.. _environment-variables:
+
 Environment Variables
 ---------------------
 
@@ -89,6 +92,43 @@ Environment Variables
    you can add arbitrary comments after the first newline.
 
 
+System and Service Credentials
+------------------------------
+
+Some of the :ref:`environment variables <environment-variables>` above can be
+set using `system and service credentials <https://systemd.io/CREDENTIALS/>`_
+instead.
+
+============================ ==============================================
+Environment Variable         Credential Name Equivalent
+============================ ==============================================
+``PBS_REPOSITORY``           ``proxmox-backup-client.repository``
+``PBS_PASSWORD``             ``proxmox-backup-client.password``
+``PBS_ENCRYPTION_PASSWORD``  ``proxmox-backup-client.encryption-password``
+``PBS_FINGERPRINT``          ``proxmox-backup-client.fingerprint``
+============================ ==============================================
+
+For example, the repository password can be stored in an encrypted file as
+follows:
+
+.. code-block:: console
+
+  # systemd-ask-password -n | systemd-creds encrypt --name=proxmox-backup-client.password - my-api-token.cred
+
+The credential can then be reused inside of unit files or in a transient scope
+unit as follows:
+
+.. code-block:: console
+
+  # systemd-run --pipe --wait \
+      --property=LoadCredentialEncrypted=proxmox-backup-client.password:/full/path/to/my-api-token.cred \
+      --property=SetCredential=proxmox-backup-client.repository:'my_default_repository' \
+      proxmox-backup-client ...
+
+Additionally, system credentials (e.g. passed down from the hypervisor to a
+virtual machine via SMBIOS type 11) can be loaded on a service via
+`LoadCredential=` as described in the manual page ``systemd.exec(5)``.
+
 Output Format
 -------------
 
-- 
2.39.5