4.0-Configuration-files.md

@@ -0,0 +1,56 @@
+## configuration files
+
+### 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 -- 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:
+
+```ini
+...
+#borgBaseDir=/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](https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables). 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:
+
+```bash
+chown root:root ./backup.details
+chmod 600 ./backup.details
+```
+
+#### skip: 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 whether it ignores it can 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 since 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.
+
+#### skip: 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, then this configuration key is **required**.
+
+#### skip: borgXtraListPath
+
+Please see section about *xtraLocations.borg* on this page.
+
+#### skip: borgExcludeListPath
+
+Please see section about *excludeLocations.borg* on this page.
+
+#### skip: 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. Please refer to the [borg prune documentation](https://borgbackup.readthedocs.io/en/stable/usage/prune.html) for details about how to set this configuration key if you want the script to automatically run borg prune.
+
+#### skip: 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.
+
+### xtraLocations.borg
+