March 2013 - tor-commits - lists.torproject.org

[translation/tsum] Update translations for tsum
by translation＠torproject.org 14 Mar '13

14 Mar '13

commit 30023864425d2ff8e5418b5fca051f6fa2da8024 Author: Translation commit bot <translation(a)torproject.org> Date: Thu Mar 14 08:45:32 2013 +0000 Update translations for tsum --- sr/short-user-manual_sr_noimg.xhtml | 18 +++++++++--------- 1 files changed, 9 insertions(+), 9 deletions(-) diff --git a/sr/short-user-manual_sr_noimg.xhtml b/sr/short-user-manual_sr_noimg.xhtml index f97461f..742674e 100644 --- a/sr/short-user-manual_sr_noimg.xhtml +++ b/sr/short-user-manual_sr_noimg.xhtml @@ -5,15 +5,15 @@ </head> <body> <h1 id="the-short-user-manual">Kratki korisnicki prirucnik</h1> - <p>This user manual contains information about how to download Tor, how to use it, and what to do if Tor is unable to connect to the network. If you can't find the answer to your question in this document, email help(a)rt.torproject.org.</p> - <p>Please note that we are providing support on a voluntary basis, and we get a lot of emails every single day. There is no need to worry if we don't get back to you straight away.</p> - <h2 id="how-tor-works">How Tor works</h2> - <p>Tor is a network of virtual tunnels that allows you to improve your privacy and security on the Internet. Tor works by sending your traffic through three random servers (also known as <em>relays</em>) in the Tor network, before the traffic is sent out onto the public Internet.</p> - <p>The image above illustrates a user browsing to different websites over Tor. The green monitors represent relays in the Tor network, while the three keys represent the layers of encryption between the user and each relay.</p> - <p>Tor will anonymize the origin of your traffic, and it will encrypt everything between you and the Tor network. Tor will also encrypt your traffic inside the Tor network, but it cannot encrypt your traffic between the Tor network and its final destination.</p> - <p>If you are communicating sensitive information, for example when logging on to a website with a username and password, make sure that you are using HTTPS (e.g. <strong>https</strong>://torproject.org/, not <strong>http</strong>://torproject.org/).</p> - <h2 id="how-to-download-tor">How to download Tor</h2> - <p>The bundle we recommend to most users is the <a href="https://www.torproject.org/projects/torbrowser.html">Tor Browser Bundle</a>. This bundle contains a browser preconfigured to safely browse the Internet through Tor, and requires no installation. You download the bundle, extract the archive, and start Tor.</p> + <p>Ovaj korisnicki prirucnik sadrzi imformacije o tome kako da preuzmete i koristite Tor i sta da radite ako Tor ne moze da se poveze na mrezu. Ako ne mozete naci odgovor na vasa pitanja u ovom dokumentu, posaljite email na help(a)rt.torproject.org.</p> + <p>Molimo vas da imate u vidu da mi pruzamo podrsku na dobrovoljnoj osnovi i da mi dobijamo dosta mejlova svaki dan. Nema potrebe da se brinete ako vam ne odgovorimo odmah. </p> + <h2 id="how-tor-works">Kako Tor funkcionise</h2> + <p>Tor je mreza virtualnih tunela koja vam omogucava da poboljsate vasu privatnost i bezbednost na Internetu. Tor funkcionise tako sto salje vas internet zahtev kroz tri nasumice izabrana servera (poznati kao <em>releji</em>) iz Tor mreze, pre nego sto je poslat na javni Internet.</p> + <p>Prikaz iznad ilustruje korisnika koji pregleda razlicite stranice koristeci Tor. Zeleni monitori predstavljau releje u Tor mrezi, dok tri kljuca predstavljaju sloj sifrovanja izmedju korisnika i releja.</p> + <p>Tor ce napraviti poreklo vaseg zahteva anonimnim i sifrovati sve izmedju vas i Tor mreze. Tor takodjer sifruje vase zahteve unutar Tor mreze, ali ne moze sifrovati vas zahtev izmedju Tor mreze i njegovog konacnog odredista.</p> + <p>Ako unosite osetljive informacije, kao na primer korisnicko ime i loziku, proverite da koristite HTTPS (e.g. <strong>https</strong>://torproject.org/, a ne <strong>http</strong>://torproject.org/).</p> + <h2 id="how-to-download-tor">Kako preuzeti Tor</h2> + <p>Paket mi preporucujemo vecini korisnika je <a href="https://www.torproject.org/projects/torbrowser.html">Tor Browser Bundle</a>. Ovaj paket sadrzi prekonfigurisan pretrazivac da bezbedno pretrazujete internet koristeci Tor, i ne zahteva instalaciju.</p> <p>There are two different ways to get hold of the Tor software. You can either browse to the <a href="https://www.torproject.org/">Tor Project website</a> and download it there, or you can use GetTor, the email autoresponder.</p> <h3 id="how-to-get-tor-via-email">How to get Tor via email</h3> <p>To receive the English Tor Browser Bundle for Windows, send an email to gettor(a)torproject.org with <strong>windows</strong> in the body of the message. You can leave the subject blank.</p>

1 0

[stem/master] Dropping the V3Dir flag
by atagar＠torproject.org 13 Mar '13

13 Mar '13

commit 8474971d99da327169e5827db660f8f1f91bbd59 Author: Damian Johnson <atagar(a)torproject.org> Date: Wed Mar 13 09:38:19 2013 -0700 Dropping the V3Dir flag Nick just pushed a change noting that the V3Dir flag has never existed, so updating our enum too. https://gitweb.torproject.org/torspec.git/commitdiff/67768b16c247f937a4345a… --- stem/__init__.py | 1 - 1 files changed, 0 insertions(+), 1 deletions(-) diff --git a/stem/__init__.py b/stem/__init__.py index f1335ac..3fee276 100644 --- a/stem/__init__.py +++ b/stem/__init__.py @@ -69,7 +69,6 @@ Library for working with the tor process. **STABLE** relay's suitable for long-lived circuits **UNNAMED** relay isn't presently bound to a nickname **V2DIR** relay supports the v2 directory protocol - **V3DIR** relay supports the v3 directory protocol **VALID** relay has been validated ================= ===========

1 0

[stem/master] 'Tortoise and the Hare' tutorial
by atagar＠torproject.org 13 Mar '13

13 Mar '13

commit c1abfa73fc24528713be233347cbd0f8796c537e Author: Damian Johnson <atagar(a)torproject.org> Date: Wed Mar 13 09:09:54 2013 -0700 'Tortoise and the Hare' tutorial Adding a tutorial for event listening. This has the most substantial example yet, making a curses graph for tor's bandwidth usage. --- docs/_static/bandwidth_graph_output.png | Bin 0 -> 8702 bytes .../label/resources/tortoise_and_the_hare.xcf | Bin 0 -> 8081 bytes docs/_static/label/tortoise_and_the_hare.png | Bin 0 -> 3750 bytes docs/_static/section/tutorial/tortoise.png | Bin 0 -> 14700 bytes docs/tutorial/tortoise_and_the_hare.rst | 204 ++++++++++++++++++++ docs/tutorials.rst | 19 ++- 6 files changed, 221 insertions(+), 2 deletions(-) diff --git a/docs/_static/bandwidth_graph_output.png b/docs/_static/bandwidth_graph_output.png new file mode 100644 index 0000000..9fa31e6 Binary files /dev/null and b/docs/_static/bandwidth_graph_output.png differ diff --git a/docs/_static/label/resources/tortoise_and_the_hare.xcf b/docs/_static/label/resources/tortoise_and_the_hare.xcf new file mode 100644 index 0000000..4a97fc0 Binary files /dev/null and b/docs/_static/label/resources/tortoise_and_the_hare.xcf differ diff --git a/docs/_static/label/tortoise_and_the_hare.png b/docs/_static/label/tortoise_and_the_hare.png new file mode 100644 index 0000000..e215db1 Binary files /dev/null and b/docs/_static/label/tortoise_and_the_hare.png differ diff --git a/docs/_static/section/tutorial/tortoise.png b/docs/_static/section/tutorial/tortoise.png new file mode 100644 index 0000000..52b5da0 Binary files /dev/null and b/docs/_static/section/tutorial/tortoise.png differ diff --git a/docs/tutorial/tortoise_and_the_hare.rst b/docs/tutorial/tortoise_and_the_hare.rst new file mode 100644 index 0000000..f575853 --- /dev/null +++ b/docs/tutorial/tortoise_and_the_hare.rst @@ -0,0 +1,204 @@ +Tortoise and the Hare +===================== + +Controllers have two methods of talking with Tor... + +* **Synchronous** - Most commonly you make a request to Tor then receive its + reply. The :func:`~stem.control.Controller.get_info` calls in the `first + tutorial <the_little_relay_that_could.html>`_ are an example of this. + +* **Asynchronous** - Controllers can subscribe to be notified when various + kinds of events occur within Tor (see the :data:`~stem.control.EventType`). + Stem's users provide a callback function to + :func:`~stem.control.Controller.add_event_listener` which is then notified + when the event occurs. + +Try to avoid lengthy operations within event callbacks. They're notified by a +single dedicated event thread, and blocking this thread will prevent the +delivery of further events. + +With that out of the way lets see an example. The following is a `curses +<http://docs.python.org/2/howto/curses.html>`_ application that graphs the +bandwidth usage of Tor... + +.. image:: /_static/bandwidth_graph_output.png + +To do this it listens to **BW events** +(the class for which is a :class:`~stem.response.events.BandwidthEvent`). These +are events that Tor emits each second saying the number of bytes downloaded and +uploaded. + +:: + + import curses + import functools + + from stem.control import EventType, Controller + from stem.util import str_tools + + # colors that curses can handle + + COLOR_LIST = { + "red": curses.COLOR_RED, + "green": curses.COLOR_GREEN, + "yellow": curses.COLOR_YELLOW, + "blue": curses.COLOR_BLUE, + "cyan": curses.COLOR_CYAN, + "magenta": curses.COLOR_MAGENTA, + "black": curses.COLOR_BLACK, + "white": curses.COLOR_WHITE, + } + + GRAPH_WIDTH = 40 + GRAPH_HEIGHT = 8 + + DOWNLOAD_COLOR = "green" + UPLOAD_COLOR = "blue" + + def main(): + with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + try: + curses.wrapper(drawBandwidthGraph, controller) + except KeyboardInterrupt: + pass # the user hit ctrl+c + + def drawBandwidthGraph(stdscr, controller): + window = Window(stdscr) + + # (downloaded, uploaded) tuples for the last 40 seconds + + bandwidth_rates = [(0, 0)] * GRAPH_WIDTH + + # Making a partial that wraps the window and bandwidth_rates with a function + # for Tor to call when it gets a BW event. + + bw_event_handler = functools.partial(_handle_bandwidth_event, window, bandwidth_rates) + + # Registering this listener with Tor. Tor reports a BW event each second. + + controller.add_event_listener(bw_event_handler, EventType.BW) + + # Pause the main thread until the user hits any key... and no, don't you dare + # ask where the 'any' key is. :P + + stdscr.getch() + + def _handle_bandwidth_event(window, bandwidth_rates, event): + # callback for when tor provides us with a BW event + + bandwidth_rates.insert(0, (event.read, event.written)) + bandwidth_rates = bandwidth_rates[:GRAPH_WIDTH] # truncate old values + _render_graph(window, bandwidth_rates) + + def _render_graph(window, bandwidth_rates): + window.erase() + + download_rates = [entry[0] for entry in bandwidth_rates] + upload_rates = [entry[1] for entry in bandwidth_rates] + + # show the latest values at the top + + label = "Downloaded (%s/s):" % str_tools.get_size_label(download_rates[0], 1) + window.addstr(0, 1, label, DOWNLOAD_COLOR, curses.A_BOLD) + + label = "Uploaded (%s/s):" % str_tools.get_size_label(upload_rates[0], 1) + window.addstr(0, GRAPH_WIDTH + 7, label, UPLOAD_COLOR, curses.A_BOLD) + + # draw the graph bounds in KB + + max_download_rate = max(download_rates) + max_upload_rate = max(upload_rates) + + window.addstr(1, 1, "%4i" % (max_download_rate / 1024), DOWNLOAD_COLOR) + window.addstr(GRAPH_HEIGHT, 1, " 0", DOWNLOAD_COLOR) + + window.addstr(1, GRAPH_WIDTH + 7, "%4i" % (max_upload_rate / 1024), UPLOAD_COLOR) + window.addstr(GRAPH_HEIGHT, GRAPH_WIDTH + 7, " 0", UPLOAD_COLOR) + + # draw the graph + + for col in xrange(GRAPH_WIDTH): + col_height = GRAPH_HEIGHT * download_rates[col] / max(max_download_rate, 1) + + for row in xrange(col_height): + window.addstr(GRAPH_HEIGHT - row, col + 6, " ", DOWNLOAD_COLOR, curses.A_STANDOUT) + + col_height = GRAPH_HEIGHT * upload_rates[col] / max(max_upload_rate, 1) + + for row in xrange(col_height): + window.addstr(GRAPH_HEIGHT - row, col + GRAPH_WIDTH + 12, " ", UPLOAD_COLOR, curses.A_STANDOUT) + + window.refresh() + + class Window(object): + """ + Simple wrapper for the curses standard screen object. + """ + + def __init__(self, stdscr): + self._stdscr = stdscr + + # Mappings of names to the curses color attribute. Initially these all + # reference black text, but if the terminal can handle color then + # they're set with that foreground color. + + self._colors = dict([(color, 0) for color in COLOR_LIST]) + + # allows for background transparency + + try: + curses.use_default_colors() + except curses.error: + pass + + # makes the cursor invisible + + try: + curses.curs_set(0) + except curses.error: + pass + + # initializes colors if the terminal can handle them + + try: + if curses.has_colors(): + color_pair = 1 + + for name, foreground in COLOR_LIST.items(): + background = -1 # allows for default (possibly transparent) background + curses.init_pair(color_pair, foreground, background) + self._colors[name] = curses.color_pair(color_pair) + color_pair += 1 + except curses.error: + pass + + def addstr(self, y, x, msg, color = None, attr = curses.A_NORMAL): + # Curses throws an error if we try to draw a message that spans out of the + # window's bounds (... seriously?), so doing our best to avoid that. + + if color is not None: + if color not in self._colors: + recognized_colors = ", ".join(self._colors.keys()) + raise ValueError("The '%s' color isn't recognized: %s" % (color, recognized_colors)) + + attr |= self._colors[color] + + max_y, max_x = self._stdscr.getmaxyx() + + if max_x > x and max_y > y: + try: + self._stdscr.addstr(y, x, msg[:max_x - x], attr) + except: + pass # maybe an edge case while resizing the window + + def erase(self): + self._stdscr.erase() + + def refresh(self): + self._stdscr.refresh() + + if __name__ == '__main__': + main() + diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 28ea3d5..646af20 100644 --- a/docs/tutorials.rst +++ b/docs/tutorials.rst @@ -1,5 +1,5 @@ -Tutorials -========= +Tutorial +======== .. Image Sources: @@ -15,6 +15,11 @@ Tutorials License: Public Domain (not a subject of copyright according the Russian civil code) Alternate: https://openclipart.org/detail/85555/communist-sabbatarian-ribbon-by-rones-… + * Tortoise and the Hare - tortoise.png + Source: https://openclipart.org/detail/27911/green-tortoise-%28cartoon%29-by-arking… + Author: arking + License: Public Domain + * Mirror Mirror On The Wall - mirror.png Source: https://openclipart.org/detail/152155/mirror-frame-by-gsagri04 Author: Unknown (gsagri04?) @@ -52,6 +57,16 @@ feet wet by jumping straight in with some tutorials... tutorial we'll programmatically start Tor then use it to read a site through mother Russia! + * - .. image:: /_static/section/tutorial/tortoise.png + :target: tutorial/tortoise_and_the_hare.html + + - .. image:: /_static/label/tortoise_and_the_hare.png + :target: tutorial/tortoise_and_the_hare.html + + As Tor runs it generates a variety of **events** that controllers can + subscribe to be notified of. In this tutorial we'll do just that, + writing a curses application that graphs the bandwidth usage of Tor. + * - .. image:: /_static/section/tutorial/mirror.png :target: tutorial/mirror_mirror_on_the_wall.html

1 0

[stem/master] More uniformly renaming to 'tutorials'
by atagar＠torproject.org 13 Mar '13

13 Mar '13

commit 89e8fb8f37ebaad8d2009fedba766d1d42831dd8 Author: Damian Johnson <atagar(a)torproject.org> Date: Wed Mar 13 09:14:33 2013 -0700 More uniformly renaming to 'tutorials' Several of our resources, including individual tutorial pages, were still under 'tutorial'. I'm also dropping the old 'tutorial.rst' (I'm not getting any replies to the tor-dev@ email and having a stale copy is confusing). --- docs/_static/section/tutorial/cauldron.png | Bin 9943 -> 0 bytes docs/_static/section/tutorial/mirror.png | Bin 2985 -> 0 bytes docs/_static/section/tutorial/soviet.png | Bin 4679 -> 0 bytes docs/_static/section/tutorial/tortoise.png | Bin 14700 -> 0 bytes docs/_static/section/tutorial/train.png | Bin 9887 -> 0 bytes docs/_static/section/tutorials/cauldron.png | Bin 0 -> 9943 bytes docs/_static/section/tutorials/mirror.png | Bin 0 -> 2985 bytes docs/_static/section/tutorials/soviet.png | Bin 0 -> 4679 bytes docs/_static/section/tutorials/tortoise.png | Bin 0 -> 14700 bytes docs/_static/section/tutorials/train.png | Bin 0 -> 9887 bytes docs/contents.rst | 11 +- docs/tutorial.rst | 74 -------- docs/tutorial/double_double_toil_and_trouble.rst | 26 --- docs/tutorial/mirror_mirror_on_the_wall.rst | 178 ------------------ docs/tutorial/the_little_relay_that_could.rst | 65 ------- docs/tutorial/to_russia_with_love.rst | 70 ------- docs/tutorial/tortoise_and_the_hare.rst | 204 --------------------- docs/tutorials.rst | 30 ++-- docs/tutorials/double_double_toil_and_trouble.rst | 26 +++ docs/tutorials/mirror_mirror_on_the_wall.rst | 178 ++++++++++++++++++ docs/tutorials/the_little_relay_that_could.rst | 65 +++++++ docs/tutorials/to_russia_with_love.rst | 70 +++++++ docs/tutorials/tortoise_and_the_hare.rst | 204 +++++++++++++++++++++ 23 files changed, 564 insertions(+), 637 deletions(-) diff --git a/docs/_static/section/tutorial/cauldron.png b/docs/_static/section/tutorial/cauldron.png deleted file mode 100644 index 74d32bf..0000000 Binary files a/docs/_static/section/tutorial/cauldron.png and /dev/null differ diff --git a/docs/_static/section/tutorial/mirror.png b/docs/_static/section/tutorial/mirror.png deleted file mode 100644 index 69c2938..0000000 Binary files a/docs/_static/section/tutorial/mirror.png and /dev/null differ diff --git a/docs/_static/section/tutorial/soviet.png b/docs/_static/section/tutorial/soviet.png deleted file mode 100644 index c54c3d8..0000000 Binary files a/docs/_static/section/tutorial/soviet.png and /dev/null differ diff --git a/docs/_static/section/tutorial/tortoise.png b/docs/_static/section/tutorial/tortoise.png deleted file mode 100644 index 52b5da0..0000000 Binary files a/docs/_static/section/tutorial/tortoise.png and /dev/null differ diff --git a/docs/_static/section/tutorial/train.png b/docs/_static/section/tutorial/train.png deleted file mode 100644 index 625b82e..0000000 Binary files a/docs/_static/section/tutorial/train.png and /dev/null differ diff --git a/docs/_static/section/tutorials/cauldron.png b/docs/_static/section/tutorials/cauldron.png new file mode 100644 index 0000000..74d32bf Binary files /dev/null and b/docs/_static/section/tutorials/cauldron.png differ diff --git a/docs/_static/section/tutorials/mirror.png b/docs/_static/section/tutorials/mirror.png new file mode 100644 index 0000000..69c2938 Binary files /dev/null and b/docs/_static/section/tutorials/mirror.png differ diff --git a/docs/_static/section/tutorials/soviet.png b/docs/_static/section/tutorials/soviet.png new file mode 100644 index 0000000..c54c3d8 Binary files /dev/null and b/docs/_static/section/tutorials/soviet.png differ diff --git a/docs/_static/section/tutorials/tortoise.png b/docs/_static/section/tutorials/tortoise.png new file mode 100644 index 0000000..52b5da0 Binary files /dev/null and b/docs/_static/section/tutorials/tortoise.png differ diff --git a/docs/_static/section/tutorials/train.png b/docs/_static/section/tutorials/train.png new file mode 100644 index 0000000..625b82e Binary files /dev/null and b/docs/_static/section/tutorials/train.png differ diff --git a/docs/contents.rst b/docs/contents.rst index 5826ad7..e25578a 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -4,11 +4,12 @@ Contents .. toctree:: :maxdepth: 2 - tutorial - tutorial/the_little_relay_that_could - tutorial/to_russia_with_love - tutorial/mirror_mirror_on_the_wall - tutorial/double_double_toil_and_trouble + tutorials + tutorials/the_little_relay_that_could + tutorials/to_russia_with_love + tutorials/tortoise_and_the_hare + tutorials/mirror_mirror_on_the_wall + tutorials/double_double_toil_and_trouble download diff --git a/docs/tutorial.rst b/docs/tutorial.rst deleted file mode 100644 index 7143892..0000000 --- a/docs/tutorial.rst +++ /dev/null @@ -1,74 +0,0 @@ -Tutorial -======== - -.. 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 - - * To Russia With Love - soviet.png - Source: https://openclipart.org/detail/146017/flag-of-the-soviet-union-by-marxist-l… - Author: Unknown - License: Public Domain (not a subject of copyright according the Russian civil code) - Alternate: https://openclipart.org/detail/85555/communist-sabbatarian-ribbon-by-rones-… - - * 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 - - * Double Double Toil and Trouble - cauldron.png - Source: https://openclipart.org/detail/174099/cauldron-by-jarda-174099 - Author: Unknown (jarda?) - License: Public Domain - -Getting started with any new library can be rather daunting, so let's get our -feet wet by jumping straight in with some tutorials... - -.. list-table:: - :widths: 1 10 - :header-rows: 0 - - * - .. 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 - - Basics for talking with Tor. This will step you through configuring Tor - and writing your first script to talk with it. - - * - .. image:: /_static/section/tutorial/soviet.png - :target: tutorial/to_russia_with_love.html - - - .. image:: /_static/label/to_russia_with_love.png - :target: tutorial/to_russia_with_love.html - - Rather than talking to Tor, we'll now talk **through** it. In this - tutorial we'll programmatically start Tor then use it to read a site - through mother Russia! - - * - .. 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 - - Getting and acting upon information about relays in the Tor network. - Relay information is provided through documents called **descriptors**. - This walks you through both where to get them and a small script to tell - you the fastest Tor exits. - - * - .. image:: /_static/section/tutorial/cauldron.png - :target: tutorial/double_double_toil_and_trouble.html - - - .. image:: /_static/label/double_double_toil_and_trouble.png - :target: tutorial/double_double_toil_and_trouble.html - - Sometimes it's easiest to learn a library by seeing how it's used in the - wild. This is a directory of scripts and applications that use stem. - diff --git a/docs/tutorial/double_double_toil_and_trouble.rst b/docs/tutorial/double_double_toil_and_trouble.rst deleted file mode 100644 index 129a302..0000000 --- a/docs/tutorial/double_double_toil_and_trouble.rst +++ /dev/null @@ -1,26 +0,0 @@ -Double Double Toil and Trouble -============================== - -Below is a listing of scripts and applications that use stem. If you have -something you would like to have included on this page then `let me know -<http://www.atagar.com/contact/>`_! - -.. list-table:: - :widths: 1 10 - :header-rows: 0 - - * - .. image:: /_static/arm.png - :target: http://www.atagar.com/arm/ - - - .. image:: /_static/label/arm.png - :target: http://www.atagar.com/arm/ - - Terminal status monitor for Tor. This provides a top like interface - including system resource usage, connection information, and much more. - -=========================================================================================================== ========== -`Consensus Tracker <https://gitweb.torproject.org/atagar/tor-utils.git/blob/HEAD:/consensusTrac…>`_ Script that performs an hourly check for the number of relays within the Tor network, looking for large jumps that may indicate a sybil attack. -`Metrics Tasks <https://gitweb.torproject.org/metrics-tasks.git/tree>`_ One-off tasks related to Tor metrics. These mostly involve using descriptor information to answer a particular question. Tasks that involve stem are: `1854 <https://gitweb.torproject.org/metrics-tasks.git/blob/HEAD:/task-1854/pylinf…>`_, `6232 <https://gitweb.torproject.org/metrics-tasks.git/blob/HEAD:/task-6232/pyentr…>`_, and `7241 <https://gitweb.torproject.org/metrics-tasks.git/blob/HEAD:/task-7241/first_…>`_. -`check_tor <http://anonscm.debian.org/gitweb/?p=users/lunar/check_tor.git;a=blob;f=chec…>`_ Nagios check to verify that a relay is participating in the Tor network. -=========================================================================================================== ========== - diff --git a/docs/tutorial/mirror_mirror_on_the_wall.rst b/docs/tutorial/mirror_mirror_on_the_wall.rst deleted file mode 100644 index 1a7f81d..0000000 --- a/docs/tutorial/mirror_mirror_on_the_wall.rst +++ /dev/null @@ -1,178 +0,0 @@ -Mirror Mirror on the Wall -========================= - -* :ref:`what-is-a-descriptor` -* :ref:`where-can-i-get-the-current-descriptors` -* :ref:`where-can-i-get-past-descriptors` -* :ref:`putting-it-together` - -.. _what-is-a-descriptor: - -What is a descriptor? ---------------------- - -Tor is made up of two parts: the application and a distributed network of a few -thousand volunteer relays. Information about these relays is public, and made -up of documents called **descriptors**. - -There are several different kinds of descriptors, the most common ones being... - -====================================================================== =========== -Descriptor Type Description -====================================================================== =========== -`Server Descriptor <../api/descriptor/server_descriptor.html>`_ Information that relays publish about themselves. Tor clients once downloaded this information, but now they use microdescriptors instead. -`ExtraInfo Descriptor <../api/descriptor/extrainfo_descriptor.html>`_ Relay information that tor clients do not need in order to function. This is self-published, like server descriptors, but not downloaded by default. -`Microdescriptor <../api/descriptor/microdescriptor.html>`_ Minimalistic document that just includes the information necessary for tor clients to work. -`Network Status Document <../api/descriptor/networkstatus.html>`_ Though tor relays are decentralized, the directories that track the overall network are not. These central points are called **directory authorities**, and every hour they publish a document called a **consensus** (aka, network status document). The consensus in turn is made up of **router status entries**. -`Router Status Entry <../api/descriptor/router_status_entry.html>`_ Relay information provided by the directory authorities including flags, heuristics used for relay selection, etc. -====================================================================== =========== - -.. _where-can-i-get-the-current-descriptors: - -Where can I get the current descriptors? ----------------------------------------- - -To work tor needs to have up-to-date information about relays within the -network. As such getting current descriptors is easy: *just run tor*. - -Tor only gets the descriptors that it needs by default, so if you're scripting -against tor you may want to set some of the following in your `torrc -<https://www.torproject.org/docs/faq.html.en#torrc>`_. Keep in mind that these -add a small burden to the network, so don't set them in a widely distributed -application. And, of course, please consider `running tor as a relay -<https://www.torproject.org/docs/tor-doc-relay.html.en>`_ so you give back to -the network! - -:: - - # Descriptors have a range of time during which they're valid. To get the - # most recent descriptor information, regardless of if tor needs it or not, - # set the following. - - FetchDirInfoExtraEarly 1 - - # If you aren't actively using tor as a client then tor will eventually stop - # downloading descriptor information that it doesn't need. To prevent this - # from happening set... - - FetchUselessDescriptors 1 - - # Tor no longer downloads server descriptors by default, opting for - # microdescriptors instead. If you want tor to download server descriptors - # then set... - - UseMicrodescriptors 0 - - # Tor doesn't need extrainfo descriptors to work. If you want tor to download - # them anyway then set... - - DownloadExtraInfo 1 - -Now that tor is happy chugging along up-to-date descriptors are available -through tor's control socket... - -:: - - from stem.control import Controller - - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - for desc in controller.get_network_statuses(): - print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) - -... or by reading directly from tor's data directory... - -:: - - from stem.descriptor import parse_file - - for desc in parse_file(open("/home/atagar/.tor/cached-consensus")): - print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) - -.. _where-can-i-get-past-descriptors: - -Where can I get past descriptors? ---------------------------------- - -Descriptor archives are available on `Tor's metrics site -<https://metrics.torproject.org/data.html>`_. These archives can be read with -the `DescriptorReader <api/descriptor/reader.html>`_... - -:: - - from stem.descriptor.reader import DescriptorReader - - with DescriptorReader(["/home/atagar/server-descriptors-2013-03.tar"]) as reader: - for desc in reader: - print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) - -.. _putting-it-together: - -Putting it together... ----------------------- - -As discussed above there are three methods for reading descriptors... - -* With the :class:`~stem.control.Controller` via methods like :func:`~stem.control.Controller.get_server_descriptors` and :func:`~stem.control.Controller.get_network_statuses`. -* By reading the file directly with :func:`~stem.descriptor.__init__.parse_file`. -* Reading with the `DescriptorReader <api/descriptor/reader.html>`_. This is best if you have you want to read everything from a directory or archive. - -Now lets say you want to figure out who the *biggest* exit relays are. You -could use any of the methods above, but for this example we'll use the -:class:`~stem.control.Controller`. This uses server descriptors, so keep in -mind that you'll likely need to set "UseMicrodescriptors 0" in your torrc for -this to work. - -:: - - import sys - - from stem.control import Controller - 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 Controller.from_port(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 - - # 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) - diff --git a/docs/tutorial/the_little_relay_that_could.rst b/docs/tutorial/the_little_relay_that_could.rst deleted file mode 100644 index 4f22b5b..0000000 --- a/docs/tutorial/the_little_relay_that_could.rst +++ /dev/null @@ -1,65 +0,0 @@ -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!), and now -you want to write a script that tells you how much it is being used. - -First, for any script to talk with your relay it will 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 our script to talk with. If you set this then be - # sure to also set either CookieAuthentication *or* HashedControlPassword! - # - # You could also use ControlSocket instead of ControlPort, which provides a - # file based socket. You don't need to have authentication if you use - # ControlSocket. For this example however we'll use a port. - - ControlPort 9051 - - # Setting this will make Tor write an authentication cookie. Anything with - # permission to read this file can connect to Tor. If you're going to run - # your script with the same user or permission group 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 your torrc. - - HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF - -When you change your torrc you'll need to either restart Tor is issue a SIGHUP -for the 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 - - with Controller.from_port(port = 9051) as controller: - 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) - -:: - - % python example.py - My Tor relay has read 33406 bytes and written 29649. - -Congratulations! You've just written your first controller script. - diff --git a/docs/tutorial/to_russia_with_love.rst b/docs/tutorial/to_russia_with_love.rst deleted file mode 100644 index 7fb7c66..0000000 --- a/docs/tutorial/to_russia_with_love.rst +++ /dev/null @@ -1,70 +0,0 @@ -To Russia With Love -=================== - -Say it's 1982, the height of the Cold War, and you're a journalist doing a piece on how the Internet looks from behind the Iron Curtain. Ignoring the minor detail that the Internet doesn't yet exist, we'll walk you through how you could do it - no passport required! - -The Internet isn't uniform. Localization, censorship, and selective service based on your IP's geographic location can make the Internet a very different place depending on where you're coming from. - -Tor relays are scattered all over the world and, as such, you can pretend to be from any place running an exit. This can be especially useful to evade pesky geolocational restrictions, such as news sites that refuse to work while you're traveling abroad. - -Tor makes `configuring your exit locale <https://www.torproject.org/docs/faq.html.en#ChooseEntryExit>`_ easy through the **ExitNodes** torrc option. Note that you don't need a control port (or even stem) to do this, though they can be useful if you later want to do something more elaborate. - -In the following example we're using stem to `start Tor <../api/process.html>`_, then reading a site through it with `PycURL <http://pycurl.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once. - -**Do not rely on the following not to leak.** Though it seems to work, DNS resolution and other edge cases might expose your real IP. If you have a suggestion for how to improve this example then please `let me know <http://www.atagar.com/contact/>`_! - -:: - - import StringIO - - import pycurl - import stem.process - - from stem.util import term - - SOCKS_PORT = 7000 - - def curl(url): - """ - Uses pycurl to fetch a site using the proxy on the SOCKS_PORT. - """ - - output = StringIO.StringIO() - - query = pycurl.Curl() - query.setopt(pycurl.URL, url) - query.setopt(pycurl.PROXY, 'localhost') - query.setopt(pycurl.PROXYPORT, SOCKS_PORT) - query.setopt(pycurl.PROXYTYPE, pycurl.PROXYTYPE_SOCKS5) - query.setopt(pycurl.WRITEFUNCTION, output.write) - - try: - query.perform() - return output.getvalue() - except pycurl.error, exc: - return "Unable to reach %s (%s)" % (url, exc) - - # Start an instance of tor configured to only exit through Russia. This prints - # tor's bootstrap information as it starts. - - def print_bootstrap_lines(line): - if "Bootstrapped " in line: - print term.format(line, term.Color.BLUE) - - print term.format("Starting Tor:\n", term.Attr.BOLD) - - tor_process = stem.process.launch_tor_with_config( - config = { - 'SocksPort': str(SOCKS_PORT), - 'ExitNodes': '{ru}', - }, - init_msg_handler = print_bootstrap_lines, - ) - - print term.format("\nChecking our endpoint:\n", term.Attr.BOLD) - print term.format(curl("http://www.atagar.com/echo.php"), term.Color.BLUE) - - tor_process.kill() # stops tor - -.. image:: /_static/locale_selection_output.png - diff --git a/docs/tutorial/tortoise_and_the_hare.rst b/docs/tutorial/tortoise_and_the_hare.rst deleted file mode 100644 index f575853..0000000 --- a/docs/tutorial/tortoise_and_the_hare.rst +++ /dev/null @@ -1,204 +0,0 @@ -Tortoise and the Hare -===================== - -Controllers have two methods of talking with Tor... - -* **Synchronous** - Most commonly you make a request to Tor then receive its - reply. The :func:`~stem.control.Controller.get_info` calls in the `first - tutorial <the_little_relay_that_could.html>`_ are an example of this. - -* **Asynchronous** - Controllers can subscribe to be notified when various - kinds of events occur within Tor (see the :data:`~stem.control.EventType`). - Stem's users provide a callback function to - :func:`~stem.control.Controller.add_event_listener` which is then notified - when the event occurs. - -Try to avoid lengthy operations within event callbacks. They're notified by a -single dedicated event thread, and blocking this thread will prevent the -delivery of further events. - -With that out of the way lets see an example. The following is a `curses -<http://docs.python.org/2/howto/curses.html>`_ application that graphs the -bandwidth usage of Tor... - -.. image:: /_static/bandwidth_graph_output.png - -To do this it listens to **BW events** -(the class for which is a :class:`~stem.response.events.BandwidthEvent`). These -are events that Tor emits each second saying the number of bytes downloaded and -uploaded. - -:: - - import curses - import functools - - from stem.control import EventType, Controller - from stem.util import str_tools - - # colors that curses can handle - - COLOR_LIST = { - "red": curses.COLOR_RED, - "green": curses.COLOR_GREEN, - "yellow": curses.COLOR_YELLOW, - "blue": curses.COLOR_BLUE, - "cyan": curses.COLOR_CYAN, - "magenta": curses.COLOR_MAGENTA, - "black": curses.COLOR_BLACK, - "white": curses.COLOR_WHITE, - } - - GRAPH_WIDTH = 40 - GRAPH_HEIGHT = 8 - - DOWNLOAD_COLOR = "green" - UPLOAD_COLOR = "blue" - - def main(): - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - try: - curses.wrapper(drawBandwidthGraph, controller) - except KeyboardInterrupt: - pass # the user hit ctrl+c - - def drawBandwidthGraph(stdscr, controller): - window = Window(stdscr) - - # (downloaded, uploaded) tuples for the last 40 seconds - - bandwidth_rates = [(0, 0)] * GRAPH_WIDTH - - # Making a partial that wraps the window and bandwidth_rates with a function - # for Tor to call when it gets a BW event. - - bw_event_handler = functools.partial(_handle_bandwidth_event, window, bandwidth_rates) - - # Registering this listener with Tor. Tor reports a BW event each second. - - controller.add_event_listener(bw_event_handler, EventType.BW) - - # Pause the main thread until the user hits any key... and no, don't you dare - # ask where the 'any' key is. :P - - stdscr.getch() - - def _handle_bandwidth_event(window, bandwidth_rates, event): - # callback for when tor provides us with a BW event - - bandwidth_rates.insert(0, (event.read, event.written)) - bandwidth_rates = bandwidth_rates[:GRAPH_WIDTH] # truncate old values - _render_graph(window, bandwidth_rates) - - def _render_graph(window, bandwidth_rates): - window.erase() - - download_rates = [entry[0] for entry in bandwidth_rates] - upload_rates = [entry[1] for entry in bandwidth_rates] - - # show the latest values at the top - - label = "Downloaded (%s/s):" % str_tools.get_size_label(download_rates[0], 1) - window.addstr(0, 1, label, DOWNLOAD_COLOR, curses.A_BOLD) - - label = "Uploaded (%s/s):" % str_tools.get_size_label(upload_rates[0], 1) - window.addstr(0, GRAPH_WIDTH + 7, label, UPLOAD_COLOR, curses.A_BOLD) - - # draw the graph bounds in KB - - max_download_rate = max(download_rates) - max_upload_rate = max(upload_rates) - - window.addstr(1, 1, "%4i" % (max_download_rate / 1024), DOWNLOAD_COLOR) - window.addstr(GRAPH_HEIGHT, 1, " 0", DOWNLOAD_COLOR) - - window.addstr(1, GRAPH_WIDTH + 7, "%4i" % (max_upload_rate / 1024), UPLOAD_COLOR) - window.addstr(GRAPH_HEIGHT, GRAPH_WIDTH + 7, " 0", UPLOAD_COLOR) - - # draw the graph - - for col in xrange(GRAPH_WIDTH): - col_height = GRAPH_HEIGHT * download_rates[col] / max(max_download_rate, 1) - - for row in xrange(col_height): - window.addstr(GRAPH_HEIGHT - row, col + 6, " ", DOWNLOAD_COLOR, curses.A_STANDOUT) - - col_height = GRAPH_HEIGHT * upload_rates[col] / max(max_upload_rate, 1) - - for row in xrange(col_height): - window.addstr(GRAPH_HEIGHT - row, col + GRAPH_WIDTH + 12, " ", UPLOAD_COLOR, curses.A_STANDOUT) - - window.refresh() - - class Window(object): - """ - Simple wrapper for the curses standard screen object. - """ - - def __init__(self, stdscr): - self._stdscr = stdscr - - # Mappings of names to the curses color attribute. Initially these all - # reference black text, but if the terminal can handle color then - # they're set with that foreground color. - - self._colors = dict([(color, 0) for color in COLOR_LIST]) - - # allows for background transparency - - try: - curses.use_default_colors() - except curses.error: - pass - - # makes the cursor invisible - - try: - curses.curs_set(0) - except curses.error: - pass - - # initializes colors if the terminal can handle them - - try: - if curses.has_colors(): - color_pair = 1 - - for name, foreground in COLOR_LIST.items(): - background = -1 # allows for default (possibly transparent) background - curses.init_pair(color_pair, foreground, background) - self._colors[name] = curses.color_pair(color_pair) - color_pair += 1 - except curses.error: - pass - - def addstr(self, y, x, msg, color = None, attr = curses.A_NORMAL): - # Curses throws an error if we try to draw a message that spans out of the - # window's bounds (... seriously?), so doing our best to avoid that. - - if color is not None: - if color not in self._colors: - recognized_colors = ", ".join(self._colors.keys()) - raise ValueError("The '%s' color isn't recognized: %s" % (color, recognized_colors)) - - attr |= self._colors[color] - - max_y, max_x = self._stdscr.getmaxyx() - - if max_x > x and max_y > y: - try: - self._stdscr.addstr(y, x, msg[:max_x - x], attr) - except: - pass # maybe an edge case while resizing the window - - def erase(self): - self._stdscr.erase() - - def refresh(self): - self._stdscr.refresh() - - if __name__ == '__main__': - main() - diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 646af20..8153181 100644 --- a/docs/tutorials.rst +++ b/docs/tutorials.rst @@ -38,51 +38,51 @@ feet wet by jumping straight in with some tutorials... :widths: 1 10 :header-rows: 0 - * - .. image:: /_static/section/tutorial/train.png - :target: tutorial/the_little_relay_that_could.html + * - .. image:: /_static/section/tutorials/train.png + :target: tutorials/the_little_relay_that_could.html - .. image:: /_static/label/the_little_relay_that_could.png - :target: tutorial/the_little_relay_that_could.html + :target: tutorials/the_little_relay_that_could.html Basics for talking with Tor. This will step you through configuring Tor and writing your first script to talk with it. - * - .. image:: /_static/section/tutorial/soviet.png - :target: tutorial/to_russia_with_love.html + * - .. image:: /_static/section/tutorials/soviet.png + :target: tutorials/to_russia_with_love.html - .. image:: /_static/label/to_russia_with_love.png - :target: tutorial/to_russia_with_love.html + :target: tutorials/to_russia_with_love.html Rather than talking to Tor, we'll now talk **through** it. In this tutorial we'll programmatically start Tor then use it to read a site through mother Russia! - * - .. image:: /_static/section/tutorial/tortoise.png - :target: tutorial/tortoise_and_the_hare.html + * - .. image:: /_static/section/tutorials/tortoise.png + :target: tutorials/tortoise_and_the_hare.html - .. image:: /_static/label/tortoise_and_the_hare.png - :target: tutorial/tortoise_and_the_hare.html + :target: tutorials/tortoise_and_the_hare.html As Tor runs it generates a variety of **events** that controllers can subscribe to be notified of. In this tutorial we'll do just that, writing a curses application that graphs the bandwidth usage of Tor. - * - .. image:: /_static/section/tutorial/mirror.png - :target: tutorial/mirror_mirror_on_the_wall.html + * - .. image:: /_static/section/tutorials/mirror.png + :target: tutorials/mirror_mirror_on_the_wall.html - .. image:: /_static/label/mirror_mirror_on_the_wall.png - :target: tutorial/mirror_mirror_on_the_wall.html + :target: tutorials/mirror_mirror_on_the_wall.html Getting and acting upon information about relays in the Tor network. Relay information is provided through documents called **descriptors**. This walks you through both where to get them and a small script to tell you the fastest Tor exits. - * - .. image:: /_static/section/tutorial/cauldron.png - :target: tutorial/double_double_toil_and_trouble.html + * - .. image:: /_static/section/tutorials/cauldron.png + :target: tutorials/double_double_toil_and_trouble.html - .. image:: /_static/label/double_double_toil_and_trouble.png - :target: tutorial/double_double_toil_and_trouble.html + :target: tutorials/double_double_toil_and_trouble.html Sometimes it's easiest to learn a library by seeing how it's used in the wild. This is a directory of scripts and applications that use stem. diff --git a/docs/tutorials/double_double_toil_and_trouble.rst b/docs/tutorials/double_double_toil_and_trouble.rst new file mode 100644 index 0000000..129a302 --- /dev/null +++ b/docs/tutorials/double_double_toil_and_trouble.rst @@ -0,0 +1,26 @@ +Double Double Toil and Trouble +============================== + +Below is a listing of scripts and applications that use stem. If you have +something you would like to have included on this page then `let me know +<http://www.atagar.com/contact/>`_! + +.. list-table:: + :widths: 1 10 + :header-rows: 0 + + * - .. image:: /_static/arm.png + :target: http://www.atagar.com/arm/ + + - .. image:: /_static/label/arm.png + :target: http://www.atagar.com/arm/ + + Terminal status monitor for Tor. This provides a top like interface + including system resource usage, connection information, and much more. + +=========================================================================================================== ========== +`Consensus Tracker <https://gitweb.torproject.org/atagar/tor-utils.git/blob/HEAD:/consensusTrac…>`_ Script that performs an hourly check for the number of relays within the Tor network, looking for large jumps that may indicate a sybil attack. +`Metrics Tasks <https://gitweb.torproject.org/metrics-tasks.git/tree>`_ One-off tasks related to Tor metrics. These mostly involve using descriptor information to answer a particular question. Tasks that involve stem are: `1854 <https://gitweb.torproject.org/metrics-tasks.git/blob/HEAD:/task-1854/pylinf…>`_, `6232 <https://gitweb.torproject.org/metrics-tasks.git/blob/HEAD:/task-6232/pyentr…>`_, and `7241 <https://gitweb.torproject.org/metrics-tasks.git/blob/HEAD:/task-7241/first_…>`_. +`check_tor <http://anonscm.debian.org/gitweb/?p=users/lunar/check_tor.git;a=blob;f=chec…>`_ Nagios check to verify that a relay is participating in the Tor network. +=========================================================================================================== ========== + diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst new file mode 100644 index 0000000..1a7f81d --- /dev/null +++ b/docs/tutorials/mirror_mirror_on_the_wall.rst @@ -0,0 +1,178 @@ +Mirror Mirror on the Wall +========================= + +* :ref:`what-is-a-descriptor` +* :ref:`where-can-i-get-the-current-descriptors` +* :ref:`where-can-i-get-past-descriptors` +* :ref:`putting-it-together` + +.. _what-is-a-descriptor: + +What is a descriptor? +--------------------- + +Tor is made up of two parts: the application and a distributed network of a few +thousand volunteer relays. Information about these relays is public, and made +up of documents called **descriptors**. + +There are several different kinds of descriptors, the most common ones being... + +====================================================================== =========== +Descriptor Type Description +====================================================================== =========== +`Server Descriptor <../api/descriptor/server_descriptor.html>`_ Information that relays publish about themselves. Tor clients once downloaded this information, but now they use microdescriptors instead. +`ExtraInfo Descriptor <../api/descriptor/extrainfo_descriptor.html>`_ Relay information that tor clients do not need in order to function. This is self-published, like server descriptors, but not downloaded by default. +`Microdescriptor <../api/descriptor/microdescriptor.html>`_ Minimalistic document that just includes the information necessary for tor clients to work. +`Network Status Document <../api/descriptor/networkstatus.html>`_ Though tor relays are decentralized, the directories that track the overall network are not. These central points are called **directory authorities**, and every hour they publish a document called a **consensus** (aka, network status document). The consensus in turn is made up of **router status entries**. +`Router Status Entry <../api/descriptor/router_status_entry.html>`_ Relay information provided by the directory authorities including flags, heuristics used for relay selection, etc. +====================================================================== =========== + +.. _where-can-i-get-the-current-descriptors: + +Where can I get the current descriptors? +---------------------------------------- + +To work tor needs to have up-to-date information about relays within the +network. As such getting current descriptors is easy: *just run tor*. + +Tor only gets the descriptors that it needs by default, so if you're scripting +against tor you may want to set some of the following in your `torrc +<https://www.torproject.org/docs/faq.html.en#torrc>`_. Keep in mind that these +add a small burden to the network, so don't set them in a widely distributed +application. And, of course, please consider `running tor as a relay +<https://www.torproject.org/docs/tor-doc-relay.html.en>`_ so you give back to +the network! + +:: + + # Descriptors have a range of time during which they're valid. To get the + # most recent descriptor information, regardless of if tor needs it or not, + # set the following. + + FetchDirInfoExtraEarly 1 + + # If you aren't actively using tor as a client then tor will eventually stop + # downloading descriptor information that it doesn't need. To prevent this + # from happening set... + + FetchUselessDescriptors 1 + + # Tor no longer downloads server descriptors by default, opting for + # microdescriptors instead. If you want tor to download server descriptors + # then set... + + UseMicrodescriptors 0 + + # Tor doesn't need extrainfo descriptors to work. If you want tor to download + # them anyway then set... + + DownloadExtraInfo 1 + +Now that tor is happy chugging along up-to-date descriptors are available +through tor's control socket... + +:: + + from stem.control import Controller + + with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + for desc in controller.get_network_statuses(): + print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) + +... or by reading directly from tor's data directory... + +:: + + from stem.descriptor import parse_file + + for desc in parse_file(open("/home/atagar/.tor/cached-consensus")): + print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) + +.. _where-can-i-get-past-descriptors: + +Where can I get past descriptors? +--------------------------------- + +Descriptor archives are available on `Tor's metrics site +<https://metrics.torproject.org/data.html>`_. These archives can be read with +the `DescriptorReader <api/descriptor/reader.html>`_... + +:: + + from stem.descriptor.reader import DescriptorReader + + with DescriptorReader(["/home/atagar/server-descriptors-2013-03.tar"]) as reader: + for desc in reader: + print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) + +.. _putting-it-together: + +Putting it together... +---------------------- + +As discussed above there are three methods for reading descriptors... + +* With the :class:`~stem.control.Controller` via methods like :func:`~stem.control.Controller.get_server_descriptors` and :func:`~stem.control.Controller.get_network_statuses`. +* By reading the file directly with :func:`~stem.descriptor.__init__.parse_file`. +* Reading with the `DescriptorReader <api/descriptor/reader.html>`_. This is best if you have you want to read everything from a directory or archive. + +Now lets say you want to figure out who the *biggest* exit relays are. You +could use any of the methods above, but for this example we'll use the +:class:`~stem.control.Controller`. This uses server descriptors, so keep in +mind that you'll likely need to set "UseMicrodescriptors 0" in your torrc for +this to work. + +:: + + import sys + + from stem.control import Controller + 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 Controller.from_port(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 + + # 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) + diff --git a/docs/tutorials/the_little_relay_that_could.rst b/docs/tutorials/the_little_relay_that_could.rst new file mode 100644 index 0000000..4f22b5b --- /dev/null +++ b/docs/tutorials/the_little_relay_that_could.rst @@ -0,0 +1,65 @@ +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!), and now +you want to write a script that tells you how much it is being used. + +First, for any script to talk with your relay it will 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 our script to talk with. If you set this then be + # sure to also set either CookieAuthentication *or* HashedControlPassword! + # + # You could also use ControlSocket instead of ControlPort, which provides a + # file based socket. You don't need to have authentication if you use + # ControlSocket. For this example however we'll use a port. + + ControlPort 9051 + + # Setting this will make Tor write an authentication cookie. Anything with + # permission to read this file can connect to Tor. If you're going to run + # your script with the same user or permission group 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 your torrc. + + HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF + +When you change your torrc you'll need to either restart Tor is issue a SIGHUP +for the 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 + + with Controller.from_port(port = 9051) as controller: + 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) + +:: + + % python example.py + My Tor relay has read 33406 bytes and written 29649. + +Congratulations! You've just written your first controller script. + diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst new file mode 100644 index 0000000..7fb7c66 --- /dev/null +++ b/docs/tutorials/to_russia_with_love.rst @@ -0,0 +1,70 @@ +To Russia With Love +=================== + +Say it's 1982, the height of the Cold War, and you're a journalist doing a piece on how the Internet looks from behind the Iron Curtain. Ignoring the minor detail that the Internet doesn't yet exist, we'll walk you through how you could do it - no passport required! + +The Internet isn't uniform. Localization, censorship, and selective service based on your IP's geographic location can make the Internet a very different place depending on where you're coming from. + +Tor relays are scattered all over the world and, as such, you can pretend to be from any place running an exit. This can be especially useful to evade pesky geolocational restrictions, such as news sites that refuse to work while you're traveling abroad. + +Tor makes `configuring your exit locale <https://www.torproject.org/docs/faq.html.en#ChooseEntryExit>`_ easy through the **ExitNodes** torrc option. Note that you don't need a control port (or even stem) to do this, though they can be useful if you later want to do something more elaborate. + +In the following example we're using stem to `start Tor <../api/process.html>`_, then reading a site through it with `PycURL <http://pycurl.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once. + +**Do not rely on the following not to leak.** Though it seems to work, DNS resolution and other edge cases might expose your real IP. If you have a suggestion for how to improve this example then please `let me know <http://www.atagar.com/contact/>`_! + +:: + + import StringIO + + import pycurl + import stem.process + + from stem.util import term + + SOCKS_PORT = 7000 + + def curl(url): + """ + Uses pycurl to fetch a site using the proxy on the SOCKS_PORT. + """ + + output = StringIO.StringIO() + + query = pycurl.Curl() + query.setopt(pycurl.URL, url) + query.setopt(pycurl.PROXY, 'localhost') + query.setopt(pycurl.PROXYPORT, SOCKS_PORT) + query.setopt(pycurl.PROXYTYPE, pycurl.PROXYTYPE_SOCKS5) + query.setopt(pycurl.WRITEFUNCTION, output.write) + + try: + query.perform() + return output.getvalue() + except pycurl.error, exc: + return "Unable to reach %s (%s)" % (url, exc) + + # Start an instance of tor configured to only exit through Russia. This prints + # tor's bootstrap information as it starts. + + def print_bootstrap_lines(line): + if "Bootstrapped " in line: + print term.format(line, term.Color.BLUE) + + print term.format("Starting Tor:\n", term.Attr.BOLD) + + tor_process = stem.process.launch_tor_with_config( + config = { + 'SocksPort': str(SOCKS_PORT), + 'ExitNodes': '{ru}', + }, + init_msg_handler = print_bootstrap_lines, + ) + + print term.format("\nChecking our endpoint:\n", term.Attr.BOLD) + print term.format(curl("http://www.atagar.com/echo.php"), term.Color.BLUE) + + tor_process.kill() # stops tor + +.. image:: /_static/locale_selection_output.png + diff --git a/docs/tutorials/tortoise_and_the_hare.rst b/docs/tutorials/tortoise_and_the_hare.rst new file mode 100644 index 0000000..f575853 --- /dev/null +++ b/docs/tutorials/tortoise_and_the_hare.rst @@ -0,0 +1,204 @@ +Tortoise and the Hare +===================== + +Controllers have two methods of talking with Tor... + +* **Synchronous** - Most commonly you make a request to Tor then receive its + reply. The :func:`~stem.control.Controller.get_info` calls in the `first + tutorial <the_little_relay_that_could.html>`_ are an example of this. + +* **Asynchronous** - Controllers can subscribe to be notified when various + kinds of events occur within Tor (see the :data:`~stem.control.EventType`). + Stem's users provide a callback function to + :func:`~stem.control.Controller.add_event_listener` which is then notified + when the event occurs. + +Try to avoid lengthy operations within event callbacks. They're notified by a +single dedicated event thread, and blocking this thread will prevent the +delivery of further events. + +With that out of the way lets see an example. The following is a `curses +<http://docs.python.org/2/howto/curses.html>`_ application that graphs the +bandwidth usage of Tor... + +.. image:: /_static/bandwidth_graph_output.png + +To do this it listens to **BW events** +(the class for which is a :class:`~stem.response.events.BandwidthEvent`). These +are events that Tor emits each second saying the number of bytes downloaded and +uploaded. + +:: + + import curses + import functools + + from stem.control import EventType, Controller + from stem.util import str_tools + + # colors that curses can handle + + COLOR_LIST = { + "red": curses.COLOR_RED, + "green": curses.COLOR_GREEN, + "yellow": curses.COLOR_YELLOW, + "blue": curses.COLOR_BLUE, + "cyan": curses.COLOR_CYAN, + "magenta": curses.COLOR_MAGENTA, + "black": curses.COLOR_BLACK, + "white": curses.COLOR_WHITE, + } + + GRAPH_WIDTH = 40 + GRAPH_HEIGHT = 8 + + DOWNLOAD_COLOR = "green" + UPLOAD_COLOR = "blue" + + def main(): + with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + try: + curses.wrapper(drawBandwidthGraph, controller) + except KeyboardInterrupt: + pass # the user hit ctrl+c + + def drawBandwidthGraph(stdscr, controller): + window = Window(stdscr) + + # (downloaded, uploaded) tuples for the last 40 seconds + + bandwidth_rates = [(0, 0)] * GRAPH_WIDTH + + # Making a partial that wraps the window and bandwidth_rates with a function + # for Tor to call when it gets a BW event. + + bw_event_handler = functools.partial(_handle_bandwidth_event, window, bandwidth_rates) + + # Registering this listener with Tor. Tor reports a BW event each second. + + controller.add_event_listener(bw_event_handler, EventType.BW) + + # Pause the main thread until the user hits any key... and no, don't you dare + # ask where the 'any' key is. :P + + stdscr.getch() + + def _handle_bandwidth_event(window, bandwidth_rates, event): + # callback for when tor provides us with a BW event + + bandwidth_rates.insert(0, (event.read, event.written)) + bandwidth_rates = bandwidth_rates[:GRAPH_WIDTH] # truncate old values + _render_graph(window, bandwidth_rates) + + def _render_graph(window, bandwidth_rates): + window.erase() + + download_rates = [entry[0] for entry in bandwidth_rates] + upload_rates = [entry[1] for entry in bandwidth_rates] + + # show the latest values at the top + + label = "Downloaded (%s/s):" % str_tools.get_size_label(download_rates[0], 1) + window.addstr(0, 1, label, DOWNLOAD_COLOR, curses.A_BOLD) + + label = "Uploaded (%s/s):" % str_tools.get_size_label(upload_rates[0], 1) + window.addstr(0, GRAPH_WIDTH + 7, label, UPLOAD_COLOR, curses.A_BOLD) + + # draw the graph bounds in KB + + max_download_rate = max(download_rates) + max_upload_rate = max(upload_rates) + + window.addstr(1, 1, "%4i" % (max_download_rate / 1024), DOWNLOAD_COLOR) + window.addstr(GRAPH_HEIGHT, 1, " 0", DOWNLOAD_COLOR) + + window.addstr(1, GRAPH_WIDTH + 7, "%4i" % (max_upload_rate / 1024), UPLOAD_COLOR) + window.addstr(GRAPH_HEIGHT, GRAPH_WIDTH + 7, " 0", UPLOAD_COLOR) + + # draw the graph + + for col in xrange(GRAPH_WIDTH): + col_height = GRAPH_HEIGHT * download_rates[col] / max(max_download_rate, 1) + + for row in xrange(col_height): + window.addstr(GRAPH_HEIGHT - row, col + 6, " ", DOWNLOAD_COLOR, curses.A_STANDOUT) + + col_height = GRAPH_HEIGHT * upload_rates[col] / max(max_upload_rate, 1) + + for row in xrange(col_height): + window.addstr(GRAPH_HEIGHT - row, col + GRAPH_WIDTH + 12, " ", UPLOAD_COLOR, curses.A_STANDOUT) + + window.refresh() + + class Window(object): + """ + Simple wrapper for the curses standard screen object. + """ + + def __init__(self, stdscr): + self._stdscr = stdscr + + # Mappings of names to the curses color attribute. Initially these all + # reference black text, but if the terminal can handle color then + # they're set with that foreground color. + + self._colors = dict([(color, 0) for color in COLOR_LIST]) + + # allows for background transparency + + try: + curses.use_default_colors() + except curses.error: + pass + + # makes the cursor invisible + + try: + curses.curs_set(0) + except curses.error: + pass + + # initializes colors if the terminal can handle them + + try: + if curses.has_colors(): + color_pair = 1 + + for name, foreground in COLOR_LIST.items(): + background = -1 # allows for default (possibly transparent) background + curses.init_pair(color_pair, foreground, background) + self._colors[name] = curses.color_pair(color_pair) + color_pair += 1 + except curses.error: + pass + + def addstr(self, y, x, msg, color = None, attr = curses.A_NORMAL): + # Curses throws an error if we try to draw a message that spans out of the + # window's bounds (... seriously?), so doing our best to avoid that. + + if color is not None: + if color not in self._colors: + recognized_colors = ", ".join(self._colors.keys()) + raise ValueError("The '%s' color isn't recognized: %s" % (color, recognized_colors)) + + attr |= self._colors[color] + + max_y, max_x = self._stdscr.getmaxyx() + + if max_x > x and max_y > y: + try: + self._stdscr.addstr(y, x, msg[:max_x - x], attr) + except: + pass # maybe an edge case while resizing the window + + def erase(self): + self._stdscr.erase() + + def refresh(self): + self._stdscr.refresh() + + if __name__ == '__main__': + main() +

1 0

[torspec/master] Remove the "V3Dir" flag from dir-spec.
by nickm＠torproject.org 13 Mar '13

13 Mar '13

commit 67768b16c247f937a4345af94beb58a4238b0730 Author: Linus Nordberg <linus(a)torproject.org> Date: Wed Mar 13 15:35:28 2013 +0100 Remove the "V3Dir" flag from dir-spec. There is no such thing as a V3Dir flag. --- dir-spec.txt | 8 +------- 1 files changed, 1 insertions(+), 7 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 4a8f007..6c5bce8 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1467,8 +1467,7 @@ "Unnamed" if another router has bound the name used by this router, and this authority binds names. "Valid" if the router has been 'validated'. - "V2Dir" if the router implements the v2 directory protocol. - "V3Dir" if the router implements this protocol. + "V2Dir" if the router implements the v2 directory protocol or later. "v" SP version NL @@ -1691,11 +1690,6 @@ supports the functionality clients need. (Currently, this is 0.1.1.9-alpha or later.) - "V3Dir" -- A router supports the v3 directory protocol if it has an open - directory port, and it is running a version of the directory protocol that - supports the functionality clients need. (Currently, this is - 0.2.0.?????-alpha or later.) - "HSDir" -- A router is a v2 hidden service directory if it stores and serves v2 hidden service descriptors, and the authority believes that it's been up for at least 25 hours (or the current value of

1 0

[torspec/master] V2Dir means v2, not "v2 or later".
by nickm＠torproject.org 13 Mar '13

13 Mar '13

commit 6a3234ad8116eb495b375cfc2fbfd9593c1e80f4 Author: Linus Nordberg <linus(a)torproject.org> Date: Wed Mar 13 15:53:38 2013 +0100 V2Dir means v2, not "v2 or later". --- dir-spec.txt | 2 +- 1 files changed, 1 insertions(+), 1 deletions(-) diff --git a/dir-spec.txt b/dir-spec.txt index 6c5bce8..c75bbb9 100644 --- a/dir-spec.txt +++ b/dir-spec.txt @@ -1467,7 +1467,7 @@ "Unnamed" if another router has bound the name used by this router, and this authority binds names. "Valid" if the router has been 'validated'. - "V2Dir" if the router implements the v2 directory protocol or later. + "V2Dir" if the router implements the v2 directory protocol. "v" SP version NL

1 0

r26107: {projects} support free software with an odp, fix the url at the end of (projects/presentations)
by Andrew Lewman 13 Mar '13

13 Mar '13

Author: phobos Date: 2013-03-13 14:48:58 +0000 (Wed, 13 Mar 2013) New Revision: 26107 Added: projects/presentations/2013-03-13-SXSW-Presentation-Loop.odp Modified: projects/presentations/2013-03-13-SXSW-Presentation-Loop.pdf projects/presentations/2013-03-13-SXSW-Presentation-Loop.ppt Log: support free software with an odp, fix the url at the end of the presentation. Added: projects/presentations/2013-03-13-SXSW-Presentation-Loop.odp =================================================================== (Binary files differ) Property changes on: projects/presentations/2013-03-13-SXSW-Presentation-Loop.odp ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Modified: projects/presentations/2013-03-13-SXSW-Presentation-Loop.pdf =================================================================== (Binary files differ) Modified: projects/presentations/2013-03-13-SXSW-Presentation-Loop.ppt =================================================================== (Binary files differ)

1 0

r26106: {} add SXSW presentation from Kelley and Karen. (projects/presentations)
by Andrew Lewman 13 Mar '13

13 Mar '13

Author: phobos Date: 2013-03-13 14:42:24 +0000 (Wed, 13 Mar 2013) New Revision: 26106 Added: projects/presentations/2013-03-13-SXSW-Presentation-Loop.pdf projects/presentations/2013-03-13-SXSW-Presentation-Loop.ppt Log: add SXSW presentation from Kelley and Karen. Added: projects/presentations/2013-03-13-SXSW-Presentation-Loop.pdf =================================================================== (Binary files differ) Property changes on: projects/presentations/2013-03-13-SXSW-Presentation-Loop.pdf ___________________________________________________________________ Added: svn:mime-type + application/octet-stream Added: projects/presentations/2013-03-13-SXSW-Presentation-Loop.ppt =================================================================== (Binary files differ) Property changes on: projects/presentations/2013-03-13-SXSW-Presentation-Loop.ppt ___________________________________________________________________ Added: svn:mime-type + application/octet-stream

1 0

[flashproxy/master] Disable the start function too when disabling.
by dcf＠torproject.org 13 Mar '13

13 Mar '13

commit 619a8ca02fb2190c269bff51a51becfdcfd4375b Author: David Fifield <david(a)bamsoftware.com> Date: Wed Mar 13 02:54:23 2013 -0700 Disable the start function too when disabling. Otherwise the debug mode would print the message Starting; will contact facilitator in 60 seconds. even though that was false. --- proxy/flashproxy.js | 1 + 1 files changed, 1 insertions(+), 0 deletions(-) diff --git a/proxy/flashproxy.js b/proxy/flashproxy.js index 31a1f60..2fa6c99 100644 --- a/proxy/flashproxy.js +++ b/proxy/flashproxy.js @@ -632,6 +632,7 @@ function FlashProxy() { /* Cease all network operations and prevent any future ones. */ this.disable = function() { puts("Disabling."); + this.start = function() { }; this.proxy_main = function() { }; this.make_proxy_pair = function(client_addr, relay_addr) { }; while (this.proxy_pairs.length > 0)

1 0

[flashproxy/master] Make URL-based registration work with HEAD as well as GET.
by dcf＠torproject.org 13 Mar '13

13 Mar '13

commit 370a2650d406f3b1b2029f54b174f7e24446b61a Author: David Fifield <david(a)bamsoftware.com> Date: Wed Mar 13 02:24:05 2013 -0700 Make URL-based registration work with HEAD as well as GET. --- facilitator/facilitator.cgi | 33 +++++++++++++++++++++++---------- 1 files changed, 23 insertions(+), 10 deletions(-) diff --git a/facilitator/facilitator.cgi b/facilitator/facilitator.cgi index bb0ac51..4885ead 100755 --- a/facilitator/facilitator.cgi +++ b/facilitator/facilitator.cgi @@ -21,7 +21,7 @@ def exit_error(status): sys.exit() # Send a base64-encoded client address to the registration daemon. -def url_reg(reg): +def send_url_reg(reg): # Translate from url-safe base64 alphabet to the standard alphabet. reg = reg.replace('-', '+').replace('_', '/') return fac.put_reg_base64(reg) @@ -35,17 +35,28 @@ if not method or not remote_addr[0]: fs = cgi.FieldStorage() +# Print the HEAD part of a URL-based registration response, or exit with an +# error if appropriate. +def url_reg(reg): + try: + if send_url_reg(reg): + output_status(204) + else: + exit_error(400) + except: + exit_error(500) + +def do_head(): + path_parts = [x for x in path_info.split("/") if x] + if len(path_parts) == 2 and path_parts[0] == "reg": + url_reg(path_parts[1]) + else: + exit_error(400) + def do_get(): path_parts = [x for x in path_info.split("/") if x] if len(path_parts) == 2 and path_parts[0] == "reg": - # This is a URL-based registration. - try: - if url_reg(path_parts[1]): - output_status(204) - else: - exit_error(400) - except: - exit_error(500) + url_reg(path_parts[1]) elif len(path_parts) == 0: try: reg = fac.get_reg(FACILITATOR_ADDR, remote_addr) or "" @@ -79,7 +90,9 @@ def do_post(): Status: 200\r \r""" -if method == "GET": +if method == "HEAD": + do_head() +elif method == "GET": do_get() elif method == "POST": do_post()

1 0