Skip to main content
RunBook Academy

← All break/fix scenarios in OPNsense

advancedHigh availability~30 min

Break/Fix: Config Sync Failed Between HA Nodes

Reported symptoms

  • ●A rule added on the master does not appear on the backup after the next sync
  • ●System → High Availability → Status: configuration sync "in error" or "no connection"
  • ●Service definitions (Unbound, DHCP, Suricata) drift between nodes

Evidence

  • · configd log on backup: XMLRPC sync connection refused / timeout to <master sync IP>
  • · No firewall rule on the sync interface for HTTPS (TCP/443) to the master from the backup
  • · Master System → High Availability → Settings: backup sync IP misconfigured
Diagnosis and resolutionclick to reveal

Root cause

Config sync uses XMLRPC over HTTPS to the master's sync IP. Either the sync IP is wrong on one side, the sync interface firewall rule blocks HTTPS, or the backup cannot resolve/reach the master's GUI port.

Remediation

1. Confirm both nodes list each other's sync IPs under System → High Availability → Settings. 2. Add an "Allow" rule on the sync interface for HTTPS from the peer sync IP. 3. From the backup, curl -k https://<master-sync-ip>/ shows the GUI. 4. Click "Synchronize to peer" on the master manually and watch configd.log.

Verification

Configuration sync reports OK; a rule added on the master appears on the backup within seconds; config diff job reports zero differences.

Prevention

Keep the master/backup sync IPs symmetric and routeable. Monitor config sync status via the API or your observability stack. Add a daily config-diff job that alerts if rules, aliases, or services diverge between nodes.

Scenario

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

  • A rule added on the master does not appear on the backup after the next sync
  • System → High Availability → Status: configuration sync “in error” or “no connection”
  • Service definitions (Unbound, DHCP, Suricata) drift between nodes

Available evidence:

  • configd log on backup: XMLRPC sync connection refused / timeout to <master sync IP>
  • No firewall rule on the sync interface for HTTPS (TCP/443) to the master from the backup
  • Master System → High Availability → Settings: backup sync IP misconfigured

Your task

Determine the cause, recover, document, and validate.

Investigation

The investigation follows the discipline taught in Part XXIX:

  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 both nodes list each other’s sync IPs under System → High Availability → Settings. 2. Add an “Allow” rule on the sync interface for HTTPS from the peer sync IP. 3. From the backup, curl -k https://<master-sync-ip>/ shows the GUI. 4. Click “Synchronize to peer” on the master manually and watch configd.log.

Verification

Configuration sync reports OK; a rule added on the master appears on the backup within seconds; config diff job reports zero differences.

Rollback

Disable HA sync temporarily; reconcile configs by hand or restore from a known-good backup.

Prevention

Keep the master/backup sync IPs symmetric and routeable. Monitor config sync status via the API or your observability stack. Add a daily config-diff job that alerts if rules, aliases, or services diverge between nodes.