# Stem Docs

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

  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