Gentoo Logo

Disclaimer : This document is a work in progress and should not be considered official yet.


Gentoo on the QNAP TurboStation TS409

Content:

1.  Overview

Warning: THIS GUIDE WON'T WORK WITH NEWER DEVICES LIKE TS419, IT WILL BRICK YOUR NAS AND I WON'T BE ABLE TO HELP YOU!!!

Warning: If you never installed Gentoo into a normal system, please just forget about installing it on your QNAP device as it will render it unusable unless you have serial access.

Important: I would highly recommend that you have serial access on your QNAP device, as this only has been tested by me and some problems may occur that couldn't be debugged without serial access

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:

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.

Code Listing 4.1: Telnet to your device

# 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.

Code Listing 4.2: Doing a backup of the contents of the flash

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

Important: Remember to extract those three files from the hard disk, before you do anything else, as you will have to format your hard disk when installing Gentoo.

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

Code Listing 4.3: Downloading the files for flashing

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

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

Code Listing 4.4: Flashing the files

# 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.

Code Listing 4.5: Telnet to your device

# 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:

Code Listing 4.6: Checking the mount point

# 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.

Code Listing 4.7: Doing a backup of the contents of the flash

# 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.

Code Listing 4.8: Flashing the files

# 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.

Code Listing 5.1: Accessing through SSH

# 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.

Note: Remember that you need at least a 2.6.27 kernel for the TS-409

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.

Code Listing 6.1: Emerging genkernel

# 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.

Code Listing 6.2: Running genkernel

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

Warning: Please remember to set the --real-root parameter accordingly!

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.

Code Listing 6.3: Enabling initramfs support

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

Warning: If you don't enable it, you won't be able to boot your new system!

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.

Code Listing 6.4: Emerging needed packages

# emerge devio u-boot-tools

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

Code Listing 6.5: Creating an U-Boot image

# cd /boot
# tmp=$(tempfile)
# devio > $tmp 'wl 0xe3a01c06,4' 'wl 0xe3811041,4' # TS-409
# 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

Warning: Please, be sure that you did the correct devio command according to your device!

We need to make the initramfs 4MB of size.

Code Listing 6.6: Making 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.

Code Listing 6.7: Flashing the images

# 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.

Code Listing 6.8: Adding sshd to the startup

# rc-update add sshd default

Warning: It's *REALLY* important that you do this, since if you don't have serial access to the machine, you won't be able to login to the system!!

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.

Code Listing 6.9: Emerging qcontrol

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

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

Code Listing 6.10: Adding qcontrol to the startup

# 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.

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


Print

Page updated December 31, 2008

Summary: This guide shows you how to install Gentoo on the QNAP Turbostation NAS.

Raúl Porcel
Author

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.