Help Center Help Articles Professional Support Community RMA & Warranty Downloads Tech Specs

UISP - Site & Device Management

Overview

This article provides essential information for managing UISP devices, sites & subscribers.

Supported Devices in UISP 1.4.x

Our goal is to increase the number of supported Ubiquiti devices with each new version of UISP. Usually, the support starts with basic monitoring functions and the ability to connect the device to UISP or find it through the Remote Discovery feature. In later stages, more advanced features are gradually added on; features such as the ability to upgrade a device's firmware, and check its statistics on the UISP dashboard. In the final phase, we add detailed information about interfaces and ports and the ability to manage the device's network configuration remotely. The table below shows the progress for each product line with the latest UISP version.

The table below shows a different Ubiquiti letter "U" to show if the feature is fully implemented or partially implemented.

new_logo_blue_25px.png Fully implemented
new_logo_gray_25px.png Partially implemented

 

Model Connection Discovery  Upgrade Statistics Dashboard Interfaces Configuration

UISP Switch

new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png

UISP Router

new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png
EdgeSwitch new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png

EdgeSwitch XP

new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png
EdgeRouter new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_gray_25px.png
UFiber new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png
EdgePower new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png      
EdgePoint new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_gray_25px.png
airMAX M new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png   new_logo_gray_25px.png
airMAX AC new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png   new_logo_gray_25px.png
LTU new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png    
Wave new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png    
airFiber new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png    
airFiber 60 new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png    
airCube new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png   new_logo_blue_25px.png
airGateway new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png new_logo_blue_25px.png    

Sites & Subscribers

UISP Terminology

Here we explain the purpose of UISP, as well as some ideal topologies for managing within UISP. Please note that UISP is primarily designed for Internet Service Providers (ISP) who want to take full advantage of the benefits Ubiquiti devices provide. UISP strives to offer advanced, fully automated functions that need a specific network topology in order to run as they were intended to. It is certainly possible to run UISP in different types of networks and deployments, but some features may be unavailable or perform sub-optimally.

The UISP side of the integrated UISP-UCRM application (referred to as the "Network module" in the rest of this guide) is exclusively dedicated to the physical structure and real topology of a network. The focus is either on backbone devices and their placement on towers or buildings, or CPE devices and their location. The CRM part of the application takes care of the business side: management of real people, services, and customers along with their personal data.

Network Module

  • Device: a physical device like a router, switch, or wireless antenna. It can be a Ubiquiti device or a manually specified 3rd party device.
  • Site: a location where a device is placed. It can be a tower, roof, building, or even a room—pretty much any geographical spot with an address. Sites are key components of a network module and they create its backbone.
  • Subscriber: a specific type of location (site) with an address, where there are devices providing internet to a single CRM client. Subscribers can be paired with services defined in CRM, allowing business-oriented operations, such as blocking a customer when payment is due or setting a traffic Shaping on specific devices associated with a particular customer.
  • AP: an Access Point is a connection point with the potential to offer an internet connection to several devices.
  • Stations / Clients: Stations or CPEs are the devices connected to an AP device. Those CPE devices create the endpoints of the network. There are also home WiFi devices such as the airCube that can have a list of connected devices, called clients. Those are devices that usually belong to a customer (like a mobile phone or laptop) and are not managed via UISP. So a possible connection between these could be: AP -> Station (CPE) -> home WiFi (airCube) -> client (laptop). 
    NOTE: Please be aware that there is a difference between a UISP client, which is a client device, and the CRM client which represents a customer paying for a Service (more info in the CRM section below).
  • GW: A main gateway in a network module. There can be several gateways in the network, one for each ISP. These are necessary for advanced features such as client suspension, setting up a traffic Shaping for a client, or measuring the throughput with NetFlow protocol. UISP facilitates a way to automatically configure advanced network features for devices added as the UISP gateway.

CRM Module

  • Client: a person or a company, who is receiving a service such as the Internet or VoIP, for example. A client can have several services in different locations with different parameters.
    NOTE: Notice the difference between a UISP client, which is a client device such as a laptop; and a CRM client which represents a "customer"—be it an individual or a company.
  • Service: One specific internet connection that represents an item on an invoice and provides a connection to one or more devices in a specific location. 

Example Deployment Scenarios

Single Location (ex. Flat)

A simple deployment, where the customer receives internet service at home. In CRM there will be one client, a real person, with a single service. That service is paired with a specific Subscriber in UISP. The Subscriber might contain:

  • One CPE, connected to an AP which is assigned to another Site.
  • Behind that CPE there could be an airCube, for example, which also belongs to the Subscriber.
  • Or instead of the airCube, there might be a 3rd party WiFi router that belongs to the customer. A network element such as a WiFi router can be added to UISP as a 3rd party device.
  • Instead of the CPE, the client might have an Optical Network Unit (ONU) like the UFiber Nano G or UFiber loco, connected to an Optical Line Terminal (OLT) such as UFiber OLT or UFiber OLT 4, which is inserted into a Site.
User Tip:
For simple, inexpensive installations it is effective to use the airCube ISP (ACB-ISP). For classic installations where a mesh WiFi network needs to be supported, we would recommend the airCube AC (ACB-AC)

Larger Area (ex. Farm)

A farm, a hotel, or a school are classic examples of a more complex customer. From the CRM point of view, it is one paying Client, with a single Service for internet provision. In this example, it is necessary to have all devices which the Client owns, assigned to only one Subscriber. 

NOTE: For customers with more complex networks it is possible to use EdgeMAX, airMAX, and other devices: it is just not the primarily supported scenario. For example, using such device configuration may cause the dashboard of that Subscriber to be rendered sub-optimally.

Multiple Locations (ex. Chain Store)

A chain store is an example of a deployment where a single customer has several locations at a considerable distance with an internet connection. In this case, it is suggested to create separate Services in CRM for each location and pair them with Subscribers in UISP. Each branch of the chain store can be then treated as a "simple flat" or a more complex "larger area" as described in the previous examples.

Repeater Point

The repeater point is a relatively common scenario that can be confusing at first glance from the UISP configuration perspective. From the geographical perspective, however, it is a single location, for example, a family house roof with both a PtP connection as well as an AP for local coverage. At the same time, the house itself is connected to the internet. In such cases, it is recommended to model the deployment in such a way that the end of the PtP and AP belong to a Site in this location. The customer's own devices inside the family house belong to a Subscriber, which will have the same address as the aforementioned Site.

User Tip:
It is important to mention that UISP doesn't support a situation where two Subscribers are connected to each other. To make the structure clear and readable, the Subscriber must always be an endpoint in the network topology. Sometimes it will be necessary to create an artificial duplicate Site, just as described in the repeater point example.

UISP Key & Device Registration Process

Introduction

Here we discuss details about the UISP generic key and how it works, as well as describing the fundamentals of the device registration process. The purpose of the UISP key is to provide secure communication using AES encryption while telling a device where to look for a UISP console (server). The process of device registration using the generic UISP key and the device-specific UISP key ensures secure communication between the user's devices and UISP.

NOTES & REQUIREMENTS This article applies to the following firmware versions: EdgeRouter: 1.9.7+ /EdgeSwitch: 1.7.3+ / UFiber OLT: 1.0.0+ / airMAX (AC): 8.4.1+ / airMAX (M): 6.1.3+ / airCube: 1.0.0+
Also please note that UISP doesn't support older airMAX devices with firmware versions 4.x, 5.x, or 7.x.
ATTENTION: For security reasons, never share your UISP key publicly. If you need to share it for whatever reason, always obscure the hostname and AES string parts of the key

UISP Generic Key Details

Here is an example of the UISP key:

wss:// your.domain.com :443 + n9yU137QSwTzBXnF...9Sk0pC7sDKGnpbxiHRI9W +

The UISP key consists of several parts, each with its own purpose. In the table below, the UISP key is split apart, and each part's purpose is described:

Key Part Purpose
wss:// WebSocket Secure connection protocol
your.domain.com Hostname or IP of the console (server) where UISP server is running
:443 Port for devices to access UISP server
n9yU137QSwTzBXnF...9Sk0pC7sDKGnpbxiHRI9W Advanced Encryption Standard key (AES key)

 

Behind the Scenes: How Does the UISP Key Work?

When a new instance of UISP is installed, it creates its own UISP key which is called The Generic UISP Key. This key represents a pointer for any device being added to the system for the first time. When the generic UISP key is entered into a device's settings, that device will try to connect to UISP using the hostname / IP and the port part of that key (see the third row of the table above).

If the connection is successful, the AES key part of the UISP key is used for secure communication between the device and UISP. When the connection is established for the first time then a new AES key is generated for the device. This new AES key replaces the original AES key in the generic UISP key, creating The Device Specific UISP Key. Then the device-specific UISP key rewrites the generic UISP key on the device and UISP stores the device’s MAC address and AES key in the PostgreSQL database.

From that point forward, each time the device wants to communicate with UISP, the AES key part of the device-specific UISP key is used and UISP uses the AES key from the PostgreSQL database for decryption/encryption.

How to Manually Register a Device via Device UI

This is only necessary for devices that cannot be found via the UISP Remote Discovery tool.

1. Open UISP and go to the Settings -> Devices section.

2. Expand the Devices Adoption section and click on the Copy UISP key to clipboard link to copy the key, which will be used again in step 5. The generic key is the same for all devices.

3. In your browser type in the IP address of the device, which should open the device's login screen. Insert the correct credentials and you will get to the Device administration screen.    

4. Go to the System or Services section.

5. Paste the UISP key.

6. Enable the UISP connection.

7. Save the device configuration.

8. Now you can go back to the UISP and check the 'devices' table. You should see the newly added device there. Authorize the device in the UISP devices list and assign it to a Site or Subscriber

How to Register a Device via SSH

EdgeMAX

admin@ER-X:~$ configure
admin@ER-X# delete service unms disable
admin@ER-X# set service unms connection wss://XX.YY.ZZ.XX:XX+XYZYXZYXYZYXZYXYZXZYXZ+allowSelfSignedCertificate
admin@ER-X# commit
admin@ER-X# save
Saving configuration to '/config/config.boot'... Done

Please replace the [wss://XX.YY.ZZ.XX:XX+XYZYXZYXYZYXZYXYZXZYXZ+allowSelfSignedCertificate] with the actual generic UISP key of the UISP application.

airMAXthe

Danger: Be extremely careful when changing airMAX devices configurations There is no validation before this manual change applies and a mistake in configuration may lead to losing connectivity to the device.

1. Edit device configuration in file /tmp/system.cfg

unms.uri=wss://XX.YY.ZZ.XX:XX+XYZYXZYXYZYXZYXYZXZYXZ+allowSelfSignedCertificate
unms.uri.changed=wss://XX.YY.ZZ.XX:XX+XYZYXZYXYZYXZYXYZXZYXZ+allowSelfSignedCertificate
unms.status=enabled

2. To apply the configuration use command /usr/etc/rc.d/rc.softrestart save

Remote Discovery

Introduction

The UISP Remote Discovery feature is a system designed to find devices in your network and easily adapt them to the UISP application. There are two methods used to discover devices:

  • Scan from the UISP Search for devices in the network(s) connected to the UISP console.
  • Scan from Devices Search for devices from other currently connected/adopted devices.

The second option allows UISP to discover devices inside private network ranges or behind NAT. It is even possible to automatically upgrade the firmware of a device if it does not meet the minimum requirements. The Scan from Devices option is especially useful for UISP Cloud users as it allows you to automatically discover and connect to local LAN devices from the Cloud.

Firmware & Device Requirements 

NOTE:To perform Remote Discovery, UISP is primarily using an EdgeRouter configured as a UISP Gateway router. But in case there is no such device in the local network, any airMAX AC device with the necessary firmware version can also be used instead. 

The Device Discovery feature is compatible with the latest firmware releases of EdgeMAX and airMAX devices. The minimum required firmware versions are:

  • EdgeRouter v2.0.8+
  • airMAX AC v8.0.7+
  • EdgeSwitch v1.9.0+

The Device Discovery Process

Remote discovery is running automatically in the background searching for all available devices. When first signing up and creating a UISP Cloud instance, for example, you are asked to add a device. If you add an EdgeRouter (with firmware v2.0.8+), UISP can then use the EdgeRouter to discover other devices in the local network (LAN). 

The UISP Remote Discovery feature can be configured from the Settings > Devices > Discovery Settings section. The default settings are set automatically, but you can customize the options:

  • Allow unsecured channels By default, the Discovery manager will only send device credentials over secured channels HTTPS/SSH. This option allows discovery to use unsecured channels (e.g. HTTP), but only for private IP address ranges.
  • Scan from UISPSearch for devices in the network(s) connected to the UISP console (server).
  • Scan from Devices Search for devices from other currently connected/adopted devices.
  • SNMP community The SNMP community string (set to public by default).
  • Hide third party devices Hide non-Ubiquiti devices from the scan results.
  • Discovery notifications Enable a discovery popup toasts.
  • Blacklist IP addresses and subnets that should be ignored by discovery.

The UISP Remote Discovery feature is running automatically in the background searching for all available devices within the IP ranges defined in the  Settings > Network > Addresses > Monitored IP subnets section. Initially, it checks if there is a gateway available in each range and if such gateway is found the range is scanned again with higher priority.

When any IP change is detected by UISP, for example when a new device is connected or when the Monitored IP subnets are changed, the scan is initiated again. This re-scan is also performed periodically in set intervals.

Connecting Devices in Private IP Range

Introduction

Sometimes you may feel forced to rewrite the FQDN in your generic UISP key with an IP address, in order to connect a device inside your network to UISP. In this situation, it is often useful to check if there is a correct source NAT set on your gateway. In this article, we will explain what is going on and how to fix the situation. 

Network Diagram

topology.png

Setting the NAT

In the schema above, the domain myuisp.com is set up on 203.0.113.1 and there is a redirect on the gateway from 203.0.113.1:443 to 192.168.1.20:443. If the address myuisp.com is opened from the airMAX device it will not work.

The reason for that is that the airMAX device asked DNS to translate myuisp.com and it received the public address 203.0.113.1. When the first packet is sent there the gateway router (EdgeRouter 4 in this example) intercepts the packet and rewrites the destination IP to 192.168.1.20 (UISP console). The UISP console (server) gets the packet and it replies with an ACK packet (acknowledges the connection) which travels to a sender address - 192.168.1.21 (airMAX device). But the airMAX device sent a request to the 203.0.113.1 server and that server never answered, so that connection eventually times out. Instead, the airMAX device receives an ACK packet from 192.168.1.20, which the airMAX device never tried to contact so that packet is discarded. 

The solution to this issue is to add a rule to the gateway which will NAT all packets going to 192.168.1.20. Here is a guide on how to set up Hairpin NAT on the EdgeRouter.

Topology View

In order to provide advanced features and tools, UISP needs to recognize and have details about all the elements of the network. In order to do that, UISP automatically creates datalinks for Ubiquiti devices (see table below for minimum firmware version needed). For networks with Ubiquiti and 3rd party devices, it is strongly recommended to add all 3rd party devices and their datalinks to UISP manually.

The topology map represents a real, physical structure of a network. This is why virtual connections like VLAN or VPN are not supported yet. It is possible to generate the map by manually creating all datalinks; but ideally, UISP should generate them automatically.

User Tips:Please note that a correct topology map is essential for some advanced features in UISP.

The first recommended step for the automatic generation of a topology map is to define the Gateway in UISP settings. Alternatively, it is possible to manually define datalinks between a gateway device and the Internet by drag and dropping the required Site from the left panel to the internet Icon. Once that is done, UISP recognizes the first device of the network, gets information from it, and will proceed to explore the rest of the network automatically.

If there are 3rd party devices in a network, then it is critical to add them manually to UISP in order to complete the topology map. Device discovery can be used to gather all necessary data about 3rd party devices through SNMP.

NOTE:It is critical to have all devices (including 3rd party devices and even unmanaged switches) in the topology map. UISP performs checks to make sure there is precisely one connection for each Ethernet port, making it impossible to correctly generate the topology map if some devices (even unmanaged switches) are left undefined.

In order for Topology View (i.e., automatic datalink generation) to work successfully, Ubiquiti devices need to have a certain minimum firmware version. Here is a complete list:

Platform

Ethernet

Wireless

GPON

EdgeRouter

2.0.4+ (EP-R6 in switch mode from 2.0.7+)

   

EdgeSwitch

1.9.0-alpha.1+

   

EdgeSwitch X

1.1.0+

   

EdgeSwitch XP

(ES-5XP / ES-8XP / ES-16XP)

2.0.0-alpha.1+

   

UFiber

3.2.0-beta.1+

 

1.0.0+

EdgePower

1.4.0+

   

EdgePower X

1.3.0+

   

airMAX M

6.1.9+

6.1.3+

 

airMAX AC

8.5.12+

8.4.1+

 

airFiber LTU

1.3.0-beta.1+

1.0.0+

 

airFiber

4.0.5-alpha.2+ / 4.1.0-beta.7+

4.0.5-alpha.2+ / 4.1.0-beta.7+

 

airCube

2.5.0-beta.2+

1.0.0+

 
ATTENTION: The most common mistakes include an undefined path to the Internet or a missing datalink between some points. You can identify this issue visually whenever you see a Subscriber on the left side of the map. When configured correctly, there is either an Internet icon or a Site on the left side of the map.
Was this article helpful?
566 out of 893 found this helpful