This article will explain how to adopt UniFi Devices to a local UniFi Network controller. The UniFi Security Gateway (USG) adoption will have some important differences when the USG is replacing a router in an already existing and functioning network. Please see this article for more: UniFi - USG: How to Adopt a USG into an Existing Network.
Table of Contents
The first configuration that must be done when unboxing a UniFi device is adoption by the UniFi Network Controller. This will allow management and further configuration of the devices by the controller. This article will explain how to adopt UniFi device(s) to a local controller. For remote adoption and adoption via the UniFi mobile app please see the Related Articles below.
In order to adopt a UniFi device the following requirements must be met:
- Install the UniFi Network Controller software and make sure it is running with the current stable version. Download the UniFi Controller software here under the Documentation section.
- The controller must be running on a machine connected locally to the UniFi devices- preferably connected via a wired connection. See the following example (note that a Cloud Key is not required, any UniFi Controller host could replace the Cloud Key in the image below):
- The controller and devices must be able to send and receive traffic over determined ports. See this article for information: UniFi - Ports Used.
- The device needs to be connected to be powered, in default state, as indicated by static white LED.
- Only if adopting UniFi Security Gateway (USG) - Verify that the default LAN network in Settings > Networks, does not conflict with the network to which your USG’s WAN interface will be connected. If your USG will be given a DHCP address on the default 192.168.1.x subnet, make sure to change the subnet of LAN network in controller settings to a different subnet, for instance: change to 192.168.2.1/24, then “Update DHCP Scope” prior to adopting the USG. As an alternative, we recommend in these cases that if possible the upstream router be put in Bridge Mode as to limit potential complications.
How to Adopt UniFi Devices
After all the above requirements are met, you’re ready to proceed with adopting your UniFi Devices. You can perform these steps from either a device connected to the same local network as your controller and devices, or from the controller itself if this is a software installation on a supported workstation.
1. Launch the UniFi Network Controller through your web browser (Google Chrome is recommended).
2. Click on the Devices tab.
3. All locally connected devices should appear in default state, as pending adoption.
- If the unadopted devices are not visible, it will be necessary to determine why the controller is unable to discover these devices before proceeding. Double check the requirements above and take a look at the Troubleshooting article in the Related Articles below.
4. If the device displays the action Upgrade, the device is in need of a firmware update. Click this before adopting and allow the UniFi device to update to the most current device firmware. Once finished, proceed to the next step.
5. Click Adopt to adopt the device. This can take a few minutes to complete.
6. The status of the UniFi device should have changed from “Pending Adoption” to “Adopting” as the device is connected to, and given the command to reach out to the controller for adoption.
User Tip: If you experience an issue where the status of the device loops from trying to adopt > disconnected > trying to adopt, it may be an issue with the firewall of the machine hosting the UniFi Network Controller. Port 8080 must be open for inbound traffic. Either open up that port or turn off the firewall if that’s a possibility. See what ports are needed for UniFi here: UniFi - Ports Used.
7. Once a connection between device and controller has been successfully established, the status will change to “Provisioning”, This indicates the controller is pushing configuration to the device.
8. After this has been completed, the status will return “Connected”. In rare occasion, you will need to leave this screen and come back to see this Status change.
Once the device appears as Connected, this indicates the device has been configured with the default site configuration. If further configurations are needed, like adding an SSID for the AP to broadcast, or changing VLANs, all this can be done through the controller now. Any changes made to site-wide configuration will cause the devices to re-provision. This means after adoption all devices will be automatically kept up to date with configuration changes.
This completes the process of adoption. If you wish to learn more about how this adoption works we’ve included a detailed explanation of the adoption process below, as well as a link to an article where you can get help troubleshooting/resolving any UniFi adoption issues you may encounter.
How Device Adoption Works
When you plug in a UniFi device like a UniFi Access Point or a UniFi Switch, the UniFi device will boot up and eventually show a static white LED. This white LED indicates that the device is not currently managed by a UniFi controller and ready to be adopted by a UniFi controller. When the device is in this state it makes itself available for discovery and adoption.
When using the UniFi controller, the Device Discovery tool scans the local network for any UniFi device. All UniFi devices, if detected show up with a status of either Managed or Pending Adoption. Devices with a white LED should show up as Pending Adoption within the UniFi controller, while other devices that have a Blue LED should show up as “Online” if managed by this controller, or “Managed by Other” if still adopted and managed by a different controller.
When the administrator clicks adopt, the adoption request is sent to the AP over port 22, using SSH to authenticate the default credentials (ubnt/ubnt) and issue the inform command. The AP then executes the set-inform command and sends the inform packet to the URL provided by the UniFi controller- and sends it over port 8080.
The device, if successful in adopting will start provisioning and be configured to match the controller’s configured wireless networks or other settings. Once it is finished the device will show as connected in the controller.
Most often when there are issues with the adoption process it is because something in the environment obstructs the above process from completing. Understanding where the device stops working can help pinpoint the issue and make it easier to resolve the issue.