Get started
Login
© 2024

Troubleshooting device connectivity

Devices within a tailnet can communicate using one of two types of connections:

Ideally, all devices would use direct connections, but a direct connection isn’t always possible. Sometimes, a device might use a relayed connection even though a direct connection is possible, which can cause performance problems. You can determine the connection type of a device using the tailscale status command.

If a device uses a relayed connection instead of a direct connection, you can troubleshoot why using the tailscale netcheck command.

The tailscale netcheck command returns information about a client’s current network connection. The information comes from STUN and the Tailscale client running on the device and can help you troubleshoot connectivity issues. For example, you can use the tailscale netcheck output to troubleshoot why a client might use a DERP relay server instead of a direct connection.

What is STUN?

STUN allows a device to determine its public IP address and the type of NAT it is behind, which is essential for establishing direct communication between devices on different private networks. STUN uses a client-server architecture model. The STUN client sends requests to a STUN server, which responds with the client's public IP address and port number.

Tailscale uses STUN (session traversal utilities for NAT) to enable direct communication between devices behind NAT firewalls or routers. The Tailscale client running on a device functions as the STUN client, and the DERP relay servers function as the STUN servers.

The Tailscale client sends a STUN request to all the DERP relay servers, and the DERP relay servers note the public IP and port it received the request from. Tailscale uses this information to determine how to traverse the NAT the client is behind. You can get this information using the tailscale netcheck command.

To better understand how Tailscale connections work, read How Tailscale works and How NAT traversal works.

The tailscale netcheck output includes the following fields:

UDP

The UDP field indicates whether the device can send outbound UDP packets.

ValueMeaningInterpretation
TrueThe STUN servers have received outbound UDP packets.The device has outbound connectivity, which is critical for getting direct connections.
FalseThe STUN servers haven’t received outbound UDP packets.The device doesn’t have outbound UDP connections and likely isn’t using direct connections.

IPv4

The IPv4 field shows the device's public IPv4 address and port number.

ValueMeaningInterpretation
Yes, <IPv4 address>The device has a valid IPv4 address and port number.The device has outbound connectivity, which is crucial for direct connections.
NoThe device doesn’t have an IPv4 address.If there’s no IPv4 address, the device doesn’t have network connectivity.

IPv6

The IPv6 field shows whether the device supports IPv6. It includes the device’s public IPv6 address and port number if it does.

ValueMeaningInterpretation
Yes, <IPv6 address>The device has an IPv6 address and port number.The device has outbound connectivity, which is critical for getting direct connections.
NoThe device doesn’t have an IPv6 address, but the operating system supports IPv6.The device either doesn’t have outbound connectivity or is using IPv4.
No, but OS has supportThe device doesn’t have an IPv6 address, and the operating system doesn’t support IPv6.The device doesn’t have IPv6 support and might or might not have outbound connectivity using IPv4.

Mapping varies by destination IP address

The MappingVariesByDestIP field states whether the device’s IP address differs between DERP relay servers. It’s the most important field to determine why a device isn’t using direct connections.

ValueMeaningInterpretation
TrueThe device’s IP address and port number combination varies between DERP relay servers.If two DERP relay servers return different results, it indicates that the device is behind a hard NAT that randomly selects the port IP address and port number combination. Hard NAT makes it difficult for Tailscale to enable direct connections, so the device is likely using a DERP relay server.
FalseThe device’s IP address and port number combination are the same across DERP relay servers.If all DERP relay servers return the same result, it indicates that the device either has no NAT or is behind an easy NAT. The device is likely to use direct connections.

When Tailscale initiates a connection, it contacts multiple DERP relay servers to obtain the outbound IP address and port combination. Each DERP relay server reports this information back to Tailscale.

If the outbound IP address varies between DERP servers, it indicates that the device is behind a NAT that varies the IP addresses between destinations. This is sometimes referred to as hard NAT.

If the outbound IP address is the same between DERP servers, it indicates that the device is behind an easy NAT or no NAT.

It’s difficult to distinguish between an easy NAT and no NAT. In the cases where a device has no NAT, the device itself has the same public IP address that it reported to the STUN servers, as well as predictable ports. In many scenarios, this means the public interface is directly attached to the client on which Tailscale is installed. However, this doesn’t always mean the IP address is available locally in the operating system. In some scenarios (such as with AWS EC2), the public IP address is not available directly in the operating system but is attached directly to the host.

Port mapping

The PortMapping field indicates which port mapping protocols the current device supports.

ValueMeaning
UPnPThe current device supports port mapping using UPnP.
NAT-PMPThe current device supports port mapping using NAT-PMP.
PCPThe current device supports port mapping using PCP.
FalseThe current device doesn’t support any of the three port mapping services.

The device likely cannot use direct connections if the value is false.

UPnP, NAT-PMP, and PCP are all different mechanisms that allow a device behind a NAT to open external ports to help with direct connections.

If the PortMapping field is false, the device cannot open external ports behind the NAT device, which makes creating direct connections difficult and likely leads to a hard NAT circumstance.

If the device supports any of the three port mapping protocols, it might be able to use direct connections, even if the IP address varies between DERP relay servers (that is, MappingVariesByDestIP is true).