o „^Iã @szdZddlZddlZddlZddlZddlZddlZddlZddlZzddlm Z Wne y9ddl m Z Ynwzddl Z Wn e yMddl Z YnwddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlZddlmZm Z m!Z!ddlm"Z"dZ#dZ$ej%j& 'dd d ¡Z(ej%j&j)d ŽZ*ej%j& )d d ddddddd¡ Z+e,e-ej%j.j/e-e0j1dƒƒƒZ2dZ3ddddddœZ4dZ5dZ6dZ7dZ8da9Gdd„de :dgd¢¡ƒZ;Gd d!„d!e :d!d"d#g¡ƒZd*d+„Z?Gd,d-„d-e@ƒZAGd.d/„d/eAƒZBd0d1„ZCd2d3„ZDe>ƒefd4d5„ƒZEd6d7„ZFdS)9a“- Module for interacting with the Tor control socket. The :class:`~stem.control.Controller` is a wrapper around a :class:`~stem.socket.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 <../faq.html#how-do-i-connect-to-tor>`_ of getting a :class:`~stem.control.Controller`, but the most flexible are :func:`~stem.control.Controller.from_port` and :func:`~stem.control.Controller.from_socket_file`. These static :class:`~stem.control.Controller` methods give you an **unauthenticated** Controller you can then authenticate yourself using its :func:`~stem.control.Controller.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 .. data:: 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 ========== =========== .. data:: EventType (enum) Known types of events that the :func:`~stem.control.Controller.add_event_listener` method of the :class:`~stem.control.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 :class:`~stem.response.events.Event` subclasses as follows... .. deprecated:: 1.6.0 Tor dropped EventType.AUTHDIR_NEWDESCS as of version 0.3.2.1. (:spec:`6e887ba`) ======================= =========== EventType Event Class ======================= =========== **ADDRMAP** :class:`stem.response.events.AddrMapEvent` **AUTHDIR_NEWDESCS** :class:`stem.response.events.AuthDirNewDescEvent` **BUILDTIMEOUT_SET** :class:`stem.response.events.BuildTimeoutSetEvent` **BW** :class:`stem.response.events.BandwidthEvent` **CELL_STATS** :class:`stem.response.events.CellStatsEvent` **CIRC** :class:`stem.response.events.CircuitEvent` **CIRC_BW** :class:`stem.response.events.CircuitBandwidthEvent` **CIRC_MINOR** :class:`stem.response.events.CircMinorEvent` **CLIENTS_SEEN** :class:`stem.response.events.ClientsSeenEvent` **CONF_CHANGED** :class:`stem.response.events.ConfChangedEvent` **CONN_BW** :class:`stem.response.events.ConnectionBandwidthEvent` **DEBUG** :class:`stem.response.events.LogEvent` **DESCCHANGED** :class:`stem.response.events.DescChangedEvent` **ERR** :class:`stem.response.events.LogEvent` **GUARD** :class:`stem.response.events.GuardEvent` **HS_DESC** :class:`stem.response.events.HSDescEvent` **HS_DESC_CONTENT** :class:`stem.response.events.HSDescContentEvent` **INFO** :class:`stem.response.events.LogEvent` **NETWORK_LIVENESS** :class:`stem.response.events.NetworkLivenessEvent` **NEWCONSENSUS** :class:`stem.response.events.NewConsensusEvent` **NEWDESC** :class:`stem.response.events.NewDescEvent` **NOTICE** :class:`stem.response.events.LogEvent` **NS** :class:`stem.response.events.NetworkStatusEvent` **ORCONN** :class:`stem.response.events.ORConnEvent` **SIGNAL** :class:`stem.response.events.SignalEvent` **STATUS_CLIENT** :class:`stem.response.events.StatusEvent` **STATUS_GENERAL** :class:`stem.response.events.StatusEvent` **STATUS_SERVER** :class:`stem.response.events.StatusEvent` **STREAM** :class:`stem.response.events.StreamEvent` **STREAM_BW** :class:`stem.response.events.StreamBwEvent` **TB_EMPTY** :class:`stem.response.events.TokenBucketEmptyEvent` **TRANSPORT_LAUNCHED** :class:`stem.response.events.TransportLaunchedEvent` **WARN** :class:`stem.response.events.LogEvent` ======================= =========== .. data:: Listener (enum) Purposes for inbound connections that Tor handles. .. versionchanged:: 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**) =============== =========== éN)Ú OrderedDict)Ú UNDEFINEDÚ CircStatusÚSignal)Úloggš™™™™™¹?ÚMALFORMED_EVENTSÚINITÚRESETÚCLOSED)!ZADDRMAPZAUTHDIR_NEWDESCSZBUILDTIMEOUT_SETZBWZ CELL_STATSÚCIRCZCIRC_BWZ CIRC_MINORÚ CONF_CHANGEDZCONN_BWZ CLIENTS_SEENÚDEBUGZ DESCCHANGEDZERRZGUARDÚHS_DESCÚHS_DESC_CONTENTÚINFOZNETWORK_LIVENESSZ NEWCONSENSUSZNEWDESCZNOTICEZNSZORCONNÚSIGNALZ STATUS_CLIENTZSTATUS_GENERALÚ STATUS_SERVERZSTREAMZ STREAM_BWZTB_EMPTYZTRANSPORT_LAUNCHEDÚWARNÚORÚDIRÚSOCKSÚTRANSÚNATDÚDNSÚCONTROLZEXTORZ HTTPTUNNEL)ZAccelDirZ AccelNameÚ DataDirectoryZDisableAllSwapZDisableDebuggerAttachmentZ HardwareAccelÚHiddenServiceNonAnonymousModeÚHiddenServiceSingleHopModeZKeepBindCapabilitiesÚPidFileZ RunAsDaemonZSandboxZSyslogIdentityTagZTokenBucketRefillIntervalZUserTÚHiddenServiceOptions)ÚhiddenservicedirÚhiddenserviceportÚhiddenserviceversionÚhiddenserviceauthorizeclientÚhiddenserviceoptions) ÚaddressÚversionz config-fileúexit-policy/defaultÚ fingerprintz config/nameszconfig/defaultsz info/namesz events/nameszfeatures/nameszprocess/descriptor-limitzstatus/version/current)úaccounting/enabled)r$r r!r"r#z¶Tor is currently not configured to retrieve server descriptors. As of Tor version 0.2.3.25 it downloads microdescriptors instead unless you set 'UseMicrodescriptors 0' in your torrc.c@óeZdZdZdS)ÚAccountingStatsa× Accounting information, determining the limits where our relay suspends itself. :var float retrieved: unix timestamp for when this was fetched :var str status: hibernation status of 'awake', 'soft', or 'hard' :var datetime interval_end: time when our limits reset :var int time_until_reset: seconds until our limits reset :var int read_bytes: number of bytes we've read relaying :var int read_bytes_left: number of bytes we can read until we suspend :var int read_limit: reading threshold where we suspend :var int written_bytes: number of bytes we've written relaying :var int write_bytes_left: number of bytes we can write until we suspend :var int write_limit: writing threshold where we suspend N©Ú__name__Ú __module__Ú __qualname__Ú__doc__©r1r1ú./usr/lib/python3/dist-packages/stem/control.pyr+©ór+© Ú retrievedÚstatusÚ interval_endZtime_until_resetZ read_bytesZread_bytes_leftZ read_limitZ written_bytesZwrite_bytes_leftZ write_limitc@r*)ÚUserTrafficAllowedzê Indicates if we're likely to be servicing direct user traffic or not. :var bool inbound: if **True** we're likely providing guard or bridge connnections :var bool outbound: if **True** we're likely providng exit connections Nr,r1r1r1r2r8»r3r8ZinboundZoutboundc@r*)ÚCreateHiddenServiceOutputaV Attributes of a hidden service we've created. Both the **hostnames** and **hostname_for_client** attributes can only be provided if we're able to read the hidden service directory. If the method was called with **client_names** then we may provide the **hostname_for_client**, and otherwise can provide the **hostnames**. :var str path: hidden service directory :var str hostname: content of the hostname file if available :var dict hostname_for_client: mapping of client names to their onion address if available :var dict config: tor's new hidden service configuration Nr,r1r1r1r2r9Är3r9©ÚpathÚhostnameÚhostname_for_clientÚconfigFcs‡fdd„}|S)zb Provides a decorator to support having a default value. This should be treated as private. csDdd„‰ˆst ˆ¡‡‡fdd„ƒ}|St ˆ¡‡‡fdd„ƒ}|S)NcSsRt |¡jdd…}d|vr| d¡nd}|dur#|t|ƒkr#||S| dt¡S)NéÚdefault)ÚinspectZ getargspecÚargsÚindexÚlenÚgetr)ÚfuncrBÚkwargsZ arg_namesZdefault_positionr1r1r2Ú get_defaultÜs  z4with_default..decorator..get_defaultcs>z ˆ|g|¢Ri|¤ŽWSˆˆ||ƒ}|tkr‚|YS©N©r)ÚselfrBrGr@©rFrHr1r2Úwrappedæs z0with_default..decorator..wrappedc?slzˆ|g|¢Ri|¤ŽD]}|Vq WdSˆˆ||ƒ}|tkr$‚|dur0|D]}|Vq*YdSYdSrIrJ)rKrBrGÚvalr@rLr1r2rMòs€ÿ þ)Ú functoolsÚwraps)rFrM©ÚyieldsrLr2Ú decoratorÛs ñzwith_default..decoratorr1)rRrSr1rQr2Ú with_defaultÕs (rTc sštdurFtjj ¡‰tj tj t ¡d¡}zˆ  |¡t ‡fdd„ˆ  ¡DƒƒaWnt yE}zt d||f¡WYd}~dSd}~wwt | ¡¡S)zá Provides a description for Tor events. :param str event: the event for which a description is needed :returns: **str** The event description or **None** if this is an event name we don't have a description for Nz settings.cfgcs0g|]}| d¡r| ¡dd…ˆ |¡f‘qS)zevent.description.éN)Ú startswithÚlowerZ get_value)Ú.0Úkey©r>r1r2Ú s0z%event_description..zFBUG: stem failed to load its internal manual information from '%s': %s)ÚEVENT_DESCRIPTIONSÚstemÚutilÚconfZConfigÚosr;ÚjoinÚdirnameÚ__file__ÚloadÚdictÚkeysÚ ExceptionrÚwarnrErW)ÚeventZ config_pathÚexcr1rZr2Úevent_descriptions  €þrkc@sÄeZdZdZd1dd„Zdd„Zdd„Zd d „Zd d „Zd d„Z dd„Z dd„Z dd„Z dd„Z d2dd„Zdd„Zdd„Zdd„Zd d!„Zd"d#„Zd$d%„Zd&d'„Zd(d)„Zd*d+„Zd,d-„Zd.d/„Zd0S)3ÚBaseControllera… Controller for the tor process. This is a minimal base class for other controllers, providing basic process communication and event listing. Don't use this directly - subclasses like the :class:`~stem.control.Controller` provide higher level functionality. It's highly suggested that you don't interact directly with the :class:`~stem.socket.ControlSocket` that we're constructed from - use our wrapper methods instead. If the **control_socket** is already authenticated to Tor then the caller should provide the **is_authenticated** flag. Otherwise, we will treat the socket as though it hasn't yet been authenticated. FcCsª||_t ¡|_g|_t ¡|_t ¡|_t ¡|_ d|_ t  ¡|_ d|_ |jj|_|jj|_|j|j_|j|j_d|_d|_g|_|j ¡rK| ¡|rS| ¡dSdS)NçF)Ú_socketÚ threadingÚRLockÚ _msg_lockÚ_status_listenersÚ_status_listeners_lockÚqueueÚQueueÚ _reply_queueÚ _event_queueÚ_reader_threadZEventÚ _event_noticeÚ _event_threadÚ_connectÚ_socket_connectÚ_closeÚ _socket_closeÚ_last_heartbeatÚ_is_authenticatedÚ_state_change_threadsÚis_aliveÚ_launch_threadsÚ_post_authentication)rKÚcontrol_socketÚis_authenticatedr1r1r2Ú__init__0s*           ÿzBaseController.__init__c Cs |jy|j ¡sQz8|j ¡}t|tjƒrn*t|tjƒr$t  d|¡nt|tj ƒr2t  d|¡nt|tj j ƒr@t  d|¡Wn t jyKYnw|j ¡r z|j |¡|j ¡}t|tj ƒre|‚|WWdƒStjy{| ¡‚w1swYdS)aÈ Sends a message to our control socket and provides back its reply. :param str message: message to be formatted and sent to tor :returns: :class:`~stem.response.ControlMessage` with the response :raises: * :class:`stem.ProtocolError` the content from the socket is malformed * :class:`stem.SocketError` if a problem arises in using the socket * :class:`stem.SocketClosed` if the socket is shut down z%Tor provided a malformed message (%s)z!Socket experienced a problem (%s)z Failed to deliver a response: %sN)rqrvÚemptyÚ get_nowaitÚ isinstancer]Z SocketClosedÚ ProtocolErrorrÚinfoÚControllerErrorÚresponseZControlMessagertÚEmptyrnÚsendrEÚclose)rKÚmessagerŽr1r1r2ÚmsgVs:     €ü ô   Ç:ùÆzBaseController.msgcCó |j ¡S)zî Checks if our socket is currently connected. This is a pass-through for our socket's :func:`~stem.socket.BaseSocket.is_alive` method. :returns: **bool** that's **True** if our socket is connected and **False** otherwise )rnr‚©rKr1r1r2r‚©s zBaseController.is_alivecCr”)zÈ Returns if the connection is for the local system or not. .. versionadded:: 1.3.0 :returns: **bool** that's **True** if the connection is for the local host and **False** otherwise )rnÚ is_localhostr•r1r1r2r–³s zBaseController.is_localhostcCr”)ae Provides the unix timestamp for when our socket was either connected or disconnected. That is to say, the time we connected if we're currently connected and the time we disconnected if we're not connected. .. versionadded:: 1.3.0 :returns: **float** for when we last connected or disconnected, zero if we've never connected )rnÚconnection_timer•r1r1r2r—¾s zBaseController.connection_timecCs| ¡r|jSdS)z¯ Checks if our socket is both connected and authenticated. :returns: **bool** that's **True** if our socket is authenticated to tor and **False** otherwise F)r‚r€r•r1r1r2r†ÌszBaseController.is_authenticatedcCs|j ¡dS)zÊ Reconnects our control socket. This is a pass-through for our socket's :func:`~stem.socket.ControlSocket.connect` method. :raises: :class:`stem.SocketError` if unable to make a socket N)rnÚconnectr•r1r1r2r˜ÖszBaseController.connectcCs6|j ¡|jD]}| ¡rt ¡|kr| ¡qdS)z Closes our socket connection. This is a pass-through for our socket's :func:`~stem.socket.BaseSocket.close` method. N)rnr‘rr‚roÚcurrent_threadra©rKÚtr1r1r2r‘às  €þzBaseController.closecCó|jS)zì Provides the socket used to speak with the tor process. Communicating with the socket directly isn't advised since it may confuse this controller. :returns: :class:`~stem.socket.ControlSocket` we're communicating with )rnr•r1r1r2Ú get_socketóózBaseController.get_socketcCrœ)zÅ Provides the unix timestamp for when we last heard from tor. This is zero if we've never received a message. :returns: float for the unix timestamp of when we last heard from tor )rr•r1r1r2Úget_latest_heartbeatýržz#BaseController.get_latest_heartbeatTcCs<|j|j ||f¡WdƒdS1swYdS)a Notifies a given function when the state of our socket changes. Functions are expected to be of the form... :: my_function(controller, state, timestamp) The state is a value from the :data:`stem.control.State` enum. Functions **must** allow for new values. The timestamp is a float for the unix time when the change occurred. This class only provides **State.INIT** and **State.CLOSED** notifications. Subclasses may provide others. If spawn is **True** then the callback is notified via a new daemon thread. If **False** then the notice is under our locks, within the thread where the change occurred. In general this isn't advised, especially if your callback could block for a while. If still outstanding these threads are joined on as part of closing this controller. :param function callback: function to be notified when our state changes :param bool spawn: calls function via a new thread if **True**, otherwise it's part of the connect/close method call N©rsrrÚappend)rKÚcallbackÚspawnr1r1r2Úadd_status_listeners"ÿz"BaseController.add_status_listenercCsj|j(gd}}|jD]\}}||kr| ||f¡q d}q ||_|WdƒS1s.wYdS)a Stops listener from being notified of further events. :param function callback: function to be removed from our listeners :returns: **bool** that's **True** if we removed one or more occurrences of the callback, **False** otherwise FTNr )rKr¢Z new_listenersZ is_changedÚlistenerr£r1r1r2Úremove_status_listener%s $öz%BaseController.remove_status_listenercCs|SrIr1r•r1r1r2Ú __enter__;szBaseController.__enter__cCs | ¡dSrI)r‘)rKZ exit_typeÚvalueÚ tracebackr1r1r2Ú__exit__>s zBaseController.__exit__cCsdS)zù Callback to be overwritten by subclasses for event listening. This is notified whenever we receive an event from the control socket. :param stem.response.ControlMessage event_message: message received from the control socket Nr1)rKÚ event_messager1r1r2Ú _handle_eventAs zBaseController._handle_eventcCs&| ¡| tj¡| ¡d|_dS©NF)rƒÚ_notify_status_listenersÚStaterr|r€r•r1r1r2r{Ls  zBaseController._connectcCsZ|j ¡d|_|j|jfD]}|r | ¡r t ¡|kr | ¡q|  t j ¡|  ¡dSr­) ryÚsetr€rxrzr‚ror™rar®r¯r r~ršr1r1r2r}Rs €  zBaseController._closecCs d|_dS)NT)r€r•r1r1r2r„ds z#BaseController._post_authenticationc Cs<|j ¡|jsd}|tjtjfvrd}n|tjkrd}t ¡}|dur;|| ¡kr; WdƒWdƒdSt t dd„|j ƒƒ|_ |j D]+\}}|rn|||f}t j||d|d}| d¡| ¡|j  |¡qI||||ƒqIWdƒn1swYWdƒdSWdƒdS1s—wYdS)z‰ Informs our status listeners that a state change occurred. :param stem.control.State state: state change that has occurred NTFcSs| ¡SrI)r‚)r›r1r1r2Úˆsz9BaseController._notify_status_listeners..z%s notification)ÚtargetrBÚname)rnÚ_get_send_lockrsr¯rr r Útimer‚ÚlistÚfilterrrrroÚThreadÚ setDaemonÚstartr¡)rKÚstateZ expect_aliveZchange_timestampr¥r£rBZ notice_threadr1r1r2r®is4   îÿ  ÷êÿ"ÿz'BaseController._notify_status_listenerscCs°|j ¡I|jr|j ¡s"tj|jdd|_|j d¡|j ¡|j r*|j  ¡sFtj|j dd|_ |j  d¡|j  ¡WdƒdSWdƒdS1sQwYdS)zq Initializes daemon threads. Threads can't be reused so we need to recreate them if we're restarted. z Tor listener)r²r³TzEvent notifierN) rnr´rxr‚ror¸Ú _reader_loopr¹rºrzÚ _event_loopr•r1r1r2rƒ•s     ÷"úzBaseController._launch_threadsc Csœ| ¡rLz(|j ¡}t ¡|_| ¡dddkr%|j |¡|j  ¡n|j  |¡Wnt j yE}z |j  |¡WYd}~nd}~ww| ¡sdSdS)a Continually pulls from the control socket, directing the messages into queues based on their type. Controller messages come in two varieties... * Responses to messages we've sent (GETINFO, SETCONF, etc). * Asynchronous events, identified by a status code of 650. éÿÿÿÿrZ650N) r‚rnZrecvrµrÚcontentrwÚputryr°rvr]r)rKZcontrol_messagerjr1r1r2r¼©s      €€úôzBaseController._reader_loopcCsd} z'|j ¡}| |¡|j ¡| ¡s)|st ¡}n t ¡|tkr)WdSWntjyF| ¡s9YdS|j   d¡|j   ¡Ynwq)zù Continually pulls messages from the _event_queue and sends them to our handle_event callback. This is done via its own thread so subclasses with a lengthy handle_event implementation don't block further reading from the socket. NTçš™™™™™©?) rwr‰r¬Z task_doner‚rµÚEVENTS_LISTENING_TIMEOUTrtrryÚwaitÚclear)rKZsocket_closed_atr«r1r1r2r½Æs&    € ûózBaseController._event_loopN©F)T)r-r.r/r0r‡r“r‚r–r—r†r˜r‘rrŸr¤r¦r§rªr¬r{r}r„r®rƒr¼r½r1r1r1r2rl s0 &S      , rlcsÊeZdZdZed¢dd„ƒZed£dd„ƒZd¤‡fd d „ Z‡fd d „Zdd„Z dd„Z e ƒe d fdd„ƒZ e ƒe fdd„ƒZe ƒe fdd„ƒZe ƒe fdd„ƒZe ƒe fdd„ƒZe ƒe fdd„ƒZe fdd„Ze ƒe fd d!„ƒZe ƒe fd"d#„ƒZe ƒe fd$d%„ƒZe ƒe fd&d'„ƒZe ƒe fd(d)„ƒZd*d+„Ze ƒd,e fd-d.„ƒZe d/d0e fd1d2„ƒZe ƒd,e fd3d4„ƒZe d/d0e fd5d6„ƒZd7d8„Ze ƒd,e fd9d:„ƒZe d/d0e fd;d<„ƒZ e ƒe d,d/d,fd=d>„ƒZ!e d fd?d@„Z"e d/fdAdB„Z#dCdD„Z$e ƒe fdEdF„ƒZ%dGdH„Z&dIdJ„Z'dKdL„Z(d¤dMdN„Z)e ƒe fdOdP„ƒZ*dQdR„Z+d¥dSdT„Z,d¦dUdV„Z-e ƒe d/d fdWdX„ƒZ.d§d[d\„Z/d]d^„Z0d_d`„Z1dadb„Z2d¦dcdd„Z3d¦dedf„Z4d¦dgdh„Z5didj„Z6dkdl„Z7dmdn„Z8dodp„Z9dqdr„Z:d¤dsdt„Z;dudv„Ze ƒe fd{d|„ƒZ?d¨d~d„Z@d©dd‚„ZAdƒd„„ZBdªd†d‡„ZCe ƒe fdˆd‰„ƒZDd¦dŠd‹„ZEeFjGjHd…fdŒd„ZIdŽd„ZJdd‘„ZKd’d“„ZLe ƒe d fd”d•„ƒZMd–d—„ZNd˜d™„ZOdšd›„ZP‡fdœd„ZQdždŸ„ZRd d¡„ZS‡ZTS)«Ú Controllerz‘ Connection with Tor's control socket. This is built on top of the BaseController and provides a more user friendly API for library users. ú 127.0.0.1r@cCsvddl}|jj |¡std|ƒ‚|dkr"|jj |¡s"td|ƒ‚|dkr0|j |¡}t |ƒS|j ||¡}t |ƒS)aO Constructs a :class:`~stem.socket.ControlPort` based Controller. If the **port** is **'default'** then this checks on both 9051 (default for relays) and 9151 (default for the Tor Browser). This default may change in the future. .. versionchanged:: 1.5.0 Use both port 9051 and 9151 by default. :param str address: ip address of the controller :param int port: port number of the controller :returns: :class:`~stem.control.Controller` attached to the given port :raises: :class:`stem.SocketError` if we're unable to establish a connection rNzInvalid IP address: %sr@zInvalid port: %s) Ústem.connectionr^Ú connectionÚis_valid_ipv4_addressÚ ValueErrorÚ is_valid_portZ_connection_for_default_portÚsocketÚ ControlPortrÆ)r%Úportr]Z control_portr1r1r2Ú from_portës   þzController.from_portú/var/run/tor/controlcCstj |¡}t|ƒS)a4 Constructs a :class:`~stem.socket.ControlSocketFile` based Controller. :param str path: path where the control socket is located :returns: :class:`~stem.control.Controller` attached to the given socket file :raises: :class:`stem.SocketError` if we're unable to establish a connection )r]rÍÚControlSocketFilerÆ)r;r…r1r1r2Úfrom_socket_file s zController.from_socket_fileFcs¨dˆ_iˆ_dˆ_t ¡ˆ_iˆ_t ¡ˆ_gˆ_dˆ_ dˆ_ dˆ_ t t ˆƒ ||¡‡fdd„}ˆ |tj¡‡fdd„}ˆ |tj¡‡fdd„}ˆ |tj¡dS) NTrmcs(|jtjkrˆ ¡ˆ tj¡dSdSrI)ÚsignalrZRELOADÚ clear_cacher®r¯r ©rir•r1r2Ú_sighup_listener/s þz-Controller.__init__.._sighup_listenercsjˆ ¡r3tdd„|j ¡Dƒƒ}tdd„|jDƒƒ}i}| |¡| |¡ˆ |d¡ˆ |¡dSdS)Ncsó |] \}}| ¡|fVqdSrI©rW©rXÚkÚvr1r1r2Ú 8ó€zEController.__init__.._confchanged_listener..css|] }| ¡gfVqdSrIrÙ©rXrÛr1r1r2rÝ9ó€Úgetconf)Úis_caching_enabledreZchangedÚitemsZunsetÚupdateÚ _set_cacheÚ_confchanged_cache_invalidation)riZto_cache_changedZto_cache_unsetÚto_cacher•r1r2Ú_confchanged_listener6s   öz2Controller.__init__.._confchanged_listenercs6|jdvrˆ ddi¡ˆ ddid¡dˆ_dSdS)N)ZEXTERNAL_ADDRESSZ DNS_USELESSÚ exit_policyr%Úgetinfo)ÚactionråÚ_last_address_excrÖr•r1r2Ú_address_changed_listenerEs  ýz6Controller.__init__.._address_changed_listener)Ú_is_caching_enabledÚ_request_cacheÚ _last_newnymrorpÚ _cache_lockÚ_event_listenersÚ_event_listeners_lockÚ_enabled_featuresÚ_is_geoip_unavailablerìÚ_last_fingerprint_excÚsuperrÆr‡Úadd_event_listenerÚ EventTyperr r)rKr…r†r×rèrí©Ú __class__r•r2r‡s"     zController.__init__cs| ¡tt|ƒ ¡dSrI)rÕr÷rÆr‘r•rúr1r2r‘MszController.closecOs&ddl}|jj|g|¢Ri|¤ŽdS)z‡ A convenience method to authenticate the controller. This is just a pass-through to :func:`stem.connection.authenticate`. rN)rÈrÉÚ authenticate)rKrBrGr]r1r1r2rüQszController.authenticatecOsL|j| ¡| ¡|j|i|¤ŽWdƒdS1swYdS)zü Reconnects and authenticates to our control socket. .. versionadded:: 1.5.0 :raises: * :class:`stem.SocketError` if unable to re-establish socket * :class:`stem.connection.AuthenticationFailure` if unable to authenticate N)rqr˜rÕrü)rKrBrGr1r1r2Ú reconnectZs  "ýzController.reconnectc Cst ¡}i}tj |¡rd}t|gƒ}n |siSd}t|ƒ}|D]0}| d¡r4|dkr4| ¡r4t d¡‚|dkr>|jr>|j‚|dkrP|j rP|  dd ¡d urP|j ‚q d d „|Dƒ}|  |d ¡} | D]} t || ƒ} | | || <|  | ¡q`|strƒt d d | ¡¡¡|r‡|St| ¡ƒdSz| dd |¡¡} tj d| ¡|  |¡tj ¡rº|sºtdd„| j ¡Dƒƒ| _| | j¡| ¡rði} | j ¡D]\} }|   ¡} | t!vsÛ| t"vrà|| | <qË|  d¡ré|| | <qË| #| d ¡d|vr÷d |_d|vrþd |_ t $dd |¡t ¡|f¡|r|WSt| ¡ƒdWStj%yG}zd|vr.||_d|vr6||_ t $dd |¡|f¡‚d }~ww)a get_info(params, default = UNDEFINED, get_bytes = False) Queries the control socket for the given GETINFO option. If provided a default then that's returned if the GETINFO option is undefined or the call fails for any reason (error response, control port closed, initiated, etc). .. versionchanged:: 1.1.0 Added the get_bytes argument. .. versionchanged:: 1.7.0 Errors commonly provided a :class:`stem.ProtocolError` when we should raise a :class:`stem.OperationFailed`. :param str,list params: GETINFO option or options to be queried :param object default: response if the query fails :param bool get_bytes: provides **bytes** values rather than a **str** under python 3.x :returns: Response depends upon how we were called as follows... * **str** with the response if our param was a **str** * **dict** with the 'param => response' mapping if our param was a **list** * default if one was provided and our call failed :raises: * :class:`stem.ControllerError` if the call fails and we weren't provided a default response * :class:`stem.InvalidArguments` if the 'params' requested was invalid * :class:`stem.ProtocolError` if the geoip database is unavailable FTzip-to-country/úip-to-country/0.0.0.0z!Tor geoip database is unavailabler%r(ÚORPortNcSóg|]}| ¡‘qSr1rÙ©rXÚparamr1r1r2r[¥óz'Controller.get_info..rêzGETINFO %s (cache fetch)ú rz GETINFO %sZGETINFOcss&|]\}}|tjj |¡fVqdSrI)r]r^Ú str_toolsÚ _to_unicoderÚr1r1r2rÝ¿s€$z&Controller.get_info..zGETINFO %s (runtime: %0.4f)zGETINFO %s (failed: %s))&rµr]r^Ú_is_strr°rVÚis_geoip_unavailabler‹rìröÚget_confÚ_get_cache_mapÚ_case_insensitive_lookupÚremoveÚLOG_CACHE_FETCHESrÚtracerarfr¶Úvaluesr“rŽÚconvertZ_assert_matchesZprereqZ is_python_3reÚentriesrãrärârWÚCACHEABLE_GETINFO_PARAMSÚ&CACHEABLE_GETINFO_PARAMS_UNTIL_SETCONFråÚdebugr)rKÚparamsr@Ú get_bytesÚ start_timeÚreplyZ is_multiplerÚ from_cacheÚcached_resultsrYÚuser_expected_keyrŽrçr¨rjr1r1r2Úget_infojs~$   €        €    €øzController.get_infocCsL| d¡}|s$| d¡}tj | d¡r|dd…n|¡}| d|i¡|S)aó get_version(default = UNDEFINED) A convenience method to get tor version that current controller is connected to. :param object default: response if the query fails :returns: :class:`~stem.version.Version` of the tor instance that we're connected to :raises: * :class:`stem.ControllerError` if unable to query the version * **ValueError** if unable to parse the version An exception is only raised if we weren't provided a default response. r&zTor éN)Ú _get_cacherr]r&ZVersionrVrå)rKr@r&Z version_strr1r1r2Ú get_versionæs  "zController.get_versionc CsÔ| d¡}|shztjj| d¡ ¡Ž}| d|i¡W|Stjygg}| d¡dkr2|  d¡| d¡dkr>|  d¡|jd d d D] }||  d ¡7}qE|| d ¡  d ¡7}tj  || dd¡¡}Y|Sw|S)a¥ get_exit_policy(default = UNDEFINED) Effective ExitPolicy for our relay. .. versionchanged:: 1.7.0 Policies retrieved through 'GETINFO exit-policy/full' rather than parsing the user's torrc entries. This should be more reliable for some edge cases. (:trac:`25739`) :param object default: response if the query fails :returns: :class:`~stem.exit_policy.ExitPolicy` of the tor instance that we're connected to :raises: * :class:`stem.ControllerError` if unable to query the policy * **ValueError** if unable to parse the policy An exception is only raised if we weren't provided a default response. rézexit-policy/fullZ ExitRelayÚ0z reject *:*ZExitPolicyRejectPrivateÚ1zreject private:*Ú ExitPolicyT©Úmultipleú,r'r%N) rr]rér"rÚ splitlinesråÚOperationFailedr r¡ÚsplitZget_config_policy)rKr@ZpolicyZrulesZ policy_liner1r1r2Úget_exit_policys& "ß  ß!zController.get_exit_policycs$‡fdd„‰‡fdd„| ˆ¡DƒS)aº get_ports(listener_type, default = UNDEFINED) Provides the local ports where tor is listening for the given type of connections. This is similar to :func:`~stem.control.Controller.get_listeners`, but doesn't provide addresses nor include non-local endpoints. .. versionadded:: 1.2.0 :param stem.control.Listener listener_type: connection type being handled by the ports we return :param object default: response if the query fails :returns: **list** of **ints** for the local ports where tor handles connections of the given type :raises: :class:`stem.ControllerError` if unable to determine the ports and no default was provided csVtjj |¡r|dkp| d¡Stjj |¡r tjj |¡dvSt dˆ|f¡dS)Nz0.0.0.0z127.)z'0000:0000:0000:0000:0000:0000:0000:0000z'0000:0000:0000:0000:0000:0000:0000:0001zCRequest for %s ports got an address that's neither IPv4 or IPv6: %sF) r]r^rÉrÊrVÚis_valid_ipv6_addressZexpand_ipv6_addressrrŒ)r%)Ú listener_typer1r2r–[s z*Controller.get_ports..is_localhostcsg|] \}}ˆ|ƒr|‘qSr1r1©rXÚaddrrÏ)r–r1r2r[góz(Controller.get_ports..)Ú get_listeners)rKr+r@r1)r–r+r2Ú get_portsDs  zController.get_portsc CsL| |d¡}|dur$g}d| ¡}zV| |¡ ¡D]L}| d¡r'| d¡s0t d||f¡‚d|vr=t d||f¡‚|dd …}| dd¡\}}|d krPq| d ¡r`| d ¡r`|dd …}|  ||f¡qWnztj yãt j d t j dt jdt jdt jdt jdt jdi|} t j dt j dt jdt jdt jdt jdt jdi|} | | ¡ ¡d} |j| ddD]-}d|vrÙ| dd¡\}}| d ¡rÑ| d ¡rÑ|dd …}|  ||f¡q³|  || f¡q³Ynw|D].\}}tjj |¡stjj |¡st d||f¡‚tjj |¡st d||f¡‚qæd d!„|Dƒ}| ||id¡|S)"aü get_listeners(listener_type, default = UNDEFINED) Provides the addresses and ports where tor is listening for connections of the given type. This is similar to :func:`~stem.control.Controller.get_ports` but includes listener addresses and non-local endpoints. .. versionadded:: 1.2.0 .. versionchanged:: 1.5.0 Recognize listeners with IPv6 addresses. :param stem.control.Listener listener_type: connection type being handled by the listeners we return :param object default: response if the query fails :returns: **list** of **(address, port)** tuples for the available listeners :raises: :class:`stem.ControllerError` if unable to determine the listeners and no default was provided Ú listenersNznet/listeners/%sú"z4'GETINFO %s' responses are expected to be quoted: %sú:z/'GETINFO %s' had a listener without a colon: %sr?r¾Zunixú[ú]rÿZDirPortZ SocksPortZ TransPortZNatdPortZDNSPortrÎZORListenAddressZDirListenAddressZSocksListenAddressZTransListenAddressZNatdListenAddressZDNSListenAddressZControlListenAddressrTr#z%Invalid address for a %s listener: %sz"Invalid port for a %s listener: %scSsg|] \}}|t|ƒf‘qSr1©Úintr,r1r1r2r[Îr.z,Controller.get_listeners..)rrWrr(rVÚendswithr]r‹Úrsplitr¡ÚInvalidArgumentsÚListenerrrrrrrrr r^rÉrÊr*rÌrå) rKr+r@r1Z proxy_addrsÚqueryr¥r-rÏZ port_optionZlistener_optionZ port_valuer1r1r2r/ist     ëùø ùø  ÷å ( ÿzController.get_listenersc CsÆ| d¡dkr t d¡‚t ¡}| d¡}| d¡}| d¡}| d¡}tjj |¡}dd „| d d ¡Dƒ\}}d d „| d d ¡Dƒ\} } t|||t d t   |  ¡¡t |ƒƒ|| || || || d S)a® get_accounting_stats(default = UNDEFINED) Provides stats related to our relaying limitations if AccountingMax was set in our torrc. .. versionadded:: 1.3.0 :param object default: response if the query fails :returns: :class:`~stem.control.AccountingStats` with our accounting stats :raises: :class:`stem.ControllerError` if unable to determine the listeners and no default was provided r)r!zAccounting isn't enabledzaccounting/hibernatingzaccounting/interval-endzaccounting/byteszaccounting/bytes-leftcSóg|]}t|ƒ‘qSr1r6©rXrNr1r1r2r[ïrz3Controller.get_accounting_stats..rr?cSr=r1r6r>r1r1r2r[ðrrr4)rr]rrµr^rZ_parse_timestampr(r+ÚmaxÚcalendarZtimegmZ timetupler7) rKr@r5r6r7ÚusedÚleftZ used_readZ used_writtenZ left_readZ left_writtenr1r1r2Úget_accounting_statsÓs,     özController.get_accounting_statscCs| tj|¡S)aÌ Provides the SOCKS **(address, port)** tuples that tor has open. .. deprecated:: 1.2.0 Use :func:`~stem.control.Controller.get_listeners` with **Listener.SOCKS** instead. :param object default: response if the query fails :returns: list of **(address, port)** tuples for the available SOCKS listeners :raises: :class:`stem.ControllerError` if unable to determine the listeners and no default was provided )r/r;r©rKr@r1r1r2Úget_socks_listenersÿszController.get_socks_listenerscCsddl}|j |¡S)a get_protocolinfo(default = UNDEFINED) A convenience method to get the protocol info of the controller. :param object default: response if the query fails :returns: :class:`~stem.response.protocolinfo.ProtocolInfoResponse` provided by tor :raises: * :class:`stem.ProtocolError` if the PROTOCOLINFO response is malformed * :class:`stem.SocketError` if problems arise in establishing or using the socket An exception is only raised if we weren't provided a default response. rN)rÈrÉÚget_protocolinfo)rKr@r]r1r1r2rFs zController.get_protocolinfocCsr| d¡}|r |S| dd¡}|s#| ¡r#| d¡}|r#tjj |¡}|r.| d|i¡|St | ¡r6dƒ‚dƒ‚)al get_user(default = UNDEFINED) Provides the user tor is running as. This often only works if tor is running locally. Also, most of its checks are platform dependent, and hence are not entirely reliable. .. versionadded:: 1.1.0 :param object default: response if the query fails :returns: str with the username tor is running as Úuserz process/userNzUnable to resolve tor's userúTor isn't running locally) rrr–Úget_pidr]r^ÚsystemrGrårË)rKr@rGÚpidr1r1r2Úget_user)s    zController.get_usercCs| d¡}|r |S| dd¡}|r| ¡rt|ƒ}|sy| ¡ry| dd¡}|durKt|ƒ}| ¡ ¡}| ¡rUnable to determine the uptime when tor is not running locallyz.Unable to determine the pid of the tor processz Unable to resolve when tor beganrH)rrr]r&Ú RequirementZGETINFO_UPTIMErrMrËrµÚfloatr–rIr^rJrrå)rKr@rrQrKr1r1r2Úget_start_time„s(     zController.get_start_timecCst ¡| ¡S)ah get_uptime(default = UNDEFINED) Provides the duration in seconds that tor has been running. .. versionadded:: 1.8.0 :param object default: response if the query fails :returns: **float** for the number of seconds tor has been running :raises: **ValueError** if unable to determine the uptime and no default was provided )rµrTrDr1r1r2Ú get_uptime·szController.get_uptimecCsfd\}}| dd¡dkrd}| dd¡r.|s#|jdd}|o"d|jv}| d¡}|o-| ¡}t||ƒS) ag Checks if we're likely to service direct user traffic. This essentially boils down to... * If we're a bridge or guard relay, inbound connections are possibly from users. * If our exit policy allows traffic then output connections are possibly from users. Note the word 'likely'. These is a decent guess in practice, but not always correct. For instance, information about which flags we have are only fetched periodically. This method is intended to help you avoid eavesdropping on user traffic. Monitoring user connections is not only unethical, but likely a violation of wiretapping laws. .. versionadded:: 1.5.0 :returns: :class:`~stem.cotroller.UserTrafficAllowed` with **inbound** and **outbound** boolean attributes to indicate if we're likely servicing direct user traffic )FFZ BridgeRelayNr!Trÿ©r@ZGuard)r Úget_network_statusÚflagsr)Zis_exiting_allowedr8)rKZinbound_allowedZoutbound_allowedZconsensus_entryrér1r1r2Úis_user_traffic_allowedÊs     z"Controller.is_user_traffic_allowedNc Cóä|dur z| d¡}Wntjy}zt d|¡‚d}~wwtjj |¡r,d|}ntjj |¡r8d|}ntd|ƒ‚z |j|dd}Wntjyc}zt |ƒ  d ¡r^t  d |¡‚‚d}~ww|skt  d ¡‚tj j  |¡S) aß get_microdescriptor(relay = None, default = UNDEFINED) Provides the microdescriptor for the relay with the given fingerprint or nickname. If the relay identifier could be either a fingerprint *or* nickname then it's queried as a fingerprint. If no **relay** is provided then this defaults to ourselves. Remember that this requires that we've retrieved our own descriptor from remote authorities so this both won't be available for newly started relays and may be up to around an hour out of date. .. versionchanged:: 1.3.0 Changed so we'd fetch our own descriptor if no 'relay' is provided. :param str relay: fingerprint or nickname of the relay to be queried :param object default: response if the query fails :returns: :class:`~stem.descriptor.microdescriptor.Microdescriptor` for the given relay :raises: * :class:`stem.DescriptorUnavailable` if unable to provide a descriptor for the given relay * :class:`stem.ControllerError` if unable to query the descriptor * **ValueError** if **relay** doesn't conform with the pattern for being a fingerprint or nickname An exception is only raised if we weren't provided a default response. Nr(ú+Unable to determine our own fingerprint: %szmd/id/%sz md/name/%sú*'%s' isn't a valid fingerprint or nicknameT©rú0GETINFO request contained unrecognized keywords:ú1Tor was unable to provide the descriptor for '%s'úHDescriptor information is unavailable, tor might still be downloading it)rr]rr^Ú tor_toolsÚis_valid_fingerprintÚis_valid_nicknamerËr:ÚstrrVÚDescriptorUnavailableÚ descriptorÚmicrodescriptorÚMicrodescriptor©rKZrelayr@rjr<Ú desc_contentr1r1r2Úget_microdescriptorós. €ÿ   €ü zController.get_microdescriptorTrQccs| ¡tjjjkr*|jddd}|st d¡‚tjj  t   |¡¡D]}|Vq"dS|  dd¡}|dur:tj dd‚tj |¡sHtj d |d‚d}d D]}tj ||¡}tj |¡r_|}nqL|durltj d |d‚tj |¡D]}t|tjjjƒs†tj d t|ƒd‚|VqrdS) a¹ get_microdescriptors(default = UNDEFINED) Provides an iterator for all of the microdescriptors that tor currently knows about. Prior to Tor 0.3.5.1 this information was not available via the control protocol. When connected to prior versions we read the microdescriptors directly from disk instead, which will not work remotely or if our process lacks read permissions. :param list default: items to provide if the query fails :returns: iterates over :class:`~stem.descriptor.microdescriptor.Microdescriptor` for relays in the tor network :raises: :class:`stem.ControllerError` if unable to query tor and no default was provided zmd/allTr]r`rNz(Unable to determine tor's data directory©r’z1Data directory reported by tor doesn't exist (%s))zcached-microdescszcached-microdescs.newz;Data directory doesn't contain cached microdescriptors (%s)z@BUG: Descriptor reader provided non-microdescriptor content (%s))rr]r&rRZGETINFO_MICRODESCRIPTORSrrerfrgÚ _parse_fileÚioÚBytesIOr r'r`r;ÚexistsraZ parse_filerŠrhÚtype)rKr@rjÚdescZdata_directoryZmicrodescriptor_fileÚfilenameZcached_descriptorsr1r1r2Úget_microdescriptors-s6€ ÿ    þùzController.get_microdescriptorsc Cszs|dur!z| d¡}Wntjy }zt d|¡‚d}~wwtjj |¡r-d|}ntjj |¡r9d|}ntd|ƒ‚z |j|dd}Wntjyd}zt |ƒ  d ¡r_t  d |¡‚‚d}~ww|slt  d ¡‚tj j  |¡WS| ¡sttƒ‚‚) aá get_server_descriptor(relay = None, default = UNDEFINED) Provides the server descriptor for the relay with the given fingerprint or nickname. If the relay identifier could be either a fingerprint *or* nickname then it's queried as a fingerprint. If no **relay** is provided then this defaults to ourselves. Remember that this requires that we've retrieved our own descriptor from remote authorities so this both won't be available for newly started relays and may be up to around an hour out of date. **As of Tor version 0.2.3.25 relays no longer get server descriptors by default.** It's advised that you use microdescriptors instead, but if you really need server descriptors then you can get them by setting 'UseMicrodescriptors 0'. .. versionchanged:: 1.3.0 Changed so we'd fetch our own descriptor if no 'relay' is provided. :param str relay: fingerprint or nickname of the relay to be queried :param object default: response if the query fails :returns: :class:`~stem.descriptor.server_descriptor.RelayDescriptor` for the given relay :raises: * :class:`stem.DescriptorUnavailable` if unable to provide a descriptor for the given relay * :class:`stem.ControllerError` if unable to query the descriptor * **ValueError** if **relay** doesn't conform with the pattern for being a fingerprint or nickname An exception is only raised if we weren't provided a default response. Nr(r[z desc/id/%sz desc/name/%sr\Tr]r^r_r`)rr]rr^rarbrcrËr:rdrVrerfÚserver_descriptorZRelayDescriptorÚ _is_server_descriptors_availableÚSERVER_DESCRIPTORS_UNSUPPORTEDrir1r1r2Úget_server_descriptorls8%€ÿ   €ü z Controller.get_server_descriptorccsT|jddd}|s| ¡st t¡‚t d¡‚tjj t   |¡¡D]}|Vq"dS)a· get_server_descriptors(default = UNDEFINED) Provides an iterator for all of the server descriptors that tor currently knows about. **As of Tor version 0.2.3.25 relays no longer get server descriptors by default.** It's advised that you use microdescriptors instead, but if you really need server descriptors then you can get them by setting 'UseMicrodescriptors 0'. :param list default: items to provide if the query fails :returns: iterates over :class:`~stem.descriptor.server_descriptor.RelayDescriptor` for relays in the tor network :raises: :class:`stem.ControllerError` if unable to query tor and no default was provided zdesc/all-recentTr]r`N) rrvr]rrwrerfrurmrnro)rKr@rjrrr1r1r2Úget_server_descriptors±s€  ÿz!Controller.get_server_descriptorscCs"| ¡tjjjkp| dd¡dkS)zM Checks to see if tor server descriptors should be available or not. ZUseMicrodescriptorsNr )rr]r&rRZMICRODESCRIPTOR_IS_DEFAULTr r•r1r1r2rvØs ÿz+Controller._is_server_descriptors_availablec CrZ) að get_network_status(relay = None, default = UNDEFINED) Provides the router status entry for the relay with the given fingerprint or nickname. If the relay identifier could be either a fingerprint *or* nickname then it's queried as a fingerprint. If no **relay** is provided then this defaults to ourselves. Remember that this requires that we've retrieved our own descriptor from remote authorities so this both won't be available for newly started relays and may be up to around an hour out of date. .. versionchanged:: 1.3.0 Changed so we'd fetch our own descriptor if no 'relay' is provided. :param str relay: fingerprint or nickname of the relay to be queried :param object default: response if the query fails :returns: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for the given relay :raises: * :class:`stem.DescriptorUnavailable` if unable to provide a descriptor for the given relay * :class:`stem.ControllerError` if unable to query the descriptor * **ValueError** if **relay** doesn't conform with the pattern for being a fingerprint or nickname An exception is only raised if we weren't provided a default response. Nr(r[zns/id/%sz ns/name/%sr\Tr]r^r_r`)rr]rr^rarbrcrËr:rdrVrerfÚrouter_status_entryÚRouterStatusEntryV3rir1r1r2rWås.!€ÿ   €ü zController.get_network_statusccsR|jddd}|st d¡‚tjjjt |¡dtjjjd}|D]}|Vq!dS)a get_network_statuses(default = UNDEFINED) Provides an iterator for all of the router status entries that tor currently knows about. :param list default: items to provide if the query fails :returns: iterates over :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for relays in the tor network :raises: :class:`stem.ControllerError` if unable to query tor and no default was provided zns/allTr]r`F)Z entry_classN) rr]rerfrzrmrnror{)rKr@rjZ desc_iteratorrrr1r1r2Úget_network_statuses s€ ýÿzController.get_network_statusesc sú| d¡r |dd…}tjj |¡std|ƒ‚| ¡tjjj kr,tj dtjjj d‚t   ¡d‰}t   ¡d‰}t   ¡}|rZ‡fdd„}‡fd d „}| |tj¡| |tj¡z’d |} |ro| d d  d d„|Dƒ¡7} | | ¡} tj d| ¡|  ¡s‡t d| j¡‚|sœW|r‘| |¡|rš| |¡dSdS tˆ||ƒ} | j|krì| jr¾| jW|rµ| |¡|r½| |¡SS tˆ||ƒ} | j|krë| jtjjkrë| j tj!j"krßt #d|¡‚t #d|| j$| j f¡‚q¿q|rô| |¡|rü| |¡ww)a get_hidden_service_descriptor(address, default = UNDEFINED, servers = None, await_result = True) Provides the descriptor for a hidden service. The **address** is the '.onion' address of the hidden service (for instance 3g2upl4pq6kufc4m.onion for DuckDuckGo). If **await_result** is **True** then this blocks until we either receive the descriptor or the request fails. If **False** this returns right away. **This method only supports v2 hidden services, not v3.** (:trac:`25417`) .. versionadded:: 1.4.0 .. versionchanged:: 1.7.0 Added the timeout argument. :param str address: address of the hidden service descriptor, the '.onion' suffix is optional :param object default: response if the query fails :param list servers: requrest the descriptor from these specific servers :param float timeout: seconds to wait when **await_result** is **True** :returns: :class:`~stem.descriptor.hidden_service.HiddenServiceDescriptorV2` for the given service if **await_result** is **True**, or **None** otherwise :raises: * :class:`stem.DescriptorUnavailable` if **await_result** is **True** and unable to provide a descriptor for the given service * :class:`stem.Timeout` if **timeout** was reached * :class:`stem.ControllerError` if unable to query the descriptor * **ValueError** if **address** doesn't conform with the pattern of a hidden service address An exception is only raised if we weren't provided a default response. ú.onionNiúÿÿÿz/'%s.onion' isn't a valid hidden service addressz#HSFETCH was added in tor version %srlcóˆ |¡dSrI©rÀrÖ©Ú hs_desc_queuer1r2Úhs_desc_listeneryózBController.get_hidden_service_descriptor..hs_desc_listenercr~rIrrÖ)Úhs_desc_content_queuer1r2Úhs_desc_content_listener|rƒzJController.get_hidden_service_descriptor..hs_desc_content_listenerz HSFETCH %srcSsg|]}d|‘qS)z SERVER=%sr1)rXÚsr1r1r2r[†rz.Ú SINGLELINEz-HSFETCH returned unexpected response code: %sTz%No running hidden service at %s.onionzFUnable to retrieve the descriptor for %s.onion (retrieved from %s): %s)%r8r]r^raZis_valid_hidden_service_addressrËrr&rRZHSFETCHÚUnsatisfiableRequestrtrurµrørùrrrar“rŽrÚis_okr‹ÚcodeÚremove_event_listenerÚ_get_with_timeoutr%rfrëÚ HSDescActionÚFAILEDÚreasonZ HSDescReasonZ NOT_FOUNDreÚdirectory_fingerprint) rKr%r@ZserversZ await_resultÚtimeoutr‚r…rÚrequestrŽrir1)r„rr2Úget_hidden_service_descriptorEsh &      ÿë    ÿô ù÷  ÿz(Controller.get_hidden_service_descriptorcCs:| ¡ ¡}|s|tkr|SdS| |||¡}t|||ƒS)a7 get_conf(param, default = UNDEFINED, multiple = False) Queries the current value for a configuration option. Some configuration options (like the ExitPolicy) can have multiple values. This provides a **list** with all of the values if **multiple** is **True**. Otherwise this will be a **str** with the first value. If provided with a **default** then that is provided if the configuration option was unset or the query fails (invalid configuration option, error response, control port closed, initiated, etc). If the configuration value is unset and no **default** was given then this provides **None** if **multiple** was **False** and an empty list if it was **True**. :param str param: configuration option to be queried :param object default: response if the option is unset or the query fails :param bool multiple: if **True** then provides a list with all of the present values (this is an empty list if the config option is unset) :returns: Response depends upon how we were called as follows... * **str** with the configuration value if **multiple** was **False**, **None** if it was unset * **list** with the response strings if multiple was **True** * default if one was provided and the configuration option was either unset or our call failed :raises: * :class:`stem.ControllerError` if the call fails and we weren't provided a default response * :class:`stem.InvalidArguments` if the configuration option requested was invalid N)rWrPrÚ get_conf_mapr )rKrr@r$rr1r1r2r ©s ) zController.get_confc sêt ¡}i}tj |¡r|g}dd„|Dƒ}|gkriStdd„|Dƒƒ}dd„|Dƒ}| |d¡}|D]} t|| ƒ} || || <| | ¡q4|s^trWt   dd  |  ¡¡¡|  |ˆ|¡Szg| dd  |¡¡} tj d | ¡| | j¡| ¡rŒtd d „| j ¡Dƒƒ} | | d¡t|ƒD]} |  ¡t ¡vr­t|| | ƒ} | | kr­|| || <|| =qt  d d  |¡t ¡|f¡|  |ˆ|¡WStjyô} z"t  d d  |¡| f¡ˆtkrït‡fdd „|DƒƒWYd} ~ S‚d} ~ ww)aÐ get_conf_map(params, default = UNDEFINED, multiple = True) Similar to :func:`~stem.control.Controller.get_conf` but queries multiple configuration options, providing back a mapping of those options to their values. There are three use cases for GETCONF: 1. a single value is provided (e.g. **ControlPort**) 2. multiple values are provided for the option (e.g. **ExitPolicy**) 3. a set of options that weren't necessarily requested are returned (for instance querying **HiddenServiceOptions** gives **HiddenServiceDir**, **HiddenServicePort**, etc) The vast majority of the options fall into the first two categories, in which case calling :func:`~stem.control.Controller.get_conf` is sufficient. However, for batch queries or the special options that give a set of values this provides back the full response. As of tor version 0.2.1.25 **HiddenServiceOptions** was the only option that falls into the third category. **Note:** HiddenServiceOptions are best retrieved via the :func:`~stem.control.Controller.get_hidden_service_conf` method instead. :param str,list params: configuration option(s) to be queried :param object default: value for the mappings if the configuration option is either undefined or the query fails :param bool multiple: if **True** then the values provided are lists with all of the present values :returns: **dict** of the 'config key => value' mappings. The value is a... * **str** if **multiple** is **False**, **None** if the configuration option is unset * **list** if **multiple** is **True** * the **default** if it was set and the value was either undefined or our lookup failed :raises: * :class:`stem.ControllerError` if the call fails and we weren't provided a default response * :class:`stem.InvalidArguments` if the configuration option requested was invalid cSsg|]}| ¡r|‘qSr1©rP©rXÚentryr1r1r2r[ óz+Controller.get_conf_map..cSsg|]}t ||¡‘qSr1)ÚMAPPED_CONFIG_KEYSrEr–r1r1r2r[ r˜cSrr1rÙrr1r1r2r[ rrázGETCONF %s (cache fetch)rz GETCONF %sÚGETCONFcsrØrIrÙrÚr1r1r2rÝ0 rÞz*Controller.get_conf_map..zGETCONF %s (runtime: %0.4f)zGETCONF %s (failed: %s)c3s|]}|ˆfVqdSrIr1rrVr1r2rÝL s€N)rµr]r^rr°r r r r rrrarfÚ_get_conf_dict_to_responser“rŽrrärrârerãrår¶rWr™rrrr)rKrr@r$rrZ lookup_paramsrrrYrrŽrçrjr1rVr2r”ÚsR0          € "€úzController.get_conf_mapcCs^i}t| ¡ƒD]$\}}|gkr"|tkr|||<q|rgnd||<q|r&|n|d||<q|S)zÇ Translates a dictionary of 'config key => [value1, value2...]' into the return value of :func:`~stem.control.Controller.get_conf_map`, taking into account what the caller requested. Nr)r¶rãr)rKZ config_dictr@r$Z return_dictrYrr1r1r2r›P s z%Controller._get_conf_dict_to_responsecCs || ¡vS)aÄ is_set(param, default = UNDEFINED) Checks if a configuration option differs from its default or not. .. versionadded:: 1.5.0 :param str param: configuration option to check :param object default: response if the query fails :returns: **True** if option differs from its default and **False** otherwise :raises: :class:`stem.ControllerError` if the call fails and we weren't provided a default response )Ú_get_custom_options)rKrr@r1r1r2Úis_sete s zController.is_setcCsr| d¡}|s7| d¡ ¡}ddd| d¡df}|D] }||vr&| |¡qtdd „|Dƒƒ}| d|i¡|S) NÚget_custom_optionsz config-textzLog notice stdoutz Log notice file /var/log/tor/logzDataDirectory /home/%s/.torZ undefinedzHiddenServiceStatistics 0cSsg|]}| dd¡‘qS)rr?)r()rXÚliner1r1r2r[ r˜z2Controller._get_custom_options..)rrr&rLr rerå)rKÚresultZ config_linesZ default_linesrŸr1r1r2rœz s  ü €zController._get_custom_optionscCs| ||id¡dS)a® Changes the value of a tor configuration option. Our value can be any of the following... * a string to set a single value * a list of strings to set a series of values (for instance the ExitPolicy) * None to either set the value to 0/NULL :param str param: configuration option to be set :param str,list value: value to set the parameter to :raises: * :class:`stem.ControllerError` if the call fails * :class:`stem.InvalidArguments` if configuration options requested was invalid * :class:`stem.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values FN)Ú set_options)rKrr¨r1r1r2Úset_conf• szController.set_confcGs| tdd„|Dƒƒd¡dS)a§ Reverts one or more parameters to their default values. :param str params: configuration option to be reset :raises: * :class:`stem.ControllerError` if the call fails * :class:`stem.InvalidArguments` if configuration options requested was invalid * :class:`stem.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values cSsg|]}|df‘qSrIr1r–r1r1r2r[¸ rz)Controller.reset_conf..TN)r¡re©rKrr1r1r2Ú reset_conf« s zController.reset_confc sêt ¡}|rdndg}t|tƒrt| ¡ƒ}|D];\‰}t|tƒr-| dˆ| ¡f¡qt|tj ƒr@|  ‡fdd„|Dƒ¡q|sH| ˆ¡qt dˆ|t |ƒj fƒ‚d |¡}| |¡}tj d|¡| ¡r”t d |t ¡|f¡| ¡r’td d „|Dƒƒ}| |d ¡| t|ƒ¡dSdSt d ||j|jf¡dd„|Dƒ} | r·tjdd t| ƒ¡| d‚|jdkrà|j d¡rØ|jd|j dd¡…} t |j|j| g¡‚t |j|j¡‚|jdvrít |j|j¡‚t  d|j¡‚)a/ Changes multiple tor configuration options via either a SETCONF or RESETCONF query. Both behave identically unless our value is None, in which case SETCONF sets the value to 0 or NULL, and RESETCONF returns it to its default value. This accepts str, list, or None values in a similar fashion to :func:`~stem.control.Controller.set_conf`. For example... :: my_controller.set_options({ 'Nickname': 'caerSidi', 'ExitPolicy': ['accept *:80', 'accept *:443', 'reject *:*'], 'ContactInfo': 'caerSidi-exit@someplace.com', 'Log': None, }) The params can optionally be a list of key/value tuples, though the only reason this type of argument would be useful is for hidden service configuration (those options are order dependent). :param dict,list params: mapping of configuration options to the values we're setting it to :param bool reset: issues a RESETCONF, returning **None** values to their defaults if **True** :raises: * :class:`stem.ControllerError` if the call fails * :class:`stem.InvalidArguments` if configuration options requested was invalid * :class:`stem.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values Z RESETCONFZSETCONFú%s="%s"csg|] }dˆ| ¡f‘qS)r¥r•r>©rr1r2r[è r.z*Controller.set_options..zGCannot set %s to %s since the value was a %s but we only accept stringsrr‡z%s (runtime: %0.4f)css |] \}}| ¡dfVqdSrIrÙrÚr1r1r2rÝ÷ rÞz)Controller.set_options..ráz"%s (failed, code: %s, message: %s)cSs*g|]\}}tjj |¡ ¡tvr|‘qSr1)r]r^rrrWÚIMMUTABLE_CONFIG_OPTIONSrÚr1r1r2r[ü s*z(%s cannot be changed while tor's runningú, )r’Z argumentsÚ552z%Unrecognized option: Unknown option 'é%ú')Z513Ú553z#Returned unexpected status code: %sN)!rµrŠrer¶rãrdr¡rPÚ collectionsÚIterableÚextendrËrqr-rar“r]rŽrr‰rrrârårærŠr’r:ÚsortedrVÚfindÚInvalidRequestr‹) rKrÚresetrZ query_compr¨r<rŽrçZimmutable_paramsrYr1r¦r2r¡º sD"         ü   zController.set_optionsc CsÌ| d¡}|durtrt d¡|St ¡}z| d¡}tj d|¡t  dt ¡|¡Wntj yD}zt  d|¡‚d}~wwt ƒ}d}|  ¡D]Ž\}}} | dkrXqNd | vr]qN|   d d ¡\} } | d krr| }d gi||<qN| d krÖ| } } d }|  ¡s•|   ¡\} }| ¡r|} n| dd ¡\}} tjj | ¡s¥t d| | f¡‚tjj |¡sµt d|| f¡‚tjj | ¡sÅt d| | f¡‚||d  t| ƒ|t| ƒf¡qN| ||| <qN| d|i¡|S)aà get_hidden_service_conf(default = UNDEFINED) This provides a mapping of hidden service directories to their attribute's key/value pairs. All hidden services are assured to have a 'HiddenServicePort', but other entries may or may not exist. :: { "/var/lib/tor/hidden_service_empty/": { "HiddenServicePort": [ ] }, "/var/lib/tor/hidden_service_with_two_ports/": { "HiddenServiceAuthorizeClient": "stealth a, b", "HiddenServicePort": [ (8020, "127.0.0.1", 8020), # the ports order is kept (8021, "127.0.0.1", 8021) ], "HiddenServiceVersion": "2" }, } .. versionadded:: 1.3.0 :param object default: response if the query fails :returns: **dict** with the hidden service configuration :raises: :class:`stem.ControllerError` if the call fails and we weren't provided a default response Úhidden_service_confNz*GETCONF HiddenServiceOptions (cache fetch)zGETCONF HiddenServiceOptionsršz-GETCONF HiddenServiceOptions (runtime: %0.4f)z)GETCONF HiddenServiceOptions (failed: %s)rú=r?ÚHiddenServiceDirÚHiddenServicePortrÇr3z;GETCONF provided an invalid HiddenServicePort port (%s): %szEGETCONF provided an invalid HiddenServicePort target address (%s): %szBGETCONF provided an invalid HiddenServicePort target port (%s): %s)rr rrrµr“r]rŽrrrrr¿r(rMr9r^rÉrÌr‹rÊr¡r7rå)rKr@Zservice_dir_maprrŽrjÚ directoryZ status_codeZdividerr¿rÛrÜrÏÚ target_portÚtarget_addressr²r1r1r2Úget_hidden_service_conf s\ $    ÿ€þ "z"Controller.get_hidden_service_confc CsÐ|s | d¡dSg}|D]S}| d|f¡t|| ¡ƒD]A\}}|dkrV|D],}t|tƒr6d||f}nt|tƒr