123 lines
5.6 KiB
Markdown
123 lines
5.6 KiB
Markdown
Ansible Role: BorgBackup
|
|
========================
|
|
|
|
Set up encrypted, compressed and deduplicated backups using [BorgBackup](https://borgbackup.readthedocs.io/en/stable/) and [Borgmatic](https://github.com/witten/borgmatic).
|
|
|
|
Works great with [BorgBase.com](https://www.borgbase.com) - Simple and Secure Hosting for your Borg Repositories. To manage BorgBase repos via Ansible, also see Andy Hawkins' [BorgBase Collection](https://galaxy.ansible.com/adhawkins/borgbase).
|
|
|
|
**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 borgbase.com 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 borgbase.com repository enabled
|
|
|
|
No need to configure the variable `borg_repository`. It's evaluated via borgbase API call.
|
|
|
|
```YAML
|
|
- hosts: all
|
|
roles:
|
|
- role: ansible-role-borgbackup
|
|
borgbase: true
|
|
borgbase_api_key: abcd1234
|
|
borg_encryption_passphrase: CHANGEME
|
|
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 local repository
|
|
|
|
```YAML
|
|
- hosts: all
|
|
roles:
|
|
- role: ansible-role-borgbackup
|
|
borg_encryption_passphrase: CHANGEME
|
|
borg_repository:
|
|
- path: /var/lib/backup
|
|
label: local
|
|
borg_source_directories:
|
|
- /var/www
|
|
borgmatic_hooks:
|
|
before_backup:
|
|
- echo "`date` - Starting backup."
|
|
postgresql_databases:
|
|
- name: users
|
|
hostname: database1.example.org
|
|
```
|
|
|
|
## Installation
|
|
|
|
- Clone latest version from Git:
|
|
```Shell
|
|
$ git clone https://git.systemausfall.org/senselab/ansible-role-borgbackup.git roles/ansible_role_borgbackup
|
|
```
|
|
- Optional: Add Andy Hawkins' [BorgBase Collection](https://galaxy.ansible.com/adhawkins/borgbase) to your `requirements.txt`:
|
|
```YAML
|
|
collections:
|
|
- 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](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns) 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.com`
|
|
- `borgbase_ssh_key_name`: How to name your SSH key at borgbase.com. 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](https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/#check-frequency) 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](https://healthchecks.io/). See [official documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/) 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
|
|
|
|
## Security
|
|
|
|
You can create a dictionary for `borg_encryption_passphrase` in an Ansible vault file:
|
|
```YAML
|
|
borg_backup_passphrases:
|
|
host1: acbd1234
|
|
host2: efgh5678
|
|
```
|
|
Additionally you have to define `borg_encryption_passphrase: "{{ borg_backup_passphrases[inventory_hostname] }}"` in your `group_vars`.
|
|
|
|
## Credits
|
|
|
|
This role is based on [Ansible Role: BorgBackup Client](https://github.com/borgbase/ansible-role-borgbackup).
|