tor-commits
Threads by month
- ----- 2026 -----
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2025 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2024 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2023 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2022 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2021 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2020 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2019 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2018 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2017 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2016 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2015 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2014 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2013 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2012 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- January
- ----- 2011 -----
- December
- November
- October
- September
- August
- July
- June
- May
- April
- March
- February
- 1 participants
- 216171 discussions
14 Mar '13
commit 68bc5de84dc90e1292c6aa19abd95f660b5e3277
Author: aagbsn <aagbsn(a)extc.org>
Date: Tue Mar 5 19:56:29 2013 +0100
8399 - Do not return 0 from get_unmeasured_bw
---
TorCtl.py | 5 +++--
1 files changed, 3 insertions(+), 2 deletions(-)
diff --git a/TorCtl.py b/TorCtl.py
index 485a2d9..9bba58d 100755
--- a/TorCtl.py
+++ b/TorCtl.py
@@ -510,8 +510,9 @@ class Router:
def get_unmeasured_bw(self):
# if unmeasured, the ratio of self.bw/self.desc_bw should be 1.0
- if self.unmeasured: return self.bw
- else: return self.desc_bw
+ if self.unmeasured and self.bw > 0: return self.bw
+ elif self.desc_bw > 0: return self.desc_bw
+ else: return 1
class Connection:
"""A Connection represents a connection to the Tor process via the
1
0
commit 61c8869f9f60b92d3208762cecd1eb463027482c
Author: Translation commit bot <translation(a)torproject.org>
Date: Thu Mar 14 09:45:19 2013 +0000
Update translations for tsum
---
sr/short-user-manual_sr_noimg.xhtml | 31 ++++++++++++++-----------------
1 files changed, 14 insertions(+), 17 deletions(-)
diff --git a/sr/short-user-manual_sr_noimg.xhtml b/sr/short-user-manual_sr_noimg.xhtml
index 85dcdbf..2c94c44 100644
--- a/sr/short-user-manual_sr_noimg.xhtml
+++ b/sr/short-user-manual_sr_noimg.xhtml
@@ -5,7 +5,7 @@
</head>
<body>
<h1 id="the-short-user-manual">Kratki korisnicki prirucnik</h1>
- <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>Ovaj korisnicki prirucnik sadrzi informacije 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>
@@ -25,21 +25,19 @@
<p>We also have experimental packages for <a href="https://www.torproject.org/docs/N900.html.en">Nokia Maemo/N900</a> and <a href="http://sid77.slackware.it/iphone/">Apple iOS</a>.</p>
<h3 id="how-to-verify-that-you-have-the-right-version">Kako proveriti da li imate pravu verziju</h3>
<p>Pre nego sto pokrenete Tor paket, terbalo bi da proverite da li imate pravu verziju.</p>
- <p>The software you receive is accompanied by a file with the same name as the bundle and the extension <strong>.asc</strong>. This .asc file is a GPG signature, and will allow you to verify the file you've downloaded is exactly the one that we intended you to get.</p>
- <p>Before you can verify the signature, you will have to download and install GnuPG:</p>
+ <p>Software koji dobijete dolazi sa istoimenim fajlom i <strong>.asc</strong> nastavkom. Ovaj .asc fajl je GPG potpis i omogucava vam da proverite da fajl koji ste preuzeli je autentican.</p>
+ <p>Pre nego sto mozete verifikovati potpis, morate preuzeti i instalirati GnuPG:</p>
<p><strong>Windows</strong>: <a href="http://gpg4win.org/download.html">http://gpg4win.org/download.html</a><br/><strong>Mac OS X</strong>: <a href="http://macgpg.sourceforge.net/">http://macgpg.sourceforge.net/</a><br/><strong>Linux</strong>: Most Linux distributions come with GnuPG preinstalled.</p>
- <p>Please note that you may need to edit the paths and the commands used below to get it to work on your system.</p>
- <p>Erinn Clark signs the Tor Browser Bundles with key 0x63FEE659. To import Erinn's key, run:</p>
+ <p>Imajte na umu da je moguce da cete morati promeniti adrese i komande koristene ispod da bi program radio na vasem sistemu.</p>
+ <p>Erinn Clark potpisuje Tor paket sa kljucem 0x63FEE659. Da bi uneli njen kljuc, pokrenite:</p>
<pre>
- <code>gpg --keyserver hkp://keys.gnupg.net --recv-keys 0x63FEE659
-</code>
+ <code>gpg --keyserver hkp://keys.gnupg.net --recv-keys 0x63FEE659</code>
</pre>
- <p>After importing the key, verify that the fingerprint is correct:</p>
+ <p>Nako sto ste uneli kljuc, proverite da je otisak tacan:</p>
<pre>
- <code>gpg --fingerprint 0x63FEE659
-</code>
+ <code>gpg --fingerprint 0x63FEE659</code>
</pre>
- <p>You should see:</p>
+ <p>Trebalo bi da vidite:</p>
<pre>
<code>pub 2048R/63FEE659 2003-10-16
Key fingerprint = 8738 A680 B84B 3031 A630 F2DB 416F 0610 63FE E659
@@ -50,14 +48,13 @@ uid Erinn Clark <erinn(a)double-helix.org>
sub 2048R/EB399FD7 2003-10-16
</code>
</pre>
- <p>To verify the signature of the package you downloaded, run the following command:</p>
+ <p>'To verify the signature of the package you downloaded, run the following command: ' Sto znaci: Da bi proverili potpis paketa koji ste preuzeli, unesite sledecu komandu: </p>
<pre>
- <code>gpg --verify tor-browser-2.2.33-2_en-US.exe.asc tor-browser-2.2.33-2_en-US.exe
-</code>
+ <code>gpg --verify tor-browser-2.2.33-2_en-US.exe.asc tor-browser-2.2.33-2_en-US.exe </code>
</pre>
- <p>The output should say <em>"Good signature"</em>. A bad signature means that the file may have been tampered with. If you see a bad signature, send details about where you downloaded the package from, how you verified the signature, and the output from GnuPG in an email to help(a)rt.torproject.org.</p>
- <p>Once you have verified the signature and seen the <em>"Good signature"</em> output, go ahead and extract the package archive. You should then see a directory similar to <strong>tor-browser_en-US</strong>. Inside that directory is another directory called <strong>Docs</strong>, which contains a file called <strong>changelog</strong>. You want to make sure that the version number on the top line of the changelog file matches the version number in the filename.</p>
- <h3 id="how-to-use-the-tor-browser-bundle">How to use the Tor Browser Bundle</h3>
+ <p>Odgovor bi trebo biti <em>"Good signature"</em>. Los potpis znaci da je moguce da je fajl bio menjan. Ako vidite los potpis posaljite detalje o stranici gde ste preuzeli paket, kako ste proverili da li je potpis tacan i poruku koju ste dobili u GnuPG programu preko mejla na help(a)rt.torproject.org.</p>
+ <p>Nako sto ste proverili potpis i videli <em>"Good signature"</em> poruku, mozete ekstraktovati arhivu. Dobicete folder zvan <strong>tor-browser_en-US</strong>. Taj folder sadrzi joj jedan folder zvan <strong>Docs</strong>, koji sadrzi fajl zvan changelog. Uverite se da broj verzije u prvoj liniji <strong>changelog</strong> fajla odgovara broj verzije u imenu fajla.</p>
+ <h3 id="how-to-use-the-tor-browser-bundle">Kako koristiti Tor pretrazivac</h3>
<p>After downloading the Tor Browser Bundle and extracting the package, you should have a directory with a few files in it. One of the files is an executable called "Start Tor Browser" (or "start-tor-browser", depending on your operating system).</p>
<p>When you start the Tor Browser Bundle, you will first see Vidalia start up and connect you to the Tor network. After that, you will see a browser confirming that you are now using Tor. This is done by displaying <a href="https://check.torproject.org/">https://check.torproject.org/</a>. You can now browse the Internet through Tor.</p>
<p>
1
0
commit 2040c6ae75f71916141d84c56e6fc63ae0f178ee
Author: Translation commit bot <translation(a)torproject.org>
Date: Thu Mar 14 09:15:20 2013 +0000
Update translations for tsum
---
sr/short-user-manual_sr_noimg.xhtml | 20 ++++++++++----------
1 files changed, 10 insertions(+), 10 deletions(-)
diff --git a/sr/short-user-manual_sr_noimg.xhtml b/sr/short-user-manual_sr_noimg.xhtml
index 742674e..85dcdbf 100644
--- a/sr/short-user-manual_sr_noimg.xhtml
+++ b/sr/short-user-manual_sr_noimg.xhtml
@@ -14,17 +14,17 @@
<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>
- <p>You can also request the Tor Browser Bundle for Mac OS X (write <strong>macos-i386</strong>), and Linux (write <strong>linux-i386</strong> for 32-bit systems or <strong>linux-x86_64</strong> for 64-bit systems).</p>
- <p>If you want a translated version of Tor, write <strong>help</strong> instead. You will then receive an email with instructions and a list of available languages.</p>
- <p><strong>Note</strong>: The Tor Browser Bundles for Linux and Mac OS X are rather large, and you will not be able to receive any of these bundles with a Gmail, Hotmail or Yahoo account. If you cannot receive the bundle you want, send an email to help(a)rt.torproject.org and we will give you a list of website mirrors to use.</p>
- <h3 id="tor-for-smartphones">Tor for smartphones</h3>
- <p>You can get Tor on your Android device by installing the package named <em>Orbot</em>. For information about how to download and install Orbot, please see the <a href="https://www.torproject.org/docs/android.html.en">Tor Project website</a>.</p>
+ <p>Postoje dva nacina da dodjete do Tor softvera. Mozete ga preuzetina <a href="https://www.torproject.org/">Tor Project stranici</a> ili mozete koristiti GetTor emejl autoresponder.</p>
+ <h3 id="how-to-get-tor-via-email">Kako preuzeti Tor preko emejla</h3>
+ <p>Da dobijete Engleski Tor paket za Windows, posaljite emejl na gettor(a)torproject.org i unesite rec<strong>windows</strong> u glavom delu mejla. Mozete ostaviti polje za predmet praznim.</p>
+ <p>Takodjer mozete zatraziti Tor paket za Mac OS X (napisite <strong>macos-i386</strong>) i za Linux (napisite <strong>linux-i386</strong> za 32 bitne sisteme ili <strong>linux-x86_64</strong> za 64 bitne sisteme).</p>
+ <p>Ako zelite prevedenu verziju Tor-a, napiste <strong>help</strong>. Mi cemo vam poslati emejl sa instrukcijama i listom dostupnih jezika.</p>
+ <p><strong>Imajte na umu</strong>: Tor paket za Linux i Mac OS X su veliki fajlovi i necete ih moci dobiti preko mejla ako koristite Gmail,Hotmail ili Yahoo. Ako niste u mogucnosti da dobijete paket koji ste zeleli, posaljite emaj na help(a)rt.torproject.org i mi cemo vam poslati listu stranica odakle mozete preuzeti zeljeni paket.</p>
+ <h3 id="tor-for-smartphones">Tor za telefone</h3>
+ <p>Mozete preuzeti Tor na svom Android uredjaju tako sto cete instalirati paket zvan <em>Orbot</em>. Za vise informacija o tome kako preuzeti i instalirati Orbot, pogledajte <a href="https://www.torproject.org/docs/android.html.en">Tor Project stranicu</a>.</p>
<p>We also have experimental packages for <a href="https://www.torproject.org/docs/N900.html.en">Nokia Maemo/N900</a> and <a href="http://sid77.slackware.it/iphone/">Apple iOS</a>.</p>
- <h3 id="how-to-verify-that-you-have-the-right-version">How to verify that you have the right version</h3>
- <p>Before running the Tor Browser Bundle, you should make sure that you have the right version.</p>
+ <h3 id="how-to-verify-that-you-have-the-right-version">Kako proveriti da li imate pravu verziju</h3>
+ <p>Pre nego sto pokrenete Tor paket, terbalo bi da proverite da li imate pravu verziju.</p>
<p>The software you receive is accompanied by a file with the same name as the bundle and the extension <strong>.asc</strong>. This .asc file is a GPG signature, and will allow you to verify the file you've downloaded is exactly the one that we intended you to get.</p>
<p>Before you can verify the signature, you will have to download and install GnuPG:</p>
<p><strong>Windows</strong>: <a href="http://gpg4win.org/download.html">http://gpg4win.org/download.html</a><br/><strong>Mac OS X</strong>: <a href="http://macgpg.sourceforge.net/">http://macgpg.sourceforge.net/</a><br/><strong>Linux</strong>: Most Linux distributions come with GnuPG preinstalled.</p>
1
0
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
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
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
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
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
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
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