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.

How and why this works — the page cache, the kernel↔daemon split, and the memory model — is 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.

No build toolchain (fleets / hardened hosts)

For pinned-kernel fleets that can’t compile on the box, install a precompiled module instead of DKMS (no compiler or kernel headers needed):

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

On Secure Boot hosts the kernel only loads signed modules, so the precompiled module’s signing key must be enrolled once with mokutil. (DKMS installs handle this automatically by signing with a per-host key and prompting you to enroll it.)