asuswrt-fwtool

The asuswrt-fwtool allows you to analyze and modify ASUSWRT firmware images. It provides functionality to extract, modify, and rebuild firmware images for ASUS WiFi routers. The tool is compatible with ASUS wireless router models that use FIT (Flattened Image Tree) firmware images.

Warning

This script modifies device firmware. Improper use can potentially result in device malfunction or "bricking," which may require advanced recovery methods. Before using asuswrt-fwtool, you must read and understand all the risks and implications involved.

By using asuswrt-fwtool, you acknowledge that you have read, understood, and agreed to all the terms outlined in the the IMPORTANT WARNING AND TERMS OF USE.

Background

The development of asuswrt-fwtool was sparked by the limitations of my recently purchased ASUS ZenWiFi Pro ET12 router. Despite its advanced features, the ET12's latest firmware lacks built-in VLAN support and doesn't allow setting up custom startup scripts, unlike routers with USB ports where this is possible. Furthermore, the Asuswrt-Merlin custom firmware, a popular solution for extending Asus router capabilities, is not available for this model, and according to its author, ET12 is not planned to be supported in the future.

Determined to overcome these restrictions, I started researching possible workarounds. Initially, I configured the router to my specifications by accessing its Linux shell via SSH. However, as expected with this approach, the changes were not persistent across reboots. As a workaround, I set up a lightweight container ansible-scheduled with a scheduled Ansible task that regularly checked my custom configuration and reapplied it if the device had been rebooted or the configuration had been reset due to other changes made via the web interface.

While functional, this workaround was far from ideal. It introduced unnecessary complexity and created an external dependency. Relying on an external service to maintain basic configuration proved inconvenient and unreliable. This motivated me to explore the possibility of injecting additional scripts directly into the firmware image, which would allow persistent custom configurations.

This investigation led to the development of asuswrt-fwtool, a tool designed to analyze and modify the stock firmware, extending the router's capabilities beyond what's available through the standard web interface.

While initially developed to address the specific limitations of the ET12 router, asuswrt-fwtool is designed to work with other Asus router models that use FIT (Flattened Image Tree) firmware images.

Features

• Inspect firmware image tree source data
• Extract rootfs from firmware images
• Apply custom overlays to existing firmware's rootfs partition
• Rebuild firmware with a customized rootfs

Requirements

This script relies on several tools, some of which may need to be installed separately.

Bash

Bash 4.0 or higher is required. You can check your Bash version by running:

bash --version

Notes for macOS users

Bash version

macOS comes with an outdated version of Bash (3.2.57) preinstalled, which is the last version released under GPLv2. To run asuswrt-fwtool, you'll need to install a more recent version of Bash. This can be done using Homebrew:

brew install bash

After installation:

1. Find the path of the new Bash version:

which bash

2. Update the shebang line in the script to use the new Bash path. For example:

#!/opt/homebrew/bin/bash

Alternatively, you can run the script explicitly with the new Bash version:

/opt/homebrew/bin/bash asuswrt-fwtool [options]

Case-sensitive filesystem

By default, macOS uses a case-insensitive filesystem, which can cause issues when extracting contents of case-sensitive filesystem images. To work around this, create and mount a disk image with a case-sensitive filesystem:

1. Use Disk Utility to create a new blank image.
2. Choose APFS (Case-sensitive) as the format.
3. Save and mount the created image.

When using the script, ensure you're working within this case-sensitive volume. It's crucial to specify the temporary directory on this new image using the -t option:

asuswrt-fwtool -t /Volumes/CaseSensitive/tmp [other options]

Replace /Volumes/CaseSensitive/tmp with the actual path to a directory on your case-sensitive volume.

Essential tools

The utilities listed below require installation unless you installed them before.

• dtc
• unsquashfs and mksquashfs
• dumpimage and mkimage

On Debian-based systems, install these with:

sudo apt install device-tree-compiler squashfs-tools u-boot-tools

On macOS, you can install the required tools using Homebrew:

brew install dtc squashfs u-boot-tools

For other distributions, use the appropriate package manager and package names.

Common Unix utilities

The following are typically pre-installed on most Unix-like systems:

• awk
• bash
• dd
• hexdump
• rsync

If any are missing, use your system's package manager to install them.

Latest versions

For the most recent releases or if packages are unavailable, you may need to compile from source:

• device-tree-compiler
• squashfs-tools
• u-boot-tools

Consult each project's documentation for build and installation guides.

Installation

Before proceeding, ensure you have installed all the dependencies listed in the Requirements section above. You can install asuswrt-fwtool by either cloning the repository or downloading the script directly.

To clone the repository, run the following command:

git clone https://github.com/ashway83/asuswrt-fwtool.git

Alternatively, download just the script:

curl -O https://raw.githubusercontent.com/ashway83/asuswrt-fwtool/main/asuswrt-fwtool

Don't forget to set the executable bit:

chmod +x asuswrt-fwtool

Note for macOS users: Update the shebang line to reflect the path to your Bash installation. For more details, please review the macOS-specific instructions in the Requirements section.

Usage

Usage: asuswrt-fwtool [OPTIONS]

Create customized ASUSWRT firmware by modifying the rootfs contents.

Operations:

  Apply overlay to firmware:
     asuswrt-fwtool -f <firmware_file> -o <overlay_dir> [-n <output_file>]

  Rebuild firmware image with custom rootfs:
     asuswrt-fwtool -f <firmware_file> -r <rootfs_dir> [-n <output_file>]

  Extract rootfs:
     asuswrt-fwtool -f <firmware_file> -e <extract_dir>

Options:

  -f <firmware_file>   Input firmware file to modify or extract from
  -o <overlay_dir>     Root of the directory tree to overlay onto the rootfs
  -n <output_file>     Output firmware file (default: input file with '_mod' suffix)
  -e <extract_dir>     Root directory to extract the firmware's rootfs into
  -r <rootfs_dir>      Root directory for the modified firmware's rootfs
  -t <temp_dir>        Temporary directory (default: system temp directory)
  -s                   View image tree source
  -q                   Quiet mode - suppress non-error output
  -h                   Display this help message and exit

Examples:
  asuswrt-fwtool -f firmware.pkgtb -o overlay -n modified_firmware.pkgtb
  asuswrt-fwtool -f firmware.pkgtb -r modified_rootfs -n modified_firmware.pkgtb
  asuswrt-fwtool -f firmware.pkgtb -e extracted_rootfs

Examples

1. Apply an overlay to a firmware image:

asuswrt-fwtool -f firmware.pkgtb -o overlay -n modified_firmware.pkgtb

2. Rebuild a firmware image with a custom rootfs:

asuswrt-fwtool -f firmware.pkgtb -r modified_rootfs -n modified_firmware.pkgtb

3. Extract the rootfs from a firmware image:

asuswrt-fwtool -f firmware.pkgtb -e extracted_rootfs

4. View the image tree source:

asuswrt-fwtool -f firmware.pkgtb -s

Resources

• Flattened Image Tree Specification
• Devicetree Specification
• Device Tree Compiler
• Squashfs-tools
• U-Boot GitHub Repository
• U-Boot Documentation

License

This project is licensed under the MIT License. See the LICENSE file for details.