High Level API¶
This is the recommended API. See the Programming Guide for “prose” documentation of these (and other) APIs.
Tor(reactor, tor_config, _process_proto=None)¶
I represent a single instance of Tor and act as a Builder/Factory for several useful objects you will probably want. There are two ways to create a Tor instance:
If you desire more control, there are “lower level” APIs which are the very ones used by this class. However, this “highest level” API should cover many use-cases:
import txtorcon @inlineCallbacks def main(reactor): # tor = yield txtorcon.connect(UNIXClientEndpoint(reactor, "/var/run/tor/control")) tor = yield txtorcon.launch(reactor) onion_ep = tor.create_onion_endpoint(port=80) port = yield onion_ep.listen(Site()) print(port.getHost())
Closes the control connection, and if we launched this Tor instance we’ll send it a TERM and wait until it exits.
The TorControlProtocol instance that is communicating with this Tor instance.
The TorConfig instance associated with the tor instance we launched. This instance represents up-to-date configuration of the tor instance (even if another controller is connected).
- _socks_endpoint – If
None(the default), a suitable SOCKS port is chosen from our config (or added). If supplied, should be a Deferred which fires an IStreamClientEndpoint (e.g. the return-value from
txtorcon.TorConfig.socks_endpoint()) or an immediate IStreamClientEndpoint You probably don’t need to mess with this.
- pool – passed on to the Agent (as
- _socks_endpoint – If
Parameters: hostname – a string Returns: a Deferred that calbacks with the hostname as looked-up via Tor (or errback). This uses Tor’s custom extension to the SOCKS5 protocol.
Parameters: ip – a string, like “127.0.0.1” Returns: a Deferred that calbacks with the IP address as looked-up via Tor (or errback). This uses Tor’s custom extension to the SOCKS5 protocol.
stream_via(host, port, tls=False, _socks_endpoint=None)¶
This returns an IStreamClientEndpoint instance that will use this Tor (via SOCKS) to visit the
- host – The host to connect to. You MUST pass host-names to this. If you absolutely know that you’ve not leaked DNS (e.g. you save IPs in your app’s configuration or similar) then you can pass an IP.
- port – Port to connect to.
- tls – If True, it will wrap the return endpoint in one that does TLS (default: False).
- _socks_endpoint – Normally not needed (default: None)
but you can pass an IStreamClientEndpoint_ directed at one
of the local Tor’s SOCKS5 ports (e.g. created with
txtorcon.TorConfig.create_socks_endpoint()). Can be a Deferred.