commit 67ee36d432c1a16a996dcbfd011e9b9e46e72a73 Author: Karsten Loesing karsten.loesing@gmx.net Date: Sat Mar 18 21:45:25 2017 +0100
Turn collector.html and onionoo.html into .jsp. --- .../torproject/metrics/web/CollecTorServlet.java | 31 + .../org/torproject/metrics/web/OnionooServlet.java | 31 + website/src/main/resources/etc/web.xml | 22 + .../src/main/resources/web/WEB-INF/collector.jsp | 940 ++++++++ website/src/main/resources/web/WEB-INF/onionoo.jsp | 2249 ++++++++++++++++++++ website/src/main/resources/web/collector.html | 940 -------- website/src/main/resources/web/onionoo.html | 2249 -------------------- 7 files changed, 3273 insertions(+), 3189 deletions(-)
diff --git a/website/src/main/java/org/torproject/metrics/web/CollecTorServlet.java b/website/src/main/java/org/torproject/metrics/web/CollecTorServlet.java new file mode 100644 index 0000000..74ca163 --- /dev/null +++ b/website/src/main/java/org/torproject/metrics/web/CollecTorServlet.java @@ -0,0 +1,31 @@ +/* Copyright 2017 The Tor Project + * See LICENSE for licensing information */ + +package org.torproject.metrics.web; + +import java.io.IOException; + +import javax.servlet.ServletException; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; + +public class CollecTorServlet extends AnyServlet { + + private static final long serialVersionUID = -7054057945737357463L; + + @Override + public void init() throws ServletException { + super.init(); + } + + @Override + public void doGet(HttpServletRequest request, + HttpServletResponse response) throws IOException, ServletException { + + /* Forward the request to the JSP that does all the hard work. */ + request.setAttribute("categories", this.categories); + request.getRequestDispatcher("WEB-INF/collector.jsp").forward(request, + response); + } +} + diff --git a/website/src/main/java/org/torproject/metrics/web/OnionooServlet.java b/website/src/main/java/org/torproject/metrics/web/OnionooServlet.java new file mode 100644 index 0000000..1133f10 --- /dev/null +++ b/website/src/main/java/org/torproject/metrics/web/OnionooServlet.java @@ -0,0 +1,31 @@ +/* Copyright 2017 The Tor Project + * See LICENSE for licensing information */ + +package org.torproject.metrics.web; + +import java.io.IOException; + +import javax.servlet.ServletException; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; + +public class OnionooServlet extends AnyServlet { + + private static final long serialVersionUID = 3036525855022445178L; + + @Override + public void init() throws ServletException { + super.init(); + } + + @Override + public void doGet(HttpServletRequest request, + HttpServletResponse response) throws IOException, ServletException { + + /* Forward the request to the JSP that does all the hard work. */ + request.setAttribute("categories", this.categories); + request.getRequestDispatcher("WEB-INF/onionoo.jsp").forward(request, + response); + } +} + diff --git a/website/src/main/resources/etc/web.xml b/website/src/main/resources/etc/web.xml index 63dd333..d19777f 100644 --- a/website/src/main/resources/etc/web.xml +++ b/website/src/main/resources/etc/web.xml @@ -284,6 +284,28 @@ </servlet-mapping>
<servlet> + <servlet-name>CollecTorServlet</servlet-name> + <servlet-class> + org.torproject.metrics.web.CollecTorServlet + </servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>CollecTorServlet</servlet-name> + <url-pattern>/collector.html</url-pattern> + </servlet-mapping> + + <servlet> + <servlet-name>OnionooServlet</servlet-name> + <servlet-class> + org.torproject.metrics.web.OnionooServlet + </servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>OnionooServlet</servlet-name> + <url-pattern>/onionoo.html</url-pattern> + </servlet-mapping> + + <servlet> <servlet-name>ResearchServlet</servlet-name> <servlet-class> org.torproject.metrics.web.ResearchServlet diff --git a/website/src/main/resources/web/WEB-INF/collector.jsp b/website/src/main/resources/web/WEB-INF/collector.jsp new file mode 100644 index 0000000..07d6f99 --- /dev/null +++ b/website/src/main/resources/web/WEB-INF/collector.jsp @@ -0,0 +1,940 @@ +<!DOCTYPE html> +<html lang="en" style="min-height:100%;"> + <head> + + <title>CollecTor</title> + + <meta charset="utf-8"> + <link href="images/favicon.ico" type="image/x-icon" rel="shortcut icon"> + + <!-- yes, we're handheld friendly :) --> + <meta name="HandheldFriendly" content="True"> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"> + <meta name="apple-mobile-web-app-capable" content="yes"> + + <!-- icons for mobile devices --> + <link rel="apple-touch-icon" href="images/apple-touch-icon-152x152.png"> + <link rel="shortcut icon" href="images/android-icon.png" sizes="196x196"> + <meta name="msapplication-square70x70logo" content="images/smalltile.png"> + <meta name="msapplication-square150x150logo" content="images/mediumtile.png"> + <meta name="msapplication-wide310x150logo" content="images/widetile.png"> + <meta name="msapplication-square310x310logo" content="images/largetile.png"> + + <!-- jQuery --> + <script src="js/jquery-3.1.1.min.js"></script> + + <!-- Bootstrap --> + <link rel="stylesheet" href="css/bootstrap.min.css"> + <script src="js/bootstrap.min.js"></script> + + <!-- Fonts --> + <link rel="stylesheet" href="css/font-awesome.min.css"> + <link rel="stylesheet" href="fonts/source-sans-pro.css"> + + <!-- custom styles and javascript --> + <link rel="stylesheet" href="css/style.css"> + <script src="js/script.js"></script> + + </head> + +<body class="noscript" style="background-image:url(images/ajax-loader.gif);background-repeat:no-repeat;background-position:center center;"> + +<!-- Using evil inline stylesheets to hide the FOUC for slow connections... --> + +<div id="wrapper" style="display:none;"> + + +<!-- backToTop-Button and Anchor --> +<noscript> +<div class="topButton" style="display:block;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div> +</noscript> +<script type="text/javascript"> +document.write('<div class="topButton" style="display:none;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div>'); +</script> +<a id="top"></a> + + + +<!-- secondary navigation --> +<nav class="navbar navbar-default navbar-secondary"> +<div class="container-fluid"> + <input type="checkbox" id="navbar-toggle-checkbox"> + <div class="navbar-header"> + <a class="navbar-brand visible-xs" href="/"><img src="images/collector-wordmark-white.png" width="264" height="50" alt="CollecTor"></a> + </div> + + </div> +</nav> +<!-- /secondary navigation --> + + + +<!-- page header for every single page --> +<div class="page-header hidden-xs"> + <a href="/"><img src="images/collector-logo.png" width="143" height="117" alt="" id="collector-logo"></a> + <a href="/"><img src="images/collector-wordmark-white.png" width="264" height="50" alt="CollecTor" id="collector-wordmark"></a> + <div> + <p> + <i>Your friendly data-collecting<br> + service in the Tor network.</i> + </p> + </div> + <div class="clearfix"></div> +</div> +<!-- /page header --> + + <div class="container"> + <div class="row"> + <div class="col-xs-12"> + + <br><br> + + <div class="jumbotron"> + <div class="text-center"> + + <h2> + Welcome to CollecTor, your friendly data-collecting service in the Tor network + </h2> + <p> + CollecTor fetches data from various + nodes and services in the public Tor network and makes it + available to the world. If you're doing research on the Tor + network, or if you're developing an application that uses + Tor network data, this is your place to start. + </p> +<a class="btn btn-primary btn-lg" style="margin: 10px" href="recent/"><i class="fa fa-chevron-right" aria-hidden="true"></i> Browse Recent Descriptors</a> +<a class="btn btn-primary btn-lg" style="margin: 10px" href="archive/"><i class="fa fa-chevron-right" aria-hidden="true"></i> Browse Archived Descriptors</a> + </div><!-- text-center --> + + + </div><!-- jumbotron --> + + </div><!-- col --> + </div><!-- row --> + + <div class="row"> + <div class="col-xs-12"> + <br> + <h1 id="available-descriptors" class="hover">Available Descriptors +<a href="#available-descriptors" class="anchor">#</a></h1> + +<p>Descriptors are available in two different file formats: recent descriptors that were published in the last 72 hours are available as plain text, and archived descriptors covering over 10 years of Tor network history are available as compressed tarballs.</p> + +<table class="table"> +<thead> +<tr> +<th>Descriptor Type</th> +<th>Type Annotation</th> +<th class="thDescriptors">Descriptors</th> +</tr> +</thead> +<tbody> +<tr class="tableHeadline"> + <td colspan="3"><b><a href="#relay-descriptors">Tor Relay Descriptors</a></b></td> +</tr> +<tr> + <td><a href="#type-server-descriptor">Relay Server Descriptors</a></td> + <td><code>@type server-descriptor 1.0</code></td> + <td><a href="recent/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-extra-info">Relay Extra-info Descriptors</a></td> + <td><code>@type extra-info 1.0</code></td> + <td><a href="recent/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-network-status-consensus-3">Network Status Consensuses</a></td> + <td><code>@type network-status-consensus-3 1.0</code></td> + <td><a href="recent/relay-descriptors/consensuses/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/relay-descriptors/consensuses/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-network-status-vote-3">Network Status Votes</a></td> + <td><code>@type network-status-vote-3 1.0</code></td> + <td><a href="recent/relay-descriptors/votes/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/relay-descriptors/votes/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-dir-key-certificate-3">Directory Key Certificates</a></td> + <td><code>@type dir-key-certificate-3 1.0</code></td> + <td><a href="archive/relay-descriptors/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-network-status-microdesc-consensus-3">Microdescriptor Consensuses</a></td> + <td><code>@type network-status-microdesc-consensus-3 1.0</code></td> + <td><a href="recent/relay-descriptors/microdescs/consensus-microdesc/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-microdescriptor">Microdescriptors</a></td> + <td><code>@type microdescriptor 1.0</code></td> + <td><a href="recent/relay-descriptors/microdescs/micro/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-network-status-2">Version 2 Network Statuses</a></td> + <td><code>@type network-status-2 1.0</code></td> + <td><a href="archive/relay-descriptors/statuses/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-directory">Version 1 Directories</a></td> + <td><code>@type directory 1.0</code></td> + <td><a href="archive/relay-descriptors/tor/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr class="tableHeadline"> + <td colspan="3"><b><a href="#bridge-descriptors">Tor Bridge Descriptors</a></b></td> +</tr> +<tr> + <td><a href="#type-bridge-network-status">Bridge Network Statuses</a></td> + <td><code>@type bridge-network-status 1.1</code></td> + <td><a href="recent/bridge-descriptors/statuses/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/bridge-descriptors/statuses/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-bridge-server-descriptor">Bridge Server Descriptors</a></td> + <td><code>@type bridge-server-descriptor 1.2</code></td> + <td><a href="recent/bridge-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/bridge-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr> + <td><a href="#type-bridge-extra-info">Bridge Extra-info Descriptors</a></td> + <td><code>@type bridge-extra-info 1.3</code></td> + <td><a href="recent/bridge-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/bridge-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr class="tableHeadline"> + <td colspan="3"><b><a href="#tor-hidden-service-descriptors">Tor Hidden Service Descriptors</a></b></td> +</tr> +<tr> + <td><a href="#type-hidden-service-descriptor">Hidden Service Descriptors</a></td> + <td><code>@type hidden-service-descriptor 1.0</code></td> + <td></td> +</tr> +<tr class="tableHeadline"> + <td colspan="3"><b><a href="#bridge-pool-assignments">BridgeDB's Bridge Pool Assignments</a></b></td> +</tr> +<tr> + <td><a href="#type-bridge-pool-assignment">Bridge Pool Assignments</a></td> + <td><code>@type bridge-pool-assignment 1.0</code></td> + <td><a href="archive/bridge-pool-assignments/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr class="tableHeadline"> + <td colspan="3"><b><a href="#exit-lists">TorDNSEL's Exit Lists</a></b></td> +</tr> +<tr> + <td><a href="#type-tordnsel">Exit Lists</a></td> + <td><code>@type tordnsel 1.0</code></td> + <td><a href="recent/exit-lists/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/exit-lists/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +<tr class="tableHeadline"> + <td colspan="3"><b><a href="#torperf">Torperf's Performance Data</a></b></td> +</tr> +<tr> + <td><a href="#type-torperf">Torperf Measurement Results</a></td> + <td><code>@type torperf 1.0</code></td> + <td><a href="recent/torperf/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> + <a href="archive/torperf/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> +</tr> +</tbody> +</table> + + </div><!-- col --> + </div><!-- row --> +<br> + + + + + <br> + <h1 id="data-formats" class="hover">Data Formats <a href="#data-formats" class="anchor">#</a></h1> + +<p> +Each descriptor provided here contains an <code>@type</code> annotation using +the format <code>@type $descriptortype $major.$minor</code>. +Any tool that processes these descriptors may parse files without meta +data or with an unknown descriptor type at its own risk, can safely parse +files with known descriptor type and same major version number, and should +not parse files with known descriptor type and higher major version +number. +</p> +</div> + + + <div class="container"> + +<br> +<h2 id="relay-descriptors" class="hover">Tor Relay Descriptors +<a href="#relay-descriptors" class="anchor">#</a> +</h2> + +<p> +Relays and directory authorities publish relay descriptors, so that +clients can select relays for their paths through the Tor network. +All these relay descriptors are specified in the +<a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt">Tor +directory protocol, version 3</a> specification document (or in the +earlier protocol +<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt">version 2</a> or +<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt">version 1</a>). +</p> + +<h3 id="type-server-descriptor" class="hover">Relay Server Descriptors +<small><code>@type server-descriptor 1.0</code></small> +<a href="recent/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-server-descriptor" class="anchor">#</a> +</h3> + +<p> +Server descriptors contain information that relays publish about +themselves. +Tor clients once downloaded this information, but now they use +microdescriptors instead. +The server descriptors in the descriptor archives +contain one descriptor per file, whereas the recently published files +contain all descriptors collected in an hour concatenated into a single +file. +</p> + +<h3 id="type-extra-info" class="hover">Relay Extra-info Descriptors +<small><code>@type extra-info 1.0</code></small> +<a href="recent/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-extra-info" class="anchor">#</a> +</h3> + +<p> +Extra-info descriptors contain relay information that Tor clients do not +need in order to function. +These are self-published, like server descriptors, but not downloaded by +clients by default. +The extra-info descriptors in the descriptor archives +contain one descriptor per file, whereas the recently published files +contain all descriptors collected in an hour concatenated into a single +file. +</p> + +<h3 id="type-network-status-consensus-3" class="hover">Network Status Consensuses +<small><code>@type network-status-consensus-3 1.0</code></small> +<a href="recent/relay-descriptors/consensuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/relay-descriptors/consensuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-network-status-consensus-3" class="anchor">#</a> +</h3> + +<p> +Though Tor relays are decentralized, the directories that track the +overall network are not. +These central points are called directory authorities, and every hour they +publish a document called a consensus, or network status document. +The consensus is made up of router status entries containing +flags, heuristics used for relay selection, etc. +</p> + +<h3 id="type-network-status-vote-3" class="hover">Network Status Votes +<small><code>@type network-status-vote-3 1.0</code></small> +<a href="recent/relay-descriptors/votes/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/relay-descriptors/votes/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-network-status-vote-3" class="anchor">#</a> +</h3> + +<p> +The directory authorities exchange votes every hour to come up with a +common consensus. +Vote documents are by far the largest documents provided here. +</p> + +<h3 id="type-dir-key-certificate-3" class="hover">Directory Key Certificates +<small><code>@type dir-key-certificate-3 1.0</code></small> +<a href="archive/relay-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-dir-key-certificate-3" class="anchor">#</a> +</h3> + +<p> +The directory authorities sign votes and the consensus with their +key that they publish in a key certificate. +These key certificates change once every few months, so they are only +available in a single descriptor archive tarball. +</p> + +<h3 id="type-network-status-microdesc-consensus-3" class="hover">Microdescriptor Consensuses +<small><code>@type network-status-microdesc-consensus-3 1.0</code></small> +<a href="recent/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-network-status-microdesc-consensus-3" class="anchor">#</a> +</h3> + +<p> +Tor clients used to download all server descriptors of active relays, but +now they only download the smaller microdescriptors which are derived from +server descriptors. +The microdescriptor consensus lists all active relays and references their +currently used microdescriptor. +The descriptor archive tarballs +contain both microdescriptor consensuses and referenced microdescriptors +together. +</p> + +<h3 id="type-microdescriptor" class="hover">Microdescriptors +<small><code>@type microdescriptor 1.0</code></small> +<a href="recent/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-microdescriptor" class="anchor">#</a> +</h3> + +<p> +Microdescriptors are minimalistic documents that just includes the +information necessary for Tor clients to work. +The descriptor archive tarballs +contain both microdescriptor consensuses and referenced microdescriptors +together. +The microdescriptors in descriptor archive tarballs +contain one descriptor per file, whereas the recently published files +contain all descriptors collected in an hour concatenated into a single +file. +</p> + +<h3 id="type-network-status-2" class="hover">Version 2 Network Statuses +<small><code>@type network-status-2 1.0</code></small> +<a href="archive/relay-descriptors/statuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-network-status-2" class="anchor">#</a> +</h3> + +<p> +Version 2 network statuses have been published by the directory +authorities before consensuses have been introduced. +In contrast to consensuses, each directory authority published their own +authoritative view on the network, and clients combined these documents +locally. +We stopped archiving version 2 network statuses in 2012. +</p> + +<h3 id="type-directory" class="hover">Version 1 Directories +<small><code>@type directory 1.0</code></small> +<a href="archive/relay-descriptors/tor/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-directory" class="anchor">#</a> +</h3> + +<p> +The first directory protocol version combined the list of active relays +with server descriptors in a single directory document. +We stopped archiving version 1 directories in 2007. +</p> + +<br> +<h2 id="bridge-descriptors" class="hover">Tor Bridge Descriptors +<a href="#bridge-descriptors" class="anchor">#</a> +</h2> + +<p> +Bridges and the bridge authority publish bridge descriptors that are used +by censored clients to connect to the Tor network. +We cannot, however, make bridge descriptors available as we do with relay +descriptors, because that would defeat the purpose of making bridges hard +to enumerate for censors. +We therefore sanitize bridge descriptors by removing all potentially +identifying information and publish sanitized versions here. +The sanitizing steps are as follows: +</p> + +<ol> +<li><b>Replace bridge identities with their digests:</b> Clients +can request a bridge's current descriptor by sending its identity string +to the bridge authority. +This is a feature to make bridges on dynamic IP addresses useful. +Therefore, the original identities (and anything that could be used to +derive them) need to be removed from the descriptors. +The bridge's RSA-based identity fingerprint is replaced with its SHA-1 +hash value, and the bridge's optional base64-encoded Ed25519 master key is +replaced with its SHA-256 digest. +The idea is to have a consistent replacement that remains stable over +months or even years (without keeping a secret for a keyed hash +function).</li> +<li><b>Remove most cryptographic keys and signatures:</b> It would be +straightforward to learn about the bridge identity from the bridge's +public key. +Replacing keys by newly generated ones seemed to be unnecessary (and would +involve keeping a state over months/years), so that most cryptographic +keys and signatures have simply been removed.</li> +<li><b>Replace IP address with IP address hash:</b> Of course, IP +addresses need to be sanitized, too. +<ul><li>IPv4 addresses are replaced with <code>10.x.x.x</code> with +<code>x.x.x</code> being the 3 byte output of +<code>H(IP address | bridge identity | secret)[:3]</code>. +The input <code>IP address</code> is the 4-byte long binary representation of +the bridge's current IP address. +The <code>bridge identity</code> is the 20-byte long binary representation of +the bridge's long-term identity fingerprint. +The <code>secret</code> is a 31-byte long secure random string that changes +once per month for all descriptors and statuses published in that month. +<code>H()</code> is SHA-256. +The <code>[:3]</code> operator means that we pick the 3 most significant bytes +of the result.</li> +<li>IPv6 addresses are replaced with <code>[fd9f:2e19:3bcf::xx:xxxx]</code> +with <code>xx:xxxx</code> being the hex-formatted 3 byte output of a similar +hash function as described for IPv4 addresses. +The only differences are that the input <code>IP address</code> is 16 bytes +long and the <code>secret</code> is only 19 bytes long.</li></ul></li> +<li><b>Replace TCP port with TCP port hash:</b> It may be less obvious +that TCP ports need to be sanitized, but an unusual TCP port used by a +high-value bridge might still stand out and provide yet another way to +locate and block the bridge. +Therefore, each non-zero TCP port is replaced with a number in the range +from 49152 to 65535 that is the result of +<code>H(port | bridge identity | secret)[:2] / 2^2 + 2^15 + 2^14</code> +written as decimal number. +The input <code>port</code> is the 2-byte long binary representation of the +TCP port. +The <code>bridge identity</code> is the 20-byte long binary representation of +the bridge's long-term identity fingerprint. +The <code>secret</code> is a 33-byte long secure random string that changes +once per month for all descriptors and statuses published in that month. +<code>H()</code> is SHA-256. +The <code>[:2]</code> operator means that we pick the 2 most significant bytes +of the result. +The subsequent integer division and additions make sure that sanitized +ports are in the range from 49152 to 65535 which is reserved for private +services. +All operations assume inputs to be in network byte order. +TCP ports that are 0 in the original descriptor are left unchanged.</li> +<li><b>Replace contact information:</b> If there is contact information in +a descriptor, the contact line is changed to +<code>somebody</code>.</li> +<li><b>Remove pluggable transport addresses and arguments:</b> Bridges may +provide transports in addition to the onion-routing protocol and include +information about these transports in their extra-info descriptors for +BridgeDB. +In that case, any IP addresses, TCP ports, or additional arguments are +removed, only leaving in the supported transport names.</li> +<li><b>Append descriptor digests:</b> Descriptors are often referenced by +their digest, but that is not possible anymore once their content has +changed. +As a workaround, sanitized descriptors contain a new line +<code>router-digest</code> with the hex representation of the SHA-1 of the +original descriptor digest excluding RSA signature and—if the bridge +uses an Ed25519 identity—a new line <code>router-digest-sha256</code> +with the base64-encoded SHA-256 of the SHA-256 digest of the original +descriptor including all signatures.</li> +</ol> + +<h3 id="type-bridge-network-status" class="hover">Bridge Network Statuses +<small><code>@type bridge-network-status 1.1</code></small> +<a href="recent/bridge-descriptors/statuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/bridge-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-bridge-network-status" class="anchor">#</a> +</h3> + +<p> +Sanitized bridge network statuses are similar to version 2 relay network +statuses, but with only a <code>published</code> line in the header and +without any lines in the footer. +The format has changed over time to accomodate changes to the sanitizing +process, with earlier versions being: +</p> + +<ul> +<li><code>@type bridge-network-status 1.0</code> was the first version.</li> +<li><code>@type bridge-network-status 1.1</code> introduced sanitized TCP +ports.</li> +</ul> + +<h3 id="type-bridge-server-descriptor" class="hover">Bridge Server descriptors +<small><code>@type bridge-server-descriptor 1.2</code></small> +<a href="recent/bridge-descriptors/server-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/bridge-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-bridge-server-descriptor" class="anchor">#</a> +</h3> + +<p> +Bridge server descriptors follow the same format as relay server +descriptors, except for the sanitizing steps described above. +The bridge server descriptor archive tarballs contain one descriptor per +file, whereas recently published bridge server descriptor files +contain all descriptors collected in an hour concatenated into a single +file to reduce the number of files. +The format has changed over time to accomodate changes to the sanitizing +process, with earlier versions being: +</p> + +<ul> +<li><code>@type bridge-server-descriptor 1.0</code> was the first version.</li> +<li>There was supposed to be a newer version indicating added +<code>ntor-onion-key</code> lines, but due to a mistake only the version number +of sanitized bridge extra-info descriptors was raised. +As a result, there may be sanitized bridge server descriptors with version +<code>@type bridge-server-descriptor 1.0</code> with and without those +lines.</li> +<li><code>@type bridge-server-descriptor 1.1</code> added +<code>master-key-ed25519</code> lines and <code>router-digest-sha256</code> to +server descriptors published by bridges using an Ed25519 master +key.</li> +<li><code>@type bridge-server-descriptor 1.2</code> introduced sanitized TCP +ports.</li> +</ul> + +<h3 id="type-bridge-extra-info" class="hover">Bridge Extra-info Descriptors +<small><code>@type bridge-extra-info 1.3</code></small> +<a href="recent/bridge-descriptors/extra-infos/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/bridge-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-bridge-extra-info" class="anchor">#</a> +</h3> + +<p> +Bridge extra-info descriptors follow the same format as relay extra-info +descriptors, except for the sanitizing steps described above. +The format has changed over time to accomodate changes to the sanitizing +process, with earlier versions being: +</p> + +<ul> +<li><code>@type bridge-extra-info 1.0</code> was the first version.</li> +<li><code>@type bridge-extra-info 1.1</code> added sanitized +<code>transport</code> lines.</li> +<li><code>@type bridge-extra-info 1.2</code> was supposed to indicate added +<code>ntor-onion-key</code> lines, but those changes only affect bridge server +descriptors, not extra-info descriptors. +So, nothing has changed as compared to version 1.1.</li> +<li><code>@type bridge-extra-info 1.3</code> added <code>master-key-ed25519</code> +lines and <code>router-digest-sha256</code> to extra-info descriptors +published by bridges using an Ed25519 master key.</li> +</ul> + +<p> +The bridge extra-info descriptor archive tarballs contain one descriptor +per file, whereas recently published bridge extra-info descriptor +files contain all descriptors collected in an hour concatenated into a single +file to reduce the number of files. +</p> + +<br> +<h2 id="tor-hidden-service-descriptors" class="hover">Tor Hidden Service Descriptors +<a href="#tor-hidden-service-descriptors" class="anchor">#</a> +</h2> + +<p> +Tor hidden services make it possible for users to hide their locations +while offering various kinds of services, such as web publishing or an +instant messaging server. +A hidden service assembles a hidden service descriptor to make its service +available in the network. +This descriptor gets stored on hidden service directories and can be +retrieved by hidden service clients. +Hidden service descriptors are not formally archived, but some libraries +support parsing these descriptors when obtaining them from a locally +running Tor instance. +</p> + +<h3 id="type-hidden-service-descriptor" class="hover">Hidden Service Descriptors +<small><code>@type hidden-service-descriptor 1.0</code></small> +<a href="#type-hidden-service-descriptor" class="anchor">#</a> +</h3> + +<p> +Hidden service descriptors contain all details that are necessary for +clients to connect to a hidden service. +Despite the version number being 1.0, these descriptors are part of the +version 2 hidden service protocol. +</p> + +<br> +<h2 id="bridge-pool-assignments" class="hover">BridgeDB's Bridge Pool Assignments +<a href="#bridge-pool-assignments" class="anchor">#</a> +</h2> + +<p> +The bridge distribution service BridgeDB publishes bridge pool assignments +describing which bridges it has assigned to which distribution pool. +BridgeDB receives bridge network statuses from the bridge authority, +assigns these bridges to persistent distribution rings, and hands them out +to bridge users. +BridgeDB periodically dumps the list of running bridges with information +about the rings, subrings, and file buckets to which they are assigned to +a local file. +The sanitized versions of these lists containing SHA-1 hashes of bridge +fingerprints instead of the original fingerprints are available for +statistical analysis. +</p> + +<h3 id="type-bridge-pool-assignment" class="hover">Bridge Pool Assignments +<small><code>@type bridge-pool-assignment 1.0</code></small> +<a href="archive/bridge-pool-assignments/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-bridge-pool-assignment" class="anchor">#</a> +</h3> + +<p> +The document below shows a BridgeDB pool assignment file +from March 13, 2011. +Every such file begins with a line containing the timestamp when BridgeDB +wrote this file. +Subsequent lines start with the SHA-1 hash of a bridge fingerprint, +followed by ring, subring, and/or file bucket information. +There are currently three distributor ring types in BridgeDB: +</p> + +<ol> +<li><b>unallocated:</b> These bridges are not distributed by BridgeDB, +but are either reserved for manual distribution or are written to file +buckets for distribution via an external tool. +If a bridge in the <code>unallocated</code> ring is assigned to a file bucket, +this is noted by <code>bucket=$bucketname</code>.</li> +<li><b>email:</b> These bridges are distributed via an e-mail +autoresponder. Bridges can be assigned to subrings by their OR port or +relay flag which is defined by <code>port=$port</code> and/or <code>flag=$flag</code>. +</li> +<li><b>https:</b> These bridges are distributed via https server. +There are multiple https rings to further distribute bridges by IP address +ranges, which is denoted by <code>ring=$ring</code>. +Bridges in the <code>https</code> ring can also be assigned to subrings by +OR port or relay flag which is defined by <code>port=$port</code> and/or +<code>flag=$flag</code>.</li> +</ol> + +<pre> +bridge-pool-assignment 2011-03-13 14:38:03 +00b834117566035736fc6bd4ece950eace8e057a unallocated +00e923e7a8d87d28954fee7503e480f3a03ce4ee email port=443 flag=stable +0103bb5b00ad3102b2dbafe9ce709a0a7c1060e4 https ring=2 port=443 flag=stable +[...] +</pre> + +<p> +As of December 8, 2014, bridge pool assignment files are no longer +archived. +</p> + +<br> +<h2 id="exit-lists" class="hover">TorDNSEL's Exit Lists +<a href="#exit-lists" class="anchor">#</a> +</h2> + +<p> +The exit list service +<a href="https://www.torproject.org/tordnsel/dist/">TorDNSEL</a> +publishes exit lists containing the IP addresses of relays that it found +when exiting through them. +</p> + +<h3 id="type-tordnsel" class="hover">Exit Lists +<small><code>@type tordnsel 1.0</code></small> +<a href="recent/exit-lists/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/exit-lists/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-tordnsel" class="anchor">#</a> +</h3> + +<p> +Tor Check makes the list of known exits and corresponding exit IP +addresses available in a specific format. +The document below shows an entry of the exit list written on +December 28, 2010 at 15:21:44 UTC. +This entry means that the relay with fingerprint <code>63BA..</code> which +published a descriptor at 07:35:55 and was contained in a version 2 +network status from 08:10:11 uses two different IP addresses for exiting. +The first address <code>91.102.152.236</code> was found in a test performed at +07:10:30. +When looking at the corresponding server descriptor, one finds that this +is also the IP address on which the relay accepts connections from inside +the Tor network. +A second test performed at 10:35:30 reveals that the relay also uses IP +address <code>91.102.152.227</code> for exiting. +</p> + +<pre> +ExitNode 63BA28370F543D175173E414D5450590D73E22DC +Published 2010-12-28 07:35:55 +LastStatus 2010-12-28 08:10:11 +ExitAddress 91.102.152.236 2010-12-28 07:10:30 +ExitAddress 91.102.152.227 2010-12-28 10:35:30 +</pre> + +<br> +<h2 id="torperf" class="hover">Torperf's Performance Data +<a href="#torperf" class="anchor">#</a> +</h2> + +<p> +The performance measurement service Torperf publishes performance data +from making simple HTTP requests over the Tor network. +Torperf uses a trivial SOCKS client to download files of various sizes +over the Tor network and notes how long substeps take. +</p> + +<h3 id="type-torperf" class="hover">Torperf Measurement Results +<small><code>@type torperf 1.0</code></small> +<a href="recent/torperf/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> +<a href="archive/torperf/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> +<a href="#type-torperf" class="anchor">#</a> +</h3> + +<p> +A Torperf results file contains a single line per Torperf run with +<code>key=value</code> pairs. +Such a result line is sufficient to learn about 1) the Tor and Torperf +configuration, 2) measurement results, and 3) additional information that +might help explain the results. +Known keys are explained below. +</p> +<ul> +<li>Configuration +<ul> +<li><code>SOURCE:</code> Configured name of the data source; required.</li> +<li><code>FILESIZE:</code> Configured file size in bytes; required.</li> +<li>Other meta data describing the Tor or Torperf configuration, e.g., +GUARD for a custom guard choice; optional.</li> +</ul></li> +<li>Measurement results +<ul> +<li><code>START:</code> Time when the connection process starts; +required.</li> +<li><code>SOCKET:</code> Time when the socket was created; required.</li> +<li><code>CONNECT:</code> Time when the socket was connected; required.</li> +<li><code>NEGOTIATE:</code> Time when SOCKS 5 authentication methods have been +negotiated; required.</li> +<li><code>REQUEST:</code> Time when the SOCKS request was sent; required.</li> +<li><code>RESPONSE:</code> Time when the SOCKS response was received; +required.</li> +<li><code>DATAREQUEST:</code> Time when the HTTP request was written; +required.</li> +<li><code>DATARESPONSE:</code> Time when the first response was received; +required.</li> +<li><code>DATACOMPLETE:</code> Time when the payload was complete; +required.</li> +<li><code>WRITEBYTES:</code> Total number of bytes written; required.</li> +<li><code>READBYTES:</code> Total number of bytes read; required.</li> +<li><code>DIDTIMEOUT:</code> 1 if the request timed out, 0 otherwise; +optional.</li> +<li><code>DATAPERCx:</code> Time when x% of expected bytes were read for +x = { 10, 20, 30, 40, 50, 60, 70, 80, 90 }; optional.</li> +<li>Other measurement results, e.g., START_RENDCIRC, GOT_INTROCIRC, etc. +for hidden-service measurements; optional.</li> +</ul></li> +<li>Additional information +<ul> +<li><code>LAUNCH:</code> Time when the circuit was launched; optional.</li> +<li><code>USED_AT:</code> Time when this circuit was used; optional.</li> +<li><code>PATH:</code> List of relays in the circuit, separated by commas; +optional.</li> +<li><code>BUILDTIMES:</code> List of times when circuit hops were built, +separated by commas; optional.</li> +<li><code>TIMEOUT:</code> Circuit build timeout in milliseconds that the Tor +client used when building this circuit; optional.</li> +<li><code>QUANTILE:</code> Circuit build time quantile that the Tor client +uses to determine its circuit-build timeout; optional.</li> +<li><code>CIRC_ID:</code> Circuit identifier of the circuit used for this +measurement; optional.</li> +<li><code>USED_BY:</code> Stream identifier of the stream used for this +measurement; optional.</li> +<li>Other fields containing additional information; optional.</li> +</ul></li> +</ul> + +<p> +Recently published Torperf measurement result files accumulate +all new Torperf measurements of a given day, which means that +they may change throughout the day. +This is different from some of the other recently published files provided here +which do not change once they are +written. +</p> + + </div> + + <br> + + +<div class="container"> + <div class="row"> + <div class="col-xs-12"> + <br> + <h1 id="automated-downloads" class="hover">Automated Downloads +<a href="#automated-downloads" class="anchor">#</a> +</h1> +<p> +There are multiple ways to download descriptors from this site. +Of course, the obvious way is to browse the directories and download contained files using your browser. However, this method cannot be automated very well.</p> + +<h2 id="recursive-wget" class="hover">Recursive downloads using <code>wget</code> +<a href="#recursive-wget" class="anchor">#</a> +</h2> + +<p>A more elaborate way to automatically download descriptors is to use Unix tools like <code>wget</code> which support recursively downloading files from this site. Example:</p> +<pre> +wget --recursive \ # turn on recursive retrieving + --reject "index.html*" \ # don't retrieve directory listings + --no-parent \ # don't ascend to parent directory + --no-host-directories \ # don't generate host-prefixed directories + --directory-prefix descriptors \ # set directory prefix + https://collector.torproject.org/recent/relay-descriptors/microdescs/ +</pre> + +<h2 id="index-json" class="hover">Custom downloaders using provided <code>index.json</code> +<a href="#index-json" class="anchor">#</a></h2> + +<p>Another automated way to download descriptors is to develop a tool that uses the provided <a href="index/index.json"><code>index.json</code></a> file or one of its compressed versions <a href="index/index.json.gz"><code>index.json.gz</code></a>, <a href="index/index.json.bz2"><code>index.json.bz2</code></a>, or <a href="index/index.json.xz"><code>index.json.xz</code></a>. +These files contain a machine-readable representation of all descriptor files available on this site. +Index files use the following custom JSON data format that might still be extended at a later time:</p> +<ul> +<li>Index object: At the document root there is always an index object with the following fields: +<ul> +<li><code>"index_created"</code>: Timestamp when this index was created using pattern <code>"YYYY-MM-DD HH:MM"</code> in the UTC timezone.</li> +<li><code>"path"</code>: Base URL of this index file and all included resources.</li> +<li><code>"files"</code>: List of file objects of files available from the document root, which will be omitted if empty. +<li><code>"directories"</code>: List of directory objects of directories available from the document root, which will be omitted if empty.</li> +</ul></li> +<li>Directory object: There is one directory object for each directory or subdirectory in the document tree containing similar fields as the index object: +<ul> +<li><code>"path"</code>: Relative path of the directory.</li> +<li><code>"files"</code>: List of file objects of files available from this directory, which will be omitted if empty. +<li><code>"directories"</code>: List of directory objects of directories available from this directory, which will be omitted if empty.</li> +</ul></li> +<li>File object: Each file that is available in the document tree is represented by a file object with the following fields: +<ul> +<li><code>"path"</code>: Relative path of the file.</li> +<li><code>"size"</code>: Size of the file in bytes.</li> +<li><code>"last_modified"</code>: Timestamp when the file was last modified using pattern <code>"YYYY-MM-DD HH:MM"</code> in the UTC timezone.</li> +</ul></li> +</ul> + + </div><!-- col --> + </div><!-- row --> + + <br> + + + +</div> + + + + <div class="container-fluid" id="footer"> + + <div class="container no-gutter"> + <div class="col-xs-6"> + <p> + © 2017 The Tor Project + </p> + </div> + <div class="col-xs-6"> + <p class="pull-right"> + + <a href="https://metrics.torproject.org/about.html#contact">Contact</a> + + </p> + </div> + </div> + + <div class="container small"> + + <p>Data on this site is freely available under a <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 no copyright declaration</a>: To the extent possible under law, the Tor Project has waived all copyright and related or neighboring rights in the data. "Tor" and the "Onion Logo" are <a href="https://www.torproject.org/docs/trademark-faq.html.en">registered trademarks</a> of The Tor Project, Inc.</p> + + </div> + + </div><!-- /footer --> + + + +</div><!-- /wrapper --> + +</body> +</html> diff --git a/website/src/main/resources/web/WEB-INF/onionoo.jsp b/website/src/main/resources/web/WEB-INF/onionoo.jsp new file mode 100644 index 0000000..d8fe74a --- /dev/null +++ b/website/src/main/resources/web/WEB-INF/onionoo.jsp @@ -0,0 +1,2249 @@ +<!DOCTYPE HTML> +<html lang="en" style="min-height:100%;"> +<head> + + <title>Onionoo</title> + + <meta charset="utf-8"> + <link href="images/favicon.ico" type="image/x-icon" rel="shortcut icon"> + + <!-- yes, we're handheld friendly :) --> + <meta name="HandheldFriendly" content="True"> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"> + <meta name="apple-mobile-web-app-capable" content="yes"> + + <!-- icons for mobile devices --> + <link rel="apple-touch-icon" href="images/apple-touch-icon-152x152.png"> + <link rel="shortcut icon" href="images/android-icon.png" sizes="196x196"> + <meta name="msapplication-square70x70logo" content="images/smalltile.png"> + <meta name="msapplication-square150x150logo" content="images/mediumtile.png"> + <meta name="msapplication-wide310x150logo" content="images/widetile.png"> + <meta name="msapplication-square310x310logo" content="images/largetile.png"> + + <!-- jQuery --> + <script src="js/jquery-3.1.1.min.js"></script> + + <!-- Bootstrap --> + <link rel="stylesheet" href="css/bootstrap.min.css"> + <script src="js/bootstrap.min.js"></script> + + <!-- Fonts --> + <link rel="stylesheet" href="css/font-awesome.min.css"> + <link rel="stylesheet" href="fonts/source-sans-pro.css"> + + <!-- custom styles and javascript --> + <link rel="stylesheet" href="css/style.css"> + <script src="js/script.js"></script> + +</head> + +<body class="noscript" style="background-image:url(images/ajax-loader.gif);background-repeat:no-repeat;background-position:center center;"> + +<!-- Using evil inline stylesheets to hide the FOUC for slow connections... --> + +<div id="wrapper" style="display:none;"> + + +<!-- backToTop-Button and Anchor --> +<noscript> +<div class="topButton" style="display:block;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div> +</noscript> +<script type="text/javascript"> +document.write('<div class="topButton" style="display:none;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div>'); +</script> +<a id="top"></a> + + + +<!-- secondary navigation --> +<nav class="navbar navbar-default navbar-secondary"> + <div class="container-fluid visible-xs"> + <input type="checkbox" id="navbar-toggle-checkbox"> + <div class="navbar-header"> + <label for="navbar-toggle-checkbox" type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-secondary" aria-expanded="false"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </label> + <a class="navbar-brand visible-xs" href="/"><img src="images/onionoo-wordmark-white.png" width="221" height="40" alt="Onionoo"></a> + </div> + <!-- Collect the nav links, forms, and other content for toggling --> + <div class="collapse navbar-collapse" id="bs-example-navbar-secondary"> + <ul class="nav navbar-nav navbar-right"> + + + <!-- secondary navigation items --> + <li><a href="#general">General</a></li> + <li><a href="#versions">Protocol versions</a></li> + <li><a href="#methods">Methods</a></li> + <li><a href="#responses">Responses</a></li> + <li><a href="#summary">Summary documents</a></li> + <li><a href="#details">Details documents</a></li> + <li><a href="#history">History objects</a></li> + <li><a href="#bandwidth">Bandwidth documents</a></li> + <li><a href="#weights">Weights documents</a></li> + <li><a href="#clients">Clients documents</a></li> + <li><a href="#uptime">Uptime documents</a></li> + <li><a href="#examples">Example usage</a></li> + <!-- /secondary navigation items --> + + </ul> + </div><!-- /.navbar-collapse --> + + </div> +</nav> +<!-- /secondary navigation --> + + + +<!-- page header for every single page --> +<div class="page-header hidden-xs"> + <a href="/"><img src="images/tor-logo-weiss.png" width="162" height="100" alt="" id="onionoo-logo"></a> + <span style="display:inline-block;width:20px;"></span> + <a href="/"><img src="images/onionoo-wordmark-white.png" width="221" height="40" alt="Onionoo" id="onionoo-wordmark"></a> + <div> + <p> + <i>The Tor network status protocol providing the<br> + data for other applications and websites.</i> + </p> + </div> + <div class="clearfix"></div> +</div> +<!-- /page header --> + + + + + + <div class="container"> + + +<br><br> + + + + <div class="jumbotron"> + <div class="text-center"> + <h2> + The Tor network status protocol + </h2> + <p>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. </p> + <a class="btn btn-primary btn-lg" style="margin: 10px" href="#protocol"><i class="fa fa-chevron-right" aria-hidden="true"></i> Tell me more!</a> + + </div><!-- text-center --> + + + </div><!-- jumbotron --> + + + + + + +<br> + + + + + +<br> +<a id="protocol"></a> + + <!-- floating anchor box --> + <div class="col-md-4 pull-right hidden-xs" style="padding:1.2em 0 0 2em;"> + <div class="list-group"> + <h3>Table of contents</h3> + <a class="list-group-item" href="#general">General</a> + <a class="list-group-item" href="#versions">Protocol versions</a> + <a class="list-group-item" href="#methods">Methods</a> + <a class="list-group-item" href="#responses">Responses</a> + <a class="list-group-item" href="#summary">Summary documents</a> + <a class="list-group-item" href="#details">Details documents</a> + <a class="list-group-item" href="#history">History objects</a> + <a class="list-group-item" href="#bandwidth">Bandwidth documents</a> + <a class="list-group-item" href="#weights">Weights documents</a> + <a class="list-group-item" href="#clients">Clients documents</a> + <a class="list-group-item" href="#uptime">Uptime documents</a> + <a class="list-group-item" href="#examples">Example usage</a> + </div> + </div> + + +<h1>The Tor network status protocol <a href="#protocol" class="anchor">#</a></h1> + +<a id="general"></a><br> +<h2>General <a href="#general" class="anchor">#</a></h2> + +<p> +The Onionoo service is designed as a RESTful web service. +Onionoo clients send HTTP GET requests to the Onionoo server which +responds with JSON-formatted replies. +Onionoo clients and their developers should follow a few rules: +</p> + +<br> + +<h3>Compression</h3> +<p> +Clients should include an <strong>"Accept-Encoding: +gzip"</strong> header in their requests and handle gzip-compressed +responses. +Only requests starting at a certain size will be compressed by the +server. +</p> + +<br> + +<h3>Caching</h3> +<p>Clients should make use of the <strong>"Last-Modified"</strong> +header of responses and include that timestamp in a +<strong>"If-Modified-Since"</strong> header of subsequent requests. +</p> + +<br> + + + +<div class="clearfix"></div> + + +<h3>Response codes</h3> +<p> +Clients should handle response codes by +distinguishing between client and server errors, and if there's a problem, +informing their users about the kind of problem. +The following response codes are used: +</p> + +<ul class="properties"> + +<li> +<b>200 OK</b> +<p> +The request was processed successfully. +</p> +</li> + +<li> +<b>304 Not Modified</b> +<p> +Server data has not changed since the +<strong>"If-Modified-Since"</strong> header included in the request. +</p> +</li> + +<li> +<b>400 Bad Request</b> +<p> +The request for a known resource could not be processed because of bad +syntax. +This is most likely a client problem. +</p> +</li> + +<li> +<b>404 Not Available</b> +<p> +The request could not be processed because the requested resource could +not be found. +This is most likely a client problem. +</p> +</li> + +<li> +<b>500 Internal Server Error</b> +<p> +There is an unspecific problem with +the server which the service operator may not yet be aware of. +Please check if there's already a bug report for this problem, and if not, +file one. +</p> +</li> + +<li> +<b>503 Service Unavailable</b> +<p> +The server is temporarily down for +maintenance, or there is a temporary problem with the server that the +service operator is already aware of. +Only file a bug report if this problem persists. +</p> +</li> + +</ul> + + +<a id="versions"></a><br> +<h2>Protocol versions <a href="#versions" class="anchor">#</a></h2> +<p> +There are plenty of reasons why we may have +to change the protocol described here. +Clients should be able to handle all valid JSON responses, ignoring +unknown fields and not breaking horribly in case of missing fields. +Protocol changes will be announced here by writing deprecated API parts with +the label <span class="label label-warning">deprecated</span> and new parts +with the label <span class="label label-primary">new</span>. +Deprecated parts will be removed one month after their announcement. +</p> + +<p>All responses contain a <strong>"version"</strong> string that +indicates whether clients can parse the document or not. +Version strings consist of a major and a minor version number. +The major version number is raised when previously required fields are +dropped or turned into optional fields, when request parameters or +response documents are removed, or when there are structural changes. +The minor version number is raised when new fields, request parameters, or +response documents are added or optional fields are dropped. +If clients support the same major version given in a response but only a +lower minor version, they should be able to parse the document but may not +understand all fields. +If clients support a lower major version, they should not attempt to parse +a document, because there may be backward-incompatible changes.</p> + +<p>Responses may also contain the optional +<strong>"next_major_version_scheduled"</strong> field that announces when +the next major version is scheduled to be deployed. +Clients should inform their users that they should upgrade to the next +major protocol version before the provided date.</p> + +<p>The following versions have been used in the past six months or are +scheduled to be deployed in the next months:</p> + +<ul> +<li><strong>1.0</strong>: First assigned version number on August 31, +2014.</li> +<li><strong>1.1</strong>: Added optional "next_major_version_scheduled" +field on September 16, 2014.</li> +<li><strong>1.2</strong>: Added qualified search terms to "search" +parameter on October 17, 2014.</li> +<li><strong>2.0</strong>: Extended search parameter to base64-encoded +fingerprints on November 15, 2014.</li> +<li><strong>2.1</strong>: Removed optional "advertised_bandwidth_fraction" +field from details documents and optional "advertised_bandwidth" and +"advertised_bandwidth_fraction" fields from weights documents on November +16, 2014.</li> +<li><strong>2.2</strong>: Removed optional "pool_assignment" field and +added "transports" field to bridge details documents on December 8, +2014.</li> +<li><strong>2.3</strong>: Added optional "flags" field to uptime +documents on March 22, 2015.</li> +<li><strong>2.4</strong>: Added optional "effective_family" field to +details documents on July 3, 2015.</li> +<li><strong>2.5</strong>: Added optional "measured" field to details +documents on August 13, 2015.</li> +<li><strong>2.6</strong>: Added optional "alleged_family" and +"indirect_family" fields and deprecated optional "family" field in details +documents on August 25, 2015.</li> +<li><strong>3.0</strong>: Extended search parameter to match any 4 hex +characters of a space-separated fingerprint on November 15, 2015.</li> +<li><strong>3.1</strong>: Removed optional "family" field on January 18, +2016.</li> +<li><strong>3.2</strong>: Extended order parameter to "first_seen" and +added response meta data fields "relays_skipped", "relays_truncated", +"bridges_skipped", and "bridges_truncated" on January 27, 2017.</li> +<li><strong>4.0</strong>: Extended search parameter to not require +leading or enclosing square brackets around IPv6 addresses anymore on +February 28, 2017.</li> +</ul> + + + +<a id="methods"></a><br> +<h2>Methods <a href="#methods" class="anchor">#</a></h2> + +<p> +The following methods each return a single document containing zero or +more objects of relays and/or bridges. +By default, all relays and bridges are included that have been running in +the past week. +</p> + +<div class="responsive-table"> + <table class="table table-striped"> + <thead> + <tr> + <th class="method">Method</th> + <th class="url">URL</th> + <th class="description">Description</th> + </tr> + </thead> + <tbody> + <tr> + <td data-title="Method" >GET</td> + <td data-title="URL" >https://onionoo.torproject.org/summary</td> + <td data-title="Description" >returns a <a href="#summary">summary document</a></td> + </tr> + <tr> + <td data-title="Method" >GET</td> + <td data-title="URL" >https://onionoo.torproject.org/details</td> + <td data-title="Description" >returns a <a href="#details">details document</a></td> + </tr> + <tr> + <td data-title="Method" >GET</td> + <td data-title="URL" >https://onionoo.torproject.org/bandwidth</td> + <td data-title="Description" >returns a <a href="#bandwidth">bandwidth document</a></td> + </tr> + <tr> + <td data-title="Method" >GET</td> + <td data-title="URL" >https://onionoo.torproject.org/weights</td> + <td data-title="Description" >returns a <a href="#weights">weights document</a></td> + </tr> + <tr> + <td data-title="Method" >GET</td> + <td data-title="URL" >https://onionoo.torproject.org/clients</td> + <td data-title="Description" >returns a <a href="#clients">clients document</a></td> + </tr> + <tr> + <td data-title="Method" >GET</td> + <td data-title="URL" >https://onionoo.torproject.org/uptime</td> + <td data-title="Description" >returns an <a href="#uptime">uptime document</a></td> + </tr> + + </tbody> + </table> +</div> + + + +<h3>Parameters</h3> +<p> +Each of the methods can be parameterized to select only a subset of relay +and/or bridge documents that are currently running or that have been +running in the past week. +(The <strong>fingerprint</strong> parameter is special here, because it +allows selecting a specific relay or bridge, regardless of whether it has +been running in the past week.) +If multiple parameters are specified, they are combined using a logical +AND operation, meaning that only the intersection of relays and bridges +matching all parameters is returned. +If the same parameter is specified more than once, only the first +parameter value is considered. +</p> + +<ul class="properties"> + +<li> +<b>type</b> +<p> +Return only relay (parameter value +<strong>relay</strong>) or only bridge documents (parameter value +<strong>bridge</strong>). +Parameter values are case-insensitive. +</p> +</li> + +<li> +<b>running</b> +<p> +Return only running (parameter value +<strong>true</strong>) or only non-running relays and/or bridges +(paramter value +<strong>false</strong>). +Parameter values are case-insensitive. +</p> +</li> + +<li> +<b>search</b> +<p> +Return only (1) relays with the parameter value matching (part of a) +nickname, (possibly $-prefixed) beginning of a hex-encoded fingerprint, +any 4 hex characters of a space-separated fingerprint, beginning of a +base64-encoded fingerprint without trailing equal signs, or beginning of +an IP address (possibly enclosed in square brackets in case of IPv6), +(2) bridges with (part of a) nickname or (possibly +$-prefixed) beginning of a hashed hex-encoded fingerprint, and (3) relays +and/or bridges matching a given qualified search term. +Searches by relay IP address include all known addresses used for onion +routing and for exiting to the Internet. +Searches for beginnings of IP addresses are performed on textual +representations of canonical IP address forms, so that searches using CIDR +notation or non-canonical forms will return empty results. +Searches are case-insensitive, except for base64-encoded fingerprints. +If multiple search terms are given, separated by spaces, the intersection +of all relays and bridges matching all search terms will be returned. +Complete hex-encoded fingerprints should always be hashed using SHA-1, +regardless of searching for a relay or a bridge, in order to not +accidentally leak non-hashed bridge fingerprints in the URL. +Qualified search terms have the form "key:value" (without double quotes) +with "key" being one of the parameters listed here except for "search", +"fingerprint", "order", "limit", "offset", and "fields", and "value" being +the string that will internally be passed to that parameter. +</p> +</li> + +<li> +<b>lookup</b> +<p> +Return only the relay with the parameter +value matching the fingerprint or the bridge with the parameter value +matching the hashed fingerprint. +Fingerprints should always be hashed using SHA-1, regardless of looking up +a relay or a bridge, in order to not accidentally leak non-hashed bridge +fingerprints in the URL. +Lookups only work for full fingerprints or hashed fingerprints consisting +of 40 hex characters. +Lookups are case-insensitive. +</p> +</li> + +<li> +<b>fingerprint</b> +<p> +Return only the relay with the parameter value matching the fingerprint +or the bridge with the parameter value matching the hashed fingerprint. +Fingerprints must consist of 40 hex characters, case does not matter. +This parameter is quite similar to the <strong>lookup</strong> parameter +with two exceptions: +(1) the provided relay fingerprint or hashed bridge fingerprint <i>must +not</i> be hashed (again) using SHA-1; +(2) the response will contain any matching relay or bridge regardless of +whether they have been running in the past week. +</p> +</li> + +<li> +<b>country</b> +<p> +Return only relays which are located in the +given country as identified by a two-letter country code. +Filtering by country code is case-insensitive. +</p> +</li> + +<li> +<b>as</b> +<p> +Return only relays which are located in the +given autonomous system (AS) as identified by the AS number (with or +without preceding "AS" part). +Filtering by AS number is case-insensitive. +</p> +</li> + +<li> +<b>flag</b> +<p> +Return only relays which have the +given relay flag assigned by the directory authorities. +Note that if the flag parameter is specified more than once, only the +first parameter value will be considered. +Filtering by flag is case-insensitive. +</p> +</li> + +<li> +<b>first_seen_days</b> +<p> +Return only relays or bridges which +have first been seen during the given range of days ago. +A parameter value "x-y" with x <= y returns relays or bridges that have +first been seen at least x and at most y days ago. +Accepted short forms are "x", "x-", and "-y" which are interpreted as +"x-x", "x-infinity", and "0-y". +</p> +</li> + +<li> +<b>last_seen_days</b> +<p> +Return only relays or bridges which +have last been seen during the given range of days ago. +A parameter value "x-y" with x <= y returns relays or bridges that have +last been seen at least x and at most y days ago. +Accepted short forms are "x", "x-", and "-y" which are interpreted as +"x-x", "x-infinity", and "0-y". +Note that relays and bridges that haven't been running in the past week +are not included in results, so that setting x to 8 or higher will lead to +an empty result set. +</p> +</li> + +<li> +<b>contact</b> +<p> +Return only relays with the parameter value +matching (part of) the contact line. +If the parameter value contains spaces, only relays are returned which +contain all space-separated parts in their contact line. +Only printable ASCII characters are permitted in the parameter value, +some of which need to be percent-encoded (# as %23, % as %25, & as +%26, + as %2B, and / as %2F). +Comparisons are case-insensitive. +</p> +</li> + +<li> +<b>family</b> +<p> +Return only the relay whose fingerprint matches the parameter value and +all relays that this relay has listed in its family by fingerprint and +that in turn have listed this relay in their family by fingerprint. +If relays have listed other relays in their family by nickname, those +family relationships will not be considered, regardless of whether they +have the Named flag or not. +The provided relay fingerprint must consist of 40 hex characters where +case does not matter, and it must not be hashed using SHA-1. +Bridges are not contained in the result, regardless of whether they define +a family. +</p> +</li> + +</ul> + +<p> +Response documents can be reduced in size by requesting only a subset +of contained fields. +</p> + +<ul class="properties"> + +<li> +<b>fields</b> +<p> +Comma-separated list of fields that will be +included in the result. +So far, only top-level fields in relay or bridge objects of details +documents can be specified, e.g., +<strong>nickname,hashed_fingerprint</strong>. +If the fields parameter is provided, all other fields which are not +contained in the provided list will be removed from the result. +Field names are case-insensitive. +</p> +</li> + +</ul> + +<p> +Relay and/or bridge documents in the response can be ordered and +limited by providing further parameters. +If the same parameter is specified more than once, only the first +parameter value is considered. +</p> + +<ul class="properties"> + +<li> +<b>order</b> +<p> +Re-order results by a comma-separated list +of fields in ascending or descending order. +Results are first ordered by the first list element, then by the second, +and so on. +Possible fields for ordering are: <strong>consensus_weight</strong> and +<strong>first_seen</strong>. +Field names are case-insensitive. +Ascending order is the default; descending order is selected by prepending +fields with a minus sign (<strong>-</strong>). +Field names can be listed at most once in either ascending or descending +order. +Relays or bridges which don't have any value for a field to be ordered by +are always appended to the end, regardless or sorting order. +The ordering is defined independent of the requested document type and +does not require the ordering field to be contained in the document. +If no <strong>order</strong> parameter is given, ordering of results is +undefined. +</p> +</li> + +<li> +<b>offset</b> +<p> +Skip the given number of relays and/or +bridges. +Relays are skipped first, then bridges. +Non-positive <strong>offset</strong> values are treated as zero and don't +change the +result. +</p> +</li> + +<li> +<b>limit</b> +<p> +Limit result to the given number of +relays and/or bridges. +Relays are kept first, then bridges. +Non-positive <strong>limit</strong> values are treated as zero and lead +to an empty +result. +When used together with <strong>offset</strong>, the offsetting step +precedes the +limiting step. +</p> +</li> + +</ul> + + +<a id="responses"></a><br> +<h2>Responses <a href="#responses" class="anchor">#</a></h2> + +<p>Responses all have the same structure, regardless of requested +method and provided parameters. +Responses contain the following fields:</p> + +<ul class="properties"> + +<li> +<b>version</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +Onionoo protocol version string. +</p> +</li> + +<li> +<b>next_major_version_scheduled</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to +be deployed. +Omitted if no major protocol changes are planned. +</p> +</li> + +<li> +<b>relays_published</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known relay network +status consensus started being valid. +Indicates how recent the relay objects in this document are. +</p> +</li> + +<li> +<b>relays_skipped <span class="label label-primary">new</span></b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Number of skipped relays as requested by a positive "offset" parameter +value. +Omitted if zero. +<span class="blue">Added on January 27, 2017.</span> +</p> +</li> + +<li> +<b>relays</b> +<code class="typeof">array of objects</code> +<span class="required-true">required</span> +<p> +Array of relay objects as specified below. +</p> +</li> + +<li> +<b>relays_truncated <span class="label label-primary">new</span></b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Number of truncated relays as requested by a positive "limit" +parameter value. +Omitted if zero. +<span class="blue">Added on January 27, 2017.</span> +</p> +</li> + +<li> +<b>bridges_published</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when +the last known bridge network status was published. +Indicates how recent the bridge objects in this document are. +</p> +</li> + +<li> +<b>bridge_skipped <span class="label label-primary">new</span></b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Number of skipped bridges as requested by a positive "offset" +parameter value. +Omitted if zero. +<span class="blue">Added on January 27, 2017.</span> +</p> +</li> + +<li> +<b>bridges</b> +<code class="typeof">array of objects</code> +<span class="required-true">required</span> +<p> +Array of bridge objects as specified below. +</p> +</li> + +<li> +<b>bridges_truncated <span class="label label-primary">new</span></b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Number of truncated bridges as requested by a positive "limit" +parameter value. +Omitted if zero. +<span class="blue">Added on January 27, 2017.</span> +</p> +</li> + +</ul> + + +<a id="summary"></a><br> +<h2>Summary documents <a href="#summary" class="anchor">#</a> +<span class="request-response"> +<a href="summary?limit=4">example request</a> +</span> +</h2> + +<p>Summary documents contain short summaries of relays with nicknames, +fingerprints, IP addresses, and running information as well as bridges +with hashed fingerprints and running information.</p> + +<h3>Relay summary objects</h3> + +<p> +Relay summary objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>n</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Relay nickname consisting of 1–19 alphanumerical characters. +Omitted if the relay nickname is <strong>"Unnamed"</strong>. +</p> +</li> + +<li> +<b>f</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +Relay fingerprint consisting of 40 upper-case hexadecimal characters. +</p> +</li> + +<li> +<b>a</b> +<code class="typeof">array of strings</code> +<span class="required-true">required</span> +<p> +Array of IPv4 or IPv6 addresses where the relay accepts +onion-routing connections or which the relay used to exit to the Internet +in the past 24 hours. +The first address is the primary onion-routing address that the relay used +to register in the network, subsequent addresses are in arbitrary order. +IPv6 hex characters are all lower-case. +</p> +</li> + +<li> +<b>r</b> +<code class="typeof">boolean</code> +<span class="required-true">required</span> +<p> +Boolean field saying whether this relay was listed as +running in the last relay network status consensus. +</p> +</li> + +</ul> + +<h3>Bridge summary objects</h3> + +<p> +Bridge summary objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>n</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Bridge nickname consisting of 1–19 alphanumerical characters. +Omitted if the bridge nickname is <strong>"Unnamed"</strong>. +</p> +</li> + +<li> +<b>h</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +SHA-1 hash of the bridge fingerprint consisting of 40 +upper-case hexadecimal characters. +</p> +</li> + +<li> +<b>r</b> +<code class="typeof">boolean</code> +<span class="required-true">required</span> +<p> +Boolean field saying whether this bridge was listed as +running in the last bridge network status. +</p> +</li> + +</ul> + + +<a id="details"></a><br> +<h2>Details documents <a href="#details" class="anchor">#</a> +<span class="request-response"> +<a href="details?limit=4">example request</a> +</span> +</h2> + +<p> +Details documents are based on network statuses published by the Tor +directories, server descriptors published by relays and bridges, and data +published by Tor network services TorDNSEL and BridgeDB. +Details documents use the most recently published data from these sources, +which may lead to contradictions between fields based on different sources +in rare edge cases. +</p> + +<h3>Relay details objects</h3> + +<p> +Relay details objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>nickname</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Relay nickname consisting of 1–19 alphanumerical characters. +Omitted if the relay nickname is <strong>"Unnamed"</strong>. +</p> +</li> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +Relay fingerprint consisting of 40 upper-case +hexadecimal characters. +</p> +</li> + +<li> +<b>or_addresses</b> +<code class="typeof">array of strings</code> +<span class="required-true">required</span> +<p> +Array of IPv4 or IPv6 addresses and TCP ports +or port lists where the relay accepts onion-routing connections. +The first address is the primary onion-routing address that the relay used +to register in the network, subsequent addresses are in arbitrary order. +IPv6 hex characters are all lower-case. +</p> +</li> + +<li> +<b>exit_addresses</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of IPv4 or IPv6 addresses that the +relay used to exit to the Internet in the past 24 hours. +IPv6 hex characters are all lower-case. +Only those addresses are listed that are different from onion-routing +addresses. +Omitted if array is empty. +</p> +</li> + +<li> +<b>dir_address</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +IPv4 address and TCP port where the relay +accepts directory connections. +Omitted if the relay does not accept directory connections. +</p> +</li> + +<li> +<b>last_seen</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when this +relay was last seen in a network status consensus. +</p> +</li> + +<li> +<b>last_changed_address_or_port</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD +hh:mm:ss) when this relay last stopped announcing an IPv4 or IPv6 address +or TCP port where it previously accepted onion-routing or directory +connections. +This timestamp can serve as indicator whether this relay would be a +suitable fallback directory. +</p> +</li> + +<li> +<b>first_seen</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when this +relay was first seen in a network status consensus. +</p> +</li> + +<li> +<b>running</b> +<code class="typeof">boolean</code> +<span class="required-true">required</span> +<p> +Boolean field saying whether this relay was listed as +running in the last relay network status consensus. +</p> +</li> + +<li> +<b>hibernating</b> +<code class="typeof">boolean</code> +<span class="required-false">optional</span> +<p> +Boolean field saying whether this relay indicated that it is hibernating +in its last known server descriptor. +This information may be helpful to decide whether a relay that is not +running anymore has reached its accounting limit and has not dropped out +of the network for another, unknown reason. +Omitted if either the relay is not hibernating, or if no information is +available about the hiberation status of the relay. +</p> +</li> + +<li> +<b>flags</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of relay flags that the directory authorities +assigned to this relay. +May be omitted if empty. +</p> +</li> + +<li> +<b>country</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Two-letter lower-case country code as found in a +GeoIP database by resolving the relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the GeoIP +database. +</p> +</li> + +<li> +<b>country_name</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Country name as found in a GeoIP database by +resolving the relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the GeoIP +database, or if the GeoIP database did not contain a country name. +</p> +</li> + +<li> +<b>region_name</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Region name as found in a GeoIP database by +resolving the relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the GeoIP +database, or if the GeoIP database did not contain a region name. +</p> +</li> + +<li> +<b>city_name</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +City name as found in a +GeoIP database by resolving the relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the GeoIP +database, or if the GeoIP database did not contain a city name. +</p> +</li> + +<li> +<b>latitude</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Latitude as found in a GeoIP database by resolving +the relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the GeoIP +database. +</p> +</li> + +<li> +<b>longitude</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Longitude as found in a GeoIP database by +resolving the relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the GeoIP +database. +</p> +</li> + +<li> +<b>as_number</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +AS number as found in an AS database by +resolving the relay's first onion-routing IP address. +AS number strings start with "AS", followed directly by the AS number. +Omitted if the relay IP address could not be found in the AS +database. +</p> +</li> + +<li> +<b>as_name</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +AS name as found in an AS database by resolving the +relay's first onion-routing IP address. +Omitted if the relay IP address could not be found in the AS +database. +</p> +</li> + +<li> +<b>consensus_weight</b> +<code class="typeof">number</code> +<span class="required-true">required</span> +<p> +Weight assigned to this relay by the +directory authorities that clients use in their path selection algorithm. +The unit is arbitrary; currently it's kilobytes per second, but that might +change in the future. +</p> +</li> + +<li> +<b>host_name</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Host name as found in a reverse DNS lookup of the +relay IP address. +This field is updated at most once in 12 hours, unless the relay IP +address changes. +Omitted if the relay IP address was not looked up or if no lookup request +was successful yet. +</p> +</li> + +<li> +<b>last_restarted</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when the +relay was last (re-)started. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>bandwidth_rate</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Average bandwidth +in bytes per second that this relay is willing to sustain over long +periods. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>bandwidth_burst</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Bandwidth in bytes +per second that this relay is willing to sustain in very short intervals. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>observed_bandwidth</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Bandwidth +estimate in bytes per second of the capacity this relay can handle. +The relay remembers the maximum bandwidth sustained output over any ten +second period in the past day, and another sustained input. +The "observed_bandwidth" value is the lesser of these two numbers. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>advertised_bandwidth</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Bandwidth in bytes per second that this +relay is willing and capable to provide. +This bandwidth value is the minimum of <strong>bandwidth_rate</strong>, +<strong>bandwidth_burst</strong>, and <strong>observed_bandwidth</strong>. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>exit_policy</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of exit-policy lines. +Missing if router descriptor containing this information cannot be +found. +May contradict the <strong>"exit_policy_summary"</strong> field in a rare +edge case: this happens when the relay changes its exit policy after the +directory authorities summarized the previous exit policy. +</p> +</li> + +<li> +<b>exit_policy_summary</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Summary +version of the relay's exit policy containing a dictionary with either an +"accept" or a "reject" element. +If there is an "accept" ("reject") element, the relay accepts (rejects) +all TCP ports or port ranges in the given list for most IP addresses and +rejects (accepts) all other ports. +May contradict the <strong>"exit_policy"</strong> field in a rare edge +case: this happens when the relay changes its exit policy after the +directory authorities summarized the previous exit policy. +</p> +</li> + +<li> +<b>exit_policy_v6_summary</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Summary version of the relay's IPv6 exit policy containing a dictionary +with either an "accept" or a "reject" element. +If there is an "accept" ("reject") element, the relay accepts (rejects) +all TCP ports or port ranges in the given list for most IP addresses and +rejects (accepts) all other ports. +Missing if the relay rejects all connections to IPv6 addresses. +May contradict the <strong>"exit_policy_summary"</strong> field in a rare +edge case: this happens when the relay changes its exit policy after the +directory authorities summarized the previous exit policy. +</p> +</li> + +<li> +<b>contact</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Contact address of the relay operator. +Omitted if empty or if descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>platform</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Platform string containing operating system and Tor +version details. +Omitted if empty or if descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>recommended_version</b> +<code class="typeof">boolean</code> +<span class="required-false">optional</span> +<p> +Boolean field saying whether the Tor software version of this relay is +recommended by the directory authorities or not. +Omitted if either the directory authorities did not recommend versions, or +the relay did not report which version it runs. +</p> +</li> + +<li> +<b>effective_family</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of $-prefixed fingerprints of relays that are in an effective, +mutual family relationship with this relay. +These relays are part of this relay's family and they consider this relay +to be part of their family. +Omitted if empty or if descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>alleged_family</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of $-prefixed fingerprints of relays that are not in an effective, +mutual family relationship with this relay. +These relays are part of this relay's family but they don't consider this +relay to be part of their family. +Omitted if empty or if descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>indirect_family</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of $-prefixed fingerprints of relays that are not in an effective, +mutual family relationship with this relay but that can be reached by +following effective, mutual family relationships starting at this relay. +Omitted if empty or if descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>consensus_weight_fraction</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Fraction of this relay's consensus weight compared to the sum of all +consensus weights in the network. +This fraction is a very rough approximation of the probability of this +relay to be selected by clients. +Omitted if the relay is not running. +</p> +</li> + +<li> +<b>guard_probability</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Probability of this relay to be selected for the guard position. +This probability is calculated based on consensus weights, relay flags, +and bandwidth weights in the consensus. +Path selection depends on more factors, so that this probability can only +be an approximation. +Omitted if the relay is not running, or the consensus does not contain +bandwidth weights. +</p> +</li> + +<li> +<b>middle_probability</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Probability of this relay to be selected for the middle position. +This probability is calculated based on consensus weights, relay flags, +and bandwidth weights in the consensus. +Path selection depends on more factors, so that this probability can only +be an approximation. +Omitted if the relay is not running, or the consensus does not contain +bandwidth weights. +</p> +</li> + +<li> +<b>exit_probability</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Probability of this relay to be selected for the exit position. +This probability is calculated based on consensus weights, relay flags, +and bandwidth weights in the consensus. +Path selection depends on more factors, so that this probability can only +be an approximation. +Omitted if the relay is not running, or the consensus does not contain +bandwidth weights. +</p> +</li> + +<li> +<b>measured</b> +<code class="typeof">boolean</code> +<span class="required-false">optional</span> +<p> +Boolean field saying whether the consensus weight of this relay is based +on a threshold of 3 or more measurements by Tor bandwidth authorities. +Omitted if the network status consensus containing this relay does not +contain measurement information. +</p> +</li> + +</ul> + +<h3>Bridge details objects</h3> + +<p> +Bridge details objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>nickname</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Bridge nickname consisting of 1–19 +alphanumerical characters. +Omitted if the bridge nickname is <strong>"Unnamed"</strong>. +</p> +</li> + +<li> +<b>hashed_fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +SHA-1 hash of the bridge fingerprint +consisting of 40 upper-case hexadecimal characters. +</p> +</li> + +<li> +<b>or_addresses</b> +<code class="typeof">array of strings</code> +<span class="required-true">required</span> +<p> +Array of sanitized IPv4 or IPv6 addresses and +TCP ports or port lists where the bridge accepts onion-routing +connections. +The first address is the primary onion-routing address that the bridge +used to register in the network, subsequent addresses are in arbitrary +order. +IPv6 hex characters are all lower-case. +Sanitized IP addresses are always in <strong>10/8</strong> or +<strong>[fd9f:2e19:3bcf/48]</strong> IP networks and are only useful to +learn which +IP version the bridge uses and to detect whether the bridge changed its +address. +Sanitized IP addresses always change on the 1st of every month at 00:00:00 +UTC, regardless of the bridge actually changing its IP address. +TCP ports are not sanitized. +</p> +</li> + +<li> +<b>last_seen</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when this +bridge was last seen in a bridge network status. +</p> +</li> + +<li> +<b>first_seen</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when this +bridge was first seen in a bridge network status. +</p> +</li> + +<li> +<b>running</b> +<code class="typeof">boolean</code> +<span class="required-true">required</span> +<p> +Boolean field saying whether this bridge was listed +as running in the last bridge network status. +</p> +</li> + +<li> +<b>flags</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of relay flags that the bridge authority +assigned to this bridge. +May be omitted if empty. +</p> +</li> + +<li> +<b>last_restarted</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) when the +bridge was last (re-)started. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>advertised_bandwidth</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Bandwidth in bytes per second that this +bridge is willing and capable to provide. +This bandwidth value is the minimum of <strong>bandwidth_rate</strong>, +<strong>bandwidth_burst</strong>, and <strong>observed_bandwidth</strong>. +Missing if router descriptor containing this information cannot be +found. +</p> +</li> + +<li> +<b>platform</b> +<code class="typeof">string</code> +<span class="required-false">optional</span> +<p> +Platform string containing operating system and Tor +version details. +Omitted if not provided by the bridge or if descriptor containing this +information cannot be found. +</p> +</li> + +<li> +<b>transports</b> +<code class="typeof">array of strings</code> +<span class="required-false">optional</span> +<p> +Array of (pluggable) transport names supported by this bridge. +</p> +</li> + +</ul> + + +<a id="history"></a><br> +<h2>History objects <a href="#history" class="anchor">#</a></h2> + +<p> +History objects are no documents by themselves, but are contained in +subsequent documents. +<p> + +<h3>Graph history objects</h3> + +<p> +Graph history objects contain the following fields: +</p> + +<ul class="properties"> + +<li> +<b>first</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) of the first data point, or more +specifically the interval midpoint of the first interval. +</p> +</li> + +<li> +<b>last</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +UTC timestamp (YYYY-MM-DD hh:mm:ss) of the last data point, or more +specifically the interval midpoint of the last interval. +</p> +</li> + +<li> +<b>interval</b> +<code class="typeof">number</code> +<span class="required-true">required</span> +<p> +Time interval between two data points in seconds. +</p> +</li> + +<li> +<b>factor</b> +<code class="typeof">number</code> +<span class="required-true">required</span> +<p> +Factor by which subsequent data values need to be multiplied to obtain +original values. +The idea is to reduce document size while still providing sufficient +detail for very different data scales. +</p> +</li> + +<li> +<b>count</b> +<code class="typeof">number</code> +<span class="required-false">optional</span> +<p> +Number of provided data points, included mostly for debugging purposes. +Can also be derived from the number of elements in the subsequent array. +</p> +</li> + +<li> +<b>values</b> +<code class="typeof">array of numbers</code> +<span class="required-true">required</span> +<p> +Array of normalized values between 0 and 999. +May contain null values. +Contains at least two subsequent non-null values to enable drawing of line +graphs. +</p> +</li> + +</ul> + + +<a id="bandwidth"></a><br> +<h2>Bandwidth documents <a href="#bandwidth" class="anchor">#</a> +<span class="request-response"> +<a href="bandwidth?limit=4">example request</a> +</span> +</h2> + +<p> +Bandwidth documents contain aggregate statistics of a relay's or +bridge's consumed bandwidth for different time intervals. +Bandwidth documents are only updated when a relay or bridge publishes a +new server descriptor, which may take up to 18 hours during normal +operation. +</p> + +<h3>Relay bandwidth objects</h3> + +<p> +Relay bandwidth objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +Relay fingerprint consisting of 40 upper-case +hexadecimal characters. +</p> +</li> + +<li> +<b>write_history</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing graph history objects with written bytes for different +time periods. +Keys are string representation of the time period covered by the graph +history object. +Keys are fixed strings <strong>"3_days"</strong>, +<strong>"1_week"</strong>, <strong>"1_month"</strong>, +<strong>"3_months"</strong>, <strong>"1_year"</strong>, and +<strong>"5_years"</strong>. +Keys refer to the last known bandwidth history of a relay, not to the time +when the bandwidth document was published. +A graph history object is only contained if the time period it covers is +not already contained in another graph history object with shorter time +period and higher data resolution. +Similarly, a graph history object is excluded if the relay did not provide +bandwidth histories on the required level of detail. +The unit is bytes per second. +Contained graph history objects may contain null values if the relay did +not provide any bandwidth data or only data for less than 20% of a given +time period. +</p> +</li> + +<li> +<b>read_history</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing graph history objects with read bytes for different time +periods. +The specification of graph history objects is similar to those in the +<strong>write_history</strong> field. +</p> +</li> + +</ul> + +<h3>Bridge bandwidth objects</h3> + +<p> +Bridge bandwidth objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +SHA-1 hash of the bridge fingerprint consisting +of 40 upper-case hexadecimal characters. +</p> +</li> + +<li> +<b>write_history</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing graph history objects with written bytes for different +time periods. +The specification of graph history objects is similar to those in the +<strong>write_history</strong> field of <strong>relays</strong>. +</p> +</li> + +<li> +<b>read_history</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing graph history objects with read bytes for different time +periods. +The specification of graph history objects is similar to those in the +<strong>write_history</strong> field of <strong>relays</strong>. +</p> +</li> + +</ul> + + +<a id="weights"></a><br> +<h2>Weights documents <a href="#weights" class="anchor">#</a> +<span class="request-response"> +<a href="weights?limit=4">example request</a> +</span> +</h2> + +<p> +Weights documents contain aggregate statistics of a relay's probability +to be selected by clients for building paths. +Weights documents contain different time intervals and are available for +relays only. +</p> + +<h3>Relay weights objects</h3> + +<p> +Relay weights objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +Relay fingerprint consisting of 40 upper-case +hexadecimal characters. +</p> +</li> + +<li> +<b>consensus_weight_fraction</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +History object containing the +fraction of this relay's consensus weight compared to the sum of all +consensus weights in the network. +This fraction is a very rough approximation of the probability of this +relay to be selected by clients. +Keys are string representation of the time period covered by the graph +history object. +Keys are fixed strings <strong>"1_week"</strong>, +<strong>"1_month"</strong>, <strong>"3_months"</strong>, +<strong>"1_year"</strong>, and <strong>"5_years"</strong>. +Keys refer to the last known weights history of a relay, not to the time +when the weights document was published. +A graph history object is only contained if the time period it covers is +not already contained in another graph history object with shorter time +period and higher data resolution. +The unit is path-selection probability. +Contained graph history objects may contain null values if the relay was +running less than 20% of a given time period. +</p> +</li> + +<li> +<b>guard_probability</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +History object containing the probability +of this relay to be selected for the guard position. +This probability is calculated based on consensus weights, relay flags, +and bandwidth weights in the consensus. +Path selection depends on more factors, so that this probability can only +be an approximation. +The specification of this history object is similar to that in the +<strong>consensus_weight_fraction</strong> field above. +</p> +</li> + +<li> +<b>middle_probability</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +History object containing the probability +of this relay to be selected for the middle position. +This probability is calculated based on consensus weights, relay flags, +and bandwidth weights in the consensus. +Path selection depends on more factors, so that this probability can only +be an approximation. +The specification of this history object is similar to that in the +<strong>consensus_weight_fraction</strong> field above. +</p> +</li> + +<li> +<b>exit_probability</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +History object containing the probability +of this relay to be selected for the exit position. +This probability is calculated based on consensus weights, relay flags, +and bandwidth weights in the consensus. +Path selection depends on more factors, so that this probability can only +be an approximation. +The specification of this history object is similar to that in the +<strong>consensus_weight_fraction</strong> field above. +</p> +</li> + +<li> +<b>consensus_weight</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +History object containing the absolute consensus weight of this relay. +The specification of this history object is similar to that in the +<strong>consensus_weight_fraction</strong> field above. +</p> +</li> + +</ul> + + +<a id="clients"></a><br> +<h2>Clients documents <a href="#clients" class="anchor">#</a> +<span class="request-response"> +<a href="clients?limit=4">example request</a> +</span> +</h2> + +<p> +Clients documents contain estimates of the average number of clients +connecting to a bridge every day. +There are no clients documents available for relays, just for bridges. +Clients documents contain different time intervals and are available for +bridges only. +</p> + +<h3>Bridge clients objects</h3> + +<p> +Bridge clients objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +SHA-1 hash of the bridge fingerprint consisting +of 40 upper-case hexadecimal characters. +</p> +</li> + +<li> +<b>average_clients</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing graph history objects with the average number of clients +connecting to this bridge. +Keys are string representation of the time period covered by the graph +history object. +Keys are fixed strings <strong>"1_week"</strong>, +<strong>"1_month"</strong>, <strong>"3_months"</strong>, +<strong>"1_year"</strong>, and <strong>"5_years"</strong>. +Keys refer to the last known clients history of a bridge, not to the time +when the clients document was published. +A graph history object is only contained if the time period it covers +is not already contained in another clients graph object with shorter +time period and higher data resolution. +The unit is number of clients. +Contained graph history objects may contain null values if the bridge did +not report client statistics for at least 50% of a given time period. +Each graph history object contains the following additional key-value +pairs: +</p> + +<ul class="properties"> + +<li> +<b>countries <span class="label label-danger">beta</span></b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing fractions of clients by country in the considered time +period. +Keys are two-letter lower-case country codes as found in a GeoIP database. +Values are numbers between 0 and 1 standing for the fraction of clients by +country. +A country is only included if at least 1% of clients came from this +country. +Omitted if the bridge did not report client statistics by country. +<span class="red"><strong>BETA:</strong> This field breaks compatibility +with the history objects contained in other documents pretty badly. +It might be removed in the future without notice.</span> +</p> +</li> + +<li> +<b>transports <span class="label label-danger">beta</span></b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing fractions of clients by transport in the considered time +period. +Keys are transport names, or <strong>"<OR>"</strong> for the default +onion-routing transport protocol. +Values are numbers between 0 and 1 standing for the fraction of clients by +transport. +Omitted if the bridge did not report client statistics by transport. +<span class="red"><strong>BETA:</strong> This field breaks compatibility +with the history objects contained in other documents pretty badly. +It might be removed in the future without notice.</span> +</p> +</li> + +<li> +<b>versions <span class="label label-danger">beta</span></b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing fractions of clients by IP version in the considered +time period. +Keys are either <strong>"v4"</strong> for IPv4 or <strong>"v6"</strong> +for IPv6. +Values are numbers between 0 and 1 standing for the fraction of clients by +version. +Omitted if the bridge did not report client statistics by IP version. +<span class="red"><strong>BETA:</strong> This field breaks compatibility +with the history objects contained in other documents pretty badly. +It might be removed in the future without notice.</span> +</p> +</li> + +</ul> + +</li> + +</ul> + + +<a id="uptime"></a><br> +<h2>Uptime documents <a href="#uptime" class="anchor">#</a> +<span class="request-response"> +<a href="uptime?limit=4">example request</a> +</span> +</h2> + +<p> +Uptime documents contain fractional uptimes of relays and bridges. +Uptime documents contain different time intervals and are available for +relays and bridges. +</p> + +<h3>Relay uptime objects</h3> + +<p> +Relay uptime objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +Relay fingerprint consisting of 40 upper-case +hexadecimal characters. +</p> +</li> + +<li> +<b>uptime</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing graph history objects with the fractional uptime of this +relay. +Keys are string representation of the time period covered by the graph +history object. +Keys are fixed strings <strong>"1_week"</strong>, +<strong>"1_month"</strong>, <strong>"3_months"</strong>, +<strong>"1_year"</strong>, and <strong>"5_years"</strong>. +Keys refer to the last known uptime history of a relay, not to the time +when the uptime document was published. +A graph history object is only contained if the time period it covers is +not already contained in another graph history object with shorter time +period and higher data resolution. +The unit is fractional uptime from 0 to 1. +Contained graph history objects may contain null values if less than 20% +of network statuses have been processed for a given time period. +</p> +</li> + +<li> +<b>flags</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing fractional times of this relay having relay flags +assigned. +Keys are flag names like <strong>"Running"</strong> or +<strong>"Exit"</strong>, values are objects similar to the +<strong>uptime</strong> field above, again with keys like +<strong>"1_week"</strong> etc. +If a relay never had a given relay flag assigned, no object is included +for that flag. +</p> +</li> + +</ul> + +<h3>Bridge uptime objects</h3> + +<p> +Bridge uptime objects contain the following key-value pairs: +</p> + +<ul class="properties"> + +<li> +<b>fingerprint</b> +<code class="typeof">string</code> +<span class="required-true">required</span> +<p> +SHA-1 hash of the bridge fingerprint consisting +of 40 upper-case hexadecimal characters. +</p> +</li> + +<li> +<b>uptime</b> +<code class="typeof">object</code> +<span class="required-false">optional</span> +<p> +Object containing uptime history objects for different time periods. +The specification of uptime history objects is similar to those in the +<strong>uptime</strong> field of <strong>relays</strong>. +</p> +</li> + +</ul> + + +<a id="examples"></a><br> +<h2>Example usage <a href="#examples" class="anchor">#</a> +</h2> + +<p> +The following examples illustrate how to build requests for some trivial +and some more complex use cases. +While Onionoo is designed mainly for developers and not end users, there +may be cases when it's easier to quickly write a specific query Onionoo +rather than to find an Onionoo client that provides the desired +information. +</p> + +<p> +<code>/summary?limit=4</code> +(<a href="/summary?limit=4">view result</a>) +</p> + +<p> +This first query returns the first four summary documents that Onionoo can +find. +The <code>limit</code> parameter should always be used while developing +new queries to avoid downloading huge responses. +</p> + +<p> +<code>/summary?limit=4&search=moria</code> +(<a href="/summary?limit=4&search=moria">view result</a>) +</p> + +<p> +The second query restricts results to relays and bridges containing the +string "moria" in one of a few searched fields. +</p> + +<p> +<code>/details?limit=4&search=moria</code> +(<a href="/details?limit=4&search=moria">view result</a>) +</p> + +<p> +The third query switches from the short summary documents to the longer +details documents containing, well, more details. +</p> + +<p> +<code>/details?limit=4&search=moria&fields=nickname</code> +(<a href="/details?limit=4&search=moria&fields=nickname">view result</a>) +</p> + +<p> +The fourth query adds the <code>fields</code> parameter which removes all +fields except the specified ones from the result. +This parameter is only implemented for details documents. +</p> + +<p> +<code>/details?limit=4&search=moria&fields=nickname&order=-consensus_weight</code> +(<a href="/details?limit=4&search=moria&fields=nickname&order=-consensus_weight">view result</a>) +</p> + +<p> +The fifth query sorts results by relay consensus weight from largest to +smallest. +</p> + +<p> +Obviously, this query can be made even more complex by adding more +parameters, and in some cases this is necessary and useful. +Please refer to the protocol specification for details. +</p> + + + +</div> + + + + + + + + + <div class="container-fluid" id="footer"> + + <div class="container no-gutter"> + <div class="col-xs-6"> + <p> + © 2017 The Tor Project + </p> + </div> + <div class="col-xs-6"> + <p class="pull-right"> + + <a href="https://metrics.torproject.org/about.html#contact">Contact</a> + + </p> + </div> + </div> + + <div class="container small"> + + <p>Data on this site is freely available under a <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 no copyright declaration</a>: To the extent possible under law, the Tor Project has waived all copyright and related or neighboring rights in the data. "Tor" and the "Onion Logo" are <a href="https://www.torproject.org/docs/trademark-faq.html.en">registered trademarks</a> of The Tor Project, Inc.</p> + + </div> + + </div><!-- /footer --> + + + +</div><!-- /wrapper --> + +</body> +</html> + diff --git a/website/src/main/resources/web/collector.html b/website/src/main/resources/web/collector.html deleted file mode 100644 index 07d6f99..0000000 --- a/website/src/main/resources/web/collector.html +++ /dev/null @@ -1,940 +0,0 @@ -<!DOCTYPE html> -<html lang="en" style="min-height:100%;"> - <head> - - <title>CollecTor</title> - - <meta charset="utf-8"> - <link href="images/favicon.ico" type="image/x-icon" rel="shortcut icon"> - - <!-- yes, we're handheld friendly :) --> - <meta name="HandheldFriendly" content="True"> - <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"> - <meta name="apple-mobile-web-app-capable" content="yes"> - - <!-- icons for mobile devices --> - <link rel="apple-touch-icon" href="images/apple-touch-icon-152x152.png"> - <link rel="shortcut icon" href="images/android-icon.png" sizes="196x196"> - <meta name="msapplication-square70x70logo" content="images/smalltile.png"> - <meta name="msapplication-square150x150logo" content="images/mediumtile.png"> - <meta name="msapplication-wide310x150logo" content="images/widetile.png"> - <meta name="msapplication-square310x310logo" content="images/largetile.png"> - - <!-- jQuery --> - <script src="js/jquery-3.1.1.min.js"></script> - - <!-- Bootstrap --> - <link rel="stylesheet" href="css/bootstrap.min.css"> - <script src="js/bootstrap.min.js"></script> - - <!-- Fonts --> - <link rel="stylesheet" href="css/font-awesome.min.css"> - <link rel="stylesheet" href="fonts/source-sans-pro.css"> - - <!-- custom styles and javascript --> - <link rel="stylesheet" href="css/style.css"> - <script src="js/script.js"></script> - - </head> - -<body class="noscript" style="background-image:url(images/ajax-loader.gif);background-repeat:no-repeat;background-position:center center;"> - -<!-- Using evil inline stylesheets to hide the FOUC for slow connections... --> - -<div id="wrapper" style="display:none;"> - - -<!-- backToTop-Button and Anchor --> -<noscript> -<div class="topButton" style="display:block;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div> -</noscript> -<script type="text/javascript"> -document.write('<div class="topButton" style="display:none;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div>'); -</script> -<a id="top"></a> - - - -<!-- secondary navigation --> -<nav class="navbar navbar-default navbar-secondary"> -<div class="container-fluid"> - <input type="checkbox" id="navbar-toggle-checkbox"> - <div class="navbar-header"> - <a class="navbar-brand visible-xs" href="/"><img src="images/collector-wordmark-white.png" width="264" height="50" alt="CollecTor"></a> - </div> - - </div> -</nav> -<!-- /secondary navigation --> - - - -<!-- page header for every single page --> -<div class="page-header hidden-xs"> - <a href="/"><img src="images/collector-logo.png" width="143" height="117" alt="" id="collector-logo"></a> - <a href="/"><img src="images/collector-wordmark-white.png" width="264" height="50" alt="CollecTor" id="collector-wordmark"></a> - <div> - <p> - <i>Your friendly data-collecting<br> - service in the Tor network.</i> - </p> - </div> - <div class="clearfix"></div> -</div> -<!-- /page header --> - - <div class="container"> - <div class="row"> - <div class="col-xs-12"> - - <br><br> - - <div class="jumbotron"> - <div class="text-center"> - - <h2> - Welcome to CollecTor, your friendly data-collecting service in the Tor network - </h2> - <p> - CollecTor fetches data from various - nodes and services in the public Tor network and makes it - available to the world. If you're doing research on the Tor - network, or if you're developing an application that uses - Tor network data, this is your place to start. - </p> -<a class="btn btn-primary btn-lg" style="margin: 10px" href="recent/"><i class="fa fa-chevron-right" aria-hidden="true"></i> Browse Recent Descriptors</a> -<a class="btn btn-primary btn-lg" style="margin: 10px" href="archive/"><i class="fa fa-chevron-right" aria-hidden="true"></i> Browse Archived Descriptors</a> - </div><!-- text-center --> - - - </div><!-- jumbotron --> - - </div><!-- col --> - </div><!-- row --> - - <div class="row"> - <div class="col-xs-12"> - <br> - <h1 id="available-descriptors" class="hover">Available Descriptors -<a href="#available-descriptors" class="anchor">#</a></h1> - -<p>Descriptors are available in two different file formats: recent descriptors that were published in the last 72 hours are available as plain text, and archived descriptors covering over 10 years of Tor network history are available as compressed tarballs.</p> - -<table class="table"> -<thead> -<tr> -<th>Descriptor Type</th> -<th>Type Annotation</th> -<th class="thDescriptors">Descriptors</th> -</tr> -</thead> -<tbody> -<tr class="tableHeadline"> - <td colspan="3"><b><a href="#relay-descriptors">Tor Relay Descriptors</a></b></td> -</tr> -<tr> - <td><a href="#type-server-descriptor">Relay Server Descriptors</a></td> - <td><code>@type server-descriptor 1.0</code></td> - <td><a href="recent/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-extra-info">Relay Extra-info Descriptors</a></td> - <td><code>@type extra-info 1.0</code></td> - <td><a href="recent/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-network-status-consensus-3">Network Status Consensuses</a></td> - <td><code>@type network-status-consensus-3 1.0</code></td> - <td><a href="recent/relay-descriptors/consensuses/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/relay-descriptors/consensuses/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-network-status-vote-3">Network Status Votes</a></td> - <td><code>@type network-status-vote-3 1.0</code></td> - <td><a href="recent/relay-descriptors/votes/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/relay-descriptors/votes/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-dir-key-certificate-3">Directory Key Certificates</a></td> - <td><code>@type dir-key-certificate-3 1.0</code></td> - <td><a href="archive/relay-descriptors/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-network-status-microdesc-consensus-3">Microdescriptor Consensuses</a></td> - <td><code>@type network-status-microdesc-consensus-3 1.0</code></td> - <td><a href="recent/relay-descriptors/microdescs/consensus-microdesc/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-microdescriptor">Microdescriptors</a></td> - <td><code>@type microdescriptor 1.0</code></td> - <td><a href="recent/relay-descriptors/microdescs/micro/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-network-status-2">Version 2 Network Statuses</a></td> - <td><code>@type network-status-2 1.0</code></td> - <td><a href="archive/relay-descriptors/statuses/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-directory">Version 1 Directories</a></td> - <td><code>@type directory 1.0</code></td> - <td><a href="archive/relay-descriptors/tor/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr class="tableHeadline"> - <td colspan="3"><b><a href="#bridge-descriptors">Tor Bridge Descriptors</a></b></td> -</tr> -<tr> - <td><a href="#type-bridge-network-status">Bridge Network Statuses</a></td> - <td><code>@type bridge-network-status 1.1</code></td> - <td><a href="recent/bridge-descriptors/statuses/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/bridge-descriptors/statuses/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-bridge-server-descriptor">Bridge Server Descriptors</a></td> - <td><code>@type bridge-server-descriptor 1.2</code></td> - <td><a href="recent/bridge-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/bridge-descriptors/server-descriptors/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr> - <td><a href="#type-bridge-extra-info">Bridge Extra-info Descriptors</a></td> - <td><code>@type bridge-extra-info 1.3</code></td> - <td><a href="recent/bridge-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/bridge-descriptors/extra-infos/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr class="tableHeadline"> - <td colspan="3"><b><a href="#tor-hidden-service-descriptors">Tor Hidden Service Descriptors</a></b></td> -</tr> -<tr> - <td><a href="#type-hidden-service-descriptor">Hidden Service Descriptors</a></td> - <td><code>@type hidden-service-descriptor 1.0</code></td> - <td></td> -</tr> -<tr class="tableHeadline"> - <td colspan="3"><b><a href="#bridge-pool-assignments">BridgeDB's Bridge Pool Assignments</a></b></td> -</tr> -<tr> - <td><a href="#type-bridge-pool-assignment">Bridge Pool Assignments</a></td> - <td><code>@type bridge-pool-assignment 1.0</code></td> - <td><a href="archive/bridge-pool-assignments/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr class="tableHeadline"> - <td colspan="3"><b><a href="#exit-lists">TorDNSEL's Exit Lists</a></b></td> -</tr> -<tr> - <td><a href="#type-tordnsel">Exit Lists</a></td> - <td><code>@type tordnsel 1.0</code></td> - <td><a href="recent/exit-lists/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/exit-lists/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -<tr class="tableHeadline"> - <td colspan="3"><b><a href="#torperf">Torperf's Performance Data</a></b></td> -</tr> -<tr> - <td><a href="#type-torperf">Torperf Measurement Results</a></td> - <td><code>@type torperf 1.0</code></td> - <td><a href="recent/torperf/" class="btn btn-primary btn-xs pull-left"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> - <a href="archive/torperf/" class="btn btn-primary btn-xs pull-right"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a></td> -</tr> -</tbody> -</table> - - </div><!-- col --> - </div><!-- row --> -<br> - - - - - <br> - <h1 id="data-formats" class="hover">Data Formats <a href="#data-formats" class="anchor">#</a></h1> - -<p> -Each descriptor provided here contains an <code>@type</code> annotation using -the format <code>@type $descriptortype $major.$minor</code>. -Any tool that processes these descriptors may parse files without meta -data or with an unknown descriptor type at its own risk, can safely parse -files with known descriptor type and same major version number, and should -not parse files with known descriptor type and higher major version -number. -</p> -</div> - - - <div class="container"> - -<br> -<h2 id="relay-descriptors" class="hover">Tor Relay Descriptors -<a href="#relay-descriptors" class="anchor">#</a> -</h2> - -<p> -Relays and directory authorities publish relay descriptors, so that -clients can select relays for their paths through the Tor network. -All these relay descriptors are specified in the -<a href="https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt">Tor -directory protocol, version 3</a> specification document (or in the -earlier protocol -<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v2.txt">version 2</a> or -<a href="https://gitweb.torproject.org/torspec.git/tree/attic/dir-spec-v1.txt">version 1</a>). -</p> - -<h3 id="type-server-descriptor" class="hover">Relay Server Descriptors -<small><code>@type server-descriptor 1.0</code></small> -<a href="recent/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/relay-descriptors/server-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-server-descriptor" class="anchor">#</a> -</h3> - -<p> -Server descriptors contain information that relays publish about -themselves. -Tor clients once downloaded this information, but now they use -microdescriptors instead. -The server descriptors in the descriptor archives -contain one descriptor per file, whereas the recently published files -contain all descriptors collected in an hour concatenated into a single -file. -</p> - -<h3 id="type-extra-info" class="hover">Relay Extra-info Descriptors -<small><code>@type extra-info 1.0</code></small> -<a href="recent/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/relay-descriptors/extra-infos/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-extra-info" class="anchor">#</a> -</h3> - -<p> -Extra-info descriptors contain relay information that Tor clients do not -need in order to function. -These are self-published, like server descriptors, but not downloaded by -clients by default. -The extra-info descriptors in the descriptor archives -contain one descriptor per file, whereas the recently published files -contain all descriptors collected in an hour concatenated into a single -file. -</p> - -<h3 id="type-network-status-consensus-3" class="hover">Network Status Consensuses -<small><code>@type network-status-consensus-3 1.0</code></small> -<a href="recent/relay-descriptors/consensuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/relay-descriptors/consensuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-network-status-consensus-3" class="anchor">#</a> -</h3> - -<p> -Though Tor relays are decentralized, the directories that track the -overall network are not. -These central points are called directory authorities, and every hour they -publish a document called a consensus, or network status document. -The consensus is made up of router status entries containing -flags, heuristics used for relay selection, etc. -</p> - -<h3 id="type-network-status-vote-3" class="hover">Network Status Votes -<small><code>@type network-status-vote-3 1.0</code></small> -<a href="recent/relay-descriptors/votes/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/relay-descriptors/votes/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-network-status-vote-3" class="anchor">#</a> -</h3> - -<p> -The directory authorities exchange votes every hour to come up with a -common consensus. -Vote documents are by far the largest documents provided here. -</p> - -<h3 id="type-dir-key-certificate-3" class="hover">Directory Key Certificates -<small><code>@type dir-key-certificate-3 1.0</code></small> -<a href="archive/relay-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-dir-key-certificate-3" class="anchor">#</a> -</h3> - -<p> -The directory authorities sign votes and the consensus with their -key that they publish in a key certificate. -These key certificates change once every few months, so they are only -available in a single descriptor archive tarball. -</p> - -<h3 id="type-network-status-microdesc-consensus-3" class="hover">Microdescriptor Consensuses -<small><code>@type network-status-microdesc-consensus-3 1.0</code></small> -<a href="recent/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-network-status-microdesc-consensus-3" class="anchor">#</a> -</h3> - -<p> -Tor clients used to download all server descriptors of active relays, but -now they only download the smaller microdescriptors which are derived from -server descriptors. -The microdescriptor consensus lists all active relays and references their -currently used microdescriptor. -The descriptor archive tarballs -contain both microdescriptor consensuses and referenced microdescriptors -together. -</p> - -<h3 id="type-microdescriptor" class="hover">Microdescriptors -<small><code>@type microdescriptor 1.0</code></small> -<a href="recent/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/relay-descriptors/microdescs/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-microdescriptor" class="anchor">#</a> -</h3> - -<p> -Microdescriptors are minimalistic documents that just includes the -information necessary for Tor clients to work. -The descriptor archive tarballs -contain both microdescriptor consensuses and referenced microdescriptors -together. -The microdescriptors in descriptor archive tarballs -contain one descriptor per file, whereas the recently published files -contain all descriptors collected in an hour concatenated into a single -file. -</p> - -<h3 id="type-network-status-2" class="hover">Version 2 Network Statuses -<small><code>@type network-status-2 1.0</code></small> -<a href="archive/relay-descriptors/statuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-network-status-2" class="anchor">#</a> -</h3> - -<p> -Version 2 network statuses have been published by the directory -authorities before consensuses have been introduced. -In contrast to consensuses, each directory authority published their own -authoritative view on the network, and clients combined these documents -locally. -We stopped archiving version 2 network statuses in 2012. -</p> - -<h3 id="type-directory" class="hover">Version 1 Directories -<small><code>@type directory 1.0</code></small> -<a href="archive/relay-descriptors/tor/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-directory" class="anchor">#</a> -</h3> - -<p> -The first directory protocol version combined the list of active relays -with server descriptors in a single directory document. -We stopped archiving version 1 directories in 2007. -</p> - -<br> -<h2 id="bridge-descriptors" class="hover">Tor Bridge Descriptors -<a href="#bridge-descriptors" class="anchor">#</a> -</h2> - -<p> -Bridges and the bridge authority publish bridge descriptors that are used -by censored clients to connect to the Tor network. -We cannot, however, make bridge descriptors available as we do with relay -descriptors, because that would defeat the purpose of making bridges hard -to enumerate for censors. -We therefore sanitize bridge descriptors by removing all potentially -identifying information and publish sanitized versions here. -The sanitizing steps are as follows: -</p> - -<ol> -<li><b>Replace bridge identities with their digests:</b> Clients -can request a bridge's current descriptor by sending its identity string -to the bridge authority. -This is a feature to make bridges on dynamic IP addresses useful. -Therefore, the original identities (and anything that could be used to -derive them) need to be removed from the descriptors. -The bridge's RSA-based identity fingerprint is replaced with its SHA-1 -hash value, and the bridge's optional base64-encoded Ed25519 master key is -replaced with its SHA-256 digest. -The idea is to have a consistent replacement that remains stable over -months or even years (without keeping a secret for a keyed hash -function).</li> -<li><b>Remove most cryptographic keys and signatures:</b> It would be -straightforward to learn about the bridge identity from the bridge's -public key. -Replacing keys by newly generated ones seemed to be unnecessary (and would -involve keeping a state over months/years), so that most cryptographic -keys and signatures have simply been removed.</li> -<li><b>Replace IP address with IP address hash:</b> Of course, IP -addresses need to be sanitized, too. -<ul><li>IPv4 addresses are replaced with <code>10.x.x.x</code> with -<code>x.x.x</code> being the 3 byte output of -<code>H(IP address | bridge identity | secret)[:3]</code>. -The input <code>IP address</code> is the 4-byte long binary representation of -the bridge's current IP address. -The <code>bridge identity</code> is the 20-byte long binary representation of -the bridge's long-term identity fingerprint. -The <code>secret</code> is a 31-byte long secure random string that changes -once per month for all descriptors and statuses published in that month. -<code>H()</code> is SHA-256. -The <code>[:3]</code> operator means that we pick the 3 most significant bytes -of the result.</li> -<li>IPv6 addresses are replaced with <code>[fd9f:2e19:3bcf::xx:xxxx]</code> -with <code>xx:xxxx</code> being the hex-formatted 3 byte output of a similar -hash function as described for IPv4 addresses. -The only differences are that the input <code>IP address</code> is 16 bytes -long and the <code>secret</code> is only 19 bytes long.</li></ul></li> -<li><b>Replace TCP port with TCP port hash:</b> It may be less obvious -that TCP ports need to be sanitized, but an unusual TCP port used by a -high-value bridge might still stand out and provide yet another way to -locate and block the bridge. -Therefore, each non-zero TCP port is replaced with a number in the range -from 49152 to 65535 that is the result of -<code>H(port | bridge identity | secret)[:2] / 2^2 + 2^15 + 2^14</code> -written as decimal number. -The input <code>port</code> is the 2-byte long binary representation of the -TCP port. -The <code>bridge identity</code> is the 20-byte long binary representation of -the bridge's long-term identity fingerprint. -The <code>secret</code> is a 33-byte long secure random string that changes -once per month for all descriptors and statuses published in that month. -<code>H()</code> is SHA-256. -The <code>[:2]</code> operator means that we pick the 2 most significant bytes -of the result. -The subsequent integer division and additions make sure that sanitized -ports are in the range from 49152 to 65535 which is reserved for private -services. -All operations assume inputs to be in network byte order. -TCP ports that are 0 in the original descriptor are left unchanged.</li> -<li><b>Replace contact information:</b> If there is contact information in -a descriptor, the contact line is changed to -<code>somebody</code>.</li> -<li><b>Remove pluggable transport addresses and arguments:</b> Bridges may -provide transports in addition to the onion-routing protocol and include -information about these transports in their extra-info descriptors for -BridgeDB. -In that case, any IP addresses, TCP ports, or additional arguments are -removed, only leaving in the supported transport names.</li> -<li><b>Append descriptor digests:</b> Descriptors are often referenced by -their digest, but that is not possible anymore once their content has -changed. -As a workaround, sanitized descriptors contain a new line -<code>router-digest</code> with the hex representation of the SHA-1 of the -original descriptor digest excluding RSA signature and—if the bridge -uses an Ed25519 identity—a new line <code>router-digest-sha256</code> -with the base64-encoded SHA-256 of the SHA-256 digest of the original -descriptor including all signatures.</li> -</ol> - -<h3 id="type-bridge-network-status" class="hover">Bridge Network Statuses -<small><code>@type bridge-network-status 1.1</code></small> -<a href="recent/bridge-descriptors/statuses/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/bridge-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-bridge-network-status" class="anchor">#</a> -</h3> - -<p> -Sanitized bridge network statuses are similar to version 2 relay network -statuses, but with only a <code>published</code> line in the header and -without any lines in the footer. -The format has changed over time to accomodate changes to the sanitizing -process, with earlier versions being: -</p> - -<ul> -<li><code>@type bridge-network-status 1.0</code> was the first version.</li> -<li><code>@type bridge-network-status 1.1</code> introduced sanitized TCP -ports.</li> -</ul> - -<h3 id="type-bridge-server-descriptor" class="hover">Bridge Server descriptors -<small><code>@type bridge-server-descriptor 1.2</code></small> -<a href="recent/bridge-descriptors/server-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/bridge-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-bridge-server-descriptor" class="anchor">#</a> -</h3> - -<p> -Bridge server descriptors follow the same format as relay server -descriptors, except for the sanitizing steps described above. -The bridge server descriptor archive tarballs contain one descriptor per -file, whereas recently published bridge server descriptor files -contain all descriptors collected in an hour concatenated into a single -file to reduce the number of files. -The format has changed over time to accomodate changes to the sanitizing -process, with earlier versions being: -</p> - -<ul> -<li><code>@type bridge-server-descriptor 1.0</code> was the first version.</li> -<li>There was supposed to be a newer version indicating added -<code>ntor-onion-key</code> lines, but due to a mistake only the version number -of sanitized bridge extra-info descriptors was raised. -As a result, there may be sanitized bridge server descriptors with version -<code>@type bridge-server-descriptor 1.0</code> with and without those -lines.</li> -<li><code>@type bridge-server-descriptor 1.1</code> added -<code>master-key-ed25519</code> lines and <code>router-digest-sha256</code> to -server descriptors published by bridges using an Ed25519 master -key.</li> -<li><code>@type bridge-server-descriptor 1.2</code> introduced sanitized TCP -ports.</li> -</ul> - -<h3 id="type-bridge-extra-info" class="hover">Bridge Extra-info Descriptors -<small><code>@type bridge-extra-info 1.3</code></small> -<a href="recent/bridge-descriptors/extra-infos/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/bridge-descriptors/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-bridge-extra-info" class="anchor">#</a> -</h3> - -<p> -Bridge extra-info descriptors follow the same format as relay extra-info -descriptors, except for the sanitizing steps described above. -The format has changed over time to accomodate changes to the sanitizing -process, with earlier versions being: -</p> - -<ul> -<li><code>@type bridge-extra-info 1.0</code> was the first version.</li> -<li><code>@type bridge-extra-info 1.1</code> added sanitized -<code>transport</code> lines.</li> -<li><code>@type bridge-extra-info 1.2</code> was supposed to indicate added -<code>ntor-onion-key</code> lines, but those changes only affect bridge server -descriptors, not extra-info descriptors. -So, nothing has changed as compared to version 1.1.</li> -<li><code>@type bridge-extra-info 1.3</code> added <code>master-key-ed25519</code> -lines and <code>router-digest-sha256</code> to extra-info descriptors -published by bridges using an Ed25519 master key.</li> -</ul> - -<p> -The bridge extra-info descriptor archive tarballs contain one descriptor -per file, whereas recently published bridge extra-info descriptor -files contain all descriptors collected in an hour concatenated into a single -file to reduce the number of files. -</p> - -<br> -<h2 id="tor-hidden-service-descriptors" class="hover">Tor Hidden Service Descriptors -<a href="#tor-hidden-service-descriptors" class="anchor">#</a> -</h2> - -<p> -Tor hidden services make it possible for users to hide their locations -while offering various kinds of services, such as web publishing or an -instant messaging server. -A hidden service assembles a hidden service descriptor to make its service -available in the network. -This descriptor gets stored on hidden service directories and can be -retrieved by hidden service clients. -Hidden service descriptors are not formally archived, but some libraries -support parsing these descriptors when obtaining them from a locally -running Tor instance. -</p> - -<h3 id="type-hidden-service-descriptor" class="hover">Hidden Service Descriptors -<small><code>@type hidden-service-descriptor 1.0</code></small> -<a href="#type-hidden-service-descriptor" class="anchor">#</a> -</h3> - -<p> -Hidden service descriptors contain all details that are necessary for -clients to connect to a hidden service. -Despite the version number being 1.0, these descriptors are part of the -version 2 hidden service protocol. -</p> - -<br> -<h2 id="bridge-pool-assignments" class="hover">BridgeDB's Bridge Pool Assignments -<a href="#bridge-pool-assignments" class="anchor">#</a> -</h2> - -<p> -The bridge distribution service BridgeDB publishes bridge pool assignments -describing which bridges it has assigned to which distribution pool. -BridgeDB receives bridge network statuses from the bridge authority, -assigns these bridges to persistent distribution rings, and hands them out -to bridge users. -BridgeDB periodically dumps the list of running bridges with information -about the rings, subrings, and file buckets to which they are assigned to -a local file. -The sanitized versions of these lists containing SHA-1 hashes of bridge -fingerprints instead of the original fingerprints are available for -statistical analysis. -</p> - -<h3 id="type-bridge-pool-assignment" class="hover">Bridge Pool Assignments -<small><code>@type bridge-pool-assignment 1.0</code></small> -<a href="archive/bridge-pool-assignments/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-bridge-pool-assignment" class="anchor">#</a> -</h3> - -<p> -The document below shows a BridgeDB pool assignment file -from March 13, 2011. -Every such file begins with a line containing the timestamp when BridgeDB -wrote this file. -Subsequent lines start with the SHA-1 hash of a bridge fingerprint, -followed by ring, subring, and/or file bucket information. -There are currently three distributor ring types in BridgeDB: -</p> - -<ol> -<li><b>unallocated:</b> These bridges are not distributed by BridgeDB, -but are either reserved for manual distribution or are written to file -buckets for distribution via an external tool. -If a bridge in the <code>unallocated</code> ring is assigned to a file bucket, -this is noted by <code>bucket=$bucketname</code>.</li> -<li><b>email:</b> These bridges are distributed via an e-mail -autoresponder. Bridges can be assigned to subrings by their OR port or -relay flag which is defined by <code>port=$port</code> and/or <code>flag=$flag</code>. -</li> -<li><b>https:</b> These bridges are distributed via https server. -There are multiple https rings to further distribute bridges by IP address -ranges, which is denoted by <code>ring=$ring</code>. -Bridges in the <code>https</code> ring can also be assigned to subrings by -OR port or relay flag which is defined by <code>port=$port</code> and/or -<code>flag=$flag</code>.</li> -</ol> - -<pre> -bridge-pool-assignment 2011-03-13 14:38:03 -00b834117566035736fc6bd4ece950eace8e057a unallocated -00e923e7a8d87d28954fee7503e480f3a03ce4ee email port=443 flag=stable -0103bb5b00ad3102b2dbafe9ce709a0a7c1060e4 https ring=2 port=443 flag=stable -[...] -</pre> - -<p> -As of December 8, 2014, bridge pool assignment files are no longer -archived. -</p> - -<br> -<h2 id="exit-lists" class="hover">TorDNSEL's Exit Lists -<a href="#exit-lists" class="anchor">#</a> -</h2> - -<p> -The exit list service -<a href="https://www.torproject.org/tordnsel/dist/">TorDNSEL</a> -publishes exit lists containing the IP addresses of relays that it found -when exiting through them. -</p> - -<h3 id="type-tordnsel" class="hover">Exit Lists -<small><code>@type tordnsel 1.0</code></small> -<a href="recent/exit-lists/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/exit-lists/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-tordnsel" class="anchor">#</a> -</h3> - -<p> -Tor Check makes the list of known exits and corresponding exit IP -addresses available in a specific format. -The document below shows an entry of the exit list written on -December 28, 2010 at 15:21:44 UTC. -This entry means that the relay with fingerprint <code>63BA..</code> which -published a descriptor at 07:35:55 and was contained in a version 2 -network status from 08:10:11 uses two different IP addresses for exiting. -The first address <code>91.102.152.236</code> was found in a test performed at -07:10:30. -When looking at the corresponding server descriptor, one finds that this -is also the IP address on which the relay accepts connections from inside -the Tor network. -A second test performed at 10:35:30 reveals that the relay also uses IP -address <code>91.102.152.227</code> for exiting. -</p> - -<pre> -ExitNode 63BA28370F543D175173E414D5450590D73E22DC -Published 2010-12-28 07:35:55 -LastStatus 2010-12-28 08:10:11 -ExitAddress 91.102.152.236 2010-12-28 07:10:30 -ExitAddress 91.102.152.227 2010-12-28 10:35:30 -</pre> - -<br> -<h2 id="torperf" class="hover">Torperf's Performance Data -<a href="#torperf" class="anchor">#</a> -</h2> - -<p> -The performance measurement service Torperf publishes performance data -from making simple HTTP requests over the Tor network. -Torperf uses a trivial SOCKS client to download files of various sizes -over the Tor network and notes how long substeps take. -</p> - -<h3 id="type-torperf" class="hover">Torperf Measurement Results -<small><code>@type torperf 1.0</code></small> -<a href="recent/torperf/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> recent</a> -<a href="archive/torperf/" class="btn btn-primary btn-xs"><i class="fa fa-chevron-right" aria-hidden="true"></i> archive</a> -<a href="#type-torperf" class="anchor">#</a> -</h3> - -<p> -A Torperf results file contains a single line per Torperf run with -<code>key=value</code> pairs. -Such a result line is sufficient to learn about 1) the Tor and Torperf -configuration, 2) measurement results, and 3) additional information that -might help explain the results. -Known keys are explained below. -</p> -<ul> -<li>Configuration -<ul> -<li><code>SOURCE:</code> Configured name of the data source; required.</li> -<li><code>FILESIZE:</code> Configured file size in bytes; required.</li> -<li>Other meta data describing the Tor or Torperf configuration, e.g., -GUARD for a custom guard choice; optional.</li> -</ul></li> -<li>Measurement results -<ul> -<li><code>START:</code> Time when the connection process starts; -required.</li> -<li><code>SOCKET:</code> Time when the socket was created; required.</li> -<li><code>CONNECT:</code> Time when the socket was connected; required.</li> -<li><code>NEGOTIATE:</code> Time when SOCKS 5 authentication methods have been -negotiated; required.</li> -<li><code>REQUEST:</code> Time when the SOCKS request was sent; required.</li> -<li><code>RESPONSE:</code> Time when the SOCKS response was received; -required.</li> -<li><code>DATAREQUEST:</code> Time when the HTTP request was written; -required.</li> -<li><code>DATARESPONSE:</code> Time when the first response was received; -required.</li> -<li><code>DATACOMPLETE:</code> Time when the payload was complete; -required.</li> -<li><code>WRITEBYTES:</code> Total number of bytes written; required.</li> -<li><code>READBYTES:</code> Total number of bytes read; required.</li> -<li><code>DIDTIMEOUT:</code> 1 if the request timed out, 0 otherwise; -optional.</li> -<li><code>DATAPERCx:</code> Time when x% of expected bytes were read for -x = { 10, 20, 30, 40, 50, 60, 70, 80, 90 }; optional.</li> -<li>Other measurement results, e.g., START_RENDCIRC, GOT_INTROCIRC, etc. -for hidden-service measurements; optional.</li> -</ul></li> -<li>Additional information -<ul> -<li><code>LAUNCH:</code> Time when the circuit was launched; optional.</li> -<li><code>USED_AT:</code> Time when this circuit was used; optional.</li> -<li><code>PATH:</code> List of relays in the circuit, separated by commas; -optional.</li> -<li><code>BUILDTIMES:</code> List of times when circuit hops were built, -separated by commas; optional.</li> -<li><code>TIMEOUT:</code> Circuit build timeout in milliseconds that the Tor -client used when building this circuit; optional.</li> -<li><code>QUANTILE:</code> Circuit build time quantile that the Tor client -uses to determine its circuit-build timeout; optional.</li> -<li><code>CIRC_ID:</code> Circuit identifier of the circuit used for this -measurement; optional.</li> -<li><code>USED_BY:</code> Stream identifier of the stream used for this -measurement; optional.</li> -<li>Other fields containing additional information; optional.</li> -</ul></li> -</ul> - -<p> -Recently published Torperf measurement result files accumulate -all new Torperf measurements of a given day, which means that -they may change throughout the day. -This is different from some of the other recently published files provided here -which do not change once they are -written. -</p> - - </div> - - <br> - - -<div class="container"> - <div class="row"> - <div class="col-xs-12"> - <br> - <h1 id="automated-downloads" class="hover">Automated Downloads -<a href="#automated-downloads" class="anchor">#</a> -</h1> -<p> -There are multiple ways to download descriptors from this site. -Of course, the obvious way is to browse the directories and download contained files using your browser. However, this method cannot be automated very well.</p> - -<h2 id="recursive-wget" class="hover">Recursive downloads using <code>wget</code> -<a href="#recursive-wget" class="anchor">#</a> -</h2> - -<p>A more elaborate way to automatically download descriptors is to use Unix tools like <code>wget</code> which support recursively downloading files from this site. Example:</p> -<pre> -wget --recursive \ # turn on recursive retrieving - --reject "index.html*" \ # don't retrieve directory listings - --no-parent \ # don't ascend to parent directory - --no-host-directories \ # don't generate host-prefixed directories - --directory-prefix descriptors \ # set directory prefix - https://collector.torproject.org/recent/relay-descriptors/microdescs/ -</pre> - -<h2 id="index-json" class="hover">Custom downloaders using provided <code>index.json</code> -<a href="#index-json" class="anchor">#</a></h2> - -<p>Another automated way to download descriptors is to develop a tool that uses the provided <a href="index/index.json"><code>index.json</code></a> file or one of its compressed versions <a href="index/index.json.gz"><code>index.json.gz</code></a>, <a href="index/index.json.bz2"><code>index.json.bz2</code></a>, or <a href="index/index.json.xz"><code>index.json.xz</code></a>. -These files contain a machine-readable representation of all descriptor files available on this site. -Index files use the following custom JSON data format that might still be extended at a later time:</p> -<ul> -<li>Index object: At the document root there is always an index object with the following fields: -<ul> -<li><code>"index_created"</code>: Timestamp when this index was created using pattern <code>"YYYY-MM-DD HH:MM"</code> in the UTC timezone.</li> -<li><code>"path"</code>: Base URL of this index file and all included resources.</li> -<li><code>"files"</code>: List of file objects of files available from the document root, which will be omitted if empty. -<li><code>"directories"</code>: List of directory objects of directories available from the document root, which will be omitted if empty.</li> -</ul></li> -<li>Directory object: There is one directory object for each directory or subdirectory in the document tree containing similar fields as the index object: -<ul> -<li><code>"path"</code>: Relative path of the directory.</li> -<li><code>"files"</code>: List of file objects of files available from this directory, which will be omitted if empty. -<li><code>"directories"</code>: List of directory objects of directories available from this directory, which will be omitted if empty.</li> -</ul></li> -<li>File object: Each file that is available in the document tree is represented by a file object with the following fields: -<ul> -<li><code>"path"</code>: Relative path of the file.</li> -<li><code>"size"</code>: Size of the file in bytes.</li> -<li><code>"last_modified"</code>: Timestamp when the file was last modified using pattern <code>"YYYY-MM-DD HH:MM"</code> in the UTC timezone.</li> -</ul></li> -</ul> - - </div><!-- col --> - </div><!-- row --> - - <br> - - - -</div> - - - - <div class="container-fluid" id="footer"> - - <div class="container no-gutter"> - <div class="col-xs-6"> - <p> - © 2017 The Tor Project - </p> - </div> - <div class="col-xs-6"> - <p class="pull-right"> - - <a href="https://metrics.torproject.org/about.html#contact">Contact</a> - - </p> - </div> - </div> - - <div class="container small"> - - <p>Data on this site is freely available under a <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 no copyright declaration</a>: To the extent possible under law, the Tor Project has waived all copyright and related or neighboring rights in the data. "Tor" and the "Onion Logo" are <a href="https://www.torproject.org/docs/trademark-faq.html.en">registered trademarks</a> of The Tor Project, Inc.</p> - - </div> - - </div><!-- /footer --> - - - -</div><!-- /wrapper --> - -</body> -</html> diff --git a/website/src/main/resources/web/onionoo.html b/website/src/main/resources/web/onionoo.html deleted file mode 100644 index d8fe74a..0000000 --- a/website/src/main/resources/web/onionoo.html +++ /dev/null @@ -1,2249 +0,0 @@ -<!DOCTYPE HTML> -<html lang="en" style="min-height:100%;"> -<head> - - <title>Onionoo</title> - - <meta charset="utf-8"> - <link href="images/favicon.ico" type="image/x-icon" rel="shortcut icon"> - - <!-- yes, we're handheld friendly :) --> - <meta name="HandheldFriendly" content="True"> - <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"> - <meta name="apple-mobile-web-app-capable" content="yes"> - - <!-- icons for mobile devices --> - <link rel="apple-touch-icon" href="images/apple-touch-icon-152x152.png"> - <link rel="shortcut icon" href="images/android-icon.png" sizes="196x196"> - <meta name="msapplication-square70x70logo" content="images/smalltile.png"> - <meta name="msapplication-square150x150logo" content="images/mediumtile.png"> - <meta name="msapplication-wide310x150logo" content="images/widetile.png"> - <meta name="msapplication-square310x310logo" content="images/largetile.png"> - - <!-- jQuery --> - <script src="js/jquery-3.1.1.min.js"></script> - - <!-- Bootstrap --> - <link rel="stylesheet" href="css/bootstrap.min.css"> - <script src="js/bootstrap.min.js"></script> - - <!-- Fonts --> - <link rel="stylesheet" href="css/font-awesome.min.css"> - <link rel="stylesheet" href="fonts/source-sans-pro.css"> - - <!-- custom styles and javascript --> - <link rel="stylesheet" href="css/style.css"> - <script src="js/script.js"></script> - -</head> - -<body class="noscript" style="background-image:url(images/ajax-loader.gif);background-repeat:no-repeat;background-position:center center;"> - -<!-- Using evil inline stylesheets to hide the FOUC for slow connections... --> - -<div id="wrapper" style="display:none;"> - - -<!-- backToTop-Button and Anchor --> -<noscript> -<div class="topButton" style="display:block;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div> -</noscript> -<script type="text/javascript"> -document.write('<div class="topButton" style="display:none;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div>'); -</script> -<a id="top"></a> - - - -<!-- secondary navigation --> -<nav class="navbar navbar-default navbar-secondary"> - <div class="container-fluid visible-xs"> - <input type="checkbox" id="navbar-toggle-checkbox"> - <div class="navbar-header"> - <label for="navbar-toggle-checkbox" type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-secondary" aria-expanded="false"> - <span class="sr-only">Toggle navigation</span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - <span class="icon-bar"></span> - </label> - <a class="navbar-brand visible-xs" href="/"><img src="images/onionoo-wordmark-white.png" width="221" height="40" alt="Onionoo"></a> - </div> - <!-- Collect the nav links, forms, and other content for toggling --> - <div class="collapse navbar-collapse" id="bs-example-navbar-secondary"> - <ul class="nav navbar-nav navbar-right"> - - - <!-- secondary navigation items --> - <li><a href="#general">General</a></li> - <li><a href="#versions">Protocol versions</a></li> - <li><a href="#methods">Methods</a></li> - <li><a href="#responses">Responses</a></li> - <li><a href="#summary">Summary documents</a></li> - <li><a href="#details">Details documents</a></li> - <li><a href="#history">History objects</a></li> - <li><a href="#bandwidth">Bandwidth documents</a></li> - <li><a href="#weights">Weights documents</a></li> - <li><a href="#clients">Clients documents</a></li> - <li><a href="#uptime">Uptime documents</a></li> - <li><a href="#examples">Example usage</a></li> - <!-- /secondary navigation items --> - - </ul> - </div><!-- /.navbar-collapse --> - - </div> -</nav> -<!-- /secondary navigation --> - - - -<!-- page header for every single page --> -<div class="page-header hidden-xs"> - <a href="/"><img src="images/tor-logo-weiss.png" width="162" height="100" alt="" id="onionoo-logo"></a> - <span style="display:inline-block;width:20px;"></span> - <a href="/"><img src="images/onionoo-wordmark-white.png" width="221" height="40" alt="Onionoo" id="onionoo-wordmark"></a> - <div> - <p> - <i>The Tor network status protocol providing the<br> - data for other applications and websites.</i> - </p> - </div> - <div class="clearfix"></div> -</div> -<!-- /page header --> - - - - - - <div class="container"> - - -<br><br> - - - - <div class="jumbotron"> - <div class="text-center"> - <h2> - The Tor network status protocol - </h2> - <p>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. </p> - <a class="btn btn-primary btn-lg" style="margin: 10px" href="#protocol"><i class="fa fa-chevron-right" aria-hidden="true"></i> Tell me more!</a> - - </div><!-- text-center --> - - - </div><!-- jumbotron --> - - - - - - -<br> - - - - - -<br> -<a id="protocol"></a> - - <!-- floating anchor box --> - <div class="col-md-4 pull-right hidden-xs" style="padding:1.2em 0 0 2em;"> - <div class="list-group"> - <h3>Table of contents</h3> - <a class="list-group-item" href="#general">General</a> - <a class="list-group-item" href="#versions">Protocol versions</a> - <a class="list-group-item" href="#methods">Methods</a> - <a class="list-group-item" href="#responses">Responses</a> - <a class="list-group-item" href="#summary">Summary documents</a> - <a class="list-group-item" href="#details">Details documents</a> - <a class="list-group-item" href="#history">History objects</a> - <a class="list-group-item" href="#bandwidth">Bandwidth documents</a> - <a class="list-group-item" href="#weights">Weights documents</a> - <a class="list-group-item" href="#clients">Clients documents</a> - <a class="list-group-item" href="#uptime">Uptime documents</a> - <a class="list-group-item" href="#examples">Example usage</a> - </div> - </div> - - -<h1>The Tor network status protocol <a href="#protocol" class="anchor">#</a></h1> - -<a id="general"></a><br> -<h2>General <a href="#general" class="anchor">#</a></h2> - -<p> -The Onionoo service is designed as a RESTful web service. -Onionoo clients send HTTP GET requests to the Onionoo server which -responds with JSON-formatted replies. -Onionoo clients and their developers should follow a few rules: -</p> - -<br> - -<h3>Compression</h3> -<p> -Clients should include an <strong>"Accept-Encoding: -gzip"</strong> header in their requests and handle gzip-compressed -responses. -Only requests starting at a certain size will be compressed by the -server. -</p> - -<br> - -<h3>Caching</h3> -<p>Clients should make use of the <strong>"Last-Modified"</strong> -header of responses and include that timestamp in a -<strong>"If-Modified-Since"</strong> header of subsequent requests. -</p> - -<br> - - - -<div class="clearfix"></div> - - -<h3>Response codes</h3> -<p> -Clients should handle response codes by -distinguishing between client and server errors, and if there's a problem, -informing their users about the kind of problem. -The following response codes are used: -</p> - -<ul class="properties"> - -<li> -<b>200 OK</b> -<p> -The request was processed successfully. -</p> -</li> - -<li> -<b>304 Not Modified</b> -<p> -Server data has not changed since the -<strong>"If-Modified-Since"</strong> header included in the request. -</p> -</li> - -<li> -<b>400 Bad Request</b> -<p> -The request for a known resource could not be processed because of bad -syntax. -This is most likely a client problem. -</p> -</li> - -<li> -<b>404 Not Available</b> -<p> -The request could not be processed because the requested resource could -not be found. -This is most likely a client problem. -</p> -</li> - -<li> -<b>500 Internal Server Error</b> -<p> -There is an unspecific problem with -the server which the service operator may not yet be aware of. -Please check if there's already a bug report for this problem, and if not, -file one. -</p> -</li> - -<li> -<b>503 Service Unavailable</b> -<p> -The server is temporarily down for -maintenance, or there is a temporary problem with the server that the -service operator is already aware of. -Only file a bug report if this problem persists. -</p> -</li> - -</ul> - - -<a id="versions"></a><br> -<h2>Protocol versions <a href="#versions" class="anchor">#</a></h2> -<p> -There are plenty of reasons why we may have -to change the protocol described here. -Clients should be able to handle all valid JSON responses, ignoring -unknown fields and not breaking horribly in case of missing fields. -Protocol changes will be announced here by writing deprecated API parts with -the label <span class="label label-warning">deprecated</span> and new parts -with the label <span class="label label-primary">new</span>. -Deprecated parts will be removed one month after their announcement. -</p> - -<p>All responses contain a <strong>"version"</strong> string that -indicates whether clients can parse the document or not. -Version strings consist of a major and a minor version number. -The major version number is raised when previously required fields are -dropped or turned into optional fields, when request parameters or -response documents are removed, or when there are structural changes. -The minor version number is raised when new fields, request parameters, or -response documents are added or optional fields are dropped. -If clients support the same major version given in a response but only a -lower minor version, they should be able to parse the document but may not -understand all fields. -If clients support a lower major version, they should not attempt to parse -a document, because there may be backward-incompatible changes.</p> - -<p>Responses may also contain the optional -<strong>"next_major_version_scheduled"</strong> field that announces when -the next major version is scheduled to be deployed. -Clients should inform their users that they should upgrade to the next -major protocol version before the provided date.</p> - -<p>The following versions have been used in the past six months or are -scheduled to be deployed in the next months:</p> - -<ul> -<li><strong>1.0</strong>: First assigned version number on August 31, -2014.</li> -<li><strong>1.1</strong>: Added optional "next_major_version_scheduled" -field on September 16, 2014.</li> -<li><strong>1.2</strong>: Added qualified search terms to "search" -parameter on October 17, 2014.</li> -<li><strong>2.0</strong>: Extended search parameter to base64-encoded -fingerprints on November 15, 2014.</li> -<li><strong>2.1</strong>: Removed optional "advertised_bandwidth_fraction" -field from details documents and optional "advertised_bandwidth" and -"advertised_bandwidth_fraction" fields from weights documents on November -16, 2014.</li> -<li><strong>2.2</strong>: Removed optional "pool_assignment" field and -added "transports" field to bridge details documents on December 8, -2014.</li> -<li><strong>2.3</strong>: Added optional "flags" field to uptime -documents on March 22, 2015.</li> -<li><strong>2.4</strong>: Added optional "effective_family" field to -details documents on July 3, 2015.</li> -<li><strong>2.5</strong>: Added optional "measured" field to details -documents on August 13, 2015.</li> -<li><strong>2.6</strong>: Added optional "alleged_family" and -"indirect_family" fields and deprecated optional "family" field in details -documents on August 25, 2015.</li> -<li><strong>3.0</strong>: Extended search parameter to match any 4 hex -characters of a space-separated fingerprint on November 15, 2015.</li> -<li><strong>3.1</strong>: Removed optional "family" field on January 18, -2016.</li> -<li><strong>3.2</strong>: Extended order parameter to "first_seen" and -added response meta data fields "relays_skipped", "relays_truncated", -"bridges_skipped", and "bridges_truncated" on January 27, 2017.</li> -<li><strong>4.0</strong>: Extended search parameter to not require -leading or enclosing square brackets around IPv6 addresses anymore on -February 28, 2017.</li> -</ul> - - - -<a id="methods"></a><br> -<h2>Methods <a href="#methods" class="anchor">#</a></h2> - -<p> -The following methods each return a single document containing zero or -more objects of relays and/or bridges. -By default, all relays and bridges are included that have been running in -the past week. -</p> - -<div class="responsive-table"> - <table class="table table-striped"> - <thead> - <tr> - <th class="method">Method</th> - <th class="url">URL</th> - <th class="description">Description</th> - </tr> - </thead> - <tbody> - <tr> - <td data-title="Method" >GET</td> - <td data-title="URL" >https://onionoo.torproject.org/summary</td> - <td data-title="Description" >returns a <a href="#summary">summary document</a></td> - </tr> - <tr> - <td data-title="Method" >GET</td> - <td data-title="URL" >https://onionoo.torproject.org/details</td> - <td data-title="Description" >returns a <a href="#details">details document</a></td> - </tr> - <tr> - <td data-title="Method" >GET</td> - <td data-title="URL" >https://onionoo.torproject.org/bandwidth</td> - <td data-title="Description" >returns a <a href="#bandwidth">bandwidth document</a></td> - </tr> - <tr> - <td data-title="Method" >GET</td> - <td data-title="URL" >https://onionoo.torproject.org/weights</td> - <td data-title="Description" >returns a <a href="#weights">weights document</a></td> - </tr> - <tr> - <td data-title="Method" >GET</td> - <td data-title="URL" >https://onionoo.torproject.org/clients</td> - <td data-title="Description" >returns a <a href="#clients">clients document</a></td> - </tr> - <tr> - <td data-title="Method" >GET</td> - <td data-title="URL" >https://onionoo.torproject.org/uptime</td> - <td data-title="Description" >returns an <a href="#uptime">uptime document</a></td> - </tr> - - </tbody> - </table> -</div> - - - -<h3>Parameters</h3> -<p> -Each of the methods can be parameterized to select only a subset of relay -and/or bridge documents that are currently running or that have been -running in the past week. -(The <strong>fingerprint</strong> parameter is special here, because it -allows selecting a specific relay or bridge, regardless of whether it has -been running in the past week.) -If multiple parameters are specified, they are combined using a logical -AND operation, meaning that only the intersection of relays and bridges -matching all parameters is returned. -If the same parameter is specified more than once, only the first -parameter value is considered. -</p> - -<ul class="properties"> - -<li> -<b>type</b> -<p> -Return only relay (parameter value -<strong>relay</strong>) or only bridge documents (parameter value -<strong>bridge</strong>). -Parameter values are case-insensitive. -</p> -</li> - -<li> -<b>running</b> -<p> -Return only running (parameter value -<strong>true</strong>) or only non-running relays and/or bridges -(paramter value -<strong>false</strong>). -Parameter values are case-insensitive. -</p> -</li> - -<li> -<b>search</b> -<p> -Return only (1) relays with the parameter value matching (part of a) -nickname, (possibly $-prefixed) beginning of a hex-encoded fingerprint, -any 4 hex characters of a space-separated fingerprint, beginning of a -base64-encoded fingerprint without trailing equal signs, or beginning of -an IP address (possibly enclosed in square brackets in case of IPv6), -(2) bridges with (part of a) nickname or (possibly -$-prefixed) beginning of a hashed hex-encoded fingerprint, and (3) relays -and/or bridges matching a given qualified search term. -Searches by relay IP address include all known addresses used for onion -routing and for exiting to the Internet. -Searches for beginnings of IP addresses are performed on textual -representations of canonical IP address forms, so that searches using CIDR -notation or non-canonical forms will return empty results. -Searches are case-insensitive, except for base64-encoded fingerprints. -If multiple search terms are given, separated by spaces, the intersection -of all relays and bridges matching all search terms will be returned. -Complete hex-encoded fingerprints should always be hashed using SHA-1, -regardless of searching for a relay or a bridge, in order to not -accidentally leak non-hashed bridge fingerprints in the URL. -Qualified search terms have the form "key:value" (without double quotes) -with "key" being one of the parameters listed here except for "search", -"fingerprint", "order", "limit", "offset", and "fields", and "value" being -the string that will internally be passed to that parameter. -</p> -</li> - -<li> -<b>lookup</b> -<p> -Return only the relay with the parameter -value matching the fingerprint or the bridge with the parameter value -matching the hashed fingerprint. -Fingerprints should always be hashed using SHA-1, regardless of looking up -a relay or a bridge, in order to not accidentally leak non-hashed bridge -fingerprints in the URL. -Lookups only work for full fingerprints or hashed fingerprints consisting -of 40 hex characters. -Lookups are case-insensitive. -</p> -</li> - -<li> -<b>fingerprint</b> -<p> -Return only the relay with the parameter value matching the fingerprint -or the bridge with the parameter value matching the hashed fingerprint. -Fingerprints must consist of 40 hex characters, case does not matter. -This parameter is quite similar to the <strong>lookup</strong> parameter -with two exceptions: -(1) the provided relay fingerprint or hashed bridge fingerprint <i>must -not</i> be hashed (again) using SHA-1; -(2) the response will contain any matching relay or bridge regardless of -whether they have been running in the past week. -</p> -</li> - -<li> -<b>country</b> -<p> -Return only relays which are located in the -given country as identified by a two-letter country code. -Filtering by country code is case-insensitive. -</p> -</li> - -<li> -<b>as</b> -<p> -Return only relays which are located in the -given autonomous system (AS) as identified by the AS number (with or -without preceding "AS" part). -Filtering by AS number is case-insensitive. -</p> -</li> - -<li> -<b>flag</b> -<p> -Return only relays which have the -given relay flag assigned by the directory authorities. -Note that if the flag parameter is specified more than once, only the -first parameter value will be considered. -Filtering by flag is case-insensitive. -</p> -</li> - -<li> -<b>first_seen_days</b> -<p> -Return only relays or bridges which -have first been seen during the given range of days ago. -A parameter value "x-y" with x <= y returns relays or bridges that have -first been seen at least x and at most y days ago. -Accepted short forms are "x", "x-", and "-y" which are interpreted as -"x-x", "x-infinity", and "0-y". -</p> -</li> - -<li> -<b>last_seen_days</b> -<p> -Return only relays or bridges which -have last been seen during the given range of days ago. -A parameter value "x-y" with x <= y returns relays or bridges that have -last been seen at least x and at most y days ago. -Accepted short forms are "x", "x-", and "-y" which are interpreted as -"x-x", "x-infinity", and "0-y". -Note that relays and bridges that haven't been running in the past week -are not included in results, so that setting x to 8 or higher will lead to -an empty result set. -</p> -</li> - -<li> -<b>contact</b> -<p> -Return only relays with the parameter value -matching (part of) the contact line. -If the parameter value contains spaces, only relays are returned which -contain all space-separated parts in their contact line. -Only printable ASCII characters are permitted in the parameter value, -some of which need to be percent-encoded (# as %23, % as %25, & as -%26, + as %2B, and / as %2F). -Comparisons are case-insensitive. -</p> -</li> - -<li> -<b>family</b> -<p> -Return only the relay whose fingerprint matches the parameter value and -all relays that this relay has listed in its family by fingerprint and -that in turn have listed this relay in their family by fingerprint. -If relays have listed other relays in their family by nickname, those -family relationships will not be considered, regardless of whether they -have the Named flag or not. -The provided relay fingerprint must consist of 40 hex characters where -case does not matter, and it must not be hashed using SHA-1. -Bridges are not contained in the result, regardless of whether they define -a family. -</p> -</li> - -</ul> - -<p> -Response documents can be reduced in size by requesting only a subset -of contained fields. -</p> - -<ul class="properties"> - -<li> -<b>fields</b> -<p> -Comma-separated list of fields that will be -included in the result. -So far, only top-level fields in relay or bridge objects of details -documents can be specified, e.g., -<strong>nickname,hashed_fingerprint</strong>. -If the fields parameter is provided, all other fields which are not -contained in the provided list will be removed from the result. -Field names are case-insensitive. -</p> -</li> - -</ul> - -<p> -Relay and/or bridge documents in the response can be ordered and -limited by providing further parameters. -If the same parameter is specified more than once, only the first -parameter value is considered. -</p> - -<ul class="properties"> - -<li> -<b>order</b> -<p> -Re-order results by a comma-separated list -of fields in ascending or descending order. -Results are first ordered by the first list element, then by the second, -and so on. -Possible fields for ordering are: <strong>consensus_weight</strong> and -<strong>first_seen</strong>. -Field names are case-insensitive. -Ascending order is the default; descending order is selected by prepending -fields with a minus sign (<strong>-</strong>). -Field names can be listed at most once in either ascending or descending -order. -Relays or bridges which don't have any value for a field to be ordered by -are always appended to the end, regardless or sorting order. -The ordering is defined independent of the requested document type and -does not require the ordering field to be contained in the document. -If no <strong>order</strong> parameter is given, ordering of results is -undefined. -</p> -</li> - -<li> -<b>offset</b> -<p> -Skip the given number of relays and/or -bridges. -Relays are skipped first, then bridges. -Non-positive <strong>offset</strong> values are treated as zero and don't -change the -result. -</p> -</li> - -<li> -<b>limit</b> -<p> -Limit result to the given number of -relays and/or bridges. -Relays are kept first, then bridges. -Non-positive <strong>limit</strong> values are treated as zero and lead -to an empty -result. -When used together with <strong>offset</strong>, the offsetting step -precedes the -limiting step. -</p> -</li> - -</ul> - - -<a id="responses"></a><br> -<h2>Responses <a href="#responses" class="anchor">#</a></h2> - -<p>Responses all have the same structure, regardless of requested -method and provided parameters. -Responses contain the following fields:</p> - -<ul class="properties"> - -<li> -<b>version</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -Onionoo protocol version string. -</p> -</li> - -<li> -<b>next_major_version_scheduled</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to -be deployed. -Omitted if no major protocol changes are planned. -</p> -</li> - -<li> -<b>relays_published</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known relay network -status consensus started being valid. -Indicates how recent the relay objects in this document are. -</p> -</li> - -<li> -<b>relays_skipped <span class="label label-primary">new</span></b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Number of skipped relays as requested by a positive "offset" parameter -value. -Omitted if zero. -<span class="blue">Added on January 27, 2017.</span> -</p> -</li> - -<li> -<b>relays</b> -<code class="typeof">array of objects</code> -<span class="required-true">required</span> -<p> -Array of relay objects as specified below. -</p> -</li> - -<li> -<b>relays_truncated <span class="label label-primary">new</span></b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Number of truncated relays as requested by a positive "limit" -parameter value. -Omitted if zero. -<span class="blue">Added on January 27, 2017.</span> -</p> -</li> - -<li> -<b>bridges_published</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when -the last known bridge network status was published. -Indicates how recent the bridge objects in this document are. -</p> -</li> - -<li> -<b>bridge_skipped <span class="label label-primary">new</span></b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Number of skipped bridges as requested by a positive "offset" -parameter value. -Omitted if zero. -<span class="blue">Added on January 27, 2017.</span> -</p> -</li> - -<li> -<b>bridges</b> -<code class="typeof">array of objects</code> -<span class="required-true">required</span> -<p> -Array of bridge objects as specified below. -</p> -</li> - -<li> -<b>bridges_truncated <span class="label label-primary">new</span></b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Number of truncated bridges as requested by a positive "limit" -parameter value. -Omitted if zero. -<span class="blue">Added on January 27, 2017.</span> -</p> -</li> - -</ul> - - -<a id="summary"></a><br> -<h2>Summary documents <a href="#summary" class="anchor">#</a> -<span class="request-response"> -<a href="summary?limit=4">example request</a> -</span> -</h2> - -<p>Summary documents contain short summaries of relays with nicknames, -fingerprints, IP addresses, and running information as well as bridges -with hashed fingerprints and running information.</p> - -<h3>Relay summary objects</h3> - -<p> -Relay summary objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>n</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Relay nickname consisting of 1–19 alphanumerical characters. -Omitted if the relay nickname is <strong>"Unnamed"</strong>. -</p> -</li> - -<li> -<b>f</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -Relay fingerprint consisting of 40 upper-case hexadecimal characters. -</p> -</li> - -<li> -<b>a</b> -<code class="typeof">array of strings</code> -<span class="required-true">required</span> -<p> -Array of IPv4 or IPv6 addresses where the relay accepts -onion-routing connections or which the relay used to exit to the Internet -in the past 24 hours. -The first address is the primary onion-routing address that the relay used -to register in the network, subsequent addresses are in arbitrary order. -IPv6 hex characters are all lower-case. -</p> -</li> - -<li> -<b>r</b> -<code class="typeof">boolean</code> -<span class="required-true">required</span> -<p> -Boolean field saying whether this relay was listed as -running in the last relay network status consensus. -</p> -</li> - -</ul> - -<h3>Bridge summary objects</h3> - -<p> -Bridge summary objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>n</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Bridge nickname consisting of 1–19 alphanumerical characters. -Omitted if the bridge nickname is <strong>"Unnamed"</strong>. -</p> -</li> - -<li> -<b>h</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -SHA-1 hash of the bridge fingerprint consisting of 40 -upper-case hexadecimal characters. -</p> -</li> - -<li> -<b>r</b> -<code class="typeof">boolean</code> -<span class="required-true">required</span> -<p> -Boolean field saying whether this bridge was listed as -running in the last bridge network status. -</p> -</li> - -</ul> - - -<a id="details"></a><br> -<h2>Details documents <a href="#details" class="anchor">#</a> -<span class="request-response"> -<a href="details?limit=4">example request</a> -</span> -</h2> - -<p> -Details documents are based on network statuses published by the Tor -directories, server descriptors published by relays and bridges, and data -published by Tor network services TorDNSEL and BridgeDB. -Details documents use the most recently published data from these sources, -which may lead to contradictions between fields based on different sources -in rare edge cases. -</p> - -<h3>Relay details objects</h3> - -<p> -Relay details objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>nickname</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Relay nickname consisting of 1–19 alphanumerical characters. -Omitted if the relay nickname is <strong>"Unnamed"</strong>. -</p> -</li> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -Relay fingerprint consisting of 40 upper-case -hexadecimal characters. -</p> -</li> - -<li> -<b>or_addresses</b> -<code class="typeof">array of strings</code> -<span class="required-true">required</span> -<p> -Array of IPv4 or IPv6 addresses and TCP ports -or port lists where the relay accepts onion-routing connections. -The first address is the primary onion-routing address that the relay used -to register in the network, subsequent addresses are in arbitrary order. -IPv6 hex characters are all lower-case. -</p> -</li> - -<li> -<b>exit_addresses</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of IPv4 or IPv6 addresses that the -relay used to exit to the Internet in the past 24 hours. -IPv6 hex characters are all lower-case. -Only those addresses are listed that are different from onion-routing -addresses. -Omitted if array is empty. -</p> -</li> - -<li> -<b>dir_address</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -IPv4 address and TCP port where the relay -accepts directory connections. -Omitted if the relay does not accept directory connections. -</p> -</li> - -<li> -<b>last_seen</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when this -relay was last seen in a network status consensus. -</p> -</li> - -<li> -<b>last_changed_address_or_port</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD -hh:mm:ss) when this relay last stopped announcing an IPv4 or IPv6 address -or TCP port where it previously accepted onion-routing or directory -connections. -This timestamp can serve as indicator whether this relay would be a -suitable fallback directory. -</p> -</li> - -<li> -<b>first_seen</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when this -relay was first seen in a network status consensus. -</p> -</li> - -<li> -<b>running</b> -<code class="typeof">boolean</code> -<span class="required-true">required</span> -<p> -Boolean field saying whether this relay was listed as -running in the last relay network status consensus. -</p> -</li> - -<li> -<b>hibernating</b> -<code class="typeof">boolean</code> -<span class="required-false">optional</span> -<p> -Boolean field saying whether this relay indicated that it is hibernating -in its last known server descriptor. -This information may be helpful to decide whether a relay that is not -running anymore has reached its accounting limit and has not dropped out -of the network for another, unknown reason. -Omitted if either the relay is not hibernating, or if no information is -available about the hiberation status of the relay. -</p> -</li> - -<li> -<b>flags</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of relay flags that the directory authorities -assigned to this relay. -May be omitted if empty. -</p> -</li> - -<li> -<b>country</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Two-letter lower-case country code as found in a -GeoIP database by resolving the relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the GeoIP -database. -</p> -</li> - -<li> -<b>country_name</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Country name as found in a GeoIP database by -resolving the relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the GeoIP -database, or if the GeoIP database did not contain a country name. -</p> -</li> - -<li> -<b>region_name</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Region name as found in a GeoIP database by -resolving the relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the GeoIP -database, or if the GeoIP database did not contain a region name. -</p> -</li> - -<li> -<b>city_name</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -City name as found in a -GeoIP database by resolving the relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the GeoIP -database, or if the GeoIP database did not contain a city name. -</p> -</li> - -<li> -<b>latitude</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Latitude as found in a GeoIP database by resolving -the relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the GeoIP -database. -</p> -</li> - -<li> -<b>longitude</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Longitude as found in a GeoIP database by -resolving the relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the GeoIP -database. -</p> -</li> - -<li> -<b>as_number</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -AS number as found in an AS database by -resolving the relay's first onion-routing IP address. -AS number strings start with "AS", followed directly by the AS number. -Omitted if the relay IP address could not be found in the AS -database. -</p> -</li> - -<li> -<b>as_name</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -AS name as found in an AS database by resolving the -relay's first onion-routing IP address. -Omitted if the relay IP address could not be found in the AS -database. -</p> -</li> - -<li> -<b>consensus_weight</b> -<code class="typeof">number</code> -<span class="required-true">required</span> -<p> -Weight assigned to this relay by the -directory authorities that clients use in their path selection algorithm. -The unit is arbitrary; currently it's kilobytes per second, but that might -change in the future. -</p> -</li> - -<li> -<b>host_name</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Host name as found in a reverse DNS lookup of the -relay IP address. -This field is updated at most once in 12 hours, unless the relay IP -address changes. -Omitted if the relay IP address was not looked up or if no lookup request -was successful yet. -</p> -</li> - -<li> -<b>last_restarted</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when the -relay was last (re-)started. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>bandwidth_rate</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Average bandwidth -in bytes per second that this relay is willing to sustain over long -periods. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>bandwidth_burst</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Bandwidth in bytes -per second that this relay is willing to sustain in very short intervals. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>observed_bandwidth</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Bandwidth -estimate in bytes per second of the capacity this relay can handle. -The relay remembers the maximum bandwidth sustained output over any ten -second period in the past day, and another sustained input. -The "observed_bandwidth" value is the lesser of these two numbers. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>advertised_bandwidth</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Bandwidth in bytes per second that this -relay is willing and capable to provide. -This bandwidth value is the minimum of <strong>bandwidth_rate</strong>, -<strong>bandwidth_burst</strong>, and <strong>observed_bandwidth</strong>. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>exit_policy</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of exit-policy lines. -Missing if router descriptor containing this information cannot be -found. -May contradict the <strong>"exit_policy_summary"</strong> field in a rare -edge case: this happens when the relay changes its exit policy after the -directory authorities summarized the previous exit policy. -</p> -</li> - -<li> -<b>exit_policy_summary</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Summary -version of the relay's exit policy containing a dictionary with either an -"accept" or a "reject" element. -If there is an "accept" ("reject") element, the relay accepts (rejects) -all TCP ports or port ranges in the given list for most IP addresses and -rejects (accepts) all other ports. -May contradict the <strong>"exit_policy"</strong> field in a rare edge -case: this happens when the relay changes its exit policy after the -directory authorities summarized the previous exit policy. -</p> -</li> - -<li> -<b>exit_policy_v6_summary</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Summary version of the relay's IPv6 exit policy containing a dictionary -with either an "accept" or a "reject" element. -If there is an "accept" ("reject") element, the relay accepts (rejects) -all TCP ports or port ranges in the given list for most IP addresses and -rejects (accepts) all other ports. -Missing if the relay rejects all connections to IPv6 addresses. -May contradict the <strong>"exit_policy_summary"</strong> field in a rare -edge case: this happens when the relay changes its exit policy after the -directory authorities summarized the previous exit policy. -</p> -</li> - -<li> -<b>contact</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Contact address of the relay operator. -Omitted if empty or if descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>platform</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Platform string containing operating system and Tor -version details. -Omitted if empty or if descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>recommended_version</b> -<code class="typeof">boolean</code> -<span class="required-false">optional</span> -<p> -Boolean field saying whether the Tor software version of this relay is -recommended by the directory authorities or not. -Omitted if either the directory authorities did not recommend versions, or -the relay did not report which version it runs. -</p> -</li> - -<li> -<b>effective_family</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of $-prefixed fingerprints of relays that are in an effective, -mutual family relationship with this relay. -These relays are part of this relay's family and they consider this relay -to be part of their family. -Omitted if empty or if descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>alleged_family</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of $-prefixed fingerprints of relays that are not in an effective, -mutual family relationship with this relay. -These relays are part of this relay's family but they don't consider this -relay to be part of their family. -Omitted if empty or if descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>indirect_family</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of $-prefixed fingerprints of relays that are not in an effective, -mutual family relationship with this relay but that can be reached by -following effective, mutual family relationships starting at this relay. -Omitted if empty or if descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>consensus_weight_fraction</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Fraction of this relay's consensus weight compared to the sum of all -consensus weights in the network. -This fraction is a very rough approximation of the probability of this -relay to be selected by clients. -Omitted if the relay is not running. -</p> -</li> - -<li> -<b>guard_probability</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Probability of this relay to be selected for the guard position. -This probability is calculated based on consensus weights, relay flags, -and bandwidth weights in the consensus. -Path selection depends on more factors, so that this probability can only -be an approximation. -Omitted if the relay is not running, or the consensus does not contain -bandwidth weights. -</p> -</li> - -<li> -<b>middle_probability</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Probability of this relay to be selected for the middle position. -This probability is calculated based on consensus weights, relay flags, -and bandwidth weights in the consensus. -Path selection depends on more factors, so that this probability can only -be an approximation. -Omitted if the relay is not running, or the consensus does not contain -bandwidth weights. -</p> -</li> - -<li> -<b>exit_probability</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Probability of this relay to be selected for the exit position. -This probability is calculated based on consensus weights, relay flags, -and bandwidth weights in the consensus. -Path selection depends on more factors, so that this probability can only -be an approximation. -Omitted if the relay is not running, or the consensus does not contain -bandwidth weights. -</p> -</li> - -<li> -<b>measured</b> -<code class="typeof">boolean</code> -<span class="required-false">optional</span> -<p> -Boolean field saying whether the consensus weight of this relay is based -on a threshold of 3 or more measurements by Tor bandwidth authorities. -Omitted if the network status consensus containing this relay does not -contain measurement information. -</p> -</li> - -</ul> - -<h3>Bridge details objects</h3> - -<p> -Bridge details objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>nickname</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Bridge nickname consisting of 1–19 -alphanumerical characters. -Omitted if the bridge nickname is <strong>"Unnamed"</strong>. -</p> -</li> - -<li> -<b>hashed_fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -SHA-1 hash of the bridge fingerprint -consisting of 40 upper-case hexadecimal characters. -</p> -</li> - -<li> -<b>or_addresses</b> -<code class="typeof">array of strings</code> -<span class="required-true">required</span> -<p> -Array of sanitized IPv4 or IPv6 addresses and -TCP ports or port lists where the bridge accepts onion-routing -connections. -The first address is the primary onion-routing address that the bridge -used to register in the network, subsequent addresses are in arbitrary -order. -IPv6 hex characters are all lower-case. -Sanitized IP addresses are always in <strong>10/8</strong> or -<strong>[fd9f:2e19:3bcf/48]</strong> IP networks and are only useful to -learn which -IP version the bridge uses and to detect whether the bridge changed its -address. -Sanitized IP addresses always change on the 1st of every month at 00:00:00 -UTC, regardless of the bridge actually changing its IP address. -TCP ports are not sanitized. -</p> -</li> - -<li> -<b>last_seen</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when this -bridge was last seen in a bridge network status. -</p> -</li> - -<li> -<b>first_seen</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when this -bridge was first seen in a bridge network status. -</p> -</li> - -<li> -<b>running</b> -<code class="typeof">boolean</code> -<span class="required-true">required</span> -<p> -Boolean field saying whether this bridge was listed -as running in the last bridge network status. -</p> -</li> - -<li> -<b>flags</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of relay flags that the bridge authority -assigned to this bridge. -May be omitted if empty. -</p> -</li> - -<li> -<b>last_restarted</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) when the -bridge was last (re-)started. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>advertised_bandwidth</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Bandwidth in bytes per second that this -bridge is willing and capable to provide. -This bandwidth value is the minimum of <strong>bandwidth_rate</strong>, -<strong>bandwidth_burst</strong>, and <strong>observed_bandwidth</strong>. -Missing if router descriptor containing this information cannot be -found. -</p> -</li> - -<li> -<b>platform</b> -<code class="typeof">string</code> -<span class="required-false">optional</span> -<p> -Platform string containing operating system and Tor -version details. -Omitted if not provided by the bridge or if descriptor containing this -information cannot be found. -</p> -</li> - -<li> -<b>transports</b> -<code class="typeof">array of strings</code> -<span class="required-false">optional</span> -<p> -Array of (pluggable) transport names supported by this bridge. -</p> -</li> - -</ul> - - -<a id="history"></a><br> -<h2>History objects <a href="#history" class="anchor">#</a></h2> - -<p> -History objects are no documents by themselves, but are contained in -subsequent documents. -<p> - -<h3>Graph history objects</h3> - -<p> -Graph history objects contain the following fields: -</p> - -<ul class="properties"> - -<li> -<b>first</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) of the first data point, or more -specifically the interval midpoint of the first interval. -</p> -</li> - -<li> -<b>last</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -UTC timestamp (YYYY-MM-DD hh:mm:ss) of the last data point, or more -specifically the interval midpoint of the last interval. -</p> -</li> - -<li> -<b>interval</b> -<code class="typeof">number</code> -<span class="required-true">required</span> -<p> -Time interval between two data points in seconds. -</p> -</li> - -<li> -<b>factor</b> -<code class="typeof">number</code> -<span class="required-true">required</span> -<p> -Factor by which subsequent data values need to be multiplied to obtain -original values. -The idea is to reduce document size while still providing sufficient -detail for very different data scales. -</p> -</li> - -<li> -<b>count</b> -<code class="typeof">number</code> -<span class="required-false">optional</span> -<p> -Number of provided data points, included mostly for debugging purposes. -Can also be derived from the number of elements in the subsequent array. -</p> -</li> - -<li> -<b>values</b> -<code class="typeof">array of numbers</code> -<span class="required-true">required</span> -<p> -Array of normalized values between 0 and 999. -May contain null values. -Contains at least two subsequent non-null values to enable drawing of line -graphs. -</p> -</li> - -</ul> - - -<a id="bandwidth"></a><br> -<h2>Bandwidth documents <a href="#bandwidth" class="anchor">#</a> -<span class="request-response"> -<a href="bandwidth?limit=4">example request</a> -</span> -</h2> - -<p> -Bandwidth documents contain aggregate statistics of a relay's or -bridge's consumed bandwidth for different time intervals. -Bandwidth documents are only updated when a relay or bridge publishes a -new server descriptor, which may take up to 18 hours during normal -operation. -</p> - -<h3>Relay bandwidth objects</h3> - -<p> -Relay bandwidth objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -Relay fingerprint consisting of 40 upper-case -hexadecimal characters. -</p> -</li> - -<li> -<b>write_history</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing graph history objects with written bytes for different -time periods. -Keys are string representation of the time period covered by the graph -history object. -Keys are fixed strings <strong>"3_days"</strong>, -<strong>"1_week"</strong>, <strong>"1_month"</strong>, -<strong>"3_months"</strong>, <strong>"1_year"</strong>, and -<strong>"5_years"</strong>. -Keys refer to the last known bandwidth history of a relay, not to the time -when the bandwidth document was published. -A graph history object is only contained if the time period it covers is -not already contained in another graph history object with shorter time -period and higher data resolution. -Similarly, a graph history object is excluded if the relay did not provide -bandwidth histories on the required level of detail. -The unit is bytes per second. -Contained graph history objects may contain null values if the relay did -not provide any bandwidth data or only data for less than 20% of a given -time period. -</p> -</li> - -<li> -<b>read_history</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing graph history objects with read bytes for different time -periods. -The specification of graph history objects is similar to those in the -<strong>write_history</strong> field. -</p> -</li> - -</ul> - -<h3>Bridge bandwidth objects</h3> - -<p> -Bridge bandwidth objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -SHA-1 hash of the bridge fingerprint consisting -of 40 upper-case hexadecimal characters. -</p> -</li> - -<li> -<b>write_history</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing graph history objects with written bytes for different -time periods. -The specification of graph history objects is similar to those in the -<strong>write_history</strong> field of <strong>relays</strong>. -</p> -</li> - -<li> -<b>read_history</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing graph history objects with read bytes for different time -periods. -The specification of graph history objects is similar to those in the -<strong>write_history</strong> field of <strong>relays</strong>. -</p> -</li> - -</ul> - - -<a id="weights"></a><br> -<h2>Weights documents <a href="#weights" class="anchor">#</a> -<span class="request-response"> -<a href="weights?limit=4">example request</a> -</span> -</h2> - -<p> -Weights documents contain aggregate statistics of a relay's probability -to be selected by clients for building paths. -Weights documents contain different time intervals and are available for -relays only. -</p> - -<h3>Relay weights objects</h3> - -<p> -Relay weights objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -Relay fingerprint consisting of 40 upper-case -hexadecimal characters. -</p> -</li> - -<li> -<b>consensus_weight_fraction</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -History object containing the -fraction of this relay's consensus weight compared to the sum of all -consensus weights in the network. -This fraction is a very rough approximation of the probability of this -relay to be selected by clients. -Keys are string representation of the time period covered by the graph -history object. -Keys are fixed strings <strong>"1_week"</strong>, -<strong>"1_month"</strong>, <strong>"3_months"</strong>, -<strong>"1_year"</strong>, and <strong>"5_years"</strong>. -Keys refer to the last known weights history of a relay, not to the time -when the weights document was published. -A graph history object is only contained if the time period it covers is -not already contained in another graph history object with shorter time -period and higher data resolution. -The unit is path-selection probability. -Contained graph history objects may contain null values if the relay was -running less than 20% of a given time period. -</p> -</li> - -<li> -<b>guard_probability</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -History object containing the probability -of this relay to be selected for the guard position. -This probability is calculated based on consensus weights, relay flags, -and bandwidth weights in the consensus. -Path selection depends on more factors, so that this probability can only -be an approximation. -The specification of this history object is similar to that in the -<strong>consensus_weight_fraction</strong> field above. -</p> -</li> - -<li> -<b>middle_probability</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -History object containing the probability -of this relay to be selected for the middle position. -This probability is calculated based on consensus weights, relay flags, -and bandwidth weights in the consensus. -Path selection depends on more factors, so that this probability can only -be an approximation. -The specification of this history object is similar to that in the -<strong>consensus_weight_fraction</strong> field above. -</p> -</li> - -<li> -<b>exit_probability</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -History object containing the probability -of this relay to be selected for the exit position. -This probability is calculated based on consensus weights, relay flags, -and bandwidth weights in the consensus. -Path selection depends on more factors, so that this probability can only -be an approximation. -The specification of this history object is similar to that in the -<strong>consensus_weight_fraction</strong> field above. -</p> -</li> - -<li> -<b>consensus_weight</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -History object containing the absolute consensus weight of this relay. -The specification of this history object is similar to that in the -<strong>consensus_weight_fraction</strong> field above. -</p> -</li> - -</ul> - - -<a id="clients"></a><br> -<h2>Clients documents <a href="#clients" class="anchor">#</a> -<span class="request-response"> -<a href="clients?limit=4">example request</a> -</span> -</h2> - -<p> -Clients documents contain estimates of the average number of clients -connecting to a bridge every day. -There are no clients documents available for relays, just for bridges. -Clients documents contain different time intervals and are available for -bridges only. -</p> - -<h3>Bridge clients objects</h3> - -<p> -Bridge clients objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -SHA-1 hash of the bridge fingerprint consisting -of 40 upper-case hexadecimal characters. -</p> -</li> - -<li> -<b>average_clients</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing graph history objects with the average number of clients -connecting to this bridge. -Keys are string representation of the time period covered by the graph -history object. -Keys are fixed strings <strong>"1_week"</strong>, -<strong>"1_month"</strong>, <strong>"3_months"</strong>, -<strong>"1_year"</strong>, and <strong>"5_years"</strong>. -Keys refer to the last known clients history of a bridge, not to the time -when the clients document was published. -A graph history object is only contained if the time period it covers -is not already contained in another clients graph object with shorter -time period and higher data resolution. -The unit is number of clients. -Contained graph history objects may contain null values if the bridge did -not report client statistics for at least 50% of a given time period. -Each graph history object contains the following additional key-value -pairs: -</p> - -<ul class="properties"> - -<li> -<b>countries <span class="label label-danger">beta</span></b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing fractions of clients by country in the considered time -period. -Keys are two-letter lower-case country codes as found in a GeoIP database. -Values are numbers between 0 and 1 standing for the fraction of clients by -country. -A country is only included if at least 1% of clients came from this -country. -Omitted if the bridge did not report client statistics by country. -<span class="red"><strong>BETA:</strong> This field breaks compatibility -with the history objects contained in other documents pretty badly. -It might be removed in the future without notice.</span> -</p> -</li> - -<li> -<b>transports <span class="label label-danger">beta</span></b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing fractions of clients by transport in the considered time -period. -Keys are transport names, or <strong>"<OR>"</strong> for the default -onion-routing transport protocol. -Values are numbers between 0 and 1 standing for the fraction of clients by -transport. -Omitted if the bridge did not report client statistics by transport. -<span class="red"><strong>BETA:</strong> This field breaks compatibility -with the history objects contained in other documents pretty badly. -It might be removed in the future without notice.</span> -</p> -</li> - -<li> -<b>versions <span class="label label-danger">beta</span></b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing fractions of clients by IP version in the considered -time period. -Keys are either <strong>"v4"</strong> for IPv4 or <strong>"v6"</strong> -for IPv6. -Values are numbers between 0 and 1 standing for the fraction of clients by -version. -Omitted if the bridge did not report client statistics by IP version. -<span class="red"><strong>BETA:</strong> This field breaks compatibility -with the history objects contained in other documents pretty badly. -It might be removed in the future without notice.</span> -</p> -</li> - -</ul> - -</li> - -</ul> - - -<a id="uptime"></a><br> -<h2>Uptime documents <a href="#uptime" class="anchor">#</a> -<span class="request-response"> -<a href="uptime?limit=4">example request</a> -</span> -</h2> - -<p> -Uptime documents contain fractional uptimes of relays and bridges. -Uptime documents contain different time intervals and are available for -relays and bridges. -</p> - -<h3>Relay uptime objects</h3> - -<p> -Relay uptime objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -Relay fingerprint consisting of 40 upper-case -hexadecimal characters. -</p> -</li> - -<li> -<b>uptime</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing graph history objects with the fractional uptime of this -relay. -Keys are string representation of the time period covered by the graph -history object. -Keys are fixed strings <strong>"1_week"</strong>, -<strong>"1_month"</strong>, <strong>"3_months"</strong>, -<strong>"1_year"</strong>, and <strong>"5_years"</strong>. -Keys refer to the last known uptime history of a relay, not to the time -when the uptime document was published. -A graph history object is only contained if the time period it covers is -not already contained in another graph history object with shorter time -period and higher data resolution. -The unit is fractional uptime from 0 to 1. -Contained graph history objects may contain null values if less than 20% -of network statuses have been processed for a given time period. -</p> -</li> - -<li> -<b>flags</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing fractional times of this relay having relay flags -assigned. -Keys are flag names like <strong>"Running"</strong> or -<strong>"Exit"</strong>, values are objects similar to the -<strong>uptime</strong> field above, again with keys like -<strong>"1_week"</strong> etc. -If a relay never had a given relay flag assigned, no object is included -for that flag. -</p> -</li> - -</ul> - -<h3>Bridge uptime objects</h3> - -<p> -Bridge uptime objects contain the following key-value pairs: -</p> - -<ul class="properties"> - -<li> -<b>fingerprint</b> -<code class="typeof">string</code> -<span class="required-true">required</span> -<p> -SHA-1 hash of the bridge fingerprint consisting -of 40 upper-case hexadecimal characters. -</p> -</li> - -<li> -<b>uptime</b> -<code class="typeof">object</code> -<span class="required-false">optional</span> -<p> -Object containing uptime history objects for different time periods. -The specification of uptime history objects is similar to those in the -<strong>uptime</strong> field of <strong>relays</strong>. -</p> -</li> - -</ul> - - -<a id="examples"></a><br> -<h2>Example usage <a href="#examples" class="anchor">#</a> -</h2> - -<p> -The following examples illustrate how to build requests for some trivial -and some more complex use cases. -While Onionoo is designed mainly for developers and not end users, there -may be cases when it's easier to quickly write a specific query Onionoo -rather than to find an Onionoo client that provides the desired -information. -</p> - -<p> -<code>/summary?limit=4</code> -(<a href="/summary?limit=4">view result</a>) -</p> - -<p> -This first query returns the first four summary documents that Onionoo can -find. -The <code>limit</code> parameter should always be used while developing -new queries to avoid downloading huge responses. -</p> - -<p> -<code>/summary?limit=4&search=moria</code> -(<a href="/summary?limit=4&search=moria">view result</a>) -</p> - -<p> -The second query restricts results to relays and bridges containing the -string "moria" in one of a few searched fields. -</p> - -<p> -<code>/details?limit=4&search=moria</code> -(<a href="/details?limit=4&search=moria">view result</a>) -</p> - -<p> -The third query switches from the short summary documents to the longer -details documents containing, well, more details. -</p> - -<p> -<code>/details?limit=4&search=moria&fields=nickname</code> -(<a href="/details?limit=4&search=moria&fields=nickname">view result</a>) -</p> - -<p> -The fourth query adds the <code>fields</code> parameter which removes all -fields except the specified ones from the result. -This parameter is only implemented for details documents. -</p> - -<p> -<code>/details?limit=4&search=moria&fields=nickname&order=-consensus_weight</code> -(<a href="/details?limit=4&search=moria&fields=nickname&order=-consensus_weight">view result</a>) -</p> - -<p> -The fifth query sorts results by relay consensus weight from largest to -smallest. -</p> - -<p> -Obviously, this query can be made even more complex by adding more -parameters, and in some cases this is necessary and useful. -Please refer to the protocol specification for details. -</p> - - - -</div> - - - - - - - - - <div class="container-fluid" id="footer"> - - <div class="container no-gutter"> - <div class="col-xs-6"> - <p> - © 2017 The Tor Project - </p> - </div> - <div class="col-xs-6"> - <p class="pull-right"> - - <a href="https://metrics.torproject.org/about.html#contact">Contact</a> - - </p> - </div> - </div> - - <div class="container small"> - - <p>Data on this site is freely available under a <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 no copyright declaration</a>: To the extent possible under law, the Tor Project has waived all copyright and related or neighboring rights in the data. "Tor" and the "Onion Logo" are <a href="https://www.torproject.org/docs/trademark-faq.html.en">registered trademarks</a> of The Tor Project, Inc.</p> - - </div> - - </div><!-- /footer --> - - - -</div><!-- /wrapper --> - -</body> -</html> -