aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorficus <ficus@robocracy.org>2012-09-22 18:07:42 +0200
committerficus <ficus@robocracy.org>2012-09-22 18:07:42 +0200
commite2973e8ea5c57bfa6ed41293e0250c68d29cfed9 (patch)
treec198195bfc91800d93300788c85efba3feaaa050 /README
parente6d4f095e61d0c875a11cec57302db9f2fd5838f (diff)
downloadtorouter-e2973e8ea5c57bfa6ed41293e0250c68d29cfed9.tar.gz
torouter-e2973e8ea5c57bfa6ed41293e0250c68d29cfed9.zip
backup WIP
Diffstat (limited to 'README')
-rw-r--r--README137
1 files changed, 117 insertions, 20 deletions
diff --git a/README b/README
index 8ba5f55..c830ded 100644
--- a/README
+++ b/README
@@ -1,33 +1,130 @@
-This is the place where we put all things relating to the Torouter.
+ _ _
+| |_ ___ _ __ ___ _ _| |_ ___ _ __
+| __/ _ \| '__/ _ \| | | | __/ _ \ '__|
+| || (_) | | | (_) | |_| | || __/ |
+ \__\___/|_| \___/ \__,_|\__\___|_|
-The project home page:
-https://trac.torproject.org/projects/tor/wiki/doc/Torouter
+Project wiki page: https://trac.torproject.org/projects/tor/wiki/doc/Torouter
-The project road map:
-https://trac.torproject.org/projects/tor/wiki/doc/Torouter/Roadmap
+= Repository Contents =
-Your DreamPlug has arrived in a disabled state - you will need to hack it:
+ 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
-0) re-flash from inside the OS it shipped with:
- https://trac.torproject.org/projects/tor/wiki/doc/DebianDreamPlug#Step9:IfyoucannotsuccessfullystarttheUSBdevices
+= Installation and Build Instructions =
-1) Create a bootable USB disk, attach the JTAG, boot/re-flash, ..., anonymity!
+There are several ways to get the debian-based torouter system running on a
+DreamPlug device:
-2) A new thing that is currently undocumented
+ - Flash a pre-built image onto an external USB stick
-To create a Torouter from this repository you'll want to clone it:
+ - Flash a pre-built image onto an internal microSD card
- git clone git://git.torproject.org/torouter.git
+ - Build and flash a new image from source
-Please see the freedom-maker/README if you wish to create a bootable USB disk.
-You will want a USB disk and the DreamPlug JTAG for reflashing, reinstalling,
-and development related activities.
+ - 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.
-If you wish to turn a DreamPlug into a Torouter simply follow these steps:
+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.
-scp torouter_easy_setup.sh DreamPlug:/tmp/
-ssh DreamPlug torouter_easy_setup.sh
+=== 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.
-The DreamPlug should now be configured as a Torouter.