ADR 010: OpenZFS 2.4.x from Debian trixie-backports

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/decisions/010-openzfs-from-trixie-backports.md. Edit at the source, not here.

ADR 010: OpenZFS 2.4.x from Debian trixie-backports

Status

Accepted

Context

Hito 0.3 requires OpenZFS as a DKMS kernel module on Trixie (see ADR 008 and ADR 009). The choices for sourcing the package are:

1. Debian main (trixie). Ships OpenZFS 2.3.x. Stable, security- supported, but locked to the major version that was current when Trixie froze.
2. Debian trixie-backports. Ships OpenZFS 2.4.x (2.4.1 as of this writing). Tracks the latest upstream major while remaining a first-party Debian archive.
3. Upstream OpenZFS APT repository. Latest upstream, but outside the Debian archive; requires trusting a non-Debian GPG key and package maintenance track.
4. Built from source against the running kernel. Highest control, but puts us in the business of shipping and qualifying OpenZFS builds — which we explicitly don’t want to do.

The 2.4.x series is desirable because two features are required by the Hito 3 architecture:

• Block cloning (feature@block_cloning). Makes CoW clones between datasets a true metadata operation, removing a class of slow copies during template / provisioning workflows.
• raidz expansion (feature@raidz_expansion). Adds a disk to an existing raidz vdev online. This is load-bearing for the Standalone-mode upgrade story (“add a disk to an existing node without recreating the pool”).

We want to baseline on 2.4.x from Hito 0.3 so that every existing localdata pool in the field is already on the target feature set when Hito 3 lands.

Decision

Source OpenZFS from trixie-backports with APT pinning.

/etc/apt/sources.list.d/backports.list:

deb http://deb.debian.org/debian trixie-backports main contrib non-free-firmware

/etc/apt/preferences.d/90-zfs-backports:

Package: src:zfs-linux
Pin: release n=trixie-backports
Pin-Priority: 990

Installed packages (pulled during preseed late_command):

• zfs-dkms — kernel module, DKMS-built per installed kernel
• zfsutils-linux — userspace (zfs, zpool, etc.)
• zfs-initramfs — initramfs hooks so ZFS is available early in boot

Rationale

• First-party Debian archive. trixie-backports is part of the Debian infrastructure. No extra GPG keys, no extra repository trust decisions. This is the lowest supply-chain cost option that still gives us 2.4.x.
• Tracks 2.4.x security updates. The pin at priority 990 ensures apt upgrade follows the 2.4.x minor stream automatically.
• Aligns with Hito 3 feature requirements. Block cloning and raidz expansion are already in 2.4.x, so Hito 3’s ZFS-on-root migration does not need a second base-package bump.
• DKMS is standard in the Debian ZFS packaging. zfs-dkms integrates cleanly with apt and the kernel lifecycle; no custom build scripts required on the node.

Consequences

• DKMS build discipline. Every kernel upgrade triggers a DKMS rebuild of the ZFS module. A failed rebuild would leave the node without ZFS after reboot. The 0.3.x release process includes a DKMS-rebuild smoke test in the CI matrix before any kernel point release is whitelisted.
• Backports-specific breakage surface. If OpenZFS 2.4.x gets a serious regression, we inherit it faster than if we were on main. Mitigation: the APT pin can be flipped to priority < 500 to roll back to the in-main version as an emergency rollback.
• Edge case during install. The DKMS build happens inside in-target during preseed late_command. If the installer kernel and the installed kernel disagree on build headers, the ZFS module may not load under the installer kernel — this is the trigger for the deferred synvirt-zfs-init.service path described in ADR 009.

Alternatives Considered

OpenZFS 2.3.x from Debian main

• Pros: Zero additional apt sources; the most conservative option.
• Cons: Blocks on a base-package bump for Hito 3 feature requirements. Every existing 0.3 pool would need a feature-flag upgrade at Hito 3.
• Decision: Rejected.

Upstream OpenZFS APT repository

• Pros: Always latest upstream.
• Cons: Non-Debian GPG key trust; extra repository to maintain in the appliance profile; support surface becomes “did upstream break us?” instead of “did Debian break us?”.
• Decision: Rejected.

Build OpenZFS from source on each node

• Pros: Full control over the build environment.
• Cons: We explicitly do not want to ship as a source-build distribution. Maintaining per-kernel artifacts is not in scope for the product.
• Decision: Rejected.