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

r26675: {website} strip trailing whitespace (website/trunk/docs/en)
by Roger Dingledine 24 Mar '14

24 Mar '14

Author: arma Date: 2014-03-24 07:02:11 +0000 (Mon, 24 Mar 2014) New Revision: 26675 Modified: website/trunk/docs/en/tor-doc-relay.wml Log: strip trailing whitespace Modified: website/trunk/docs/en/tor-doc-relay.wml =================================================================== --- website/trunk/docs/en/tor-doc-relay.wml 2014-03-24 07:00:12 UTC (rev 26674) +++ website/trunk/docs/en/tor-doc-relay.wml 2014-03-24 07:02:11 UTC (rev 26675) @@ -28,33 +28,33 @@ - An easy way to get started is with Vidalia, a graphical interface for - Tor. Vidalia is not included in the standard Tor Browser Bundle, although it - <a href="https://www.torproject.org/docs/faq.html.en#WhereDidVidaliaGo">once - was</a>. + An easy way to get started is with Vidalia, a graphical interface for + Tor. Vidalia is not included in the standard Tor Browser Bundle, although it + <a href="https://www.torproject.org/docs/faq.html.en#WhereDidVidaliaGo">once + was</a>. - The Vidalia Bridge Bundle, the Vidalia Relay Bundle - and the Vidalia Exit Bundle are available on the - <a href="https://www.torproject.org/download/download.html.en">download - page</a>. These bundles are only available for Windows. They come - preconfigured to run Tor as a bridge, a non-exit relay, or an exit relay. + The Vidalia Bridge Bundle, the Vidalia Relay Bundle + and the Vidalia Exit Bundle are available on the + <a href="https://www.torproject.org/download/download.html.en">download + page</a>. These bundles are only available for Windows. They come + preconfigured to run Tor as a bridge, a non-exit relay, or an exit relay. - Vidalia is also available as a standalone package from <a - href="https://people.torproject.org/~erinn/vidalia-standalone-bundles/">this - directory</a>. To use the Vidalia standalone, you will first need to <a - href="https://torproject.org/projects/torbrowser.html.en">download - the Tor Browser Bundle</a> or the <a href="https://www.torproject.org/download/download.html.en">Tor Expert Bundle</a>. - Unpack the Vidalia package into your Tor Browser folder. This will allow - Vidalia to control and configure the Tor Browser Bundle's Tor client. If - you use the Expert Bundle, which contains Tor only and no browser, you'll + Vidalia is also available as a standalone package from <a + href="https://people.torproject.org/~erinn/vidalia-standalone-bundles/">this + directory</a>. To use the Vidalia standalone, you will first need to <a + href="https://torproject.org/projects/torbrowser.html.en">download + the Tor Browser Bundle</a> or the <a href="https://www.torproject.org/download/download.html.en">Tor Expert Bundle</a>. + Unpack the Vidalia package into your Tor Browser folder. This will allow + Vidalia to control and configure the Tor Browser Bundle's Tor client. If + you use the Expert Bundle, which contains Tor only and no browser, you'll need to inform Vidalia of your Tor's location. - Make sure your Tor works by using Tor as a client (surf with the Tor + Make sure your Tor works by using Tor as a client (surf with the Tor Browser, for example). Verify that your clock and timezone are set correctly. If possible, synchronize your clock with public <a href="http://en.wikipedia.org/wiki/Network_Time_Protocol">time @@ -106,8 +106,8 @@ - You can set up a relay without using Vidalia if you wish. Tor's - configuration file is named 'torrc'. In the Tor Browser folder, it's + You can set up a relay without using Vidalia if you wish. Tor's + configuration file is named 'torrc'. In the Tor Browser folder, it's located at <pre>Data\Tor\torrc</pre> Open the file with a text editor and add the following lines: @@ -119,17 +119,17 @@ ContactInfo human@... </pre> - If you want to be a bridge, read about the BridgeRelay and - ServerTransportPlugin values <a + If you want to be a bridge, read about the BridgeRelay and + ServerTransportPlugin values <a href="https://www.torproject.org/projects/obfsproxy-instructions.html.en#instruct…">on this page</a>. - Tor will use all your bandwidth if you don't set limits for it. Some - options are described in <a href="<page docs/faq>#LimitTotalBandwidth">these</a> + Tor will use all your bandwidth if you don't set limits for it. Some + options are described in <a href="<page docs/faq>#LimitTotalBandwidth">these</a> <a href="<page docs/faq>#BandwidthShaping">FAQ entries</a>. - See the <a href="https://gitweb.torproject.org/tor.git/blob/HEAD:/src/config/torrc.sample.in">sample - torrc file</a> and the <a + See the <a href="https://gitweb.torproject.org/tor.git/blob/HEAD:/src/config/torrc.sample.in">sample + torrc file</a> and the <a href="https://www.torproject.org/docs/tor-manual.html.en">man page</a> for other Tor options you may want to set. @@ -165,9 +165,9 @@ When your relay has decided that it's reachable, it will upload a "server descriptor" to the directories, to let clients know what address, ports, keys, etc your relay is using. You can search <a - href="https://atlas.torproject.org/">Atlas</a> or <a - href="https://globe.torproject.org/">Globe</a> for - the nickname you configured, to make sure it's there. You may need to wait + href="https://atlas.torproject.org/">Atlas</a> or <a + href="https://globe.torproject.org/">Globe</a> for + the nickname you configured, to make sure it's there. You may need to wait up to one hour for the directories to publish the new server information. <hr> @@ -179,11 +179,11 @@ href="https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-announce">tor-announce</a> mailing list. It is very low volume, and it will keep you informed of new stable releases. - - As a relay operator, you should consider subscribing to the + + As a relay operator, you should consider subscribing to the <a href="https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-relays"> tor-relays mailing list</a>. You might find <a - href="../docs/documentation.html.en#MailingLists">other higher-volume + href="../docs/documentation.html.en#MailingLists">other higher-volume Tor lists</a> of interest to you as well.

1 0

r26674: {website} make the faq work better on website mirrors too (website/trunk/docs/en)
by Roger Dingledine 24 Mar '14

24 Mar '14

Author: arma Date: 2014-03-24 07:00:12 +0000 (Mon, 24 Mar 2014) New Revision: 26674 Modified: website/trunk/docs/en/faq.wml Log: make the faq work better on website mirrors too Modified: website/trunk/docs/en/faq.wml =================================================================== --- website/trunk/docs/en/faq.wml 2014-03-24 06:57:32 UTC (rev 26673) +++ website/trunk/docs/en/faq.wml 2014-03-24 07:00:12 UTC (rev 26674) @@ -981,7 +981,7 @@ it sends. The Tor Browser Bundle tries to keep application-level data, like the user-agent string, uniform for all users. The Tor Browser can't do anything about text that you type into forms, though. <a - href="https://www.torproject.org/download/download-easy.html.en#warning">Be + href="<page download/download-easy>#warning">Be careful and be smart.</a> @@ -1517,7 +1517,7 @@ You can set Proxy IP address, port, and authentication information in Tor Browser's Network Settings. If you're using Tor another way, check out the HTTPProxy and HTTPSProxy config options in the <a -href="https://www.torproject.org/docs/tor-manual.html.en">man page</a>, +href="<page docs/tor-manual>">man page</a>, and modify your torrc file accordingly. You will need an HTTP proxy for doing GET requests to fetch the Tor directory, and you will need an HTTPS proxy for doing CONNECT requests to get to Tor relays. (It's fine @@ -1642,7 +1642,7 @@ You can still verify your Tor Browser download by downloading the signature file (.asc) along with your package and <a - href="https://www.torproject.org/docs/verifying-signatures.html.en"> + href="<page docs/verifying-signatures>"> checking the GPG signature</a> as before. We now have an additional verification method that allows you to verify the build as well as the download. @@ -1658,7 +1658,7 @@ <pre>gpg --keyserver keys.mozilla.org --recv-keys 0x29846B3C683686CC</pre> (This will bring you developer Mike Perry's public key. Other developers' key IDs can be found on - <a href="https://www.torproject.org/docs/signing-keys.html.en">this + <a href="<page docs/signing-keys>">this page</a>.)</li> <li>Verify the sha256sums.txt file by executing this command: <pre>gpg --verify <NAME OF THE SIGNATURE FILE>.asc sha256sums.txt</pre></li> @@ -1794,7 +1794,7 @@ </pre> If you've installed <a - href="https://www.torproject.org/projects/obfsproxy-debian-instructions.html.en#i…">Obfsproxy</a>, + href="<page projects/obfsproxy-debian-instructions>#instructions">Obfsproxy</a>, you'll need to add one more line: <pre> @@ -2845,7 +2845,7 @@ for most flaggings are documented on the <a href="https://trac.torproject.org/projects/tor/wiki/doc/badRelays">bad relays wiki</a>. Please <a - href="https://torproject.org/about/contact.html.en">contact us</a> so + href="<page about/contact>">contact us</a> so we can sort out the issue. <hr> @@ -3400,7 +3400,7 @@ <a href="https://exonerator.torproject.org/"> Exonerator</a> is a web service that can check if an IP address was a relay at a given time. We can also <a - href="https://torproject.org/about/contact.html.en">provide a signed + href="<page about/contact>">provide a signed letter</a> if needed. <hr> @@ -3510,7 +3510,7 @@ hidden service?</a></h3> - See the <a href="https://www.torproject.org/docs/tor-hidden-service.html.en"> + See the <a href="<page docs/tor-hidden-service>"> official hidden service configuration instructions</a>. @@ -3838,7 +3838,7 @@ That's where the <a - href="https://torproject.org/projects/torbrowser.html.en">Tor Browser + href="<page projects/torbrowser>">Tor Browser Bundle</a> comes in. We produce a web browser that is preconfigured to help you control the risks to your privacy and anonymity while browsing the Internet. Not only are the above technologies disabled to prevent @@ -4123,7 +4123,7 @@ But since we want to do a lot of work on quality-of-service and better queuing approaches first, you shouldn't expect this change anytime soon (if ever). However if you are keen, there are a couple of -<a href="https://www.torproject.org/getinvolved/volunteer.html.en#Research"> +<a href="<page getinvolved/volunteer>#Research"> research ideas</a> that may involve changing the cell size. @@ -4158,7 +4158,7 @@ We've made quite a bit of progress on this problem lately. You can read more -details on the <a href="https://www.torproject.org/docs/pluggable-transports.html.en"> +details on the <a href="<page docs/pluggable-transports>"> pluggable transports page</a>. You may also be interested in <a href="https://www.youtube.com/watch?v=GwMr8Xl7JMQ">Roger and Jake's talk at 28C3</a>, or <a href="https://www.youtube.com/watch?v=JZg1nqs793M">Runa's @@ -4224,10 +4224,10 @@ minutes, and often more frequently than that. This makes it extremely dificult for websites to create any sort of persistent profile of Tor users (assuming you did not <a - href="https://torproject.org/download/download.html.en#warning">identify + href="<page download/download>#warning">identify yourself in other ways</a>). No one Tor relay can know enough information to compromise any Tor user because of Tor's <a - href="https://www.torproject.org/about/overview.html.en#thesolution">encrypted + href="<page about/overview>#thesolution">encrypted three-hop circuit</a> design.

1 0

r26673: {website} and clean up links in the volunteer page as well (website/trunk/getinvolved/en)
by Roger Dingledine 24 Mar '14

24 Mar '14

Author: arma Date: 2014-03-24 06:57:32 +0000 (Mon, 24 Mar 2014) New Revision: 26673 Modified: website/trunk/getinvolved/en/volunteer.wml Log: and clean up links in the volunteer page as well Modified: website/trunk/getinvolved/en/volunteer.wml =================================================================== --- website/trunk/getinvolved/en/volunteer.wml 2014-03-24 06:55:51 UTC (rev 26672) +++ website/trunk/getinvolved/en/volunteer.wml 2014-03-24 06:57:32 UTC (rev 26673) @@ -977,7 +977,7 @@ Relay operators presently have a couple options for monitoring the status of their relay: <a - href="https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia">Vidalia</a> + href="#project-vidalia">Vidalia</a> which is a gui and <a href="https://www.atagar.com/arm/">arm</a> which uses curses. This project would be to make a new kind of monitor specifically for relay operators that provides a status dashboard site on localhost. @@ -1005,7 +1005,7 @@ This project has the potential for numerous users, one of which is an interface for <a - href="https://www.torproject.org/getinvolved/volunteer.html.en#project-torouter">Torouter</a>. + href="#project-torouter">Torouter</a>. We should check if Torouter has any special use cases or constraints we should take into consideration. @@ -1075,7 +1075,7 @@ Likely Mentors: Steven (sjmurdoch), Ximin (infinity0), George (asn) For Tor users in censored countries, we have a <a - href="https://www.torproject.org/docs/pluggable-transports.html.en"> + href="<page docs/pluggable-transports>"> pluggable transports</a> framework that uses external programs to bypass censorship in different ways. Each of these have their own strengths and weaknesses. @@ -1083,7 +1083,7 @@ We have deployed <a - href="https://www.torproject.org/projects/obfsproxy.html.en">obfsproxy</a> + href="<page projects/obfsproxy>">obfsproxy</a> and <a href="http://crypto.stanford.edu/flashproxy/">flashproxy</a> bridges for a while, accessible using separately-installed pluggable transport clients. Recently, we added this client support to the main Tor Browser @@ -1408,7 +1408,7 @@ <li><a href="https://github.com/guardianproject/orfox">Orfox (gecko prototype)</a></li> <li><a href="https://github.com/guardianproject/orweb">Orweb (production browser on WebView)</a></li> <li><a href="http://starkravingfinkle.org/blog/2013/10/geckoview-embedding-gecko-in-your…">GeckoView info</a></li> - <li><a href="https://www.torproject.org/projects/torbrowser.html.en">Tor Browser (desktop)</a></li> + <li><a href="<page projects/torbrowser>">Tor Browser (desktop)</a></li> </ul>

1 0

r26672: {website} use the <page> tag consistently in the jobs pages too (website/trunk/about/en)
by Roger Dingledine 24 Mar '14

24 Mar '14

Author: arma Date: 2014-03-24 06:55:51 +0000 (Mon, 24 Mar 2014) New Revision: 26672 Modified: website/trunk/about/en/jobs-browserhacker.wml website/trunk/about/en/jobs-extdev.wml website/trunk/about/en/jobs-pluggabletransport.wml Log: use the <page> tag consistently in the jobs pages too Modified: website/trunk/about/en/jobs-browserhacker.wml =================================================================== --- website/trunk/about/en/jobs-browserhacker.wml 2014-03-24 06:54:56 UTC (rev 26671) +++ website/trunk/about/en/jobs-browserhacker.wml 2014-03-24 06:55:51 UTC (rev 26672) @@ -23,7 +23,7 @@ would be a contract position spanning 9-12 months, with the possibility of future continuation. You will also be working closely with our existing browser hackers, and with the new extension developer. If you also have -<a href="https://www.torproject.org/about/jobs-extdev.html.en">extension +<a href="<page about/jobs-extdev>">extension developer</a> experience, please feel free to apply to both positions. Modified: website/trunk/about/en/jobs-extdev.wml =================================================================== --- website/trunk/about/en/jobs-extdev.wml 2014-03-24 06:54:56 UTC (rev 26671) +++ website/trunk/about/en/jobs-extdev.wml 2014-03-24 06:55:51 UTC (rev 26672) @@ -25,7 +25,7 @@ is a contractor position, and may involve working with one or more existing contractors on these projects. You will also be working closely with the new and existing <a -href="https://www.torproject.org/about/jobs-browserhacker.html.en">browser +href="<page about/jobs-browserhacker>">browser hacker</a> positions. If you also have direct C++ hacking experience, feel free to apply to both positions. Modified: website/trunk/about/en/jobs-pluggabletransport.wml =================================================================== --- website/trunk/about/en/jobs-pluggabletransport.wml 2014-03-24 06:54:56 UTC (rev 26671) +++ website/trunk/about/en/jobs-pluggabletransport.wml 2014-03-24 06:55:51 UTC (rev 26672) @@ -76,9 +76,9 @@ <li> Know about Tor -<a href="https://www.torproject.org/docs/pluggable-transports.html.en">pluggable +<a href="<page docs/pluggable-transports>">pluggable transports</a> and their -<a href="https://gitweb.torproject.org/torspec.git/blob/HEAD:/pt-spec.txt">specification</a>. +<a href="<specblob>pt-spec.txt">specification</a>. </li> <li>

1 0

r26671: {website} use the <page> tag consistently in the download pages too (website/trunk/download/en)
by Roger Dingledine 24 Mar '14

24 Mar '14

Author: arma Date: 2014-03-24 06:54:56 +0000 (Mon, 24 Mar 2014) New Revision: 26671 Modified: website/trunk/download/en/download-easy.wml website/trunk/download/en/download.wml Log: use the <page> tag consistently in the download pages too Modified: website/trunk/download/en/download-easy.wml =================================================================== --- website/trunk/download/en/download-easy.wml 2014-03-24 06:49:34 UTC (rev 26670) +++ website/trunk/download/en/download-easy.wml 2014-03-24 06:54:56 UTC (rev 26671) @@ -233,7 +233,7 @@ <li>Use HTTPS versions of websites Tor will encrypt your traffic <a -href="https://www.torproject.org/about/overview.html.en#thesolution">to +href="<page overview>#thesolution">to and within the Tor network</a>, but the encryption of your traffic to the final destination website depends upon on that website. To help ensure private encryption to websites, the Tor Browser Bundle includes @@ -295,7 +295,7 @@ <li class="dropdown"><a href="#windows">Microsoft Windows</a></li> <li class="dropdown"><a href="#mac">Apple OS X</a></li> <li class="dropdown"><a href="#linux">Linux/Unix</a></li> -<li class="dropdown"><a href="../download/download.html.en">All Downloads</a></li> +<li class="dropdown"><a href="<page download/download>">All Downloads</a></li> </ul> </div> </div> Modified: website/trunk/download/en/download.wml =================================================================== --- website/trunk/download/en/download.wml 2014-03-24 06:49:34 UTC (rev 26670) +++ website/trunk/download/en/download.wml 2014-03-24 06:54:56 UTC (rev 26671) @@ -317,7 +317,7 @@ Tor will encrypt your traffic -<a href="https://www.torproject.org/about/overview.html.en#thesolution">to and +<a href="<page overview>#thesolution">to and within the Tor network</a>, but the encryption of your traffic to the final destination website depends upon on that website. To help ensure private encryption to websites, the Tor Browser Bundle includes <a

1 0

r26670: {website} use the <page> tag to resume working on website mirrors (website/trunk/projects/en)
by Roger Dingledine 24 Mar '14

24 Mar '14

Author: arma Date: 2014-03-24 06:49:34 +0000 (Mon, 24 Mar 2014) New Revision: 26670 Modified: website/trunk/projects/en/obfsproxy-debian-instructions.wml website/trunk/projects/en/obfsproxy.wml Log: use the <page> tag to resume working on website mirrors Modified: website/trunk/projects/en/obfsproxy-debian-instructions.wml =================================================================== --- website/trunk/projects/en/obfsproxy-debian-instructions.wml 2014-03-24 03:26:26 UTC (rev 26669) +++ website/trunk/projects/en/obfsproxy-debian-instructions.wml 2014-03-24 06:49:34 UTC (rev 26670) @@ -22,7 +22,7 @@ <img width="7%" height="7%" style="float: left;" src="$(IMGROOT)/icon-Obfsproxy.jpg"> Hey! If you are not using Debian or Ubuntu, you better look - <a href="../projects/obfsproxy-instructions.html.en">at this other guide</a> + <a href="<page projects/obfsproxy-instructions>">at this other guide</a> which sets up Obfsproxy from source. Modified: website/trunk/projects/en/obfsproxy.wml =================================================================== --- website/trunk/projects/en/obfsproxy.wml 2014-03-24 03:26:26 UTC (rev 26669) +++ website/trunk/projects/en/obfsproxy.wml 2014-03-24 06:49:34 UTC (rev 26670) @@ -71,7 +71,7 @@ As of Tor Browser 3.6-beta-1, obfsproxy is now included in the <a -href="https://www.torproject.org/projects/torbrowser.html.en#downloads-beta">official +href="<page projects/torbrowser>#downloads-beta">official Tor Browser packages</a>.

1 0

[tor/master] quiet the debug message in circuit_build_times_disabled()
by arma＠torproject.org 24 Mar '14

24 Mar '14

commit 85ef58e5ba4f9678981242e1a1ee581798b0531d Author: Roger Dingledine <arma(a)torproject.org> Date: Mon Mar 24 02:31:13 2014 -0400 quiet the debug message in circuit_build_times_disabled() something recently made it get called once per second, which will clutter up your debug log file. --- src/or/circuitstats.c | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/or/circuitstats.c b/src/or/circuitstats.c index eaefc9e..c093ecd 100644 --- a/src/or/circuitstats.c +++ b/src/or/circuitstats.c @@ -94,18 +94,22 @@ circuit_build_times_disabled(void) if (consensus_disabled || config_disabled || dirauth_disabled || state_disabled) { +#if 0 log_debug(LD_CIRC, "CircuitBuildTime learning is disabled. " "Consensus=%d, Config=%d, AuthDir=%d, StateFile=%d", consensus_disabled, config_disabled, dirauth_disabled, state_disabled); +#endif return 1; } else { +#if 0 log_debug(LD_CIRC, "CircuitBuildTime learning is not disabled. " "Consensus=%d, Config=%d, AuthDir=%d, StateFile=%d", consensus_disabled, config_disabled, dirauth_disabled, state_disabled); +#endif return 0; } }

1 0

[stem/master] Minor tutorial revisions
by atagar＠torproject.org 24 Mar '14

24 Mar '14

commit 4b667d253258bc0363c82e81d0689fc0eff416e9 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Mar 23 16:03:19 2014 -0700 Minor tutorial revisions Took a quick read through our tutorials. Just minor reordering and rewording. --- docs/tutorials/mirror_mirror_on_the_wall.rst | 57 +++++++++++++------------- docs/tutorials/to_russia_with_love.rst | 2 +- stem/control.py | 2 +- 3 files changed, 31 insertions(+), 30 deletions(-) diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst index a14e050..918417b 100644 --- a/docs/tutorials/mirror_mirror_on_the_wall.rst +++ b/docs/tutorials/mirror_mirror_on_the_wall.rst @@ -6,8 +6,8 @@ with what they are and where to get them then you may want to skip to the end. * :ref:`what-is-a-descriptor` * :ref:`where-can-i-get-the-current-descriptors` -* :ref:`can-i-get-descriptors-from-tor` * :ref:`where-can-i-get-past-descriptors` +* :ref:`can-i-get-descriptors-from-the-tor-process` * :ref:`putting-it-together` .. _what-is-a-descriptor: @@ -38,7 +38,7 @@ 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 download it like -tor does*. +Tor does*. The `stem.descriptor.remote <../api/descriptor/remote.html>`_ module downloads descriptors from the tor directory authorities and mirrors. **Please show @@ -59,12 +59,29 @@ Listing the current relays in the Tor network is as easy as... except Exception as exc: print "Unable to retrieve the consensus: %s" % exc -.. _can-i-get-descriptors-from-tor: +.. _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) + +.. _can-i-get-descriptors-from-the-tor-process: -Can I get descriptors from Tor? -------------------------------- +Can I get descriptors from the Tor process? +------------------------------------------- -If you already have Tor running on your system then it is already getting +If you already have Tor running on your system then it is already downloading descriptors on your behalf. Reusing these is a great way to keep from burdening the rest of the Tor network. @@ -102,7 +119,7 @@ the network! DownloadExtraInfo 1 -Now that Tor is happy chugging along up-to-date descriptors are available +Now that Tor is happy chugging along, up-to-date descriptors are available through Tor's control socket... :: @@ -124,33 +141,17 @@ through Tor's control socket... 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... +As discussed above there are four 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. +* Download descriptors directly with `stem.descriptor.remote <../api/descriptor/remote.html>`_. +* Read a single file with :func:`~stem.descriptor.__init__.parse_file`. +* Read multiple files or an archive with the `DescriptorReader <../api/descriptor/reader.html>`_. +* Requesting them from Tor with :class:`~stem.control.Controller` methods like :func:`~stem.control.Controller.get_server_descriptors` and :func:`~stem.control.Controller.get_network_statuses`. 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 diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst index c928c00..e69e828 100644 --- a/docs/tutorials/to_russia_with_love.rst +++ b/docs/tutorials/to_russia_with_love.rst @@ -19,7 +19,7 @@ Tor relays are scattered all over the world and, as such, you can pretend to be 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 `SocksiPy <http://socksipy.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once. +In the following example we're using Stem to `start Tor <../api/process.html>`_, then read a site through it with `SocksiPy <http://socksipy.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 there may be edge cases that expose your real IP. If you have a suggestion for how to improve this example then please `let me know <https://www.atagar.com/contact/>`_! diff --git a/stem/control.py b/stem/control.py index 8ea9fe7..bf86135 100644 --- a/stem/control.py +++ b/stem/control.py @@ -1482,7 +1482,7 @@ class Controller(BaseController): :param list default: items to provide if the query fails :returns: iterates over - :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for + :class:`~stem.descriptor.router_status_entry.RouterStatusEntry` for relays in the tor network :raises: :class:`stem.ControllerError` if unable to query tor and no

1 0

[stem/master] Improving our FAQ and making entries more succinct
by atagar＠torproject.org 24 Mar '14

24 Mar '14

commit 8680265c7e27f1c9bb8c18ca96b1b204f3013003 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Mar 23 22:32:59 2014 -0700 Improving our FAQ and making entries more succinct Reordering and rewording our FAQ. This moves examples for the 'How do I connect to Tor?' examples to their respective modules to both make the FAQ entry more readable, and the modules more informative. This also dropped the "How do I get information about my exits?" FAQ entry since it's largely redundant with the 'Determine The Exit You’re Using' example in our tutorials. --- docs/faq.rst | 412 +++++++++++++++++++++------------------------------- stem/connection.py | 27 ++++ stem/control.py | 62 +++++++- stem/socket.py | 42 +++++- 4 files changed, 286 insertions(+), 257 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index cb70ba5..872e5b5 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -6,16 +6,15 @@ Frequently Asked Questions * :ref:`what_is_stem` * :ref:`does_stem_have_any_dependencies` * :ref:`what_python_versions_is_stem_compatible_with` - * :ref:`what_license_is_stem_under` - * :ref:`are_there_any_other_controller_libraries` * :ref:`can_i_interact_with_tors_controller_interface_directly` + * :ref:`are_there_any_other_controller_libraries` + * :ref:`what_license_is_stem_under` * :ref:`where_can_i_get_help` * **Usage** * :ref:`how_do_i_connect_to_tor` * :ref:`how_do_i_request_a_new_identity_from_tor` - * :ref:`how_do_i_get_information_about_my_exits` * :ref:`how_do_i_reload_my_torrc` * :ref:`what_is_that_with_keyword_i_keep_seeing_in_the_tutorials` @@ -45,61 +44,48 @@ Does Stem have any dependencies? **No.** All you need in order to use Stem is Python. -When it is available Stem will use `pycrypto <https://www.dlitz.net/software/pycrypto/>`_ to validate descriptor signatures. However, there is no need to install pycrypto unless you need this functionality. +When it is available Stem will use `pycrypto +<https://www.dlitz.net/software/pycrypto/>`_ to validate descriptor signatures. +However, there is no need to install pycrypto unless you need this +functionality. .. _what_python_versions_is_stem_compatible_with: What Python versions is Stem compatible with? --------------------------------------------- -Stem works with **Python 2.6 and greater**. This includes the Python 3.x series by installing Stem via python3 (see our `installation instructions <https://pypi.python.org/pypi/stem/>`_ for more information). - -.. _what_license_is_stem_under: - -What license is Stem under? ---------------------------- - -Stem is under the `LGPLv3 <https://www.gnu.org/licenses/lgpl>`_. - -.. _are_there_any_other_controller_libraries: - -Are there any other controller libraries? ------------------------------------------ - -Yup. The most mature controller libraries are written in Python, but there's a few options in other languages as well. By far the most mature alternative to Stem are `Txtorcon <https://txtorcon.readthedocs.org/>`_ and `TorCtl <https://gitweb.torproject.org/pytorctl.git>`_. - -`Txtorcon <https://txtorcon.readthedocs.org/>`_ is an actively maintained controller library written by Meejah for `Twisted <https://twistedmatrix.com/trac/>`_. In the future we plan to `integrate Stem and Txtorcon <https://www.torproject.org/getinvolved/volunteer.html.en#txtorcon-stemInteg…>`_ to some degree, but that is still a ways off. - -`TorCtl <https://gitweb.torproject.org/pytorctl.git>`_ was Stem's predecessor and `deprecated in December 2012 <https://blog.torproject.org/blog/torctl-deprecation-and-stem-plans>`_ in favor of Stem. Though no longer actively developed, it's still quite functional and still used for several `TorFlow <https://gitweb.torproject.org/torflow.git>`_ based projects. - -The following are the functional controller libraries I'm aware of. Dates are for highly active development. If I missed one then please `let me know <https://www.atagar.com/contact/>`_! - -========================================================== ================ ======================= -Library Language Developed -========================================================== ================ ======================= -`Stem <https://stem.torproject.org/>`_ Python October 2011 - Present -`Txtorcon <https://txtorcon.readthedocs.org/>`_ Python (Twisted) February 2012 - Present -`TorCtl <https://gitweb.torproject.org/pytorctl.git>`_ Python July 2008 - November 2011 -`PHP TorCtl <https://github.com/dunglas/php-torcontrol/>`_ PHP February 2013 -`JTorCtl <https://gitweb.torproject.org/jtorctl.git>`_ Java June 2005 - May 2009 -========================================================== ================ ======================= +Stem works with **Python 2.6 and greater**. This includes the Python 3.x series +by installing Stem via python3 (see our `installation instructions +<https://pypi.python.org/pypi/stem/>`_ for more information). .. _can_i_interact_with_tors_controller_interface_directly: Can I interact with Tor's controller interface directly? -------------------------------------------------------- -Yup. You don't need a library to interact with Tor's `controller interface <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_, and interacting with it directly is a great way of learning about what it can do. The exact details for how you connect to Tor depend on two things... +Yup. You don't need a library to interact with Tor's `controller interface +<https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_, and +interacting with it directly is a great way to learn about what it can do. The +exact details for how you connect to Tor depend on two things... -* Where is Tor listening for controller connections? This is specified by either the **ControlPort** or **ControlSocket** option in your torrc. If you have neither then Tor will not accept controller connections. -* What type of authentication is Tor's controller interface using? This is defined by your **CookieAuthentication** or **HashedControlPassword** option. If you have neither then Tor does not restrict access. +* Where is Tor listening for controller connections? This is specified by + either the **ControlPort** or **ControlSocket** option in your torrc. If you + have neither then Tor will not accept controller connections. + +* What type of authentication is Tor's controller interface using? This is + defined by your **CookieAuthentication** or **HashedControlPassword** option. + If you have neither then Tor does not restrict access. We'll tackle each of these scenarios one at a time... **I'm using a ControlPort** ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you are using a **ControlPort** then the easiest method of talking with Tor is via **telnet**. You always need to authenticate after connecting, even if Tor does not restrict access. If your torrc doesn't have a **CookieAuthentication** or **HashedControlPassword** then to authenticate you will simply call **AUTHENTICATE** after connecting without any credentials. +If you are using a **ControlPort** then the easiest method of talking with Tor +is via **telnet**. You always need to authenticate after connecting, even if +Tor does not restrict access. If your torrc doesn't have a +**CookieAuthentication** or **HashedControlPassword** then to authenticate you +will simply call **AUTHENTICATE** after connecting without any credentials. :: @@ -122,7 +108,8 @@ If you are using a **ControlPort** then the easiest method of talking with Tor i **I'm using a ControlSocket** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -A **ControlSocket** is a file based socket, so we'll use **socat** to connect to it... +A **ControlSocket** is a file based socket, so we'll use **socat** to connect +to it... :: @@ -141,7 +128,10 @@ A **ControlSocket** is a file based socket, so we'll use **socat** to connect to **I'm using cookie authentication** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Cookie authentication simply means that your credential is the content of a file in Tor's **DataDirectory**. You can learn information about Tor's method of authentication (including the cookie file's location) by calling **PROTOCOLINFO**... +Cookie authentication simply means that your credential is the content of a +file in Tor's **DataDirectory**. You can learn information about Tor's method +of authentication (including the cookie file's location) by calling +**PROTOCOLINFO**... :: @@ -159,7 +149,10 @@ Cookie authentication simply means that your credential is the content of a file 250-VERSION Tor="0.2.5.1-alpha-dev" 250 OK -Cookie authentication has two flavors: **COOKIE** and **SAFECOOKIE**. Below we'll show you how to authenticate via COOKIE. SAFECOOKIE authentication is a lot more involved, and not something you will want to do by hand (though Stem supports it transparently). +Cookie authentication has two flavors: **COOKIE** and **SAFECOOKIE**. Below +we'll show you how to authenticate via COOKIE. SAFECOOKIE authentication is a +lot more involved, and not something you will want to do by hand (though Stem +supports it transparently). To get the credential for your AUTHENTICATE command we will use **hexdump**... @@ -184,7 +177,8 @@ To get the credential for your AUTHENTICATE command we will use **hexdump**... **I'm using password authentication** ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Tor's other method of authentication is a credential you know. To use it ask Tor to hash your password, then use that in your torrc... +Tor's other method of authentication is a credential you know. To use it ask +Tor to hash your password, then use that in your torrc... :: @@ -212,12 +206,60 @@ Authenticating with this simply involves giving Tor the credential... 250 closing connection Connection closed by foreign host. +.. _are_there_any_other_controller_libraries: + +Are there any other controller libraries? +----------------------------------------- + +Yup. The most mature controller libraries are written in Python, but there's a +few options in other languages as well. By far the most mature alternative to +Stem are `Txtorcon <https://txtorcon.readthedocs.org/>`_ and `TorCtl +<https://gitweb.torproject.org/pytorctl.git>`_. + +`Txtorcon <https://txtorcon.readthedocs.org/>`_ is an actively maintained +controller library written by Meejah for `Twisted +<https://twistedmatrix.com/trac/>`_. In the future we plan to `integrate Stem +and Txtorcon +<https://www.torproject.org/getinvolved/volunteer.html.en#txtorcon-stemInteg…>`_ +to some degree, but that is still a ways off. + +`TorCtl <https://gitweb.torproject.org/pytorctl.git>`_ was Stem's predecessor +and `deprecated in December 2012 +<https://blog.torproject.org/blog/torctl-deprecation-and-stem-plans>`_ in favor +of Stem. Though no longer actively developed, it's still quite functional and +still used for several `TorFlow <https://gitweb.torproject.org/torflow.git>`_ +based projects. + +The following are the functional controller libraries I'm aware of. Dates are +for highly active development. If I missed one then please `let me know +<https://www.atagar.com/contact/>`_! + +========================================================== ================ ======================= +Library Language Developed +========================================================== ================ ======================= +`Stem <https://stem.torproject.org/>`_ Python October 2011 - Present +`Txtorcon <https://txtorcon.readthedocs.org/>`_ Python (Twisted) February 2012 - Present +`TorCtl <https://gitweb.torproject.org/pytorctl.git>`_ Python July 2008 - November 2011 +`PHP TorCtl <https://github.com/dunglas/php-torcontrol/>`_ PHP February 2013 +`JTorCtl <https://gitweb.torproject.org/jtorctl.git>`_ Java June 2005 - May 2009 +========================================================== ================ ======================= + +.. _what_license_is_stem_under: + +What license is Stem under? +--------------------------- + +Stem is under the `LGPLv3 <https://www.gnu.org/licenses/lgpl>`_. + .. _where_can_i_get_help: Where can I get help? --------------------- -Do you have a Tor related question or project that you would like to discuss? If so then find us on the `tor-dev@ email list <https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev>`_ and `IRC <https://www.torproject.org/about/contact.html.en#irc>`_. +Do you have a Tor related question or project that you would like to discuss? +If so then find us on the `tor-dev@ email list +<https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev>`_ and `IRC +<https://www.torproject.org/about/contact.html.en#irc>`_. Usage ===== @@ -229,131 +271,39 @@ How do I connect to Tor? Once you have Tor running and `properly configured <tutorials/the_little_relay_that_could.html>`_ you have a few ways of connecting to it. The following are the most common methods for getting a :class:`~stem.control.Controller` instance, from the highest to lowest level... -#. :func:`stem.connection.connect_port` and :func:`stem.connection.connect_socket_file` - - Writing a commandline script? Then the `connection module <api/connection.html>`_ provide you the quickest and most hassle free method for getting a :class:`~stem.control.Controller`. - - These functions connect and authenticate to the given port or socket, providing you with a :class:`~stem.control.Controller` that's ready to use. If Tor requires a password then the user will be prompted for it. When the connection cannot be established this prints a description of the problem to stdout then returns **None**. - - For instance... - - :: - - import sys - - from stem.connection import connect_port +#. `Connection Module <api/connection.html>`_ - if __name__ == '__main__': - controller = connect_port() + Writing a commandline script? Then the :func:`~stem.connection.connect_port` + and :func:`~stem.connection.connect_socket_file` functions provide you the + quickest and most hassle free method for getting a + :class:`~stem.control.Controller`. - if not controller: - sys.exit(1) # unable to get a connection + These functions connect and authenticate to the given port or socket, + providing you a one-line method of getting a + :class:`~stem.control.Controller` that's ready to use. If Tor requires a + password then the user will be prompted for it. When the connection cannot + be established this prints a description of the problem to stdout and + returns **None**. - print "Tor is running version %s" % controller.get_version() - controller.close() +#. `Control Module <api/control.html>`_ - :: + The connection module helpers above are all well and good when you need a + quick-and-dirty connection for your commandline script, but they're + inflexible. In particular their lack of exceptions and direct use of + stdin/stdout make them undesirable for more complicated situations. That's + where the Controller's :func:`~stem.control.Controller.from_port` and + :func:`~stem.control.Controller.from_socket_file` methods come in. - % python example.py - Tor is running version 0.2.4.10-alpha-dev (git-8be6058d8f31e578) - - ... or if Tor isn't running... - - :: - - % python example.py - [Errno 111] Connection refused - -#. :func:`stem.control.Controller.from_port` and :func:`stem.control.Controller.from_socket_file` - - The connection module helpers above are all well and good when you need a quick-and-dirty connection for your commandline script, but they're inflexible. In particular their lack of exceptions and direct use of stdin/stdout make them undesirable for more complicated situations. That's where the Controller's :func:`~stem.control.Controller.from_port` and :func:`~stem.control.Controller.from_socket_file` methods come in. - - These static :class:`~stem.control.Controller` methods return an **unauthenticated** controller you can then authenticate yourself using its :func:`~stem.control.Controller.authenticate` method. - - For instance... - - :: - - import getpass - import sys - - import stem - import stem.connection - - from stem.control import Controller - - if __name__ == '__main__': - try: - controller = Controller.from_port() - except stem.SocketError as exc: - print "Unable to connect to tor on port 9051: %s" % exc - sys.exit(1) - - try: - controller.authenticate() - except stem.connection.MissingPassword: - pw = getpass.getpass("Controller password: ") - - try: - controller.authenticate(password = pw) - except stem.connection.PasswordAuthFailed: - print "Unable to authenticate, password is incorrect" - sys.exit(1) - except stem.connection.AuthenticationFailure as exc: - print "Unable to authenticate: %s" % exc - sys.exit(1) - - print "Tor is running version %s" % controller.get_version() - controller.close() - - If you're fine with allowing your script to raise exceptions then this can be more nicely done as... - - :: - - from stem.control import Controller - - if __name__ == '__main__': - with Controller.from_port() as controller: - controller.authenticate() - - print "Tor is running version %s" % controller.get_version() + These provide the most flexible method of connecting to Tor, and for + sophisticated applications is what you'll want. #. `Socket Module <api/socket.html>`_ - For the diehards among us you can skip the conveniences of a high level :class:`~stem.control.Controller` and work directly with the raw components. At Stem's lowest level your connection with Tor is a :class:`~stem.socket.ControlSocket` subclass. This provides methods to send, receive, disconnect, and reconnect to Tor. - - One level up is the :class:`~stem.control.BaseController`. This wraps the :class:`~stem.socket.ControlSocket` and provides a :func:`~stem.control.BaseController.msg` method so you can send messages and receive their reply in a thread safe manner. Finally comes the :class:`~stem.control.Controller`, which extends :class:`~stem.control.BaseController` to provide more user friendly methods. - - Directly using the :class:`~stem.socket.ControlSocket` is unsafe when it's being managed through a :class:`~stem.control.BaseController`, but if you're interested in dealing with lower level components directly then that is certainly an option... - - :: - - import stem - import stem.connection - import stem.socket - - if __name__ == '__main__': - try: - control_socket = stem.socket.ControlPort(port = 9051) - stem.connection.authenticate(control_socket) - except stem.SocketError as exc: - print "Unable to connect to tor on port 9051: %s" % exc - sys.exit(1) - except stem.connection.AuthenticationFailure as exc: - print "Unable to authenticate: %s" % exc - sys.exit(1) - - print "Issuing 'GETINFO version' query...\n" - control_socket.send('GETINFO version') - print control_socket.recv() - - :: - - % python example.py - Issuing 'GETINFO version' query... - - version=0.2.4.10-alpha-dev (git-8be6058d8f31e578) - OK + For the diehards among us you can skip the conveniences of a high level + :class:`~stem.control.Controller` and work directly with the raw components. + At Stem's lowest level your connection with Tor is a + :class:`~stem.socket.ControlSocket` subclass. This provides methods to send, + receive, disconnect, and reconnect to Tor. .. _how_do_i_request_a_new_identity_from_tor: @@ -394,61 +344,6 @@ And with Stem... controller.authenticate() controller.signal(Signal.NEWNYM) -For lower level control over Tor's circuits and path selection see the `client usage tutorial <tutorials/to_russia_with_love.html>`_. - -.. _how_do_i_get_information_about_my_exits: - -How do I get information about my exits? ----------------------------------------- - -To learn about the Tor relays you're presently using call :func:`~stem.control.Controller.get_circuits`. The last relay in the circuit's path is your exit... - -:: - - from stem import CircStatus - from stem.control import Controller - - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - for circ in controller.get_circuits(): - if circ.status != CircStatus.BUILT: - continue - - exit_fp, exit_nickname = circ.path[-1] - - exit_desc = controller.get_network_status(exit_fp, None) - exit_address = exit_desc.address if exit_desc else 'unknown' - - print "Exit relay" - print " fingerprint: %s" % exit_fp - print " nickname: %s" % exit_nickname - print " address: %s" % exit_address - print - -:: - - % python example.py - Exit relay - fingerprint: 94AD3437EC49A31E8D6C17CC3BDE8316C90262BE - nickname: davidonet - address: 188.165.236.209 - - Exit relay - fingerprint: 6042CC1C69BBFE83A1DD2BCD4C15000A0DD5E1BC - nickname: Gnome5 - address: 178.209.50.230 - - Exit relay - fingerprint: 9634F910C2942A2E46720DD161A873E3A619AD90 - nickname: veebikaamera - address: 81.21.246.66 - - Exit relay - fingerprint: A59E1E7C7EAEE083D756EE1FF6EC31CA3D8651D7 - nickname: chaoscomputerclub19 - address: 31.172.30.2 - .. _how_do_i_reload_my_torrc: How do I reload my torrc? @@ -473,7 +368,9 @@ Tor is configured through its `torrc <https://www.torproject.org/docs/faq.html.e What is that 'with' keyword I keep seeing in the tutorials? ----------------------------------------------------------- -Python's '**with**' keyword is shorthand for a try/finally block. With a :class:`~stem.control.Controller` the following... +Python's `with <http://effbot.org/zone/python-with-statement.htm>`_ keyword +is shorthand for a try/finally block. With a :class:`~stem.control.Controller` +the following... :: @@ -491,7 +388,11 @@ Python's '**with**' keyword is shorthand for a try/finally block. With a :class: finally: controller.close() -This helps to make sure that regardless of if your code raises an exception or not the control connection will be cleaned up afterward. Note that this means that if you leave the 'with' scope your :class:`~stem.control.Controller` will be closed. For instance... +This helps to make sure that regardless of if your code raises an exception or +not the control connection will be cleaned up afterward. Note that this means +that if you leave the 'with' scope your :class:`~stem.control.Controller` will +be closed. The following for instance is a bug common when first learning +Stem... :: @@ -510,25 +411,11 @@ This helps to make sure that regardless of if your code raises an exception or n reporter = BandwidthReporter(controller) # The following line is broken because the 'controller' we initialised - # above was disconnected once we left the 'with' scope. + # above was disconnected once we left the 'with' scope. To fix this the + # print_bandwidth() call should be in the 'with' block. reporter.print_bandwidth() -To fix this we could either move the print_bandwidth() call into the 'with' scope, or simply avoid using 'with' all together... - -:: - - if __name__ == '__main__': - controller = Controller.from_port(port = 9051) - - try: - reporter = BandwidthReporter(controller) - reporter.print_bandwidth() - finally: - controller.close() - -For more information about the 'with' keyword see `here <http://effbot.org/zone/python-with-statement.htm>`_. - Development =========== @@ -537,15 +424,19 @@ Development How do I get started? --------------------- -The best way of getting involved with any project is to jump right in! Our `bug tracker <https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs>`_ lists several development tasks. In particular look for the 'easy' keyword when getting started. - -If you have any questions then I'm always more than happy to help (I'm **atagar** on `oftc <http://www.oftc.net/oftc/>`_ and also available `via email <https://www.atagar.com/contact/>`_). +The best way of getting involved with any project is to jump right in! Our `bug +tracker <https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs>`_ lists +several development tasks. In particular look for the 'easy' keyword when +getting started. If you have any questions then I'm always more than happy to +help! I'm **atagar** on `oftc <http://www.oftc.net/oftc/>`_ and also available +`via email <https://www.atagar.com/contact/>`_. -To start hacking on Stem please do the following and don't hesitate to let me know if you get stuck or would like to discuss anything! +To start hacking on Stem please do the following and don't hesitate to let me +know if you get stuck or would like to discuss anything! -1. Clone our `git <http://git-scm.com/>`_ repository: **git clone https://git.torproject.org/stem.git** -2. Find a `bug or feature <https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs>`_ that sounds interesting. -3. When you have something that you would like to contribute back do the following... +#. Clone our `git <http://git-scm.com/>`_ repository: **git clone https://git.torproject.org/stem.git** +#. Find a `bug or feature <https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs>`_ that sounds interesting. +#. When you have something that you would like to contribute back do the following... * If you don't already have a publicly accessible Stem repository then set one up. `GitHub <https://github.com/>`_ in particular is great for this. * File a `trac ticket <https://trac.torproject.org/projects/tor/newticket>`_, the only fields you'll need are... @@ -565,14 +456,20 @@ How do I run the tests? Stem has three kinds of tests: **unit**, **integration**, and **static**. -**Unit** tests are our most frequently ran tests. They're quick, they're easy, and provide good test coverage... +**Unit** tests are our most frequently ran tests. They're quick, they're easy, +and provide good test coverage... :: ~$ cd stem/ ~/stem$ ./run_tests.py --unit -**Integration** tests start a live Tor instance and test against that. This not only provides additional test coverage, but lets us check our continued interoperability with new releases of Tor. Running these require that you have `Tor installed <https://www.torproject.org/download/download.html.en>`_. You can exercise alternate Tor configurations with the ``--target`` argument (see ``run_tests.py --help`` for a list of its options). +**Integration** tests start a live Tor instance and test against that. This not +only provides additional test coverage, but lets us check our continued +interoperability with new releases of Tor. Running these require that you have +`Tor installed <https://www.torproject.org/download/download.html.en>`_. You +can exercise alternate Tor configurations with the ``--target`` argument (see +``run_tests.py --help`` for a list of its options). :: @@ -580,9 +477,14 @@ Stem has three kinds of tests: **unit**, **integration**, and **static**. ~/stem$ ./run_tests.py --integ --tor /path/to/tor ~/stem$ ./run_tests.py --integ --target RUN_COOKIE -**Static** tests use `pyflakes <https://launchpad.net/pyflakes>`_ to do static error checking and `pep8 <http://pep8.readthedocs.org/en/latest/>`_ for style checking. If you have them installed then they automatically take place as part of all test runs. +**Static** tests use `pyflakes <https://launchpad.net/pyflakes>`_ to do static +error checking and `pep8 <http://pep8.readthedocs.org/en/latest/>`_ for style +checking. If you have them installed then they automatically take place as part +of all test runs. -If you have **Python 3** installed then you can test our Python 3 compatibility with the following. *Note that need to still initially execute run_tests.py with a 2.x version of Python.* +If you have **Python 3** installed then you can test our Python 3 compatibility +with the following. *Note that need to still initially execute run_tests.py +with a 2.x version of Python.* :: @@ -595,14 +497,16 @@ See ``run_tests.py --help`` for more usage information. How do I build the site? ------------------------ -If you have `sphinx <http://sphinx-doc.org/>`_ version 1.1 or later installed then building our site is as easy as... +If you have `Sphinx <http://sphinx-doc.org/>`_ version 1.1 or later installed +then building our site is as easy as... :: ~$ cd stem/docs ~/stem/docs$ make html -When it's finished you can direct your browser to the *_build* directory with a URI similar to... +When it's finished you can direct your browser to the *_build* directory with a +URI similar to... :: @@ -613,7 +517,15 @@ When it's finished you can direct your browser to the *_build* directory with a What is the copyright for patches? ---------------------------------- -Stem is under the LGPLv3 which is a fine license, but poses a bit of a problem for sharing code with our other projects (which are mostly BSD). To share code without needing to hunt down prior contributors we need Tor to have the copyright for the whole Stem codebase. Presently the copyright of Stem is jointly held by its main author (`Damian <https://www.atagar.com/>`_) and the `Tor Project <https://www.torproject.org/>`_. - -If you submit a substantial patch I'll ask if you're fine with it being in the public domain. This would mean that there are no legal restrictions for using your contribution, and hence won't pose a problem if we reuse Stem code in other projects. +Stem is under the LGPLv3 which is a fine license, but poses a bit of a problem +for sharing code with our other projects (which are mostly BSD). To share code +without needing to hunt down prior contributors we need Tor to have the +copyright for the whole Stem codebase. Presently the copyright of Stem is +jointly held by its main author (`Damian <https://www.atagar.com/>`_) and the +`Tor Project <https://www.torproject.org/>`_. + +If you submit a substantial patch I'll ask if you're fine with it being in the +public domain. This would mean that there are no legal restrictions for using +your contribution, and hence won't pose a problem if we reuse Stem code in +other projects. diff --git a/stem/connection.py b/stem/connection.py index 82ad25b..769f432 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -11,6 +11,33 @@ applications and the python interactive interpreter, but does several things that makes it undesirable for applications (uses stdin/stdout, suppresses exceptions, etc). +:: + + import sys + + from stem.connection import connect_port + + if __name__ == '__main__': + controller = connect_port() + + if not controller: + sys.exit(1) # unable to get a connection + + print "Tor is running version %s" % controller.get_version() + controller.close() + +:: + + % python example.py + Tor is running version 0.2.4.10-alpha-dev (git-8be6058d8f31e578) + +... or if Tor isn't running... + +:: + + % python example.py + [Errno 111] Connection refused + The :func:`~stem.connection.authenticate` function, however, gives easy but fine-grained control over the authentication process. For instance... diff --git a/stem/control.py b/stem/control.py index bf86135..ddcc5df 100644 --- a/stem/control.py +++ b/stem/control.py @@ -2,11 +2,65 @@ # See LICENSE for licensing information """ -Classes for interacting with the tor control socket. +Module for interacting with the Tor control socket. The +:class:`~stem.control.Controller` is a wrapper around a +:class:`~stem.socket.ControlSocket`, retaining many of its methods (connect, +close, is_alive, etc) in addition to providing its own for working with the +socket at a higher level. + +Stem has `several ways <../faq.html#how-do-i-connect-to-tor>`_ of getting a +:class:`~stem.control.Controller`, but the most flexible are +:func:`~stem.control.Controller.from_port` and +:func:`~stem.control.Controller.from_socket_file`. These static +:class:`~stem.control.Controller` methods give you an **unauthenticated** +Controller you can then authenticate yourself using its +:func:`~stem.control.Controller.authenticate` method. For example... -Controllers are a wrapper around a :class:`~stem.socket.ControlSocket`, -retaining many of its methods (connect, close, is_alive, etc) in addition to -providing its own for interacting at a higher level. +:: + + import getpass + import sys + + import stem + import stem.connection + + from stem.control import Controller + + if __name__ == '__main__': + try: + controller = Controller.from_port() + except stem.SocketError as exc: + print "Unable to connect to tor on port 9051: %s" % exc + sys.exit(1) + + try: + controller.authenticate() + except stem.connection.MissingPassword: + pw = getpass.getpass("Controller password: ") + + try: + controller.authenticate(password = pw) + except stem.connection.PasswordAuthFailed: + print "Unable to authenticate, password is incorrect" + sys.exit(1) + except stem.connection.AuthenticationFailure as exc: + print "Unable to authenticate: %s" % exc + sys.exit(1) + + print "Tor is running version %s" % controller.get_version() + controller.close() + +If you're fine with allowing your script to raise exceptions then this can be more nicely done as... + +:: + + from stem.control import Controller + + if __name__ == '__main__': + with Controller.from_port() as controller: + controller.authenticate() + + print "Tor is running version %s" % controller.get_version() **Module Overview:** diff --git a/stem/socket.py b/stem/socket.py index dfdce08..cb74f21 100644 --- a/stem/socket.py +++ b/stem/socket.py @@ -2,9 +2,45 @@ # See LICENSE for licensing information """ -Supports message based communication with sockets speaking the tor control -protocol. This lets users send messages as basic strings and receive responses -as instances of the :class:`~stem.response.ControlMessage` class. +Supports communication with sockets speaking the Tor control protocol. This +allows us to send messages as basic strings, and receive responses as +:class:`~stem.response.ControlMessage` instances. + +**This module only consists of low level components, and is not intended for +users.** See our `tutorials <tutorials.html>`_ and `Control Module +<api/control.html>`_ if you're new to Stem and looking to get started. + +With that aside, these can still be used for raw socket communication with +Tor... + +:: + + import stem + import stem.connection + import stem.socket + + if __name__ == '__main__': + try: + control_socket = stem.socket.ControlPort(port = 9051) + stem.connection.authenticate(control_socket) + except stem.SocketError as exc: + print "Unable to connect to tor on port 9051: %s" % exc + sys.exit(1) + except stem.connection.AuthenticationFailure as exc: + print "Unable to authenticate: %s" % exc + sys.exit(1) + + print "Issuing 'GETINFO version' query...\\n" + control_socket.send('GETINFO version') + print control_socket.recv() + +:: + + % python example.py + Issuing 'GETINFO version' query... + + version=0.2.4.10-alpha-dev (git-8be6058d8f31e578) + OK **Module Overview:**

1 0

[translation/bridgedb] Update translations for bridgedb
by translation＠torproject.org 24 Mar '14

24 Mar '14

commit dca1f1c4787e689adcbec388c34ff41748506600 Author: Translation commit bot <translation(a)torproject.org> Date: Mon Mar 24 04:45:03 2014 +0000 Update translations for bridgedb --- cv/LC_MESSAGES/bridgedb.po | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/cv/LC_MESSAGES/bridgedb.po b/cv/LC_MESSAGES/bridgedb.po index 6491a88..8b9d3b0 100644 --- a/cv/LC_MESSAGES/bridgedb.po +++ b/cv/LC_MESSAGES/bridgedb.po @@ -4,13 +4,14 @@ # # Translators: # Translators: +# Дима <rastamaf(a)gmail.com>, 2014 msgid "" msgstr "" "Project-Id-Version: The Tor Project\n" "Report-Msgid-Bugs-To: https://trac.torproject.org/projects/tor\n" "POT-Creation-Date: 2013-03-27 21:41+0000\n" -"PO-Revision-Date: 2014-03-21 21:20+0000\n" -"Last-Translator: Phoul <colin(a)torproject.org>\n" +"PO-Revision-Date: 2014-03-24 04:40+0000\n" +"Last-Translator: Дима <rastamaf(a)gmail.com>\n" "Language-Team: Chuvash (http://www.transifex.com/projects/p/torproject/language/cv/)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" @@ -21,7 +22,7 @@ msgstr "" #: lib/bridgedb/templates/base.html:33 msgid "What are bridges?" -msgstr "" +msgstr "Мĕнле кĕперсем?" #: lib/bridgedb/templates/base.html:34 #, python-format @@ -31,7 +32,7 @@ msgstr "" #: lib/bridgedb/templates/base.html:39 msgid "I need an alternative way of getting bridges!" -msgstr "" +msgstr "Мана урăх çул кĕпер тĕрекĕсем кирлĕ!" #: lib/bridgedb/templates/base.html:40 #, python-format @@ -70,11 +71,11 @@ msgstr "" #: lib/bridgedb/templates/captcha.html:8 msgid "Type the two words" -msgstr "" +msgstr "Иккĕ сăмах çыр" #: lib/bridgedb/templates/index.html:6 msgid "Step 1" -msgstr "" +msgstr "1 Утăм" #: lib/bridgedb/templates/index.html:8 #, python-format @@ -83,7 +84,7 @@ msgstr "" #: lib/bridgedb/templates/index.html:13 msgid "Step 2" -msgstr "" +msgstr "2 Утăм" #: lib/bridgedb/templates/index.html:15 #, python-format @@ -92,7 +93,7 @@ msgstr "" #: lib/bridgedb/templates/index.html:19 msgid "Step 3" -msgstr "" +msgstr "3 Утăм" #: lib/bridgedb/templates/index.html:21 #, python-format

1 0