zfsbootmenu-core: run boot environment hooks after environment mount

Additions by @ahesford: expose ZBM_SELECTED_MOUNTPOINT, update docs

Closes: #486 [via git-merge-pr]

docs/man/dist/man7/zfsbootmenu.7

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "ZFSBOOTMENU" "7" "2023-09-12" "" "ZFSBootMenu"
+.TH "ZFSBOOTMENU" "7" "2023-09-16" "" "ZFSBootMenu"
 .SH NAME
 zfsbootmenu \- System Integration
 .SH SYNOPSIS
@@ -480,7 +480,7 @@ ZFSBootMenu will abandon its attempt to unlock the filesystem and indicate succe
 .INDENT 3.5
 Boot\-selection hooks will be installed from the directory \fI${zfsbootmenu_hook_root}/boot\-sel.d\fP\&. These hooks will be executed after a user has selected a boot environment, but before ZFSBootMenu attempts to load and boot the kernel.
 .sp
-Teardown hooks will be installed from the directory \fI${zfsbootmenu_hook_root}/teardown.d\fP\&. These hooks will be exectued after the kernel for a selected environment has been loaded and is launching via \fBkexec\fP is imminent. Some hardware initialized by the ZFSBootMenu kernel may not be properly reinitialized when a boot environment is launched; teardown hooks may be useful to unbind drivers from problematic hardware or remove associated kernel modules.
+Teardown hooks will be installed from the directory \fI${zfsbootmenu_hook_root}/teardown.d\fP\&. These hooks will be executed after the kernel for a selected environment has been loaded and is launching via \fBkexec\fP is imminent. Some hardware initialized by the ZFSBootMenu kernel may not be properly reinitialized when a boot environment is launched; teardown hooks may be useful to unbind drivers from problematic hardware or remove associated kernel modules.
 .sp
 Boot\-selection and teardown hooks each have access to three environment variables that describe the boot environment that is about to be launched:
 .sp
@@ -505,7 +505,16 @@ The path to the initramfs corresponding to the selected kernel, again relative t
 .UNINDENT
 .UNINDENT
 .sp
-No boot\-selection or teardown hook should assume that the filesystem named in \fBZBM_SELECTED_BE\fP is currently mounted. In addition, no teardown hook should assume that the ZFSBootMenu environment is in a consistent operating state. ZFSBootMenu may have exported some or all pools prior to executing teardown hooks.
+Additionally, boot\-selection hooks will have access to a fourth environment variable:
+.sp
+\fBZBM_SELECTED_MOUNTPOINT\fP
+.INDENT 0.0
+.INDENT 3.5
+The path where the selected boot environment is currently mounted, which is the root relative to which ZFSBootMenu will attempt to load the selected kernel and initramfs.
+.UNINDENT
+.UNINDENT
+.sp
+Teardown hooks should never assume that the filesystem named in \fBZBM_SELECTED_BE\fP is currently mounted. In addition, no teardown hook should assume that the ZFSBootMenu environment is in a consistent operating state. ZFSBootMenu may have exported some or all pools prior to executing teardown hooks.
 .sp
 In general, it is not possible to cleanly abort a boot attempt from boot\-selection or teardown hooks. However, a boot\-selection or teardown hook may take control of the boot attempt by implementing its own \fBkexec\fP load and execution without returning to ZFSBootMenu. 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.
 .UNINDENT

docs/man/zfsbootmenu.7.rst

@@ -296,7 +296,7 @@ Hooks should be marked executable and placed in a subdirectory of *${zfsbootmenu
 
   Boot-selection hooks will be installed from the directory *${zfsbootmenu_hook_root}/boot-sel.d*. These hooks will be executed after a user has selected a boot environment, but before ZFSBootMenu attempts to load and boot the kernel.
 
-  Teardown hooks will be installed from the directory *${zfsbootmenu_hook_root}/teardown.d*. These hooks will be exectued after the kernel for a selected environment has been loaded and is launching via **kexec** is imminent. Some hardware initialized by the ZFSBootMenu kernel may not be properly reinitialized when a boot environment is launched; teardown hooks may be useful to unbind drivers from problematic hardware or remove associated kernel modules.
+  Teardown hooks will be installed from the directory *${zfsbootmenu_hook_root}/teardown.d*. These hooks will be executed after the kernel for a selected environment has been loaded and is launching via **kexec** is imminent. Some hardware initialized by the ZFSBootMenu kernel may not be properly reinitialized when a boot environment is launched; teardown hooks may be useful to unbind drivers from problematic hardware or remove associated kernel modules.
 
   Boot-selection and teardown hooks each have access to three environment variables that describe the boot environment that is about to be launched:
 
@@ -312,7 +312,13 @@ Hooks should be marked executable and placed in a subdirectory of *${zfsbootmenu
 
     The path to the initramfs corresponding to the selected kernel, again relative to the root of **ZBM_SELECTED_BE**.
 
-  No boot-selection or teardown hook should assume that the filesystem named in **ZBM_SELECTED_BE** is currently mounted. In addition, no teardown hook should assume that the ZFSBootMenu environment is in a consistent operating state. ZFSBootMenu may have exported some or all pools prior to executing teardown hooks.
+  Additionally, boot-selection hooks will have access to a fourth environment variable:
+
+  **ZBM_SELECTED_MOUNTPOINT**
+
+    The path where the selected boot environment is currently mounted, which is the root relative to which ZFSBootMenu will attempt to load the selected kernel and initramfs.
+
+  Teardown hooks should never assume that the filesystem named in **ZBM_SELECTED_BE** is currently mounted. In addition, no teardown hook should assume that the ZFSBootMenu environment is in a consistent operating state. ZFSBootMenu may have exported some or all pools prior to executing teardown hooks.
 
   In general, it is not possible to cleanly abort a boot attempt from boot-selection or teardown hooks. However, a boot-selection or teardown hook may take control of the boot attempt by implementing its own **kexec** load and execution without returning to ZFSBootMenu. 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.
 

zfsbootmenu/lib/zfsbootmenu-core.sh

@@ -290,6 +290,14 @@ kexec_kernel() {
 
   CLEAR_SCREEN=1 load_key "${fs}"
 
+  tput cnorm
+  tput clear
+
+  if ! mnt=$( mount_zfs "${fs}" ); then
+    emergency_shell "unable to mount $( colorize cyan "${fs}" )"
+    return 1
+  fi
+
   # Variables to tell user hooks what BE has been selected
   hook_envs=(
     ZBM_SELECTED_BE="${fs}"
@@ -298,15 +306,9 @@ kexec_kernel() {
   )
 
   # Run boot-environment hooks, if they exist
-  env "${hook_envs[@]}" /libexec/zfsbootmenu-run-hooks "boot-sel.d"
-
-  tput cnorm
-  tput clear
-
-  if ! mnt=$( mount_zfs "${fs}" ); then
-    emergency_shell "unable to mount $( colorize cyan "${fs}" )"
-    return 1
-  fi
+  env "${hook_envs[@]}" \
+    ZBM_SELECTED_MOUNTPOINT="${mnt}" \
+    /libexec/zfsbootmenu-run-hooks "boot-sel.d"
 
   cli_args="$( load_be_cmdline "${fs}" )"
   root_prefix="$( find_root_prefix "${fs}" "${mnt}" )"