Tor Token Bucket Bandwidth Algorithm: Configuration and Behavior

A token bucket is a flow control algorithm where tokens accumulate at a fixed rate (BandwidthRate) up to a maximum bucket size (BandwidthBurst). Transmitting data consumes tokens - one token per byte. When the bucket is empty, transmission must wait until tokens accumulate. This allows bursting above the sustained rate (up to BandwidthBurst) as long as tokens are available, while the long-term average cannot exceed BandwidthRate. For Tor relays, this means a relay set to BandwidthRate 10MB BandwidthBurst 20MB can handle a 20 MBps burst for the duration the burst bucket can sustain it, but averages 10 MBps over time. The bucket fills at 10 MBps and is consumed at the burst rate during peaks.

BandwidthRate should be set to approximately 80-90% of the server's available sustained bandwidth capacity, accounting for other services (OS, management traffic) sharing the network interface. For a server with 1Gbps uplink where you want to dedicate 500Mbps to Tor, set BandwidthRate 500 MBits. BandwidthBurst should be set higher than BandwidthRate to allow handling traffic bursts efficiently - typically 1.5-2x the rate value. A server with a good uplink link and no other traffic can set BandwidthBurst equal to the full link capacity. In practice, Tor's actual throughput is determined by the Tor network's demand for your relay's bandwidth - many relays run below their configured limit because the network does not direct enough traffic to them.

Tor offers both BandwidthRate (applies to all Tor traffic including as a client) and RelayBandwidthRate (applies only to relayed traffic, not the local Tor client's own traffic). For dedicated relay servers, these can be set identically. For servers also running hidden services or being used as clients, RelayBandwidthRate allows capping relay contribution while preserving bandwidth for client and hidden service traffic. The Accounting options (AccountingMax, AccountingStart, AccountingRule) work with the same token bucket to enforce monthly bandwidth caps, essential for servers with capped hosting plans.

Tor logs bandwidth usage at regular intervals. NOTICE-level log entries show bandwidth-per-second read/write. The control port provides detailed bandwidth statistics through GETINFO bw-event and traffic statistics commands. Monitor whether the relay consistently runs near its BandwidthRate (saturation) or significantly below (under-utilized). A consistently saturated relay should have BandwidthRate increased if the uplink supports it. An under-utilized relay at the configured rate indicates the Tor network is not routing enough traffic to it - lower-bandwidth relays may experience this, especially before earning the stable and HSDir flags.

Tor's newer congestion control algorithm (KIST and later improvements) interacts with the token bucket. KIST (Kernel-Informed Socket Transport) integrates kernel TCP socket buffer states into Tor's scheduling decisions, allowing more accurate filling of the token bucket without creating queue buildup that causes head-of-line blocking. With KIST enabled (default in Tor 0.3.2+), the effective throughput available from the token bucket is more efficiently utilized compared to older scheduling. Ensure KISTSchedRunInterval in torrc is not set too low (which increases CPU overhead) or too high (which reduces scheduling responsiveness).