Stem Docs

Extrainfo Descriptor

Extrainfo Descriptor

Parsing for Tor extra-info descriptors. These are published by relays whenever their server descriptor is published and have a similar format. However, unlike server descriptors these don’t contain information that Tor clients require to function and as such aren’t fetched by default.

Defined in section 2.2 of the dir-spec, extra-info descriptors contain interesting but non-vital information such as usage statistics. Tor clients cannot request these documents for bridges.

Extra-info descriptors are available from a few sources...

  • control port via ‘GETINFO extra-info/digest/*’ queries
  • the ‘cached-extrainfo’ file in tor’s data directory

Module Overview:

ExtraInfoDescriptor - Tor extra-info descriptor.
  |  |- RelayExtraInfoDescriptor - Extra-info descriptor for a relay.
  |  +- BridgeExtraInfoDescriptor - Extra-info descriptor for a bridge.
  |
  |- digest - calculates the upper-case hex digest value for our content
  +- get_unrecognized_lines - lines with unrecognized content
stem.descriptor.extrainfo_descriptor.DirResponse(enum)

Enumeration for known statuses for ExtraInfoDescriptor’s dir_*_responses.

DirResponse Description
OK network status requests that were answered
NOT_ENOUGH_SIGS network status wasn’t signed by enough authorities
UNAVAILABLE requested network status was unavailable
NOT_FOUND requested network status was not found
NOT_MODIFIED network status unmodified since If-Modified-Since time
BUSY directory was busy
stem.descriptor.extrainfo_descriptor.DirStat(enum)

Enumeration for known stats for ExtraInfoDescriptor’s dir_*_direct_dl and dir_*_tunneled_dl.

DirStat Description
COMPLETE requests that completed successfully
TIMEOUT requests that didn’t complete within a ten minute timeout
RUNNING requests still in process when measurement’s taken
MIN smallest rate at which a descriptor was downloaded in B/s
MAX largest rate at which a descriptor was downloaded in B/s
D1-4 and D6-9 rate of the slowest x/10 download rates in B/s
Q1 and Q3 rate of the slowest and fastest quarter download rates in B/s
MD median download rate in B/s
class stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor(raw_contents, validate=True)[source]

Bases: stem.descriptor.Descriptor

Extra-info descriptor document.

Variables:
  • nickname (str) – * relay’s nickname
  • fingerprint (str) – * identity key fingerprint
  • published (datetime) – * time in UTC when this descriptor was made
  • geoip_db_digest (str) – sha1 of the geoIP database file for IPv4 addresses
  • geoip6_db_digest (str) – sha1 of the geoIP database file for IPv6 addresses
  • transport (dict) – * mapping of transport methods to their (address, port, args) tuple, these usually appear on bridges in which case all of those are None

Bi-directional connection usage:

Variables:
  • conn_bi_direct_end (datetime) – end of the sampling interval
  • conn_bi_direct_interval (int) – seconds per interval
  • conn_bi_direct_below (int) – connections that read/wrote less than 20 KiB
  • conn_bi_direct_read (int) – connections that read at least 10x more than wrote
  • conn_bi_direct_write (int) – connections that wrote at least 10x more than read
  • conn_bi_direct_both (int) – remaining connections

Bytes read/written for relayed traffic:

Variables:
  • read_history_end (datetime) – end of the sampling interval
  • read_history_interval (int) – seconds per interval
  • read_history_values (list) – bytes read during each interval
  • write_history_end (datetime) – end of the sampling interval
  • write_history_interval (int) – seconds per interval
  • write_history_values (list) – bytes written during each interval

Cell relaying statistics:

Variables:
  • cell_stats_end (datetime) – end of the period when stats were gathered
  • cell_stats_interval (int) – length in seconds of the interval
  • cell_processed_cells (list) – measurement of processed cells per circuit
  • cell_queued_cells (list) – measurement of queued cells per circuit
  • cell_time_in_queue (list) – mean enqueued time in milliseconds for cells
  • cell_circuits_per_decile (int) – mean number of circuits in a decile

Directory Mirror Attributes:

Variables:
  • dir_stats_end (datetime) – end of the period when stats were gathered
  • dir_stats_interval (int) – length in seconds of the interval
  • dir_v2_ips (dict) – mapping of locales to rounded count of requester ips
  • dir_v3_ips (dict) – mapping of locales to rounded count of requester ips
  • dir_v2_share (float) – percent of total directory traffic it expects to serve
  • dir_v3_share (float) – percent of total directory traffic it expects to serve
  • dir_v2_requests (dict) – mapping of locales to rounded count of requests
  • dir_v3_requests (dict) – mapping of locales to rounded count of requests
  • dir_v2_responses (dict) – mapping of DirResponse to their rounded count
  • dir_v3_responses (dict) – mapping of DirResponse to their rounded count
  • dir_v2_responses_unknown (dict) – mapping of unrecognized statuses to their count
  • dir_v3_responses_unknown (dict) – mapping of unrecognized statuses to their count
  • dir_v2_direct_dl (dict) – mapping of DirStat to measurement over DirPort
  • dir_v3_direct_dl (dict) – mapping of DirStat to measurement over DirPort
  • dir_v2_direct_dl_unknown (dict) – mapping of unrecognized stats to their measurement
  • dir_v3_direct_dl_unknown (dict) – mapping of unrecognized stats to their measurement
  • dir_v2_tunneled_dl (dict) – mapping of DirStat to measurement over ORPort
  • dir_v3_tunneled_dl (dict) – mapping of DirStat to measurement over ORPort
  • dir_v2_tunneled_dl_unknown (dict) – mapping of unrecognized stats to their measurement
  • dir_v3_tunneled_dl_unknown (dict) – mapping of unrecognized stats to their measurement

Bytes read/written for directory mirroring:

Variables:
  • dir_read_history_end (datetime) – end of the sampling interval
  • dir_read_history_interval (int) – seconds per interval
  • dir_read_history_values (list) – bytes read during each interval
  • dir_write_history_end (datetime) – end of the sampling interval
  • dir_write_history_interval (int) – seconds per interval
  • dir_write_history_values (list) – bytes read during each interval

Guard Attributes:

Variables:
  • entry_stats_end (datetime) – end of the period when stats were gathered
  • entry_stats_interval (int) – length in seconds of the interval
  • entry_ips (dict) – mapping of locales to rounded count of unique user ips

Exit Attributes:

Variables:
  • exit_stats_end (datetime) – end of the period when stats were gathered
  • exit_stats_interval (int) – length in seconds of the interval
  • exit_kibibytes_written (dict) – traffic per port (keys are ints or ‘other’)
  • exit_kibibytes_read (dict) – traffic per port (keys are ints or ‘other’)
  • exit_streams_opened (dict) – streams per port (keys are ints or ‘other’)

Bridge Attributes:

Variables:
  • bridge_stats_end (datetime) – end of the period when stats were gathered
  • bridge_stats_interval (int) – length in seconds of the interval
  • bridge_ips (dict) – mapping of locales to rounded count of unique user ips
  • geoip_start_time (datetime) – replaced by bridge_stats_end (deprecated)
  • geoip_client_origins (dict) – replaced by bridge_ips (deprecated)
  • ip_versions (dict) – mapping of ip protocols to a rounded count for the number of users
  • ip_versions – mapping of ip transports to a count for the number of users

* attribute is either required when we’re parsed with validation or has a default value, others are left as None if undefined

get_unrecognized_lines()[source]
digest()[source]

Provides the upper-case hex encoded sha1 of our content. This value is part of the server descriptor entry for this relay.

Returns:str with the upper-case hex digest value for this server descriptor
class stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor(raw_contents, validate=True)[source]

Bases: stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor

Relay extra-info descriptor, constructed from data such as that provided by “GETINFO extra-info/digest/*”, cached descriptors, and metrics (specification).

Variables:signature (str) – * signature for this extrainfo descriptor

* attribute is required when we’re parsed with validation

digest(*args, **kwds)[source]
class stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor(raw_contents, validate=True)[source]

Bases: stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor

Bridge extra-info descriptor (bridge descriptor specification)

digest()[source]