diff --git a/docs.json b/docs.json index 5c9392b..7bc6e57 100644 --- a/docs.json +++ b/docs.json @@ -89,6 +89,7 @@ "icon": "desktop", "pages": [ "manage/clients/understanding-clients", + "manage/clients/nat-traversal", "manage/clients/install-client", "manage/clients/configure-client", "manage/clients/update-client", @@ -469,6 +470,10 @@ "source": "/manage/sites/install-kubernetes", "destination": "/self-host/manual/kubernetes/newt/helm", "permanent": true + }, + { + "source": "/manage/sites/configure-site#nat-traversal-tweaks", + "destination": "/manage/clients/nat-traversal" } ], "seo": { diff --git a/manage/clients/nat-traversal.mdx b/manage/clients/nat-traversal.mdx new file mode 100644 index 0000000..4ba692e --- /dev/null +++ b/manage/clients/nat-traversal.mdx @@ -0,0 +1,140 @@ +--- +title: "NAT Traversal" +description: "How clients connect directly to sites or relay through Pangolin, and how to improve reliability" +--- + +import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx"; + + + + + +When a client connects to a site, Pangolin tries to establish the most direct path possible. Clients have two major operation modalities: NAT hole punching and relaying. A client will first attempt to hole punch before falling back to relaying. + +## NAT Hole Punching + +NAT hole punching establishes a direct peer-to-peer connection between the client and site, bypassing the need to route traffic through the Pangolin server. The server coordinates the initial connection by helping both peers discover each other's network addresses, allowing them to establish a direct tunnel through their respective NATs and firewalls. + +For a deeper look at how Pangolin coordinates hole punching between clients and sites, see [NAT Hole Punching in Pangolin](https://pangolin.net/news/nat-holepunching). + +Direct connections typically offer: + +- Better performance (speed and bandwidth) +- Lower VPS transit costs when you self-host + +## Relaying + +If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server. + +Clients can relay traffic through a Pangolin server—through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT hole punching capabilities of Newt. + +Relaying is reliable when direct paths are blocked by NAT or firewall rules, but traffic passes through your Pangolin node instead of traveling directly between the client and site. + + +If you use [Pangolin Cloud](https://app.pangolin.net/auth/signup) and want relayed traffic to stay on infrastructure you control, [self-host a remote node](/manage/remote-node/understanding-nodes). Relayed client traffic then traverses your node rather than Pangolin's shared cloud infrastructure. + + +## Check Whether a Site Is Relayed + +You can confirm whether a connection is direct or relayed from the client. + +### GUI clients + +In a GUI client (Mac, Windows, Android, or iOS/iPadOS), open **Preferences**, go to the **Status** tab, and switch to the **JSON** view. Under each connected site in the `peers` object, check `isRelay`: + +- `isRelay: false` — direct hole-punched connection to the site +- `isRelay: true` — traffic is relayed through your Pangolin server + +Example (values obfuscated): + +```json +{ + "agent": "Pangolin macOS", + "connected": true, + "orgId": "org_example123", + "peers": { + "1001": { + "connected": true, + "endpoint": "203.0.113.10:51820", + "isRelay": false, + "name": "Office Network", + "siteId": 1001 + }, + "1002": { + "connected": true, + "endpoint": "198.51.100.5:21820", + "isRelay": true, + "name": "Remote Lab", + "siteId": 1002 + } + }, + "registered": true, + "version": "0.8.4" +} +``` + +In this example, **Office Network** is connected directly (`isRelay: false`) and **Remote Lab** is relayed (`isRelay: true`). + +### CLI + +On Linux or when using [Pangolin CLI](/manage/clients/install-client), run `pangolin status`. The **RELAY** column shows whether each site is relayed (`true`) or directly connected (`false`): + +```bash +pangolin status +AGENT VERSION STATUS ORG +Pangolin CLI 0.10.1 Connected org_example123 + +SITE ENDPOINT STATUS LAST SEEN RELAY +Office Network 203.0.113.10:51820 Connected 1s ago false +Remote Lab 198.51.100.5:21820 Connected 1s ago true +``` + +Use either view when troubleshooting hole punching or verifying that configuration changes took effect. + +## Improve Hole Punching Reliability + +Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency. + +In some environments, depending on the NAT type and firewall, you may need to tweak settings to get optimal connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make. + +Another option is to keep Newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in your firewall to DNAT to Newt. See [Configure Sites](/manage/sites/configure-site) for the full list of Newt flags and environment variables. + +## FAQ + + + + Hole punching can fail when either side sits behind a restrictive NAT, symmetric NAT, or a firewall that blocks the UDP ports needed for peer discovery. When that happens, the client and site fall back to relaying through your Pangolin server so the tunnel still comes up reliably. + + + + **GUI clients:** Open **Preferences**, go to the **Status** tab, and switch to the **JSON** view. Each entry under `peers` includes an `isRelay` field—`false` for direct, `true` when relayed. + + **CLI:** Run `pangolin status` and check the **RELAY** column for each site. + + See [Check Whether a Site Is Relayed](#check-whether-a-site-is-relayed) for examples. + + + + Yes. Whether the path is direct or relayed, client-to-site traffic is encrypted over WireGuard. Relaying changes the network path, not the encryption of the tunnel itself. + + + + Direct hole-punched connections usually offer lower latency and higher throughput because traffic does not pass through your Pangolin node. Relayed connections add an extra hop through Gerbil, which can increase latency and bandwidth use on the node—especially relevant if you self-host and pay for transit. + + + + You can disable relaying with `disable-relay` in the client config or `--disable-relay` / `DISABLE_RELAY=true` on CLI clients. If hole punching fails, the client will not fall back to a relay and the site may not connect. See [Configure Clients](/manage/clients/configure-client) for details. + + + + Yes. Set `disable-holepunch` in the client config or use `--disable-holepunch` / `DISABLE_HOLEPUNCH=true` on CLI clients to skip hole punching and connect through the relay path. See [Configure Clients](/manage/clients/configure-client) for details. + + + + On self-hosted Pangolin, relayed traffic passes through your own Gerbil instance. On [Pangolin Cloud](https://app.pangolin.net/auth/signup), relayed traffic may traverse Pangolin's shared infrastructure unless you [self-host a remote node](/manage/remote-node/understanding-nodes), in which case relayed client traffic uses your node instead. + + + + Not always. Many networks hole punch successfully without inbound rules. If punching is unreliable, try firewall tweaks from [Tailscale's firewall guide](https://tailscale.com/kb/1361/firewall) or pin Newt to a static port with `--port` / `PORT` and DNAT that port to Newt on the site host. + + diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 031f022..ccfad53 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -59,20 +59,6 @@ Machine clients authenticate with an ID and secret string. These credentials are ## Client Modalities -Clients have two major operation modalities. A client will first attempt to hole punch before falling back to relaying. +Clients connect to sites using NAT hole punching or relaying. A client first attempts a direct peer-to-peer tunnel, then falls back to relaying through your Pangolin server if hole punching fails. -### Relaying - -Clients can relay traffic through a Pangolin server - through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of Newt. - -### NAT Hole Punching - -NAT hole punching establishes a direct peer-to-peer connection between the client and site, bypassing the need to route traffic through the Pangolin server. The server coordinates the initial connection by helping both peers discover each other's network addresses, allowing them to establish a direct tunnel through their respective NATs and firewalls. - -If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server. - -Take a look at [some things you can do to improve reliability](/manage/sites/configure-site#nat-traversal-tweaks) if you are not getting reliable hole punching. - -This should help to: -- Increase performance (speed/bandwidth) -- Reduce VPS transit costs +See [NAT Traversal](/manage/clients/nat-traversal) for how each modality works, how to check whether a site is relayed, and tips for improving hole punching reliability. diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index 2373972..2c156da 100644 --- a/manage/sites/configure-site.mdx +++ b/manage/sites/configure-site.mdx @@ -610,11 +610,3 @@ newt \ --tls-client-key ./client.key \ --tls-client-ca ./ca.crt ``` - -## NAT Traversal Tweaks - -Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency. - -In some environment depending on the NAT type and firewall, you may need to tweak some settings to get optimal connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make. - -Another option is to keep newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in the your firewall to DNAT to Newt.