Gentoo live ISO and ZFSBootMenu for T2 Macs, with ZFS

A container build that produces, from one kernel build:

• a bootable Gentoo live image carrying the t2 overlay kernel and matching ZFS modules and tools, for installing Gentoo on a ZFS root with native encryption;
• a ZFSBootMenu EFI executable built on that same kernel, to boot the installed system.

See plan/ for the background.

Fan Controller

Also look in fans for fan controlling scripts for the 2019 Mac Pro.

• fans/t2-fans - Copy to /usr/local/sbin/t2-fans
• fans/t2-fans.openrc - Copy to /etc/init.d/t2-fans
• Both need to be executable.
• Run rc-update add t2-fans default for Gentoo/OpenRC systems

Why build an image

None of the images linked from the t2linux wiki ship ZFS. The T2-Ubuntu ISO fails with zfs-dkms only because Ubuntu's packaged ZFS is older than the ISO's kernel; current OpenZFS supports kernels well past 6.6. Building the kernel and ZFS together from Gentoo avoids the mismatch, and the live environment is already Gentoo, with the overlay configured.

Build

Needs Docker with BuildKit and about 30G of free space. The kernel is compiled from source; everything else that can be is pulled from the Gentoo binhost.

./build.sh

The results land in out/:

gentoo-t2-zfs-<kernel>.iso    the live image
EFI/zbm/VMLINUX.EFI           ZFSBootMenu
*.txt                         versions and checksums of each

Build arguments (./build.sh --build-arg NAME=value):

Argument	Default	Meaning
KERNEL_BRANCH	6.18	Kernel branch to take from the overlay
KERNEL_VERSION	(unset)	Exact version, e.g. 6.18.55; overrides auto-select
T2_OVERLAY_URI	pierolenzo's	Git URL of the t2 overlay
ISO_LABEL	T2GENTOOZFS	Volume label, also used to find the live media
STAGE3_IMAGE	gentoo/stage3:latest	Base image (must be an OpenRC stage)
PORTAGE_IMAGE	gentoo/portage:latest	Gentoo tree snapshot
ZBM_VERSION	3.1.0	ZFSBootMenu release; set ZBM_SHA256 to match

The overlay's kernel ebuilds are generated automatically and the newest one does not always patch cleanly. Unless KERNEL_VERSION is set, the build walks the branch from newest to oldest and builds the first version whose patches apply.

The two base images move daily, so a rebuild on another day compiles a new kernel. To rebuild against the same tree as an earlier build, pass both as image@sha256:...; docker build prints the digests it resolved.

Test

./test-qemu.sh
ssh -p 2222 gentoo@localhost

Boots the ISO as a USB stick under UEFI QEMU with a blank 4G NVMe disk.

Use

Write the ISO to a USB stick (this erases it):

dd if=out/gentoo-t2-zfs-<version>.iso of=/dev/sdX bs=4M status=progress oflag=sync

Boot the Mac holding Option and pick the EFI entry. As for any Linux on a T2 Mac, Secure Boot must be set to "No Security" and booting from external media allowed in Startup Security Utility.

In the live system:

• User gentoo, password gentoo, passwordless sudo. The root password is also gentoo, so su works.
• sshd is running with password login enabled; root login over SSH is not.
• Wired network is configured by dhcpcd. For Wi-Fi use iwctl.
• zfs and the T2 drivers (t2bce_*, this overlay's name for apple-bce) are loaded at boot.
• The Gentoo tree and the t2 overlay are in /var/db/repos, and the kernel build tree is in /usr/src/linux.

ZFSBootMenu

Copy out/EFI/zbm/VMLINUX.EFI to EFI/zbm/VMLINUX.EFI on the EFI system partition. It is a single file holding the T2 kernel, an initramfs with the ZFS modules and the T2 drivers, and the kernel command line quiet loglevel=0 intel_iommu=on iommu=pt pm_async=off.

It imports the pool, asks for the passphrase of an encrypted boot environment, and boots the kernel it finds in that environment's /boot. What it needs from the installed system:

• a kernel and initramfs in /boot of the root dataset (not on the EFI partition), and the initramfs must contain ZFS;

• the pool's bootfs property, or org.zfsbootmenu:active, pointing at the root dataset;

• the installed kernel's command line in the org.zfsbootmenu:commandline property. ZFSBootMenu does not pass its own command line on, so the T2 options have to be repeated there:

  zfs set org.zfsbootmenu:commandline="rw intel_iommu=on iommu=pt pm_async=off" zroot/ROOT
  

The installed system's initramfs asks for the passphrase a second time unless the key is made available to it; the ZFSBootMenu documentation describes the usual keyfile-in-initramfs arrangement.

To change the command line of the EFI file without rebuilding, edit zbm/config.yaml and rerun ./build.sh with the base images pinned as above; only the last stage is rebuilt.

Layout

Dockerfile      rootfs stage (the live system) and iso stage
rootfs/         files copied over the live root
iso/mkiso.sh    initramfs, squashfs and ISO assembly
iso/grub.cfg    boot menu
zbm/mkzbm.sh    ZFSBootMenu EFI executable
zbm/config.yaml generate-zbm configuration, including the command line
zbm/dracut.conf.d/  extra dracut settings for the ZFSBootMenu initramfs