fiaasco.borgbackup

Borg Backup Role

This role installs Borg Backup on both backup servers and clients. It comes with a script called 'borg-backup' that makes it easier to use on the client side. You can use options like info, init, list, backup, and mount. If installed, Automysqlbackup will run before the backup process.

This role supports both self-hosted backups and offsite storage options like rsync.net and Hetzner Storage Box as your Borg server.

You can set up append-only repositories to protect the backups from being deleted by clients.

To use this role, you need Ansible version 2.9 or higher.

Required Variables

Create a group called borgbackup_servers in your inventory and add one or more hosts. The borgbackup_management group is only needed if you want to enable append-only mode and clean up backups from a secure host.

[borgbackup_servers]
backup1.fiaas.co

[borgbackup_management]
supersecurehost

Set the necessary details for your backup endpoints and how long to keep them:

borgbackup_servers:
  - id: fiaas
    fqdn: backup1.fiaas.co
    user: borgbackup
    type: normal
    home: /backup/
    pool: repos
    options: ""
  - id: rsync
    fqdn: yourhost.rsync.net
    user: userid
    type: rsync.net
    home: ""
    pool: repos
    options: "--remote-path=borg1"
  - id: hetzner
    fqdn: username.your-storagebox.de
    user: username
    type: hetzner
    home: ""
    pool: repos
    options: ""

borgbackup_retention:
  hourly: 12
  daily: 7
  weekly: 4
  monthly: 6
  yearly: 1

NOTE: The trailing / in item.home is necessary.

Set a Borg passphrase for each host:

host_vars:client1:
borgbackup_passphrase: Ahl9EiNohr5koosh1Wohs3Shoo3ooZ6p

By default, this role will create a cron job in /etc/cron.d/borg-backup that runs as root every day at a random hour between 0 and 5 am, at a random minute. You can change these defaults if needed:

borgbackup_client_user: root
borgbackup_cron_day: "*"
borgbackup_cron_minute: "{{ 59|random }}"
borgbackup_cron_hour: "{{ 5|random }}"

Override borgbackup_client_user if necessary, for example, if you want to run the backup as a different user.

To use append-only repositories, set borgbackup_appendonly: True in your host or group vars. You can also specify a management station in borgbackup_management_station that will be allowed to prune old backups. Only this management station can remove old backups from any client. This adds an extra layer of security.

Be aware of the limitations of append-only mode: pruned backups may seem removed, but they are only deleted from the transaction log until something writes to the repository in normal mode.

Check the default configurations for this role to see which locations are backed up in backup_include. Adjust as needed in your inventory.

Installing Borg from Package

You can install Borg from a package by setting the following variable:

borgbackup_install_from_pkg: true

On EPEL systems (like RedHat/CentOS), the epel-release repository will be added automatically using the geerlingguy.repo-epel role.

Usage

To configure Borg on the server and on a client, run:

ansible-playbook -i inventory/test backup.yml -l backup1.fiaas.co
ansible-playbook -i inventory/test backup.yml -l client1.fiaas.co

Testing

All role functionality is tested using Molecule with a local Docker connection to keep things simple. For more on Molecule testing, see https://molecule.readthedocs.io/en/latest/. Tests are written using Testinfra; more details can be found at https://testinfra.readthedocs.io/en/latest/.

You can run tests on any machine running a local Docker engine: (Make sure you are in the root directory of this role)

$ virtualenv -p python3 ~/.venv/fiaasco-borgbackup-docu
$ source ~/.venv/fiaasco-borgbackup-docu/bin/activate
$ pip3 install -r requirements.txt
$ molecule test

All functionalities should be tested thoroughly. If builds fail, they will not be approved in PR reviews! Each test scenario runs a complete setup with a backup server, performs a backup, and checks restoration along with other minor tests to ensure stability.

Test Scenarios

default

molecule test

This tests the common functionalities on Debian platforms using the two most recent official Debian releases.

centos

molecule test -s centos

This tests the common functionalities on EPEL platforms using the two latest official CentOS releases.

ubuntu

molecule test -s ubuntu

This tests the common functionalities on Ubuntu platforms using the two latest official Ubuntu releases.

multiple

molecule test -s multiple

This tests if the role works correctly when two or more backup servers are defined.

lamp

molecule test -s lamp

This tests functionality when the fiaas.lamp role is installed, ensuring compatibility with a Fiaas host. Check molecule.yml for more details.

clients

molecule test -s clients

This is the most comprehensive test scenario, covering all supported platforms and their combinations (e.g., Debian 8 + 9 + 10, Fedora 31, etc.). This scenario can be expanded as more systems and platforms are included.