Define BE selection variables in teardown hook environment

To allow completely custom overrides of the final boot process, teardown
hooks are called with three variables in their environment:

- ZBM_SELECTED_BE: filesystem holding the selected boot environment
- ZBM_SELECTED_KERNEL: path to the kernel within the selected BE
- ZBM_SELECTED_INITRAMFS: path to the corresponding initramfs

This is motivated by a desire to allow Xen users to inject a load/kexec
into the following stage, effectively making ZBM responsible for
selecting dom0 without making ZBM understand Xen at all.

Closes #231.

Author: ahesford

90zfsbootmenu/zfsbootmenu-lib.sh

@@ -782,8 +782,10 @@ kexec_kernel() {
   # Run teardown hooks, if they exist
   if [ -d /libexec/teardown.d ]; then
     for tdhook in /libexec/teardown.d/*; do
+      [ -x "${tdhook}" ] || continue
       zinfo "Processing hook: ${tdhook}"
-      [ -x "${tdhook}" ] && "${tdhook}"
+      env "ZBM_SELECTED_INITRAMFS=${initramfs}" \
+        "ZBM_SELECTED_KERNEL=${kernel}" "ZBM_SELECTED_BE=${fs}" "${tdhook}"
     done
     unset tdhook
   fi

man/zfsbootmenu.7

@@ -133,7 +133,7 @@
 .\" ========================================================================
 .\"
 .IX Title "zfsbootmenu 7"
-.TH zfsbootmenu 7 "2021-10-31" "1.11.0" "ZFSBootMenu"
+.TH zfsbootmenu 7 "2021-11-19" "1.11.0" "ZFSBootMenu"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -299,7 +299,30 @@ Any installed hooks are run right before the ZFSBootMenu menu will be presented;
 .IX Item "zfsbootmenu_teardown=<executable-list>"
 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 \fB<executable\-list>\fR that exists and is executable will be installed.
 .Sp
-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 \fBkexec\fR is invoked to jump into the selected kernel. This script can be used, for example, to unbind drivers from hardware or remove kernel modules.
+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 \fBkexec\fR is invoked to jump into the selected kernel. This script can be used, for example, to unbind drivers from hardware or remove kernel modules.
+.Sp
+Teardown hooks have access to three environment variables that describe the boot environment that is about to be launched:
+.RS 4
+.IP "\fB\s-1ZBM_SELECTED_BE\s0\fR" 4
+.IX Item "ZBM_SELECTED_BE"
+The \s-1ZFS\s0 filesystem containing the boot environment that is about to be launched.
+.IP "\fB\s-1ZBM_SELECTED_KERNEL\s0\fR" 4
+.IX Item "ZBM_SELECTED_KERNEL"
+The path to the kernel that will be booted, relative to the root of \fB\s-1ZBM_SELECTED_BE\s0\fR.
+.IP "\fB\s-1ZBM_SELECTED_INITRAMFS\s0\fR" 4
+.IX Item "ZBM_SELECTED_INITRAMFS"
+The path to the initramfs corresponding to the selected kernel, again relative to the root of \fB\s-1ZBM_SELECTED_BE\s0\fR.
+.RE
+.RS 4
+.Sp
+The hook \fImust not\fR assume that the filesystem \fB\s-1ZBM_SELECTED_BE\s0\fR is currently mounted or that the pool on which it resides is currently imported. However, a teardown hook has the freedom to import a pool (preferably read-only) and mount the boot environment to inject additional processing before boot. To abort a pending boot, invoking
+.Sp
+.Vb 1
+\&  kexec \-\-unload
+.Ve
+.Sp
+should be sufficient to return to the main menu. Likewise, the hook may construct and execute its own \fIkexec\fR command to alter boot-time parameters. This may be useful, for example, to allow ZFSBootMenu to select a boot environment and then restructure the boot process to launch a Xen kernel with the selected environment configured as dom0.
+.RE
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 \&\fBgenerate-zbm\fR(5) \fBgenerate-zbm\fR(8) \fBdracut.conf\fR(5)

pod/zfsbootmenu.7.pod

@@ -204,7 +204,31 @@ Any installed hooks are run right before the ZFSBootMenu menu will be presented;
 
 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 B<E<lt>executable-listE<gt>> 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 B<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.
+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 B<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.
+
+Teardown hooks have access to three environment variables that describe the boot environment that is about to be launched:
+
+=over 4
+
+=item B<ZBM_SELECTED_BE>
+
+The ZFS filesystem containing the boot environment that is about to be launched.
+
+=item B<ZBM_SELECTED_KERNEL>
+
+The path to the kernel that will be booted, relative to the root of B<ZBM_SELECTED_BE>.
+
+=item B<ZBM_SELECTED_INITRAMFS>
+
+The path to the initramfs corresponding to the selected kernel, again relative to the root of B<ZBM_SELECTED_BE>.
+
+=back
+
+The hook I<must not> assume that the filesystem B<ZBM_SELECTED_BE> is currently mounted or that the pool on which it resides is currently imported. However, a teardown hook has the freedom to import a pool (preferably read-only) and mount the boot environment to inject additional processing before boot. To abort a pending boot, invoking
+
+  kexec --unload
+
+should be sufficient to return to the main menu. Likewise, the hook may construct and execute its own I<kexec> command to alter boot-time parameters. This may be useful, for example, to allow ZFSBootMenu to select a boot environment and then restructure the boot process to launch a Xen kernel with the selected environment configured as dom0.
 
 =back