| pick your distro, get ZFS on root
kldload — your platform, your way, free
Source
How Things Actually Work

What nobody teaches you anymore.

There was a time when using a computer meant understanding how it worked. Not all of it — nobody knows all of it — but the important parts. How it boots. How programs talk to the kernel. How data gets to the disk. How a packet gets from here to there.

That knowledge is disappearing. Not because it's obsolete — it's more relevant than ever — but because the industry decided abstractions are better than understanding. Use Kubernetes. Use Terraform. Use Docker. Don't ask how. Just kubectl apply and move on.

The problem is: when abstractions break — and they always break — you need to understand what's underneath. And if nobody taught you what's underneath, you're stuck. You can't debug what you don't understand.

kldload isn't just an installer. It's a working reference implementation of how a Linux system actually boots, from UEFI firmware to userspace. Every script is readable. Every choice is documented. When you install kldload, you can open the scripts and see exactly how it works. That's the point.

This page exists because the boot chain is where everything important happens — and almost nobody understands it. Security people worry about runtime attacks while the boot process is unverified. SREs troubleshoot application problems when the root cause is a kernel module that didn't load. Developers deploy containers without knowing that every container shares the same kernel and the same boot chain. If you understand what's below, you can fix what's above. If you don't, you're guessing.

How your computer actually boots

Most people think booting is: press power, wait, see login screen. Here's what actually happens, and what kldload does at each stage:

1. Firmware (UEFI)

The CPU wakes up and runs the firmware burned into your motherboard. UEFI looks at a special partition on your disk (the EFI System Partition) and finds a .EFI binary to run. That binary is your bootloader. The firmware doesn't know or care what operating system you have. It just runs the binary.

The firmware is the building superintendent. It unlocks the front door and lets in whoever's name is on the list.
kldload: one EFI binary on the ESP. That's ZFSBootMenu.EFI (Linux) or loader.efi (FreeBSD). Secure Boot verifies its signature before running it. If someone replaced it with malware, the firmware catches it here. Most distros put GRUB here. kldload puts ZFSBootMenu — which can read ZFS directly, eliminating the need for a separate /boot partition on ext4.

2. Bootloader (ZFSBootMenu)

On a kldload system, the bootloader is ZFSBootMenu. It scans your ZFS pools, finds all the boot environments, and shows you a menu. Pick one, and it loads that environment's kernel and initramfs into memory. This is where boot environments become powerful — you can switch between completely different system states at this point.

The bootloader is the elevator. It knows about every floor and lets you pick which one to go to.
This is why boot environments work. ZFSBootMenu sees every dataset under rpool/ROOT/ as a bootable system. Upgrade broke something? The pre-upgrade snapshot is still there. Pick it from the menu. Boot in 15 seconds. No rescue USB. No reinstall. No GRUB recovery mode. Just a menu of known-good states. BSD has had this for 20 years with beadm. Linux has it now because of ZFSBootMenu.

3. Initramfs (the mini operating system)

The kernel starts, but it can't mount ZFS yet — ZFS support is a module, and modules live on disk, and the disk is ZFS. Chicken and egg. The solution: the initramfs is a tiny Linux environment packed into RAM that contains just enough to load the ZFS module, import the pool, and mount the real root filesystem. Then it hands off to the real system.

The initramfs is a temporary scaffolding. You build it to reach the roof, then take it down once the building is standing.
This is where kldload's build-time approach pays off. The ZFS module inside the initramfs was compiled and signed during image creation. It matches the kernel exactly. On a traditional system, DKMS builds the module after install — and if a kernel update changes the ABI, the initramfs has the wrong module and the system doesn't boot. kldload ships the kernel and the module as a matched pair. The initramfs is correct by construction, not by luck.

4. systemd (the service manager)

Once the real root is mounted, systemd takes over. It reads unit files that describe every service the system should run, figures out the dependency graph, and starts everything in parallel. Network, SSH, logging, your web server — all managed by systemd. Every service is isolated, restartable, and observable.

systemd is the orchestra conductor. Every musician (service) knows their part, but the conductor decides when everyone starts playing and makes sure nobody's out of sync.
By the time systemd starts, ZFS is mounted, WireGuard module is loaded, and eBPF is available. The kernel modules were ready before systemd existed. This is the difference between "available at second zero" and "starts 5-7 seconds into boot." A WireGuard tunnel configured in systemd-networkd comes up in the first wave of services — before SSH, before your web server, before anything that talks to the network. Your application boots into an already-encrypted network. It doesn't have to wait for a VPN daemon to start.

5. Your application

Now you're in userspace. Everything above this point exists to get you here. All those layers — firmware, bootloader, initramfs, kernel, systemd — they're infrastructure. They exist so your code can run safely, reliably, and fast. Understanding them means understanding why your application behaves the way it does.

You don't need to know how the plumbing works to take a shower. But when the water stops, the person who understands the pipes fixes it in five minutes. Everyone else waits for the plumber.

This is the whole boot chain. Five stages. Every layer verified, every module signed, every block checksummed.

Most people never see this. They press power and see a login screen. The five stages between those two events are where security lives, where performance is determined, where reliability is decided. Understanding them is the difference between someone who deploys systems and someone who can fix them.

Every step described above corresponds to a function in the kldload source code:

Stage 1 (EFI)        → k_install_bootloader()    in bootloader.sh
Stage 2 (ZFSBootMenu) → k_zbm_find_efi()          in bootloader.sh
Stage 3 (initramfs)  → update-initramfs / dracut   in bootloader.sh
Stage 4 (systemd)    → k_enable_firstboot()        in profiles.sh
Stage 5 (your app)   → that's your job

Read them. They're bash scripts written to be read. cat $(which kldload-install-target) shows you the entire installer. The source code is the documentation.

← Your filesystem is lying to you. The conversation nobody is having. →