4.0-Configuration-files.md

@@ -4,7 +4,7 @@
 
 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)
+- 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)
@@ -15,7 +15,7 @@ To skip a configuration key, simply comment it out by placing a '#' before it:
 
 ```ini
 ...
-#borgBaseDir=/this/is/ignored/because-of-the-#-symbol
+#borgXtraListPath=/this/is/ignored/because-of-the-#-symbol
 ...
 ```
 
@@ -30,19 +30,19 @@ 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.
+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.
 
 #### 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**.
+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**.
 
 #### skip: borgXtraListPath
 
-Please see section about *xtraLocations.borg* on this page.
+Please see the section about *xtraLocations.borg* on this page.
 
 #### skip: borgExcludeListPath
 
-Please see section about *excludeLocations.borg* on this page.
+Please see the section about *excludeLocations.borg* on this page.
 
 #### skip: borgPruneSettings
 
@@ -54,3 +54,57 @@ If your remote server does not support running the borg server-side component, t
 
 ### xtraLocations.borg
 
+This is a plain-text list of additional files and directories you'd like the script to include in your backup. Entries should be listed one per line. By convention, directories should include a trailing slash but this is not required. For example, let's include the following locations in our backup:
+
+```ini
+/home/jsmith/
+/etc/program/*.conf
+/etc/foo.bar
+/opt/foo
+```
+
+The above would include:
+
+- the entire directory */home/jsmith/* and all files and subdirectories contained therein;
+- all files in */etc/program/* directory with the extension *.conf*;
+- the individual file */etc/foo.bar*; and
+- the directory */opt/foo*, notice that the lack of trailing slash doesn't matter.
+
+This file is *strictly optional* but recommended since it's often nice to include your server configuration and/or things like reverse-proxy configurations when backing up your mailcow installation. Remember, the script will backup the following regardless of this file's contents:
+
+- mailcow directory (whatever directory contains *mailcow.conf*)
+- mailcow SQL database
+- the following mailcow volumes:
+  - vmail
+  - rspamd
+  - postfix
+  - redis
+  - crypt
+
+If you want to skip processing this file, simply comment-out the related configuration key in *backup.details*:
+
+```ini
+#borgXtraListPath=...
+```
+
+If you want to use a different file to list additional locations, simply update the entry in *backup.details* to point to that file. Bear in mind that the structure of that file must still be as indicated above:
+
+```ini
+borgXtraListPath='/path/to/your/xtraLocations.list'
+```
+
+### excludeLocations.borg
+
+This is a plain-text file containing **borg-specific** patterns describing what files you'd like ignored during the backup. These can be files within the default backup set and/or locations you have specified in your list of extra locations (e.g. *xtraLocations.borg*). To specify exclusions, list them one per line in this file. If you want to use a different file, simply update the entry in *backup.details*:
+
+```ini
+borgExcludeListPath='/path/to/your/exclusions.list'
+```
+
+You need to run *'borg help patterns'* for information on how to specify exclusion patterns since the format is not always standard shell format and only sometimes uses standard regex format.
+
+In most cases, this file will be skipped since you probably want to back everything up. The included sample file is already blank but you can explicitly skip exclusion processing to speed things up by commenting-out the relevant line in *backup.details* as follows:
+
+```ini
+#borgExcludeListPath=...
+```