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 boards

WA8.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.

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: 2019/08/10 17:40 by tmomas