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 require a reboot. 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 platform marks the device’s firmware status as Update pending reboot in the web console and in ndcli device 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):

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

Previewing with `--dry-run`

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

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

This creates a task that runs a preview on the device — nothing is installed. 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

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 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 --org --schedule daily-patch
ndcli run firmware-upgrade --mode minor             --org --schedule monthly-reboot
ndcli run firmware-upgrade --mode major             --org --schedule semi-annual-major

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

Running upgrades from the web console

The web console’s Run page includes Firmware Upgrade as a command. Select the mode, configure the reboot option, pick your targets, and either run immediately or attach a schedule. The firmware status column on the Devices page updates as devices complete their upgrades.

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 "2026-07-01 03:00"

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

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

Full reference

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