_                        _            
| |_ ___  _ __ ___  _   _| |_ ___ _ __ 
| __/ _ \| '__/ _ \| | | | __/ _ \ '__|
| || (_) | | | (_) | |_| | ||  __/ |   
 \__\___/|_|  \___/ \__,_|\__\___|_|   

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

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,

    $ 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'

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.