VFS_AIO_RATELIMIT(8) System Administration tools VFS_AIO_RATELIMIT(8) NAME vfs_aio_ratelimit - Implement async-I/O rate-limiting for Samba SYNOPSIS vfs objects = aio_ratelimit DESCRIPTION This VFS module is part of the samba(7) suite. The aio_ratelimit VFS module enables run-time rate-limiting on specific shares by enforcing upper limit on async I/O operations. An administrator may define this limit as operations per-second or bytes-per-second. When one of those limits is exceeded, a delay value (in microseconds) is calculated based on current I/O load and injected to async I/O operations, yielding an implicit throughput ceiling. A configurable burst allowance is supported via a burst multiplier, allowing short-term bursts above the steady-state rate while still enforcing a long-term ceiling. Rate-limiter state is periodically persisted to a local TDB, allowing limits to be enforced consistently across client reconnects and smbd restarts. This module operates only on asynchronous VFS READ/WRITE operation. This module is stackable. CONFIGURATION Straight forward use: [share] path = /path/to/share vfs objects = aio_ratelimit OPTIONS aio_ratelimit:read_iops_limit = count Upper limit of READ operations-per-second before injecting delays. Zero value implies no limit. Default: 0, Max: 1000000 Example: aio_ratelimit:read_iops_limit = 1000 aio_ratelimit:read_bw_limit = count Upper limit of READ bandwidth (bytes-per-second) before injecting delays. Zero value implies no limit. Supports size suffixes (K, M, G, T). Default: 0, Max: 1T Example: aio_ratelimit:read_bw_limit = 2M aio_ratelimit:read_burst_mult = value Burst multiplier for READ operations, expressed in tenths (e.g., 15 = 1.5x). Defines the token bucket capacity as a multiple of the rate limit, allowing short-term bursts above the steady-state rate. Default: 15 (1.5x), Max: 100 (10x) Example: aio_ratelimit:read_burst_mult = 20 aio_ratelimit:write_iops_limit = count Upper limit of WRITE operations-per-second before injecting delays. Zero value implies no limit. Default: 0, Max: 1000000 Example: aio_ratelimit:write_iops_limit = 1000 aio_ratelimit:write_bw_limit = count Upper limit of WRITE bandwidth (bytes-per-second) before injecting delays. Zero value implies no limit. Supports size suffixes (K, M, G, T). Default: 0, Max: 1T Example: aio_ratelimit:write_bw_limit = 1M aio_ratelimit:write_burst_mult = value Burst multiplier for WRITE operations, expressed in tenths (e.g., 15 = 1.5x). Defines the token bucket capacity as a multiple of the rate limit, allowing short-term bursts above the steady-state rate. Default: 15 (1.5x), Max: 100 (10x) Example: aio_ratelimit:write_burst_mult = 15 BURST BEHAVIOR The read_burst_mult and write_burst_mult parameters control the maximum burst capacity of the rate limiter relative to the configured rate limits. The effective burst capacity is calculated as: rate_limit * (burst_mult / 10). For example, with read_iops_limit = 1000 and read_burst_mult = 15, the burst capacity is 1000 * 1.5 = 1500 IOPS. This allows short-term I/O bursts above the steady-state rate while still enforcing the configured long-term limit. The appropriate burst multiplier depends on workload characteristics. Workloads with larger or more variable asynchronous I/O requests may require a higher burst value to avoid premature throttling, while smaller or latency-sensitive workloads may benefit from lower values. Note The read_burst_mult and write_burst_mult parameters do not change the long-term average throughput, which remains limited by read_iops_limit/read_bw_limit and write_iops_limit/write_bw_limit respectively. Higher burst values only affect initial acceleration and recovery from idle periods. VERSION This man page is part of version 4.24.0 of the Samba suite. AUTHOR The original Samba software and related utilities were created by Andrew Tridgell. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed. Samba 4.24.0 03/20/2026 VFS_AIO_RATELIMIT(8)