Attended Sysupgrade – The right way of updating OpenWrt Firmware

I should have discovered this years ago!

I never came across this feature, and it was apparently available a few versions ago. Just now, when version 25.12.0 was officially released, I learned how to simplify upgrading from one version to another (I did this from 24.10.2 to 25.12.0).

I have developed my own routine for backing up packages and configuration files, installing a new image, and restoring everything. To be honest, I always hate doing that, especially in a business environment, as it always requires some downtime. This is why I sometimes fall behind on some sub-versions of OpenWrt firmware (I was still on 24.10.2 instead of 24.10.5).

When you cannot afford extended downtime, you can minimise it with this approach: Attended Sysupgrade (ASU).

On its official page, you can read:

A couple of clicks and a short wait let you download and install a new image with your previous packages and configuration. This eliminates the need to make a list of packages you installed manually or re-enter the configuration just to upgrade your firmware. 

This sounds like a dream, as this was the only feature that all OpenWrt users were missing – upgrading the firmware while everything stays the same.

This package comes preinstalled by default in the OpenWrt 25.12 series, along with the new package manager apk instead of opkg.

It’s like on routers with stock firmware: when you upgrade the firmware, your config stays there. Let’s see if that magic is indeed there. Spoiler alert: it is!

I was interested to see if I could simply update my router from OpenWrt 24.10.2 to 25.12.0 without losing time on backing up and restoring, as I have tended to do in the past.

Of course, I did my own backup the way I always do, just in case, but I was full of hope at this stage that all would go as planned.

On my current router, running 24.10.2, I installed Attended Sysupgrade (ASU):

opkg update
opkg install luci-app-attendedsysupgrade

Because my current router, the Flint 2 (GL.iNet GL-MT6000), has large flash storage, I could also install the owut package. But you do not need to! Read on for an explanation of why.

opkg install owut

The owut package is a tool that you run from the command line of your device to upgrade its OpenWrt firmware while retaining custom packages and device configurations. In its simplest form, you just run owut upgrade; a few minutes later, your device reboots and is running the latest version of OpenWrt with the most current package versions.

Before I even started, I asked myself a question: should I use Attended Sysupgrade (ASU) or owut?

For upgrading your OpenWrt firmware whilst maintaining specific packages and configurations, Attended Sysupgrade is the preferable choice over owut.

Here is why Attended Sysupgrade is preferable:

• Flawless Package Retention: ASU communicates with the OpenWrt build servers to request a custom-compiled firmware image that has all of your currently installed packages pre-baked into the image itself (the squashfs partition). When the router reboots, all your packages are already there.

• Space Efficiency: Because ASU bakes the packages into the compressed read-only partition, it saves a significant amount of flash storage space compared to installing packages manually after flashing.

• How owut differs: owut (OpenWrt Upgrade Tool) acts more like a wrapper for the traditional sysupgrade process. It downloads the generic release image and then attempts to reinstall your packages via opkg after the upgrade. This can occasionally fail if repositories have changed across major versions or if you run out of overlay space during the reinstallation process.

If you read the section How owut differs, here is an advantage of ASU: when you request firmware and any of the packages on your system do not exist in the latest version, it will fail, warn you about what is missing, and prevent you from moving forward — and that’s a good thing! I will explain further.

There is, however, one caveat that you need to remember.

Neither ASU nor owut will back up the /root folder by default, or any custom configuration in the /etc/ folder, if you do not tell them to do so in advance.

You can, of course, change that. If you follow my other OpenWrt posts, you know you can add files and folders to be kept by editing /etc/sysupgrade.conf or, from LuCI > System > Backup / Flash Firmware, adding them in the Configuration tab. Simple!

Important note!

When jumping between major releases (such as from 24.x to a future 25.x release), be aware that underlying software structures occasionally change. Whilst your configuration files will be preserved by the backup mechanism, it is always good practice to download a manual backup archive (.tar.gz) to your computer before initiating the upgrade, just in case a major syntax change requires you to reset and manually reconfigure certain services.

There was a very significant jump from version 23.x to 24.x in the past; due to many underlying changes with Firewall4 and interface names, I often needed to start from scratch. With 24.10 to 25.12.x, you don’t need to worry as much.

Let’s see how ASU works in practice!

Attended Sysupgrade (ASU) in practice

Once you have installed ASU and logged into the LuCI web panel, you will see a new option under System called Attended Sysupgrade, where you will be greeted with the following:

After clicking the green Search for firmware upgrade button, you will then be presented with the options available for your device.

Because my device was on 24.10.2, the next version presented to me was 24.10.5. From the dropdown menu, I could then choose version 25.12.0.

When you are ready to do so, click (NOT YET!) the green Request firmware image button.

But, before you do that…

Make sure to go to System > Backup / Flash Firmware and then to the Configuration tab.

There, you must add all the custom configuration files and folders you have on your router that must be maintained, backed up, and restored upon upgrade.

For example, mine looks like this:

# /etc/example.conf
# /etc/openvpn/
/etc/ssl/
/etc/cloudflared/
/root/

I want to keep the ssl folder and its contents, as well as cloudflared and my /root folder.

I also highly recommend that you Generate archive from the Actions tab and check that the archive is extractable (not corrupted). If, for some reason, it is corrupted, refer to my post: How to Backup Your OpenWrt Router When Built-in Tools Fail.

If your firmware should, for some reason, update with the new packages but lose its configurations, you can easily upload your backup via System > Backup / Flash Firmware > Restore backup, and have everything back as it was in no time.

Moving on…

Your router will communicate with the official OpenWrt servers and check what is available. At this time, it will check which packages are currently on your router and what is available in the repository.

If the server detects that any of your packages have not yet been moved to the new version, it will throw an error.

From this error screen, you will see that the package (luci-app-nft-qos), which is available in the 24.10.x repository, is not yet available in 25.12.x.

Because of that, you cannot move forward and you need to resolve this issue first.

You have two options:

1. Hold off on the update until the package upon which you rely on your current device becomes available, or
2. Remove the package that is causing the conflict, reboot your device, and try again.

Once the conflict is resolved, we can move on.

Now click Request firmware image and wait.

Firstly, the server will validate the packages that need to be included in your firmware.

Then it will build the firmware for you.

Once the firmware is successfully created, you will be presented with the following information.

Before you click the green Install firmware image button, make sure that the option Keep settings and retain the current configuration is ticked as well.

The installation will then commence.

Wait patiently until your router applies everything and reboots into the new version.

If all goes well, your router should restart with the new firmware, with all the packages that you previously installed (using the official installation method) and all configurations applied.

If you have upgraded to version 25.12.0 for the first time and you log back into LuCI, you will be greeted with a question asking if you want to automatically check for new firmware versions.

If you decide to enable checking, you will be asked, in the next step, to add one line to the router configuration.

You just need to click Save & Apply and you are ready.

This method of upgrading OpenWrt will definitely help more users to supercharge their compatible routers, not only extending their lifespan but also increasing their privacy.

👏 🙌

PS. If you installed Cloudflare Tunnel on your OpenWrt Router, this package was installed manually. Despite the fact that it updates itself regularly, you will need to re-install it (re-download) after the first reboot with the new firmware. For that, refer to the Install the official cloudflared package step. Remember that in the 25.12 series, opkg has changed to apk.