UCI config migration across OpenWrt releases

[Eric]

On Monday, April 13th, 2026 at 11:43, Jonas Lochmann <openwrt at jonaslochmann.de> wrote:
> Am Mon, Apr 13, 2026 at 03:35:32PM +0200, schrieb Tanjeff Moos via openwrt-devel:
> > * For minor updates (e.g. 24.10.5 → 24.10.6), configurations can usually
> >   be kept.
> 
> I agree with this.
> 
> > * For major updates (e.g. 24.10.x → 25.12.1), recreating the
> >   configuration is recommended.
> 
> I only once recreated the configuration and this was when the device
> was migrated from one switch configuration system to another. I could
> have avoided even that by attaching a serial console and editing the
> configuration using that after the update (or perfectly creating a
> suitable new configuration before updating without applying it).
> 
> > However, many of those discussions are quite old, so I am wondering whether
> > this guidance is still accurate today.
> 
> I think this depends on the target group. For very simple users that do
> not read changelogs or release announcements, I would still recommend
> that. Otherwise, I see no reason to not keep the configuration.

For the most part, crossing one version works just fine.  Most
packages these days use a uci-defaults script to upgrade their
config if there are any changes, although of course you'll no
doubt find exceptions somewhere.

If you attempt to jump more than one version, though, you'll
probably (almost certainly) have some issues and if you're
unwilling to do, for example, four distinct upgrades for 
22 -> 23 -> 24 -> 25, then you're better off just wiping it 
down and using your old config "on paper" as notes to rebuild.

Big breaking changes (swconfig -> DSA) are almost always walled
off in sysupgrade with the 'compat_version' setting, so when you
attempt to keep config, sysupgrade simply refuses and you get
a message that gives you some search terms to help figure out
what's going on (but best is to seek help on the forum).

My recommendation at present is that unless sysupgrade refuses
to keep config, it's good to go for a single major version bump.

Eric