From a22ff185f9836023817f9d4f8df3157b948f8cf2 Mon Sep 17 00:00:00 2001 From: Colin Wilk Date: Sat, 27 Jun 2026 15:22:45 +0200 Subject: borg!: support multiple backups to same target This brings support for multiple backups pointing to the same borg server, different repositories, from the same client. We support this by parsing the SSH authorized key file first and appending allowed repositories to allow independent definitions of the borg targets. So that the decryption_keys do not clash we include the repository name as well as the host in the key. This will lead to new keys being created for existing hosts in the new format. Old Format: {{ combine({inventory_hostname: borg_keys.stdout}) }} New Format: {{ combine({(inventory_hostname ~ '_' ~ borg_repo_name): borg_keys.stdout}) }} If upgrading from an older version that used just the hostname as the key, your existing `decryption_keys.yml` can be manually removed once the new format is also added. --- README.md | 229 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 208 insertions(+), 21 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d556818..5281a01 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -Ansible Role: BorgBackup -======================== +# Ansible Role: BorgBackup An Ansible role that installs and configures a systemd service for BorgBackup on a client and (delegated) server. @@ -9,8 +8,7 @@ The documentation assumes basic knowledge about BorgBackup. You can get up to speed with Borg by reading their excellent documentation on . -How it works ------------- +## How it works ```mermaid sequenceDiagram @@ -27,8 +25,7 @@ borg-client->>Ansible: Store decryption keys borg-client-->borg-server: Do Backup ``` -Installation ------------- +## Installation via ansible-galaxy @@ -54,8 +51,7 @@ ansible-galaxy role install git+https://github.com/kliwniloc/ansible-role-borgba name: kliwniloc.borgbackup ``` -Role Variables --------------- +## Role Variables For more details, see: [`defaults/main.yml`](defaults/main.yml) @@ -76,7 +72,7 @@ will default to `borg_server_host`. ```yaml borg_server_host: "" # Required borg_server_host_ssh_key: "" # Required -borg_server_host_url: {{ borg_server_host }} # Optional +borg_server_host_url: { { borg_server_host } } # Optional ``` The role creates a user for the Borg repositories on the Borg server. You can @@ -121,6 +117,8 @@ your Borg backups, but it is not used by default. > If you want true end-to-end encryption, you should configure a passphrase > Read more: [BorgBackup Security](https://borgbackup.readthedocs.io/en/stable/internals/security.html#offline-key-security) + + `borg_included_dirs` and `borg_excluded_dirs` finally picks what directories will be backed up by Borg. @@ -167,18 +165,17 @@ see man-page systemd.timer(5). borg_backup_script_location: /usr/local/bin/run_borg_backup borg_backup_timer_name: borg_backup borg_backup_service_name: borg_backup -borg_backup_argument: '{{ borg_server_host_url }}' -borg_systemd_oncalendar: '*-*-* 02:00:00' +borg_backup_argument: "{{ borg_server_host_url }}" +borg_systemd_oncalendar: "*-*-* 02:00:00" borg_systemd_accuracysec: 60min ``` -Example Playbooks ------------------ +## Example Playbooks -Simple Playbook +### Simple Playbook ```yaml -- name: > +- name: >- Add Borg backup to the borg-client and save the decryption keys alongside the playbook hosts: borg-client @@ -192,10 +189,10 @@ Simple Playbook - /opt/project ``` -Multiple Backup servers +### Multiple Backup Servers ```yaml -- name: > +- name: >- Add Borg backup with multiple borg servers to the borg-client and save the decryption keys alongside the playbook hosts: borg-client @@ -212,12 +209,202 @@ Multiple Backup servers borg_server_host_ssh_key: ssh-rsa BBBBBBBB... ``` -Dependencies ------------- +### Multiple Repositories on Single Server, Single Client (Multi-Instance) + +> [!NOTE] +> **This is considered a beta feature** +> This feature is still being developed and has some quirks around it. +> We plan to release this properly on the next major version with some breaking +> changes to make this less of a footgun. Until then, read this section +> carefully. + +When a single client host needs to back up different data sets to the same Borg +server (e.g., system configs and user data), you can run the role multiple times +with different `borg_repo_name` values. + +**Important:** Each invocation must have a unique `borg_backup_argument` to create +separate systemd timer units. + + + +```yaml +- name: Configure multi-instance backup (same host, different repos) + hosts: borg-client + vars: + borg_server_host: borg-server + borg_server_host_ssh_key: ssh-rsa AAAAAAAA... + borg_decryption_keys_yaml_path: "{{ playbook_dir }}/decryption_keys.yml" + + roles: + - role: kliwniloc.borgbackup + vars: + borg_repo_name: configs + borg_backup_argument: configs + borg_compression: zstd + borg_included_dirs: + - /etc + borg_systemd_oncalendar: "*-*-* 02:00:00" + + - role: kliwniloc.borgbackup + vars: + borg_repo_name: home-data + borg_backup_argument: home-data + borg_compression: lz4 + borg_included_dirs: + - /home + borg_excluded_dirs: + - /home/*/.cache + borg_systemd_oncalendar: "*-*-* 04:00:00" +``` + +This creates: + +- Two repositories on the Borg server: `/opt/borg/configs` and `/opt/borg/home-data` +- Two systemd timers: `borg_backup@configs.timer` and `borg_backup@home-data.timer` +- A single SSH keypair shared between both repositories +- A single `authorized_keys` entry with both repositories in `--restrict-to-repository` + +## Important Behaviors and Limitations + +### Consistent `--append-only` Setting Required + +All repositories for a given host must use the same `borg_mode_append_only` +setting. The role will fail with an error if you attempt to configure +repositories with conflicting `--append-only` settings for the same host. + +This is because the SSH `authorized_keys` entry uses a single `--append-only` +flag that applies to all repositories accessible via that key. + +```yaml +# This will FAIL - conflicting append-only settings +roles: + - role: kliwniloc.borgbackup + vars: + borg_repo_name: configs + borg_mode_append_only: false # ERROR: inconsistent + + - role: kliwniloc.borgbackup + vars: + borg_repo_name: home-data + borg_mode_append_only: true # ERROR: inconsistent +``` + +### Single SSH Key per Host\*\* + +The role generates one SSH keypair per client host. All repositories for that +host share the same SSH key for authentication to the Borg server. + +### Decryption Keys Storage Format + +Decryption keys are stored in the `decryption_keys.yml` file using the format: + +```yaml +hostname_repo_name: | + To restore key use borg key import --paper /path/to/repo + BORG PAPER KEY v1 + ... +``` + +For hosts with multiple repos, each repository has its own entry: + +- `borg-client_configs` +- `borg-client_home-data` + +### Deprovisioning Borg Repositories + +This role does not currently handle deprovisioning or removing repositories. +Deprovisioning must be done manually or via separate playbooks. + +### Removing a Repository + +To remove a specific repository (applies to both single and multi-instance setups): + +1. Stop and disable the systemd timer and service: + + ```bash + systemctl stop borg_backup@ARGUMENT.timer + systemctl disable borg_backup@ARGUMENT.timer + systemctl stop borg_backup@ARGUMENT.service + systemctl disable borg_backup@ARGUMENT.service + ``` + + Replace `ARGUMENT` with the `borg_backup_argument` value for that repository. + +2. Remove the backup script: + + ```bash + rm /usr/local/bin/run_borg_backup@ARGUMENT + ``` + +3. _(Multi-instance only)_ Edit the base backup script to remove the repository block: + + ```bash + # Edit /usr/local/bin/run_borg_backup + # Remove the ANSIBLE MANAGED BLOCK for the deleted repository + ``` + +4. _(If other repositories remain)_ Update `authorized_keys` on the Borg server + to remove the repository restriction. Edit `/opt/borg/.ssh/authorized_keys` + and remove the `--restrict-to-repository /opt/borg/REPONAME` from the + appropriate line. + + If this is the last repository for the host, remove the entire line instead. + +5. Delete the repository on the Borg server: + + ```bash + ssh borg@SERVER "borg delete /opt/borg/REPONAME" + # Or simply: ssh borg@SERVER "rm -rf /opt/borg/REPONAME" + ``` + +6. Remove the decryption key entry from your `decryption_keys.yml`. + +## Deprovisioning a Complete Host + +To remove all backup configuration for a host: + +1. Stop and disable all systemd timers and services: + + ```bash + systemctl list-units --type=timer --all | grep borg_backup + # For each relevant timer: + systemctl stop borg_backup@*.timer + systemctl disable borg_backup@*.timer + ``` + +2. Remove all backup scripts: + + ```bash + rm -f /usr/local/bin/run_borg_backup* + ``` + +3. Remove the SSH key from the Borg server's `authorized_keys`: + + ```bash + # On the Borg server, edit /opt/borg/.ssh/authorized_keys + # Remove the line containing root@HOSTNAME + ``` + +4. Delete all repositories for the host on the Borg server: + + ```bash + ssh borg@SERVER "rm -rf /opt/borg/HOSTNAME" + # For multi-instance: + ssh borg@SERVER "rm -rf /opt/borg/HOSTNAME_repo1" + ssh borg@SERVER "rm -rf /opt/borg/HOSTNAME_repo2" + ``` + +5. Remove all decryption key entries for the host from your + `decryption_keys.yml`. + +## Dependencies None. -License -------- +## License MIT -- cgit v1.2.3