nbops-ansible-router/README.md

nbops-ansible-router

Ansible framework for building a Debian 13 BIRD router VM from an initial Debian 12 install.

The first stage performs the Debian 12 to Debian 13 dist upgrade. Router configuration then installs WireGuard and BIRD, applies forwarding sysctl values, and renders configs from variables.

Layout

• site.yml - main entry point.
• inventories/production/hosts.yml - VM inventory placeholder.
• group_vars/routers.yml - shared router variables.
• roles/debian_dist_upgrade - Debian 12 to Debian 13 upgrade workflow.
• roles/bird_router - WireGuard, sysctl forwarding, CZ.NIC BIRD packages, and BIRD configuration.

Usage

Edit inventories/production/hosts.yml, then run:

ansible-playbook site.yml

To run only the OS upgrade stage:

ansible-playbook site.yml --tags debian_upgrade

The upgrade role expects the VM to start on Debian 12/bookworm and upgrades it to Debian 13/trixie.

Router Secrets

WireGuard private keys are read from environment variables by default:

export WG1_PRIVATEKEY='...'
export WG2_PRIVATEKEY='...'
ansible-playbook site.yml

For production, prefer Ansible Vault group vars instead of committing secrets. Public keys, allowed IPs, BGP peers, package track, and package version are defined in group_vars/routers.yml.

BIRD Package Track

The router role configures the CZ.NIC Labs apt repository for BIRD. Defaults:

• bird_track: bird2
• bird_package_version: 2.19.1-cznic.1~trixie

To test BIRD 3 later, set:

bird_track: bird3
bird_package_version: ""