leekspin 1.1.0

.. -*- mode: rst-mode -*-

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

Leekspin (á la `the original internet masterpiece <http://leekspin.com/>`_) is
a small library 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>`_. ♥Ⓐ