From dfc4db18602ecadf8876e1585f679f684b7a22ca Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Thu, 16 Jun 2022 15:30:53 -0700 Subject: [PATCH] Document environment variable interpolation (#546). --- NEWS | 5 +- ...reparation-and-cleanup-steps-to-backups.md | 6 +- ...movable-drive-or-an-intermittent-server.md | 2 +- docs/how-to/backup-your-databases.md | 10 ++- docs/how-to/deal-with-very-large-backups.md | 2 +- docs/how-to/develop-on-borgmatic.md | 2 +- docs/how-to/extract-a-backup.md | 2 +- docs/how-to/inspect-your-backups.md | 2 +- docs/how-to/make-backups-redundant.md | 2 +- docs/how-to/make-per-application-backups.md | 2 + docs/how-to/monitor-your-backups.md | 2 +- docs/how-to/provide-your-passwords.md | 81 +++++++++++++++++++ docs/how-to/run-arbitrary-borg-commands.md | 2 +- docs/how-to/upgrade.md | 2 +- 14 files changed, 109 insertions(+), 13 deletions(-) create mode 100644 docs/how-to/provide-your-passwords.md diff --git a/NEWS b/NEWS index fb797d52e..472d37f45 100644 --- a/NEWS +++ b/NEWS @@ -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 diff --git a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md index 1a5d03366..39bad04fc 100644 --- a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md +++ b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md @@ -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 diff --git a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md index 00906274a..1ce53bae4 100644 --- a/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md +++ b/docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md @@ -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 diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index f90286ddf..dccb9e6e9 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -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 diff --git a/docs/how-to/deal-with-very-large-backups.md b/docs/how-to/deal-with-very-large-backups.md index 2a6bff44e..ef552eacc 100644 --- a/docs/how-to/deal-with-very-large-backups.md +++ b/docs/how-to/deal-with-very-large-backups.md @@ -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 diff --git a/docs/how-to/develop-on-borgmatic.md b/docs/how-to/develop-on-borgmatic.md index 8cad4c744..80ecf3047 100644 --- a/docs/how-to/develop-on-borgmatic.md +++ b/docs/how-to/develop-on-borgmatic.md @@ -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 diff --git a/docs/how-to/extract-a-backup.md b/docs/how-to/extract-a-backup.md index ea641db16..0dd47b0cc 100644 --- a/docs/how-to/extract-a-backup.md +++ b/docs/how-to/extract-a-backup.md @@ -3,7 +3,7 @@ title: How to extract a backup eleventyNavigation: key: ๐Ÿ“ค Extract a backup parent: How-to guides - order: 6 + order: 7 --- ## Extract diff --git a/docs/how-to/inspect-your-backups.md b/docs/how-to/inspect-your-backups.md index 0d7663f1d..b2a1d92d6 100644 --- a/docs/how-to/inspect-your-backups.md +++ b/docs/how-to/inspect-your-backups.md @@ -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 diff --git a/docs/how-to/make-backups-redundant.md b/docs/how-to/make-backups-redundant.md index c2c0b0e52..c42e29ac9 100644 --- a/docs/how-to/make-backups-redundant.md +++ b/docs/how-to/make-backups-redundant.md @@ -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 diff --git a/docs/how-to/make-per-application-backups.md b/docs/how-to/make-per-application-backups.md index e7152ec3b..84e1649fb 100644 --- a/docs/how-to/make-per-application-backups.md +++ b/docs/how-to/make-per-application-backups.md @@ -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/). diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md index 3c415faae..3dabb7de2 100644 --- a/docs/how-to/monitor-your-backups.md +++ b/docs/how-to/monitor-your-backups.md @@ -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 diff --git a/docs/how-to/provide-your-passwords.md b/docs/how-to/provide-your-passwords.md new file mode 100644 index 000000000..052886e5d --- /dev/null +++ b/docs/how-to/provide-your-passwords.md @@ -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. diff --git a/docs/how-to/run-arbitrary-borg-commands.md b/docs/how-to/run-arbitrary-borg-commands.md index ae42307ff..f0e152947 100644 --- a/docs/how-to/run-arbitrary-borg-commands.md +++ b/docs/how-to/run-arbitrary-borg-commands.md @@ -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 diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md index 5affe0f63..cdcdefe5f 100644 --- a/docs/how-to/upgrade.md +++ b/docs/how-to/upgrade.md @@ -3,7 +3,7 @@ title: How to upgrade borgmatic eleventyNavigation: key: ๐Ÿ“ฆ Upgrade borgmatic parent: How-to guides - order: 11 + order: 12 --- ## Upgrading