From f5cb19eddd1708b18b4079fb98c666b602277be5 Mon Sep 17 00:00:00 2001 From: phil Date: Sun, 9 Apr 2023 09:51:26 +0200 Subject: [PATCH] Add README --- README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..73851e7 --- /dev/null +++ b/README.md @@ -0,0 +1,86 @@ +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 +- Schedule regular backups using Cron +- Export borg repo keys to localhost +- Optional: Setup borgbase.com SSH key and repository via API + +## Example playbook with Cron timer and borgbase.com repository enabled + +```YAML +- hosts: all + roles: + - role: ansible-role-borgbackup + borgbase: true + borgbase_api_key: abcd1234 + borg_encryption_passphrase: CHANGEME + borg_repository: + - path: ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo + label: borgbase + borg_source_directories: + - /var/www + borgmatic_hooks: + before_backup: + - echo "`date` - Starting backup." + postgresql_databases: + - name: users + hostname: database1.example.org + port: 5433 +``` + +## Installation + +Clone latest version from Git +```Shell +$ git clone https://git.systemausfall.org/senselab/ansible-role-borgbackup.git roles/ansible_role_borgbackup +``` + +## 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. + +#### 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_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](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 + +#### Misc Variables +- `ssh_config_path`: Path of you SSH config file. Defaults to `/root/.ssh/config`.