User Tools

Site Tools


toh:ubiquiti:common

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+

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

  1. To unlock the partitions, you need to download WA.v8.5.4.37936.180524.1215.bin and first flash it via webinterface.
  2. log into the webif and set your password. SSH is not working otherwise.
  3. scp the firmware file onto the target: scp WA.v8.5.4.37936.180524.1215.bin ubnt@192.168.1.20:/tmp
  4. scp the OpenWrt sysupgrade image onto the target: scp ubnt_nanostation-ac-squashfs-sysupgrade.bin ubnt@192.168.1.20:/tmp
  5. ssh into the target: ssh ubnt@192.168.1.20
  6. double check the partition table:
    1. cat /proc/mtd
    2. size of mtd2:kernel should be 0x00100000
    3. size of mtd3:rootfs should be 0x00e60000
  7. cd /tmp
  8. 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).
  9. convert hexadecimal 0x00100000 to decimal: 1048576, divided by blocksize 4096 = 256
  10. 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
  11. 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
  12. 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:

  1. Perform a factory reset
  2. 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
  3. 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
  4. 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

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:

how to flash

  1. downgrade first:
    1. copy firmware to the device, e.g.: scp BZ.qca956x.v3.7.58.6385.170508.0957.bin ubnt@192.168.1.20:/tmp
    2. log into the device with SSH: ssh ubnt@192.168.1.20 with password ubnt
    3. to downgrade: fwupdate.real -m /tmp/BZ.qca956x.v3.7.58.6385.170508.0957.bin
  2. flash OpenWrt:
    1. copy firmware to the device, e.g.: scp openwrt-ath79-generic-ubnt_unifiac-pro-squashfs-sysupgrade.bin ubnt@192.168.1.20:/tmp
    2. log into the device with SSH: ssh ubnt@192.168.1.20 with password ubnt
    3. flash openwrt to partition kernel0: mtd write /tmp/openwrt-ath79-generic-ubnt_unifiac-pro-squashfs-sysupgrade.bin kernel0
    4. erase partition kernel1: mtd erase kernel1
    5. write a single 0-byte in bs: dd if=/dev/zero of=/dev/mtd4 bs=1 count=1
    6. 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.More information about cookies
toh/ubiquiti/common.txt · Last modified: 2020/05/30 15:28 by rogerpueyo