[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] 'Down the Rabbit Hole' tutorial
commit b4da7f833ded8123d4af709dad4c5c84cccbd147
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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**.
+
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits