Change Log


  • Add an OBv3 hacking guide.

  • Remove tox and simplify build procedure.

  • A single OnionBalance can now support multiple onion services.


  • v2 codebase now uses Cryptodome instead of the deprecated PyCrypto library.

  • v3 codebase is now more flexible when it comes to requiring a live consensus. This should increase the reachability of Onionbalance in scenarios where the network is having trouble establishing a new consensus.

  • v3 support for connecting to the control port through a Unix socket. Patch by Peter Tripp.

  • Introduce status socket support for v3 onions. Patch by vporton.

  • Sending a SIGHUP signal now reloads the v3 config. Patch by Peter Chung.


  • Allow migration from Tor to Onionbalance by reading tor private keys directly using the ‘key’ directive in the YAML config file. Also update onionbalance-config to support that.

  • Improve onionbalance-config for v3 onions. Simplify the output directory (and change docs to reflect so) and the wizard suggestions.


  • Initial support for v3 onions!


  • Fix a bug which could cause descriptor fetching to crash and stall if an old instance descriptor was retrieved from a HSDir. #64

  • Minors fixes to documentation and addition of a tutorial.


  • Add functionality to reconnect to the Tor control port while Onionbalance is running. Thank you to Ceysun Sucu for the patch. #45

  • Fix bug where instance descriptors were not updated correctly when an instance address was listed under multiple master service. #49

  • Improve performance by only requesting each unique instance descriptor once per round, rather once for each time it was listed in the config file. #51

  • Fix bug where an exception was raised when the status socket location did not exist.

  • Improve the installation documentation for Debian and Fedora/EPEL installations.


  • Remove unicode tags from the yaml files generated by onionbalance-config.

  • Fix bug resulting in invalid instance onion addresses when attempting to remove the “.onion” TLD. #44


  • Log error when Onionbalance does not have permission to read a private key. #34

  • Fix bug loading descriptors when an address with .onion extension is listed in the configuration file. #37

  • Add support for connecting to the Tor control port over a unix domain socket. #3


  • Use setproctitle to set a cleaner process title

  • Replace the python-schedule dependency with a custom scheduler.

  • Add a Unix domain socket which outputs the status of the Onionbalance service when a client connects. By default this socket is created at /var/run/onionbalance/control. Thank you to Federico Ceratto for the original socket implementation.

  • Add support for handling the SIGINT and SIGTERM signals. Thank you to Federico Ceratto for this feature.

  • Upgrade tests to use the stable Tor 0.2.7.x release.

  • Fix bug when validating the modulus length of a provided RSA private key.

  • Upload distinct service descriptors to each hidden service directory by default. The distinct descriptors allows up to 60 introduction points or backend instances to be reachable by external clients. Thank you to Ceysun Sucu for describing this technique in his Masters thesis.

  • Add INITIAL_DELAY option to wait longer before initial descriptor publication. This is useful when there are many backend instance descriptors which need to be downloaded.

  • Add configuration option to allow connecting to a Tor control port on a different host.

  • Remove external image assets when documentation is generated locally instead of on ReadTheDocs.


  • Streamline the integration tests by using Tor and Chutney from the upstream repositories.

  • Fix bug when HSFETCH is called with a HSDir argument (3d225fd).

  • Remove the ‘schedule’ package from the source code and re-add it as a dependency. This Python package is now packaged for Debian.

  • Extensively restructure the documentation to make it more comprehensible.

  • Add –version argument to the command line

  • Add configuration options to output log entries to a log file.


  • Remove dependency on the schedule package to prepare for packaging Onionbalance in Debian. The schedule code is now included directly in onionbalance/

  • Fix the executable path in the help messages for onionbalance and onionbalance-config.


  • Patch to resolve issue when saving generated torrc files from onionbalance-config in Python 2.


  • Initial release