NAME

onionbalance-config - tool for generating onionbalance(1) config files and keys

SYNOPSIS

onionbalance-config [-h] [–hs-version {v3}] [–key KEY] [-p PASSWORD] [-n NUM_INSTANCES] [-s NUM_SERVICES] [-t TAG] [–output OUTPUT] [–no-interactive] [-v VERBOSITY] [–service-virtual-port SERVICE_VIRTUAL_PORT] [–service-target SERVICE_TARGET] [–version]

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.

FULL INVOCATION

onionbalance-config [-h] [--hs-version {v3}] [--key KEY] [-p PASSWORD]


                           [-n NUM_INSTANCES] [-s NUM_SERVICES] [-t TAG]


                           [--output OUTPUT] [--no-interactive] [-v VERBOSITY]


                           [--service-virtual-port SERVICE_VIRTUAL_PORT]


                           [--service-target SERVICE_TARGET] [--version]
onionbalance-config generates config files and keys for Onionbalance instances
and management servers. Calling without any options will initiate an
interactive mode.
options:


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


  --hs-version {v3}     Onion service version (only v3 is supported).


  --key KEY             RSA private key for the master onion service.


  -p, --password PASSWORD


                        Optional password which can be used to encrypt the


                        master service private key.


  -n NUM_INSTANCES      Number of instances to generate (default: 2).


  -s NUM_SERVICES       Number of services to generate (default: 1).


  -t, --tag TAG         Prefix name for the service instances (default: node).


  --output OUTPUT       Directory to store generate config files. The


                        directory will be created if it does not already exist


                        (default: config/).


  --no-interactive      Try to run automatically without prompting for user


                        input.


  -v VERBOSITY          Minimum verbosity level for logging. Available in


                        ascending order: debug, info, warning, error,


                        critical) (default: info).


  --service-virtual-port SERVICE_VIRTUAL_PORT


                        Onion service port for external client connections


                        (default: 80).


  --service-target SERVICE_TARGET


                        Target IP and port where your service is listening


                        (default: 127.0.0.1:80).


  --version             show program's version number and exit
    

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

CONFIGURATION FILE FORMAT

This is a sample configuration file that can be adapted:

# Onion Load Balancer Config File example
#
# Each Onion Service key line should be associated with a list of 0 or more
# instances which contain the onion address of the load balancing backend
# service.
services:
- instances: # web


  - address: wmilwokvqistssclrjdi5arzrctn6bznkwmosvfyobmyv2fc3idbpwyd.onion


    name: web1


  - address: fp32xzad7wlnpd4n7jltrb3w3xyj23ppgsnuzhhkzlhbt5337aw2joad.onion


    name: web2


  key: lsainlbvqg6obox2xkcmlv65rlctarxzuzod4juicfj6cstmoimkxyyd.key
- instances: # irc


  - address: drdoqmg4p43tbtoqxuxs2ax2vgfpetqtvgnpdugh5b2i7f7zxrzvy7id.key


    name: irc1


  - address: u6uoeftsysttxeheyxtgdxssnhutmoo2y2rw6igh5ez4hpxaz4dap7ad.onion


    name: irc2


  key: 6kjmifbfmd2232gpsu7am2psp2ydennc4zhq53zcwlirps5jmpnaikyd.key
    

FILES

onionbalance-config generates the following files:

config.yaml

This is the configuration file that is used by the Onionbalance management server.

ONION_ADDRESS.key

Each service instance have a private key, which will be derived into the public address and identity for the Onion Service. Each private key file is named after the .onion address, so ONION_ADDRESS.key will be actually like dpkhemrbs3oiv2fww5sxs6r2uybczwijzfn2ezy2osaj7iox7kl7nhad.key. It is essential that you keep this file secure.

By default, onionbalance-config writes these files in the config/ folder, relative to the folder where it was invoked from.

The actual folder can be explicitly set by invoking onionbalance-config with the --output flag.

To configure the system-wide service, onionbalance-config should set --output to /etc/onionbalance.

EXIT STATUS

onionbalance-config exits with a non-zero status in case of errors.

Exit status is 2 on command line invocation errors.

For other, general errors, the exit status is 1.

Otherwise, the exit status is 0.

AUTHOR

George Kadianakis, Donncha O’Cearbhaill, Silvio Rhatto <rhatto@torproject.org>

SEE ALSO

The docs/ folder distributed with Onionbalance contains the full documentation, which should also be available at <https://onionservices.torproject.org/apps/web/onionbalance/>.

The Onionbalance source code and all documentation may be downloaded from <https://gitlab.torproject.org/tpo/onion-services/onionbalance>.

AUTHORS

Silvio Rhatto rhatto@torproject.org.