Document environment variable interpolation (#546).

This commit is contained in:
Dan Helfman 2022-06-16 15:30:53 -07:00
parent 35706604ea
commit dfc4db1860
14 changed files with 109 additions and 13 deletions

5
NEWS
View file

@ -1,6 +1,7 @@
1.6.4.dev0
* #546: Substitute an environment variable anywhere in a borgmatic configuration option value with
new "${MY_ENV_VAR}" syntax.
* #546: Keep your repository passphrases and database passwords outside of borgmatic's
configuration file with environment variable interpolation. See the documentation for more
information: https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/
1.6.3
* #541: Add "borgmatic list --find" flag for searching for files across multiple archives, useful

View file

@ -3,7 +3,7 @@ title: How to add preparation and cleanup steps to backups
eleventyNavigation:
key: 🧹 Add preparation and cleanup steps
parent: How-to guides
order: 8
order: 9
---
## Preparation and cleanup hooks
@ -61,6 +61,10 @@ variables you can use here:
* `repository`: path of the current repository as configured in the current
borgmatic configuration file
Note that you can also interpolate in [arbitrary environment
variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).
## Global hooks
You can also use `before_everything` and `after_everything` hooks to perform

View file

@ -3,7 +3,7 @@ title: How to backup to a removable drive or an intermittent server
eleventyNavigation:
key: 💾 Backup to a removable drive/server
parent: How-to guides
order: 9
order: 10
---
## Occasional backups

View file

@ -3,7 +3,7 @@ title: How to backup your databases
eleventyNavigation:
key: 🗄️ Backup your databases
parent: How-to guides
order: 7
order: 8
---
## Database dump hooks
@ -100,6 +100,14 @@ hooks:
- name: all
```
### External passwords
If you don't want to keep your database passwords in your borgmatic
configuration file, you can instead pass them in via [environment
variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/)
or command-line [configuration
overrides](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#configuration-overrides).
### Configuration backups

View file

@ -3,7 +3,7 @@ title: How to deal with very large backups
eleventyNavigation:
key: 📏 Deal with very large backups
parent: How-to guides
order: 3
order: 4
---
## Biggish data

View file

@ -3,7 +3,7 @@ title: How to develop on borgmatic
eleventyNavigation:
key: 🏗️ Develop on borgmatic
parent: How-to guides
order: 12
order: 13
---
## Source code

View file

@ -3,7 +3,7 @@ title: How to extract a backup
eleventyNavigation:
key: 📤 Extract a backup
parent: How-to guides
order: 6
order: 7
---
## Extract

View file

@ -3,7 +3,7 @@ title: How to inspect your backups
eleventyNavigation:
key: 🔎 Inspect your backups
parent: How-to guides
order: 4
order: 5
---
## Backup progress

View file

@ -3,7 +3,7 @@ title: How to make backups redundant
eleventyNavigation:
key: ☁️ Make backups redundant
parent: How-to guides
order: 2
order: 3
---
## Multiple repositories

View file

@ -203,3 +203,5 @@ indentation and a leading dash.)
Be sure to quote your overrides if they contain spaces or other characters
that your shell may interpret.
An alternate to command-line overrides is passing in your values via [environment variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).

View file

@ -3,7 +3,7 @@ title: How to monitor your backups
eleventyNavigation:
key: 🚨 Monitor your backups
parent: How-to guides
order: 5
order: 6
---
## Monitoring and alerting

View file

@ -0,0 +1,81 @@
---
title: How to provide your passwords
eleventyNavigation:
key: 🔒 Provide your passwords
parent: How-to guides
order: 2
---
## Environment variable interpolation
If you want to use a Borg repository passphrase or database passwords with
borgmatic, you can set them directly in your borgmatic configuration file,
treating those secrets like any other option value. But if you'd rather store
them outside of borgmatic, whether for convenience or security reasons, read
on.
As of version 1.6.4, borgmatic supports interpolating arbitrary environment
variables directly into option values in your configuration file. That means
you can instruct borgmatic to pull your repository passphrase, your database
passwords, or any other option values from environment variables. For
instance:
```yaml
storage:
encryption_passphrase: ${MY_PASSPHRASE}
```
This uses the `MY_PASSPHRASE` environment variable as your encryption
passphrase. Note that the `{` `}` brackets are required. Just `$MY_PASSPHRASE`
will not work.
In the case of `encryption_passphrase` in particular, an alternate approach
is to use Borg's `BORG_PASSPHRASE` environment variable, which doesn't even
require setting an explicit `encryption_passphrase` value in borgmatic's
configuration file.
For [database
configuration](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/),
the same approach applies. For example:
```yaml
hooks:
postgresql_databases:
- name: users
password: ${MY_DATABASE_PASSWORD}
```
This uses the `MY_DATABASE_PASSWORD` environment variable as your database
password.
### Interpolation defaults
If you'd like to set a default for your environment variables, you can do so with the following syntax:
```yaml
storage:
encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
```
Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE`
environment variable is not set. Without a default, if the environment
variable doesn't exist, borgmatic will error.
### Disabling interpolation
To disable this environment variable interpolation feature entirely, you can
pass the `--no-environment-interpolation` flag on the command-line.
### Related features
Another way to override particular options within a borgmatic configuration
file is to use a [configuration
override](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#configuration-overrides)
on the command-line. But please be aware of the security implications of
specifying secrets on the command-line.
Additionally, borgmatic action hooks support their own [variable
interpolation](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation),
although in that case it's for particular borgmatic runtime values rather than
(only) environment variables.

View file

@ -3,7 +3,7 @@ title: How to run arbitrary Borg commands
eleventyNavigation:
key: 🔧 Run arbitrary Borg commands
parent: How-to guides
order: 10
order: 11
---
## Running Borg with borgmatic

View file

@ -3,7 +3,7 @@ title: How to upgrade borgmatic
eleventyNavigation:
key: 📦 Upgrade borgmatic
parent: How-to guides
order: 11
order: 12
---
## Upgrading