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. It is the fastest ZeroFS mount path when a module is available for the 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. DKMS excludes module builds below that floor and applies no version exclusion above it. Every otherwise eligible kernel presented to DKMS is attempted, whether or not CI has certified it yet. 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.

ZeroFS continuously tests the source package against these kernel channels:

Every discovered kernel is built and boot-tested with a ZeroFS mount and basic I/O before its compatibility lock is merged. The lock is CI evidence only and does not gate installation.

Debian 13, Rocky Linux 9 and 10, and openSUSE Leap 16 ship kernels older than 6.18.

Installation

Package

Kernel and userspace packages share the standard ZeroFS repository. Configure it once, then install zerofs and the generic kernel-client package:

curl -fsSL https://pkgs.zerofs.net/zerofs.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/zerofs.gpg
echo 'deb [signed-by=/usr/share/keyrings/zerofs.gpg] https://pkgs.zerofs.net/deb stable main' \
  | sudo tee /etc/apt/sources.list.d/zerofs.list >/dev/null
sudo apt update
sudo apt install zerofs zerofs-kernel-client

zerofs-kernel-client installs the module source under /usr/src, registers it with DKMS, and builds it for eligible kernels. mount -t zerofs loads the installed module through its filesystem alias. The commands above assume the matching headers and the compiler and bindgen versions recorded by the kernel are installed. Ubuntu normally also uses linux-lib-rust-$(uname -r); Debian kernels without packaged Rust metadata need linux-source-X.Y; Fedora uses kernel-devel; and openSUSE uses kernel-default-devel, kernel-devel, kernel-source, and kernel-syms. Package names can differ for custom kernels. The DKMS hook uses only installed packages and never downloads build inputs itself.

Installing the package builds the module for the running and newest installed kernels that already have headers. With no eligible header tree, it registers the source, prints a warning, and leaves the package configured so a later distribution DKMS hook can build it. Later kernel installations trigger a build automatically when their development inputs are present. If that build fails, the new kernel has no ZeroFS module. Debian and Ubuntu normally leave kernel package configuration incomplete when their DKMS hook fails. Fedora and openSUSE may finish installing the kernel despite the failed module build. Check dkms status before rebooting and keep the preceding kernel installed as a boot fallback while the incompatibility is fixed; zerofs mount remains available without the kernel module. The package does not install or hold the distribution kernel. Use the same ZeroFS release on the server.

When zerofs-kernel-client is configured, missing kernel-specific Rust metadata or exact distribution source produces a warning and leaves the source registered. Install the missing input, then run sudo dkms autoinstall. Kernels below the version floor are skipped; other compilation and module-install failures fail this package configuration step. For kernels installed later, whether the kernel transaction also fails is determined by the distribution hook as described above.

The build wrapper selects the appropriate path automatically:

• kernels with CONFIG_RUST=y and packaged Rust metadata use the normal external-module build;
• kernels with CONFIG_RUST=y but no packaged metadata regenerate it from the distribution kernel source;
• compatible x86-64 kernels with CONFIG_RUST=n use the self-contained build described below.

Manual source build

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)"
sudo modprobe zerofs

Verify the installation:

modinfo zerofs
grep zerofs /proc/filesystems

Secure Boot

DKMS signs locally built modules with its machine-local key when module signing is configured by the distribution. Check Secure Boot and the installed module:

mokutil --sb-state
modinfo -F signer zerofs

If Secure Boot rejects the module, follow the distribution's DKMS/MOK prompt to enroll that local key, then reboot and run sudo modprobe zerofs. The key and enrollment command are distribution-specific; the ZeroFS package neither ships a universal module key nor enrolls one automatically. Enrollment is not required when Secure Boot is disabled or the local DKMS key is already trusted. MOK enrollment requires UEFI boot through the distribution's shim and console access; other boot chains need their own key-enrollment procedure.

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 DKMS wrapper compiles the matching 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 path uses the configured headers tree for .config, generated headers, and Module.symvers, plus the separately packaged distribution kernel source and matching Rust, C, and LLVM tools. These must be installed through the package manager rather than downloaded by the DKMS hook. The self-contained path is narrower than the normal Rust build, currently supports x86-64 only, and 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.