UniFi Video is an obsolete product line.

This application and its related devices will no longer receive any manner of technical support, including functional and security updates. Additionally, there will be no further updates to Help Center content pertaining to UniFi Video.

UISP - Troubleshooting

Overview

This article addresses the most common issues related to UISP and provides instructions on how to solve them. To contact the UISP support team, and send them your UISP support info please create a support request. Please attach your support info to the request (if applicable). 

Note:  If you already have an open ticket about your issue, you can just reply to the last email you received from our support team and send the support info or any other additional information and requested files.

Table of Contents

My UISP doesn't start

Back to Top

UISP runs in docker containers. For that reason, the first step should always be to check on those containers by running the sudo docker ps command. In case, any container is failing, please run this command sudo tar -cvjSf /tmp/uisp-logs.tar.bz2 /home/unms/data/logs, download the uisp-logs.tar.bz2 file from the /tmp folder. and attach it to a support request as described in the Overview above (or send it as a reply if you already have an open ticket).

My device cannot connect to UISP

Back to Top

Each device needs to have a clear route to the UISP console in order to connect. There are three basic tools that can be used to check if the route from the device to UISP is free. Please note that some of those commands may be inaccessible on some devices

  1. ping
  2. traceroute
  3. curl

1, Use SSH to get into the device and try to ping the hostname of the UISP console. If the ping cannot go through, there is a network issue either in the device's configuration or on the route from the device. The connection can be also impossible if there is any packet loss or high latency (over 400ms).

Here are the other two commands that can be used to get more information about the network issue. . Replace the <UISP hostname> with the actual hostname of your UISP console and remove the <>:

2, Traceroute from the device to the UISP console:

traceroute -n <UISP hostname>

3, Check if the connection is upgraded 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://<UISP hostname>/

The output should look like this:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: qGHgK3En71di5rrssAZTmtRTyFk=

db332780afad264425162cb11d19ffd1ac9ad3658f63cb56968a8a2592054a39aac950bcdae301e39eea75f28c7d3e7dd32a568f0fcf67f25b692434c825ffc7d13b7f8bcec1fb649919d784723f039ef50deb939eeb2b1bd602f56339ac20b65b3

If the device can ping the UISP hostname but it cannot connect anyway, please send us the output of these tests as well as support info of the device and your UISP. In order to send those files please follow the guide above.

My devices' connections are flapping

Back to Top

Note:  A flapping connection occurs when the device is repeatedly switching status from "Active" to "Disconnected", often within a narrow time frame.

As a first step, it is necessary to find out if the flapping is being experienced by the customers as well. If they are getting outages of internet service, then UISP is reporting the actual status just as it should. If customers report stable connection, the flapping is most likely caused by devices having issues connecting to the UISP console correctly. The two most common reasons for that are network issues and overload.

  • How to verify if it's a network issue: SSH into one of the flapping devices and run at least one hour-long ping pointed to the hostname of the UISP console. You can use this command
    ping -q -w 3600 your hostname here > /tmp/ping_result.txt &
    Please note that this command will run for an hour in the background. You need to wait before the ping's output will be saved in the ping_result.txt file located in /tmp folder. After the hour please check if there is any packet loss and/or latency over 400ms. If there is any packet loss or high latency then the flapping is caused by the network instability. For the UISP Cloud instances, please contact us as described in the Overview of this article, and in the Description let us know where the flapping devices are located (the country is sufficient).
  • How to verify if it's an overload issue: Check both the UISP console and the device for CPU and RAM load. For the UISP Cloud instances, please contact us as described in the Overview of this article, and in the Description let us know we need to check the load on the server. The device can be checked with the top command. 

It is also possible that the restart of the UISP will help. For self-hosted UISP instances, the restart can be done via CLI command, and for UISP Cloud users, there is an option to visit the UISP Cloud Access Portal and click on the restart button at the bottom of the screen.

Suspension / Traffic shaping is not working

Back to Top

For all advanced network features, UISP needs to know which IP address should be suspended/shaped. It is possible to check if the UISP knows that IP by opening the Devices view and clicking on the Subscribers tab. In the IP address column, there should be an IP address of the shaped/suspended device. In case the desired IP address is not present on that screen then:

  • Make sure that the desired IP address is not also the management IP address of the device. This is mostly relevant for devices in the bridge mode since those devices often have only one IP and it is the management one.  There are several ways of solving this situation. One of them is to connect a Ubiquiti device downstream from the CPE, add that device to UISP and then Suspend/Shape its IP address. Another way is to switch the device into a Router mode so that it has more IP addresses than just the management one. Lastly, it is possible to create a 3rd party device in UISP with the static IP address of the Client's downstream device. Please note that this will not work for 3rd party devices with dynamic IP.
  • Check the Settings > Network > Monitored IP subnets. The desired IP has to be in the range of this setting. 

If everything seems to be configured correctly, please select one specific device, note its IP address and use the method described above to send us that device's support file, the noted IP address, and backup of the EdgeRouter device used as UISP gateway.

NetFlow is not working

Back to Top

Please note that there are two places where NetFlow is displayed. In the CRM module within the Client dashboard, and on the dashboard of a Subscriber (at the top left corner of the traffic graph). For NetFlow, there are the same rules as for the other advanced network features (suspend, shaping). UISP has to know which IP to measure, that IP needs to be assigned to a specific Subscriber, and it has to be within Settings > Network > Monitored IP subnets range. Also, it is necessary to configure at least one router to provide NetFlow data to UISP. The ideal device for this is the main gateway since in most networks all the data is going through it. In case of issues with NetFlow, it is necessary to make sure that the router is sending Netflow data to the correct IP address and port. In our NetFlow article, there is a generic troubleshooting guide on how to perform that check.
In case the router is indeed sending NetFlow data to UISP but it is not displayed anyway, please send us a screenshot of the monitored subnets settings, and NetFlow settings. Then select one client that is not displaying the NetFlow data and send us a screenshot of the corresponding Subscriber's dashboard, the IP address of the device assigned to that Subscriber, and a screenshot of the Subscriber tab inside the Device view (make sure that the column IP address is enabled). Lastly, we need support info from the UISP and the client device. 

My Device is refused (AES key)

Back to Top

To understand this issue it is necessary to have a basic knowledge of the generic UISP key. When there is a mismatch between the AES key of the device and the record in the UISP database, the device will be refused immediately after connecting with the error message "Peer closed connection". There are two possible reasons:

  1. There is a generic AES key on the device but a specific AES key in the UISP database.
  2. There is a device-specific AES key in the device but no record of that device in the UISP database.

As a first step try to search for the device in UISP by using its IP or MAC address. If there is a record of the device UISP, then it most likely has the triangle error icon by its name and there should be the "Reset UISP key" button available for that device. Clicking on the button will reset the device-specific AES key recorded for that device's MAC address in the UISP database. The device should then connect automatically.  If not, then delete the device from UISP and insert the generic UISP key into its interface.
In case the device had no record in UISP then go to the "Devices" view and look for the "Add device" button. Click on the arrow next to that button and then click on the "Copy UISP key to the clipboard" link. Now you have the generic UISP key in your clipboard and you can insert it into your device. 
In case nothing helps, please contact us as described above. Make sure to include support info from the device and UISP. 

SMTP server not working

Back to Top

Listed below are some important settings and details when using a Gmail account for the configuration of the SMTP server in UISP. In order to receive email alerts from UISP, the SMTP server has to be configured. 

  • We recommend enabling the 2-Step-Verification and generating an App password, which will be then used in the password field. 
  • If the Organization email is different from the Sender address in mailer settings, the outgoing emails may be limited or rejected on some SMTP servers. Note that the Organization email address is used in the email header attribute From (this will make the email look as if it came from that Organization's email address).
  • If the Organization email is different from the Sender address in mailer settings (which is typical for personal SMTP account email), it may cause the sending will fail on some SMTP servers.
  • Gmail SMTP server can use a different address or alias (other than the username of that particular Gmail account) but it is necessary to configure that address in the user's Gmail settings. See the Send emails from a different address or alias help article to learn more. Otherwise, the header attribute From will be replaced by the account user's username.
  • Personal Gmail accounts can send a maximum of 500 emails in a day and G Suite accounts can send a maximum of 2000 emails in a day. We recommend setting the Throttler configuration to accommodate these limits.

Google Maps not working (API key)

Back to Top

Here we discuss how to allow self-hosted UISP Application instances to display Google Maps and how to set up a Google API key. UISP Cloud instances do not have to configure a Google Maps API Key since it is already set up using Ubiquiti's own API Key.

ATTENTION: Since July 16th, 2018 it is mandatory to enable billing with a credit card and have a valid API key for all Google projects.

Before Google Maps API can be used, you must make sure the required APIs are enabled in your Google API console.

To view your list of enabled APIs:

  1. Go to the Google API console.
  2. Select or create your project.
  3. First, go to the Dashboard and click on the 'Enable APIS and Services' button. You will see a list of different APIS. Use the search box to find Geocoding API, Maps Elevation APIMaps JavaScript API, Places API for Web and enable it. 

To create the API Key, follow the steps listed below:

  1. Go to the Google API console.
  2. Select your project.
  3. Select Create credentials and API key in the corresponding menu.
  4. Your API key will then be created and you can use it in Settings → UISP → Google Maps API Key. UISP Cloud instances will not have this option since users will not have to configure this themselves: it has already been set by default using our own Google Maps API key.
  5. If you want, you can restrict the key to your domain to prevent unauthorized use and quota theft.

UISP Cloud - Common Issues

Back to Top

Here we list the most common issues encountered by users when using the free UISP Cloud accompanied by the recommended steps to solve them.

User Tips: Check the Ubiquiti System Status page to determine if there is an outage or if the UISP Cloud service is running.

UISP Cloud - Forgotten Password

It is important to distinguish between the local password of the UISP Cloud instance (<your hostname>/uisp.com) and the log-in to the UISP Cloud Access Portal (uisp.com). The Access portal is where the Cloud instance is managed and it uses the UI Account credentials (the same credentials which are used to access Ubiquiti community forums).Local UISP Cloud instance passwords can be managed by clicking on the Manage UISP users icon located at the bottom of the page.
user_management.png
This will open a popup window with a list of UISP users present in this UISP Cloud instance. 
password_reset.png
Select the user that needs a password reset and click on the three-dot menu on the right. An option to reset the password will appear. The same method can be used to disable two-factor authentication (2FA).

ATTENTION: In case the local login is not working, make sure that the email address was not used instead of the login name.

UISP Cloud - Single Sign-On Authentication failed

If there is the error message Authentication failed please click on the arrow at the top left to go back to the main login screen and use the Sign in with the local account link. It is possible to change local account credentials through the method described above. 

ATTENTION: In case the local login is not working, make sure that the email address was not used instead of the login name.

This error is most likely caused by disabled UI Account access for the specific user. When local credentials are used to access UISP, please go to Settings -> Users edit the specific user, and enable the Ubiquiti single sign-on. 

UISP Cloud - The UISP instance is Missing

If there is no active instance present when the UISP Cloud Access Portal is opened and there is no record of any UISP instance, do not worry. We keep data backups for at least a month. Please use the Ubiquiti support request form, provide the hostname of the instance, and we will recover the instance to the state before it was suspended.

UISP Cloud - The Application is Stuck in a Restarting Loop

There may be several causes for this, but there is no reason to worry. Cloud data is backed up on UISP servers for at least a month. Please use the Ubiquiti support request form, provide the hostname of the instance, and the Ubiquiti community username and we will make sure the UISP instance runs again.

UISP Cloud - The Controller is Missing Devices

In order to use the free UISP Cloud, you must connect and maintain:

  • At least 1 active Ubiquiti device within the first 24 hours of using this service.
  • At least 10 active Ubiquiti devices in total after 30 days and onward.
Note:  Only active Operator Ubiquiti devices count towards this limit. This means that any 3rd party devices, UniFi devices, devices without required up-to-date firmware, and also End-of-Life (EOL) devices do NOT count towards this limit.

In order to continue using this free service, you must keep your devices connected and active, otherwise, they are not counted towards this limit. In case any device is disconnected it will be still counted as active for up to two days. If that device connects within those two days—even for a second and then disconnects again, the timer resets, and the two-day grace period starts again. When the minimum device limit is not met, there will be a notification on the UISP interface and the system will send an email message. If the device limit is not met, then the Cloud controller will be disabled and eventually deleted.

Please note that in such a case, it is possible for others to use the hostname for their own instance. Make sure to reclaim the hostname at your earliest convenience to avoid this situation. The longer the hostname is not used the bigger the chance someone else may pick it up.

UISP Cloud - After logging in, there is a "UISP is starting" message with a picture of a rocket

This means the UISP application is having some issues starting. If you see this for a prolonged period of time please contact our support by using the Ubiquiti support request form, and let us know the hostname of the instance. We will analyze and fix the situation.

Any other issue

If there is an issue we did not list here, feel free to contact us by submitting a request. Feel free to attach screenshots (ideally of the whole screen) since they are often useful to give us a clear idea of the situation at hand, and as much description as possible.

Ping, Latency & Outages Guide

Back to Top

Introduction

User Tip: There is a global ping setting in UISP options but you can overrule it for an individual device if necessary. Click on the device in the Devices section and a right panel will open. Click on the Manage tab, expand the Advanced section, enable the Device specific settings to change the ping address. 

In this guide, we will talk in detail about how exactly UISP uses ping for several different purposes and how outages are configured.

Ping Interval

Firstly let's talk about different ping tests in UISP:
Latency ping: In order to measure a device's latency UISP can instruct that device to send a ping. By default, such ping is targeted to the UISP server, but users can redirect it to anywhere else. When the route is set to a different location and the ping target is unreachable, the device's status will remain "Active" because the Monitoring PING is still going through. The situation will be visibly highlighted in the device's Latency graph (a Latency outage).

Note: It is possible to further configure the Latency ping interval in the Settings > Devices > Ping Settings section.

Monitoring ping: There is a WebSocket channel opened between a device and UISP and both sides are periodically checking if the connection is healthy. If they cannot see each other for a user-specified amount of time, an outage is created and that device status is changed to "Disconnected".
Ping Address: By default, the value of this setting is the same as the UISP hostname. It is, however, possible to change this address and ping a different target for latency reading. In order to measure the Latency ping to the Internet precisely, we suggest using 'ping.ubnt.com' in this field.
Ping interval (default): This value represents a period of time between Latency ping attempts while a device is running normally.
Ping interval (outage): This value represents a period of time between Latency ping attempts while a device is reporting a Latency outage. The idea is that a user probably wants the ping to be more frequent in case of a Latency outage so that the Latency graph is filled with accurate latency values as soon as possible.

PING for 3rd party device: This ping is actively sent from the UISP console (server) in order to monitor the connection to a third-party device. Optionally enable this setting in the device-specific settings for a third-party device.

Outage Settings

User Tip: In order to receive email alerts about an outage, users have to opt-in for alerts by checking the Alerts checkbox in the Settings > Users > Users.

This configuration influences how the Monitoring Ping behaves. Each value defines a time interval after which a device is considered to be in an outage state after the Monitoring Ping failed. There are different times according to some situations as described below:

Running device reportable outage: This value represents a time interval after which a device is considered in an outage state if it was running normally before.

Restarting device reportable outage: This value represents a time interval after which a device is considered in an outage state if it was in the process of restarting before.

Upgrading device reportable outage: This value represents a time interval after which a device is considered in an outage state if it was being upgraded before.
E-mail report to include outages over: This value represents a time interval after which UISP sends an actual email alert after the Outage status is activated on a device.

Note: When a device is in maintenance mode, no outage is reported and no email alerts are sent.
Note: By default, outages are created for devices attached to Sites and are disabled for devices connected to Subscribers. If alerts are enabled for a Subscriber, though, then for devices attached to such a Subscriber, outages are created as well. 

Was this article helpful?
42 out of 131 found this helpful