Introduction

Network Status APIs

Network Status APIs is a web-based protocol to learn about currently running Tor relays and bridges. Network Status APIs itself was not designed as a service for human beings---at least not directly.

If you want to host your own version of Network Status APIs, read INSTALL.md

Network Status APIs | Installation Guide

Welcome to Network Status APIs! This guide will teach you how you to host your very own instance of Network Status APIs.

What you need

The only thing that is required to compile the project is Rust 1.68+, you can install it by following the official guide on Rust's webiste

Setup

The binary expects to find some env variables at runtime, without those the program will panic. You can find the necessary envs in the .env.example file in the project folder.

Create an .env file that will contain the needed variables to run the service locally:

$ cat .env.example > .env

You may need to contact the Tor admins if you need access to some of the variables needed in .env file.

Run with cargo

After Rust is installed on your machine, you simply need to run

$ cargo run --release

Build from source

If you want to build the program from source, you can run

$ cargo build --release

This will install all the dependencies needed to compile the project's binary, after compilation completes successfully you'll find the binary under /target/release.

Finally, you can run the binary by simply running the binary

$ ./target/release/network-status-api

Technical documentation

Onionoo API

Summary from https://metrics.torproject.org/onionoo.html#uptime

Endpoints:

  • /details

  • /bandwidth

  • /weights

  • `/clients

  • /uptime

  • /summary

Parameters:

  • For /search:
    • fp
    • nickname
    • ip
    • hashed hex-encoded fingerprint
    • "qualified search term" in the form key:value. Possible keys:
      • ~~ search, fingerprint, order, limit, offset, fields~~'
      • 'as_name'
      • 'as'
      • 'contact'
      • 'country'
      • 'family'
      • 'first_seen_days'
      • 'flag'
      • 'host_name'
      • 'last_seen_days'
      • 'lookup' (fingerprint)
      • 'os'
      • 'recommended_version
      • 'running'
      • 'type'
      • 'version' For relay/bridge details response
      • fields
        • nickname
        • hashed_fingerprint
        • ?
  • 'as_name'
  • 'as'
  • 'contact'
  • 'country'
  • 'family'
  • 'first_seen_days'
  • 'flag'
  • 'host_name'
  • 'last_seen_days'
  • 'lookup'
  • 'os'
  • 'recommended_version
  • 'running'
  • 'type'
  • 'version'

For relay/bridge documents:

  • limit
  • offset
  • limit

Responses

  • version'
  • 'next_major_version_scheduled'
  • 'build_revision'
  • 'relays_published'
  • 'relays_skipped'
  • 'relays'
  • 'relays_truncated'
  • 'bridges_published'
  • 'bridges_skipped'
  • 'bridges'
  • 'bridges_truncated

Details documents

Relay Details documents

  • 'advertised_bandwidth'
  • 'alleged_family'
  • 'as'
  • 'as_name'
  • 'bandwidth_avg'
  • 'bandwidth_burst'
  • 'city_name'
  • 'consensus_weight'
  • 'consensus_weight_fraction'
  • 'contact'
  • 'country'
  • 'country_name'
  • 'dir_address'
  • 'effective_family'
  • 'exit_addresses'
  • 'exit_policy'
  • 'exit_policy_summary'
  • 'exit_policy_v6_summary'
  • 'exit_probability'
  • 'fingerprint'
  • 'first_seen'
  • 'flags'
  • 'guard_probability'
  • 'hibernating'
  • 'host_name'
  • 'indirect_family'
  • 'last_changed_address_or_port'
  • 'last_restarted'
  • 'last_seen'
  • 'latitude'
  • 'longitude'
  • 'measured'
  • 'middle_probability'
  • 'nickname'
  • 'observed_bandwidth'
  • 'or_addresses'
  • 'overload_general_timestamp'
  • 'platform'
  • 'recommended_version'
  • 'region_name'
  • 'running'
  • 'unreachable_or_address'
  • 'unverified_host_names'
  • 'verified_host_names'
  • 'version'
  • 'version_status`

Bridge Details documents

  • 'advertised_bandwidth'
  • 'contact'
  • 'first_seen'
  • 'flags'
  • 'last_restarted'
  • 'last_seen'
  • 'nickname'
  • 'or_addresses'
  • 'overload_general_timestamp'
  • 'platform'
  • 'recommended_version'
  • 'running'
  • 'version_status`
  • 'version'
  • blocklist
  • bridgedb_distributor
  • hashed_fingerprint
  • transports

Graph History objects

  • `first'
  • 'last'
  • 'interval'
  • 'factor'
  • 'count'
  • 'values

Bandwidth documents

Relay bandwidth objects

  • 'fingerprint'
  • 'overload_fd_exhausted`
  • 'overload_ratelimits'
  • 'read_history'
  • 'write_history'

Bridge bandwidth objects

^ same?

  • 'fingerprint'
  • 'overload_fd_exhausted`
  • 'overload_ratelimits'
  • 'read_history'
  • 'write_history'

Weights documents

Relay weights objects

'

  • 'fingerprint'
  • 'consensus_weight_fraction'
  • 'guard_probability'
  • 'middle_probability'
  • 'exit_probability'
  • 'consensus_weight

Client documents

Bridge client objects

  • 'average_clients'
  • 'fingerprint`

Uptime documents

Relay Uptime objects

  • 'fingerprint'
  • 'flags'
  • 'uptime`

Bridge Uptime objects

  • 'fingerprint'
  • 'uptime`

Known applications that use or will this Web API

From @irl feedback and other issues:

Endpoints that can be dropped:

  • /summary was only ever used by Tor Atlas
  • One of the keys lets you look up history of historical relays to verify the first_seen and uptime, and was only ever used by the t-shirt awarding Python script.

Endpoints that should stay:

  • /search exists to facilitate Relay Search with human typing on a keyboard queries.
    • improve it by specifying what to spect from some characters (#25)
    • improve it by searching with fp and nickname (#24)
  • key/value parameters exist for easier scripting use, eg. OrNetStats pulling data about relay families or the Bypass Censorship dashboard pulling data about the bridges it runs.
  • The aggregated search feature is widely used. To be implemented server-side

New endpoints:

  • ?: expose the directory authorities shipped with tor (#41)
  • ?: measured bandwidths from votes, bandwidth scanner data (#30)
  • ?: proxy vm queries (#50, metrics exposed to vm) or something similar to vmgateway

New params:

  • pagination (can be implemented with actix-web-pagination)
  • allow parameters and search terms to be specified more than once (#43)
  • additional_flag: currently computed by Relay Search client-side. To be implemented server-side (see also #39)
  • fallback_directory? (#39#note_2985815)
  • ?: search bridges: search by distributor and transport. There's a new 'transport-info' field in the cached-extrainfo: transport-info version=0.1.0 implementation=lyrebird (#55)
  • ed25519 fps? (#40)

New properties in response:

  • ed25519 fps (#40)

advanced relay search:

  • "Not Recommended"

Current Onionoo API:

(uncomplete docs) https://gitlab.torproject.org/juga/networkstatusapi/-/blob/issue56_apistos_doc/docs/src/openapi_onionoo.yaml?ref_type=heads&plain=1

https://networkstatusapi-72c5c5.pages.torproject.net/onionoo.html, https://gitlab.torproject.org/juga/networkstatusapi/-/blob/issue56_apistos_doc/docs/src/onionoo.md?ref_type=heads

Metrics Website list:

https://gitlab.torproject.org/juga/networkstatusapi/-/blob/issue56_apistos_doc/docs/src/metrics_website1.txt?ref_type=heads

Automatically generating OpenAPI specification from the code

Web OpenAPI diagrams

(automatically generated with swagger_to_uml)

API

SVG file, openapi.puml

Class diagrams

(automatically generated with ruml)

models dir:

models

SVG file, models.puml

metrics dir:

metrics

SVG file, metrics.puml

victoriametrics dir:

SVG file, victoriametrics.puml