Stem Docs

Controller

Controller

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.

New 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.

New 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.

New 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.

New 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.

New 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
exception stem.ControllerError[source]

Bases: exceptions.Exception

Base error for controller communication issues.

exception stem.ProtocolError[source]

Bases: stem.ControllerError

Malformed content from the control socket.

exception stem.OperationFailed(code=None, message=None)[source]

Bases: stem.ControllerError

Base exception class for failed operations that return an error code

Variables:
  • code (str) -- error code returned by Tor
  • message (str) -- error message returned by Tor or a human readable error message
exception stem.UnsatisfiableRequest(code=None, message=None)[source]

Bases: stem.OperationFailed

Exception raised if Tor was unable to process our request.

exception stem.CircuitExtensionFailed(message, circ=None)[source]

Bases: stem.UnsatisfiableRequest

An attempt to create or extend a circuit failed.

Variables:circ (stem.response.CircuitEvent) -- response notifying us of the failure
exception stem.DescriptorUnavailable(message)[source]

Bases: stem.UnsatisfiableRequest

Tor was unable to provide a descriptor for the given relay.

Changed in version 1.7.0: Subclassed under UnsatisfiableRequest rather than OperationFailed.

exception stem.Timeout(message)[source]

Bases: stem.UnsatisfiableRequest

Timeout requested by the caller was reached.

New in version 1.7.0.

exception stem.InvalidRequest(code=None, message=None)[source]

Bases: stem.OperationFailed

Exception raised when the request was invalid or malformed.

exception stem.InvalidArguments(code=None, message=None, arguments=None)[source]

Bases: stem.InvalidRequest

Exception class for requests which had invalid arguments.

Variables:
  • code (str) -- error code returned by Tor
  • message (str) -- error message returned by Tor or a human readable error message
  • arguments (list) -- a list of arguments which were invalid
exception stem.SocketError[source]

Bases: stem.ControllerError

Error arose while communicating with the control socket.

exception stem.SocketClosed[source]

Bases: stem.SocketError

Control socket was closed before completing the message.

exception stem.DownloadFailed(url, error, stacktrace, message=None)[source]

Bases: exceptions.IOError

Inability to download a resource. Python's urllib module raises a wide variety of undocumented exceptions (urllib2.URLError, socket.timeout, and others).

This wraps lower level failures in a common exception type that retains their exception and stacktrace.

New in version 1.8.0.

Variables:
  • url (str) -- url we failed to download from
  • error (Exception) -- original urllib exception
  • stacktrace (traceback) -- original stacktrace
  • stacktrace_str (str) -- string representation of the stacktrace
exception stem.DownloadTimeout(url, error, stacktrace, timeout)[source]

Bases: stem.DownloadFailed

Timeout reached while downloading this resource.

New in version 1.8.0.