OnionBalance - Horizontal Scaling for Tor Hidden Services

OnionBalance v3 consists of a management node that holds the master descriptor key and multiple front nodes that serve actual client connections. The management node publishes a descriptor to the hidden service directory that references introduction points from all front nodes. Clients connect to any available introduction point, which routes them to the corresponding front node.

The management node does not handle any client traffic - it only manages descriptor publication. The front nodes run standard Tor hidden service configurations but publish their introduction points to the management node rather than directly to the directory. The management node aggregates these into a single combined descriptor published under the master onion address.

This architecture separates the key management function from the traffic handling function. If a front node is compromised, the attacker does not gain access to the master descriptor key. The management node can be more strictly firewalled than front nodes because it never handles client traffic directly.

Each front node is a standard Tor hidden service with one modification: it uses a slave key mode that allows OnionBalance to publish its introduction points under the master descriptor. Install tor on each front node and configure torrc:

HiddenServiceDir /var/lib/tor/front_service/
HiddenServicePort 80 127.0.0.1:8080
HiddenServiceVersion 3
HiddenServiceOnionbalanceInstance 1

The HiddenServiceOnionbalanceInstance 1 directive tells Tor that this is a front node for OnionBalance. It generates a separate key pair used for the front node identity but does not publish a descriptor on its own. The front node starts tor, generates its keys, and waits for the management node to retrieve and publish its introduction points.

Deploy multiple front nodes in different data centers and ideally different AS numbers for maximum resilience. Two front nodes in Romania and two in Iceland provides both geographic redundancy and AS-level diversity. If a data center outage takes down two nodes, the remaining two in the other location continue serving traffic without any user-visible disruption.

Install OnionBalance on the management node. The management node needs access to the master hidden service private key and the ability to connect to each front node's Tor control port. Install from PyPI: pip3 install onionbalance

Create the OnionBalance configuration file at /etc/onionbalance/config.yaml:

services:
  - key: /etc/onionbalance/master_key
    instances:
      - address: FRONT_NODE_1_ONION_ADDRESS
      - address: FRONT_NODE_2_ONION_ADDRESS
      - address: FRONT_NODE_3_ONION_ADDRESS
      - address: FRONT_NODE_4_ONION_ADDRESS

Run onionbalance with: onionbalance -c /etc/onionbalance/config.yaml -v. Monitor the output for successful descriptor retrievals from each front node and successful publication of the combined master descriptor. After the first successful publication, clients can reach all front nodes through the master onion address.

OnionBalance automatically removes front nodes from the descriptor when they become unreachable. The check interval is configurable but defaults to a few minutes. During the period between a node going down and the descriptor being updated, some clients may attempt to connect to an unreachable introduction point and fail before retrying with a working one.

Minimize this failover window by increasing the descriptor refresh frequency. More frequent refreshes mean faster detection of failed nodes and faster update of the published descriptor. The trade-off is additional load on the hidden service directory servers and more Tor circuit activity from the management node.

Monitor each front node's availability with external health checks. An independent monitoring service that verifies each front node's onion address responds correctly and alerts you when response time increases provides early warning before OnionBalance detects the failure. Addressing performance issues before they become complete failures improves user experience and reduces the frequency of failover events.