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

Project wiki page: https://trac.torproject.org/projects/tor/wiki/doc/Torouter

= Repository Contents =

  README            this file
  ./doc             (WIP) text file 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 several ways to get the debian-based torouter system running on a
DreamPlug device:

 - Flash a pre-built image onto an external USB stick

 - Flash a pre-built image onto an internal microSD card

 - Build and flash a new image from source

 - Install the FreedomBox distribution or a "vanilla" debian, then run a
   torouter takeover/upgrade script

For the later, see the "Building" section, then follow either the USB stick or
microSD 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 included GuruPlug JTAG device.

=== Flash Pre-Built Image to External USB stick ===

TODO:

    $ dd if=$IMGFILE of=$USBBASEDEV

=== Flash Pre-Built Image to Internal microSD card ===

TODO:

    $ dd if=$IMGFILE of=$USBBASEDEV

Mount the device, make changes to /etc/fstab. Also need to make changes to the
initrd image?

Make changes to u-boot configuration.

=== 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 a USB
stick. Insert a USB storage device and partition it to have a small (~80MB)
boot partition followed by an ext3 root partition (1GB or so minimum). 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 thumb
stic! 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 stick quickly), run the
copy2img.sh script with the "base" device of the thumbstick as an argument (eg,
$STICKNODE=/dev/sdc):

    $ sudo ./copy2img.sh $STICKNODE

=== 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). 

First, upgrade u-boot to a recent version (see directions in freedom-maker
directory), then set the appropriate bootloader environment variables:

    baudrate=115200
    bootargs=console=ttyS0,115200 root=/dev/sdc2 rootdelay=10
    bootcmd=${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;
    bootdelay=3
    filesize=2982D0
    stderr=serial
    stdin=serial
    stdout=serial
    x_bootargs=console=ttyS0,115200
    x_bootargs_root=root=/dev/sdc2 rootdelay=10
    x_bootcmd_ethernet=ping 192.168.2.1
    x_bootcmd_initrd=fatload usb 2:1 0x6900000 uInitrd
    x_bootcmd_kernel=fatload usb 2:1 0x6400000 uImage
    x_bootcmd_usb=usb start

FYI, there are at least two variants of the DreamPlug hardware, with slightly
differing chipsets.