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
26101610stait 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.0only fails insysupgrade --test, i.e. after download and signature check.--ignore-minor-compat-versiondoes not help, because the major branch offwtool_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-runreads branch, mirrors, keys andgood_signaturesfrom uci, fetches the manifest, verifies it withecdsaverify, 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-actiononly takes effect aftersysupgrade --test - Stage 2 in RAM root: write the kernel to
kernel1andkernel2, 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 -bto/tmpbefore teardown,nand_restore_configafter the UBI volumes are rebuilt. The preinit finds the archive just as it does for a normal sysupgrade.compat_versionin the archive is raised to the value from the image (fwtool -q -i). Otherwise the node would be back at1.1after the restore and would later accept images for the old layout.
Image Name -ka
- From 2025.1 the images are called
ubiquiti-edgerouter-x-kaandubiquiti-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
compatiblestays the same;fwtool_check_image()and sysupgrade notice none of this- Visible: the model is then called
Ubiquiti EdgeRouter X KA. An ERX without-kainimage_nameis 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.shrolls 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_version1.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-fetchwithoutgluon-wan, as with the autoupdater. For at least seven of the 18 field nodes, the gateway route went viabr-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-runthen seeskernelin/proc/mtdand 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.shknows both layouts. - Bad blocks:
mtd writeskips 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
microndand 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
