medium riskcluster affecting~45 min

Runbook: Troubleshoot pfsync

1 · Prerequisites

Confirm every item is in place before any state change.

Two OPNsense appliances with pfsync configured
Access to the GUI on both appliances
A long-lived test session that can be used to validate replication

2 · Pre-checks

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

· Confirm the sync interface IP and the syncpeer IP on both appliances
· Capture the current pfsync state from the shell of both appliances with ifconfig pfsync0, noting syncdev, syncpeer and syncok
· Establish a long-lived TCP session (for example a download or an SSH connection) that can be observed during failover
· 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.

1From the shell of each appliance, run ifconfig pfsync0 and confirm syncdev names the dedicated sync interface, syncpeer names the other appliance's sync address, and syncok is 1
2Run pfctl -ss | wc -l on each appliance and compare the state counts. A large discrepancy indicates replication is not happening
3Capture on the sync interface with tcpdump -n -i <sync_if> proto pfsync and confirm packets are flowing between the two appliances. Filter on the protocol, not a port: pfsync is its own IP protocol, number 240, and carries no port number
4If no packets are flowing, check the firewall rules on the sync interface and confirm a pass rule for protocol PFSYNC (IP protocol 240) from the peer's sync address to this appliance's sync address is present, with the mirror-image rule on the peer
5Confirm the syncpeer IP is reachable from the sync interface (ping from the shell)
6Confirm the sync interface is not shared with any other traffic (such as management) that could saturate it
7If states are replicating but a failover still loses sessions, check the state table size and the pfsync peer configuration on both appliances
8If the replication count is stuck, re-apply the settings at System > High Availability > Settings > Save on both appliances, which reconfigures the pfsync interface
9Force a failover on the primary and confirm the long-lived test session survives the failover

4 · Verification

Confirm the procedure actually fixed the problem.

✓The state counts on both appliances match within a few percent
✓A forced failover on the primary does not drop a long-lived TCP session
✓pfsync packets are observed on the sync interface in both directions
✓The firewall log on the sync interface shows permitted pfsync traffic

5 · Rollback

If verification fails, undo the procedure in reverse order.

↶If pfsync is causing problems, disable Synchronise State on the secondary to stop the appliance from accepting replicated state
↶Revert the configuration to the last known-good backup under System > Configuration > Backups
↶If the sync interface is saturated, isolate the bulky traffic from the sync interface or move it to a dedicated link

6 · Escalation

When the runbook isn't enough, contact:

· Engage the network team if the sync interface is not passing traffic between the two appliances
· Engage the platform team if the firmware versions diverge on the two appliances
· Engage the on-call engineer if a failover causes a sustained outage rather than a brief blip

Purpose

Diagnose and restore pfsync state replication on an OPNsense HA pair so that established sessions survive a CARP failover.

When to use this runbook

Use this runbook when established sessions do not survive a failover, when the state table sizes on the two appliances are noticeably different, or when pfsync packets are not observed on the sync interface.

pfsync is carried directly over IP as protocol 240 and has no TCP or UDP port. Every filter in this runbook — in tcpdump and in the firewall rules — therefore selects a protocol rather than a port. An operator hunting for a port to open will not find one.

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.