Sync & Delivery

The sync mechanism is how configuration changes propagate from NetDefense to devices. Whenever you modify a snippet, change a template, or reassign an OU, the affected devices need to receive the updated configuration.

How Sync Works

NetDefense computes a SHA-256 hash of the expected configuration payload for each device, based on its current OU assignments, templates, snippets, and variables. This hash is compared against the hash stored from the device’s last successful sync.

• SYNCED — the device’s active configuration matches the current expected hash. No action needed.
• NOT SYNCED — the hashes differ, meaning configuration changes have been made since the device last synced.

The sync hash is calculated based on the origin policy and kept in the NetDefense database, not on the device itself.

Caution

If a device’s local configuration is changed manually and drifts from the NetDefense policy, a normal sync will not reapply the configuration because the hashes still match. Use --force to push the configuration regardless of hash state.

Drift Detection

In addition to the hash-based sync state, NetDefense tracks a drift status for each device. Where the sync hash answers “does the device have the latest configuration we sent?”, the drift status answers “is the device’s running configuration still what we last delivered?”.

Drift Status	Meaning
IN_SYNC	The running configuration matches the last-delivered configuration. No action needed.
DRIFT	The running configuration has diverged from the last sync. A manual change was likely made directly on the device.
NEVER_SYNCED	The device has never received a sync. No baseline to compare against.
UNKNOWN	Drift information has not yet been collected for this device.
ERROR	The drift check itself encountered an error on the device.

A DRIFT status does not block syncs — it’s informational. Running ndcli sync apply --device <name> (with or without --force) will push the current expected configuration and clear the drift.

Tip

Use --drift-status DRIFT to quickly find all devices that have diverged from their last sync:

ndcli device list --drift-status DRIFT
ndcli sync status --drift-status DRIFT

Triggering syncs

Today, every sync is operator-initiated: configuration only reaches a device when someone runs ndcli sync apply (or the equivalent web action), which queues a sync task that the device executes the next time NDAgent connects to NetDefense. NetDefense doesn’t push changes on its own.

Auto-Sync Soon

A future release will let devices opt into pulling new configuration on their own — the Auto-Sync column already shown in ndcli sync status is the placeholder for that flag. Until that ships, the column has no effect on behaviour: every sync still requires an explicit trigger.

Check Sync Status

View in NDWeb

ndcli sync status

╭───────────────────┬────────────────┬───────────┬───────────┬──────────────┬──────────────╮
│ Device            │ OU             │ Auto-Sync │ Synced At │ Status       │ Drift        │
├───────────────────┼────────────────┼───────────┼───────────┼──────────────┼──────────────┤
│ fw-branch-austin  │ branch-offices │ Yes       │ 1d        │ ○ NOT SYNCED │ ⚠ DRIFT      │
│ fw-branch-chicago │ branch-offices │ Yes       │ 3h        │ ● SYNCED     │ ✓ IN_SYNC    │
│ fw-branch-denver  │ branch-offices │ Yes       │ 3h        │ ● SYNCED     │ ✓ IN_SYNC    │
│ fw-guest-lobby    │ guest-networks │ Yes       │ 5m        │ ● SYNCED     │ ✓ IN_SYNC    │
│ fw-hq-primary     │ production     │ Yes       │ 5m        │ ● SYNCED     │ ✓ IN_SYNC    │
│ fw-hq-secondary   │ production     │ Yes       │ 5m        │ ● SYNCED     │ ✓ IN_SYNC    │
│ fw-staging-01     │ staging        │ No        │ 1h        │ ○ NOT SYNCED │ ✓ IN_SYNC    │
╰───────────────────┴────────────────┴───────────┴───────────┴──────────────┴──────────────╯

Total: 7 devices

Reading this output:

• fw-staging-01 shows NOT SYNCED because no one has triggered a sync since its last config change — the policy is updated, the device just hasn’t been told to apply it yet.
• fw-branch-austin also shows NOT SYNCED, but its last sync was over a day ago and it’s running an older agent version (2.3.9). Worth investigating connectivity or agent freshness before retrying.
• The other devices are all SYNCED with recent sync times, indicating healthy operations.

Trigger Sync

View in NDWeb

Manually push configuration to a specific device:

ndcli sync apply --device fw-staging-01

Or sync all devices in an OU at once:

ndcli sync apply --ou production

You can also use --force to push the configuration even if the hashes already match, which is useful for troubleshooting or to override drifted configurations due to local changes.

Removing snippets from templates

Most snippet types behave symmetrically: attaching a snippet creates the entry on the device; detaching it (and triggering a sync) removes the entry on the device. NDAgent identifies its own entries by an ownership marker — a UUID prefix or a name prefix, depending on the snippet type — and on every sync it diffs the device’s managed entries against the desired set from your templates, deleting anything in the former but not the latter.

A few snippet types are asymmetric by design: removing them from a template does not undo what was already applied on the device. These are always singleton configurations (one record per device, no concept of “delete the row”) where the safest default is to stop pushing changes rather than guess what “removed” should mean.

Currently asymmetric snippet types

Snippet type	What detach does	How to undo
ZABBIX_SETTINGS	Device keeps the last-applied Zabbix Agent configuration. Sync stops touching Services › Zabbix Agent › Settings.	Push a ZABBIX_SETTINGS snippet with "enabled": false to disable the agent, or edit the original values directly in the OPNsense UI.

The companion list snippet types (ZABBIX_USERPARAMETER, ZABBIX_ALIAS) follow the symmetric rule — detach + sync removes them from the device.

Why the asymmetry

For symmetric snippet types — firewall aliases, firewall rules, Unbound host overrides / forwards / aliases / ACLs, Zabbix UserParameters, Zabbix item-key aliases, WireGuard servers/peers — “delete” is a well-defined operation: NDAgent knows which records it created (by UUID prefix or name prefix) and can DELETE each one through the OPNsense REST API.

For a singleton config tree there’s no analogous operation. Imagine detaching ZABBIX_SETTINGS from a template: should that:

1. Leave the device alone (current behavior) — last-applied settings persist, sync stops touching them.
2. Reset to OPNsense defaults — NDAgent would have to know the plugin’s defaults, which drift across OPNsense versions.
3. Disable the service entirely — surprise outage if the template was detached for an unrelated reason.

Option 1 is the conservative default. Detaching a singleton snippet is treated as “stop managing this config from NetDefense” rather than “revert this config on the device”. Disabling the service is an explicit operator action, not a side effect of template reorganization.

Tip

Rule of thumb: if a snippet type maps to a list of records on the device, removing it cleans up. If it maps to a single config tree (settings panel, mode switch, etc.), removing it stops further updates without undoing prior pushes.

If future snippet types introduce additional singleton configurations, they’ll be added to the table above with the same semantics.