1ONIONBALANCE(1) OnionBalance ONIONBALANCE(1)
2
6 onionbalance - a Tor hidden service load balancer
7
9 You can start the OnionBalance management server once all of your back‐
10 end onion service instances are running.
11 You will need to create a configuration file which list the backend
13 hidden services and the location of your hidden service keys.
14 $ onionbalance -c config.yaml
16 or
18 $ sudo service onionbalance start
20 The management server must be left running to publish new descriptors
22 for your onion service.
23 NOTE:
25 Multiple OnionBalance management servers can be run simultaneously
26 with the same master private key and configuration file to provide
27 redundancy.
28
30 onionbalance
31 onionbalance distributes the requests for a Tor hidden services across
32 multiple Tor instances.
33 usage: onionbalance [-h] [-i IP] [-p PORT] [-s SOCKET] [-c CONFIG]
35 [-v VERBOSITY] [--version]
36 -h, --help
38 show this help message and exit
39 -i <ip>, --ip <ip>
41 Tor controller IP address
42 -p <port>, --port <port>
44 Tor controller port
45 -s <socket>, --socket <socket>
47 Tor unix domain control socket location
48 -c <config>, --config <config>
50 Config file location
51 -v <verbosity>, --verbosity <verbosity>
53 Minimum verbosity level for logging. Available in ascending
54 order: debug, info, warning, error, critical). The default is
55 info.
56 --version
58 show program's version number and exit
59
61 The OnionBalance management server is primarily configured using a YAML
62 configuration file.
63 # Onion Load Balancer Config File
65 # ---
66 # Each hidden service key line should be followed be followed by a list of 0
67 # or more instances which contain the onion address of the load balancing
68 # hidden service
69 REFRESH_INTERVAL: 600 # How often to poll for updated descriptors
71 services:
72 - key: /path/to/private_key # 7s4hxwwifcslrus2.onion
73 instances:
74 - address: o6ff73vmigi4oxka # web1
75 - address: nkz23ai6qesuwqhc # web2
76 - key: /path/to/private_key.enc # dpkdeys3apjtqydk.onion
77 instances:
78 - address: htbzowpp5cn7wj2u # irc1
79 - address: huey7aiod8dja8a3 # irc2
80 The services section of the configuration file contains a list of mas‐
83 ter onion services that OnionBalance is responsible for.
84 Each key option specifies the location of the 1024 bit private RSA key
86 for the hidden service. This master private key determines the address
87 that users will use to access your onion service. This private key must
88 be kept secure.
89 The location of the private key is evaluated as an absolute path, or
91 relative to the configuration file location.
92 You can use existing Tor hidden service private key with OnionBalance
94 to keep your onion address.
95 Each backend Tor onion service instance is listed by its unique onion
97 address in the instances list.
98 NOTE:
100 You can replace backend instance keys if they get lost or compro‐
101 mised. Simply start a new backend hidden service under a new key
102 and replace the address in the config file.
103 If you have used the onionbalance-config tool you can simply use the
105 generated config file from master/config.yaml.
106 NOTE:
108 By default onionbalance will search for a config.yaml file in the
109 current working directory.
110 Configuration Options
112 The OnionBalance command line options can also be specified in the
113 OnionBalance configuration file. Options specified on the command line
114 take precedence over the related configuration file options:
115 TOR_CONTROL_SOCKET:
117 The location of the Tor unix domain control socket. OnionBalance
118 will attempt to connect to this control socket first before
119 falling back to using a control port connection. (default:
120 /var/run/tor/control)
121 TOR_ADDRESS:
123 The address where the Tor control port is listening. (default:
124 127.0.0.1)
125 TOR_PORT:
127 The Tor control port. (default: 9051)
128 TOR_CONTROL_PASSWORD:
130 The password for authenticating to a Tor control port which is
131 using the HashedControlPassword authentication method. This is
132 not needed when the Tor control port is using the more common
133 CookieAuthentication method. (default: None)
134 Other options:
136 LOG_LOCATION
138 The path where OnionBalance should write its log file.
139 LOG_LEVEL
141 Specify the minimum verbosity of log messages to output. All log
142 messages equal or higher the the specified log level are output.
143 The available log levels are the same as the --verbosity command
144 line option.
145 REFRESH_INTERVAL
147 How often to check for updated backend hidden service descrip‐
148 tors. This value can be decreased if your backend instance are
149 under heavy loaded causing them to rotate introduction points
150 quickly. (default: 600 seconds).
151 PUBLISH_CHECK_INTERVAL
153 How often should to check if new descriptors need to be pub‐
154 lished for the master hidden service (default: 360 seconds).
155 INITIAL_DELAY
157 How long to wait between starting OnionBalance and publishing
158 the master descriptor. If you have more than 20 backend
159 instances you may need to wait longer for all instance descrip‐
160 tors to download before starting (default: 45 seconds).
161 DISTINCT_DESCRIPTORS
163 Distinct descriptors are used if you have more than 10 backend
164 instances. At the cost of scalability, this can be disabled to
165 appear more like a standard onion service. (default: True)
166 STATUS_SOCKET_LOCATION
168 The OnionBalance service creates a Unix domain socket which pro‐
169 vides real-time information about the currently loaded service
170 and descriptors. This option can be used to change the location
171 of this domain socket. (default: /var/run/onionbalance/control)
172 The following options typically do not need to be modified by the end
174 user:
175 REPLICAS
177 How many set of HSDirs to upload too (default: 2).
178 MAX_INTRO_POINTS
180 How many introduction points to include in a descriptor
181 (default: 10)
182 DESCRIPTOR_VALIDITY_PERIOD
184 How long a hidden service descriptor remains valid (default:
185 86400 seconds)
186 DESCRIPTOR_OVERLAP_PERIOD
188 How long to overlap hidden service descriptors when changing
189 descriptor IDs (default: 3600 seconds)
190 DESCRIPTOR_UPLOAD_PERIOD
192 How often to publish a descriptor, even when the introduction
193 points don't change (default: 3600 seconds)
194 Environment Variables
196 ONIONBALANCE_CONFIG
197 Override the location for the OnionBalance configuration file.
198 The loaded configuration file takes precedence over environment vari‐
200 ables. Configuration file options will override environment variable
201 which have the same name.
202 ONIONBALANCE_LOG_LOCATION
204 See the config file option.
205 ONIONBALANCE_LOG_LEVEL
207 See the config file option
208 ONIONBALANCE_STATUS_SOCKET_LOCATION
210 See the config file option
211 ONIONBALANCE_TOR_CONTROL_SOCKET
213 See the config file option
214
216 /etc/onionbalance/config.yaml
217 The configuration file, which contains services entries.
218 config.yaml
220 Fallback location for torrc, if /etc/onionbalance/config.yaml is
221 not found.
222
224 Full documentation for the OnionBalance software is available at
225 https://onionbalance.readthedocs.org/
226
228 Donncha O'Cearbhaill <donncha@donncha.is>
2290.1.4 Jul 20, 2018 ONIONBALANCE(1)