OpenWrt upgrade process

Introduction

Typically, when a new version of OpenWrt is released, I completely wipe the router and start over. However, with the recent release of 15.05.1, I wanted to perform an in-place upgrade while preserving all of my data.

Before we begin, it’s important to understand how the OpenWrt upgrade process works. It’s best to quote the wiki on this one:

Both the LuCI and sysupgrade upgrade procedures work by saving specified configuration files, wiping the entire file system, installing the new version of OpenWrt and then restoring back the saved configuration files. This means that any parts of the file system that are not specifically saved will be lost.

In particular, any manually installed software packages you may have installed after the initial OpenWrt installation have to be reinstalled after an OpenWrt upgrade. That way everything will match, e.g. the updated Linux kernel and any installed kernel modules.

Any configuration files or data files placed in locations not specifically listed as being preserved below will also be lost in an OpenWrt upgrade. Be sure to check any files you have added or customized from a default OpenWrt install to back up these items before an upgrade.

This is important to note because OpenWrt doesn’t automatically preserve everything by default. You’ll need to tell OpenWrt which files and directories to preserve in a configuration file.

Preparation

Check your release

Start by viewing the /etc/openwrt_release file to double-check the version you’re running. Here, you can see I’m on 15.05.

DISTRIB_ID='OpenWrt'
DISTRIB_RELEASE='15.05'
DISTRIB_REVISION='r46767'
DISTRIB_CODENAME='chaos_calmer'
DISTRIB_TARGET='ar71xx/generic'
DISTRIB_DESCRIPTION='OpenWrt Chaos Calmer 15.05'
DISTRIB_TAINTS=''

Backup

I would highly recommend you make a backup of any necessary configuration files. If you haven’t seen it, I wrote a small script to export a list of installed packages to /etc, then tar and gzip everything in /etc (where most of your configuration files are stored).

Also, it’s important to test your backups before you need them! 🙂

Preservation

Next, you’ll need to determine what files will be preserved through the upgrade by using the command below.

opkg list-changed-conffiles

If a file or directory is not in this list, it will not be preserved through the upgrade.

OpenWrt will preserve any files or directories listed in /lib/upgrade/keep.d/ (e.g., /lib/upgrade/keep.d/keep.me) or /etc/sysupgrade.conf. The easiest thing to do is list your needed files or directories in /etc/sysupgrade.conf. My file is shown below.

## This file contains files and directories that should
## be preserved during an upgrade.

/etc/config/
/etc/crontabs/
/etc/uhttpd.crt
/etc/uhttpd.key
/etc/rc.local

You can see that I’m choosing to preserve the entire /etc/config directory, as well as all my crontabs, the certificate and key for LuCI, and my startup file.

Upgrade

I recommend using the sysupgrade utility, since it’s tailor-made for this process.

Start by downloading the new firmware. For upgrades, always use the firmware that ends in sysupgrade.bin, not the factory.bin firmware. In my case, I’m using a TP-Link Archer C7 v2 going from 15.05 to 15.05.1, so I’ll be using this file. Keep in mind, you’ll need enough space in RAM to download the files.

cd /tmp
wget https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/openwrt-15.05.1-ar71xx-generic-archer-c7-v2-squashfs-sysupgrade.bin

Next, I highly recommend checking the MD5 sum to make sure the file isn’t corrupt.

cd /tmp
wget https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/md5sums
md5sum -c md5sums 2> /dev/null | grep OK

If the MD5 sum returns OK, you can proceed with the upgrade (the -v flag tells sysupgrade to be verbose.).

sysupgrade -v /tmp/openwrt-15.05.1-ar71xx-generic-archer-c7-v2-squashfs-sysupgrade.bin

Expect the upgrade to take a few minutes. The router should reboot when completed.

Verification

Verify you can SSH into your router (assuming you chose to preserve the correct configuration files), then view the /etc/openwrt_release file to check the new version you’re running.

DISTRIB_ID='OpenWrt'
DISTRIB_RELEASE='15.05.1'
DISTRIB_REVISION='r48532'
DISTRIB_CODENAME='chaos_calmer'
DISTRIB_TARGET='ar71xx/generic'
DISTRIB_DESCRIPTION='OpenWrt Chaos Calmer 15.05.1'
DISTRIB_TAINTS=''

Now, you’ll need to re-download all your previously installed packages (this is where that backup list comes in handy).

opkg update
opkg list-upgradable
opkg install package1 package2 package3

I had to re-enable LuCI, you probably will too.

/etc/init.d/uhttpd start
/etc/init.d/uhttpd enable

In addition, you’ll need to disable any unneeded services again.

/etc/init.d/telnet stop
/etc/init.d/telnet disable

 

Let me know how your upgrade went!

Logan

8 thoughts on “OpenWrt upgrade process

  1. Thank you, Logan!

    After reading the entire upgrade page on OpenWrt which was too extensive for me I luckily came across your guide which explained a lot better what the steps are and what should be taken care of.

    The upgrade process from BB 14.07 to CC 15.05.1 was straightforward on my Archer C7 thanks to your guide, I spent some time though trying to backup all settings and remember all packages installed and why I installed some of them 2 years ago :).

    A few notes that got my attention in your guide and a few hints I came across while upgrading:

    -your URL ends in -factory.bin while you clearly state that we should use the one ending in sysupgrade.bin. I chose the latter and it worked fine: https://downloads.openwrt.org/chaos_calmer/15.05.1/ar71xx/generic/openwrt-15.05.1-ar71xx-generic-archer-c7-v2-squashfs-sysupgrade.bin

    -the default wget cannot download files via https so you need to install the real wget: opkg install wget (suppose you already updated the lists with opkg update)

    -after installing wget, you will still have trouble getting files via https because of missing certificates. The steps are:
    mkdir -p /etc/ssl/certs
    export SSL_CERT_DIR=/etc/ssl/certs
    source /etc/profile
    opkg install ca-certificates

    -one will probably encounter the TRX error but it’s ok: 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 (from their page)

    -if your 5GHz radio still cannot start you should simply delete the “option txpower ‘xx'” from /etc/config/wireless and restart the network service: “/etc/init.d/network restart”

    -one might always look for the least used channel around house/office in order to get the most out of the WiFi connection (look for some tools that check which channels are most used and pick the last one. Macs have a built-in tool for that)

    -don’t forget to secure your router: allow login only via SSH with keys, disable password login, install luci-ssl for https access, etc

    Thanks again for the simple guide, looking forward for other useful posts.

    Bosch

    • Bosch,

      Thanks for pointing out the incorrect link, I’ve updated it! Also, I’m using the BusyBox version of wget and it’s working with HTTPS…
      root@c7:~# wget -v
      wget: invalid option -- v
      BusyBox v1.23.2 (2016-01-02 18:01:44 CET) multi-call binary.

      Usage: wget [-c|--continue] [-s|--spider] [-q|--quiet] [-O|--output-document FILE]
      [--header 'header: value'] [-Y|--proxy on/off] [-P DIR]
      [-U|--user-agent AGENT] URL...

      Retrieve files via HTTP or FTP

      -s Spider mode - only check file existence
      -c Continue retrieval of aborted transfer
      -q Quiet
      -P DIR Save to DIR (default .)
      -O FILE Save to FILE ('-' for stdout)
      -U STR Use STR for User-Agent header
      -Y Use proxy ('on' or 'off')

    • I just removed the ‘s’ character from “https” in the image download link and I was able to use wget like normal. This was done from the Chaos Calmer 15.05 version using what I believe was the default (unmodified) version of wget.

      Happy Hacking

  2. Hi,

    Many thanks for this great article.

    At my home, I use an Archer C7 v2 (which I initially flashed with Barrier Breaker and upgraded to Chaos Calmer 15.05 some time ago) as gateway in my LAN. As I found out lately that there is a new version of Chaos Calmer (15.05.1), your article was very welcome and I decided to follow it.

    I added a step before sysupgrade where a list of the custom packages I installed (see https://wiki.openwrt.org/doc/howto/generic.sysupgrade -> listuserpackages.sh) was generated, though.

    The upgrade was successful and my C7 is up and running w/o problems so far I could see by now.

    Here are some of the issues I ran into, maybe this is helpful for others.

    1. After reboot, login worked, but no internet connection was possible.
    “netstat -r” (route) was okay, “ping 8.8.8.8” was possible, so DNS was apparently not working
    => The problem was that the dhcp lease file was configured to be on external USB drive but as the USB drive could not be mounted (yet.. due to yet-to-be-installed packages) dnsmasq was not working

    2. The custom user packages list I created contained every package in one line. To be able to install all of them at once via “opkg install pkg1 pkg2 pkg3 …”:
    => sed ‘:a;N;$!ba;s/\n/ /g’ user_installed_pkgs.txt > user_installed_pkgs_one_line.txt
    => opkg install `cat user_installed_pkgs_one_line.txt`
    For already installed packages thats also working (was the case, my file listed many already installed packages), opkg then tells e.g. “kmod-usb2 (3.18.23-1) installed in root is up to date.”

    3. Some errors were printed out during opkg install:

    3.1 “Configuring dbus.
    Unknown group “netdev” in message bus configuration file”
    => I ignored it, because regarding https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=385495, it seems a non-critical bug in avahi

    3.2 “Configuring block-mount.
    this file has been obseleted. please call “/sbin/block mount” directly
    block: mounting /dev/mtdblock2 (squashfs) as /mnt/mtdblock2 failed (-1) – Unknown error -1
    block: /dev/mtdblock3 is already mounted
    block: mounting /dev/sda1 (vfat) as /mnt/sda1 failed (-1) – Unknown error -1″
    => This was caused by dependency problems (e.g. “Configuring kmod-fs-vfat.” came later, “already mounted” is not really a problem and squashfs was fine after reboot

    3.3 “Collected errors:
    * resolve_conffiles: Existing conffile /etc/vnstat.conf is different from the conffile in the new package. The new conffile will be placed at /etc/vnstat.conf-opkg.
    * resolve_conffiles: Existing conffile /etc/config/vnstat is different from the conffile in the new package. The new conffile will be placed at /etc/config/vnstat-opkg.
    * resolve_conffiles: Existing conffile /etc/avahi/avahi-daemon.conf is different from the conffile in the new package. The new conffile will be placed at /etc/avahi/avahi-daemon.conf-opkg.”
    => This was resolved by diff’ing and adjusting the files manually

    4. Luci auth/login appears for each page
    After the initial login, I only could see the Status page. No matter what I clicked in Luci afterwards lead me to the login page again (in Firefox).
    => It turned out to be that rpcd was not running, with “/etc/init.d/rpcd start” (+
    enable) the problem was gone (found the solution here: https://github.com/openwrt/luci/issues/547)

    Thanks
    Patrick

    • Patrick, thanks for sharing! I haven’t used OpenWrt in some time (I’m currently using Ubiquiti gear). Have you considered switching to LEDE? I heard OpenWrt development was stopping.

      • Yesterday, I switched to LEDE from CC and so far I didn’t encounter any problems. I did it like an OpenWrt upgrade.

        After checking OpenWrt Website yesterday I read that LEDE and OpenWrt will unify again 🙂

        • Nice, thanks for the reply!

          Yes, I read that as well. Glad the two are finally on friendly terms again.

Leave a Reply to kenshin Cancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.