commit 7d3f310aea65a00471b021c93e30f40d55f5f268 Author: Karsten Loesing karsten.loesing@gmx.net Date: Thu Jul 6 10:22:09 2017 +0200
Reduce index.html to simple placeholder page.
Implements part of #21551. --- src/main/resources/web/index.html | 2196 +------------------------------------ 1 file changed, 4 insertions(+), 2192 deletions(-)
diff --git a/src/main/resources/web/index.html b/src/main/resources/web/index.html index ab79638..e617f34 100644 --- a/src/main/resources/web/index.html +++ b/src/main/resources/web/index.html @@ -20,12 +20,8 @@ <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"> @@ -33,89 +29,9 @@
<!-- 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">
@@ -126,15 +42,11 @@ document.write('<div class="topButton" style="display:none;"><a href="#top"><i c <div class="jumbotron"> <div class="text-center"> <h2> - The Tor network status protocol + Onionoo </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> - + <p>This page has moved to <code><a href="https://metrics.torproject.org/onionoo.html">https://metrics.torproject.org/onionoo.html</a></code>.</p> + <p>Please update any bookmarks and report any links to this page.</p> + <p>This placeholder page will be removed in the future.</p> </div><!-- text-center -->
@@ -142,2106 +54,6 @@ document.write('<div class="topButton" style="display:none;"><a href="#top"><i c
- - - -<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 -(parameter 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 hibernation 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>
tor-commits@lists.torproject.org
-
karsten＠torproject.org