Twisted-based asynchronous Tor control protocol implementation. Includes unit-tests, examples, state-tracking code and configuration abstraction.
Python Other
Failed to load latest commit information.
debian fix dependency name Sep 2, 2012
docs use VERSION consistently in release-checklist Jul 27, 2016
examples Create tunnel_tls_through_tor_client.py Feb 7, 2016
integration fix integration tests Jan 17, 2015
logo create a logo Dec 9, 2012
scripts git test-release a chance of working Dec 28, 2015
signatues signatures for 0.15.0 Jul 26, 2016
test pep8/whitespace Jul 26, 2016
twisted/plugins Cleanups and more tests for "tor:" endpoint parser May 31, 2015
txtorcon pep8/whitespace Jul 26, 2016
walkthrough better walkthrough code Dec 27, 2015
.coveragerc tell covereage where source code is Oct 10, 2015
.gitignore rename tox virtualenv's and gitignore them Feb 3, 2015
.travis.yml remove flake8 from travis until it's fixed Feb 25, 2016
Dockerfile fix integration tests Jan 17, 2015
INSTALL use ipaddress instead of ipaddr Mar 9, 2016
LICENSE Include LICENSE in manifest, and add 2013 to copyright dates (issue #53) May 18, 2013
MANIFEST.in ignore .pyc, fixing issue #76 Jun 15, 2014
Makefile git test-release a chance of working Dec 29, 2015
README.rst use ipaddress instead of ipaddr Mar 9, 2016
TODO remove irrelevant TODOs Sep 25, 2012
dev-requirements.txt use ipaddress instead of ipaddr Mar 9, 2016
docs-requirements.txt use ipaddress instead of ipaddr Mar 9, 2016
meejah.asc initial import Feb 29, 2012
requirements.txt use ipaddress instead of ipaddr Mar 9, 2016
setup.py whitespace, pep8 and metadata improvements for setup.py Oct 25, 2015
tox.ini Merge pull request #155 from meejah/153-ipaddress-instead-of-ipaddr Mar 16, 2016

README.rst

README

Documentation at https://txtorcon.readthedocs.org

https://travis-ci.org/meejah/txtorcon.png?branch=master https://coveralls.io/repos/meejah/txtorcon/badge.png http://codecov.io/github/meejah/txtorcon/coverage.svg?branch=master http://api.flattr.com/button/flattr-badge-large.png

quick start

For the impatient, there are two quick ways to install this:

$ pip install txtorcon

... or, if you checked out or downloaded the source:

$ python setup.py install

... or, better yet, use a virtualenv and the dev requirements:

$ virtualenv venv
$ ./venv/bin/pip install -e .[dev]

For OSX, we can install txtorcon with the help of easy_install:

$ easy_install txtorcon

To avoid installing, you can just add the base of the source to your PYTHONPATH:

$ export PYTHONPATH=`pwd`:$PYTHONPATH

Then, you will want to explore the examples. Try "python examples/stream_circuit_logger.py" for instance.

On Debian testing (jessie), or with wheezy-backports (big thanks to Lunar^ for all his packaging work) you can install easily:

$ apt-get install python-txtorcon

You may also like this asciinema demo for an overview.

Tor configuration

You'll want to have the following options on in your torrc:

CookieAuthentication 1
CookieAuthFileGroupReadable 1

If you want to use unix sockets to speak to tor:

ControlSocketsGroupWritable 1
ControlSocket /var/run/tor/control

The defaults used by py:meth:txtorcon.build_local_tor_connection will find a Tor on 9051 or /var/run/tor/control

overview

txtorcon is a Twisted-based asynchronous Tor control protocol implementation. Twisted is an event-driven networking engine written in Python and Tor is an onion-routing network designed to improve people's privacy and anonymity on the Internet.

The main abstraction of this library is txtorcon.TorControlProtocol which presents an asynchronous API to speak the Tor client protocol in Python. txtorcon also provides abstractions to track and get updates about Tor's state (txtorcon.TorState) and current configuration (including writing it to Tor or disk) in txtorcon.TorConfig, along with helpers to asynchronously launch slave instances of Tor including Twisted endpoint support.

txtorcon runs all tests cleanly on:

  • Debian "squeeze", "wheezy" and "jessie"
  • OS X 10.4 (naif)
  • OS X 10.8 (lukas lueg)
  • OS X 10.9 (kurt neufeld)
  • Fedora 18 (lukas lueg)
  • FreeBSD 10 (enrique fynn) (needed to install "lsof")
  • RHEL6
  • Reports from other OSes appreciated.

If instead you want a synchronous (threaded) Python controller library, check out Stem at https://stem.torproject.org/

quick implementation overview

txtorcon provides a class to track Tor's current state -- such as details about routers, circuits and streams -- called txtorcon.TorState and an abstraction to the configuration values via txtorcon.TorConfig which provides attribute-style accessors to Tor's state (including making changes). txtorcon.TorState provides txtorcon.Router, txtorcon.Circuit and txtorcon.Stream objects which implement a listener interface so client code may receive updates (in real time) including Tor events.

txtorcon uses trial for unit-tests and has 100% test-coverage -- which is not to say I've covered all the cases, but nearly all of the code is at least exercised somehow by the unit tests.

Tor itself is not required to be running for any of the tests. ohcount claims around 2000 lines of code for the core bit; around 4000 including tests. About 37% comments in the not-test code.

There are a few simple integration tests, based on Docker. More are always welcome!

dependencies / requirements

  • twisted: txtorcon should work with any

    Twisted 11.1.0 or newer. Twisted 15.4.0+ works with Python3, and so does txtorcon (if you find something broken on Py3 please file a bug).

  • GeoIP: optional provides location information for ip addresses; you will want to download GeoLite City from MaxMind or pay them for more accuracy. Or use tor-geoip, which makes this sort-of optional, in that we'll query Tor for the IP if the GeoIP database doesn't have an answer. It also does ASN lookups if you installed that MaxMind database.

  • development: Sphinx if you want to build the documentation. In that case you'll also need something called python-repoze.sphinx.autointerface (at least in Debian) to build the Interface-derived docs properly.

  • development: coverage to run the code-coverage metrics, and Tox

  • optional: GraphViz is used in the tests (and to generate state-machine diagrams, if you like) but those tests are skipped if "dot" isn't in your path

In any case, on a Debian wheezy, squeeze or Ubuntu system, this should work:

apt-get install -y python-setuptools python-twisted python-ipaddr python-geoip graphviz tor
apt-get install -y python-sphinx python-repoze.sphinx.autointerface python-coverage # for development

Using pip this would be:

pip install Twisted ipaddr pygeoip
pip install GeoIP Sphinx repoze.sphinx.autointerface coverage  # for development

or:

pip install -r requirements.txt
pip install -r dev-requirements.txt

or for the bare minimum:

pip install Twisted  # will install zope.interface too

documentation

It is likely that you will need to read at least some of control-spec.txt from the torspec git repository so you know what's being abstracted by this library.

Run "make doc" to build the Sphinx documentation locally, or rely on ReadTheDocs https://txtorcon.readthedocs.org which builds each tagged release and the latest master.

There is also a directory of examples/ scripts, which have inline documentation explaining their use.

contact information

For novelty value, the Web site (with built documentation and so forth) can be viewed via Tor at http://timaq4ygg2iegci7.onion although the code itself is hosted via git:

torsocks git clone git://timaq4ygg2iegci7.onion/txtorcon.git

or:

git clone git://github.com/meejah/txtorcon.git

You may contact me via meejah at meejah dot ca with GPG key 0xC2602803128069A7 or see meejah.asc in the repository. The fingerprint is 9D5A 2BD5 688E CB88 9DEB CD3F C260 2803 1280 69A7.

It is often possible to contact me as meejah in #tor-dev on OFTC but be patient for replies (I do look at scrollback, so putting "meejah: " in front will alert my client).

More conventionally, you may get the code at GitHub and documentation via ReadTheDocs:

Please do use the GitHub issue-tracker to report bugs. Patches, pull-requests, comments and criticisms are all welcomed and appreciated.