UCI config migration across OpenWrt releases

[Eric]

On Saturday, April 18th, 2026 at 00:32, Thibaut <hacks at slashdirt.org> wrote:
> > Le 17 avr. 2026 à 17:05, Eric via openwrt-devel <openwrt-devel at lists.openwrt.org> a écrit :
> >
> > Every image has all of its /etc/uci-defaults/* files in place, so whenever
> > you run 'sysupgrade ...' to install an image, you get the new set of uci
> > default scripts (this is how upgrades actually "upgrade" the defaults).
> >
> > Your step 2 above has all of the uci-defaults scripts ready to run, which
> > happens on reboot, and then the "preserve config" restore happens after
> > that and overwrites some of the files that were just created (for example,
> > the default wireless config is created from defaults and then overwritten
> > by the restore).
> 
> In fact it’s the other way around. Configs are restored very early on after the kernel is loaded (in preinit stage) - and thus before the shipped uci-defaults are run - which is exactly why user configs can be migrated as needed.

Gah, yeah, I got that part backwards, thanks (I can't blame lack
of coffee, as it was 1700 when I wrote it... Or maybe I can?
Is lack of beer a thing?)

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).