pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-08 05:56:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add information about hole punching improvements

Browse Source
This commit is contained in:
Owen
2025-12-11 14:39:39 -05:00
parent 1a755588a6
commit edec8aa9b8
3 changed files with 75 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
manage/clients/understanding-clients.mdx
View File

@@ -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)

114
manage/sites/configure-site.mdx
View File

@@ -7,15 +7,15 @@ description: "Configure Newt for connecting to Pangolin sites"
<ResponseField name="id" type="string" required>
Newt ID generated by Pangolin to identify the client.
**Example**: `31frd0uzbjvp721`
</ResponseField>
<ResponseField name="secret" type="string" required>
A unique secret used to authenticate the client ID with the websocket.
**Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
<Warning>
Keep this secret private and secure. It's used for authentication.
</Warning>
@@ -23,159 +23,165 @@ description: "Configure Newt for connecting to Pangolin sites"
<ResponseField name="endpoint" type="string" required>
The endpoint where both Gerbil and Pangolin reside for websocket connections.
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="port" type="integer">
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`
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface.
**Default**: `1280`
</ResponseField>
<ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint.
**Default**: `9.9.9.9`
</ResponseField>
<ResponseField name="log-level" type="string">
The log level to use for Newt output.
**Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
**Default**: `INFO`
</ResponseField>
<ResponseField name="ping-interval" type="string">
Interval for pinging the server.
**Default**: `3s`
</ResponseField>
<ResponseField name="ping-timeout" type="string">
Timeout for each ping.
**Default**: `5s`
</ResponseField>
<ResponseField name="docker-socket" type="string">
Set the Docker socket path for container discovery integration.
**Example**: `/var/run/docker.sock`
</ResponseField>
<ResponseField name="docker-enforce-network-validation" type="boolean">
Validate the container target is on the same network as the Newt process.
**Default**: `false`
</ResponseField>
<ResponseField name="health-file" type="string">
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`
</ResponseField>
<ResponseField name="updown" type="string">
Script to be called when targets are added or removed.
**Example**: `/path/to/updown.sh`
</ResponseField>
<ResponseField name="blueprint-file" type="string">
Path to blueprint file to define Pangolin resources and configurations.
**Example**: `/path/to/blueprint.yaml`
</ResponseField>
<ResponseField name="no-cloud" type="boolean">
Don't fail over to the cloud when using managed nodes in Pangolin Cloud.
**Default**: `false`
</ResponseField>
<ResponseField name="disable-clients" type="boolean">
Disable clients on the WireGuard interface.
**Default**: `false` (clients enabled)
</ResponseField>
<ResponseField name="native" type="boolean">
Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root).
**Default**: `false` (uses userspace netstack)
</ResponseField>
<ResponseField name="interface" type="string">
Name of the WireGuard interface.
**Default**: `newt`
</ResponseField>
<ResponseField name="metrics" type="boolean">
Enable Prometheus /metrics exporter.
**Default**: `true`
</ResponseField>
<ResponseField name="otlp" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.
**Default**: `false`
</ResponseField>
<ResponseField name="metrics-admin-addr" type="string">
Admin/metrics bind address.
**Default**: `127.0.0.1:2112`
</ResponseField>
<ResponseField name="metrics-async-bytes" type="boolean">
Enable async bytes counting (background flush; lower hot path overhead).
**Default**: `false`
</ResponseField>
<ResponseField name="region" type="string">
Optional region resource attribute for telemetry and metrics.
**Example**: `us-west-2`
</ResponseField>
<ResponseField name="enforce-hc-cert" type="boolean">
Enforce certificate validation for health checks.
**Default**: `false` (accepts any cert)
</ResponseField>
<ResponseField name="tls-client-cert-file" type="string">
Path to client certificate file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.crt`
</ResponseField>
<ResponseField name="tls-client-key" type="string">
Path to client private key file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.key`
</ResponseField>
<ResponseField name="tls-client-ca" type="string">
Path to CA certificate file for validating remote certificates (can be specified multiple times).
**Example**: `/path/to/ca.crt`
</ResponseField>
<ResponseField name="tls-client-cert" type="string">
Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead.
**Example**: `/path/to/client.p12`
</ResponseField>
<ResponseField name="prefer-endpoint" type="string">
Prefer this endpoint for the connection (if set, will override the endpoint from the server).
**Example**: `https://preferred.endpoint.com`
</ResponseField>
@@ -199,15 +205,19 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
Newt secret for authentication (equivalent to `--secret`)
</ResponseField>
<ResponseField name="PORT" type="integer">
Port for the peers to connect to Newt on (equivalent to `--port`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
**Default**: `1280`
</ResponseField>
<ResponseField name="DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`)
**Default**: `9.9.9.9`
</ResponseField>
@@ -221,13 +231,13 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
<ResponseField name="NO_CLOUD" type="boolean">
Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`).
**Default**: `false`
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`)
**Default**: `INFO`
</ResponseField>
@@ -237,13 +247,13 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
<ResponseField name="PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s`
</ResponseField>
<ResponseField name="PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s`
</ResponseField>
@@ -253,7 +263,7 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
<ResponseField name="DOCKER_ENFORCE_NETWORK_VALIDATION" type="boolean">
Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)
**Default**: `false`
</ResponseField>
@@ -263,43 +273,43 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
<ResponseField name="DISABLE_CLIENTS" type="boolean">
Disable clients on the WireGuard interface (equivalent to `--disable-clients`).
**Default**: `false`
</ResponseField>
<ResponseField name="USE_NATIVE_INTERFACE" type="boolean">
Use native WireGuard interface (Linux only, equivalent to `--native`)
**Default**: `false`
</ResponseField>
<ResponseField name="INTERFACE" type="string">
Name of the WireGuard interface (equivalent to `--interface`)
**Default**: `newt`
</ResponseField>
<ResponseField name="NEWT_METRICS_PROMETHEUS_ENABLED" type="boolean">
Enable Prometheus /metrics exporter (equivalent to `--metrics`).
**Default**: `true`
</ResponseField>
<ResponseField name="NEWT_METRICS_OTLP_ENABLED" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT (equivalent to `--otlp`).
**Default**: `false`
</ResponseField>
<ResponseField name="NEWT_ADMIN_ADDR" type="string">
Admin/metrics bind address (equivalent to `--metrics-admin-addr`).
**Default**: `127.0.0.1:2112`
</ResponseField>
<ResponseField name="NEWT_METRICS_ASYNC_BYTES" type="boolean">
Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`).
**Default**: `false`
</ResponseField>
@@ -309,7 +319,7 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
<ResponseField name="ENFORCE_HC_CERT" type="boolean">
Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).
**Default**: `false`
</ResponseField>
@@ -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.

6
manage/sites/install-site.mdx
View File

@@ -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: