diff --git a/docs.json b/docs.json
index 86570c1..839eaa7 100644
--- a/docs.json
+++ b/docs.json
@@ -179,7 +179,8 @@
"pages": [
"manage/remote-node/understanding-nodes",
"manage/remote-node/quick-install-remote",
- "manage/remote-node/config-file"
+ "manage/remote-node/config-file",
+ "manage/remote-node/backhaul"
]
},
"manage/endpoints-and-pops",
diff --git a/manage/remote-node/backhaul.mdx b/manage/remote-node/backhaul.mdx
index 94b8b88..f14623e 100644
--- a/manage/remote-node/backhaul.mdx
+++ b/manage/remote-node/backhaul.mdx
@@ -1,17 +1,67 @@
-https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-on-a-router
-/etc/docker/daemon.json
+---
+title: "Site to Cloud"
+description: "Turn a remote node into a network concentrator that routes traffic between a cloud VPC and your Pangolin sites"
+---
+
+import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
+
+
+
+
+
+
+ Site to cloud is an advanced [remote node](/manage/remote-node/understanding-nodes) configuration available in [Pangolin Cloud](https://app.pangolin.net/auth/signup).
+
+
+A standard remote node terminates WireGuard tunnels and proxies HTTP(S) traffic to your resources. A **backhaul** node goes a step further: it acts as an IP router between an entire network, such as a cloud VPC, and your Pangolin sites. Instead of just forwarding individual resource connections, the node forwards whole subnets, letting hosts on either side reach each other without installing Newt on every machine.
+
+This is useful when you want to bridge a cloud network (for example, an AWS VPC) with your on-prem or office network through Pangolin, using a node running in that VPC as the concentrator.
+
+
+ Site to cloud builds on top of a normal remote node install. Read [Remote Nodes](/manage/remote-node/understanding-nodes) and [Quick Install Guide](/manage/remote-node/quick-install-remote) first if you haven't deployed a node yet.
+
+
+## How It Works
+
+- **The node routes, it doesn't just proxy.** Gerbil creates the WireGuard interface directly on the host and Docker forwards packets between it and the host's network, rather than isolating traffic inside a container network namespace.
+- **The cloud network learns to route to the node.** You add a route in your VPC (or other network) so that traffic destined for the Pangolin overlay is sent to the node.
+- **The node learns to route to the cloud network.** You register the VPC's CIDR on the node so it's pushed down to your sites as a route.
+- **Sites route natively.** Sites connect with Newt's native routing mode so the tunnel subnet is a real route on the site's host, not just an application-layer proxy.
+
+## Prerequisites
+
+- A Linux server with Docker and root access, dedicated to running the backhaul node.
+- Administrative access to the cloud network you want to bridge (for example, an AWS VPC) so you can edit security groups, route tables, and instance settings.
+
+## Enable IP Forwarding on the Host
+
+Because the node forwards packets between the WireGuard tunnel and the host network instead of only terminating them, the host must have IP forwarding enabled.
+
+```bash
+sudo sysctl -w net.ipv4.ip_forward=1
+```
+
+Make it permanent by adding `net.ipv4.ip_forward=1` to `/etc/sysctl.d/99-pangolin-backhaul.conf`.
+
+Docker enables forwarding in its own iptables rules by default, but if you've disabled Docker's iptables management, or packets are still being dropped, allow forwarded traffic through Docker's chain in `/etc/docker/daemon.json`:
+
+```json title="/etc/docker/daemon.json"
{
"ip-forward-no-drop": true
-}
+}
+```
-Docker will also enabling forwarding by default but if not sudo sysctl -w net.ipv4.ip_forward=1 and make perminate with
+Restart Docker after changing this file. See Docker's [packet filtering and firewalls guide](https://docs.docker.com/engine/network/packet-filtering-firewalls/#docker-on-a-router) for background on running Docker on a router.
-docker-compose-host.yml
+## Deploy the Node with Host Networking
+
+The standard node install runs Gerbil and Traefik on a bridge network, with Traefik sharing Gerbil's network namespace. For backhaul, all three services run with `network_mode: host` instead. This gives Gerbil direct access to the host's network stack and routing table, which is required for it to create routes for the subnets you register instead of only handling its own tunnel traffic.
+
+```yaml title="docker-compose.yml"
name: pangolin
services:
pangolin:
- image: docker.io/fosrl/pangolin-node:1.4.0
- # image: 537824365807.dkr.ecr.us-west-1.amazonaws.com/pangolin_node_owen
+ image: docker.io/fosrl/pangolin-node:latest
container_name: pangolin
restart: unless-stopped
network_mode: host
@@ -26,7 +76,7 @@ services:
retries: 15
gerbil:
- image: docker.io/fosrl/gerbil:1.4.2
+ image: docker.io/fosrl/gerbil:latest
container_name: gerbil
restart: unless-stopped
network_mode: host
@@ -62,24 +112,36 @@ services:
volumes:
pangolin-data-dynamic:
pangolin-data-certificates:
+```
-config/config.yml
-app:
- log_level: debug
+
+ With `network_mode: host`, containers bind to ports directly on the host, so there's no `ports` mapping and no `network_mode: service:gerbil` on Traefik like there is in the [standard install](/self-host/manual/docker-compose). Gerbil and Traefik reach each other and Pangolin over `localhost`.
+
+
+## Configure the Node
+
+The `config.yml` for a backhaul node uses the same fields as any [remote node](/manage/remote-node/config-file), mounted at `config/config.yml`:
+
+```yaml title="config/config.yml"
+gerbil:
+ start_port: 51820
+ base_endpoint: "203.0.113.10" # REPLACE WITH YOUR NODE'S PUBLIC IP OR DOMAIN
+ reachable_at: http://localhost:3003
server:
internal_port: 3001
internal_hostname: localhost
-gerbil:
- start_port: 51820
- base_endpoint: "54.176.101.5"
- reachable_at: http://localhost:3003
managed:
- endpoint: https://app.pangolin.dev.fosrl.io
- id: "owjiufga6mdj94k"
- secret: "iicbif2oxlqzkx13eb501h586h1gtxiwpr7nu52tr1rpbcqi"
+ id: "he4g78wevj25msf"
+ secret: "n7sd18twfko0q0vrb7wyclqzbvvnx1fqt7ezv8xewhdb9s7d"
+```
+See the [configuration file reference](/manage/remote-node/config-file) for every available option.
-config/traefik/traefik_config.yml
+## Configure Traefik
+
+Traefik's config is largely the same as a standard node, with `trustedIPs` opened up to accept the proxy protocol header from Gerbil on the host network:
+
+```yaml title="config/traefik/traefik_config.yml"
api:
insecure: true
dashboard: true
@@ -110,7 +172,7 @@ entryPoints:
address: ":443"
proxyProtocol:
trustedIPs:
- - 0.0.0.0/0 # This is coming from gerbil
+ - 0.0.0.0/0 # This is coming from Gerbil
- ::1/128
transport:
respondingTimeouts:
@@ -121,35 +183,91 @@ serversTransport:
ping:
entryPoint: "web"
+```
+## Configure the Cloud Network
-Use .site.pangolin.net to resolve the site between multiple exit nodes in the same cloud. this will return the routable address of the site that we can route to and if the site moves between nods because they are down or something this will follow the site but you can expect a little downtime when it moves
+This section uses AWS as an example, but the same steps apply to any VPC-style network: the node needs to be allowed to receive and forward traffic for the whole network, and the network needs a route pointing back at the node.
+
+
+ The node is acting as a concentrator for the whole network, not just serving its own ports, so its security group must accept all traffic from the VPC's CIDR. Otherwise the security group blocks the inbound traffic it's meant to forward.
-You must allow all traffic into the node from the network so it can act as a concentrator otherwise the security group will block this inbounc traffic.
-images/security_group_inbound_to_node.png
+
+ 
+
+
-Add the subnet to the route tables so that the data in the VPC knows to route to the node. Use the node as the instance id.
-images/subnet_in_route_table.png
+
+ Add a route in the VPC's route table for the WireGuard overlay subnet assigned to your node (shown as the node's **Address** on its page in the [Pangolin dashboard](https://app.pangolin.net)), targeting the node's instance or network interface. This tells the rest of the VPC to send anything destined for the Pangolin overlay — other sites and clients — to the node.
-Disable source destination check or the VPC will block VPN traffic from entering the node
-images/source_destination_check_menu.png
-images/source_destination_check_box.png
+
+ 
+
+
-Put the VPC subnet into the routes on the remote node to be pushed to the sites
-images/subnet_programmed_on_node.png
+
+ By default, AWS drops any packet where an instance isn't the source or destination, which would silently break a node that's forwarding traffic on behalf of others. Disable the source/destination check on the node's instance so it's allowed to route traffic that isn't addressed to itself.
-Run the site with --native-main to create the routes and network interface on the host
+
+ 
+
+
+
+ 
+
+
+
+
+ In the node's settings in the Pangolin dashboard, add the VPC's CIDR (for example, `172.31.0.0/16`) to **Remote Subnets** under the **Networking** tab. This is pushed down to your sites as a route, so they know to send traffic for that subnet through this node's tunnel.
+
+ You can also set **Preference Labels** on the node and apply matching labels to sites, which enforces that those sites connect through this remote node specifically. This is useful once you have more than one node or point of presence and want particular sites to always backhaul through this one.
+
+
+ 
+
+
+
+
+## Enable Native Routing on Your Sites
+
+For the VPC and a site's network to route to each other, the tunnel needs to be a real route on the site's host, not just something Newt proxies at the application layer. Start Newt with `--native-main` so it creates the network interface and routes directly on the host:
+
+```bash
sudo newt --id 34s48my8iba5wsl --secret ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh --endpoint https://app.pangolin.net --native-main
+```
+On Windows, set `nativeMain` in the Newt client's `config.json` instead:
-if running on windows sometimes windows does not respond to pings:
-Enable-NetFirewallRule -DisplayName "File and Printer Sharing (Echo Request - ICMPv4-In)"
-
-%PROGRAMDATA%/newt/newt-client/config.json
+```json title="%PROGRAMDATA%/newt/newt-client/config.json"
{
- "id": "34s48my8iba5wsl",
- "secret": "ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh",
- "endpoint": "https://app.pangolin.net",
- "nativeMain": true
+ "id": "34s48my8iba5wsl",
+ "secret": "ts1v7480qqw01j7ba4uiw5y7l58skw7anpji2ndludhgzloh",
+ "endpoint": "https://app.pangolin.net",
+ "nativeMain": true
}
+```
+
+
+ Windows doesn't respond to ICMP echo requests (ping) over the tunnel interface by default. If you need to ping a Windows site, enable the built-in firewall rule for it:
+
+ ```powershell
+ Enable-NetFirewallRule -DisplayName "File and Printer Sharing (Echo Request - ICMPv4-In)"
+ ```
+
+
+## Resolving a Site's Address Directly
+
+If something outside of Pangolin's normal resource routing needs to reach a site directly, for example a static route configured elsewhere in your network, you can resolve `.site.pangolin.net` to get the site's current routable address.
+
+This is useful with backhaul because a site's traffic can move between exit nodes if one becomes unavailable. The DNS record always follows the site to whichever node it's currently connected through.
+
+
+ Expect a short gap in resolution when a site moves between nodes while the DNS record updates.
+
+
+## High Availability
+
+Deploy multiple nodes in your network. Each node will have a different routable subnet. Repeating the above steps will ensure they are routed to uniquely. Sites will connect to one of the nodes in the network and if it does down fail over to another online node.
+
+Make sure to use the site's DNS address to connect to it as when it moves between nodes its address may change.
\ No newline at end of file
diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx
index 2c156da..bc1c6ba 100644
--- a/manage/sites/configure-site.mdx
+++ b/manage/sites/configure-site.mdx
@@ -9,10 +9,18 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
## Flags
+
+Almost every setting below can also be set via an environment variable (**Env var**) or in the [config file](#config-file) (**Config file key**) instead of as a CLI flag. Values are resolved with priority `CLI flag > environment variable > config file > default`, so a flag always overrides an env var, which always overrides what's saved on disk. This makes environment variables and config files particularly useful for containerized environments where CLI flags are less convenient.
+
+
Newt ID generated by Pangolin to identify the client.
**Example**: `31frd0uzbjvp721`
+
+ **Env var**: `NEWT_ID`
+
+ **Config file key**: `id`
@@ -20,6 +28,10 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
**Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
+ **Env var**: `NEWT_SECRET`
+
+ **Config file key**: `secret`
+
Keep this secret private and secure. It's used for authentication.
@@ -29,48 +41,108 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
The endpoint where the Pangolin server resides for websocket connections.
**Example**: `https://pangolin.example.com`
+
+ **Env var**: `PANGOLIN_ENDPOINT`
+
+ **Config file key**: `endpoint`
Site name to use when provisioning with a provisioning key. Supports `{{env.VARIABLE_NAME}}` templating from the process environment. If omitted, Pangolin assigns a random animal-based name (changeable in the dashboard).
**Example**: `my-edge-site` or `'{{env.SERIAL_NUMBER}}-edge'`
+
+ **Env var**: `NEWT_NAME`
+
+ **Config file key**: `name`
Path to a blueprint YAML file applied **once** at provisioning (imperative bootstrap). Unlike `--blueprint-file`, Newt does not keep reapplying it, so resources you edit in the dashboard are not overwritten on later runs. See [Site provisioning keys](/manage/sites/site-provisioning).
**Example**: `/path/to/bootstrap.yaml`
+
+ **Env var**: `PROVISIONING_BLUEPRINT_FILE`
+
+ **Config file key**: `provisioningBlueprintFile`
Provisioning key from Pangolin (alternative to a `provisioningKey` field inside the config file). Newt exchanges it once for site credentials, then persists `id` and `secret` to the config file and ignores the key on later runs. This flag is not written into the config file. See [Site provisioning keys](/manage/sites/site-provisioning).
**Example**: `spk_...`
+
+ **Env var**: `NEWT_PROVISIONING_KEY`
+
+ **Config file key**: `provisioningKey`
- Path to a JSON file where Newt reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and other options). When you use [site provisioning](/manage/sites/site-provisioning), Newt writes `id` and `secret` into this file after a successful exchange.
+ Path to a JSON file where Newt reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and virtually every other flag below). When you use [site provisioning](/manage/sites/site-provisioning), Newt writes `id` and `secret` into this file after a successful exchange. See [Config File](#config-file) for the default path on each platform.
**Example**: `/var/newt.json`
+
+ **Env var**: `CONFIG_FILE`
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`
+
+ **Env var**: `PORT`
+
+ **Config file key**: `port`
+
+
+
+ Use a native WireGuard interface for client tunnels instead of the userspace netstack implementation.
+
+ **Default**: `false`
+
+ **Env var**: `USE_NATIVE_INTERFACE`
+
+ **Config file key**: `native`
+
+
+
+ Use a native WireGuard interface for the main tunnel (instead of netstack).
+
+ **Default**: `false`
+
+ **Env var**: `USE_NATIVE_MAIN_INTERFACE`
+
+ **Config file key**: `nativeMain`
+
+
+
+ Name of the native main tunnel WireGuard interface (used with `--native-main`).
+
+ **Default**: `newt`
+
+ **Env var**: `INTERFACE_MAIN`
+
+ **Config file key**: `interfaceMain`
MTU for the internal WireGuard interface.
**Default**: `1280`
+
+ **Env var**: `MTU`
+
+ **Config file key**: `mtu`
DNS server to use for resolving the endpoint.
**Default**: `9.9.9.9`
+
+ **Env var**: `DNS`
+
+ **Config file key**: `dns`
@@ -79,401 +151,356 @@ import PangolinCloudTocCta from "/snippets/pangolin-cloud-toc-cta.mdx";
**Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
**Default**: `INFO`
+
+ **Env var**: `LOG_LEVEL`
+
+ **Config file key**: `logLevel`
Interval for pinging the server.
**Default**: `15s`
+
+ **Env var**: `PING_INTERVAL`
+
+ **Config file key**: `pingInterval`
Timeout for each ping.
**Default**: `7s`
+
+ **Env var**: `PING_TIMEOUT`
+
+ **Config file key**: `pingTimeout`
Idle timeout for UDP proxied client flows before cleanup.
**Default**: `90s`
+
+ **Env var**: `NEWT_UDP_PROXY_IDLE_TIMEOUT`
+
+ **Config file key**: `udpProxyIdleTimeout`
Set the Docker socket path for container discovery integration.
**Example**: `/var/run/docker.sock`
+
+ **Env var**: `DOCKER_SOCKET`
+
+ **Config file key**: `dockerSocket`
Validate the container target is on the same network as the Newt process.
**Default**: `false`
+
+ **Env var**: `DOCKER_ENFORCE_NETWORK_VALIDATION`
+
+ **Config file key**: `dockerEnforceNetworkValidation`
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`
+
+ **Env var**: `HEALTH_FILE`
+
+ **Config file key**: `healthFile`
Script to be called when targets are added or removed.
**Example**: `/path/to/updown.sh`
+
+ **Env var**: `UPDOWN_SCRIPT`
+
+ **Config file key**: `updownScript`
Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: Newt keeps applying the file, and it remains the source of truth (dashboard changes can be overwritten on the next apply). For a one-time bootstrap blueprint with provisioning keys, use `--provisioning-blueprint-file` instead.
**Example**: `/path/to/blueprint.yaml`
+
+ **Env var**: `BLUEPRINT_FILE`
+
+ **Config file key**: `blueprintFile`
Don't fail over to the cloud when using managed nodes in Pangolin Cloud.
**Default**: `false`
+
+ **Env var**: `NO_CLOUD`
+
+ **Config file key**: `noCloud`
Disable clients on the WireGuard interface.
**Default**: `false` (clients enabled)
+
+ **Env var**: `DISABLE_CLIENTS`
+
+ **Config file key**: `disableClients`
Disable SSH auth daemon and native SSH mode (remote auth daemon integrations still work).
**Default**: `false`
+
+ **Env var**: `DISABLE_SSH`
+
+ **Config file key**: `disableSsh`
Name of the WireGuard interface.
**Default**: `newt`
+
+ **Env var**: `INTERFACE`
+
+ **Config file key**: `interface`
Enable Prometheus /metrics exporter.
**Default**: `false`
+
+ **Env var**: `NEWT_METRICS_PROMETHEUS_ENABLED`
+
+ **Config file key**: `metrics`
Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.
**Default**: `false`
+
+ **Env var**: `NEWT_METRICS_OTLP_ENABLED`
+
+ **Config file key**: `otlp`
Admin/metrics bind address.
**Default**: `127.0.0.1:2112`
+
+ **Env var**: `NEWT_ADMIN_ADDR`
+
+ **Config file key**: `metricsAdminAddr`
Enable async bytes counting (background flush; lower hot path overhead).
**Default**: `false`
+
+ **Env var**: `NEWT_METRICS_ASYNC_BYTES`
+
+ **Config file key**: `metricsAsyncBytes`
Enable pprof debug endpoints on the admin server.
**Default**: `false`
+
+ **Env var**: `NEWT_PPROF_ENABLED`
+
+ **Config file key**: `pprof`
Optional region resource attribute for telemetry and metrics.
**Example**: `us-west-2`
+
+ **Env var**: `NEWT_REGION`
+
+ **Config file key**: `region`
Enforce certificate validation for health checks.
**Default**: `false` (accepts any cert)
+
+ **Env var**: `ENFORCE_HC_CERT`
+
+ **Config file key**: `enforceHcCert`
Path to client certificate file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.crt`
+
+ **Env var**: `TLS_CLIENT_CERT`
+
+ **Config file key**: `tlsClientCertFile`
Path to client private key file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.key`
+
+ **Env var**: `TLS_CLIENT_KEY`
+
+ **Config file key**: `tlsClientKey`
Path to CA certificate file for validating remote certificates (can be specified multiple times).
**Example**: `/path/to/ca.crt`
+
+ **Env var**: `TLS_CLIENT_CAS` (comma-separated list)
+
+ **Config file key**: `tlsClientCa` (array of strings in the config file)
Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead.
**Example**: `/path/to/client.p12`
+
+ **Env var**: `TLS_CLIENT_CERT_PKCS12`
+
+ **Config file key**: `tlsClientCert`
Pre-shared key for auth daemon authentication.
+
+ **Env var**: `AD_KEY`
+
+ **Config file key**: `adPreSharedKey`
Path to the principals file for auth daemon.
**Default**: `/var/run/auth-daemon/principals`
+
+ **Env var**: `AD_PRINCIPALS_FILE`
+
+ **Config file key**: `adPrincipalsFile`
Path to the CA certificate file for auth daemon.
**Default**: `/etc/ssh/ca.pem`
+
+ **Env var**: `AD_CA_CERT_PATH`
+
+ **Config file key**: `adCaCertPath`
Generate a random password for authenticated users.
**Default**: `false`
+
+ **Env var**: `AD_GENERATE_RANDOM_PASSWORD`
+
+ **Config file key**: `adGenerateRandomPassword`
Print the Newt version and exit.
+
+ Print the fully resolved configuration (including which source — default, config file, environment, or CLI — each value came from) and exit. Secrets are masked. Useful for confirming what a config file actually loaded.
+
+ **Default**: `false`
+
+
Prefer this endpoint for the connection (if set, will override the endpoint from the server).
**Example**: `https://preferred.endpoint.com`
+
+ **Config file key**: `preferEndpoint`
-## Environment Variables
+## Config File
-All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Newt in containerized environments.
+Newt can be configured entirely with a JSON config file instead of (or in addition to) CLI flags and environment variables. Almost every flag documented above has a matching camelCase key in this file — see the **Config file key** on each flag for its exact name.
-
-When both environment variables and CLI arguments are provided, CLI arguments take precedence.
-
+You can use `--config-file` or the `CONFIG_FILE` environment variable to point Newt at a specific path. Newt also writes to this file: when [site provisioning](/manage/sites/site-provisioning) succeeds, the resolved `id` and `secret` are persisted here so you don't need to pass `--id`/`--secret` (or a provisioning key) on every subsequent run.
-
- Endpoint of your Pangolin server (equivalent to `--endpoint`)
-
+### Default locations
-
- Newt ID generated by Pangolin (equivalent to `--id`)
-
+If `--config-file`/`CONFIG_FILE` isn't set, Newt reads and writes the config file at a platform-specific default path:
-
- Newt secret for authentication (equivalent to `--secret`)
-
+| Platform | Default path |
+| --- | --- |
+| macOS | `~/Library/Application Support/newt-client/config.json` |
+| Windows | `%PROGRAMDATA%\newt\newt-client\config.json` |
+| Linux / others | `~/.config/newt-client/config.json` |
-
- Pre-shared key used to authenticate external auth daemons to Newt (equivalent to `--ad-pre-shared-key`)
-
+### Example
-
- Path to the principals file for auth daemon (equivalent to `--ad-principals-file`).
-
- **Default**: `/var/run/auth-daemon/principals`
-
-
-
- Path to the CA certificate file for auth daemon (equivalent to `--ad-ca-cert-path`).
-
- **Default**: `/etc/ssh/ca.pem`
-
-
-
- Generate a random password for authenticated users (equivalent to `--ad-generate-random-password`).
-
- **Default**: `false`
-
-
-
- Site name when provisioning with a provisioning key (equivalent to `--name`). Supports `{{env.VARIABLE_NAME}}` templating from the environment.
-
-
-
- Provisioning key string (equivalent to `--provisioning-key`). See [Site provisioning keys](/manage/sites/site-provisioning).
-
-
-
- Path to a bootstrap-only blueprint file (equivalent to `--provisioning-blueprint-file`). See [Site provisioning keys](/manage/sites/site-provisioning).
-
-
-
- Path to the JSON config file where Newt loads and persists settings (equivalent to `--config-file`). Use this instead of the default location under the home folder when you want a fixed path (typical for containers and provisioning).
-
- **Example**: `/var/newt.json`
-
-
-
- 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`
-
-
-
- Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
-
-
-
- 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`
-
-
-
- Path to Docker socket for container discovery (equivalent to `--docker-socket`)
-
-
-
- Interval for pinging the server (equivalent to `--ping-interval`)
-
- **Default**: `15s`
-
-
-
- Timeout for each ping (equivalent to `--ping-timeout`)
-
- **Default**: `7s`
-
-
-
- Idle timeout for UDP proxied client flows before cleanup (equivalent to `--udp-proxy-idle-timeout`).
-
- **Default**: `90s`
-
-
-
- Path to updown script for target add/remove events (equivalent to `--updown`)
-
-
-
- Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)
-
- **Default**: `false`
-
-
-
- Path to health file for connection monitoring (equivalent to `--health-file`)
-
-
-
- Disable clients on the WireGuard interface (equivalent to `--disable-clients`).
-
- **Default**: `false`
-
-
-
- Disable SSH auth daemon and native SSH mode (equivalent to `--disable-ssh`).
-
- **Default**: `false`
-
-
-
- Name of the WireGuard interface (equivalent to `--interface`)
-
- **Default**: `newt`
-
-
-
- Enable Prometheus /metrics exporter (equivalent to `--metrics`).
-
- **Default**: `false`
-
-
-
- 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`
-
-
-
- Enable pprof debug endpoints on the admin server (equivalent to `--pprof`).
-
- **Default**: `false`
-
-
-
- Optional region resource attribute for telemetry and metrics (equivalent to `--region`).
-
-
-
- Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).
-
- **Default**: `false`
-
-
-
- Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`)
-
-
-
- Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`)
-
-
-
- Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags)
-
-
-
- Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead
-
-
-## Loading secrets from files
-
-You can use `--config-file` or the `CONFIG_FILE` environment variable to set the path of the config file where Newt stores credentials and other settings between runs.
-
-```
-$ cat ~/.config/newt-client/config.json
+```json
{
+ "endpoint": "https://app.pangolin.net",
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
- "endpoint": "https://app.pangolin.net",
- "tlsClientCert": ""
+ "name": "my-edge-site",
+
+ "dns": "9.9.9.9",
+ "logLevel": "INFO",
+ "interface": "newt",
+ "mtu": 1280,
+ "port": 34534,
+
+ "pingInterval": "15s",
+ "pingTimeout": "7s",
+ "udpProxyIdleTimeout": "90s",
+
+ "disableClients": false,
+ "disableSsh": false,
+ "noCloud": false,
+
+ "dockerSocket": "unix:///var/run/docker.sock",
+ "dockerEnforceNetworkValidation": false,
+
+ "healthFile": "/tmp/healthy",
+ "blueprintFile": "/path/to/blueprint.yaml",
+
+ "tlsClientCertFile": "",
+ "tlsClientKey": "",
+ "tlsClientCa": []
}
```
-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!
+
+You only need to include the keys you want to set — anything omitted falls back to an environment variable, then its built-in default. Run `newt --show-config` to see every resolved setting alongside where it came from (config file, environment, CLI, or default), which is useful for confirming what a config file actually loaded.
+
-Default locations:
-
-- **macOS**: `~/Library/Application Support/newt-client/config.json`
-- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
-- **Linux/Others**: `~/.config/newt-client/config.json`
+
+Fields like `secret`, `tlsClientKey`, and `adPreSharedKey` are sensitive. Restrict file permissions on the config file accordingly.
+
## Docker Socket Integration