Quickstart

Before you start

Use a minimal Debian 13 host or VM with two or more network interfaces, a reachable management address and an administrator SSH key. Keep the inventory and site variables outside the role defaults so each customer deployment remains explicit.

Prepare the repository

Create the inventory, define interface addresses and protect the Vault password. Store private VPN keys, certificates and customer-specific values in encrypted variables. Review the generated changes before touching a production firewall.

Apply the playbook

Run ansible-playbook -i inventory.yml site.yml from the administration workstation. The roles install packages, configure systemd-networkd, render nftables, start the VPN and routing services, then enable the selected HA components.

Verify the host

Check ip address, ip route, nft list ruleset, systemctl --failed and journalctl. For an HA pair, verify the VRRP state, Conntrackd status, FRR neighbors and both VPN tunnels before moving traffic.

Repeat safely

Reapplying the playbook is the normal update path. Make one change at a time, validate it in CI or a lab, then apply it to the standby firewall before the active firewall.

First validation

Before applying to production, run the syntax check and inspect the rendered variables. Confirm that the management path is reachable, that the expected default route exists and that the firewall does not accidentally expose a service on the WAN.

Inventory shape

Keep the two firewalls in separate host groups and define interface facts per host. The playbook should know which interface is WAN, which is LAN, and which addresses are owned by the node or by the VRRP VIP.

[firewalls]
fw1 ansible_host=10.20.10.3
fw2 ansible_host=10.20.10.4

[firewalls:vars]
ansible_user=debian

Vault and secrets

Encrypt IPsec pre-shared keys, WireGuard private keys and certificates before committing them. The Vault password is an external deployment secret, not a value to place in group variables or generated files.

ansible-vault encrypt_string --name strongswan_psk
ansible-playbook --syntax-check -i inventory.yml site.yml

First packet test

After deployment, test the management route first, then the default route, DNS, NAT and one published service. Capture on both sides of the firewall when a connection fails instead of changing several rules at once.

Prepare the network first

Before the first run, document the management path, WAN gateway, internal networks, VLAN tags, MTU and expected default route. Confirm that the host has console or out-of-band access. Firewall automation can intentionally change the active network configuration and should not be tested without a recovery path.

Review before applying

Run the syntax check, inspect inventory resolution and use check mode where supported. Review package changes, rendered interface names, firewall objects, routes and service enablement. Keep secrets encrypted and pass Vault credentials through the deployment environment.

Acceptance tests

Test management access, DNS, the default route, one allowed outbound flow, one denied flow, each published service, VPN reachability and HA failover. Record expected results so a later change can be compared with the original baseline.