No description

Find a file

stefano 7999306c18 It clarifies that the ZFS password should be at least 8 chars long		2025-12-31 18:21:18 +01:00
README.md	Added article link	2025-12-21 09:45:22 +01:00
void-zfs-install.sh	It clarifies that the ZFS password should be at least 8 chars long	2025-12-31 18:21:18 +01:00

README.md

Void Linux on ZFS with Hibernation - Semi-Automated Installer

This repository contains an interactive installation script that automates the setup of Void Linux on ZFS, with:

Native ZFS root filesystem
Full disk encryption (ZFS native encryption)
Encrypted swap on a dedicated LUKS partition
Working hibernation and resume
Optional KDE Plasma desktop environment
Boot management via ZFSBootMenu (UEFI)

The script is based on real-world usage and on the accompanying article published on https://it-notes.dragas.net, and aims to turn a complex manual procedure into a repeatable and less error-prone process.

⚠️ Important Warning

This script will DESTROY ALL DATA on the selected disk.

It is intended for experienced users only.
Read the code, understand what it does, and use it at your own risk.

This is not an unattended installer. User interaction is required.

Features

Single-disk ZFS layout with sane defaults
ZFS native encryption for the root pool
Separate LUKS-encrypted swap partition
Correct resume-from-hibernation handling with ZFSBootMenu
Automatic generation of ZFSBootMenu EFI entries
Optional KDE Plasma desktop installation
Optional Flatpak support
CPU microcode installation (Intel or AMD)
Clear logging and step-by-step progress output

Requirements

Booted from the hrmpf live environment
https://github.com/leahneukirchen/hrmpf
UEFI system
Secure Boot disabled
Single disk (NVMe, SATA, SAS, or eMMC)
Internet connectivity
A keyboard layout compatible with early-boot passphrase entry (US layout recommended)

What This Script Assumes

One disk only (no mirrors or RAID)
GPT partitioning
EFI System Partition (512 MB)
Swap on a dedicated partition, not a ZFS zvol
ZFSBootMenu used as the only boot loader
Dracut-based initramfs (Void Linux default)

If your setup differs, you will need to adapt the script manually.

High-Level Disk Layout

/dev/
├─ EFI System Partition (512 MB)
├─ Swap (LUKS encrypted) (RAM size + margin)
└─ ZFS Pool Partition (remaining space)

Encryption Model

ZFS root is encrypted using native OpenZFS encryption
Swap uses LUKS1 encryption
A random keyfile for swap is stored on the encrypted ZFS filesystem
ZFSBootMenu unlocks the swap before mounting ZFS during resume

This design allows hibernation to work correctly on a ZFS root system.

Usage

Boot into the hrmpf live environment, ensure networking is available, then run:

chmod +x void-zfs-install.sh
./void-zfs-install.sh

The script will guide you through:

Disk selection
Swap size calculation
Encryption passphrases
System configuration (hostname, locale, timezone)
Desktop installation (optional)

Before any destructive action, a full summary is shown and explicit confirmation is required.

Interaction Required

The script is not fully unattended. You will be prompted for:

ZFS encryption passphrase
Swap encryption passphrase
Root password (inside chroot)
Desktop user password (if desktop is enabled)

Logging

A full installation log is written to:

/tmp/void-zfs-install.log

This is useful for debugging or post-install review.

Security Notes

The ZFS encryption passphrase is written to a key file during installation and copied into the installed system, exactly as described in the accompanying article.
This favors automation and recovery over maximum secrecy.
Review and adjust the encryption strategy if your threat model requires it.

ZFSBootMenu: https://docs.zfsbootmenu.org/
Void Linux Handbook: https://docs.voidlinux.org/
hrmpf live system: https://github.com/leahneukirchen/hrmpf

Also based on:

Void Linux (UEFI) from ZFSBootMenu - which doesn't address swap. Using a zvol for swap (not the best solution) prevents hibernation and resume. Our approach uses a separate encrypted swap partition that enables proper resume.
Void Linux Full Disk Encryption - excellent for btrfs or ext4, but we want ZFS. We'll borrow the swap configuration approach from here.
Install Void Linux with a desktop environment + Flatpaks - for the desktop portion.

License

2025, Stefano Marinelli - stefano@dragas.it - MIT License

Do whatever you want with it, but you are responsible for your data and your system.

Disclaimer

This script is provided as-is, without warranty of any kind.
If it breaks your system, eats your data, or teaches you something new the hard way, that's on you.

Enjoy ZFS on Void Linux.