[tor-commits] [stem/master] Adding connection resolution tutorial
atagar at torproject.org
atagar at torproject.org
Mon Sep 30 03:03:32 UTC 2013
commit b0be16b7e93f56e6189cea6b0b991cded1db6a02
Author: Damian Johnson <atagar at torproject.org>
Date: Sun Sep 29 20:01:16 2013 -0700
Adding connection resolution tutorial
Introducing a new tutorial section called 'East of the Sun & West of the Moon'
(... I love that fairytale) that introduces users to our utility modules.
Presently this just has connection resolution, a spiffy new feature I added
last weekend.
---
docs/_static/label/east_of_the_sun.png | Bin 0 -> 3270 bytes
docs/_static/label/resources/east_of_the_sun.xcf | Bin 0 -> 7582 bytes
.../section/tutorials/resources/windrose.svg | 191 ++++++++++++++++++++
docs/_static/section/tutorials/windrose.png | Bin 0 -> 8319 bytes
docs/contents.rst | 1 +
docs/tutorials.rst | 14 ++
docs/tutorials/east_of_the_sun.rst | 78 ++++++++
7 files changed, 284 insertions(+)
diff --git a/docs/_static/label/east_of_the_sun.png b/docs/_static/label/east_of_the_sun.png
new file mode 100644
index 0000000..3fd091e
Binary files /dev/null and b/docs/_static/label/east_of_the_sun.png differ
diff --git a/docs/_static/label/resources/east_of_the_sun.xcf b/docs/_static/label/resources/east_of_the_sun.xcf
new file mode 100644
index 0000000..1cf75cc
Binary files /dev/null and b/docs/_static/label/resources/east_of_the_sun.xcf differ
diff --git a/docs/_static/section/tutorials/resources/windrose.svg b/docs/_static/section/tutorials/resources/windrose.svg
new file mode 100644
index 0000000..59d4835
--- /dev/null
+++ b/docs/_static/section/tutorials/resources/windrose.svg
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="492"
+ height="484"
+ viewBox="-5 -5 128 126"
+ id="svg2"
+ sodipodi:version="0.32"
+ inkscape:version="0.48.3.1 r9886"
+ sodipodi:docname="Compass_card_(sl).svg"
+ inkscape:output_extension="org.inkscape.output.svg.inkscape"
+ version="1.1"
+ inkscape:export-filename="/home/atagar/Desktop/Compass_card_(sl).png"
+ inkscape:export-xdpi="23.958799"
+ inkscape:export-ydpi="23.958799">
+ <metadata
+ id="metadata105">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title></dc:title>
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <defs
+ id="defs103">
+ <inkscape:perspective
+ sodipodi:type="inkscape:persp3d"
+ inkscape:vp_x="0 : 242 : 1"
+ inkscape:vp_y="0 : 1000 : 0"
+ inkscape:vp_z="492 : 242 : 1"
+ inkscape:persp3d-origin="246 : 161.33333 : 1"
+ id="perspective107" />
+ </defs>
+ <sodipodi:namedview
+ inkscape:window-height="696"
+ inkscape:window-width="1024"
+ inkscape:pageshadow="2"
+ inkscape:pageopacity="0.0"
+ guidetolerance="10.0"
+ gridtolerance="10.0"
+ objecttolerance="10.0"
+ borderopacity="1.0"
+ bordercolor="#666666"
+ pagecolor="#ffffff"
+ id="base"
+ showgrid="false"
+ inkscape:zoom="0.95454545"
+ inkscape:cx="246"
+ inkscape:cy="273.72233"
+ inkscape:window-x="0"
+ inkscape:window-y="24"
+ inkscape:current-layer="svg2"
+ inkscape:window-maximized="0" />
+ <g
+ id="g4"
+ transform="matrix(1.2776887,0,0,1.2776887,-19.635229,-19.332998)">
+ <g
+ id="g6">
+ <polygon
+ points="95.833496,26.863281 71.893066,60.804688 61.893066,60.804688 "
+ id="polygon8"
+ style="fill:#c5f2fb" />
+ <polygon
+ points="27.95166,26.864258 61.893066,50.804688 61.893066,60.804688 "
+ id="polygon10"
+ style="fill:#c5f2fb" />
+ <polygon
+ points="27.952637,94.746094 51.893066,60.804688 61.893066,60.804688 "
+ id="polygon12"
+ style="fill:#c5f2fb" />
+ <polygon
+ points="95.834473,94.745117 61.893066,70.804688 61.893066,60.804688 "
+ id="polygon14"
+ style="fill:#c5f2fb" />
+ </g>
+ <g
+ id="g16">
+ <polygon
+ points="27.952148,26.863281 51.893066,60.804688 61.893066,60.804688 "
+ id="polygon18"
+ style="fill:#4291e4" />
+ <polygon
+ points="95.834473,26.864258 61.893066,50.804688 61.893066,60.804688 "
+ id="polygon20"
+ style="fill:#4291e4" />
+ <polygon
+ points="95.833496,94.746094 71.893066,60.804688 61.893066,60.804688 "
+ id="polygon22"
+ style="fill:#4291e4" />
+ <polygon
+ points="27.95166,94.745117 61.893066,70.804688 61.893066,60.804688 "
+ id="polygon24"
+ style="fill:#4291e4" />
+ </g>
+ <polygon
+ stroke-miterlimit="100"
+ points="71.893066,60.804688 95.834473,94.746094 61.893066,70.804688 27.952148,94.746094 51.893066,60.804688 27.952148,26.863281 61.893066,50.804688 95.834473,26.863281 "
+ id="polygon26"
+ style="fill:none;stroke:#000000;stroke-width:0.5;stroke-miterlimit:100" />
+ </g>
+ <g
+ id="g28"
+ transform="matrix(1.2776887,0,0,1.2776887,-19.635229,-19.332998)">
+ <g
+ id="g30">
+ <polygon
+ points="61.893066,12.804688 71.893066,50.804688 61.893066,60.804688 "
+ id="polygon32"
+ style="fill:#d4e5f7" />
+ <polygon
+ points="51.893066,50.804688 13.893066,60.804688 61.893066,60.804688 "
+ id="polygon34"
+ style="fill:#d4e5f7" />
+ <polygon
+ points="51.893066,70.804688 61.893066,108.80469 61.893066,60.804688 "
+ id="polygon36"
+ style="fill:#d4e5f7" />
+ <polygon
+ points="71.893066,70.804688 109.89307,60.804688 61.893066,60.804688 "
+ id="polygon38"
+ style="fill:#d4e5f7" />
+ </g>
+ <g
+ id="g40">
+ <polygon
+ points="61.893066,12.804688 51.893066,50.804688 61.893066,60.804688 "
+ id="polygon42"
+ style="fill:#0d0ba9" />
+ <polygon
+ points="71.893066,50.804688 109.89307,60.804688 61.893066,60.804688 "
+ id="polygon44"
+ style="fill:#0d0ba9" />
+ <polygon
+ points="71.893066,70.804688 61.893066,108.80469 61.893066,60.804688 "
+ id="polygon46"
+ style="fill:#0d0ba9" />
+ <polygon
+ points="51.893066,70.804688 13.893066,60.804688 61.893066,60.804688 "
+ id="polygon48"
+ style="fill:#0d0ba9" />
+ </g>
+ <polygon
+ points="71.893066,70.804688 61.893066,108.80469 51.893066,70.804688 13.893555,60.804688 51.893066,50.804688 61.893066,12.804688 71.893066,50.804688 109.89307,60.804688 "
+ id="polygon50"
+ style="fill:none;stroke:#000000;stroke-width:0.5" />
+ </g>
+ <g
+ id="g52"
+ transform="matrix(1.2776887,0,0,1.2776887,-19.635229,-19.332998)">
+ <polyline
+ points="61.8930664,60.8046875 61.8930664,12.8046875 61.8930664,108.8046875 "
+ id="polyline54"
+ style="fill:none;stroke:#000000;stroke-width:0.5" />
+ <line
+ x1="109.89307"
+ y1="60.804688"
+ x2="13.893555"
+ y2="60.804688"
+ id="line56"
+ style="fill:none;stroke:#000000;stroke-width:0.5" />
+ <line
+ x1="95.834473"
+ y1="26.863281"
+ x2="27.952148"
+ y2="94.746094"
+ id="line58"
+ style="fill:none;stroke:#000000;stroke-width:0.5" />
+ <polyline
+ points="61.8930664,60.8046875 27.9521484,26.8632813 95.8344727,94.7460938 "
+ id="polyline60"
+ style="fill:none;stroke:#000000;stroke-width:0.5" />
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+ x="111.68595"
+ y="54.181816"
+ id="text2480"><tspan
+ sodipodi:role="line"
+ id="tspan2482" /></text>
+</svg>
diff --git a/docs/_static/section/tutorials/windrose.png b/docs/_static/section/tutorials/windrose.png
new file mode 100644
index 0000000..da799d9
Binary files /dev/null and b/docs/_static/section/tutorials/windrose.png differ
diff --git a/docs/contents.rst b/docs/contents.rst
index e1e4763..fbb0ecd 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -8,6 +8,7 @@ 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/double_double_toil_and_trouble
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
index 8153181..267a6c4 100644
--- a/docs/tutorials.rst
+++ b/docs/tutorials.rst
@@ -26,6 +26,11 @@ Tutorial
License: Public Domain
Alternate: https://openclipart.org/detail/174179/miroir-rectangulaire-by-defaz36-174179
+ * East of the Sun & West of the Moon - windrose.png
+ Source: https://commons.wikimedia.org/wiki/File:Compass_card_%28sl%29.svg
+ Author: Andrejj
+ License: CC0 (https://creativecommons.org/publicdomain/zero/1.0/deed.en)
+
* Double Double Toil and Trouble - cauldron.png
Source: https://openclipart.org/detail/174099/cauldron-by-jarda-174099
Author: Unknown (jarda?)
@@ -78,6 +83,15 @@ feet wet by jumping straight in with some tutorials...
This walks you through both where to get them and a small script to tell
you the fastest Tor exits.
+ * - .. image:: /_static/section/tutorials/windrose.png
+ :target: tutorials/east_of_the_sun.html
+
+ - .. image:: /_static/label/east_of_the_sun.png
+ :target: tutorials/east_of_the_sun.html
+
+ Stem provides several utility modules frequently useful for Tor
+ controller applications. Here we introduce some of them.
+
* - .. image:: /_static/section/tutorials/cauldron.png
:target: tutorials/double_double_toil_and_trouble.html
diff --git a/docs/tutorials/east_of_the_sun.rst b/docs/tutorials/east_of_the_sun.rst
new file mode 100644
index 0000000..5a94df9
--- /dev/null
+++ b/docs/tutorials/east_of_the_sun.rst
@@ -0,0 +1,78 @@
+East of the Sun & West of the Moon
+==================================
+
+The following is an overview of some of the utilities stem provides.
+
+* :ref:`connection-resolution`
+
+.. _connection-resolution:
+
+Connection Resolution
+---------------------
+
+Connection information is a useful tool for learning more about network
+applications like Tor. Our :func:`stem.util.connection.get_connections`
+function provides an easy method for accessing this information, with a few
+caveats...
+
+* Connection resolvers are platform specific. We `support several
+ <../api/util/connection.html#stem.util.connection.Resolver>`_ but not not
+ all, most notably Windows (:trac:`9850`).
+
+* By default Tor runs with a feature called **DisableDebuggerAttachment**. This
+ prevents debugging applications like gdb from analyzing Tor unless it is run
+ as root. Unfortunately this also alters the permissions of the Tor process
+ /proc contents breaking numerous system tools (including our resolvers). To
+ use this function you need to either run as root (discouraged) or add
+ **DisableDebuggerAttachment 0** to your torrc.
+
+Please note that if you operate an exit relay it is **highly** discouraged for
+you to look at or record this information. Not only is doing so eavesdropping,
+but likely also a violation of wiretap laws.
+
+With that out of the way, how do you look up this information? Below is a
+simple script that dumps Tor's present connections.
+
+::
+
+ import sys
+
+ from stem.util.connection import get_connections, get_system_resolvers
+ from stem.util.system import get_pid_by_name
+
+ resolvers = get_system_resolvers()
+
+ if not resolvers:
+ print "Stem doesn't support any connection resolvers on our platform."
+ sys.exit(1)
+
+ picked_resolver = resolvers[0] # lets just opt for the first
+ print "Our platform supports connection resolution via: %s (picked %s)" % (', '.join(resolvers), picked_resolver)
+
+ tor_pids = get_pid_by_name('tor', multiple = True)
+
+ if not tor_pids:
+ print "Unable to get tor's pid. Is it running?"
+ sys.exit(1)
+ elif len(tor_pids) > 1:
+ print "You're running %i instances of tor, picking the one with pid %i" % (len(tor_pids), tor_pids[0])
+ else:
+ print "Tor is running with pid %i" % tor_pids[0]
+
+ print "\nConnections:\n"
+
+ for conn in get_connections(picked_resolver, process_pid = tor_pids[0], process_name = 'tor'):
+ print " %s:%s => %s:%s" % (conn.local_address, conn.local_port, conn.remote_address, conn.remote_port)
+
+::
+
+ % python example.py
+ Our platform supports connection resolution via: proc, netstat, sockstat, lsof, ss (picked proc)
+ Tor is running with pid 17303
+
+ Connections:
+
+ 192.168.0.1:59014 => 38.229.79.2:443
+ 192.168.0.1:58822 => 68.169.35.102:443
+
+
More information about the tor-commits
mailing list