leekspin 1.1.1

An Onion Router descriptor generator

.. -*- coding: utf-8; mode: rst-mode ; -*-

================================================
Leekspin: An Onion Router descriptor generator
================================================

Leekspin (á la `the original internet masterpiece <http://leekspin.com/>`_) is a small
tool for generating mocked Onion Router (OR) descriptors, such as
`those used by relays <https://metrics.torproject.org/formats.html#descriptortypes>`_
and `bridges <https://para.noid.cat/bridgedb/descriptors.html>`_ within
`Tor <https://www.torproject.org>`_ in order to convey information about said relay/bridge
to the Tor directory authorities, the bridge authority, and Tor clients connecting to the
network.

This library is meant to be used to generate mock descriptors for testing other Tor
libraries and programs, such as `Stem <https://gitweb.torproject.org/stem.git>`_ and
`BridgeDB <https://gitweb.torproject.org/bridgedb.git>`_.

The keys, hash digests, and signatures generated within these mock descriptors are meant
to be indistinguishable from those generated by real relays and bridges within the Tor
network.

Installing
==========

The very simplest way, if you use `pip <http://www.pip-installer.org/en/latest/>`_, would
be to do::

$ pip install leekspin

Otherwise, the standard setuptools commands work just fine::

$ git clone https://github.com/isislovecruft/leekspin.git
$ cd leekspin
$ python setup.py install --record installed-files.txt

Running
=======

Leekspin will install a script named… ``leekspin``. To use it to generate 20 bridge
descriptors, do::

$ leekspin -n 20

And to generate 20 relay descriptors::

$ leekspin -r -n 20

Bugs
====

Should you decide to use this tool, and especially should you be so insane and to try
hacking on it, you will likely find bugs. You may find bugs in Leekspin, BridgeDB, Stem,
Tor's `specifications <https://gitweb.torproject.org/torspec.git`_, and possibly even in
Tor. Please, for math's sake! Report them! The Tor developers will love you forever. You
can `report bugs here on our issue tracker <https://trac.torproject.org>`_.