This article is meant to help resolve errors concerning STUN connectivity between the UniFi managed devices and the UniFi Network Controller.
NOTES & REQUIREMENTS:
In order for STUN to work properly, the client devices need to be able to resolve to and communicate over UDP port 3478 with the UniFi Network Controller. UDP Port 3478 must be open inbound on the controller machine.
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 Controller 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 that might read something like: "This device is not able to connect to the internal STUN server on your Controller. Please check if the device is able to reach the STUN server on port 3478".
This error indicates that the controller is not able to properly connect via the STUN protocol with this particular device, which can prevent some of the features in the UniFi Network Controller 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 Controller. In this case, the controller acts as the STUN server. In order for STUN communication to work properly, the UniFi device must be able to resolve to the UniFi Controller 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 controller UI, as well as to initiate contact and communicate details from the device to the controller.
A number of UniFi administrators may have noticed the sudden appearance of this error after upgrading to UniFi Network Controller software 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 Controller user interface in that software version.
If this issue is encountered immediately after initial device adoption, try refreshing the controller 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 Controller. To resolve this, make sure to open UDP port 3478 on your controller machine firewall and ensure that your router is properly relaying STUN traffic to the UniFi Controller from the UniFi devices.
If you are using your UniFi Controller 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 controller using port 8080.
NOTE: The following directions require the presence of a UniFi Security Gateway to be effective. If you have another router, follow a similar method using the router’s configuration method.
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 your UniFi Controller 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 Controller.
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 controller 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 controller under Settings > Controller:
If the checkbox next to “Override inform host with controller hostname/IP” is checked, make sure the controller hostname/IP is publicly accessible to devices that are being managed outside of your controller’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.