System images and updates#

Two panels on the Overview tab of the System page deal with new releases. Updates says whether a newer release exists, and installs a new agent package in place. System images, below it, is where a whole-system upgrade happens.

A system image is a complete system — kernel, base platform, agent, web interface and installer — installed beside the running one. Both stay on the router, and which one it starts with is a setting, so a bad image is undone by one restart rather than by a restore.

The Updates panel#

The agent reads the release channel 45 seconds after it starts and every 24 hours after that. The panel says what it found. It installs nothing by itself.

The panel's header shows the channel and when it last looked (stable channel · checked 3h ago), or Checks off. Check now reads the channel at once. It needs the operator role, and it is disabled while checks are off.

What the panel says:

"Up to date. This router runs 0.9.1."
When a newer release exists: "0.9.2 is available on the stable channel. This router runs 0.9.1.", with the release date and a Release notes link; a line saying how the release was checked; What’s new, the release notes themselves; 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 also shows a badge, 0.9.2 available, on every tab.
"The version this router runs (…) cannot be compared with …", when the two versions cannot be ordered.
"The last check failed:" and the reason, when it did.
"This router does not check for updates.", when checks are off.

Nothing has been downloaded at that point. The agent has read the channel's index, and checked it against the checksum file published beside it, and the release notes against their entry in that file, before showing a word of them. Both come from the same host, so that proves they agree, not that they are authentic. The line about the check has three states: failed, in red; passed on a release that is not signed, in amber, saying so; and passed on a signed release. Releases are not signed yet.

In Advanced mode the panel also lists the commands that verify and install the image by hand.

Agent package#

The web interface and the agent can be updated without a new system image. When a newer agent package is published, the section says "0.9.2 can be installed now, without a reboot.", and what will happen: "The router downloads the package (…), checks it against both the checksum file published with it and the channel index, installs it and restarts the agent. The web interface is unavailable for about ten seconds; the router keeps forwarding traffic. The system image is not changed."

Install 0.9.2 now needs the admin role and a licence. For anyone else it is disabled, with the reason: "Admin role required to install the agent", or "Installing updates needs a licence. Enter a licence key under Admin → Licence." While it runs, the section shows where it has got to — downloading, checking, installing, then "The agent is restarting with 0.9.2. This page reloads when it answers." — and the page reloads itself when the new agent answers. Afterwards it says "0.9.2 is installed and running.", or that installing failed, and why.

When there is nothing to install, the section says why, or "There is no agent package to install."

The previous package stays on the router: "0.9.1 is still on this router (…). Reinstalling it goes back to that version." Reinstall 0.9.1 asks "Go back to 0.9.1?" before it does.

Both are recorded in the audit log: "Installed an agent update" when it starts, and "Finished an agent update" from the new agent once it is running. The whole procedure is Upgrade the agent only.

Update check#

Setting	Does
Check daily	"Reads the release channel once a day, and sends the licence key only to fetch a newer release’s checksums and notes." The daily read carries nothing about the router; the licence key goes only with the two requests into a newer release’s directory. Off, the router makes no request at all.
Channel	Stable, or Beta, with release candidates.

Only an administrator can change these; everyone else sees "Only an administrator can change these." A change is saved at once, and recorded as "Changed the update settings".

Reading the channel's index carries no licence key and nothing about the router. When the index names a newer release, the checksum file and the release notes are fetched from that release's directory with the licence key, because the release host serves a release directory only to a licence key. A router that must not reach the internet turns the check off.

The System images panel#

The panel lists the images on the router, each with up to two badges:

Badge	Means
Running	The image the router started with.
Default	The image it starts with next time.

Adding an image makes it the default and leaves the running one alone until the next restart, so the two badges are often on different rows. When the router does not list its images, the panel says "The router did not list its images."

For an administrator, each row also offers:

Make default, on any image that is not the default. The panel then says "<name> is now the default."
Delete, on any image that is not running. It asks "Delete <name>?"; the second press deletes it, and the panel says "<name> was deleted." Left for five seconds, the button goes back.

Delete only what you have finished with. The old image is the way back from a bad upgrade.

Adding an image#

Add an image from a URL takes the image's address: "The router downloads and installs it, which takes several minutes. It becomes the default and is used from the next restart." Add image is enabled once the address begins with http:// or https://. The agent checks it again: it must be an http or https URL with a host.

The button reads Adding… until the router has finished; the request waits up to 15 minutes for it, so keep the page open. Then the panel says "The image was added. It is used from the next restart.", and the list shows the new image as the default.

The release host serves images only to a licence key. For an address on the release host, the agent adds the licence key entered under Admin → Licence, so the address can be pasted as the channel publishes it. An address on any other host is used as it is.

Adding, deleting and choosing the default are recorded in the audit log: "Installed a system image", "Deleted a system image", "Changed the default system image", with the image concerned.

The whole upgrade, in order#

Take a backup, on the Backup page.
Add the image from its address, here. Wait for it.
Check the list. The new image should be Default; the old one should still be Running.
Save the configuration with Save configuration in the page header, if changes have been applied since it was last saved. The router starts with its saved configuration.
Restart 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.
Keep the old image until you are satisfied. It is the way back.

Going back, if the new image misbehaves: Make default on the old image, and restart. If the router cannot be reached at all, its boot menu lists both images, and the old one can be chosen at the console for one start.

What survives an upgrade#

The router's /config directory is carried into the new image. That holds the configuration, the configuration history, and the agent's data: the accounts, the audit log, the licence and the web certificate. So an upgrade should keep your configuration, your accounts, your audit history and your licence, and should not ask anyone to sign in with anything new.

For automation#

bash

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

POST /api/system/image needs the admin role. op is one of add, show, set_default or delete: add takes url; set_default and delete take name, which must be an installed image's name; show takes neither and is the only one not recorded. Every answer carries the router's output and the refreshed list.

GET /api/updates is what the Updates panel shows; POST /api/updates/check checks now; PUT /api/admin/updates changes Check daily and Channel; and POST /api/updates/install installs the agent package (admin, licensed).