How to install Debian on the DreamPlug
This page aims to describe how you can install Debian on a DreamPlug. Thanks to Clint for helping me figure things out!
Before you start, make sure that you have the following packages installed on your computer: debootstrap, fdisk (you can also use GParted) and screen. You will also need a USB stick. Please note that you will be installing the Debian base system with a very small set of packages, not a full system install.
Step 1: Prepare the USB stick
Grab a USB stick and create a small FAT16 partition and a big Linux partition (I used ext3) on it. You can do all this with GParted if you're not used to the command line.
Below is the partition table for my 4GB USB stick:
Device Boot Size Id System /dev/sdb1 165M 6 FAT16 /dev/sdb2 3.75GB 83 Linux
The first partition will hold the kernel image, and the second partition will hold the root filesystem (i.e. the filesystem which will be mounted as
Step 2: Download and copy uImage to the USB stick
Download the following two files to your hard drive and confirm that the MD5 hashes match:
$ wget http://dreamplug.googlecode.com/files/uImage $ wget http://dreamplug.googlecode.com/files/uImage.MD5.txt
You can run md5sum uImage to calculate the hash and compare this to the hash in uImage.MD5.txt.
Alternatively to downloading a manufacturer-provided kernel image, it is possible (but more inconvenient) to build a uImage from a stock Linux kernel. See http://sheeva.with-linux.com/sheeva/
Mount the FAT16 partition of the USB stick and copy over the uImage. Make sure you replace /dev/sdb1 and /path/to/uImage with the correct path:
# mkdir /media/fat16 # mount /dev/sdb1 /media/fat16 # cp /path/to/uImage /media/fat16 # umount /media/fat16
Step 3: Put the Debian installer on the USB stick
Mount the Linux partition of the USB stick and put the Debian installer on it. Make sure you replace /dev/sdb2 with the correct path. If you want to add more packages, simply add them on the --include line below:
# mkdir /media/ext3 # mount /dev/sdb2 /media/ext3 # debootstrap --foreign --arch=armel --variant=minbase --include=linux-image-2.6-kirkwood,module-init-tools,udev,netbase,net-tools,ifupdown,iproute,whiptail,vim-tiny squeeze /media/ext3 http://cdn.debian.net/debian/
Step 4: Additional configuration
I suggest that you take a couple of minutes to edit some of the files in /media/ext3/etc. Some of the files you would normally expect to find in this directory will either be empty, contain the wrong information or not exist at all.
Copy over your /etc/hosts file to the USB stick and edit it (only necessary if you have some fancy setup or want to change the hostname of the device):
# cp /etc/hosts /media/ext3/etc/ # vim /media/ext3/etc/hosts
If you changed the hostname in the hosts file, make sure you also edit the hostname file:
# vim /media/ext3/etc/hostname
The file /media/ext3/etc/apt/sources.list is empty by default. I suggest you copy over your version from /etc/apt/sources.list and edit it accordingly:
# cp /etc/apt/sources.list /media/ext3/etc/apt/ # vim /media/ext3/etc/apt/sources.list
Alternatively, this may work as a reasonable Squeeze sources.list configuration file:
deb http://ftp.de.debian.org/pub/debian/ squeeze main non-free contrib deb-src http://ftp.de.debian.org/pub/debian/ squeeze main non-free contrib deb http://security.debian.org/ squeeze/updates main
If you used squeeze in the debootstrap line in strep 3, then you will want to edit the sources.list file to also use squeeze. You may also want to edit /etc/network/interfaces.
When you are done modifying files on the USB stick, unmount it and unplug it from your machine:
# umount /media/ext3
You may need to change more or less things depending on if you're using debootstrap or multistrap (e.g. multistrap automatically manages
Step 5: Prepare the DreamPlug
The remaining steps in this howto requires that you use the JTAG board. This is an optional item and is not included by default when you buy the DreamPlug. If you don't have the JTAG board at this point, go buy one immediately.
Make sure that the DreamPlug is powered off. Plug your USB stick into one of the two USB ports, and connect the DreamPlug to the JTAG board. Make sure that the cables are connected properly to the JTAG and UART ports.
If you are unsure how to connect the DreamPlug to the JTAG board, see the user guide for instructions. You can download the user guide from http://dreamplug.googlecode.com/files/DreamPlug%20User%20Guide_US_v1.1.pdf
Before you power on the DreamPlug, you will want to make sure that you can see what's happening the second it boots. Check that the USB cable from the JTAG board is plugged into your computer, and run the following command:
# screen /dev/ttyUSB0 115200
One thing to note with the above command is that the device may not show up as ttyUSB0 (my computer sees it as ttyUSB2). You can run dmesg to see which number you should be using. The number at the end of the line above (115200) is the bits-per-second rate for the serial connection. If successful, you should have a blank terminal with a white square cursor in the top left corner.
Step 6: Power it on and interrupt the boot sequence
When you're ready, power on the DreamPlug and hit any key to interrupt the boot sequence. If you're too slow and the system starts to boot, simply pull out the power and try again. You should see something like this when it boots:
U-Boot 2011.06-02334-g8f495d9-dirty (Mar 28 2011 - 05:21:06) Marvell-DreamPlug SoC: Kirkwood 88F6281_A0 DRAM: 512 MiB SF: Detected MX25L1606 with page size 256, total 1 MiB In: serial Out: serial Err: serial Net: egiga0, egiga1 88E1121 Initialized on egiga0 88E1121 Initialized on egiga1 Hit any key to stop autoboot: 0
If you interrupt the boot at the right time, you should see a prompt with Marvell>>.
Step 7: Start the USB devices
So you have powered up the DreamPlug, interrupted the boot sequence and you are now looking at a prompt. To start the USB devices, type the following:
Marvell>> usb start
If successful, you should see a message saying that USB and storage devices was found. If this is the case, jump to step 8.
If you see a message saying Device NOT ready, try again. If, after a couple of attempts, it still doesn't work, jump to step 9.
Step 8: If you can successfully start the USB devices
Run the following two commands to set some environment variables:
Marvell>> setenv x_bootcmd_kernel fatload usb 2:1 0x6400000 uImage Marvell>> setenv x_bootargs_root root=/dev/sdc2 rootdelay=10 panic=10 init=/bin/bash
fatload usb 2:1 0x6400000 uImage means "There should be a FAT partition at the USB device
1, let's use the file named
uImage in there as our kernel". In a nutshell, use
fatload usb 0:1 for the internal microSD card,
fatload usb 1:1 for the SD card slot, or
fatload usb 2:1 for a USB stick.
/dev/sdc2 should be the root filesystem (that is, the EXT3 partition you debootstrapped or multistrapped earlier) on your USB stick. Use
/dev/sda2 for the internal microSD card or
/dev/sdb2 for the SD card slot.
If you want the DreamPlug to use these settings from now on, issue command below. You might want to skip this step in order to boot from a device just once.
When you are ready, run the following command to boot:
Once you've booted Debian, jump to step 10.
Step 9: If you cannot successfully start the USB devices
For some strange reason, I could not seem to start the USB devices. Whenever I tried to run usb start, I would get a message saying Device NOT ready. This also happened when there were no USB devices attached to the DreamPlug. After trying three different USB sticks and wasting a lot of time, I decided to install Debian from inside Ubuntu.
Booting it should show the following on the serial line:
reading uImage 2712400 bytes read ## Booting kernel from Legacy Image at 06400000 ... Image Name: Linux-18.104.22.168 Created: 2011-02-08 8:18:48 UTC Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 2712336 Bytes = 2.6 MiB Load Address: 00008000 Entry Point: 00008000 Verifying Checksum ... OK Loading Kernel Image ... OK OK Starting kernel ... Uncompressing Linux... done, booting the kernel. Linux version 22.214.171.124 (firstname.lastname@example.org) (gcc version 4.2.1) #1 PREEMPT Tue Feb 8 03:18:41 EST 2011 CPU: Feroceon 88FR131  revision 1 (ARMv5TE), cr=00053977
Power up the DreamPlug and boot into Ubuntu. Log on as root (the default username and password is root/nosoup4u) and see if the system finds your USB stick:
root@ubuntu:~# df -h
Chances are that Ubuntu automounted your USB stick as /media/usb0 and /media/usb2. This is what it looks like on my system:
Filesystem Size Used Avail Use% Mounted on /dev/sdc1 165M 2.6M 163M 2% /media/usb0 /dev/sdc2 3.7G 222M 3.3G 7% /media/usb2
You don't want these devices mounted on /media, so unmount now:
root@ubuntu:~# umount /media/usb0 root@ubuntu:~# umount /media/usb2
Mount the Linux partition of your USB stick on /mnt:
root@ubuntu:~# mount /dev/sdc2 /mnt
Once that's done, run the following set of commands to continue with the Debian installation if you used the debootstrap method:
root@ubuntu:~# chroot /mnt /bin/bash root@ubuntu:~# /debootstrap/debootstrap --second-stage
When debootstrap completes, you should see a line saying I: Base system installed successfully. If you see errors of some kind, try again. If it still doesn't work, try the whole process again with a different USB stick.
The next step is to write a line to /etc/inittab and set a root password:
root@ubuntu:~# echo 'T0:2345:respawn:/sbin/getty -L ttyS0 115200 linux' >> /etc/inittab root@ubuntu:~# passwd root
When you're done setting a strong and secure password, run the following commands to finalize the installation on the USB stick:
root@ubuntu:~# exit root@ubuntu:~# umount /mnt root@ubuntu:~# reboot
When the system starts up again, interrupt the boot sequence and enter the following commands:
Marvell>> setenv x_bootargs_root root=/dev/sdc2 rootdelay=10 Marvell>> boot
Once you've booted Debian, proceed to step 10.
Step 10: Copy the system from the USB stick to the microSD card
TODO: if you didn't do step 9 and thus didn't set a password, how do you log on to the device? Default username/password, maybe?
When the system has finished booting, you should see a line that says Debian GNU/Linux 6.0 and a login prompt. Log in as root.
To allow the DreamPlug to boot Debian without external storage, copy the /dev/sdc2 partition to /dev/sda2 (which is what Linux will call the ext3 partition of your microSD card):
mkdir /mnt/sda2/ cd /mnt/ mount -t ext3 /dev/sda2 /mnt/sda2/ cd /mnt/sda2 mv * old-fs-data/ # keep the old FS around in case we want to rescue cp -arvx / /mnt/sda2/ # this copies from /dev/sdc2 to /dev/sda2 cd / umount /mnt/sda2/
Once that's done, reboot the system.
To then return to fully booting off of microSD so you can repurpose the USB stick, interrupt the boot sequence and enter the following commands:
Marvell>> setenv x_bootcmd_kernel fatload usb 0:1 0x6400000 uImage Marvell>> setenv x_bootargs_root root=/dev/sda2 rootdelay=10 Marvell>> saveenv Marvell>> reset
If you did everything right, your DreamPlug should now boot Debian without any external storage.
Step 11: Set up a symlink for kernel module loading
You may also want to setup a symlink for kernel module loading until you have a new kernel:
ln -s /old-fs-data/lib/modules/126.96.36.199/ /lib/modules/188.8.131.52 ln -s /old-fs-data/lib/firmware/mrvl/ /lib/firmware/mrvl
Step 12: Wireless Access Point
If you want to run a wireless AP with the built in chipset, do the following:
wget http://spinifex.net/plugs/downloads/dreamplug/uaputl.zip unzip uaputl.zip ./uaputl
Step 13: Happy hacking
At this point, you can do whatever you want. I suggest installing openssh-server so that you can drop the JTAG board and connect to the device via SSH. You may also want to look at [https://trac.torproject.org/projects/tor/wiki/doc/TorDreamPlug] for instructions on how to install Tor, how to configure Tor as a bridge or a relay, how to set up an open Wifi that routes over Tor transparently etc.