Runbook: Configure Multi-WAN

Purpose

This runbook configures Multi-WAN on OPNsense: a second ISP uplink is added, gateway tiers are set, and outbound NAT and policy routing are wired so traffic fails over and recovers predictably. It is the runbook to reach for whenever the design requires more than one internet path.

When to use this runbook

Use this runbook when a second ISP is being added for redundancy or capacity, and the existing single-WAN deployment is stable. It assumes the design decision (failover-only vs load-balanced) has already been made and approved.

Pre-checks

• Capture a fresh encrypted config backup before any change.
• Confirm both ISPs are physically up and link LEDs are on the relevant NICs.
• Confirm the second WAN IP plan: static (with the ISP-supplied /29 or /30), DHCP, or PPPoE credentials.
• Confirm the change is approved and recorded in the change management system.
• Notify stakeholders of the planned failover window if the failover test will drop traffic.

Procedure

1. Assign the new interface. Go to Interfaces > Assignments, pick the new NIC from the dropdown, click +, and Save.
2. Configure the new OPT (WAN2) interface. Click the new OPT entry. Check Enable interface. Set IPv4 configuration type to Static IPv4, DHCP, or PPPoE per the ISP. Set IPv6 configuration type to None unless there is a concrete IPv6 plan. Save and Apply.
3. Confirm WAN2 obtains an address. At the shell, ifconfig <new_wan> shows an IP and netstat -rn shows a default route via the new gateway. If the route is missing, the ISP hand-off is not yet active.
4. Configure the gateway in System > Gateways. The new gateway is auto-created on interface assignment. Edit it: set a descriptive name (e.g. WAN2_GW), pick the correct monitor IP (the ISP gateway on-link, or a stable public IP like 1.1.1.1), and disable Far Gateway if the gateway is on-link.
5. Set the gateway tier. Pick Tier 1 for primary, Tier 2 for failover, Tier 3 for backup-only. Different tiers in the same group do not load-balance; tiers only matter within the same group.
6. Create a gateway group. System > Gateway Groups > +. Name (e.g. WAN_FAILOVER), set Tier 1 to WAN1, Tier 2 to WAN2. Set Trigger level to Member down (failover) or Packet loss (more aggressive). Save.
7. (Optional) Create a load-balance group. Create a second gateway group with both WANs at Tier 1 for load-balanced mode. For sticky load balancing, combine this with a policy-routing rule that uses the group plus a sticky-address firewall rule option.
8. Switch outbound NAT to Hybrid mode. Firewall > NAT > Outbound > Manual outbound NAT rule generation > Save & Apply. Click Generate rules to recreate the per-interface mappings.
9. Verify the auto-generated NAT rules. Confirm both internal subnets are now mapped to each WAN address. Add custom rules below for source-specific pinning (e.g. a server that must always egress on WAN2).
10. Add policy-routing rules. Firewall > Rules > LAN > + for an Allow rule that sets Gateway to the new gateway group. This binds LAN traffic to the failover group.
11. Set DNS. System > Settings > General > set DNS servers to ones reachable on both WANs, or leave at the ISP defaults and accept that DNS may use the active WAN only.
12. Save and apply all changes. Then test failover by physically disconnecting WAN1 (or set the WAN1 gateway to Disabled in System > Gateways).
13. Watch the gateway log. System > Log Files > Gateways. Apinger should mark WAN1 as down within the monitor interval (default ~10 seconds).
14. Test from an internal host. curl -4 https://ifconfig.me should show the WAN2 IP within a few seconds of WAN1 going down.
15. Reconnect WAN1. Apinger should mark it as up and traffic should return to WAN1 within the recovery interval (~10 seconds + delay).
16. Document the gateway IPs, tiers, and the failover/recovery test results in the change record.

Verification

• Both WAN interfaces show status: active and a valid public IP.
• In System > Gateways, both gateways show as Online initially.
• Failing over WAN1 flips the LAN egress IP to WAN2 within ~15 seconds (one apinger cycle).
• Reconnecting WAN1 returns egress to WAN1 within ~30 seconds (one cycle + recovery delay).
• pfctl -sn shows outbound NAT rules mapping each internal subnet to the active WAN.
• pfctl -sr shows the LAN policy-routing rule bound to the gateway group.

Rollback

• Disable the multi-WAN gateway group and revert the LAN rule’s gateway to default.
• Switch outbound NAT back to Automatic (or the prior mode) and apply.
• Disable the second WAN interface and remove its assignment.
• Restore the pre-change encrypted config backup from System > Configuration > Backups.
• Re-patch the switch port the second WAN NIC was on back to its prior state.
• Confirm all egress traffic is back on the original WAN within a minute.

Escalation

• Escalate to the ISP if the second WAN never obtains an address; confirm the line is active and the credentials/PVC/VLAN match.
• Escalate to the network team if failover occurs but traffic still drops; suspect asymmetric routing or a NAT rule pinned to the wrong WAN.
• Escalate to security if the second WAN opens a new path to the internet that bypasses existing egress filtering; require the change record to explicitly approve the new path.
• Escalate to the application owner if a specific application breaks on failover; common with applications that hard-code DNS or that pin to a specific IP.