9P File Access

ZeroFS serves standard 9P2000.L to stock Linux v9fs and the private 9P2000.L.Z dialect to ZeroFS clients. On a supported kernel, the native kernel client is the fastest mount path. The bundled zerofs mount command is the fallback when the native module is unavailable or cannot be loaded.

Over 9P, fsync returns after ZeroFS has flushed the data to stable storage. NFS COMMIT does not provide the same guarantee. Use a 9P client for workloads whose durability depends on fsync.

The 9P server does not authenticate clients or encrypt traffic. It trusts the numeric identity supplied by the client. Keep TCP listeners on loopback or a controlled network, and use an authenticated tunnel or VPN across untrusted networks.

Configure the Server

Enable a TCP listener, a Unix socket, or both:

[servers.ninep]
addresses = ["127.0.0.1:5564"]
unix_socket = "/tmp/zerofs.9p.sock"

zerofs init includes both local endpoints. Omit addresses when only the Unix socket is needed. Start the server after editing the configuration:

zerofs run --config zerofs.toml

Choose a Client

Client	Protocol	Installation	Connection loss
Native kernel client	`9P2000.L.Z`	Signed exact-kernel module managed by DKMS	Reconnects within its configured grace period
`zerofs mount`	`9P2000.L.Z` over FUSE	Included in the Linux `zerofs` binary	Reconnects and restores supported session state
Stock Linux v9fs	`9P2000.L`	Linux 9P modules	Does not restore a session; remount after disconnect

The private dialect adds reconnect support and compound metadata operations. Stock v9fs remains useful when installing a ZeroFS-specific client is not an option.

Native Kernel Client

Install the generic zerofs-kernel-client package as described in Native kernel client. Once DKMS has installed the module for the running kernel and it is loaded:

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

The kernel-client guide covers Unix sockets, HA endpoint pairs, cache modes, Secure Boot, and source builds.

Bundled FUSE Client

zerofs mount is available in Linux builds. It mounts through FUSE as the current user, so the mount point must be writable by that user.

mkdir -p "$HOME/mnt/zerofs"
zerofs mount 127.0.0.1:5564 "$HOME/mnt/zerofs"

A target can be host, host:port, tcp://host:port, unix:/path, or a bare path beginning with / or .. A bare hostname uses port 5564. For high availability, pass both nodes as a comma-separated target set.

The command stays in the foreground. Press Ctrl+C to unmount, or unmount it from another terminal with fusermount3 -u and the mount point.

Mount Options

Option	Behavior
`--read-only`	Mounts the filesystem read-only.
`--access owner\|root\|all`	Controls which local users can enter the FUSE mount; the default is `owner`. `root` and `all` require `user_allow_other` in `/etc/fuse.conf` unless the command runs as root.
`--aname <path>`	Roots the mount at an existing server-side directory instead of the filesystem root.
`--relaxed-consistency false`	Disables the attribute, data, symlink, and prefetch caches so reads and lookups reach the server. It also forces write-through.
`--writeback false`	Disables the FUSE writeback cache without disabling the other relaxed-consistency caches.
`--msize <bytes>`	Requests a 9P message size. The default and server maximum are 10 MiB.

Reconnection

zerofs mount reconnects with backoff after the server or network disappears. It rebinds linked open files by inode ID and reacquires recorded byte-range locks before resuming operations. An open file whose final link was removed cannot be rebound and becomes stale.

Retries of reorder-sensitive mutations retain their operation ID. Automatic retries stop at the 120-second protocol horizon; an unresolved mutation is reported as an ambiguous connection failure. If a stale handle held a byte-range lock, the client stops the session because it can no longer preserve that lock guarantee.

Stock Linux v9fs

Load the stock kernel modules if they are not already available:

sudo modprobe 9p
sudo modprobe 9pnet_fd

Mount the standard dialect over TCP or a local Unix socket:

sudo mkdir -p /mnt/zerofs
sudo mount -t 9p \
  -o trans=tcp,port=5564,version=9p2000.L,access=user \
  127.0.0.1 /mnt/zerofs

Stock v9fs does not negotiate the ZeroFS extensions and does not rebuild its session after a server restart or network interruption. Unmount and mount it again after the endpoint is reachable.

For a persistent TCP mount, add an _netdev entry to /etc/fstab:

127.0.0.1 /mnt/zerofs 9p trans=tcp,port=5564,version=9p2000.L,access=user,_netdev 0 0

Client Caching

The v9fs cache option controls client-side caching and cross-client visibility:

Mode	Behavior
`none`	Minimizes client caching.
`mmap`	Enables page-cache support for memory-mapped files.
`loose`	Retains data and metadata more aggressively, allowing stale observations across clients.
`fscache`	Uses the kernel FS-Cache subsystem when it is configured.

Select a mode for the workload's coherence and mmap requirements, then measure it. msize requests the maximum message size; ZeroFS accepts up to 10 MiB.

Identity and Locking

All 9P clients send numeric identities to a server that trusts them. Keep UID and GID assignments consistent between machines. zerofs mount sends the caller's UID and primary GID. Stock 9P2000.L carries one numeric UID; ZeroFS uses that value as both UID and GID.

ZeroFS supports advisory POSIX byte-range locks from the native client, zerofs mount, and stock v9fs. Locks live in server memory and disappear when the server restarts or an HA takeover begins. ZeroFS clients attempt to reacquire recorded locks during reconnect, but another session can acquire a lock during the gap. These locks are not a distributed fencing mechanism.

Limitations

ZeroFS does not support extended attributes or POSIX ACLs over 9P.
Stock v9fs has no ZeroFS reconnect or compound-operation extensions and cannot send supplementary groups.
zerofs mount sends the caller's primary GID but not supplementary groups.
zerofs mount supports plain allocation, hole punching, and zero range through fallocate. Other allocation modes return EOPNOTSUPP.
copy_file_range, SEEK_DATA/SEEK_HOLE, ioctl, and poll are not implemented by zerofs mount; the kernel may fall back where it has an alternative.
rename works, but RENAME_NOREPLACE, RENAME_EXCHANGE, and RENAME_WHITEOUT are not supported by the 9P operation used by zerofs mount.

Native kernel client

Compare with NFS