Documentation

CLI Tools Reference

kldload ships a set of optional k* CLI tools for system management. All tools work identically across CentOS, Debian, Ubuntu, Fedora, Rocky, RHEL, and Arch.

Nothing is replaced. The native tools (zfs, zpool, apt, dnf, qemu-img, etc.) are untouched and always work directly. The k* tools are thin wrappers that simplify common operations by removing repetitive flags, adding sensible defaults, and taking advantage of the ZFS safety net (automatic snapshots before destructive operations, cleanup after upgrades, DKMS verification after kernel changes). They exist to reduce the number of steps in routine tasks — not to replace the underlying commands.

Note: The k* tools are included with the Desktop and Server profiles. The Core profile does not include them — it installs ZFS on root with stock distro tools only. See Editions.

Every tool below is a bash script. Not a compiled binary. Not a Python package. A bash script you can read with cat $(which ksnap). Each one wraps 3-10 ZFS or package manager commands into one command with sensible defaults. The value isn't the tool itself — it's the pattern it encodes. kpkg install encodes "snapshot before installing." kupgrade encodes "snapshot, upgrade, rebuild DKMS, verify." Once you understand the pattern, you can use the native commands directly. The tools are teaching you ZFS operational best practices by running them for you.

kst — System status

One-command health dashboard.

kst

Shows: - ZFS pool status (ONLINE/DEGRADED/FAULTED) - Root filesystem usage and compression ratio - Snapshot count and latest snapshot age - Boot environment count - Memory, CPU, uptime - Service status: kldload-webui, sshd, zfs-zed, sanoid.timer, NetworkManager

kst is the first thing you run when you SSH into a machine. It answers: is the pool healthy? How much space is left? When was the last snapshot? Are the services running? On a stock distro you'd run zpool status, zfs list, systemctl status, free -h, and uptime separately. kst runs all of them and formats the output on one screen. It's not clever — it's convenient.

ksnap — Snapshot management

ksnap                    # snapshot all key datasets
ksnap /home              # snapshot a specific path
ksnap list               # list all snapshots with dates and sizes
ksnap rollback /home     # roll back to the last snapshot
ksnap destroy <name>     # delete a specific snapshot

Snapshot naming: manual-YYYYMMDD-HHMMSS

kbe — Boot environments

kbe list                         # list all boot environments
kbe create my-checkpoint         # create a named BE
kbe activate my-checkpoint       # set it as the default for next boot
kbe rollback my-checkpoint       # roll back to a BE
kbe delete old-environment       # remove a BE

Boot environments are ZFS datasets under rpool/ROOT/. ZFSBootMenu lets you choose between them at boot time.

kbe is the most important tool here. It's the Linux equivalent of FreeBSD's bectl. Without it, boot environment management is: zfs snapshot rpool/ROOT/default@name, zfs clone rpool/ROOT/default@name rpool/ROOT/new-be, zpool set bootfs=rpool/ROOT/new-be rpool. Three commands that have to be right or the system doesn't boot. kbe create does all three. kbe activate switches the boot target. kbe rollback reverts. The value is that you'll actually use boot environments because the tool makes it easy enough to use before every risky change.

kclone — Copy-on-Write cloning

kclone /srv/production /srv/staging

Creates an instant ZFS clone. The clone starts at near-zero space and grows only as you make changes. Uses: - Testing database changes without affecting production - Creating dev/staging environments from live data - Duplicating any directory with zero copy cost

kdf — ZFS disk usage

kdf              # all datasets
kdf /home        # specific path

Shows: used/available space, compression ratio (color-coded), quota, mountpoint for every ZFS dataset. Also shows pool-level stats: size, allocated, free, fragmentation.

kdir — Create ZFS datasets

kdir /srv/myproject                               # create a dataset
kdir -p /srv/apps/frontend/static                  # create parents too
kdir -o compression=zstd -o quota=50G /srv/archive # with properties

Like mkdir, but creates a ZFS dataset instead of a plain directory. Each kdir path gets its own snapshots, compression, and quotas.

kclone and kdir change how you think about directories. On ext4, mkdir /srv/myapp creates a name in a directory tree. It shares the filesystem with everything else. On ZFS, kdir /srv/myapp creates a dataset — independent compression, snapshots, quota, encryption. kclone /srv/production /srv/staging gives you an instant copy that shares all blocks with the original. These aren't fancy wrappers — they're one-line commands that create storage domains instead of directory entries. The mental shift is: stop creating directories, start creating datasets.

kpkg — Universal package manager

kpkg install nginx       # install (auto-detects apt/dnf)
kpkg remove nginx        # remove
kpkg search redis        # search
kpkg info nginx          # package details
kpkg update              # refresh package lists
kpkg upgrade             # upgrade all packages
kpkg list                # list installed

Automatically takes a ZFS snapshot before every install/remove/upgrade. Snapshot naming: kpkg-YYYYMMDD-HHMMSS.

kupgrade — Safe system upgrade

kupgrade

Creates boot environment snapshot: pre-upgrade-YYYYMMDD-HHMMSS
Runs full system upgrade (apt dist-upgrade or dnf upgrade)
Cleans up old packages
Verifies ZFS DKMS modules for every installed kernel
Re-signs DKMS modules if Secure Boot is active

If the upgrade breaks something:

kbe activate pre-upgrade-20260321-143000
reboot

kexport — Disk image export

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

KEXPORT_NAME=myserver kexport qcow2   # custom filename

See export-formats.html for details on each format and how to import them.

kexport turns any kldload system into a deployment artifact. Install once on a KVM test VM. Verify it works. kexport all produces qcow2, raw, VHD, VMDK, and OVA from the same disk. Upload the raw to AWS as an AMI. Upload the VHD to Azure. Upload the qcow2 to Proxmox. Upload the VMDK to ESXi. Five platforms from one install. The image is the same bytes — just different container formats. The ZFS pool inside is identical everywhere.

krecovery — Disaster recovery

Boot from the kldload ISO to recover a broken system:

krecovery import rpool                    # import the ZFS pool
krecovery list-be                         # list boot environments
krecovery list-snapshots rpool/home       # list snapshots
krecovery activate <snapshot>             # set which BE to boot
krecovery rollback <snapshot>             # roll back a dataset
krecovery chroot                          # enter the system for manual fixes
krecovery reinstall-bootloader /dev/sda   # rebuild ZFSBootMenu
krecovery export-logs /mnt/usb            # copy logs for diagnosis

krecovery is the tool you hope you never need. Boot the kldload live ISO, run krecovery, and it walks you through importing the pool, listing boot environments, activating a known-good snapshot, and reinstalling the bootloader if needed. On a stock distro, recovering a broken boot means: boot rescue media, mount the root filesystem (which filesystem? which partition? which mount options?), chroot, fix GRUB, rebuild initramfs, pray. krecovery automates all of that for ZFS. The pool knows its own structure. The snapshots know their own history. Recovery is guided, not improvised.

kldload-webui — Web management UI

systemctl status kldload-webui    # check if running
systemctl restart kldload-webui   # restart

Access at http://<host>:8080. Features: - Disk selection and install wizard - ZFS dataset listing - System status and log viewing - WebSocket-based real-time log streaming during install

kldload-install-target — The installer

# Interactive (called by the web UI)
kldload-install-target

# Unattended with answers file
kldload-install-target --config /path/to/answers.env

See unattended-install.html for answer file format.

← kldload-core Basic operations →