vfs_aio_ratelimit — Implement async-I/O rate-limiting for Samba with cluster-wide coordination
vfs objects = aio_ratelimit
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.
Cluster Support: When clustering is enabled in Samba, cluster-wide rate limiting is automatically enabled by default. Each share's configured rate limit applies to that share across the entire cluster. Limits for different shares are tracked and enforced independently of one another.
This module operates only on asynchronous VFS READ/WRITE operations.
This module is stackable.
Straight forward use:
[share]
path = /path/to/share
vfs objects = aio_ratelimit
Cluster deployment example (cluster-wide limits):
[global]clustering = yes[shared-storage]path = /mnt/shared vfs objects = aio_ratelimit aio_ratelimit:read_iops_limit = 10000 aio_ratelimit:write_bw_limit = 1G
The 10000 IOPS and 1G bandwidth limits apply to the entire cluster.
Cluster deployment with per-node limits:
[global]clustering = yes[shared-storage]path = /mnt/shared vfs objects = aio_ratelimit aio_ratelimit:read_iops_limit = 10000
Each node independently enforces the 10000 IOPS limit.
Upper limit of READ operations-per-second before injecting delays. Zero value implies no limit.
In cluster mode, this is the global limit enforced across all nodes. The limit is automatically distributed equally among all active smbd processes performing I/O on this share.
Default: 0, Max: 1000000
Example: aio_ratelimit:read_iops_limit = 1000
Upper limit of READ bandwidth (bytes-per-second) before injecting delays. Zero value implies no limit. Supports size suffixes (K, M, G, T).
In cluster mode, this is the global limit enforced across all nodes. The limit is automatically distributed equally among all active smbd processes performing I/O on this share.
Default: 0, Max: 1T
Example: aio_ratelimit:read_bw_limit = 2M
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
Upper limit of WRITE operations-per-second before injecting delays. Zero value implies no limit.
In cluster mode, this is the global limit enforced across all nodes. The limit is automatically distributed equally among all active smbd processes performing I/O on this share.
Default: 0, Max: 1000000
Example: aio_ratelimit:write_iops_limit = 1000
Upper limit of WRITE bandwidth (bytes-per-second) before injecting delays. Zero value implies no limit. Supports size suffixes (K, M, G, T).
In cluster mode, this is the global limit enforced across all nodes. The limit is automatically distributed equally among all active smbd processes performing I/O on this share.
Default: 0, Max: 1T
Example: aio_ratelimit:write_bw_limit = 1M
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
When Samba clustering is enabled, cluster-wide rate limiting is
automatically enabled by default. The configured limits apply to the
entire cluster, not individual nodes. This requires
the ratelimitd daemon, which must be enabled at build
time with --with-ratelimitd.
[share]
aio_ratelimit:read_iops_limit = 1000
With cluster mode enabled (default when clustering is active), the module automatically distributes bandwidth among active connections on that share. For example, with a 1000 IOPS limit:
4 active connections → Each gets ~250 IOPS
10 active connections → Each gets ~100 IOPS
Total cluster throughput: Always limited to 1000 IOPS
The distribution happens automatically as connections are established and closed.
Nodes with more active connections will naturally use more of the total bandwidth. This ensures fair per-connection allocation across the cluster.
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.
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.