ZFS Bootloader for root-on-ZFS systems with support for snapshots and native full disk encryption
This release is dedicated to the late Jürgen Buchmüller (@pullmoll), a major contributor to the Void Linux project. Although ZFSBootMenu strives to support as many Linux distributions as possible, Void Linux is the distribution of choice for the entire ZFSBootMenu team. We have benefited greatly from pullmoll's enduring commitment to Void Linux. He will be missed.
stty
to the list of required binariesgenerate-zbm
is executed with the --debug
flag, -q
is no longer passed in to DracutEFI.Stub
in config.yaml
,
and adding :
inst_rules
to install udev rules, instead of hard-coding a file pathroot=
prefix for Gentoo systemshostid
configuration assistanceA pair of new features have been developed to combat the delicate dance sometimes required to synchronize hostid
in the boot environment (BE), the initramfs for the BE, and the initramfs for ZFSBootMenu. Both of these are controlled by ZFSBootMenu kernel command line options.
Set zbm.import_policy=hostid
to allow run-time reconfiguration of the SPL hostid. If a pool is preferred via zbm.prefer
and the pool can not be imported with a preconfigured hostid, the system will attempt to adopt the hostid of the system that last imported the pool. If a preferred pool is not set and no pools can be imported using a preconfigured hostid, the system will adopt the hostid of the first otherwise-importable pool. After adopting a detected hostid, ZFSBootMenu will subsequently attempt to import as many pools as possible.
Setting zbm.set_hostid
will cause ZFSBootMenu to set the spl.spl_hostid
command-line parameter for the selected boot environment to the hostid used to import its pool. The SPL kernel module will use this value as the hostid of the booted environment regardless of the contents of /etc/hostid
. As a special case, if the hostid to be set is zero, ZFSBootMenu will instead set spl_hostid=00000000
, which should be used by dracut-based initramfs images to write an all-zero /etc/hostid in the initramfs prior to importing the boot pool.
The main boot environment screen and snapshot list screen can now be sorted by multiple criteria. By default, these listings are sorted by name. One of zbm.sort_key=name
, zbm.sort_key=creation
, or zbm.sort_key=used
can be set on the command line to change the default used. MOD+O
can be pressed at run time to change the sort order to the next in the list.
The internal zfsbootmenu-lib.sh
library is now sourced by default in the recovery shell. This makes a number of helper functions available for general use.
Since Dracut
can find command line options from multiple places, it can be difficult to determine which option was used to control bootloader behavior. The command zbmcmdline
will show the command line as seen by Dracut.
Instead of flowing the helper key text to the width of the screen, shortcut key text is now arranged in one or more columns. Low resolution screens or terminals with small dimensions will use a single column to show the text. As the terminal dimensions increase, text will be laid out in up to a maximum of three left-aligned columns.
ZFSBootMenu has an internal logging system backed by /dev/kmsg
and dmesg
. Logging is now enabled throughout the entire system, tracking both debug
level messages as well as warnings
and errors
. When a warning or error condition has occurred, a yellow [!]
or red [!]
notification will appear in the upper left of the screen. Pressing MOD+L
will access this logging system, allowing you to easily see these messages.
To aid in debugging issues, debug logging has been added in all of the internal library functions. These messages can be enabled by setting loglevel=7
on the ZFSBootMenu command line.
Binary releases in the form of a standalone EFI file and a kernel/initramfs pair for x86_64
will now be made available with each future tagged release. To allow for the most compatiblity with the myriad system configurations out there, a few features will be embedded in the builds:
zbm.import_policy=hostid
zbm.set_hostid
The EFI binary can be used as a recovery tool by naming it BOOTX86.EFI
and adding it to an EF00
partition on a USB drive. It can also be used as a drop-in bootloader for your system without needing to locally build a copy. See UEFI Booting for example efibootmgr
commands.
Some command line options have now been deprecated with the inclusion of zbm.import_policy
. See zfsbootmenu(7).
run.sh
and setup.sh
testing scripts to simplify usagestty
to required exectables in module-setup.sh (Andrew J. Hesford)--uefi-stub
when EFI.Stub is configured (Andrew J. Hesford)Happy New Year! ZFSBootMenu 1.8.1 provides a few minor enhancements and bug fixes.
/boot
contains some unversioned kernel files. (#128)Ctrl
and Ctrl-Alt
as hotkey modifiers in addition to Alt
to fix issues with some non-US keymaps. (#124)force_import
and timeout
kernel command-line options are now expected to be zbm.force_import
and zbm.timeout
; the old forms are deprecated but will continue to work for the forseeable future.zbm.show
and zbm.skip
command-line options force the menu to appear or be skipped if zbm.timeout
is not also set.ZFSBootMenu 1.8.0 offers a significant list of new features, fixes and general improvements.
generate-zbm
command now ensures that the target directory for boot images has sufficient space, rather than copying partial and generally broken files.loglevel
kernel-command-line argument.zfsbootmenu
program on the initramfs, allowing the menu to be accessed over SSH using something like the dracut-crypt-ssh module.zbm.tmux
command-line option and the zfsbootmenu_tmux
dracut option in the zfsbootmenu(7) manual page.zfsbootmenu_setup
and zfsbootmenu_teardown
dracut options in the zfsbootmenu(7) manual page.org.zfsbootmenu:keysource
property of a ZFS encryptionroot to a specific filesystem. When ZFSBootMenu attempts to load a key from a file://
location, it will first attempt to load the key at that location relative to the filesystem specified by org.zfsbootmenu:keysource
. If this succeeds, ZFSBootMenu will retain a copy of the key in the initramfs so that subsequent need for the key (for example, when re-importing a pool read-write to set default boot options or duplicate a snapshot) will not require re-entry of the passphrase. See descriptions of the org.zfsbootmenu:keysource
ZFS property in the zfsbootmenu(7) manual page.Alt+C
hot key provides the means to chroot into a selected boot environment. If the pool is mounted read-write, the chroot will be writable, allowing recovery operations directly from ZFSBootMenu.This is a minor bug-fix release.
/etc/hostid
in the ZFSBootMenu dracut module in anticipation of similar changes in the upcoming OpenZFS 2.0.0 release. This caused inconsistent behavior on systems using the musl C library with current versions of ZFS on Linux, resulting in potentially unbootable systems without forcing the spl_hostid
command-line parameter. Now, the ZFSBootMenu dracut module attempts to discover the installed version of ZFS and behave consistently.940cd4c - Fall back to legacy hostid creation for ZFS < 2.0 (Andrew J. Hesford) 6cc0076 - Fix key_wrapper calls with out CLEAR_SCREEN defined (Zach Dykstra) 65a1a33 - Loop the emergency shell when initial pool imports fail (Andrew J. Hesford)
In addition to a bug fixes, this release targets refinements that improve usability and offer contextual help within the menus.
console
kernel command-line option and should behave as expected over a serial console.hostid(1)
command to populate the default hostid in the ZFSBootMenu initramfs, the dracut module will prefer to copy the /etc/hostid
from the host, which should produce more consistent behavior on musl systems.alt-h
within any menu, provides descriptions of functionality provided by ZFSBootMenu.zbm.lines
and zbm.columns
allow the size of the terminal at boot time.generate-zbm
fails to parse the YAML configuration, more detailed messages pinpoint parsing errors.dbe91a1 - Fix console handling when attached to a serial line (Andrew J. Hesford) 9959d10 - Respect ZFS hostid behavior on musl (Andrew J. Hesford) f4a60e6 - Capture and print config.yaml eval failure (Zach Dykstra) 2ebad45 - Sort environments, fix preview (Zach Dykstra) cc6e27c - Control size/target of ZFSBootMenu output (Zach Dykstra) bb294b3 - Enable dynamic line wrapping for header (Zach Dykstra) 8993591 - Enable global help system (Zach Dykstra) 7879876 - Read-only helpers (Zach Dykstra)
Revert omitting rootfs-block
by default from the ZFSBootMenu initramfs. rootfs-block
is a hard requirement of crypt
, which is used to setup LUKS beneath ZFS.
This release brings significant improvements to the pool import process. Previously, all available pools were discovered and then their health was scraped to confirm that they were in an 'ONLINE' state before importing them. This process had a few subtle shortcomings that were highlighted by the pending release of OpenZFS 2.0.0. In particular, if a zpool has been upgraded via zpool upgrade
to enable OpenZFS 2.0.0 feature flags, but the ZFSBootMenu initramfs contains an older version of OpenZFS, the pool was not able to be automatically imported in ZFSBootMenu. The import process now relies on zpool import -N -a -o readonly=on
to attempt to import all available and otherwise healthy pools in read-only mode. By using zpool itself to determine all of the pools that can/should be imported, ZFSBootMenu now avoids the fragile process of scraping and interpreting the human-friendly text output of zpool import
.
resume
is on the command line, but the pool has been imported read-write. This function is now used when generating a preview, making the modification more transparent to user inspection.config.yaml
defaults were adjusted to more closely match normal use cases. This works in tandem with the --enable
toggle in generate-zbm
to provide a better out-of-the-box experience.resume=
and to subsequently append noresume
.skim
in place of fzf
for greater platform availability. fzf
is preferred when creating an initramfs.generate-zbm --enable
or generate-zbm --disable
ZFSBootMenu 1.4.1 is a minor update, updating the provided Makefile for packagers.
ZFSBootMenu 1.4 includes significant internal changes and some user-visible functional changes in the generate-zbm
script.
generate-zbm
to improve consistency and facilitate future development.generate-zbm
easier to understand.generate-zbm.5
, generate-zbm.8
and zfsbootmenu.7
) to document the creation and use of ZFSBootMenu images.--migrate
command-line option to convert existing INI configurations to the new format.--kernel
, --kver
and --prefix
to make generate-zbm
easier to incorporate on non-Void systems.--version
to allow customized output versioning of images.%current
or %{current}
tags in --kver
and --version
values.--cmdline
command-line option to override the configured CommandLine
value without editing the configuration file.0979051 - Add documentation for generate-zbm, its config and initramfs options (Zach Dykstra, et al.) ee1d9d8 - Unmask import_args in functions calling import_pool (Zach Dykstra) 3b2b2f0 - Add explicit --migrate option to generate-zbm (Andrew J. Hesford) 3cd3a8e - Improve error handling and automatic config conversion (Andrew J. Hesford) 80e0c30 - Switch syslinux entry to heredoc, fix syslinux.cfg file copy (Zach Dykstra) 6351226 - Move to YAML configuration, improve version handling (Andrew J. Hesford, Zach Dykstra) 5fdb872 - Add configuration options for kernel, version and prefix (Andrew J. Hesford) 79295ec - Add an optional parameter to safeCopy: (Zach Dykstra) 8aa133f - Clean up control flow in generate-zbm (Andrew J. Hesford)