In Part 2 we went over initial configuration of VyOS including setting up:

• Interfaces
• SSH
• Static routes
• DNS
• DHCP servers
• DNS forwarding
• SNAT
• Firewall rules

Now we want I want to do this in a more automated fashion, my goto is Ansible for something like this configuration management.

VyOS documentation on Automation with Ansible is a bit sparse, I may put a PR in to add some of these examples.

There are some good modules in the vyos.vyos Ansible collection which I may migrate a lot of this to use If they work well enough, but for now we will focus on the vyos_config and using a jinja file for templating.

If you are new to Ansible, then this post is not an introduction to Ansible, so I sugest you check out Jeff Geerlings Ansible 101, this is a fantastic introduction to Ansible and how powerful it can be then come back here.

Step 1 - Ansible directory structure

You can pull from my Github - vyos-lab to get you started. I will be creating a new branch for each post and my main branch is what is running in my lab at the moment so feel free to peek ahead.

.
├── ansible.cfg
├── group_vars
│   ├── all
│   │   └── defaults.yml
│   └── vyos.yml
├── hosts
├── Pipfile
├── Pipfile.lock
├── README.md
├── requirements.yml
├── roles
│   ├── vyos_base
│   │   ├── handlers
│   │   │   └── main.yml
│   │   ├── tasks
│   │   │   └── main.yml
│   │   └── templates
│   │       └── base.j2
│   └── vyos_users
│       ├── handlers
│       │   └── main.yml
│       ├── tasks
│       │   └── main.yml
│       └── templates
│           └── users.j2
├── vars
│   └── users.yml
├── vyos_base.yml
└── vyos_users.yml

Step 2 - Initial setup

I have used pipenv to create a python environment so I dont have to install ansible on my local machine, you can follow along with your installed version of ansible or you can install pipenv with your OS package manager*.

*Obviously you are using Linux the best OS

Then simply run pipenv install and when that is complete jump into your virtual python environment with pipenv shell.

I also have created a nix flake devshell if you are feeling that way which is in main

You should have the latest version of ansible installed along with ansible-lint and ansible-pylibssh which replaces paramiko.

Now you have ansible, you need to configure your hosts file, I have set up DNS entries on my pi-hole servers for these so I can use just the hostname, you may need to add extra bits but heres my hosts file.

# ./hosts
[vyos:children] # So we have a `vyos` group
lab

# This is to create a lab group so we can share variables for other
devices in our lab
[lab]
firewall.lab  # ansible_ssh_host=192.168.1.251 <- Add this if you can't
ssh to your vyos machine using hostname only

Now we will set some ansible defaults in ansible.cfg

[defaults]
inventory = hosts # This tells ansible to use the hosts file
we just created as the inventory

# These are just some other defaults I throw in.
host_key_checking = no
retry_files_enabled = false
ANSIBLE_INVENTORY_UNPARSED_FAILED = true

Next we want to set up our group vars group_vars/all/defaults.yml, This will be used in our jinja templating to set name-servers and our static route to our HOME router as well as the url for adding image updates.

# ./group_vars/all/defaults.yml
name_servers:
  - 192.168.1.114 # Set this to whatever dns servers you want
  - 192.168.1.115

default_gateway: 192.168.1.254 # Set this to your home router

rolling: true # This sets that we are using rolling vyos not LTS
rolling_url: "https://raw.githubusercontent.com/vyos/vyos-nightly-build/refs/heads/current/version.json"
# Will probalby change this var to just `update_url:` so it can be used
for rolling and LTS

After this we need to tell ansible how it is going to connect to our VyOS machines, as this uses network_cli for its connection. We can set this up in group_vars/vyos.yml which is why the vyos group is in our inventory file as I may be adding a mikrotik router to my lab to do some more complex networking.

# ./group_vars/vyos.yml

---
ansible_connection: network_cli
ansible_network_os: vyos
ansible_become: true
ansible_become_method: enable
ssh_port: 22
ansible_user: YOUR-USERNAME

ansible_python_interpereter: /usr/bin/env python3

Nearly there, Now we need to set up our user in users.yml I put this in ./vars/

# ./vars/users.yml
users:
  - name: YOUR-USERNAME
    ssh_keys:
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAATRIMED
      - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAATRIMED

Go grab or generate an ssh key pair and add your public key/s to the ssh_keys list, you can add multiple keys as the template will loop over them and add them.

We are now all set up and now can create our roles.

Part 3 - Roles

Base role

I wanted to make my ansible modular and use roles for each area of VyOS, the first role I want to look at is the base role, this sets up the basic settings such as:

• hostname
• ssh
  • port
  • disable-password auth
• set name-servers
• set static route out
• delete vyos user
• set update config

So if we look at our directory structure we have three directories under each role. handlers,tasks and templates.

templates is where all the magic happens, lets have a look at our template for our base role.

# ./roles/vyos_base/templates/base.j2

{# Set hostname #}
set system host-name {{ inventory_hostname_short }}

{# Set SSH #}
set service ssh port {{ ssh_port }}
set service ssh disable-password-authentication

{# Set Nameservers  #}
{% for nameserver in name_servers %}
set system name-server {{ nameserver }}
{% endfor %}

{# Set Static route #}
set protocols static route 0.0.0.0/0 next-hop {{ default_gateway }}

{# Remove vyos user #}
delete system login user vyos

{# Set rolling update url #}
{% if rolling %}
set system update-check url '{{ rolling_url }}'
{% endif %}

I have added comments for what each bit does, first we set the hostname then set ssh then name-servers followed by static route , we then remove the vyos user then set the update url

Now we don’t want to run this first as if you haven’t already set up a user other than vyos then this will either fail or lock you out as you will delete the vyos user.

User role

Lets now have a look at our user role template, again same format as the previous role structure.

{# Set up user and ssh key #}

{% for user in users %}
{% for key in user.ssh_keys %}
system login user {{ user.name }} authentication public-keys {{ key.split()[2] }} key '{{ key.split()[1] }}'
system login user {{ user.name }} authentication public-keys {{ key.split()[2] }} type '{{ key.split()[0] }}'

{% endfor %}
{% endfor %}

In this loop we could add multiple users and multiple keys if we wanted to.

Tasks

Now for each role we have a tasks/main.yml which all follow the same format

# roles/ROLE_NAME/tasks/main.yml

- name: "Set up ROLE_NAME"
  vyos.vyos.vyos_config:
    src: CONFIG_NAME.j2
  notify: Save config

Handlers

Each role has a handler handlers/main.yml which is the same and this just saves the config.

---
- name: Save config
  vyos.vyos.vyos_config:
    save: true

Playboook

The final piece, to be able to run the roles we need a playbook. I put these in the root of the directory. Generally I name them the same as the role to make it easier.

./vyos_base.yml
---
- name: Set up VyOS Base
  hosts: vyos
  gather_facts: true
  order: inventory
  roles:
    - vyos_base

./vyos_users.yml
---
- name: Set up VyOS Users
  hosts: vyos
  gather_facts: false
  order: inventory
  vars_files:
    - ./vars/users.yml
  roles:
    - vyos_users

You will notice I add vars_files: this is so we can use the users.yml as I see it as a gobal variable and not a group or host var.

Part 4 - Running the playbook

Users

Now, If we should be in a position to run our playbooks, Again important to note we want to add our user first then run the base role.

Now since I have set up my vyos user and vyos password to be vyos from Part 1 the first run I will have to use a command line variable. So I will run:

ansible-playbook vyos_users.yml -e'ansible_user=vyos ansible_password=vyos' --diff

I use the --diff flag to show what has changed, helps when debugging when adding --check which will run in check mode and not actually make any changes, but show what changes would be made.

For demonstration, I added a new user called blog with same keys as my user. My output looks like this:

NOTE: adjusted output formatting for better reading

PLAY [Set up VyOS Users] *********************************************

TASK [vyos_users : Set up Users] *************************************
[system login user]
+ blog {
+     authentication {
+         public-keys oliverkelly@laptop {
+             key "AAAAC3NzaC1lZDI1NTE5AAAATRIMED"
+             type "ssh-ed25519"
+         }
+     }
+ }


[edit]
[WARNING]:To ensure idempotency and correct diff the input configuration
lines should be similar to how they appear if present in the running
configuration on device including the indentation
changed: [firewall.lab]

RUNNING HANDLER [vyos_users : Save config] ***************************
changed: [firewall.lab]

PLAY RECAP ***********************************************************
firewall.lab: ok=2 changed=2 unreachable=0 failed=0 skipped=0 rescued=0 
ignored=0

Base

For demonstration purposes I deleted some config so that the ansible would add it back in.

Heres the output of ansible-playbook vyos_base.yml --diff

NOTE: adjusted output formatting for better reading

PLAY [Set up VyOS Base] **********************************************

TASK [Gathering Facts] ***********************************************
ok: [firewall.lab]

TASK [vyos_base : Set up base configuration] *************************
[service ssh]
+ disable-password-authentication
[system login user]
- vyos {
- }
[system]
+ host-name "firewall"
+ update-check {
+     url "https://raw.githubusercontent.com/vyos/vyos-nightly-build/refs/heads/current/version.json"
+ }


[edit]
[WARNING]:To ensure idempotency and correct diff the input configuration
lines should be similar to how they appear if present in the running 
configuration on device including the indentation
changed: [firewall.lab]

RUNNING HANDLER [vyos_base : Save config] *****************************
changed: [firewall.lab]

PLAY RECAP ************************************************************
firewall.lab : ok=3 changed=2 unreachable=0 failed=0 skipped=0 rescued=0
ignored=0

As you can see, this is a nice way to have our config for vyos as code and this is just the first bit. In Part 4 we will look at creating our networks with a new role.

• Vyos
• Homelab
• Proxmox
• Networking
• Vxlan