Tor implements a highly customizable control protocol which can be used to tune almost all aspects of its operation.

Enabling Control Port

First enable control port, which is disabled by default. There are several ways we can enable it:

Edit torrc configuration file (normally located in /etc/tor/torrc on unix systems). Uncomment ControlPort line as follows:

## The port on which Tor will listen for local connections from Tor
## controller applications, as documented in control-spec.txt.
ControlPort 9051

Enable control port using –controlport flag:

tor --controlport 9051

Connecting to Control Port

Once control port is enabled, we can connect to it using any telnet client:

$ telnet localhost 9051

As soon as you connect you must authenticate using predifined password hash which is ”” by default. You may change control port password by editing HashedControlPassword line in torrc configuration file. Use authenticate keyword to login.

authenticate ""
250 OK

Tor Control Commands

Viewing and Setting configuration variables

Tor depends on several configuration variables which can be viewed and changed. Most of these variables are set in torrc file, but you can override them at run time.

getconf - get a value stored in a configuration variable.

getconf controlport
250 ControlPort=9051

setconf - set configuration variables. Most of them can be set in torrc file; however, there are several variables (e.g. __DisablePredictedCircuits) which can only be set through through control interface.

setconf controlport=9051
250 OK

resetconf - reset configuration variable to its default value.

resetconf controlport
250 OK
getconf controlport
250 ControlPort=0

saveconf - save current configuration values to torrc file. Special values such as __DisablePredictedCircuits will not be saved.

For a complete listing of configuration variables that you can view or set issue the following command:

getinfo config/names

Viewing Logs

Tor has an advanced logging system which allows us to see exactly what it is doing in the background. Using setevents command, you can specify event types that you want to track. Valid event types include:

CIRC - circuit events. Includes information on newly created, already existing, and closed circuits.
STREAM - stream events. Provides information on status of application streams including which circuit is used for the connection.
ORCONN - network connection events. These events display newly established and closed connections to Tor nodes.
BW - bandwidth in the last second. If you enable this event, it will produce output every second even if there is no activity.
STREAM_BW - bandwidth used by individual streams. Unlike BW, STREAM_BW displays data only when there is activity.
DEBUG, INFO, NOTICE, WARN, ERR - informational messages of varying severity.
ADDRMAP - address mapping events. These events show domain-to-ip mapping that is cached by tor client.
NEWDESC, AUTHDIR_NEWDESCS, DESCCHANGED - dirserver events.
STATUS_GENERAL, STATUS_CLIENT, STATUS_SERVER - status information
GUARD - guard node events.
NS - network status events.

So, in order to enable console output of events of type CIRC (circuit events) issue the following command:

setevents circ

Multiple events can be specified at the same time:

setevents circ stream orconn

Prepend keyword EXTENDED to see extended event information where available:

setevents extended circ

NOTE: Every time you issue setevents command all displayed event types will be reset.

The following command will show you a range of interesting information:

setevents extended circ stream orconn addrmap status_general status_client guard

For a complete listing of event types use the following command:

getinfo events/names

Querying runtime information

Tor has a large number of runtime variables that it needs to keep track of in order to successfully build circuits. We can query this information using getinfo command.

To list currently open circuits:

getinfo circuit-status
250+circuit-status=
4 BUILT Xaishacha,Bellum,croeso
3 BUILT blutroth,TorMiddleMan391,sabotage
2 BUILT blutroth,poolTOR,$9E9FAD3187C9911B71849E0E63F35C7CD41FAAA3
1 BUILT blutroth,$E285783006B1B7193B296A5C858B95FD85566A60,$E56FEABE3E7D822931F768A7A0F18E7BEA901EBD
.
250 OK

Too list currently open streams:

getinfo stream-status
250+stream-status=
4 SUCCEEDED 2 74.125.39.147:80
2 SUCCEEDED 2 74.125.39.147:80
3 SUCCEEDED 2 74.125.39.147:80
.
250 OK

In case you don't see expected output, enable appropriate event output using setevents command.

For a complete listing of information types issue the following command:

getinfo info/names

Creating Custom Circuits

Using Tor control protocol you can create custom circuits of different sizes. Regardless of circuit size the last node must be configured as exit-node. In order to successfully create and use custom circuits we must first disable Tor's automatic circuit creation mechanism. While it can not be completely disabled (?), we can still use the following configuration options to force Tor clients to use our custom made circuits:

setconf __DisablePredictedCircuits=1      <- disable preemptively creating circuits
setconf MaxOnionsPending=0                <- maximum circuits pending
setconf newcircuitperiod=999999999        <- longer period before creating new circuit
setconf maxcircuitdirtiness=999999999     <- longer period for circuit expiration

You can delete already created circuits so they don't interfere:

closecircuit 2
250 OK
closecircuit 1
250 OK
getinfo circuit-status
250-circuit-status=
250 OK

Creating five and more hop circuits

Use extendcircuit command to create or extend circuits.

extendcircuit 0 blutroth,TorMiddleMan391,sabotage,croeso,chaoscomputerclub23
250 EXTENDED 5
getinfo circuit-status
250-circuit-status=5 EXTENDED blutroth,TorMiddleMan391,sabotage
250 OK
getinfo circuit-status
250-circuit-status=5 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso
250 OK
getinfo circuit-status
250-circuit-status=5 BUILT blutroth,TorMiddleMan391,sabotage,croeso,chaoscomputerclub23
250 OK

Immediately following extendcircuit is the circuit id. 0 means create new circuit. Any other number will extend an already existing circuit with the supplied circuit id.

In order to create 10 or more hop circuits, you will need to increase the circuit build timeout configuration. This does not really increase your anonymity, but it is still fun to send your packets flying around the world. We will use the following command to produce a 10 hop circuit:

extendcircuit 0 blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga,bettyboop,optipiii866,chaoscomputerclub23

Below is a complete circuit creation session:

setconf circuitbuildtimeout=300
250 OK
extendcircuit 0 blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga,bettyboop,optipiii866,chaoscomputerclub23
250 EXTENDED 18
650 CIRC 18 LAUNCHED
650 CIRC 18 EXTENDED blutroth
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga,bettyboop
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga,bettyboop,optipiii866
650 CIRC 18 EXTENDED blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga,bettyboop,optipiii866,chaoscomputerclub23
650 CIRC 18 BUILT blutroth,TorMiddleMan391,sabotage,croeso,Xaishacha,aim1loxal1net,Tonga,bettyboop,optipiii866,chaoscomputerclub23

Now when we make a request to google.com you will see the following output (provided you have used setevents ahead of time).

650 STREAM 60 NEW 0 google.com:80
650 STREAM 60 SENTCONNECT 18 google.com:80
650 STREAM 60 REMAP 18 64.233.187.99:80
650 STREAM 60 SUCCEEDED 18 64.233.187.99:80
650 STREAM 61 NEW 0 www.google.com:80
650 STREAM 61 SENTCONNECT 18 www.google.com:80
650 STREAM 61 REMAP 18 209.85.135.147:80
650 STREAM 61 SUCCEEDED 18 209.85.135.147:80
650 STREAM 62 NEW 0 www.google.de:80
650 STREAM 62 SENTCONNECT 18 www.google.de:80
650 STREAM 62 REMAP 18 209.85.135.147:80
650 STREAM 62 SUCCEEDED 18 209.85.135.147:80
650 STREAM 60 CLOSED 18 64.233.187.99:80
650 STREAM 61 CLOSED 18 209.85.135.147:80
650 STREAM 62 CLOSED 18 209.85.135.147:80

A new circuit id 60 is created destined for google.com port 80, which connects using our circuit with id 18 . We will appear to be coming from tor.anonymizer.ccc.de [81.169.137.209].

Creating two hop circuits

Two hop circuits are a bit more practical in real world situations where you sacrifice a bit of privacy for a slight speed increase. Our circuit will be going through tor.anonymizer.ccc.de.

extendcircuit 0 blutroth,chaoscomputerclub23
250 EXTENDED 11
getinfo circuit-status
250-circuit-status=18 BUILT blutroth,chaoscomputerclub23
250 OK

Creating really fast one hop circuits

If privacy is not an issue and we simply need to use a specific exit node we can use single node circuits. This comes in handy when a service is offered only to specific IP space. For example, you can stream certain BBC shows only if you come from UK IP address space.

You will need to modify Tor source code to make this work. Download the latest source tarball from http://www.torproject.org/download-unix.html.en

You will need to edit tor/src/or/control.c file. Remove or comment out the following lines:

if (circ && (circuit_get_cpath_len(circ)<2 || hop==1)) {
   connection_write_str_to_buf(
                   "551 Can't attach stream to one-hop circuit.\r\n", conn);
   return 0;
 }

Compile with the usual:

./configure
make
make install

NOTE: I had to apt-get install libevent-dev libssl-dev on my Debian test box for compilation to work.

You will need to disable a few more safety mechanisms to create one-hop circuits:

setconf FastFirstHop=0
setconf EnforceDistinctSubnets=0
setconf UseEntryGuards=0

Since we will use the same node for both entry and exit, we must find a node which supports appropriate exist policy. One such node is dsync:

getinfo circuit-status
250-circuit-status=
250 OK
extendcircuit 0 desync
250 EXTENDED 40
650 CIRC 40 LAUNCHED
650 CIRC 40 EXTENDED desync
650 CIRC 40 BUILT desync
getinfo circuit-status
250-circuit-status=40 BUILT desync
250 OK
650 STREAM 29 NEW 0 whatismyip.org:80 SOURCE_ADDR=127.0.0.1:37631 PURPOSE=USER
650 STREAM 29 REMAP 0 206.176.224.3:80 SOURCE=CACHE
650 STREAM 29 SENTCONNECT 40 206.176.224.3:80 
650 STREAM 29 REMAP 40 206.176.224.3:80 SOURCE=EXIT
650 STREAM 29 SUCCEEDED 40 206.176.224.3:80 
650 STREAM 29 CLOSED 40 206.176.224.3:80 REASON=DONE
650 CIRC 40 CLOSED desync REASON=FINISHED

NOTE: Sometimes you will encounter a STREAM message saying that it ended the stream before any data was received due to a TORPROTOCOL error. Try finding a different exit node or reconnecting to the same exit node a few times.

Leaky circuits

It is possible to utilize additional misdirection by using any member of an established circuit as an exit node (provided the node has the necessary exit policy). First we will need to disable automated stream to circuit assignment:

setconf __LeaveStreamsUnattached=1

Next let's use a one-hop example to display how we can manually attach outgoing streams to previously created circuits:

250-circuit-status=
250 OK
extendcircuit 0 desync
250 EXTENDED 56
650 CIRC 56 LAUNCHED
650 CIRC 56 EXTENDED desync
650 CIRC 56 BUILT desync
650 STREAM 61 NEW 0 whatismyip.org:80 SOURCE_ADDR=127.0.0.1:59353 PURPOSE=USER
attachstream 61 56
650 STREAM 61 REMAP 0 206.176.224.3:80 SOURCE=CACHE
650 STREAM 61 SENTCONNECT 56 206.176.224.3:80 
250 OK
650 STREAM 61 REMAP 56 206.176.224.3:80 SOURCE=EXIT
650 STREAM 61 SUCCEEDED 56 206.176.224.3:80 
650 STREAM 61 CLOSED 56 206.176.224.3:80 REASON=DONE
650 CIRC 56 CLOSED desync REASON=FINISHED

Now, let's create a new 4 hop circuit. In this case we will exit from hop 3 instead of default hop 4 using HOP=3 parameter of the ATTACHSTREAM command:

extendcircuit 0 sabotage,SEC,chaoscomputerclub23,desync

250 EXTENDED 17
650 CIRC 17 LAUNCHED
650 CIRC 17 EXTENDED sabotage
650 CIRC 17 EXTENDED sabotage,SEC
650 CIRC 17 EXTENDED sabotage,SEC,chaoscomputerclub23
650 CIRC 17 EXTENDED sabotage,SEC,chaoscomputerclub23,desync
650 CIRC 17 BUILT sabotage,SEC,chaoscomputerclub23,desync
650 STREAM 11 NEW 0 whatismyip.org:80 SOURCE_ADDR=127.0.0.1:45597 PURPOSE=USER
attachstream 11 17 HOP=3
650 STREAM 11 REMAP 0 206.176.224.3:80 SOURCE=CACHE
650 STREAM 11 SENTCONNECT 17 206.176.224.3:80 
250 OK
650 STREAM 11 REMAP 17 206.176.224.3:80 SOURCE=EXIT
650 STREAM 11 SUCCEEDED 17 206.176.224.3:80 
650 STREAM 11 CLOSED 17 206.176.224.3:80 REASON=DONE

The IP address returned by whatismyip.org is 81.169.137.209 (tor.anonymizer.ccc.de) which corresponds to chaoscomputerclub23 exit node.

HINT: Attach a stream to circuit 0 to let Tor client assign it automatically.

Other tricks

Below are a few more random tricks:

Get country code for an ip address:

getinfo ip-to-country/216.66.24.2
250-ip-to-country/216.66.24.2=us
250 OK

Switch to new circuits:

signal newnym

Let's redirect all CNN traffic to BBC ;)

mapaddress www.cnn.com=www.bbc.co.uk

Reduce tor traffic by disabling preemptive circuit creation:

setconf __DisablePredictedCircuits=1

Speed up tor:

setconf CircuitBuildTimeout 10

Use specific exit node for a website

mapaddress www.bbc.co.uk=www.bbc.co.uk.ephemer.exit

Resolve domains and ip addresses:

setevents addrmap
250 OK
resolve 2600.com
650 ADDRMAP 2600.com 216.66.24.2 "2008-10-11 05:07:45" EXPIRES="2008-10-11 12:07:45"
250 OK
resolve mode=reverse 216.66.24.2
250 OK
650 ADDRMAP REVERSE[216.66.24.2] phalse.2600.COM "2008-10-11 05:09:10" EXPIRES="2008-10-11 12:09:10"

Automation

The following python application can be used to automate circuit creation using TorCtl library. Using this script you will be able to specify which countries you want to use for each hop, how many ocean and continent crossings you want to take, specify circuit sizes, and many other tweaks. You can get it here:

https://thesprawl.org/code/src/tor-autocircuit-0.2.tar.gz

TorCtl requires python geoip module. On Debian based systems, it can be installed with the following command: