Unms — device discovery

How Discovery Works

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.   

Blocking the Discovery

If you wish to prevent your device from being discovered, you can perform the following configuration.

airMAX: Go to 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

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 stepsudo systemctl stop docker
#backup of docker folder, just in casecp -au /var/lib/docker /var/lib/docker.bak
#into the file /etc/docker/daemon.json put this  {"storage-driver": "overlay2"}#install the Docker againsudo 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 . 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 .

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 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 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  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.