[tor-commits] [stem/master] Moving tutorials to sub-pages
atagar at torproject.org
atagar at torproject.org
Mon Mar 4 08:17:57 UTC 2013
commit f4d2b20b2d954852faa59d39ce9f38f7cb11dcd2
Author: Damian Johnson <atagar at torproject.org>
Date: Mon Feb 18 22:12:01 2013 -0800
Moving tutorials to sub-pages
Making pages for each of the tutorials and making tutorial.rst a pretty listing
similar to the download page. This should hopefully make this page far more
approachable by newcomers.
---
docs/_static/label/mirror_mirror_on_the_wall.png | Bin 0 -> 2675 bytes
.../label/resources/mirror_mirror_on_the_wall.xcf | Bin 0 -> 7035 bytes
.../resources/the_little_relay_that_could.xcf | Bin 0 -> 7273 bytes
docs/_static/label/the_little_relay_that_could.png | Bin 0 -> 3162 bytes
docs/_static/section/tutorial/mirror.png | Bin 0 -> 2985 bytes
docs/_static/section/tutorial/train.png | Bin 0 -> 9887 bytes
docs/contents.rst | 3 +
docs/tutorial.rst | 168 ++++----------------
docs/tutorial/mirror_mirror_on_the_wall.rst | 83 ++++++++++
docs/tutorial/the_little_relay_that_could.rst | 56 +++++++
10 files changed, 172 insertions(+), 138 deletions(-)
diff --git a/docs/_static/label/mirror_mirror_on_the_wall.png b/docs/_static/label/mirror_mirror_on_the_wall.png
new file mode 100644
index 0000000..930d786
Binary files /dev/null and b/docs/_static/label/mirror_mirror_on_the_wall.png differ
diff --git a/docs/_static/label/resources/mirror_mirror_on_the_wall.xcf b/docs/_static/label/resources/mirror_mirror_on_the_wall.xcf
new file mode 100644
index 0000000..794cf7b
Binary files /dev/null and b/docs/_static/label/resources/mirror_mirror_on_the_wall.xcf differ
diff --git a/docs/_static/label/resources/the_little_relay_that_could.xcf b/docs/_static/label/resources/the_little_relay_that_could.xcf
new file mode 100644
index 0000000..2589e8d
Binary files /dev/null and b/docs/_static/label/resources/the_little_relay_that_could.xcf differ
diff --git a/docs/_static/label/the_little_relay_that_could.png b/docs/_static/label/the_little_relay_that_could.png
new file mode 100644
index 0000000..8c23539
Binary files /dev/null and b/docs/_static/label/the_little_relay_that_could.png differ
diff --git a/docs/_static/section/tutorial/mirror.png b/docs/_static/section/tutorial/mirror.png
new file mode 100644
index 0000000..69c2938
Binary files /dev/null and b/docs/_static/section/tutorial/mirror.png differ
diff --git a/docs/_static/section/tutorial/train.png b/docs/_static/section/tutorial/train.png
new file mode 100644
index 0000000..625b82e
Binary files /dev/null and b/docs/_static/section/tutorial/train.png differ
diff --git a/docs/contents.rst b/docs/contents.rst
index 6b0311c..390f0a9 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -36,3 +36,6 @@ Contents
api/util/term
api/util/tor_tools
+ tutorial/the_little_relay_that_could
+ tutorial/mirror_mirror_on_the_wall
+
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
index 0ca3d51..e5afa11 100644
--- a/docs/tutorial.rst
+++ b/docs/tutorial.rst
@@ -1,150 +1,42 @@
Tutorial
========
-Getting started with any new library can be rather daunting, so let's get our feet wet by jumping straight in with a tutorial...
-
-* :ref:`the-little-relay-that-could` - Hello world with the control port.
-* :ref:`mirror-mirror-on-the-wall` - Querying information about the Tor network.
-
-.. _the-little-relay-that-could:
-
-The Little Relay that Could
----------------------------
-
-Let's say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
-
-First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
-
-Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
-
-::
-
- # This provides a port for the script we write to talk to. If you set this
- # then be sure to also have either set the CookieAuthentication flag *or*
- # provide a HashedControlPassword!
-
- ControlPort 9051
-
- # This will make Tor write an authentication cookie file. Anything that can
- # read that file can connect to Tor. If you're going to run this script with
- # the same user as Tor then this is the easiest method of authentication to
- # use.
-
- CookieAuthentication 1
-
- # Alternatively we can authenticate with a password. To set a password first
- # get its hash...
- #
- # % tor --hash-password "my_password"
- # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
- #
- # ... and use that for the HashedControlPassword in our torrc.
-
- HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
-
-You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now let's write a script that tells us how many bytes Tor has sent and received...
-
-::
-
- from stem.control import Controller
-
- controller = Controller.from_port(control_port = 9051)
- controller.authenticate() # provide the password here if you set one
-
- bytes_read = controller.get_info("traffic/read")
- bytes_written = controller.get_info("traffic/written")
-
- print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
- controller.close()
+.. Image Sources:
+
+ * The Little Relay That Could - train.png
+ Source: https://openclipart.org/detail/140185/tren-train-by-antroares
+ Author: Antroares
+ License: Public Domain
+ Alternate: https://openclipart.org/detail/1128/train-roadsign-by-ryanlerch
+
+ * Mirror Mirror On The Wall - mirror.png
+ Source: https://openclipart.org/detail/152155/mirror-frame-by-gsagri04
+ Author: Unknown (gsagri04?)
+ License: Public Domain
+ Alternate: https://openclipart.org/detail/174179/miroir-rectangulaire-by-defaz36-174179
-::
-
- % python example.py
- My Tor relay has read 33406 bytes and written 29649.
-
-Congratulations! You've just written your first controller script.
-
-.. _mirror-mirror-on-the-wall:
-
-Mirror Mirror on the Wall
--------------------------
-
-A script that tells us our contributed bandwidth is neat and all, but now let's figure out who the *biggest* exit relays are.
-
-Information about the Tor relay network come from documents called **descriptors**. Descriptors can come from a few things...
-
-1. The Tor control port with GETINFO options like **desc/all-recent** and **ns/all**.
-2. Files in Tor's data directory, like **cached-descriptors** and **cached-consensus**.
-3. The descriptor archive on `Tor's metrics site <https://metrics.torproject.org/data.html>`_.
-
-We've already used the control port, so for this example we'll use the cached files directly. First locate Tor's data directory. If your torrc has a DataDirectory line then that's the spot. If not then check Tor's man page for the default location.
-
-Tor has several descriptor types. For bandwidth information we'll go to the server descriptors, which are located in the **cached-descriptors** file. These have somewhat infrequently changing information published by the relays themselves.
-
-To read this file we'll use the :class:`~stem.descriptor.reader.DescriptorReader`, a class designed to read descriptor files. The **cached-descriptors** is full of server descriptors, so the reader will provide us with :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances (a :class:`~stem.descriptor.server_descriptor.ServerDescriptor` subclass for relays).
+Getting started with any new library can be rather daunting, so let's get our feet wet by jumping straight in with a tutorial...
-::
+.. list-table::
+ :widths: 1 10
+ :header-rows: 0
- import sys
- from stem.descriptor.reader import DescriptorReader
- from stem.util import str_tools
-
- # provides a mapping of observed bandwidth to the relay nicknames
- def get_bw_to_relay():
- bw_to_relay = {}
-
- with DescriptorReader(["/home/atagar/.tor/cached-descriptors"]) as reader:
- for desc in reader:
- if desc.exit_policy.is_exiting_allowed():
- bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
-
- return bw_to_relay
-
- # prints the top fifteen relays
-
- bw_to_relay = get_bw_to_relay()
- count = 1
-
- for bw_value in sorted(bw_to_relay.keys(), reverse = True):
- for nickname in bw_to_relay[bw_value]:
- print "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2))
- count += 1
-
- if count > 15:
- sys.exit()
+ * - .. image:: /_static/section/tutorial/train.png
+ :target: tutorial/the_little_relay_that_could.html
-::
+ - .. image:: /_static/label/the_little_relay_that_could.png
+ :target: tutorial/the_little_relay_that_could.html
- % python example.py
- 1. herngaard (40.95 MB/s)
- 2. chaoscomputerclub19 (40.43 MB/s)
- 3. chaoscomputerclub18 (40.02 MB/s)
- 4. chaoscomputerclub20 (38.98 MB/s)
- 5. wannabe (38.63 MB/s)
- 6. dorrisdeebrown (38.48 MB/s)
- 7. manning2 (38.20 MB/s)
- 8. chaoscomputerclub21 (36.90 MB/s)
- 9. TorLand1 (36.22 MB/s)
- 10. bolobolo1 (35.93 MB/s)
- 11. manning1 (35.39 MB/s)
- 12. gorz (34.10 MB/s)
- 13. ndnr1 (25.36 MB/s)
- 14. politkovskaja2 (24.93 MB/s)
- 15. wau (24.72 MB/s)
+ "Hello World" for talking with Tor. This will step you through
+ configuring Tor and writing your first script to talk with it.
-This can be easily done through the controller too...
+ * - .. image:: /_static/section/tutorial/mirror.png
+ :target: tutorial/mirror_mirror_on_the_wall.html
-::
+ - .. image:: /_static/label/mirror_mirror_on_the_wall.png
+ :target: tutorial/mirror_mirror_on_the_wall.html
- def get_bw_to_relay():
- bw_to_relay = {}
-
- with Controller.from_port(control_port = 9051) as controller:
- controller.authenticate()
-
- for desc in controller.get_server_descriptors():
- if desc.exit_policy.is_exiting_allowed():
- bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
-
- return bw_to_relay
+ Getting and acting on information about relays in the Tor network. This
+ walks you through Tor descriptors, both where to get them and writing a
+ small script to tell you the fastest Tor exits.
diff --git a/docs/tutorial/mirror_mirror_on_the_wall.rst b/docs/tutorial/mirror_mirror_on_the_wall.rst
new file mode 100644
index 0000000..d9a4dd8
--- /dev/null
+++ b/docs/tutorial/mirror_mirror_on_the_wall.rst
@@ -0,0 +1,83 @@
+Mirror Mirror on the Wall
+-------------------------
+
+A script that tells us our contributed bandwidth is neat and all, but now let's figure out who the *biggest* exit relays are.
+
+Information about the Tor relay network come from documents called **descriptors**. Descriptors can come from a few things...
+
+1. The Tor control port with GETINFO options like **desc/all-recent** and **ns/all**.
+2. Files in Tor's data directory, like **cached-descriptors** and **cached-consensus**.
+3. The descriptor archive on `Tor's metrics site <https://metrics.torproject.org/data.html>`_.
+
+We've already used the control port, so for this example we'll use the cached files directly. First locate Tor's data directory. If your torrc has a DataDirectory line then that's the spot. If not then check Tor's man page for the default location.
+
+Tor has several descriptor types. For bandwidth information we'll go to the server descriptors, which are located in the **cached-descriptors** file. These have somewhat infrequently changing information published by the relays themselves.
+
+To read this file we'll use the :class:`~stem.descriptor.reader.DescriptorReader`, a class designed to read descriptor files. The **cached-descriptors** is full of server descriptors, so the reader will provide us with :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances (a :class:`~stem.descriptor.server_descriptor.ServerDescriptor` subclass for relays).
+
+::
+
+ import sys
+ from stem.descriptor.reader import DescriptorReader
+ from stem.util import str_tools
+
+ # provides a mapping of observed bandwidth to the relay nicknames
+ def get_bw_to_relay():
+ bw_to_relay = {}
+
+ with DescriptorReader(["/home/atagar/.tor/cached-descriptors"]) as reader:
+ for desc in reader:
+ if desc.exit_policy.is_exiting_allowed():
+ bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
+
+ return bw_to_relay
+
+ # prints the top fifteen relays
+
+ bw_to_relay = get_bw_to_relay()
+ count = 1
+
+ for bw_value in sorted(bw_to_relay.keys(), reverse = True):
+ for nickname in bw_to_relay[bw_value]:
+ print "%i. %s (%s/s)" % (count, nickname, str_tools.get_size_label(bw_value, 2))
+ count += 1
+
+ if count > 15:
+ sys.exit()
+
+::
+
+ % python example.py
+ 1. herngaard (40.95 MB/s)
+ 2. chaoscomputerclub19 (40.43 MB/s)
+ 3. chaoscomputerclub18 (40.02 MB/s)
+ 4. chaoscomputerclub20 (38.98 MB/s)
+ 5. wannabe (38.63 MB/s)
+ 6. dorrisdeebrown (38.48 MB/s)
+ 7. manning2 (38.20 MB/s)
+ 8. chaoscomputerclub21 (36.90 MB/s)
+ 9. TorLand1 (36.22 MB/s)
+ 10. bolobolo1 (35.93 MB/s)
+ 11. manning1 (35.39 MB/s)
+ 12. gorz (34.10 MB/s)
+ 13. ndnr1 (25.36 MB/s)
+ 14. politkovskaja2 (24.93 MB/s)
+ 15. wau (24.72 MB/s)
+
+This can be easily done through the controller too...
+
+::
+
+ def get_bw_to_relay():
+ bw_to_relay = {}
+
+ with Controller.from_port(control_port = 9051) as controller:
+ controller.authenticate()
+
+ for desc in controller.get_server_descriptors():
+ if desc.exit_policy.is_exiting_allowed():
+ bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
+
+ return bw_to_relay
+
+
diff --git a/docs/tutorial/the_little_relay_that_could.rst b/docs/tutorial/the_little_relay_that_could.rst
new file mode 100644
index 0000000..e3f7675
--- /dev/null
+++ b/docs/tutorial/the_little_relay_that_could.rst
@@ -0,0 +1,56 @@
+The Little Relay that Could
+---------------------------
+
+Let's say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
+
+First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
+
+Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
+
+::
+
+ # This provides a port for the script we write to talk to. If you set this
+ # then be sure to also have either set the CookieAuthentication flag *or*
+ # provide a HashedControlPassword!
+
+ ControlPort 9051
+
+ # This will make Tor write an authentication cookie file. Anything that can
+ # read that file can connect to Tor. If you're going to run this script with
+ # the same user as Tor then this is the easiest method of authentication to
+ # use.
+
+ CookieAuthentication 1
+
+ # Alternatively we can authenticate with a password. To set a password first
+ # get its hash...
+ #
+ # % tor --hash-password "my_password"
+ # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
+ #
+ # ... and use that for the HashedControlPassword in our torrc.
+
+ HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
+
+You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now let's write a script that tells us how many bytes Tor has sent and received...
+
+::
+
+ from stem.control import Controller
+
+ controller = Controller.from_port(control_port = 9051)
+ controller.authenticate() # provide the password here if you set one
+
+ bytes_read = controller.get_info("traffic/read")
+ bytes_written = controller.get_info("traffic/written")
+
+ print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
+ controller.close()
+
+::
+
+ % python example.py
+ My Tor relay has read 33406 bytes and written 29649.
+
+Congratulations! You've just written your first controller script.
+
More information about the tor-commits
mailing list