Ansible Role: Restic

Beta: This role is currently in beta.

Description

Restic is a flexible backup solution written in Go. It can work with various backup types, remove duplicate data, and perform incremental backups.

This role installs Restic on a client, sets up backup locations, and can create systemd timers or cron jobs to automate backups. It also prepares scripts for manual backup runs.

This project is based on the work done in donat-b/ansible-restic and arillso/ansible.restic. Our aim is to simplify and modernize the role by using systemd timers, defining backup paths in /etc/crontab, and minimizing options (not tested with S3 or Windows).

Backup Scripts

This role generates a backup script and a credential file for each backup in the restic_script_dir. These scripts can be used manually to trigger backups, and are also utilized for scheduled backups if restic_create_schedule is set to true. Avoid manually editing these files, as it could affect your backups.

To run a backup manually on Linux, you would execute:

$ /path/to/backup/script/backup-example.sh

By default, backups will have the tag manual. You can add more tags like this:

$ /path/to/backup/script/backup-example.sh --tag deployment

CRON / Scheduled Tasks

You can configure backups to run automatically as scheduled tasks. Note that you need admin permissions on Linux to set this up.

If automatic task creation isn’t an option (like on a shared server using a web interface), use the generated scripts. Prefix the command with CRON=true to mark it as a scheduled task:

CRON=true /path/to/backup/script/backup-example.sh

Installation

You can install the role by cloning or downloading it from the GitHub repository, or by using Ansible Galaxy:

ansible-galaxy install roles-ansible.restic

Requirements

• bzip2

Role Variables

Repos

Restic uses repositories to store data. You need at least one repository defined. Repositories can be local or remote, as described in the official documentation.

Using an SFTP repository

For SFTP, ensure passwordless access is configured. Distributing SSH keys is beyond the role's scope.

Variables for Repositories

Example Repositories

restic_repos:
  local:
    location: /srv/restic-repo
    password: securepassword0
    init: true
  remote:
    location: rest:https://restic_rest_server.example.com:8000/restic-repo/
    password: securepassword1
    init: true
  sftp:
    location: sftp:user@host:/srv/restic-repo
    password: securepassword2
    init: true
  aws:
    location: s3:s3.amazonaws.com/bucket_name
    password: securepassword3
    init: true
    aws_access_key: accesskey
    aws_secret_access_key: secretaccesskey
    aws_default_region: eu-west-1
  azure:
    location: azure:container:/
    password: securepassword4
    init: true
    azure_account_name: storageaccountname
    azure_account_key: somekey # One of these is needed
    azure_account_sas: sasurl  # Optionally
    azure_endpoint_suffix: core.windows.net
  b2:
    location: b2:bucketname:path/to/repo
    password: securepassword5
    init: true
    b2_account_id: accountid
    b2_account_key: accountkey

Backups

A backup defines which directories or files to back up to the repositories specified in restic_repos.

Available Backup Variables

Example Backups

restic_backups:
  data:
    name: data
    repo: remote
    src: /path/to/data
    scheduled: true
    schedule_oncalendar: '*-*-* 01:00:00'
  database:
    name: database
    repo: remote
    stdin: true
    stdin_cmd: pg_dump -Ubackup db_name
    stdin_filename: db_name_dump.sql
    scheduled: true
    schedule_oncalendar: '*-*-* 01:30:00'
    niceness: 10
  all_databases:
    name: all_databases
    repo: remote
    src: /var/dumped_data
    scheduled: true
    schedule_oncalendar: '*-*-* 02:00:00'
    pre_backup_cmd: cd /var/dumped_data && mariadb -N -e 'show databases' | while read dbname; do mariadb-dump --complete-insert --routines --triggers --single-transaction "$dbname" > "$dbname".sql; done

restic_backups can also be specified as an array, which may be deprecated in future versions. Currently, the name key is used for identifying access and backup files.

Exclude

The exclude key allows specifying files to be excluded. You can use multiple exclusion keys:

exclude:
    exclude_caches: true
    exclude:
        - /path/to/file
    iexclude:
        - /path/to/file
    exclude_file:
        - /path/to/file
    exclude_if_present:
        - /path/to/file

Refer to the documentation for details.

Dependencies

This role does not have any other Ansible role dependencies.

Example Playbook

- name: Backup home directories to /mnt/backup every night
  hosts: localhost
  roles:
    - {role: do1jlr.restic, tags: restic}
  vars:
    restic_create_schedule: true
    restic_repos:
      local:
        location: '/mnt/backup'
        password: 'ChangM3'
        init: true
    restic_backups:
      home:
        name: home
        repo: local
        src: /home/
        scheduled: true
        schedule_oncalendar: '*-*-* 01:00:00'

License

This project is licensed under the MIT License. See the LICENSE file for full license text.