Ansible Role: BorgBackup Client

Set up encrypted, compressed and deduplicated backups using BorgBackup and Borgmatic. Currently supports Debian/Ubuntu, CentOS/Red Hat/Fedora, Archlinux and Manjaro.

Works great with BorgBase.com - Simple and Secure Hosting for your Borg Repositories. To manage BorgBase repos via Ansible, also see Andy Hawkins' BorgBase Collection.

Main features

• Install Borg and Borgmatic from PyPi or distro packages
• Set up Borgmatic config
• Schedule regular backups using Cron or Systemd timer

Breaking changes

• Older versions of this role set up a separate Cron job for creating and checking backups. With recent Borgmatic version, this feature is now managed in Borgmatic. As a result the extra Cron job will be removed by this role.
• Older versions of this role only supported Cron for scheduling. If you use Systemd timers, be sure to remove the Cron job in /etc/cron.d/borgmatic first. The role will also alert you when trying to use both timers.

Example playbook with root as backup user and Cron timer

- hosts: all
  roles:
  - role: borgbase.ansible_role_borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository:
      - ssh://xxxxxx@xxxxxx.repo.borgbase.com/./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://xxxxxx@xxxxxx.repo.borgbase.com/./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

Example playbook using Docker

- hosts: all
  roles:
    - role: borgbase.ansible_role_borgbackup
      borg_install_method: docker
      borgmatic_timer: cron
      borg_repository: ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo
      borg_encryption_passphrase: CHANGEME
      borg_source_directories:
        - /var/www
      borg_ssh_private_key: !vault |
                $ANSIBLE_VAULT;1.1;AES256
                65373636303732303236313234666230386333636233313631663135323734626265616532633064
                316334...truncated

Installation

Download from Ansible Galaxy

$ ansible-galaxy install borgbase.ansible_role_borgbackup

Clone 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 repository. Your own server or BorgBase.com repo. Can be a list if you want to backup to multiple repositories.

Optional Variables

• borg_dep_packages: Dependency Packages to install borg(backup) and borgmatic.

• borg_distro_packages: contains the names of distributions packages for borg(backup) and borgmatic, only used if borg_install_method is set to package.

• borg_encryption_passcommand: The standard output of this command is used to unlock the encryption key.

• borg_encryption_passphrase: Password to use for repokey or keyfile. Empty if repo is unencrypted.

• borg_exclude_from: Read exclude patterns from one or more separate named files, one pattern per line.

• borg_exclude_patterns: Paths or patterns to exclude from backup. See official documentation for more.

• borg_install_method: By default pip is used to install borgmatic. To install via your distributions package manager set this to package and (if needed) overwrite the borg_distro_packages variable to contain your distributions package names required to install borgmatic. Note that many distributions ship outdated versions of borgbackup and borgmatic; use at your own risk. To install via a Docker container, set this to "docker". Docker must be installed on target host.

• borg_require_epel: When using borg_install_method: package on RHEL-based distributions, the EPEL repo is required. To disable the check (e.g. when using a custom mirror instead of the epel-release package), set this to false. Defaults to {{ ansible_os_family == 'RedHat' and ansible_distribution != 'Fedora' }} (i.e. true on Enterprise Linux-based distros).

• borg_lock_wait_time: Config maximum seconds to wait for acquiring a repository/cache lock. Defaults to 5 seconds.

• borg_one_file_system: Don't cross file-system boundaries. Defaults to true

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

• borg_remote_path: Path to the borg executable on the remote. It will default to borg.

• borg_remote_rate_limit: Remote network upload rate limit in kiBytes/second.

• borg_retention_policy: Retention policy for how many backups to keep in each category (daily, weekly, monthly, etc).

• borg_source_directories: List of local folders to back up. Default is /etc/hostname to prevent an empty backup.

• borg_ssh_key_name: Name of the SSH public and pivate key. Default id_ed25519

• borg_ssh_key_file_path: SSH-key to be used. Default ~/.ssh/{{ borg_ssh_key_name }}

• borg_ssh_key_type: The algorithm used to generate the SSH private key. Choose: rsa, dsa, rsa1, ecdsa, ed25519. Default: ed25519

• borg_ssh_private_key: Content of the ssh private key, may you want to provide it. Only keys without passphrase is supported. Most useful for Docker deployments. IMPORTANT! Be sure to provide the content of this variable via an Ansible Vault.

• borg_ssh_command: Command to use instead of just "ssh". This can be used to specify SSH options.

• borg_version: Force a specific borg version to be installed

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

• borgmatic_check_last: Number of archives to check. Defaults to 3

• borgmatic_checks: List of consistency checks. Defaults to monthly checks. See docs for all options.

• borgmatic_config_name: Name to use for the Borgmatic config file. Defaults to config.yaml

• borgmatic_timer_hour: Hour when regular create and prune cron/systemd-timer job will run. Defaults to {{ 6 | random }}

• borgmatic_timer_minute: Minute when regular create and prune cron/systemd-timer job will run. Defaults to {{ 59 | random }}

• borgmatic_hooks: Hooks to monitor your backups e.g. with Healthchecks. See official documentation for more.

• borgmatic_timer: If the variable is set, a timer is installed. A choice must be made between cron and systemd.

• borgmatic_relocated_repo_access_is_ok: Bypass Borg error about a repository that has been moved. Defaults to false

• borgmatic_store_atime: Store atime into archive. Defaults to true

• borgmatic_store_ctime: Store ctime into archive. Defaults to true

• borgmatic_version: Force a specific borgmatic version to be installed

• borg_user: Name of the User to create Backups (service account). When using Docker, must be root.

• borg_group: Name of the Group to create Backups (service account). When using Docker, must be root.

• borgmatic_docker_image_name: When using borg_install_method=docker, name docker image to build. Defaults to ansible_borgmatic

• borgmatic_docker_container_name: When using borg_install_method=docker, name of the docker container. Defaults to ansible_borgmatic

• borgmatic_docker_timezone: Timezone to use when using borg_install_method=docker. Defaults to UTC

Contributing

Pull requests (PR) are welcome, as long as they add features that are relevant for a meaningful number of users. All PRs are tested for style and functionality. To run tests locally (needs Docker):

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

License

MIT/BSD

Author

© 2018-2023 Manuel Riel and contributors.