Skip to main content
RunBook Academy

← All runbooks in OPNsense

high riskcluster affecting~120 min

Runbook: Build an HA Pair

1 · Prerequisites

Confirm every item is in place before any state change.

  • Two identical OPNsense appliances with the same minor version installed
  • Dedicated sync interface between the two appliances (no switch in the path preferred)
  • CARP-capable upstream switch with multicast support
  • Maintenance window scheduled with the operations team

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

  • · Confirm both appliances boot, run the upgrade wizard, and reach the GUI on the management interface
  • · Confirm the time on both appliances is synchronised to within a second
  • · Plan the addressing: WAN shared IP, LAN shared IP, dedicated sync IPs, and per-appliance CARP VHID per shared subnet
  • · Confirm the firmware version is identical on both appliances

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

  1. 1On the primary appliance, configure the WAN and LAN interfaces with a per-appliance IP and the shared CARP IP as an alias
  2. 2On the primary appliance, configure the dedicated sync interface with a private IP on a /30 shared only with the peer, and add a pass rule on that interface for protocol PFSYNC (IP protocol 240) from the peer's sync address to this appliance's sync address — pfsync carries no port number, so the rule matches on the protocol alone
  3. 3On the primary appliance, navigate to System > High Availability > Settings and enable Synchronise State; set the sync interface to the dedicated link and the syncpeer to the secondary appliance IP
  4. 4On the primary appliance, under System > High Availability > Settings > Synchronise Config, enable the sections that should be replicated (typically rules, NAT, aliases, services)
  5. 5On the primary appliance, add a CARP virtual IP per shared subnet with a unique VHID and the lowest skew (defaults to 0 or 1 for the primary)
  6. 6On every interface that carries a CARP virtual IP, confirm the rules pass protocol CARP; the advertisements travel on that parent interface, not on the sync link
  7. 7On the secondary appliance, configure the same interfaces with per-appliance IPs and the same shared CARP IPs
  8. 8On the secondary appliance, configure the sync interface with an IP on the same subnet as the primary sync interface
  9. 9On the secondary appliance, enable Synchronise State pointing to the primary appliance IP
  10. 10Trigger a config sync from the primary and confirm the secondary GUI reflects the configuration change
  11. 11Power off the primary appliance and confirm the secondary takes over the CARP VIPs and that traffic continues to flow
  12. 12Power the primary back on and confirm it reclaims the VIPs and the secondary returns to backup

4 · Verification

Confirm the procedure actually fixed the problem.

  • ✓Both appliances show the same CARP status (master on primary, backup on secondary) and the VIPs are reachable from inside the LAN
  • ✓A forced failover on the primary causes the secondary to assume the VIPs within a few seconds
  • ✓Config sync replicates a test change (for example a new alias) from the primary to the secondary
  • ✓pf states are replicated via pfsync so an established session survives the failover

5 · Rollback

If verification fails, undo the procedure in reverse order.

  • ↶If the primary is unstable, leave it physically disconnected and let the secondary run as a single appliance
  • ↶Disable configuration synchronisation on the primary to stop it pushing bad configuration to the secondary, and disable Synchronise State on the secondary to stop it accepting replicated state
  • ↶Restore the previous single-appliance configuration on both devices if HA is abandoned

6 · Escalation

When the runbook isn't enough, contact:

  • · Engage the network team if the switch is not passing CARP multicast between the two appliances
  • · Engage the platform team if the firmware versions diverge and config sync must be temporarily disabled
  • · Engage the on-call engineer if a failover causes a sustained outage rather than a brief blip

Purpose

Build a two-node OPNsense HA pair with CARP virtual IPs for failover and pfsync over a dedicated link for state replication, and validate the pair with a forced failover.

When to use this runbook

Use this runbook when greenfielding a new HA pair, when rebuilding a pair after a hardware swap, or when converting a single-appliance deployment into a pair as part of a higher-availability engagement.

Pre-checks

Before starting the procedure, confirm the prerequisites and pre-checks are met. The structured lists are rendered from the frontmatter by the page layout.

Procedure

Follow the steps from the frontmatter procedure steps. The page layout renders the steps as a checklist with copy-to-clipboard affordances.

Verification

After the procedure, the structured verification items from the frontmatter are rendered as a checklist.

Rollback

If the procedure fails or makes things worse, follow the structured rollback steps from the frontmatter.

Escalation

The structured escalation path is rendered from the frontmatter. Use it if the operator cannot complete the procedure safely.

References

  1. OPNsense documentation — High Availability
  2. OPNsense documentation — Configure CARP
  3. FreeBSD — pfsync(4)