Void Linux ZFS Root Installation Guide: ZFSBootMenu & Dracut Setup
Installing Void Linux on a root ZFS filesystem offers an exceptional combination of unmatched data integrity, robust snapshot management, and the blistering speed and simplicity of the independent runit init system. Because the standard Void Linux installer does not provide out-of-the-box support for ZFS, setting up a native ZFS root requires a manual installation using a specialized live environment, such as Leah Neukirchen's ZFS-enabled hrmpf ISO. By pairing Void Linux with ZFSBootMenu—a self-contained, dependency-free bootloader that boots directly from ZFS datasets using kexec—you can construct a highly resilient, modern operating system environment equipped with full encryption, dataset segregation, and seamless snapshot rollback capabilities.
In this article
Understanding the Void Linux ZFS Architecture
Combining the minimalist design of Void Linux with the robust enterprise features of the ZFS filesystem delivers an exceptionally resilient and high-performing operating environment.
Running Void Linux on a native root ZFS filesystem unlocks advanced data integrity protections, instant snapshot capabilities, efficient copy-on-write mechanics, and transparent compression. Unlike traditional filesystems, ZFS acts as both a volume manager and a filesystem, protecting against data corruption through automatic checksumming and self-healing algorithms. For users seeking a rolling-release distribution free of systemd, pairing Void Linux with ZFS offers ultimate control, transparency, and modern storage management features right down to the metal.
However, because the standard official Void Linux installer lacks out-of-the-box ZFS support, achieving a ZFS root installation requires a manual, highly methodical bootstrapping process. Users cannot rely on point-and-click installation wizards; instead, they must manually partition drives, construct the ZFS pool, configure hierarchical datasets, and compile custom initramfs images. This architectural requirement demands a solid understanding of both command-line Linux administration and the intricacies of OpenZFS.
To successfully navigate this complex installation path, administrators frequently rely on community-maintained resources and collaborative documentation. Many developers turn to Leah Neukirchen's ZFS-enabled hrmpf live ISO images to establish an initial environment where ZFS utilities are fully functional. Additionally, community repositories found via searches for void linux zfs github projects provide invaluable shell scripts, configuration templates, and automated helper tools. Real-world troubleshooting tips, edge-case solutions, and installation feedback shared across void linux zfs reddit discussions further assist users in overcoming hurdles related to bootloaders and Dracut configurations.
Recommend downloading and flashing the ZFS-enabled hrmpf live ISO to simplify the initial environment setup, as it contains all necessary ZFS kernel modules pre-loaded.
With a clear understanding of the architectural requirements and community resources at your disposal, you can proceed with confidence to prepare your storage pools and bootstrap the system.
Preparing the ZFS Pool and Datasets
Preparing the disk structure and configuring native ZFS datasets form the foundation of a robust Void Linux root installation.
Before configuring any datasets, you must correctly partition your target storage drive and spin up a healthy ZFS pool. Because standard Void Linux live images do not include out-of-the-box ZFS support, you should use a specialized environment like Leah Neukirchen's ZFS-enabled hrmpf ISO. Once booted into this live medium, identify your target drive and partition it to include a primary EFI System Partition (ESP) formatted as FAT32, alongside a secondary partition allocated entirely for your ZFS root pool. When creating the zpool, it is best practice to explicitly set the block size and feature flags to ensure compatibility and maximum performance. For instance, initializing the pool with an ashift of 12 optimizes block alignment for modern Advanced Format drives, while enabling features such as lz4 compression ensures efficient data throughput right out of the gate.
Crucially, ZFS requires a unique system identifier known as a hostid to prevent dataset corruption, especially if you plan to move drives between machines or manage multi-device pools. You must generate and write this hostid to your installation environment before writing any data to the pool. Following this system-level configuration, the next step involves mapping out a clean, hierarchical dataset layout. Rather than dumping everything into a single directory, a proper native ZFS installation utilizes isolated child datasets for the root system, home directories, and optional swap or temporary spaces. This architectural split allows for granular snapshotting, independent property inheritance, and straightforward maintenance as your Void Linux installation grows and evolves across multiple boot environments.
Creating the Root Pool and Generating a Hostid
Properly preparing your target storage device and generating a persistent system hostid are crucial first steps for a stable Void Linux ZFS root installation.
Before configuring any filesystems, you must partition your target drive to accommodate both the EFI System Partition (ESP) required for modern UEFI firmware and the primary ZFS pool partition. Using a tool like parted or gdisk, create a standard GPT partition table on your target disk. The first partition should be a dedicated EFI system partition, typically sized between 512 MiB and 1 GiB, formatted later as FAT32. The remaining free space on the disk should be allocated to a second partition intended for ZFS. It is essential to ensure this partition spans the rest of the drive while leaving a small safety margin at the end of the disk for optimal alignment and partition table breathing room.
Once the partitions are in place, you can initialize the ZFS pool using the ZFS partition you just created. It is standard practice to name the root pool zroot. When creating the pool, explicitly set the ashift parameter to 12. This tells ZFS to use 4KiB block sizes, which perfectly aligns with modern Advanced Format hard drives and Solid State Drives (SSDs), preventing severe performance degradation and write amplification issues. An example command to initialize an unencrypted root pool with proper ashift settings would be zpool create -f -o ashift=12 -O compression=on -O acltype=posixacl -O xattr=sa -O normalization=formD -O relatime=on zroot /dev/disk/by-id/your-partition-id. For encrypted installations, you would additionally specify encryption parameters and key locations during this creation phase.
After the pool has been successfully created and imported, you must generate a stable system hostid. ZFS relies on the hostid to prevent multiple systems from accidentally importing and corrupting the same pool, particularly in environments with shared storage or multi-boot configurations. Because live installation environments generate random temporary hostids on every boot, failing to set a permanent hostid will cause severe mount failures and kernel panics upon your first reboot into the new installation. Generate a stable, unique 32-bit hexadecimal hostid using the zgenhostid utility with a forced prefix. For example, executing zgenhostid -f 0x00bab10c writes the required binary identification directly to /etc/hostid. This file will later be copied into your chroot environment so that the installed Void Linux system consistently identifies as the legitimate owner of the zroot pool.
With the partition table structured, the pool initialized with optimal sector alignment, and a persistent hostid secured, you are ready to construct the hierarchical ZFS dataset layout.
Configuring Native ZFS Datasets
Establishing a robust and flexible ZFS dataset hierarchy is the cornerstone of any reliable root-on-ZFS installation on Void Linux.
When installing Void Linux with ZFS, the dataset layout must be meticulously planned to separate the operating system base from user data, transient runtime directories, and mutable configuration files. This separation enables powerful administrative features, including granular snapshotting, easy rollbacks of the root environment without affecting home directories, and simplified maintenance routines. By avoiding a monolithic structure and adhering to best practices recommended by ZFSBootMenu, you ensure that boot environments remain isolated and pristine.
To achieve this, the primary root pool must be partitioned into specific hierarchical datasets. The foundation begins with a parent container dataset for the operating system root, typically designated as zroot/ROOT, with its mountpoint disabled to prevent unwanted automatic mounting at the root level. Beneath this container, individual boot environments or distribution-specific datasets like zroot/ROOT/void are created, assigned a mountpoint of slash, and configured with canmount set to noauto. This explicit noauto setting is crucial because it prevents the kernel or standard mount utilities from attempting to mount the root dataset prematurely during early boot before ZFS modules and ZFSBootMenu have successfully initialized the pool.
| Dataset Name | Mountpoint | Canmount | Purpose |
|---|---|---|---|
| zroot/ROOT | none | on | Parent container for operating system boot environments |
| zroot/ROOT/void | / | noauto | Primary Void Linux root filesystem and boot environment |
| zroot/home | /home | on | Persistent storage location for user home directories |
In addition to the primary system and home datasets, administrators frequently create auxiliary datasets such as zroot/var/log or zroot/var/tmp to isolate high-write directories from the main root snapshot lifecycle. Setting appropriate compression algorithms, such as LZ4 or ZSTD, across all newly created datasets further optimizes storage efficiency and I/O performance prior to bootstrapping the base Void Linux system files.
With the underlying ZFS datasets fully defined and properly parameterized, the environment is primed for bootstrapping the Void Linux userland via XBPS.
With the foundational pool and hostid established, we can now dive deeper into creating and tailoring the specific root and home datasets to accommodate the upcoming XBPS bootstrap process.
Bootstrapping Void Linux via XBPS
With your ZFS storage layout fully initialized and properly mounted under the target directory, you can begin populating the filesystem with the core Void Linux userland using the native XBPS package manager.
The process of bootstrapping Void Linux onto your ZFS root filesystem involves leveraging the XBPS package manager from a running live environment to install the base system architecture. Because the standard Void installation media does not natively manage ZFS partitions during automated runs, this manual staging phase requires pointing the installer directly at your mounted target directory. By specifying the appropriate architecture and repository keys, you download and unpack the minimal operating system files, establishing the foundation of your new system without relying on traditional partition-based installers.
Before executing the package download, you must ensure that all repository keys are correctly copied into the target environment so that XBPS can cryptographically verify every downloaded package. Once the target is prepared, running the bootstrap command populates the zroot/ROOT/void dataset with essential utilities, the base system package, and the package manager itself. This establishes a fully functional Void Linux tree inside your ZFS datasets, preparing the environment for administrative chroot configuration, kernel installation, and service management.
Running the Base Installation
Before bootstrapping the Void Linux environment inside the newly created ZFS filesystems, several critical configuration files and keys must be copied to the target mount directory to ensure proper system recognition and integrity.
Once the ZFS datasets are mounted under the target directory (typically /mnt), you must transfer essential system files from the live environment to maintain continuity. Start by copying the generated hostid file using the command cp /etc/hostid /mnt/etc/hostid. This step is vital because ZFS uses the system hostid to prevent pool import conflicts, and an inconsistent hostid between the installer and the chroot environment can prevent the pool from mounting during early boot. If you configured native ZFS encryption with a keyfile, you must also copy your key—such as cp /etc/zfs/zroot.key /mnt/etc/zfs/zroot.key—ensuring that the target directory /mnt/etc/zfs exists beforehand. Additionally, copy the active zpool cachefile to /mnt/etc/zfs/zpool.cache so that the ZFS subsystem can automatically locate and import your pool on subsequent boots without manual intervention.
Security and package management continuity also require transferring XBPS repository keys. Copy the contents of the local keys directory into the target installation by executing cp -R /var/db/xbps/keys /mnt/var/db/xbps/. Without these cryptographic keys, the package manager will refuse to verify or install any software inside the chroot environment, rendering you unable to update or fetch necessary kernel and filesystem modules. With all prerequisite files securely copied into place, you are ready to bootstrap the core operating system using the XBPS package manager.
The base system installation is performed using the XBPS bootstrap utility, which downloads and extracts the foundational Void Linux packages directly onto your ZFS root dataset. Execute the bootstrap command by pointing it to the target mount point and specifying your preferred package mirror, for example: XBPS_ARCH=x86_64 xbps-install -S -r /mnt -R https://repo-default.voidlinux.org/current. This command instructs XBPS to initialize a root environment at /mnt, synchronize the remote repository index, and install the foundational meta-packages—including base-system, coreutils, and the package manager itself—onto your configured zroot/ROOT/void dataset. Ensure that your network connection is active during this step, as XBPS will stream all required base packages directly from the official repositories into your new ZFS root.
After the bootstrap process completes successfully, the core files of your Void Linux installation reside on the ZFS datasets, setting the stage for the chroot configuration phase.
Chrooting and Core System Configuration
Once the base system is bootstrapped onto your new ZFS filesystems, you must transition into the chroot environment to configure fundamental system parameters, establish root access, and initialize Void Linux services.
Begin by entering the newly installed system environment using the custom Void Linux utility, xchroot. Executing xchroot /mnt automatically binds essential virtual filesystems like /dev, /proc, and /sys into the target directory, ensuring that your configuration commands interact properly with the underlying kernel and hardware. Once inside the chroot, your terminal prompt changes, indicating that you are now operating directly within your new Void Linux installation.
The first priority inside the chroot is configuring your system locale and keyboard layout. Open /etc/default/libc-locales and uncomment your desired locale, such as en_US.UTF-8 UTF-8, then generate the locale files by running xbps-reconfigure -f glibc-locales. Next, configure your persistent keymap by editing /etc/rc.conf and setting the KEYMAP variable to match your keyboard configuration, ensuring proper input behavior during early boot and runtime.
Time synchronization and localization require setting up the correct local timezone. Create a symbolic link from your specific timezone file within /usr/share/zoneinfo to /etc/localtime. For example, linking /usr/share/zoneinfo/UTC or your regional zone ensures that system logs and cron jobs maintain accurate timestamps.
Securing the system requires assigning a secure password to the root user. Execute the passwd command and follow the prompts to define and confirm your root password. Additionally, verify that your hostname is properly defined in /etc/hostname and mapped to localhost within /etc/hosts.
Unlike systemd-based distributions, Void Linux utilizes the runit init system for service supervision. Services are managed through symlinks inside the /var/service directory pointing to available services located in /etc/sv. To enable core system services such as dhcpcd for networking, sshd for remote administration, or chronyd for network time synchronization, create symbolic links manually using the ln -s command. For instance, linking /etc/sv/dhcpcd to /var/service/ ensures that your network configuration utility starts automatically on every subsequent boot of your ZFS root environment.
With localizations set, the root password established, and runit services linked for automatic startup, your core environment is prepared for advanced storage and kernel integration.
Now that the base files are deployed to your storage pool, the next step involves entering the chroot environment to configure core system parameters, localization, and root credentials.
Dracut and Initramfs Integration for ZFS
Configuring the initramfs using Dracut is a critical step to ensure that your Void Linux system can successfully recognize, decrypt, and mount your ZFS root filesystem during early boot.
Once you have chrooted into your newly bootstrapped Void Linux environment, you must install the required ZFS packages, Dynamic Kernel Module Support, and essential boot utilities using the XBPS package manager. This includes installing the zfs and dkms packages, alongside efibootmgr and the appropriate CPU microcode to ensure complete hardware compatibility.
Next, you need to configure Dracut to incorporate ZFS modules and omit unnecessary filesystems like Btrfs or swap resume hooks. By creating a custom configuration file in the /etc/dracut.conf.d/ directory, you instruct Dracut to add the ZFS module, force load ZFS kernel drivers, disable file system checks with nofsck="yes", and include any required encryption key files.
After establishing these configuration rules, you must compile the initramfs images across all installed kernels by executing the xbps-reconfigure command, ensuring that the final boot images contain all necessary logic for handling your ZFS root pool.
Installing Essential ZFS and Boot Packages
With the base Void Linux system bootstrapped and your chroot environment initialized, you must install the critical software packages required to manage the ZFS filesystem, build kernel modules on the fly, and handle Unified Extensible Firmware Interface (UEFI) boot entries.
Before installing packages inside your chroot, ensure that your package manager is fully up to date and that the necessary repositories are enabled. Because Void Linux manages package repositories dynamically, updating the system repositories first prevents dependency conflicts during the installation of kernel modules and ZFS utilities.
To install the required backend packages, execute the XBPS package manager command for the chroot environment. You will need to install the core ZFS package along with Dynamic Kernel Module Support (DKMS) to ensure that the ZFS kernel modules compile correctly against your current kernel version. Additionally, you must install efibootmgr to manipulate NVRAM boot variables, along with the appropriate CPU microcode package for your processor architecture.
For systems powered by Intel processors, install the intel-ucode package. If your motherboard runs an AMD CPU, install the amd-ucode package instead. These microcode updates are loaded early in the boot process by the bootloader or initramfs, mitigating hardware vulnerabilities and improving CPU stability.
Run the following command inside your chroot to install these essential components simultaneously: xbps-install -S zfs dkms efibootmgr (along with your specific CPU microcode). This command pulls in the ZFS userland utilities, the kernel-independent DKMS infrastructure, and boot management tools required for the subsequent Dracut configuration phase.
Once these packages are successfully installed, your Void Linux environment will have the necessary tools to compile ZFS modules and interface with your motherboard's UEFI firmware.
Configuring Dracut Modules and Compiling
Proper configuration of Dracut is a critical milestone when installing Void Linux on a ZFS root filesystem, as it ensures that the generated initramfs contains all the modules, drivers, and decryption keys required to discover and mount your ZFS pools during early boot.
To configure Dracut for ZFS on Void Linux, you must create a dedicated configuration file within the chroot environment. Typically, system administrators place this configuration inside the `/etc/dracut.conf.d/` directory, naming the file either `zol.conf` or `zfs.conf`. This file informs Dracut which modules to load and which unnecessary features to strip away, streamlining the initial ramdisk for ZFS compatibility.
Inside your newly created Dracut configuration file, you need to define several essential directives. Set `nofsck="yes"` to prevent the boot process from running standard filesystem checks on ZFS pools, which are managed natively by ZFS itself rather than traditional utilities. Next, explicitly instruct Dracut to incorporate the ZFS module by adding it to the inclusion list, while safely omitting conflicting or unused modules such as Btrfs and swap resume utilities to keep the initramfs lightweight and free of errors.
Furthermore, you must force Dracut to load the ZFS kernel drivers early in the boot sequence by appending them to the driver list. If your ZFS root pool utilizes native encryption, you also need to make sure that your key files are bundled directly into the initramfs image. This is accomplished by utilizing the `install_items` directive to point directly to your dataset's key file location inside the chroot.
Failing to include the encryption keys in the Dracut install_items will result in a boot failure where the root dataset cannot be decrypted.
Once your configuration file is accurately populated and saved, the final step in this phase is to compile the initramfs images for your installed kernels. On Void Linux, package configurations and kernel hooks are managed through the XBPS package manager. You can trigger a full regeneration of all initramfs images by executing the `xbps-reconfigure -fa` command. This ensures that every installed kernel is paired with an updated initramfs built according to your custom Dracut rules, making the system fully prepared to interact with your ZFS storage pool upon reboot.
With Dracut successfully configured and the initramfs compiled with ZFS and encryption support, your system is ready for bootloader integration.
With Dracut properly configured and the initramfs generated, the system is fully prepared to hand off execution to the bootloader.
Implementing ZFSBootMenu to Boot Linux from ZFS
Implementing ZFSBootMenu on Void Linux delivers a robust, self-contained bootloader experience that eliminates the need for traditional kernel and initramfs files to reside on the EFI System Partition.
By utilizing ZFSBootMenu, your Void Linux installation gains native capability to discover kernels, initialization images, and boot environments directly from your ZFS datasets. This approach leverages kexec to transition cleanly from the lightweight bootloader environment into your fully loaded root pool, bypassing many of the constraints associated with standard bootloaders when managing advanced ZFS features like encryption and multiple boot environments. To achieve a seamless installation, you must meticulously handle your EFI System Partition, deploy the bootloader binary or configuration, and establish the correct dataset properties so the system can locate and parse your operating system components during early boot.
EFI System Partition (ESP) Setup
Proper configuration of the EFI System Partition is a mandatory step to ensure your ZFS-enabled Void Linux system can boot reliably across reboots.
Before ZFSBootMenu can load your kernel and initramfs from the ZFS datasets, your system firmware needs a dedicated, accessible location to read initial boot binaries. The EFI System Partition (ESP), typically formatted as FAT32, serves this critical role. If you created a new ESP during the disk partitioning phase, you must verify that it is properly formatted with a FAT32 file system using standard utilities like mkfs.fat. For systems utilizing multiple boot disks or mirrored configurations, ensuring the ESP is replicated across drives or correctly referenced is vital for hardware redundancy.
Inside your chroot environment, you must ensure the ESP is correctly mounted so that bootloader installations and future kernel updates populate the correct directory structure. Conventionally, the ESP is mounted at /boot/efi or simply /efi. You should create this mount point inside your target root directory if it does not already exist, and mount the specific partition using its Universally Unique Identifier (UUID) to prevent device-naming discrepancies on subsequent boots. You can retrieve the partition UUID using the blkid utility.
To make this mount permanent across system reboots, you must record it in your /etc/fstab file. Add an entry mapping the ESP UUID to your chosen mount point with the appropriate options, ensuring it is set to vfat filesystems. A correctly configured /etc/fstab entry prevents systemd or vfs mount routines from failing during early boot sequences and ensures that ZFSBootMenu updates—which often copy new EFI binaries directly to the ESP—always write to the correct physical storage sector.
With the FAT32-formatted ESP securely mounted and documented in fstab, your environment is fully prepared for installing and configuring ZFSBootMenu.
Installing and Configuring ZFSBootMenu
Choosing how to deploy ZFSBootMenu on your Void Linux installation is a critical step in finalizing your setup, offering flexibility depending on your preference for precompiled simplicity or deep system customization.
When setting up ZFSBootMenu as your primary bootloader, you generally choose between two distinct installation approaches: downloading a prebuilt EFI binary or generating a custom image directly from your system packages. The first and most straightforward method involves fetching the prebuilt VMLINUZ.EFI binary provided by the ZFSBootMenu project. This method requires minimal configuration; you simply create an appropriate directory structure within your EFI System Partition, typically at /boot/efi/EFI/ZBM/, and copy the downloaded binary there. It provides a robust, self-contained environment that works out of the box without needing to manage local initramfs compilation routines for the bootloader itself.
Alternatively, you can install the zfsbootmenu package directly inside your Void Linux environment using XBPS and build a custom bootloader image tailored specifically to your hardware and kernel preferences. This second method relies on configuring /etc/zfsbootmenu/config.yaml, where you can define global parameters, kernel command-line arguments, image output paths, and specific pool behaviors. Building your own image ensures that the bootloader stays synchronized with your system libraries and kernel updates, giving advanced users absolute control over the components included in the ZFSBootMenu environment.
Regardless of the installation route you select, managing user interaction and boot delays is easily handled through the zbm-kcl utility. By default, ZFSBootMenu pauses during startup to let you select a specific boot environment, snapshot, or kernel version. Using zbm-kcl, you can inspect or modify the kernel command line stored in the ZFS dataset properties and adjust the menu timeout values to suit your preference. Whether you want an instantaneous boot or a generous window to select historical snapshots, zbm-kcl allows you to fine-tune these operational parameters dynamically without needing to recreate your EFI binaries.
With your preferred ZFSBootMenu installation method complete and your timeout configurations adjusted, your system is fully prepared to discover and launch your Void Linux kernels directly from the ZFS root datasets.
Setting Dataset Properties and Boot Entries
Properly configuring dataset properties and registering your boot entries is vital to ensure that ZFSBootMenu can successfully locate your encryption keys, pass the correct kernel parameters, and interface with your motherboard's UEFI firmware.
Once ZFSBootMenu and your core system are in place, you must instruct the bootloader on how to interact with your specific storage layout. This is accomplished primarily by setting user properties directly on your ZFS datasets. These properties are queried dynamically by ZFSBootMenu at boot time, eliminating the need to hardcode complex kernel command lines inside external configuration files.
- org.zfsbootmenu:commandline - Defines the kernel command-line arguments (such as "quiet loglevel=3 rw") that will be appended when booting your Void Linux environment.
- org.zfsbootmenu:keysource - Specifies the dataset pool and path where encryption keyfiles reside (e.g., zroot/ROOT/void), allowing ZFSBootMenu to automatically unlock dependent child datasets without prompting multiple times.
To apply these properties, execute the appropriate zfs set commands from your chroot or live environment. For example, setting the command line parameters on your root dataset ensures that every snapshot or boot environment inherits these rules. If your pool is encrypted, associating the keysource property correctly is mandatory so that ZFSBootMenu can parse the key material before attempting to load your root file system.
With dataset properties finalized, you must register the ZFSBootMenu EFI application with your motherboard's NVRAM using efibootmgr. Ensure that your ESP is mounted, and run a command specifying your disk, partition number, and the relative path to the ZFSBootMenu binary (for example, /EFI/ZBM/VMLINUZ.EFI). This creates a persistent UEFI boot entry. Alternatively, if you prefer using a multi-boot manager like rEFInd, you can configure a manual stanza pointing directly to the ZFSBootMenu EFI executable.
Configuring these metadata properties and firmware hooks guarantees that your machine can autonomously discover, decrypt, and boot your Void Linux root filesystem on every subsequent startup.
Let us proceed by examining the precise steps required for setting up your EFI System Partition and installing the ZFSBootMenu environment.
Finalizing the Void Linux ZFS Installation
With all core system configuration, bootloader setups, and kernel image compilations successfully completed inside your chroot environment, you have reached the final phase of your void linux zfs installation.
Before leaving the chroot, you must ensure that all network configurations and temporary files used during the installation process are thoroughly cleaned up. Remove any temporary symbolic links you created for DNS resolution, such as the temporary copy of resolv.conf, to prevent network resolution issues upon your first real boot into the new system. Verify that all essential configuration files, including your fstab, crypttab, Dracut modules, and ZFS encryption keys, are correctly placed and possess the proper file permissions.
Once the cleanup tasks inside the chroot are finished, exit the chroot environment by typing exit or pressing Ctrl+D. You will return to your live hrmpf ISO environment. At this stage, it is critical to unmount all active filesystems in the correct recursive order to prevent filesystem corruption or dangling references. Using a recursive unmount flag—such as executing umount -n -R /mnt—ensures that the EFI system partition, bind-mounted pseudo-filesystems like dev, proc, and sys, and all individual ZFS child datasets mounted under the target directory are safely detached.
The absolute final step before rebooting your machine is exporting the ZFS storage pool. Exporting the pool (for instance, zpool export zroot) flushes all pending data to disk, writes the latest transaction group metadata, and safely marks the pool as disengaged from the live environment. This prevents pool locking issues and ensures that ZFSBootMenu can cleanly import the pool upon system startup. After exporting the pool, you can safely reboot your machine, remove the live installation media, and let ZFSBootMenu take over.
Cleanup, Unmounting, and Pool Export
With your Void Linux system fully configured, packages installed, and bootloader ready, you are just a few commands away from completing the ZFS root installation.
Before leaving the chroot environment, you must clean up any temporary files or symlinks created during the bootstrapping process. If you copied or symlinked your live environment's resolv.conf to /mnt/etc/resolv.conf to download packages via XBPS, remove or reset it now to prevent networking issues on your first real boot. Once cleanup is complete, type exit or press Ctrl+D to leave the xchroot environment and return to your live installation medium shell.
Next, you must unmount all of the filesystems you mounted under /mnt in the correct manner. Because ZFS mounts and bind mounts can be complex, use the recursive unmount flag to safely strip away every active mount point without corrupting the table. Execute the command umount -n -R /mnt to carefully unmount your ESP, root, home, and any other nested child datasets.
The final and most critical step before rebooting your hardware is exporting the ZFS storage pool. Running zpool export zroot writes all pending log transactions, safely flushes data to your physical drives, and releases the pool lock so it can be cleanly imported by ZFSBootMenu on your next startup. Neglecting to export the pool can result in dirty states or missing metadata when the system powers back on. Once the export command finishes successfully without errors, you can safely reboot your machine, remove your installation USB, and experience your new void linux zfs root environment.
Safely cleaning your environment, recursively unmounting filesystems, and exporting the zpool ensures a seamless handoff to ZFSBootMenu.
Proceeding with these final unmounting and export procedures guarantees a flawless transition into your newly installed Void Linux operating system.
By successfully completing a Void Linux ZFS root installation, you have established a high-performance, resilient operating system that marries the lightweight efficiency of the runit init system with the enterprise-grade data integrity of OpenZFS. Utilizing ZFSBootMenu and Dracut grants you direct visibility into your boot environments and snapshots right from the bootloader, ensuring you can safely test updates and roll back system states effortlessly. To maintain and secure your new setup, your immediate next steps should include creating standard non-root user accounts, configuring automated snapshots with tools like zfs-auto-snapshot, and restarting your system to test your decryption passphrases and boot menu configurations.