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

############################
 Leekspin  |Latest Version|
############################

.. image::
    https://raw.githubusercontent.com/isislovecruft/leekspin/develop/doc/sphinx/source/_static/Loituma.gif


**************************************
 An Onion Router descriptor generator
**************************************

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

This tool is meant to be used to generate mock descriptors for testing or
fuzzing other Tor libraries and programs, such as
`Stem <https://gitweb.torproject.org/stem.git>`_,
`BridgeDB <https://gitweb.torproject.org/bridgedb.git>`_, and
`Tor <https://gitweb.torproject.org/tor.git>`_.  The keys, hash digests, and
signatures generated within these mock descriptors are meant to be
indistinguishable from those generated by real relays, bridges, and Hidden
Services within the Tor network.


:authors: `Isis Lovecruft`_ <isis@torproject.org>
:licence: MIT licence, see `LICENSE`_ file for details
:copyright: © 2013-2016 Isis Lovecruft, The Tor Project, Inc.


.. |Latest Version| image:: https://pypip.in/version/leekspin/badge.svg?style=flat
   :target: https://pypi.python.org/pypi/leekspin/
.. |Build Status| image:: https://travis-ci.org/isislovecruft/leekspin.svg
   :target: https://travis-ci.org/isislovecruft/leekspin
.. |Coverage Status| image:: https://coveralls.io/repos/isislovecruft/leekspin/badge.png?branch=develop
   :target: https://coveralls.io/r/isislovecruft/leekspin?branch=develop
.. _Isis Lovecruft: https://fyb.patternsinthevoid.net
.. _LICENSE: https://github.com/isislovecruft/leekspin/blob/develop/LICENSE


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://git.torproject.org/user/isis/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
twenty-three Bridge descriptors, do::

    $ leekspin --bridge -n 23

And to generate forty-two Relay descriptors::

    $ leekspin --relay -n 42

And, likewise, to generate ten hidden service descriptors, do::

    $ leekspin --hidden-service -n 10


^^^^^^^^^^^^^^^^^
Commandline Flags
^^^^^^^^^^^^^^^^^

.. code-block:: shell

   $ leekspin -h
   usage: leekspin [-h] [[-v | -q] [--version] [-r | -b | -hs] [-n DESCRIPTORS]

   Generate a signed set of network-status, extra-info, and server descriptor
   documents for mock Tor relays or bridges.


Optional arguments:

-h, --help            show this help message and exit
-v, --verbose         print information to stdout
-q, --quiet           don't print anything
--version             print leekspin version and exit

Descriptor types:

-r, --relay            generate Relay descriptors
-b, --bridge           generate Bridge descriptors
-hs, --hidden-service  generate Hidden Service rendezvous descriptors

Descriptor variations:

-xt, --without-tap    generate descriptors without TAP support, e.g. without RSA keys
-xn, --without-ntor   generate descriptors without ntor support, e.g. without Ed25519 keys

Required arguments:

-n DESCRIPTORS, --descriptors DESCRIPTORS  generate <n> sets of descriptors


Bugs
========

Should you decide to use this tool, and especially should you be so insane as
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 on our issue tracker here <https://trac.torproject.org>`_ .