Controller
**********

Module for interacting with the Tor control socket. The "Controller"
is a wrapper around a "ControlSocket", retaining many of its methods
(connect, close, is_alive, etc) in addition to providing its own for
working with the socket at a higher level.

Stem has several ways of getting a "Controller", but the most flexible
are "from_port()" and "from_socket_file()". These static "Controller"
methods give you an **unauthenticated** Controller you can then
authenticate yourself using its "authenticate()" method. For example…

   import getpass
   import sys

   import stem
   import stem.connection

   from stem.control import Controller

   if __name__ == '__main__':
     try:
       controller = Controller.from_port()
     except stem.SocketError as exc:
       print("Unable to connect to tor on port 9051: %s" % exc)
       sys.exit(1)

     try:
       controller.authenticate()
     except stem.connection.MissingPassword:
       pw = getpass.getpass("Controller password: ")

       try:
         controller.authenticate(password = pw)
       except stem.connection.PasswordAuthFailed:
         print("Unable to authenticate, password is incorrect")
         sys.exit(1)
     except stem.connection.AuthenticationFailure as exc:
       print("Unable to authenticate: %s" % exc)
       sys.exit(1)

     print("Tor is running version %s" % controller.get_version())
     controller.close()

If you’re fine with allowing your script to raise exceptions then this
can be more nicely done as…

   from stem.control import Controller

   if __name__ == '__main__':
     with Controller.from_port() as controller:
       controller.authenticate()

       print("Tor is running version %s" % controller.get_version())

**Module Overview:**

   event_description - brief description of a tor event type

   Controller - General controller class intended for direct use
     | |- from_port - Provides a Controller based on a port connection.
     | +- from_socket_file - Provides a Controller based on a socket file connection.
     |
     |- authenticate - authenticates this controller with tor
     |- reconnect - reconnects and authenticates to socket
     |
     |- get_info - issues a GETINFO query for a parameter
     |- get_version - provides our tor version
     |- get_exit_policy - provides our exit policy
     |- get_ports - provides the local ports where tor is listening for connections
     |- get_listeners - provides the addresses and ports where tor is listening for connections
     |- get_accounting_stats - provides stats related to relaying limits
     |- get_protocolinfo - information about the controller interface
     |- get_user - provides the user tor is running as
     |- get_pid - provides the pid of our tor process
     |- get_start_time - timestamp when the tor process began
     |- get_uptime - duration tor has been running
     |- is_user_traffic_allowed - checks if we send or receive direct user traffic
     |
     |- get_microdescriptor - querying the microdescriptor for a relay
     |- get_microdescriptors - provides all currently available microdescriptors
     |- get_server_descriptor - querying the server descriptor for a relay
     |- get_server_descriptors - provides all currently available server descriptors
     |- get_network_status - querying the router status entry for a relay
     |- get_network_statuses - provides all presently available router status entries
     |- get_hidden_service_descriptor - queries the given hidden service descriptor
     |
     |- get_conf - gets the value of a configuration option
     |- get_conf_map - gets the values of multiple configuration options
     |- is_set - determines if an option differs from its default
     |- set_conf - sets the value of a configuration option
     |- reset_conf - reverts configuration options to their default values
     |- set_options - sets or resets the values of multiple configuration options
     |
     |- get_hidden_service_conf - provides our hidden service configuration
     |- set_hidden_service_conf - sets our hidden service configuration
     |- create_hidden_service - creates a new hidden service or adds a new port
     |- remove_hidden_service - removes a hidden service or drops a port
     |
     |- list_ephemeral_hidden_services - list ephemeral hidden serivces
     |- create_ephemeral_hidden_service - create a new ephemeral hidden service
     |- remove_ephemeral_hidden_service - removes an ephemeral hidden service
     |
     |- add_event_listener - attaches an event listener to be notified of tor events
     |- remove_event_listener - removes a listener so it isn't notified of further events
     |
     |- is_caching_enabled - true if the controller has enabled caching
     |- set_caching - enables or disables caching
     |- clear_cache - clears any cached results
     |
     |- load_conf - loads configuration information as if it was in the torrc
     |- save_conf - saves configuration information to the torrc
     |
     |- is_feature_enabled - checks if a given controller feature is enabled
     |- enable_feature - enables a controller feature that has been disabled by default
     |
     |- get_circuit - provides an active circuit
     |- get_circuits - provides a list of active circuits
     |- new_circuit - create new circuits
     |- extend_circuit - create new circuits and extend existing ones
     |- repurpose_circuit - change a circuit's purpose
     |- close_circuit - close a circuit
     |
     |- get_streams - provides a list of active streams
     |- attach_stream - attach a stream to a circuit
     |- close_stream - close a stream
     |
     |- signal - sends a signal to the tor client
     |- is_newnym_available - true if tor would currently accept a NEWNYM signal
     |- get_newnym_wait - seconds until tor would accept a NEWNYM signal
     |- get_effective_rate - provides our effective relaying rate limit
     |- is_geoip_unavailable - true if we've discovered our geoip db to be unavailable
     |- map_address - maps one address to another such that connections to the original are replaced with the other
     +- drop_guards - drops our set of guard relays and picks a new set

   BaseController - Base controller class asynchronous message handling
     |- msg - communicates with the tor process
     |- is_alive - reports if our connection to tor is open or closed
     |- is_localhost - returns if the connection is for the local system or not
     |- connection_time - time when we last connected or disconnected
     |- is_authenticated - checks if we're authenticated to tor
     |- connect - connects or reconnects to tor
     |- close - shuts down our connection to the tor process
     |- get_socket - provides the socket used for control communication
     |- get_latest_heartbeat - timestamp for when we last heard from tor
     |- add_status_listener - notifies a callback of changes in our status
     +- remove_status_listener - prevents further notification of status changes

stem.control.State(enum)

   Enumeration for states that a controller can have.

   +------------+--------------------------------+
   | State      | Description                    |
   |============|================================|
   | **INIT**   | new control connection         |
   +------------+--------------------------------+
   | **RESET**  | received a reset/sighup signal |
   +------------+--------------------------------+
   | **CLOSED** | control connection closed      |
   +------------+--------------------------------+

stem.control.EventType(enum)

   Known types of events that the "add_event_listener()" method of the
   "Controller" can listen for.

   The most frequently listened for event types tend to be the logging
   events (**DEBUG**, **INFO**, **NOTICE**, **WARN**, and **ERR**),
   bandwidth usage (**BW**), and circuit or stream changes (**CIRC**
   and **STREAM**).

   Enums are mapped to "Event" subclasses as follows…

   Deprecated since version 1.6.0: Tor dropped
   EventType.AUTHDIR_NEWDESCS as of version 0.3.2.1. (spec)

   +-------------------------+--------------------------------------------------------+
   | EventType               | Event Class                                            |
   |=========================|========================================================|
   | **ADDRMAP**             | "stem.response.events.AddrMapEvent"                    |
   +-------------------------+--------------------------------------------------------+
   | **AUTHDIR_NEWDESCS**    | "stem.response.events.AuthDirNewDescEvent"             |
   +-------------------------+--------------------------------------------------------+
   | **BUILDTIMEOUT_SET**    | "stem.response.events.BuildTimeoutSetEvent"            |
   +-------------------------+--------------------------------------------------------+
   | **BW**                  | "stem.response.events.BandwidthEvent"                  |
   +-------------------------+--------------------------------------------------------+
   | **CELL_STATS**          | "stem.response.events.CellStatsEvent"                  |
   +-------------------------+--------------------------------------------------------+
   | **CIRC**                | "stem.response.events.CircuitEvent"                    |
   +-------------------------+--------------------------------------------------------+
   | **CIRC_BW**             | "stem.response.events.CircuitBandwidthEvent"           |
   +-------------------------+--------------------------------------------------------+
   | **CIRC_MINOR**          | "stem.response.events.CircMinorEvent"                  |
   +-------------------------+--------------------------------------------------------+
   | **CLIENTS_SEEN**        | "stem.response.events.ClientsSeenEvent"                |
   +-------------------------+--------------------------------------------------------+
   | **CONF_CHANGED**        | "stem.response.events.ConfChangedEvent"                |
   +-------------------------+--------------------------------------------------------+
   | **CONN_BW**             | "stem.response.events.ConnectionBandwidthEvent"        |
   +-------------------------+--------------------------------------------------------+
   | **DEBUG**               | "stem.response.events.LogEvent"                        |
   +-------------------------+--------------------------------------------------------+
   | **DESCCHANGED**         | "stem.response.events.DescChangedEvent"                |
   +-------------------------+--------------------------------------------------------+
   | **ERR**                 | "stem.response.events.LogEvent"                        |
   +-------------------------+--------------------------------------------------------+
   | **GUARD**               | "stem.response.events.GuardEvent"                      |
   +-------------------------+--------------------------------------------------------+
   | **HS_DESC**             | "stem.response.events.HSDescEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **HS_DESC_CONTENT**     | "stem.response.events.HSDescContentEvent"              |
   +-------------------------+--------------------------------------------------------+
   | **INFO**                | "stem.response.events.LogEvent"                        |
   +-------------------------+--------------------------------------------------------+
   | **NETWORK_LIVENESS**    | "stem.response.events.NetworkLivenessEvent"            |
   +-------------------------+--------------------------------------------------------+
   | **NEWCONSENSUS**        | "stem.response.events.NewConsensusEvent"               |
   +-------------------------+--------------------------------------------------------+
   | **NEWDESC**             | "stem.response.events.NewDescEvent"                    |
   +-------------------------+--------------------------------------------------------+
   | **NOTICE**              | "stem.response.events.LogEvent"                        |
   +-------------------------+--------------------------------------------------------+
   | **NS**                  | "stem.response.events.NetworkStatusEvent"              |
   +-------------------------+--------------------------------------------------------+
   | **ORCONN**              | "stem.response.events.ORConnEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **SIGNAL**              | "stem.response.events.SignalEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **STATUS_CLIENT**       | "stem.response.events.StatusEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **STATUS_GENERAL**      | "stem.response.events.StatusEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **STATUS_SERVER**       | "stem.response.events.StatusEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **STREAM**              | "stem.response.events.StreamEvent"                     |
   +-------------------------+--------------------------------------------------------+
   | **STREAM_BW**           | "stem.response.events.StreamBwEvent"                   |
   +-------------------------+--------------------------------------------------------+
   | **TB_EMPTY**            | "stem.response.events.TokenBucketEmptyEvent"           |
   +-------------------------+--------------------------------------------------------+
   | **TRANSPORT_LAUNCHED**  | "stem.response.events.TransportLaunchedEvent"          |
   +-------------------------+--------------------------------------------------------+
   | **WARN**                | "stem.response.events.LogEvent"                        |
   +-------------------------+--------------------------------------------------------+

stem.control.Listener(enum)

   Purposes for inbound connections that Tor handles.

   Changed in version 1.8.0: Added the EXTOR and HTTPTUNNEL listeners.

   +-----------------+------------------------------------------------------------------------------------------------+
   | Listener        | Description                                                                                    |
   |=================|================================================================================================|
   | **OR**          | traffic we’re relaying as a member of the network (torrc’s **ORPort** and **ORListenAddress**) |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **DIR**         | mirroring for tor descriptor content (torrc’s **DirPort** and **DirListenAddress**)            |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **SOCKS**       | client traffic we’re sending over Tor (torrc’s **SocksPort** and **SocksListenAddress**)       |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **TRANS**       | transparent proxy handling (torrc’s **TransPort** and **TransListenAddress**)                  |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **NATD**        | forwarding for ipfw NATD connections (torrc’s **NatdPort** and **NatdListenAddress**)          |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **DNS**         | DNS lookups for our traffic (torrc’s **DNSPort** and **DNSListenAddress**)                     |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **CONTROL**     | controller applications (torrc’s **ControlPort** and **ControlListenAddress**)                 |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **EXTOR**       | pluggable transport for Extended ORPorts (torrc’s **ExtORPort**)                               |
   +-----------------+------------------------------------------------------------------------------------------------+
   | **HTTPTUNNEL**  | http tunneling proxy (torrc’s **HTTPTunnelPort**)                                              |
   +-----------------+------------------------------------------------------------------------------------------------+


Exceptions and Attribute Enums
==============================

Library for working with the tor process.

**Module Overview:**

   Endpoint - Networking endpoint.
     |- ORPort - Tor relay endpoint.
     +- DirPort - Descriptor mirror.

   ControllerError - Base exception raised when using the controller.
     |- ProtocolError - Malformed socket data.
     |
     |- OperationFailed - Tor was unable to successfully complete the operation.
     |  |- UnsatisfiableRequest - Tor was unable to satisfy a valid request.
     |  |  |- CircuitExtensionFailed - Attempt to make or extend a circuit failed.
     |  |  |- DescriptorUnavailable - The given relay descriptor is unavailable.
     |  |  +- Timeout - Caller requested timeout was reached.
     |  |
     |  |
     |  +- InvalidRequest - Invalid request.
     |     +- InvalidArguments - Invalid request parameters.
     |
     +- SocketError - Communication with the socket failed.
        +- SocketClosed - Socket has been shut down.

   DownloadFailed - Inability to download a resource.
     +- DownloadTimeout - Download timeout reached.

stem.Runlevel(enum)

   Rating of importance used for event logging.

   +-------------+-------------------------------------------------------+
   | Runlevel    | Description                                           |
   |=============|=======================================================|
   | **ERR**     | critical issues that impair tor’s ability to function |
   +-------------+-------------------------------------------------------+
   | **WARN**    | non-critical issues the user should be aware of       |
   +-------------+-------------------------------------------------------+
   | **NOTICE**  | information that may be helpful to the user           |
   +-------------+-------------------------------------------------------+
   | **INFO**    | high level runtime information                        |
   +-------------+-------------------------------------------------------+
   | **DEBUG**   | low level runtime information                         |
   +-------------+-------------------------------------------------------+

stem.Signal(enum)

   Signals that the tor process will accept.

   Changed in version 1.3.0: Added the HEARTBEAT signal.

   Changed in version 1.8.0: Added the ACTIVE and DORMANT signals. You
   can check for Tor support for these signals with the
   **DORMANT_MODE** "Requirement"

   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | Signal                    | Description                                                                                                                 |
   |===========================|=============================================================================================================================|
   | **RELOAD** or **HUP**     | reloads our torrc                                                                                                           |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **SHUTDOWN** or **INT**   | shut down, waiting ShutdownWaitLength first if we’re a relay                                                                |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **DUMP** or **USR1**      | dumps information about open connections and circuits to our log                                                            |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **DEBUG** or **USR2**     | switch our logging to the DEBUG runlevel                                                                                    |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **HALT** or **TERM**      | exit tor immediately                                                                                                        |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **NEWNYM**                | switch to new circuits, so new application requests don’t share any circuits with old ones (this also clears our DNS cache) |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **CLEARDNSCACHE**         | clears cached DNS results                                                                                                   |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **HEARTBEAT**             | trigger a heartbeat log message                                                                                             |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **DORMANT**               | enables *dormant mode*, during which tor will avoid cpu and network usage                                                   |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+
   | **ACTIVE**                | disables *dormant mode*                                                                                                     |
   +---------------------------+-----------------------------------------------------------------------------------------------------------------------------+

stem.Flag(enum)

   Flag assigned to tor relays by the authorities to indicate various
   characteristics.

   **Note:** The BADDIRECTORY flag was removed from tor.

   Changed in version 1.5.0: Added the NO_ED_CONSENSUS flag.

   Changed in version 1.8.0: Added the STALE_DESC flag.

   +---------------------+---------------------------------------------------------------------------------+
   | Flag                | Description                                                                     |
   |=====================|=================================================================================|
   | **AUTHORITY**       | relay is a directory authority                                                  |
   +---------------------+---------------------------------------------------------------------------------+
   | **BADEXIT**         | relay shouldn’t be used as an exit due to being either problematic or malicious |
   +---------------------+---------------------------------------------------------------------------------+
   | **BADDIRECTORY**    | relay shouldn’t be used for directory information                               |
   +---------------------+---------------------------------------------------------------------------------+
   | **EXIT**            | relay’s exit policy makes it more useful as an exit rather than middle hop      |
   +---------------------+---------------------------------------------------------------------------------+
   | **FAST**            | relay’s suitable for high-bandwidth circuits                                    |
   +---------------------+---------------------------------------------------------------------------------+
   | **GUARD**           | relay’s suitable for being an entry guard (first hop)                           |
   +---------------------+---------------------------------------------------------------------------------+
   | **HSDIR**           | relay is being used as a v2 hidden service directory                            |
   +---------------------+---------------------------------------------------------------------------------+
   | **NAMED**           | relay can be referred to by its nickname                                        |
   +---------------------+---------------------------------------------------------------------------------+
   | **NO_ED_CONSENSUS** | relay’s Ed25519 doesn’t reflrect the consensus                                  |
   +---------------------+---------------------------------------------------------------------------------+
   | **RUNNING**         | relay is currently usable                                                       |
   +---------------------+---------------------------------------------------------------------------------+
   | **STABLE**          | relay’s suitable for long-lived circuits                                        |
   +---------------------+---------------------------------------------------------------------------------+
   | **STALE_DESC**      | relay descriptor is outdated and should be re-uploaded                          |
   +---------------------+---------------------------------------------------------------------------------+
   | **UNNAMED**         | relay isn’t currently bound to a nickname                                       |
   +---------------------+---------------------------------------------------------------------------------+
   | **V2DIR**           | relay supports the v2 directory protocol                                        |
   +---------------------+---------------------------------------------------------------------------------+
   | **VALID**           | relay has been validated                                                        |
   +---------------------+---------------------------------------------------------------------------------+

stem.CircStatus(enum)

   Statuses that a circuit can be in. Tor may provide statuses not in
   this enum.

   Changed in version 1.6.0: Added the GUARD_WAIT signal.

   +----------------+----------------------------------------------------------------------+
   | CircStatus     | Description                                                          |
   |================|======================================================================|
   | **LAUNCHED**   | new circuit was created                                              |
   +----------------+----------------------------------------------------------------------+
   | **BUILT**      | circuit finished being created and can accept traffic                |
   +----------------+----------------------------------------------------------------------+
   | **GUARD_WAIT** | waiting to see if there’s a circuit with a better guard before using |
   +----------------+----------------------------------------------------------------------+
   | **EXTENDED**   | circuit has been extended by a hop                                   |
   +----------------+----------------------------------------------------------------------+
   | **FAILED**     | circuit construction failed                                          |
   +----------------+----------------------------------------------------------------------+
   | **CLOSED**     | circuit has been closed                                              |
   +----------------+----------------------------------------------------------------------+

stem.CircBuildFlag(enum)

   Attributes about how a circuit is built. These were introduced in
   tor version 0.2.3.11. Tor may provide flags not in this enum.

   +-------------------+---------------------------------------------------+
   | CircBuildFlag     | Description                                       |
   |===================|===================================================|
   | **ONEHOP_TUNNEL** | single hop circuit to fetch directory information |
   +-------------------+---------------------------------------------------+
   | **IS_INTERNAL**   | circuit that won’t be used for client traffic     |
   +-------------------+---------------------------------------------------+
   | **NEED_CAPACITY** | circuit only includes high capacity relays        |
   +-------------------+---------------------------------------------------+
   | **NEED_UPTIME**   | circuit only includes relays with a high uptime   |
   +-------------------+---------------------------------------------------+

stem.CircPurpose(enum)

   Description of what a circuit is intended for. These were
   introduced in tor version 0.2.1.6. Tor may provide purposes not in
   this enum.

   +----------------------+-----------------------------------------------------------------+
   | CircPurpose          | Description                                                     |
   |======================|=================================================================|
   | **GENERAL**          | client traffic or fetching directory information                |
   +----------------------+-----------------------------------------------------------------+
   | **HS_CLIENT_INTRO**  | client side introduction point for a hidden service circuit     |
   +----------------------+-----------------------------------------------------------------+
   | **HS_CLIENT_REND**   | client side hidden service rendezvous circuit                   |
   +----------------------+-----------------------------------------------------------------+
   | **HS_SERVICE_INTRO** | server side introduction point for a hidden service circuit     |
   +----------------------+-----------------------------------------------------------------+
   | **HS_SERVICE_REND**  | server side hidden service rendezvous circuit                   |
   +----------------------+-----------------------------------------------------------------+
   | **TESTING**          | testing to see if we’re reachable, so we can be used as a relay |
   +----------------------+-----------------------------------------------------------------+
   | **CONTROLLER**       | circuit that was built by a controller                          |
   +----------------------+-----------------------------------------------------------------+
   | **MEASURE_TIMEOUT**  | circuit being kept around to see how long it takes              |
   +----------------------+-----------------------------------------------------------------+

stem.CircClosureReason(enum)

   Reason that a circuit is being closed or failed to be established.
   Tor may provide reasons not in this enum.

   +---------------------------+---------------------------------------------------------------------------+
   | CircClosureReason         | Description                                                               |
   |===========================|===========================================================================|
   | **NONE**                  | no reason given                                                           |
   +---------------------------+---------------------------------------------------------------------------+
   | **TORPROTOCOL**           | violation in the tor protocol                                             |
   +---------------------------+---------------------------------------------------------------------------+
   | **INTERNAL**              | internal error                                                            |
   +---------------------------+---------------------------------------------------------------------------+
   | **REQUESTED**             | requested by the client via a TRUNCATE command                            |
   +---------------------------+---------------------------------------------------------------------------+
   | **HIBERNATING**           | relay is currently hibernating                                            |
   +---------------------------+---------------------------------------------------------------------------+
   | **RESOURCELIMIT**         | relay is out of memory, sockets, or circuit IDs                           |
   +---------------------------+---------------------------------------------------------------------------+
   | **CONNECTFAILED**         | unable to contact the relay                                               |
   +---------------------------+---------------------------------------------------------------------------+
   | **OR_IDENTITY**           | relay had the wrong OR identification                                     |
   +---------------------------+---------------------------------------------------------------------------+
   | **OR_CONN_CLOSED**        | connection failed after being established                                 |
   +---------------------------+---------------------------------------------------------------------------+
   | **FINISHED**              | circuit has expired (see tor’s MaxCircuitDirtiness config option)         |
   +---------------------------+---------------------------------------------------------------------------+
   | **TIMEOUT**               | circuit construction timed out                                            |
   +---------------------------+---------------------------------------------------------------------------+
   | **DESTROYED**             | circuit unexpectedly closed                                               |
   +---------------------------+---------------------------------------------------------------------------+
   | **NOPATH**                | not enough relays to make a circuit                                       |
   +---------------------------+---------------------------------------------------------------------------+
   | **NOSUCHSERVICE**         | requested hidden service does not exist                                   |
   +---------------------------+---------------------------------------------------------------------------+
   | **MEASUREMENT_EXPIRED**   | same as **TIMEOUT** except that it was left open for measurement purposes |
   +---------------------------+---------------------------------------------------------------------------+

stem.CircEvent(enum)

   Type of change reflected in a circuit by a CIRC_MINOR event. Tor
   may provide event types not in this enum.

   +-----------------------+--------------------------------------------------------------+
   | CircEvent             | Description                                                  |
   |=======================|==============================================================|
   | **PURPOSE_CHANGED**   | circuit purpose or hidden service state has changed          |
   +-----------------------+--------------------------------------------------------------+
   | **CANNIBALIZED**      | circuit connections are being reused for a different circuit |
   +-----------------------+--------------------------------------------------------------+

stem.HiddenServiceState(enum)

   State that a hidden service circuit can have. These were introduced
   in tor version 0.2.3.11. Tor may provide states not in this enum.

   Enumerations fall into four groups based on their prefix…

   +---------+---------------------------------+
   | Prefix  | Description                     |
   |=========|=================================|
   | HSCI_*  | client-side introduction-point  |
   +---------+---------------------------------+
   | HSCR_*  | client-side rendezvous-point    |
   +---------+---------------------------------+
   | HSSI_*  | service-side introduction-point |
   +---------+---------------------------------+
   | HSSR_*  | service-side rendezvous-point   |
   +---------+---------------------------------+

   +-------------------------------+--------------------------------------------------------+
   | HiddenServiceState            | Description                                            |
   |===============================|========================================================|
   | **HSCI_CONNECTING**           | connecting to the introductory point                   |
   +-------------------------------+--------------------------------------------------------+
   | **HSCI_INTRO_SENT**           | sent INTRODUCE1 and awaiting a reply                   |
   +-------------------------------+--------------------------------------------------------+
   | **HSCI_DONE**                 | received a reply, circuit is closing                   |
   +-------------------------------+--------------------------------------------------------+
   | **HSCR_CONNECTING**           | connecting to the introductory point                   |
   +-------------------------------+--------------------------------------------------------+
   | **HSCR_ESTABLISHED_IDLE**     | rendezvous-point established, awaiting an introduction |
   +-------------------------------+--------------------------------------------------------+
   | **HSCR_ESTABLISHED_WAITING**  | introduction received, awaiting a rend                 |
   +-------------------------------+--------------------------------------------------------+
   | **HSCR_JOINED**               | connected to the hidden service                        |
   +-------------------------------+--------------------------------------------------------+
   | **HSSI_CONNECTING**           | connecting to the introductory point                   |
   +-------------------------------+--------------------------------------------------------+
   | **HSSI_ESTABLISHED**          | established introductory point                         |
   +-------------------------------+--------------------------------------------------------+
   | **HSSR_CONNECTING**           | connecting to the introductory point                   |
   +-------------------------------+--------------------------------------------------------+
   | **HSSR_JOINED**               | connected to the rendezvous-point                      |
   +-------------------------------+--------------------------------------------------------+

stem.RelayEndReason(enum)

   Reasons why the stream is to be closed.

   +---------------------+----------------------------------------------------------------------+
   | RelayEndReason      | Description                                                          |
   |=====================|======================================================================|
   | **MISC**            | none of the following reasons                                        |
   +---------------------+----------------------------------------------------------------------+
   | **RESOLVEFAILED**   | unable to resolve the hostname                                       |
   +---------------------+----------------------------------------------------------------------+
   | **CONNECTREFUSED**  | remote host refused the connection                                   |
   +---------------------+----------------------------------------------------------------------+
   | **EXITPOLICY**      | OR refuses to connect to the destination                             |
   +---------------------+----------------------------------------------------------------------+
   | **DESTROY**         | circuit is being shut down                                           |
   +---------------------+----------------------------------------------------------------------+
   | **DONE**            | connection has been closed                                           |
   +---------------------+----------------------------------------------------------------------+
   | **TIMEOUT**         | connection timed out                                                 |
   +---------------------+----------------------------------------------------------------------+
   | **NOROUTE**         | routing error while contacting the destination                       |
   +---------------------+----------------------------------------------------------------------+
   | **HIBERNATING**     | relay is temporarily hibernating                                     |
   +---------------------+----------------------------------------------------------------------+
   | **INTERNAL**        | internal error at the relay                                          |
   +---------------------+----------------------------------------------------------------------+
   | **RESOURCELIMIT**   | relay has insufficient resources to service the request              |
   +---------------------+----------------------------------------------------------------------+
   | **CONNRESET**       | connection was unexpectedly reset                                    |
   +---------------------+----------------------------------------------------------------------+
   | **TORPROTOCOL**     | violation in the tor protocol                                        |
   +---------------------+----------------------------------------------------------------------+
   | **NOTDIRECTORY**    | directory information requested from a relay that isn’t mirroring it |
   +---------------------+----------------------------------------------------------------------+

stem.StreamStatus(enum)

   State that a stream going through tor can have. Tor may provide
   states not in this enum.

   +-------------------+-------------------------------------------------+
   | StreamStatus      | Description                                     |
   |===================|=================================================|
   | **NEW**           | request for a new connection                    |
   +-------------------+-------------------------------------------------+
   | **NEWRESOLVE**    | request to resolve an address                   |
   +-------------------+-------------------------------------------------+
   | **REMAP**         | address is being re-mapped to another           |
   +-------------------+-------------------------------------------------+
   | **SENTCONNECT**   | sent a connect cell along a circuit             |
   +-------------------+-------------------------------------------------+
   | **SENTRESOLVE**   | sent a resolve cell along a circuit             |
   +-------------------+-------------------------------------------------+
   | **SUCCEEDED**     | stream has been established                     |
   +-------------------+-------------------------------------------------+
   | **FAILED**        | stream is detached, and won’t be re-established |
   +-------------------+-------------------------------------------------+
   | **DETACHED**      | stream is detached, but might be re-established |
   +-------------------+-------------------------------------------------+
   | **CLOSED**        | stream has closed                               |
   +-------------------+-------------------------------------------------+

stem.StreamClosureReason(enum)

   Reason that a stream is being closed or failed to be established.
   This includes all values in the "RelayEndReason" enumeration as
   well as the following. Tor may provide reasons not in this enum.

   +-----------------------+-----------------------------------------------------------+
   | StreamClosureReason   | Description                                               |
   |=======================|===========================================================|
   | **END**               | endpoint has sent a RELAY_END cell                        |
   +-----------------------+-----------------------------------------------------------+
   | **PRIVATE_ADDR**      | endpoint was a private address (127.0.0.1, 10.0.0.1, etc) |
   +-----------------------+-----------------------------------------------------------+

stem.StreamSource(enum)

   Cause of a stream being remapped to another address. Tor may
   provide sources not in this enum.

   +---------------+---------------------------------------------+
   | StreamSource  | Description                                 |
   |===============|=============================================|
   | **CACHE**     | tor is remapping because of a cached answer |
   +---------------+---------------------------------------------+
   | **EXIT**      | exit relay requested the remap              |
   +---------------+---------------------------------------------+

stem.StreamPurpose(enum)

   Purpsoe of the stream. This is only provided with new streams and
   tor may provide purposes not in this enum.

   +-------------------+-----------------------------------------------------------------+
   | StreamPurpose     | Description                                                     |
   |===================|=================================================================|
   | **DIR_FETCH**     | fetching directory information (descriptors, consensus, etc)    |
   +-------------------+-----------------------------------------------------------------+
   | **DIR_UPLOAD**    | uploading our descriptor to an authority                        |
   +-------------------+-----------------------------------------------------------------+
   | **DNS_REQUEST**   | user initiated DNS request                                      |
   +-------------------+-----------------------------------------------------------------+
   | **DIRPORT_TEST**  | checking that our directory port is reachable externally        |
   +-------------------+-----------------------------------------------------------------+
   | **USER**          | either relaying user traffic or not one of the above categories |
   +-------------------+-----------------------------------------------------------------+

stem.ORStatus(enum)

   State that an OR connection can have. Tor may provide states not in
   this enum.

   +-----------------+-----------------------------------------------------------------+
   | ORStatus        | Description                                                     |
   |=================|=================================================================|
   | **NEW**         | received OR connection, starting server-side handshake          |
   +-----------------+-----------------------------------------------------------------+
   | **LAUNCHED**    | launched outbound OR connection, starting client-side handshake |
   +-----------------+-----------------------------------------------------------------+
   | **CONNECTED**   | OR connection has been established                              |
   +-----------------+-----------------------------------------------------------------+
   | **FAILED**      | attempt to establish OR connection failed                       |
   +-----------------+-----------------------------------------------------------------+
   | **CLOSED**      | OR connection has been closed                                   |
   +-----------------+-----------------------------------------------------------------+

stem.ORClosureReason(enum)

   Reason that an OR connection is being closed or failed to be
   established. Tor may provide reasons not in this enum.

   +---------------------+----------------------------------------------------------------------------------+
   | ORClosureReason     | Description                                                                      |
   |=====================|==================================================================================|
   | **DONE**            | OR connection shut down cleanly                                                  |
   +---------------------+----------------------------------------------------------------------------------+
   | **CONNECTREFUSED**  | got a ECONNREFUSED when connecting to the relay                                  |
   +---------------------+----------------------------------------------------------------------------------+
   | **IDENTITY**        | identity of the relay wasn’t what we expected                                    |
   +---------------------+----------------------------------------------------------------------------------+
   | **CONNECTRESET**    | got a ECONNRESET or similar error from relay                                     |
   +---------------------+----------------------------------------------------------------------------------+
   | **TIMEOUT**         | got a ETIMEOUT or similar error from relay                                       |
   +---------------------+----------------------------------------------------------------------------------+
   | **NOROUTE**         | got a ENOTCONN, ENETUNREACH, ENETDOWN, EHOSTUNREACH, or similar error from relay |
   +---------------------+----------------------------------------------------------------------------------+
   | **IOERROR**         | got a different kind of error from relay                                         |
   +---------------------+----------------------------------------------------------------------------------+
   | **RESOURCELIMIT**   | relay has insufficient resources to service the request                          |
   +---------------------+----------------------------------------------------------------------------------+
   | **MISC**            | connection refused for another reason                                            |
   +---------------------+----------------------------------------------------------------------------------+
   | **PT_MISSING**      | no pluggable transport was available                                             |
   +---------------------+----------------------------------------------------------------------------------+

stem.AuthDescriptorAction(enum)

   Actions that directory authorities might take with relay
   descriptors. Tor may provide reasons not in this enum.

   +-----------------------+------------------------------------------------------+
   | AuthDescriptorAction  | Description                                          |
   |=======================|======================================================|
   | **ACCEPTED**          | accepting the descriptor as the newest version       |
   +-----------------------+------------------------------------------------------+
   | **DROPPED**           | descriptor rejected without notifying the relay      |
   +-----------------------+------------------------------------------------------+
   | **REJECTED**          | relay notified that its descriptor has been rejected |
   +-----------------------+------------------------------------------------------+

stem.StatusType(enum)

   Sources for tor status events. Tor may provide types not in this
   enum.

   +---------------+-------------------------------------------------------------+
   | StatusType    | Description                                                 |
   |===============|=============================================================|
   | **GENERAL**   | general tor activity, not specifically as a client or relay |
   +---------------+-------------------------------------------------------------+
   | **CLIENT**    | related to our activity as a tor client                     |
   +---------------+-------------------------------------------------------------+
   | **SERVER**    | related to our activity as a tor relay                      |
   +---------------+-------------------------------------------------------------+

stem.GuardType(enum)

   Use a guard relay can be for. Tor may provide types not in this
   enum.

   +-------------+------------------------------------+
   | GuardType   | Description                        |
   |=============|====================================|
   | **ENTRY**   | used to connect to the tor network |
   +-------------+------------------------------------+

stem.GuardStatus(enum)

   Status a guard relay can have. Tor may provide types not in this
   enum.

   +---------------+-------------------------------------------------------------------+
   | GuardStatus   | Description                                                       |
   |===============|===================================================================|
   | **NEW**       | new guard that we weren’t previously using                        |
   +---------------+-------------------------------------------------------------------+
   | **DROPPED**   | removed from use as one of our guards                             |
   +---------------+-------------------------------------------------------------------+
   | **UP**        | guard is now reachable                                            |
   +---------------+-------------------------------------------------------------------+
   | **DOWN**      | guard is now unreachable                                          |
   +---------------+-------------------------------------------------------------------+
   | **BAD**       | consensus or relay considers this relay to be unusable as a guard |
   +---------------+-------------------------------------------------------------------+
   | **GOOD**      | consensus or relay considers this relay to be usable as a guard   |
   +---------------+-------------------------------------------------------------------+

stem.TimeoutSetType(enum)

   Way in which the timeout value of a circuit is changing. Tor may
   provide types not in this enum.

   +-----------------+--------------------------------------------------------------------------+
   | TimeoutSetType  | Description                                                              |
   |=================|==========================================================================|
   | **COMPUTED**    | tor has computed a new timeout based on prior circuits                   |
   +-----------------+--------------------------------------------------------------------------+
   | **RESET**       | timeout reverted to its default                                          |
   +-----------------+--------------------------------------------------------------------------+
   | **SUSPENDED**   | timeout reverted to its default until network connectivity has recovered |
   +-----------------+--------------------------------------------------------------------------+
   | **DISCARD**     | throwing out timeout value from when the network was down                |
   +-----------------+--------------------------------------------------------------------------+
   | **RESUME**      | resumed calculations to determine the proper timeout                     |
   +-----------------+--------------------------------------------------------------------------+

stem.ConnectionType(enum)

   Purpose for a tor connection. Tor may provide types not in this
   enum.

   The meaning behind these values is a bit unclear, pending ticket
   10086.

   Added in version 1.2.0.

   +-----------------+----------------------------------------------------------------------+
   | ConnectionType  | Description                                                          |
   |=================|======================================================================|
   | **OR**          | carrying traffic within the tor network                              |
   +-----------------+----------------------------------------------------------------------+
   | **DIR**         | fetching or sending tor descriptor data                              |
   +-----------------+----------------------------------------------------------------------+
   | **EXIT**        | carrying traffic between the tor network and an external destination |
   +-----------------+----------------------------------------------------------------------+

stem.TokenBucket(enum)

   Bucket categories of TB_EMPTY events.

   Added in version 1.2.0.

   +-----------------+--------------------------------+
   | TokenBucket     | Description                    |
   |=================|================================|
   | **GLOBAL**      | global token bucket            |
   +-----------------+--------------------------------+
   | **RELAY**       | relay token bucket             |
   +-----------------+--------------------------------+
   | **ORCONN**      | bucket used for OR connections |
   +-----------------+--------------------------------+

stem.HSDescAction(enum)

   Action beeing taken in a HS_DESC event.

   Added in version 1.2.0.

   Changed in version 1.4.0: Added the UPLOAD and UPLOADED actions.

   Changed in version 1.5.0: Added the CREATED action.

   +-----------------+--------------------------------------------------------------------------+
   | HSDescAction    | Description                                                              |
   |=================|==========================================================================|
   | **REQUESTED**   | uncached hidden service descriptor is being requested                    |
   +-----------------+--------------------------------------------------------------------------+
   | **UPLOAD**      | descriptor is being uploaded with HSPOST                                 |
   +-----------------+--------------------------------------------------------------------------+
   | **RECEIVED**    | hidden service descriptor has been retrieved                             |
   +-----------------+--------------------------------------------------------------------------+
   | **UPLOADED**    | descriptor was uploaded with HSPOST                                      |
   +-----------------+--------------------------------------------------------------------------+
   | **IGNORE**      | fetched descriptor was ignored because we already have its v0 descriptor |
   +-----------------+--------------------------------------------------------------------------+
   | **FAILED**      | we were unable to retrieve the descriptor                                |
   +-----------------+--------------------------------------------------------------------------+
   | **CREATED**     | hidden service descriptor was just created                               |
   +-----------------+--------------------------------------------------------------------------+

stem.HSDescReason(enum)

   Reason for the hidden service descriptor to fail to be fetched.

   Added in version 1.3.0.

   Changed in version 1.4.0: Added the UPLOAD_REJECTED reason.

   Changed in version 1.6.0: Added the QUERY_NO_HSDIR reason.

   Changed in version 1.8.0: Added the QUERY_RATE_LIMITED reason.

   +-------------------------+------------------------------------------------------------+
   | HSDescReason            | Description                                                |
   |=========================|============================================================|
   | **BAD_DESC**            | descriptor was unparseable                                 |
   +-------------------------+------------------------------------------------------------+
   | **QUERY_REJECTED**      | hidden service directory refused to provide the descriptor |
   +-------------------------+------------------------------------------------------------+
   | **UPLOAD_REJECTED**     | descriptor was rejected by the hidden service directory    |
   +-------------------------+------------------------------------------------------------+
   | **NOT_FOUND**           | descriptor with the given identifier wasn’t found          |
   +-------------------------+------------------------------------------------------------+
   | **QUERY_NO_HSDIR**      | no hidden service directory was found                      |
   +-------------------------+------------------------------------------------------------+
   | **QUERY_RATE_LIMITED**  | request was throttled                                      |
   +-------------------------+------------------------------------------------------------+
   | **UNEXPECTED**          | failure type is unknown                                    |
   +-------------------------+------------------------------------------------------------+

stem.HSAuth(enum)

   Type of authentication being used for a HS_DESC event.

   Added in version 1.2.0.

   +-------------------+-----------------------------------------------------------------------------+
   | HSAuth            | Description                                                                 |
   |===================|=============================================================================|
   | **NO_AUTH**       | no authentication                                                           |
   +-------------------+-----------------------------------------------------------------------------+
   | **BASIC_AUTH**    | general hidden service authentication                                       |
   +-------------------+-----------------------------------------------------------------------------+
   | **STEALTH_AUTH**  | authentication method that hides service activity from unauthorized clients |
   +-------------------+-----------------------------------------------------------------------------+
   | **UNKNOWN**       | unrecognized method of authentication                                       |
   +-------------------+-----------------------------------------------------------------------------+
