1 4.0 Configuration details file
Asif Bacchus edited this page 2 years ago

backup.details file

This file contains all the data needed to access your borg remote data repo. The included sample file is fully commented and should be fairly simple for you to customize. Blank lines and those starting with a '#' are ignored. This script assumes you are adhering to generally accepted security best-practices and using SSH keys to access your repo along with a password and/or repo-key. No provision has been made for SSH access via password or a non-encrypted repo which does not at least require a password. ALL configuration keys are required except the following:

  • borgRepoPassphrase (unknown behaviour if skipped -- see note below)
  • borgKeyfileLocation (will use default location if required)
  • borgXtraListPath (optional list of additional files to include in backup)
  • borgExcludeListPath (optional list of files to exclude from backup)
  • borgPruneSettings (optional but highly recommended)
  • borgRemote (depends on remote-server support)

To skip a configuration key, simply comment it out by placing a '#' before it:

...
#borgXtraListPath=/this/is/ignored/because-of-the-#-symbol
...

If any configuration option does not make sense to you or you do not understand it, please refer to the borg documentation. I have kept the name of the configuration keys very similar to the borg environment variables they set so it should be easy for you to look things up.

Finally, please remember to protect your details file if it contains a password to your borg repo! Even if it doesn't, you should still protect this file to prevent accidental changes which would very likely cause errors in performing backups. Your file should be locked-out to root only as follows:

chown root:root ./backup.details
chmod 600 ./backup.details

borgRepoPassphrase

If you leave the borgRepoPassphrase parameter undefined, the script will insert a dummy passphrase for you. In the case of an unencrypted repo, I have no idea if borg checks this dummy passphrase and fails or simply ignores it and happily continues. I have no idea because I've never tested an unencypted repo and, really, you shouldn't be running in such a configuration! Sorry, I won't test this corner case unless I have several requests to do so and implement support for this feature. File an issue if you need this functionality. For reference, a dummy passphase is inserted because otherwise borg sits waiting (literally) forever for a passphrase to be supplied. With a dummy passphrase, it just fails and issues an error which allows the script to exit properly and log the error.

borgKeyfileLocation

If you skip this parameter, borg will use its internal default location in the event it requires a key file to access your repo. This is only relevant for repos created using the keyfile option since repokey locations store the key within the repo itself and rely solely on the passphrase for decryption. If you are using a keyfile style repo and store your keys in a non-default location, this configuration key is required.

borgXtraListPath

Please see page 4.1 in this wiki.

borgExcludeListPath

Please see page 4.2 in this wiki.

borgPruneSettings

If you omit this, the script will not run borg prune to remove old archives within your repo. Running borg prune is highly recommended to control the history and size of your repo, but if you want to skip this operation then simply comment-out this configuration key. I've provided a few examples and notes on page 4.3 but please also refer to the borg prune documentation for details about how to set this configuration key if you want the script to automatically run borg prune.

borgRemote

If your remote server does not support running the borg server-side component, then you can omit this configuration key. This will result in much slower performance, so I'd suggest talking to your provider if this is the case.

examples

I've provided few examples of using the configuration details file on page 4.4. If you're stuck, file an issue and I'll try to help you out.