Download and verify#

The image goes to subscribers; there is no public download. Releases live at https://releases.rhymelikedi.me/ behind your licence key: the host answers a release directory only to a licence that is paid up, and it is the same key you enter on the router's Licence page. In a browser, open releases.rhymelikedi.me/download, paste the key, and every release directory opens for twelve hours. From a shell the key is the password and the user name does not matter, as the commands below show. The channel index — stable.json and beta.json — needs no key: it carries versions and checksums and nothing else.

/latest/ follows the newest stable release and never moves backwards; a specific version lives in its own directory, /v0.7.0/ and so on. A pre-release tag — v1.2.3-rc1 and the like — gets its own directory and an entry in beta.json, and does not move /latest/. Open the directory you want in a browser first: the file names carry the version, and every command below needs the version you are downloading substituted into it.

export WHL_KEY='WHL1.…'            # your licence key, from the purchase e-mail

Check the checksum before you write the stick. An image that arrived wrong fails in ways that look like broken hardware.

Download the image and check it#

curl -fL -u "licence:$WHL_KEY" -O https://releases.rhymelikedi.me/latest/wheelhouse-0.5.1-amd64.iso
curl -fL -u "licence:$WHL_KEY" -O https://releases.rhymelikedi.me/latest/wheelhouse-0.5.1-amd64.iso.sha256
sha256sum -c wheelhouse-0.5.1-amd64.iso.sha256
# wheelhouse-0.5.1-amd64.iso: OK

On macOS use shasum -a 256 -c instead of sha256sum -c.

Newer releases also carry a single SHA256SUMS over the whole directory, which is the form the release notes point at:

curl -fL -u "licence:$WHL_KEY" -O https://releases.rhymelikedi.me/latest/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS

--ignore-missing is there because you will normally have downloaded one file out of several. Read the output. It must name the file you downloaded and say OK. --ignore-missing with nothing downloaded also exits zero, so a silent success proves nothing on its own.

What is in a release directory#

The directory-wide SHA256SUMS, its .asc signature, CHANGELOG.md and the vyos-build patch arrive in releases after 0.5.1, along with a channel index naming the newest version. In 0.5.1 and earlier there is no CHANGELOG.md and no signature on the host, so the ISO's own .sha256 sidecar is the command to use.

The agent .deb comes back from the next release. It is in the same directory, behind the same licence key, and it exists so a router you already run can take a newer agent in place instead of a whole new image — Upgrade the agent only is what to do with it. The router fetches it the way it fetches an image: the key travels as the URL password, so the URL you hand it reads https://licence:<key>@releases.rhymelikedi.me/latest/wheelhouse-agent_<v>_amd64.deb, and from a shell it is -u "licence:$WHL_KEY" like every command on this page. Nothing in the release host changes to serve it — the same gate stands in front of the whole directory.

curl -fL -u "licence:$WHL_KEY" -O https://releases.rhymelikedi.me/latest/wheelhouse-agent_0.8.1_amd64.deb
sha256sum --ignore-missing -c SHA256SUMS

The bare-binary tarballs are not published: they are build artefacts, and nothing installs one on a router. No directory on the host carries a .deb today — 0.8.0 and 0.8.1 were published without one.

SOURCES-<v>-amd64.txt and the patch are the corresponding-source record. Wheelhouse is built on VyOS, which is GPL-2, and those two files are how you get from the image back to the source it came from. The same record is on the installed system under /usr/share/doc/wheelhouse/ — About Wheelhouse has the full offer.

What a checksum proves, and what it does not#

It detects a corrupt download. It does not detect a hostile one. The checksum is served from the same host as the image, so anyone who could replace one could replace the other. A signature is what proves who built it.

Once a release carries a signature, checking it is two separate steps: the sums for the file you fetched, then the signature over SHA256SUMS itself. You need the release public key for the second, and without it gpg will only tell you it has never heard of the signer.

curl -fL -u "licence:$WHL_KEY" -O https://releases.rhymelikedi.me/latest/SHA256SUMS
curl -fL -u "licence:$WHL_KEY" -O https://releases.rhymelikedi.me/latest/SHA256SUMS.asc
curl -fLO https://releases.rhymelikedi.me/wheelhouse-release.asc

sha256sum --ignore-missing -c SHA256SUMS     # must name your file and say OK

ring=$(mktemp -d)                            # a throwaway keyring, so checking a
gpg --homedir "$ring" --import wheelhouse-release.asc      # download never touches
gpg --homedir "$ring" --verify SHA256SUMS.asc SHA256SUMS   # your own
rm -rf "$ring"

install/sign.sh verify SHA256SUMS runs those two steps in order, with the same throwaway keyring when WHEELHOUSE_PUBKEY names the key file, and says plainly when there is no signature to check; REQUIRE_SIGNATURE=1 turns that into a failure. It has no --ignore-missing and checks every line of SHA256SUMS, so it only succeeds where the whole tag directory is present. For a single downloaded image, use the commands above.

No release signing key exists yet, so there is nothing to verify against today. When one is generated, its public half will be published at https://releases.rhymelikedi.me/wheelhouse-release.asc and its fingerprint printed in the security policy. Until then the checksum tells you the download survived the network, and nothing about who built it.

Watching for a new release#

Each channel is a small JSON document at the root of the download host, regenerated whenever a tag publishes:

https://releases.rhymelikedi.me/stable.json
https://releases.rhymelikedi.me/beta.json

{
  "channel": "stable",
  "version": "0.5.1",
  "tag": "v0.5.1",
  "base": "https://releases.rhymelikedi.me/v0.5.1/",
  "notes": "https://releases.rhymelikedi.me/v0.5.1/CHANGELOG.md",
  "checksums": "SHA256SUMS",
  "signature": "SHA256SUMS.asc",
  "signed": false,
  "artifacts": [
    {"name": "wheelhouse-0.5.1-amd64.iso", "kind": "iso", "arch": "amd64",
     "size": 512483328, "sha256": "…"}
  ]
}

version is the comparison key, base plus an artefact name forms the download URL, sha256 is what to check, and signed says whether signature is real. Unknown fields may be added, so a consumer must ignore them. The channel is derived from the tag: a plain vX.Y.Z is stable, anything with a pre-release suffix is beta. A channel never moves backwards, so re-running an old tag will not tell every router that the newest release is last month's.

The router reads the stable index on a timer and the System page says when a newer version exists; it installs nothing itself — Upgrading the image.

See also#

• Write the stick — the next step.
• What you need — before you download 600 MB onto a machine that cannot run it.
• Watching for releases — turning the channel index into something that tells you.
• Upgrading the image — what to do with the next one.
• Corresponding source — what SOURCES-<v>-amd64.txt and the patch are part of.
• Downloads — the release host's door: paste the key, then browse.