Skip to content

Devices

A device represents a firewall appliance (an OPNsense instance) managed by NetDefense. Each device runs the NDAgent daemon, which connects back to NetDefense to receive configuration updates, report heartbeats, and execute tasks.

Device Lifecycle

Section titled “Device Lifecycle”

Devices go through these states:

StatusMeaning
PENDINGThe device has registered itself using the organization’s registration token, but an administrator has not yet approved it. No configuration is delivered in this state.
ENABLEDApproved and active. The device receives configuration syncs and can participate in VPN networks.
DISABLEDTemporarily deactivated by an administrator. The device record is preserved but no syncs are delivered.

A typical flow: a new firewall is installed, NDAgent starts, it registers using the Registration Token, it appears as PENDING, then an admin approves it and it becomes ENABLED.

Key Device Fields

Section titled “Key Device Fields”
  • Version — the NDAgent software version running on the device. Useful for identifying devices that need updating.
  • Heartbeat — how recently the device checked in. A device that hasn’t sent a heartbeat in a long time may be offline or having connectivity issues.
  • Synced At — when the device last successfully applied a configuration. “Never” means it has never been synced. Configuration changes propagate when an operator triggers a sync — see Sync Mechanism.
  • Drift — whether the device’s running configuration matches what NetDefense last delivered. See Drift Detection for the full status breakdown.

List Devices

Section titled “List Devices”
Terminal window
ndcli device list
╭───────────────────┬───────────┬────────────────┬─────────┬───────────┬───────────┬──────────────╮
│ Name              │ Status    │ OU             │ Version │ Heartbeat │ Synced At │ Drift        │
├───────────────────┼───────────┼────────────────┼─────────┼───────────┼───────────┼──────────────┤
│ fw-branch-austin  │ ● ENABLED │ branch-offices │ 2.3.9   │ 2m        │ 1d        │ ⚠ DRIFT      │
│ fw-branch-chicago │ ● ENABLED │ branch-offices │ 2.4.0   │ 1m        │ 3h        │ ✓ IN_SYNC    │
│ fw-branch-denver  │ ● ENABLED │ branch-offices │ 2.4.0   │ now       │ 3h        │ ✓ IN_SYNC    │
│ fw-guest-lobby    │ ● ENABLED │ guest-networks │ 2.4.1   │ now       │ 5m        │ ✓ IN_SYNC    │
│ fw-hq-primary     │ ● ENABLED │ production     │ 2.4.1   │ now       │ 5m        │ ✓ IN_SYNC    │
│ fw-hq-secondary   │ ● ENABLED │ production     │ 2.4.1   │ now       │ 5m        │ ✓ IN_SYNC    │
│ fw-lab-bench      │ ◐ PENDING │ -              │ -       │ now       │ Never     │ NEVER_SYNCED │
│ fw-staging-01     │ ● ENABLED │ staging        │ 2.4.1   │ now       │ 1h        │ ✓ IN_SYNC    │
╰───────────────────┴───────────┴────────────────┴─────────┴───────────┴───────────┴──────────────╯

Notice fw-lab-bench is PENDING with no OU, version, or sync history — it just registered and is waiting for approval. fw-branch-austin shows DRIFT, meaning its running configuration has diverged from the last sync — worth investigating with ndcli device describe fw-branch-austin.

Describe a Device

Section titled “Describe a Device”
Terminal window
ndcli device describe fw-hq-primary
Name:         fw-hq-primary
UUID:         e2eb98b8-0ed3-11f1-8792-66a021937fa2
Status:       ENABLED
Organization: example-org
OUs:          production
Version:      2.4.1


Heartbeat:    2026-02-20 19:17:31 (4m)
Synced At:    2026-02-20 19:16:43 (5m)
Synced Hash:  sha256:74cdf4051f6adc...
Drift Status: IN_SYNC
Created:      2026-01-06 19:17:43
Updated:      2026-02-20 19:17:43

The Synced Hash is a SHA-256 fingerprint of the configuration currently active on the device. NetDefense compares this against the expected hash to determine whether the device is in sync.

Drift Status shows whether the running configuration on the device matches what NetDefense last delivered. See Drift Detection for the full list of values.

Approve a Device

Section titled “Approve a Device”

When a new device connects via NDAgent, it appears in PENDING status until approved.

Terminal window
ndcli device approve fw-lab-bench

After approval, the device transitions to ENABLED and can be assigned to Organizational Units to start receiving configuration.

Remove a Device

Section titled “Remove a Device”

Removing a device — with ndcli device remove <name> or from the device detail page in the web app — is permanent; there’s no undo.

Terminal window
ndcli device remove fw-lab-bench

Permanently deletes the device. On its next contact the device removes all NetDefense-managed configuration (firewall rules, aliases, VPN, users, external authentication servers, certificates and CAs, package repositories) except certificates and CAs still in use by a service, uninstalls the NetDefense agent and repository, and cannot be restored. Re-adding it requires a fresh installation.

A short log of the cleanup is left on the firewall at /var/log/ndagent-decommission.log. If the device used an external authentication server, check that log for a leftover authentication-server entry and rotate the directory’s bind password — see Removal.

Packages NetDefense installed on the device through a software policy are left alone — NetDefense doesn’t keep a record of them, so they simply stay installed and stop being managed.

If the device is offline when you remove it, decommissioning happens the next time it comes back online. Until then, it simply can’t reconnect — its control-plane record is already gone.

Adding the Same Firewall Back

Section titled “Adding the Same Firewall Back”

To bring a previously removed firewall back under NetDefense, run the installer again with the organization’s registration token — the same one-line install used for a first-time setup — then approve it once it appears.

It comes back as a brand-new device under its hostname. Nothing carries over from the earlier registration: no history, no OU or VPN membership, no variable overrides.