This article explains how device discovery works on UNMS and how to troubleshoot any issues that may be encountered.
ATTENTION: Since the UNMS version 1.1.0 there is a new discovery tool called Remote DIscovery. If you are running 1.1.0 or higher please visit this link.
NOTES & REQUIREMENTS: Devices using older firmware will have to upgrade to latest version in order to be discovered. If the device has firmware versions as the ones listed below, please upgrade:
Table of Contents
- How Discovery Works
- Blocking the Discovery
- Related Articles
Understanding how device discovery works, helps interpret and solve issues if they arise. This article explains how the discovery process works and what to do if you either cannot discover a device or you can discover it, but it won't connect. In case you do not want your device to be discovered for some reason, this article also includes how to prevent discovery.
How Discovery Works
UNMS tries to find Ubiquiti and 3rd party devices through several tools. This is the process it follows:
- UNMS uses a PING to make sure there is a device on the given IP address.
- If UNMS gets an answer, the process continues and at that point, the device will appear as an 'Unknown device'.
- Ubiquiti Discovery is leveraged to get detailed information about the device. In this step, the TCP protocol is used first and in the second wave the UDP protocol. If the device indeed is one of Ubiquiti's and it has discovery enabled it should send back basic information shown in the Discovery Manager: name, SSID, model, firmware version, MAC address and a list of all interfaces.
- If the device doesn't reply to Ubiquiti Discovery then UNMS uses SNMP protocol to download some basic info about the device.
ATTENTION: If either UNMS or a device you need to discover are placed on a public IP range, please make sure all conditions for TCP discovery are met.
Issue: I can't see any devices or some devices are missing
Can you ping the device from the UNMS server?
Check traceroute/ping/curl from your UNMS server to the device's IP. Please note that the ping has to be lower than 400ms otherwise discovery can fail.
ping 192.168.x.x traceroute -n 192.168.x.x
Is your OS supported?
Discovery doesn't work on Debian 8. It's recommended upgrading to Debian 9 which is officially supported.
Are you using virtualization? If yes, is it the supported one?
Discovery doesn't work on UNMS instances running on an LXC container. This is only one of several issues with LXC containers, which is why they are not officially supported. Please use KVM instead.
Do you have a supported storage driver?
Discovery doesn't work on systems without overlay2 storage driver. Please check that your Kernel includes this driver and your Docker is using it. Here are some pointers on adding the overlay2:
#stop the Docker as a first step
sudo systemctl stop docker
#backup of docker folder, just in case
cp -au /var/lib/docker /var/lib/docker.bak
#into the file /etc/docker/daemon.json put this
#install the Docker again
sudo systemctl start docker
Are you searching for the correct IP range?
Make sure that you are using only 24 ranges for public IP addresses. For public IPs, UNMS doesn't allow to search higher ranges. For private IPs it is possible to go to /16 but the search will be very long.
Is device discovery enabled on the device?
Discovery doesn't work on devices with disabled Discovery. Please make sure that Discovery is enabled in your device in the following locations or by following these instructions:
- airMAX: Under
Settings > Services > Device Discovery. If the checkbox is set to OFF change it to ON and click
- EdgeRouter: UDP discovery is always active on EdgeRouters, but in some cases, you need to make sure TCP discovery is enabled as well. For example when UNMS is on the public IP and the device is on a private one. You can enable TCP discovery by running:
set service ubnt-discover-server protocol tcp_udp commit save
Are UDP packets allowed through?
Discovery doesn't work with blocked port 10001. Please check if there isn't an active firewall record for blocking UDP packets on port 10001, as seen in the Blocking the Discovery section.
Do you use an IP address in range 172.x.y.z? Is there a possible collision with Docker?
Check collision with Docker's virtual subnet. While rare, the container's IP might collide with the real IP in your network. Run
ifconfig on your UNMS server to see Docker's IPs:
$ ifconfig br-6805a10e2e92 Link encap:Ethernet HWaddr 02:42:d3:f8:f1:64 inet addr:172.18.0.1 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::42:d3ff:fef8:f164/64 Scope:Link UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:196618 errors:0 dropped:0 overruns:0 frame:0 TX packets:10 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:5506244 (5.5 MB) TX bytes:764 (764.0 B) docker0 Link encap:Ethernet HWaddr 02:42:dd:1c:c3:57 inet addr:172.17.0.1 Bcast:0.0.0.0 Mask:255.255.0.0 inet6 addr: fe80::42:ddff:fe1c:c357/64 Scope:Link UP BROADCAST MULTICAST MTU:1500 Metric:1 RX packets:8 errors:0 dropped:0 overruns:0 frame:0 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0 collisions:0 txqueuelen:0 RX bytes:536 (536.0 B) TX bytes:648 (648.0 B)
If such an IP exists in your network you will have to change Docker's subnet with the following:
cd /home/unms/app docker-compose -p unms down docker network create unms_default --subnet 172.30.0.1/24 docker-compose -p unms up -d
If you find there is a collision with docker, please note that you can change the docker subnet which UNMS uses, through installation script parameters. See UNMS - Optional Installation Steps for more information.
Are the UDP packets arriving?
Check with tcpdump that your device receives UDP packet from your UNMS instance and sends back an answer.
Issue: Ubiquiti devices are found as Unknown
Are you running UNMS on a public IP?
If UNMS (up to 0.13.1) has a public IP address and a device has a private IP, there will be an issue with device discovery. UNMS most likely won't recognize this device correctly. This was fixed in 0.13.2.
Is your device supported?
Consider if your device is supported by UNMS, here is a list of supported devices.
Is discovery enabled on the device?
If discovery is disabled the device will show as unknown in UNMS device discovery.
Are UDP packets allowed through?
If they are not, the device will show as unknown in UNMS device discovery.
Are the UDP packets arriving?
If not, then the device will show as unknown in UNMS device discovery.
Issue: I can discover the device, but the connection to UNMS is failing
NOTE: Not every tool is available on all devices. Only EdgeRouters are guaranteed to have all the tools described below.
Is it possible to ping UNMS from the device?
Check traceroute/ping/curl from the device to your UNMS server IP / domain name:
ping unms-server.com traceroute -n 192.168.x.x curl --insecure https://192.168.x.x:443/v2.1/nms/version
Does the connection upgrade to WebSocket?
Check HTTPS upgrade to WebSocket:
curl --insecure --include --no-buffer --header "Connection: Upgrade" --header "Upgrade: websocket" --header "Host: example.com:80" --header "Origin: http://example.com:80" --header "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" --header "Sec-WebSocket-Version: 13" https://192.168.x.x:443/
The values of the
--header parameters do not matter, you can use example.com as shown. Only the last parameter must be the real address of your UNMS server. This should return an output similar to the following, indicating that the upgrade to WebSocket was successful:
HTTP/1.1 101 Switching Protocols Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: qGHgK3En71di5rrssAZTmtRTyFk= db332780afad264425162cb11d19ffd1ac9ad3658f63cb56968a8a2592054a39aac950bcdae301e39eea75f28c7d3e7dd32a568f0fcf67f25b692434c825ffc7d13b7f8bcec1fb649919d784723f039ef50deb939eeb2b1bd602f56339ac20b65b3
Is the time configured correctly?
Make sure the device has the correct time and date set. SSL connection requires valid time and date. This might be an issue for devices not connected to the internet or with NTP service which is disabled.
Is the AES key correct?
If the device has been connected previously try refreshing its UNMS key by clicking Refresh on the corresponding row in the Devices table. If this doesn't succeed, it is also possible to manually paste the universal UNMS key via the device's UI.
Issue: There is an error message about contacting support
Do you know where to contact us?
This error means that some device sent a block of data which UNMS cannot parse. Usually, it is a single device and if its IP address is omitted from the search range the discovery continues without issues. In any case please write a post in our community forum and we will gladly help you.
Blocking the Discovery
If you wish to prevent your device from being discovered, you can perform the following configuration.
airMAX: Go to
Settings > Services > Device Discovery > set checkbox to OFF and click
EdgeRouter: Currently this can be done only through the firewall rule. To set up the rule issue the following commands:
configure edit firewall name disable-discover set default-action accept set rule 100 action 'drop' set rule 100 description 'Drop discovery packets' set rule 100 protocol 'udp' set rule 100 destination port 10001 exit # apply rule to the interface that is connected to the Internet set interfaces ethernet eth0 firewall local name 'disable-discover' commit save show interfaces
NOTE: The rule will block entire incoming UDP communication to port 10001, potentially disabling more than just the discovery.
To disable the rule, issue the following:
configure delete interfaces ethernet eth0 firewall local name 'disable-discover' commit save