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