Upgrade the agent only#

You will end up with a newer agent and web interface running on the image you already have. The Updates panel on the System page installs the agent package from the release the channel offers: about ten seconds, one restart of the agent, and no restart of the router, which keeps forwarding traffic throughout.

Everything else — the kernel, the base system, the installer — comes only with a new system image. Upgrade the whole system is the path when a release changes more than the agent, and it is the whole upgrade.

Before you start#

The admin role and a licence. The release host serves the package only to a licensed router; without a licence the button is disabled with the reason Installing updates needs a licence. Enter a licence key under Admin → Licence.
Update checks turned on, with the Check daily switch on the same panel, and a router that can reach the release host. The panel offers a package only once it has read the channel.
A backup.

Step 1 — See what is offered#

System → Overview → Updates. The panel's header says which channel it reads and when it last checked; Check now reads the channel again.

The Agent package section says what can be installed:

0.9.2 can be installed now, without a reboot.

and, beneath it, 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. When nothing is offered, the section says why — for example, that the channel names the version this router already runs.

Step 2 — Install it#

Press Install version now. The section follows the install:

The panel says	Meaning
Downloading 0.9.2…	The package is being fetched from the release host
Checking 0.9.2 against its published checksums…	The checksum file, the channel index and the bytes that arrived must all agree
Installing 0.9.2…	The package is being installed
The agent is restarting with 0.9.2. This page reloads when it answers.	The old agent has handed over; the page waits for the new one
0.9.2 is installed and running.	Done
Installing 0.9.2 failed.	The reason is beneath it

The page reloads itself when the new agent answers.

The package also has to name itself as the agent, for this machine's architecture and for the version asked for; anything else is refused before it is installed.

Step 3 — Confirm#

The Updates panel says Up to date. This router runs 0.9.2. The Support page's This router panel shows the agent's version too.
The Audit log tab records Installed an agent update, with both versions, and Finished an agent update from the new agent.

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.

Going back#

The router keeps the last two packages it installed this way. When one of them is not the version running, the panel names it and its size, says Reinstalling it goes back to that version., and offers Reinstall 0.9.1. Press it, then Go back to 0.9.1? to go ahead. It installs from the router's own copy, so it works even when the release host no longer offers that version.

With no earlier package on the router, going back takes the package from an older release, installed by hand at the console, or a new system image. If the new agent will not start at all, Locked out of the UI covers finding out why.

Two things to know#

An image upgrade replaces the agent. The package writes into the part of the disk that belongs to the system image, so installing a new image brings that image's agent with it. That is usually what you want; but updating the agent in place and then installing an older image goes backwards. Keep the two in step.

It has been exercised by hand, on one router. In-place installs, a refused downgrade and the forced reinstall that followed it have been run against a licensed release host on the demonstration router. No automated test installs the package on a router before a release.

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 '{}' "$R/api/updates/install"          # the newest the channel offers
curl -sk -H "Authorization: Bearer $T" "$R/api/updates"   # follow "install": its phase

POST /api/updates/install needs the admin role and a licence. It answers 202 and the work runs on: the install object moves through downloading, verifying, installing and restarting, and the new agent writes done, or failed with a reason. A version that is not newer than the one running needs "force": true, as in {"version":"0.9.1","force":true}.

A router that cannot reach the release host cannot install this way, and has no upload for a package. At its console, a package copied across by hand installs with sudo dpkg -i wheelhouse-agent_<version>_amd64.deb, which restarts the agent itself.

The off-router agent#

The developer install's install.sh puts the agent on a machine that is not the router and points it at an existing router's HTTP API. It has its own upgrade: it backs up the old binary, health-checks the new one and rolls back on failure.