Firmware Upgrades

NetDefense can upgrade the OPNsense firmware on your managed firewalls directly from the platform — no SSH, no console access, no manual package management. Upgrades are issued as run commands that you can target at a single device, an OU, or your entire organization, and they integrate with named schedules so the work happens automatically.

Two upgrade modes

Minor — point release within the current series

A minor upgrade moves a device to a newer OPNsense release within the same series. A device running 26.1.2 can be upgraded to 26.1.9; it cannot be moved to 26.7 or 27.1 via a minor upgrade.

Minor upgrades are the standard maintenance path. They support --no-reboot (see No-downtime upgrades below), which makes them suitable for daily or continuous automation.

Major — series jump

A major upgrade moves a device across an OPNsense series boundary — for example, 25.1 → 25.7, or 25.7 → 26.1.

Major upgrades always apply the full package set and always reboot, up to three times. They are not candidates for the no-reboot split-apply path. Plan a maintenance window before running one.

No-downtime upgrades (`--no-reboot`)

The most important behavior in minor upgrades is split-apply: pass --no-reboot and the platform applies only the packages that do not require a reboot — application-layer packages and plugins. Base and kernel packages are not installed; they stay at the current version until a subsequent upgrade run that includes a reboot.

Because the reboot-free packages are applied while the firewall is live, there is no traffic interruption. The firewall continues passing traffic throughout the operation.

The product_version reported by the device does not advance until base and kernel are also applied. To complete the upgrade, run ndcli run firmware-upgrade --mode minor (without --no-reboot) during a maintenance window — that run installs base/kernel and reboots the device.

Mixed state

After a --no-reboot run, the device enters a mixed state: application packages are at the new version, base/kernel are not yet upgraded. The firmware task’s result says so: Reboot pending — mixed state on the task’s page in the web console, and Pending: base/kernel deferred — reboot required to complete upgrade in ndcli task describe. The device is fully operational in this state.

To complete the upgrade and clear the mixed state, run a standard minor upgrade (with reboot):

On Run, choose Upgrade firmware in Minor mode with Reboot after upgrade on, pick the device, and run it now or Later, in a maintenance window.

ndcli run firmware-upgrade --mode minor --device fw-prod-01 --at "2030-07-01 03:00"

Previewing with `--dry-run`

Before committing an upgrade, you can run it in preview mode:

On Run, choose Upgrade firmware, switch Dry run on, pick the device and click Run now. The task’s page on Tasks shows the result.

ndcli run firmware-upgrade --mode minor --dry-run --device fw-prod-01

Once the task completes, ndcli task describe <code> shows the result:

Firmware upgrade result:
  Preview:  yes (dry-run — nothing was installed)
  Mode:     minor
  Version:  26.1.2 → 26.1.9
  Packages: 66 to apply

Either way, the task runs a preview on the device and installs nothing.

When a firmware task completes

From ndagent 1.20.1, the device decides when an upgrade is done. OPNsense runs the update in the background, and the task stays IN_PROGRESS for as long as it runs — through the reboot, when there is one. It completes once the update is applied and, if the run reboots, the device is back up — a run without a reboot, once every planned package is installed.

A run that OPNsense reports as failed, or whose outcome the device can’t confirm before the task’s time runs out, ends FAILED with the reason. If the device’s connection drops during an update, the task waits and is settled when the device reconnects.

Recommended scheduling strategy

The most practical approach layers three schedules:

Schedule	Mode	Reboot	Cadence	Effect
Daily patch	`minor`	`--no-reboot`	Daily	Application packages always current; zero downtime
Monthly window	`minor`	(default)	Monthly	Completes the upgrade: installs base/kernel and reboots
Semi-annual major	`major`	(always)	Semi-annual	Series jump on a defined cycle

Create the schedules once, attach the commands, and the platform maintains your fleet without manual involvement:

Create the three schedules on Schedules. Then, on Run, set up each Upgrade firmware command for the entire organization (Minor with Reboot after upgrade off, Minor with it on, and Major), choose On schedule, pick its schedule and click Register.

# Create the cadences
ndcli schedule create --name daily-patch       --cron "0 3 * * *"   --timezone UTC
ndcli schedule create --name monthly-reboot    --cron "0 4 1 * *"   --timezone UTC
ndcli schedule create --name semi-annual-major --cron "0 5 1 1,7 *" --timezone UTC

# Wire up the commands (whole organization)
ndcli run firmware-upgrade --mode minor --no-reboot --all --schedule daily-patch
ndcli run firmware-upgrade --mode minor             --all --schedule monthly-reboot
ndcli run firmware-upgrade --mode major             --all --schedule semi-annual-major

These three create recurring tasks you can see and manage under Scheduled Tasks.

One firmware run per device at a time

OPNsense runs one firmware job at a time, so a device takes firmware tasks one after another. A task that arrives while another is running on the same device waits, showing Waiting for another firmware task on this device to finish..., and runs after it. If the first run reboots the device, the waiting task never gets its turn — once the device is back, it fails with:

The firmware task was not started: the agent stopped or lost its connection before it could run (it was waiting for another firmware task or for OPNsense to be free). Nothing was applied by this task.

A waiting task whose own time runs out first fails with The firmware task expired while it waited for another firmware task on this device; nothing was started.

So don’t let two firmware schedules fire at the same device at the same time. It’s easy to do by accident: a daily schedule and a weekly schedule set to the same time of day fire together once a week. Stagger them instead — the schedules above start an hour apart, so a run, reboot included, normally finishes before the next one begins.

Running upgrades from the web console

The web console’s Run page includes Upgrade firmware as a command. Choose the mode, decide whether to leave Reboot after upgrade on (switch it off for the no-reboot split-apply), pick your targets, and run now, run once later, or register it on a schedule. The Dashboard’s OPNsense versions bar and each device’s OPNsense slot follow the devices as they complete their upgrades — see OPNsense versions and updates.

Running upgrades with the MCP server

The firmware upgrade command is also available as an MCP tool for AI-assisted workflows. You can instruct an AI assistant to upgrade a device or preview an upgrade, and the tool forwards the request to the platform with the appropriate flags.

CLI quick reference

# Minor — upgrades to latest point release in the series, with reboot
ndcli run firmware-upgrade --mode minor --device fw-prod-01

# Minor — no-reboot split-apply (zero downtime; base/kernel deferred)
ndcli run firmware-upgrade --mode minor --no-reboot --device fw-prod-01

# Minor — deferred to a maintenance window
ndcli run firmware-upgrade --mode minor --device fw-prod-01 --at "2030-07-01 03:00"

# Major — series jump (always reboots)
ndcli run firmware-upgrade --mode major --device fw-prod-01 --at "2030-07-01 04:00"

# Dry run — preview across an OU
ndcli run firmware-upgrade --mode minor --dry-run --ou edge-routers

Devices in a firmware track

A device in a firmware track is refused a firmware upgrade, in any state, a device that is still leaving its track included. Its track moves it between releases.

Warning: this command will trigger a firmware upgrade and reboot the targeted device(s).
Error: [FIRMWARE_DEVICE_MANAGED] These devices are in a firmware track, which moves them between releases; move them out of their track to run a firmware upgrade on them: fw-prod-01
  Hint: See where the devices stand with 'ndcli firmware status', and take a device out of its track with 'ndcli firmware device set <device> --track unmanaged' before upgrading it by hand.

Registering a firmware upgrade on a schedule for such a device is refused too. A recurring firmware upgrade that already exists skips devices that are in a track instead of failing. Move the device to Unmanaged first, or leave its updates to the track. The web console’s Run page works the same way: with Upgrade firmware selected it greys out devices in a track and leaves them out of Select all, and it blocks a run when Entire organization or a chosen OU would reach one.

Full reference

The complete flag list, dry-run output format, and task output details are in the run firmware-upgrade reference page.