Table of Contents

Upgrading OpenWrt firmware using CLI

Back up OpenWrt configuration

Follow Backup and restore, or skip this section if you do not want to preserve existing configuration.

Download and verify the OpenWrt firmware upgrade image

Most of the information you need to select the proper image is contained in the output of ubus call system board. Here's an abbreviated version, use these values for navigating the downloads site and selecting the proper image: 

$ ubus call system board
{
        "board_name": "tplink,archer-c7-v4",
        "rootfs_type": "squashfs",
        "release": {
                "firmware_url": "https://downloads.openwrt.org/",
                "target": "ath79/generic",
        }
}

Download and use only OpenWrt firmware images ending in “-sysupgrade.bin” for command line upgrades of most devices. (The “-factory.bin” images are for the first installation only, when you are moving from factory firmware to OpenWrt; all subsequent upgrades should use “sysupgrades”.)

For x86, armsr and loongarch systems there are no “sysupgrade” images, just generic “combined” images (combined in the sense that they contain both boot/kernel and rootfs partitions). These combined firmware images should have the same family of filesystem as your old one (see rootfs_type, above). The image name should also contain the proper boot type, efi or BIOS; check this with ls /sys/firmware/efi/ and if that directory exists, then use efi otherwise the non-EFI/BIOS boot image.

:!: 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:
  3. DOWNLOAD_LINK="http://URLOFFIRMWAREBIN"; SHA256SUMS="http://URLOFSHA256"
  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: 
    FILE_NAME: OK
  6. Do not continue, if the checksum verification mismatches!

Troubleshooting:

Command-line instructions

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 
free
 
# Upload firmware
scp firmware_image.bin root@openwrt.lan:/tmp
 
# Flash firmware
sysupgrade -v /tmp/firmware_image.bin

Troubleshooting:

If sysupgrade is not available.

# Flash firmware
mtd -r write /tmp/firmware_image.bin firmware
Saving config files...
etc/config/dhcp
etc/config/dropbear
etc/config/firewall
etc/config/luci
etc/config/network
etc/config/snmpd
etc/config/system
etc/config/ubootenv
etc/config/ucitrack
etc/config/uhttpd
etc/config/wireless
etc/dropbear/authorized_keys
etc/dropbear/dropbear_dss_host_key
etc/dropbear/dropbear_rsa_host_key
etc/firewall.user
etc/group
etc/hosts
etc/inittab
etc/passwd
etc/profile
etc/rc.local
etc/shadow
etc/shells
etc/sudoers
etc/sudoers.d/custom
etc/sysctl.conf
etc/sysupgrade.conf
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

** Troubleshooting **

Flash the new OpenWrt firmware

  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/firmware_image.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...
etc/config/dhcp
...
etc/config/wireless
etc/dropbear/authorized_keys
...
etc/sysupgrade.conf
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.)

Troubleshooting:

Post-upgrade steps

Comparing new package config options

See also: Opkg extras, UCI extras

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. 

# Install packages
opkg update
opkg install diffutils
 
# Find new configurations
find /etc -name "*-opkg"
 
# Compare UCI configurations
diff /etc/config/snmpd /etc/config/snmpd-opkg
 
# Manually merge changes to the current config and remove default config
vi /etc/config/snmpd
rm /etc/config/snmpd-opkg
 
# Or replace current config with the default one
mv /etc/config/snmpd-opkg /etc/config/snmpd
 
# Apply changes
/etc/init.d/snmpd restart
reboot

Low memory workarounds: /tmp is too small to hold the downloaded file

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. 

rm -r /tmp/opkg-lists/
sync && echo 3 > /proc/sys/vm/drop_caches
rm /etc/modules.d/*80211*
rm /etc/modules.d/*ath9k*
rm /etc/modules.d/b43*
reboot

The wireless drivers usually take up quite some amount of RAM and are not required if you are connected by wire. You can delete the relevant symlinks in etc/modules.d and reboot to free up the RAM.

Still no room in /tmp?

Use netcat only if you really cannot free enough RAM with other means. Any network issues during the process are likely to brick your device.

Flash using ssh

# Linux PC
cat firmware_image.bin | ssh root@openwrt.lan mtd write - firmware

Flash using netcat

# Linux PC
nc -q 0 192.168.1.1 1234 < openwrt-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin
 
# OpenWrt
nc -l -p 1234 | mtd write - firmware