ZFSBootMenu Build Containers
Official ZFSBootMenu release assets are built within OCI containers based on the
zbm-builder image. The image is built atop
Void Linux and provides a predictable environment without the need to install ZFSBootMenu or
its dependencies on the host system. While ZFSBootMenu is officially packaged for Void Linux and is guaranteed to work
well with the tools provided therein, the experience is not always as smooth for users of other distributions. System
packages for ZFSBootMenu or its requirements may be missing entirely. Tooling may be outdated and missing features that
ZFSBootMenu uses to provide an enhanced user experience. (Where possible, ZFSBootMenu will test for features and work
around their absence.) The
zbm-builder container image provides a means to work around the limitations of particular
distributions and provides all users with first-class ZFSBootMenu support.
zbm-builder.sh script provides a front-end for integrating custom ZFSBootMenu configurations into the build
container without the complexity of directly controlling the container runtime.
Users wishing to build custom ZFSBootMenu images should be familiar with the core concepts of ZFSBootMenu as outlined in
the project README. For those interested, the container README
provides more details on the operation of the ZFSBootMenu build container. However, the
build helper provides a front-end for integrating custom ZFSBootMenu configurations into the
build container and abstracts away many of the complex details discussed in that document.
If a custom build container is desired, buildah and
podman are generally required. A
Dockerfile is provided for convenience, but feature parity with the
script is not guaranteed. The container README provides more information about the
process of creating a custom build image.
buildah (if desired) using the package manager in your distribution:
xbps-install podman buildah
On Arch or its derivatives,
pacman -S podman buildah
On Debian or its derivatives,
apt-get install podman buildah
It is possible to configure
podman for rootless container deployment. Consult the
tutorial for details.
docker using the package manager in your distribution:
On Arch or its derivatives,
pacman -S docker
On Debian or its derivatives,
apt-get install docker
Non-root users that should be permitted to work with Docker images and containers should belong to the
groups. For example:
usermod -a -G docker zbmuser
zbmuser to the
docker group on systems that provide the
The Build Container and Its Helper
zbm-builder container is based on a Void Linux image that uses an LTS kernel and a relatively recent version of
ZFS. When run, the container entrypoint will:
Fetch a specified or default version of the ZFSBootMenu source repository (or use a local copy that is bind-mounted into the container);
Perform an "installation" of this repository into the container instance to ensure that ZFSBootMenu is usable within;
Optionally run some scripts to customize the container instance;
Merge default and build-specific ZFSBootMenu configurations; and
Produce a ZFSBootMenu image.
To facilitate interaction with the host, the container should be run with a build directory (along with an output directory, if it is not already a child of the build directory) bind-mounted into the container.
Advanced users may wish to build images from a local copy of the ZFSBootMenu source tree. To make this possible,
either fetch and unpack a source tarball or clone the git repository locally. The local repository should be
bind-mounted to the
/zbm directory within the container.
zbm-builder.sh helper script requires nothing more than functional installations of
bash and one of
docker. Simply download a copy of the script to a convenient directory. The helper coordinates volume
mounts necessary to read configurations from and write output to the host and ensures that the system's hostid file is
passed through. The script also supports a simple configuration file that allows options to be recorded for repeated
Building a ZFSBootMenu Image
To build a default image, invoke
zbm-builder.sh with no arguments. For example, from the directory that contains the
./zbm-builder.sh to produce a default kernel/initramfs pair in the
The default behavior of
Pull the default builder image,
./hostiddoes not exist, copy
/etc/hostid(if it exists) to
Spawn an ephemeral container from the builder image and run its build process:
Bind-mount the working directory into the container to expose local configurations to the builder
./config.yamlexists, inform the builder to use that custom configuration instead of the default
Run the internal build script to produce output in the
Custom ZFSBootMenu Hooks
ZFSBootMenu supports custom hooks in three stages:
early_setuphooks run after the
zfskernel driver has been loaded, but before ZFSBootMenu attempts to import any pools.
setuphooks run after pools are imported, right before ZFSBootMenu will either boot a default environment or present a menu.
teardownhooks run immediately before ZFSBootMenu will
kexecthe kernel for the selected environment.
zbm-builder.sh runs, it will identify custom hooks as executable files in the respective subdirectories of its
For each hook directory that contains at least one executable file,
zbm-builder.sh will write custom configuration
mkinitcpio that will include these files in the output images.
Fully Customizing Images
The entrypoint for the ZFSBootMenu implements a
tiered configuration approach
that allows default configurations to be augmented or replaced with local configurations in the build directory. A
config.yaml may be provided in the working directory to override the default ZFSBootMenu configuration;
configuration snippets for
mkinitcpio can be placed in the
subdirectories, respectively. For
mkinitcpio configurations, a complete
mkinitcpio.conf can be placed in the
working directory to override the standard configuration.
mkinitcpio configuration prepared by
zbm-builder.sh may include custom snippets installed in a
mkinitcpio.d subdirectory of the build directory. The
default mkinitcpio configuration includes a loop to source these snippets.
Should you prefer to overide the default
mkinitcpio.conf in your build, any files in the
subdirectory will need to be sourced within your custom configuration. In general, it is better to leave the default
mkinitcpio.conf and store all custom configurations in the
The build container runs its build script from the working directory on the host. In general, relative paths in custom
configuration files are generally acceptable and refer to locations relative to the build directory. If absolute paths
are preferred or required for some configurations, note that the build directory will be mounted as
/build in the
The internal build script always overrides the output paths for ZFSBootMenu components and UEFI executables to
ensure that the images will reside in a specified output directory (or, by default, a
build subdirectory of build
directory) upon completion. Relative paths are primarily useful for specifying local
More advanced users may wish to alter the build process itself. Some control over the build process is exposed through
command-line options that are described in the output of
Before adjusting these command-line options, seek a thorough understanding of the
image build process and the command sequence of