From f66105f94b5f1aaea91b7343b31617e5dfc1ef21 Mon Sep 17 00:00:00 2001 From: Manu <3916435+m3nu@users.noreply.github.com> Date: Tue, 18 Feb 2020 12:47:24 +0800 Subject: [PATCH] Re-arrange and expand readme (#28) --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 68 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 1c398e3..bb193fe 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,57 @@ # Ansible Role: BorgBackup Client -An Ansible Role that sets up automated remote backups on the target machine. Uses [BorgBackup](https://borgbackup.readthedocs.io/en/stable/) and [Borgmatic](https://github.com/witten/borgmatic). Currently supports Debian/Ubuntu and CentOS/RHEL/Fedora. +[![Build Status](https://travis-ci.org/borgbase/ansible-role-borgbackup.svg?branch=master)](https://travis-ci.org/borgbase/ansible-role-borgbackup) [![Ansible Galaxy](https://img.shields.io/ansible/role/30531)](https://galaxy.ansible.com/m3nu/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). Currently supports Debian/Ubuntu and CentOS/RHEL/Fedora. + +Works great with [BorgBase.com](https://www.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](https://www.borgbase.com) repo for storing backups (optional) + + +## Example Playbook + +``` +- hosts: webservers + roles: + - 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 +``` + + +## 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/borgbackup +``` + ## Role Variables ### Required Arguments -- `borg_repository`: Full path to repository. Your own server or [BorgBase.com](https://www.borgbase.com) repo. Only required if not using the [BorgBase.com](https://www.borgbase.com) auto creation of repositories. +- `borg_repository`: Full path to repository. Your own server or [BorgBase.com](https://www.borgbase.com) repo. Not required when using auto creation of repositories. - `borg_source_directories`: List of local folders to back up. ### Optional Arguments @@ -27,6 +73,8 @@ An Ansible Role that sets up automated remote backups on the target machine. Use - `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](https://www.borgbase.com) repository auto creation +This role can also set up a new repository on BorgBase, using the arguments below. Thanks to [Philipp Rintz](https://github.com/p-rintz) for contribution this feature. + - `create_repo`: Whether to let the role create the repository for the server. Default: False - `bb_token`: Your [BorgBase.com](https://www.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". @@ -38,26 +86,27 @@ An Ansible Role that sets up automated remote backups on the target machine. Use - `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. -## Example Playbook + +### Use BorgBase Module Standalone +You can also use the BorgBase-Ansible module directly if needed: ``` -- hosts: webservers - roles: - - 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 +- 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 - [x] Testing @@ -80,4 +129,4 @@ MIT/BSD ## Author -Manuel Riel. Created for [BorgBase.com](https://www.borgbase.com) - Simple and Secure Hosting for your Borg Repositories. +© 2018-2020 Manuel Riel and contributors.