Tor Hidden Services Load Balancing: OnionBalance

ID N0WHERE:83596
Type n0where
Reporter N0where
Modified 2016-05-25T15:46:54


Tor Hidden Services Load Balancing

The OnionBalance software allows for Tor hidden service requests to be distributed across multiple backend Tor instances. OnionBalance provides load-balancing while also making onion services more resilient and reliable by eliminating single points-of-failure. This tool is designed to allow requests to Tor onion service to be directed to multiple back-end Tor instances, thereby increasing availability and reliability. The design involves collating the set of introduction points created by one or more independent Tor onion service instances into a single ‘master’ onion service descriptor.

The master descriptor is signed by the onion service permanent key and published to the HSDir system as normal. Clients who wish to access the onion service would then retrieve the _ master _ service descriptor and try to connect to introduction points from the descriptor in a random order. If a client successfully establishes an introduction circuit, they can begin communicating with one of the onion services instances with the normal onion service protocol defined in rend-spec.txt


OnionBalance is under active development and new features are being added regularly:

  • Load balancing between up to 60 backend hidden services
  • Storage of the hidden service private key separate to th hidden service hosts


  • Instance – A load-balancing node running an individual onion service.
  • Introduction Point – A Tor relay chosen by an onion service instance as a medium-term _ meeting-place _ for initial client connections.
  • Master Descriptor – An onion service descriptor published with the desired onion address containing introduction points for each instance.
  • Management Server – Server running OnionBalance which collates introduction points and publishes a master descriptor.
  • Metadata Channel – A direct connection from an instance to a management server which can be used for instance descriptor upload and transfer of other data.

Management Server

is the machine running the OnionBalance daemon. It holds the master hidden service private key. This machine can be located geographically isolated from the machines hosting the hidden service content. It does not need to serve any content. OnionBalance requires that a recent version of Tor ( >= ) is installed on the management server system. This version might not be available in your operating system’s repositories yet.s.

The management server need to have its control port enabled to allow the OnionBalance daemon to talk to the Tor process. This can be done by uncommenting the ControlPort option in your torrc configuration file. Alternatively you can replace your torrc file with the following is suitable for the Tor instance running on the management server:

DataDirectory tor-data

ControlPort 9051
CookieAuthentication 1
SocksPort 0

RunAsDaemon 1

Backend Instance

Each backend instance should be run a standard onion service which serves your website or other content. More information about configuring onion services is available in the Tor Project’s hidden service configuration guide . If you have used the onionbalance-config tool you should transfer the generated instance config files and keys to the Tor configuration directory on the backend servers.

DataDirectory tor-data

# ControlPort 9051
# CookieAuthentication 1
SocksPort 0

RunAsDaemon 1

# Configure each onion service instance with a unique permanent key.
# HiddenServiceDir tor-data/hidden_service/
# HiddenServicePort 80


OnionBalance requires at least one system that is running the OnionBalance management server. The OnionBalance software does not need to be installed on the backend servers which provide the hidden service content (i.e. web site, IRC server etc.). OnionBalance is not yet packaged for most Linux and BSD. The tool can be installed from PyPI or directly from the Git repository:

# pip install onionbalance


$ git clone
$ cd onionbalance
# python install

If you are running Debian unstable or testing, you can install OnionBalance with the following command:

# apt-get install onionbalance

You can start the OnionBalance management server once all of your backend onion service instances are running. You will need to create a configuration file which list the backend hidden services and the location of your hidden service keys.

$ onionbalance -c config.yaml


$ sudo service onionbalance start

The management server must be left running to publish new descriptors for your onion service.

Tor Hidden Services Load Balancing: OnionBalance documentation

Tor Hidden Services Load Balancing: OnionBalance Download