VFS_AIO_RATELIMIT(8)

NAME
vfs_aio_ratelimit - Implement async-I/O rate-limiting for Samba with cluster-wide coordination

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.

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.

CONFIGURATION

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.

OPTIONS

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

CLUSTER BEHAVIOR

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.

    Note

    Nodes with more active connections will naturally use more of the total bandwidth. This ensures fair per-connection allocation across the cluster.

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.25.0rc1 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.