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:
| Status | Meaning |
|---|---|
| PENDING | The 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. |
| ENABLED | Approved and active. The device receives configuration syncs and can participate in VPN networks. |
| DISABLED | Temporarily 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”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”ndcli device describe fw-hq-primaryName: fw-hq-primaryUUID: e2eb98b8-0ed3-11f1-8792-66a021937fa2Status: ENABLEDOrganization: example-orgOUs: productionVersion: 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_SYNCCreated: 2026-01-06 19:17:43Updated: 2026-02-20 19:17:43The 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.
ndcli device approve fw-lab-benchAfter approval, the device transitions to ENABLED and can be assigned to Organizational Units to start receiving configuration.