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 to 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)
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 then 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. Save the ping's output and 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 the 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.