Running Tor on chumby One

Here's a HOWTO on building and running Tor on chumby One.

=Installing Tor=

No-touch install
For people who don't want to build Tor from scratch, you can download an installer package that works with a stock chumby One (it does *not* work with the chumby classic). The package can be found here. This package is tested to work on a chumby One with firmware version 1.0.3. The overall structure and robustness of the install needs to be improved, but this will need to be done by someone with more script-fu than I have. However, chumby is an embedded platform, so we have the luxury of having almost no variation from device to device, unless of course you've gone and hacked yours up (and hackers beware, running this installer will mercilessly overwrite any hooks you may have installed that conflict with the installer's).

The ZIP file contains a script called "userhook2" and a tarball. The script will create a swapfile, install tor libraries, a default torrc that sets up Tor as a low-bandwidth (24KBps) bridge, and installs some CGI scripts that can help you monitor the status of Tor.

Once you have downloaded the package here is what you need to do to install Tor:


 * Unzip the contents onto the root directory of a blank USB drive.
 * Plug the USB drive into your chumby One.
 * Reboot. Wait about 2-3 minutes for Tor to install. It takes a little while.
 * The chumby will then go on to its normal state of showing widgets. You may now remove the USB drive.
 * You will probably also want to configure your router/firewall to forward port 443 to your chumby device, otherwise bridge mode won't work.

From now on, every time you boot the chumby, it will automatically load Tor.

It's very important that you check that Tor is running properly once it's installed. Most home and work environments block the Tor port by default, and the Tor logfile will tell you this if you have a problem. Part of the installer puts a cgi-script on the chumby One's internal web server, so you can monitor the status of your Tor program, and also see how much memory and CPU it is using. You can access this cgi script by going to a URL of:

http:///cgi-bin/custom/torlog

You can see a [sample torlog page here].

Uninstalling
To uninstall the no-touch install, [restore factory defaults]. This will also nuke your network settings, so if you have a network access key you'll have to re-enter it.

If you don't want to do that, you can just delete the file /psp/rfs1/userhook2, and tor will no longer load on reboot. Other directories to scrub, if you want to be thorough, would be /psp/cgi-bin, /mnt/storage/tor, /mnt/storage/lib, and the swap file in /mnt/storage (you'll have to call swapoff /mnt/storage/swap first).

Do it Yourself
Getting Tor installed also requires libevent to be installed. For sanity on an embedded system, chumby's / filesystem is read-only. It's not recommended to "mount -o remount,rw /", because it makes programs difficult to uninstall. The best practice is to store all your libraries inside the hacker partition, called "/mnt/storage". /mnt/storage is not used at all by the normal chumby firmware, but because the root firmware image is typically smaller than the smallest microSD card we can buy, we take all the extra space and put it in a read/write storage partition. You'll find that on some devices, the amount of space available can vary.

If you are careful and only put your scripts in /psp and /mnt/storage, you'll find that if you screw things up you can always just go to "Special Options" mode and restore factory defaults, and everything will just go away; restore factory defaults reformats /mnt/storage and restores /psp to a factory new condition.

So, to facilitate library loading from /mnt/storage, a lib path is included that points there:

LD_LIBRARY_PATH=/lib:/lib:/usr/lib:/usr/local/lib:/mnt/storage/lib:/mnt/storage/local/lib

Thus, the easiest way to install and run Tor is to copy the libevent .libs content into /mnt/storage/lib, and then copy Tor to the storage partition, and run it.

Since Tor can consume a bit of memory, and only 64 MB is available on the chumby One, it's recommended that you create a swap partition to handle any overflow, so that you can use your chumby One uninterrupted for normal widget viewing and music listening.

=Building Tor=

Let's assume you have access to a Linux machine. This procedure was executed on an Ubuntu 9.04 image.

First, you will need download and install a cross-compiling toolchain. Instructions on how to do this can be found here: http://wiki.chumby.com/mediawiki/index.php/GNU_Toolchain.

Then, grab the tor source: https://www.torproject.org/dist/tor-0.2.1.21.tar.gz

Tar and unzip. Before you can compile Tor, you're going to need to build some of your own dependencies too. In particular, you need libevent, openssl, and zlib.

libevent: http://www.monkey.org/~provos/libevent-1.4.13-stable.tar.gz openssl: http://www.openssl.org/source/openssl-0.9.8l.tar.gz zlib: http://www.zlib.net/zlib-1.2.3.tar.gz

Before proceeding, I suggest building a simple hello world program and verifying that arm-linux-gcc is working correctly.

Building libevent
This one is fairly easy. Just run this command inside the libevent source root: ./configure --host=arm-linux

And then run make

The libraries don't need to be installed, since you will bundle them up with the tor binary anyways. They are held in .libs.

Building zlib
This one is a little bit trickier. It doesn't really have cross-compilation support built into the configure script. So, first, run ./configure In the zlib source root, and then you need to hand-edit the Makefile. You need to add the "arm-linux-" prefix for the following variables:
 * LDFLAGS
 * CPP
 * AR
 * RANLIB

The top few lines of the Makefile will look a bit like this: CC=arm-linux-gcc

CFLAGS=-O3 -DUSE_MMAP

LDFLAGS=-L. libz.a LDSHARED=arm-linux-gcc CPP=arm-linux-gcc -E

LIBS=libz.a SHAREDLIB=libz.so SHAREDLIBV=libz.so.1.2.3 SHAREDLIBM=libz.so.1

AR=arm-linux-ar rc RANLIB=arm-linux-ranlib

Now you can run "make" and a libz.a should appear in the source root.

Building open SSL
This one is also a little bit tricky. You can find a guide to cross-compiling open SSL here, but basically, the steps are outlined below.

First, configure open SSL for linux-generic32: ./Configure linux-generic32

Then, patch the Makefile to add the arm-linux- prefix to all the key programs and paths: 29c29 < INSTALLTOP=/usr/local/ssl --- > INSTALLTOP=/usr/arm-linux/local/ssl 32c32 < OPENSSLDIR=/usr/local/ssl --- > OPENSSLDIR=/usr/arm-linux/local/ssl 62c62 < CC= gcc --- > CC= arm-linux-gcc 69,71c69,71 < AR=ar $(ARFLAGS) r < ARD=ar $(ARFLAGS) d < RANLIB= /usr/bin/ranlib --- > AR=arm-linux-ar $(ARFLAGS) r > ARD=arm-linux-ar $(ARFLAGS) d > RANLIB= /usr/arm-linux/bin/ranlib 75c75 < MAKEDEPPROG= gcc --- > MAKEDEPPROG= arm-linux-gcc

Now you can run "make", and then "make install" to install the header files in /usr/arm-linux/local/ssl/include/, although you may want to edit that path in case you don't have access to that directory.

Building Tor
Now that you've got all your dependent libraries, you can finally build Tor. Here's the configuration command line I used for configuring Tor:

./configure --host=arm-linux --with-libevent-dir=/home/chumby/tor/libevent-1.4.13-stable/.libs/ --with-openssl-dir=/usr/arm-linux/local/ssl/ -includedir=/usr/arm-linux/local/ssl/include/ --with-zlib-dir=/home/chumby/tor/zlib-1.2.3/

As you can see, I just hand Tor the paths to all the libraries we had built, and the include directory for open SSL.

Once you've run the configure command, you can now build tor with simply "make". The tor binary ends up in src/or/tor, and there is also a "test" program in the same directory, appropriately called test. If you want to make sure everything has gone well, copy the test program over to your chumby One, toss it in /tmp, and run it.