Build Your Own

kldload is a re-packer. It gives you the base — a bootable ISO with ZFS on root, WireGuard, eBPF observability, and your choice of nine distributions — and you build what you need on top. Not a pre-baked appliance. Not a black-box image. A starting point that respects your judgment about what your infrastructure should look like.

This hub page is your map to the entire Build Your Own section. Start with the Getting Started guides if you are new, jump to an Infrastructure or Services recipe if you know what you want, or use the Quick Start Paths and Architecture Decision Tree further down to find the right approach for your situation.

Every kldload build follows the same three-step loop: configure, install, customize. You express your intent through environment variables and answer files. The installer reads those variables, partitions your disk, lays down ZFS, bootstraps the target distro, and hands off to your postinstall scripts. The entire process is deterministic — the same inputs always produce the same system.

The beauty of this loop is that it is repeatable. Check your answer file and postinstall script into git. Run the same build on bare metal, in a VM, or through Packer. Deploy ten identical edge servers or a hundred CI runners. Every build is auditable, diffable, and version-controlled.

New to Build Your Own? Start here. These five guides take you from zero to a fully customized system — understanding the concepts, writing your first answer file, integrating with infrastructure-as-code tooling, writing postinstall scripts, and knowing every variable at your disposal.

Production-tested blueprints for common infrastructure roles. Each recipe includes a complete answer file, a postinstall script, a bill of materials (hardware or VM specs), and operational notes. These are not toy examples — they are the configurations we run and the configurations our users deploy in production.

Purpose-built service stacks that take advantage of ZFS features most traditional deployments ignore. Instant snapshots for consistent database backups. Clones for zero-cost staging environments. Compression that halves your storage bill. These recipes show how to deploy common services the kldload way.

Not sure where to begin? Find your goal below and follow the recommended path. Each path lists the pages to read in order, the profile and distro to choose, and the key environment variables to set.

kldload has four profiles that determine what gets installed. Choosing the right one is the single most important decision in your build. Use this decision tree to find yours.

Not sure? Start with server. It is the most versatile profile — you get everything kldload offers without the overhead of a GUI. You can always add GNOME later with a single package group install, or strip tools you do not need. The server profile is the default for a reason.

kldload supports nine distributions. Each uses its native package manager and bootstrap tool — there is no abstraction layer, no custom package format. The OS you install is the same OS you would get from the vendor, plus ZFS on root.

One of kldload's defining features is the ability to install completely offline. The ISO ships with embedded package mirrors ("darksites") for RPM distributions (CentOS, RHEL, Rocky, Fedora), Debian, and Ubuntu. These mirrors contain every package needed for a full installation — base system, ZFS DKMS modules, kernel, firmware, and all kldload tools. No network required.

Offline capability is not just a convenience — it is a security property. When you install from the darksite, you know exactly which packages are being installed because they were baked into the ISO at build time. No supply-chain surprises, no CDN compromises, no man-in-the-middle on package downloads. The ISO is your bill of materials.

An answer file is a shell-sourceable file of environment variables. It completely describes a build. When you pass an answer file to kldload-install-target, the installer reads every variable and uses it to drive the installation. No interactive prompts, no ambiguity, no "it depends on the phase of the moon" surprises.

See the Environment Reference for the complete list of variables, or browse the recipes in this section for real-world examples you can copy and modify.

Postinstall scripts are the extension point where your build becomes yours. The installer calls your script after the base OS is installed and configured but before the first reboot. Here are the patterns that appear across most production builds.

For a complete treatment of the postinstaller API and more patterns, see the Postinstallers guide.

This section (Build Your Own) and the Appliance Recipes section serve different audiences. Understanding the distinction helps you find the right starting point.

In practice, many users start with an appliance recipe and evolve it into a custom Build Your Own configuration as their needs grow. The two approaches use the same underlying mechanisms — the difference is in how much you customize.

Build Your Own scales from one machine to thousands. The same answer file that installs a single edge server can deploy a fleet of identical systems when combined with Packer, Terraform, and Ansible. Here is how the pieces fit together at scale.

You have the map. Now pick a path and start building.