Updating

The NetDefense plugin ships through OPNsense’s standard package system, so updates flow through the same channels as everything else on the device.

Automatic Updates

Tip

If you installed NetDefense using the repository method, the plugin will be automatically updated during regular OPNsense system updates.

The NetDefense repository is registered alongside the official OPNsense repositories. In practice:

• NetDefense updates are included in standard pkg upgrade operations
• Updates apply during scheduled firmware updates
• No manual steps are needed for routine updates

Devices in a firmware track

A device in a firmware track is held at an exact OPNsense release. Between its track’s windows, OPNsense’s own Check for updates and Update see nothing newer than that pin from OPNsense’s repositories. The NetDefense repository isn’t pinned, so the agent keeps updating as described here. See Firmware tracks on the firewall.

Updating via System Updates

The easiest way to keep NetDefense updated is through OPNsense’s built-in update system:

1. Navigate to System > Firmware > Updates

2. Click Check for updates

3. If updates are available (including NetDefense), click Update

4. The system will download and apply all available updates

NetDefense updates will be applied along with any other pending updates.

Scheduled Updates

If you have configured automatic updates in OPNsense, NetDefense will be updated automatically:

1. Navigate to System > Settings > Cron

2. Verify your firmware update schedule

3. NetDefense updates will be included in these scheduled updates

Note

We recommend keeping your OPNsense system on a regular update schedule to receive security patches and new features promptly.

Manual Updates

Via Command Line

If you prefer to update NetDefense specifically or need to update outside the normal schedule:

Repository Update

pkg update -f

pkg upgrade os-netdefense

pkg upgrade

Manual Package

For manual package updates (air-gapped environments):

1. Download the latest package from the repository

   curl -L -O https://repo.netdefense.io/prod/opnsense/os-netdefense-X.Y.Z.pkg

2. Transfer to OPNsense device

   scp os-netdefense-X.Y.Z.pkg root@your-opnsense-ip:/tmp/

3. Install the update

   ssh root@your-opnsense-ip
   pkg add -f /tmp/os-netdefense-X.Y.Z.pkg

4. Restart the service

   service ndagent restart

Checking Current Version

Via Web Interface

The installed plugin version can be found at:

System > Firmware > Plugins

Look for os-netdefense in the list of installed plugins.

Via Command Line

pkg info os-netdefense

This displays the installed version along with other package details.

Update Notifications

OPNsense surfaces update notifications in the web interface when new versions are available:

• A notification badge appears on the System menu
• Available updates are listed on the System > Firmware > Updates page

Version Compatibility

OPNsense Compatibility

NetDefense supports:

• OPNsense 26.1.11 and later
• FreeBSD 14 and FreeBSD 15 base systems (amd64)

On an earlier release, upgrade OPNsense first — see Prerequisites.

Update Safety

Updates preserve:

• All configuration settings
• Device registration status
• Log history

Upgrade Notes

Agent 1.27.0 and Series Upgrade Checks

From 1.27.0:

• A remote session ends when its client leaves. When the relay reports that the client is gone, the agent ends its side at once, and the session’s task completes with Relay session ended: client disconnected. A session no client joins within 5 minutes completes with client never connected, where it used to fail. The task’s messages start with “Relay session” where they said “Pathfinder session”.
• A major firmware upgrade always runs its own firmware check first, even with --no-check, and waits up to 3 minutes for it. It asks OPNsense for the upgrade only when that check offers the next series. A run that was asked to skip the check says so: its result carries check_first_ignored, and a failure ends with A series upgrade always checks first; check_first=false was ignored. See run firmware-upgrade.
• A used re-bind token is cleared at once. The agent clears the Re-bind Token field in the same run that used it, as soon as the device is registered again, instead of at a later start. See Re-binding.
• The sync summary counts software changes. Packages and plugins a software policy installs or removes, and package repositories it writes or removes, are counted with the other changes.
• Cleaner logs on shutdown. Stopping the agent no longer logs its WebSocket read ending as an error. A plugin helper that exits without a report now says why in the task error, and a configuration save run from a terminal is no longer cut off when the session drops or someone presses Ctrl-.

Agent 1.26.0 and Crash Restarts

From 1.26.0:

• The agent restarts itself after a crash. It starts again about 30 seconds after it stops unexpectedly. During those seconds, OPNsense’s service status can show it as stopped.
• Crash output reaches the agent log. What the agent prints when it crashes, or when it fails before its own logging starts, now appears in its log under Services > NetDefense > Log File.
• Backups never capture a half-written configuration. A backup waits for a configuration save in progress and takes only a complete file. If the file stays incomplete, the backup fails instead.
• Configuration writes aren’t cut off mid-save. The agent and the plugin let a save to config.xml finish, even when they are asked to stop.
• Plugins a software policy installs or removes join or leave OPNsense’s plugin list, as when you install or remove them under System > Firmware > Plugins. A device an earlier agent managed is set right at its next sync. Package installs also run with the device’s PATH, so they no longer print sh: syslog-ng: not found.
• A managed alias whose uuid changes moves to the new uuid without breaking what refers to it. An alias nothing refers to moves in the same sync; one still in use keeps its old uuid, with a warning, until nothing refers to it. See The managed uuid.

The upgrade switches the agent’s service to the new layout by itself; there is nothing to do.

Agent 1.25.0 and Firmware Tracks

From 1.25.0, the agent can hold a device at an exact OPNsense release and apply a firmware track’s updates at its windows. A device on an older agent can be put in a track, but is sent nothing until its agent is upgraded. See Firmware tracks on the firewall.

The same release can run a series upgrade, OPNsense 26.1 to 26.7, when a firmware track whose switch is on sends one. A series upgrade takes the firewall offline, reboots it three times and has no automatic rollback, and it is off for every track until you switch it on. Read Series Upgrades first.

Agent 1.23.0 and Managed Rules and Aliases

From 1.23.0, a rule or alias snippet describes the whole object, and PREPEND and APPEND rules are placed within each OPNsense rule section — see RULE and ALIAS fields and Where Rules Land on the Device. The first sync that reaches a device after its agent is upgraded can change the device even if no template changed:

• PREPEND rules an older agent placed after the device’s own rules move ahead of them. On OPNsense 26.7 the default LAN allow rules sit at sequence 1 and 11, which older agents’ PREPEND rules came after.
• To make room, the device’s own rules can get higher sequence numbers. Each change is a separate configuration revision on the device, and each is listed in the sync result.
• A setting made by hand on a managed rule or alias, and missing from its snippet, is reset to OPNsense’s default: an alias’s GeoIP address families, URL-table refresh and authentication, expiry or categories, or a rule’s logging, for example.
• A rule or alias whose snippet sets a field the device’s OPNsense doesn’t have is refused, and the device keeps the one it had.

Repository installs upgrade with OPNsense

A device installed from the NetDefense repository upgrades the agent automatically with its OPNsense updates, so there may be no separate moment to prepare. Before that device’s next OPNsense update, pull the managed aliases and rules that have settings made by hand, and copy what you want to keep into their snippets — see Agent and OPNsense versions. Once those fields are in the snippets, builds for a device on an older agent are refused with SNIPPET_AGENT_TOO_OLD until its agent is upgraded, so upgrade it soon after — see Manual Updates.

Agent 1.22.1 and OPNsense Update Checks

From 1.22.1, the agent checks for OPNsense updates every 6 hours, give or take up to 25 minutes so that a fleet doesn’t check all at once. It also checks once after each boot of the firewall, after the installed OPNsense version changes, and after a firmware upgrade run through NetDefense. Older agents checked every 15 minutes.

Each check downloads about 0.5 MB from the OPNsense mirror. A check you start yourself under System > Firmware counts as well: the agent picks up its result at its next refresh, within 15 minutes. The Dashboard and each device page show when the device last checked.

Agent 1.21.0 and TLS-Inspection Proxies

A firewall behind a TLS-inspection proxy disconnects after this upgrade

From 1.21.0, the agent checks its connection to NetDefense only against public root certificates built into the agent, never against the firewall’s certificate store. An agent whose traffic to NetDefense passes through a TLS-inspection proxy disconnects after upgrading, and stays offline until the proxy’s CA certificate is set in Extra CA File.

A firewall that reaches NetDefense directly needs nothing. For one behind an inspection proxy, including one that updates automatically with OPNsense:

1. Before the upgrade, save the proxy’s CA certificate on the firewall, where only root can change it — see Extra CA File for the requirements.

2. Right after the upgrade, enter its path in Services > NetDefense > Settings, under Advanced Settings, Control Plane, Extra CA File, and click Apply.

Do this on the firewall itself, through its web interface or a root shell. A NetDefense remote session can’t reach a device while it’s offline.

Post-Update Verification

After updating, verify the plugin is working correctly:

1. Check the service status

   service ndagent status

2. Review the logs for any errors

   Navigate to Services > NetDefense > Log File

3. Verify connectivity in your NetDefense dashboard

   The device should remain online and connected after the update.

Troubleshooting Updates

Update Fails to Apply

If the update process fails:

1. Clear the package cache and retry:

   pkg clean -a
   pkg update -f
   pkg upgrade os-netdefense

2. Check for dependency conflicts:

   pkg check -d

Service Doesn’t Start After Update

If the agent fails to start after an update:

1. Check the logs:

   tail -50 /var/log/ndagent.log

2. Verify configuration integrity:

   Navigate to Services > NetDefense > Settings and click Apply

3. Manually restart the service:

   service ndagent restart

See the Troubleshooting guide for more detailed solutions.