{"id":13551972,"url":"https://github.com/borgbase/ansible-role-borgbackup","last_synced_at":"2026-01-27T02:07:50.250Z","repository":{"id":40355211,"uuid":"151834805","full_name":"borgbase/ansible-role-borgbackup","owner":"borgbase","description":"Ansible role to set up Borg and Borgmatic","archived":false,"fork":false,"pushed_at":"2024-08-14T07:26:11.000Z","size":103,"stargazers_count":216,"open_issues_count":45,"forks_count":98,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-08-14T08:46:58.892Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/borgbase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-06T11:48:04.000Z","updated_at":"2024-08-14T07:26:15.000Z","dependencies_parsed_at":"2024-03-12T09:48:11.452Z","dependency_job_id":"c906338c-38d3-4ede-a6bb-1d68ff1d1483","html_url":"https://github.com/borgbase/ansible-role-borgbackup","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgbase%2Fansible-role-borgbackup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgbase%2Fansible-role-borgbackup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgbase%2Fansible-role-borgbackup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/borgbase%2Fansible-role-borgbackup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/borgbase","download_url":"https://codeload.github.com/borgbase/ansible-role-borgbackup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243301128,"owners_count":20269286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:01:56.752Z","updated_at":"2026-01-27T02:07:50.232Z","avatar_url":"https://github.com/borgbase.png","language":"Jinja","funding_links":[],"categories":["HTML","Jinja","others"],"sub_categories":[],"readme":"# Ansible Role: BorgBackup Client\n\n[![Test](https://github.com/borgbase/ansible-role-borgbackup/actions/workflows/main.yml/badge.svg)](https://github.com/borgbase/ansible-role-borgbackup/actions/workflows/main.yml) [![Ansible Galaxy](https://img.shields.io/ansible/role/d/borgbase/ansible_role_borgbackup?logo=ansible\u0026color=5cbec1\u0026label=Ansible%20Galaxy)](https://galaxy.ansible.com/ui/standalone/roles/borgbase/ansible_role_borgbackup/)\n\nSet up encrypted, compressed and deduplicated backups using [BorgBackup](https://borgbackup.readthedocs.io/en/stable/) and [Borgmatic](https://github.com/witten/borgmatic). Currently supports Debian/Ubuntu, CentOS/Red Hat/Fedora, Archlinux and Manjaro.\n\nWorks 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).\n\n**Main features**\n- Install Borg and Borgmatic from PyPi or distro packages\n- Set up Borgmatic config\n- Schedule regular backups using Cron or Systemd timer\n\n## Breaking changes\n- Older versions of this role set up a separate Cron job for creating and checking\n  backups. With recent Borgmatic version, this feature is now managed in Borgmatic.\n  As a result the extra Cron job will be removed by this role.\n- Older versions of this role only supported Cron for scheduling. If you use\n  Systemd timers, be sure to remove the Cron job in `/etc/cron.d/borgmatic` first.\n  The role will also alert you when trying to use both timers.\n\n## Example playbook with root as backup user, using the distro package and Cron timer\n\n```\n- hosts: all\n  roles:\n  - role: borgbase.ansible_role_borgbackup\n    borg_install_method: package\n    borg_encryption_passphrase: CHANGEME\n    borg_repository:\n      - ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo\n    borg_source_directories:\n      - /var/www\n    borgmatic_hooks:\n      before_backup:\n      - echo \"`date` - Starting backup.\"\n      postgresql_databases:\n      - name: users\n        hostname: database1.example.org\n        port: 5433\n```\n\n## Example playbook with service user and Systemd timer\n\n```\n- hosts: all\n  roles:\n  - role: borgbase.ansible_role_borgbackup\n    borg_encryption_passphrase: CHANGEME\n    borg_repository: ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo\n    borgmatic_timer: systemd\n    borg_user: \"backupuser\"\n    borg_group: \"backupuser\"\n    borg_source_directories:\n      - /var/www\n    borg_retention_policy:\n      keep_hourly: 3\n      keep_daily: 7\n      keep_weekly: 4\n      keep_monthly: 6\n```\n\n## Example playbook with custom configuration options (borgmatic 1.8+)\n\n**Note:** `borgmatic_custom_config` requires borgmatic 1.8.0 or later.\n\n```\n- hosts: all\n  roles:\n  - role: borgbase.ansible_role_borgbackup\n    borg_encryption_passphrase: CHANGEME\n    borg_repository: ssh://xxxxxx@xxxxxx.repo.borgbase.com/./repo\n    borg_source_directories:\n      - /var/www\n    borgmatic_custom_config:\n      uptime_kuma:\n        push_url: https://uptime.kuma.example.com/abcd1234\n      ntfy:\n        topic: backups\n        server: https://ntfy.sh\n      output_verbosity: 1\n```\n\n## Installation\n\nDownload from Ansible Galaxy\n```\n$ ansible-galaxy install borgbase.ansible_role_borgbackup\n```\n\nClone latest version from Github\n```\n$ git clone https://github.com/borgbase/ansible-role-borgbackup.git roles/ansible_role_borgbackup\n```\n\n\n## Role Variables\n\n### Required Variables\n- `borg_repository`: Full path to repository. Your own server or [BorgBase.com](https://www.borgbase.com) repo.\n  Can be a list if you want to backup to multiple repositories.\n\n### Optional Variables\n- `borg_dep_packages`: Dependency Packages to install `borg(backup)` and `borgmatic`.\n- `borg_distro_packages`: contains the names of distributions packages for `borg(backup)` and `borgmatic`, only used if `borg_install_method` is set to `package`.\n- `borg_encryption_passcommand`: The standard output of this command is used to unlock the encryption key.\n- `borg_encryption_passphrase`: Password to use for repokey or keyfile. Empty if repo is unencrypted.\n- `borg_exclude_from`: Read exclude patterns from one or more separate named files, one pattern per line.\n- `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.\n- `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. `none` completely disables installation management.\n- `borg_require_epel`: When using `borg_install_method: package` on RHEL-based distributions, the EPEL repo is required. To disable the check (e.g. when using a custom mirror instead of the `epel-release` package), set this to `false`. Defaults to `{{ ansible_os_family == 'RedHat' and ansible_distribution != 'Fedora' }}` (i.e. `true` on Enterprise Linux-based distros).\n- `borg_lock_wait_time`: Config maximum seconds to wait for acquiring a repository/cache lock. Defaults to 5 seconds.\n- `borg_one_file_system`: Don't cross file-system boundaries. Defaults to `true`\n- `borg_compression`: Compression algorithm to use. Defaults to `auto,zstd`\n- `borg_pip_packages`: Dependancy Packages (pip) to install `borg(backup)` and `borgmatic`.\n- `borg_remote_path`: Path to the borg executable on the remote. It will default to `borg`.\n- `borg_remote_rate_limit`: Remote network upload rate limit in kiBytes/second.\n- `borgmatic_retries`: Number of times to retry a failing backup before giving up. Defaults to 0 (i.e., does not attempt retry).\n- `borgmatic_retry_wait`: Wait time between retries (in seconds) to allow transient issues to pass. Increases after each retry as a form of backoff. Defaults to 0 (no wait).\n- `borg_retention_policy`: Retention policy for how many backups to keep in each category (daily, weekly, monthly, etc).\n- `borg_source_directories`: List of local folders to back up. Default is `/etc/hostname` to prevent an empty backup.\n- `borg_ssh_key_name`: Name of the SSH public and private key. Default `id_ed25519`\n- `borg_ssh_key_file_path`: SSH-key to be used. Default `~/.ssh/{{ borg_ssh_key_name }}`\n- `borg_ssh_key_type`: The algorithm used to generate the SSH private key. Choose: `rsa`, `dsa`, `rsa1`, `ecdsa`, `ed25519`. Default: `ed25519`\n- `borg_ssh_key_comment`: Comment added to the SSH public key.\n- `borg_ssh_command`: Command to use instead of just \"ssh\". This can be used to specify SSH options.\n- `borg_version`: Force a specific borg version to be installed\n- `borg_venv_path`: Path to store the venv for `borg(backup)` and `borgmatic`\n\n- `borgmatic_check_last`: Number of archives to check. Defaults to `3`\n- `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.\n- `borgmatic_config_name`: Name to use for the Borgmatic config file. Defaults to `config.yaml`\n- `borgmatic_timer_hour`: Hour when regular create and prune cron/systemd-timer job will run. Defaults to `{{ range(0, 5) | random(seed=inventory_hostname) }}`\n- `borgmatic_timer_minute`: Minute when regular create and prune cron/systemd-timer job will run. Defaults to `{{ range(0, 59) | random(seed=inventory_hostname) }}`\n- `borgmatic_timer_flags`: Flags to pass to borgmatic cron/systemd-timer job, like \"--log-file /path/to/file.log --log-file-verbosity 2\"\n- `borgmatic_timer_cron_name`: Name to use for the cron job or systemd timer. Defaults to `borgmatic`\n- `borgmatic_systemd_nonewprivileges`: NoNewPrivileges Systemd unit setting to allow running commands with \"sudo\" in config.yaml. Default is to prevent.\n- `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.\n- `borgmatic_timer`: If the variable is set, a timer is installed. A choice must be made between `cron` and `systemd`.\n- `borgmatic_relocated_repo_access_is_ok`: Bypass Borg error about a repository that has been moved. Defaults to `false`\n- `borgmatic_unknown_unencrypted_repo_access_is_ok`: Bypass Borg error about a previously unknown unencrypted repository. Defaults to `false`\n- `borgmatic_store_atime`: Store atime into archive. Defaults to `true`\n- `borgmatic_store_ctime`: Store ctime into archive. Defaults to `true`\n- `borgmatic_version`: Force a specific borgmatic version to be installed\n- `borgmatic_custom_config`: Custom YAML configuration (as a dictionary) to add to the borgmatic config file. Allows adding any additional borgmatic options not covered by other variables. **Requires borgmatic 1.8.0 or later.** See example above.\n\n- `borg_user`: Name of the User to create Backups (service account)\n- `borg_group`: Name of the Group to create Backups (service account)\n\n\n## Contributing\n\nPull 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):\n\n```\n$ pip install -r requirements-dev.txt\n$ molecule test\n```\n\n## License\n\nMIT/BSD\n\n## Author\n\n© 2018-2023 Manuel Riel and contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborgbase%2Fansible-role-borgbackup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fborgbase%2Fansible-role-borgbackup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fborgbase%2Fansible-role-borgbackup/lists"}