txtorcon is a Twisted-based Python asynchronous controller library for Tor, following control-spec. This would be of interest to anyone wishing to write event-based software in Python that talks to (and/or launches) a Tor program.
You get real-time access to all state in Tor (circuits, streams, logging, hidden-services) and utilities to launch or connect to running Tor instances (including Tor Browser Bundle).
The main code is around 2300 lines according to ohcount, or about 5600 lines including tests.
With txtorcon installed, you can use "onion:" port/endpoint strings with any endpoint-aware Twisted program. For example, to use Twisted Web to serve your ~/public_html as a hidden service (-n means don’t daemonize and log to stdout):
$ twistd -n web --port "onion:80" --path ~/public_html 2014-05-30 21:40:23-0600 [-] Log opened. #...truncated 2014-05-30 21:41:16-0600 [TorControlProtocol,client] Tor launching: 90% Establishing a Tor circuit 2014-05-30 21:41:17-0600 [TorControlProtocol,client] Tor launching: 100% Done 2014-05-30 21:41:17-0600 [TorControlProtocol,client] Site starting on 46197 2014-05-30 21:41:17-0600 [TorControlProtocol,client] Starting factory <twisted.web.server.Site instance at 0x7f57667d0cb0> 2014-05-30 21:41:17-0600 [TorControlProtocol,client] Set up hidden service "2vrrgqtpiaildmsm.onion" on port 80
There’s a complete demonstration at asciinema.org.
Some (other) features and motivating examples:
- txtorcon.TorConfig tracks and allows updating of config with attribute-style acccess (including hidden services):
A slight change to the Echo Server example on the front page of Twisted’s Web site can make it appear as a hidden service:
from __future__ import print_function from twisted.internet import protocol, reactor, endpoints class Echo(protocol.Protocol): def dataReceived(self, data): self.transport.write(data) class EchoFactory(protocol.Factory): def buildProtocol(self, addr): return Echo() endpoints.serverFromString(reactor, "onion:1234").listen(EchoFactory()).addCallback(lambda x: print(x.getHost())) reactor.run()
This is just a one-line change. Note there isn’t even an “import txtorcon” (although it does need to be installed so that Twisted finds the IPlugin that does the parsing).
This documentation was generated January 29, 2015.
If you’re using Debian, txtorcon is now in testing (jessie) and wheezy-backports thanks to Lunar:
echo "deb http://ftp.ca.debian.org/debian/ wheezy-backports main" >> /etc/apt/sources.list apt-get update apt-get install python-txtorcon
It also appears txtorcon is in Gentoo but I don’t use Gentoo (if anyone has a shell-snippet that installs it, send a pull-request).
Installing the wheel files requires a recent pip and setuptools. At least on Debian, it is important to upgrade setuptools before pip. This procedure appears to work fine:
virtualenv foo . foo/bin/activate pip install --upgrade setuptools pip install --upgrade pip pip install path/to/txtorcon-0.9.0-py27-none-any.whl