Installing Debian Squeeze On Pogoplug v3/Oxnas Cleanly

Disclaimer

All data and information provided in this tutorial is for informational purposes only. The author makes no representations as to accuracy, completeness, currentness, suitability, or validity of any information on this tutorial and will not be liable for any errors, omissions, or delays in this information or any losses, injuries, or damages arising from its display or use. All information is provided on an as-is basis.

In no event the author we be liable for any loss or damage including without limitation, indirect or consequential loss or damage, or any loss or damage whatsoever arising from loss of data or profits arising out of, or in connection with, the use of this tutorial.

Motivation

ArchLinux ARM ("ALARM") has officially dropped support for the PogoPlug v3/Oxnas in June 2013. Actually, the Oxnas port was already broken before due to ArchLinux' cutting edge philosophy and causing users many troubles, although it was working fine somewhen in 2012.

Various users have tried porting stable releases of Debian to the Pogoplug v3/Oxnas and documented their attempts in various forum postings (see References). I have tried their instructions, and although I learned a lot from them (actually I wouldn't have been able to put up this tutorial without them - thank you guys!) I have stepped over few shortcomings:

They set up more than just a base system with networking.
They rely on complicated scripts which suffer from breakage, skip warnings and require maintenance.
They do not work with the latest ALARM version from December 2012.
They don't provide enough instructions on how to set up the rootfs. Some users (varkey, shv) provide their own rootfs, but lack documentation how they were actually built.
Some of these rootfs are not cleanly built from scratch, but rather adopted from other rootfs (like doozan's rootfs for the kirkwood platform) and are cluttered with stuff which is not necessary for the proper operation of the v3/Oxnas, i.e. kirkwood kernels or binaries from the original Pogoplug distribution.
Some rootfs are hosted on not very trustworthy download platforms.

The main purpose of this tutorial is to provide instructions on how to build and install a Debian rootfs from scratch on the Pogoplug v3/Oxnas, using only official binaries from Debian and ALARM.

Requirements and assumptions

The tutorial assumes that you have the following prerequisites (other versions/distributions might work as well but could require other or additional packages):

A Pogoplug v3/Oxnas machine (well, obviously!) connected to the network via DHCP
ALARM installed on your Pogoplug v3/Oxnas according to the official tutorial.
The latest default kernel which comes with ALARM (Warhead SE's 2.6.31.6_SMP_820)
Another machine with a running live environment of Ubuntu (tested on Ubuntu 13.04 32bit with 8GB of RAM).
A working internet connection

Preparing the (live) environment

In this tutorial, we will not touch the existing ALARM installation but instead create a new Debian rootfs, which can be booted instead of the ALARM system. We do all the steps on our machine running the live Ubuntu environment.

Settings paths

Before we start, we want to set some shell variables so they reflect the directories, which will hold the contents of the ALARM and Debian rootfs:

export arch=/home/ubuntu/alarm

export pogodebian=/home/ubuntu/pogodebian-rootfs

Now, let's create these directories:

mkdir $pogodebian

mkdir $arch

Getting and extracting the ALARM rootfs

We need the latest ALARM rootfs. You should already have it on your ALARM stick, thus please copy it over and do the following only if you lost it or your ALARM stick got damaged:

wget http://os.archlinuxarm.org/os/oxnas/ArchLinuxARM-2012.12-oxnas.tar.gz

Now, extract the ALARM rootfs:

sudo tar xzvpf ArchLinuxARM-2012.12-oxnas.tar.gz -C alarm

Getting required software for building the Debian rootfs

This tutorial relies on debootstrap and qemu. Before we can install the required packages, we need to update the package lists in the live environment:

sudo apt-get update

Now we can install all need packages:

sudo apt-get install qemu-user-static debootstrap

Building the rootfs

This section covers the actual work - building the complete rootfs from scratch.

Debootstrapping stage1 and stage2

Debootstrap the first stage:

sudo debootstrap --verbose --arch armel --foreign squeeze $pogodebian/ http://ftp.de.debian.org/debian

(You may want to replace ftp.de.debian.org by a mirror near you.)

Copy over qemu into the debootstrapped system:

sudo cp /usr/bin/qemu-arm-static $pogodebian/usr/bin/

Mount various filesystems for the chroot:

sudo mount --rbind /dev $pogodebian/dev

sudo mount -t proc none $pogodebian/proc

sudo mount -o bind /sys $pogodebian/sys

Now we can chroot into the new system:

sudo chroot $pogodebian

And start the 2nd stage debootstrap process

debootstrap/debootstrap --second-stage

Once it has finished, we want to get out of the chroot:

exit

Copying over the pogo-specific stuff from ALARM

Copy over kernel modules from ALARM:

sudo cp -a $arch/lib/modules/2.6.31.6_SMP_820 $pogodebian/lib/modules/

create directory for the gmac firmware (corresponding to kernel):

sudo mkdir $pogodebian/lib/firmware/2.6.31.6_SMP_820

copy gmac firmware:

sudo cp -a $arch/lib/modules/gmac_copro_firmware $pogodebian/lib/firmware/2.6.31.6_SMP_820

Copy LED support binaries:

sudo cp -a $arch/sbin/proled $pogodebian/sbin/

sudo cp -a $arch/sbin/devmem2 $pogodebian/sbin/

Applying various fixes:

Fix owner for all files copied:

sudo chown -R root:root $pogodebian/lib/modules/2.6.31.6_SMP_820

sudo chown root:root $pogodebian/lib/firmware/2.6.31.6_SMP_820

sudo chown root:root $pogodebian/sbin/proled

sudo chown root:root $pogodebian/sbin/devmem2

Gunzip all kernel modules (debian squeeze/wheezy can't handle gzipped ones):

sudo gunzip -r $pogodebian/lib/modules/2.6.31.6_SMP_820/

(note: Outputs two times "Too many levels of symbolic links", ignore that)

Configure the base system:

First, chroot back into our rootfs:

sudo chroot $pogodebian

To, enable the constantly emited LED after bootup success, we need to edit /etc/rc.local and add these lines:

# turn on LED
/sbin/proled green

Of course, the LED should be turned off on shutdown. Thus we need to put the following into /etc/rc0.d/K081halt before the halt action (included in this excerpt):

log_action_msg "Will now halt"
/sbin/proled off
halt -d -f $netdown $poweroff $hddown

We also want to loading pogo-specific kernel modules on bootup, thus we need to add these lines to /etc/modules:

mii
gmac
oxnas-led

We also want shell concurrency and have no hardware lock, thus we need to add these lines to /etc/default/rcS:

HWCLOCKACCESS=no
CONCURRENCY=shell

Update the module dependencies as the system will not find the unzipped modules otherwise (corresponding to kernel):

depmod -a 2.6.31.6_SMP_820

Next, we need to populate the package sources by putting in this line to /etc/apt/sources.list:

deb http://ftp.de.debian.org/debian squeeze main

Now, we can refresh the package lists:

apt-get update

Once this is done, we install some basic packages (mostly required for networking and remote access):

apt-get install locales openssh-server usbutils psmisc dhcp3-client

We fix the locales by first commenting out our locale in /etc/locale.gen:

en_US.UTF-8 UTF-8

And re-generating them:

locale-gen

Of course, it's a good idea to set a root password:

passwd

Next, we set the hostname by editing /etc/hostname and replacing the stuff derived from the live environment by our own:

yourhostname

Now we populate /etc/fstab so our rootfs will get properly mounted on the next boot:

/dev/root      /               ext3    noatime,errors=remount-ro 0 1
tmpfs          /tmp            tmpfs   defaults          0       0

And configure the network by editing /etc/network/interfaces>:

auto lo eth0
iface lo inet loopback
iface eth0 inet dhcp
hwaddress ether xx:xx:xx:xx:xx:xx

Replace the xx:xx:xx:xx:xx:xx above by the real Mac address of your pogo!

Now exit the chroot again:

exit

That's it, we are now ready to copy the rootfs to our USB media.

Copying and finalizing

Plug in the USB media you want to use for your Debian Pogoplug installation. In the following, we assume that your media has been recognized as /dev/sdb and that you want to freshly format it, loosing all data that has been previously stored.

Be cautious! Using the wrong device may wipe the data on your computer!

Next, we wipe the partition table:

sudo dd if=/dev/zero of=/dev/sdb bs=512 count=1024

And create a new one using fdisk:

sudo fdisk /dev/sdb

You should get something like this:

Device contains neither a valid DOS partition table, nor Sun, SGI or OSF disklabel
Building a new DOS disklabel with disk identifier 0x274aa42c.
Changes will remain in memory only, until you decide to write them.
After that, of course, the previous content won't be recoverable.
Warning: invalid flag 0x0000 of partition table 4 will be corrected by w(rite)

Now, create a new primary partition over the whole USB drive using the n command like this:

Command (m for help): n
Partition type:
   p   primary (0 primary, 0 extended, 4 free)
   e   extended
Select (default p): p
Partition number (1-4, default 1): 1
First sector (2048-7813119, default 2048): 
Using default value 2048
Last sector, +sectors or +size{K,M,G} (2048-7813119, default 7813119): 
Using default value 7813119

Write the changes to the disk and exit fdisk using the w command:

Command (m for help): w
The partition table has been altered!
Calling ioctl() to re-read partition table.
Syncing disks.

Now that we have the disk partitioned, we can format it with the ext3 filesystem:

sudo mkfs.ext3 -m00 /dev/sdb1

Next we create a mount point on the live system:

sudo mkdir /mnt/pogostick

And mount the disk:

sudo mount /dev/sdb1 /mnt/pogostick

Almost done. We go to the chroot, copy all the stuff over to the USB stick and umount it:

cd $pogodebian

sudo cp -a . /mnt/pogostick/

sudo umount /mnt/pogostick

Finally, we plug out the USB stick, put it in the v3/Oxnas Pogoplug and boot it! If everything went fine, the LED should first flash green, then go our for a few seconds and finally become steadily green. We now should be able to ping the system and ssh into it and start playing with it.

Notes, caveats and shortcomings

The binary mkfs.ext3 is not always what you might think it is. Actually it's a symlink to mkfs.ext2, and depending on your /etc/mke2fs.conf file, it may not create an ext3 filesystem but ext4 or ext2 without warning. The Pogoplug v3/Oxnas kernel supports only ext3 though, so double-check that you really get the right filesystem created!.
This tutorial does not work for Debian Wheezy without further modifications. It boots up to the point where the LED is turned off and seems to hang then. If you know about the essentials bits which are missing, please contact me!
Installing of the Wifi Driver for the Pogoplug Pro is not covered here, thus the resulting rootfs has no wifi support without executing additional steps.