Native Kernel Client

The native client is an out-of-tree Linux module. It registers the zerofs filesystem with VFS and speaks 9P2000.L.Z over TCP or a Unix socket. Use it when ZeroFS provides a package for the exact running kernel. Use zerofs mount otherwise.

How it works

zerofs.ko connects Linux VFS and netfslib directly to the ZeroFS 9P server. Relaxed consistency uses the page cache, readahead, writeback, writable mmap, and netfslib direct I/O. The client also supports fallocate, SEEK_DATA, SEEK_HOLE, POSIX record locks, flock, and durable fsync.

The native path avoids the /dev/fuse handoff and has lower client-side overhead. Workload and cache state determine the end-to-end difference.

Stock Linux v9fs is also supported. It needs no ZeroFS module, but uses standard 9P2000.L and does not implement the private reconnect or metadata operations. See 9P File Access.

Compatibility

Linux 6.18 is the minimum supported kernel. The target must also provide:

• x86-64 or little-endian arm64;
• CONFIG_MODULES;
• CONFIG_NETFS_SUPPORT;
• CONFIG_UNIX;
• CONFIG_FILE_LOCKING;
• CONFIG_RANDSTRUCT=n and CONFIG_GCC_PLUGIN_RANDSTRUCT=n.

Each prebuilt package targets one exact kernel. Supported packages are:

Each package is built against its distribution kernel and boot-tested with a ZeroFS mount.

Ubuntu 24.04, Debian 13, Rocky Linux 9 and 10, and openSUSE Leap 16 ship kernels older than 6.18. Ubuntu 24.04 requires its HWE kernel.

Installation

Package

The kernel version links in the compatibility table point to the matching repository descriptor. Copy its URL into repo_url, then install the selector:

repo_url='https://pkgs.zerofs.net/kernel/apt/ubuntu/26.04/generic/x86_64/zerofs-kernel.list'

curl -fsSL https://pkgs.zerofs.net/zerofs.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/zerofs.gpg
curl -fsSL "$repo_url" \
  | sudo tee /etc/apt/sources.list.d/zerofs-kernel.list >/dev/null
sudo apt update
sudo apt install zerofs-kernel-client

zerofs-kernel-client installs the exact kernel and module packages for that channel.

The package runs depmod, loads the module when it matches the running kernel, and installs /usr/lib/modules-load.d/zerofs.conf for subsequent boots.

Source

A source build requires a kernel with CONFIG_RUST=y, its matching rust/libkernel.rmeta, kernel headers, and the compiler and bindgen versions used for that kernel. CONFIG_MODVERSIONS=y also requires Module.symvers and CONFIG_EXTENDED_MODVERSIONS=y.

cd ZeroFS/kernel
make KDIR=/lib/modules/"$(uname -r)"/build

module_path=$(make -s \
  KDIR=/lib/modules/"$(uname -r)"/build module-path)
sudo install -D -m 0644 "$module_path" \
  "/lib/modules/$(uname -r)/updates/zerofs/zerofs.ko"
sudo depmod -a "$(uname -r)"
printf '%s\n' zerofs | \
  sudo tee /etc/modules-load.d/zerofs.conf >/dev/null
sudo modprobe zerofs

Verify the installation:

modinfo zerofs
grep zerofs /proc/filesystems

Mounting

The source is an IP-literal TCP endpoint, a Unix socket, or a comma-separated HA endpoint set.

sudo mkdir -p /mnt/zerofs
sudo mount -t zerofs \
  -o consistency=relaxed,msize=10485760 \
  127.0.0.1:5564 /mnt/zerofs

Unmount with sudo umount /mnt/zerofs.

Kernels without Rust

ZeroFS can build an x86-64 module for a compatible kernel with CONFIG_RUST=n. The release build compiles the exact kernel's Rust support and ZeroFS together, internalizes the Rust code, and runs the result through the target kernel's normal module build. The resulting module imports C kernel symbols and does not require Rust support from the running kernel.

This requires the complete configured kernel source, Module.symvers, and matching Rust and LLVM tools. Distribution headers are not enough, so this path is used for controlled prebuilt packages rather than DKMS. It does not support kernels older than Linux 6.18.

CI tests this path by booting an upstream Linux 6.18 kernel built with CONFIG_RUST=n.