Download and verify#

Every tagged release is mirrored publicly at releases.rhymelikedi.me. /latest/ follows the newest tag; a specific version lives at its own directory, /v0.5.1/ and so on. Open /latest/ in a browser first, because the file names carry the version and every command below needs the version you are actually downloading substituted into it. 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 -fLO https://releases.rhymelikedi.me/latest/wheelhouse-0.5.1-amd64.iso
curl -fLO 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 -fLO 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 last four arrive from the release after 0.5.1 onwards, 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, and SHA256SUMS covers only the packages and tarballs — which is why the ISO's own .sha256 sidecar is the command above.

SOURCES-<v>.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/, so a customer holding only the box can still find it — 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. The signature is the part that proves who built it.

Once a release carries a signature, install/sign.sh verify checks the sums first and the signature second, and says plainly when there is nothing to check:

curl -fLO https://releases.rhymelikedi.me/latest/SHA256SUMS
curl -fLO https://releases.rhymelikedi.me/latest/SHA256SUMS.asc
WHEELHOUSE_PUBKEY=<the release public key> install/sign.sh verify SHA256SUMS
REQUIRE_SIGNATURE=1 install/sign.sh verify SHA256SUMS   # fail if nothing is signed

WHEELHOUSE_PUBKEY names an armoured public key file; the script imports it into a throwaway keyring, so verifying a download never touches your own.

Where the release public key will be published is not settled: <TODO: owner>. A signature you cannot get a trusted key for proves nothing, so until that is answered the checksum is the whole story and you should treat it as such.

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 is never moved backwards, so re-running an old tag will not tell every router that the newest release is last month's.

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.
• The source offer — what SOURCES-<v>.txt and the patch are part of.
• Downloads — the release host itself.

Checked against docs/install.md, docs/deploy.md, docs/security.md, .forgejo/workflows/publish.sh, .forgejo/workflows/release-index.py, install/sign.sh.