What Is the Onionbalance Tool in Tor?

Onionbalance is a specialized load-balancing and high-availability tool designed for Tor hidden services (onion services). This article explains what Onionbalance is, how it functions under the Tor network architecture, its core benefits for scalability and security, and the typical scenarios in which onion service operators deploy it.

The Purpose of Onionbalance

In a standard Tor setup, an onion service runs on a single backend server associated with a single Tor daemon instance. As traffic increases or during distributed denial-of-service (DDoS) events, that single server often becomes a bottleneck, causing connection timeouts and performance degradation.

Onionbalance solves this limitation by distributing incoming connection requests across multiple distinct backend instances while presenting a single, unified .onion address to users.

How Onionbalance Works

Onionbalance alters how onion service descriptors are published and managed across the Tor network:

1. Backend Instances: Multiple independent Tor instances (workers) run the actual service or application. Each backend generates its own set of introduction points.
2. Master Management: The Onionbalance management server collects the introduction point information from all configured backend instances.
3. Combined Descriptors: Onionbalance generates and signs a master descriptor that aggregates the introduction points of the backend instances. It then publishes this master descriptor to the Tor Distributed Hash Table (HSDir).
4. Client Connection: When a client requests the service via the master .onion address, Tor randomly selects one of the published introduction points. This routes the client to one of the backend instances, effectively spreading the load.

Key Benefits and Features

• Load Distribution: High-traffic services can scale horizontally by adding more backend servers to handle concurrent connections.
• Redundancy and High Availability: If one backend server goes offline or crashes, Onionbalance removes its introduction points in subsequent descriptor updates, ensuring the service remains accessible through the remaining operational backends.
• DDoS Mitigation: Spreading connections over multiple physical or virtual servers reduces the impact of targeted resource-exhaustion attacks.
• Enhanced Key Security: The master onion private key can be isolated on a dedicated, hardened management machine, while individual backend workers only hold their own temporary keys. If a single backend instance is compromised, the primary master address remains secure.
• Tor v3 Support: Modern versions of Onionbalance fully support Tor version 3 onion services, allowing up to hundreds of introduction points to be published concurrently.

Common Use Cases

Onionbalance is primarily deployed by high-traffic onion sites, large-scale media organizations providing secure whistleblowing platforms (such as SecureDrop instances), and public privacy-focused portals that require consistent uptime and capacity beyond what a single server can provide.