vfs_aio_ratelimit 8 Samba System Administration tools &doc.version; 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: /path/to/share aio_ratelimit Cluster deployment example (cluster-wide limits): yes /mnt/shared aio_ratelimit 10000 1G The 10000 IOPS and 1G bandwidth limits apply to the entire cluster. Cluster deployment with per-node limits: yes /mnt/shared aio_ratelimit 10000 Each node independently enforces the 10000 IOPS limit. aio_ratelimit:read_iops_limit = count 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 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). 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 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. 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 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). 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 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 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. 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. This man page is part of version &doc.version; of the Samba suite. 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.