_ _ | |_ ___ _ __ ___ _ _| |_ ___ _ __ | __/ _ \| '__/ _ \| | | | __/ _ \ '__| | || (_) | | | (_) | |_| | || __/ | \__\___/|_| \___/ \__,_|\__\___|_| 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: TODO: XXX: FYI, there are at least two variants of the DreamPlug hardware, with slightly differing chipsets.