Configuration synchronisation — what does and does not sync

Two firewalls in an HA pair should run the same configuration. Manually keeping them in sync is error-prone: an operator adds a rule to FW-A, forgets FW-B, and failover moves traffic to FW-B with the rule missing.

config sync solves this. It is a separate feature from pfsync. pfsync replicates state; config sync replicates configuration.

What config sync copies

OPNsense config sync copies the entire configuration between nodes:

• Interfaces and addresses
• Firewall rules
• NAT rules
• Aliases
• DHCP scopes
• DNS (Unbound) configuration
• WireGuard instances and peers
• IPsec configuration
• Certificates
• Users and groups (except local passwords, see below)
• Services configuration
• Cron jobs
• Routes

What config sync does NOT copy

The following are deliberately node-local and do not sync:

• Local passwords and API keys — the API key on the MASTER is different from the API key on the BACKUP. This is by design; sharing keys would defeat the audit trail.
• CARP configuration — each node has its own CARP state (MASTER vs BACKUP). The CARP VIPs themselves sync, but the master/backup state is per-node.
• Hostname — each node keeps its own hostname.
• System logs — local only.
• Local caches — Unbound’s cache, for example, is per-node.
• State table — handled by pfsync, not config sync.

How config sync works

The sync is pull-based. The BACKUP node periodically contacts the MASTER node over the sync interface (using a dedicated XMLRPC or HTTPS endpoint, depending on the version) and asks for the configuration. The MASTER returns the configuration, the BACKUP applies it.

$ configctl filter sync

The default sync interval is short (every few minutes). For operator-driven changes, the change can be pushed immediately rather than waiting for the next poll.

Configuring config sync

Under System → High Availability → Settings:

• Synchronise configuration: enabled.
• Synchronise to IP: the MASTER node’s sync IP (or its CARP management IP).
• Username / password: a service account on the MASTER with read-only access to the configuration.

The service account must have sufficient privileges to read the entire configuration. The OPNsense default is a built-in account for this purpose; the operator should not delete or disable it.

Verifying config sync

The verification is simple:

1. On the MASTER, make a small change (e.g., add an alias).
2. On the BACKUP, watch for the alias to appear within the poll interval.
3. On the BACKUP, check the configuration via GUI to confirm.

If the BACKUP does not receive the change:

• The sync service is not running on the MASTER.
• The service account credentials are wrong on the BACKUP.
• The firewall is blocking the sync traffic.
• The XMLRPC/HTTPS endpoint is unreachable.

Anti-pattern: configuration drift

If an operator makes a change on the BACKUP that the MASTER does not have, the next sync will overwrite the BACKUP’s change with the MASTER’s configuration. This is called “config drift” — the BACKUP and MASTER have different configurations for a period.

The mitigation is the change process: always make changes on the MASTER. The BACKUP is treated as read-only. If a change is needed on the BACKUP, the operator knows the next sync will overwrite it.

What about services that should be different on each node?

Some configuration should legitimately differ: CARP state, local passwords, hostname. These are excluded from config sync by design.

If the operator needs different firewall rules on each node (e.g., testing), they should be done in a dedicated test environment, not on a production HA pair.