Files

Jean-Gabriel Gill-Couture 6554ac5341 docs: fix pair integration subnet in diagram, add to examples index

- Fixed network topology diagram in pair README: 192.168.10.x -> 192.168.1.x
  to match the actual code (OPNsense boots on .1 of 192.168.1.0/24)
- Added explanation of NIC juggling to the diagram section
- Updated single-VM "What's next" to link to pair example (was "in progress")
- Added opnsense_pair_integration to examples/README.md table and category

2026-03-31 12:29:35 -04:00

2.1 KiB

Raw Permalink Blame History

OPNsense Firewall Pair Integration Example

Boots two OPNsense VMs, bootstraps both with automated SSH/API setup, then configures a CARP HA firewall pair using FirewallPairTopology and CarpVipScore. Fully automated, CI-friendly.

Quick start

# Prerequisites (same as single-VM example)
./examples/opnsense_vm_integration/setup-libvirt.sh

# Boot + bootstrap + pair test (fully unattended)
cargo run -p opnsense-pair-integration -- --full

What it does

Creates a shared LAN network + 2 OPNsense VMs (2 NICs each: LAN + WAN)
Bootstraps both VMs sequentially using NIC link control to avoid IP conflicts:
- Disables backup's LAN NIC
- Bootstraps primary on .1 (login, SSH, webgui port 9443)
- Changes primary's LAN IP from .1 to .2
- Swaps NICs (disable primary, enable backup)
- Bootstraps backup on .1
- Changes backup's LAN IP from .1 to .3
- Re-enables all NICs
Applies pair scores via FirewallPairTopology:
- CarpVipScore — CARP VIP at .1 (primary advskew=0, backup advskew=100)
- VlanScore — VLAN 100 on both
- FirewallRuleScore — ICMP allow on both
Verifies CARP VIPs and VLANs via REST API on both firewalls

Network topology

Host (192.168.1.10)
 |
 +--- virbr-pair (192.168.1.0/24, NAT)
 |         |              |
 |    fw-primary       fw-backup
 |    vtnet0=.2        vtnet0=.3
 |    (CARP VIP: .1)
 |
 +--- virbr0 (default, DHCP)
           |              |
      fw-primary       fw-backup
      vtnet1=dhcp      vtnet1=dhcp (WAN)

Both VMs boot with OPNsense's default LAN IP of 192.168.1.1. The NIC juggling sequence ensures only one VM has its LAN NIC active at a time during bootstrap, avoiding address conflicts.

Requirements

Same as the single-VM example: Linux with KVM, libvirt, ~20 GB disk space, ~20 minutes first run.

Commands

Command	Description
`--check`	Verify prerequisites
`--boot`	Boot + bootstrap both VMs
(default)	Run pair integration test
`--full`	Boot + bootstrap + test (CI mode)
`--status`	Show both VMs' status
`--clean`	Destroy both VMs and networks

2.1 KiB Raw Permalink Blame History