UNMS - Device Discovery


Overview


This article describes how device discovery works on UNMS and what to do if you encounter issues.

NOTES & REQUIREMENTS:
The discovery feature is one of the top priorities for UNMS version 0.13.0 and will include many improvements and changes which will be included in this article once it is released.

Table of Contents


  1. Introduction
  2. How Discovery Works
  3. Blocking the Discovery
  4. Troubleshooting
    1. Issue: I can't see any devices or some devices are missing
    2. Issue: I can discover the device but connection to UNMS is failing
    3. Issue: Domain Name Resolution Issues
  5. Related Articles

Introduction


Back to Top

It is important to know how discovery works to understand what issues we could run into. This article explains how the discovery process actually 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 sends discovery packets to every IP address in the given range and waits for device reply. The device sends back basic information shown in the Discovery Manager: name, SSID, model, firmware version, MAC address and a list of all interfaces. The discovery packet is sent using UDP to port 10001, it consists of four bytes 0x1 0x0 0x0 0x0.

ATTENTION: The device only responds to packets sent from private network ranges.

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:

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

Troubleshooting


Back to Top

Find below three possible troubleshooting scenarios and how to solve each of them.


Issue: I can't see any devices or some devices are missing


Known Issues:

  • Discovery doesn't work on Debian 8. It's recommended upgrading to Debian 9 which is officially supported.
  • Discovery doesn't work on UNMS instance running in LXC container. This is one of more problems with LXC containers and therefore they are not officially supported.
  • The current version (0.12.0) of UNMS discovery can't find devices with IPs in public ranges (it could work with old FW, but not with new one). It will be fixed in 0.13.0.
  • Make sure that Discovery is enabled in your device:
    • airMAX: under SETTINGS > Services -> Device Discovery. If the checkbox is set to OFF change it to ON and click Save Settings.
    • EdgeRouter: under SETTINGS > System > UBNT Discovery. If the checkbox is set to OFF change it to ON and click Save. Plus you need to check if there isn't an active firewall record for blocking UDP packets on port 10001, as seen in the Blocking the Discovery section
  • Check traceroute/ping/curl from your UNMS server to device's IP.
    ping 192.168.x.x
    traceroute -n 192.168.x.x
  • Check collision with Docker's virtual subnet.

    While rare, the container's IP might collide with 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
    
    UNMS also contains installation parameters. See UNMS - Optional Installation Steps for more information.
  • Check with tcpdump that your device receives UDP packet from your UNMS instance and sends back an answer.
  • Make sure that you are using only 24 ranges for public IP addresses. 
  • Consider if your device is supported by UNMS, here is a list of supported devices:
    • EdgeRouter (since UNMS 0.11.0)
    • EdgeSwitch (since UNMS 0.11.0)
    • UFiber OLT (since UNMS 0.11.0)
    • airMAX (AC/M) (since UNMS 0.11.0)
    • airCube (since UNMS 0.11.0)
    • airFiber OLT (since UNMS 0.12.0)
    • EdgeSwitch XP (since UNMS 0.12.0)
    • EdgePower (since UNMS 0.12.0)

    NOTE: If your FW is not at least this version then discovery process will forcibly update your device to the latest FW:
    • EdgeRouter older than 1.9.7-hotfix4
    • EdgeSwitch older than 1.7.3. (if they are older than 1.4.0. you have to upgrade manually)
    • UFiber OLT no threshold is set
    • airMAX M older than 8.4.3
    • airMAX AC older than 6.1.3
    • airCube no threshold is set
    • airFiber LTU older than 1.1.1
    • EdgeSwitch XP older than 1.4.0
    • EdgePower older than 1.2.0

    Issue: I can discover the device, but the connection to UNMS is failing


    Back to Top

    NOTE: Not every tool is available on all devices. Only EdgeRouters are guaranteed to have all tools described below.
    • Check traceroute/ping/curl from 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
      
    • 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: SGVsbG8sIHdvcmxkIQ==" --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 output similar to the following, indicating that upgrade to WebSocket was successful:
      HTTP/1.1 101 Switching Protocols
      Upgrade: websocket
      Connection: Upgrade
      Sec-WebSocket-Accept: qGHgK3En71di5rrssAZTmtRTyFk=
      
      db332780afad264425162cb11d19ffd1ac9ad3658f63cb56968a8a2592054a39aac950bcdae301e39eea75f28c7d3e7dd32a568f0fcf67f25b692434c825ffc7d13b7f8bcec1fb649919d784723f039ef50deb939eeb2b1bd602f56339ac20b65b3
      
    • Make sure device has 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.
    • If the device has been connected previously try refreshing its UNMS key, by clicking Refresh on the corresponding row in Devices table. If this doesn't succeed, it is also possible to manually paste the universal UNMS key via the device's UI.

    Issue: Domain Name Resolution Issues


    Back to Top


    Related Articles


    Back to Top

    UNMS - Optional Installation Steps