Wheelhouse docs

Upgrade the whole system#

You will end up with a new Wheelhouse image installed beside the running one, both on disk, and the router running the new one. The kernel, the base system, the agent, the web interface and the installer all move together, because they all come from the image.

The previous image stays on disk and can still be started, so undoing a bad upgrade is a restart into it, not a restore.

Before you start#

  • A backup. Take a backup that is actually complete. Every time, without exception: it takes a minute, and it is what stands between a bad upgrade and a rebuild.
  • The admin role.
  • The address of the new image. Release directories are named after the version, so an image's address has the form https://releases.rhymelikedi.me/v0.9.2/wheelhouse-0.9.2-amd64.iso; open releases.rhymelikedi.me/download in a browser, with your licence key, to see what is published. Download and verify.
  • Room on the disk for a second image. The System page's Disk used tile shows how full it is.
  • Any applied changes you want to keep, saved: Save configuration in the System page header. Changes that are not saved are lost when the router restarts.

Step 1 — Learn that there is a new release#

System → Overview → Updates. When the channel names a newer release, the panel says so — 0.9.2 is available on the stable channel. This router runs 0.9.1. — with its release date, a link to the release notes, the notes themselves under What’s new, and To install the new system image, add it under System images below. It is used from the next restart, with the image's size. The page header shows a 0.9.2 available badge on every tab.

In Advanced mode the panel also shows the same upgrade written out as commands for the console.

Step 2 — Add the image#

System → Overview → System images, as an admin. The panel lists the images on the disk, the one running marked Running and the one the router starts by default marked Default.

  1. Put the image's address in Add an image from a URL: The router downloads and installs it, which takes several minutes. It becomes the default and is used from the next restart.
  2. Press Add image. It shows Adding… until the router has finished; keep the page open.
  3. The panel says The image was added. It is used from the next restart. The new image is marked Default; the running image is unchanged until the router restarts.

The audit log records it as Installed a system image.

A router that cannot reach the release host cannot be upgraded from this panel. Add an image from a URL takes an http or https address only; there is no upload. On such a router, copy the image across by hand and use the base system's own command at the console, which takes a local path:

bash
add system image /path/to/wheelhouse-0.9.2-amd64.iso

Step 3 — Restart#

System → Overview → Power → Restart router. Enter the host name when asked, then press Restart now. The panel says The router is restarting. This page reconnects when it is back.

Step 4 — Check what came across#

The configuration, the accounts and their passwords, the audit log, the licence, the web certificate and the configuration history all live on the persistent part of the disk, which the new image takes over. After the restart:

  • Sign in with your existing account.
  • System → Overview: the Version panel's Product names the new version. Under System images the new image is marked Running and Default, and the old one is still listed.
  • System → Audit log still has your history, and the Licence page still shows a valid licence.

A browser can hold the previous version's files for a moment. A page that looks wrong right after an upgrade usually needs one hard reload.

Undoing it#

The old image is still on disk.

  • From the web interface: System images → Make default on the old image, then restart.
  • From the boot menu: the boot menu lists every installed image. Choose the old one for a single start. This is the way that works when the new image does not bring up the network or the agent at all.
  • From the console: set system image default-boot offers a list to choose the default from; then reboot.

Delete the old image once you are done with it: Delete on its row, then Delete name? to go ahead. It is offered on every image except the one running.

Upgrading more than one router#

There is no fleet-wide upgrade. The Fleet page shows each router's version and applies pending changes to one router at a time; it has no image action. Upgrade each router from its own System page, and upgrade one first and live with it for a while before doing the rest.

Reinstalling from a newer ISO is not an upgrade#

wheelhouse-install refuses to run on an installed system and says to add the image instead. Booting the new ISO and installing over the disk erases everything, including the persistent part of the disk, and gives you a new machine. Rebuilding a router is a restore, not an upgrade.

For automation#

bash
R=https://<router>:8443
T=wh_...                                    # an admin token
curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"op":"add","url":"https://releases.rhymelikedi.me/v0.9.2/wheelhouse-0.9.2-amd64.iso"}' \
  "$R/api/system/image"
curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"action":"reboot"}' "$R/api/system/power"

op may be add, show, set_default or delete. Both routes are admin only and recorded in the audit log, the address with any key in it redacted. As on the page, the router adds its licence key to an address on the release host that carries none.

See also#

Updated 2026-09-18 upgrade images operations

Edit this page