From a6532c2ce3f8fd1cf7d6ae3a6911008fbf6f0f0b Mon Sep 17 00:00:00 2001 From: Chris Lu Date: Tue, 28 Apr 2026 13:27:48 -0700 Subject: [PATCH] FUSE-Mount: document -fuse.maxBackground flag (#9258) --- FUSE-Mount.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/FUSE-Mount.md b/FUSE-Mount.md index af4c202..c7c910f 100644 --- a/FUSE-Mount.md +++ b/FUSE-Mount.md @@ -353,6 +353,35 @@ Notes: * `-cacheDirWrite` (if unset, falls back to `-cacheDir`, which defaults to `os.TempDir()`) is where the swap file lives. When upload stalls are possible it is strongly recommended to point this at a dedicated disk — not `/tmp` — and to set `-writeBufferSizeMB` below the available space on that disk. * The cap is a mount-global limit, not per-file. With many concurrently open writers it will serialize them rather than corrupt any of them. +### Tuning kernel FUSE concurrency (`-fuse.maxBackground`) + +The Linux kernel FUSE driver caps the number of asynchronous in-flight requests it will hand to a userspace filesystem at once. Two knobs control this, both exposed under `/sys/fs/fuse/connections//`: + +* `max_background` — hard cap on background (asynchronous) requests in flight. +* `congestion_threshold` — when in-flight requests reach this value, the kernel marks the bdi as congested, throttling new submissions. Derived as `3/4 * max_background`. + +Default `max_background` in `weed mount` is **128**, which is fine for most workloads. Heavy parallel-upload workloads (large `rclone`/`rsync` syncs, ML dataset ingest, many writer processes) can saturate that queue and become latency-bound on the FUSE channel itself rather than on volume servers. + +`-fuse.maxBackground=N` lets you raise the cap at mount time, so the value persists across reboots without a startup script that writes to `/sys/fs/fuse/connections//max_background`: + +```bash +weed mount \ + -filer=localhost:8888 -dir=/mnt/seaweedfs \ + -fuse.maxBackground=2048 +``` + +With the example above, the kernel sets `max_background=2048` and `congestion_threshold=1536` (3/4 of 2048) on the new FUSE connection — equivalent to: + +```bash +echo 2048 | sudo tee /sys/fs/fuse/connections//max_background +echo 1536 | sudo tee /sys/fs/fuse/connections//congestion_threshold +``` + +Notes: +* The flag only changes a kernel queue-depth limit; it does not allocate memory in `weed mount` itself. Pair with `-concurrentWriters`/`-concurrentReaders` if the userspace side is also the bottleneck. +* `congestion_threshold` is derived by the kernel-FUSE layer as `3/4 * max_background` and is not separately tunable from the command line. If you need a non-3/4 ratio, write `/sys/fs/fuse/connections//congestion_threshold` directly after mount. +* Raising this value is cheap; raising it without measuring is rarely useful. Confirm queue saturation (e.g. via FUSE-channel latency or stalled-writer symptoms) before tuning. + ### Weed Mount Performance Compared to any other distributed file systems, the `weed mount` performance should exceed most other solutions, or at least on par. This is because `weed mount` has multiple optimization techniques: