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).
Table of Contents
- My UISP doesn't start
- My device cannot connect to UISP
- My devices' connections are flapping
- Suspension/Traffic shaping is not working
- NetFlow is not working
- My Device is refused (AES key)
- SMTP server not working
- Google Maps not working (API key)
- UISP Cloud - Common Issues
- Ping, Latency & Outages Guide
My UISP doesn't start
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
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, 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
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
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
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
bridgemode 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
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)
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:
- There is a generic AES key on the device but a specific AES key in the UISP database.
- 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
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 emailis different from the
Sender addressin 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 emailis different from the
Sender addressin 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
Fromwill 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)
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.
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:
- Go to the Google API console.
- Select or create your project.
To create the API Key, follow the steps listed below:
- Go to the Google API console.
- Select your project.
- Select Create credentials and API key in the corresponding menu.
- 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.
- If you want, you can restrict the key to your domain to prevent unauthorized use and quota theft.
UISP Cloud - Common Issues
Here we list the most common issues encountered by users when using the free UISP Cloud accompanied by the recommended steps to solve them.
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.
This will open a popup window with a list of UISP users present in this UISP Cloud instance.
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).
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.
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.
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
Devicessection 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.
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).
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.
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.