Ansible Role: BorgBackup

Set up encrypted, compressed and deduplicated backups using BorgBackup and Borgmatic.

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 Debian package repositories
• Set up Borgmatic config and bash completition
• Schedule regular backups using Cron
• Export borg repo keys to localhost
• Optional: Setup borgbase.com SSH key and repository via API

Example playbook with Cron timer and borgbase.com repository enabled

No need to configure the variable borg_repository. It's evaluated via borgbase API call.

- hosts: all
  roles:
  - role: ansible-role-borgbackup
    borgbase: true
    borgbase_api_key: abcd1234
    borg_encryption_passphrase: CHANGEME
    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 local repository

- hosts: all
  roles:
  - role: ansible-role-borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository:
      - path: /var/lib/backup
        label: local
    borg_source_directories:
      - /var/www
    borgmatic_hooks:
      before_backup:
      - echo "`date` - Starting backup."
      postgresql_databases:
      - name: users
        hostname: database1.example.org

Installation

• Clone latest version from Git:

  $ git clone https://git.systemausfall.org/senselab/ansible-role-borgbackup.git roles/ansible_role_borgbackup
  

• Optional: Add Andy Hawkins' BorgBase Collection to your requirements.txt:

  collections:
    - name: adhawkins.borgbase
  

Role Variables

Required Variables

• borg_repository.path: Full path to repository.
• borg_repository.label: A label for this repository.

Optional Variables

Borg Variables

• 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_key_export_path: Path to save borg key backups.
• 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_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_command: Command to use instead of just "ssh". This can be used to specify SSH options.
• borg_user: Name of the User to create Backups. Defeaults to root.
• borg_group: Name of the Group to create Backups. Defaults to root.
• borg_user_ssh_config_path: Path of you SSH config file. Defaults to /root/.ssh/config.

Borgbase Variables

• borgbase_api_key: API key to interact with borgbase.com`
• borgbase_ssh_key_name: How to name your SSH key at borgbase.com. Default to backup_{{ inventory_hostname }}.

Borgmatic variables

• 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_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

Security

You can create a dictionary for borg_encryption_passphrase in an Ansible vault file:

borg_backup_passphrases:
  host1: acbd1234
  host2: efgh5678

Additionally you have to define borg_encryption_passphrase: "{{ borg_backup_passphrases[inventory_hostname] }}" in your group_vars.

Credits

This role is based on Ansible Role: BorgBackup Client.