This article is meant to help resolve errors concerning STUN connectivity between the UniFi managed devices and the UniFi Network application.
Table of Contents
- What is STUN?
- Why has this error suddenly appeared?
- How to Resolve this Error
- How to Add a STUN Port Forwarding Rule in UniFi
- Verify Proper UniFi Network Inform URL
- Related Articles
A warning sign may be visible next to the Connected device as shown:
If you click on the device and expand the error at the top of the device properties pane you will see a "STUN Communication Failed" error.
This error indicates that the Network application is not able to properly connect via the STUN protocol with this particular device, which can prevent some of the features in UniFi Network like device Debug Terminal from working properly. This document will explain what these errors mean and how to troubleshoot and resolve them.
STUN stands for Session Traversal Utilities for NAT and includes a set of protocols used in networking to better handle communication when going through network address translation (NAT). In simple terms, STUN provides a way for devices to securely communicate with other devices when they're located behind a router. This is necessary because the devices in your network have individual IP addresses that are used to communicate internally, but not known to servers/clients outside of your network. STUN when used by a particular application, will go and initiate a connection with a public STUN server and request to know what address will be used by the STUN server to communicate with the device through its router.
UniFi devices use STUN to properly communicate with the UniFi Network application. In this case, the application acts as the STUN server. In order for STUN communication to work properly, the UniFi device must be able to resolve to the UniFi Network application via the inform URL and communicate with the address via port 3478.
UniFi requires STUN connectivity for a variety of functions, for example, locating devices through the application user interface, as well as to initiate contact and communicate details from the device to the application.
A number of UniFi administrators may have noticed the sudden appearance of this error after upgrading to UniFi Network versions 5.6.x+. This doesn't reflect an issue with STUN on these versions, rather it is bringing attention to a previously existing issue. It is only visible now because the error message itself was added to the application user interface in that software version.
If this issue is encountered immediately after initial device adoption, try refreshing the application page/giving this a few minutes for STUN to properly connect.
In cases where this persists for longer periods of time, this error message most often results from a connectivity issue with STUN from the device to the UniFi Network application. To resolve this, make sure to open UDP port 3478 on the firewall of the machine hosting the UniFi Network application, and ensure that your router is properly relaying STUN traffic to the UniFi Network application from the UniFi devices.
If you are using UniFi Network to manage devices that are not located behind the same router, you will need to set up a port forward similar to how you created one for the inform packets to be forwarded to the application using port 8080.
1. To do this with a USG, go to Settings > Routing & Firewall > Port Forwarding and click "Create New Port Forward Rule" to create a new rule.
2. Fill out these fields similar to the following example, using the IP address of the machine / device hosting the UniFi Network application in the Forward IP field, and UDP ports 3478 in both port fields:
|Name: give the new rule a name to be able to recognize it later.
Enabled: make sure to check the box to "enable this port forward rule" to make it active.
Forward IP: the IP address of your UniFi Network application host.
Forward Port: 3478
Logs: Enable logging if you wish to log activity which can be later retrieved as described in this article.
3. Click “Save” to apply these changes. After some time, or if you restart your device, the error message should no longer be visible.
If after verifying the application firewall is not blocking traffic, you may need to verify that the device hasn’t been configured with an incorrect inform URL. This setting can be found in the Network application under System Settings > Controller Configuration:
If “Override Inform Host" is enabled, make sure the Network application's hostname/IP is publicly accessible to devices that are being managed outside of your application's local network, otherwise this will provide the wrong STUN URL to the UniFi devices. If the hostname/IP would only be accessible locally to the device, uncheck this box and click “Apply Changes”.
Note that 192.168.1.6 is only the IP in this example, yours will likely be a different hostname/IP address.