ONIONBALANCE-CONFIG(1)

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