From edec8aa9b8ca247dabe1c4a2e9b58456a313fbd5 Mon Sep 17 00:00:00 2001 From: Owen Date: Thu, 11 Dec 2025 14:39:39 -0500 Subject: [PATCH] Add information about hole punching improvements --- manage/clients/understanding-clients.mdx | 8 +- manage/sites/configure-site.mdx | 114 +++++++++++++---------- manage/sites/install-site.mdx | 6 +- 3 files changed, 75 insertions(+), 53 deletions(-) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 3ff8ac4..5c7752d 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -5,7 +5,7 @@ description: "Create a client to connect to your Pangolin network from a remote A client is a way to access resources on sites remotely and privately via a virtual private network. Clients are used with private resources to faciliate zero-trust network access. -By default a client does not have access to any hosts on the local network of the site. Admins must explicitely define resources on the site and give specific users and roles access to the resources. +By default a client does not have access to any hosts on the local network of the site. Admins must explicitely define resources on the site and give specific users and roles access to the resources. Users must log in and connect from a Pangolin client for [Window, Mac, and Linux](/manage/clients/install-client). Machine (automated systems and servers) connect with an ID and secret. @@ -29,7 +29,7 @@ There are two types of clients: user devices and machines. ### User Devices -A user may download a client for their specific system. Before they can connect, they must select a Pangolin server to authenticate to using their provided Pangolin account. Users can log in as a Pangolin user or with your attached external identity provider. +A user may download a client for their specific system. Before they can connect, they must select a Pangolin server to authenticate to using their provided Pangolin account. Users can log in as a Pangolin user or with your attached external identity provider. Examples include: @@ -40,7 +40,7 @@ Then, just like in the Pangolin dashboard, a user selects the organization to co ### Machines -Machine clients are for servers and automated systems that are not associated with a specific user. +Machine clients are for servers and automated systems that are not associated with a specific user. Examples include: @@ -63,7 +63,7 @@ Clients can relay traffic through a Pangolin server - through Gerbil specificall While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats. -Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve hole punch reliability and performance. +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) diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index daa39be..361f8cb 100644 --- a/manage/sites/configure-site.mdx +++ b/manage/sites/configure-site.mdx @@ -7,15 +7,15 @@ description: "Configure Newt for connecting to Pangolin sites" Newt ID generated by Pangolin to identify the client. - + **Example**: `31frd0uzbjvp721` A unique secret used to authenticate the client ID with the websocket. - + **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6` - + Keep this secret private and secure. It's used for authentication. @@ -23,159 +23,165 @@ description: "Configure Newt for connecting to Pangolin sites" The endpoint where both Gerbil and Pangolin reside for websocket connections. - + **Example**: `https://pangolin.example.com` + + Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports. + + **Example**: `34534` + + MTU for the internal WireGuard interface. - + **Default**: `1280` DNS server to use for resolving the endpoint. - + **Default**: `9.9.9.9` The log level to use for Newt output. - + **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` - + **Default**: `INFO` Interval for pinging the server. - + **Default**: `3s` Timeout for each ping. - + **Default**: `5s` Set the Docker socket path for container discovery integration. - + **Example**: `/var/run/docker.sock` Validate the container target is on the same network as the Newt process. - + **Default**: `false` Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Newt. - + **Example**: `/tmp/healthy` Script to be called when targets are added or removed. - + **Example**: `/path/to/updown.sh` Path to blueprint file to define Pangolin resources and configurations. - + **Example**: `/path/to/blueprint.yaml` Don't fail over to the cloud when using managed nodes in Pangolin Cloud. - + **Default**: `false` Disable clients on the WireGuard interface. - + **Default**: `false` (clients enabled) Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root). - + **Default**: `false` (uses userspace netstack) Name of the WireGuard interface. - + **Default**: `newt` Enable Prometheus /metrics exporter. - + **Default**: `true` Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT. - + **Default**: `false` Admin/metrics bind address. - + **Default**: `127.0.0.1:2112` Enable async bytes counting (background flush; lower hot path overhead). - + **Default**: `false` Optional region resource attribute for telemetry and metrics. - + **Example**: `us-west-2` Enforce certificate validation for health checks. - + **Default**: `false` (accepts any cert) Path to client certificate file (PEM/DER format) for mTLS. - + **Example**: `/path/to/client.crt` Path to client private key file (PEM/DER format) for mTLS. - + **Example**: `/path/to/client.key` Path to CA certificate file for validating remote certificates (can be specified multiple times). - + **Example**: `/path/to/ca.crt` Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead. - + **Example**: `/path/to/client.p12` Prefer this endpoint for the connection (if set, will override the endpoint from the server). - + **Example**: `https://preferred.endpoint.com` @@ -199,15 +205,19 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Newt secret for authentication (equivalent to `--secret`) + + Port for the peers to connect to Newt on (equivalent to `--port`) + + MTU for the internal WireGuard interface (equivalent to `--mtu`) - + **Default**: `1280` DNS server to use for resolving the endpoint (equivalent to `--dns`) - + **Default**: `9.9.9.9` @@ -221,13 +231,13 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`). - + **Default**: `false` Log level (equivalent to `--log-level`) - + **Default**: `INFO` @@ -237,13 +247,13 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Interval for pinging the server (equivalent to `--ping-interval`) - + **Default**: `3s` Timeout for each ping (equivalent to `--ping-timeout`) - + **Default**: `5s` @@ -253,7 +263,7 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`) - + **Default**: `false` @@ -263,43 +273,43 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Disable clients on the WireGuard interface (equivalent to `--disable-clients`). - + **Default**: `false` Use native WireGuard interface (Linux only, equivalent to `--native`) - + **Default**: `false` Name of the WireGuard interface (equivalent to `--interface`) - + **Default**: `newt` Enable Prometheus /metrics exporter (equivalent to `--metrics`). - + **Default**: `true` Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT (equivalent to `--otlp`). - + **Default**: `false` Admin/metrics bind address (equivalent to `--metrics-admin-addr`). - + **Default**: `127.0.0.1:2112` Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`). - + **Default**: `false` @@ -309,7 +319,7 @@ When both environment variables and CLI arguments are provided, CLI arguments ta Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`). - + **Default**: `false` @@ -331,7 +341,7 @@ When both environment variables and CLI arguments are provided, CLI arguments ta ## Loading secrets from files -You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs. +You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs. ``` $ cat ~/.config/newt-client/config.json @@ -343,9 +353,9 @@ $ cat ~/.config/newt-client/config.json } ``` -This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you have run it once! +This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you have run it once! -Default locations: +Default locations: - **macOS**: `~/Library/Application Support/newt-client/config.json` - **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json` @@ -486,3 +496,11 @@ 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. diff --git a/manage/sites/install-site.mdx b/manage/sites/install-site.mdx index 27edbc7..af6be48 100644 --- a/manage/sites/install-site.mdx +++ b/manage/sites/install-site.mdx @@ -15,9 +15,13 @@ Use this command to automatically install Newt. It detects your system architect curl -fsSL https://static.pangolin.net/get-newt.sh | bash ``` +#### Windows + +If you would like to use Newt on Windows as a service or with clients, wintun.dll is sometimes required. Please use latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest). + ### Manual Download -Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases) for ARM and AMD64 (x86_64) architectures. +Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases/latest) for ARM and AMD64 (x86_64) architectures. Download and install manually: