OpenWrt sysupgrade support

sysupgrade is an OpenWrt invention that allows the rootfs to be updated to another firmware.

In general the sysupgrade process will:

1. create a backup of relavent configuration files (ie UCI config and anything else in /etc/config) as a sysupgrade.tgz file
2. upgrade the rootfs
3. store the sysupgrade.tgz file in sysupgrade.tgz in the rootfs so that do_mount_root boot hook will find it and restore it on the next boot
   • In the event a squashfs+overlay filesystem is used the sysupgrade.tgz must be stored in a temporary location (because the squashfs rootfs is a read-only filesystem). This is done via the platform_copy_config() function in /lib/upgrade/platform.sh where a boot hook is used to then copy that file to the rootfs on the next boot

In a nutshell this is provided by:

• /sbin/sysupgrade script from the base-files package
• /lib/upgrade/platform.sh - target specific script providing functions to check the image integrity, perform the upgrade, and copy the backup file to flash following the upgrade
• /lib/preinit/79_move_config - identifies and moves the backup file from the flash so that it gets installed on first boot following the upgrade

The sysupgrade script has some useful commandline arguments:

• -v will show verbose info
• -c will save all files on the overlay filesystem
• -n will upgrade without saving configuration

For Gateworks Venice, Newport, and Ventana the file used for sysupgrade is the same used for an initial installation:

• venice: use the compressed disk image: openwrt-23.03-imx8mm.img.gz
• newport: use the compressed disk image: openwrt-20.06-newport.img.gz
• ventana: use the ubi image: bin/imx6/*-squashfs-nand_*.ubi

When performing a sysupgrade with a large amount of backup data (ie using the -c argument with a lot of filesystem changes) it is important to ensure you have enough space to store the sysupgrade.tgz backup file. The backup file is stored in a target and boot device specific location:

• venice/emmc: on the 'boot' partition (P1) containing the kernel+dtb+script
• newport/emmc: on the 'boot' partition (P2) containing the kernel+dtb+script (Note that P1 on Newport is used by boot firmware)
• ventana/emmc: on the 'boot' partition (P1) containing the kernel+dtb+script
• ventana/NAND: directly on the 'rootfs_data' ubifs volume

You can find more information about sysupgrade on the OpenWrt wiki ​here

Sysupgrade via command line

Examples:

• Upgrade a 256MB flash device:

  cd /tmp
  wget http://192.168.1.175/openwrt/imx6/gateworks-imx6-ventana-squashfs-nand_normal.ubi
  sysupgrade -v gateworks-imx6-ventana-squashfs-nand_normal.ubi
  

• from a URL:

  sysupgrade -v http://192.168.1.175/openwrt/imx6/gateworks-imx6-ventana-squashfs-nand_normal.ubi
  

Using LuCI Web-Admin

To perform a sysupgrade using the OpenWrt WebGUI, please use an ubi file, such as ​ventana-owrt-20.06-normal.ubi

Go to the top System tab, then the lower tab should be selected as Backup / Flash Firmware.

Under 'Flash new firmware image' please select the ubi from the location on the desktop PC.

In the background, this is what is happening on the serial console

Switching to ramdisk...
[  447.449487] UBIFS: background thread "ubifs_bgt0_0" stops
[  447.519016] UBIFS: un-mount UBI device 0, volume 0
[  447.585743] UBI: detaching mtd2 from ubi0
[  447.591108] UBI: mtd2 is detached from ubi0
ubiformat: mtd2 (nand), size 250609664 bytes (239.0 MiB), 1912 eraseblocks of 131072 bytes (128.0 KiB), min. I/O size 2048 bytes
libscan: scanning eraseblock 1911 -- 100 % complete
ubiformat: 1912 eraseblocks have valid erase counter, mean value is 1
ubiformat: flashing eraseblock 154 -- 100 % complete
ubiformat: formatting eraseblo[  467.802383] UBI: attaching mtd2 to ubi0
ubiformat: formatting eraseblock 1911 -- 100 % complete
[  468.505882] UBI: scanning is finished
[  468.525333] UBI: volume 0 ("rootfs") re-sized from 153 to 1868 LEBs
[  468.532619] UBI: attached mtd2 (name "rootfs", size 239 MiB) to ubi0
[  468.539101] UBI: PEB size: 131072 bytes (128 KiB), LEB size: 126976 bytes
[  468.545937] UBI: min./max. I/O unit sizes: 2048/2048, sub-page size 2048
[  468.552783] UBI: VID header offset: 2048 (aligned 2048), data offset: 4096
[  468.559702] UBI: good PEBs: 1912, bad PEBs: 0, corrupted PEBs: 0
[  468.565719] UBI: user volume: 1, internal volumes: 1, max. volumes count: 128
[  468.572885] UBI: max/mean erase counter: 4/2, WL threshold: 4096, image sequence number: 250308913
[  468.581878] UBI: available PEBs: 0, total reserved PEBs: 1912, PEBs reserved for bad PEB handling: 40
[  468.591156] UBI: background thread "ubi_bgt0d" started, PID 4603
UBI device number 0, total 1912 LEBs (242778112 bytes, 231.5 MiB), available 0 LEBs (0 bytes), LEB size 126976 bytes (124.0 KiB)
[  468.666681] UBIFS: background thread "ubifs_bgt0_0" started, PID 4621
[  468.686194] UBIFS: start fixing up free space
[  469.759179] UBIFS: free space fixup complete
[  469.782548] UBIFS: mounted UBI device 0, volume 0, name "rootfs"
[  469.788572] UBIFS: LEB size: 126976 bytes (124 KiB), min./max. I/O unit sizes: 2048 bytes/2048 bytes
[  469.797786] UBIFS: FS size: 235794432 bytes (224 MiB, 1857 LEBs), journal size 9023488 bytes (8 MiB, 72 LEBs)
[  469.807805] UBIFS: reserved for root: 0 bytes (0 KiB)
[  469.812924] UBIFS: media format: w4/r0 (latest is w4/r0), UUID 58020D53-74F0-4A4C-83AA-B2FB6B08508F, small LPT model
[  469.877200] UBIFS: un-mount UBI device 0, volume 0
[  469.882090] UBIFS: background thread "ubifs_bgt0_0" stops
sysupgrade successful
[  469.904545] imx2-wdt 20bc000.wdog: Device shutdown: Expect reboot!
[  469.910875] reboot: Restarting system

Customizing Sysupgrade

There is a specified set of files that get backed up and restored to the newly upgraded image along with all of UCI. This is configured in /etc/sysupgrade.conf. If you want your init changes to persist across a sysupgrade be sure to configure things properly. You may want to create an OpenWrt package and use UCI configuration to help do that for you.