General NAS customisation guide

= ABOUT =

Mindbender aka Markus Toth
The time when i started hacking on my first NAS (the first generation Linkstation) in 2005 there was no general article or guide how to hack it at all. The only thing that was existing at these days were reviews. Actually many NAS-hacking-communities have emerged the past years with wikis/forums/mailings lists….but still nobody ever wrote a general article about how to start hacking them, and what should be done to channel development efforts and how to start a new community. This article should cover exactly this, treat it as a source of base information and as a loose guide as all devices are different and many things have to be redone each time for each new box. As NAS are embedded devices you can use this guide for hacking your embedded router as well. I hope others are joining me in the challenge of enhancing this guide

About NAS
NAS is an acronym for "Network Attached Storage". Checkout this Wikipedia-article to find out what this is at all and what it is for: http://en.wikipedia.org/wiki/Network_attached_storage

About non-x86 NAS Devices
About 99 % of end-user-NAS are not based on the x86-arch which you know from your normal PC. The mainboards and chipsets used by NAS-manufacturers cover various different archs: PowerPC, MIPS, ARM, Broadcom ….

Therefore you cannot install any different OS like Windows that was only designed and compiled for the x86 and where no source is available. That’s where Unix / Linux is the key. About 99 % of all current NAS-devices are using a Unix or Linux OS inside. Linux again is used in 90 %, only a few use some variant of BSD as the underlying OS.

Why to customize at all?
Well, the reason is simple. If you are not satisfied with the features of an embedded box and you want to enhance it you have to hack it. Normally there are new firmwares released by the manufacturer which fix bugs and add some features, but these are rather small changes most of the time.

My suggestion: Never wait for a manufacturer to implement feature X in the firmware for Box Y for you … even if you tell him that you would like to see that.

If you ask now why I am of that opinion then i can tell you that most of the time the manufacturer itself has problems to integrate applications. If a NAS gets designed it is common that the actually selling company goes to other (more low-level) manufacturers who build and sell development boards for some specific purpose, then the board is chosen, modifications are done and then it is manufactured by this hidden manufacturer. So the hidden manufacturer more or less is the supplier of the mainboards, the heart of the NAS. So…do not get confused when you research in the internet which NAS might fit best to you and you find out later that the board was based on the same board as several others.

NOTE: Currently the Marvell Boards based on the Orion design are used in nearly all boxes.

The hidden manufacturers modify some kernel-sources to get support for the specific boards in the Linux Kernel. Most of the time it is only done once and in a very dirty way. That’s why it is impossible for them to submit this patches to http://kernel.org ….they would never accept such hacks there.

Also they provide the Linux OS for the box most of the time compiled for exactly this kernel together with a cross toolchain for that system. So they more or less already defined the only C-library-version that the OS could be based on. The cross toolchain is only able to build binaries for exactly this uclibc/glibc.

What do we learn from this? The selling companies cannot upgrade the kernel inside the boxes or they can do it only with major efforts…it is very unlikely that this will be done as it costs money. Because of the dirty hacks in the kernel sources some features are just impossible. After the hidden manufacturer has ported everything and the selling company has started to sell the box there won`t be many new innovative new features.

= WHERE TO START? =

So you have just bought a new NAS box and you want to hack it. I list some things to do here chronologically here.

You do not want to reinvent the wheel. The best point currently to find out if there is a community is at http://nas-central.org/ALL_COMMUNITIES/Collection_of_NAS-Hacking_communities.html If you find one there you are lucky. Never forget that there maybe is one not mentioned there so it is time to use your favourite search engine. If you do not find one: Look at the nas-central.org mainpage. Most likely there already is a wiki...so why not use it? If there is no wiki existing for your vendor let us know. We will set it up for you. Actually there are some pages available which allow you to create some sort of subwiki/subforum and you can start a mailing list at http://groups.yahoo.com for example….do not forget to link all of them together….then you do not have to waste money for webhosting and think about if it makes sense at all because of lack of interest maybe. You do not need to register a new domain which also costs money at this point. Others will search like you for a community as well. And they need to find everything as good as possible. The moment there is a central place, information can be stored there. Put all the info you know in the wiki. and put all of them in the Wiki. Now it depends on the common interest and the amount of sold boxes until you will see some other guys joining you. Many vendors make it problematic to obtain the GPL sources,they want you to pay fees or want you to send them cds with money...thats why you circumvent that and make it available for everyone. I have invested quite some time to gather all the GPL source packages at gpl.nas-central.org. Check out if you maybe can download a GPL package for your box before there.....and donate the money that you would have wasted.
 * Search the net if a community already is existing
 * Check if maybe NAS-Central.org itself provides a wiki for the vendor of your box
 * Link everything together
 * Start gathering box specific information
 * Try to get hands on the GPL sources of the box and make them available for downloading.

= OBTAINING BOX SPECIFIC INFORMATION =

Open the box

 * 1) Get your camera ready, take pics of everything
 * 2) Disassemble the box
 * 3) Take high res pics of both sides of the mainboard
 * 4) Take pics of the used components, write down the part number if you cannot take a proper pic.
 * 5) Make all pics available by uploading them to the wiki

Identify the parts used

 * 1) Identify the manufacturer
 * 2) Identify the part itself
 * 3) Try to get datasheets for the parts
 * 4) Make the info available and the datasheets as well

No opening of device needed

 * 1) Very often the webserver for webinterface is not setup securely. It might be possible to see the directory structure via custom urls. It might be enough to find an existing telnetd binary on the box
 * 2) Webinterface cgi exploits are sometimes existing because data is only validated on the client side. Jim Buzbee usually tries this in his NAS reviews at smallnetbuilder.com. If the webserver runs as root (occurs very often) it might be possible to even execute commands on the box. If a telnetd binary is on the box this is very handy.
 * 3) Reverse engineering of updating mechanism which is independent from the webinterface. If the firmwareupdate binary is not uploaded via the webinterface but instead via a additional windows/linux tool then wireshark might discover some interesting network packets and a custom designed protocol while updating the firmware. (example: ACP protocoll on all arm9 based linkstations/terastations).

Flash based NAS devices (Most BYOD devices)
Modifying configuration files which are stored on the hdd. Flash-based NAS devices do not have any Linux OS on a hdd, its completely stored in a flash chip on the mainboard. If the hdd is completely used for the share data or if there is no telnetd/sshd/netcat server binary included it gets harder to get shell access, serial might be the last option then. Some flash based NAS devices store several config files like smb.conf on the hdd. If you own one which stores smb.conf on the hdd and you know where telnetd is stored then try to start it by creating a script that does everything that is needed to start telnetd and which starts the telnet-daemon at the end: echo "pts/0" >>/etc/securetty /usr/sbin/telnetd To automatically execute this script, which we name init_telnet.sh here, everytime the box is booting add this line to the smb.conf: root preexec = /conf/init_telnet.sh Replace /conf/ with the directory name where then config is stored.
 * 1) !/bin/ash

Opening of the device needed

 * 1) Searching for telnetd/sshd/netcat server on the NAS hdd by connecting it to a linux workstation and make it startup automatically. Disassemble the box, connect the HDD to a linux pc (Knoppix or Ubuntu Live might be handy for Windows/OSX users), and check the partition structure for the main linux partition. Hopefully this partition is mountable ,older boxes used ext3 as the filesystem but lately XFS was used on several never devices. Then its time to search for a telnetd/sshd/netcat binary that was left by the firmware developer. If there is one you need to find a way to start it automatically after bootup of the NAS. It depends on the startup mechanism of the custom linux distribution that the firmware is based on how this can be achieved. This varies from full blown startup mechanism with several different runlevels to having everything started up from within the /etc/init.d/rcS file. Then modify it so a telnetd/sshd/netcat server is started automatically. Put the HDD back into the box and try to boot. If everything works out you will be able to connect via telnet to the box.
 * 2) If there is no telnetd,sshd or netcat binary there are 2 ways to proceed, locating and soldering serial or cross-compiling telnetd, installing it on the NAS hdd and make it start up automatically.

Getting serial access - Soldering probably mandatory


First thing is to identify the serial ports. On embedded boards the serial headers are not soldered most of the time as it takes time to do this (which costs the vendor money) and because the vendor does not want you to play around with the box.

On the right side you see some examples for serial ports in embedded devices.

Next step is to solder solder pins into the holes or a different header if there are pads or anything.

The dangerous part most of the time is to identify the right pinout on the board and to build/find the right cable to connect this serial port to your workstation.

If you identified a serial port with 4 pins then you need to identify the pinout for:


 * 1) Transmit (TX)
 * 2) Receive (RX)
 * 3) Power (3.3V)*
 * 4) Ground (GND)


 * ... in 99.9 % of the cases you do not need to connect Power. And connecting Power is the usually the only thing that can destroy the serial port if connected to the wrong pin. Make sure you know TX, RX, Power and GND of the cable you are using and don`t use the Power cable. To go safe not to destroy your box only use TX/RX/GND.

Examples for building/obtaining a compatible serial cable for these 3.3V serial ports:
 * buffalo:Building_a_Custom_Serial_Interface
 * http://www.nslu2-linux.org/wiki/HowTo/AddASerialPort
 * buffalo:Serial_port
 * buffalo:Use_a_cheap_phone_sync_cable_with_the_serial_port

With serial access its possible to:
 * see the bootloader log and subsequently to identify which bootloader is used and maybe even control it
 * see the kernel log and subsequently to see which vanilla kernel this kernel is based on.
 * get access to a root shell of the NAS box most of the time.
 * if shell access is available it is possible to extract the flash contents which might be usefull later when box gets bricked jtag is needed.

Commands for obtaining useful information about the device
cat /proc/cpuinfo   -> info about CPU cat /proc/meminfo   -> info about memory cat /proc/mtd       -> info about flash "partitions" /lib/libc.so.6      -> info about C library uname -a            -> info about kernel version lsmod               -> info about loaded kernel modules mount               -> info about mounted partitions dmesg               -> print out the kernel messages since bootup

Gather this information and put it on the wiki page of the NAS box.

Creating a backup of the flash
With the newer kernels usually the flash is accessable via the mtd driver. The mtd driver provides 2 different types of devices for accessing the flash. Read more about that in the official documentation. First thing to do is to check the info about the flash "partitions" cat /proc/mtd then you know which partitions are available. Usually there is one containing the bootloader and optionaly there are others which a kernel/initrd/configuration files. before messing up anything it is a good idea to backup the flash contents of every flash partition. you can use cat or dd for that purpose. Notice that X represents the number of the device. cat /dev/mtdX > mtdX.backup or dd if=/dev/mtdX of=mtdX.backup bs=1k

With older 2.4 kernels (older than 2.4.20) the mtd driver might not be used. in that case there most likely are devices called /dev/flX which allow read-write access to the flash via the same device. In case there are no mtd or fl devices it might happen that you need to create the device manually with mknod.

Investigating the updating mechanism created by vendor
The more that is known about the updating mechanism the better. The goal is to create enhanced telnet or ssh enabled firmwares so others do not need to open their box to get to the shell (in case there is no easily reproduceable exploit).

Creating compatible telnet enabled linux firmwares

 * 1) Unpack linux firmware
 * 2) Obtain a telnet binary from a debian repository or cross compile it
 * 3) Integrate telnet (install it in a proper location and make it startup automatically)
 * 4) Pack it again
 * 5) Test it
 * 6) If it is working make the new firmware image available for others

Embedded Linux Bootloader overview
TODO: add general info and then specific info about the bootloaders Here we have some very general info about Embedded Bootloaders: http://www.cs.tau.ac.il/telux/lin-club_files/linux-boot/slide0000.htm

Redboot

 * RedBoot Debug and Bootstrap Firmware
 * Redboot User Guide

UBoot (former ppcboot)

 * http://linuxdevices.com/articles/AT5085702347.html
 * http://www.denx.de/wiki/bin/view/DULG/Manual

IDTBoot

 * http://www.linux-mips.org/wiki/IDT_SIM

Apex

 * http://wiki.buici.com/wiki/Apex_Bootloader

Getting JTAG access - Soldering probably mandatory

 * JTAG FAQ

= INTERMEDIATE TOPICS - No C-coding knowledge needed =

Setting up the Codesourcery ARM9 Crosstoolchain
Setting_up_the_codesourcery_toolchain_for_X86_to_ARM9_cross_compiling

Creating a crosstoolchain

 * http://www.kegel.com/crosstool/
 * http://www.gentoo.org/proj/en/base/embedded/handbook
 * http://www.gentoo.org/proj/en/base/embedded/cross-development.xml (deprecated)
 * http://dev.gentoo.org/~vapier/eh/?part=1&chap=4
 * http://gcc.gnu.org/wiki/Building_Cross_Toolchains_with_gcc

Creating Optware Feeds
The first thing if you want to create an optware feed is to check if there isn`t maybe a already existing feed that would work on your box. Look at this page for investigating this: http://www.nslu2-linux.org/wiki/Optware/Platforms?from=Unslung.OptwarePlatforms

http://www.nslu2-linux.org/wiki/Optware/HomePage http://trac.nslu2-linux.org/optware/browser/trunk/platforms/adding-a-new-platform.txt

Replacing the OS
this article shows how bootstrapping of ubuntu works on a ppc linkstation/kurobox: buffalo:Ubuntu_installation_guide this article (which is work in progress) shows how to create/update gentoo for the kurobox(ppc): buffalo:User:RussK/Create_2007_kurobox_Gentoo should be helpful for writing this section.

To create a easy installable firmware you need to investigate how the updating mechanism of the rootfs works.

Ubuntu server
= ADVANCED TOPICS - C-coding knowledge mandatory =

Microcontroller software replacement
If your box has a Microcontroller which controls the buttons and the leds then the source is most likely missing for that app in the GPL-source code as it was coded by the vendor. As the goal is to get full opensource it is needed to recode this daemon.

example: buffalo:Avr_evtd

Daisy Chain
Idea from http://scratchpad.wikia.com/wiki/Open_Turbostation:Boot_Loader#Boot_Loader_Daisy_Chains

Porting latest vanilla (or arch specific) kernel
Basically it works that way:
 * 1) Create a diff between the GPL kernel source and the vanilla kernel source of the same version
 * 2) Reorder/recode all the non-standard things
 * 3) If you own Marvell Orion SoC-based device, follow this guide: Orion NAS customisation guide
 * 4) create a patch
 * 5) try to submit it at the relevevant page
 * http://kernel.org
 * http://linux-mips.org
 * http://www.arm.linux.org.uk