NAME

remoTor - a console-based Tor controller and log analyzer with PSYC notification

SYNOPSIS

 remotor [<options>] [<nickname>]
 
 Options:
         -p <password>  Authentication string needed to take control
         -H <host>      Tor router host
         -P <port>      Tor router control port
         -S <path>      connect to the Tor control unix Socket instead
         -l <logfile>   Keep a transaction log
         -i <seconds>   Request a stream status if idle for a while
         -m <path>      Monitor a logging pipe for interesting Tor events
         -f             Forward circuit creation requests to PSYC
         -c <config>    Alternate configuration file to use
         -t <uniform>   PSYC address to send notifications to
         -b <uniform>   PSYC address to bind to
 
 <nickname> matches an entry from the <config> file.

DESCRIPTION

Here's a little console-based perl script that lets you control your Tor process, monitor circuits as they happen, issue commands like changing your identity and such.

I found vidalia too heavy and arm too confusing and didn't see a simple tool that would leverage the Tor control protocol without excessive nuisances, just a bit of noise reduction and text coloring.

Monitoring outgoing connections

When remotor is running on the same machine as tor, it can additionally monitor the hostnames the tor process is building circuits for. You may want to do this if you have devices in your house that you don't trust, for example. The regular Tor control protocol doesn't let you have this information other than by continously polling the stream status, and even then you may miss out on some short exfiltration going on. remotor lets you have this information and even lets you study it later rather than having to keep your eyes on the control console all the time.

Forwarding messages to a chatroom

remotor can forward critical Tor events to a chatroom using the PSYC protocol. With an advanced server such as psyced you can use a regular IRC client to view the messages, but you can also use a simple 'psyclisten' as provided with the Net::PSYC library. Let it run and pass its bind address to remotor using the '-t' flag.

psyced comes with a "remotor" place which is preset to receive messages from this tool, all you need to do is install psyced and use your IRC client to join #remotor.

remotor can also forward host monitoring, if you enabled that. Additionally a person at the remotor console can interact with the people in the chatroom using the built-in chat.

Be careful when you use other IP addresses than localhost since Net::PSYC does not encrypt its packets. You may want to learn about SSH port forwarding, gnunet-vpn, cjdns or other tunneling strategies.

CONFIGURATION

You may want to persist certain configuration settings or keep separate configurations for different Tor routers. The default config file resides in ~/.tor/remotor.ini. Here's an example for the ini syntax in use:

        [default]
        host=192.168.0.1
        port=9051
        auth=somesecretrandomstring
        notify=psyc://127.0.0.1/@remotor
        monitor=/var/run/tor/log.fifo

The configuration file is a safer place to store authentication strings than the command line which can be read by other users of the computing device (in case you have any). The 'default' entry will be used unless you specify a nickname.

OPTIONS

Monitoring outgoing connections

remotor can additionally monitor the debug log of the Tor process using the -s and/or -f flags. In this case remotor needs to be running on the same system as the Tor router. In the torrc you need to modify the logging parameters as follows:

        SafeLogging relay
        LogMessageDomains 1
        Log [app]debug-debug file /var/run/tor/log.fifo
        Log           notice file /var/run/tor/log.fifo

You can use a different path and pass it using -s. remotor will attempt to mkfifo the necessary pipe if it is missing, so run remotor *before* you restart tor.

AUTHORS

carlo von lynX.

COPYRIGHT

This program is free software, published under the Affero GNU Public License. A disclaimer isn't necessary in my country, nor do I need to mention the current year to assert a copyright.