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.