run firmware-upgrade

ndcli run firmware-upgrade upgrades the OPNsense firmware on managed firewall devices. It supports two upgrade modes and a split-apply strategy that lets you deliver package updates without any reboot, deferring only the base system and kernel to a scheduled maintenance window.

ndcli run firmware-upgrade --device <name> --mode minor|major [flags] <target-flags> [--at <time>] [--schedule <name>]

Flags

Flag	Required	Default	Description
`--mode`	Yes		Upgrade mode: `minor` or `major` (see Upgrade modes)
`--reboot` / `--no-reboot`	No	`--reboot`	Whether to include a reboot. `--no-reboot` applies only reboot-free packages; base/kernel are left pending until a subsequent upgrade run without `--no-reboot`. See Split-apply. Rejected for `major` — major upgrades always reboot.
`--dry-run`	No	false	Create a preview task without installing anything. Inspect the result with `ndcli task describe <code>`.

Target flags

Inherited from ndcli run. At least one is required.

Flag	Repeatable	Description
`--device <name>`	Yes	Target a specific device by name
`--ou <name>`	Yes	Target every enabled device in the OU
`--org`	No	Target every enabled device in the organization

Scheduling flags

Flag	Description
`--at <time>`	Defer a one-time upgrade to a future instant. Accepts relative offsets (`2h`, `1d`) or timestamps. See `run` scheduling.
`--schedule <name>`	Attach the upgrade to a named recurring schedule.

Upgrade modes

`minor` — point release within the same series

Upgrades within the currently installed series. For example, a device running 26.1.2 with --mode minor upgrades to the latest available 26.1.x release. It cannot move to 26.7 or 27.x.

Minor upgrades support --no-reboot (see Split-apply).

`major` — series jump

Upgrades across a major OPNsense series boundary. For example, 25.1 → 25.7, or 25.7 → 26.1.

Major upgrades always require a reboot and always apply the full package set in a single pass. The --no-reboot flag is rejected for major mode.

Split-apply (`--no-reboot`)

When you pass --no-reboot to a minor upgrade, 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 remain at the current version until a subsequent upgrade run that includes a reboot.

The product_version reported by the device does not advance until base and kernel are applied. To complete the upgrade, run the same command without --no-reboot (or schedule ndcli run firmware-upgrade --mode minor for a maintenance window). That run installs the remaining base/kernel packages and reboots the device.

After a --no-reboot run the device enters a mixed state: application packages are at the new version, base/kernel are not yet upgraded. This state is visible on the device detail page in the web console (see Mixed state) and in ndcli device describe.

Split-apply lets you run minor firmware maintenance on a daily or continuous basis — keeping application packages current with zero downtime — while isolating base/kernel reboots to a separate, explicitly scheduled window.

Mixed state

When a device has base/kernel packages pending, its firmware status shows as Update pending reboot. The device operates normally. To complete the upgrade and clear the mixed state, run a minor upgrade with reboot (the default):

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

Dry run

--dry-run creates a task that runs a preview on the device without installing anything. The command returns a task code immediately; the result is available via ndcli task describe <code> once the task completes.

ndcli run firmware-upgrade --device fw-prod-01 --mode minor --dry-run
ndcli task describe <code>

The Firmware upgrade result block in the task output:

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

Examples

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

# Minor upgrade — no-reboot (only reboot-free packages applied; base/kernel left pending)
ndcli run firmware-upgrade --mode minor --no-reboot --device fw-prod-01

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

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

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

# Recurring daily no-reboot minor upgrade (run against the whole org)
ndcli run firmware-upgrade --mode minor --no-reboot --org --schedule daily-patch

# Recurring monthly minor upgrade with reboot (for base/kernel)
ndcli run firmware-upgrade --mode minor --org --schedule monthly-reboot-window

# Recurring semi-annual major upgrade
ndcli run firmware-upgrade --mode major --org --schedule semi-annual-major

Recommended scheduling strategy

A common pattern is three overlapping schedules:

Schedule	Mode	Reboot	Cadence	Effect
`daily-patch`	`minor`	`--no-reboot`	Daily	Keeps application packages current with zero downtime
`monthly-reboot-window`	`minor`	(default)	Monthly	Applies pending base/kernel, clears mixed state
`semi-annual-major`	`major`	(always)	Semi-annual	Jumps the OPNsense series

This layered approach means most devices are never more than a day behind on application packages, while base and kernel updates are batched into a monthly window — and major series upgrades happen on a predictable six-month cycle.

Task output

Each device targeted produces one task. Inspect it with:

ndcli task list --type FIRMWARE_UPGRADE
ndcli task describe <code>

The Firmware upgrade result block in ndcli task describe shows the outcome. Examples for each scenario:

Minor with reboot (default):

Firmware upgrade result:
  Mode:     minor
  Version:  26.1.2 → 26.1.9
  Packages: 116 applied
  Rebooted: yes
  Applied:  yes

Minor with --no-reboot (split-apply):

Firmware upgrade result:
  Mode:     minor
  Version:  26.1.2 → 26.1.9
  Packages: 116 applied
  Pending:  base/kernel deferred — reboot required to complete upgrade
  Rebooted: no
  Applied:  yes

The product_version on the device does not advance until a subsequent run applies base/kernel with a reboot.

Dry run:

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