OpenWrt: Upgrading OpenWrt to the latest snapshot build

Update Jan 2023: I have written an updated article on doing a sysupgrade from older OpenWrt versions to 19.x.  If you want to do an in-place sysupgrade of a 19.x or earlier snapshot, use the instructions from the newer article, but selecting a snapshot image instead of a stable release image.

Although stables releases of OpenWrt come out every 6 to 12 months, the automatically built snapshots offer a way to embrace the latest features, patches, and security fixes without waiting that long.

A sysupgrade procedure works by saving the configuration files from known locations, deleting the entire filesystem, installing the new version of OpenWrt, and then restoring the configuration files.

This is usually painless, but there can be issues if configuration changes have been made in non-standard file locations and are not saved. Additionally, custom packages do not survive the sysupgrade and have to be reinstalled (to ensure compatibility with the kernel) and their new configurations must be manually merged.

The definitive guide to upgrades can be found here on the OpenWrt wiki.

Identify Customizations

Since this is an OpenWrt upgrade, I’m going to assume that ssh is enabled. If you want to use serial access instead, read my article here.

You should go ahead and ssh into your router as root (same login used for the LuCI web interface). The current version of the firmware can be determined using:

# cat /etc/banner
# cat /tmp/sysinfo/board_name
# cat /tmp/sysinfo/model

You can use this information when choosing the correct sysupgrade binary and also for validating that the upgrade was successful.

Verify Package Manager

Before moving on, make sure opkg does not use any deprecated URL by trying a refresh.

# opkg update

If you have any messages that look like “opkg_download: Failed to download http://downloads.openwrt.org/snapshots/trunk/mvebu/generic/packages/base/Packages.gz, wget returned 8”, then you need to edit your opkg repository URL.

Modify “/etc/opkg/distfeeds.conf” so that it points to your current releases packages. For example, for Chaos Calmer here is the URL for package management. Use ‘http’ instead of ‘https’ unless you are prepared to install the correct certificates.

When complete, you should have no errors when running ‘opkg update’.

Custom Packages

Then identify any custom packages that need to be reinstalled.

The listuserpackages.sh script and listuserpackages.awk script described on the wiki page can tell you which packages have been user installed. I like the output of listuserpackages.awk because it can easily be used after the reinstall.

ACTION: You need to copy this list to your local host because you will need to reinstall these with opkg after the upgrade.

Custom Configurations

Then we need to know the list of configuration files that sysupgrade will preserve which consists of the content of files in ‘keep.d’:

cat /lib/upgrade/keep.d/*

Files listed in ‘syupgrade.conf’

cat /etc/sysupgrade.conf

And the file list coming from the command below:

opkg list-changed-conffiles

If you have other configuration files that need to be preserved, you should add them to /etc/sysupgrade.conf.

ACTION: Add any files not recognized by the methods above to /etc/sysupgrade.conf

Downloading the Image

I’m going to assume that the router has internet access to directly download the sysupgrade image. If the router does not have public internet access, you could use either scp or tftp as described here to copy it to the router.

Pick the appropriate image for your hardware from the snapshots build folder. The ‘linksys-shelby’ is the one appropriate for my WRT1900ACSV2, obviously you need to pick the one that matches your router. There is a table here.

# cd /tmp
# opkg install wget
# wget --no-check-certificate https://archive.openwrt.org/chaos_calmer/15.05.1/mvebu/generic/openwrt-15.05.1-mvebu-armada-385-linksys-shelby-squashfs-sysupgrade.tar

You now have the sysupgrade image in the /tmp directory, which take note is a RAM storage space that will not survive a reboot. Now verify the checksum of the downloaded file by downloading the ‘md5sums’ file that is located in the same directory as the binary.

# wget --no-check-certificate https://archive.openwrt.org/chaos_calmer/15.05.1/mvebu/generic/md5sums
# md5sum -c md5sums 2> /dev/null | grep OK

Upgrade Procedure

Run sysupgrade with the binary image located in /tmp.

# sysupgrade -v /tmp/openwrt-15.05.1-mvebu-armada-385-linksys-shelby-squashfs-sysupgrade.tar

After an “Upgrade completed” or “sysupgrade successful” message, the system will reboot and you will need to give it a minute and then ssh back in. Upon entry, you should see a new version embedded in the banner “Bleeding Edge, xxxxx” which is the build number of the snapshot you selected.

  _______                     ________        __
 |       |.-----.-----.-----.|  |  |  |.----.|  |_
 |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
 |_______||   __|_____|__|__||________||__|  |____|
          |__| W I R E L E S S   F R E E D O M
 -----------------------------------------------------
 DESIGNATED DRIVER (Bleeding Edge, 50082)
 -----------------------------------------------------

Post Installation

Reinstall user packages

Now you need to run ‘opkg install <packagename>’ on all the custom packages you had installed before the upgrade.

This can be done manually, but if you copied the output of the listuserpackages.awk script from earlier and paste that into a file name /tmp/oldpkgs.txt, then you can use xargs to run opkg against each package.

# cat /tmp/oldpkgs.txt | xargs opkg install

The collected errors will be shown at the bottom. More than likely you will get a few ‘Cannot install package xxxxx’, which could be a result of the package no longer being available on the newer kernel. Retry those manually.

And where a new conf file created, you will be warned and the newer one will be created as ‘/etc/config/<filename>-opkg’. You will need to manually review and merge these files.

 

REFERENCES

https://wiki.openwrt.org/doc/howto/generic.sysupgrade

https://openwrt.org/docs/guide-user/installation/sysupgrade.cli (new upgrade procedure, sha256sum)

https://wiki.openwrt.org/about/history

https://wiki.openwrt.org/about/latest

https://downloads.openwrt.org/snapshots/trunk/mvebu/generic/

https://downloads.openwrt.org/chaos_calmer/15.05.1/mvebu/generic/

https://peejseej.nl/2017/08/sha265sum-on-openwrt/ (sha256sum comes from coreutils-sha256sum)

https://fixmynix.com/build-openwrt-minimal-image-custom-firmware/

 

NOTES:

Backing up /etc configurations on OpenWrt

cd /etc && tar cvf custometc.tar *

Do you have a musl libraries or uClibc?

ls -l /lib | grep libc

ld-musl-arm.so.1 -> libc.so

sha256 checksum calculation

# opkg install coreutils-sha256sum
# wget --no-check-certificate http://downloads.openwrt.org/snapshots/targets/mvebu/cortexa9/sha256sums
# sha256sum -c sha256sums 2>/dev/null | grep OK