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”
  • Online — whether the device is connected to NetDefense right now: online, offline, or unknown when NetDefense can’t tell.
  • 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.
  • Firmware track — the firmware track the device is in (fast, regular or stable), or Unmanaged, the default. Only registered devices, enabled or disabled, can join a track. ndcli firmware status lists the track of every device. ndcli device list and ndcli device describe don’t show it.

List Devices

Section titled “List Devices”

Open Devices in the sidebar. Each row shows the device’s status, OUs, agent version, last heartbeat and drift, and the filter bar narrows the list by name, status, OU or drift. See Devices list.

Describe a Device

Section titled “Describe a Device”

Click a device’s name in the Devices list. Its page shows live telemetry, the device’s OUs and VPN networks, its variable overrides and its drift status. See Device detail.

A device whose agent reports facts also gets a Facts block: its timezone, interfaces, OPNsense version, operating system and hostname.

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 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.

Open the pending device from Devices and click Approve, or choose Approve from its row’s … menu.

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

A device being re-bound can be approved only once it has registered with its rebind token. Until then, the approval is refused with DEVICE_REBIND_PENDING.

Remove a Device

Section titled “Remove a Device”

Removing a device is permanent; there’s no undo.

Open the device and click Delete, or choose Delete from its row’s … menu in the Devices list.

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.

If the device was in a firmware track, the cleanup also releases its firmware pin, and NetDefense removes its track membership and history with the device. See Firmware tracks on the firewall.

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.