Getting Started

OnionBalance implements round-robin like load balancing on top of Tor hidden services. A typical OnionBalance deployment will incorporate one management servers and multiple backend application servers.

Architecture

The management server runs the OnionBalance daemon and will regularly publish hidden service routing information to the Tor network.

The backend application servers / node runs their own standard Tor hidden service. Client access the public hidden service address are then routed to one of the backend application servers.

Management Server

is the machine running the OnionBalance daemon. It 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.

Backend Instance
Each backend application server will run a Tor hidden service. EXPLAIN

Note

The onionbalance-config tool can be used to quickly generate keys and config files for your OnionBalance deployment.

The OnionBalance tool provide two command line tools:

onionbalance acts as a long running daemon.

onionbalance-config is a helper utility which eases the process of creating keys and configuration files for onionbalance and the backend Tor instances.

Installing and Configuring Tor

Tor is need on the management server and every backend hidden service instance.

Management Server

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.

It is recommended that you install Tor from the Tor Project repositories to ensure you stay up to date with the latest Tor releases.

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

After configuring Tor you should restart your Tor process

$ sudo service tor reload

Backend Instances

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

After configuring Tor you should restart your Tor process

$ sudo service tor reload