How ZFSBootMenu Is Configured at Run Time

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.