Show pagesourceOld revisionsBacklinksBack to top × Table of Contents Common Procedures for Ubiquiti Products What board do I have? OpenWrt installation on WA and XC boards WA v8.7.0 / XC v8.7.0 WA v8.5.7 WA v8.5.4+ (not recommended) OpenWrt installation on XM boards OpenWrt installation on XW boards XW v6.1.7 OpenWrt installation on BZ boards BZ.v3.7.58+ 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.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 by blocksize 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 Click to display ⇲ Click to hide ⇱ $ ssh ubnt@192.168.1.20 Warning: Permanently added '192.168.1.20' (RSA) to the list of known hosts. ubnt@192.168.1.20's password: BusyBox v1.19.4 (2018-05-24 12:15:05 EEST) built-in shell (ash) Enter 'help' for a list of built-in commands. 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" WA.v8.5.4# cd /tmp/ WA.v8.5.4# fwupdate.real -m WA.v8.5.4.37936.180524.1215.bin -d Found mtd block: /dev/mtd0(u-boot) Found mtd block: /dev/mtd1(u-boot-env) Found mtd block: /dev/mtd2(kernel) Found mtd block: /dev/mtd3(rootfs) Found mtd block: /dev/mtd4(cfg) Found mtd block: /dev/mtd5(EEPROM) Got U-Boot variable: mtdparts = mtdparts=ath-nor0:256k(u-boot),64k(u-boot-env),1024k(kernel),14720k(rootfs),256k(cfg),64k(EEPROM) Adding U-Boot partition: u-boot 9F000000 00040000 Adding U-Boot partition: u-boot-env 9F040000 00010000 Adding U-Boot partition: kernel 9F050000 00100000 Adding U-Boot partition: rootfs 9F150000 00E60000 Adding U-Boot partition: cfg 9FFB0000 00040000 Adding U-Boot partition: EEPROM 9FFF0000 00010000 Calculating flash size: Adding block: /dev/mtd0("u-boot") - size: 00040000 Adding block: /dev/mtd1("u-boot-env") - size: 00010000 Adding block: /dev/mtd2("kernel") - size: 00100000 Adding block: /dev/mtd3("rootfs") - size: 00E60000 Adding block: /dev/mtd4("cfg") - size: 00040000 Adding block: /dev/mtd5("EEPROM") - size: 00010000 Total flash size: 01000000 Flash start: 9F000000 Flash end: A0000000 Header MAGIC 'UBNT' Current: WA.ar934x.v8.5.4.37936.180524.1215 New ver: WA.ar934x.v8.5.4.37936.180524.1215 Versions: New(525572) 8.5.4, Required(525057) 8.3.1 Signature MAGIC 'ENDS' FW Part: "u-boot"(1), MAGIC: 'PART', Base: 0x9F000000, DLen: 0x00038980, PLen: 0x00040000 Adding adjusted FW partition: name: 'u-boot' flash_base: 0x9F000000 mem_base: 0xBDBDBDBD size: 0x00040000 entry_point: 0xBDBDBDBD data_len: 0x00038980 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== FW Part: "kernel"(2), MAGIC: 'PART', Base: 0x9F050000, DLen: 0x000F3259, PLen: 0x00100000 FW Part: "rootfs"(3), MAGIC: 'PART', Base: 0x9F150000, DLen: 0x006E0000, PLen: 0x00E60000 FW Part: "script"(4), MAGIC: 'EXEC', Base: 0x00000000, DLen: 0x0000AA50, PLen: 0x0000AA50 Extract Script: 'tar -xz -C /tmp' Pre-Check Script '/tmp/bin/precheck' success. Adding adjusted FW partition: name: 'kernel' flash_base: 0x9F050000 mem_base: 0x80002000 size: 0x00100000 entry_point: 0x80002000 data_len: 0x000F3259 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Adding adjusted FW partition: name: 'rootfs' flash_base: 0x9F150000 mem_base: 0xBDBDBDBD size: 0x00E60000 entry_point: 0xBDBDBDBD data_len: 0x006E0000 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Signature MAGIC 'ENDS' Working(1) with block: /dev/mtd0 Working(2) with block: /dev/mtd0 End check: 9F000000 + 00040000 <= 9F040000 Creating FIS partition: 0 => name: 'u-boot' flash_base: 0x9F000000 mem_base: 0xBDBDBDBD size: 0x00040000 entry_point: 0xBDBDBDBD data_len: 0x00038980 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Working(1) with block: /dev/mtd0 Skipping: artificial: 0, unallocated: 0,writeable: 1024(WRITEABLE: 400, flags: C00), fw.flash_base: 9F050000 < blk->base: 9F000000 + blk->size: 40000 Working(1) with block: /dev/mtd1 Skipping: artificial: 0, unallocated: 0,writeable: 1024(WRITEABLE: 400, flags: C00), fw.flash_base: 9F050000 < blk->base: 9F040000 + blk->size: 10000 Copying FIS partition: 1 => name: 'u-boot-env' flash_base: 0x9F040000 mem_base: 0xBDBDBDBD size: 0x00010000 entry_point: 0xBDBDBDBD data_len: 0x00010000 desc_cksum: 0xBDBDBDBD file_cksum: 0xBDBDBDBD =========================== Working(1) with block: /dev/mtd2 Working(2) with block: /dev/mtd2 End check: 9F050000 + 00100000 <= 9F150000 Creating FIS partition: 2 => name: 'kernel' flash_base: 0x9F050000 mem_base: 0x80002000 size: 0x00100000 entry_point: 0x80002000 data_len: 0x000F3259 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Working(1) with block: /dev/mtd2 Skipping: artificial: 0, unallocated: 0,writeable: 1024(WRITEABLE: 400, flags: C00), fw.flash_base: 9F150000 < blk->base: 9F050000 + blk->size: 100000 Working(1) with block: /dev/mtd3 Working(2) with block: /dev/mtd3 End check: 9F150000 + 00E60000 <= 9FFB0000 Creating FIS partition: 3 => name: 'rootfs' flash_base: 0x9F150000 mem_base: 0xBDBDBDBD size: 0x00E60000 entry_point: 0xBDBDBDBD data_len: 0x006E0000 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Working(3) with block: /dev/mtd4 Copying FIS partition: 4 <= name: 'cfg' flash_base: 0x9FFB0000 mem_base: 0xBDBDBDBD size: 0x00040000 entry_point: 0xBDBDBDBD data_len: 0x00040000 desc_cksum: 0xBDBDBDBD file_cksum: 0xBDBDBDBD =========================== Working(3) with block: /dev/mtd5 Copying FIS partition: 5 <= name: 'EEPROM' flash_base: 0x9FFF0000 mem_base: 0xBDBDBDBD size: 0x00010000 entry_point: 0xBDBDBDBD data_len: 0x00010000 desc_cksum: 0xBDBDBDBD file_cksum: 0xBDBDBDBD =========================== New FIS entries count 6 Fixer return code: 0 Exec Script: '/tmp/bin/preflash' Working(1) with block: /dev/mtd0 Working(2) with block: /dev/mtd0 Unlocking /dev/mtd0(u-boot) ... Unlocking device failed: ioctl(MEMUNLOCK): Operation not supported Writing 'u-boot ' to /dev/mtd0(u-boot ) ... Writing: 0x00038980 bytes with offset 0x00000000 [%0 ] Block on '/dev/mtd0' at 00000000(len: 00010000) has no changes. [%28 ] Block on '/dev/mtd0' at 00010000(len: 00010000) has no changes. [%56 ] Block on '/dev/mtd0' at 00020000(len: 00010000) has no changes. [%84 ] Block on '/dev/mtd0' at 00030000(len: 00008980) has no changes. [%100] End check: 9F000000 + 00040000 <= 9F040000 Creating FIS partition: 0 => name: 'u-boot' flash_base: 0x9F000000 mem_base: 0xBDBDBDBD size: 0x00040000 entry_point: 0xBDBDBDBD data_len: 0x00038980 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Working(1) with block: /dev/mtd0 Skipping: artificial: 0, unallocated: 0,writeable: 1024(WRITEABLE: 400, flags: C00), fw.flash_base: 9F050000 < blk->base: 9F000000 + blk->size: 40000 Working(1) with block: /dev/mtd1 Skipping: artificial: 0, unallocated: 0,writeable: 1024(WRITEABLE: 400, flags: C00), fw.flash_base: 9F050000 < blk->base: 9F040000 + blk->size: 10000 Copying FIS partition: 1 => name: 'u-boot-env' flash_base: 0x9F040000 mem_base: 0xBDBDBDBD size: 0x00010000 entry_point: 0xBDBDBDBD data_len: 0x00010000 desc_cksum: 0xBDBDBDBD file_cksum: 0xBDBDBDBD =========================== Working(1) with block: /dev/mtd2 Working(2) with block: /dev/mtd2 Unlocking /dev/mtd2(kernel) ... Unlocking device failed: ioctl(MEMUNLOCK): Operation not supported Writing 'kernel ' to /dev/mtd2(kernel ) ... Writing: 0x000F3259 bytes with offset 0x00000000 [%0 ] Block on '/dev/mtd2' at 00000000(len: 00010000) has no changes. [%6 ] Block on '/dev/mtd2' at 00010000(len: 00010000) has no changes. [%13 ] Block on '/dev/mtd2' at 00020000(len: 00010000) has no changes. [%19 ] Block on '/dev/mtd2' at 00030000(len: 00010000) has no changes. [%26 ] Block on '/dev/mtd2' at 00040000(len: 00010000) has no changes. [%32 ] Block on '/dev/mtd2' at 00050000(len: 00010000) has no changes. [%39 ] Block on '/dev/mtd2' at 00060000(len: 00010000) has no changes. [%46 ] Block on '/dev/mtd2' at 00070000(len: 00010000) has no changes. [%52 ] Block on '/dev/mtd2' at 00080000(len: 00010000) has no changes. [%59 ] Block on '/dev/mtd2' at 00090000(len: 00010000) has no changes. [%65 ] Block on '/dev/mtd2' at 000A0000(len: 00010000) has no changes. [%72 ] Block on '/dev/mtd2' at 000B0000(len: 00010000) has no changes. [%78 ] Block on '/dev/mtd2' at 000C0000(len: 00010000) has no changes. [%85 ] Block on '/dev/mtd2' at 000D0000(len: 00010000) has no changes. [%92 ] Block on '/dev/mtd2' at 000E0000(len: 00010000) has no changes. [%98 ] Block on '/dev/mtd2' at 000F0000(len: 00003259) has no changes. [%100] End check: 9F050000 + 00100000 <= 9F150000 Creating FIS partition: 2 => name: 'kernel' flash_base: 0x9F050000 mem_base: 0x80002000 size: 0x00100000 entry_point: 0x80002000 data_len: 0x000F3259 desc_cksum: 0x00000000 file_cksum: 0x00000000 =========================== Working(1) with block: /dev/mtd2 Skipping: artificial: 0, unallocated: 0,writeable: 1024(WRITEABLE: 400, flags: C00), fw.flash_base: 9F150000 < blk->base: 9F050000 + blk->size: 100000 Working(1) with block: /dev/mtd3 Working(2) with block: /dev/mtd3 Unlocking /dev/mtd3(rootfs) ... Unlocking device failed: ioctl(MEMUNLOCK): Operation not supported Writing 'rootfs ' to /dev/mtd3(rootfs ) ... Writing: 0x006E0000 bytes with offset 0x00000000 [%0 ] Block on '/dev/mtd3' at 00000000(len: 00010000) has no changes. [%0 ] Block on '/dev/mtd3' at 00010000(len: 00010000) has no changes. [%1 ] Block on '/dev/mtd3' at 00020000(len: 00010000) has no changes. [%2 ] Block on '/dev/mtd3' at 00030000(len: 00010000) has no changes. [%3 ] Block on '/dev/mtd3' at 00040000(len: 00010000) has no changes. [%4 ] Block on '/dev/mtd3' at 00050000(len: 00010000) has no changes. [%5 ] Block on '/dev/mtd3' at 00060000(len: 00010000) has no changes. [%6 ] Block on '/dev/mtd3' at 00070000(len: 00010000) has no changes. [%7 ] Block on '/dev/mtd3' at 00080000(len: 00010000) has no changes. [%8 ] Block on '/dev/mtd3' at 00090000(len: 00010000) has no changes. [%9 ] Block on '/dev/mtd3' at 000A0000(len: 00010000) has no changes. [%10 ] Block on '/dev/mtd3' at 000B0000(len: 00010000) has no changes. [%10 ] Block on '/dev/mtd3' at 000C0000(len: 00010000) has no changes. [%11 ] Block on '/dev/mtd3' at 000D0000(len: 00010000) has no changes. [%12 ] Block on '/dev/mtd3' at 000E0000(len: 00010000) has no changes. [%13 ] Block on '/dev/mtd3' at 000F0000(len: 00010000) has no changes. [%14 ] Block on '/dev/mtd3' at 00100000(len: 00010000) has no changes. [%15 ] Block on '/dev/mtd3' at 00110000(len: 00010000) has no changes. [%16 ] Block on '/dev/mtd3' at 00120000(len: 00010000) has no changes. [%17 ] Block on '/dev/mtd3' at 00130000(len: 00010000) has no changes. [%18 ] Block on '/dev/mtd3' at 00140000(len: 00010000) has no changes. [%19 ] Block on '/dev/mtd3' at 00150000(len: 00010000) has no changes. [%20 ] Block on '/dev/mtd3' at 00160000(len: 00010000) has no changes. [%20 ] Block on '/dev/mtd3' at 00170000(len: 00010000) has no changes. [%21 ] ^C WA.v8.5.4# dd if=/tmp/openwrt-ath79-generic-ubnt_nanostation-ac-squashfs-sysupgrade.bin of=/dev/mtdblock2 count=256 b s=4096 256+0 records in 256+0 records out WA.v8.5.4# dd if=/tmp/openwrt-ath79-generic-ubnt_nanostation-ac-squashfs-sysupgrade.bin of=/dev/mtdblock3 skip=256 bs =4096 976+1 records in 976+1 records out WA.v8.5.4# sync WA.v8.5.4# reboot WA.v8.5.4# Connection to 192.168.1.20 closed by remote host. Connection to 192.168.1.20 closed. 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 password ubnt 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 password ubnt 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" This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.OKMore information about cookies Last modified: 2023/04/29 21:06by yolo