Boot images#

The Boot images panel sits below the Overview row on the System page and is where a whole-system upgrade happens. An image is a complete system — kernel, base, agent, UI, installer — installed alongside the running one. Both stay on disk, and which one boots is a setting. That is what makes an upgrade reversible: a bad image is one reboot away from being undone, not a restore.

Everything on this panel is admin-only and immediate. Nothing here stages, and every operation except show is written to the audit log.

The list#

The images come from GET /api/system, which parses show system image into a table. Each row shows the image name and up to two badges:

Badge	Means
`running`	This is the image the router booted into.
`default`	This is the image it will boot next time.

Those two are frequently different, and that is the whole mechanism: installing an image changes the default and leaves the running one alone until you reboot.

Beside each row, for an admin:

Boot by default — offered on any image that is not already the default.
Delete — offered on any image that is not running. It arms first: the button becomes Confirm delete.

A router that reports nothing says "No image information available."

Installing an image#

One field and one button:

Field	Hint
Install an image from a URL	"the router downloads and installs it (minutes); it becomes the default boot image, the running one stays until you reboot"

Below the field, the equivalent command updates as you type:

add system image https://releases.rhymelikedi.me/v0.6.0/wheelhouse-0.6.0-amd64.iso

The button enables when the field looks like an http(s) URL. The agent validates it again — it must parse, its scheme must be http or https, and it must have a host — and returns 400 naming the requirement otherwise: "url must be an http(s) URL of a Wheelhouse image" — agent/parity.go, handleImage.

The request stays open until the router is done. A router downloading and installing a 500 MB image over a domestic uplink takes minutes, so the call uses the agent's long-running HTTP client — 15 minutes — and the button reads Installing… the whole time. Do not close the tab.

When it returns, the response carries the router's own output and a fresh image table, so the list updates without a second read.

Setting the default and deleting#

Both take an image name, validated against ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ before it reaches the router; anything else is refused with "name must be an installed image name".

set system image default-boot
delete system image

The audit entries are image-set_default and image-delete, each with the name in the path field.

Delete only what you are finished with. The old image is the way back from a bad upgrade, and once it is gone the way back is a restore.

The whole upgrade, in order#

Take a backup. Not the configuration — the whole of /config. See Backup and restore.
Install the image from its URL, here. Wait for it.
Check the list. The new image should be default; the old one should still be running.
Reboot, from Power, typing the host name to confirm.
Sign in and check. The new image should now be running, with the old one still listed.
Leave the old image alone until you are satisfied. It is your rollback.

Going back, if the new image misbehaves: Boot by default on the old image and reboot. If the router is not reachable at all, the boot menu lists both images and you can pick the old one for a single boot from the console — which is the path that works when the new image does not bring the network up.

What survives an upgrade#

/config is the persistent partition and add system image carries it into the new image. That covers the configuration, the agent's state file, the audit log, the API key, the TLS certificate and the configuration archive — so an upgrade should keep your configuration, your accounts, your audit history and your licence, and should not ask you to sign in again with anything new.

Knowing an image exists#

Nothing on the router checks for updates. There is no update notification, no banner and no version check — the agent never asks anyone whether it is current. The download host carries a machine-readable channel index, and polling it is a cron job you write, not something the product does.

From the API#

bash

curl -sk -X POST -H "Authorization: Bearer $T" \
  -H 'Content-Type: application/json' \
  -d '{"op":"add","url":"https://releases.rhymelikedi.me/v0.6.0/wheelhouse-0.6.0-amd64.iso"}' \
  https://<router>:8443/api/system/image

op is one of add, show, set_default or delete. add takes url; set_default and delete take name; show takes neither and is the only one not audited. Every response carries the router's output and the refreshed image table.

Upgrading the control plane only#

A new agent and UI without a new kernel is a .deb installed on a running router. It needs no reboot, touches nothing under /config, and is how a control-plane fix reaches a router between image releases. It is not done from this panel, and it comes with two caveats worth reading before you rely on it — no test in this project installs the package on a router, and it writes into /usr, which an image upgrade replaces. The procedure and both caveats are in docs/upgrade.md.