path: root/freedom-maker/README
diff options
authorficus <ficus@robocracy.org>2012-09-11 01:16:38 +0200
committerficus <ficus@robocracy.org>2012-09-12 01:25:30 +0200
commite55744bb195f0d665332ceb48acb57b4a4e186b5 (patch)
tree70824873c9dad07bf55c9e8101a97321f78fc6f5 /freedom-maker/README
parente109d94422d0687fc84d8aa1804c2b209785d0aa (diff)
update to FBx public-0.1 freedom-maker
Snapshot commit with no torouter-specific changes re-applied. Updated freedom-maker image to a significantly more recent version, used by the FreedomBox project. This includes a shift from debian "stable" to "testing" (wheezy), which has a Linux 3.2 kernel. date Fri, 24 Aug 2012 03:50:41 +0000 repo git://anonscm.debian.org/freedombox/freedom-maker.git commit de1f66f0651a3a7c306331eeda1db93535b1470a (public-0.1)
Diffstat (limited to 'freedom-maker/README')
1 files changed, 395 insertions, 37 deletions
diff --git a/freedom-maker/README b/freedom-maker/README
index 1428d26..6039861 100644
--- a/freedom-maker/README
+++ b/freedom-maker/README
@@ -1,60 +1,418 @@
Freedom-Maker - Bdale's building tools for the FreedomBox project
-Install required build packages:
- apt-get install multistrap qemu-user-static
+Welcome to the FreedomBox! This project is the central hub of the FreedomBox
+project, it builds and installs the file-system image that turns any computer
+into a FreedomBox.
-To build for a DreamPlug, use
+There are a couple ways to use this system:
- sudo ./mk_dreamplug_rootfs
+1. If you just want to use a FreedomBox and don't care about changing how it
+ works or mucking about in its insides (if you're like most people), you
+ should get a pre-built image from someone and copy it to an SD card or USB
+ drive. If you don't have a JTAG or don't know what one is, make sure to ask
+ for the SD card image.
-This will yield a file tree under build/dreamplug, representing the
-contents of a root file system. Get that onto a USB stick with a Linux
-friendly file system (ext3 and not vfat) with something like
+2. If you want to change and build on it, you can use:
- sudo mount /dev/sdc1 /media/freedom
- sudo rsync -atvz --progress build/dreamplug/ /media/freedom/
- sudo umount /media/freedom
+ A. A USB stick. This requires a JTAG, but doesn't require opening up the
+ DreamPlug, or,
-Move the USB stick to the DreamPlug, and arrange to boot the existing kernel
-from internal microSD pointing to our new root filesystem by interrupting the
-boot to talk to U-Boot:
+ B. A microSD card and adapter. You can use the one from inside the
+ DreamPlug. You won't need a JTAG, but you will need to open the DreamPlug
+ and void the warranty.
+*** Warning! There are no "training wheels" here .. read the scripts and
+*** understand what they're going to do before you run them...
+# Recent Firmware Necessary!
+Modern kernels need a relatively recent version of the u-boot firmware. If
+you still use old firmware (including what Global Scale ships on the units by
+default), then you need to update, which requires having the JTAG dongle (to
+gain console serial port access). One way to know you've got old firmware
+is if booting a Linux kernel results in errors about corrupt gzip data and
+a failure to launch the kernel.
+Note that re-flashing firmware will erase all configuration variables. If
+preserving your exising boot config is important, use printenv and make notes
+before proceeding. Also note that any time you're re-flashing boot firmware,
+there is a slight chance you could 'brick' your device leaving it unbootable.
+If that happens, the JTAG interface can be used to recover.
+The instructions for updating firmaware go something like this (thanks to
+Ian Campbell for his notes):
+ Using 2012.04.01-2 which is current Wheezy. Prep by mounting a USB stick.
+ wget http://http.debian.net/debian/pool/main/u/u-boot/u-boot_2012.04.01-2_armel.deb
+ dpkg-deb -x u-boot_2012.04.01-2_armel.deb u-boot_2012.04.01-2_armel
+ cp u-boot_2012.04.01-2_armel/usr/lib/u-boot/dreamplug/* /media/usbdisk
+ Move the USB stick to your DreamPlug. Flash the new firmare:
+ usb start
+ fatload usb 2 0x6400000 u-boot.kwb
+ sf probe 0
+ sf erase 0x0 0x80000
+ sf write 0x6400000 0x0 0x${filesize}
+ (You must, of course, fill in the size of the file you're loading in hex)
+At this point, you should be able to reset the DreamPlug and have it boot to
+a serial console prompt. If that fails, you'll need real JTAG magic to try
+Note that if you use the 'make usb' target to create a bootable USB stick
+image, we include the required firmware in /boot/dreamplug, so the above
+fatload command might be replaced with:
+ fatload usb 2 0x6400000 dreamplug/u-boot.kwb
+# To Use It
+You'll need to copy the image to the memory card or USB stick:
+1. Figure out which device your card actually is.
+ A. Unplug your card.
+ B. Run "df" to show you the list of devices your computer actually knows
+ about.
+ C. Plug your card in.
+ D. Run "df" again, your computer should know about a new device or two: your
+ memory card. It's probably "/dev/sd(someletter)". It *won't be*
+ /dev/sda.
+2. Decompress the image:
+ $ tar -xjvf freedombox-unstable_*.tar.bz2
+3. Copy the image to your card. Whatever you do, make sure you don't copy it to
+ /dev/sda. That'll break your system.
+ # dd bs=1M if=freedombox-unstable_*.img of=/dev/sd(thesameletter)
+ When picking a device, use the drive-letter destination, like /dev/sdb, not a
+ numbered destination, like /dev/sdb1. The device-without-a-number refers to
+ the entire device, while the device-with-a-number refers to a specific
+ partition. We want to use the whole device.
+Now, what you need to do depends on whether you're using the microSD card or USB
+stick method:
+- USB drive: You'll hook the JTAG up to the DreamPlug before booting and use the
+ JTAG to control the boot process, so we can boot from the USB drive.
+- microSD card: You'll put the microSD card into the DreamPlug's internal
+ microSD card slot and boot the DreamPlug. It'll restart once to finish the
+ install process, then it's ready to use.
+## Running from a microSD Card
+When DD has finished, take the microSD card out of your computer and plug it
+into your DreamPlug. If you have a JTAG, you can watch it boot. You'll see it
+restart once during the boot process. If you don't have a JTAG, wait a while (5
+minutes or less) and it'll be available over SSH (port 22). You might need to
+use nmap to find it:
+ $ nmap -p 22 --open -sV
+ ...
+ Interesting ports on
+ 22/tcp open ssh OpenSSH 6.0p1 Debian 2 (protocol 2.0)
+ Service Info: OS: Linux
+ ...
+Once you've found it, SSH into the box:
+ $ ssh root@
+## Running from a USB Stick
+Move the USB stick to the DreamPlug, obtain a serial console, and hit reset. A
+good way to access the serial console (actually USB serial emulation provided by
+the optional JTAG dongle), is to use 'screen', like so:
screen /dev/ttyUSB0 115200
-# Reboot the DreamPlug
-# You should see "Hit any key to stop autoboot: " - hit a key, any key
- setenv x_bootargs_root root=/dev/sdc1 rootdelay=10
- saveenv
- reset
-The system should boot to a login prompt and the default password is
-'freedom' for the root user.
+Interrupt the boot by pressing a key during the autoboot countdown, and type the
+following to boot from the USB stick:
+ setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
+ setenv x_bootcmd_kernel fatload usb 2 0x6400000 uImage
+ setenv x_bootcmd_initrd fatload usb 2 0x6900000 uInitrd
+ setenv x_bootargs_root root=/dev/sdc2 rootdelay=10
+ boot
+The system should boot to a login prompt, using only the bits on the stick.
+The default root password is 'freedom'. The normal user is "fbx" and the
+password is "frdm".
- - - - -
-If you want to set things up to boot from the internal microSD card, once
-you're logged into the system booted from root on USB stick you can use:
+To set things up to boot from the internal microSD card, once you're logged into
+the system booted from root on USB stick you can use:
- sh /boot/copy2dream.sh
+ /sbin/copy2dream
-If you choose to to reflash the device entirely you'll want to do the
-following to switch the root filesystem back to the internal microSD card:
+Note that if you don't have a reasonable system date and time set in the
+DreamPlug before running this command, you may see a long stream of warnings
+from tar about timestamps being in the future. It is safe to ignore these.
- screen /dev/ttyUSB0 115200
-# Reboot the DreamPlug
-# You should see "Hit any key to stop autoboot: " - hit a key, any key
+On reboot, you may want to interrupt the boot and type the following to ensure
+you boot from the internal microSD by default. This bootcmd line elides the
+time-consuming attempts to boot grom gigE, which makes boot go much faster:
+ setenv bootcmd '${x_bootcmd_usb}; ${x_bootcmd_kernel}; ${x_bootcmd_initrd}; setenv bootargs ${x_bootargs} ${x_bootargs_root}; bootm 0x6400000 0x6900000;'
+ setenv x_bootcmd_kernel fatload usb 0 0x6400000 uImage
+ setenv x_bootcmd_initrd fatload usb 0 0x6900000 uInitrd
setenv x_bootargs_root root=/dev/sda2 rootdelay=10
-- - - - -
+# To Make It
+If you want to build your own image yourself, you're more than welcome to.
+Whether you're using a USB drive or a microSD card, you'll need to ensure that
+it's at least 2 GB in size and that it has two partitons:
+1. The stick must start with a 128 MB FAT partition for the boot directory.
+2. The rest of the stick is an EXT2 partition, for the main installation.
+The rest of the steps you need to follow depend on whether you're using a USB
+stick or a microSD card.
+## Building on a USB Stick
+Partition a USB stick to have a small FAT partition and large ext2 partition,
+create a /media/freedom mount point, and add entries to /etc/fstab like:
+ /dev/sdb1 /media/freedom/boot vfat user,noauto 0 0
+ /dev/sdb2 /media/freedom ext2 user,noauto 0 0
+This will allow the Makefile to mount and unmount the stick at will.
+If you have a favorite Debian mirror, update the file fbx-base.conf setting the
+source= line.
+To populate the stick with bits for a DreamPlug, just plug it in to your
+computer and type:
+ make
+This will build a file tree under build/dreamplug, representing the contents of
+a root file system, then that content will be copied to the stick.
+## Building it on a microSD card.
+Changing the image and building your own is a simple 18 step process! Lots of
+thanks to Nick Hardiman for putting these instructions together.
+### Get Ready
+1. Start your workstation.
+2. Use a Debian OS, the version doesn't matter. A virtual image, such
+ as a VirtualBox image, is fine. Usually.
+3. Use the root account.
+### Prepare an SD Card
+4. Find a microSD card with SD card holder. It must be at least 2GB
+ in size.
+5. Insert the card into your workstation.
+6. Install a partition editor. Install parted if you are a masochist.
+ # apt-get install parted
+7. Create 2 partitions. Use cfdisk, parted, gparted or similar.
+ # cfdisk /dev/sdb
+ a. First partition: 128meg (no smaller or the kernel copy will run
+ out of room and make - see below - will end with an error).
+ b. Second partition: The rest of the card (anything over 600 MB
+ should work).
+8. Make a note of the SD card’s device name. Mine is /dev/sdb (my
+ workstation’s layout is simple: one disk called /dev/sda and
+ nothing else defined).
+9. Format the two partitions.
+ a. First partition: FAT
+ # mkdosfs /dev/sdb1
+ b. Second partition: ext3
+ # mkfs.ext3 /dev/sdb2
+10. Create the mountpoints on your workstation.
+ # mkdir -p /media/freedom/boot
+11. Mount the second partition.
+ # mount /dev/sdb2 /media/freedom/
+12. Mount the first partition.
+ # mount /dev/sdb1 /media/freedom/boot/
+13. Check your work.
+ # mount
+ sysfs on /sys type sysfs (rw,nosuid,nodev,noexec,relatime)
+ ...
+ /dev/sdb2 on /media/freedom type ext3
+ (rw,relatime,errors=continue,barrier=1,data=ordered)
+ /dev/sdb1 on /media/freedom/boot type vfat
+ (rw,relatime,fmask=0022,dmask=0022,codepage=cp437,iocharset=utf8,shortname=mixed,errors=remount-ro)
+### Clone the Git Repository
+14. Install git.
+ # apt-get install git
+ Reading package lists... Done
+ ...
+ After this operation, 15.3 MB of additional disk space will be used.
+ Do you want to continue [Y/n]?
+ ...
+15. Clone Nick Daly’s repository.
+ $ git clone https://github.com/NickDaly/freedom-maker.git
+ Cloning into 'freedom-maker'...
+### Create the Debian OS.
+16. Change to the new directory.
+ $ cd ~/freedom-maker/
+17. Kick off:
+ $ make weekly-card
+18. Enter your password when asked by "sudo". If that fails, run:
+ $ su -c "make weekly-card"
+If you do that, you'll need to enter the root password to build the image.
+The next part took about an hour, but required no input from me. Packages were
+downloaded. Lots of commands were run. Many harmless errors were ignored:
+ sysvinit: restarting...init: timeout opening/writing control channel /run/initctl
+ .init: timeout opening/writing control channel /run/initctl
+ ...
+There was good news:
+ Multistrap system installed successfully...
+ Copying the source directory to the FreedomBox root.
+There was an enormous amount of this:
+ bin/bash
+ 818092 100% 7.07MB/s 0:00:00 (xfer#1, to-check=1102/1123)
+ bin/cat
+ 42736 100% 362.91kB/s 0:00:00 (xfer#2, to-check=1101/1123)
+ bin/chgrp
+ 54996 100% 383.62kB/s 0:00:00 (xfer#3, to-check=1100/1123)
+ ...
+Finally an image is copied and zipped up for redistribution:
+ dd if=/dev/sdb of="freedombox-unstable_`date +%Y.%m%d`.img" bs=1M
+ 3781+1 records in
+ 3781+1 records out
+ 3965190144 bytes (4.0 GB) copied, 266.174 s, 14.9 MB/s
+ Image copied. The microSD card may now be removed.
+ tar -cjvf "freedombox-unstable_`date +%Y.%m%d`.tar.bz2"
+ "freedombox-unstable_`date +%Y.%m%d`.img"
+ freedombox-unstable_2012.0705.img
+The end. Hooray! The SD card is ready for the DreamPlug.
+# To Understand It
+Be aware that this is a *very* imcomplete solution for now, suitable only
+for developers .. you will want to at least do things like create unique
+ssh host keys for your device!
+Digging into the code should be fairly straightforward. There are only six
+files you need to be aware of:
+- /Makefile: The makefile that describes and builds the system.
+- /mk_dreamplug_rootfs: Builds the DreamPlug's root file-system.
+- /bin/projects: The place for external projects to hook into and customize
+ themselves before they're copied to the image.
+- /bin/finalize: Finalizes and prepares the build for booting.
+- /source: The root file system.
+- /source/install.sh: Pre-boot configuration that needs to be run on the device
+ itself (from within a chroot).
+## Makefile
+There are three major targets to be aware of:
+- dreamstick: The default target. This loads an image to a USB drive that can
+ be used to install the FreedomBox without opening up your DreamPlug and
+ voiding the warranty. You'll need a JTAG, though.
+- weekly-card: The target used to produce the weekly FreedomBox test release.
+ This will copy the image to a card that can be popped directly into the
+ microSD card slot in the DreamPlug. The DreamPlug will boot happily without
+ needing a JTAG.
+- stamp-dreamplug-rootfs: The root file system itself. It doesn't get installed
+ anywhere (that's done by the other two targets), but is a good way to test
+ whether the image will actually build, without waiting for all that pesky
+ hardware I/O.
+## mk_dreamplug_rootfs
+Starts building the system by creating all the destination directories and
+installing the base system.
+## /bin/projects
+Where projects that want to integrate into the FreedomBox should hook into.
+Keep in mind, we aren't in a chroot at this point. The only environment
+variables you'll probably need are:
+- user: The non-root user's name (uid = 1000).
+- homedir: The non-root user's home-directory.
+## /bin/finalize
+Getting the system ready for boot, doing the things that don't need to be done
+inside a chroot. You probably don't need to change this.
+## /source
-To turn the device into a Torouter you'll want to do the following:
- # ssh or login to the router
- wget https://gitweb.torproject.org/torouter.git/blob_plain/HEAD:/packages/torouter_easy_setup.sh
- bash torouter_easy_setup.sh
- reboot
+The root file system on the DreamPlug. Modify this, and you're modifying what
+ends up on the FreedomBox.
-This should result in a proper Torouter without any need for further configuration.
+## /source/install.sh
-Be aware that this is an imcomplete solution for now .. you will want to at
-least do things like create unique ssh host keys for your device!
+This is executed from a chroot during the build process to do configuration that
+needs to be done on the device itself. You shouldn't need to modify this. If
+you're installing a project that needs to change how the system configures
+itself, you're probably doing something wrong.