Configuration synchronisation — versioning and conflicts

Config sync is a feature that can fail silently if the two nodes disagree about which configuration is canonical. This lesson covers the failure modes and the recovery.

How config sync resolves the canonical version

Each OPNsense node carries a configuration revision number that increments with every save. When the BACKUP pulls the MASTER’s configuration, it compares the revision. If the MASTER’s revision is higher, the BACKUP applies it. If the BACKUP’s revision is higher (because a change was made locally and not synced), the BACKUP rejects the sync.

This is intentional: the BACKUP will not overwrite its own configuration with the MASTER’s. The operator must explicitly reconcile.

Symptoms of a config sync version drift

The symptoms:

• The BACKUP’s GUI shows older rules than the MASTER’s.
• The BACKUP logs show config sync failed or similar messages.
• A change made on the MASTER does not appear on the BACKUP after the next poll.
• Failover moves traffic to the BACKUP, and the BACKUP does not have the rules the MASTER had — connections break.

Why version drift happens

The most common causes:

1. A change was made on the BACKUP directly. The most common operator error.
2. A restore was performed on the BACKUP (e.g., from a backup file). The restored configuration has its own revision history.
3. A failed sync was retried with a stale cached configuration on the BACKUP.
4. Clock skew between the two nodes, which can affect revision ordering if revisions are timestamp-based.

Recovery from a version drift

The recovery procedure:

1. Identify which node has the canonical configuration (the one the operator believes is correct).
2. On the other node, force a pull from the canonical node: configctl filter sync or the GUI equivalent.
3. If that fails because the local revision is higher, manually reconcile:
   • On the drifting node, export the configuration.
   • Compare it to the canonical.
   • Decide which changes are real and which are stale.
   • Apply the correct configuration to the drifting node.

Prevention: the discipline

The discipline that prevents drift:

• MASTER for changes. Operators only make changes on the MASTER. The BACKUP is treated as read-only.
• GUI for changes. Changes via the supported GUI/API flow are tracked by revision. SSH-level edits to /conf/backup/.../filter.conf are not.
• No restores on the BACKUP. A restore brings its own revision history. Restores happen during a maintenance window with explicit manual reconciliation.
• Backups are versioned. Every backup file is named with the date and stored in a way that makes the chronology obvious.

Audit the audit trail

OPNsense records every configuration change in the system log. The audit log answers “who changed what, when”. A regular review of the audit log catches drift before it becomes a security issue.

The review is part of the monthly checklist for the HA estate.