Installing OpenWrt on the Seagate DockStar

Eric Cooper <>

September 2010


This HOWTO is obsolete and is provided here for historical purposes only. Please see this page for updated instructions.


  1. Introduction
  2. Using pre-built images (no assembly required!)
  3. Installing the images
  4. Upgrading the firmware with new OpenWrt images
  5. Miscellaneous tips and tricks
  6. Building your own OpenWrt kernel and root filesystem images
  7. Installation using a serial cable
  8. Troubleshooting
  9. Restoring the factory firmware


This document describes how to install an OpenWrt kernel and rootfs on the internal NAND flash of the Seagate FreeAgent DockStar™ so that it will boot into OpenWrt at power-on, with no USB storage device required.

The main method presented here does not require opening the case or attaching a serial cable, just using the Linux command line on the DockStar. But I also describe a method that does use a serial cable to interact with the u-boot bootloader. This was the approach I initially used to get OpenWrt working on the DockStar, but it should only be necessary now if the first approach fails for some reason.

If you've never used OpenWrt before, this guide is a good starting point. Further help can be found by searching the OpenWrt Wiki, the OpenWrt forums, or asking on the #openwrt IRC channel on

Important: if possible, do not connect your DockStar to the outside Internet prior to re-flashing. Otherwise the factory firmware will automatically "phone home" and modify itself, making it more difficult to connect via ssh.

Using pre-built images (no assembly required!)

If you don't want to compile your own OpenWrt firmware, you can simply download a pre-built kernel image and root filesystem image.

Installing the images

  1. Obtain the kernel and rootfs images as described above. Copy them to a USB flash drive.

  2. Download the blparam program from Cloud Engines and copy it to the USB drive.

  3. Follow Alexander Holler's instructions to connect to your DockStar via ssh. If you previously connected the DockStar to the Internet, you might have to follow these instructions instead.

    The following instructions should be executed on the DockStar.

  4. Kill off some unneeded processes:

    # killall -9 hbwd
    # killall -9 hbplug
  5. Insert the USB drive in the DockStar, mount it somewhere, and change to that directory:

    # mount /dev/sda1 /mnt
    # cd /mnt
  6. Make a backup of the factory firmware onto the USB drive if you think you might want to restore it some day.

  7. Set the magic u-boot parameters. These are case-sensitive, so make sure you type them correctly.

    # ./blparam arcNumber=2097
    # ./blparam mainlineLinux=yes
  8. Now you're ready to flash the kernel and rootfs images onto your DockStar. WARNING: perform the following steps in exactly this order, and double-check everything you type before hitting return. If you overwrite the u-boot partition by mistake, you will brick your DockStar and you will have to use a JTAG cable to recover.

    # flash_eraseall /dev/mtd1
    # nandwrite /dev/mtd1 dockstar-uImage
    # flash_eraseall /dev/mtd2
    # nandwrite /dev/mtd2 dockstar-rootfs
  9. Erase the rootfs_data partition so that OpenWrt will create a jffs2 overlay filesystem there when it boots. It's OK if this step fails with a "read-only filesystem" error.

    # flash_eraseall /dev/mtd3
  10. That's all there is to it. Unmount and remove the USB drive and power-cycle the DockStar. It should reboot into OpenWrt.

    If you're using my pre-built images, it will request an IP address via DHCP. If you compiled your own firmware and didn't change the default configuration, it will use the static address

Upgrading the firmware with new OpenWrt images

After you've installed OpenWrt on your DockStar, configured it to your liking, and used it for a while, you will eventually want to upgrade the firmware (to a new OpenWrt release, or a custom build with additional kernel modules, for example).

I've used the following procedure to upgrade my DockStar from one version of OpenWrt to another.

  1. Make a backup of your DockStar, because you will be re-flashing it to the default configuration. I use rsync for this.

    Copy at least the /etc/config directory. Depending on your setup you may want to back up additional files. It's also useful to save the list of additional packages you've installed:

    # opkg list_installed
  2. Build or download the new firmware (uImage and rootfs) that you want to flash. Make sure the files are padded to a 128K multiple. Transfer them to the /tmp directory on the DockStar using scp, rsync, or a USB drive.

  3. Login to the DockStar and execute the following. You may need to install the mtd-utils package on your DockStar if the flash_eraseall and nandwrite utilities are not found.

    # cd /tmp
    # md5sum new-uImage new-rootfs
    (verify that the MD5 checksums match the originals before proceeding)
    # flash_eraseall /dev/mtd1
    # nandwrite /dev/mtd1 new-uImage
    # flash_eraseall /dev/mtd2
    # nandwrite /dev/mtd2 new-rootfs

    The /dev/mtd3 partition is in use by a mounted filesystem (/overlay) so you need to reboot immediately after erasing it:

    # flash_eraseall /dev/mtd3
    # reboot
  4. If everything goes well, your DockStar will reboot with the new kernel and root filesystem. Now you can restore the configuration you backed up in the first step.

    If you get the dreaded blinking orange LED, I'm afraid you will have to use a serial cable to recover.

Miscellaneous tips and tricks

Here are some things I've found helpful when using my DockStar with OpenWrt.

Configuring the LEDs

You can use the Luci web interface (under System > LED Configuration) to set up the LEDs, or edit /etc/config/system. For example, I have my green LED configured to blink on network activity using the following settings:

config led
	option sysfs 'dockstar:green:health'
	option trigger netdev
	option dev eth0
	option mode 'link tx rx'
Using the top USB connector

If you're not using the top connector for a Seagate FreeAgent Go™ drive, I recommend a female 5-pin mini-USB to female USB adapter (available here or here). They fit well and make the top connector more useful for conventional USB devices. It would be nicer if they came in white, but you can't beat the price.

Building your own OpenWrt kernel and root filesystem images

The instructions in this section are not needed if you use the pre-built images described above.

If you've never built the OpenWrt firmware before, please refer to this HOWTO.

You need to build your own OpenWrt kernel and root filesystem image, because OpenWrt's Marvell Kirkwood target currently supports only the Sheevaplug, which has a different NAND flash layout.

  1. Use make menuconfig to configure the build system for a kirkwood target. Add squashfs in the target images section. Also select built-in luci and ntpclient packages.

    Use make kernel_menuconfig to add built-in SCSI disk, USB EHCI, USB storage, and ext2 filesystem support. (This step isn't required, but I recommend it. It will allow you to boot from a USB flash drive if the root filesystem on internal flash is corrupted.)

    Do an initial build.

  2. Change to build_dir/linux-kirkwood/linux- and apply the following patches, based on work done by Alexander Holler <>.

    Support the DockStar flash layout and the OpenWrt naming scheme:

    --- a/arch/arm/mach-kirkwood/sheevaplug-setup.c
    +++ b/arch/arm/mach-kirkwood/sheevaplug-setup.c
    @@ -33,7 +33,11 @@ static struct mtd_partition sheevaplug_nand_parts[] = {
     		.offset = MTDPART_OFS_NXTBLK,
     		.size = SZ_4M
     	}, {
    -		.name = "root",
    +		.name = "rootfs",
    +		.offset = MTDPART_OFS_NXTBLK,
    +		.size = SZ_32M
    +	}, {
    +		.name = "rootfs_data",
     		.offset = MTDPART_OFS_NXTBLK,
     		.size = MTDPART_SIZ_FULL

    Support the DockStar LEDs:

    diff --git a/arch/arm/mach-kirkwood/sheevaplug-setup.c b/arch/arm/mach-kirkwood/sheevaplug-setup.c
    index 555f7c3..648c741 100644
    --- a/arch/arm/mach-kirkwood/sheevaplug-setup.c
    +++ b/arch/arm/mach-kirkwood/sheevaplug-setup.c
    @@ -62,9 +62,15 @@ static struct mvsdio_platform_data sheeva_esata_mvsdio_data = {
     static struct gpio_led sheevaplug_led_pins[] = {
    -		.name			= "plug:green:health",
    +		.name			= "dockstar:green:health",
     		.default_trigger	= "default-on",
    -		.gpio			= 49,
    +		.gpio			= 46, /* green */
    +		.active_low		= 1,
    +	},
    +	{
    +		.name			= "dockstar:orange:misc",
    +		.default_trigger	= "none",
    +		.gpio			= 47, /* orange */
     		.active_low		= 1,
    @@ -84,7 +90,8 @@ static struct platform_device sheevaplug_leds = {
     static unsigned int sheevaplug_mpp_config[] __initdata = {
     	MPP29_GPIO,	/* USB Power Enable */
    -	MPP49_GPIO,	/* LED */
    +	MPP46_GPIO,	/* LED green */
    +	MPP47_GPIO,	/* LED orange */

    Rebuild the kernel with make at the top level. The kernel image will be in bin/kirkwood/openwrt-kirkwood-uImage.

  3. Pad the kernel image to a multiple of 128K bytes:

    # dd if=openwrt-kirkwood-uImage of=dockstar-uImage bs=128k conv=sync
  4. Prepare the rootfs image. Do not use the squashfs file in bin/kirkwood. (It is a combined image with both the kernel and the root filesystem.) Instead, cd to build_dir/linux-kirkwood and run the command

    dd if=root.squashfs of=dockstar-rootfs bs=128k conv=sync

    to pad the (rootfs-only) squashfs file to a 128K multiple.

  5. Now you can install the images as described above.

Installation using a serial cable

As mentioned above, this approach should normally not be necessary. But if your DockStar fails to boot with the previous method, this approach may work. See also the "Troubleshooting" section below.

  1. Prepare the kernel and rootfs images as described above. Copy them to a TFTP server on your network.

  2. Open the case and install a serial cable. See Alexander Holler's page for the serial pinout (and how to open the case) and this page for a picture of where to find the connector.

  3. Connect your DockStar to your network and use a terminal program like minicom to connect to it (speed 115200, no flow control). Power-on the DockStar. You should see the u-boot output as it boots. Type any character to interrupt the boot sequence:

    U-Boot 1.1.4 (Jul 16 2009 - 21:02:16) Cloud Engines (3.4.16)
    U-Boot code: 00600000 -> 0067FFF0  BSS: -> 00690D60
    Soc: 88F6281 A0 (DDR2)
    CPU running @ 1200Mhz L2 running @ 400Mhz
    SysClock = 400Mhz , TClock = 200Mhz
    DRAM CAS Latency = 5 tRP = 5 tRAS = 18 tRCD=6
    DRAM CS[0] base 0x00000000   size 128MB
    DRAM Total size 128MB  16bit width
    Flash:  0 kB
    Addresses 8M - 0M are saved for the U-Boot usage.
    Mem malloc Initialization (8M - 7M): Done
    NAND:256 MB
    CPU : Marvell Feroceon (Rev 1)
    Streaming disabled
    Write allocate disabled
    USB 0: host mode
    PEX 0: interface detected no Link.
    Net:   egiga0 [PRIME], egiga1
    Hit any key to stop autoboot:  0
  4. Use the setenv command in u-boot to set the ipaddr and netmask variables for the DockStar's IP address, and the serverip variable to the IP address of your TFTP server. Check that you have connectivity by doing

    CE>> ping $(serverip)
  5. Now you're ready to flash the kernel and rootfs images onto your DockStar. WARNING: perform the following steps in exactly this order, and double-check everything you type before hitting return. If you overwrite the u-boot partition by mistake, you will brick your DockStar and you will have to use a JTAG cable to recover.

    CE>> mw 0x800000 0 0x100000
    CE>> tftpboot 0x800000 dockstar-uImage
    # take note of the "bytes transferred" in hex and make sure that it's less than 0x100000
    # if not, redo the "mw" command above with a larger size, and use that size in the commands below
    # CAREFULLY erase the uImage partition and flash it with the new kernel
    CE>> nand erase 0x100000 0x400000
    CE>> nand write.e 0x800000 0x100000 0x100000  # or larger size if needed
    CE>> mw 0x800000 0 0x200000
    CE>> tftpboot 0x800000 dockstar-rootfs
    # as above, make sure 0x200000 is larger than the rootfs image size, or adjust accordingly
    # CAREFULLY erase the rootfs partition and flash it with new squashfs image
    CE>> nand erase 0x500000 0x2000000
    CE>> nand write.e 0x800000 0x500000 0x200000  # or larger size if needed
    # CAREFULLY erase the rootfs_data partition so openwrt will create a jffs2 overlay filesystem
    CE>> nand erase 0x2500000 0xdb00000
  6. Set some magic u-boot parameters and save them:

    CE>> setenv arcNumber 2097
    CE>> setenv mainlineLinux yes
    CE>> saveenv
  7. Type reset, or just power-cycle the DockStar. It should boot into OpenWrt.


While getting this to work, I occasionally observed incorrect writes to the rootfs partition. If your kernel boots but fails to find the root filesystem due to errors in the squashfs root partition, that might be the problem. (But that symptom can also be caused by flashing a squashfs image that is not 128K-aligned, so check that also.) The following steps may allow you to recover.

  1. If you didn't do the "recommended" part of configuring your kernel (enabling support for USB storage and ext2), do it now, then rebuild the kernel and re-flash it.

  2. Format a USB drive with one partition containing an ext2 filesystem. As root, un-tar the contents of bin/kirkwood/openwrt-kirkwood-rootfs.tar.gz onto the USB drive, and also copy the dockstar-rootfs image onto the drive (as a regular file).

  3. In u-boot, do

    CE>> setenv bootargs_root root=/dev/sda1 rootdelay=10 rootfstype=ext2
    CE>> boot

    Your DockStar should boot with the USB drive as its root filesystem.

  4. Configure OpenWrt so that it can network to the outside world. Then do:

    # opkg update
    # opkg install mtd-utils

    (Alternatively, you can copy the mtd-utils package, or its commands, onto the USB drive before booting the DockStar.)

  5. Use the mtd-utils commands to flash the /dev/mtd2 partition:

    # flash_eraseall /dev/mtd2
    # nandwrite /dev/mtd2 /dockstar-rootfs
  6. Type reboot and hope that your rootfs partition is now correct.

Restoring the factory firmware

It should be possible to restore the factory firmware by following the instructions in this thread.