peter/borgmatic
1
0
Fork 0
mirror of https://github.com/borgmatic-collective/borgmatic.git synced 2026-07-30 13:23:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Dan Helfman
2025-02-09 15:27:58 -08:00
parent 49719dc309
commit efdbee934a
2 changed files with 65 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
borgmatic/config/schema.yaml
+43 -30
View File
@@ -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
+22 -12
View File
@@ -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 do this, save each encrypted credentials to
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`).
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