feat(mount): add max-write option and kernel readahead tuning

Add --max-write option to control FUSE write request size and improve
readahead configuration for better sequential read performance.

Changes:
- Add --max-write option (default 1 MiB) instead of hardcoded value
- Increase --max-read-ahead default from 128 KiB to 1 MiB
- Detect kernel max write limit (tunable on Linux 6.13+ via procfs)
- Cap MaxWrite and MaxReadAhead to kernel limits with user notification
- Tune kernel readahead via sysfs on Linux when running as root
- Enforce minimum 128 KiB readahead to prevent performance degradation
- Add platform-specific implementations (Linux sysfs, no-op for others)

The kernel sysfs tuning writes to /sys/class/bdi/<major>:<minor>/read_ahead_kb
to make --max-read-ahead actually effective, since FUSE only sets a ceiling
and the kernel default remains 128 KiB otherwise.

Signed-off-by: Anagh Kumar Baranwal <[email protected]>

Author: darthShadow

cmd/cmount/mount.go

@@ -99,6 +99,9 @@ func mountOptions(VFS *vfs.VFS, device string, mountpoint string, opt *mountlib.
 		options = append(options, "-o", option)
 	}
 	options = append(options, opt.ExtraFlags...)
+	// FIXME: Use mountlib.Opt.MaxWrite and mountlib.Opt.MaxReadAhead options
+	// instead of hardcoded values for consistency with mount2.
+	// Also consider adding sysfs kernel readahead tuning via TuneKernelReadAhead.
 	if runtime.GOOS == "linux" {
 		options = append(options, "-o", "big_writes")
 		options = append(options, "-o", fmt.Sprintf("max_write=%d", 1048576))

cmd/mount2/mount.go

@@ -5,6 +5,7 @@ package mount2
 
 import (
 	"fmt"
+	"os"
 	"runtime"
 	"time"
 
@@ -24,14 +25,39 @@ func init() {
 //
 // man mount.fuse for more info and note the -o flag for other options
 func mountOptions(fsys *FS, f fs.Fs, opt *mountlib.Options) (mountOpts *fuse.MountOptions) {
+	// Get the kernel's effective max write size (1 MiB on Linux <6.13, tunable on 6.13+)
+	kernelMaxWrite := mountlib.GetEffectiveMaxWrite()
+
+	// Cap MaxWrite to kernel limit
+	requestedMaxWrite := int(fsys.opt.MaxWrite)
+	effectiveMaxWrite := requestedMaxWrite
+	if effectiveMaxWrite > kernelMaxWrite {
+		effectiveMaxWrite = kernelMaxWrite
+		fs.Infof(f, "MaxWrite %d exceeds kernel limit %d, capping to kernel limit",
+			requestedMaxWrite, kernelMaxWrite)
+	}
+
+	// Apply minimum readahead enforcement (128 KiB) for consistency with kernel sysfs tuning
+	readAheadKiB := mountlib.EnforceMinReadAheadKiB(int(fsys.opt.MaxReadAhead / 1024))
+	readAheadBytes := readAheadKiB * 1024
+
+	// Cap MaxReadAhead to effective MaxWrite (larger values can't be used in single requests)
+	requestedReadAhead := readAheadBytes
+	effectiveReadAhead := readAheadBytes
+	if effectiveReadAhead > effectiveMaxWrite {
+		effectiveReadAhead = effectiveMaxWrite
+		fs.Infof(f, "MaxReadAhead %d exceeds effective MaxWrite %d, capping to MaxWrite",
+			requestedReadAhead, effectiveMaxWrite)
+	}
+
 	mountOpts = &fuse.MountOptions{
 		AllowOther:         fsys.opt.AllowOther,
 		FsName:             opt.DeviceName,
 		Name:               "rclone",
 		DisableXAttrs:      true,
 		Debug:              fsys.opt.DebugFUSE,
-		MaxReadAhead:       int(fsys.opt.MaxReadAhead),
-		MaxWrite:           1024 * 1024, // Linux v4.20+ caps requests at 1 MiB
+		MaxReadAhead:       effectiveReadAhead,
+		MaxWrite:           effectiveMaxWrite,
 		DisableReadDirPlus: true,
 		MaxStackDepth:      fsys.opt.MaxStackDepth,
 
@@ -136,7 +162,6 @@ func mountOptions(fsys *FS, f fs.Fs, opt *mountlib.Options) (mountOpts *fuse.Mou
 
 	}
 	var opts []string
-	// FIXME doesn't work opts = append(opts, fmt.Sprintf("max_readahead=%d", maxReadAhead))
 	if fsys.opt.AllowOther {
 		opts = append(opts, "allow_other")
 	}
@@ -263,5 +288,20 @@ func mount(VFS *vfs.VFS, mountpoint string, opt *mountlib.Options) (<-chan error
 	}
 
 	fs.Debugf(f, "Mount started")
+
+	// Log effective FUSE settings for debugging
+	fs.Debugf(f, "FUSE: MaxWrite=%d (kernel limit %d) MaxReadAhead=%d",
+		mountOpts.MaxWrite, mountlib.GetEffectiveMaxWrite(), mountOpts.MaxReadAhead)
+
+	// Tune kernel readahead to match FUSE setting (Linux only, requires root)
+	// This makes --max-read-ahead actually work by setting the sysfs value.
+	// Only attempt if running as root to avoid warning spam for non-root users.
+	// Use mountOpts.MaxReadAhead (already capped) to ensure FUSE and sysfs match exactly.
+	if mountOpts.MaxReadAhead > 0 && os.Getuid() == 0 {
+		if err := mountlib.TuneKernelReadAhead(mountpoint, mountOpts.MaxReadAhead/1024); err != nil {
+			fs.LogLevelPrintf(fs.LogLevelWarning, nil, "Failed to tune kernel readahead: %v", err)
+		}
+	}
+
 	return errs, umount, nil
 }

cmd/mountlib/mount.go

@@ -100,9 +100,21 @@ var OptionsInfo = fs.Options{{
 	Groups:  "Mount",
 }, {
 	Name:    "max_read_ahead",
-	Default: fs.SizeSuffix(128 * 1024),
-	Help:    "The number of bytes that can be prefetched for sequential reads (not supported on Windows)",
-	Groups:  "Mount",
+	Default: fs.SizeSuffix(1024 * 1024),
+	Help: "The number of bytes that can be prefetched for sequential reads. " +
+		"On Linux as root, this also sets the kernel readahead via sysfs. " +
+		"On other platforms or as non-root, only the FUSE ceiling is set " +
+		"and actual readahead may remain at the kernel default (128 KiB). " +
+		"Set to 0 to use FUSE default and leave kernel sysfs unchanged. " +
+		"(not supported on Windows)",
+	Groups: "Mount",
+}, {
+	Name:    "max_write",
+	Default: fs.SizeSuffix(1024 * 1024),
+	Help: "Maximum size of a FUSE write request. The FUSE library caps this at the kernel limit. " +
+		"Linux kernels 4.20+ support up to 1 MiB. Kernel 6.13+ allows tuning via " +
+		"/proc/sys/fs/fuse/max_pages_limit. (not supported on Windows)",
+	Groups: "Mount",
 }, {
 	Name:    "write_back_cache",
 	Default: false,
@@ -182,6 +194,7 @@ type Options struct {
 	Daemon             bool          `config:"daemon"`
 	DaemonWait         fs.Duration   `config:"daemon_wait"` // time to wait for ready mount from daemon, maximum on Linux or constant on macOS/BSD
 	MaxReadAhead       fs.SizeSuffix `config:"max_read_ahead"`
+	MaxWrite           fs.SizeSuffix `config:"max_write"`
 	ExtraOptions       []string      `config:"option"`
 	ExtraFlags         []string      `config:"fuse_flag"`
 	AttrTimeout        fs.Duration   `config:"attr_timeout"` // how long the kernel caches attribute for

cmd/mountlib/readahead_linux.go

@@ -0,0 +1,121 @@
+//go:build linux
+
+package mountlib
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/rclone/rclone/fs"
+	"golang.org/x/sys/unix"
+)
+
+const (
+	// Maximum time to wait for sysfs path to appear
+	sysfsTimeout = 1 * time.Second
+	// Polling interval when waiting for sysfs
+	sysfsPollInterval = 50 * time.Millisecond
+	// MinReadAheadKiB is the minimum readahead value (kernel default)
+	MinReadAheadKiB = 128
+	// DefaultMaxWrite is the kernel's default max FUSE write size (1 MiB).
+	// This has been the limit since Linux 4.20 (256 pages × 4 KiB).
+	// Kernel 6.13+ allows tuning via /proc/sys/fs/fuse/max_pages_limit.
+	DefaultMaxWrite = 1024 * 1024
+	// procMaxPagesLimit is the procfs path for the tunable max pages (kernel 6.13+)
+	procMaxPagesLimit = "/proc/sys/fs/fuse/max_pages_limit"
+)
+
+// EnforceMinReadAheadKiB returns sizeKiB with minimum enforcement applied.
+// Values below MinReadAheadKiB (128 KiB) are raised to MinReadAheadKiB
+// to avoid accidentally degrading performance. Zero and negative values
+// are normalized to zero (meaning "use default").
+func EnforceMinReadAheadKiB(sizeKiB int) int {
+	if sizeKiB <= 0 {
+		return 0
+	}
+	if sizeKiB < MinReadAheadKiB {
+		return MinReadAheadKiB
+	}
+	return sizeKiB
+}
+
+// TuneKernelReadAhead sets the kernel readahead for the FUSE mount.
+// This must be called after the mount is ready.
+// sizeKiB is the desired readahead in KiB. Values below 128 KiB are
+// raised to 128 KiB (the kernel default) to avoid degraded performance.
+// Returns error if tuning fails (caller may choose to log and continue).
+func TuneKernelReadAhead(mountpoint string, sizeKiB int) error {
+	sizeKiB = EnforceMinReadAheadKiB(sizeKiB)
+
+	var st syscall.Stat_t
+	if err := syscall.Stat(mountpoint, &st); err != nil {
+		return fmt.Errorf("stat mountpoint %q: %w", mountpoint, err)
+	}
+
+	major := unix.Major(st.Dev)
+	minor := unix.Minor(st.Dev)
+	sysfsPath := fmt.Sprintf("/sys/class/bdi/%d:%d/read_ahead_kb", major, minor)
+
+	// Poll for sysfs path to appear (may take a moment after mount)
+	deadline := time.Now().Add(sysfsTimeout)
+	for {
+		if _, err := os.Stat(sysfsPath); err == nil {
+			break // Path exists
+		}
+		if time.Now().After(deadline) {
+			return fmt.Errorf("sysfs path %q did not appear within %v", sysfsPath, sysfsTimeout)
+		}
+		time.Sleep(sysfsPollInterval)
+	}
+
+	// Write the value
+	if err := os.WriteFile(sysfsPath, []byte(strconv.Itoa(sizeKiB)), 0644); err != nil {
+		return fmt.Errorf("write to %q: %w", sysfsPath, err)
+	}
+
+	fs.LogLevelPrintf(fs.LogLevelNotice, nil, "Set kernel readahead to %d KiB for %q", sizeKiB, mountpoint)
+	return nil
+}
+
+// GetKernelReadAhead returns the current kernel readahead for the mountpoint in KiB.
+func GetKernelReadAhead(mountpoint string) (int, error) {
+	var st syscall.Stat_t
+	if err := syscall.Stat(mountpoint, &st); err != nil {
+		return 0, err
+	}
+
+	major := unix.Major(st.Dev)
+	minor := unix.Minor(st.Dev)
+	sysfsPath := fmt.Sprintf("/sys/class/bdi/%d:%d/read_ahead_kb", major, minor)
+
+	data, err := os.ReadFile(sysfsPath)
+	if err != nil {
+		return 0, err
+	}
+
+	return strconv.Atoi(strings.TrimSpace(string(data)))
+}
+
+// GetEffectiveMaxWrite returns the kernel's effective maximum FUSE write size.
+// On Linux 6.13+, this reads /proc/sys/fs/fuse/max_pages_limit and calculates
+// the limit as max_pages × page_size. On older kernels where the procfs tunable
+// doesn't exist, returns DefaultMaxWrite (1 MiB).
+func GetEffectiveMaxWrite() int {
+	data, err := os.ReadFile(procMaxPagesLimit)
+	if err != nil {
+		// Pre-6.13 kernel or procfs not mounted
+		return DefaultMaxWrite
+	}
+
+	maxPages, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	if err != nil || maxPages <= 0 {
+		return DefaultMaxWrite
+	}
+
+	pageSize := os.Getpagesize()
+	return maxPages * pageSize
+}

cmd/mountlib/readahead_linux_test.go

@@ -0,0 +1,82 @@
+//go:build linux
+
+package mountlib
+
+import (
+	"os"
+	"testing"
+)
+
+func TestGetKernelReadAhead(t *testing.T) {
+	// Test on a real mounted filesystem (root fs always exists)
+	val, err := GetKernelReadAhead("/")
+	if err != nil {
+		t.Skipf("Cannot read sysfs (may need root or sysfs not mounted): %v", err)
+	}
+	if val <= 0 {
+		t.Errorf("Expected positive readahead value, got %d", val)
+	}
+	t.Logf("Root filesystem readahead: %d KiB", val)
+}
+
+func TestTuneKernelReadAhead_PermissionDenied(t *testing.T) {
+	// Non-root users should get a permission error, not a crash
+	if os.Getuid() == 0 {
+		t.Skip("Test requires non-root user")
+	}
+
+	err := TuneKernelReadAhead("/", 1024)
+	if err == nil {
+		t.Error("Expected permission error for non-root user")
+	}
+	// Verify it's a sensible error, not a panic
+	t.Logf("Expected error: %v", err)
+}
+
+func TestEnforceMinReadAheadKiB(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    int
+		expected int
+	}{
+		{"zero passes through", 0, 0},
+		{"below minimum raised to 128", 64, 128},
+		{"well below minimum raised to 128", 1, 128},
+		{"exactly minimum unchanged", 128, 128},
+		{"above minimum unchanged", 256, 256},
+		{"large value unchanged", 1024, 1024},
+		{"negative normalized to zero", -1, 0},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := EnforceMinReadAheadKiB(tc.input)
+			if got != tc.expected {
+				t.Errorf("EnforceMinReadAheadKiB(%d) = %d, want %d", tc.input, got, tc.expected)
+			}
+		})
+	}
+}
+
+func TestGetEffectiveMaxWrite(t *testing.T) {
+	maxWrite := GetEffectiveMaxWrite()
+
+	// Should return a positive, reasonable value (at least 64 KiB, typical minimum)
+	minReasonable := 64 * 1024
+	if maxWrite < minReasonable {
+		t.Errorf("GetEffectiveMaxWrite() = %d, want >= %d", maxWrite, minReasonable)
+	}
+
+	// Should be page-aligned
+	pageSize := os.Getpagesize()
+	if maxWrite%pageSize != 0 {
+		t.Errorf("GetEffectiveMaxWrite() = %d, not page-aligned (page size %d)", maxWrite, pageSize)
+	}
+
+	// Log the result for visibility
+	if _, err := os.Stat(procMaxPagesLimit); err == nil {
+		t.Logf("Kernel 6.13+: max_pages_limit present, effective MaxWrite = %d bytes", maxWrite)
+	} else {
+		t.Logf("Kernel <6.13: using DefaultMaxWrite = %d bytes", maxWrite)
+	}
+}

cmd/mountlib/readahead_other.go

@@ -0,0 +1,43 @@
+//go:build !linux
+
+package mountlib
+
+import (
+	"errors"
+
+	"github.com/rclone/rclone/fs"
+)
+
+// MinReadAheadKiB is the minimum readahead value (kernel default).
+// On non-Linux platforms this is defined for API compatibility but not enforced.
+const MinReadAheadKiB = 128
+
+// DefaultMaxWrite is the kernel's default max FUSE write size (1 MiB).
+// On non-Linux platforms this is defined for API compatibility.
+const DefaultMaxWrite = 1024 * 1024
+
+// EnforceMinReadAheadKiB returns sizeKiB unchanged on non-Linux platforms.
+// Minimum enforcement only applies on Linux where kernel sysfs tuning is supported.
+func EnforceMinReadAheadKiB(sizeKiB int) int {
+	return sizeKiB
+}
+
+// TuneKernelReadAhead sets the kernel readahead for the FUSE mount.
+// On non-Linux platforms this is a no-op that returns nil.
+func TuneKernelReadAhead(mountpoint string, sizeKiB int) error {
+	fs.Debugf(nil, "readahead: kernel tuning not supported on this platform")
+	return nil // Not an error, just unsupported
+}
+
+// GetKernelReadAhead returns the current kernel readahead for the mountpoint in KiB.
+// On non-Linux platforms this returns an error.
+func GetKernelReadAhead(mountpoint string) (int, error) {
+	return 0, errors.New("not supported on this platform")
+}
+
+// GetEffectiveMaxWrite returns the kernel's effective maximum FUSE write size.
+// On non-Linux platforms this returns DefaultMaxWrite (1 MiB) as we cannot
+// detect kernel limits.
+func GetEffectiveMaxWrite() int {
+	return DefaultMaxWrite
+}