Nathan Laundry

ZFS Boot Menu Autoinstaller: Automating the Tedious Bits

zfs debian automation bash linux homelab boot-menu scripting here-documents
GitHub

ZFS Boot Menu Autoinstaller: Automating the Tedious Bits

Hey friends,

I’ve mentioned this script in a few places before, but I wanted to give it a proper writeup since it’s become one of my most-used automation tools. This project came out of the same motivation as my ProxBox systems—I was preparing to rebuild my homelab after moving and wanted everything to be reproducible.

As I talked about in my YouTube video about ZFS Boot Menu, ZFS Boot Menu is incredible for homelab use. The ability to boot from any snapshot, roll back system changes instantly, and manage multiple boot environments is a game-changer for anyone experimenting with different configurations.

The problem? The manual installation process is absolutely brutal.

The Problem: 50+ Manual Steps

If you’ve ever tried to install Debian with ZFS Boot Menu manually, you know what I’m talking about. The official documentation is thorough, but it requires:

  • Precise disk partitioning with fdisk
  • Creating ZFS pools with specific settings
  • Bootstrapping a Debian system with debootstrap
  • Configuring the chroot environment
  • Setting up ZFS Boot Menu
  • Configuring the EFI bootloader
  • Multiple reboots and configuration steps

One small mistake—like forgetting to set the right ashift value or misconfiguring the EFI partition—and you’re starting over. I made that mistake more times than I care to admit.

The Solution: Automation Through Bash

Since I knew I’d be rebuilding multiple machines, I decided to bite the bullet and automate the entire process. The result is a bash script that handles all the tedious bits while still giving you the flexibility to customize your setup.

What the Script Does

The autoinstaller handles the complete installation by:

  • Detecting available disks and letting you choose the target
  • Partitioning automatically with proper EFI and ZFS layouts
  • Creating ZFS pools with optimized settings for modern hardware
  • Installing Debian using debootstrap
  • Configuring the chroot environment with proper repositories and packages
  • Setting up ZFS Boot Menu with all the right configurations
  • Installing the EFI bootloader with proper fallback options

The Technical Details

The script makes some opinionated choices that work well for homelab use:

  • ashift=12: Optimized for 4K sector alignment (works with most modern drives)
  • compression=lz4: Fast compression with minimal CPU overhead
  • autotrim: Automatic SSD optimization
  • relatime: Reduced disk writes for access times

These settings give you the performance benefits of ZFS without the complexity of tuning everything manually.

Using Here-Documents for Complex Operations

One of the interesting challenges was handling the chroot environment setup. As I mentioned in my Life and Lab 1 post, I used bash here-documents to pass entire command sequences into the chroot environment. This let me handle complex configuration tasks in a clean, readable way.

chroot $MOUNT_POINT /bin/bash <<-EOF
    # Configure apt sources
    cat > /etc/apt/sources.list <<-EOF_APT
    deb http://deb.debian.org/debian bookworm main contrib non-free-firmware
    deb-src http://deb.debian.org/debian bookworm main contrib non-free-firmware
    EOF_APT
    
    # Update package lists and install essentials
    apt update
    apt install -y linux-image-amd64 linux-headers-amd64 zfsutils-linux
    
    # Configure ZFS Boot Menu
    # ... more configuration here
EOF

The nested here-documents were tricky to get right, but they made the script much more maintainable than trying to handle everything with individual commands.

How to Use It

The script is designed to be run from a Debian live environment. Once you’ve booted into a live system:

sudo su
apt update && apt install curl
curl -O https://raw.githubusercontent.com/NLaundry/zfsbootmenu-autoinstaller/main/setup-zfsbootmenu.sh
chmod +x setup-zfsbootmenu.sh
./setup-zfsbootmenu.sh

The script will walk you through disk selection and handle the rest automatically. It includes plenty of prompts and confirmations so you don’t accidentally wipe the wrong disk.

What I Learned

Building this script taught me a lot about bash scripting, particularly around error handling and user interaction. Some key lessons:

Error Handling is Critical: ZFS operations can fail in subtle ways, so the script includes extensive error checking and rollback capabilities.

User Prompts Matter: Making the script interactive with clear prompts prevents those “oh no, I just wiped the wrong disk” moments.

Documentation is Your Friend: The ZFS Boot Menu documentation is excellent, but translating it into automation required understanding not just what to do, but why each step matters.

Testing is Essential: I probably reinstalled Debian 20+ times while developing this script. Having a test VM was crucial.

The Results

Since building this script, I’ve used it to install ZFS Boot Menu on:

  • My main development workstation
  • Multiple homelab servers
  • Test VMs for experimentation
  • Friends’ systems (with their permission, of course)

Each installation takes about 15-20 minutes instead of the 2+ hours it used to take manually. More importantly, I’m confident that every installation is consistent and properly configured.

Fair Warning

This script represents my understanding of ZFS Boot Menu installation as of late 2024. It’s worked reliably for my use cases, but ZFS and boot configuration can be tricky. I’d recommend:

  • Testing in a VM first
  • Having backups of any important data
  • Understanding what the script does before running it
  • Being prepared to troubleshoot if something goes wrong

The script is available on GitHub with installation instructions and configuration details.

Building for Reproducibility

This script is part of my broader approach to homelab automation. Whether it’s the ProxBox systems for cluster deployment or this ZFS Boot Menu installer, the goal is always the same: build it once, use it everywhere.

The peace of mind that comes from knowing you can rebuild your entire infrastructure quickly and consistently is worth the upfront investment in automation. Plus, you learn a ton about the underlying technologies while building the automation.

That’s the beauty of project-based learning—you don’t just end up with a useful tool, you gain deep understanding of how everything works underneath.

Cheers,

Nathan

~Nathan Laundry