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...
- if you have ‘DownloadExtraInfo 1’ in your torrc...
- control port via ‘GETINFO extra-info/digest/*’ queries
- the ‘cached-extrainfo’ file in tor’s data directory
- tor metrics, at https://metrics.torproject.org/data.html
- directory authorities and mirrors via their DirPort
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
- 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
- class stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor(raw_contents, validate=True)[source]¶
Bases: stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor
Bridge extra-info descriptor (bridge descriptor specification)