zfsbootmenu - System integration
ZFSBootMenu behavior is controlled through ZFS filesystem properties and command-line options provided to the ZFSBootMenu kernel.
These options are set on the kernel command line when booting the initramfs or UEFI bundle. Default options were chosen to allow general systems to boot without setting any values.
-
By default, ZFSBootMenu will look for the bootfs property on the first pool it imports to select the default boot environment. If you have multiple pools, substitute the name of your preferred pool for <pool> in the argument root=zfsbootmenu:POOL=<pool>.
- spl_hostid=<hostid>
-
When creating an initramfs or UEFI bundle, the hostid from the system is copied into the target. If this image will be used on another system with a different hostid, it can be overridden with this option.
Replace <hostid> with an eight-digit hexadecimal number.
- zbm.force_import=1
-
Set this option to attempt to force pool imports. When set, this invokes zpool import -f in place of the regular zpool import command, which will attempt to import a pool that's potentially in use on another system. Use this option with caution!
Omit this option or explicitly specify zbm.force_import=0 to disable forced imports.
- force_import=1
-
Deprecated; use zbm.force_import.
- zbm.timeout
-
This option accepts numeric values that control whether and when the boot-environment menu should be displayed.
- zbm.timeout=0 | zbm.skip
-
When possible, bypass the menu and immediately boot a configured bootfs pool property.
- zbm.timeout=-1 | zbm.show
-
Rather than present a countdown timer for automatic selection, immediately display the boot-environment menu.
- zbm.timeout=<positive integer>
-
Display a countdown timer for the specified number of seconds before booting the configured bootfs boot environment.
- timeout
-
Deprecated; use zbm.timeout.
- zbm.tmux
-
Indicate that ZFSBootMenu should be run under tmux in the initramfs. With this enabled, debug-level logging for the ZFSBootMenu scripts can be easily viewed. The tooling must also be installed with an additional dracut configuration option listed below.
The following properties can be set at any level of the boot-environment hierarchy to control boot behavior.
-
An identifier used to select which kernel to boot among all kernels found in the /boot directory of the selected boot environment. This can be a partial kernel name (e.g., 5.4) or a full filename (e.g., vmlinuz-5.7.11_1).
If the identifier does not match any kernels, the latest kernel will be chosen as a fallback.
-
A list of command-line arguments passed to the kernel selected by ZFSBootMenu for final boot.
Do not set root=; ZFSBootMenu will set this option for for you.
-
This controls whether boot environments appear in or are hidden from ZFSBootMenu.
- off
-
For boot environments with mountpoint=/, set org.zfsbootmenu:active=off to HIDE the environment.
- on
-
For boot environments with mountpoint=legacy, set org.zfsbootmenu:active=on to SHOW the environment.
By default, ZFSBootMenu only shows boot environments with the property mountpoint=/.
-
This specifies the prefix added to the ZFS filesystem provided as the root filesystem on the kernel command line. For example, the command-line argument root=zfs:zroot/ROOT/void has root prefix root=zfs:.
The default prefix is root=zfs: on all systems except those that appear to be Arch Linux. For Arch, the default root prefix is zfs=.
Set this property to override the value determined from inspecting the boot environment.
-
If specified, this provides the name of the ZFS filesystem from which keys for a particular boot environment will be sourced.
Normally, when ZFSBootMenu attempts to load encryption keys for a boot environment, it will attempt to look for a key file at the path specified by the keylocation property on the encryptionroot for that boot environment. If that file does not exist, and keyformat=passphrase is set for the encryptionroot (or keylocation=prompt), ZFSBootMenu will prompt for a passphrase to unlock the boot environment. These passphrases entered are not cached by default.
When org.zfsbootmenu:keysource is a mountable ZFS filesystem, before prompting for a passphrase when keylocation is not set to prompt, ZFSBootMenu will attempt to mount <filesystem> (unlocking that, if necessary) and search for the key file at keylocation relative to <filesystem>. If such a file is found, it will be copied to the initramfs, and the copy in the initramfs will be used to decrypt the original boot environment. Any copied keys are retained until ZFSBootMenu boots an environment, so a single password prompt can be sufficient to unlock several pools with the same keysource or prevent prompts from reappearing when the pool must be exported and reimported (for example, to alter boot parameters from within ZFSBootMenu).
In addition to standard dracut configuration options, the ZFSBootMenu dracut module supports addtional options to customize boot behavior.
-
An optional variable specifying a space-separated list of paths to setup hooks that will be installed in the ZFSBootMenu initramfs. Any path in the list <executable-list> that exists and is executable will be installed.
Any installed hooks are run right before the ZFSBootMenu menu will be presented; ZFS pools will generally have been imported and the default boot environment will be available in the BOOTFS environment variable. Hooks will not be run if the countdown timer expires (or was set to zero) and the default boot environment is automatically selected. Note: The hooks may be run multiple times if the menu is invoked multiple times, e.g., by dropping to an emergency shell and then returning to the menu. If a script should only run once, the script is responsible for keeping track of this.
-
An optional variable specifying a space-separated list of paths to teardown hooks that will be installed in the ZFSBootMenu initramfs. Any path in the list <executable-list> that exists and is executable will be installed.
Some hardware initialized by the kernel used to boot ZFSBootMenu may not be properly reinitialized when a boot environment is launched. Any teardown hooks installed into the ZFSBootMenu initramfs, will be run immediately before kexec is invoked to jump into the selected kernel. This script can be used, for example, to unbind drivers from hardware or remove kernel modules.
-
An optional variable enabling the installation of tmux and a minimal tmux.conf in the initramfs.
-
An optional variable specifying the path to an alternate tmux configuration file. If this key is set but no file exists at the path <tmux.conf>, the default configuration file is instead used.
generate-zbm(5) generate-zbm(8) dracut.conf(5)
ZFSBootMenu Team https://github.com/zbm-dev/zfsbootmenu