.\" Man page generated from reStructuredText. . .TH "ONIONBALANCE" "1" "Sep 03, 2020" "0.2.0" "OnionBalance" .SH NAME onionbalance \- a Tor onion service load balancer . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SH ONIONBALANCE-CONFIG TOOL .SS Description .sp The \fBonionbalance\-config\fP tool is the fastest way to generate the necessary keys and config files to get your onion service up and running. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ onionbalance\-config .ft P .fi .UNINDENT .UNINDENT .sp When called without any arguments, the config generator will run in an interactive mode and prompt for user input. .sp The \fBmaster\fP directory should be stored on the management server while the other \fBinstance\fP directories should be transferred to the respective backend servers. .SS Files .INDENT 0.0 .TP .B master/config.yaml This is the configuration file that is used my the OnionBalance management server. .TP .B master/.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. .TP .B master/torrc\-server A sample Tor configuration file which can be used with the Tor instance running on the management server (v2\-only). .TP .B srv/torrc\-instance A sample Tor config file which contains the Tor \fBHiddenService*\fP options needed for your backend Tor instance (v2\-only). .TP .B srv//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). .UNINDENT .SS See Also .sp Full documentation for the \fBOnionBalance\fP software is available at \fI\%https://onionbalance.readthedocs.org/\fP .SH DESCRIPTION .sp You can start the OnionBalance management server once all of your backend onion service instances are running. .sp You will need to create a \fI\%configuration file\fP which list the backend onion services and the location of your hidden service keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ onionbalance \-c config.yaml .ft P .fi .UNINDENT .UNINDENT .sp or .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo service onionbalance start .ft P .fi .UNINDENT .UNINDENT .sp 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Multiple OnionBalance management servers can be run simultaneously with the same master private key and configuration file to provide redundancy. .UNINDENT .UNINDENT .SH CONFIGURATION FILE FORMAT .sp The OnionBalance management server is primarily configured using a YAML configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # 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 .ft P .fi .UNINDENT .UNINDENT .sp The \fBservices\fP section of the configuration file contains a list of master onion services that OnionBalance is responsible for. .sp Each \fBkey\fP 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 \fBmust\fP be kept secure. .sp The location of the private key is evaluated as an absolute path, or relative to the configuration file location. .sp You can use existing Tor onion service private key with OnionBalance to keep your onion address. .sp Each backend Tor onion service instance is listed by its unique onion address in the \fBinstances\fP list. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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 \fBaddress\fP in the config file. .UNINDENT .UNINDENT .sp If you have used the onionbalance\-config tool you can simply use the generated config file from \fBmaster/config.yaml\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default onionbalance will search for a \fBconfig.yaml\fP file in the current working directory. .UNINDENT .UNINDENT .SS Configuration Options .sp 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: .INDENT 0.0 .TP .B 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) .TP .B TOR_ADDRESS: The address where the Tor control port is listening. (default: 127.0.0.1) .TP .B TOR_PORT: The Tor control port. (default: 9051) .TP .B 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) .UNINDENT .sp Other options: .INDENT 0.0 .TP .B LOG_LOCATION The path where OnionBalance should write its log file. .TP .B 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. .TP .B 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). .TP .B PUBLISH_CHECK_INTERVAL How often should to check if new descriptors need to be published for the master onion service (default: 360 seconds). .TP .B 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). .TP .B 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) .TP .B 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) .UNINDENT .sp The following options typically do not need to be modified by the end user: .INDENT 0.0 .TP .B REPLICAS How many set of HSDirs to upload too (default: 2). .TP .B MAX_INTRO_POINTS How many introduction points to include in a descriptor (default: 10) .TP .B DESCRIPTOR_VALIDITY_PERIOD How long a onion service descriptor remains valid (default: 86400 seconds) .TP .B DESCRIPTOR_OVERLAP_PERIOD How long to overlap onion service descriptors when changing descriptor IDs (default: 3600 seconds) .TP .B DESCRIPTOR_UPLOAD_PERIOD How often to publish a descriptor, even when the introduction points don\(aqt change (default: 3600 seconds) .UNINDENT .SS Environment Variables .INDENT 0.0 .TP .B ONIONBALANCE_CONFIG Override the location for the OnionBalance configuration file. .UNINDENT .sp The loaded configuration file takes precedence over environment variables. Configuration file options will override environment variable which have the same name. .INDENT 0.0 .TP .B ONIONBALANCE_LOG_LOCATION See the config file option. .TP .B ONIONBALANCE_LOG_LEVEL See the config file option .TP .B ONIONBALANCE_STATUS_SOCKET_LOCATION See the config file option .TP .B ONIONBALANCE_TOR_CONTROL_SOCKET See the config file option .UNINDENT .SH FILES .INDENT 0.0 .TP .B /etc/onionbalance/config.yaml The configuration file, which contains \fBservices\fP entries. .TP .B config.yaml Fallback location for torrc, if /etc/onionbalance/config.yaml is not found. .UNINDENT .SH SEE ALSO .sp Full documentation for the \fBOnionBalance\fP software is available at \fI\%https://onionbalance.readthedocs.org/\fP .SH AUTHOR George Kadianakis, Donncha O'Cearbhaill .\" Generated by docutils manpage writer. .