How ZFSBootMenu Boots a Linux System on ZFS

Updated

ZFSBootMenu boots Linux by first starting a small, self-contained Linux image (either a UEFI application or a dedicated kernel plus initramfs), then importing healthy ZFS pools, choosing a boot environment based on the bootfs property or user selection, and finally launching the selected kernel with kexec. This applies to any Linux distribution installed on ZFS; the only requirement is that ZFSBootMenu itself can be started by EFI, a boot manager like rEFInd, or a BIOS bootloader like syslinux.

The boot sequence

The documentation describes the process in these stages:

  1. Start the ZFSBootMenu image. Boot it directly via EFI (as a self-contained UEFI application), through an EFI boot manager such as rEFInd, through a BIOS bootloader such as syslinux, or as a dedicated Linux kernel and initramfs.
  2. Import ZFS pools. ZFSBootMenu finds all healthy ZFS pools and imports them. Optionally, it can be told to find and import only one specific pool.
  3. Select a preferred boot environment. If the ZFSBootMenu command line names a pool preference and that pool was imported, the filesystem marked by its bootfs property is preferred. If no pool preference is given, or the preferred pool is not found, the bootfs filesystem on the first-found pool is preferred.
  4. Count down or fall back to manual choice. If a suitable bootfs is identified, an interruptable countdown (10 seconds by default) starts to boot that environment automatically. If no bootfs can be identified, or the countdown is interrupted, ZFSBootMenu presents its menu for manual selection.
  5. Launch the kernel. Once a suitable kernel and initramfs are identified — automatically or by direct user selection — ZFSBootMenu starts that kernel using the kexec command.

What "boot environment" means here

A boot environment can represent different versions of a Linux distribution, earlier snapshots of a common root, or entirely different distributions. Because ZFSBootMenu discovers kernels and initramfs images inside ZFS filesystems rather than relying on a fixed configuration file, the set of bootable environments follows what actually exists in the pools it imports.

What you can do from the pre-boot environment

Beyond selecting an environment, ZFSBootMenu allows manipulation of snapshots before boot. For advanced users, it can even bootstrap a system installation via zfs recv. These capabilities are part of the same small Linux system that performs discovery and booting.

Practical implications

  • Pool preference matters. Naming a pool on the command line changes which bootfs is honored; without it, the first-found pool's bootfs wins.
  • The countdown is interruptable. The default 10-second window is the point at which automatic boot can be stopped to reach the menu.
  • No bootfs, no autoboot. If no bootfs value can be identified, expect the menu rather than an automatic boot.

For deployment details, the documentation lists local installation, building in a container, command-line arguments, run-time configuration, signature verification, and prebuilt EFI executables (x86_64 EFI image and x86_64 recovery image) as the places to continue.