How to update OpenWRT while retaining existing configuration and all custom packages

How to update OpenWRT while retaining existing configuration and all custom packages

OpenWRT upgrades itself by saving configuration files from known locations (plus manually defined files), overwriting the partition with the latest firmware and then restoring the saved configuration.

This usually works for the configuration itself, however the process doesn’t take care of any custom packages that were previously installed manually (either through LuCI or with opkg). These packages need to be noted down beforehand and then reinstalled. This can be done manually or partially automatic using opkgscript.

This guide was tested and run on an x86 based device using the combined/ext4 filesystem image – this image file has a read/write root partition intended for advanced devices with write-resistant storage.

Connect via SSH and run the following commands to create a list of currently installed packages:

chmod +x
sh write

The script saves the list to /etc/config/opkg.installed. Download and store that file somewhere locally for record keeping.
For extra safety you can SSH/SCP into the OpenWRT device and download the whole /etc folder (configuration files are stored mostly in /etc/config).

Then proceed to perform the system upgrade as indicated in the official OpenWRT guide. I personally prefer using the command line method for this (since LuCI basically does the same thing).

It is best to perform the upgrade using a wired connection since most wireless drivers are separate packages that need to be installed manually, making them unavailable after the upgrade.

Start with retrieving the latest firmware image available for your device – it can either be downloaded directly to the OpenWRT  device or downloaded to the computer and then transferred (via SCP) to the device. Check that it is extracted and placed under /tmp as that is the RAM-based tmpfs.

Finally, when you’re certain that everything that should have been saved is stored safely, run:

sysupgrade -v /tmp/firmware_image.bin

It’s a good idea to keep a ping running on the device’s IP to find out when it returns online (and if it returns). Luckily, my update went without a hitch and within a minute the device was back online and running the latest release:

The configuration files should have survived the upgrade – check for the presence of the /etc/config/opkg.installed file. If it’s missing, restore the entire /etc/config folder from your previous backup. Then re-download opkgscript:

chmod +x

Be sure to run opkg update first, then we can reinstall the lost packages:

sh -v install

Depending on how many custom packages were installed before, this process may take a while. When done perform one final restart and you should find OpenWRT configured and running as before the upgrade.

If you’ve upgraded between major releases some things may have changed or no longer work as before – in those cases things will need to be addressed and reconfigured manually.

References: (1), (2), (3)

Leave a Reply

%d bloggers like this: