Add documentation for generate-zbm, its config and initramfs options

Master documents reside in the `pod` subdirectory (except for
`generate-zbm.8`, which is inlined in `bin/generate-zbm` and may be
converted to man pages by running, from the repository root, the helper
`releng/pod2man.sh`. The `releng/tag-release.sh` helper will convert the
docs as part of the release process.

Co-authored-by: Zach Dykstra <[email protected]>
Co-authored-by: Andrew J. Hesford <[email protected]>
Co-authored-by: Érico Rolim <[email protected]>

Author: 3 people

README.md

@@ -6,7 +6,7 @@
 
 zfsbootmenu is implemented as a Dracut module to provide an experience similar to FreeBSD's bootloader, for Linux distributions. In broad strokes, it works as follows:
 
-* Via GRUB, direct EFI booting, etc, boot a Linux kernel along with an initramfs containing ZFS Boot Menu
+* Via GRUB, direct EFI booting, etc, boot a Linux kernel along with an initramfs containing ZFSBootMenu
 * Look for `zfsbootmenu` on the kernel command line
     * Optionally specify a default pool (if multiple are present)
 * Find all healthy pools and then import them
@@ -30,7 +30,7 @@ This tool makes uses of the following additional software:
  * [Linux Kernel](https://www.kernel.org)
  * [ZFS on Linux](https://zfsonlinux.org)
  * [dracut](https://github.com/dracutdevs/dracut)
- 
+
  ZFSBootMenu has been tested successfully with Kernel 5.7.13, Dracut 050 and ZFS On Linux 0.8.4.
 
 # System prereqs
@@ -53,7 +53,7 @@ NAME   PROPERTY  VALUE                       SOURCE
 zroot  bootfs    zroot/ROOT/void.2019.11.01  local
 ```
 
-On start, ZFS Boot Menu will find the highest versioned kernel in `zroot/ROOT/void.2019.11.01/boot`, confirm that a matching initramfs is present, and default to booting the OS with that.
+On start, ZFSBootMenu will find the highest versioned kernel in `zroot/ROOT/void.2019.11.01/boot`, confirm that a matching initramfs is present, and default to booting the OS with that.
 
 # Installation
 
@@ -69,7 +69,7 @@ Because ZFS properties are inherited by default, it is possible to set the `org.
 
 ## EFI
 
-ZFS Boot Menu integrates nicely with an EFI system. There will be two key things to configure here.
+ZFSBootMenu integrates nicely with an EFI system. There will be two key things to configure here.
 
 * The mountpoint of the EFI partition and it's contents
 * The mountpoint of the boot environment `/boot` and it's contents
@@ -90,7 +90,7 @@ vmlinuz-5.4.6_1
 ```
 
 
-Once `/boot` is backed by ZFS in a boot environment, you'll need to install the boot menu files. Typically, EFI partitions are mounted to `/boot/efi`, and contain a number of sub-directories. In this example, `/boot/efi/EFI/void` holds the ZFS Boot Menu kernel and initramfs.
+Once `/boot` is backed by ZFS in a boot environment, you'll need to install the boot menu files. Typically, EFI partitions are mounted to `/boot/efi`, and contain a number of sub-directories. In this example, `/boot/efi/EFI/void` holds the ZFSBootMenu kernel and initramfs.
 
 ```
 # lsblk -f /dev/sda
@@ -122,7 +122,7 @@ If you are using a pre-built kernel and initramfs downloaded from the releases p
 efibootmgr --disk /dev/sda \
   --part 1 \
   --create \
-  --label "ZFS Boot Menu" \
+  --label "ZFSBootMenu" \
   --loader /vmlinuz-0.7.5 \
   --unicode 'root=zfsbootmenu:POOL=zroot ro initrd=\EFI\void\initramfs-0.7.5.img quiet spl_hostid=a8c0a2a8' \
   --verbose
@@ -134,7 +134,7 @@ Each time the bootmenu is updated, a new EFI entry will need to be manually adde
 
 ### rEFInd
 
-`rEFInd` is considerably easier to install and manage. Refer to your distributions packages for installation. Once rEFInd has been installed, you can create `refind_linux.conf` in the directory holding the ZFS Boot Menu files (`/boot/efi/EFI/void` in our example):
+`rEFInd` is considerably easier to install and manage. Refer to your distributions packages for installation. Once rEFInd has been installed, you can create `refind_linux.conf` in the directory holding the ZFSBootMenu files (`/boot/efi/EFI/void` in our example):
 
 ```
 "Boot Default BE" "ro quiet loglevel=0 timeout=0 zfsbootmenu:POOL= spl_hostid="
@@ -144,32 +144,15 @@ Each time the bootmenu is updated, a new EFI entry will need to be manually adde
 
 As with the efibootmgr section, the `zfsbootmenu:POOL=` and `spl_hostid=` options need to be configured to match your environment.
 
-This file will configure `rEFInd` to create two entries for each kernel and initrams pair it finds. The first will directly boot into the environment set via the `bootfs` pool property. The second will force ZFS Boot Menu to display an environment / kernel / snapshot selection menu, allowing you to boot alternate environments, kernels and snapshots.
-
-# Command line options
+This file will configure `rEFInd` to create two entries for each kernel and initrams pair it finds. The first will directly boot into the environment set via the `bootfs` pool property. The second will force ZFSBootMenu to display an environment / kernel / snapshot selection menu, allowing you to boot alternate environments, kernels and snapshots.
 
-ZFS Boot Menu currently understands the following options:
+# Kernel command-line options
 
-* `spl_hostid=` used to set the system hostid if you are using a pre-built initramfs from the release page.
-* `force_import=0|1` set to `1` to attempt to force import all pools on the system. Use with caution!
-* `read_write=0|1` set to `1` to enable writes to pools when importing. Pools are imported read-only by default as a safety precaution.
-* `timeout=`
- * A value of `0` will result in the system immediately booting from the pool configured in the `bootfs` pool property
- * A value of `-1` will result in the system displaying a boot menu.
- * Any other positive value will show a countdown timer to boot the environment configured under `bootfs`, otherwise it will default to a boot menu.
-* `""|zfsbootmenu|zfsbootmenu:|zfsbootmenu:POOL=zroot` The first three values are functionally identical. The fourth can be used to prefer a pool if multiple are present in the system.
+The [zfsbootmenu(7)](pod/zfsbootmenu.7.pod#cli-parameters) manual page describes command-line options for ZFSBootMenu kernels in detail.
 
 # ZFS properties
 
-The following properties can be set at whatever level of the pool you'd prefer to control the boot behavior.
-
-* `org.zfsbootmenu:kernel` this can be a partial kernel name `(5.4)` or an explicit name `(vmlinuz-5.6.11_1)`.
-* `org.zfsbootmenu:commandline` set the list of kernel commandline options to be passed to the final OS. Do not set `root=`, this is set for you.
-* `org.zfsbootmenu:active` controls whether boot environments appear in or are hidden from ZFS Boot Menu:
-  - If a boot environment has the property `mountpoint=/`, set `org.zfsbootmenu:active=off` to *hide* the environment. For any other value, including not set, the boot environment will be shown.
-  - If a boot environment has the property `mountpoint=legacy`, set `org.zfsbootmenu:active=on` to *show* the environment. For any other value, including not set, the boot environment will be hidden. **Note**: Not all Linux distributions support booting from filesystems with `mountpoint=legacy`.
-* `org.zfsbootmenu:rootprefix` controls the prefix added to the ZFS filesystem provided as the root to kernels booted by ZFSBootMenu. For example, the command-line argument `root=zfs:zroot/ROOT/void` has the root prefix `root=zfs:`, which is the default value unless the boot environment appears to be Arch Linux; for Arch, the default root prefix is `zfs=`. Set `org.zfsbootmenu:rootprefix` on any boot environment or its parent to override this default. Remember to include the `root=` component if necessary and any delimiters like `:` or `=` that separate the prefix from the root filesystem.
-
+The [zfsbootmenu(7)](pod/zfsbootmenu.7.pod#zfs-properties) manual page describes ZFS properties interpreted by ZFSBootMenu.
 
 # initramfs creation
 
@@ -189,59 +172,11 @@ Your distribution should have packages for these already.
 
 ## config.yaml
 
-The YAML file `/etc/zfsbootmenu/config.yaml` is used to control the behavior of `generate-zbm`. An example YAML configuration file follows:
-
-```
-Global:
-  ManageImages: false
-  BootMountPoint: /boot/efi
-  DracutConfDir: /etc/zfsbootmenu/dracut.conf.d
-Components:
-  ImageDir: /boot/efi/EFI/void
-  Versions: false
-  Enabled: false
-  syslinux:
-    Config: /boot/syslinux/syslinux.cfg
-    Enabled: false
-EFI:
-  ImageDir: /boot/efi/EFI/void
-  Versions: 2
-  Enabled: false
-Kernel:
-  CommandLine: ro quiet loglevel=0
-```
-
-### Global
-* `ManageImages` Set this to 1 to allow `generate-zbm` to perform any actions (creation, removal of old files, etc)
-* `DracutConfDir` Set this to the location of the dracut configuration director for ZFS Boot Menu. This *CAN NOT* be the same location as the system `dracut.conf.d`, as the configuration files there directly conflict with the creation of the bootmenu initramfs.
-* `BootMountPoint` Generally, set this to the location of your ESP. `generate-zbm` will ensure that this is mounted when images are created and, if `generate-zbm` does the mounting, will unmount this filesystem on exit. If you wish to avoid the mount checks, remove this parameter.
-* `Version` A specific ZFS Boot Menu version string to use in producing images. In the string, the value `%{current}` will be replaced with the release version of ZFS Boot Menu. The default value is simply the current release version.
-
-### Kernel
-* `CommandLine` If you're making a unified EFI file or a syslinux configuration, this is the command line passed to the boot image. Refer to [Command line options](README.md#command-line-options).
-* `Path` The full path to a specific kernel to use when making the boot images. If not specified, `generate-zbm` will try to pick a reasonable kernel.
-* `Version` A specific kernel version to use. The value "%{current}" will be replaced with the output of `uname -r`; the braces can be omitted if `%current` ends on a word bounary. If not set, `generate-zbm` will try to parse the path of the selected kernel for a version.
-* `Prefix` The prefix to use for the names of ZFS Boot Menu images. By default, the prefix is extracted from the input kernel name.
-
-### Components
-* `ImageDir` This is the destination directory for the initramfs and kernel.
-* `Enabled` Set to `true` to enable creation of separate ZFS Boot Menu kernel and initramfs images. The default value is `false`.
-* `Versions` Set to `false` or `0` to disable image versioning; `generate-zbm` will not use its `Global.Version` parameter to name outputs, and will keep exactly one backup copy of every image it produces. Set to `true` (which behaves as `1`) or a positive integer to enable image versioning; `generate-zbm` will append the value of `Global.Version` to every image it produces, followed by a revision as `_$revision`. `generate-zbm` will save `Config.Versions` *revisions* of all images that match the current value of `Global.Versions`. In addition, `generate-zbm` will save the *highest* revision of the most recent `Config.Versions` other image versions found.
-
-### Components.syslinux
-* `Enabled` Set to `true` to enable syslinux configuration generation. The default value is `false`.
-* `Config` Set to the path of the syslinux configuration file to produce.
-
-### EFI
-* `ImageDir` This is the destination directory for the unified EFI file.
-* `Enabled` Set to `true` to enable creation of unified UEFI bundles. The default value is `false`.
-* `Versions` Behaves similarly to `Components.Versions`, but acts on files matching the UEFI bundle naming scheme.
-* `Stub` This is the path to the stub loader used to boot the unified EFI image. If not set, a default of `/usr/lib/gummiboot/linuxx64.efi.stub` is assumed.
-
+[config.yaml](pod/generate-zbm.5.pod) is used to control the operation of [generate-zbm](bin/generate-zbm). 
 
 ## Conversion of legacy configurations
 
-In prior versions of ZFS Boot Menu, an INI format was used for configuration. In general, migration to the new format is not automatic, but `generate-zbm` can perform the migration if your distribution package has not done it for you. To migrate an existing configuration, just run
+In prior versions of ZFSBootMenu, an INI format was used for configuration. In general, migration to the new format is not automatic, but `generate-zbm` can perform the migration if your distribution package has not done it for you. To migrate an existing configuration, just run
 
 ```
 generate-zbm --migrate [ini-config] [--config yaml-config]
@@ -257,7 +192,7 @@ Whenever `generate-zbm` attempts to migrate configuraton files, it will exit imm
 
 # Native encryption
 
-ZFS Boot Menu can import pools or filesystems with native encryption enabled. If your boot environments are not encrypted but say /home is, you will not receive a decryption prompt. To ensure that you can decrypt your pool to load the kernel and initramfs, you'll need to you have the filesystem parameters configured correctly.
+ZFSBootMenu can import pools or filesystems with native encryption enabled. If your boot environments are not encrypted but say /home is, you will not receive a decryption prompt. To ensure that you can decrypt your pool to load the kernel and initramfs, you'll need to you have the filesystem parameters configured correctly.
 
 ```
 zfs get all zroot | egrep '(encryption|keylocation|keyformat)'
@@ -274,4 +209,4 @@ For Dracut-based systems, this can be done by creating `/etc/dracut.conf.d/zol.c
 install_items+=" /etc/zfs/zroot.key "
 ```
 
-It's critical that you do not put this key file into the ZFS Boot Menu initramfs, since that file exists on an unencrypted volume - leaving your pool essentially wide-open.
+It's critical that you do not put this key file into the ZFSBootMenu initramfs, since that file exists on an unencrypted volume - leaving your pool essentially wide-open.

bin/generate-zbm

@@ -16,6 +16,8 @@ use File::Path qw(make_path remove_tree);
 use File::Glob qw(:globally :nocase);
 use Sort::Versions;
 
+use Pod::Usage qw(pod2usage);
+
 use Data::Dumper;
 $Data::Dumper::Indent   = 1;
 $Data::Dumper::Sortkeys = 1;
@@ -67,20 +69,7 @@ GetOptions(
   "migrate|m:s" => \$runConf{migrate},
   "config|c=s"  => \$runConf{config},
   "help|h"      => sub {
-    my $bin  = basename($0);
-    my $help = << "EOF";
-Usage: $bin [options]
-  -v|--version    Manually set the version
-  -k|--kernel     Manually set the path to the kernel
-  -K|--kver       Manually set the kernel version
-  -p|--prefix     Manually set the output kernel prefix
-  -b|--bootdir    Manually set the location to search for kernel files
-  -C|--confd      Manually set the Dracut configuration directory
-  -c|--config     Manually set the configuration file
-  -l|--cmdline    Manually set the kernel command line
-  -m|--migrate    Migrate legacy INI file to new YAML format
-EOF
-    print $help;
+    pod2usage( -verbose => 2 );
     exit;
   },
 );
@@ -266,7 +255,7 @@ unless ( nonempty $runConf{kernel_prefix} and nonempty $runConf{kernel_version}
   }
 }
 
-printf "Creating ZFS Boot Menu %s from kernel %s\n", $runConf{version}, $runConf{kernel};
+printf "Creating ZFSBootMenu %s from kernel %s\n", $runConf{version}, $runConf{kernel};
 
 # Create a unified kernel/initramfs/command line EFI file
 if ( enabled $config{EFI} ) {
@@ -399,7 +388,7 @@ EOF
     my $kernel = basename($entry);
     my ( undef, $version ) = split( '-', $kernel );
     my $label      = "ZFSBootMenu-$version";
-    my $menu_label = "ZFS Boot Menu $version";
+    my $menu_label = "ZFSBootMenu $version";
 
     if ($add_default) {
       print CFG "DEFAULT $label\n\n";
@@ -705,3 +694,68 @@ sub convertImageConfig {
   delete $section->{Versioned};
   delete $section->{Copies};
 }
+
+
+__END__
+
+=head1 NAME
+
+B<generate-zbm> - ZFSBootMenu initramfs generator
+
+=head1 SYNOPSIS
+
+B<generate-zbm> [options]
+
+=head1 OPTIONS
+
+Where noted, command-line options supersede options in the B<generate-zbm>(5) configuration file.
+
+=over 4
+
+=item B<--version|-v> I<zbm-version>
+
+Override the ZFSBootMenu version; supersedes I<Global.Version>
+
+=item B<--kernel|-k> I<kernel-path>
+
+Manually specify a specific kernel; supersedes I<Kernel.Path>
+
+=item B<--kver|-K> I<kernel-version>
+
+Manually specify a specific kernel version; supersedes I<Kernel.Version>
+
+=item B<--prefix|-p> I<image-prefix>
+
+Manually specify the output image prefix; supersedes I<Kernel.Prefix>
+
+=item B<--confd|-C> I<confd-path>
+
+Specify the dracut configuration directory; supersedes I<Global.DracutConfDir>
+
+=item B<--cmdline|-l> I<options>
+
+Override the kernel command line; supersedes I<Kernel.CommandLine>
+
+=item B<--bootdir|-b> I<boot-path>
+
+Specify the path to search for kernel files; default: I</boot>
+
+=item B<--config|-c> I<conf-file>
+
+Specify the path to a configuration file; default: I</etc/zfsbootmenu/config.yaml>
+
+=item B<--migrate|-m> [I<ini-config>]
+
+Migrate a legacy INI file to the new YAML format, writing the converted file to the path specified by B<--config>. If I<ini-config> is not specified, a default path is chosen by removing any I<.yaml> suffix in the B<--config> path and appending a I<.ini> suffix.
+
+=back
+
+=head1 SEE ALSO
+
+B<generate-zbm>(5) B<zfsbootmenu>(7)
+
+=head1 AUTHOR
+
+ZFSBootMenu Team L<https://github.com/zdykstra/zfsbootmenu>
+
+=cut