kalos / ansible-restic

Deploy restic backup program

Ansible Role: restic

Description

Deploy restic - fast, secure, efficient backup program.

Requirements

• Ansible >= 2.8
• bzip2 installed on deployer machine (same one where ansible is installed)

Role Variables

All variables which can be overridden are stored in defaults/main.yml file as well as in table below.

Name	Default Value	Description
restic_version	0.10.0	restic package version. Also accepts latest as parameter.
restic_user	"root"	system user to run restic
restic_group	"root"	system group to run restic
restic_shell	"/bin/false"	the shell for the restic user, change this if you want to be able to su to it
restic_install_path	"/usr/local/bin"	directory where restic binary will be installed
restic_cache_path	"/var/cache/restic"	directory where restic keeps a cache with some files from the repository on the local machine
restic_cron_mailto	restic_user	who to mail results of the restic crons to, set to "" to not mail
restic_cron_stdout_file	null	what file to log restic output to, null means include in mailto, use /dev/null to discard
restic_cron_stderr_file	null	what file to log restic errors to, null means include in mailto, use /dev/null to discard
restic_sudo_command_whitelist	[]	whitelist of commands restic is allowed to run with sudo
restic_includes_files	[]	include list from file, instead use multiple FILE/DIR arguments in command
restic_excludes_files	[]	exclude list from file, instead use multiple --exclude FILE/DIR arguments in restic command
restic_repos	[]	restic repositories, cron jobs and systemd configuration. More in defaults/main.yml

Security

To ensure high security this role can allow restic to be run as different user than root and still allowing read-only access to files. This is implemented by following PR#1483 from restic repository.

If you need to run certain tools as another user, make sure to list those in restic_sudo_command_whitelist as follows:

restic_sudo_command_whitelist:
   - command: /usr/bin/some_backup_related_command_that_needs_sudo
     runas: root

Then, in your actual backup command, add the command as sudo -u root /usr/bin/some_backup_related_command_that_needs_sudo.

Helpers

This role also installs helper scripts to restic_install_path. These scripts are named after your repository and will ensure environment variables are correct for that repository.

For example, if you have a restic repository named testrepo, you could use the restic-testrepo command, which will execute restic with the correct environment variables to manipulate that repository.

Systemd service and timer

This role supports both cron and systemd. Just set the right variables in restic_repos (defaults/main.yml).

Example

Playbook

Use it in a playbook as follows:

- hosts: all
  roles:
    - paulfantom.restic

Local Testing

The preferred way of locally testing the role is to use Docker and molecule (v3.x). You will have to install Docker on your system. See Get started for a Docker package suitable to for your system. All packages you need to can be specified in one line:

pip install -rtest-requirements.txt

This should be similar to one listed in .travis.yml file in install section. After installing test suit you can run test by running

molecule test

For more information about molecule go to their docs.

Travis CI

Combining molecule and travis CI allows to test how new PRs will behave when used with multiple ansible versions and multiple operating systems. This also allows to create test scenarios for different role configurations. As a result test matrix is quite large and takes more time than local testing, so please be patient.

Contributing

See contributor guideline.

License

This project is licensed under MIT License. See LICENSE for more details.