Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

advancedHigh availability~25 min

Break/Fix: pfsync Not Replicating States

Reported symptoms

  • ●Failover works but every active connection drops
  • ●pfctl -ss on the backup is empty or drastically smaller than the master
  • ●Established TCP sessions to internal services reset after failover

Evidence

  • · ifconfig pfsync0 reports syncok: 0, or names the wrong syncdev or syncpeer
  • · tcpdump -n -i <sync_if> proto pfsync: no pfsync traffic from the peer. There is no port to filter on — pfsync is its own IP protocol, number 240
  • · pfsync is configured but the firewall rule on the sync interface does not pass IP protocol pfsync (240)
Diagnosis and resolutionclick to reveal

Root cause

pfsync updates are not flowing between the nodes — either the sync interface or peer IP is wrong, or the rules on the sync interface do not pass IP protocol pfsync (240). Operators frequently look for a UDP or TCP port to open and find none, because pfsync has no port: it is carried directly over IP as protocol 240.

Remediation

1. Confirm System → High Availability → Settings names the sync interface under "Synchronize all states via" and the peer's sync address under "Synchronize peer IP" on both nodes. 2. Confirm ifconfig pfsync0 shows the expected syncdev and syncpeer and syncok: 1. 3. Add a pass rule on the sync interface for protocol PFSYNC from the peer sync IP to this node's sync IP, and the mirror-image rule on the peer. 4. Apply, then run tcpdump -n -i <sync_if> proto pfsync and confirm traffic in both directions. 5. Force a state build on the master and verify the backup sees it.

Verification

pfctl -ss on the backup shows the same state count as the master (within seconds). Failover test preserves long-lived TCP sessions.

Prevention

pfsync and CARP should be enabled together. Treat the sync interface rules as a single change with HA enable: IP protocol pfsync (240) between the two sync addresses, plus the XMLRPC config-sync traffic. CARP is a separate concern — its multicast, 224.0.0.18, belongs on each VIP's parent interface, not on the sync link. Verify with `pfctl -ss` on the backup before declaring HA healthy.

Scenario

You are operating an OPNsense HA pair in active/passive. The following symptoms appear:

  • Failover works but every active connection drops
  • pfctl -ss on the backup is empty or drastically smaller than the master
  • Established TCP sessions to internal services reset after failover

Available evidence:

  • ifconfig pfsync0 reports syncok: 0, or names the wrong syncdev or syncpeer
  • tcpdump -n -i <sync_if> proto pfsync: no pfsync traffic from the peer. There is no port to filter on — pfsync is its own IP protocol, number 240
  • pfsync is configured but the firewall rule on the sync interface does not pass IP protocol pfsync (240)

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XXVIII:

  1. Form hypothesis, find evidence, test, validate.
  2. Use the available evidence above to bound the search.
  3. Reach one of the likely root causes.

Recovery procedure

(Do not reveal until you have reasoned through the problem.)

  1. Identify the failing component.
  2. Apply the remediation pathway.
  3. Validate with the verification step.
  4. Document the incident.

Remediation

  1. Confirm System → High Availability → Settings names the sync interface under “Synchronize all states via” and the peer’s sync address under “Synchronize peer IP”, on both nodes. 2. Confirm ifconfig pfsync0 shows the expected syncdev and syncpeer, and syncok: 1. 3. Add a pass rule on the sync interface for protocol PFSYNC from the peer sync IP to this node’s sync IP, and the mirror-image rule on the peer. 4. Apply, then run tcpdump -n -i <sync_if> proto pfsync and confirm traffic in both directions. 5. Force a state build on the master and verify the backup sees it.

Verification

pfctl -ss on the backup shows the same state count as the master (within seconds). Failover test preserves long-lived TCP sessions.

Rollback

Disable pfsync on both nodes if needed. CARP failover still works without it, but every existing connection is dropped at the failover and has to be re-established by the client.

Prevention

pfsync and CARP should be enabled together. Treat the sync interface rules as a single change with HA enable: IP protocol pfsync (240) between the two sync addresses, plus the XMLRPC config-sync traffic. CARP is a separate concern — its multicast, 224.0.0.18, belongs on each VIP’s parent interface, not on the sync link. Verify with pfctl -ss on the backup before declaring HA healthy.