Ansible role to set up Borg and Borgmatic
8429ec5bc1
* Move common Python packages to main.yml, install dependent Python packages first. |
||
---|---|---|
.github/workflows | ||
defaults | ||
library | ||
meta | ||
module_utils | ||
molecule/default | ||
tasks | ||
templates | ||
vars | ||
.yamllint | ||
LICENSE | ||
README.md | ||
requirements-dev.txt |
Ansible Role: BorgBackup Client
Set up encrypted, compressed and deduplicated backups using BorgBackup and Borgmatic. Currently supports Debian/Ubuntu and CentOS/Red Hat.
Works great with BorgBase.com - Simple and Secure Hosting for your Borg Repositories.
Main features:
- Set up Borg and Borgmatic
- Add cron job at random time
- Provision new remote BorgBase.com repo for storing backups (optional)
Example Playbook
- hosts: webservers
roles:
- role: m3nu.ansible_role_borgbackup
borg_encryption_passphrase: CHANGEME
borg_repository: m5vz9gp4@m5vz9gp4.repo.borgbase.com:repo
borg_source_directories:
- /srv/www
- /var/lib/automysqlbackup
borg_exclude_patterns:
- /srv/www/old-sites
borg_retention_policy:
keep_hourly: 3
keep_daily: 7
keep_weekly: 4
keep_monthly: 6
borgmatic_hooks:
before_backup:
- echo "`date` - Starting backup."
postgresql_databases:
- name: users
hostname: database1.example.org
port: 5433
Installation
Download from Ansible Galaxy
$ ansible-galaxy install m3nu.ansible_role_borgbackup
Clone to local folder
$ git clone https://github.com/borgbase/ansible-role-borgbackup.git roles/ansible_role_borgbackup
Role Variables
Required Arguments
borg_repository
: Full path to repository. Your own server or BorgBase.com repo. Not required when using auto creation of repositories. Can be a list if you want to backup to multiple repositories.borg_source_directories
: List of local folders to back up.
Optional Arguments
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_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 totrue
borg_remote_path
: Path to the borg executable on the remote. It will default toborg
.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_ssh_command
: Command to use instead of just "ssh". This can be used to specify ssh options.borgmatic_check_last
: Number of archives to check. Defaults to3
borgmatic_checks
: List of consistency checks. Defaults to['repository']
borgmatic_config_name
: Name to use for the borgmatic config file. Defaults toconfig.yaml
borgmatic_cron_checks_day
: Day when cron job for infrequent checks will run. Defaults to{{ 28 | random }}
borgmatic_cron_checks_hour
: Hour when cron job for infrequent checks will run. Defaults to{{ range(7, 24) | random }}
borgmatic_cron_checks_minute
: Minute when cron job for infrequent checks will run. Defaults to{{ 59 | random }}
borgmatic_cron_hour
: Hour when regular create and prune cron job will run. Defaults to{{ 6 | random }}
borgmatic_cron_minute
: Minute when regular create and prune cron job will run. Defaults to{{ 59 | random }}
borgmatic_hooks
: Hooks to monitor your backups e.g. with Healthchecks. See official documentation for more.borgmatic_large_repo
: Less frequent, monthly repo checking. Defaults totrue
borgmatic_relocated_repo_access_is_ok
: Bypass Borg error about a repository that has been moved. Defaults tofalse
borgmatic_store_atime
: Store atime into archive. Defaults totrue
borgmatic_store_ctime
: Store ctime into archive. Defaults totrue
ssh_key_file
: Path to a private ssh key file (default is.ssh/id_ed25519
). It generates a ed25519 key if the file doesn't exist yet.
Optional Arguments for BorgBase.com repository auto creation
This role can also set up a new repository on BorgBase, using the arguments below. Thanks to Philipp Rintz for contribution of this feature.
create_repo
: Whether to let the role create the repository for the server. Default: Falsebb_token
: Your BorgBase.com API-Token. Should be Create Only for security reasons.bb_region
: Which region the backups should be saved in. Choice: "eu" or "us".bb_new_sshkey
: Whether to use the automatically created SSH_key. Default: Truebb_sshkey
: If there is a key already available on BorgBase.com that should be used, it can be set with this variable. The key needs to be exactly the same, including key-comment.bb_append
: Should the permission of the newly created repository be append only? Default: Truebb_quota
: To use a quota for the Server. Default: Falsebb_quota_size
: Will need to be set ifbb_quota
is set to True. In Gigabyte.bb_alertdays
: After how many days of no backup activity should alerts be sent out? Defaults to off.bb_repo_name
: What name the created repository should have. Defaults to the inventory_hostname.
Use BorgBase Module Standalone
You can also use the BorgBase-Ansible module directly if needed:
- name: Create new repository for server in EU with new SSH_key and quota
borgbase:
repository_name: "{{ inventory_hostname }}"
token: "Your Borgbase API Token"
new_ssh_key: True
ssh_key: "{{ some_variable }}"
append_only: True
quota_enable: True
quota: 1000 #in GB
region: eu
alertdays: 2
delegate_to: localhost
Planned features
- Testing
- Multiple repos in one role-call instead of callng this role multiple times.
- Support more OSs, like Red Hat/Fedora/CentOS, SuSE, Gentoo, Slackware, Arch, BSD
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-2020 Manuel Riel and contributors.