Caution
This article was written at the time of the release of OpenWrt 23, and the content described in this article may change in the future. Please be sure to back up important data, carefully read possible error messages, and operate with caution. The author does not make any guarantees about the content of this article.
WHY? Why does this article exist?#
Because the OpenWrt community is lazy or understaffed did not provide an additional set of suitable upgrade tools for the x86 target, the x86 device system upgrade tool is the same as other targets, only the sysupgrade tool, which can only flash the disk image in a simple and crude way. The OpenWrt documentation provides a pacifying solution that is neither elegant nor simple and has side effects.
Tip
Another better solution is to use extroot, which uses a SquashFS image to separate the OverlayFS upper and lower onto different disks. When upgrading the version, directly use the pre-compiled image to flash the disk where the lower is located, and then modify the extroot configuration to redirect the OverlayFS to the original upper disk to restore the original state. However, due to the fact that the current mainstream OpenWrt community has not yet fixed this 5-year-old bug, the extroot configuration does not take effect, so this solution is not feasible. 1
As a technically inexperienced and not very knowledgeable but exploratory ProUser victim, I took the time to write this upgrade guide based on an upgrade script 2 to make it easier for OpenWrt newcomers to upgrade and keep up with the latest updates.
Best Practice Solution#
Warning
The method described in this article is only applicable to the OpenWrt mainstream and branch variants such as ImmortalWrt that have good distribution versions and package management sources, and is not applicable to any self-compiled or "great god" modified reissue versions.
Note
The target of this article is x86_64, upgrading to OpenWrt 23.05.0, please adjust it to meet your own needs.
OpenWrt x86 is essentially a specialized version of a Linux distribution, theoretically it can of course retain the configuration and upgrade major versions like a general Linux distribution, but as mentioned earlier, there is no upgrade tool, so a series of operations need to be performed to manually achieve it.
Get the version number (optional)#
oldver=$(awk -F\" 'NR==2 {print $2}' /usr/lib/os-release)
newver=23.05.0
Upgrade all packages (optional)#
opkg update
opkg upgrade netifd
# Upgrading netifd separately because it will restart the network interface and interrupt the SSH connection
opkg list-upgradable | cut -d ' ' -f 1 | xargs opkg upgrade
Replace the kernel#
Important
Confirm the boot partition mount location here. My mount location is /boot and there is no secondary mount. The file tree looks like this. Please modify the path according to the actual kernel location.
tree /boot
/boot
├── boot
│ ├── grub
│ │ ├── boot.img
│ │ ├── core.img
│ │ ├── grub.cfg
│ │ └── grub.cfg.b
│ ├── vmlinuz
│ └── vmlinuz.23.05.0-rc3
└── efi
└── boot
└── bootx64.efi
-
Backup the old version of the kernel
mv /boot/boot/vmlinuz /boot/boot/vmlinuz.$oldver
-
Download the new version of the kernel
wget -O /boot/boot/vmlinuz "https://downloads.openwrt.org/releases/23.05.0/targets/x86/64/openwrt-23.05.0-x86-64-generic-kernel.bin"
-
Verify that the file hash is consistent
sha256sum /boot/boot/vmlinuz
Process the packages#
-
Manually download the kernel.ipk of the new release version
Note that this is not the actual kernel, but the software package that opkg provides kernel version dependencies
wget https://downloads.openwrt.org/releases/23.05.0/targets/x86/64/packages/kernel_5.15.134-1-47964456485559d992fe6f536131fc64_x86_64.ipk
-
Manually download the keyring.ipk of the new release version (optional)
wget https://downloads.openwrt.org/releases/packages-23.05/x86_64/base/openwrt-keyring_2022-03-25-62471e69-2_x86_64.ipk
Note
The key used in the release version is different from the snapshot/rc version, so when switching between them, you need to install keyring.ipk, otherwise you don't need to.
Install them:
opkg install kernel_*
opkg install openwrt-keyring_*
Modify opkg source#
-
Replace the distribution version number of the software source
sed -i.backup "s/$oldver/$newver/g" /etc/opkg/distfeeds.conf
-
Update the package list
opkg update
Upgrade the new release version packages#
- Disable /lib/functions.sh
(Forgot why this step was taken, please add it in the comments if you know)
mv /lib/functions.sh /lib/functions.sh.b
- Upgrade the base files
opkg upgrade base-files
- Upgrade all other packages except netifd by forcing overwrite
opkg list-upgradable | cut -d ' ' -f 1 | grep -v 'netifd' | xargs opkg upgrade --force-overwrite
- Upgrade netifd
opkg upgrade netifd
reboot&done#
If everything goes well, after restarting, it will be a brand new version of OpenWrt.
If there were errors earlier that you didn't handle, this restart may not start again.
Comments#
Footnotes#
-
It is believed that some derivative versions have merged and fixed the code, but since they may lack distribution versions and package management sources, they are not discussed here. ↩
-
It was probably found online during the OpenWrt 21 era, some of which have expired, and the source of the script is no longer available. If you know the source, please leave a link in the comments: ↩