Gentoo on the QNAP TurboStation TS109/TS209

1.  Overview

The installation works this way: You telnet into the actual QNAP firmware installed on your machine, so you can flash an initramfs and a kernel to boot it into an installation environment. This will replace the QNAP firmware.

Once you've installed it like a normal Gentoo system, the kernel will be located on one partition of the flash device, an initramfs will be located into another flash partition that will let you boot into your Gentoo installation on your hard disk.

With the newest U-Boot version you would be able to recover the device in case something goes wrong and you didn't break or touched the U-Boot partition.

This guide is pretty much based on Martin Michlmayr's guide about installing on Debian, so if you don't understand what I wrote before chapter 5, please check his guide, or mail me.

2.  Requirements

To be able to install Gentoo, you'll need the following:

• A QNAP TurboStation device
• One internal SATA disk installed
• A network connection
• Another machine from where you can reach your QNAP device with an ssh and a telnet client installed. For example i've used net-misc/openssh for ssh and net-misc/telnet-bsd for telnet.
• An USB stick(if you haven't used QFinder in your device)
• A DHCP server(if you haven't used QFinder in your device)

3.  Before you start

Before you decide to install Gentoo on your QNAP device, please read the following FAQ on Martin Michlmayr's page about installing Debian, suited for your model:

• TS-209 FAQ

4.  Installing the installation environment

The most important thing, we'll do a backup of the current QNAP firmware, in case we may want to remove Gentoo, or in case we just want to return the device into its original state. The firmware is located in the following partitions: mtd1 contains the kernel, mtd2 and mtd3 contain the rootfs. We'll also flash the installation environment to our device.

You'll also need to do a backup of your hard disk, in case you have something on it, since we'll format it as well.

There are two ways of doing this, that depends wether you've used the QFinder application(which is the most common option if you have used your device) or not. We'll describe how to do it in both ways.

If you used QFinder

First you need to activate the remote login, so you can telnet to your device. Using the QNAP web interface, follow the following steps:

• Click on Administration, by default the user is admin and the password is admin
• Click on Remote login under System Tools
• Enable telnet and leave the port by default(13131) and press apply.

# telnet 192.168.0.131 13131 (replace this IP with yours)

13131 is the port used by your device for telnet. The user and password are the same as the web interface.

Once we're in, we'll do a backup of the current flash partitions, to do so, we'll change the directory to our current hard disk, and copy the contents of the partitions to it.

# cd /share/HDA_DATA/Public
# cat /dev/mtdblock1 > mtd1
# cat /dev/mtdblock2 > mtd2
# cat /dev/mtdblock3 > mtd3

Now we'll download the necessary files for installing the minimal enviroment for installing Gentoo. For doing so, we'll use wget.

# wget http://dev.gentoo.org/~armin76/arm/qnap/ts209/install/gentooinstall.initramfs
# wget http://dev.gentoo.org/~armin76/arm/qnap/ts209/install/gentooinstall.kernel
# wget http://dev.gentoo.org/~armin76/arm/qnap/ts209/install/flash-gentoo.sh

Once we have those files, we'll proceed to the flashing of them.

# sh flash-gentoo.sh

After the script is done, it will ask you to reboot the device. Do so, and go to the installation chapter

If you didn't use QFinder

The difference between the previous method, is that you don't need to enable telnet and that, unfortunately, wget isn't available. That means you'll need an USB stick where to save the backups of the flash partitions, and where you'll put the installation files of Gentoo for flashing them later.

As I already said on the requirements, you need a DHCP server running in your network, as the device is automatically configured for DHCP.

Connect the USB stick to your PC and put the files located here inside it. Put them in the root of your stick. Turn on your QNAP device and wait until it makes three beeps, after some minutes. Plug the USB stick on your QNAP. Check your DHCP server for what IP did the device got, and then telnet to it.

# telnet 192.168.0.131 13131 (replace this IP with yours)

After you're in, check where your USB stick has been mounted automatically, you can do so with the following:

# mount | grep external
/dev/sdi1 on /share/external/sdi type vfat [...]

We know that the stick has been mounted in /share/external/sdi(in this case). So lets change the directory.

# cd /share/external/sdi
# cat /dev/mtdblock1 > mtd1
# cat /dev/mtdblock2 > mtd2
# cat /dev/mtdblock3 > mtd3

Now that we have done a backup of the current flash, let's flash the install environment for Gentoo.

# sh flash-gentoo.sh

After the script is done, it will ask you to reboot the device. Remove the USB stick, reboot your device and keep reading.

5.  Accessing the install environment

After you reboot your device, it should boot to the Gentoo install environment, which is more or less a netboot environment, except that it doesn't boot from the network but from the flash.

Once the system is ready, the status led will change to green, and it will do a beep. If you have a DHCP server in your network, check its logs and see which IP the device got assigned. If the device failed to obtain an IP, it will default to 192.168.0.131.

For accessing the install environment you'll need to SSH in.

# ssh root@192.168.0.131 (replace this with the IP of the device)
Password: gentoo

You can now proceed to the installation chapter.

6.  Installing Gentoo

Overview

The installation on this device is more or less the same as any other kind of machine. However there are some very important differences. We need an initramfs for booting our system, and we need to flash the kernel and the initramfs to the flash. Therefore, we don't need a boot partition, we need genkernel to compile our kernel(or you can skip this by creating your own initramfs).

So please read and follow the ARM Handbook from the beginning, just skip the 10th chapter, as its irrelevant for our machine. I'll just explain what we have to do differently. Please read below first so you know when you have to go back to this document during the installation.

Partitions

As I already explained, we don't need a boot partition, although you can create it anyway if you want to have your kernels and initramfs separated from the main partition.

Stages information

Here's some information about the stages.

• Architecture: arm
• Subarchitecture: armv5tel
• CHOST: armv5tel-softfloat-linux-gnueabi
• Profile: default/linux/arm/2008.0

We'll be using the new EABI, also called gnueabi, instead of the old ABI. That is armel on Debian. There's no exact reason for why we should use this EABI and not the old one, apart that this one is better than the old. However, those who have the TS409 can only use the new EABI, as using old ABI binaries will make the processor hang. This is due to a problem in the design of the processor used on the TS409, called Marvell Orion 88F5281 D0. The TS109 and TS209 aren't affected by this problem, since they use the Marvell Orion 88F5182 A2 which doesn't have this problem.

Therefore, we need an armv5tel-softfloat-linux-gnueabi stage3 from the mirrors. Check out your nearest mirror , and look in /releases/arm/autobuilds for downloading a current stage3.

Configuring and installing the kernel

Here comes the most difficult part of all the Gentoo installation, so please be careful. This part should be done after chapter 6 of the handbook.

To configure and create our kernel along with an initramfs, after we've emerged our favourite flavour of the kernel, we have to emerge genkernel, so please do so.

However, with the genkernel version which is currently stable, we don't have the option to specify the real root partition in which our system will be. We need it so we don't have to touch the bootloader parameters. For doing this, we need the 9999 version.

# echo 'sys-kernel/genkernel **' >> /etc/portage/package.keywords
# emerge genkernel

After that, we have to start configure our kernel, we'll use the default config for the Orion processors, which is what our machine has. We'll also set the --real-root parameter to the device where our rootfs is located.

# genkernel --arch-override=arm --no-mountboot --makeopts=-j3 --kernel-config=/usr/src/linux/arch/arm/configs/orion5x_defconfig \
 --real-root=/dev/sda1 --menuconfig all

Configure the kernel as you would normally, but don't touch anything marked as built-in, since its needed for normal operation.

Due to the configuration of our system, as I already explained, we need an initramfs for booting, by default the Orion config doesn't have initramfs support enabled, so please enable it.

General setup --->
	[*] Initial RAM filesystem and RAM disk (initramfs/initrd) support
	()	  Initramfs source file(s)

After genkernel has finished, you need to prepare the initramfs and the kernel for flashing. To do so, you need to emerge sys-block/devio and dev-embedded/u-boot-tools.

# emerge devio u-boot-tools

Now you need to create an U-Boot image for flashing it to the flash.

# cd /boot
# tmp=$(tempfile)
# devio > $tmp 'wl 0xe3a01c06,4' 'wl 0xe381101d,4' # TS-109/209
# cat $kernel >> $tmp (replace $kernel by the kernel you just compiled with genkernel)
# mkimage -A arm -O linux -T kernel -C none -a 0x00008000 -e 0x00008000 -d $tmp image.uboot

We need to make the initramfs 4MB of size.

# dd if=$initramfs of=$initramfs.padded ibs=4194304 conv=sync (replace $initramfs by the name of the initramfs)

Now we flash both the kernel and the initramfs to the flash partitions, mtdblock1 and mtdblock2, respectively.

# cat image.uboot > /dev/mtdblock1
# cat $initramfs.padded > /dev/mtdblock2

Enabling SSH access

Now we add sshd to the startup of our system so we can access it when we boot into our new system.

# rc-update add sshd default

Emerging qcontrol

Qcontrol is an application that allows us to control some functions of our QNAP device, like the leds at the front, the buzzer, and the fan. Although i'd recommend not playing with the fan control. We'll use qcontrol for our device, mainly to make a beep and change the status led so we know when its ready or when its going to shutdown.

# echo 'sys-apps/qcontrol' >> /etc/portage/package.keywords
# emerge qcontrol

Let's not forget to add it to the startup of our system.

# rc-update add qcontrol default

Enabling serial console access (optional)

The following is for those who have access to the machine using the serial port. By default the ttyS0 port is configured to 9600bps. Thats okay if you have your client configured to 9600bps, however, as you probably know, the serial port on the machine is configured at 115200bps. So probably you want to change the speed of the port in the ttyS0 line of the /etc/inittab file.

Finishing the installation

This is pretty much all the installation, read all the recommendations of the handbook, and remember to change the root password and/or create some users. But please read the references, as they're very useful.

7.  References

This document is mainly based on the following guides and pages, please have a look at them, since they're very useful.

• Martin Michlmayr's page about Debian and the QNAP TS-209
• Info about U-Boot on the QNAP TS-209

8.  Thanks

I'd like to thank everyone who has helped me porting Gentoo to this machine, first QNAP Inc. since they provided us some hardware to do this porting and they've been very helpful.

Martin Michlmayr also helped me understanding some stuff of the QNAP machine and gave me some hints about the issues I was hitting. Also I would like to thank Andrew Gaffney for working hard on the netboot part of the catalyst and genkernel utilities.

9.  TODO

• Document the recover process

The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.