Annotate mkinitcpio.conf to explain ZBM specifics

Author: ahesford

etc/zfsbootmenu/mkinitcpio.conf

@@ -1,4 +1,9 @@
 # vim:set ft=sh
+
+# This is the mkinitcpio.conf file that ZFSBootMenu will read by default when
+# creating images. The syntax is the same as an ordinary mkinitcpio.conf file,
+# although the `zfsbootmenu` hook will recognize a few additional variables.
+
 # MODULES
 # The following modules are loaded before any boot hooks are
 # run.  Advanced users may wish to specify all system modules
@@ -26,30 +31,16 @@ FILES=()
 # help on a given hook.
 # 'base' is _required_ unless you know precisely what you are doing.
 # 'udev' is _required_ in order to automatically load modules
-# 'filesystems' is _required_ unless you specify your fs modules in MODULES
-# Examples:
-##   This setup specifies all modules in the MODULES setting above.
-##   No raid, lvm2, or encrypted root is needed.
-#    HOOKS=(base)
-#
-##   This setup will autodetect all modules for your system and should
-##   work as a sane default
-#    HOOKS=(base udev autodetect block filesystems)
-#
-##   This setup will generate a 'full' image which supports most systems.
-##   No autodetection is done.
-#    HOOKS=(base udev block filesystems)
+# 'block' is almost certainly _required_ to allow ZBM to find a pool
+# 'keyboard' is almost certainly _required_ to allow interaction with ZBM
 #
-##   This setup assembles a pata mdadm array with an encrypted root FS.
-##   Note: See 'mkinitcpio -H mdadm' for more information on raid devices.
-#    HOOKS=(base udev block mdadm encrypt filesystems)
+# 'zfsbootmenu' is _required_ for ZBM functionality.  However, this is added
+# implicitly by generate-zbm(8) and does not need to be specified here unless
+# you intend to run mkinitcpio directly. If you include it here and use
+# generate-zbm, the module will marked for inclusion twice, which is generally
+# harmless.
 #
-##   This setup loads an lvm2 volume group on a usb device.
-#    HOOKS=(base udev block lvm2 filesystems)
-#
-##   NOTE: If you have /usr on a separate partition, you MUST include the
-#    usr, fsck and shutdown hooks.
-HOOKS=(base udev autodetect modconf block filesystems keyboard zfsbootmenu )
+HOOKS=(base udev autodetect modconf block filesystems keyboard zfsbootmenu)
 
 # COMPRESSION
 # Use this to compress the initramfs image. By default, gzip compression
@@ -65,3 +56,44 @@ HOOKS=(base udev autodetect modconf block filesystems keyboard zfsbootmenu )
 # COMPRESSION_OPTIONS
 # Additional options for the compressor
 #COMPRESSION_OPTIONS=()
+
+# ZFSBOOTMENU OPTIONS
+# The options below may be specified to control ZFSBootMenu image creation.
+
+# zfsbootmenu_module_root
+# Set this option to override the default location to the core ZFSBootMenu
+# libraries and utilities that will be installed in the image.
+#zfsbootmenu_module_root="/usr/share/zfsbootmenu"
+
+# zfsbootmenu_miser
+# mkinitcpio uses busybox to provide core utilities. However, by default, the
+# 'zfsbootmenu' hook will install system versions of the utilities on which it
+# depends. Most likely, your system gets these utilities from util-linux rather
+# than busybox. Set zfsbootmenu_miser to "yes", "1" or "on" (without regard to
+# case) to allow the module to exclude utilities that are already provided by
+# busybox. This may shrink your ZFSBootMenu image slightly, but is not as well
+# tested and may break some (non-essential) ZFSBootMenu features.
+#zfsbootmenu_miser="no"
+
+# zfsbootmenu_early_setup, zfsbootmenu_setup, zfsbootmenu_teardown
+# ZFSBootMenu supports user-provided hooks that may be run at various points in
+# the boot process. Set each of these variables to an array of executable files
+# that should be installed as user hooks in the provided image. Files that are
+# not executable will be ignored. See the zfsbootmenu(7) manual page for more
+# details about these hooks.
+#
+# 'zfsbootmenu_early_setup' hooks are run after ZFS modules are loaded, but
+# before ZFSBootMenu attempts to import any pools. Hooks here, for example, can
+# unlock LUKS volumes or otherwise manage devices that must be made available
+# before a pool can be recognized.
+#
+# 'zfsbootmenu_setup' hooks are run after pools are imported and right before
+# the menu is presented.
+#
+# 'zfsbootmenu_teardown' hooks are run immediately before a chosen boot
+# environment is about to be launched. Any writable ZFS pools will have been
+# exported, but read-only pools will generally still be available.
+#
+#zfsbootmenu_early_setup=()
+#zfsbootmenu_setup=()
+#zfsbootmenu_teardown=()