[tor-commits] [stem/master] 'Down the Rabbit Hole' tutorial

atagar at torproject.org atagar at torproject.org
Sat May 24 20:52:16 UTC 2014


commit b4da7f833ded8123d4af709dad4c5c84cccbd147
Author: Damian Johnson <atagar at 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-nayrhcrel
+   
    * 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**.
+



More information about the tor-commits mailing list