Borg wrapper

I don't recommend relying on this script in production yet. Or, at least, frequently review and verify your backups.

https://www.borgbackup.org/

Borg documentation: https://borgbackup.readthedocs.io/en/stable/

Setup

• Download and extract the latest release
• Copy the sample.config directory to config
• Edit config/borg.env and add your config options
• Add a secure passphrase to the first line of the borg_passphrase file
• Edit exclude.txt and include.txt with your requirements. One entry per line
• From the root of the repo, run ./borg-wrapper.sh --init to initialize the repo
• IMPORTANT: Back up your passphrase and the keyfile generated by Borg. Without these two, you will not be able to access your backups
• Use crontab (or the scheduler of your choice) to run ./borg-wrapper.sh --backup --automated --live periodically. See crontab_example for an example configuration
• If you need to run multiple profiles, you can use the --config option to specify a different config directory

See src/help.sh for all command line options.

env file

Comment out or remove an option to use its default.

Required options

Option	Description
TARGET_DIRECTORY	Full path to the backup target directory Local or remote The directory must be empty Directory will be created if it does not exist The parent directory must exist

Required when REMOTE=true

Option	Description
REMOTE_DOMAIN	FQDN or IP of the Borg backup server/target
REMOTE_SSH_PRIVKEY	Full path to the private SSH key used to log in to REMOTE_DOMAIN. Cannot be password protected
REMOTE_USER	Username to log in to REMOTE_DOMAIN

Required when WEBHOOK_ENABLED=true

Option	Description
WEBHOOK_URL	Your webhook URL

Optional options

These options are optional. If not set, the default will be used.

Option	Default	Description
BACKUP_PASSPHRASE_FILE	configDirectory/ borg_passphrase	Full path to the file containing the passphrase. **Make sure you protect and back up this file**
BACKUP_PREFIX	hostname-	Backup name prefix
COMPACT_ON_BACKUP	true	Run compact after every backup
EXCLUDE_FILE	configDirectory/ exclude.txt	Full path to the file with a list of paths to exclude in the backup
INCLUDE_FILE	configDirectory/ include.txt	Full path to the file with a list of paths to include in the backup
KEEP_DAILY	7	Keep this many daily backups
KEEP_HOURLY	2	Keep this many hourly backups
KEEP_MONTHLY	12	Keep this many monthly backups
KEEP_WEEKLY	4	Keep this many weekly backups
KEEP_WITHIN	24H	Keep all backups in this period
KEEP_YEARLY	-1 (infinitely)	Keep this many yearly backups
KEYFILE	configDirectory/ keyfile	Full path to the keyfile to encrypt backups with. The file cannot exist; Borg generates it. **Make sure you protect and back up this file**
KEYFILE_IN_REPO	false	Store the backup keyfile unencrypted in the backup repo
LOG_FILE	configDirectory/ borg.log	Full path to the script log file
ONE_FILE_SYSTEM	true	Set to true to exclude mounted file systems from backup
PRUNE_ON_BACKUP	true	Run prune after every backup
REMOTE_PORT	22	Port to connect to REMOTE_DOMAIN
REMOTE	false	Back up to a remote target over SSH
WEBHOOK_ENABLED	false	Enable logging to webhook
WEBHOOK_VERBOSE	true	More verbose webhook logging. Set to false to only send a single message at the end of a successful operation. Only affects --backup and --init

Webhook logging

This is developed for use with Matrix-Hookshot generic webhooks. Add the Transformation JavaScript from hookshot_webhook_js_transformation.js to enable @room mentions for errors. Make sure you give the webhook appservice user permissions to @room. However, this should work with any webhook reader that accepts unauthenticated PUT JSON requests with the key text. To edit the behavior, edit the webhook function in src/utils.js to fit your needs.

Mac

On Mac, you must give cron full disk access.

• In the terminal, enter open /usr/sbin
• Go to System Settings -> Privacy & Security -> Full Disk Access
• From Finder, drag cron into the Full Disk Access window