Sysupgrade vs factory image upgrade

Installing and Using OpenWrt
#1

I have been using OpenWRT for many years, but I use it in a specific way. I always build custom image and put all relevant config files into the image, so when I flash the image, I do not have to do anything else and it runs right from the bat exactly in the state I want it.

So far I have been using this approach on TL-WR1043ND (v1 and v2) and I always used factory image for the upgrade, because I believed that sysupgrade might leave some leftovers from the previous version behind.

Recently however I have tried to upgrade Archer C7 (v5) several times with factory upgrade and bricked the device (boot failed with "Bad magic number") and I had to rescue the device with TFTP boot. For some reason, booting the same image via TFTP worked.

I was surprised and tried to find out what is the correct way to upgrade the system, and most importantly, what is really the difference between sysupgrade and factory images. To my surprise I only found some recommendations and sometimes even contradicting, like never use factory on the system which already runs OpenWRT (I did it for past 10 years), or use sysupgrade when you want to preserve the config (which I did not).

I wonder, is there a wiki or a technical reference, which clarifies the topic? And why it behaves differently on two different devices?

#2

You use

  • "sysupgrade" image if you flash from a live OpenWrt system. Either sysupgrade from LuCI or using SSH console.
  • "factory" image if you flash by using the original OEM firmware, the possibly built-in TFTP recovery interface (in some routers), or some other recovery tool from the original manufacturer.

For most routers the factory image contains a header that makes it compatible (recognizable) with the OEM flashing routine: like "Factory = header + sysupgrade image + possibly padding". But flashing that factory image via sysupgrade would brick the router.

For most routers the functionality of the factory and sysupgrade images is identical. In both cases no files are usually preserved in flashing, but instead after a flashing you will have a new firmware image (as /rom) and a new empty "overlay" file system (as /overlay) for read/write material. If you saved settings, they get written to that overlay at the end of the sysupgrade process. In a live router you then see them seamlessy combined as root dir "/".

Some rare cases, usually the oldest router models, may have simple image structures and the factory image might have no special header, so it could work also with the OpenWrt sysupgrade process. Also some other routers e.g. those with only SD memory cards (without any proper flash) may have different procedures.

The is much variation between routers, as bootloaders vary and also the filesystems have evolved during the years.

There is no definitive wiki guide, but some links:

https://openwrt.org/docs/guide-user/installation/generic.sysupgrade#downloading_the_openwrt_upgrade_image

https://openwrt.org/docs/guide-quick-start/sysupgrade.luci#verify_firmware_file_and_flash_the_firmware

And the device specific page for your router naturally also clearly points out to using the sysupgrade image in sysupgrade:
https://openwrt.org/toh/tp-link/archer-c7-1750#installation

OpenWrt Factory Firmware: Use this file the first time you flash OpenWrt onto the router as it came from the “factory.”
OpenWrt Sysupgrade Firmware: Use this file to upgrade an OpenWrt “system” to a newer OpenWrt version.

(of course, similarly also for you old router: https://openwrt.org/toh/hwdata/tp-link/tp-link_tl-wr1043nd_v2 )

4 Likes
What is the Difference between the install and upgrade urls?
#3

Thanks for the detailed reply.

I would just add that I always used

mtd -r write <image> firmware

to flash the new images onto devices. It was working on the old TL-WR1043ND v2 with factory image, so I was surprised it does not work anymore on Archer C7 (v5).

I understand now that the difference between the images is some kind of additional header (for factory image) and that this header "bricks" Archer C7 (when flashed directly to the memory), but I still do not understand, why exactly same thing works for the older router. The devices seems to be not that different...

#4

Just that devices are different, especially TP-Link has played around with different partitioning schemes a lot recently. Low-level tools like mtd require a close knowledge how the systems are set up - on some devices that can be done (as hnyman mentioned, particularly the older devices were simple enough to accept this), on others it could be fatal.

1 Like
#5

You assume that the new router would have the exactly same bootloader as your old one...

Well, that actually means that you have never sysupgraded from OpenWrt perspective, but instead you have used a brute-force to write the image. You have completely bypassed the actual sysupgrade logic.

#6

No, I would assume that image built for the particular target (either TL-WR1043ND, or Archer C7 ) would accommodate the platform bootloader the same way. That would be the one of the reasons to have different targets when building the image.

I never intended "to bypass" anything, nor "brute force it". I simply used this approach because it worked for the past 10 years (when I started building my images) for every router I had (old ASUS then TL-WR1043ND v1 and v2).

#7

"target" is more like a processor family, like Atheros ar71xx or ath79.
Inside that there is a large variation of devices, which each have specific rules.

Foir example, here are the recipe collections for only TP-Link devices in ar71xx:

#8

You are right, when I wrote "target" I meant what is passed as "PROFILE" to the make and which identifies individual devices down to the hardware revision. Target is indeed "ath79" or "ar71xx" and is something different.