[tor-commits] [stem/master] FAQ entry for 'How do I connect to Tor?'
atagar at torproject.org
atagar at torproject.org
Sun Sep 1 17:25:12 UTC 2013
commit 53068b2f3066df1a01be5f13a3578263e21fac54
Author: Damian Johnson <atagar at torproject.org>
Date: Sun Sep 1 10:23:49 2013 -0700
FAQ entry for 'How do I connect to Tor?'
While code reviewing ra's RTT Prober work I realized that our site didn't
explain the various ways a user can get a Controller. Adding a FAQ entry with
examples that explains it.
---
docs/faq.rst | 122 +++++++++++++++++++++++-
docs/tutorials/the_little_relay_that_could.rst | 2 +-
2 files changed, 122 insertions(+), 2 deletions(-)
diff --git a/docs/faq.rst b/docs/faq.rst
index 006ed59..d942c0e 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -12,6 +12,7 @@ Frequently Asked Questions
* **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`
@@ -68,7 +69,7 @@ Yup. The most mature controller libraries are written in python, but there's a f
`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-stemIntegration>`_ to some degree, but that is still a ways off.
-`TorCtl <https://gitweb.torproject.org/pytorctl.git>`_ is 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.
+`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 <http://www.atagar.com/contact/>`_!
@@ -92,6 +93,125 @@ Do you have a tor related question or project that you would like to discuss? If
Usage
=====
+.. _how_do_i_connect_to_tor:
+
+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
+
+ 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()
+
+ ::
+
+ % 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()
+
+#. `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
+
.. _how_do_i_request_a_new_identity_from_tor:
How do I request a new identity from Tor?
diff --git a/docs/tutorials/the_little_relay_that_could.rst b/docs/tutorials/the_little_relay_that_could.rst
index c30ae55..751c216 100644
--- a/docs/tutorials/the_little_relay_that_could.rst
+++ b/docs/tutorials/the_little_relay_that_could.rst
@@ -42,7 +42,7 @@ the following configuration options...
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 since it started. If you're unfamiliar
+many bytes Tor has sent and received since it started. Note that there are a `few ways to connect to Tor <../faq.html#how-do-i-connect-to-tor>`_. If you're unfamiliar
with the '**with**' keyword then see `here
<../faq.html#what-is-that-with-keyword-i-keep-seeing-in-the-tutorials>`_...
More information about the tor-commits
mailing list