Installing OpenWrt on a Unifi AP AC Lite in 2023

OpenWrt is a very powerful OS and can be configured to be much more useful and capable than just an access point, but these instructions assume you have other devices on your network handling those duties. Our goal here is just to replace the OS on the Unifi AP AC Lite with OpenWrt, leaving the AP to only handle wireless connectivity to the rest of your network.

Before you start

Make sure you’ve got some empty IP addresses.

Make sure you take a note of your Unifi network’s SSH username & password. Once you begin the process, you will not be able to manage them from the Unifi controller. Out of the box, they’re ubnt:ubnt, but either through upgrading or twiddling over the years, mine were not that anymore. You can find them in the System Settings page, under Network Device SSH Authentication.

Downgrade the Unifi AP AC Lite

According to the OpenWrt Wiki, recent versions of the Unifi AP firmware have disabled write access to certain flash sections and removed some of the tools necessary for installing OpenWrt. These updates will hinder the installation process of OpenWrt. The easiest workaround for these restrictions is to downgrade the firmware to a version that predates the implementation of these protections. However, it is unclear which specific protections were introduced in which firmware versions. Therefore, to ensure a comprehensive approach, I recommend downgrading to the earliest available firmware version. As of July 2023, the earliest firmware version available on Ubiquiti’s site is v3.7.58. Click the Download button and then click through the EULA popup to view the download URL for the firmware. At the time of writing, it can be found at https://dl.ui.com/unifi/firmware/U7PG2/3.7.58.6385/BZ.qca956x.v3.7.58.6385.170508.0957.bin.

You now need to find your Unifi AP AC Lite in your Unifi console and navigate to the Location URL field in the Settings > Manage menu. Paste the link to the .bin file in the Location URL field, hit Update, and follow the prompts. The Unifi console will display a scary looking popup that asks you to confirm you’re happy to install firmware from a custom location and that there may be compatibility issues after installation. Hit Confirm on this message and the Unifi AP will reboot automatically once it completes installing the firmware.

The “compatibility issues” mentioned in that message appear to include a problem where the old firmware is unable to connect to the up to date console, so from this point on the Unifi console will be unable to adopt or configure the Unifi AP AC Lite. All configuration from this point on will be via SSH. Once installation has complete and the Unifi AP AC Lite has rebooted, if you have a DHCP allocation set , it will start up and respond on that address, otherwise it will use its default address, 192.168.1.20.

Install the OpenWrt firmware

To install the OpenWrt firmware, connect to the Unifi AP with SSH. The SSH server that’s included in v3.7.58 is pre-LogJam, so it only offers old, out of date key algorithms. Depending on how up to date your SSH client is, it may not support these algorithms by default. If so, you’ll see the following error message.

$ ssh ubnt@192.168.1.20
Unable to negotiate with 192.168.1.20 port 22: no matching host key type found.
Their offer: ssh-rsa,ssh-dss

To connect to an older SSH server such as this, you have to manually specify an acceptable key algorithm, using the HostKeyAlgorithms option. If successful, you should see a number of messages or banners scroll by and be presented with a BZ prompt that includes the downgraded firmware version.

$ ssh -oHostKeyAlgorithms=+ssh-dss ubnt@192.168.1.20
[...]
BZ.v3.7.58#

Once connected, you’ll need to download the latest suitable OpenWrt firmware to the Unifi AP. According to the OperWrt hardware wiki, as of July 2023 the latest version is 22.03.05, compiled for the ath79 target and packaged for the AC Lite. You can download it using the curl command, which I have split over multiple lines for readability here.

BZ.v3.7.58# curl \
> https://downloads.openwrt.org/releases/22.03.5/targets/ath79/generic/\
> openwrt-22.03.5-ath79-generic-ubnt_unifiac-lite-squashfs-sysupgrade.bin \
> >openwrt.bin
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 6208k  100 6208k    0     0   339k      0  0:00:18  0:00:18 --:--:--  602k

APs like the Unifi AP AC Lite do not have storage in the form of HDDs or SSDs, but as embedded flash chips known as MTDs. This means we’re not going to write our image to a partition such as /dev/sda like you would when flashing an SD card for a Raspberry Pi. Instead, we deal with MTD character devices such as /dev/mtd4 or we can use the mtd tool to operate on the devices for us. To see the equivalent of the MTD’s partition table, you can look in the /proc/mtd file.

BZ.v3.7.58# 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"

Unifi APs have two “partitions” that can have images written to them, kernel0 and kernel1, to allow Ubiquiti to be clever and roll-back to a previous image if an upgrade fails. OpenWrt does not have this ability and is can only boot from the first of the two “partitions”. We will therefore use the mtd tool to write our openwrt.bin file to the kernel0 partition.

BZ.v3.7.58# mtd write openwrt.bin kernel0
Unlocking kernel0 ...

Writing from openwrt.bin to kernel0 ...

At this point, you have successfully written OpenWrt to the first “partition”, but Unifi’s OS will still be installed to the second one. We can use the mtd tool to erase the second “partition”, kernel1, leaving only OpenWrt installed on the AP.

BZ.v3.7.58# mtd erase kernel1
Unlocking kernel1 ...
Erasing kernel1 ...

Finally, we need to let the Unifi AP AC Lite know which “partition” to boot in to. This is done by writing a single 0 byte to the boot selector or “bs” partition in order to indicate kernel0. In an earlier command we saw that the mtd4 character device contained the “bs” partition, so we can use dd to write the single 0 byte.

BZ.v3.7.58# dd if=/dev/zero bs=1 count=1 of=/dev/mtd4
1+0 records in
1+0 records out

The only piece of Unifi’s OS that’s left is what remains in the Unifi AP AC Lite’s RAM. Rebooting the AP now will restart the device and load OpenWrt as the AP’s OS.

BZ.v3.7.58# reboot
Connection to 192.168.1.20 closed by remote host.
Connection to 192.168.1.20 closed.

Configure OpenWrt

Your Unifi AP AC Lite has now rebooted, launched OpenWrt and is listening on the IP address 192.168.1.1 over it’s ethernet port.

To begin setting up your AP, log in to LuCI, OpenWrt’s web-based admin panel, on http://192.168.1.1/cgi-bin/luci/. Your new admin username is root and, by default, the password is simply password. This can and should be changed in the “Router Password” tab on the the System > Administration page.

The next step is to change your AP’s IP address as it will probably either be clashing with your normal router or be entirely incorrect for the rest of your network; this can be set in the Network > Interfaces page. Choose the lan device on that page and press the “Edit” button. On the dialog that pops up you can either replace the static IP address with one of your own choosing or switch to an allocated address by selecting “DHCP client” from the “Protocol” drop down.

As OpenWrt is designed to support many different powerful router configurations, Dnsmasq is installed, enabled and started by default and provides DNS and DHCP for IPv4 networks. Odhcpd is also installed, enabled and started by default and provides RA and DHCP for IPv6 networks. Since we want to use the Unifi AP AC Lite as just an access point, we must stop and disable both of these services.

The last part to configure your AP is to add the SSIDs you want to broadcast. Unifi AP AC Lites have two radios onboard, an 802.11acn radio broadcasting on 5GHz and an 802.11bgn radio broadcasting on 2.4GHz. Adding SSIDs is accomplished by pressing the “Add” button next to each and filling out the required fields. If you want to broadcast the same SSID on both frequencies to allow clients to migrate between them, you’ll need to create two identical SSIDs, one for each radio.

Finally, you’ll need to save and apply the changes your made above. This can be done by pressing the “UNSAVED CHANGES” link found in the top-right of the web admin panel. This will present you with a text based version of all the changes you have made, allowing you to confirm you’ve not made any typos and apply the configuration.

What next?

Sit back and enjoy your AP, you weird nerd! Alternatively, start to dig in to the OpenWrt documentation to expand on the ideas in this post. For example, I hope to cover band steering, 802.11r, 802.11k & 802.11v fast transition roaming and 802.1X access controls in subsequent, upcoming blogposts.

2023-07-25

Leave a comment