Common Procedures for Ubiquiti Products
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.
What board do I have?
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:
- airMAX M (AirOS 5 and 6):
- XM
- XW
- TI
- airMAX AC (AirOS 7 and 8):
- WA
- 2WA
- XC
- 2XC
- airMAX Legacy (original airMAX):
- XS2
- XS5
- UniFi:
- BZ.<SoC> (SoC = e.g.: ipq806x, qca956x)
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.
OpenWrt versions to avoid
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.
OpenWrt installation on Ubiquiti AirMAX AC Devices (WA and/or XC boards)
The following method has been tested with these versions of AirOS.
- WA v8.7.4
WA.v8.7.4.45112
- XC v8.7.4
XC.v8.7.4.45112
- WA V8.7.0
WA.v8.7.0.42152
- XC v8.7.0
XC.v8.7.0.42152
- WA v8.5.7
WA.v8.5.7.38314
The 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.
WA v8.5.4+ (not recommended,use this method if everything above fails.)
Source: https://github.com/openwrt/openwrt/pull/689#issuecomment-493658317
this method was tested with versions:
- 8.5.4
- WA v8.5.7
WA.v8.5.7.38314 - WA v8.7.4
WA.v8.7.4.45112 - XC v8.7.4
XC.v8.7.4.45112
Needed:
- SSH access
- Original AirOS firmware file
- OpenWRT sysupgrade image (Not factory image)
- dd command
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.
Unlock the flash partitions
- To unlock the partitions, you need to download WA.v8.5.4.37936.180524.1215.bin and first flash it via webinterface. For this example, we will use version AirOS 8.5.4, but any of the mentioned tested versions will work.
- log into the webif and set your password. SSH is not working otherwise.
- scp the firmware file onto the target:
scp WA.v8.5.4.37936.180524.1215.bin ubnt@192.168.1.20:/tmp - scp the OpenWrt sysupgrade image onto the target:
scp ubnt_nanostation-ac-squashfs-sysupgrade.bin ubnt@192.168.1.20:/tmp - ssh into the target:
ssh ubnt@192.168.1.20 - double check the partition table:
cat /proc/mtd- size of mtd2:kernel should be
0x00100000 - size of mtd3:rootfs should be
0x00e60000
cd /tmpfwupdate.real -m /tmp/WA.v8.5.4.37936.180524.1215.bin -dand abort the command after a few seconds (when it is on block /dev/mtd3) by pressing Ctrl+C.- convert hexadecimal
0x00100000to decimal:1048576, divided byblocksize 4096=256 - copy only the first
0x00100000bytes into the kernel partition:dd if=/tmp/ubnt_nanostation-ac-squashfs-sysupgrade.bin of=/dev/mtdblock2 bs=4096 count=256 - copy the rest of the image into the rootfs partition:
dd if=/tmp/ubnt_nanostation-ac-squashfs-sysupgrade.bin of=/dev/mtdblock3 bs=4096 skip=256 - reboot!
Partition Table
WA.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"
CLI recording
Troubleshooting
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.
One more thing:
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.
OpenWrt installation on XM boards
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:
- Perform a factory reset
- Flash AirOS v5.6.15-sign (from [https://dl.ubnt.com/firmwares/XN-fw/v5.6.15/XM.v5.6.15-sign.31612.170908.1458.bin|Ubiquiti's web site]) via web GUI or TFTP recovery
- Flash AirOS v5.6.15-unsigned (from [https://dl.ubnt.com/firmwares/XN-fw/v5.6.15/XM.v5.6.15.30572.170328.1107.bin|Ubiquiti's web site]) via TFTP recovery
- Downgrade to AirOS v5.5.x (latest known v5.5 version is v5.5.11, available for download at several places) via web GUI or TFTP recovery: this step will modify overwrite the device's bootloader, U-Boot, with the old mtd layour
Once AirOS v5.5.x is running, install OpenWrt by flashing a factory image via web GUI, CLI or TFTP.
OpenWrt installation on XW boards
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 v6.1.7
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.
OpenWrt installation on BZ boards
BZ.v3.7.58+
With this version, we can just downgrade and then use the standard mtd util to flash OpenWrt directly.
We will need:
- SSH
- OpenWrt sysupgrade image for our device
- Ubnt Firmware version BZ.v3.7.58: https://dl.ui.com/unifi/firmware/U7PG2/3.7.58.6385/BZ.qca956x.v3.7.58.6385.170508.0957.bin there are lots of different versions depending on the SoC, download the one suitable for your device.
how to flash
- downgrade first:
- copy firmware to the device, e.g.:
scp BZ.qca956x.v3.7.58.6385.170508.0957.bin ubnt@192.168.1.20:/tmp - log into the device with SSH:
ssh ubnt@192.168.1.20with passwordubnt - to downgrade:
fwupdate.real -m /tmp/BZ.qca956x.v3.7.58.6385.170508.0957.bin
- flash OpenWrt:
- copy firmware to the device, e.g.:
scp openwrt-ath79-generic-ubnt_unifiac-pro-squashfs-sysupgrade.bin ubnt@192.168.1.20:/tmp - log into the device with SSH:
ssh ubnt@192.168.1.20with passwordubnt - flash openwrt to partition kernel0:
mtd write /tmp/openwrt-ath79-generic-ubnt_unifiac-pro-squashfs-sysupgrade.bin kernel0 - erase partition kernel1:
mtd erase kernel1 - write a single 0-byte in bs:
dd if=/dev/zero of=/dev/mtd4 bs=1 count=1 - reboot
Partition Table
UBNT-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"