Document environment variable interpolation (#546).

NEWS

@@ -1,6 +1,7 @@
 1.6.4.dev0
- * #546: Substitute an environment variable anywhere in a borgmatic configuration option value with
+ * #546: Keep your repository passphrases and database passwords outside of borgmatic's
-   new "${MY_ENV_VAR}" syntax.
+   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

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

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
 

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
 

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
 

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
 

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
 

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
 

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
 

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/).

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

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.

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
 

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