How to provide your passwords

Providing passwords and secrets to borgmatic

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. For instance, you can specify your Borg passhprase with:

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 obtain the Borg passphrase to a repository.

For example, to ask the Pass password manager to provide the passphrase:

encryption_passcommand: pass path/to/borg-repokey

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:

encryption_passphrase: ${YOUR_PASSPHRASE}

Prior to version 1.8.0 Put this option in the storage: section of your configuration.

This uses the YOUR_PASSPHRASE environment variable as your encryption passphrase. Note that the { } brackets are required. $YOUR_PASSPHRASE by itself 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, the same approach applies. For example:

postgresql_databases:
    - name: users
      password: ${YOUR_DATABASE_PASSWORD}

Prior to version 1.8.0 Put this option in the hooks: section of your configuration.

This uses the YOUR_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:

encryption_passphrase: ${YOUR_PASSPHRASE:-defaultpass}

Here, "defaultpass" is the default passphrase if the YOUR_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.

Or if you'd like to disable interpolation within a single option value, you can escape it with a backslash. For instance, if your password is literally ${A}@!:

encryption_passphrase: \${A}@!

Another way to override particular options within a borgmatic configuration file is to use a configuration override 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, 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 to pull in an external password.

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!