OPNsense High Availability with CARP: Active-Passive Failover Setup

OPNsense supports active-passive HA using CARP (Common Address Redundancy Protocol) for virtual IPs and pfsync for connection state synchronization. When the primary node fails, the secondary takes over in under a second with existing TCP sessions intact.

Architecture

ISP → [CARP VIP on WAN] → Primary OPNsense ←→ pfsync ←→ Secondary OPNsense
                                         ↓
                           [CARP VIP on LAN] → Managed Switch → LAN

Both nodes have:

• WAN interface (real IPs from ISP — you need two IPs or VLAN)
• LAN interface
• SYNC interface (dedicated link between nodes for pfsync + config sync)

Hardware

Two identical or compatible units. Common homelab pairs:

• Two Protectli FW4C units
• Two Topton N5105 mini-PCs with identical NIC cards

The sync interface needs at least a direct crossover cable or a dedicated switch port between the nodes.

Step 1: Network addressing plan

Node	WAN IP	LAN IP	SYNC IP
Primary	203.0.113.2/30	192.168.1.2/24	172.16.0.1/30
Secondary	203.0.113.3/30	192.168.1.3/24	172.16.0.2/30
CARP VIP WAN	203.0.113.4	—	—
CARP VIP LAN	—	192.168.1.1	—

Step 2: Configure the primary node

Create CARP virtual IPs

Interfaces → Virtual IPs → Add:

• Type: CARP
• Interface: WAN
• IP address: 203.0.113.4/30
• Virtual IP password: (shared secret, same on both nodes)
• VHID group: 1
• Advertising frequency: Base 1 / Skew 0 (primary always advertises faster)

Repeat for LAN CARP VIP.

Enable pfsync

Interfaces → Assignments → add the SYNC interface. Then:

System → High Availability → Settings:

• Synchronize states: ✓
• Synchronize interface: SYNC
• Synchronize peer IP: 172.16.0.2

Configure firewall rule for pfsync traffic

On the SYNC interface, allow pfsync protocol from 172.16.0.2.

Step 3: Configure the secondary node

Mirror the interface configuration with the secondary IPs. In HA settings:

• VHID Skew: 100 (secondary advertises slower — primary wins by default)

Enable XMLSync to push config changes from primary to secondary: System → High Availability → Settings → Synchronize config to IP: 172.16.0.2

Step 4: Verify failover

# On a LAN client, ping the CARP LAN VIP continuously
ping 192.168.1.1

# Reboot the primary
# Observe: ping continues after ~1 second gap
# Secondary takes over the CARP VIP

Check System → High Availability → Status on both nodes to confirm MASTER/BACKUP state.

Common pitfalls

• Both nodes showing MASTER — pfsync traffic is being blocked; check SYNC interface firewall rules
• Sessions not surviving failover — pfsync not configured or sync latency too high
• Config sync not working — verify root SSH keys are exchanged between nodes, or use password auth for XMLSync

Coming from pfSense? pfSenseLab ↗ has a CARP comparison between OPNsense and pfSense implementations.