DOCSEARCHbyAlgolia
Submit Docs

ZeroFS Documentation

website·Indexed 32 days ago

https://www.zerofs.net/docs

A log-structured filesystem that exposes S3-compatible, Azure Blob Storage, or Google Cloud Storage as POSIX filesystems over NFS and 9P, or as raw block devices via NBD. Features include a Kubernetes CSI driver, high availability, read replicas, and a native Linux kernel client. It provides a web UI with a file manager and live dashboard, and supports encryption using XChaCha20-Poly1305.

Tokens
34.6K
Snippets
123
Records
234
Agent score
67%

What's inside ZeroFS

  1. Overview of ZeroFS storage capabilities

    ZeroFS serves S3-compatible buckets (including Amazon S3, Google Cloud Storage, Azure Blob, and local disks) as POSIX filesystems or raw block devices. It uses a log-structured approach where writes are sent as immutable segments that are compressed and encrypted before upload. It supports one writer with multiple read-only replicas against the same bucket.

  2. Overview of the ZeroFS native Linux kernel client

    ZeroFS provides a native out-of-tree Linux filesystem module written primarily in Rust. It registers zerofs with the Virtual File System (VFS), utilizes netfslib for data movement, and communicates using the private 9P2000.L.Z dialect over TCP or Unix sockets. Unlike the userspace client (zerofs mount), the kernel module eliminates the /dev/fuse round-trip, reducing latency for chatty network filesystem operations.

  3. Overview of ZeroFS storage and access methods

    ZeroFS exposes S3-compatible, Azure Blob Storage, or Google Cloud Storage as filesystem mounts and NBD block devices. It stores all filesystem data and metadata in the configured object store, using local disks only for caching. It supports several access methods:

    • Native Kernel Client: The fastest mount option for supported Linux kernels (DKMS-managed).
    • FUSE Client: Bundled client that works across a wider range of systems and mounts without root.
    • NFSv3: Compatible with stock NFS clients on macOS, Linux, and Windows.
    • 9P: Compatible with stock Linux v9fs.
    • Client Libraries: Path-based filesystem operations for Python, TypeScript, and Go (no mount required).
    • NBD Block Devices: Files under .nbd can be attached as Linux block devices for volume managers, VM disks, or filesystems.
    • Kubernetes CSI Driver: Dynamically provisioned persistent volumes backed by a shared ZeroFS gateway via 9P.

  4. Overview of the ZeroFS Native Kernel Client

    The native client is an out-of-tree Linux module (zerofs.ko) that registers the zerofs filesystem with the Virtual File System (VFS) and communicates using the 9P2000.L.Z protocol over TCP or Unix sockets. It is the highest-performance mount path for ZeroFS, avoiding the /dev/fuse handoff and reducing client-side overhead. It supports advanced features including fallocate, SEEK_DATA, SEEK_HOLE, POSIX record locks, flock, and durable fsync.

  5. Overview of ZeroFS Client Libraries

    ZeroFS provides official client libraries for Python, TypeScript/Node, and Go. These libraries allow applications to perform path-based filesystem operations (read, write, stat, readdir, open) by speaking the 9P2000.L.Z dialect directly to the server, eliminating the need for a kernel mount. All libraries wrap a shared Rust core (zerofs-client), ensuring consistent behavior regarding connection targets, fast-path extensions, and reconnect/cancellation semantics. They use a trusted-network model where the client asserts its UID at connection time.

  6. Overview of ZeroFS Kubernetes CSI Driver

    The zerofs-csi driver exposes a ZeroFS filesystem to Kubernetes as dynamically provisioned persistent volumes. It registers as csi.zerofs.net. Each volume is implemented as a directory on a ZeroFS filesystem backed by a leader/standby gateway pair. Pods mount these directories over 9P. The driver supports mount volumes only (no block mode).

  7. Understand ZeroFS write atomicity and durability

    ZeroFS ensures that every filesystem mutation is visible atomically via a single database transaction. A transaction includes extent pointers, segment accounting, inode metadata, directory changes, and global statistics.

    Outcomes of a mutation:

    • Failure before commit: No part of the mutation is visible.
    • Commit with uncertain outcome: Either the complete mutation is visible or it is entirely absent; partial transactions are never exposed.
    • Crash before durability barrier: A previously visible mutation may be absent after restart, but only as part of an atomic unflushed suffix.
    • Crash after durability barrier: The complete mutation is guaranteed to be present after restart.

  8. Understand ZeroFS Key Architecture

    ZeroFS uses a two-tier key hierarchy to protect data:

    1. Data Encryption Key (DEK): A 256-bit key used to encrypt data. It is not used directly; instead, two subkeys are derived from it via HKDF-SHA256: one for file-data frames (zerofs-v1-segment) and one for metadata SST blocks (zerofs-v1-encryption).
    2. Key Encryption Key (KEK): Derived from the user's password using Argon2id. The KEK is used to wrap (encrypt) the DEK.

    The wrapped DEK is stored as a bincode-serialized object named zerofs.key at the database path on the object store. This object contains the Argon2id salt, a 24-byte nonce, a version field, and the wrapped DEK.

  9. ZeroFS Storage Engine Overview

    ZeroFS uses a hybrid storage model where file data is stored in immutable segment objects and metadata is managed via an LSM tree on the same object store.

    • Extents: File data is split into 32 KiB extents. Each extent is compressed and encrypted into a 'frame'.
    • Segments: Frames are packed into immutable segment objects. These are written once and only removed during reclamation.
    • Metadata LSM Tree: Stores inodes, directory entries, tombstones, stats, and a 32-byte FrameLoc (pointer) per extent, as well as live-byte counters per segment.
    • Segment Key Structure: Keys follow the pattern segments/{shard}/{epoch}/{counter}. The shard (low byte of the counter) prevents object-store hot-prefix throttling by round-robining across 256 prefixes.

  10. Understand ZeroFS licensing options

    ZeroFS is dual-licensed under the GNU AGPL v3 and a commercial license. The GNU AGPL v3 is intended for developers building open-source applications and is fully featured. Organizations that require different terms, such as exemption from AGPL obligations, priority support, SLAs, or deployment assistance, should obtain a commercial license by contacting [email protected].

  11. Understand ZeroFS cache layers

    ZeroFS utilizes two distinct caches, each consisting of a memory tier and a disk tier:

    1. Raw-parts cache: Stores 128 KiB parts of object bytes (file data and metadata SST objects) exactly as they exist in the object store (compressed and encrypted). This is the only cache that holds file data. Disk data is stored in parts_cache/.
    2. Decoded-block cache: Stores metadata blocks (inode and directory entries plus 32-byte extent pointers) after they have been decrypted and decompressed. Disk data is stored in hybrid_cache/.

    Both disk tiers are located within a per-volume directory inside the configured cache.dir.

  12. ZeroFS System Architecture Overview

    ZeroFS implements a filesystem core that supports NFS, 9P, and NBD servers within a single userspace process. The architecture separates storage into two distinct planes: a Metadata Plane and a Data Plane. Both planes utilize a shared raw-parts cache (memory and disk) for object bytes. Metadata is managed via an LSM tree on the object store, while file data is stored as immutable segment objects.