ZFSBootMenu: a bootloader for root-on-ZFS with snapshots and encryption

A small Linux system whose only job is to boot another one

ZFSBootMenu is a Linux bootloader that attempts to provide an experience similar to FreeBSD's bootloader. The key idea is that the boot loader is not a small program in a reserved sector, it is a whole small operating system, one that happens to know how to find other Linux kernels and initramfs images inside ZFS filesystems.

The README describes it as a small, self-contained Linux system. When a suitable kernel and initramfs are identified, either through an automatic process or through direct user selection, ZFSBootMenu launches that kernel using the kexec command. So the flow is: the machine powers on, ZFSBootMenu comes up, it finds the bootable environments, the user picks one or lets it pick, and the chosen kernel is loaded into memory and started with kexec without a reboot.

What the ZFS features buy is the rest of the README. A user can have multiple boot environments, with different distributions for example, manipulate snapshots before booting, and, as the README puts it, for the adventurous user even bootstrap a system installation via zfs recv. That last one is the interesting capability: a new system can be received over the network into a ZFS dataset and booted, which is a form of installation that does not involve an installer at all.

The project also has its own documentation site, a primer called Boot Environments and You that explains the boot environment model for people who have not used one, and an IRC channel on libera.chat. The repository carries a cpanfile and a .perltidyrc, which is a hint about the implementation language, and a docs/ directory with man pages under docs/man/dist, split into man5, man7 and man8 sections, so the configuration file, the library and the command line tools are all documented.

The Makefile shows exactly what gets installed where

The Makefile is short and it is the best available description of what the package contains. The install target depends on core, dracut, initcpio and zbm-release, so a single make install covers the main system plus both initramfs integrations.

The paths it writes to are conventional Unix ones. The core system goes to $(DESTDIR)/$(MODDIR)/zfsbootmenu with MODDIR set to /usr/share, so /usr/share/zfsbootmenu, and the configuration file lands in /etc/zfsbootmenu, with CONFDIR set to /etc/zfsbootmenu, and the file is etc/zfsbootmenu/config.yaml. The binaries in bin/ are installed to /usr/bin, and the man pages are split by section, the man5 pages describing the configuration, the man7 pages the library and the man8 pages the commands.

The two initramfs integrations are the interesting part, because they are what makes the bootloader able to read the pool in the first place. The dracut target installs a module into /usr/lib/dracut/modules.d/90zfsbootmenu, with a 90 prefix so it sorts late, and the initcpio target installs the initcpio tree into /usr/lib/initcpio and drops an etc/zfsbootmenu/mkinitcpio.conf into the configuration directory.

There is also a set of hooks and examples installed under /usr/share/examples/zfsbootmenu, with contrib/* going into a hooks subdirectory, and the examples/ directory supplies a refind_linux.conf and a syslinux.cfg. The media/splash.bmp is installed alongside them, which is the boot splash image. The version script is releng/version.sh, run by the show-version target, and there is a separate zbm-release target that calls it with an update flag.

Two initramfs ecosystems, one bootloader

The presence of both dracut/ and initcpio/ directories in the repository is the clearest structural fact about the project, and it is a deliberate choice rather than an accident. Dracut is the initramfs generator used by the Fedora and Red Hat family, and mkinitcpio is the one used by Arch, and a bootloader that wants to find a root-on-ZFS pool has to be able to run inside either kind of initramfs environment to get there. Supporting both means the same bootloader has to be integrated into two different module and hook conventions.

The Makefile reflects that split cleanly. The dracut target installs a directory tree into /usr/lib/dracut/modules.d/90zfsbootmenu and copies the dracut configuration fragments into /etc/zfsbootmenu/dracut.conf.d/. The initcpio target installs into /usr/lib/initcpio and puts a single mkinitcpio.conf in /etc/zfsbootmenu. The core install is shared.

For a user, this means the package is installable on either family, but the configuration you write is not identical between them, since the two initramfs systems have different hooks and different ways of expressing what runs early. The repository topics list dracut, initcpio and mkinitcpio, and also void-linux, which is a distribution built around runit and its own initramfs approach, and the examples directory shows syslinux and refind configuration for reference.

The docs/ directory also holds the manual pages, and the readthedocs configuration at the root with a .readthedocs.yaml is what builds the documentation site, so the same source produces both the web documentation and the man pages.

Snapshots and encryption are the two features that justify it

The description names the two capabilities in the project title area, snapshots and native full disk encryption, and the README body explains the first of them. Manipulating snapshots before booting is the operation that changes the day to day behaviour of a root-on-ZFS machine. If a kernel update goes wrong, the rollback is not a package manager operation and a reinstall, it is choosing an earlier snapshot at the boot menu, before any of the broken system is loaded. Because the bootloader is a separate small system, it can mount the pool and act on it even when the operating system it is booting is unbootable.

The second is encryption, and the phrase native full disk encryption in the description means the encryption is handled by the bootloader and the ZFS stack itself rather than by an external mechanism such as a LUKS container or a hardware encrypted volume presented to the pool. The difference matters operationally. With the boot loader handling it, there is one fewer layer between the data and the key, and the system can be unlocked by a single passphrase at the boot menu rather than by unlocking a volume and then selecting an environment.

The zfs recv capability belongs to the same family. Because a ZFS dataset can be received over the network and the bootloader can find it, a new system can be installed by receiving a stream rather than by running an installer, and the same mechanism gives a natural path for replicating an environment to another machine.

The cost of all this is that the bootloader is a system to maintain. A traditional bootloader is a few hundred kilobytes that rarely change, while this one is a Linux distribution with its own release cycle, and the repository's own versioning shows it, with v3.0.0 and v3.0.1 in January 2025 and v3.1.0 in January 2026.

Where ZFSBootMenu is the wrong tool

Three cases argue against it. The first is a machine that does not use ZFS for root. The whole design presumes a root-on-ZFS system, and the repository topics, openzfs, zpool, zfsonlinux and snapshots, make that plain. If your root filesystem is ext4 or btrfs, the boot environment and snapshot model you are being sold does not apply, and a conventional bootloader plus your distribution's own tooling is the better answer.

The second case is a distribution that manages the bootloader for you. Installing ZFSBootMenu means taking over the boot path of a machine that a distribution's installer and upgrade process also want to control. The upgrade behaviour described in the README, where the bootloader must be reinstalled or re-run after certain operations, is the kind of friction that appears again at every kernel upgrade if the two do not cooperate.

The third case is hardware that cannot run the extra layer. The bootloader is a full Linux system with a kernel and an initramfs of its own, and it has to run before your real kernel and initramfs, which means it needs to fit in whatever early boot space the platform gives it and that the platform's firmware can load. This is a real constraint on some configurations, particularly with encrypted volumes where the space is contested.

There is also a philosophical point. A bootloader that can mount a ZFS pool, roll back snapshots and bootstrap a received system is a system with a great deal of power running before anything else does. That is exactly what you want when your root filesystem is on ZFS and you need to recover it, and it is a large amount of trusted computing base for a machine that might not need it. The MIT licence means you can read the code, and the repository publishes the man pages and the source, which is the right posture for something in that position, but the decision to hand it that power is a decision about risk, not about features.

Editorial conclusion

ZFSBootMenu suits a Linux administrator who runs root-on-ZFS, keeps several boot environments or snapshots, and wants a menu at power on with the ability to roll back before the kernel starts. It does not suit a machine with a conventional root filesystem, and it does not suit a distribution whose packages manage the bootloader for you without cooperation. Before you adopt it, read the documentation and the Boot Environments and You primer linked from the README, and note that the last push was on 2026-08-16 with the newest release v3.1.0 from 2026-01-01.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zbm-dev/zfsbootmenu on GitHub