Ansible Role: BorgBackup

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

Works with BorgBase.com and Hetzner StorageBox. 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 completion
• Optional (borgbase): Setup borgbase.com SSH key and repository via API
• Optional (hetzner): import ssh (sub-accounts are supported)

The Debian packages contains a systemd timer for running borgmatic every day between 0:00 and 3:00.

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 Hetzner StorageBox repository

The ssh "sub-account" feature provided by Hetzner is supported. See u12345-sub123 in username and hostname.

- hosts: all
  roles:
  - role: ansible-role-borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository:
      - path: "ssh://u12345-sub123@u12345-sub123.your-storagebox.de:23/./borg"
        label: storagebox
    borg_source_directories:
      - /var/www

By default the ssh sub-account is supposed to assigned to a directory whose name matches {{ inventory_hostname }} of the host using this sub-account as a backup storage. You may override this assumption by providing the borg_storagebox_sub_account_path variable.

Installation

• Clone latest version from Git:

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

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 private 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. Defaults 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_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

Hetzner StorageBox Variables

• borg_storagebox_sub_account_path: path assigned to an ssh sub-account (default: {{ inventory_hostname }})

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.