Jean-Gabriel Gill-Couture
6554ac5341
- 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
65 lines
2.1 KiB
Markdown
65 lines
2.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
1. Creates a shared LAN network + 2 OPNsense VMs (2 NICs each: LAN + WAN)
|
|
2. 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
|
|
3. 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
|
|
4. 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 |
|