Ansible Role: BorgBackup Client

This role helps you set up backups that are encrypted, compressed, and deduplicated using BorgBackup and Borgmatic. It currently works with Debian/Ubuntu, CentOS/Red Hat/Fedora, Archlinux, and Manjaro.

It works well with BorgBase.com - a simple and secure place to host your Borg repositories. For managing BorgBase repositories with Ansible, check out Andy Hawkins' BorgBase Collection.

Main Features

• Install Borg and Borgmatic from PyPi or your package manager
• Set up Borgmatic configuration
• Schedule regular backups with Cron or Systemd timer

Breaking Changes

• Previous versions created a separate Cron job for backup tasks. Recent Borgmatic versions handle this within Borgmatic. The separate Cron job will now be removed by this role.
• Earlier versions only supported Cron for scheduling. If you want to use Systemd timers, please delete the Cron job in /etc/cron.d/borgmatic first. The role will notify you if both timers are in use.

Example Playbook with Root User and Cron Timer

- hosts: all
  roles:
  - role: borgbase.ansible_role_borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository:
      - ssh://[email protected]/./repo
    borg_source_directories:
      - /var/www
    borgmatic_hooks:
      before_backup:
      - echo "`date` - Starting backup."
      postgresql_databases:
      - name: users
        hostname: database1.example.org
        port: 5433

Example Playbook with Service User and Systemd Timer

- hosts: all
  roles:
  - role: borgbase.ansible_role_borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository: ssh://[email protected]/./repo
    borgmatic_timer: systemd
    borg_user: "backupuser"
    borg_group: "backupuser"
    borg_source_directories:
      - /var/www
    borg_retention_policy:
      keep_hourly: 3
      keep_daily: 7
      keep_weekly: 4
      keep_monthly: 6

Installation

You can install it from Ansible Galaxy:

$ ansible-galaxy install borgbase.ansible_role_borgbackup

Or clone the latest version from GitHub:

$ git clone https://github.com/borgbase/ansible-role-borgbackup.git roles/ansible_role_borgbackup

Role Variables

Required Variables

• borg_repository: Full path to the repository, either on your own server or on BorgBase.com. It can be a list for multiple repositories.

Optional Variables

• borg_dep_packages: Additional packages to install borg(backup) and borgmatic.

• borg_distro_packages: Names of distribution packages for borg(backup) and borgmatic, used if borg_install_method is set to package.

• borg_encryption_passcommand: Command's output used to unlock the encryption key.

• borg_encryption_passphrase: Password for repokey or keyfile; leave empty if not encrypted.

• borg_exclude_from: Read exclude patterns from specific files, one pattern per line.

• borg_exclude_patterns: Paths or patterns to exclude from backup; check documentation for details.

• borg_install_method: Use pip for installation by default; set to package to use your package manager.

• borg_require_epel: Required EPEL repo for RHEL-based distributions when using package installation. Set to false to skip the check.

• borg_lock_wait_time: Maximum wait time for acquiring a lock (default is 5 seconds).

• borg_one_file_system: Avoid crossing file-system boundaries (default: true).

• borg_pip_packages: Packages (pip) to install borg(backup) and borgmatic.

• borg_remote_path: Path to the borg executable on the remote server (default: borg).

• borg_remote_rate_limit: Upload rate limit in kiBytes/second.

• borg_retention_policy: Policy determining how many backups to keep.

• borg_source_directories: List of local folders to back up (default is /etc/hostname).

• borg_ssh_key_name: Name of the SSH public/private key (default: id_ed25519).

• borg_ssh_key_file_path: Path to the SSH key (default: ~/.ssh/{{ borg_ssh_key_name }}).

• borg_ssh_key_type: SSH private key generation algorithm choices (default: ed25519).

• borg_ssh_command: Custom SSH command with options if needed.

• borg_version: Force installation of a specific borg version.

• borg_venv_path: Path to save the venv for borg(backup) and borgmatic.

• borgmatic_check_last: Number of archives to check (default: 3).

• borgmatic_checks: Frequency of consistency checks (default: monthly).

• borgmatic_config_name: Name of the Borgmatic config file (default: config.yaml).

• borgmatic_timer_hour: Hour for the cron/systemd timer job (default: random hour).

• borgmatic_timer_minute: Minute for the cron/systemd timer job (default: random minute).

• borgmatic_hooks: Hooks for monitoring backups.

• borgmatic_timer: Choose between cron or systemd for the timer.

• borgmatic_relocated_repo_access_is_ok: Bypass error for moved repositories (default: false).

• borgmatic_store_atime: Store atime in the archive (default: true).

• borgmatic_store_ctime: Store ctime in the archive (default: true).

• borgmatic_version: Force installation of a specific borgmatic version.

• borg_user: Username for creating backups (service account).

• borg_group: Group name for creating backups (service account).

Contributing

You are welcome to submit pull requests (PR) that add relevant features. All PRs will be tested for style and functionality. To test locally (requires Docker):

$ pip install -r requirements-dev.txt
$ molecule test

License

MIT/BSD

Author

© 2018-2023 Manuel Riel and contributors.