Operating System#

Cleanroom OS is the Buildroot image booted by worker nodes. It lives in the cleanroom-os repository as a Buildroot BR2_EXTERNAL tree, so project-owned configs, overlays, and scripts stay separate from downloaded Buildroot releases and build artifacts.

Target#

The initial image targets Soekris net6501-70 boards:

x86_64 Buildroot system
Linux 4.19.204 kernel
bzImage for PXE boot
initramfs/cpio root filesystem
serial console on ttyS0 at 115200
DHCP on eth0

The net6501-70 has Intel 82574L Ethernet ports. The kernel builds e1000e directly into the image, so the NICs do not require the broad linux-firmware package. Avoid adding old e100 firmware unless a different hardware target needs it.

Image Contents#

The development image includes enough tools to make hardware bring-up practical:

Bash, BusyBox, CA certificates, and ethtool
OpenSSH server and client
root password and root SSH authorized keys for debugging
NTP and ntpdate
Avahi and nss-mdns
rsyslog for forwarding system logs off-node
eudev-backed dynamic device creation

The worker binary will be baked into the image once the worker interface is ready. Local OS logs are not durable; system logs should be forwarded, and job logs/artifacts belong to the controller.

Build Workflow#

Large files should stay outside synced repos. The default local work directory is:

~/.cache/cleanroom-os/

It contains:

archives/: downloaded Buildroot tarballs
buildroot/: extracted Buildroot source trees
dl/: shared package download cache
output/: Buildroot output directories and generated images

The normal build is:

make -C ~/repos/cleanroom-os build

Machine-local overrides go in cleanroom-os/build.env, which is ignored by git. Start from:

cp build.env.default build.env

Common overrides:

CLEANROOM_OS_WORKDIR=/storage/cleanroom-os-work make build
BUILDROOT_VERSION=2026.05 make build
OUTPUT_DIR=/tmp/cleanroom-os-build make olddefconfig

Expected artifacts are under:

~/.cache/cleanroom-os/output/soekris-net6501-pxe-<buildroot-version>/images/

The important PXE artifact is bzImage; rootfs.cpio and rootfs.tar are also generated for inspection and alternate boot flows.

First Full Build Notes#

A first-run build was tested using only the default cache path, pretending older /storage/buildroot state did not exist. The build completed and produced:

bzImage
rootfs.cpio
rootfs.tar

Fixes learned from that build:

Pin Linux headers to the selected kernel series with BR2_PACKAGE_HOST_LINUX_HEADERS_CUSTOM_4_19=y; otherwise Buildroot may fall back to incompatible headers and toolchain choices.
Do not include linux-firmware just for the Soekris NICs; it pulls a large firmware archive and is unnecessary for Intel 82574L with built-in e1000e.
Disable the ORC unwinder for Linux 4.19 builds unless the host has elfutils/libelf development headers. The tracked kernel config selects frame-pointer unwinding instead.
Old Linux 4.19 plus a modern host compiler emits warnings. Treat hard Buildroot exits as failures; warning noise alone is expected.

Upgrading Buildroot#

Do not edit files inside extracted buildroot-* directories. Upgrade by changing the version and validating the external tree:

make BUILDROOT_VERSION=2026.05 fetch
make BUILDROOT_VERSION=2026.05 OUTPUT_DIR=/tmp/cleanroom-os-upgrade olddefconfig
make BUILDROOT_VERSION=2026.05 OUTPUT_DIR=/tmp/cleanroom-os-upgrade build

If config symbols change, use Buildroot’s config tools through the wrapper:

make menuconfig
make savedefconfig
make linux-menuconfig
make linux-update-defconfig

Save durable changes back into cleanroom-os/configs/ or cleanroom-os/board/soekris-net6501/. Keep the downloaded Buildroot tree disposable.

Current Gaps#

Only eth0 is configured for DHCP today; the other Soekris ports should appear as eth1 through eth3 but are not auto-configured yet.
The worker binary and its init script still need to be added.
rsyslog forwarding needs a controller or collector target.
Root password and SSH debug access are intentional for bring-up, not a final production security posture.