_ _ | |_ ___ _ __ ___ _ _| |_ ___ _ __ | __/ _ \| '__/ _ \| | | | __/ _ \ '__| | || (_) | | | (_) | |_| | || __/ | \__\___/|_| \___/ \__,_|\__\___|_| 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.