stem_examples/README.md

stem_examples

Examples of using the Python stem library to query the state of a running tor.

You can set TOR_CONTROLLER_PASSWORD in the environment if your tor control port requires a password.

• check_digests
• compare_flags
• exit_used
• introduction_points
• list_circuits
• mappaddress
• outdated_relays
• relay_connections
• tor_bootstrap_check

check_digests

Checking Descriptor Digests

Tor relay information is provided by multiple documents. Signed descriptors transitively validate others by inclusion of their digest. For example, our consensus references server descriptor digest, and server descriptors in turn cite extrainfo digests.

Stem can calculate digests from server, extrainfo, microdescriptor, and consensus documents. For instance, to validate an extrainfo descriptor...

https://stem.torproject.org/tutorials/examples/check_digests.html

compare_flags Comparing Directory Authority Flags

Compares the votes of two directory authorities, in this case moria1 and maatuska, with a special interest in the 'Running' flag.

https://stem.torproject.org/tutorials/examples/compare_flags.html

connection_resolution Connection Resolution

Connection information is a useful tool for learning more about network applications like Tor. Our stem.util.connection.get_connections() function provides an easy method for accessing this information.

exit_used Exit Used

Determine The Exit You're Using

https://stem.torproject.org/tutorials/examples/exit_used.html

introduction_points Introduction Points

This script tests if you can reach a hidden service, passed as an onion address as an argument. If no argument is given, 3 common onion sites are tested: Facebook, DuckDuckGo, and .

https://stem.torproject.org/tutorials/over_the_river.html

list_circuits List Circuits

Tor creates new circuits and tears down old ones on your behalf, so how can you get information about circuits Tor currently has available? https://stem.torproject.org/tutorials/examples/list_circuits.html

mappaddress

Mappaddress queries the socks proxy with an onion address and returns the IP address that it will use for it. the address will be in the block specified by the VirtualAddrNetworkIPv4 setting of the torrc, e.g.

VirtualAddrNetworkIPv4 172.16.0.0/12

outdated_relays List Outdated Relays

Time marches on. Tor makes new releases, and at some point needs to drop support for old ones. Below is the script we used on ticket 9476 to reach out to relay operators that needed to upgrade.

https://stem.torproject.org/tutorials/examples/outdated_relays.html

relay_connections Connection Summary

The following provides a summary of your relay's inbound and outbound connections.

To use this you must set DisableDebuggerAttachment 0 in your torrc. Otherwise connection information will be unavailable.

https://stem.torproject.org/tutorials/examples/relay_connections.html

Download Tor Descriptors

Tor relays provide a mirror for the tor relay descriptors it has cached. These are available from its ORPort using Tor's wire protocol, and optionally with http as well from a DirPort.

https://stem.torproject.org/tutorials/examples/download_descriptor.html

Votes by Bandwidth Authorities

Tor takes into account a relay's throughput when picking a route through the Tor network for its circuits. That is to say large, fast relays receive more traffic than small ones since they can better service the load.

To determine a relay's throughput special authorities, called bandwidth authorities, take periodic measurements using them. The lifecycle of new Tor relays is a bit more complicated than that, butthat's the general idea.

Bandwidth authorities include their measurements in their votes. The following gets their current votes then prints how many relays it had a measurement for.

https://stem.torproject.org/tutorials/examples/votes_by_bandwidth_authorities.html

tor_bootstrap_check

A script by adrelanos@riseup.net to check what percentage of boostrapping tor is at.