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