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

[Christian Ebner]

some nits inline

On 3/27/25 11:47, Maximiliano Sandoval wrote:
> Signed-off-by: Maximiliano Sandoval <m.sandoval at proxmox.com>
> ---
>   docs/backup-client.rst | 36 ++++++++++++++++++++++++++++++++++++
>   1 file changed, 36 insertions(+)
> 
> diff --git a/docs/backup-client.rst b/docs/backup-client.rst
> index e11c0142..aea63bd1 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,39 @@ Environment Variables
>      you can add arbitrary comments after the first newline.
>   
>   
> +System Credentials
> +------------------
> +
> +Some of the :ref:`environment variables <environment-variables>` above can be
> +set using `system 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, a credential for the repository password can be stored in an

this sounds a bit redundant, maybe just
```
For example, the repository password can ...
```

> +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 be then reused inside of unit files or in a transient scope

The credential can then be reused ...

> +unit as follows:
> +
> +.. code-block:: console
> +
> +  # systemd-run --pipe --wait \
> +  --property=LoadCredentialEncrypted=proxmox-backup-client.password:my-api-token.cred \

This required the full path to the encrypted file to work as expected, 
so maybe that should be mentioned as otherwise this trips up first users 
(me included).

> +  --property=SetCredential=proxmox-backup-client.repository:'my_default_repository' \
> +  proxmox-backup-client ...
> +
> +
>   Output Format
>   -------------
>

Further, it might be nice to have an example on how to invoke the client 
if the credentials are passed in as system credentials instead, e.g.
```
systemd-run --pipe --wait \\
     --property=LoadCredential=proxmox-backup-client.repository \\
     --property=LoadCredential=proxmox-backup-client.password \\
     --property=LoadCredential=proxmox-backup-client.encryption-password \\
     --property=LoadCredential=proxmox-backup-client.fingerprint \\
     proxmox-backup-client ...
```