<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Frequently Asked Questions — Stem 1.1.0 documentation</title>
<link rel="stylesheet" href="_static/haiku.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/print.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/theme_extras.js"></script>
<link rel="shortcut icon" href="_static/favicon.png"/>
<link rel="top" title="Stem 1.1.0 documentation" href="index.html" />
<link rel="up" title="Contents" href="contents.html" />
<link rel="next" title="API" href="api.html" />
<link rel="prev" title="Download" href="download.html" />
</head>
<body>
<div class="header"><img class="rightlogo" src="_static/logo.png" alt="Logo"/><h1 class="heading"><a href="index.html">
<span>Stem Docs</span></a></h1>
<h2 class="heading"><span>Frequently Asked Questions</span></h2>
</div>
<div class="topnav">
<p>
<ul id="navbar">
<li><a href="index.html">Home</a></li>
<li><a href="tutorials.html">Tutorials</a>
<ul>
<li><a href="tutorials/the_little_relay_that_could.html">Hello World</a></li>
<li><a href="tutorials/to_russia_with_love.html">Client Usage</a></li>
<li><a href="tutorials/tortoise_and_the_hare.html">Event Listening</a></li>
<li><a href="tutorials/mirror_mirror_on_the_wall.html">Tor Descriptors</a></li>
<li><a href="tutorials/east_of_the_sun.html">Utilities</a></li>
<li><a href="tutorials/double_double_toil_and_trouble.html">Examples</a></li>
</ul>
</li>
<li><a href="api.html">API</a>
<ul>
<li><a href="api/control.html">stem.control</a></li>
<li><a href="api/connection.html">stem.connection</a></li>
<li><a href="api/socket.html">stem.socket</a></li>
<li><a href="api/process.html">stem.process</a></li>
<li><a href="api/response.html">stem.response</a></li>
<li><a href="api/exit_policy.html">stem.exit_policy</a></li>
<li><a href="api/version.html">stem.version</a></li>
<li><a href="api.html#descriptors">Descriptors</a></li>
<li><a href="api.html#utilities">Utilities</a></li>
</ul>
</li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/doc/stem">Development</a>
<ul>
<li><a href="#">FAQ</a></li>
<li><a href="change_log.html">Change Log</a></li>
<li><a href="https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs">Bug Tracker</a></li>
<li><a href="download.html">Download</a></li>
</ul>
</li>
</ul>
</p>
</div>
<div class="content">
<div class="section" id="frequently-asked-questions">
<h1>Frequently Asked Questions<a class="headerlink" href="#frequently-asked-questions" title="Permalink to this headline">¶</a></h1>
<ul class="simple">
<li><strong>General Information</strong></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="#what-is-stem"><em>What is stem?</em></a></li>
<li><a class="reference internal" href="#does-stem-have-any-dependencies"><em>Does stem have any dependencies?</em></a></li>
<li><a class="reference internal" href="#what-python-versions-is-stem-compatible-with"><em>What python versions is stem compatible with?</em></a></li>
<li><a class="reference internal" href="#what-license-is-stem-under"><em>What license is stem under?</em></a></li>
<li><a class="reference internal" href="#are-there-any-other-controller-libraries"><em>Are there any other controller libraries?</em></a></li>
<li><a class="reference internal" href="#where-can-i-get-help"><em>Where can I get help?</em></a></li>
</ul>
</div></blockquote>
<ul class="simple">
<li><strong>Usage</strong></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="#how-do-i-connect-to-tor"><em>How do I connect to Tor?</em></a></li>
<li><a class="reference internal" href="#how-do-i-request-a-new-identity-from-tor"><em>How do I request a new identity from Tor?</em></a></li>
<li><a class="reference internal" href="#how-do-i-get-information-about-my-exits"><em>How do I get information about my exits?</em></a></li>
<li><a class="reference internal" href="#how-do-i-reload-my-torrc"><em>How do I reload my torrc?</em></a></li>
<li><a class="reference internal" href="#what-is-that-with-keyword-i-keep-seeing-in-the-tutorials"><em>What is that ‘with’ keyword I keep seeing in the tutorials?</em></a></li>
</ul>
</div></blockquote>
<ul class="simple">
<li><strong>Development</strong></li>
</ul>
<blockquote>
<div><ul class="simple">
<li><a class="reference internal" href="#how-do-i-get-started"><em>How do I get started?</em></a></li>
<li><a class="reference internal" href="#how-do-i-run-the-tests"><em>How do I run the tests?</em></a></li>
<li><a class="reference internal" href="#how-do-i-build-the-site"><em>How do I build the site?</em></a></li>
<li><a class="reference internal" href="#what-is-the-copyright-for-patches"><em>What is the copyright for patches?</em></a></li>
</ul>
</div></blockquote>
</div>
<div class="section" id="general-information">
<h1>General Information<a class="headerlink" href="#general-information" title="Permalink to this headline">¶</a></h1>
<div class="section" id="what-is-stem">
<span id="id1"></span><h2>What is stem?<a class="headerlink" href="#what-is-stem" title="Permalink to this headline">¶</a></h2>
<p>Stem is a python controller library that you can use to interact with <a class="reference external" href="https://www.torproject.org/">tor</a>. With it you can write scripts and applications with capabilities similar to <a class="reference external" href="https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia">Vidalia</a> and <a class="reference external" href="https://www.atagar.com/arm/">arm</a>.</p>
<p>From a technical standpoint, stem is a python implementation of Tor’s <a class="reference external" href="https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt">directory</a> and <a class="reference external" href="https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt">control specifications</a>. <a class="reference external" href="tutorials.html">To get started see our tutorials!</a></p>
</div>
<div class="section" id="does-stem-have-any-dependencies">
<span id="id2"></span><h2>Does stem have any dependencies?<a class="headerlink" href="#does-stem-have-any-dependencies" title="Permalink to this headline">¶</a></h2>
<p><strong>No.</strong> All you need in order to use stem is python.</p>
<p>When it is available stem will use <a class="reference external" href="https://www.dlitz.net/software/pycrypto/">pycrypto</a> to validate descriptor signatures. However, there is no need to install pycrypto unless you need this functionality.</p>
</div>
<div class="section" id="what-python-versions-is-stem-compatible-with">
<span id="id3"></span><h2>What python versions is stem compatible with?<a class="headerlink" href="#what-python-versions-is-stem-compatible-with" title="Permalink to this headline">¶</a></h2>
<p>Stem works with <strong>python 2.6 and greater</strong>. This includes the python 3.x series by installing stem via python3 (see our <a class="reference external" href="https://pypi.python.org/pypi/stem/">installation instructions</a> for more information).</p>
</div>
<div class="section" id="what-license-is-stem-under">
<span id="id4"></span><h2>What license is stem under?<a class="headerlink" href="#what-license-is-stem-under" title="Permalink to this headline">¶</a></h2>
<p>Stem is under the <a class="reference external" href="https://www.gnu.org/licenses/lgpl">LGPLv3</a>.</p>
</div>
<div class="section" id="are-there-any-other-controller-libraries">
<span id="id5"></span><h2>Are there any other controller libraries?<a class="headerlink" href="#are-there-any-other-controller-libraries" title="Permalink to this headline">¶</a></h2>
<p>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 <a class="reference external" href="https://txtorcon.readthedocs.org/">Txtorcon</a> and <a class="reference external" href="https://gitweb.torproject.org/pytorctl.git">TorCtl</a>.</p>
<p><a class="reference external" href="https://txtorcon.readthedocs.org/">Txtorcon</a> is an actively maintained controller library written by Meejah for <a class="reference external" href="https://twistedmatrix.com/trac/">Twisted</a>. In the future we plan to <a class="reference external" href="https://www.torproject.org/getinvolved/volunteer.html.en#txtorcon-stemIntegration">integrate Stem and Txtorcon</a> to some degree, but that is still a ways off.</p>
<p><a class="reference external" href="https://gitweb.torproject.org/pytorctl.git">TorCtl</a> was Stem’s predecessor and <a class="reference external" href="https://blog.torproject.org/blog/torctl-deprecation-and-stem-plans">deprecated in December 2012</a> in favor of Stem. Though no longer actively developed, it’s still quite functional and still used for several <a class="reference external" href="https://gitweb.torproject.org/torflow.git">TorFlow</a> based projects.</p>
<p>The following are the functional controller libraries I’m aware of. Dates are for highly active development. If I missed one then please <a class="reference external" href="https://www.atagar.com/contact/">let me know</a>!</p>
<table border="1" class="docutils">
<colgroup>
<col width="59%" />
<col width="16%" />
<col width="25%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Library</th>
<th class="head">Language</th>
<th class="head">Developed</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><a class="reference external" href="https://stem.torproject.org/">Stem</a></td>
<td>Python</td>
<td>October 2011 - Present</td>
</tr>
<tr class="row-odd"><td><a class="reference external" href="https://txtorcon.readthedocs.org/">Txtorcon</a></td>
<td>Python (Twisted)</td>
<td>February 2012 - Present</td>
</tr>
<tr class="row-even"><td><a class="reference external" href="https://gitweb.torproject.org/pytorctl.git">TorCtl</a></td>
<td>Python</td>
<td>July 2008 - November 2011</td>
</tr>
<tr class="row-odd"><td><a class="reference external" href="https://github.com/dunglas/php-torcontrol/">PHP TorCtl</a></td>
<td>PHP</td>
<td>February 2013</td>
</tr>
<tr class="row-even"><td><a class="reference external" href="https://gitweb.torproject.org/jtorctl.git">JTorCtl</a></td>
<td>Java</td>
<td>June 2005 - May 2009</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="where-can-i-get-help">
<span id="id10"></span><h2>Where can I get help?<a class="headerlink" href="#where-can-i-get-help" title="Permalink to this headline">¶</a></h2>
<p>Do you have a tor related question or project that you would like to discuss? If so then find us on the <a class="reference external" href="https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev">tor-dev@ email list</a> and <a class="reference external" href="https://www.torproject.org/about/contact.html.en#irc">IRC</a>.</p>
</div>
</div>
<div class="section" id="usage">
<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
<div class="section" id="how-do-i-connect-to-tor">
<span id="id11"></span><h2>How do I connect to Tor?<a class="headerlink" href="#how-do-i-connect-to-tor" title="Permalink to this headline">¶</a></h2>
<p>Once you have Tor running and <a class="reference external" href="tutorials/the_little_relay_that_could.html">properly configured</a> you have a few ways of connecting to it. The following are the most common methods for getting a <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> instance, from the highest to lowest level...</p>
<ol class="arabic">
<li><p class="first"><a class="reference internal" href="api/connection.html#stem.connection.connect_port" title="stem.connection.connect_port"><tt class="xref py py-func docutils literal"><span class="pre">stem.connection.connect_port()</span></tt></a> and <a class="reference internal" href="api/connection.html#stem.connection.connect_socket_file" title="stem.connection.connect_socket_file"><tt class="xref py py-func docutils literal"><span class="pre">stem.connection.connect_socket_file()</span></tt></a></p>
<p>Writing a commandline script? Then the <a class="reference external" href="api/connection.html">connection module</a> provide you the quickest and most hassle free method for getting a <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a>.</p>
<p>These functions connect and authenticate to the given port or socket, providing you with a <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> 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 <strong>None</strong>.</p>
<p>For instance...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">from</span> <span class="nn">stem.connection</span> <span class="kn">import</span> <span class="n">connect_port</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="n">controller</span> <span class="o">=</span> <span class="n">connect_port</span><span class="p">()</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="c"># unable to get a connection</span>
<span class="k">print</span> <span class="s">"Tor is running version </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">controller</span><span class="o">.</span><span class="n">get_version</span><span class="p">()</span>
<span class="n">controller</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<div class="highlight-python"><pre>% python example.py
Tor is running version 0.2.4.10-alpha-dev (git-8be6058d8f31e578)</pre>
</div>
<p>... or if Tor isn’t running...</p>
<div class="highlight-python"><pre>% python example.py
[Errno 111] Connection refused</pre>
</div>
</li>
<li><p class="first"><a class="reference internal" href="api/control.html#stem.control.Controller.from_port" title="stem.control.Controller.from_port"><tt class="xref py py-func docutils literal"><span class="pre">stem.control.Controller.from_port()</span></tt></a> and <a class="reference internal" href="api/control.html#stem.control.Controller.from_socket_file" title="stem.control.Controller.from_socket_file"><tt class="xref py py-func docutils literal"><span class="pre">stem.control.Controller.from_socket_file()</span></tt></a></p>
<p>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 <a class="reference internal" href="api/control.html#stem.control.Controller.from_port" title="stem.control.Controller.from_port"><tt class="xref py py-func docutils literal"><span class="pre">from_port()</span></tt></a> and <a class="reference internal" href="api/control.html#stem.control.Controller.from_socket_file" title="stem.control.Controller.from_socket_file"><tt class="xref py py-func docutils literal"><span class="pre">from_socket_file()</span></tt></a> methods come in.</p>
<p>These static <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> methods return an <strong>unauthenticated</strong> controller you can then authenticate yourself using its <a class="reference internal" href="api/control.html#stem.control.Controller.authenticate" title="stem.control.Controller.authenticate"><tt class="xref py py-func docutils literal"><span class="pre">authenticate()</span></tt></a> method.</p>
<p>For instance...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">getpass</span>
<span class="kn">import</span> <span class="nn">sys</span>
<span class="kn">import</span> <span class="nn">stem</span>
<span class="kn">import</span> <span class="nn">stem.connection</span>
<span class="kn">from</span> <span class="nn">stem.control</span> <span class="kn">import</span> <span class="n">Controller</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">controller</span> <span class="o">=</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">()</span>
<span class="k">except</span> <span class="n">stem</span><span class="o">.</span><span class="n">SocketError</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="k">print</span> <span class="s">"Unable to connect to tor on port 9051: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exc</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">()</span>
<span class="k">except</span> <span class="n">stem</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">MissingPassword</span><span class="p">:</span>
<span class="n">pw</span> <span class="o">=</span> <span class="n">getpass</span><span class="o">.</span><span class="n">getpass</span><span class="p">(</span><span class="s">"Controller password: "</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">(</span><span class="n">password</span> <span class="o">=</span> <span class="n">pw</span><span class="p">)</span>
<span class="k">except</span> <span class="n">stem</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">PasswordAuthFailed</span><span class="p">:</span>
<span class="k">print</span> <span class="s">"Unable to authenticate, password is incorrect"</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">except</span> <span class="n">stem</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">AuthenticationFailure</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="k">print</span> <span class="s">"Unable to authenticate: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exc</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"Tor is running version </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">controller</span><span class="o">.</span><span class="n">get_version</span><span class="p">()</span>
<span class="n">controller</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>If you’re fine with allowing your script to raise exceptions then this can be more nicely done as...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">stem.control</span> <span class="kn">import</span> <span class="n">Controller</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">()</span> <span class="k">as</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">()</span>
<span class="k">print</span> <span class="s">"Tor is running version </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">controller</span><span class="o">.</span><span class="n">get_version</span><span class="p">()</span>
</pre></div>
</div>
</li>
<li><p class="first"><a class="reference external" href="api/socket.html">Socket Module</a></p>
<p>For the diehards among us you can skip the conveniences of a high level <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> and work directly with the raw components. At Stem’s lowest level your connection with Tor is a <a class="reference internal" href="api/socket.html#stem.socket.ControlSocket" title="stem.socket.ControlSocket"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocket</span></tt></a> subclass. This provides methods to send, receive, disconnect, and reconnect to Tor.</p>
<p>One level up is the <a class="reference internal" href="api/control.html#stem.control.BaseController" title="stem.control.BaseController"><tt class="xref py py-class docutils literal"><span class="pre">BaseController</span></tt></a>. This wraps the <a class="reference internal" href="api/socket.html#stem.socket.ControlSocket" title="stem.socket.ControlSocket"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocket</span></tt></a> and provides a <a class="reference internal" href="api/control.html#stem.control.BaseController.msg" title="stem.control.BaseController.msg"><tt class="xref py py-func docutils literal"><span class="pre">msg()</span></tt></a> method so you can send messages and receive their reply in a thread safe manner. Finally comes the <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a>, which extends <a class="reference internal" href="api/control.html#stem.control.BaseController" title="stem.control.BaseController"><tt class="xref py py-class docutils literal"><span class="pre">BaseController</span></tt></a> to provide more user friendly methods.</p>
<p>Directly using the <a class="reference internal" href="api/socket.html#stem.socket.ControlSocket" title="stem.socket.ControlSocket"><tt class="xref py py-class docutils literal"><span class="pre">ControlSocket</span></tt></a> is unsafe when it’s being managed through a <a class="reference internal" href="api/control.html#stem.control.BaseController" title="stem.control.BaseController"><tt class="xref py py-class docutils literal"><span class="pre">BaseController</span></tt></a>, but if you’re interested in dealing with lower level components directly then that is certainly an option...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">stem</span>
<span class="kn">import</span> <span class="nn">stem.connection</span>
<span class="kn">import</span> <span class="nn">stem.socket</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">control_socket</span> <span class="o">=</span> <span class="n">stem</span><span class="o">.</span><span class="n">socket</span><span class="o">.</span><span class="n">ControlPort</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span>
<span class="n">stem</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">authenticate</span><span class="p">(</span><span class="n">control_socket</span><span class="p">)</span>
<span class="k">except</span> <span class="n">stem</span><span class="o">.</span><span class="n">SocketError</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="k">print</span> <span class="s">"Unable to connect to tor on port 9051: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exc</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">except</span> <span class="n">stem</span><span class="o">.</span><span class="n">connection</span><span class="o">.</span><span class="n">AuthenticationFailure</span> <span class="k">as</span> <span class="n">exc</span><span class="p">:</span>
<span class="k">print</span> <span class="s">"Unable to authenticate: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exc</span>
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"Issuing 'GETINFO version' query...</span><span class="se">\n</span><span class="s">"</span>
<span class="n">control_socket</span><span class="o">.</span><span class="n">send</span><span class="p">(</span><span class="s">'GETINFO version'</span><span class="p">)</span>
<span class="k">print</span> <span class="n">control_socket</span><span class="o">.</span><span class="n">recv</span><span class="p">()</span>
</pre></div>
</div>
<div class="highlight-python"><pre>% python example.py
Issuing 'GETINFO version' query...
version=0.2.4.10-alpha-dev (git-8be6058d8f31e578)
OK</pre>
</div>
</li>
</ol>
</div>
<div class="section" id="how-do-i-request-a-new-identity-from-tor">
<span id="id12"></span><h2>How do I request a new identity from Tor?<a class="headerlink" href="#how-do-i-request-a-new-identity-from-tor" title="Permalink to this headline">¶</a></h2>
<p>In Tor your identity is the three-hop <strong>circuit</strong> over which your traffic travels through the Tor network.</p>
<p>Tor periodically creates new circuits. When a circuit is used it becomes <strong>dirty</strong>, and after ten minutes new connections will not use it. When all of the connections using an expired circuit are done the circuit is closed.</p>
<p>An important thing to note is that a new circuit does not necessarily mean a new IP address. Paths are randomly selected based on heuristics like speed and stability. There are only so many large exits in the Tor network, so it’s not uncommon to reuse an exit you have had previously.</p>
<p>Tor does not have a method for cycling your IP address. This is on purpose, and done for a couple reasons. The first is that this capability is usually requested for not-so-nice reasons such as ban evasion or SEO. Second, repeated circuit creation puts a very high load on the Tor network, so please don’t!</p>
<p>With all that out of the way, how do you create a new circuit? You can customise the rate at which Tor cycles circuits with the <strong>MaxCircuitDirtiness</strong> option in your <a class="reference external" href="https://www.torproject.org/docs/faq.html.en#torrc">torrc</a>. <a class="reference external" href="https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia">Vidalia</a> and <a class="reference external" href="https://www.atagar.com/arm/">arm</a> both provide a method to request a new identity, and you can do so programmatically by sending Tor a NEWNYM signal.</p>
<p>To do this with telnet...</p>
<div class="highlight-python"><pre>% telnet localhost 9051
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
AUTHENTICATE
250 OK
SIGNAL NEWNYM
250 OK</pre>
</div>
<p>And with stem...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">stem</span> <span class="kn">import</span> <span class="n">Signal</span>
<span class="kn">from</span> <span class="nn">stem.control</span> <span class="kn">import</span> <span class="n">Controller</span>
<span class="k">with</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span> <span class="k">as</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">()</span>
<span class="n">controller</span><span class="o">.</span><span class="n">signal</span><span class="p">(</span><span class="n">Signal</span><span class="o">.</span><span class="n">NEWNYM</span><span class="p">)</span>
</pre></div>
</div>
<p>For lower level control over Tor’s circuits and path selection see the <a class="reference external" href="tutorials/to_russia_with_love.html">client usage tutorial</a>.</p>
</div>
<div class="section" id="how-do-i-get-information-about-my-exits">
<span id="id15"></span><h2>How do I get information about my exits?<a class="headerlink" href="#how-do-i-get-information-about-my-exits" title="Permalink to this headline">¶</a></h2>
<p>To learn about the Tor relays you’re presently using call <a class="reference internal" href="api/control.html#stem.control.Controller.get_circuits" title="stem.control.Controller.get_circuits"><tt class="xref py py-func docutils literal"><span class="pre">get_circuits()</span></tt></a>. The last relay in the circuit’s path is your exit...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">stem</span> <span class="kn">import</span> <span class="n">CircStatus</span>
<span class="kn">from</span> <span class="nn">stem.control</span> <span class="kn">import</span> <span class="n">Controller</span>
<span class="k">with</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span> <span class="k">as</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">()</span>
<span class="k">for</span> <span class="n">circ</span> <span class="ow">in</span> <span class="n">controller</span><span class="o">.</span><span class="n">get_circuits</span><span class="p">():</span>
<span class="k">if</span> <span class="n">circ</span><span class="o">.</span><span class="n">status</span> <span class="o">!=</span> <span class="n">CircStatus</span><span class="o">.</span><span class="n">BUILT</span><span class="p">:</span>
<span class="k">continue</span>
<span class="n">exit_fp</span><span class="p">,</span> <span class="n">exit_nickname</span> <span class="o">=</span> <span class="n">circ</span><span class="o">.</span><span class="n">path</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="n">exit_desc</span> <span class="o">=</span> <span class="n">controller</span><span class="o">.</span><span class="n">get_network_status</span><span class="p">(</span><span class="n">exit_fp</span><span class="p">,</span> <span class="bp">None</span><span class="p">)</span>
<span class="n">exit_address</span> <span class="o">=</span> <span class="n">exit_desc</span><span class="o">.</span><span class="n">address</span> <span class="k">if</span> <span class="n">exit_desc</span> <span class="k">else</span> <span class="s">'unknown'</span>
<span class="k">print</span> <span class="s">"Exit relay"</span>
<span class="k">print</span> <span class="s">" fingerprint: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exit_fp</span>
<span class="k">print</span> <span class="s">" nickname: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exit_nickname</span>
<span class="k">print</span> <span class="s">" address: </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="n">exit_address</span>
<span class="k">print</span>
</pre></div>
</div>
<div class="highlight-python"><pre>% 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</pre>
</div>
</div>
<div class="section" id="how-do-i-reload-my-torrc">
<span id="id16"></span><h2>How do I reload my torrc?<a class="headerlink" href="#how-do-i-reload-my-torrc" title="Permalink to this headline">¶</a></h2>
<p>Tor is configured through its <a class="reference external" href="https://www.torproject.org/docs/faq.html.en#torrc">torrc</a>. When you edit this file you need to either restart Tor or issue a <strong>SIGHUP</strong> for the changes to be reflected. To issue a SIGHUP you can either...</p>
<blockquote>
<div><ul class="simple">
<li>Run <strong>pkill -sighup tor</strong>.</li>
<li>Send Tor a <strong>SIGHUP</strong> signal through its control port...</li>
</ul>
</div></blockquote>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">stem</span> <span class="kn">import</span> <span class="n">Signal</span>
<span class="kn">from</span> <span class="nn">stem.control</span> <span class="kn">import</span> <span class="n">Controller</span>
<span class="k">with</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span> <span class="k">as</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">authenticate</span><span class="p">()</span>
<span class="n">controller</span><span class="o">.</span><span class="n">signal</span><span class="p">(</span><span class="n">Signal</span><span class="o">.</span><span class="n">SIGHUP</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="what-is-that-with-keyword-i-keep-seeing-in-the-tutorials">
<span id="id18"></span><h2>What is that ‘with’ keyword I keep seeing in the tutorials?<a class="headerlink" href="#what-is-that-with-keyword-i-keep-seeing-in-the-tutorials" title="Permalink to this headline">¶</a></h2>
<p>Python’s ‘<strong>with</strong>‘ keyword is shorthand for a try/finally block. With a <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> the following...</p>
<div class="highlight-python"><pre>with Controller.from_port(port = 9051) as controller:
# do my stuff</pre>
</div>
<p>... is equivialnt to...</p>
<div class="highlight-python"><pre>controller = Controller.from_port(port = 9051)
try:
# do my stuff
finally:
controller.close()</pre>
</div>
<p>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 <a class="reference internal" href="api/control.html#stem.control.Controller" title="stem.control.Controller"><tt class="xref py py-class docutils literal"><span class="pre">Controller</span></tt></a> will be closed. For instance...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">BandwidthReporter</span><span class="p">(</span><span class="nb">object</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">controller</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">controller</span> <span class="o">=</span> <span class="n">controller</span>
<span class="k">def</span> <span class="nf">print_bandwidth</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">bytes_read</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">controller</span><span class="o">.</span><span class="n">get_info</span><span class="p">(</span><span class="s">"traffic/read"</span><span class="p">)</span>
<span class="n">bytes_written</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">controller</span><span class="o">.</span><span class="n">get_info</span><span class="p">(</span><span class="s">"traffic/written"</span><span class="p">)</span>
<span class="k">print</span> <span class="s">"My Tor relay has read </span><span class="si">%s</span><span class="s"> bytes and written </span><span class="si">%s</span><span class="s">."</span> <span class="o">%</span> <span class="p">(</span><span class="n">bytes_read</span><span class="p">,</span> <span class="n">bytes_written</span><span class="p">)</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="k">with</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span> <span class="k">as</span> <span class="n">controller</span><span class="p">:</span>
<span class="n">reporter</span> <span class="o">=</span> <span class="n">BandwidthReporter</span><span class="p">(</span><span class="n">controller</span><span class="p">)</span>
<span class="c"># The following line is broken because the 'controller' we initialised</span>
<span class="c"># above was disconnected once we left the 'with' scope.</span>
<span class="n">reporter</span><span class="o">.</span><span class="n">print_bandwidth</span><span class="p">()</span>
</pre></div>
</div>
<p>To fix this we could either move the print_bandwidth() call into the ‘with’ scope, or simply avoid using ‘with’ all together...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">'__main__'</span><span class="p">:</span>
<span class="n">controller</span> <span class="o">=</span> <span class="n">Controller</span><span class="o">.</span><span class="n">from_port</span><span class="p">(</span><span class="n">port</span> <span class="o">=</span> <span class="mi">9051</span><span class="p">)</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">reporter</span> <span class="o">=</span> <span class="n">BandwidthReporter</span><span class="p">(</span><span class="n">controller</span><span class="p">)</span>
<span class="n">reporter</span><span class="o">.</span><span class="n">print_bandwidth</span><span class="p">()</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">controller</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>For more information about the ‘with’ keyword see <a class="reference external" href="http://effbot.org/zone/python-with-statement.htm">here</a>.</p>
</div>
</div>
<div class="section" id="development">
<h1>Development<a class="headerlink" href="#development" title="Permalink to this headline">¶</a></h1>
<div class="section" id="how-do-i-get-started">
<span id="id19"></span><h2>How do I get started?<a class="headerlink" href="#how-do-i-get-started" title="Permalink to this headline">¶</a></h2>
<p>The best way of getting involved with any project is to jump right in! Our <a class="reference external" href="https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs">bug tracker</a> lists several development tasks. In particular look for the ‘easy’ keyword when getting started.</p>
<p>If you have any questions then I’m always more than happy to help (I’m <strong>atagar</strong> on <a class="reference external" href="http://www.oftc.net/oftc/">oftc</a> and also available <a class="reference external" href="https://www.atagar.com/contact/">via email</a>).</p>
<p>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!</p>
<ol class="arabic simple">
<li>Clone our <a class="reference external" href="http://git-scm.com/">git</a> repository: <strong>git clone https://git.torproject.org/stem.git</strong></li>
<li>Find a <a class="reference external" href="https://trac.torproject.org/projects/tor/wiki/doc/stem/bugs">bug or feature</a> that sounds interesting.</li>
<li>When you have something that you would like to contribute back do the following...</li>
</ol>
<blockquote>
<div><ul class="simple">
<li>If you don’t already have a publicly accessible stem repository then set one up. <a class="reference external" href="https://github.com/">GitHub</a> in particular is great for this.</li>
<li>File a <a class="reference external" href="https://trac.torproject.org/projects/tor/newticket">trac ticket</a>, the only fields you’ll need are...</li>
</ul>
<blockquote>
<div><ul class="simple">
<li>Summary: short description of your change</li>
<li>Description: longer description and a link to your repository with either the git commits or branch that has your change</li>
<li>Type: ‘defect’ if this is a bug fix and ‘enhancement’ otherwise</li>
<li>Priority: rough guess at the priority of your change</li>
<li>Component: Stem</li>
</ul>
</div></blockquote>
<ul class="simple">
<li>I’ll review the change and give suggestions. When we’re both happy with it I’ll push your change to the official repository.</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="how-do-i-run-the-tests">
<span id="id20"></span><h2>How do I run the tests?<a class="headerlink" href="#how-do-i-run-the-tests" title="Permalink to this headline">¶</a></h2>
<p>Stem has three kinds of tests: <strong>unit</strong>, <strong>integration</strong>, and <strong>static</strong>.</p>
<p><strong>Unit</strong> tests are our most frequently ran tests. They’re quick, they’re easy, and provide good test coverage...</p>
<div class="highlight-python"><pre>~$ cd stem/
~/stem$ ./run_tests.py --unit</pre>
</div>
<p><strong>Integration</strong> 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 <a class="reference external" href="https://www.torproject.org/download/download.html.en">tor installed</a>. You can exercise alternate tor configurations with the <tt class="docutils literal"><span class="pre">--target</span></tt> argument (see <tt class="docutils literal"><span class="pre">run_tests.py</span> <span class="pre">--help</span></tt> for a list of its options).</p>
<div class="highlight-python"><pre>~/stem$ ./run_tests.py --integ
~/stem$ ./run_tests.py --integ --tor /path/to/tor
~/stem$ ./run_tests.py --integ --target RUN_COOKIE</pre>
</div>
<p><strong>Static</strong> tests use <a class="reference external" href="https://launchpad.net/pyflakes">pyflakes</a> to do static error checking and <a class="reference external" href="http://pep8.readthedocs.org/en/latest/">pep8</a> for style checking. If you have them installed then pyflakes automatically takes place as part of all test runs, but style checking is run separately...</p>
<div class="highlight-python"><pre>~/stem$ ./run_tests.py --style</pre>
</div>
<p>If you have <strong>python 3</strong> installed then you can test our python 3 compatibility with the following. <em>Note that need to still initially execute run_tests.py with a 2.x version of python.</em></p>
<div class="highlight-python"><pre>~/stem$ ./run_tests.py --all --python3</pre>
</div>
<p>See <tt class="docutils literal"><span class="pre">run_tests.py</span> <span class="pre">--help</span></tt> for more usage information.</p>
</div>
<div class="section" id="how-do-i-build-the-site">
<span id="id21"></span><h2>How do I build the site?<a class="headerlink" href="#how-do-i-build-the-site" title="Permalink to this headline">¶</a></h2>
<p>If you have <a class="reference external" href="http://sphinx-doc.org/">sphinx</a> version 1.1 or later installed then building our site is as easy as...</p>
<div class="highlight-python"><pre>~$ cd stem/docs
~/stem/docs$ make html</pre>
</div>
<p>When it’s finished you can direct your browser to the <em>_build</em> directory with a URI similar to...</p>
<div class="highlight-python"><pre>file:///home/atagar/stem/docs/_build/html/index.html</pre>
</div>
</div>
<div class="section" id="what-is-the-copyright-for-patches">
<span id="id22"></span><h2>What is the copyright for patches?<a class="headerlink" href="#what-is-the-copyright-for-patches" title="Permalink to this headline">¶</a></h2>
<p>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 (<a class="reference external" href="https://www.atagar.com/">Damian</a>) and the <a class="reference external" href="https://www.torproject.org/">Tor Project</a>.</p>
<p>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.</p>
</div>
</div>
</div>
<div class="bottomnav">
</div>
<div class="footer">
</div>
</body>
</html>
