/usr/share/doc/onionbalance/html/running-onionbalance.html is in onionbalance 0.1.6-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Running OnionBalance — OnionBalance 0.1.6 documentation</title>
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.1.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="top" title="OnionBalance 0.1.6 documentation" href="index.html" />
<link rel="up" title="Getting Started" href="getting-started.html" />
<link rel="next" title="onionbalance-config Tool" href="onionbalance-config.html" />
<link rel="prev" title="Getting Started" href="getting-started.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body role="document">
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="running-onionbalance">
<h1>Running OnionBalance<a class="headerlink" href="#running-onionbalance" title="Permalink to this headline">¶</a></h1>
<div class="section" id="description">
<h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
<p>You can start the OnionBalance management server once all of your backend
onion service instances are running.</p>
<p>You will need to create a <a class="reference internal" href="#configuration-file-format"><span class="std std-ref">configuration file</span></a>
which list the backend hidden services and the location of your hidden
service keys.</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> onionbalance -c config.yaml
</pre></div>
</div>
<p>or</p>
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> sudo service onionbalance start
</pre></div>
</div>
<p>The management server must be left running to publish new descriptors for
your onion service.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Multiple OnionBalance management servers can be run simultaneously with
the same master private key and configuration file to provide redundancy.</p>
</div>
</div>
<div class="section" id="command-line-options">
<h2>Command-Line Options<a class="headerlink" href="#command-line-options" title="Permalink to this headline">¶</a></h2>
<div class="section" id="onionbalance">
<h3>onionbalance<a class="headerlink" href="#onionbalance" title="Permalink to this headline">¶</a></h3>
<p>onionbalance distributes the requests for a Tor hidden services across multiple Tor instances.</p>
<p>usage: onionbalance [-h] [-i IP] [-p PORT] [-s SOCKET] [-c CONFIG]
[-v VERBOSITY] [–version]</p>
<dl class="option">
<dt id="cmdoption-onionbalance-h">
<span id="cmdoption-onionbalance--help"></span><code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-onionbalance-h" title="Permalink to this definition">¶</a></dt>
<dd><p>show this help message and exit</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-onionbalance-i">
<span id="cmdoption-onionbalance--ip"></span><code class="descname">-i</code><code class="descclassname"> <ip></code><code class="descclassname">, </code><code class="descname">--ip</code><code class="descclassname"> <ip></code><a class="headerlink" href="#cmdoption-onionbalance-i" title="Permalink to this definition">¶</a></dt>
<dd><p>Tor controller IP address</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-onionbalance-p">
<span id="cmdoption-onionbalance--port"></span><code class="descname">-p</code><code class="descclassname"> <port></code><code class="descclassname">, </code><code class="descname">--port</code><code class="descclassname"> <port></code><a class="headerlink" href="#cmdoption-onionbalance-p" title="Permalink to this definition">¶</a></dt>
<dd><p>Tor controller port</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-onionbalance-s">
<span id="cmdoption-onionbalance--socket"></span><code class="descname">-s</code><code class="descclassname"> <socket></code><code class="descclassname">, </code><code class="descname">--socket</code><code class="descclassname"> <socket></code><a class="headerlink" href="#cmdoption-onionbalance-s" title="Permalink to this definition">¶</a></dt>
<dd><p>Tor unix domain control socket location</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-onionbalance-c">
<span id="cmdoption-onionbalance--config"></span><code class="descname">-c</code><code class="descclassname"> <config></code><code class="descclassname">, </code><code class="descname">--config</code><code class="descclassname"> <config></code><a class="headerlink" href="#cmdoption-onionbalance-c" title="Permalink to this definition">¶</a></dt>
<dd><p>Config file location</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-onionbalance-v">
<span id="cmdoption-onionbalance--verbosity"></span><code class="descname">-v</code><code class="descclassname"> <verbosity></code><code class="descclassname">, </code><code class="descname">--verbosity</code><code class="descclassname"> <verbosity></code><a class="headerlink" href="#cmdoption-onionbalance-v" title="Permalink to this definition">¶</a></dt>
<dd><p>Minimum verbosity level for logging. Available in ascending order: debug, info, warning, error, critical). The default is info.</p>
</dd></dl>
<dl class="option">
<dt id="cmdoption-onionbalance--version">
<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-onionbalance--version" title="Permalink to this definition">¶</a></dt>
<dd><p>show program’s version number and exit</p>
</dd></dl>
</div>
</div>
<div class="section" id="configuration-file-format">
<span id="id1"></span><h2>Configuration File Format<a class="headerlink" href="#configuration-file-format" title="Permalink to this headline">¶</a></h2>
<p>The OnionBalance management server is primarily configured using a YAML
configuration file.</p>
<div class="highlight-yaml" id="example-config-yaml"><div class="highlight"><pre><span></span><span class="c1"># Onion Load Balancer Config File</span>
<span class="c1"># ---</span>
<span class="c1"># Each hidden service key line should be followed be followed by a list of 0</span>
<span class="c1"># or more instances which contain the onion address of the load balancing</span>
<span class="c1"># hidden service</span>
<span class="l l-Scalar l-Scalar-Plain">REFRESH_INTERVAL</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">600</span> <span class="c1"># How often to poll for updated descriptors</span>
<span class="l l-Scalar l-Scalar-Plain">services</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">key</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">/path/to/private_key</span> <span class="c1"># 7s4hxwwifcslrus2.onion</span>
<span class="l l-Scalar l-Scalar-Plain">instances</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">address</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">o6ff73vmigi4oxka</span> <span class="c1"># web1</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">address</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">nkz23ai6qesuwqhc</span> <span class="c1"># web2</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">key</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">/path/to/private_key.enc</span> <span class="c1"># dpkdeys3apjtqydk.onion</span>
<span class="l l-Scalar l-Scalar-Plain">instances</span><span class="p p-Indicator">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">address</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">htbzowpp5cn7wj2u</span> <span class="c1"># irc1</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">address</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain">huey7aiod8dja8a3</span> <span class="c1"># irc2</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">services</span></code> section of the configuration file contains a list of
master onion services that OnionBalance is responsible for.</p>
<p>Each <code class="docutils literal"><span class="pre">key</span></code> option specifies the location of the 1024 bit private RSA key
for the hidden service. This master private key determines the address
that users will use to access your onion service. This private key <strong>must</strong>
be kept secure.</p>
<p>The location of the private key is evaluated as an absolute path, or
relative to the configuration file location.</p>
<p>You can use existing Tor hidden service private key with OnionBalance
to keep your onion address.</p>
<p>Each backend Tor onion service instance is listed by its unique onion
address in the <code class="docutils literal"><span class="pre">instances</span></code> list.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can replace backend instance keys if they get lost or compromised.
Simply start a new backend hidden service under a new key and replace
the <code class="docutils literal"><span class="pre">address</span></code> in the config file.</p>
</div>
<p>If you have used the <a class="reference internal" href="onionbalance-config.html#onionbalance-config"><span class="std std-ref">onionbalance-config</span></a> tool
you can simply use the generated config file from <code class="docutils literal"><span class="pre">master/config.yaml</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">By default onionbalance will search for a <code class="docutils literal"><span class="pre">config.yaml</span></code> file in
the current working directory.</p>
</div>
<div class="section" id="configuration-options">
<h3>Configuration Options<a class="headerlink" href="#configuration-options" title="Permalink to this headline">¶</a></h3>
<p>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:</p>
<dl class="docutils">
<dt>TOR_CONTROL_SOCKET:</dt>
<dd>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)</dd>
<dt>TOR_ADDRESS:</dt>
<dd>The address where the Tor control port is listening. (default: 127.0.0.1)</dd>
<dt>TOR_PORT:</dt>
<dd>The Tor control port. (default: 9051)</dd>
<dt>TOR_CONTROL_PASSWORD:</dt>
<dd>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)</dd>
</dl>
<p>Other options:</p>
<dl class="docutils">
<dt>LOG_LOCATION</dt>
<dd>The path where OnionBalance should write its log file.</dd>
<dt>LOG_LEVEL</dt>
<dd>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.</dd>
<dt>REFRESH_INTERVAL</dt>
<dd>How often to check for updated backend hidden service descriptors. This
value can be increased if your backend instance are under heavy loaded
causing them to rotate introduction points quickly.
(default: 600 seconds).</dd>
<dt>PUBLISH_CHECK_INTERVAL</dt>
<dd>How often should to check if new descriptors need to be published for
the master hidden service (default: 360 seconds).</dd>
<dt>INITIAL_DELAY</dt>
<dd>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).</dd>
<dt>DISTINCT_DESCRIPTORS</dt>
<dd>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)</dd>
<dt>STATUS_SOCKET_LOCATION</dt>
<dd>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)</dd>
</dl>
<p>The following options typically do not need to be modified by the end user:</p>
<dl class="docutils">
<dt>REPLICAS</dt>
<dd>How many set of HSDirs to upload too (default: 2).</dd>
<dt>MAX_INTRO_POINTS</dt>
<dd>How many introduction points to include in a descriptor (default: 10)</dd>
<dt>DESCRIPTOR_VALIDITY_PERIOD</dt>
<dd>How long a hidden service descriptor remains valid (default:
86400 seconds)</dd>
<dt>DESCRIPTOR_OVERLAP_PERIOD</dt>
<dd>How long to overlap hidden service descriptors when changing
descriptor IDs (default: 3600 seconds)</dd>
<dt>DESCRIPTOR_UPLOAD_PERIOD</dt>
<dd>How often to publish a descriptor, even when the introduction points
don’t change (default: 3600 seconds)</dd>
</dl>
</div>
<div class="section" id="environment-variables">
<h3>Environment Variables<a class="headerlink" href="#environment-variables" title="Permalink to this headline">¶</a></h3>
<dl class="docutils">
<dt>ONIONBALANCE_CONFIG</dt>
<dd>Override the location for the OnionBalance configuration file.</dd>
</dl>
<p>The loaded configuration file takes precedence over environment variables.
Configuration file options will override environment variable which have the
same name.</p>
<dl class="docutils">
<dt>ONIONBALANCE_LOG_LOCATION</dt>
<dd>See the config file option.</dd>
<dt>ONIONBALANCE_LOG_LEVEL</dt>
<dd>See the config file option</dd>
<dt>ONIONBALANCE_STATUS_SOCKET_LOCATION</dt>
<dd>See the config file option</dd>
<dt>ONIONBALANCE_TOR_CONTROL_SOCKET</dt>
<dd>See the config file option</dd>
</dl>
</div>
</div>
<div class="section" id="files">
<h2>Files<a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>/etc/onionbalance/config.yaml</dt>
<dd>The configuration file, which contains <code class="docutils literal"><span class="pre">services</span></code> entries.</dd>
<dt>config.yaml</dt>
<dd>Fallback location for torrc, if /etc/onionbalance/config.yaml is
not found.</dd>
</dl>
</div>
<div class="section" id="see-also">
<h2>See Also<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
<p>Full documentation for the <strong>OnionBalance</strong> software is available at
<a class="reference external" href="https://onionbalance.readthedocs.org/">https://onionbalance.readthedocs.org/</a></p>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="index.html">OnionBalance</a></h1>
<p class="blurb">Load balancing and redundancy for Tor hidden services.</p>
<h3>Navigation</h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Running OnionBalance</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#description">Description</a></li>
<li class="toctree-l2"><a class="reference internal" href="#command-line-options">Command-Line Options</a></li>
<li class="toctree-l2"><a class="reference internal" href="#configuration-file-format">Configuration File Format</a></li>
<li class="toctree-l2"><a class="reference internal" href="#files">Files</a></li>
<li class="toctree-l2"><a class="reference internal" href="#see-also">See Also</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="use-cases.html">Use Cases</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="design.html">Design Document</a></li>
<li class="toctree-l1"><a class="reference internal" href="contributors.html">Contributors</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Change Log</a></li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="index.html">Documentation overview</a><ul>
<li><a href="getting-started.html">Getting Started</a><ul>
<li>Previous: <a href="getting-started.html" title="previous chapter">Getting Started</a></li>
<li>Next: <a href="onionbalance-config.html" title="next chapter">onionbalance-config Tool</a></li>
</ul></li>
</ul></li>
</ul>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.4.9</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
|
<a href="_sources/running-onionbalance.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>
|