Cooking with Onions: Reclaiming the Onionbalance

by asn | March 17, 2020

Welcome to another issue of Cooking with Onions!
Onionbalance is one of the standard ways onion service administrators can load balance onion services, but it didn't work for v3 onions. Until now. We just released a new version of Onionbalance that supports v3 onion services.
The core functionality remains the same: Onionbalance allows onion service operators to achieve the property of high availability by allowing multiple machines to handle requests for an onion service.
If you are already familiar with configuring Tor onion services, setting up Onionbalance is simple. Check the precise setup instructions on our documentation page.

What took you so long?

We deployed next generation v3 onions two years ago, but we just added v3 support for Onionbalance. This took a while...
Introducing v3 functionality to Onionbalance wasn't easy. The v3 protocol is more secure and robust than v2, but those benefits come with a more complicated protocol. That made Onionbalance integration harder.
To implement v3 support for Onionbalance, we had to jump through various hoops, and in some cases, we had to take the more complicated scenic route.
In particular, some of the advanced v3 crypto was not allowing us to pull the classic Onionbalance trick of making a user think they are going to the frontend service but in reality visiting a backend service. To work around this, we were forced to make the OnionBalance setup procedure a bit more complicated: operators now need to explicitly configure their backend services to act as Onionbalance instances via the torrc.
Finally, as part of our work on Onionbalance v3, we also had to implement v3 descriptor support for Stem, a Python controller library for Tor.

What's next?

We're still missing Onionbalance packages for Debian and pip. We want to conduct more tests before replacing the existing packages with the new Onionbalance, so we expect these to be ready in April. The current version of Onionbalance is 0.1.9, and our plan is to create the packages when 0.2.0 is released.
Additionally, these features are still to come:
  • Support for v3 "distinct descriptor" mode. This mode allows Onionbalance v2 to load-balance more than 10 backend instances, whereas currently Onionbalance v3 has a limit of 8 backend instances. In theory, Onionbalance could load-balance hundreds of backend instances by publishing descriptors at small time intervals that contain introduction points from a different subset of those instances each time.
  • Minimize the differences between both v3 and other descriptors. Currently Onionbalance v3 descriptors can look different from other descriptors, which makes it possible for clients and HSDirs to learn that a service is using Onionbalance. This can be an issue for more advanced onion service threat models
  • Enable client authorization on the frontend service. This may be needed in specialized use cases. Adding this feature would first require implementing client authorization support to Stem v3 descriptors and then using that feature in Onionbalance.
  • Allow the ability to transfer your existing v3 onion service to Onionbalance.
Right now, any sort of testing and feedback would be really helpful for us. Also, if you are in the mood for coding or fixing bugs, it would be great if you could provide patches for any of the above missing features or any other feature you might need: We also have a GitHub mirror for people who feel more comfortable there.
We hope this new flavor gives the transition to v3 onion services a boost. And now that Onionbalance is back in active development, maybe you'll join us in kitchen and write some code?
Until next time! :)


Please note that the comment area below has been archived.

March 17, 2020


Can you stop using github and host them internally on gitea? Github's account creation is blocking tor. will be nice

March 18, 2020


I agree that GitLab ia better than GitHub, but I think there are better alternatives.

** e.g. is Java-Script-free, Free Software and hostable

March 24, 2020


I really don't know anything about Onion Balance or the Tor HS internals, but I can't help but think... wouldn't it have been smarter to embed the OnionBalance logic into Tor directly when v3 was being developed? Such that any two or more Tor instances hosting an HS with the same private key would automatically share requests? This is how i2p does multihoming, although i2p has the convenience of being DHT-based. Just wondering.