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

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

• 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.
• Auto-Sync — whether the device automatically pulls new configurations when changes are detected (see Sync Mechanism).

Tip

Enable Auto-Sync on all production devices. It ensures configuration changes propagate automatically without requiring manual intervention after each update.

List Devices

View in NDWeb

ndcli device list

╭───────────────────┬───────────┬────────────────┬─────────┬───────────┬───────────╮
│ Name              │ Status    │ OU             │ Version │ Heartbeat │ Synced At │
├───────────────────┼───────────┼────────────────┼─────────┼───────────┼───────────┤
│ fw-branch-austin  │ ● ENABLED │ branch-offices │ 2.3.9   │ 2m        │ 1d        │
│ fw-branch-chicago │ ● ENABLED │ branch-offices │ 2.4.0   │ 1m        │ 3h        │
│ fw-branch-denver  │ ● ENABLED │ branch-offices │ 2.4.0   │ now       │ 3h        │
│ fw-guest-lobby    │ ● ENABLED │ guest-networks │ 2.4.1   │ now       │ 5m        │
│ fw-hq-primary     │ ● ENABLED │ production     │ 2.4.1   │ now       │ 5m        │
│ fw-hq-secondary   │ ● ENABLED │ production     │ 2.4.1   │ now       │ 5m        │
│ fw-lab-bench      │ ◐ PENDING │ -              │ -       │ now       │ Never     │
│ fw-staging-01     │ ● ENABLED │ staging        │ 2.4.1   │ now       │ 1h        │
╰───────────────────┴───────────┴────────────────┴─────────┴───────────┴───────────╯

Notice fw-lab-bench is PENDING with no OU, version, or sync history — it just registered and is waiting for approval.

Describe a Device

View in NDWeb

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
Auto-Sync:    true

Heartbeat:    2026-02-20 19:17:31 (4m)
Synced At:    2026-02-20 19:16:43 (5m)
Synced Hash:  sha256:74cdf4051f6adc...
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.

Approve a Device

View in NDWeb

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

ndcli device approve fw-lab-bench

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