From e760e830ed88e6008d421d7005bd1cd3930b3cd4 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Fri, 16 Oct 2026 10:29:09 +1000 Subject: docs: Ansible example - backups with the vyos.blueprints collection --- docs/configexamples/ansible.md | 58 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) (limited to 'docs') 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//`: + +- `_.cfg`: the configuration as shown by `show configuration`; + this is the file to restore from +- `_.set`: the same configuration as `set` commands, for reading + and comparing +- `_.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. -- cgit v1.2.3 From e358a865aaf6098321b6da27a6d01c3525427754 Mon Sep 17 00:00:00 2001 From: omnom62 Date: Fri, 16 Oct 2026 10:48:39 +1000 Subject: docs: Ansible example - wrap to 80 columns, shorten an existing heading --- docs/configexamples/ansible.md | 38 ++++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 18 deletions(-) (limited to 'docs') diff --git a/docs/configexamples/ansible.md b/docs/configexamples/ansible.md index a83d25a5..d2594b9b 100644 --- a/docs/configexamples/ansible.md +++ b/docs/configexamples/ansible.md @@ -157,7 +157,7 @@ set system name-server '192.0.2.1' ``` -## The simple way without configuration of the hostname (one task for all routers): +## The simple way without configuring the hostname (one task for all routers): ```none # nano /root/hosts_v2 @@ -210,16 +210,17 @@ vyos9 : ok=1 changed=0 unreachable=0 failed=0 s ## 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. +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: +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 @@ -242,14 +243,15 @@ Back up every router of the inventory with one command, run from `/root`: For each router, this creates three files with the same timestamp in `/root/backups//`: -- `_.cfg`: the configuration as shown by `show configuration`; - this is the file to restore from -- `_.set`: the same configuration as `set` commands, for reading - and comparing -- `_.json`: the VyOS version, model and serial number of the router +- `_.cfg`: the configuration as shown by `show + configuration`; this is the file to restore from +- `_.set`: the same configuration as `set` commands, for + reading and comparing +- `_.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: +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 @@ -262,8 +264,8 @@ To back up only some routers, name a group or a host of the inventory: ``` ```{note} -Backups contain password hashes and keys. The files are created readable only by -their owner; keep the backup directory protected as well. +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 -- cgit v1.2.3