Onionoo —

a Tor network status protocol

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.
• 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.
• torchart is a PHP WordPress plugin which draws 3 day traffic charts using pChart currently used for displaying metric charts on icetor.is.
• challenger aggregates graph data from relays participating in EFF's 2014 Tor Challenge to provide statistics like total bytes transferred.
• AnOnionooid is an Android app that helps find and explore Tor relays and bridges.
• OnionTip uses Onionoo's data to distribute donations to relays that have a bitcoin address in their contact line.
• koninoo is a simple Java command line interface for querying Onionoo data.
• The DuckDuckGo search engine displays Tor node details when being asked for "tor node" followed by a search term.
• OnionView is a simple web service which uses Tor relay data to plot the location of active Tor nodes onto an interactive map of the world.

The following library facilitates development of Onionoo clients:

• OnionPy is a comprehensive pure-Python (2.7+) Onionoo wrapper with caching support.

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.