L2 and L3 Adoption for Ubiquiti Access Points on a Self-Hosted UniFi Network Controller

I recently setup a self-hosted Ubiquiti UniFi Network Controller running on a Linux Mint VM, and if you missed the article, you could check it out here. So, I have been busy adding Access Points (APs), I want to say that it has been quite a smooth ride except for a few challenges that come with any new solution. In this article, I want to share my observations, best practices, and lessons learned while adopting APs to the controller.

Adoption is the process of connecting a UniFi devices (e.g., APs, cameras, switches, routers, etc.) to the UniFi application that will manage it, which in our case is the UniFi Network Controller. I will try to give deep analysis of what goes on during this adoption process.

There are two adoption scenarios, and these depend on your network design:

1. Layer 2 adoption
2. Layer 3 adoption

UniFi AP Layer 2 Adoption

Before we dive deep into the UniFi AP L2 adoption, let’s quickly reminder ourselves of what goes on at L2 (also known as Data Link Layer) of the OSI model. This layer is responsible for transferring data (Data-link frames) between nodes on the same local area network (LAN) segment. Data-link frames don’t cross the boundaries of a local network (LAN). Having said this, the UniFi L2 adoption can ONLY work if the controller and the AP are on the same LAN subnet. The L2 adoption scenario can be depicted in the example topology below:

In the above topology, the UniFi AP and the controller are in the same subnet 192.168.1.0/24 and the same Local Area Network (LAN 100). The Gateway router 192.168.1.1 is providing two critical services; DHCP and NAT. DHCP will be for the automatic assignment of IP addresses to the Access Points and the user devices that connect to the AP once it comes online. NAT is the technique used to translate internal private IP addresses to a publicly routable IP address.

Here are a few points and recommendations to note in this setup:

1. Gateway (GW) router configuration to support DHCP and NAT (this router can be from any 3^rd party vendor).
2. It’s best practice to assign the UniFi Network Controller Server with a static IP (remember to exclude it from the DHCP pool).
3. The GW interface (LAN interface on the GW router), the UniFi controller, the UniFi AP must be within the same subnet and VLAN.
4. I would recommend using a PoE (Power over Ethernet) switch for such deployments. It makes the installation neat and smooth especially if you are planning to install many APs.
5. Make sure there is no firewall in the path between the UniFi AP and the UniFi controller, as the firewall will block the adoption process. If you must have the firewall, make sure to open ports 8080 (TCP) and 10001 (UDP), these are used in the adoption communication between the AP and the controller. I will elaborate on this later with some deep dive packet analysis.
6. Make sure the UniFi controller can access the internet.
7. Make sure the UniFi AP is in the factory default setting. So, if you are reusing an AP that was previously deployed on another controller or network. I recommend to first reset it to factory default. To reset a UniFi AP, make sure the AP is powered and then use a pin to press down and hold the reset button for more than 10 seconds.  

If you have all the above points in check, the L2 adoption process for UniFi is very straight forward and simple. As soon the AP has finished booting, it will show up under devices in the controller web GUI with a link “Click to Adopt”, Click the link to start the adoption process.

The AP will go through different stages of adoption which include “Adopting”, “Getting Ready”, “Offline”, “Updating”, etc. In some instances, it might briefly show “Adoption Failed” but this should not worry you. After some time, it will go back to the adopting stage before it’s finally “Online”. Should the AP go through all these stages but still show “Adoption Failed”, there is an option for “Advanced Adoption”.

Click in the AP, and click on “Advanced Adoption”:

The default “Device username/password” for advanced adoption is “ubnt/ubnt”.

If at this stage you have successfully adopted your UniFi APs, well and good. But before we celebrate, let’s dive deeper into what happens during the L2 adoption process and maybe this will give you insights on how to troubleshoot adoption failures in case they happen. For this, i did a small exercise of capturing sample packets at the UniFi Network Controller interface and analyzing them with wireshark. To capture sample packets, I reset the APs so I can capture the messages exchanges between the AP and the controller during the adoption process and then used a Linux CLI tool called tcpdump to capture the packets into pcap file format, transferred the file from the server to my laptop using WinSCP, and used WireShark to analyze the packets.

And here are key points I noted in this packet analysis:

1.) When the AP is booted, it will go through the normal DHCP process and obtain an IP from the gateway router. However we shall not discuss the details of DHCP in this article.

2.) Once the AP has an IP address, it will try to discover who is the UniFi Network Controller so it can send the adoption request. The AP does this by sending a UDP broadcast packet on port 10001 as seen in the capture below (So if there is a firewall in the PATH, the packets will be dropped and this stage will fail):

3.) The UniFi Network Controller server will then respond to the AP with a TCP [SYN] handshake on port 22 as seen below:

4.) Once the TCP handshake is completed, the UniFi Controller will try to establish a secure connection with the AP using SSHv2 so that the Controller and AP can be ready to exchange information over a secure communication. This is done using a series of Client-Server key exchange as seen in the capture below, but this is out of scope for this article.

5.) Once a secure channel is established between the AP and Controller, the AP then initiates an adoption request towards the controller on TCP port 8080. The AP does this by sending an HTTP POST request. It’s at this point that the AP will appear on the controller web GUI with status “Click to Adopt”. When you click this link, the controller will respond to the AP with HTTP/1.1 200 which means OK. And the AP will go through the adoption process. This takes about 2-3 mins and the AP will be ready to come online.

UniFi AP Layer 3 Adoption

Layer 3 adoption of UniFi APs is simple but not straight forward, in this case the UniFi AP and the server running the UniFi Controller instance are on separate networks. Just like we did for L2, let’s also briefly try to understand what happens on the L3 network. Layer 3 of the OSI model is the network layer, which is responsible for the logical addressing, routing, and delivery of data packets across different networks. The network layer uses IP (Internet Protocol) to perform these functions. In this scenario, the AP (on 192.168.1.0/24) and the Controller (on 192.168.2.0/24) are on separate logical networks. For our case, the topology is simplified but the rules are the same even for more complex topologies.

Here are a few points and recommendations to note in the L3 setup:

1. The AP network should be able to reach the Controller network. You can test this by connecting a laptop to the same switch as the AP and try pinging the UniFi Controller.
2. The UniFi Controller and the AP should be able to access the internet. Meaning that the DHCP and NAT should be functioning properly before trying the adoption process. Yet again, a laptop connected to the AP switch can be used to test this.
3. Make sure you have access to the gateway router that is doing the DHCP function, you will need to check the DHCP log once you connect the AP to verify that the AP has acquired an IP because you will need this IP in the adoption L3 process.

Once the above points are in check, note down the IP assigned to the AP by DHCP and test ping from the UniFi Controller CLI. If the ping is successful, proceed to login into the AP using SSH. (Some versions of OpenSSH included in linux OS disable ssh-dss so add the option -oHostKeyAlgorithms=+ssh-dss to the SSH command):

At “Are you sure you want to continue connecting (yes/no/[fingerprint])?” type “yes”

Default Password: ubnt

Note the port used for this step (8080), Once again, if you have a firewall in the PATH between the AP and the controller, disable the firewall or make sure that port 8080 is open. If the above command is successful, check the Controller Web GUI, under Devices, the AP should show up with status “Click to Adopt”.

Click the link to start the adoption process. The AP will go through different stages of adoption which include “adopting”, “updating”, “getting ready”, and finally “Online”. Use “Advanced Adoption” option if the AP returns “Adoption Failure” at the end of the Adoption process. The default “username/password” for advanced adoption is “ubnt/ubnt”.