Overview — ZFSBootMenu 3.1.0 documentation

Skip to main content

Back to top

Ctrl+K

Search<br>Ctrl+K

.rst

.pdf

Overview

Contents

x86_64 EFI Image<br>x86_64 Recovery Image<br>View on GitHub

ZFSBootMenu is a bootloader that provides a powerful and flexible discovery, manipulation and booting of Linux on ZFS.<br>Originally inspired by the FreeBSD bootloader, ZFSBootMenu leverages the features of modern OpenZFS to allow users to<br>choose among multiple "boot environments" (which may represent different versions of a Linux distribution, earlier<br>snapshots of a common root, or entirely different distributions), manipulate snapshots in a pre-boot environment and,<br>for the adventurous user, even bootstrap a system installation via zfs recv.

In essence, ZFSBootMenu is a small, self-contained Linux system that knows how to find other Linux kernels and initramfs<br>images within ZFS filesystems. When a suitable kernel and initramfs are identified (either through an automatic process<br>or direct user selection), ZFSBootMenu launches that kernel using the kexec command.

Overview#

In broad strokes, ZFSBootMenu works as follows:

Via direct EFI booting, an EFI boot manager like rEFInd, a BIOS bootloader like syslinux, or some other means,<br>boot a ZFSBootMenu image (as either a self-contained UEFI application or a dedicated Linux kernel and initramfs).

Find all healthy ZFS pools and import them (or, at the user's option, find and import only a specific pool).

If appropriate, select a preferred boot environment:

If the ZFSBootMenu command line specifies a pool preference, and that pool has been imported, prefer the filesystem<br>indicated by its bootfs property (if defined).

If the ZFSBootMenu command line specifies no pool preference or the preferred pool is not found, prefer the<br>filesystem indicated by the bootfs property (if defined) on the first-found pool.

If a suitable bootfs has been identified, start an interruptable countdown (by default, 10 seconds) to<br>automatically boot that environment.

If no bootfs value can be identified or the automatic countdown was interrupted, search all imported pools for<br>filesystems that set mountpoint=/ and contain Linux kernels and initramfs images in their /boot<br>subdirectories. Present a list of matching environments for user selection via fzf.

Mount the filesystem representing the selected boot environment and find either the highest versioned kernel or a<br>specifically selected kernel version in its /boot directory.

Using kexec, load the selected kernel and its initramfs image into memory, setting the kernel command line with<br>the contents of the org.zfsbootmenu:commandline property for that filesystem.

Unmount all ZFS filesystems.

Boot the final kernel and initramfs.

At this point, the system will be booting into your usual OS-managed kernel and initramfs, along with any arguments<br>needed to correctly boot your system.

Whenever ZFSBootMenu encounters natively encrypted ZFS filesystems that it intends to scan for boot environments, it<br>will prompt the user to enter a passphrase as necessary.

Distribution Agnostic#

ZFSBootMenu is capable of booting just about any Linux distribution. Distributions that are known to boot without<br>requiring any special configuration include:

Void

Chimera

Alpine

openSUSE (Leap, Tumbleweed)

Gentoo

Fedora

Debian and its descendants (Ubuntu, Linux Mint, Devuan, etc.)

Arch

Red Hat and its descendants (RHEL, CentOS, etc.) are expected to work as well but have never been tested.

ZFSBootMenu provides several configuration options that can be used to fine-tune the boot process for nonstandard<br>configurations.

Easily Deployed and Extensively Configurable#

Each release includes pre-generated boot images, based on Void Linux, that should work for the majority of users. These<br>images are available for x86_64 UEFI and legacy BIOS systems in the form of an EFI executable or a kernel and<br>initramfs. Users of other platforms or that require custom configurations can build local images, running the<br>ZFSBootMenu image generator either in a host installation or in the controlled environment of an OCI (Docker) container.

Modern UEFI platforms provide a wide range of options for launching ZFSBootmenu.<br>For legacy BIOS systems, syslinux is a convenient choice. A<br>syslinux guide for Void Linux describes the syslinux<br>installation and configuration process in the context of a broader Void Linux installation.

Local Installation#

The ZFSBootMenu repository includes a Makefile with targets to install the<br>generate-zbm builder, all necessary components, manual pages and some convenient helpers. A<br>local ZFSBootMenu installation requires some additional software that may be available as packages in your distribution<br>or may need to be manually installed. The following components are required or recommended for inclusion in the<br>bootloader image:

fzf

kexec-tools

mbuffer (recommended, but not required)

In addition, generate-zbm requires a few Perl modules:

perl...