Architecture
This page describes how ZeroFS is structured: the protocol servers, the shared filesystem core, and the storage backend.
System Overview
The NFS, 9P, and NBD servers run in one userspace process and share a single filesystem layer. Data passes through encryption and caching, and SlateDB stores it in S3 as an LSM tree:
Choosing a Protocol
Because the servers share one filesystem layer, protocols mix on a single instance: NBD device files in .nbd/, for example, are created and resized with regular file operations through an NFS or 9P mount. Which protocol to mount with depends on the client and the workload:
| Mount | Client | Use case |
|---|---|---|
| NFS | NFS client that ships with macOS, Linux, and Windows | Mounting from any operating system without installing software |
| 9P | Linux kernel 9p module | fsync-dependent workloads (databases, transactional systems); closer POSIX adherence than NFS |
zerofs mount | FUSE client bundled in the zerofs binary; speaks 9P to the same server | Linux mounts without root; reconnects on its own after server restarts and network interruptions |
| NBD | nbd-client | Raw block devices for ext4, XFS, ZFS pools, and VM disks |
The fsync difference is the deciding factor for databases. NFS COMMIT semantics allow fsync to return before data reaches stable storage. Over 9P — kernel client or zerofs mount — fsync returns only after data is durable.
Filesystem Limits
The limits below are design constants of the on-disk format:
| Limit | Value | Where it comes from |
|---|---|---|
| Maximum file size | 16 EiB | File sizes are stored as 64-bit integers |
| Maximum filesystem size | 16 EiB | Byte counts are stored as 64-bit integers |
| Files over the filesystem's lifetime | 2^64 | Inode IDs are 64-bit and never reused |
| Hardlinks per file | 2^32 | Link counts are stored as 32-bit integers |
| Chunk size | 32 KiB | File data is split into 32 KiB chunks with 64-bit indexing |
In practice, S3 provider limits, performance with billions of objects, and storage cost take effect long before these values.
df reports the configured quota (max_size_gb) as the filesystem's total size; without a quota, the total is 16 EiB. The NFS server caps the sizes it reports at 8 EiB because some NFS clients cannot handle larger values, while the 9P server reports the full quota — so df can show different totals for the same filesystem depending on the mount protocol.