Wheelhouse docs

Corresponding source#

A Wheelhouse OS image contains software licensed under the GNU General Public License and other copyleft licences. You are entitled to the complete corresponding source for those parts, whether or not you got the image from us, and this page is where it is.

There is nothing to request and nobody to write to. Wheelhouse takes the GPLv2 §3(a) route rather than the three-year written offer of §3(b): the corresponding source is distributed with the object code. It is inside the image, in the same directory as the licence texts, and it is published again beside the release you downloaded. There is no postal offer anywhere in the product, and no address to publish.

The image build enforces that. It fails if SOURCE-OFFER.txt ever reads like a §3(b) offer — it greps for write to:, cost of performing and on a physical medium — and fails again if the file stops naming the three things the §3(a) route depends on: the source tarball, SOURCES.txt and the release host. The file ships on every image at /usr/share/wheelhouse/doc/SOURCE-OFFER.txt, which /usr/share/doc/wheelhouse is a symlink to.

The proprietary half — the agent, the web UI and the installer — is not covered. Where that line falls is below.

1. In the image, on the machine you are holding#

The complete source of the GPL build tooling this image was built with travels inside the image itself:

/usr/share/wheelhouse/doc/wheelhouse-<version>-<arch>-build-source.tar.gz

/usr/share/doc/wheelhouse is a symlink to /usr/share/wheelhouse/doc, so the path the console banner prints and this documentation has always named still reaches these files. They cannot live under /usr/share/doc itself: the image's filesystem is built with a rule that removes everything below /usr/share/doc/<directory>/ except copyright and README files, after every build hook has run — which is why v0.7.0's image carried none of them.

That is the vyos-build tree at the exact commit the image came from, with Wheelhouse's changes already applied and every file Wheelhouse adds to it. It does not depend on a server still being there. Two things it does not contain: the proprietary agent package, which is not corresponding source for anything, and itself — an archive cannot contain itself, so the copy of this directory inside it has no tarball in it.

The build asserts that the file is present and is a real gzip before the image is released.

2. Beside the release#

Every release publishes a source record beside the image on the download host. Its name is SOURCES-<version>-amd64.txt and it lives in that release's directory:

releases.rhymelikedi.me/v<version>/SOURCES-<version>-amd64.txt

That is the same URL the product's own System → About page links to. The current release is at the download host.

The same record is on the machine, at /usr/share/wheelhouse/doc/SOURCES.txt, so it travels with the object code rather than only with the download. The two differ in one respect: the in-image copy is written before the image is built, so it points at /var/lib/dpkg/status for the package versions, while the published copy is written afterwards and carries the full package list.

What the record says#

The shape, with the values a build fills in:

Wheelhouse OS <version> — corresponding source

Base:      https://github.com/vyos/vyos-build @ <commit>
           branch rolling, pinned in packaging/iso/build-iso.sh
Arch:      <arch>
Container: vyos/vyos-build:rolling@sha256:<digest>
Agent:     wheelhouse-agent_<version>_amd64.deb (proprietary; a separate program
           driving VyOS over its HTTP API)

Corresponding source for the GPL build tooling — ON THIS MACHINE:
  /usr/share/wheelhouse/doc/wheelhouse-<version>-<arch>-build-source.tar.gz

The rest of the release, at https://releases.rhymelikedi.me/v<version>/
  vyos-build-wheelhouse-<version>-amd64.patch
  SOURCES-<version>-amd64.txt
  wheelhouse-<version>-amd64.iso  and  .iso.sha256

Changes to the GPL build tooling, published as vyos-build-wheelhouse-<version>-amd64.patch:
  scripts/image-build/build-vyos-image  --iso-application "VyOS" -> "Wheelhouse"
  scripts/image-build/build-vyos-image  --iso-volume "VyOS" -> "WHEELHOUSE"
  scripts/image-build/build-vyos-image  hostname=vyos -> hostname=wheelhouse, and + quiet

Files added to the base, all Wheelhouse's own work and none derived from it:
  data/build-flavors/wheelhouse.toml
  data/live-build-config/hooks/live/50-wheelhouse-brand.binary
  data/live-build-config/hooks/live/50-wheelhouse-brand.chroot
  data/live-build-config/includes.binary/isolinux/splash.png    (replaced)
  data/live-build-config/bootloaders/grub-pc/splash.png         (replaced)
  data/live-build-config/includes.chroot/usr/share/wheelhouse/doc/
  packages/wheelhouse-agent_<version>_amd64.deb

Installed packages:
  <every package and its exact version>

Three things in there are what a source request actually needs: the vyos-build commit, the container digest the build ran in, and the exact version of every installed package.

The build-tooling patch#

Wheelhouse modifies one GPL file, and only in the build tooling rather than in the image. Three substitutions in scripts/image-build/build-vyos-image: the ISO's application and volume identifiers, so a Wheelhouse stick does not mount under the base's name, and the live image's kernel command line, which sets the host name and adds quiet. The patch is published with each release as vyos-build-wheelhouse-<version>-amd64.patch, is named in the source record, and the build fails outright if the diff comes out empty — so a release cannot quietly ship with the patch unrecorded.

The patch now reproduces every file the build adds, not only the one it modifies: the build flavor data/build-flavors/wheelhouse.toml and both branding hooks appear in it in full. Up to and including v0.7.0 it carried the single modified file, and the record listed the added ones by path without their contents — which is not enough to rebuild the tree that produced the image.

3. From upstream#

Every GPL and LGPL component in the image is an unmodified upstream VyOS or Debian package. Their source is the Debian source package for the version installed:

bash
# on the router: what is installed, and at exactly which version
dpkg-query -W -f='${Package} ${Version}\n' | sort

# on a Debian machine with matching sources, one package's source
apt-get source <package>=<version>

Where the version has aged out of the mirrors, https://snapshot.debian.org keeps them. For the base itself, the source is the vyos-build commit named in the record:

bash
git clone https://github.com/vyos/vyos-build
git -C vyos-build checkout <commit from SOURCES.txt>

Why there is no postal offer#

GPLv2 §3(b)'s written offer binds the distributor for three years to an address that has to keep receiving post. There is no such address. §3(a) — ship the source with the binary — puts the obligation on the build instead, and the build enforces it: if the words of a §3(b) offer reappear in SOURCE-OFFER.txt, the image does not build.

What this does not cover#

The Wheelhouse agent, the web UI and the installer are proprietary and are not derived from any GPL work. They are separate programs that drive the router over its HTTP API and op-mode commands. Their source is not published. Built on VyOS sets out where that boundary sits, and /usr/share/wheelhouse/doc/THIRD-PARTY.txt says the same on the machine.

The permissively-licensed libraries compiled into the agent and bundled into the UI are a separate matter again: their licences require notices, not source, and those notices ship in full at /usr/share/doc/wheelhouse-agent/copyright — Third-party licences.

Checking any of this yourself#

On a running router, without a network:

bash
cat /usr/share/wheelhouse/doc/SOURCES.txt        # what this image was built from
cat /usr/share/wheelhouse/doc/SOURCE-OFFER.txt   # where the source is, verbatim
ls -l /usr/share/wheelhouse/doc/*-build-source.tar.gz   # the build tooling's own source
# /usr/share/doc/wheelhouse is a symlink to that directory, so those paths work too
ls /usr/share/doc/<package>/copyright            # that package's licence and copyright
ls /usr/share/common-licenses/                   # the full GPL, LGPL and Apache texts

The per-package copyright files are generated from the packages actually installed in the image, not transcribed by hand, so they cannot drift from what is on the disk.

See also#

Updated 2026-09-03 gpl source licences legal

Edit this page