stefano/void-zfs-hibernation
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
14 commits 1 branch 0 tags 62 KiB
  • Shell 100%
Find a file
Exact
Stefano Marinelli 6a8919fd3f Added Gnome and XFCE
2026-08-24 09:52:52 +02:00
README.md Added Gnome and XFCE 2026-08-24 09:52:52 +02:00
void-zfs-install.sh Added Gnome and XFCE 2026-08-24 09:52:52 +02: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

  • KDE Plasma, GNOME, XFCE, or minimal installation profiles

  • 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

  • ZFSBootMenu generated locally from the Void package, with primary, backup, and fallback EFI images

  • KDE Plasma, GNOME, XFCE, or minimal installation profiles

  • Optional Flatpak support

  • CPU microcode installation (Intel or AMD)

  • Preflight checks and cleanup after errors or interruptions

  • Full logging and an initial recursive recovery snapshot

Requirements

  • Booted from the hrmpf live environment
    https://github.com/leahneukirchen/hrmpf

  • UEFI system with EFI variables available

  • 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

  • Dracut includes the key and crypttab in the initramfs so swap is available for 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 based on the installed RAM

  • Encryption passphrases

  • System configuration (hostname, locale, timezone)

  • Desktop profile (kde, gnome, xfce, or none; KDE is the default)

Before any destructive action, a full summary is shown. To continue, you must type ERASE /dev/... with the selected disk path exactly as shown.

The input validation and swap calculations can be checked without root privileges:

./void-zfs-install.sh --self-test

Interaction Required

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

  • ZFS encryption passphrase

  • Swap encryption passphrase

  • Root password (inside chroot)

  • Desktop profile and optional Flatpak support

  • Desktop user password (for KDE, GNOME, or XFCE)

Profiles, Networking, and Hibernation

The desktop prompt accepts kde, gnome, xfce, or none, without regard to case. Press Enter for KDE.

The graphical profiles enable dbus, elogind, polkitd, and NetworkManager, configure PipeWire, disable competing network services and acpid, point resolv.conf to NetworkManager, and grant sudo access to members of wheel. Flatpak is optional for each one.

  • KDE Plasma uses SDDM.

  • GNOME uses GDM and its default Wayland session; Xorg remains available from the login screen.

  • XFCE uses LightDM and its conventional Xorg session, with the integration packages included in Void's XFCE image.

Log in at the selected profile's display-manager screen with the desktop user created during installation. Hibernate from any graphical profile with:

loginctl hibernate

The minimal (none) profile creates no desktop user, enables dhcpcd, and keeps a working resolv.conf. Log in on the console as root and hibernate with:

ZZZ -Z

Logging

A full installation log is written to:

/tmp/void-zfs-install.log

It is also copied to the installed system at:

/var/log/void-zfs-install.log

The installed copy is preserved if an error occurs after the base system has been created.

Recovery

A successful installation creates the recursive snapshot zroot@install. ZFSBootMenu is installed as a primary image, a backup image, and the standard EFI/BOOT/BOOTX64.EFI fallback.

To inspect the installed system from a live environment:

zpool import -N -R /mnt zroot
zfs load-key zroot
zfs mount zroot/ROOT/void

List the recovery snapshots with:

zfs list -t snapshot

Security Notes

  • The ZFS passphrase is stored in /etc/zfs/zroot.key inside the encrypted installed system and included in its initramfs. The temporary copy in the live system is removed as soon as it is no longer needed.

  • The swap installation passphrase is kept in temporary mode-0600 files and shredded after a random /boot/volume.key has been enrolled.

  • Review and adjust the encryption strategy if your threat model requires it.

Related Documentation

Also based on:

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.