NAT traversal

NAT traversal is the set of techniques that let two devices connect directly even though both sit behind network address translation (NAT). Most devices don’t have a public IP address of their own. A home router, office firewall, or mobile carrier shares one public address among many devices, and only lets in traffic that answers something a device sent out first. That keeps unsolicited traffic out, but it also means two devices behind different NATs can’t connect to each other the ordinary way.

How Managed Nebula gets through NAT

1. When DNClient starts, the host connects to the network’s lighthouses and tells them its local addresses. The lighthouse also sees the public address and port the host’s NAT assigned, which the host has no way to see itself.
2. When a host wants to reach another host, it asks a lighthouse for every address that peer might be reachable at: its public address and port, and its local addresses.
3. The lighthouse also tells the peer who’s trying to reach it, and both hosts send UDP packets toward each other. To most NATs and firewalls, the incoming packets look like replies to traffic that just went out, so they’re let through. This is UDP hole punching.
4. Hosts try every address they learned, so two hosts on the same LAN end up connecting over their local addresses instead of going out to the internet and back.

Once a path is open, the hosts complete the handshake and traffic flows directly between them as a peer-to-peer connection. Ordinary hosts don’t need any inbound ports opened or forwarded. Only lighthouses and relays need a UDP port that other hosts can reach.

When hole punching fails

Some NATs can’t be punched through. A symmetric NAT uses a different public port for every destination, so the address a lighthouse learned for a host doesn’t work for anyone else. Carrier-grade NAT on cellular networks often behaves this way, and some firewalls block outbound UDP entirely.

For these cases, traffic goes through a relay. By default every lighthouse in the network, including the managed lighthouse, also acts as a relay, and you can add dedicated relays of your own. Relayed traffic stays end-to-end encrypted between the two hosts, so the relay can’t read or change it.

Tuning NAT traversal

A few config overrides adjust how hosts find each other:

• punchy.delay and punchy.respond_delay change the timing of hole punching, which can help with NATs that are sensitive to the order packets arrive in.
• lighthouse.local_allow_list controls which local addresses a host reports. Hosts running Docker, for example, report Docker network addresses that no other host can reach. See Configuring hosts with tags.
• preferred_ranges tells a host which underlay ranges to prefer when a peer has several addresses.