THE

SPRAWL

  •  
  •  
  •  
  • Every installation of Tor includes a server and communication protocol used to control all aspects of client's 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
    

    To 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
    

    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.

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

    sudo apt-get install python-geoip
    

    External Links

    Published on October 3rd, 2009 by iphelix

    sprawlsimilar

    16 jan
    2010
    2600 magazine article

    My article on the Tor control protocol was published in the Winter 2009-2010 issue of the 2600 Magazine. Read more.

    tor nodes

    Download tor-nodes.py
    Size 372 bytes
    DateAugust 27th, 2011
    Version0.2

    Enumerates IP addresses of Tor nodes by querying Tor client. Read more.

    tor autocircuit

    Download tor-autocircuit-0.2.tar.gz
    Size 37.9 KB
    DateOctober 28th, 2010
    Version0.2

    Tor Autocircuit automatically creates Tor circuits according to a predefined set of rules (e.g. geolocation, number of hops, etc.). This script requires TorCtl python library Read more.


    sprawlcomments

    All original content on this site is copyright protected and licensed under Creative Commons - Attribution, NonCommercial, ShareAlike 4.0 International.

    π
    ///\oo/\\\