The ISO#
wheelhouse-<version>-amd64.iso is the base platform built from source with the
Wheelhouse package baked in, its identity replaced, and its
corresponding-source record written beside it. The build is
packaging/iso/build-iso.sh: it clones vyos-build,
renders an image flavor, stages a branding overlay, drops the .deb into
vyos-build/packages/ — live-build installs every package found there — and runs the
upstream builder inside the upstream build container.
It takes 30 to 60 minutes and needs a privileged container, because live-build mounts filesystems.
DEB=dist/wheelhouse-agent_1.2.3_amd64.deb VERSION=1.2.3 bash packaging/iso/build-iso.shWhat it produces#
Everything lands in $BUILD_DIR/out, and the release workflow publishes all of it
together:
| File | What |
|---|---|
wheelhouse-<version>-amd64.iso | The image. |
wheelhouse-<version>-amd64.iso.sha256 | Its checksum. |
wheelhouse-<version>-amd64-build-source.tar.gz | The complete source of the GPL build tooling this image was built with, with the Wheelhouse changes already applied. |
vyos-build-wheelhouse-<version>-amd64.patch | Those changes, as a readable diff. |
SOURCES-<version>-amd64.txt | The vyos-build commit, the build container's digest, and every installed package with its exact version. |
The last three are the corresponding-source record. Compliance is GPLv2 §3(a) — the source is published beside the binary. There is no §3(b) written offer, so nothing that ships may promise one, and the branding hook fails the build if the wording creeps back in.
Environment#
| Variable | Default | Meaning |
|---|---|---|
DEB | (required) | The agent package to bake in. |
VERSION | dev | The image version string. |
BUILD_DIR | /srv/wheelhouse-build | Where the checkout and the output go. Must be a host path, because docker -v needs one even when this script itself runs inside a job container. |
VYOS_COMMIT | the pin in the script | The vyos-build commit to build from. head follows the branch instead, prints a warning, and must not be shipped. |
VYOS_BRANCH | rolling | The branch and the container tag. Upstream renamed current to rolling in 2026. |
VYOS_BUILD_REPO | upstream's GitHub repository | Where the checkout comes from. |
VYOS_BUILD_IMAGE | vyos/vyos-build:$VYOS_BRANCH | The build container. |
BUILD_BY | a string in the script | The builder identity recorded in the image. |
The base is pinned to a commit, in the source tree rather than in CI, so the base is a property of the tree. There is no tag to pin to: the newest tag upstream belongs to a branch marked unmaintained, and the maintained rolling branch has no tags at all.
The flavor#
packaging/iso/wheelhouse.toml is a template —
@VERSION@ and @VYOS_BASE@ are substituted, and the build fails if any @…@
marker survives. It declares two things.
default_config#
The configuration the image boots with when there is no config.boot yet: a live boot,
and the first boot after an install. It is upstream's own default with four changes,
kept otherwise verbatim so the syntax stays upstream's:
| Change | Effect |
|---|---|
host-name wheelhouse | Sets the live login prompt, the banner's header, the DHCP client identity and the common name of the certificate the agent generates on first boot. |
NTP off pool.ntp.org | The image does not point at the upstream project's NTP pool. |
| A login banner of our own | Without banner post-login, upstream renders its own template into /etc/motd: a welcome line, a logo and a support portal, on the console and — through pam_motd — over SSH. Setting the node replaces that template wholesale. The upstream credit stays, one line, at the bottom. |
system option kernel quiet | How the boot of an installed box stops being a screen of the base's systemd unit descriptions. Two upstream paths honour it: the image installer reads the configuration it has just copied, so the very first boot after an install is already quiet, and system_option.py does the same on every commit — so an operator can undo it with delete system option kernel quiet, commit, save and reboot. The live boot is separate, on the kernel command line, because the bootloader rather than this file decides that one. |
\n in a banner value becomes a real newline, so agetty's own escapes cannot be used
there.
/etc/os-release#
An [[includes_chroot]] entry, and the only place that file is written. See
Identifying the system.
The branding overlay#
Three things are staged into the checkout: the splash image, two live-build hooks, and the licence documents.
The splash#
It replaces both copies of upstream's own. That artwork is copyrighted by its author with all rights reserved, and their licence permits redistributing a self-built image only if the artwork is replaced — so this is a licence condition, not a preference. Both copies ship because the ISOLINUX one is what both bootloaders draw, and live-build copies the GRUB directory regardless.
50-wheelhouse-brand.chroot#
Runs inside the chroot, after every include is in place. Each check below fails the build:
| Check | Reason |
|---|---|
The five documents exist under /usr/share/wheelhouse/doc | They are the licence and source answer a customer gets: TERMS, THIRD-PARTY, SOURCE-OFFER, SOURCES and the build-source tarball. |
/usr/share/doc/wheelhouse is a symlink to that directory | Every path the banners print and the documentation names has to keep working, and the documents cannot live under /usr/share/doc — mksquashfs -ef data/live-build-config/rootfs/excludes strips everything below /usr/share/doc/<dir>/ except copyright and README, after every hook has run. A symlink at that level survives. |
The agent's own notice exists at /usr/share/wheelhouse-agent/third-party.md | The same exclude, the same reason. |
/etc/machine-id is absent or empty | This is the only place a baked-in id can be seen: the installer truncates the file afterwards, which masks it. Every box installed from an image with a baked id would share one machine-id, and the licence fingerprint with it. |
| None of them carries an unfilled owner placeholder | A placeholder in one of those four is a compliance defect. |
SOURCE-OFFER.txt does not read like a §3(b) written offer | A written offer needs a real address behind it for three years, and there is none. |
/etc/os-release says ID=wheelhouse | If the flavor's override stops winning, the image would report itself as the base to hostnamectl, monitoring agents and Ansible facts. |
It also does three things:
- Replaces
/usr/share/vyos/EULAwith a symlink to../wheelhouse/doc/TERMS.txt. Upstream's release build type installs a commercial end-user licence agreement there that no flavor entry can outrank, and nothing in the GPL requires shipping another company's commercial terms. Replaced rather than deleted, because the operational CLI'sshow licensepages that exact path, and it now shows the Wheelhouse terms. - Round-trips
/etc/os-releaseinto/usr/lib/os-release, because Debian normally makes the former a symlink to the latter and the include may have left the two disagreeing. - Removes upstream's Secure Boot MOK certificate from
/var/lib/shim-signed/mok. It is a public certificate, not a key, and it is not enrolled in firmware.
50-wheelhouse-brand.binary#
Runs against the built image directory, and is what labels the boot menu entries.
The upstream patches#
Three literal strings in upstream's build script cannot be reached by any flavor key, so the build patches them — and verifies both that the literal was there and that it is gone afterwards, failing if upstream has moved on:
| Patched | To | Reason |
|---|---|---|
--iso-application "VyOS" | "Wheelhouse" | A Wheelhouse stick otherwise mounts under the base's name. |
--iso-volume "VyOS" | "WHEELHOUSE" | And blkid -L otherwise sees the base's name. Uppercase because ISO 9660 wants it that way. |
hostname=vyos username=live | hostname=wheelhouse quiet username=live | The live kernel command line sets the host name before any configuration is loaded, so the first console prompt otherwise names the base. quiet stops fourteen upstream unit descriptions printing between the splash and the banner. |
quiet raises the console log level to KERN_ERR and tells systemd not to print unit
status. Panics, oopses and units that actually fail still reach the screen, so a
broken boot still says so. There are two escape hatches, and the build protects the
first: the fail-safe menu entry boots without quiet, and the build fails if upstream
ever adds quiet to that line. Failing that, both bootloaders let an operator edit the
command line before booting — Tab in ISOLINUX, e in GRUB.
Because upstream's builder is GPL-2, those changes are published: the diff is written to
out/vyos-build-wheelhouse-<version>-amd64.patch and named in SOURCES. It now carries
every file the build adds — the flavor and both hooks in full — not only the one file
Wheelhouse modifies.
What ships in /usr/share/wheelhouse/doc/#
/usr/share/doc/wheelhouse is a symlink to it.
| File | What |
|---|---|
TERMS.txt | The product's terms. Also what /usr/share/vyos/EULA resolves to. |
THIRD-PARTY.txt | Third-party notices. |
SOURCE-OFFER.txt | Where the corresponding source is published. |
SOURCES.txt | The base commit, the container, and every installed package with its version. Written into the chroot before the build, so this copy points at dpkg for the package list; the copy beside the ISO carries the list itself. |
wheelhouse-<version>-<arch>-build-source.tar.gz | The corresponding source itself: the vyos-build tree at that commit with Wheelhouse's changes applied. |
What has been booted#
The live image has been booted, installed to a disk and rebooted into, both in virtual
machines and on physical hardware, several times each. No other hardware is on
record, and an add system image upgrade of a Wheelhouse box has been done once, in a
virtual machine, and never on physical hardware.
There is no hardware compatibility list. The image's driver packages can be listed from
SOURCES-<version>-amd64.txt, which is not a compatibility claim.
amd64 only#
There is no arm64 image and no virtual-machine image — no qcow2, no OVA. The arm64
.deb exists for running the agent off-router against an arm64 router. The image boots
UEFI or legacy BIOS: it is a hybrid ISO carrying both grub-efi-amd64 and grub-pc.
See also#
- The
.deb— what gets baked in. - Identifying the system — what a built image calls itself.
- Channel index format — where the artefacts are published.
- What first boot does — what happens the first time it boots.
- About Wheelhouse — the licence boundary and the attribution.
- The image and the image flavor
- Built on VyOS and the source offer
- Upgrade the image