Filesystem drivers

title: Filesystem drivers

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

:material-file-tree:{ .lg .middle } ext4
Single-device, journal-replay-on-open, MBR/GPT auto-detect. The most common chained distro filesystem.
:material-file-tree:{ .lg .middle } XFS
Single-device. v5 superblock format. AlmaLinux 9 uses XFS for both /boot and /.
:material-file-tree-outline:{ .lg .middle } 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.
:material-database:{ .lg .middle } 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.
:material-lock:{ .lg .middle } 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.
:material-magnify-scan:{ .lg .middle } 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.