UCI config migration across OpenWrt releases

[Rich Brown]

What a fabulous description. Thanks

Is this written down in the Wiki anywhere? Given the work Eric put into it, we should capture it permanently

Rich

> On Apr 18, 2026, at 10:24, Eric via openwrt-devel <openwrt-devel at lists.openwrt.org> wrote:
> 
> In any case, sysupgrade does:
> 
> 1) Create backup and stash it.
> 2) Copy/dd in new image with complete default uci-defaults.
> 3) Reboot.
> 4) Restore backup.
> 5) Each /etc/uci-defaults/* is run.  Often it starts off with 
>   '[ -e /etc/config/whatever ] && continue' or some such thing
>   to bail out if there's already a user config.
> 6) If a config change (i.e., migration is needed), do it now.
> 7) If script completes without error, delete it; scripts with
>   an error exit are retained and re-run at each reboot.
> 
> And installing or upgrading a package:
> 
> 1) Installs package contents, updates package manager database etc.
> 2) The package may contain a uci-defaults script, which is installed
>   in the usual place (that's how it got there during image build).
> 3) By default, the package also contains a "post-install" script,
>   called 'postinst' script defined in include/package-pack.mk.
> 4) The package manager fires off the post install script, which
>   then loads '/lib/function.sh' and runs the 'default_postinst'
>   function mentioned previously.
> 5) This executes any uci-defaults, just like steps 5-7 above,
>   effecting any needed migration, upgrades or whatever.
>   script associated with the package).
>