This page describes common procedures across Ubiquiti routers. If you edit / add information about a specific model, please consider linking to this page to avoid repeating common instructions.
Ubiquiti doesn't make a firmware per board, but instead uses one image for a whole series of boards. Most of the time, these series have a two(/three) letter acronym in order to differentiate them.
At the time of writing, there are these acronyms, sorted by product series:
You find your firmware version in the web interface in Settings→System. If your firmware version is e.g. WA.V8.5.4, you have a WA board.
There's a bug in the first releases of OpenWRT 23.05 that causes the flash to be read-only for many Ubiquiti devices. This was fixed in release 23.05.3. Discussed here and here, fixed here.
There's a distinct bug in the first releases of OpenWRT 24.10 that causes mostly the same symptoms on mostly the same devices. This was fixed in release 24.10.3. Discussed here, fixed in Linux 6.6.103.
If you're unlucky enough to have flashed one of the buggy versions, the recovery procedure is here.
The following method has been tested with these versions of AirOS.
WA.v8.7.4.45112XC.v8.7.4.45112WA.v8.7.0.42152XC.v8.7.0.42152WA.v8.5.7.38314The firmware for these Ubiquiti devices is signed. Since there are no mtd utilities available on the stock firmware the original fwupdate.real binary must be used. Please make sure make sure to have one of the previous versions installed, depending on your device. MAYBE, the instructions won't work for other versions.
For flashing OpenWrt you need to use a firmware which has this patch integrated. This is the case for the latest snapshot version.
This is not working anymore with latest snapshot version (tested 2024-01-20). Old snapshot builds from 2024-02 are still working. Images for Nanostations can be found here. For other devices you need to compile it for yourself.
To install unsigned firmware the fwupdate.real binary (which is in fact just a symlink to ubntbox) must be patched:
hexdump -Cv /bin/ubntbox | sed 's/14 40 fe 27/00 00 00 00/g' | hexdump -R > /tmp/fwupdate.real chmod +x /tmp/fwupdate.real
After that, the OpenWrt factory image can be installed using the patched binary:
/tmp/fwupdate.real -m /tmp/openwrt-ath79-generic-ubnt_DEVICE_MODEL-squashfs-factory.bin
Warning:
Some devices are experiencing a bug in OpenWRT version 23 and later. On those devices, the configuration is lost every time the device is restarted. For now, version 22.03.x of OpenWRT is the most current version that does NOT have problems saving the configuration made after rebooting. Do not upgrade to OpenWRT 23 or higher until the bug that prevents saving the configuration after a reboot is resolved. If you upgrade to a higher version, you will NOT be able to return to version 22 by flashing the sysupgrade image. You will notice that if you do, you cannot downgrade from the recent version you have flashed, and changes in the configuration will no longer persist after rebooting. The only way (for now) to go back to version 22 is by reinstalling the original AirOS and repeating the whole process again.
Source: https://github.com/openwrt/openwrt/pull/689#issuecomment-493658317
this method was tested with versions:
WA.v8.5.7.38314WA.v8.7.4.45112XC.v8.7.4.45112Needed:
With this firmware version, we will be using the original update utility to unlock the flash and we write OpenWrt directly to /dev/mtdblock[x] with dd.
scp WA.v8.5.4.37936.180524.1215.bin ubnt@192.168.1.20:/tmpscp ubnt_nanostation-ac-squashfs-sysupgrade.bin ubnt@192.168.1.20:/tmpssh ubnt@192.168.1.20cat /proc/mtd0x001000000x00e60000cd /tmpfwupdate.real -m /tmp/WA.v8.5.4.37936.180524.1215.bin -d and abort the command after a few seconds (when it is on block /dev/mtd3) by pressing Ctrl+C.0x00100000 to decimal: 1048576, divided by blocksize 4096 = 2560x00100000 bytes into the kernel partition: dd if=/tmp/ubnt_nanostation-ac-squashfs-sysupgrade.bin of=/dev/mtdblock2 bs=4096 count=256dd if=/tmp/ubnt_nanostation-ac-squashfs-sysupgrade.bin of=/dev/mtdblock3 bs=4096 skip=256WA.v8.5.4# cat /proc/mtd dev: size erasesize name mtd0: 00040000 00010000 "u-boot" mtd1: 00010000 00010000 "u-boot-env" mtd2: 00100000 00010000 "kernel" mtd3: 00e60000 00010000 "rootfs" mtd4: 00040000 00010000 "cfg" mtd5: 00010000 00010000 "EEPROM"
It may happen that following this, OpenWRT will work, but fail to keep settings across reboots. Reflashing once more the squashfs-sysupgrade.bin file through OpenWRT's web interface did fix this in one case where less radical options (like the firstboot command of confirming that the overlayfs is correctly mounted) did not. YMMV.
For now, version 22.03.x of OpenWRT is the most current version that does NOT have problems saving the configuration made after rebooting. Do not upgrade to OpenWRT 23 or higher until the bug that prevents saving the configuration after a reboot is resolved. If you upgrade to a higher version, you will NOT be able to return to version 22 by flashing the sysupgrade image. You will notice that if you do, you cannot downgrade from the recent version you have flashed, and changes in the configuration will no longer persist after rebooting. The only way (for now) to go back to version 22 is by reinstalling the original AirOS and repeating the whole process again.
Do not attempt to install OpenWrt on an XM device running AirOS 5.6 or newer!
The mtd partitions layout for XM-type devices changed from AirOS v5.5 to AirOS v5.6. Before installing OpenWrt, downgrade first to AirOS 5.5.
Steps for downgrading to AirOS 5.5:
Once AirOS v5.5.x is running, install OpenWrt by flashing a factory image via web GUI, CLI or TFTP.
Ubiquiti devices with XW boards do not have the limitation that those based on XM have when installing OpenWRT and when downgrading. What is required is to have a firmware version of AirOS 6.0.4 or lower. As of version 6.0.6, Ubiquiti only supports digitally signed firmwares. If you already have a version higher than 6.0.6 installed, you can do the following to downgrade successfully:
1 - Install version 6.0.6beta:
https://www.ubnt.com/downloads/XN-fw-internal/v6.0.6/XM.v6.0.6-beta.30875.170526.0038.bin
https://www.ubnt.com/downloads/XN-fw-internal/v6.0.6/TI.v6.0.6-beta.30875.170526.0008.bin
https://www.ubnt.com/downloads/XN-fw-internal/v6.0.6/XW.v6.0.6-beta.30875.170526.0023.bin
2 - Install 6.0.4:
https://www.ubnt.com/downloads/XN-fw-internal/v6.0.4/XM.v6.0.4-cs.30805.170505.1525.bin
https://www.ubnt.com/downloads/XN-fw-internal/v6.0.4/XW.v6.0.4-cs.30805.170505.1510.bin
https://www.ubnt.com/downloads/XN-fw-internal/v6.0.4/TI.v6.0.4-cs.30805.170505.1456.bin
In version 6.0.4 you can now install OpenWRT directly by loading the firmware through the GUI. You do not need to downgrade to lower versions.
XW-type devices with newer hardware revisions required the firmware to be RSA-signed to allow flashing. Since there are no mtd utilities available on the stock firmware the original fwupdate.real binary must be used.
Please make sure you have got firmware version XW.v6.1.7.32555 installed (upgrade or downgrade if necessary).
Once there, head to https://github.com/true-systems/ubnt-openwrt-flashing and follow the instructions on the README.md document.
You can also find relevant information on the OpenWrt Forum.
With this version, we can just downgrade and then use the standard mtd util to flash OpenWrt directly.
We will need:
scp BZ.qca956x.v3.7.58.6385.170508.0957.bin ubnt@192.168.1.20:/tmp ssh ubnt@192.168.1.20 with password ubntfwupdate.real -m /tmp/BZ.qca956x.v3.7.58.6385.170508.0957.bin scp openwrt-ath79-generic-ubnt_unifiac-pro-squashfs-sysupgrade.bin ubnt@192.168.1.20:/tmp ssh ubnt@192.168.1.20 with password ubnt mtd write /tmp/openwrt-ath79-generic-ubnt_unifiac-pro-squashfs-sysupgrade.bin kernel0 mtd erase kernel1dd if=/dev/zero of=/dev/mtd4 bs=1 count=1UBNT-BZ.v3.9.43# cat /proc/mtd dev: size erasesize name mtd0: 00060000 00010000 "u-boot" mtd1: 00010000 00010000 "u-boot-env" mtd2: 00790000 00010000 "kernel0" mtd3: 00790000 00010000 "kernel1" mtd4: 00020000 00010000 "bs" mtd5: 00040000 00010000 "cfg" mtd6: 00010000 00010000 "EEPROM"