1ONIONBALANCE(1)                  OnionBalance                  ONIONBALANCE(1)
2
3
4

NAME

6       onionbalance - a Tor hidden service load balancer
7

DESCRIPTION

9       You can start the OnionBalance management server once all of your back‐
10       end onion service instances are running.
11
12       You will need to create a configuration file  which  list  the  backend
13       hidden services and the location of your hidden service keys.
14
15          $ onionbalance -c config.yaml
16
17       or
18
19          $ sudo service onionbalance start
20
21       The  management  server must be left running to publish new descriptors
22       for your onion service.
23
24       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

COMMAND-LINE OPTIONS

30   onionbalance
31       onionbalance distributes the requests for a Tor hidden services  across
32       multiple Tor instances.
33
34          usage: onionbalance [-h] [-i IP] [-p PORT] [-s SOCKET] [-c CONFIG]
35                              [-v VERBOSITY] [--version]
36
37       -h, --help
38              show this help message and exit
39
40       -i <ip>, --ip <ip>
41              Tor controller IP address
42
43       -p <port>, --port <port>
44              Tor controller port
45
46       -s <socket>, --socket <socket>
47              Tor unix domain control socket location
48
49       -c <config>, --config <config>
50              Config file location
51
52       -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
57       --version
58              show program's version number and exit
59

CONFIGURATION FILE FORMAT

61       The OnionBalance management server is primarily configured using a YAML
62       configuration file.
63
64          # 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
70          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
81
82       The services section of the configuration file contains a list of  mas‐
83       ter onion services that OnionBalance is responsible for.
84
85       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
90       The location of the private key is evaluated as an  absolute  path,  or
91       relative to the configuration file location.
92
93       You  can  use existing Tor hidden service private key with OnionBalance
94       to keep your onion address.
95
96       Each backend Tor onion service instance is listed by its  unique  onion
97       address in the instances list.
98
99       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
104       If  you  have  used the onionbalance-config tool you can simply use the
105       generated config file from master/config.yaml.
106
107       NOTE:
108          By default onionbalance will search for a config.yaml  file  in  the
109          current working directory.
110
111   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
116       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
122       TOR_ADDRESS:
123              The address where the Tor control port is  listening.  (default:
124              127.0.0.1)
125
126       TOR_PORT:
127              The Tor control port. (default: 9051)
128
129       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
135       Other options:
136
137       LOG_LOCATION
138              The path where OnionBalance should write its log file.
139
140       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
146       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
152       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
156       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
162       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
167       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
173       The  following  options typically do not need to be modified by the end
174       user:
175
176       REPLICAS
177              How many set of HSDirs to upload too (default: 2).
178
179       MAX_INTRO_POINTS
180              How  many  introduction  points  to  include  in  a   descriptor
181              (default: 10)
182
183       DESCRIPTOR_VALIDITY_PERIOD
184              How  long  a  hidden  service descriptor remains valid (default:
185              86400 seconds)
186
187       DESCRIPTOR_OVERLAP_PERIOD
188              How long to overlap hidden  service  descriptors  when  changing
189              descriptor IDs (default: 3600 seconds)
190
191       DESCRIPTOR_UPLOAD_PERIOD
192              How  often  to  publish a descriptor, even when the introduction
193              points don't change (default: 3600 seconds)
194
195   Environment Variables
196       ONIONBALANCE_CONFIG
197              Override the location for the OnionBalance configuration file.
198
199       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
203       ONIONBALANCE_LOG_LOCATION
204              See the config file option.
205
206       ONIONBALANCE_LOG_LEVEL
207              See the config file option
208
209       ONIONBALANCE_STATUS_SOCKET_LOCATION
210              See the config file option
211
212       ONIONBALANCE_TOR_CONTROL_SOCKET
213              See the config file option
214

FILES

216       /etc/onionbalance/config.yaml
217              The configuration file, which contains services entries.
218
219       config.yaml
220              Fallback location for torrc, if /etc/onionbalance/config.yaml is
221              not found.
222

SEE ALSO

224       Full  documentation  for  the  OnionBalance  software  is  available at
225       https://onionbalance.readthedocs.org/
226

AUTHOR

228       Donncha O'Cearbhaill <donncha@donncha.is>
229
230
231
232
2330.1.4                            Jul 20, 2018                  ONIONBALANCE(1)
Impressum