OpenWrt: Upgrading OpenWrt to the latest snapshot build

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.

Custom Packages

The first step is to identify any custom packages that need to be reinstalled.

The script and listuserpackages.awk script 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: files under ‘/lib/upgrade/keep.d/’, files listed in ‘/etc/syupgrade.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\

You now have the sysupgrade image in the /tmp directory, which take note is a RAM storage space.  Now verify the checksum:

# wget --no-check-certificate
# md5sum -c md5sums 2> /dev/null | grep OK

Upgrade Procedure

Now with your image located in /tmp:

# sysupgrade -v /tmp/openwrt-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

Check for any upgrades
# opkg update
# opkg list-upgradable
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.



How to build OpenWrt minimal image, or a custom firmware