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.