Update documentation to describe delayed !credential tag approach (#966).

borgmatic/config/schema.yaml

@@ -250,7 +250,7 @@ properties:
             repositories that were initialized with passphrase/repokey/keyfile
             encryption. Quote the value if it contains punctuation, so it parses
             correctly. And backslash any quote or backslash literals as well.
-            Defaults to not set.
+            Defaults to not set. Supports the "!credential" tag.
         example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
     checkpoint_interval:
         type: integer
@@ -989,13 +989,13 @@ properties:
                         Username with which to connect to the database. Defaults
                         to the username of the current user. You probably want
                         to specify the "postgres" superuser here when the
-                        database name is "all".
+                        database name is "all". Supports the "!credential" tag.
                     example: dbuser
                 restore_username:
                     type: string
                     description: |
                         Username with which to restore the database. Defaults to
-                        the "username" option.
+                        the "username" option. Supports the "!credential" tag.
                     example: dbuser
                 password:
                     type: string
@@ -1003,13 +1003,14 @@ properties:
                         Password with which to connect to the database. Omitting
                         a password will only work if PostgreSQL is configured to
                         trust the configured username without a password or you
-                        create a ~/.pgpass file.
+                        create a ~/.pgpass file. Supports the "!credential" tag.
                     example: trustsome1
                 restore_password:
                     type: string
                     description: |
                         Password with which to connect to the restore database.
-                        Defaults to the "password" option.
+                        Defaults to the "password" option. Supports the
+                        "!credential" tag.
                     example: trustsome1
                 no_owner:
                     type: boolean
@@ -1169,13 +1170,14 @@ properties:
                     type: string
                     description: |
                         Username with which to connect to the database. Defaults
-                        to the username of the current user.
+                        to the username of the current user. Supports the
+                        "!credential" tag.
                     example: dbuser
                 restore_username:
                     type: string
                     description: |
                         Username with which to restore the database. Defaults to
-                        the "username" option.
+                        the "username" option. Supports the "!credential" tag.
                     example: dbuser
                 password:
                     type: string
@@ -1183,6 +1185,14 @@ properties:
                         Password with which to connect to the database. Omitting
                         a password will only work if MariaDB is configured to
                         trust the configured username without a password.
+                        Supports the "!credential" tag.
+                    example: trustsome1
+                restore_password:
+                    type: string
+                    description: |
+                        Password with which to connect to the restore database.
+                        Defaults to the "password" option. Supports the
+                        "!credential" tag.
                     example: trustsome1
                 mariadb_dump_command:
                     type: string
@@ -1201,12 +1211,6 @@ properties:
                         run a specific mariadb version (e.g., one inside a
                         running container). Defaults to "mariadb".
                     example: docker exec mariadb_container mariadb           
-                restore_password:
-                    type: string
-                    description: |
-                        Password with which to connect to the restore database.
-                        Defaults to the "password" option.
-                    example: trustsome1
                 format:
                     type: string
                     enum: ['sql']
@@ -1295,13 +1299,14 @@ properties:
                     type: string
                     description: |
                         Username with which to connect to the database. Defaults
-                        to the username of the current user.
+                        to the username of the current user. Supports the
+                        "!credential" tag.
                     example: dbuser
                 restore_username:
                     type: string
                     description: |
                         Username with which to restore the database. Defaults to
-                        the "username" option.
+                        the "username" option. Supports the "!credential" tag.
                     example: dbuser
                 password:
                     type: string
@@ -1309,12 +1314,14 @@ properties:
                         Password with which to connect to the database. Omitting
                         a password will only work if MySQL is configured to
                         trust the configured username without a password.
+                        Supports the "!credential" tag.
                     example: trustsome1
                 restore_password:
                     type: string
                     description: |
                         Password with which to connect to the restore database.
-                        Defaults to the "password" option.
+                        Defaults to the "password" option. Supports the
+                        "!credential" tag.
                     example: trustsome1
                 mysql_dump_command:
                     type: string
@@ -1451,25 +1458,28 @@ properties:
                     type: string
                     description: |
                         Username with which to connect to the database. Skip it
-                        if no authentication is needed.
+                        if no authentication is needed. Supports the
+                        "!credential" tag.
                     example: dbuser
                 restore_username:
                     type: string
                     description: |
                         Username with which to restore the database. Defaults to
-                        the "username" option.
+                        the "username" option. Supports the "!credential" tag.
                     example: dbuser
                 password:
                     type: string
                     description: |
                         Password with which to connect to the database. Skip it
-                        if no authentication is needed.
+                        if no authentication is needed. Supports the
+                        "!credential" tag.
                     example: trustsome1
                 restore_password:
                     type: string
                     description: |
                         Password with which to connect to the restore database.
-                        Defaults to the "password" option.
+                        Defaults to the "password" option. Supports the
+                        "!credential" tag.
                     example: trustsome1
                 authentication_database:
                     type: string
@@ -1528,18 +1538,20 @@ properties:
             username:
                 type: string
                 description: |
-                    The username used for authentication.
+                    The username used for authentication. Supports the
+                    "!credential" tag.
                 example: testuser
             password:
                 type: string
                 description: |
-                    The password used for authentication.
+                    The password used for authentication. Supports the
+                    "!credential" tag.
                 example: fakepassword
             access_token:
                 type: string
                 description: |
                     An ntfy access token to authenticate with instead of
-                    username/password.
+                    username/password. Supports the "!credential" tag.
                 example: tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2
             start:
                 type: object
@@ -1634,14 +1646,15 @@ properties:
             token:
                 type: string
                 description: |
-                    Your application's API token.
+                    Your application's API token. Supports the "!credential" tag.
                 example: 7ms6TXHpTokTou2P6x4SodDeentHRa
             user:
                 type: string
                 description: |
-                    Your user/group key (or that of your target user), viewable 
-                    when logged into your dashboard: often referred to as 
+                    Your user/group key (or that of your target user), viewable
+                    when logged into your dashboard: often referred to as
                     USER_KEY in Pushover documentation and code examples.
+                    Supports the "!credential" tag.
                 example: hwRwoWsXMBWwgrSecfa9EfPey55WSN
             start:
                 type: object
@@ -1915,19 +1928,19 @@ properties:
                 type: string
                 description: |
                     The username used for authentication. Not needed if using
-                    an API key.
+                    an API key. Supports the "!credential" tag.
                 example: testuser
             password:
                 type: string
                 description: |
                     The password used for authentication. Not needed if using
-                    an API key.
+                    an API key. Supports the "!credential" tag.
                 example: fakepassword
             api_key:
                 type: string
                 description: |
                     The API key used for authentication. Not needed if using
-                    an username/password.
+                    an username/password. Supports the "!credential" tag.
                 example: fakekey
             start:
                 type: object
@@ -2208,7 +2221,7 @@ properties:
                 type: string
                 description: |
                     PagerDuty integration key used to notify PagerDuty
-                    when a backup errors.
+                    when a backup errors. Supports the "!credential" tag.
                 example: a177cad45bd374409f78906a810a3074
         description: |
             Configuration for a monitoring integration with PagerDuty. Create an

docs/how-to/provide-your-passwords.md

@@ -71,11 +71,13 @@ accomplish the same thing with this configuration:
 ```yaml
 encryption_passcommand: cat ${CREDENTIALS_DIRECTORY}/borgmatic.pw
 ```
+
 Note that the name `borgmatic.pw` is hardcoded in the systemd service file.
 
-You can use the `!credential` tag for any option value in a borgmatic
-configuration file. So for example, use `!credential` to load systemd
-credentials for database or monitoring passwords:
+The `!credential` tag works for several different options in a borgmatic
+configuration file besides just `encryption_passphrase`. For instance, the
+username, password, and API token options within database and monitoring hooks
+support `!credential`. For example:
 
 ```yaml
 postgresql_databases:
@@ -84,11 +86,15 @@ postgresql_databases:
       password: !credential systemd borgmatic_db1
 ```
 
-But first you'll need to modify the borgmatic systemd service file to support
-loading multiple credentials (assuming you need to load more than one or
-anything not named `borgmatic.pw`).
+For specifics about which options are supported, see the
+[configuration
+reference](https://torsion.org/borgmatic/docs/reference/configuration/).
+
+To use these credentials, you'll need to modify the borgmatic systemd service
+file to support loading multiple credentials (assuming you need to load more
+than one or anything not named `borgmatic.pw`).
 
-To do this, save each encrypted credentials to
+Start by saving each encrypted credentials to
 `/etc/credstore.encrypted/borgmatic/`. E.g.,
 
 ```bash
@@ -129,11 +135,15 @@ encryption_passcommand: cat ${CREDENTIALS_DIRECTORY}/borgmatic_backupserver1
 Adjust `borgmatic_backupserver1` according to the name of the credential and the
 directory set in the service file.
 
-Be aware that when using this systemd `!credential` feature, you can no longer
-run borgmatic outside of its systemd service, as the credentials are only
-available from within the context of that service. The one exception is
-`borgmatic config validate`, which doesn't actually load any credentials and
-should continue working anywhere.
+Be aware that when using this systemd `!credential` feature, you may no longer
+be able to run certain borgmatic actions outside of the systemd service, as the
+credentials are only available from within the context of that service. So for
+instance, `borgmatic list` necessarily relies on the `encryption_passphrase` in
+order to access the Borg repository, but it shouldn't need to load any
+credentials for your database or monitoring hooks.
+
+The one exception is `borgmatic config validate`, which doesn't actually load
+any credentials and should continue working anywhere.
 
 
 ### Environment variable interpolation