papanito.borg

Ansible Role "papanito.borg"

This Ansible role sets up regular backups using Borg. It does the following:

[Optional] Delete any existing backup repository.
Initialize a repository at protocol://backup_server:target_dir or just target_dir.

Notes

If the repository at target_dir already exists, it won't be initialized again. If you don't specify backup_server, it assumes you want to back up to a local directory.
Create a systemd service that runs a backup script borg.sh from borgbackup.org on a schedule defined by backup_schedule.
A custom borg-script named automatic-backup-{{service_name}}.sh will be placed in /opt/borg_backup and will include:
- backup_source_dir
- backup_exclude_file or backup_exclude_list
- backup_schedule

Requirements

None

Role Variables

Here are all the variables you can use:

Parameter	Description	Default Value
`backup_server`	Name of the backup server (assumes local backup if not defined).	-
`backup_user`	Name of the user for server connection.	-
`backup_port`	Port to use for connecting to `backup_server`.	-
`protocol`	Protocol to connect to the `backup_server`.	`ssh`
`backup_name`	[Required] Name of the backup.	-
`backup_encryption_key`	[Required] Passphrase for the encryption key using `repokey`.	-
`backup_encryption_method`	Borg encryption method, currently only `repokey` is supported.	`repokey`
`target_dir`	Directory where backups will be stored on the `backup_server`.	`"./backups/{{ backup_name }}"`
`backup_delete`	WARNING If set to `true`, existing backup repository will be deleted.	`false`
`backup_create`	Use the role to delete an existing repository by running with `-e backup_delete=true -e backup_create=false`.	`true`
`backup_schedule`	Schedule notation for the daily backup.	`--* 03:00:00`
`backup_include_list`	List of directories to back up.	-
`backup_exclude_file`	`EXCLUDEFILE` containing exclude patterns. Takes precedence over `backup_exclude_list`.	-
`backup_exclude_list`	List of patterns to exclude from backup.	-

Here are parameters related to the systemd service file:

Parameter	Description	Default Value
`systemd_target_dir`	Location for copying `.service` files	`/etc/systemd/system/`
`borg_systemd_user`	User for the `systemd` service	`backup`
`borg_systemd_group`	Group for the `systemd` service	`backup`
`borg_systemd_on_failure`	If specified, an [OnFailure] entry will be added to the service file.	`-`
`systemd_script_mode`	File permission for the script	`0774`
`systemd_service_mode`	File permission for the service file	`0644`

The deployed script also sets options for prune as described at borg prune. If a value is expected to be a number but isn't defined, that option won't be included.

Parameter	Description	Default Value
`backup_prune_dryrun`	`-n, --dry-run` do not change the repository	`false`
`backup_prune_force`	`--force` prune corrupted archives	`false`
`backup_prune_stats`	`-s, --stats` show statistics for deleted archives	`true`
`backup_prune_list`	`--list` output a list of kept/pruned archives	`true`
`backup_prune_keep_within`	`--keep-within INTERVAL` keep all archives within this period	-
`backup_prune_keep_last`	`--keep-last` number of recently kept archives	-
`backup_prune_keep_minutely`	`--keep-minutely` number of minutely kept archives	-
`backup_prune_keep_hourly`	`-H, --keep-hourly` number of hourly kept archives	-
`backup_prune_keep_daily`	`-d, --keep-daily` number of daily kept archives	-
`backup_prune_keep_weekly`	`-w, --keep-weekly` number of weekly kept archives	-
`backup_prune_keep_monthly`	`-m, --keep-monthly` number of monthly kept archives	-
`backup_prune_keep_yearly`	`-y, --keep-yearly` number of yearly kept archives	-
`backup_prune_save_space`	`--save-space` work slower but use less space	`false`

To hide sensitive information, use ansible-vault. You can set up a password file in ansible.cfg, so you won't need to specify vault parameters. To create an encrypted variable for backup_encryption_key, use:

ansible-vault encrypt_string 'SupersecretPa$$phrase' --name 'backup_encryption_key'

Dependencies

None

Examples

Example Playbook for Remote Backup

Below is an example of using this role with specified variables:

- hosts: localhost
  vars:
  - backup_server: borg.intra
  - backup_user: borguser
  - backup_name: mybackupname
  - backup_encryption_key: test
  - backup_port: 23
  - target_dir: "/var/backups/"
  - backup_schedule: "*-*-* 03:00:00"
  - backup_exclude_list:
    - "*/Downloads"
    - "*/google-chrome*"
  - backup_include_list:
    - /home/papanito
  - backup_prune_keep_daily: 7
  - backup_prune_keep_weekly: 5
  - backup_prune_keep_monthly: 6
  - backup_prune_keep_yearly: 1
  
  roles:
  - role: papanito.borg

This will create a backup at ssh://[email protected]:/var/backup/mybackupname and create the following systemd files:

/opt/borg_backup/automatic-backup-mybackupname-borg.intra.sh (backup script)
/etc/systemd/system/automatic-backup-mybackupname-borg.intra.service (systemd service file)
/etc/systemd/system/automatic-backup-mybackupname-borg.intra.timer (systemd timer file)

Example Playbook for Local Backup

Here’s another example for a local backup setup:

- hosts: localhost
  vars:
  - backup_name: mybackupname
  - backup_encryption_key: test
  - target_dir: "/var/backup/"
  - backup_schedule: "*-*-* 03:00:00"
  - backup_exclude_list:
    - "*/Downloads"
    - "*/google-chrome*"
  - backup_include_list:
    - /home/papanito
  - backup_prune_keep_daily: 7
  - backup_prune_keep_weekly: 5
  - backup_prune_keep_monthly: 6
  - backup_prune_keep_yearly: 1

This will create a backup at /var/backup/mybackupname and the following systemd files:

/opt/borg_backups/automatic-backup-mybackupname-local.sh (backup script)
/etc/systemd/system/automatic-backup-mybackupname-local.service (systemd service file)
/etc/systemd/system/automatic-backup-mybackupname-local.timer (systemd timer file)