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 installation on WA and XC boards
WA v8.7.4 / XC v8.7.4
Please make sure you have got firmware version WA.v8.7.4.45112
or XC.v8.7.4.45112
, depending on your device.
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.
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
WA v8.7.0 / XC v8.7.0
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 you have got firmware version WA.v8.7.0.42152
or XC.v8.7.0.42152
, depending on your device.
The instructions won't work for other versions.
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
WA v8.5.7
Please make sure you have got firmware version WA.v8.5.7.38314
installed https://dl.ubnt.com/firmwares/XC-fw/v8.5.7/WA.v8.5.7.38314.180628.1036.bin.
The instructions won't work for other versions.
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 fd/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
WA v8.5.4+ (not recommended)
Source: https://github.com/openwrt/openwrt/pull/689#issuecomment-493658317
this method was tested with versions:
- 8.5.4
- 8.5.7
Needed:
- SSH
- Original firmware file
- dd
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.
- 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 /tmp
fwupdate.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).- convert hexadecimal
0x00100000
to decimal:1048576
, divided byblocksize 4096
=256
- copy only the first
0x00100000
bytes 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.
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.20
with 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.20
with 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"