UNMS - Device Discovery


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:
  • airCube no threshold is set
  • airFiber LTU older than 1.1.1
  • airFiber older than 4.1.0-beta.6
  • airMAX AC older than 8.4.3
  • airMAX M older than 6.1.3
  • EdgeRouter older than 1.9.7-hotfix4
  • EdgeSwitch older than 1.7.3. (older than 1.4.0. will have upgrade manually)
  • EdgeSwitch XP older than 1.4.0
  • EdgePower older than 1.2.0
  • UFiber OLT no threshold is set

Table of Contents

  1. Introduction
  2. How Discovery Works
  3. Troubleshooting
    1. Issue: I can't see any devices or some devices are missing
    2. Issue: Ubiquiti devices are found as Unknown
    3. Issue: I can discover the device but connection to UNMS is failing
    4. Issue: There is an error message about contacting the support 
  4. Blocking the Discovery
  5. Related Articles


Back to Top

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

Back to Top

UNMS tries to find Ubiquiti and 3rd party devices through several tools. This is the process it follows:

  1. UNMS uses a PING to make sure there is a device on the given IP address.
  2. If UNMS gets an answer, the process continues and at that point, the device will appear as an 'Unknown device'.
  3. 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.
  4. 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

Back to Top

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 
"storage-driver": "overlay2"

#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 Save Settings.
  • 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

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:  Bcast:  Mask:
            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:  Bcast:  Mask:
            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
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=


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

Back to Top

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 Save Settings

EdgeRouter: Currently this can be done only through the firewall rule. To set up the rule issue the following commands:

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
# apply rule to the interface that is connected to the Internet
set interfaces ethernet eth0 firewall local name 'disable-discover'

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:

delete interfaces ethernet eth0 firewall local name 'disable-discover'

Related Articles

Back to Top

UNMS - Optional Installation Steps

Was this article helpful?
24 out of 44 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community