User Tools

Site Tools


OpenWrt Sysupgrade

Before reading this, please have a look at Flash Layout.

A sysupgrade will replace the entire OpenWrt installation: the Linux kernel, the SquashFS partition and the JFFS2 partition. You cannot save installed OPKG packages: you will have to install them again after sysupgrade. That way everything will match, e.g. the flashed Linux Kernel and installed Kernel modules. You can manually save some of your configuration files, but be aware that on rare occasions you will need to modify an old configuration file to work with the updated program.

In the Terminal Upgrade steps below, there is an easy script to run that produces a list of all packages that were installed, or upgraded, in the time since your last sysupgrade. Keep this list for later.

It is important to download the firmware image file to the /tmp directory. The /tmp directory is stored in RAM (using tmpfs), not in the flash storage. It is unlikely that there is sufficient free space in flash memory but it is possible to arrange sufficient free space in RAM. You may need to Free up RAM beforehand.

Terminal Upgrade Process

  1. You should check how much main memory you have currently available:
    In case you do not have enough free main memory, consult Free up RAM.
  2. Populate your /etc/sysupgrade.conf with the configuration files you want to keep
  3. Make a list of packages you've installed since the last full install or sysupgrade, to reinstall after your first successful reboot
    find /overlay/ | sed s:/overlay::g | while read file; do opkg search $file; done | awk '{print $1}' | sort | uniq
    or as of Chaos Calmer (or earlier?):
    find /overlay/upper/ | sed s:/overlay/upper::g | while read file; do opkg search $file; done | awk '{print $1}' | sort | uniq
  4. Obtain suitable OpenWrt firmware image: for trunk
        cd /tmp
    AA stable
        cd /tmp
    1. :!: for x86 systems there is no "sysupgrade" image, just be sure to use the new firmware image has the same family of filesystem (if the current firmware uses squashfs then the new will use squashfs as well and if the current has ext the new will use ext filesystem. Note that an upgrade from ext2 [10.03.1] to ext4 [12.09] seems not working. Tested 10.03.1 squashfs to 12.09 squashfs, working ; 10.03.1 squashfs to 12.09 ext4 failed; 10.03.1 ext2 to 12.09 ext4 failed)
  5. check the integrity of the image file:
    md5sum -c md5sums 2> /dev/null | grep OK
  6. use the following command to upgrade:
    sysupgrade -v /tmp/openwrt-ar71xx-generic-wzr-hp-ag300h-squashfs-sysupgrade.bin
  • The verbose-option should give some output similar to this:
    root@openwrt:/tmp$ sysupgrade -v openwrt-ar71xx-generic-tl-wr1043nd-v1-squashfs-sysupgrade.bin
    Saving config files...
    Switching to ramdisk...
    Performing system upgrade...
    Unlocking firmware ...
    Writing from <stdin> to firmware ...
    Appending jffs2 data from /tmp/sysupgrade.tgz to firmware...TRX header not found
    Error fixing up TRX header
    Writing from <stdin> to firmware ...
    Upgrade completed
    Rebooting system...
  • After the automatic reboot, the system should come up with the setting in the saved configuration files: same network IP addresses, same SSH password, etc. In case that it does not, try a cold reset (= interrupt the electrical current to the device, wait a couple of seconds and then connect it again).
  • After the cold reboot, you should gain access and here you could check things out:
    uname -a
    iptables -V
For unknown reasons such a cold reset has often been reported to be necessary after a sysupgrade. This is very very bad in case you performed this remotely!
  • After a successful upgrade, you will need to reinstall all previously installed packages. You made a list of these in Step 3 above. Package configurations are preserved, but not the actual packages themselves.
    opkg update
    opkg install tc iptables-mod-ipopt wol usb-ohci usb-storage ...

LuCI Web Upgrade Process

  1. Download a suitable OpenWrt firmware image file to your PC
  2. Login to the WebInterface of the router (default:
  3. Select SystemBackup / Flash FirmwareConfiguration to edit /etc/sysupgrade.conf (Attitude Adjustment)
    • Select SystemSystemCustom Files to edit /etc/sysupgrade.conf (Previous versions)
  4. Select SystemBackup / Flash FirmwareActions (Attitude Adjustment)
    • Select SystemFlash Firmware (Previous versions)
  5. Upload the OpenWrt image file you downloaded to your PC at step 1 to your router via LuCI
  6. LuCI will calculate the MD5 checksum of the file, if it's correct, you are green to go
  7. Wait until the router comes back online
  8. You do need to reinstall opkg-packages

Alternatives to OpenWrt Sysupgrade


  1. If sysupgrade is not supported for your embedded device, you should use mtd instead:
    mtd -r write /tmp/openwrt-ar71xx-generic-wzr-hp-ag300h-squashfs-sysupgrade.bin firmware


Direct method

Netcat could be employed if you cannot free enough RAM. See netcat. Netcat needs to be installed first.

This method is NOT recommended!
  1. On your Linux PC run:
    nc -q0 1234 < openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin
  2. On the router run:
    nc -l -p 1234 | mtd write - firmware

Indirect method

This method is much SAFER if you have enough RAM.

This method is fine for self built firmwares.

You should check how much RAM you have currently available.(In case you do not have enough left, consult Free up RAM.)


Transferring image file to a temporary location
  1. On your Linux PC run:
    cat [specified firmware].bin | pv -b | nc -l -p 3333
  2. On the router run:
    nc 3333 > /tmp/[specified firmware].bin 

The port 3333 an IP address are just examples. The command 'pv -b' is optional for tracking progress but maybe you have to install pv to your system previously.

Write it to flash
  • sysupgrade:
    sysupgrade -v /tmp/[specified firmware].bin 
  • mtd:
    mtd -r write /tmp/[specified firmware].bin firmware

I have tested under Ubuntu 11.10.


Make sure your router have enough memory.

root@OpenWrt:/# free

Make sure you have set the password for your router.(you must set a password for your router to enable the SSH). If not, set by doing this:

linux$ telnet
root@OpenWrt:/# passwd
See First Login for more details.

Copy your firmware to your router

On your Linux PC run:

linux$ scp openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin root@
Input 'yes' to estabilish authenticity, then input the password of your router. Wait scp command finished. Now you can see your firmware in /tmp directory.

Write the firmware to your router

root@OpenWrt:/# sysupgrade -v /tmp/[specified firmware].bin 

Note is the ip address(may be called GateWay) of your router. Check by run:

linux$ route -n 
or you can check the the /etc/config/network file, '' is the loopback ipaddress, the other one is the ip address of your router.
root@OpenWrt:/# cat /etc/config/network | grep 'ipaddr' 

Free up RAM

First check memory usage with the free or top or cat /proc/meminfo commands; proceed if you have as much free RAM as the image is in size plus an some additional MiB of free memory.

root@openwrt:/$ free total used free shared buffers Mem: 29540 18124 11416 0 1248 -/+ buffers: 16876 12664 Swap: 0 0 0

In this example there are precisely 11416 KiB of RAM unused. All the rest 32768 - 11416 = 21352 KiB are used somehow and a portion of it can and will be made available by the kernel, if it be needed, the problem is, we do not know how much exactly that is. Make sure enough is available. Free space in /tmp also counts towards free memory. Therefore with:

root@openwrt:/$ free Mem: 13388 12636 752 0 1292 Swap: 0 0 0 Total: 13388 12636 752
root@openwrt:/$ df Filesystem 1K-blocks Used Available Use% Mounted on /dev/root 2304 2304 0 100% /rom tmpfs 6696 60 6636 1% /tmp tmpfs 512 0 512 0% /dev /dev/mtdblock3 576 288 288 50% /overlay mini_fo:/overlay 2304 2304 0 100% /

One has actually 752+6636 KiB of free memory available.

  • quickest and safest way to free up, some RAM is to delete the opkg packages file:
    rm -r /tmp/opkg-lists/
  • drop caches:
    echo 3 > /proc/sys/vm/drop_caches
  • prevent wireless drivers to be loaded at next boot and then reboot:
    rm /etc/modules.d/*80211*
    rm /etc/modules.d/*ath9k*
    rm /etc/modules.d/b43*

The wireless drivers, usually take up quite some amount of RAM and are not required (unless you are connected via wireless of course ;-)), so an easy way to free up some RAM is to delete the symlinks in etc/modules.d so these are not loaded into memory at the next reboot.


doc/howto/generic.sysupgrade.txt · Last modified: 2015/08/08 02:49 by msouth