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.

	Fully implemented
	Partially implemented

Model	Connection	Discovery	Upgrade	Statistics	Dashboard	Interfaces	Configuration
UISP Switch
UISP Router
EdgeSwitch
EdgeSwitch XP
EdgeRouter
UFiber
EdgePower
EdgePoint
airMAX M
airMAX AC
LTU
Wave
airFiber
airFiber 60
airCube
airGateway

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 of the airMAX family. Those CPE devices create the endpoints of the network. On the other hand, a home WiFi router like an airCube will 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: airMAX 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 gateway in a network module. There can be several gateways in the network. 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 NetFlow using an EdgeRouter with firmware 2.0.1. or higher.

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 the CRM client which basically means "customer"—be it an individual or a company.
• Service: One specific internet connection that represents an item on an invoice and is providing 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 also 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 that 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.

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. The general recommendation for this situation is to use Ubiquiti's Enterprise WiFi solution: UniFi. In the future, it will be possible to integrate an UniFi site as a virtual device into UISP and to insert such a device into a Subscriber.

Once that happens, there will be a dashboard of the UniFi site available in UISP with a direct link to the UniFi Controller. Particular devices will not be manageable directly through UISP but only via the link to the UniFi Controller. However, the UISP unified alert system will work seamlessly with this setup.

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.

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.

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 (shown in different colors above), each with its own purpose. In the table below, the UISP key is split apart, and each part's purpose is described:

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

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: