docs: Ansible example - backups with the vyos.blueprints collection

1 files changed, 58 insertions, 0 deletions

diff --git a/docs/configexamples/ansible.md b/docs/configexamples/ansible.md
index 8bbd9306..a83d25a5 100644
--- a/docs/configexamples/ansible.md
+++ b/docs/configexamples/ansible.md
@@ -208,5 +208,63 @@ vyos8                      : ok=1    changed=0    unreachable=0    failed=0    s
 vyos9                      : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
 ```
 
+## Backups with the vyos.blueprints collection
+
+Regular configuration backups of many routers are a common task. Instead of writing
+the playbook yourself, you can use the ready-made, tested roles of the
+[vyos.blueprints](https://github.com/vyos/vyos.blueprints) collection. They work with
+the inventory and variables created above.
+
+```{note}
+vyos.blueprints and the vyos.vyos collection it builds on need **ansible-core 2.16 or
+newer**. The Ansible packages of older Debian releases are too old; install a current
+version with pip, for example in a virtual environment, together with
+`ansible-pylibssh`, the SSH library Ansible uses for network devices:
+
+    python3 -m venv /root/ansible-venv
+    . /root/ansible-venv/bin/activate
+    pip install ansible-core ansible-pylibssh
+```
+
+Install the collection on the Ansible control node. Until its first release is
+published on Ansible Galaxy, install it from GitHub:
+
+```none
+# ansible-galaxy collection install git+https://github.com/vyos/vyos.blueprints.git
+```
+
+Back up every router of the inventory with one command, run from `/root`:
+
+```none
+# ansible-playbook vyos.blueprints.backup -i hosts
+```
+
+For each router, this creates three files with the same timestamp in
+`/root/backups/<router>/`:
+
+- `<router>_<timestamp>.cfg`: the configuration as shown by `show configuration`;
+  this is the file to restore from
+- `<router>_<timestamp>.set`: the same configuration as `set` commands, for reading
+  and comparing
+- `<router>_<timestamp>.json`: the VyOS version, model and serial number of the router
+
+The newest 10 backups per router are kept; older ones are removed. To change the
+location or the number of backups kept:
+
+```none
+# ansible-playbook vyos.blueprints.backup -i hosts -e backup_root=/srv/vyos-backups -e backup_keep=30
+```
+
+To back up only some routers, name a group or a host of the inventory:
+
+```none
+# ansible-playbook vyos.blueprints.backup -i hosts -e vyos_backup_hosts=vyos9
+```
+
+```{note}
+Backups contain password hashes and keys. The files are created readable only by
+their owner; keep the backup directory protected as well.
+```
+
 In the next chapter of the example, we'll use Ansible with jinja2
 templates and variables.