Low-Level Protocol Classes¶
build_tor_connection¶
- txtorcon.build_tor_connection(connection, build_state=True, wait_for_proto=True, password_function=<function <lambda>>)¶
This is used to build a valid TorState (which has .protocol for the TorControlProtocol). For example:
from twisted.internet import reactor from twisted.internet.endpoints import TCP4ClientEndpoint import txtorcon def example(state): print "Fully bootstrapped state:",state print " with bootstrapped protocol:",state.protocol d = txtorcon.build_tor_connection(TCP4ClientEndpoint(reactor, "localhost", 9051)) d.addCallback(example) reactor.run()
- Parameters:
password_function – See
txtorcon.TorControlProtocol
build_state – If True (the default) a TorState object will be built as well. If False, just a TorControlProtocol will be returned via the Deferred.
- Returns:
a Deferred that fires with a TorControlProtocol or, if you specified build_state=True, a TorState. In both cases, the object has finished bootstrapping (i.e. TorControlProtocol.post_bootstrap or TorState.post_bootstap has fired, as needed)
build_local_tor_connection¶
- txtorcon.build_local_tor_connection(reactor, host='127.0.0.1', port=9051, socket='/var/run/tor/control', *args, **kwargs)¶
This builds a connection to a local Tor, either via 127.0.0.1:9051 or /var/run/tor/control (by default; the latter is tried first). See also
build_tor_connection
for other key-word arguments that are accepted here also.Note: new code should use
txtorcon.connect()
instead.- Parameters:
host – An IP address to find Tor at. Corresponds to the ControlListenAddress torrc option.
port – The port to use with the address when trying to contact Tor. This corresponds to the ControlPort option in torrc (default is 9051).
TorControlProtocol¶
- class txtorcon.TorControlProtocol(password_function=None)¶
This is the main class that talks to a Tor and implements the “raw” procotol.
This instance does not track state; see
txtorcon.TorState
for 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.
TorProtocolFactory¶
- class txtorcon.TorProtocolFactory(password_function=<function TorProtocolFactory.<lambda>>)¶
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¶
- class txtorcon.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 validtxtorcon.TorControlProtocol
instance by that point.connection_creator is a callable that should return a Deferred that callbacks with a
txtorcon.TorControlProtocol
; seetxtorcon.launch_tor()
for the default one which is a functools.partial that will callconnect(TorProtocolFactory())
on an appropriate twisted.internet.endpoints.TCP4ClientEndpoint- Parameters:
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
- Variables:
tor_protocol – The TorControlProtocol instance connected to the Tor this ProcessProtocol>` is speaking to. Will be valid after the Deferred returned from
TorProcessProtocol.when_connected()
is triggered.