docs.zfsbootmenu.org

A ZFS boot environment (BE) is a bootable ZFS filesystem or snapshot that ZFSBootMenu presents as a menu entry at boot time. In ZFSBootMenu, boot environments can represent different versions of a Linux distribution, earlier snapshots of a common root, or entirely different distributions. ZFSBootMenu discovers these environments across imported pools, lets you pick one (or manipulate its snapshots) before booting, and then launches the selected kernel and initramfs with kexec.

How ZFSBootMenu Treats Boot Environments

ZFSBootMenu is a small, self-contained Linux system that knows how to find other Linux kernels and initramfs images inside ZFS filesystems. It does not chainload a fixed boot sector; instead it searches ZFS datasets for bootable content and builds a menu from what it finds.

The documented boot flow is:

1. Boot a ZFSBootMenu image via direct EFI booting, an EFI boot manager such as rEFInd, a BIOS bootloader such as syslinux, or another method. The image can be a self-contained UEFI application or a dedicated Linux kernel and initramfs.
2. Find all healthy ZFS pools and import them — or, at the user's option, find and import only a specific pool.
3. 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 indicated by its bootfs property (if defined).
   • If no pool preference is specified or the preferred pool is not found, prefer the filesystem indicated by the bootfs property (if defined) on the first-found pool.
4. If a suitable bootfs is identified, start an interruptable countdown (10 seconds by default) to automatically boot that environment.
5. If no bootfs value can be identified or the countdown is interrupted, search for boot environments and present them for selection.

The key mechanism is the bootfs pool property: it names the default boot environment for a pool, which is what the automatic countdown uses. Everything else in the menu comes from discovery of kernels and initramfs images within ZFS filesystems.

What Counts as a Boot Environment

Because a BE is just a ZFS filesystem or snapshot containing a kernel and initramfs, the same pool can hold several kinds of entries:

This is why the documentation describes choosing among "multiple boot environments" as the core function: the menu is not limited to one installed OS.

Why This Matters in Practice

• Rollback without a rescue disk. If an upgrade breaks the system, an earlier root snapshot is already a menu entry; you select it at boot rather than repairing from external media.
• Side-by-side testing. A second distribution or a pre-upgrade snapshot can coexist with the primary root, and the bootfs property decides which one boots by default.
• Pre-boot manipulation. ZFSBootMenu allows snapshots to be manipulated in the pre-boot environment, so you can adjust environments before launching a kernel.
• Bootstrap via zfs recv. For the adventurous user, ZFSBootMenu can even bootstrap a system installation by receiving a dataset with zfs recv.

For example, a user who runs a rolling-release distribution might keep a snapshot from before each major upgrade. After a bad upgrade, they interrupt the 10-second countdown, pick the pre-upgrade snapshot from the menu, and boot into the previous state — no separate recovery environment required.

Where to Go Next

The documentation at docs.zfsbootmenu.org covers the surrounding pieces: distribution-agnostic design, local installation and building in a container, command-line arguments, run-time configuration, signature verification, and prebuilt EFI executables (an x86_64 EFI image and an x86_64 recovery image). If your question is specifically about boot environments, the bootfs property and the snapshot-selection behavior described above are the parts to focus on.

ZFSBootMenu is a bootloader for Linux on ZFS: a small, self-contained Linux system that finds kernels and initramfs images inside ZFS filesystems, lets you pick or manipulate boot environments before booting, and then starts the chosen kernel with kexec. The site docs.zfsbootmenu.org hosts the official documentation for version 3.1.0, covering installation, configuration, command-line arguments, and prebuilt EFI executables. It is relevant if you run Linux on ZFS and want snapshot-based boot environments or pre-boot recovery; it is not needed for non-ZFS systems.

What the bootloader actually does

The documentation describes the boot flow in concrete steps:

1. A ZFSBootMenu image is started — either as a self-contained UEFI application or as a dedicated Linux kernel and initramfs — via direct EFI boot, an EFI boot manager such as rEFInd, a BIOS bootloader such as syslinux, or another method.
2. ZFSBootMenu finds all healthy ZFS pools and imports them, or imports only a specific pool if the user chooses.
3. It selects a preferred boot environment: if the command line names a pool and that pool is imported, the filesystem marked by its bootfs property is preferred; if no pool is named or the preferred pool is missing, the bootfs filesystem on the first-found pool is used.
4. If a suitable bootfs is identified, an interruptable countdown (10 seconds by default) starts an automatic boot. If no bootfs is found or the countdown is interrupted, a selection interface follows.

The key mechanism is that ZFSBootMenu does not chainload a fixed boot sector — it reads ZFS directly, so any kernel and initramfs visible in the pool can be a boot target.

Boot environments: the reason to use it

ZFSBootMenu is built around "boot environments," which the documentation describes as potentially different versions of a Linux distribution, earlier snapshots of a common root, or entirely different distributions. Because these are ZFS datasets and snapshots, you can:

• choose among them at boot time;
• manipulate snapshots in the pre-boot environment;
• bootstrap a system installation via zfs recv, which the docs present as an option for adventurous users.

For example, if an upgrade breaks your root, you can boot an earlier snapshot of the same root from the menu instead of reaching for external rescue media.

What the documentation site contains

The 3.1.0 docs are organized around these topics:

The site also links to the project's GitHub repository. The documentation is available in .rst and .pdf forms.

How to decide whether to read further

• Read the installation and EFI sections if you want to boot Linux from ZFS and need a bootloader that understands snapshots and multiple roots.
• Read the command-line and run-time configuration sections if you already use ZFSBootMenu and want to control which pool or bootfs is preferred, or adjust the automatic-boot countdown behavior.
• Skip it if your system does not use ZFS, since the entire tool depends on OpenZFS features.

The documentation does not state pricing or login requirements for the software or the site; treat availability and access terms as things to confirm on the site itself rather than assumptions.

Yes. ZFSBootMenu is described in its documentation as distribution-agnostic: it is a small, self-contained Linux system that locates other Linux kernels and initramfs images inside ZFS filesystems and boots a chosen one with kexec. Because it does not depend on a particular distribution's boot chain, it can present boot environments from different distributions, different versions of one distribution, or earlier snapshots of a common root. Deployment is equally flexible: you can install it locally, build it in a container, or use prebuilt EFI executables after signature verification.

What “distribution-agnostic” means in practice

ZFSBootMenu does not boot a fixed root filesystem. At startup it imports healthy ZFS pools, identifies candidate boot environments, and either automatically boots a preferred environment or lets you choose one from a menu. The documentation lists these possible boot environments:

• different versions of a Linux distribution;
• earlier snapshots of a common root;
• entirely different distributions.

It also allows snapshot manipulation in the pre-boot environment, and, for advanced users, bootstrapping a system installation via zfs recv. The practical requirement is that the kernels and initramfs images you want to boot live in ZFS filesystems that ZFSBootMenu can find and import — not that they come from one specific distribution.

How the boot process works

The documented flow is:

1. Boot a ZFSBootMenu image — as a self-contained UEFI application, or as a dedicated Linux kernel and initramfs — via direct EFI booting, an EFI boot manager such as rEFInd, a BIOS bootloader such as syslinux, or another method.
2. ZFSBootMenu finds all healthy ZFS pools and imports them, or imports only a specific pool if configured.
3. It selects a preferred boot environment:
   • If the command line specifies a pool preference and that pool is imported, the filesystem indicated by its bootfs property is preferred, if defined.
   • If no pool preference is given, or the preferred pool is not found, the bootfs property on the first-found pool is preferred, if defined.
4. If a suitable bootfs is identified, an interruptable countdown (10 seconds by default) starts to boot that environment automatically.
5. If no bootfs can be identified or the countdown is interrupted, a search begins (the documentation excerpt ends at this point).

Deployment options

The documentation groups deployment under “Easily Deployed and Extensively Configurable” and names these paths:

For prebuilt binaries, the documentation pairs the download with signature verification, so verify the signature before booting an image. Run-time behavior is configurable through command-line arguments and run-time configuration, which is where pool preference and similar settings are expressed.

Choosing an approach

• Use prebuilt EFI executables if you want the self-contained UEFI application path and are prepared to verify signatures first.
• Install locally if you want ZFSBootMenu integrated into an existing system's boot setup.
• Build in a container if you want to produce the image yourself in a controlled build environment.

All three lead to the same runtime behavior: pool import, boot-environment selection, and kexec into the chosen kernel. The documentation does not state pricing or login requirements for these resources, so check the site directly for access conditions.

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.

ZFSBootMenu can be configured at run time through command-line arguments passed to the ZFSBootMenu image when it is booted. The documentation lists "Command-Line Arguments" as a distinct configuration topic alongside local installation, container builds, and boot environments. These arguments control boot behavior — for example, specifying a pool preference or adjusting the automatic boot countdown — rather than changing the installed image itself.

What Run-Time Configuration Controls

According to the overview, the boot process works like this:

1. A ZFSBootMenu image is booted via direct EFI booting, an EFI boot manager such as rEFInd, a BIOS bootloader such as syslinux, or another method. The image can be a self-contained UEFI application or a dedicated Linux kernel and initramfs.
2. ZFSBootMenu finds all healthy ZFS pools and imports them — or, at the user's option, finds and imports only a specific pool.
3. It selects a preferred boot environment:
   • If the command line specifies a pool preference and that pool has been imported, the filesystem indicated by its bootfs property is preferred (if defined).
   • If no pool preference is specified, or the preferred pool is not found, the bootfs property on the first-found pool is preferred (if defined).
4. If a suitable bootfs is identified, an interruptable countdown starts (10 seconds by default) to automatically boot that environment.
5. If no bootfs value is identified or the countdown is interrupted, ZFSBootMenu continues to its selection interface (the excerpt ends here).

So the documented run-time knobs affect which pool is considered, which boot environment is preferred, and whether an automatic boot happens.

How to Apply Arguments

The documentation does not, in the provided material, spell out the exact syntax for passing arguments. What it does establish is that arguments are supplied on the ZFSBootMenu command line at boot time. In practice, that means adding them wherever your boot path lets you pass kernel or bootloader parameters — for example, in a bootloader entry or an EFI boot configuration. Consult the "Command-Line Arguments" page on docs.zfsbootmenu.org for the exact option names and format before relying on any specific flag.

Verifying the Result

After adding an argument, reboot into ZFSBootMenu and observe:

• Pool preference: only the intended pool should be imported when a preference is set and that pool exists.
• Boot environment: the environment tied to the preferred pool's bootfs should be preselected.
• Countdown: the automatic boot timer should appear and be interruptable; interrupting it should drop you into the selection interface.

If the preferred pool is missing, the documented fallback is the bootfs of the first-found pool — a useful behavior to test deliberately.

Common Pitfalls

• Assuming arguments persist. Run-time arguments apply to that boot only; they are not a substitute for image-level configuration.
• Expecting a preference to force a pool. The preference only applies if the pool is actually imported and found.
• Missing the countdown window. The default 10-second timer is interruptable, but you must act within it to reach manual selection.
• Guessing flag syntax. The overview confirms the mechanism but not the exact flags; use the dedicated Command-Line Arguments documentation page.

For the full option list and syntax, the authoritative source is the Command-Line Arguments section of the ZFSBootMenu 3.1.0 documentation at docs.zfsbootmenu.org.