LEDE firmware upgrade (LuCI or command line)

A firmware upgrade will replace the current LEDE system with a new version: a newer Linux kernel, a new root partition and a new overlay partition.
The default upgrade will automatically preserve basic LEDE configuration by saving and then restoring configuration files in default locations (/etc/config). This will preserve things like network settings, WiFi settings, the device hostname, and so on.
Installed packages and their own configuration will not be preserved, so it may be necessary to document your programs and save the settings that will need to be re-installed or restored after the upgrade.
There are scripts available from OpenWRT forum to deal with that automatically.

WARNING!!! WARNING!!! WARNING!!!
ANY PARTS OF THE SYSTEM THAT ARE NOT SAVED BEFORE THE UPGRADE WILL BE LOST!
PROCEED AT YOUR OWN RISK!

-

Pre-upgrade steps

Some helpful steps to identify what you must restore after the upgrade. If you didn't install anything, feel free to skip this.

A one-line awk script (provided by user valentijn):

root@lede:/# awk '/^Package:/{PKG= $2} /^Status: .*user installed/{print PKG}' /
usr/lib/opkg/status

This script will output a list of user (and default) installed packages, without the “Package:” prefix.

The LuCI and command line upgrades will preserve configuration files:

  • listed by opkg list-changed-conffiles
  • listed within the text files in /lib/upgrade/keep.d/ (for example, /lib/upgrade/keep.d/base-file-essential)
  • listed in /etc/sysupgrade.conf

Based on the list of user-installed packages identified above, you may know that you have other configuration or data files that need to be preserved and that are not included in the default set of files to save.
Your new files should be added to /etc/sysupgrade.conf. By default, this file just has comments in it.

LuCI method

Go to System > Backup/Flash Firmware > Configuration tab. This will display the current contents of /etc/sysupgrade.conf file and the edit window can be used to add additional lines to the file. Click “Submit” when done editing.

To view all the configuration files that will be saved on an upgrade, click the “Open list…” button.

Command-line method

Edit /etc/sysupgrade.conf with an editor. For example:

root@lede:/# vi /etc/sysupgrade.conf
## This file contains files and directories that should
## be preserved during an upgrade.

# /etc/example.conf
# /etc/openvpn/

Downloading the LEDE upgrade image

Only the firmware image ending with“-sysupgrade.bin” should be used for LEDE upgrades. The image ending with “-factory.bin” is ONLY for installing LEDE for the first time, over the device's stock firmare.
:!: For x86 systems there is no “sysupgrade” image, just be sure to use the new firmware image has the same family of filesystem.

LuCI method

Download the desired upgrade file to your PC using a web browser, download the sha256sums text file you find in the same page.

Command-line method

Download the desired upgrade file to the local RAM drive on your LEDE system.
The /tmp directory is stored in RAM (using tmpfs), not in the permanent flash storage.

Let's move in /tmp

root@lede:/# cd /tmp 

we now download the file

root@lede:/# wget DOWNLOAD_LINK

Let's now download the sha256sums file (in the same page you find the download link of your firmware image)

root@lede:/# wget SHA256SUMS_DOWNLOAD_LINK

Now we check that the image's checksum is correct, so we know it was downloaded correctly.
This command outputs a large amount of text we don't care about (it will check for all files listed in the sha256sums file), so we filter its output to show only the line where it shows an “OK”.

root@lede:/# sha256sum -c sha256sums 2> /dev/null | grep OK

If it will show a line where it confirms that the file was downloaded correctly.

FILE_NAME: OK

Here the above steps are squashed together in a copy-paste friendly one-liner, write your links in it of course:

DOWNLOAD_LINK="link of firmware" ; SHA256SUMS="link of sha256sums" ; cd /tmp ; wget $DOWNLOAD_LINK ; wget $SHA256SUMS ; sha256sum -c sha256sums 2> /dev/null | grep OK 

Troubleshooting: /tmp is too small to hold the downloaded file

If your device's /tmp filesystem is not large enough to store the 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.

root@lede:/# 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@lede:/$ free
Mem:         13388        12636          752            0         1292
Swap:            0            0            0
Total:       13388        12636          752
root@lede:/# 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% /

here we have 752+6636 KiB of free memory available.

The easiest and safest way to free up some RAM is to delete the packages lists

root@lede:/# rm -r /tmp/opkg-lists/

You can also try to drop caches:

root@lede:/# sync && echo 3 > /proc/sys/vm/drop_caches

As a last desperate measure you can prevent wireless drivers to be loaded at next boot and then reboot: The wireless drivers usually take up quite a bit of RAM and are not really required if you are upgrading, as they will be reinstalled anyway.
You shouldn't do this if you are connected to the system via wireless, of course ;-).

root@lede:/# rm /etc/modules.d/*80211*
root@lede:/# rm /etc/modules.d/*ath9k*
root@lede:/# rm /etc/modules.d/b43*
root@lede:/# reboot

Upgrading the LEDE firmware

LuCI method

  • Select System > Backup / Flash Firmware > Actions tab
  • Upload the firmware upgrade file in the Flash new firmware image section
  • LuCI will calculate the sha256 checksum of the file, check it with the sha256sum you find in the sha256sums file you also downloaded.
  • 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.

Command-line method

write the following command to upgrade:

root@lede:/# sysupgrade -v /tmp/*.bin

The 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...
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/LEDE developer jow's post at https://dev.openwrt.org/ticket/8623

Wait until the router comes back online.
The system should come up the same configuration settings as before: the same network IP addresses, same SSH password, etc.

Troubleshooting

In case it does not reboot, wait 5 minutes then try a cold reset (= interrupt the electrical current to the device, wait a couple of seconds and then connect it again).
:!: Warning, interrupting current while the device is updating might softbrick it and require serial or even jtag connection to recover it.
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!

Post-upgrade operations

The simpler way to see if the firmware was actually upgraded.

LuCI method

Go to Status > Overview to verify you are running the new release.

Command line method

In SSH, the login banner states the release information like version and so on.

After the firmware update, it is good to check for any updated packages released after the base OS firmware image was built.

After a successful upgrade, you will need to reinstall all previously installed packages. You made a list of these above. 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, it might not be necessary.

Afaik there is no way to do this with Luci webinterface.

Command line method

Go to Status > Overview to verify you are running the new release.

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 diffutils program is helpful for this.

install diffutils

root@lede:/# opkg install diffutils

locate all -opkg files

root@lede:/# find /etc -name *-opkg

compare old customized /etc/config/snmpd with new generic file /etc/config/snmpd-opkg

root@lede:/# diff /etc/config/snmpd /etc/config/snmpd-opkg

merge in any needed changes to the active version of the configuration file

root@lede:/# vi /etc/config/snmpd

if the new version provided by the package maintainer should replace the old config file then just swap it in

root@lede:/# mv /etc/config/snmpd-opkg /etc/config/snmpd 

clean up by removing the package manager-version of the configuration file

root@lede:/# rm /etc/config/snmpd-opkg


Finally, the newly installed packages should be enabled and started (if they need this; many do)

LuCI method

Go to System > Startup and enable any service you need.

Command line method

example to start snmpd:

root@lede:/# /etc/init.d/snmpd enable && /etc/init.d/snmpd start 

The upgrade is fully complete now. It is a good idea to do a test reboot and ensure all expected functionality is working as before.

root@lede:/# reboot

Manual firmwmare upgrade procedures

These procedures are only needed in unusual circumstances.

mtd

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

netcat

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 192.168.1.1 1234 < lede-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin
  1. 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.)

free
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 192.168.1.111 3333 > /tmp/[specified firmware].bin 

The port 3333 an IP address 192.168.1.111 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 
OR
  • mtd:
    mtd -r write /tmp/[specified firmware].bin firmware

scp

Make sure your router has enough memory.

root@lede:/# free

Make sure you have set the password for your router (you must set a password for your router to enable the SSH).

Copy your firmware to your router

On your Linux PC run:

linux$ scp lede-ar71xx-tl-wr1043nd-v1-squashfs-sysupgrade.bin root@192.168.1.1:/tmp

Input 'yes' to establish authenticity, then input the password of your router. Wait for scp command to finish. Now you can see your firmware in /tmp directory.

Write the firmware to your router

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

Legacy Information: LuCI flash_keep section of /etc/config/luci

Luci has a separate set of settings in the “config extern 'flash_keep'” section of the file /etc/config/luci relating to configuration files that should be preserved.

In the past, it appears this list was used by LuCI (see this post). However, LuCI upgrade procedure actually calls the sysupgrade script and so it appears the flash_keep settings in /etc/config/luci are now ignored.