Introduction

The Firmware Mod Kit allows for easy deconstruction and reconstruction of firmware images for various embedded devices. While it primarily targets Linux based routers, it should be compatible with most firmware that makes use of common firmware formats and file systems such as TRX/uImage and SquashFS/CramFS.

Prerequisites

In order to get and build the Firmware Mod Kit, you must have a subversion client, standard Linux development tools (gcc, make, etc) and the zlib development package. If you are running a Debian based Linux distro such as Ubuntu, these utilities can be installed via apt-get:

For Ubuntu:

$ sudo apt-get install subversion build-essential zlib1g-dev

OR for RedHat/CentOS:

yum groupinstall "Development Tools"
yum install svn
yum install zlib1g-dev

For other distros, you should install the equivalent packages using your distro's package manager.

The Firmware Mod Kit is only supported on the Linux platform.

Tools / Utilities

The Firmware Mod Kit consists of a collection of tools useful when working with embedded firmware images:

While these tools can be used individually, there are several scripts that automate the extraction and reassembly of firmware:

Extracting Firmware

Automated firmware extraction typically works with most firmware images that employ uImage/TRX firmware headers and use SquashFS or CramFS file systems. Currently, extract-ng.sh is the preferred method of extraction as it supports more firmware types than the older extract_firmware.sh script. However, extract_firmware.sh is still included and works with many firmware formats.

Usage for both extract-ng.sh and extract_firmware.sh is straight forward:

  $ ./extract-ng.sh firmware.bin
  $ ./extract_firmware.sh firmware.bin working_directory/

By default, output from extract-ng.sh will be located in the 'fmk' directory, while extract_firmware.sh will place extracted data into the specified working directory.

Re-Building Firmware

Which build script to use is dependant on which extraction script was used. If you extracted a firmware image with extract-ng.sh, then you must use build-ng.sh to re-build it. Likewise, if extract_firmware.sh was used, then build_firmware.sh must be invoked when re-building an image:

  $ ./build-ng.sh [-nopad]
  $ ./build_firmware.sh ouput_directory/ working_directory/

The new firmware generated by build-ng.sh will be located at 'fmk/new-firmware.bin', while build_firmware.sh will generate firmware images in several different formats and save them in the specified output directory.

The optional -nopad switch will instruct build-ng.sh to NOT pad the firmware up to its original size.

Modifying DD-WRT Web Pages

One very unique feature of the Firmware Mod Kit is its ability to extract and rebuild files from the DD-WRT Web GUI. This is automated by the ddwrt-gui-extract.sh and ddwrt-gui-restore.sh scripts.

Once you have extracted a DD-WRT firmware image using extract-ng.sh, you can extract the Web files by running:

  $ ./ddwrt-gui-extract.sh

This will create a directory named 'www' and extract the Web files there. You may modify the files any way you like, but you cannot add or delete files.

When you are finished editing, you can rebuild the Web files by running:

  $ ./ddwrt-gui-restore.sh

Examples

This example demonstrates how to extract a firmware image, replace its existing telnet daemon with a custom built one, and then build a new firmware image:

  $ ./extract-ng.sh firmware.bin
  $ cp new-telnetd fmk/rootfs/usr/sbin/telnetd
  $ ./build-ng.sh

Below is an example of the commands to run in order to extract a DD-WRT firmware image, modify the Web index page, and build a new firmware image:

  $ ./extract-ng.sh firmware.bin
  $ ./ddwrt-gui-extract.sh
  $ echo "HELLO WORLD" > www/index.asp
  $ ./ddwrt-gui-restore.sh
  $ ./build-ng.sh