5.6 KiB

Ansible Role: BorgBackup

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

Works great with - 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
  • Export borg repo keys to localhost
  • Optional: Setup SSH key and repository via API

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

Example playbook with Cron timer and repository enabled

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

- hosts: all
  - role: ansible-role-borgbackup
    borgbase: true
    borgbase_api_key: abcd1234
    borg_encryption_passphrase: CHANGEME
      - /var/www
      - echo "`date` - Starting backup."
      - name: users
        port: 5433

Example playbook with local repository

- hosts: all
  - role: ansible-role-borgbackup
    borg_encryption_passphrase: CHANGEME
      - path: /var/lib/backup
        label: local
      - /var/www
      - echo "`date` - Starting backup."
      - name: users


  • Clone latest version from Git:
    $ git clone roles/ansible_role_borgbackup
  • Optional: Add Andy Hawkins' BorgBase Collection to your requirements.txt:
      - 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_ssh_key_name: How to name your SSH key at 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


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

  host1: acbd1234
  host2: efgh5678

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


This role is based on Ansible Role: BorgBackup Client.