commit b4da7f833ded8123d4af709dad4c5c84cccbd147 Author: Damian Johnson atagar@torproject.org Date: Sat May 24 13:49:49 2014 -0700

'Down the Rabbit Hole' tutorial

Adding a tutorial for our new interpreter, giving an overview of both how to run it and what it can do. Think this might be my favorite tutorial yet... --- docs/_static/label/down_the_rabbit_hole.png | Bin 0 -> 2596 bytes .../label/resources/down_the_rabbit_hole.xcf | Bin 0 -> 6800 bytes docs/_static/prompt/attach.png | Bin 0 -> 19213 bytes docs/_static/prompt/events_command.png | Bin 0 -> 13914 bytes docs/_static/prompt/events_variable.png | Bin 0 -> 17084 bytes docs/_static/prompt/help.png | Bin 0 -> 41900 bytes docs/_static/prompt/info.png | Bin 0 -> 23483 bytes docs/_static/prompt/python.png | Bin 0 -> 63694 bytes docs/_static/prompt/starting_tor.png | Bin 0 -> 22249 bytes docs/_static/prompt/tor_commands.png | Bin 0 -> 41184 bytes docs/_static/section/tutorials/mad_hatter.png | Bin 0 -> 19278 bytes .../section/tutorials/resources/mad_hatter.xcf | Bin 0 -> 35098 bytes docs/_templates/layout.html | 1 + docs/conf.py | 2 +- docs/contents.rst | 3 +- docs/tutorials.rst | 19 ++++ docs/tutorials/down_the_rabbit_hole.rst | 111 ++++++++++++++++++++ 17 files changed, 134 insertions(+), 2 deletions(-)

diff --git a/docs/_static/label/down_the_rabbit_hole.png b/docs/_static/label/down_the_rabbit_hole.png new file mode 100644 index 0000000..a3d3587 Binary files /dev/null and b/docs/_static/label/down_the_rabbit_hole.png differ diff --git a/docs/_static/label/resources/down_the_rabbit_hole.xcf b/docs/_static/label/resources/down_the_rabbit_hole.xcf new file mode 100644 index 0000000..c4c61ee Binary files /dev/null and b/docs/_static/label/resources/down_the_rabbit_hole.xcf differ diff --git a/docs/_static/prompt/attach.png b/docs/_static/prompt/attach.png new file mode 100644 index 0000000..96add67 Binary files /dev/null and b/docs/_static/prompt/attach.png differ diff --git a/docs/_static/prompt/events_command.png b/docs/_static/prompt/events_command.png new file mode 100644 index 0000000..3f058ae Binary files /dev/null and b/docs/_static/prompt/events_command.png differ diff --git a/docs/_static/prompt/events_variable.png b/docs/_static/prompt/events_variable.png new file mode 100644 index 0000000..f104767 Binary files /dev/null and b/docs/_static/prompt/events_variable.png differ diff --git a/docs/_static/prompt/help.png b/docs/_static/prompt/help.png new file mode 100644 index 0000000..52eece9 Binary files /dev/null and b/docs/_static/prompt/help.png differ diff --git a/docs/_static/prompt/info.png b/docs/_static/prompt/info.png new file mode 100644 index 0000000..e23fa1c Binary files /dev/null and b/docs/_static/prompt/info.png differ diff --git a/docs/_static/prompt/python.png b/docs/_static/prompt/python.png new file mode 100644 index 0000000..ea46114 Binary files /dev/null and b/docs/_static/prompt/python.png differ diff --git a/docs/_static/prompt/starting_tor.png b/docs/_static/prompt/starting_tor.png new file mode 100644 index 0000000..3e63792 Binary files /dev/null and b/docs/_static/prompt/starting_tor.png differ diff --git a/docs/_static/prompt/tor_commands.png b/docs/_static/prompt/tor_commands.png new file mode 100644 index 0000000..51f2f2b Binary files /dev/null and b/docs/_static/prompt/tor_commands.png differ diff --git a/docs/_static/section/tutorials/mad_hatter.png b/docs/_static/section/tutorials/mad_hatter.png new file mode 100644 index 0000000..0c27756 Binary files /dev/null and b/docs/_static/section/tutorials/mad_hatter.png differ diff --git a/docs/_static/section/tutorials/resources/mad_hatter.xcf b/docs/_static/section/tutorials/resources/mad_hatter.xcf new file mode 100644 index 0000000..cb29e62 Binary files /dev/null and b/docs/_static/section/tutorials/resources/mad_hatter.xcf differ diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 66e2895..5f60231 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -29,6 +29,7 @@ <li><a href="{{ pathto('tutorials/tortoise_and_the_hare') }}">Event Listening</a></li> <li><a href="{{ pathto('tutorials/mirror_mirror_on_the_wall') }}">Tor Descriptors</a></li> <li><a href="{{ pathto('tutorials/east_of_the_sun') }}">Utilities</a></li> + <li><a href="{{ pathto('tutorials/down_the_rabbit_hole') }}">Interpreter</a></li> <li><a href="{{ pathto('tutorials/double_double_toil_and_trouble') }}">Examples</a></li> </ul> </li> diff --git a/docs/conf.py b/docs/conf.py index 801ef91..756bd20 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -142,7 +142,7 @@ html_static_path = ['_static']

# If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +html_use_smartypants = False

# Custom sidebar templates, maps document names to template names. #html_sidebars = {} diff --git a/docs/contents.rst b/docs/contents.rst index 9555673..6667123 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -8,8 +8,9 @@ Contents tutorials/the_little_relay_that_could tutorials/to_russia_with_love tutorials/tortoise_and_the_hare - tutorials/east_of_the_sun tutorials/mirror_mirror_on_the_wall + tutorials/east_of_the_sun + tutorials/down_the_rabbit_hole tutorials/double_double_toil_and_trouble

tutorials/examples/compare_flags diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 2b13b79..40b5439 100644 --- a/docs/tutorials.rst +++ b/docs/tutorials.rst @@ -31,6 +31,13 @@ Tutorial Author: Andrejj License: CC0 (https://creativecommons.org/publicdomain/zero/1.0/deed.en)

+ * Mad Hatter - mad_hatter.png + Source: http://www.krepcio.com/vitreosity/archives/MadHatter-ALL-illus600.jpg + Author: John Tenniel + License: Public Doman + Augmented: Colored by me, and used the card from... + https://openclipart.org/detail/1892/mad-hatter-with-label-on-hat-by-nayrhcre... + * Double Double Toil and Trouble - cauldron.png Source: https://openclipart.org/detail/174099/cauldron-by-jarda-174099 Author: Unknown (jarda?) @@ -92,6 +99,18 @@ feet wet by jumping straight in with some tutorials... Stem provides several utility modules frequently useful for Tor controller applications. Here we introduce some of them.

+ * - .. image:: /_static/section/tutorials/mad_hatter.png + :target: tutorials/down_the_rabbit_hole.html + + - .. image:: /_static/label/down_the_rabbit_hole.png + :target: tutorials/down_the_rabbit_hole.html + + Interactive interpreter for Tor that provides you with direct access to + Tor's `control interface + https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt`_ + via either python or direct requests. This is an easy way of + experimenting with Stem and learning what Tor can do. + * - .. image:: /_static/section/tutorials/cauldron.png :target: tutorials/double_double_toil_and_trouble.html

diff --git a/docs/tutorials/down_the_rabbit_hole.rst b/docs/tutorials/down_the_rabbit_hole.rst new file mode 100644 index 0000000..2cfbabb --- /dev/null +++ b/docs/tutorials/down_the_rabbit_hole.rst @@ -0,0 +1,111 @@ +Down the Rabbit Hole +==================== + +Underneath it all Stem is a Python implementation of Tor's `control +https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt`_ and +`directory specifications +https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt`_. +Anything you can do with Stem you can also do `with telnet +<../faq.html#can-i-interact-with-tors-controller-interface-directly>`_ (albeit +with quite a bit of extra work). + +Playing with Tor's control port directly is a great way of learning what +Tor can and cannot do. This is handy because Stem can take advantage of +anything the control interface offers, but conversely is also limited by +things it lacks. + +To help Stem offers a control prompt with nice usability improvements over +telnet... + +* Irc-style commands like '**/help**'. +* Is a **python interpreter** (like IDLE). +* Tab completion for Tor's controller commands. +* History scrollback by pressing up/down. +* Transparently handles Tor authentication at startup. +* Colorized output for improved readability. + +.. _getting-started: + +Getting started +--------------- + +Getting started with the control prompt is easy. Assuming you have Stem +installed it will be available under **/usr/bin/tor-prompt**, and can attach +to either an existing Tor instance or start one of its own. + +If Tor's already running `with a control port +<the_little_relay_that_could.html>`_ then you can attach to it using +**--interface** or **--socket** (by default it checks on **port 9051**)... + +.. image:: /_static/prompt/attach.png + +If Tor isn't running this prompt will start a temporary instance of its own. +Tor will have a minimal non-relaying configuration, and be shut down when +you're done. + +.. image:: /_static/prompt/starting_tor.png + +.. _what-can-i-do-with-it: + +What can I do with it? +---------------------- + +This prompt accepts three types of commands... + +* Commands for the interpreter itself, such as **/help** and **/info**. These + are handled by the interpreter and always begin with a slash. + +* Commands for Tor's control port, such as **GETINFO version** and **GETCONF + ExitPolicy**. These are passed along directly to Tor. + +* Commands that do not match either of the above are treated as Python. + +To get a list of the interpreter and Tor commands run **/help**. You can also +run **/help [command]** (such as **/help SIGNAL**) to get details on what +does... + +.. image:: /_static/prompt/help.png + +Another useful interpreter command is **/info [relay]** which provides +information about a relay. With this you can look up details about any relay by +its IP address, fingerprint, or nickname... + +.. image:: /_static/prompt/info.png + +Tor commands are passed along directly to Tor's control port, providing raw +responses just as telnet would... + +.. image:: /_static/prompt/tor_commands.png + +And last but certainly not least this prompt provides a Python interpreter, +just like IDLE. You start with a :class:`~stem.control.Controller` for you Tor +instance available as your **controller** variable. This makes it easy to +experiment with Stem and see what it can do... + +.. image:: /_static/prompt/python.png + +.. _event-handling: + +Event handling +-------------- + +As mentioned in an `earlier tutorial <tortoise_and_the_hare.html>`_ you can +subscribe to receive events from Tor. Stem's :class:`~stem.control.Controller` +does this with its :func:`~stem.control.Controller.add_event_listener` method, +but with our raw Tor access we can also subscribe with **SETEVENTS [event +types]**. + +Events we've received are available in two different ways. First, **/events** +provides a quick dump of the events we've received thus far... + +.. image:: /_static/prompt/events_command.png + +You can list events of just a certain type by saying which (for instance +**/events BW**). More useful though is your **events** variable, which is a +list of :class:`~stem.response.events.Event` instances we've received... + +.. image:: /_static/prompt/events_variable.png + +To stop receiving events run **SETEVENTS** without any event types, and to +clear the backlog of events we've received run **/events clear**. +