Firmware

The Firmware page manages firmware tracks for the active organization. You sort devices into the Fast, Regular and Stable tracks, give each track a schedule, and watch each OPNsense release make its way through them. The ideas behind it, such as soak, evidence and the pin, are in the guide. This page describes what the screen shows and does.

Where it is

Firmware is in the sidebar between Backups and Tasks, and in the mobile menu. It is shown to every organization, whatever its plan. If the plan doesn’t include firmware tracks, the page says so.

• The page belongs to the organization selected in the sidebar switcher. Changing the organization restarts the page: no draft, selection, filter or open dialog carries over. With none selected, the page reads No organization selected and Please select an organization from the sidebar to manage its firmware tracks.
• The page refreshes itself while it is open. The rollout card says The soak left is counted by NetDefense and refreshed every minute.
• Dates on the page, such as the next window, approvals, halts and failures, are shown in the timezone you chose under Settings.
• A Read-Only member can see everything and change nothing. Every control that writes is disabled, and the configuration card says You have read-only access to this organization: firmware settings can be viewed, not changed.

The page, top to bottom

The header reads Firmware, with Stage OPNsense updates for and the organization’s name. Below it, in order:

1. A banner, only after a refresh has failed.
2. End-of-life notes, only when they apply.
3. The Firmware configuration card.
4. When a configuration exists, the three track cards, Fast, Regular and Stable, side by side on wide screens.
5. The Devices card.
6. The Rollout card, with the Series upgrades part inside it.

Without a configuration, only the first three can show.

The order of work the page itself suggests is the one in its toast after you enable Firmware: Firmware enabled. Attach a schedule to each track, then add devices to a track.

States of the page

You see	What it means
Grey placeholder blocks	The first read is still loading.
A red card, Could not load the firmware configuration: …, and Try again	The first read failed. The header stays.
A red banner, Could not refresh the firmware configuration: …. Showing the last answer.	A refresh failed after an answer was shown. It goes away when a later read succeeds.
The enable panel	Firmware isn’t configured, and the plan allows it.
A plan notice, with Enable Firmware disabled	Firmware isn’t configured, and the plan doesn’t include firmware tracks. Nothing else is shown.
A plan notice above a read-only view	Firmware was set up, and the plan no longer includes it.
An alert in the configuration card	Firmware is configured but disabled.

If the server has no firmware routes at all, the error reads Firmware tracks are not available on this NetDefense server yet.

When the plan doesn’t include firmware tracks

The notice reads Firmware tracks are not available on your plan. With no configuration, it says Upgrade your plan to stage OPNsense updates across the Fast, Regular and Stable tracks. and offers View plans. Enable Firmware and the reboot switch are disabled, and nothing else is shown. A write that the plan refuses while the page is open isn’t an error: you get a warning toast with the server’s text, and the notice appears.

When the plan stopped including firmware tracks

If Firmware was set up first, the page keeps showing the configuration, the tracks and the devices, read-only:

Your plan no longer includes firmware tracks, so the configuration, the tracks and the devices are shown as they are, read-only. No window runs, and every device still in a track is released: each agent puts back the setting its device had before it joined, and the device is unmanaged again. The only changes left are detaching a track’s schedule, moving a device to Unmanaged, disabling Firmware and deleting its configuration. Upgrade your plan to put devices in tracks again, edit their settings, halt or promote releases.

Those four controls stay open. Everything else is closed: turning Firmware on, Reboot after update, the soak and evidence inputs, Apply major upgrades, attaching a schedule, the Fast, Regular and Stable choices in every device selector, and every promote, halt and clear button.

Firmware configuration

Not configured, with a plan that allows it. The card says Enabling Firmware creates the three tracks (Fast, Regular and Stable) with their default settings. No device joins a track and no track has a schedule until you set that up., with a Reboot after update switch, on by default, and Enable Firmware.

Reboot after update is one setting for the whole organization, and the default for the update steps of every window. Its help reads: On: the full update, base and kernel included, then a reboot. Off: userland packages only, no reboot; base and kernel wait for a window with reboot on. Changing it shows Windows now apply the full update and reboot the device. or Windows now apply userland packages only, without a reboot. A series upgrade needs it on.

Configured. The card shows an Enabled or Disabled badge, with a switch beside it that turns Firmware on and off. A footer line counts the devices that are in a track, and Delete configuration sits beside it.

• Turning Firmware on again asks nothing, and shows Firmware enabled. Add devices to a track to start. It doesn’t bring any device back.
• Disabled shows Firmware is disabled: no window runs and no device can join a track. Devices that were in a track are released as their agents confirm.
• Turning it off opens Disable Firmware? It says how many devices are in a track, and that every one of them is released: each agent puts back the setting its device had before it joined, and the device is unmanaged again. A device that is offline or disabled keeps its pin until the step reaches it. It adds that devices keep the release they run, and that enabling Firmware later does not bring any device back. Confirm with Disable Firmware.
• Delete configuration opens Delete the firmware configuration? This deletes the three tracks with their schedules, and the releases they approved. Halts and each device's history stay. The dialog’s wording is broader than what happens. Your named schedules stay on the Schedules page, and only the tracks’ windows on them are removed. It is refused while a device is in a track or still leaving one. The error toast names the devices, and the dialog stays open. Confirm with Delete configuration. The card then returns to the enable panel.

Track cards

Each card has the track’s name, a badge counting its devices, and one line about the track:

Track	Line on the card
Fast	Takes a release first, once it has soaked since OPNsense published it.
Regular	Takes a release after it has soaked in Fast and enough Fast devices reached it.
Stable	Takes a release after it has soaked in Regular and enough Regular devices reached it.

Under it, when they aren’t zero, the card breaks the devices down, for example 2 managed · 1 enrolling · 1 held · 1 unenrolling.

Settings

• Soak (days) and Evidence (devices) with Save settings, which is enabled only when a valid value changed. Soak is a whole number from 0 to 365, and evidence a whole number from 0 to 1000. Fast’s evidence is fixed at 0 and disabled. Saving shows {Track} settings saved. Releases already approved stay approved.
• The help under the inputs says what each means. For example, Days a release soaks after it met its evidence in Fast, before Regular takes it. and Distinct Fast devices that must have reached a release first.

Apply major upgrades

A switch with an info button beside it, off by default. It is the per-track switch for series upgrades. Turning it on opens Apply major upgrades in {Track}? with the warnings, and the switch moves only once NetDefense confirms. Turning it off asks nothing. The toasts read Major upgrades are on for {Track}. Its windows upgrade the devices that pass the checks once the new series is approved here. and Major upgrades are off for {Track}., with the number of upgrade steps cancelled when there were any.

The info button, About series upgrades, opens a dialog with the same warnings and what a rollback needs. Reading it changes nothing, and it stays usable for a read-only member and on a plan without firmware tracks. If the server doesn’t offer the switch, the card says This NetDefense server does not support major upgrades yet.

Schedule

The field is labelled {Track} windows, for example Fast windows, with the help A window runs on a named schedule from the Schedules page. Tracks may share one.

• No schedule: a dropdown reading Pick a schedule… lists your schedules with their cron expressions, and Attach attaches it. With no schedules, it says No schedules found. Create one under Schedules first.
• Attached: the schedule’s name and Detach. Detaching asks first: The devices in {Track} keep their pin, but their windows stop firing. and, in amber, They get no update until a schedule is attached again.

Under the field, one line says whether the track runs. The first that applies wins:

Line	Meaning
Not scheduled — won't run	No schedule is attached.
Plan lacks firmware tracks — won't run	The plan no longer includes them.
Schedule disabled — won't run	The schedule exists, and is disabled.
Firmware disabled — won't run	Firmware is disabled.
Scheduled and next window …	The track runs.

Enabling Firmware attaches no schedule. Nothing runs for a track until one is attached and enabled, and Firmware is enabled.

Devices

The Devices card lists every device of the organization, 25 to a page. It reads Choose, device by device, which track moves it. A device in no track stays Unmanaged: NetDefense changes nothing on it. Devices are chosen by name. There is no OU filter, no OU column and no pattern.

When joining isn’t possible, an alert says why: Firmware is disabled. Enable it to add devices to a track., or, when the plan doesn’t include tracks, Your plan does not include firmware tracks, so no device can be added to a track. The ones still in a track are being released, and a device can still be moved to Unmanaged.

Filters

A text box, Filter by name…, matches names that contain the text. Filter by track offers All tracks, Unmanaged, Fast, Regular and Stable. Filter by state offers All states, Enrolling, Managed, Held and Unenrolling. Clear filters appears when any is active. An empty result reads No devices found and Try adjusting your filters.

Columns

Column	What it shows
Checkbox	Selects a device. The checkbox in the table header ticks every device on the page that can be moved, and no others.
Device	The name, linking to the device’s page, and a line such as agent 1.25.0, or agent version unknown. A device that isn’t enabled shows its status first.
Track	A dropdown: Unmanaged, Fast, Regular, Stable. The default is Unmanaged. A device still leaving its track reads Unmanaged.
State	Enrolling, Managed, Held or Unenrolling, with a hover text, or plain Unmanaged.
Pinned at	The release in monospace and series 26.7 under it, an amber warning mark when the pin changed outside NetDefense, or —.
Series upgrade	A badge: Eligible, Waiting, Held, Not eligible or None available. — for a device in no track, not managed, or disabled. See Series Upgrades.
Last step	The outcome, how long ago, with the exact time on hover, and the agent’s own error text if there is one.
Notes	Anything worth knowing, in this order: why the Track dropdown is closed, the hold reason, why no step is sent, a release the system made by itself, notes on the check and on the last series upgrade.

The state hovers read:

State	Hover
Enrolling	Joined the track; the agent has not confirmed the pin yet.
Managed	Pinned, and moved by the windows of its track.
Held	In the track but not enrolled: the agent declined to pin the device, and says why. NetDefense asks again at the track's next window.
Unenrolling	Leaving the track; the agent has not confirmed that the original setting is back.

The Track dropdown is closed for a device that is still leaving its track (Still leaving its track: it can join a track again once its agent has confirmed.) and for one that isn’t registered yet (Approve the device first: only registered devices can join a track.). Notes also says when no step is sent: Its NetDefense agent is older than 1.24.0, so no firmware step is sent until it is upgraded. or The device is disabled, so no firmware step is sent until it is enabled.

Moving devices

• One device: pick a track in its dropdown. It applies at once, and a toast counts the result, for example Fast: 1 added.
• Taking a device out of its track: pick Unmanaged. Release {device} from {Track}? explains The agent puts back the setting this device had before it joined a track, and the device is unmanaged again. It keeps the release it runs now. Confirm with Release device. Here, “release” means the device leaves the track, and not an OPNsense release.
• Several devices: tick their rows. A bar shows {n} devices selected, a Move to… dropdown, Apply and Clear selection, and says Select at most 500 devices at a time: a move is all or nothing. when you go over. Move {n} devices to {Track}? lists the first eight names and explains Each device is asked to pin the release it runs now, and then moves with the windows of this track; one that cannot be pinned is held, and says why. A device already in another track keeps its pin. Confirm with Move devices. To take several out, Release {n} devices from their tracks? confirms with Release devices.

After a move, a toast counts the results in the order added, moved, released, updated and unchanged, for example Regular: 1 added, 1 moved. It adds how many queued firmware steps were cancelled, if any, and a warning for each device that gets no step until something changes: its agent is older than 1.24.0, or it is disabled.

Rollout

The Rollout card shows where each OPNsense release stands on its way through Fast, Regular and Stable. It has a refresh button, and can show a line about NetDefense’s own package repository under its subtitle. That line is plain text about NetDefense’s side. It isn’t an alert, and asks nothing of you.

With nothing to show, it reads No release to show yet. A series appears here once a device in a track runs it or one of its releases is approved.

Per series

Each OPNsense series has a section, for example OPNsense 26.7, with a column for each track. A header reads the track’s name, soak 9d and, except for Fast, evidence 1. Each column has two parts:

• Moves devices to is the release the track moves its devices of this series to. A badge says whether it was approved auto or manual, with the date, and the buttons Promote… and Halt…. Or No release approved yet.
• Takes next is the release waiting for the track, with a state, or Nothing waiting. Under it, soak complete or the time left, such as 2d 3h left, and for the later tracks evidence 0/1 device. The time left is NetDefense’s count, never a countdown in your browser.

The states of a release waiting for a track:

State	Meaning
Ready	Its soak is over and the track is about to approve it.
Soaking	It is in its soak.
Waiting for the previous track	The track before it hasn’t approved it.
Waiting for evidence	Not enough devices of the previous track have reached it.
Blocked by a failure	An unresolved failure stands against it in an earlier track.

A stalled release shows an amber line: Too few devices in {Previous} can still reach this release to meet the evidence {Track} asks for. Add devices to {Previous}, or lower the evidence count., or An unresolved failure in an earlier track blocks this release. Clear it once it is resolved.

Failures, halts and the form

• Failures blocking a release lists each as {version} failed in {Track} on {device names}, with {n} failure(s), last {date}. A later success on the release clears it too. and Clear failures. The success has to come from the same device: a failure stops blocking the release when that device later reaches it, or when you clear it. Without any failure, the list reads No unresolved failure blocks a release.
• Halted releases lists each as {version} — {reason} with who halted it and when, and Lift halt. Without any, No release is halted.
• Act on a release is for a release the board doesn’t list. Type its directory name as OPNsense’s mirror spells it, such as 26.7.5 or 26.7.3_11, in Release, then choose Promote now… or Halt…. A name that isn’t one reads That is not a release directory name. Use the mirror's spelling: 26.7.5, or 26.7.3_11 for a hotfix. To send an urgent security release out at once, promote it to all three tracks.

All of these buttons are disabled for a read-only member and on a plan that lost the feature, and Promote also while Firmware is disabled. Halt stays available while Firmware is disabled.

Dialogs

• The dialog Promote {version} now: The release skips its soak and its evidence in the tracks you choose: their devices receive it at their next window. A halted release cannot be promoted. Choose Fast, Regular, Stable or All three tracks, and confirm with Promote now. Opened from Takes next, it preselects that track. Opened from Moves devices to, it preselects none, and Promote now stays disabled until you choose.
• The dialog Halt {version}: No track approves a halted release, and the steps queued for it that were not sent yet are cancelled. Devices already on it stay on it: there is no rollback. The Reason, up to 255 characters, is required, and Halt release is disabled until you type one.
• The dialog Lift the halt on {version}?: The release competes for the tracks again, under the soak and evidence they ask for.
• The dialog Clear the failures of {version}?: The failures recorded for this release in {Track} stop blocking it, so it can move on. The records stay in each device's history.

A bare series name such as 26.7 is also the GA release of that series. In these dialogs the page adds a line saying that it acts on that release, not on the series upgrade, which has its own controls.

Series upgrades

Inside the Rollout card, Series upgrades says A track moves its devices from one OPNsense series to the next, behind a switch of its own on each track. The series goes through Fast, Regular and Stable like a release, with the same soak and evidence settings. Read Series Upgrades first. A series upgrade takes the device offline, reboots it three times and has no automatic rollback.

An upgrade block, OPNsense 26.1 → 26.7, with Promote to all… and Halt…, is drawn only while a device that is pinned in a track runs the series the upgrade leaves. A device in no track, or one that is still enrolling or held at enrolment, doesn’t count. A column is drawn only for a track that has such a device. With none, the part reads No series upgrade to show yet. If the page can’t read which series the devices run, it shows every upgrade and track under a red line, so that Halt is never missing.

A track’s column shows:

• A state: Path closed, Soaking, Ready, Waiting for the previous track, Waiting for evidence, Blocked by a failure, Halted or Approved.
• Major upgrades on or Major upgrades off. Off reads The switch for major upgrades is off in this track: the series moves through it, but no device is asked to upgrade.
• The soak left and the evidence, and a line about a stall.
• Why no upgrade starts: and a reason, such as Major upgrades are switched off on this NetDefense server, for every organization., that reboot is disabled, that every device’s agent is older than 1.25.0, that the upgrade files haven’t been seen on OPNsense’s mirror in the last 30 minutes, that the track hasn’t approved the last release of the old series yet, or that devices wait for one ordinary window.
• A notice, OPNsense replaced the upgrade files after this track approved the series. The approval stands; halt the series to stop it.
• When it was approved, a count such as 2 eligible · 1 on 26.7 · 1 upgraded by NetDefense, and a Promote… button.

The dialogs are Promote the {series} upgrade now, Halt the {series} upgrade, Lift the halt on the {series} upgrade? and Clear the failures of the {series} upgrade? The promote dialog repeats the warning that an upgrade takes the device offline, and says that a device is upgraded only in a track whose switch is on, at its next window. Promoting a series whose upgrade path is closed is refused: The 26.7 upgrade cannot be promoted yet: OPNsense's upgrade path is closed. NetDefense has not seen all its files on OPNsense's mirror in the last 30 minutes, or ever. Try again once the board shows the path open. Failures blocking a series upgrade and Halted series upgrades work like the lists for releases.

The end-of-life note

At the top of the page, an amber note appears when devices of the organization run a series that NetDefense flags as end of life. NetDefense flags a series only while its upgrade path is open and it has a supported upgrade out of it. Today that means OPNsense 26.1:

OPNsense 26.1 is end of life, so the 3 devices still on it get no more fixes. Upgrade them to the next series, or put them in a track with series upgrades turned on.

It counts the organization’s devices on that series, unmanaged ones included. It comes from the rollout, so an organization that never enabled Firmware sees no note. A series that NetDefense has no upgrade out of is never flagged, and that is not a statement that it is supported. The flag is NetDefense’s inference from the upgrade path, not a published date.

Elsewhere in the web app

• Devices list: an organization that has a firmware configuration gets a Firmware column. Each cell is a pill with the track and the pin, such as Fast · 26.7.3, Regular · held, Fast · enrolling or leaving Stable, or — for a device in no track. Its hover says the state, the pin, the series and the series-upgrade verdict. The track list is read once when the page opens.
• Device page: a Firmware track card, after the facts and before Drift Status, only for an organization with a configuration. It shows the track, state, pin, series, series-upgrade verdict, last step, any hold reason and a Manage on the Firmware page link, or This device is not in a firmware track: NetDefense changes nothing about its OPNsense updates. and Add it to a track on the Firmware page. A Boot environment before a major (ZFS) switch sits in it for a device in a track, and Recent steps lists the last five.
• Schedules: on a schedule’s page, a track’s window is a spec of kind FIRMWARE, reading Fast track firmware window, with a Managed on the Firmware page link instead of the usual buttons. A schedule that a track runs on can’t be deleted, and the delete dialog says so beforehand: It also carries the firmware window of the Fast track, so it cannot be deleted until that track is detached from it. Detach it on the Firmware page first.
• Tasks: firmware steps appear as Firmware track step tasks, of type FIRMWARE_TRACK. A completed one shows a Firmware Track Result card in its details. See Tasks.

What isn’t here

• Run → Upgrade firmware is the older, one-off command, and it isn’t part of tracks. A device in a track is refused it.
• The dashboard’s OPNsense … available lines are device telemetry, not firmware tracks.
• There is no rollback control, no per-device schedule and no OU targeting.