Upgrade using Attended Sysupgrade
Attended SysUpgrade (ASU) simplifies upgrading your firmware. A couple clicks and a short wait lets you download and install a new image along with updates to your added packages and configuration. This eliminates the need to make a list of packages you installed manually or re-enter configuration just to upgrade your firmware. ASU is included in OpenWrt by default on most devices, and is available to use on both the LuCI web UI and command-line interface.
Because it is initiated by a person who waits until it's complete, it's called “attended” sysupgrade. There is also a video overview available.
From LuCI
The LuCI Attended Sysupgrade App is powered by the luci-app-attendedsysupgrade package. Which provides a page in the router's web interface. It requests a new firmware image built with the current set of packages, waits until it's ready, then downloads and flashes the image. If Keep Configuration is checked in the GUI, the device preserves all the settings.
To install luci-app-attendedsysupgrade, go to System → Software, update the package list, and search for luci-app-attendedsysupgrade. Install it in the usual manner.
To upgrade your firmware:
- Make a backup: Go to System → Backup/Flash firmware. Click Generate archive. (Just do it. Every time...)
- Go to System → Attended Sysupgrade.
- Click Search for sysupgrade.
- Select your desired version from the dropdown, and click Request Sysupgrade.
- There will be a short wait as the server builds a custom image that includes updates to all the packages that are currently installed.
- When that completes, you will see a window describing the new firmware:
- If you wish to keep settings, check the box. Otherwise, settings will be set to factory default.
- Click Install Sysupgrade and the router will download the new image, flash it, and reboot.
- You'll be running the new firmware, with all your packages and settings intact.
The main window, click Search for sysupgrade
Select an available release and click Request Sysupgrade
Review the generated image, choose Keep Settings (or not), and click Install Sysupgrade
From CLI
The included owut package is generally considered the best CLI option now. It performs an upgrade similar to ASU, but is run from SSH/command line instead of the web GUI.
If you are using an old version of OpenWrt, 23.05 or before, then the auc package is available. For details on auc, continue on this page.
AUC
To install the auc package, ssh into the router and enter opkg install auc or in the web interface, go to System → Software, update the package list, and search for auc. Install it in the usual manner.
To upgrade your device firmware, first Make A Backup (see first step above). Then enter auc on the command line. The default is to get the next version. You can specify the following options on the command line.
root@openwrt.lan:~# auc --help auc (0.2.4-8) auc: Attended sysUpgrade CLI client Usage: auc [-b <branch>] [-B <ver>] [-c] [-f] [-h] [-r] [-y] -b <branch> use specific release branch -B <ver> use specific release version -c only check if system is up-to-date -f use force -h output help -n dry-run (don't download or upgrade) -r check only for release upgrades -F <fstype> override filesystem type -y don't wait for user confirmation Please report issues to improve the server: https://github.com/aparcar/asu/issues
Here are the details of each option.
| Name | Default | Description |
|---|---|---|
-b <branch> | installed branch | Search for updates on this specific branch. The value is a string containing a release branch name, 19.07 or 23.05, or the snapshot branch name, SNAPSHOT. |
-B <ver> | newest version on current branch | Search for updates for this specific release version. Must be on the branch specified with -b or an error will be reported. If the branch is SNAPSHOT, then the only valid value for -B is again SNAPSHOT, and specifying the value is redundant. |
-c | false | Perform all the steps to check if the system is up-to-date, then quit. If changes are found, then a list of the detected differences is shown, color coded so that you can see if packages are upgrading or downgrading with the target branch and version. Since this is a completely non-destruction operation, running auc -c is a quick and safe way to see what changes have been released since your last sysupgrade. |
-f | false | Force an upgrade, even when there are no changes detected. |
-n | false | Perform a dry-run, by actually building the image, but then quit before download and install. Since the image is never downloaded, this is very much like -c in its local effect, but since it builds the image, you see all the error checking performed by the build server, too. |
-r | false | Check only for release upgrades. Like -c, but ignores any package changes. This is a quick way to see if there is a “dot” release on the branch currently installed. |
-F <fstype> | current installed fstype, usually squashfs | Build the image to override the current filesystem type. This is an advanced option, which can brick many devices, so use great care. On generic devices, like x86 or armsr, you can switch between squashfs and ext4 without issues. |
-y | false | Assume 'yes' for all the user confirmation prompts and run to completion. |
Example use
To use auc to check for new packages, or newer versions of the current branch, simply use the -c option. This is completely benign, as auc terminates after reporting what it sees without doing anything further. Using -c to experiment with the other options is a safe way to explore how auc works.
$ auc -c auc/0.3.2-1 Server: https://sysupgrade.openwrt.org Running: SNAPSHOT r24414-255d5c9bf8 on x86/64 (generic) Available: SNAPSHOT r24414-255d5c9bf8 Requesting package lists... base-files: 1548-r24414-255d5c9bf8 -> 1549-r24427-c4fe1bfc65 dnsmasq-full: 2.89-6 -> 2.89-7
By default, auc works on the branch currently installed on your device. The -b option can be used to change this behavior, so that you can upgrade or downgrade between release branches (like 19.07 or 23.05) or snapshot (where you just literally use snapshot as the value). The -B option can be used to select a specific version within a branch, such as 22.03.1 or 23.05.0.
This example detects that 23.05.2 is installed, and shows information related to downgrading to 22.03.4.
As indicated by the warning, this is probably not a good idea as the jump in versions is “too far”, but you *can* use -B to downgrade within a branch pretty safely.
$ auc -c -b 22.03 -B 22.03.4 auc/0.3.2-1 Server: https://sysupgrade.openwrt.org Running: 23.05.2 r23630-842932a63d on x86/64 (generic) Available: 22.03.4 r20123-38ccc47687 WARNING: Downgrade to older branch may not work as expected! Requesting package lists... kmod-usb-storage: 5.15.137-1 -> 5.10.176-1 terminfo: 6.4-2 -> 6.3-2 openssh-sftp-server: 9.5p1-1 -> 9.3p2-1 libopenssl: 3.0.12-1 -> 1.1.1w-1 luci-app-statistics: git-23.315.63824-5a81162 -> git-23.153.53801-38f5b55 ...
ASU Server
The ASU Server listens for image requests and, if valid, automatically generates them. It coordinates several OpenWrt ImageBuilders and caches the resulting images in a Redis database. If an image is cached, the server can provide it immediately without rebuilding.
The ASU Server provides an API to request custom firmware images with any selection of packages pre-installed. This avoids the need to set up a build environment, and makes it possible to create a custom firmware image even using a mobile device.
- The current production ASU Server is
sysupgrade.openwrt.org. It provides released versions, release candidates, and the main branch snapshot. - There is a development server at
asu.aparcar.orgthat is not always running.
ASU relies on significant updates to ImageBuilder, primarily by @aparcar on the Github repo.
Extroot configuration
If your device is configured for Extroot, then you will need to reboot twice after any sysupgrade. The external root filesystem does not remount after the first boot. There is no need to modify or recreate extroot settings, just reboot again and the configuration will work as before and continue to do so.