Kernel Mount (seaweed-vfs) — Deploy, Build & Upgrade

Operational reference for Kernel Mount: how to install, configure, run, build from source, and upgrade seaweed-vfs on a single host or a fleet. For the quickstart see Kernel Mount; for how it works under the hood see Kernel Mount internals.

Components

A working mount has two halves, shipped as separate packages:

• seaweedvfs kernel module (GPL-2.0) — owns the VFS (inodes, dentries, page cache) and does zero networking. It builds for your exact running kernel. Source: seaweedfs/seaweedvfs-kmod.
• sw-kd daemon — the userspace process that does all SeaweedFS networking (filer gRPC for metadata, volume HTTP for data) over the /dev/seaweedvfs character device. Ships as a prebuilt binary; architecture-specific but kernel-independent.

The module alone does not give you a mount — you always install both.

Packages

Each release on seaweedfs/artifactory publishes three packages, as both .deb and .rpm. Pick one module package plus the daemon:

Requirements

• Linux, kernel 6.1 or newer, x86_64 or arm64 (CI validates 6.1 LTS → 7.0).
• A reachable filer gRPC address — the filer’s HTTP port + 10000 (default 18888).
• One of apt, dnf, yum, zypper for the installer and packages.
• For DKMS or source builds only: make, gcc, and kernel headers (linux-headers-$(uname -r) on Debian/Ubuntu, kernel-devel on RHEL/SUSE).

Install

One-line installer (recommended)

Detects your package manager, architecture, and kernel; installs the module (via DKMS) and the daemon; and — when you pass FILER — configures and 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 resolves the newest vfs-* release automatically. Re-run the same command any time to upgrade in place.

Installer environment variables

Precompiled module (fleets / hardened hosts)

Pinned-kernel boxes that can’t compile install the precompiled .ko instead — 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

A precompiled package must exist for your exact kernel version. On signed-module hosts see Secure Boot.

Manual package install

To fetch the packages yourself from the releases page:

# Debian / Ubuntu — DKMS module + daemon
sudo apt install ./seaweedfs-vfs-dkms_<ver>_all.deb ./seaweedfs-vfs_<ver>_amd64.deb
# ...or a precompiled module instead of DKMS (no compiler/headers on the box):
sudo apt install --no-install-recommends \
  ./seaweedfs-vfs-kmod-$(uname -r)_<ver>_amd64.deb ./seaweedfs-vfs_<ver>_amd64.deb

# RHEL / Fedora  (on SUSE: zypper install)
sudo dnf install ./seaweedfs-vfs-dkms-<ver>-1.noarch.rpm ./seaweedfs-vfs-<ver>-1.x86_64.rpm

Deploy

The daemon is managed by systemd and reads a single config file.

Configure

/etc/seaweedfs-vfs/config is an environment file sourced by the service:

# Filer gRPC address (host:port) the daemon connects to.
FILER=filer.example.com:18888

# Optional extra sw-kd arguments, space-separated. Examples:
#   --io-uring          drive the kernel<->daemon channel with an io_uring ring
#   --distributed-locks honour flock/POSIX locks across clients via the filer
#                       (also load the module with distributed_locks=1)
EXTRA_ARGS=

The one-line installer writes FILER here for you when you pass it.

Start

sudo systemctl enable --now seaweed-vfs.service

The unit runs modprobe seaweedvfs first (creating /dev/seaweedvfs), then sw-kd --filer ${FILER}. Because the daemon is stateless (path-based protocol), it restarts on failure and re-attaches to live mounts transparently.

Mount

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

Or 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; sudo umount /mnt/seaweed to unmount. See Kernel Mount for more on the mount step.

Module parameters

• distributed_locks=1 — route advisory (flock/POSIX) locks through the filer’s lock service so they are honoured across mounts and clients (off by default). Set it in /etc/modprobe.d/seaweedvfs.conf and pair it with the daemon’s --distributed-locks in EXTRA_ARGS.

Build from source

The kernel module is GPL-2.0 and builds out-of-tree against your running kernel’s headers; source is at seaweedfs/seaweedvfs-kmod. (The sw-kd daemon ships as a prebuilt binary in the seaweedfs-vfs package — you don’t build it.)

make                                  # builds seaweedvfs.ko
sudo insmod seaweedvfs.ko             # udev then creates /dev/seaweedvfs
# ...run the daemon (or the systemd unit), then mount as above
sudo rmmod seaweedvfs                 # to unload

This needs make, gcc, and the kernel headers/build tree for your running kernel.

Register with DKMS

To have the module rebuild automatically across kernel upgrades:

sudo cp -r . /usr/src/seaweedfs-vfs-<version>/
sudo dkms add     -m seaweedfs-vfs -v <version>
sudo dkms build   -m seaweedfs-vfs -v <version>
sudo dkms install -m seaweedfs-vfs -v <version>

Upgrade

Re-run the installer — it detects an existing install and reloads only what changed:

curl -fsSL https://raw.githubusercontent.com/seaweedfs/artifactory/main/seaweed-vfs/install.sh | sudo bash

It stages the new packages first, then compares the loaded module’s srcversion to the new one to choose the least disruptive path:

• Only the daemon changed → restart sw-kd under the live mounts. In-flight requests get -ENOTCONN and the daemon re-attaches — a brief I/O pause, no unmount.
• The kernel module changed → a full reload is unavoidable (a loaded module can’t be swapped with users on it): unmount → rmmod → modprobe → remount, restarting the daemon around it.

Force the choice with SEAWEEDFS_VFS_UPGRADE=1 (always upgrade) or SEAWEEDFS_VFS_UPGRADE=0 (treat as a fresh install).

Kernel upgrades

• DKMS rebuilds the module automatically for the new kernel — nothing to do.
• Precompiled (SEAWEEDFS_VFS_KMOD=1) modules are tied to one exact kernel; install the matching seaweedfs-vfs-kmod-<new-kver> package (or re-run the installer with SEAWEEDFS_VFS_KMOD=1) for the new kernel before you boot into it.

Secure Boot

When Secure Boot is on, the kernel loads only signed modules, so modprobe fails with “Key was rejected by service” until the module’s signing key is enrolled:

• DKMS signs the module with a per-host MOK key and prompts you to enroll it (mokutil --import …, then reboot). The installer detects Secure Boot and reminds you.
• Precompiled / bare .ko — sign with the kernel’s sign-file (/lib/modules/$(uname -r)/build/scripts/sign-file) using a key you mokutil --import once across the fleet.

For Kubernetes and immutable hosts (Talos / Flatcar / Fedora CoreOS), see the module’s install notes.