Firmware Tracks on the Firewall

Firmware tracks hold a device at an exact OPNsense release. This page is for the person at the firewall: where the pin shows in OPNsense, what OPNsense’s own update screens do while it is there, and what happens to it when you change a setting, stop the agent or remove the plugin.

What the device needs

• The NetDefense agent 1.24.0 or later, and 1.25.0 or later for series upgrades. NetDefense sends nothing to an older agent.
• The plugin enabled and the device registered, with the agent’s OPNsense API credentials set up under Services > NetDefense > Settings. Without them a step is held with held_check_failed.
• OPNsense’s Community edition. A device with a subscription key, or a release type other than Community, is held and never pinned.

The pin

A device in a track is held at one release through OPNsense’s own firmware setting. In the OPNsense interface it is under System > Firmware > Settings, in the Flavour field, which is an advanced-mode field:

• Unpinned, it reads (default).
• Pinned, it reads (custom), and a text box under it holds the pin, for example 26.7/MINT/26.7.3/latest.
• When a Flavour is set, the page switches advanced mode on by itself, so the field is visible.

The pin names a folder of one release on OPNsense’s mirror: <series>/MINT/<release folder>/latest. The folder is the series alone for the GA release (26.7), <series>.N for a point release (26.7.3), and <series>.N_M for a hotfix folder made after a series’ final release.

OPNsense writes the pin into its generated repository files at boot, at every core post-install, on a firmware reload and on rc.syshook update. In /usr/local/etc/pkg/repos/OPNsense.conf an unpinned device has url: "https://pkg.opnsense.org/${ABI}/26.7/latest", and a pinned one ends in ${ABI}/26.7/MINT/26.7.3/latest.

The agent writes only the Flavour. It never writes the Mirror, Type, Subscription or Reboot settings of that form, and it never keeps the Subscription key in any of its fields.

What OPNsense’s update screens show while a device is pinned

The firewall’s Check for updates, the Update button and OPNsense’s automatic firmware update all read the pinned folder’s catalog. From OPNsense’s own repositories they see nothing newer than the pinned release, so when nothing else is pending, the Status tab reads There are no updates available on the selected mirror. Between windows, a pinned firewall isn’t offered a newer release by OPNsense’s repositories.

The pin is a guardrail, not a lock.

• Only OPNsense’s own repositories are pinned. The NetDefense repository, plugin repositories and any other repository you enabled aren’t, and still update.
• A release’s folder can take hotfix revisions, so a pinned device can still be offered a newer revision of the release it is pinned to. The agent treats the pin as unchanged afterwards.
• On the last release of a series, OPNsense still offers the next series, whatever the pin says. For a 26.1 device on its last release, the Status tab reads There are 3 updates available, total download size is 1.2GiB. This update requires a reboot. and the Updates tab offers Upgrade. The pin doesn’t hide that offer, and doesn’t stop an upgrade you start by hand, from the Upgrade button, the console menu, rc.firmware upgrade or a cron job. After one, the agent pins the device again on the new series at its first pass over the pin, and reports that the pin changed. The device stays in its track.

One update available

On some devices the first check at a pin lists one entry that is a reinstall of the OPNsense core package at the version it already has, and the Status tab reads There is 1 update available, total download size is <size>. No version moves. The agent counts these entries and ignores them: they never hold a window, and they never trigger a reinstall. After a series upgrade the first checks can show the same kind of entry for the NetDefense package and the core. Leave a tracked device’s updates to its track.

What a step does on the firewall

Joining a track is an enroll. The agent checks the device, writes the pin at the release it has installed, forces a check, and judges what the check lists. If the check lists a downgrade, another FreeBSD version, a core, base or kernel entry beyond the installed release, a pending base or kernel, or a package added or removed, the agent puts the setting back and the step is held. An offered series upgrade, hotfix upgrades of the same release, upgrades of ordinary packages and same-version reinstall entries don’t hold it. The task message reads Checking the device before pinning it....

A window is an advance. The agent puts right any pin that changed from outside, checks that the target release’s folder is on the device’s mirror, moves the pin to that folder, forces a check, and judges the plan: it must land on the target, with no downgrade, and base and kernel together. Only then does it ask OPNsense to update, which reboots when base or kernel change. Afterwards it reads the installed release back, and for a rebooting update, base and kernel must be at the planned release. The pin then follows the installed release. The task message goes through Checking the firmware pin..., Checking what <target> offers..., and Updating from <from> to <target>; OPNsense will reboot if it needs to..., or Updating the packages from <from> to <target> without a reboot....

• If anything fails before the update is requested, the pin goes back to where it was and the step is held.
• A failed update pulls the pin back to the installed release, so that it doesn’t stay ahead of the device. If a firmware job is still running, the agent does it once the firewall is idle.
• With Reboot after update off, a window applies userland packages only. If the plan holds only base and kernel, the step ends with nothing to do and the pin back where it was.
• OPNsense runs one firmware job at a time. A step that finds another firmware job running, such as a check or an update started from the interface, cron or a shell, waits for it, and is held with held_firmware_busy if OPNsense drops the request twice. The task message reads Waiting for another firmware task on this device to finish... while it waits.

Leaving a track is an unenroll. The agent puts back the Flavour it found when it enrolled the device, which is always (default), because a device with a Flavour of its own is never enrolled. It forces a check so that the Status tab shows what is newest, and deletes its record of the pin. The task message reads Restoring the firmware setting.... The setting is changed only while it still holds a value the agent wrote. If somebody else changed it, it is left as it is and the step reports that the pin changed outside NetDefense.

If you change the setting yourself

Resetting the Flavour to (default), restoring an older configuration, or changing the mirror or the type counts as a change to the pin. The agent writes the pin again at the installed release at its next pass over the pin, and the next result reports it. That applies to any value that isn’t the one the agent wrote, a custom Flavour you typed while the device was enrolled included. If the pin keeps being reset, the agent waits longer between attempts, and it never gives up while the device is in its track.

A device that already has a Flavour of its own is never enrolled. The step is held with held_custom_flavour, until you set the Flavour back to (default).

One exception: if the device now has a subscription or a release type other than Community, the agent leaves the Flavour alone, and every window is held with held_unsupported_edition. A reset by hand then sticks.

To take a device out of its track, move it to Unmanaged in NetDefense. Resetting the setting on the firewall doesn’t release it.

Removing the plugin, stopping the agent, deleting the device

Removing the plugin. pkg delete os-netdefense, or Remove on System > Firmware > Plugins, runs a step that prints Stopping ndagent and then Releasing the firmware pin (if the agent holds one). It restores the original Flavour only if the setting still equals a value the agent wrote. A Flavour set by someone else stays. It then runs OPNsense’s own firmware flush and reload, but no update check, so the Status tab shows nothing new until the next Check for updates. The console prints a result: released, or nothing_pinned, already_restored, not_ours or no_state when nothing was released, and the removal goes on either way.

Upgrading the plugin keeps the pin. If an upgrade is carried out as a removal followed by an install, the new agent pins the device again at its first pass over the pin. Removing the package and putting it back soon after has the same result.

Stopping the agent. The track logic runs inside the agent, so a stopped or disabled agent isn’t expected to re-pin, move or release anything. Expect the pin to stay until the agent runs again, you reset it by hand or the package is removed. Don’t count on stopping the agent to release a device: move it to Unmanaged while the agent runs.

Deleting the device in NetDefense. The cleanup on the device releases the pin as one of its steps, before it removes the agent. The agent logs Firmware pin released, and the cleanup log is /var/log/ndagent-decommission.log. See Remove a Device.

Don’t delete the agent’s record. The agent keeps what it wrote, the original setting, the track and its last contact in /var/db/ndagent/firmware-track.json. Deleting that file strands the pin: the agent no longer owns it, and the next enroll is held as held_custom_flavour. It isn’t a way to release a device.

Thirty days without contact

After 30 days without contact from an enabled device, the agent removes its own pin, and NetDefense moves the device to Unmanaged. Neither side sends a message. Each measures on its own clock.

• A contact is a connection that NetDefense accepted. It counts while the connection is up, and from the moment it ended.
• A powered-off firewall, or one cut off from NetDefense, counts as out of contact. So does a disabled device, because it is refused when it connects.
• A signed task from NetDefense proves that it still holds the device. It counts as contact, and calls the release off.
• A clock that jumps at boot, such as a dead battery before NTP, isn’t mistaken for a month of silence.
• A device that comes back after more than 30 days is released even though its connection is up. It is no longer in a track, and you add it again.

After the release the agent doesn’t pin the device again by itself, not even if the package is reinstalled or someone resets the Flavour. Only NetDefense putting it in a track again pins it.

A disabled device keeps its pin and gets no windows. Enabled again within 30 days, it is expected to take part in the next window.

High availability

Each node of a pair keeps its own pin. OPNsense’s configuration sync between the nodes doesn’t include the firmware settings, so each node is enrolled, pinned and moved on its own.

For ordinary windows the agent does nothing specific to a pair: it doesn’t look for one, and it neither orders nor staggers the nodes. What to do about that is in High-availability pairs. A series upgrade is different. The agent holds it for a pair member, and changes nothing. It treats a node as a member when any of these is configured, applied or not: a virtual IP in CARP mode (or any virtual IP with a VHID), a state-synchronization interface (pfsync), or a configuration-sync address. In OPNsense these are Interfaces > Virtual IPs, and the Synchronize all states via and Synchronize Config fields under System > High Availability > Settings. If the agent can’t read them, the step is held with held_check_failed.

Mirrors and repositories

A custom mirror isn’t a hold by itself. The agent probes the release’s folder on the mirror the device really uses, which it reads from the generated repository file. A mirror that doesn’t carry the folder holds the step with held_release_folder_missing, and one the agent can’t reach holds it with held_check_failed. So does a mirror reached through a proxy that the agent’s fetch doesn’t know. A pinned device whose folder is still missing at a later check is released: the agent restores the original setting and NetDefense moves the device to Unmanaged.

Where to look

• The setting: System > Firmware > Settings, Flavour.
• The agent’s log: Services > NetDefense > Log File. Lines to look for: Firmware flavour written, The firmware pin needs to be written again: <why>, The firmware pin keeps being changed outside NetDefense; the periodic round leaves it alone for a while, The pinned release folder is not on the device's mirror (first miss); the pin stays, and Holding the series upgrade: <why>.
• What the step reported: the task’s message and result, in the web app or with ndcli task describe, and ndcli firmware history <device>. See Troubleshooting for the reasons.
• OPNsense’s upgrade cache: /var/cache/opnsense-update, where an unfinished series upgrade leaves .kernel.pending, .base.pending and .pkgs.pending markers.