History

classabbyamp a16297f9b3 remove remaining pod docs, references to them, and releng scripts		2022-12-22 20:58:28 -05:00
..
README.md	remove remaining pod docs, references to them, and releng scripts	2022-12-22 20:58:28 -05:00
console-init.sh	Write data to console to recalculate size	2022-02-19 10:19:40 -06:00
esp-sync.sh	Add minimal documentation to ESP sync hook	2022-03-11 08:53:50 -06:00
keycache.sh	Note that the keycache setup hook is obsolete	2021-06-21 10:26:04 -04:00
luks-unlock.sh	Make the emergency shell slightly fancy	2022-03-04 22:06:21 -06:00
remote-ssh-build.sh	contrib/remote-ssh-build.sh: fix for new zbm-builder.sh design	2022-11-29 16:47:06 -05:00
snapshot-teardown.sh	Add a contrib script to snapshot the BE prior to boot	2022-06-28 10:46:00 -05:00
syslinux-update.sh	generate-zbm: deprecate syslinux support	2022-11-02 12:41:46 -04:00
xhci-teardown.sh	Fix the SC2295 class of warnings	2021-11-07 10:45:04 -06:00

README.md

User-Contributed Scripts for ZFSBootMenu

The contrib directory contains an assorted collection of helper scripts that augment core functionality. These scripts are reviewed and approved by members of the core team, but not all are thoroughly tested. Some have not been tested at all. User-contributed scripts are intended as starting points for customized setup hooks that can be deployed within the ZFSBootMenu environment or for generate-zbm hooks that alter the process of creating ZFSBootMenu images.

Script Directory

Brief descriptions of contributed scripts appear below for convenience. Please review the scripts themselves for more thorough descriptions of their use.

console-init.sh - In some configurations, the dracut event loop that configures the ZFSBootMenu environment will fail to initialize the console with desired font and keymap settings. This script can be added as an "early setup" hook to force console initialization.
esp-sync.sh - This script can run as a "post-image" hook to generate-zbm to synchronize the contents of one EFI system partition with others, providing tolerance against disk failures.
keycache.sh - This early-setup hook provided a simple means for run-time caching of ZFS encryption keys. Although the script has been retained for historical reference, use of the org.zfsbootmenu:keysource property is now the preferred method to control caching of filesystem credentials.
luks-unlock.sh - This is a proof of concept for storing ZFS native-encryption keys on a LUKS-encrypted volume. When installed as an early-setup hook, this facilitates, e.g., multiple-slot keys for ZFS pools that use native encryption.
remote-ssh-build.sh - This is a standalone script intended to wrap the zbm-builder.sh image-builder script, incorporating a dropbear SSH server, host keys and an authorized_keys file that permit remote access and pool unlocking within a ZFSBootMenu image.
snapshot-teardown.sh - This "teardown" hook will capture a pre-boot snapshot of the boot environment that has been selected for booting.
syslinux-update.sh - This script can run as a post-image hook for generate-zbm to construct a configuration file for syslinux. This provides an extension to basic functionality that was originally built into generate-zbm itself.
xhci-teardown.sh - ZFSBootMenu relies on kexec to launch kernels within boot environments. Some hardware, including certain XHCI USB controllers, cannot be properly re-initialized after kexec jumps into the new kernel. This teardown hook unbinds all detected XHCI controllers from the ZFSBootMenu kernel before jumping into the new kernel, allowing devices to be properly initialized.