Ansible role to set up Borg and Borgmatic
Go to file
Frank Dornheim dd960dcf4e
Restructure role, add Systemd timer option. By @conloos (#112)
* add full path

* Update Readme.me: reorder optional Arguments, update cron -> systemd timer

* remove ssh_key_file; change cron to timer

* Removed cronie from package installation because systemd timer is used

* docker.sh - Stops all or selected containers to save the persistent data intact. The containers are started in reverse order

* Created arguments_specs.yml

* Role restructured:
  - if needed creation of a service user incl. creation of the ssh-key,
  - add the ssh key to authorized_keys,
  - auto init of the repos,
  - creation and start of systemd timer and services and
  - installation of the Docker helperscript.

* restructure role add import logic

* cleanup: user backup_user

* - "borg_source_directories" is not longer a required Argument
- add "borg_keys_directory" to load key from Service user during starting borgmatic by sudo

* Add borgmatic_initialization_repo (bool) as option to disable init of repo

* cleanup

* fix ansible-lint errors and warnings

* fix letter turner

* add option: borgmatic_timer

* add:
  - borgmatic_timer_systemd: true
readd:
  - borgmatic_cron_name: "borgmatic"

* - renamed borgmatic_cron_name to borgmatic_timer_cron_name to be more convergent.
- Change recommendations implemented by m3nu so that creation of a timer (systemd or cron) is optional and can be selected via borgmatic_timer.

* Add description to borgmatic_timer_cron_name and borgmatic_timer

* Add variable borg_cron_package to install the cron-packages in case of using timer: cron

* reworked timer install logic

* reworked timer install logic

* Add comments for running backup with service account

* add new parameters for tests

* Switch created to perform the backup as root or service account. If a service account is to be used, it will be created.

* Refactored: Check for ssh-key if not present, genereate them.

* Refactored

* Refactored

* renamed tasks/03_configure.yml to tasks/04_create_links_to_borg_and_borgmatic.yml

* Refactored

* Refactored

* add example for service account

* Update Python version for testing

* No auto init

* Add description to install_backup

* Add description to install_backup

* set coverage back to: m3nu.ansible_role_borgbackup

* The initialization of the repository must be activated and does not take place automatically.

* The initialization of the repository must be activated and does not take place automatically.

* Removed install_backup as var (bool) to prevent that this role run

* Rename backup_ssh_command to borg_ssh_command, tis was a double definition

* Renamed backup_repository to borg_repository and add better explanations

* remove copy ssh-keys and cert parts

* Add comments to borg_ssh_key_file and borg_ssh_key_type

* Set allways the borg_ssh_key_file and borg_ssh_command to load the right ssh-key. Add borg_ssh_key_type to select the key type by user

* Add borg_ssh_key_type

* renamed id_rsa to backup

* generate ssh-keys (backup and backup.pub) and add better explanation

* Print out key if borgmatic_initialization_repo is false

* Remove 'su - {{ borgbackup_user }} -c' to execute the borgmatic by the right user

* Add Check frequency, therefore, we no longer need to distinguish between normal and large repos

* Add link to Article

* renamed backup_ssh_command and backup_ssh_key_file to borg_ssh_command and borg_ssh_key_file

* Removed: borgmatic_initialization_repo

* Removed: borgmatic_initialization_repo

* Removed: borgmatic_initialization_repo

* revert changes

* Add Full Automation

* polishing

* rename backup.timer and bakup.service to borgmatic.timer and borgmatic.service

* remove debug

* Try to find services in ansible_facts

* Forgot to install Cron

* change borg_ssh_key_type to ed25519

* remove conditional checks

* - add hint to using a service user
- renamed: borg_ssh_key_file to borg_ssh_key_file_path
- removed advanced example

* add borg_ssh_key_name, renamed borg_ssh_key_file to borg_ssh_key_file_path

* removed static pointing to ~/.ssh/backup SSH private key

* Add README-Advanced-Examples.md for storing more examples

* Fix test idempotence

* Dont symlink when using distro packages

* Remove old test targets, consistent wording, remove tag

* Remove helper scripts, fix absolute path

* Fix cron job, add assert to prevent duplicate timers

* nit-pick

* Create bin links as root, no borg_ssh_command by default.

* Add breaking changes note to README

---------

Co-authored-by: Manu <manu@snapdragon.cc>
2023-03-28 18:01:12 +01:00
.github/workflows Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
defaults Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
meta Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
molecule/default Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
tasks Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
templates Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
vars Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
.ansible-lint Remove borgbase module, now separate (#100) 2022-05-13 11:17:47 +04:00
.gitignore Remove borgbase module, now separate (#100) 2022-05-13 11:17:47 +04:00
.yamllint Add Manjaro support (by @verbumfeit), CI fixes. (#65) 2021-04-20 14:53:35 +08:00
EXAMPLES.md Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
LICENSE initial commit 2018-10-06 20:04:20 +08:00
README.md Restructure role, add Systemd timer option. By @conloos (#112) 2023-03-28 18:01:12 +01:00
requirements-dev.txt Add Manjaro support (by @verbumfeit), CI fixes. (#65) 2021-04-20 14:53:35 +08:00

Ansible Role: BorgBackup Client

Test Ansible Galaxy

Set up encrypted, compressed and deduplicated backups using BorgBackup and Borgmatic. Currently supports Debian/Ubuntu, CentOS/Red Hat/Fedora, Archlinux and Manjaro.

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 PyPi or distro packages
  • Set up Borgmatic config
  • Schedule regular backups using Cron or Systemd timer

Breaking changes

  • Older versions of this role set up a separate Cron job for creating and checking backups. With recent Borgmatic version, this feature is now managed in Borgmatic. As a result the extra Cron job will be removed by this role.
  • Older versions of this role only supported Cron for scheduling. If you use Systemd timers, be sure to remove the Cron job in /etc/cron.d/borgmatic first. The role will also alert you when trying to use both timers.

Example playbook with root as backup user and Cron timer

- hosts: all
  roles:
  - role: m3nu.ansible_role_borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository: ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo
    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 service user and Systemd timer

- hosts: all
  roles:
  - role: m3nu.ansible_role_borgbackup
    borg_encryption_passphrase: CHANGEME
    borg_repository: ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo
    borgmatic_timer: systemd
    borg_user: "backupuser"
    borg_group: "backupuser"
    borg_source_directories:
      - /var/www
    borg_retention_policy:
      keep_hourly: 3
      keep_daily: 7
      keep_weekly: 4
      keep_monthly: 6

Installation

Download from Ansible Galaxy

$ ansible-galaxy install m3nu.ansible_role_borgbackup

Clone latest version from Github

$ git clone https://github.com/borgbase/ansible-role-borgbackup.git roles/ansible_role_borgbackup

Role Variables

Required Variables

  • borg_repository: Full path to repository. Your own server or BorgBase.com repo. Can be a list if you want to backup to multiple repositories.

Optional Variables

  • borg_dep_packages: Dependency Packages to install borg(backup) and borgmatic.

  • borg_distro_packages: contains the names of distributions packages for borg(backup) and borgmatic, only used if borg_install_method is set to package.

  • 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_install_method: By default pip is used to install borgmatic. To install via your distributions package manager set this to package and (if needed) overwrite the borg_distro_packages variable to contain your distributions package names required to install borgmatic. Note that many distributions ship outdated versions of borgbackup and borgmatic; use at your own risk.

  • 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_pip_packages: Dependancy Packages (pip) to install borg(backup) and borgmatic.

  • 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_version: Force a specific borg version to be installed

  • borg_venv_path: Path to store the venv for borg(backup) and borgmatic

  • 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_timer: If the variable is set, a timer is installed. A choice must be made between cron and systemd.

  • 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

  • borg_user: Name of the User to create Backups (service account)

  • borg_group: Name of the Group to create Backups (service account)

Contributing

Pull requests (PR) are welcome, as long as they add features that are relevant for a meaningful number of users. All PRs are tested for style and functionality. To run tests locally (needs Docker):

$ pip install -r requirements-dev.txt
$ molecule test

License

MIT/BSD

Author

© 2018-2023 Manuel Riel and contributors.