Upgrading OpenWrt firmware using CLI

:!: For experienced users only!

This HOWTO will upgrade an existing OpenWrt firmware to a new version from the SSH command line.
A lot of information in this wiki page duplicates content of generic OpenWrt OS upgrade procedure.
Non-experienced users are strongly advised to Upgrading OpenWrt firmware using LuCI instead.
If you need some configuration options changed for the first boot, for example you need Wi-Fi enabled after flashing, follow this guide: Flashing OpenWrt with Wi-Fi enabled on first boot

Follow: Backup and restore

If you do not want to preserve existing configuration or files, feel free to skip this section.

Download and use only OpenWrt firmware images ending in “-sysupgrade.bin” for command line upgrades.
For x86 systems there is no “sysupgrade” image, just be sure the new firmware image has the same family of filesystem as your old one.

:!: Note: upgrade files must be placed in /tmp, as the sysupgrade procedure unmounts flash storage during the upgrade process. If the upgrade file is not in /tmp, sysupgrade will NOT perform any upgrade and only reboot the system.

Download the desired upgrade file to your OpenWrt's /tmp directory and verify firmware checksum. /tmp directory is stored in the device RAM:

  1. Check free memory is available: Run free. Proceed, if “free Mem” is the size of your firmware file + some extra mem (at least twice the size of your firmware file is perfect).
  2. Set the following variables to the download address of your OpenWrt firmware file (you must customize the URL!). You'll find a link to the file “sha256sums” in the Supplementary Files section of the download page for the architecture of your router, beneath the Image Files section:
  4. Download and check the firmware checksum with:
    cd /tmp;wget $DOWNLOAD_LINK;wget $SHA256SUMS;sha256sum -c sha256sums 2>/dev/null|grep OK
  5. In the screen output, look for the correct checksum verification:
  6. Do not continue, if the checksum verification mismatches!


  • If you cant use 'wget' (e.g. because you want to transfer firmware from your PC to your OpenWrt device)
    • you can use scp: scp openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin root@ (Ensure you have set a non-null password for your device root account to properly use scp.)
    • you can use ssh: ssh root@ “cat > /tmp/openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin” < openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin (Also ensure you have set a non-null password for your device root account.)
    • you can also use nc/netcat:
      1. On your Linux PC run: cat [specified firmware].bin | pv -b | nc -l -p 3333
      2. On your OpenWrt device run (Assuming is the IP of your Linux PC): nc 3333 > /tmp/[specified firmware].bin
  • If the checksum mismatches: Redo the firmware download, if the mismatch remains, ask for help in the "Installing and Using OpenWrt" Forum
  • If low on RAM see: CLI - Low Memory Workarounds

OpenWrt provides sysupgrade utility for firmware upgrade procedure.

Verify firmware image checksum. Verify the router has enough free RAM. Upload the firmware from local PC. Flash the firmware.

# Check the free RAM 
# Upload firmware
scp firmware_image.bin root@openwrt.lan:/tmp
# Flash firmware
sysupgrade -v /tmp/firmware_image.bin

If sysupgrade is not available.

# Flash firmware
mtd -r write /tmp/firmware_image.bin firmware
  • The sysupgrade verbose-option should give some output similar to this. The list of configuration files saved will change depending on what packages you have installed and which files you have configured to be saved, as per above.
Saving config files...
killall: watchdog: no process killed
Sending TERM to remaining processes ... ubusd askfirst logd logread netifd odhcpd snmpd uhttpd ntpd dnsmasq
Sending KILL to remaining processes ... askfirst
Switching to ramdisk...
Performing system upgrade...
Unlocking firmware ...

Writing from <stdin> to firmware ...  [w]
Appending jffs2 data from /tmp/sysupgrade.tgz to firmware...TRX header not found
Error fixing up TRX header
Upgrade completed
Rebooting system...

Note: The “TRX header not found” and “Error fixing up TRX header” errors are not a problem as per OpenWrt developer jow's post at https://dev.openwrt.org/ticket/8623

  • Wait until the router comes back online
  • After the automatic reboot, the system should come up the same configuration settings as before: the same network IP addresses, same SSH password, etc.
  • Proceed to the “Additional configuration after an OpenWrt upgrade” section, below


In case it does not help, try a cold reset (= interrupt the electrical current to the device, wait a couple of seconds and then connect it again). Be careful about /etc/opkg.conf as explained here. 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.

  1. The firmware file is now in /tmp, so you can start the flashing process
  2. Preferably have an assistant physically present at the location of the device, if you upgrade it from remote (as some devices may require a hard reset after the update)
  3. Execute the following command to upgrade:
    sysupgrade -v /tmp/*.bin
  4. You can add the `-n` option if you DO NOT want to preserve any old configuration files and configure upgraded device from clean state (network/system settings will be lost as well)
  5. While the new firmware gets flashed, an output similar to the following will be shown:
    Saving config files...
    killall: watchdog: no process killed
    Sending TERM to remaining processes ... ubusd askfirst logd logread netifd odhcpd snmpd uhttpd ntpd dnsmasq
    Sending KILL to remaining processes ... askfirst
    Switching to ramdisk...
    Performing system upgrade...
    Unlocking firmware ...
    Writing from <stdin> to firmware ...  [w]
    Appending jffs2 data from /tmp/sysupgrade.tgz to firmware...TRX header not found
    Error fixing up TRX header
    Upgrade completed
    Rebooting system...
  6. Ignore the “TRX header not found” and “Error fixing up TRX header” errors. These errors are not relevant according to https://dev.openwrt.org/ticket/8623
  7. Wait until the router comes back online. The system should come up the same configuration settings as before (same network IP addresses, same SSH password, etc.)


  • does not reboot automatically or remains unresponsive: Wait 5 minutes, then do a hard reset: Turn it off, wait 2-3 seconds and turn it back on (or pull the power plug and plug it back in).
    :!: Doing this while the device is still updating might softbrick it and require serial or even jtag connection to recover it. Such a cold restart has been reported to be required often after a sysupgrade by command line.
  • OPKG issues: if after flashing you have issues with package installation or because opkg.conf has outdated data, read https://dev.openwrt.org/ticket/13309
  • 'sysupgrade' not available on your OpenWrt device, you can use 'mtd' instead to flash the firmware: mtd -r write /tmp/openwrt-ar71xx-generic-wzr-hp-ag300h-squashfs-sysupgrade.bin firmware

Post-upgrade steps

  • Verify the new OS version: The simpler way to see if the firmware was actually upgraded. In SSH, the login banner states the release information like version and so on.
  • if you used extroot, then see this howto about restoring it
  • Check for any upgradable packages Opkg Package Manager. After the firmware update, it is good to check for any updated packages released after the base OS firmware image was built.
  • Reinstall user-installed packages. After a successful upgrade, you will need to reinstall all previously installed packages according to your notes. Package configuration files should have been preserved due to steps above, but not the actual packages themselves. If you used the scripts provided in the forum, this step might not be necessary.

Blindly upgrading packages (manually or via script) can lead you into all sorts of trouble.

Just because there is an updated version of a given package does not mean it should be installed or that it will function properly. Inform yourself before doing any upgrades to determine if it is safe to upgrade. Avoid upgrading core packages.

There are two ways to manage/install packages in OpenWrt: with the LuCI web interface Software menu (System > Software), and via the command line interface (CLI). Both methods invoke the same CLI opkg executable, and as of OpenWrt 19.07.0, the LuCI interface now has an 'Updates' tab with a listing of packages that have available upgrades. The LuCI Upgrade… button performs the same opkg upgrade command that is discussed in this article. The same warnings apply to upgrading packages using LuCI and the CLI.

Generally speaking, the use of opkg upgrade is very highly discouraged. It should be avoided in almost all circumstances. In particular, bulk upgrading is very likely to result in major problems, but even upgrading individual packages may cause issues. It is also important to stress that this is distinctly different from the sysupgrade path for upgrading OpenWrt releases (major versions as well as maintenance upgrades). opkg upgrade will not update the OpenWrt version. Only sysupgrade can do that. The two are not equivalent.

Unlike the 'big distros' of Linux, OpenWrt is optimized to run on systems with limited resources. This includes the opkg package manager, which does not have built-in ABI (Application Binary Interface) compatibility and kernel version dependencies verification. Although sometimes there may be no issues, there is no guarantee and the upgrade can result in various types of incompatibilities that can range from minor to severe, and it may be very difficult to troubleshoot. In addition, the opkg upgrade process will consume flash storage space. Since it does not (and cannot) overwrite the original (stored in ROM), it must store the upgraded packages in the r/w overlay.

In the vast majority of cases, any security patches of significant importance/risk will be rapidly released in an official stable maintenance release to be upgraded using the sysupgrade system. This is the recommended method for keeping up-to-date.

Those looking to be on the bleeding edge can consider using the snapshot releases, but should be mindful of the differences between stable and snapshot. Or, alternatively, build a custom image with the desired updated packages included in that image. The remaining users who still want to use opkg upgrade should only do so with selected individual packages (do not bulk update, and do not blindly update) and they should be aware that problems may occur that could necessitate a complete reset-to-defaults to resolve.

If you're already having issues, or wish to 'undo' the upgraded packages: create a backup (optional; can be restored after the reset is complete) and then perform a reset to defaults (firstboot).

If you do choose to upgrade packages, especially with a script, you have been warned. Don't complain on the forum, and be ready to deal with the consequences, troubleshooting, and resolution yourself.

The new package installations will have installed new, default versions of package configuration files. As your existing configuration files were already in place, opkg would have displayed a warning about this and saved the new configuration file versions under *-opkg filenames.

The new package-provided configuration files should be compared with your older customized files to merge in any new options or changes of syntax in these files. The diff tool is helpful for this.

Manual Config Diff

# install diffutils
opkg install diffutils
# locate all -opkg files
find /etc -name *-opkg
# compare current customized /etc/config/snmpd VS new /etc/config/snmpd-opkg
diff /etc/config/snmpd /etc/config/snmpd-opkg
# manually add / merge new changes into the active config file
vi /etc/config/snmpd
# OR you may use the new version provided by the maintainer and overwrite the old config file
mv /etc/config/snmpd-opkg /etc/config/snmpd
# remove maintainer version of the configuration file
rm /etc/config/snmpd-opkg
# Some user-installed packages need to be enabled and started, for example to start snmpd:
/etc/init.d/snmpd enable && /etc/init.d/snmpd start
# optional: Manual reboot is a good idea to ensure all expected functionality is working as before.

Opkg Extras (uci) Diff

:!: Set up Opkg extras and UCI extras to be able to use the following features.

# Install packages
opkg update
opkg install diffutils
# Find new configurations
opkg newconf
# Compare UCI configurations
uci diff snmpd
# Merge needed changes to the current version
vi /etc/config/snmpd
rm /etc/config/snmpd-opkg
# Or replace the current version with the new one
mv /etc/config/snmpd-opkg /etc/config/snmpd
# Apply new configuration
/etc/init.d/snmpd restart

If your device's /tmp filesystem is not large enough to store the OpenWrt upgrade image, this section provides tips to temporarily 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.

# 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:

# free
Mem:         13388        12636          752            0         1292
Swap:            0            0            0
Total:       13388        12636          752
# 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 package lists:
rm -r /tmp/opkg-lists/
  • drop caches:
sync && 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.

Still No Room in /tmp?

Only recommended for devices with really very little RAM, you could try the more risky flashing-by-streaming-to-mtd variant (risky, because the firmware gets streamed from the client to the device during flashing. Any network issues during the process are likely to brick your device). Use this only, if you really cannot free enough RAM with other means. Netcat must be installed on the OpenWrt device for this. If you need help for netcat, refer to external links: 1, 2, 3, 4, 5

Flash from ssh client PC

# Upload and flash firmware
cat firmware_image.bin | ssh root@openwrt.lan mtd write - firmware

Flash using netcat

On your Linux PC run:

nc -q0 1234 < openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin

On the OpenWrt device, run:

nc -l -p 1234 | mtd write - firmware
This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
  • Last modified: 2021/09/18 09:56
  • by someothertime