NAME

       onionbalance - a Tor hidden service load balancer

DESCRIPTION

       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

       or

          $ sudo service onionbalance start

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

       NOTE:
          Multiple  OnionBalance  management  servers can be run simultaneously with the same master private key
          and configuration file to provide redundancy.

COMMAND-LINE OPTIONS

   onionbalance
       onionbalance distributes the requests for a Tor hidden services across multiple Tor instances.

       usage: onionbalance [-h] [-i IP] [-p PORT] [-c CONFIG] [-v VERBOSITY]
                           [--version]

       -h, --help
              show this help message and exit

       -i <ip>, --ip <ip>
              Tor controller IP address

       -p <port>, --port <port>
              Tor controller port

       -c <config>, --config <config>
              Config file location

       -v <verbosity>, --verbosity <verbosity>
              Minimum verbosity level for logging.  Available in ascending order: debug, info,  warning,  error,
              critical).  The default is info.

       --version
              show program's version number and exit

CONFIGURATION FILE FORMAT

       The OnionBalance management server is primarily configured using a YAML configuration file.

          # Onion Load Balancer Config File
          # ---
          # Each hidden service key line should be followed be followed by a list of 0
          # or more instances which contain the onion address of the load balancing
          # hidden service

          REFRESH_INTERVAL: 600 # How often to poll for updated descriptors
          services:
              - key: /path/to/private_key # 7s4hxwwifcslrus2.onion
                instances:
                  - address: o6ff73vmigi4oxka # web1
                  - address: nkz23ai6qesuwqhc # web2
              - key: /path/to/private_key.enc # dpkdeys3apjtqydk.onion
                instances:
                  - address: htbzowpp5cn7wj2u # irc1
                  - address: huey7aiod8dja8a3 # irc2

       The services section of the configuration file contains a list of master onion services that OnionBalance
       is responsible for.

       Each  key  option  specifies  the  location  of the 1024 bit private RSA key for the hidden service. This
       master private key determines the address that users will use to access your onion service. This  private
       key must be kept secure.

       The  location  of the private key is evaluated as an absolute path, or relative to the configuration file
       location.

       You can use existing Tor hidden service private key with OnionBalance to keep your onion address.

       Each backend Tor onion service instance is listed by it's unique onion address in the instances list.

       NOTE:
          You can replace backend instance keys if they get lost or compromised.  Simply  start  a  new  backend
          hidden service under a new key and replace the address in the config file.

       If  you  have  used  the  onionbalance-config  tool  you  can  simply  use the generated config file from
       master/config.yaml.

       NOTE:
          By default onionbalance will search for a config.yaml file in the current working directory.

   Configuration Options
       LOG_LOCATION
              The path where OnionBalance should write its log file.

       LOG_LEVEL
              Specify the minimum verbosity of log messages to output. All log messages equal or higher the  the
              specified  log  level are output. The available log levels are the same as the --verbosity command
              line option.

       REFRESH_INTERVAL
              How often to check for updated backend hidden service descriptors. This value can be increased  if
              your  backend  instance are under heavy loaded causing them to rotate introduction points quickly.
              (default: 600 seconds).

       PUBLISH_CHECK_INTERVAL
              How often should to check if new descriptors need to be published for the  master  hidden  service
              (default: 360 seconds).

       The following options typically do not need to be modified by the end user:

       REPLICAS
              How many set of HSDirs to upload too (default: 2).

       MAX_INTRO_POINTS
              How many introduction points to include in a descriptor (default: 10)

       DESCRIPTOR_VALIDITY_PERIOD
              How long a hidden service descriptor remains valid (default: 86400 seconds)

       DESCRIPTOR_OVERLAP_PERIOD
              How  long  to  overlap  hidden  service  descriptors  when  changing descriptor IDs (default: 3600
              seconds)

       DESCRIPTOR_UPLOAD_PERIOD
              How often to publish a descriptor, even when the introduction points don't change  (default:  3600
              seconds)

   Environment Variables
       ONIONBALANCE_CONFIG
              Override the location for the OnionBalance configuration file.

       The  loaded  configuration  file takes precedence over environment variables.  Configuration file options
       will override environment variable which have the same name.

       ONIONBALANCE_LOG_LOCATION
              See the config file option.

       ONIONBALANCE_LOG_LEVEL
              See the config file option

FILES

       /etc/onionbalance/config.yaml
              The configuration file, which contains services entries.

       config.yaml
              Fallback location for torrc, if /etc/onionbalance/config.yaml is not found.

SEE ALSO

       Full documentation for the OnionBalance software is available at https://onionbalance.readthedocs.org/

AUTHOR

       Donncha O'Cearbhaill <donncha@donncha.is>

0.1.3                                           February 02, 2016                                ONIONBALANCE(1)