[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Adding connection resolution tutorial



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

_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits