Documentation

What is kldload

kldload is the re-packer. It builds the image. kldload is what you’re running afterward — an opinionated OS layer on top of your chosen distro that gives you ZFS on root, universal CLI tools, boot environments, offline package mirrors, and a consistent experience across nine operating systems.

This page covers what OpenZFS gives you that a stock Linux install doesn’t.

The short version: kldload is a stock Linux distro (or FreeBSD) with kernel modules baked in at build time. The OS underneath is unmodified. apt, dnf, pacman, pkg — they all work exactly as they do on a stock install. What kldload adds is: ZFS on root (properly configured), boot environments (via ZFSBootMenu), WireGuard (kernel module, not a daemon), optional tools that abstract cross-distro differences, and automatic snapshots. Everything added is optional. Everything underneath is stock. The core profile ships nothing but ZFS on root and a vanilla distro.

Just want ZFS on root with no extras? Choose the Core profile during install. You get ZFS on root, ZFSBootMenu, and a stock distro — nothing else. See Editions & Profiles.

Nothing removed, everything optional

kldload does not modify, patch, replace, or remove anything from the base distro. apt, dnf, zfs, zpool, systemctl — they all work exactly as they do on a stock install. The underlying OS is completely standard.

What kldload adds is a set of optional k* convenience commands that automate common tasks and provide a consistent interface across distro families. You can use them, or ignore them entirely and operate the system with native tools. Both approaches are fully supported.

One optional command set across Debian and CentOS/RHEL

Every kldload system ships the same k* CLI tools regardless of distro. If you don’t want to remember whether it’s apt or dnf, dpkg -l or rpm -qa, the k* tools abstract away the differences:

You type	On CentOS/RHEL it runs	On Debian it runs
`kpkg install nginx`	`dnf install -y nginx`	`apt-get install -y nginx`
`kpkg remove nginx`	`dnf remove -y nginx`	`apt-get remove -y nginx`
`kpkg search redis`	`dnf search redis`	`apt-cache search redis`
`kpkg update`	`dnf check-update`	`apt-get update`
`kpkg upgrade`	`dnf upgrade -y`	`apt-get upgrade -y`
`kpkg list`	`rpm -qa \\| sort`	`dpkg -l`
`kpkg info nginx`	`dnf info nginx`	`apt-cache show nginx`

And every kpkg install, remove, and upgrade takes an automatic ZFS snapshot first. If a package breaks something, roll back in seconds.

This is significant: you can write scripts, documentation, and automation that work across all distro families with zero conditional logic. kpkg install htop tmux nginx works on CentOS, Debian, Ubuntu, Fedora, Rocky, RHEL, and Arch.

This isn't about replacing package managers. It's about what happens around the package operation. On a stock distro, apt install nginx installs nginx. If it breaks your system, your options are: uninstall and hope, or reinstall from scratch. On kldload, kpkg install nginx does three things: snapshots the root filesystem, runs the native package manager, and logs the operation. If nginx's postinst script corrupts your Apache config, rolls back a library, or does anything unexpected — ksnap rollback undoes the entire operation atomically. The package manager is the same. The safety net is new.

Automatic safety net for every operation

kldload tools create ZFS snapshots before destructive operations:

Tool	Snapshot before	Naming
`kpkg install`	Package install	`kpkg-YYYYMMDD-HHMMSS`
`kpkg remove`	Package removal	`kpkg-YYYYMMDD-HHMMSS`
`kpkg upgrade`	Package upgrade	`kpkg-YYYYMMDD-HHMMSS`
`kupgrade`	Full system upgrade	`pre-upgrade-YYYYMMDD-HHMMSS`
`ksnap`	Manual snapshot	`manual-YYYYMMDD-HHMMSS`

Plus sanoid runs automatic hourly/daily/weekly/monthly snapshots in the background.

The result: you can’t permanently break your system with a package operation. Every change is reversible.

Boot environments

Stock Linux doesn’t have boot environments. If a kernel update breaks your system, you’re in recovery mode or reinstalling.

kldload gives you ZFSBootMenu + boot environments:

kbe create before-risky-change    # checkpoint
kupgrade                          # upgrade the system
# Broken? Reboot, pick the old BE from the menu
# Or: kbe activate before-risky-change && reboot

Every upgrade, every kernel change, every module rebuild — you can always go back to the last working state in one command.

BSD has had boot environments since 2012 (beadm on FreeBSD, beadm on illumos). It's the reason BSD sysadmins don't worry about upgrades. Linux never had this because Linux never had ZFS on root. kldload brings the BSD operational model to Linux. The name kbe is deliberate — it's the Linux equivalent of bectl. Same concept, same workflow, different kernel.

What this means in practice: you can upgrade the kernel, the init system, glibc — literally anything — and if it breaks, you're one reboot away from the previous state. Not "restore from backup." Not "chroot from a rescue disk." Pick the old boot environment from a menu and press Enter. 15 seconds. The broken upgrade is still there — you just aren't booting it. Fix it later, or destroy it and try again.

ZFS on root (not bolted on)

Stock CentOS and Debian don’t support ZFS on root out of the box. Getting ZFS on root working manually requires:

Custom partitioning (EFI + ZFS partition)
Pool creation with the right properties (ashift, compression, acltype, xattr, relatime)
Dataset hierarchy (separate /home, /var/log, /var/cache, /srv)
DKMS module build for the running kernel
Initramfs with ZFS support
Bootloader that understands ZFS (ZFSBootMenu or GRUB with ZFS patches)
Hostid configuration (zgenhostid)
Proper fstab/mount ordering

kldload does all of this automatically during install. The dataset hierarchy is deterministic:

rpool
├── ROOT/default      /                (the OS)
├── home              /home            (user data, separate snapshots)
├── root              /root
├── srv               /srv             (application data)
└── var
    ├── log           /var/log         (logs, separate snapshots)
    ├── cache         /var/cache       (no auto-snapshot, cache is disposable)
    └── tmp           /var/tmp         (no auto-snapshot)

Each path is an independent ZFS dataset with its own snapshot schedule, compression settings, quotas, and send/receive replication.

The 8 things kldload automates that you'd have to do by hand: partitioning (EFI + ZFS), pool creation with production-grade defaults, dataset hierarchy, kernel module compilation and MOK signing, initramfs with ZFS embedded, ZFSBootMenu installation, hostid generation, and proper mount ordering. On a stock distro, getting all 8 right takes an experienced admin 1-2 hours. Getting any one wrong means the system won't boot. kldload does all 8 in 2 minutes, tested across 9 operating systems, with the same result every time.

The module is compiled and signed at image build time — not on the target machine. No compiler on the target. No DKMS in the boot path. The kernel and the module ship as a matched pair. Read about the three models: userland, DKMS, and build-time.

Offline installation

Both RPM and APT package mirrors are baked into the ISO:

~900 RPMs for CentOS/RHEL installs
~2,700 .debs for Debian installs

No internet required. Boot from USB, pick your distro, install. This matters for: - Air-gapped environments - Unreliable network connections - Consistent, reproducible installs (same packages every time) - Fast deployment (no downloading 2GB+ of packages per machine)

Instant CoW cloning

kclone creates copy-on-write clones of any directory:

kclone /srv/production /srv/staging

The clone is instant (takes milliseconds) and starts at near-zero disk space. Only divergent blocks consume space. Use cases:

Clone a production database for testing
Create a staging environment from live data
Duplicate a project directory without doubling disk usage

Multi-distro from one ISO

One ISO installs nine operating systems:

CentOS Stream 9, Fedora 41, Rocky Linux 9, RHEL 9 — RPM-based, offline via darksite
Debian 13, Ubuntu 24.04 — APT-based, offline via darksite
Arch Linux — pacman, internet required (rolling release)
FreeBSD 15.0 — native ZFS, base sets downloaded on demand
OpenBSD 7.8 — chain-boot install, experimental

Same USB stick, same installer, same ZFS layout, same boot environments. Each distro uses its native tools (dnf, apt, pacman, pkg). The k* tools provide a consistent interface across all of them.

Nine operating systems from one USB is not a gimmick. It's the consequence of the re-packer design. kldload doesn't ship a custom distro. It downloads vendor packages and assembles vendor images with kernel modules baked in. Each distro is installed using its own native tools: dnf --installroot for RPM distros, debootstrap for Debian/Ubuntu, pacman --root for Arch, base set extraction for FreeBSD. The result is a stock vendor install with ZFS on root. Not a fork. Not a remix. Your distro, with the modules the vendor chose not to ship.

Export to any hypervisor

kexport converts a running system to portable disk images:

kexport qcow2   # KVM / Proxmox / OpenStack
kexport vhd     # Azure / Hyper-V
kexport vmdk    # VMware ESXi / vSphere
kexport ova     # VMware / VirtualBox
kexport raw     # dd-ready image

Build one system, deploy it everywhere.

Health dashboard in one command

kst

Instantly shows pool health, disk usage, compression ratios, snapshot counts, boot environments, memory, CPU, uptime, and service status. No setup, no agents, no configuration.

What’s not changed

kldload is deliberately non-invasive. The base distro is stock:

Kernel — unmodified distro kernel. ZFS is compiled against it and signed at image build time — not a custom kernel.
Package managers — apt and dnf are untouched. kpkg wraps them optionally; it does not replace, intercept, or modify them.
Init system — stock systemd. No custom init, no wrapper services around systemd.
Filesystem tools — zfs, zpool, zdb are standard OpenZFS. The k* tools call them underneath.
Network stack — standard NetworkManager. WireGuard is the stock kernel module.
No proprietary components — everything is open source (BSD 3-Clause).
No lock-in — exports to any format, runs on any hardware. kexport uses qemu-img, not a custom tool.

If you uninstalled every k* tool, you’d have a standard distro with ZFS on root. The k* tools are additions, not modifications.

This is the design principle that matters most. kldload is not a distro. It’s a layer. Remove the layer and the distro underneath is untouched. This means: vendor security patches still apply. Vendor documentation still applies. Vendor support (for RHEL) still applies. Your team’s existing knowledge of CentOS, Debian, Ubuntu, or Arch still applies. Nothing was forked. Nothing was replaced. Everything was added, and everything added is optional.

The entire value of kldload is in the kernel modules (ZFS, WireGuard — compiled and signed at build time) and the convenience tools (kpkg, ksnap, kbe — readable bash scripts). The kernel modules give you capabilities the vendor didn’t ship. The tools make those capabilities accessible. Remove either and the other still works. Remove both and you have a stock distro that happens to have a really well-configured ZFS pool.

← Containers on ZFS — Docker, Podman & Firecracker. kldload-core →