Onionoo

Onionoo is a web-based protocol to learn about currently running Tor relays and bridges. Onionoo itself was not designed as a service for human beings—at least not directly. Onionoo provides the data for other applications and websites which in turn present Tor network status information to humans. The following Onionoo clients are currently available:

  • Atlas is a web application to discover Tor relays. It provides useful information on how relays are configured along with graphics about their past.
  • Compass is a Python script and website that extracts consensus weight information of currently running relays and aggregates weights of relays running in the same country or same autonomous system.
  • Tor2web is a web proxy to Tor Hidden Services. It uses Onionoo to get the list of currently running Tor Exits to detect if the client is a Tor user and if so redirect them to the .onion address.
  • Globe is a web application that allows you to search for Tor relays and bridges. It gives you a detailed overview of properties and configurations of a relay or bridge.
  • The Nos oignons website uses Onionoo to visualize bandwidth histories of their relays.
  • The metrics website visualizes diversity of the Tor network using bubble graphs.
The following Onionoo clients are currently unmaintained, but are still a good idea:
  • mOnionO is an Android app that lets you add your relays or bridges to your favorites list and keeps you always informed whether they are running or not.

Developing Onionoo applications

The project pages of the Onionoo clients listed above have further information for contacting the authors and contributing ideas or code. The authors will be happy to hear your thoughts!

You don't find your favorite Onionoo client above? Want to implement your own and tell us to add it to the list? The Onionoo clients above are backed by a web-based protocol, which facilitates developing new applications displaying Tor status information. Here are a few ideas for new Onionoo clients:

  • Tor controller extension: Extend Vidalia and/or arm to look up details for the bridge that the user is running and display what pool the bridge is contained in.
  • Social network site plugin: Add a plugin to the social network site of your choice to show your friends what Tor relays and bridges you're running and how that helps users around the world.
  • Desktop tray icon: Write a tray icon for your favorite desktop environment that tells you when your relay or bridge is down and that displays some basic usage statistics.
  • E-mail notification service: Improve our e-mail notification service Weather by implementing its own relay search or extending it to report when a bridge drops off the network.
  • Command-line tool: Implement a command-line tool that quickly searches a relay or bridge and prints out some status information to help debug problems.
  • (Insert your idea here.)

Want to help with developing the Onionoo server that provides Tor status data, or want to run your own Onionoo server instance? The Onionoo server is written in Java with a tiny portion of Java Servlets. Instructions for setting up the Onionoo server to fetch the required data from the Tor servers is described in the INSTALL file in the sources. For more details see the source code and issue tracker.

Related projects

TorStatus is the name of a nowadays unmaintained website that displays Tor relay information similar to Atlas. There are still a few TorStatus websites running.

There's another project from summer 2011 called TorStatus which is a rewrite of the original TorStatus in Python/Django. Unfortunately, it's also unmaintained.

Finally, there's the consensus-health page which has the primary purpose of indicating problems with creating a network status consensus. As a side-effect this page lists all currently running relays and how the directory authorities voted on them.