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:
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 (
>= 0.2.7.1-alpha ) 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
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 127.0.0.1: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 https://github.com/DonnchaC/onionbalance.git $ cd onionbalance # python setup.py 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.