Using a Unifi controller half a continent away

I’ve been a reasonably happy camper using Ubiquiti’s Unifi line of WiFi access points at my home for about 8 years now. Adding a new one this week got me thinking. Unifi equipment by default discovers the controller through IP broadcasting. That works fine when everything is in the same broadcast domain, nice and local. At my house things are different, though. My Unifi controller runs half a continent away in a different subnet. Setting DHCP option 43 on my OPNSense firewall’s DHCP service made adoption of the new access point a breeze. Here’s how to do it!

So what is DHCP option 43 and why should you care? First off, DHCP options are settings on a DHCP server that will be communicated to your client devices when they request their configuration from the network. DHCP obviously gives you an IP address, a default gateway and DNS servers for use but that’s far from all it can do. The DHCP protocol provides a whole slew of standardized other settings that you can pass on to client devices. These settings are called DHCP options and they’re numbered. Option 43 is an option that you can use for vendor-specific settings that aren’t universally standardized. Ubiquiti’s Unifi producst use the contents of this option to figure out where the controller lives if it’s not on the local network.

My OPNSense box currently still uses ISC DHCP but that will change in the near future as the ISC product is being deprecated. For now, this is what it is. I’ll update this article when the dust on DHCP settles with the OPNSense project.

Now without further ado, the contents of the option 43 field should be a hexadecimally encoded set of numbers that represent two bytes of Unifi-specific configuration and four bytes for your IPv4, also encoded in hexadecimal.

Hexadecimal is a numbering system that is base-16 instead of our usual base-10 decimal system. In order to represent these numbers, we borrow letters from the alphabet because we don’t have enough numerals to represent this notation. Here’s how it works:

Hexadecimal numbers are usually prefixed with the dollar sign $ or the prefix 0x and for representing bytes they also get a leading zero. A value of 10 on a byte would be $0A or 0x0A in hexadecimal. You can use online decimal to hexadecimal converters to do conversion for you automatically.

My Unifi controller lives at IPv4 address 10.20.0.20 so in hexadecimal that would be $0A $14 $00 $14, prefixed with the two configuration bytes for Unifi: $01 and $04. These tell the Unifi equipment that we’re going to use the next 4 bytes for the controller’s address. This setting probably is configurable because IPv6 uses 16 bytes for an address, but let’s not go there for now. Unifi has only recently added support for IPv6 in the first place so I’m not going to rely on that just yet.

OPNSense’s DHCP GUI allows me to set option 43 in the form of a String data type, so let’s choose that in the ‘Type’ dropdown. To get Unifi to pick up the option correctly, the form of the ‘Value’ field is like this:

01:04:0A:14:00:14

Save the setting, wait for the DHCP service to restart, and you’re in business. Hook up your new Unifi equipment to the network and look for it to receive a DHCP lease from your OPNSense box. When it does, you should also see it appear in your Unifi controller at around the same time ready for adoption.

This way your Unifi controller could live half a continent away while adding new access points to your local environment remains smooth and simple. This setting only needs to be applied once. You could do this for a huge office or campus environment and all your equipment will seamlessly find a controller that you can safely run in a proper datacenter environment rather than a utility closet.