_ _
| |_ ___ _ __ ___ _ _| |_ ___ _ __
| __/ _ \| '__/ _ \| | | | __/ _ \ '__|
| || (_) | | | (_) | |_| | || __/ |
\__\___/|_| \___/ \__,_|\__\___|_|
Project wiki page: https://trac.torproject.org/projects/tor/wiki/doc/Torouter
= Repository Contents =
README this file
./doc user and developer documentation
./freedom-maker firmware build scripts
./config torouter configuration files
./packages source for torouter-specific software packages
= Installation and Build Instructions =
There are a couple ways to get the debian-based torouter system running on a
DreamPlug device:
- Flash a pre-built image onto an SD card
- Install the FreedomBox distribution or a "vanilla" debian, then run a
torouter takeover/upgrade script
- Build and flash a new image from source (perhaps with modifications)
For the later, see the "Building" section, then follow the SD card directions.
Regardless of the installation method and target, if the device is in a
"factory fresh" state some bootloader preparation is required. See the
"DreamPlug Preparation" section below; you will need serial console access to
the DreamPlug, for example with the (sometimes bundled) GuruPlug JTAG device.
=== Flash Pre-Built Image to an SD card ===
The command to write a raw image file $IMGFILE to an SD card connected via a
USB adapter with block device $USBBASEDEV is:
$ dd bs=1M if=$IMGFILE of=$USBBASEDEV
On linux you can try to figure out the $USBBASEDEV using the 'lsblk' command;
you are looking for the base device (eg, /dev/sdb) not a partition (eg,
/dev/sdb2). The SD care should not be mounted; use 'umount' to unmount the card
if any partitions were mounted automatically for some reason.
!!! Be careful not to overwrite the wrong base device !!!
If the downloaded image name is "torouter-unstable-20120928-4GB-USB.img.gz" and
the SD card block device is "/dev/sdb", first unzip the image file and dd it to
the card:
$ gunzip torouter-unstable-20120928-4GB-USB.img.gz
$ sudo dd bs=1M if=./torouter-unstable-20120928-4GB-USB.img of=/dev/sdb
$ sync # doesn't hurt
You can then remove the SD card, put it in your DreamPlug, and boot up. If this
is the first boot with a factory-fresh DreamPlug, you'll need to configure
u-boot; see below.
=== Torouter Takeover Script ===
Simply copy over the torouter_easy_setup.sh and execute it (with sudo
permissions) on the device. Substituting $DPHOST for an actual IP/hostname):
scp packages/torouter_easy_setup.sh $DPHOST:/tmp/
ssh $DPHOST /tmp/torouter_easy_setup.sh
= Build a Torouter Image From Scratch =
NOTE: it may be (?) that the deb.torproject.org apt repo needs to exist in the
*host* operating system. See https://www.torproject.org/docs/debian.html.en
These instructions assume a debian wheezy host system.
In brief, the build process proceeds to:
1. use the ``multistrap`` tool to fetch debian packages and build a complete
root filesystem
2. copies in some torouter-specific configuration files
3. optionally copies in locally-built torouter-specific .deb files
3. emulates booting into the system using qemu to run some more configuration
steps
By default, the multistrap process will try to fetch pre-build torouter
software and configuration packages (such as the web user interface) from
torouter.torproject.org. If you've made local changes to those packages, you
can bundle in your own .deb files by building them into the
./packages/packages-for-upload directory, though the local packages may get
overwriten by apt updates if the version number is not high enough. See
./packages/README for build instructions.
To proceed with building the torouter image, first fetch build-system
dependancies (this probably isn't an exhaustive list):
$ apt-get install rsync multistrap qemu-user-static u-boot-tools git mercurial debootstrap extlinux
Then enter the freedom-maker directory and run a build:
$ cd ./freedom-maker
$ sudo ./buildrootfs.sh
If that was ultimately successful (you can ignore some apt warnings and errors
that may scroll by), you now have a root filesystem ready to be copied to an SD
card. Insert a card and partition it to have a small (~80MB)
boot partition followed by an ext3 root partition (1GB or so minimum). You
might want to take care and block align the partitions to get better write
performance; see ./doc/sd_card.txt for more info. Make note of the boot and
root partition nodes (eg, $BOOTNODE=/dev/sdc1 and $ROOTNODE=/dev/sdc2), then
copy over the built distribution:
$ sudo ./copy2card.sh $BOOTNODE $ROOTNODE
If that was successful, contratulations, you now have a usable torouter SD
card! You could skip ahead now to DreamPlug Perparation.
If you want to dump your fresh un-booted image to a static .img file (which
could be distributed to others or flashed to another card quickly), run the
copy2img.sh script with the "base" device of the thumbstick as an argument (eg,
$STICKNODE=/dev/sdc):
$ sudo ./copy2img.sh $STICKNODE
And then rename the .img file produced to something more memorable.
=== DreamPlug Preparation ===
Prepping a vanilla DreamPlug device is somewhat involved and will require a
access to the hardware serial console (eg, using a GuruPlug-branded JTAG device
functions as a USB serial console adapter).
The default SD card images include the u-boot firmware required to boot from
the card. Insert a flashed SD card into the DreamPlug and connect to the
powered-off DreamPlug using the serial converter with the screen command:
$ screen /dev/ttyUSB0 115200
Power up the DreamPlug and quickly press enter in the screen session to
interrupt boot. Then enter the following commands into the running u-boot
session (change the last argument of the 'sf write' line, in hex, if the .kwb
file size changes from exactly 196076 bytes):
usb start
fatload usb 1 0x6400000 uboot.2012.04.01-2_armel.kwb
sf probe 0
sf erase 0x0 0x80000
sf write 0x6400000 0x0 0x2fdec
setenv baudrate 115200
setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root} ${x_bootargs_console}; bootm 0x6400000 0x6900000;'
setenv x_bootargs_console 'ttyS0,115200'
setenv x_bootargs_root 'root=/dev/sdb2 rootdelay=10'
setenv x_bootcmd_initrd 'fatload usb 1:1 0x6900000 uInitrd'
setenv x_bootcmd_kernel 'fatload usb 1:1 0x6400000 uImage'
setenv x_bootcmd_usb 'usb start'
saveenv
reset
The DreamPlug should now boot straight up as a torouter; connect via ethernet
on the LAN port (eth1, "to the right") to access the web user interface and
configure wifi.
