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).

There is a Walkthrough and HOWTOs.

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.
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:

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):

class EchoFactory(protocol.Factory):
    def buildProtocol(self, addr):
        return Echo()

endpoints.serverFromString(reactor, "onion:1234").listen(EchoFactory()).addCallback(lambda x: print(x.getHost()))

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 Mar 11, 2017.

https://travis-ci.org/meejah/txtorcon.png?branch=master https://coveralls.io/repos/meejah/txtorcon/badge.png https://pypip.in/d/txtorcon/badge.png

Getting txtorcon:

The canonical URI is http://timaq4ygg2iegci7.onion Code available at https://github.com/meejah/txtorcon

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

Known Users:

  • txtorcon received a brief mention at 29C3 starting at 12:20 (or via youtube).
  • carml command-line utilities for Tor
  • APAF anonymous Python application framework
  • OONI the Open Observatory of Network Interference
  • exitaddr scan Tor exit addresses

Indices and tables