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 ext4/combined 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).


If you’ve resized the root partition and/or added additional partitions, make sure to save the current partitions layout with fdisk -l, as the update will reset all partitions to OpenWRT’s defaults:

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.


If you have resized the root filesystem before, you’ll now discover that it has shrunk (the default root size in OpenWRT 21 is just 100MB). This may very well be insufficient with a large number of extra packages. In this case you’ll need to enlarge the root filesystem after every OpenWRT update.

Start by installing parted

opkg update && opkg install parted

Run parted and resize the second (root) partition:

(parted) resizepart 2 10000000s

Of course adjust the size to the correct value for you – the s following the number tells it to use sectors instead of (mega)bytes. Use the exact number you’ve saved before the update.
If you’ve had additional partitions on the storage device you’ll notice those are now gone too, so make sure the new size doesn’t go beyond the previous size and overlap the other partitions (corrupting them). We’ll take care of those later.

Check the new size with

(parted) p

Switch the size display mode from (default) MB to MiB using:

(parted) unit MiB print list

Then continue to recreate the other partition(s) with the exact starting and ending sector number as before (mkpart PART-TYPE [FS-TYPE] START END):

(parted) mkpart p ext3 10002432s 500115455s

Exit parted and double check that the partition layout is identical with the one before the update with

fdisk -l

The proceed to resize the root filesystem (we’ve only resized the partition so far):

resize2fs /dev/sda2

and finally reboot.

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)

One comment

  1. Thank you very much for this guide! I’d been planning on making an OpenWRT x86 router, and this guide has been very helpful for me as a supplement to the documentation to know how to update it when it’s not on a consumer router firmware

    Matthias Galvin

Leave a Reply