Kernel Mount (seaweed-vfs)

seaweed-vfs is a Linux kernel filesystem client for SeaweedFS — a real mount -t seaweedvfs mount, not FUSE. A thin kernel module handles the filesystem while a userspace daemon (sw-kd) does the SeaweedFS networking.

Why use it over FUSE?

  • Faster cached access — reads and metadata are served by the kernel, not handed off to a userspace process on every call.
  • Won’t run out of memory at scale — the mount process stays small whether it exposes thousands of files or tens of millions, so it can’t OOM the way a FUSE client’s growing inode map can.
  • Drop-in — a real mount you manage with mount, /etc/fstab, and systemd; restart or upgrade the daemon without unmounting.

Performance

What makes it faster than a FUSE mount:

  • Cached reads and metadata never leave the kernel. FUSE bounces essentially every VFS call out to a userspace process; the kernel mount calls the daemon only on a cache miss or a write — repeat reads, stats, and directory listings come straight from the kernel’s page and dentry caches.
  • Kernel readahead and the page cache accelerate sequential and repeated reads, exactly like a local filesystem.
  • An optional io_uring fast path (ublk-style) keeps many requests in flight for high-concurrency workloads; the default read()/write() channel is the fallback.
  • Memory scales with available RAM, not file count. The kernel mount uses memory in proportion to what the OS can spare — reclaimable cache the kernel frees under pressure — instead of growing with the number of files in the cluster the way a FUSE client does.

Throughput and latency vary by workload and hardware — these are architectural properties, not a published benchmark. The page cache, the kernel↔daemon split, and the memory model are covered in depth in the Kernel Mount technical reference.

Requirements

  • Linux, kernel 6.1 or newer (x86_64 or arm64).
  • A reachable SeaweedFS filer gRPC address — the filer’s HTTP port + 10000 (default 18888), e.g. filer.example.com:18888.
  • One of apt, dnf, yum, or zypper.

Install

A single command installs the kernel module and the daemon, builds the module for your running kernel (via DKMS), and — when you pass a filer — starts the daemon ready to mount:

curl -fsSL https://raw.githubusercontent.com/seaweedfs/artifactory/main/seaweed-vfs/install.sh \
  | sudo FILER=filer.example.com:18888 bash

It auto-detects your package manager, architecture, and kernel. Re-run the same command any time to upgrade in place.

Mount

sudo mkdir -p /mnt/seaweed
sudo mount -t seaweedvfs filer.example.com:18888 /mnt/seaweed

Or mount automatically at boot via /etc/fstab:

none  /mnt/seaweed  seaweedvfs  filer=filer.example.com:18888,_netdev  0 0

Then read and write /mnt/seaweed like any local directory:

ls /mnt/seaweed
df -h /mnt/seaweed

Unmount with sudo umount /mnt/seaweed.

For pinned-kernel fleets with no compiler, Secure Boot signing, manual package install, building the module from source, and in-place upgrades, see Kernel Mount operations.