diff --git a/README.md b/README.md index 4d0fdad91..925b2b333 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,9 @@ borgmatic is powered by [Borg Backup](https://www.borgbackup.org/). ### Credentials Sentry +Docker +Podman +Podman ## Getting started diff --git a/docs/how-to/provide-your-passwords.md b/docs/how-to/provide-your-passwords.md index 01bd6a9cf..b4b5a8df8 100644 --- a/docs/how-to/provide-your-passwords.md +++ b/docs/how-to/provide-your-passwords.md @@ -19,6 +19,7 @@ encryption_passphrase: yourpassphrase But if you'd rather store them outside of borgmatic, whether for convenience or security reasons, read on. + ### Delegating to another application borgmatic supports calling another application such as a password manager to @@ -31,15 +32,6 @@ to provide the passphrase: encryption_passcommand: pass path/to/borg-passphrase ``` -Another example for [KeePassXC](https://keepassxc.org/): - -```yaml -encryption_passcommand: keepassxc-cli show --show-protected --attributes Password credentials.kdbx borg_passphrase -``` - -... where `borg_passphrase` is the title of the KeePassXC entry containing your -Borg encryption passphrase in its `Password` field. - New in version 1.9.9 Instead of letting Borg run the passcommand—potentially multiple times since borgmatic runs Borg multiple times—borgmatic now runs the passcommand itself and passes the @@ -48,9 +40,9 @@ should only ever get prompted for your password manager's passphrase at most once per borgmatic run. -### Using systemd service credentials +### systemd service credentials -borgmatic supports using encrypted [systemd +borgmatic supports reading encrypted [systemd credentials](https://systemd.io/CREDENTIALS/). To use this feature, start by saving your password as an encrypted credential to `/etc/credstore.encrypted/borgmatic.pw`, e.g., @@ -146,13 +138,154 @@ The one exception is `borgmatic config validate`, which doesn't actually load any credentials and should continue working anywhere. +### Container secrets + +New in version 1.9.11 When +running inside a container, borgmatic can read [Docker +secrets](https://docs.docker.com/compose/how-tos/use-secrets/) and [Podman +secrets](https://www.redhat.com/en/blog/new-podman-secrets-command). Creating +those secrets and passing them into your borgmatic container is outside the +scope of this documentation, but here's a simple example of that with [Docker +Compose](https://docs.docker.com/compose/): + +```yaml +services: + borgmatic: + # Use the actual image name of your borgmatic container here. + image: borgmatic:latest + secrets: + - borgmatic_passphrase +secrets: + borgmatic_passphrase: + file: /etc/borgmatic/passphrase.txt +``` + +This assumes there's a file on the host at `/etc/borgmatic/passphrase.txt` +containing your passphrase. Docker or Podman mounts the contents of that file +into a secret named `borgmatic_passphrase` in the borgmatic container at +`/run/secrets/`. + +Once your container secret is in place, you can consume it within your borgmatic +configuration file: + +```yaml +encryption_passphrase: "{credential container borgmatic_passphrase}" +``` + +This reads the secret securely from a file mounted at +`/run/secrets/borgmatic_passphrase` within the borgmatic container. + +The `{credential ...}` syntax 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 ...}`: + +```yaml +postgresql_databases: + - name: invoices + username: postgres + password: "{credential container borgmatic_db1}" +``` + +For specifics about which options are supported, see the +[configuration +reference](https://torsion.org/borgmatic/docs/reference/configuration/). + + +### KeePassXC passwords + +New in version 1.9.11 borgmatic +supports reading passwords from the [KeePassXC](https://keepassxc.org/) password +manager. To use this feature, start by creating an entry in your KeePassXC +database, putting your password into the "Password" field of that entry and +making sure it's saved. + +Then, you can consume that password in your borgmatic configuration file. For +instance, if the entry's title is "borgmatic" and your KeePassXC database is +located at `/etc/keys.kdbx`, do this: + +```yaml +encryption_passphrase: "{credential keepassxc /etc/keys.kdbx borgmatic}" +``` + +But if the entry's title is multiple words like `borg pw`, you'll +need to quote it: + +```yaml +encryption_passphrase: "{credential keepassxc /etc/keys.kdbx 'borg pw'}" +``` + +With this in place, borgmatic runs the `keepassxc-cli` command to retrieve the +passphrase on demand. But note that `keepassxc-cli` will prompt for its own +passphrase in order to unlock its database, so be prepared to enter it when +running borgmatic. + +The `{credential ...}` syntax 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 ...}`: + +```yaml +postgresql_databases: + - name: invoices + username: postgres + password: "{credential keepassxc /etc/keys.kdbx database}" +``` + +For specifics about which options are supported, see the +[configuration +reference](https://torsion.org/borgmatic/docs/reference/configuration/). + + +### File-based credentials + +New in version 1.9.11 borgmatic +supports reading credentials from arbitrary file paths. To use this feature, +start by writing your credential into a file that borgmatic has permission to +read. Take care not to include anything in the file other than your credential. +(borgmatic is smart enough to strip off a trailing newline though.) + +You can consume that credential file in your borgmatic configuration. For +instance, if your credential file is at `/credentials/borgmatic.txt`, do this: + +```yaml +encryption_passphrase: "{credential file /credentials/borgmatic.txt}" +``` + +With this in place, borgmatic reads the credential from the file path. + +The `{credential ...}` syntax 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 ...}`: + +```yaml +postgresql_databases: + - name: invoices + username: postgres + password: "{credential file /credentials/database.txt}" +``` + +For specifics about which options are supported, see the +[configuration +reference](https://torsion.org/borgmatic/docs/reference/configuration/). + + ### Environment variable interpolation New in 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: +values from environment variables. + +Be aware though that environment variables may be less secure than some of the +other approaches above for getting credentials into borgmatic. That's because +environment variables may be visible from within child processes and/or OS-level +process metadata. + +Here's an example of using an environment variable from borgmatic's +configuration file: ```yaml encryption_passphrase: ${YOUR_PASSPHRASE} @@ -214,6 +347,7 @@ can escape it with a backslash. For instance, if your password is literally encryption_passphrase: \${A}@! ``` + ## Related features Another way to override particular options within a borgmatic configuration @@ -226,9 +360,3 @@ 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. - -Lastly, if you do want to specify your passhprase directly within borgmatic -configuration, but you'd like to keep it in a separate file from your main -configuration, you can [use a configuration include or a merge -include](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/#configuration-includes) -to pull in an external password. diff --git a/docs/static/docker.png b/docs/static/docker.png new file mode 100644 index 000000000..a3a192ab8 Binary files /dev/null and b/docs/static/docker.png differ diff --git a/docs/static/keepassxc.png b/docs/static/keepassxc.png new file mode 100644 index 000000000..059e7af9f Binary files /dev/null and b/docs/static/keepassxc.png differ diff --git a/docs/static/podman.png b/docs/static/podman.png new file mode 100644 index 000000000..9d5d7a41f Binary files /dev/null and b/docs/static/podman.png differ diff --git a/docs/static/systemd.png b/docs/static/systemd.png index 40d9adf26..ced38c9e8 100644 Binary files a/docs/static/systemd.png and b/docs/static/systemd.png differ