Provided by: onionbalance_0.2.2-1.1_all bug

NAME

       onionbalance - a Tor onion service load balancer

ONIONBALANCE-CONFIG TOOL

   Description
       The  onionbalance-config tool is the fastest way to generate the necessary keys and config
       files to get your onion service up and running.

          $ onionbalance-config

       When called without any arguments, the config generator will run in  an  interactive  mode
       and prompt for user input.

       The  master  directory  should be stored on the management server while the other instance
       directories should be transferred to the respective backend servers.

   Files
       master/config.yaml
              This is the configuration file that is used my the Onionbalance management server.

       master/<ONION_ADDRESS>.key
              The private key which will become the public address and identity  for  your  onion
              service. It is essential that you keep this key secure.

       master/torrc-server
              A  sample Tor configuration file which can be used with the Tor instance running on
              the management server (v2-only).

       srv/torrc-instance
              A sample Tor config file which contains the Tor HiddenService* options  needed  for
              your backend Tor instance (v2-only).

       srv/<ONION_ADDRESS>/private_key
              Directory containing the private key for your backend onion service instance.  This
              key is less critical as it can be rotated if lost or compromised (v2-only).

   See Also
       Full    documentation    for    the    Onionbalance    software    is     available     at
       https://onionbalance.readthedocs.org/

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 onion 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: in about 10 minutes you should have a fully functional onionbalance setup.

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

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 onion
       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 onion service private key with Onionbalance to  keep  your  onion
       address.

       Each  backend  Tor  onion  service  instance  is listed by its 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 onion 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
       The  Onionbalance  command  line  options  can  also  be  specified  in  the  Onionbalance
       configuration file. Options specified on the command line take precedence over the related
       configuration file options:

       TOR_CONTROL_SOCKET:
              The  location  of  the Tor unix domain control socket. Onionbalance will attempt to
              connect to this control socket first before falling back to using  a  control  port
              connection.  (default: /var/run/tor/control)

       TOR_ADDRESS:
              The address where the Tor control port is listening. (default: 127.0.0.1)

       TOR_PORT:
              The Tor control port. (default: 9051)

       TOR_CONTROL_PASSWORD:
              The  password  for  authenticating  to  a  Tor  control  port  which  is  using the
              HashedControlPassword authentication method.  This  is  not  needed  when  the  Tor
              control port is using the more common CookieAuthentication method.  (default: None)

       Other 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 onion service descriptors. This value can be
              decreased 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
              onion service (default: 360 seconds).

       INITIAL_DELAY
              How  long  to  wait  between  starting  Onionbalance  and  publishing  the   master
              descriptor.  If you have more than 20 backend instances you may need to wait longer
              for all instance descriptors to download before starting (default: 45 seconds).

       DISTINCT_DESCRIPTORS
              Distinct descriptors are used if you have more than 10 backend instances.   At  the
              cost  of  scalability,  this  can  be disabled to appear more like a standard onion
              service. (default: True)

       STATUS_SOCKET_LOCATION
              The Onionbalance service creates a Unix  domain  socket  which  provides  real-time
              information about the currently loaded service and descriptors.  This option can be
              used   to   change   the   location   of    this    domain    socket.     (default:
              /var/run/onionbalance/control)

       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 onion service descriptor remains valid (default: 86400 seconds)

       DESCRIPTOR_OVERLAP_PERIOD
              How  long  to  overlap  onion  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

       ONIONBALANCE_STATUS_SOCKET_LOCATION
              See the config file option

       ONIONBALANCE_TOR_CONTROL_SOCKET
              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

       George Kadianakis, Donncha O'Cearbhaill <asn@torproject.org>