EdgeRouter X: unattended upgrade from 2023.2 to 2025.1 via auto-updater, without(!) config loss

For EdgeRouter X and X-SFP on the 6 MB kernel layout for Gluon 2025.1.x: the package neanderfunk-erx-migrate (AGPL-3.0, feed branch v2023.2.x).
Here are the key points, everything else is in the README.

Starting Point

  • Kernel 6.6 from OpenWrt 24.10: 3,173,564 bytes. The two old slots have 3 MB each, so 27 KB are missing. In the current 26101610sta it is 3,175,938 bytes (ERX) and 3,176,094 bytes (SFP), about 30 KB over the slot.
  • The release notes for Gluon v2025.1 list manual steps and refer to darkxst/erx-migration. Following them, the config is lost.
  • compat_version 1.x -> 2.0 only fails in sysupgrade --test, i.e. after download and signature check. --ignore-minor-compat-version does not help, because the major branch of fwtool_check_image() does not evaluate the flag.
  • Consequence with two mirrors and 24 cron runs: roughly 345 MB of useless traffic per day per node.

Procedure

  • Stage 1: 2023.2 intermediate image with the package, delivered via the normal autoupdater (compat 1.x -> 1.x)
  • Trigger: only micron.d, hourly at minute 37, after one hour of uptime, the whole run under /var/lock/autoupdater.lock
  • Target: not included in the image. erx-migrate-run reads branch, mirrors, keys and good_signatures from uci, fetches the manifest, verifies it with ecdsaverify, and takes file name, size and SHA256 from the line of the target model. The threshold is capped at 2 (ZIEL_SIGNATUREN).
  • Download: the package handles this itself, because the autoupdater’s --no-action only takes effect after sysupgrade --test
  • Stage 2 in RAM root: write the kernel to kernel1 and kernel2, compare via readback, and only then set the boot index to 0, rebuild the UBI volumes, and restore the config. Order and writes come from darkxst/erx-migration.
  • Release coupling: every new release in the branch becomes the target without any further step. As long as unmigrated ERX devices are in the field, a migration belongs before every release.

Config

  • sysupgrade -b to /tmp before teardown, nand_restore_config after the UBI volumes are rebuilt. The preinit finds the archive just as it does for a normal sysupgrade.
  • compat_version in the archive is raised to the value from the image (fwtool -q -i). Otherwise the node would be back at 1.1 after the restore and would later accept images for the old layout.

Image Name -ka

  • From 2025.1 the images are called ubiquiti-edgerouter-x-ka and ubiquiti-edgerouter-x-sfp-ka
  • An unmigrated node cannot find its manifest line this way, so the autoupdater aborts at model_ok, before the download
  • Under the old name, the same manifest can contain the intermediate image
  • compatible stays the same; fwtool_check_image() and sysupgrade notice none of this
  • Visible: the model is then called Ubiquiti EdgeRouter X KA. An ERX without -ka in image_name is an unmigrated node on the map.
  • Patch: devices/erx-ka-imagename.sh, which also explains how the name is removed again

Error Behavior

  • Deferred (log AUFSCHUB): no uplink, too few signatures, mirror not yet up to date, image missing or corrupt. Retry after one hour.
  • Aborted (log ABBRUCH): pre-check failed, migration not carried out. Marker in /tmp, no retry until the next boot.
  • No flash write as long as the migration does not actually start. Log and image are in /tmp; there is no state across reboots.
  • If stage 2 does not start, erx-migrate.sh rolls back after five minutes and restarts micrond; the node continues running normally
  • Log: http://[<knoten>]/cgi-bin/erx-migrate-log, open like the status page, RAM only

Status as of 01.11.2026

  • Test node: two runs on 31.10., intermediate image via autoupdater, target from the real stable manifest, node offline for about two minutes. In the first run, hostname, contact, location, SSH keys, port roles and addresses were preserved. In the second, the start at minute 37 also ran without manual intervention.
  • Field: 14 ERX and 4 ERX SFP in 11 domains. Intermediate image and start done here by hand, without the uptime limit. Boot index beforehand: seven times 1 and eleven times 0. All 18 got through the first handover.

Limits

  • The starting state was always 26091920sta (2023.2.6). From Gluon 2022.1, the intermediate image (compat_version 1.1) should pass with --ignore-minor-compat-version, untested on the ERX. Up to 2021.1 (OpenWrt 19.07) probably not, also untested.
  • The download runs via uclient-fetch without gluon-wan, as with the autoupdater. For at least seven of the 18 field nodes, the gateway route went via br-mesh_other. All our ERX devices have their own VPN link, but an ERX without any such link has not been tested.
  • There is no remote way back after the kernel write. A new kernel on the old rootfs would mean: no modules and no network. erx-migrate-run then sees kernel in /proc/mtd and ends, and there is no automatic retry. Rescue is then only possible via the serial console. On the test device, one address set by hand was enough each time, after which the run could continue; erx-migrate.sh knows both layouts.
  • Bad blocks: mtd write skips them (so it should be safe), but the marking cannot be queried in the image. The readback catches the consequence. After the second failed attempt, stage 2 aborts; according to the code, the device then no longer starts and needs the console. A wrong readback has never occurred on a device so far.
  • Reboot paths: the script stops micrond and our own watchdogs. Other packages that reboot when sysupgrade sends TERM and KILL during teardown must be checked separately.

Integration

  • Dependencies: gluon-core, micrond, ecdsautils
  • ziel.conf: names the target models; without an entry, the package does nothing
  • Package: neanderfunk-erx-migrate

2 Likes