kldload

BYOL0 — bring your own layer zero

A build tool that assembles a Linux distribution onto ZFS root from the vendor's own package repositories — and the artifact OS that falls out of it.

Boot environments, air-gapped installs, and a snapshot before every package transaction.

The family: kldload — the substrate · zxplore — the ZFS console · wgxplore — the WireGuard console · vmxplore — the VM console

There are two ways to use this.

1 — As a build tool, against your own Linux. It replaces the "download the .iso" step. dnf --installroot, debootstrap or pacstrap against the vendor's own CDN, then ZFS and NVIDIA compiled against the kernel that install just laid down, signed and MOK-enrolled so they load with Secure Boot left on. Nothing forked, nothing patched. The build stops wherever you decide — a plain install you finish by hand, or a fully baked image that gets deployed rather than installed.

2 — As the finished article. The ISO is what that build leaves behind: ZFS on root with boot environments, WireGuard, KVM, Kubernetes, an eBPF observability plane and a local AI stack, with the kernel and its out-of-tree modules pinned as one matched set so a routine update cannot separate them.

The thing it adds that a vendor image does not have: apt, dnf and pacman snapshot the root before every transaction, so reversing a failed upgrade is one command rather than a rescue USB and an evening.

Two substrates in the installer menu — Fedora and Debian — and two package managers underneath. Both install with the network unplugged, from complete mirrors baked into the ISO.

Website: kldload.com · Download: full ISO / net installer · Release notes: 1.4.2 · Discord: discord.gg/QX8wf38N3V

The install, in two screens. Boot the USB and this opens by itself — no terminal, no wiki. It is also reachable at https://<host>:8443 from another machine, for a box with no screen.

Pick what to build — the distribution, the profile, and what goes in:

Say where it goes, then start it:

First boot. Nobody drives this part. The machine bootstraps Kubernetes, pulls the AI model and builds its golden images on its own, then tells you whether anything was flagged.

zxplore — the ZFS console. Every dataset, every property, and the snapshot list that makes apt rollback possible.

Docker's layers are ZFS datasets. The storage driver is zfs, so a pull is a clone and every layer inherits the pool's compression.

wgxplore — the WireGuard estate. Four planes across the fleet, joined into one view, with every peer no host declares called out.

vmxplore — the VM estate. Grouped by what the machines are for rather than by name, with the guest's own screen rendered in the console — no separate viewer. Disks are ZFS zvols, so a clone is instant and a rollback is one command.

ztxplore — the OpenZFS test lab. Six distributions on zvols, each running the distro's own ZFS packages against its own kernel. Goldens are built once and cloned per run, and it reports what did not build as plainly as what did.

Kubernetes, HA by default. Three control planes behind a kube-vip VIP; adding a node reconciles the mesh, etcd and the firewall everywhere else.

Metrics, grouped. 29 Grafana dashboards: the estate, eBPF, the pool, and the OpenZFS test lab kept separate from it.

Legacy BIOS is absent by design, not untested: the installer writes GPT with an EFI System Partition and a ZFS pool, and Secure Boot, ZFSBootMenu, boot repair and rollback all operate on the ESP. See docs/INSTALL.md for the full detail.

# Download and burn (USB target)
curl -L -o kldload.iso https://dl.kldload.com/kldload-free-latest.iso        # full: offline mirrors, ~15 GB
curl -L -o kldload.iso https://dl.kldload.com/kldload-free-net-latest.iso    # or the net installer, ~2.2 GB
sudo wipefs -af /dev/sdX
sudo dd if=kldload.iso of=/dev/sdX bs=4M oflag=direct conv=fsync status=progress && sync

# Or build from source
git clone https://github.com/kldload/kldload.git && cd kldload
PROFILE=desktop ./deploy.sh build
sudo ./deploy.sh burn /dev/sdX      # names the device, shows it, asks before writing

The full image carries the offline mirrors, the Kubernetes images and the AI stack, about 15 GB. Two smaller ways to build it:

EDITION=net ./deploy.sh build            # tools only, ~2.2 GB — installs from the distros' mirrors
DARKSITES=fedora OLLAMA=no ./deploy.sh build   # one mirror, no AI stack — a Fedora-only offline desktop
./deploy.sh menu                         # a checklist that writes kldload.env and shows the size

PAYLOAD, DARKSITES (debian, fedora, el), K8S_IMAGES and OLLAMA are the knobs; ./deploy.sh help lists them with sizes. The ISO name says what it carries: -net, or -fedora for a single mirror.

Boot the USB → the web UI opens over TLS at https://<host>:8443 → pick distro + profile + disk → install.

Building saturates every core by default. To keep the machine usable while it runs, cap the compress step — it is the long one:

KLDLOAD_BUILD_PROCESSORS=$(( $(nproc) - 4 )) PROFILE=desktop ./deploy.sh build

Full-disk ZFS encryption is on by default and the flow is short:

1. Download & burn the ISO to a USB stick (see Quickstart above).
2. Boot the USB. The installer opens automatically in the browser at https://<host>:8443 — no login prompt.
3. Choose your distribution, profile, and target disk. Encryption is pre-selected (recommended) — set your disk encryption passphrase — and start the install.
4. When it finishes the machine reboots. Remove the USB stick.
5. At the ZFSBootMenu prompt, enter your encryption passphrase. It is asked once: first boot re-asks a second time while the system installs the key that makes the later boots single-prompt, and every boot after that takes one passphrase.
6. The desktop loads and the console opens at https://<host>:8443 — no certificate warning, no login prompt. Done.

The passphrase is always required. There is no configuration in which encryption is silently skipped, and turning Secure Boot on or off does not change that. TPM2 auto-unlock is on the roadmap.

Secure Boot is off by default. With it off the firmware boots ZFSBootMenu directly: no shim, no GRUB stage, no MOK enrollment, and nothing to miss at a ten-second prompt. That is the right default for a lab machine, and it is the path above.

Turn it on when the machine's threat model wants a verified boot chain, by setting KLDLOAD_ENABLE_SECURE_BOOT=1 at install time. The install then generates a per-install MOK, signs ZFSBootMenu and the out-of-tree modules with it, and boots firmware → shim → GRUB → kernel. That path needs three extra steps:

1. When the install finishes it powers the machine off rather than rebooting — so you control the enrollment boot instead of racing an auto-reboot. Remove the USB stick.
2. Power on and enter firmware setup (usually Del, F2, or F10). Enable Secure Boot, then save and exit.
3. On the next boot the blue MokManager screen appears — it waits only ~10 seconds, so press any key immediately, then: Enroll MOK → Continue → Yes → password kldload → Reboot. The password is literally kldload — not your admin or encryption password.

Missed the MokManager screen? Just reboot — kldload re-offers enrollment on every boot until the key is actually enrolled. No reinstall. If you end up at a "Secure Boot validation failed" screen instead, the app grid's Secure Boot Repair tool (or sudo kldload-mok-repair from any terminal — including the live USB) diagnoses and queues the fix in one step.

Full install walkthrough, including what each Secure Boot failure looks like and how to decide whether to run with it on at all: docs/INSTALL.md.

Secure Boot is off by default, and none of the below applies to a default install. These are the failure modes of the opt-in path (KLDLOAD_ENABLE_SECURE_BOOT=1).

Shouldn't happen on a fresh install — the console cert is issued by the kldload CA, which is trusted in the browser automatically. If a warning appears, re-import the CA root (clearing any stale entry first):

kldload-trust-cert                                              # re-import the CA root
# stubborn? drop stale entries first, then re-import:
certutil -d sql:"$HOME/.pki/nssdb" -D -n kldload-webui 2>/dev/null
certutil -d sql:"$HOME/.pki/nssdb" -D -n kldload-ca     2>/dev/null
kldload-trust-cert

Only remote browsers do — sign in with your admin account (a wheel/ sudo user). On the machine itself the console never prompts.

Those two are what the installer offers, because they are the two that get tested — and the two that deliver the offline promise. Everything else in the RPM and APT families is a network install, which is a different product from the one this README describes.

The method underneath is not distro-specific: kldload installs by calling dnf --installroot or debootstrap against a distribution's own repositories. Nothing is forked, nothing is patched, and no image is pre-baked for a given distro.

Which means the reachable set is wider than the tested one. RHEL, CentOS Stream, Rocky, Ubuntu and Arch all still work with KLDLOAD_DISTRO=<name> — the code paths are there and maintained — but they are not on the menu, not mirrored offline, and not tested, and the menu is the honest statement of what is. Adding one back is repository configuration, not new machinery.

Fedora and Debian are deliberately the widest useful pair rather than a narrow one: two package managers, two firmware-splitting conventions, two initramfs generators, and one leading-edge substrate against one stable one. Most bugs worth finding show up as a difference between them.

The honest bound: a new distribution needs its repos and keys declared, and its kernel paired with a version of OpenZFS that builds against it. That is a morning's work, not a port.

Live environment is Fedora 44 (kernel 7.0.x — currently 7.0.12 — with OpenZFS 2.4.3 on root).

Fedora 44 + ZFS: OpenZFS ships a native fc44 build (2.4.3), so there is no fc43 bridge. The kernel is not taken as whatever Fedora ships today: builder/kernel-pin.sh reads the ceiling OpenZFS itself declares (zfs-dkms Conflicts — 2.4.3 caps at kernel ≤ 7.0.999) and resolves the newest matching build, pulling kernel, -core, -modules, -devel and -headers as one set so they cannot be split. On the installed system that set plus NVIDIA is versionlocked at first boot, so a routine dnf update cannot pull a kernel ZFS has no build for.

A GUI-first workstation that looks like stock RHEL 10: expert operations — ZFS replication, KVM, Kubernetes, eBPF observability — exposed as point-and-shoot desktop apps, not CLI rituals.

• Install-time Platform Options. Checkboxes for NVIDIA drivers, KVM, Kubernetes, eBPF tooling, and golden-image building. Desktop-only, default-clean — you opt into the heavy stuff.
• Native app windows. Each tool (VMs, Kubernetes, ZFS, Metrics, the model, …) opens as its own chromeless GTK/WebKit window — no browser chrome, no left menu — backed by the same web console the server edition serves.
• Console as its own app. The tmux F-key operator cockpit (k9s, ZFS internals, eBPF panels, VM/log streams) is a single Console application — not embedded inside every tool window.
• Local model. Ollama with Open WebUI (plus RAG and voice) as a desktop app. No cloud, no telemetry.

kube-cluster up           # single- or three-node K8s in < 20 minutes
kube-demo                 # PetClinic + ArgoCD smoke test
klab golden centos        # build the CentOS golden VM
klab matrix run script.sh # run a change against every supported distro in parallel

• OpenZFS on root — checksummed, compressed, snapshotted, self-healing on mirrors. lz4 default. Native AES-256-GCM encryption recommended and pre-selected in the installer (TPM2 auto-unlock when the hardware has it, passphrase at boot otherwise); dedup optional.
• ZFSBootMenu — UEFI bootloader that understands ZFS. Boot environments. Seconds-fast rollback. No GRUB.
• WireGuard — kernel-level encrypted networking. One UDP port at the firewall.
• eBPF observability — BCC tools + bpftrace + an F-key tmux cockpit on the host; Cilium + Hubble + Tetragon inside the K8s profile (no kube-proxy, no iptables, no sidecars).
• KVM hypervisor — libvirt + qemu-kvm with every VM on a ZFS zvol. ~100 ms clones via COW. Atomic snapshots. fs-freeze app-consistency. Incremental zfs send replication.
• Docker & podman on ZFS — every image layer is a real dataset, not a directory inside an overlay. A pull is a clone, layers inherit compression, and the whole container estate — layers, the engine's database and the volumes — snapshots and replicates as one recursive zfs send. Measured: a running container cloned and started in 328 ms with its state intact, and 24.7 GB of estate in a single stream. Docker on the apt distros, podman on the RPM ones. The full list of what this replaces →
• NVIDIA + CUDA — drivers and CUDA optional at install. Time-sliced GPU sharing across the model and guest VMs. No PCIe passthrough required.
• Ollama + Open WebUI — local model: RAG over the codebase + voice + tmux awareness + ReAct agent loop + eBPF-aware tool registry. No cloud, no telemetry.
• Observability — Prometheus + Grafana + Loki + Alertmanager, Go + bash exporters, pre-wired dashboards, zed ZFS events bridged to Loki.
• Secure Boot + MOK — per-machine key generation, automatic module signing, DKMS auto-sign on kernel upgrades. Off by default.
• Image export — kexport produces qcow2 / VMDK / VHD / OVA / raw, auto-sealed with cloud-init multi-datasource config. Ready for Packer or direct hypervisor import.
• Offline + Air-gap — RPM and APT mirrors baked in. The USB is the deployment, the recovery, and the air gap.

kldload invents almost nothing. It is an opinionated assembly of software you already know, installed from the vendors' own repos and wired together so the pieces actually meet. If you recognise a name below, that is the point — you already know how to operate it, and nothing here is a bespoke reimplementation you would have to learn.

Nothing is forked and nothing is patched. The tree carries zero .patch files and zero vendored third-party source; every component arrives from its upstream package repo, its official release artifact, or its own git remote.

Two shipped components are not open source, and it would be dishonest to bury them in a list like this: Google Chrome (the default desktop browser and the renderer for the kldload GUI apps — its open-source upstream Chromium is what Debian targets get) and the NVIDIA driver + CUDA, which is opt-in at install. Everything else below is open source under its own licence.

No cloud, no telemetry, no API key — the models and the index live on the machine.

GParted, TestDisk/PhotoRec, ddrescue, fsarchiver, smartmontools, nvme-cli, p7zip, ntfs-3g/exfatprogs, fio, stress-ng, memtest86+ — the install USB doubles as the recovery USB.

The installer bootstraps each target with that distro's own tool — debootstrap for Debian and dnf --installroot for Fedora. The same two paths reach the rest of their families when driven directly, but only these two are on the menu and tested. Packages come from the vendors' own CDNs; the ISO itself is built with Red Hat's lorax, dracut, squashfs-tools and xorriso inside a Fedora 44 container.

Three of the consoles are their own BSD-3 projects by the same author, with their own repos and release cadence. kldload builds each from its own upstream at ISO-build time and records the exact commit it shipped, so an installed system can say precisely what it is running:

wgxplore now has its own repo, but the copy kldload builds and ships is the in-tree wg/ — folded in on 2026-08-10 as a read-only estate lens, which is why its recorded commit is kldload's HEAD rather than a separate upstream. The two have since diverged, with the in-tree copy carrying work the standalone repo does not, so treat wg/ as the source of what is on the ISO.

They run on any Linux or BSD box — kldload is their first-party distribution, not their owner.

Licences are each project's own; kldload ships them unmodified and adds no licence terms of its own to them. See License for kldload's.

apt, dnf and pacman are symlinked to kldload-pkg-wrapper at install, so these are the normal commands — a script, unattended-upgrades or the GUI updater get the same protection.

Rollback clones the snapshot into a new boot environment rather than running zfs rollback, which cannot touch a mounted root and would destroy every newer snapshot. Nothing is overwritten.

Live environment:  Fedora 44 (kernel 7.0.x, OpenZFS 2.4.3)
Builder:           Fedora 44 container (lorax + squashfs-tools + xorriso + dracut)
Bootstrap paths:   dnf --installroot  (Fedora)
                   debootstrap        (Debian)

Installer:         Python web UI + ~10 bash libraries (lib/) + backend/bin tools
Web UI:            single HTML file per edition + WebSocket install-log stream
Single-port TLS:   kldload-proxy fronts the web UI, Grafana, Prometheus, Headlamp,
                   Bob, k9s/ttyd, and the libvirt console on one URL (:8443) with one cert

The user picks the target distro at install time. After install the system runs upstream packages from the vendor's public repos. There is no kldload package repository and no kldload-specific runtime updates — dnf update / apt upgrade / pacman -Syu just work.

Current release: 1.4.2 — Hardware (August 2026). 195 commits since 1.4.1: 30 features, 127 fixes, 120 files changed.

• Full changelog: CHANGELOG.md
• Release notes, with screenshots: kldload.com/releases/1.4.2.html
• History back to 1.0: kldload.com/release-notes.html

Every release is tagged, so git show v1.4.2 is the exact tree an ISO was built from. Cutting one: docs/RELEASING.md.

BSD-3-Clause. See LICENSE.