commit b0be16b7e93f56e6189cea6b0b991cded1db6a02 Author: Damian Johnson atagar@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:formatimage/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 + +