Identifying the system#

hostnamectl, an Ansible fact-gather and a monitoring agent all read /etc/os-release. On a Wheelhouse box it identifies the product and names the base it is built on.

/etc/os-release

PRETTY_NAME="Wheelhouse OS 0.5.1"
NAME="Wheelhouse"
ID=wheelhouse
ID_LIKE="vyos debian"
VERSION="0.5.1"
VERSION_ID="0.5.1"
HOME_URL="https://wheelhouse.rhymelikedi.me/"
DOCUMENTATION_URL="https://docs.wheelhouse.rhymelikedi.me/"
SUPPORT_URL="https://docs.wheelhouse.rhymelikedi.me/"
VYOS_VERSION="rolling@a1b2c3d4e5f6"

Key	Value	Notes
`ID`	`wheelhouse`	What a script should branch on.
`ID_LIKE`	`vyos debian`	So a tool that knows either still recognises the image.
`VERSION`, `VERSION_ID`	the image version	Substituted from `@VERSION@` at build time.
`VYOS_VERSION`	`<branch>@<commit>`	The base version, so support, monitoring and Ansible facts can read it.
`HOME_URL`	the product site
`DOCUMENTATION_URL`, `SUPPORT_URL`	the documentation site	Both name the same host. The support procedure is documented there, and there is no separate portal.
`BUG_REPORT_URL`	absent	There is no public issue tracker. The key is optional and is left out.

This file is machine-parsed: hostnamectl, Ansible's ansible_facts, monitoring agents and any UI that renders a *_URL key as a link. The image build therefore fails on an unfilled owner placeholder and on a surviving @…@ template marker, and both checks read the whole rendered flavor including its comments.

The fuller credit — the base commit, the container, and every installed package with its version — is in /usr/share/doc/wheelhouse/SOURCES.txt.

Which layer writes it#

The upstream image builder writes its own hardcoded os-release into the chroot and then runs the flavor's [[includes_chroot]] loop afterwards in the same function, so the flavor's entry is the last writer. Nothing else competes for the path.

Setting the flavor's website_url / support_url keys does not work: the builder reads its own defaults there, not the merged build configuration.

The branding hook asserts that ordering:

grep -q '^ID=wheelhouse$' /etc/os-release ||
    fail "/etc/os-release was not overridden by the flavor (see wheelhouse.toml)"

If that write ever moves, the build fails rather than shipping an image that calls itself something else. The hook also copies /etc/os-release over /usr/lib/os-release: Debian normally makes the first a symlink to the second, and an include can leave the two disagreeing.

Where every version string comes from#

There are four, and they are not the same number.

String	Source	Seen at
The agent version	Compiled in: `version` in `agent/main.go`, set at build time with `-ldflags "-X main.version=…"`	`wheelhouse-agent version`, and the `wheelhouse_build_info{version}` metric
The image version	`VERSION` / `VERSION_ID` in `/etc/os-release`, substituted at image build	`hostnamectl`, and anything reading `os-release`
The package version	The `.deb` control file	`dpkg-query -W wheelhouse-agent`, and the console banner's header
The base version	`VYOS_VERSION` in `/etc/os-release`; on a plain base box carrying only the package, `VERSION_ID`	The console banner's credit line, and `show version`

The web UI has two sources for the version it shows. The product block on GET /api/system is the box's own answer and always wins; failing that, VITE_WHEELHOUSE_VERSION, stamped into the bundle by the same job that builds the image. There is no hardcoded fallback constant, so an unstamped developer build with no agent block reports unknown.

What `show version` reports#

The operational CLI's show version is the base's own command and reports the base's own fields, with the image version it was built under. GET /api/version passes that data through unchanged, and GET /api/system parses it into key-value pairs for the System page.

The web UI resolves the product's identity from one block rather than by reassembling it out of that output. GET /api/system carries a product block that the agent builds from /etc/os-release plus its own compiled-in version: name, version, the agent build, the base, the architecture and boot_via. The block wins over the build-time stamp.

Reading it#

bash

cat /etc/os-release
hostnamectl                                   # Operating System: Wheelhouse OS 0.5.1
dpkg-query -W -f='${Version}\n' wheelhouse-agent
wheelhouse-agent version
cat /usr/share/doc/wheelhouse/SOURCES.txt     # image only

In Ansible, ansible_distribution is Wheelhouse and ansible_distribution_version is the image version; the base is ansible_facts['os_release']['VYOS_VERSION'] if your fact-gather keeps unknown keys.