pfsync configuration on OPNsense

Configuring pfsync correctly is the difference between an HA pair that survives failover and one that drops every connection. This lesson walks through the configuration step by step.

The sync interface

The sync interface is a dedicated physical or virtual interface between the two firewalls. It is not on any production VLAN. It carries only pfsync traffic (and optionally the configuration synchronisation traffic).

The address scheme is typically a /30 from a documentation range:

FW-A sync: 10.99.0.1/30
FW-B sync: 10.99.0.2/30

A /30 has exactly two usable addresses — one for each firewall. This is the cleanest possible design: nothing else can have an address on this segment.

Configuring the sync interface on OPNsense

The sync interface is configured like any other interface:

1. Assign a physical interface (e.g., ix1) under Interfaces → Assignments.
2. Give it a static IP (10.99.0.1/30 on FW-A, 10.99.0.2/30 on FW-B).
3. Add a pass rule on the sync interface for protocol PFSYNC, source the peer’s sync address, destination this node’s sync address. pfsync has no port — it is its own IP protocol, number 240 — so the rule selects a protocol, not a port. Add the mirror-image rule on the other node.
4. Do not add firewall rules that allow production traffic. The sync interface should be reachable only by pfsync and config sync.
5. Block everything else with an explicit Block any → any rule.

$ ifconfig pfsync0

pfsync0: flags=0<> metric 0 mtu 1500
      groups: pfsync
      syncdev: ix1 syncpeer: 10.99.0.2 maxupd: 128 defer: off
      syncok: 1

Configuring pfsync

Under System → High Availability → Settings:

• Synchronize all states via: the sync interface (e.g., ix1 or the OPT interface assigned to the sync network). Leaving this unset disables state synchronisation entirely.
• Synchronize peer IP: the other node’s sync IP. Left blank, pfsync uses the multicast group 224.0.0.240 on the sync interface instead.
• Sync compatibility: the pfsync protocol version both nodes should speak. It matters during a rolling upgrade, when the two nodes are briefly on different releases.

Save the configuration. The pfsync0 virtual interface comes up. State replication begins.

Verifying replication

The verification is on both nodes:

1. On FW-A, run pfctl -s state | wc -l. Note the count.
2. On FW-B, run the same command. The count should be within 1% of FW-A’s.
3. Open a new connection (e.g., curl https://192.0.2.10) from a LAN host. The state for that connection appears on FW-A.
4. Within a fraction of a second, the same state appears on FW-B.

pfctl -s state prints addresses, never hostnames, so grep for the server’s IP rather than its DNS name:

$ pfctl -s state | grep -c '192.0.2.10:443'

1

If FW-B shows 0 where FW-A shows the entry, or if the totals from step 2 diverge and stay diverged, replication is broken.

Common misconfigurations

The most common pfsync mistakes:

1. Sync interface on the production data path. pfsync will work, but the security model is broken — anyone on that path can inject pfsync packets.
2. Peer IP is wrong. Replication silently fails. The symptom is divergence of state counts after a few minutes.
3. Sync interface is firewalled and blocks pfsync. The rules on the sync interface must pass IP protocol pfsync (240) between the two sync addresses, in both directions. Operators who look for a port to open find nothing, because pfsync has no port.
4. MTU mismatch. If the sync interface has a smaller MTU than the rest, large pfsync packets will fragment and may be dropped. Set MTU explicitly.
5. Multicast routing. If the sync interface is on a shared switch with multiple segments, ensure multicast is not blocked between the segments.