Should you keep settings during OpenWrt sysupgrade?
LuCI’s Keep settings and retain the current configuration restores configuration files from the sysupgrade backup to the new firmware. Settings such as /etc/config can be preserved, but manually installed package binaries need reinstalling unless they are included in the new image. It does not preserve every custom file or the entire previous firmware.
The more important boundary is configuration compatibility. A target architecture transition, partition-layout change, or switch and network-model migration can require clean configuration. Restoring the old settings can overwrite new defaults and remove network access even when the backup archive itself is valid.
Freeze device and image identity before flashing
| Item | Value to retain | Decision use |
|---|---|---|
| Board identity | Model, board_name, and target | Prevent selection of another device image. |
| Current release | Version, revision, and architecture | Define the upgrade path and release notes. |
| Image | Filename, checksum, and validation | Exclude transfer damage and wrong format. |
| Preservation list | sysupgrade -l output | Review files before creating the archive. |
| Package list | User-installed packages | Build the post-upgrade reinstall plan. |
ubus call system board
cat /etc/openwrt_release
sysupgrade -l > /tmp/sysupgrade-files.txt
if command -v apk >/dev/null; then apk info > /tmp/packages-before-upgrade.txt; else opkg list-installed > /tmp/packages-before-upgrade.txt; fiCopy these files to an administration workstation. A backup stored only under /tmp on the router is not recovery material when an upgrade leaves the overlay unreachable.
Create the backup and inspect its contents
sysupgrade -b /tmp/backup-before-upgrade.tar.gz
tar -tzf /tmp/backup-before-upgrade.tar.gz | sort > /tmp/backup-contents.txt
sha256sum /tmp/backup-before-upgrade.tar.gz
ls -lh /tmp/backup-before-upgrade.tar.gz /tmp/backup-contents.txtDo not trust only the archive-created message. Confirm that required custom files appear in the listing. Scripts, certificates, and keys outside conffile declarations and /etc/sysupgrade.conf may require separate preservation. Move backups containing private keys to encrypted storage.
Validate the image and upgrade path
Most already-installed devices use an image ending in -sysupgrade.bin; do not confuse it with a factory image. Compare the downloaded checksum with the official download directory and run the device-side image test.
sha256sum /tmp/openwrt-device-sysupgrade.bin
sysupgrade -T /tmp/openwrt-device-sysupgrade.binPassing sysupgrade -T does not prove complete configuration compatibility. Read device-specific release notes, target migration instructions, and sysupgrade warnings. When the test fails, do not bypass it with a force option; recheck the image and board.
Decide whether Keep settings is appropriate
- A normal update within a stable release line without a migration warning: Keep settings can be considered after reviewing the preservation list and backup.
- Architecture, target, partition, or switch configuration changes: follow the clean-install or migration procedure in the release documentation. Do not automatically restore the previous network configuration.
- Several major releases are skipped: check intermediate requirements and package-format changes. Do not assume every stored config remains compatible through one flash.
- Many custom packages are installed: the backup does not preserve package binaries. Verify their presence in the new feed and compatibility with the new kernel ABI.
- The router is remote and local recovery is unavailable: do not attempt a risky migration without physical, serial, or failsafe recovery.
Post-upgrade verification order
After reboot, verify firmware version, LAN access, WAN, DNS, firewall, and critical services in that order. Confirm the base network before reinstalling every package. If an interface name changed, compare against the new defaults and migrate only required settings.
Before restoring a backup, recheck compatibility with the new configuration format. Selective restoration can be safer than overwriting the entire archive during a structural migration.
Limits of rollback evidence
A configuration backup is not the previous firmware image. A rollback plan also needs the prior device-specific image, checksum, package list, and recovery access method. When a partition layout changed, a simple downgrade can be more dangerous, so follow the device documentation.
Record the image checksum, Keep settings decision, restored files, reinstalled packages, and verification outcome. That operational record prevents the same uncertainty at the next upgrade and is more useful than an unexplained archive alone.
Related guides
Official references
- OpenWrt release notes – supported upgrade ranges, device migrations, and known issues by release
- OpenWrt sysupgrade script – the actual handling of backups, image tests, and CLI options
- OpenWrt sysupgrade.conf – the official file for extending the preservation list
- OpenWrt common upgrade logic – the implementation of backup archives and platform upgrade stages
Earlier verification notes preserved from this article
Verification level: official documentation checked
Sysupgrade backup, image, and package boundaries were checked against OpenWrt documentation. No specific router migration was reproduced, so this guide does not replace device release notes.