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

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