Skip to content

Filesystem drivers#

cloud-boot ships pure-Go userland filesystem drivers so that the bootstrap kernel can stay minimal. Instead of carrying CONFIG_EXT4_FS, CONFIG_XFS_FS, CONFIG_BTRFS_FS, and an out-of-tree OpenZFS module, the kernel only needs virtio-blk and the userland drivers read everything from /dev/vdN.

This pivot — codename userland-fs-drivers — replaced unix.Mount(2) with a per-FS Go reader from the github.com/go-filesystems/* org.

Support matrix#

FS Single-device Multi-device LUKS overlay Native encryption
ext4 ✓ — (use md/dm) ✓ —
XFS ✓ — (use md/dm) ✓ —
btrfs ✓ ✓ all 6 profiles ✓ —
ZFS ✓ ✓ all 5 layouts ✓ ✓ AES-CCM/GCM

btrfs RAID profiles#

Profile Devices Mechanism
single 1 direct read
raid0 2+ striped, multi-device routing
raid1 2+ mirror — single-leg open works
raid10 4+ mirror pairs + striping
raid5 3+ data + 1 parity column (healthy-read)
raid6 4+ data + 2 parity columns (healthy-read)
dup 1 (2 copies) DUP — picks the local stripe

ZFS layouts#

Layout Devices Mechanism
single 1 direct read
mirror 2+ identical legs — open any one
raidz1 3+ data + 1 parity column
raidz2 4+ data + 2 parity columns
raidz3 5+ data + 3 parity columns

Healthy-path vs degraded-path

The matrix above covers healthy-path reads — all data devices present. Degraded reads (one or more legs missing, requiring parity reconstruction) need a Reed-Solomon GF(2^8) implementation that isn't shipped yet. RAID-Z1 / btrfs RAID5 can be reconstructed with a single XOR; Z2/Z3/RAID6 need a proper Vandermonde-based GF reconstruction. Cloud images aren't degraded in the typical install, so this rarely matters in practice.

Driver pages#

  • ext4

    Single-device, journal-replay-on-open, MBR/GPT auto-detect. The most common chained distro filesystem.

  • XFS

    Single-device. v5 superblock format. AlmaLinux 9 uses XFS for both /boot and /.

  • btrfs (incl. RAID)

    Single + RAID0/1/10/5/6. Multi-device discovery via on-disk fsid scan. Six profiles verified against real mkfs.btrfs output. Three pre-existing on-disk format bugs in the lib were fixed along the way.

  • ZFS (incl. RAID-Z)

    Single + mirror + raidz1/2/3. Multi-vdev pools open via OpenFromDevices after findZFSVdevs matches pool_guid + sorts legs by LeafGUIDs. Eleven pre-existing on-disk format bugs in the lib were fixed along the way.

  • LUKS overlay

    LUKS1/LUKS2 unlock via github.com/go-fde/luks → BlockBackend adapter → any of the four FS opener paths layered on top of the plaintext device.

  • Multi-device discovery

    How findBtrfsLegs (fsid scan) and findZFSVdevs (label NVList scan) assemble multi-device pools at boot time.

Why this matters for the kernel#

With the userland FS pivot, kernel/disk-arm64.config drops:

-CONFIG_EXT4_FS=y
-CONFIG_XFS_FS=y
-CONFIG_BTRFS_FS=y

CONFIG_VFAT_FS stays — it's needed by Path C to write the reboot sink's ESP, where we mount a freshly-created GPT partition we own end-to-end. Approximate size reduction of the kernel Image: ~5 MiB.

ZFS support that previously required either an out-of-tree OpenZFS DKMS module or the zfsutils-linux userspace stack now requires neither. The pure-Go ZFS driver in go-filesystems/zfs reads real OpenZFS-produced pools end-to-end — single-vdev, mirror, and all three raidz levels — verified in CI against zpool create fixtures generated by zfsutils-linux 2.1.11 on Debian 12.