Protocol and Helper Classes¶
(experimental; details may change) This connects to the given endpoint, presuming it is a Tor control connection and gives back a TorControlProtocol instance. This does not reconnect if the connection is dropped. This is the preferred entry point to control a running Tor; if you need to start a Tor see Launching Tor.
- endpoint – A Twisted IEndpoint, in practice either a TCP4ClientEndpoint or a UnixClientEndpoint. By default, Tor uses “tcp:localhost:9051” or “unix:/var/run/tor/control”.
- password_function – This is only consulted if the Tor to which we connect does not have cookie authentication enabled. In that case, this function is called to request a password. It may return a Deferred.
A Deferred that fires with a ready-to-use TorControlProtocol instance is returned, or Failure if a connection can’t be established.
This is the main class that talks to a Tor and implements the “raw” procotol.
This instance does not track state; see
txtorcon.TorStatefor the current state of all Circuits, Streams and Routers.
txtorcon.TorState.build_circuit()allows you to build custom circuits.
txtorcon.TorControlProtocol.add_event_listener()can be used to listen for specific events.
To see how circuit and stream listeners are used, see
txtorcon.TorState, which is also the place to go if you wish to add your own stream or circuit listeners.
Parameters: password_function – A zero-argument callable which returns a password (or Deferred). It is only called if the Tor doesn’t have COOKIE authentication turned on. Tor’s default is COOKIE.
If set, a callable to query for a password to use for authentication to Tor (default is to use COOKIE, however). May return Deferred.
Version of Tor we’ve connected to.
If not None, this is the PID of the Tor process we own (TAKEOWNERSHIP, etc).
events we’ve subscribed to (keyed by name like “GUARD”, “STREAM”)
all valid events (name -> Event instance)
A list of all valid signals we accept from Tor
This Deferred is triggered when the connection is closed. If there was an error, the errback is called instead.
This Deferred is triggered when we’re done setting up (authentication, getting information from Tor). You will want to use this to do things with the
TorControlProtocolclass when it’s set up, like:
def setup_complete(proto): print "Setup complete, attached to Tor version",proto.version def setup(proto): proto.post_bootstrap.addCallback(setup_complete) ep = TCP4ClientEndpoint(reactor, "localhost", 9051) ep.connect(TorProtocolFactory()) d.addCallback(setup)
See the helper method
Mostly for internal use; gives you the raw string back from the GETINFO command. See
Mostly for internal use; calls GETINFO for a single key and calls line_cb with each line received, as it is received.
Uses GETINFO to obtain informatoin from Tor.
Parameters: args –
should be a list or tuple of strings which are valid information keys. For valid keys, see control-spec.txt from torspec.
make some way to automagically obtain valid keys, either from running Tor or parsing control-spec
Deferredwhich will callback with a dict containing the keys you asked for. If you want to avoid the parsing into a dict, you can use get_info_raw instead.
Uses GETCONF to obtain configuration values from Tor.
Parameters: args – any number of strings which are keys to get. To get all valid configuraiton names, you can call:
Returns: a Deferred which callbacks with one or many configuration values (depends on what you asked for). See control-spec for valid keys (you can also use TorConfig which will come set up with all the keys that are valid). The value will be a dict.
Note that Tor differentiates between an empty value and a default value; in the raw protocol one looks like ‘250 MyFamily’ versus ‘250 MyFamily=’ where the latter is set to the empty string and the former is a default value. We differentiate these by setting the value in the dict to DEFAULT_VALUE for the default value case, or an empty string otherwise.
Same as get_conf, except that the results are not parsed into a dict
set configuration values. see control-spec for valid keys. args is treated as a list containing name then value pairs. For example,
set_conf('foo', 'bar')will (attempt to) set the key ‘foo’ to value ‘bar’.
Deferredthat will callback with the response (‘OK’) or errback with the error code and message (e.g.
"552 Unrecognized option: Unknown option 'foo'. Failing.")
Issues a signal to Tor. See control-spec or
txtorcon.TorControlProtocol.valid_signalsfor which ones are available and their return values.
Deferredwhich callbacks with Tor’s response (
OKor something like
552 Unrecognized signal code "foo").
Parameters: evt – event name, see also
Add a listener to an Event object. This may be called multiple times for the same event. If it’s the first listener, a new SETEVENTS call will be initiated to Tor.
Currently the callback is any callable that takes a single argument, that is the text collected for the event from the tor control protocol.
For more information on the events supported, see control-spec section 4.1
this is a low-level interface; if you want to follow circuit or stream creation etc. see TorState and methods like add_circuit_listener
need an interface for the callback show how to tie in Stem parsing if you want
Returns: a Deferred which will give you PROTOCOLINFO; see control-spec
Call the AUTHENTICATE command.
Sends the QUIT command, which asks Tor to hang up on this controller connection.
If you’ve taken ownership of the Tor to which you’re connected, this should also cause it to exit. Otherwise, it won’t.
returns a Deferred which will fire with the response data when we get it
Note that basically every request is ultimately funelled through this command.
Builds TorControlProtocol objects. Implements IProtocolFactory for Twisted interaction.
If your running Tor doesn’t support COOKIE authentication, then you should supply a password callback.
Builds protocols to talk to a Tor client on the specified address. For example:
ep = TCP4ClientEndpoint(reactor, "localhost", 9051) ep.connect(TorProtocolFactory()) reactor.run()
By default, COOKIE authentication is used if available.
Parameters: password_function – If supplied, this is a zero-argument method that returns a password (or a Deferred). By default, it returns None. This is only queried if the Tor we connect to doesn’t support (or hasn’t enabled) COOKIE authentication.
TorProcessProtocol(connection_creator, progress_updates=None, config=None, ireactortime=None, timeout=None, kill_on_stderr=True, stdout=None, stderr=None)¶
This will read the output from a Tor process and attempt a connection to its control port when it sees any ‘Bootstrapped’ message on stdout. You probably don’t need to use this directly except as the return value from the
txtorcon.launch_tor()method. tor_protocol contains a valid
txtorcon.TorControlProtocolinstance by that point.
connection_creator is a callable that should return a Deferred that callbacks with a
txtorcon.launch_tor()for the default one which is a functools.partial that will call
connect(TorProtocolFactory())on an appropriate twisted.internet.endpoints.TCP4ClientEndpoint
- connection_creator – A no-parameter callable which returns a Deferred which promises a IStreamClientEndpoint. If this is None, we do NOT attempt to connect to the underlying Tor process.
- progress_updates – A callback which received progress updates with three args: percent, tag, summary
- config – a TorConfig object to connect to the TorControlProtocl from the launched tor (should it succeed)
- ireactortime – An object implementing IReactorTime (i.e. a reactor) which needs to be supplied if you pass a timeout.
- timeout – An int representing the timeout in seconds. If we are unable to reach 100% by this time we will consider the setting up of Tor to have failed. Must supply ireactortime if you supply this.
- kill_on_stderr – When True, kill subprocess if we receive anything on stderr
- stdout – Anything subprocess writes to stdout is sent to .write() on this
- stderr – Anything subprocess writes to stderr is sent to .write() on this
- tor_protocol – The TorControlProtocol instance connected to the Tor this ProcessProtocol>` is speaking to. Will be valid when the connected_cb callback runs.
- connected_cb – Triggered when the Tor process we represent is fully bootstrapped
This will terminate (with SIGTERM) the underlying Tor process.
Returns: a Deferred that callback()’s (with None) when the process has actually exited.
A timeout was supplied during setup, and the time has run out.
Clean up my temporary files.
progress(percent, tag, summary)¶
Can be overridden or monkey-patched if you want to get progress updates yourself.