Tor Relay Overload Detection and Response Guide

Tor 0.4.6+ reports overload conditions in its relay descriptor and in logs. The overload-general field in the descriptor indicates: CPU saturation (Tor's scheduler is unable to keep up with circuit work), memory saturation (Tor's memory usage is approaching system memory limits), and connection saturation (file descriptor limit reached). Monitor overload status: grep 'Overload' /var/log/tor/notices.log or check the relay's descriptor on Tor Metrics. When an overload is reported, Tor Metrics displays it in the relay details page under 'Relay flags and conditions'. Overload conditions hurt the Tor network: directory authorities factor overload status into bandwidth measurements, effectively reducing the relay's consensus weight and circuit selection frequency. A relay that reports persistent overload will eventually have reduced impact on the network.

CPU overload occurs when Tor cannot process circuit work fast enough. Indicators: Tor log shows 'Scheduler overload: n cells have piled up' or 'We're experiencing a CPU overload' messages. System-level: CPU usage near 100% for sustained periods (check with top or vmstat). Response: (1) verify AES-NI is available and used - grep aes /proc/cpuinfo should show the aes flag, (2) upgrade to a VPS with more CPU cores or faster per-core performance - Tor can use multiple cores for cryptographic operations, (3) reduce BandwidthRate to limit throughput to what the CPU can handle without overload, (4) check for other CPU-consuming processes competing with Tor - isolate Tor to its own server if possible.

Memory overload occurs when Tor's memory usage approaches the system limit. Tor maintains in-memory buffers for active circuits - high circuit count or high per-circuit traffic can exhaust memory. Indicators: Tor log shows 'We are low on memory. Tor will try to reduce its memory use now.' System level: free -m shows low available memory, system logs show OOM (out-of-memory) killer activity. Response: (1) increase MaxMemInQueues in torrc to explicitly limit Tor's memory use (default is 8GB or RAM/8, whichever is lower), (2) upgrade to a VPS with more RAM - 1-2GB RAM minimum for busy relays, 4-8GB for high-traffic relays, (3) reduce circuit limits via MaxOnionQueueDelay (drops circuits whose queued cells are too old), (4) disable OOM kill: DisableOOMKill 1 - Tor handles memory management gracefully itself.

Tor uses Linux file descriptors for each network connection. High-traffic relays can exhaust the default file descriptor limit. Indicators: Tor log shows 'Couldn't open a socket: Too many open files' or 'Unable to launch a new connection to relay'. Response: increase the file descriptor limit for the Tor process. In /etc/systemd/system/tor.service.d/override.conf: [Service] LimitNOFILE=65536. Or set in /etc/security/limits.conf: debian-tor hard nofile 65536. Verify the limit is applied: check /proc/$(pgrep tor)/limits and look for Max open files. Also configure the system-wide socket limit: sysctl -w net.core.somaxconn=4096 and fs.file-max=200000. High-bandwidth relays routinely need 10,000-50,000 open file descriptors.

Bandwidth saturation occurs when relay traffic exceeds the VPS's network interface capacity. Indicators: packet loss visible in ip -s link show, Tor log shows 'We have used almost all of our bandwidth' (when BandwidthRate is configured below actual capacity). Response: (1) if actual network interface is saturated, upgrade to a higher-bandwidth VPS plan or add a second network interface, (2) configure BandwidthRate and BandwidthBurst to cap below 80% of actual interface capacity to prevent saturation-related packet loss, (3) use tc (traffic control) to set kernel-level bandwidth limits with burst tolerance: tc qdisc add dev eth0 root tbf rate 500mbit burst 32kbit latency 400ms. Monitor actual throughput: vnstat -l -i eth0 for real-time interface statistics. Traffic that exceeds the configured BandwidthRate is queued by Tor, increasing memory usage - ensure BandwidthRate is below available capacity to avoid cascading CPU/memory overload from bufferbloat.