docs-v2/manage/sites/configure-site.mdx

---
title: "Configure Sites"
description: "Configure Pangolin site connector setting" 
---



## Flags

<Note>
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.
</Note>

<ResponseField name="id" type="string" required>
  Site ID generated by Pangolin to identify the client.

  **Example**: `31frd0uzbjvp721`

  **Env var**: `SITE_ID`

  **Config file key**: `id`

  **Legacy env var**: `NEWT_SECRET`
</ResponseField>

<ResponseField name="secret" type="string" required>
  A unique secret used to authenticate the site with the websocket.

  **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`

  **Env var**: `SITE_SECRET`

  **Config file key**: `secret`

  **Legacy env var**: `NEWT_SECRET`
  <Warning>
  Keep this secret private and secure. It's used for authentication.
  </Warning>
</ResponseField>

<ResponseField name="endpoint" type="string" required>
  The endpoint where the Pangolin server resides for websocket connections.

  **Example**: `https://pangolin.example.com`

  **Env var**: `PANGOLIN_ENDPOINT`

  **Config file key**: `endpoint`
</ResponseField>

<ResponseField name="name" type="string">
  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**: `SITE_NAME`

  **Config file key**: `name`
</ResponseField>

<ResponseField name="provisioning-blueprint-file" type="string">
  Path to a blueprint YAML file applied **once** at provisioning (imperative bootstrap). Unlike `--blueprint-file`, the site 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`
</ResponseField>

<ResponseField name="provisioning-key" type="string">
  Provisioning key from Pangolin (alternative to a `provisioningKey` field inside the config file). The site 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**: `SITE_PROVISIONING_KEY`

  **Config file key**: `provisioningKey`

  **Legacy env var**: `NEWT_PROVISIONING_KEY`
</ResponseField>

<ResponseField name="config-file" type="string">
  Path to a JSON file where the site reads and persists settings (`endpoint`, `id`, `secret`, optional `provisioningKey`, and virtually every other flag below). When you use [site provisioning](/manage/sites/site-provisioning), the site 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/site.json`

  **Env var**: `CONFIG_FILE`
</ResponseField>

<ResponseField name="port" type="integer">
  Port for the peers to connect to the site 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`
</ResponseField>

<ResponseField name="native" type="boolean">
  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`
</ResponseField>

<ResponseField name="native-main" type="boolean">
  Use a native WireGuard interface for the main tunnel (instead of netstack).

  **Default**: `false`

  **Env var**: `USE_NATIVE_MAIN_INTERFACE`

  **Config file key**: `nativeMain`
</ResponseField>

<ResponseField name="interface-main" type="string">
  Name of the native main tunnel WireGuard interface (used with `--native-main`).

  **Default**: `pangolin`

  **Env var**: `INTERFACE_MAIN`

  **Config file key**: `interfaceMain`
</ResponseField>

<ResponseField name="mtu" type="integer">
  MTU for the internal WireGuard interface.

  **Default**: `1280`

  **Env var**: `MTU`

  **Config file key**: `mtu`
</ResponseField>

<ResponseField name="dns" type="string">
  DNS server to use for resolving the endpoint.

  **Default**: `9.9.9.9`

  **Env var**: `DNS`

  **Config file key**: `dns`
</ResponseField>

<ResponseField name="log-level" type="string">
  The log level to use for the site output.

  **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`

  **Default**: `INFO`

  **Env var**: `LOG_LEVEL`

  **Config file key**: `logLevel`
</ResponseField>

<ResponseField name="ping-interval" type="string">
  Interval for pinging the server.

  **Default**: `15s`

  **Env var**: `PING_INTERVAL`

  **Config file key**: `pingInterval`
</ResponseField>

<ResponseField name="ping-timeout" type="string">
  Timeout for each ping.

  **Default**: `7s`

  **Env var**: `PING_TIMEOUT`

  **Config file key**: `pingTimeout`
</ResponseField>

<ResponseField name="udp-proxy-idle-timeout" type="string">
  Idle timeout for UDP proxied client flows before cleanup.

  **Default**: `90s`

  **Env var**: `SITE_UDP_PROXY_IDLE_TIMEOUT`

  **Config file key**: `udpProxyIdleTimeout`

  **Legacy env var**: `NEWT_UDP_PROXY_IDLE_TIMEOUT`
</ResponseField>

<ResponseField name="docker-socket" type="string">
  Set the Docker socket path for container discovery integration.

  **Example**: `/var/run/docker.sock`

  **Env var**: `DOCKER_SOCKET`

  **Config file key**: `dockerSocket`
</ResponseField>

<ResponseField name="docker-enforce-network-validation" type="boolean">
  Validate the container target is on the same network as the the site process.

  **Default**: `false`

  **Env var**: `DOCKER_ENFORCE_NETWORK_VALIDATION`

  **Config file key**: `dockerEnforceNetworkValidation`
</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 the site.

  **Example**: `/tmp/healthy`

  **Env var**: `HEALTH_FILE`

  **Config file key**: `healthFile`
</ResponseField>

<ResponseField name="updown" type="string">
  Script to be called when targets are added or removed.

  **Example**: `/path/to/updown.sh`

  **Env var**: `UPDOWN_SCRIPT`

  **Config file key**: `updownScript`
</ResponseField>

<ResponseField name="blueprint-file" type="string">
  Path to a blueprint file that defines Pangolin resources and settings. This mode is declarative: the site 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`
</ResponseField>

<ResponseField name="no-cloud" type="boolean">
  Don't fail over to the cloud when using managed nodes in Pangolin Cloud.

  **Default**: `false`

  **Env var**: `NO_CLOUD`

  **Config file key**: `noCloud`
</ResponseField>

<ResponseField name="disable-clients" type="boolean">
  Disable clients on the WireGuard interface.

  **Default**: `false` (clients enabled)

  **Env var**: `DISABLE_CLIENTS`

  **Config file key**: `disableClients`
</ResponseField>

<ResponseField name="disable-ssh" type="boolean">
  Disable SSH auth daemon and native SSH mode (remote auth daemon integrations still work).

  **Default**: `false`

  **Env var**: `DISABLE_SSH`

  **Config file key**: `disableSsh`
</ResponseField>

<ResponseField name="interface" type="string">
  Name of the WireGuard interface.

  **Default**: `pangolin`

  **Env var**: `INTERFACE`

  **Config file key**: `interface`
</ResponseField>

<ResponseField name="metrics" type="boolean">
  Enable Prometheus /metrics exporter.

  **Default**: `false`

  **Env var**: `SITE_METRICS_PROMETHEUS_ENABLED`

  **Config file key**: `metrics`

  **Legacy env var**: `NEWT_METRICS_PROMETHEUS_ENABLED`
</ResponseField>

<ResponseField name="otlp" type="boolean">
  Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.

  **Default**: `false`

  **Env var**: `SITE_METRICS_OTLP_ENABLED`

  **Config file key**: `otlp`

  **Legacy env var**: `NEWT_METRICS_OTLP_ENABLED`
</ResponseField>

<ResponseField name="metrics-admin-addr" type="string">
  Admin/metrics bind address.

  **Default**: `127.0.0.1:2112`

  **Env var**: `SITE_ADMIN_ADDR`

  **Config file key**: `metricsAdminAddr`

  **Legacy env var**: `NEWT_ADMIN_ADDR`
</ResponseField>

<ResponseField name="metrics-async-bytes" type="boolean">
  Enable async bytes counting (background flush; lower hot path overhead).

  **Default**: `false`

  **Env var**: `SITE_METRICS_ASYNC_BYTES`

  **Config file key**: `metricsAsyncBytes`

  **Legacy env var**: `NEWT_METRICS_ASYNC_BYTES`
</ResponseField>

<ResponseField name="pprof" type="boolean">
  Enable pprof debug endpoints on the admin server.

  **Default**: `false`

  **Env var**: `SITE_PPROF_ENABLED`

  **Config file key**: `pprof`

  **Legacy env var**: `NEWT_PPROF_ENABLED`
</ResponseField>

<ResponseField name="region" type="string">
  Optional region resource attribute for telemetry and metrics.

  **Example**: `us-west-2`

  **Env var**: `SITE_REGION`

  **Config file key**: `region`

  **Legacy env var**: `NEWT_REGION`
</ResponseField>

<ResponseField name="enforce-hc-cert" type="boolean">
  Enforce certificate validation for health checks.

  **Default**: `false` (accepts any cert)

  **Env var**: `ENFORCE_HC_CERT`

  **Config file key**: `enforceHcCert`
</ResponseField>

<ResponseField name="tls-client-cert-file" type="string">
  Path to client certificate file (PEM/DER format) for mTLS.

  **Example**: `/path/to/client.crt`

  **Env var**: `TLS_CLIENT_CERT`

  **Config file key**: `tlsClientCertFile`
</ResponseField>

<ResponseField name="tls-client-key" type="string">
  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`
</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`

  **Env var**: `TLS_CLIENT_CAS` (comma-separated list)

  **Config file key**: `tlsClientCa` (array of strings in the config file)
</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`

  **Env var**: `TLS_CLIENT_CERT_PKCS12`

  **Config file key**: `tlsClientCert`
</ResponseField>

<ResponseField name="ad-pre-shared-key" type="string">
  Pre-shared key for auth daemon authentication.

  **Env var**: `AD_KEY`

  **Config file key**: `adPreSharedKey`
</ResponseField>

<ResponseField name="ad-principals-file" type="string">
  Path to the principals file for auth daemon.

  **Default**: `/var/run/auth-daemon/principals`

  **Env var**: `AD_PRINCIPALS_FILE`

  **Config file key**: `adPrincipalsFile`
</ResponseField>

<ResponseField name="ad-ca-cert-path" type="string">
  Path to the CA certificate file for auth daemon.

  **Default**: `/etc/ssh/ca.pem`

  **Env var**: `AD_CA_CERT_PATH`

  **Config file key**: `adCaCertPath`
</ResponseField>

<ResponseField name="ad-generate-random-password" type="boolean">
  Generate a random password for authenticated users.

  **Default**: `false`

  **Env var**: `AD_GENERATE_RANDOM_PASSWORD`

  **Config file key**: `adGenerateRandomPassword`
</ResponseField>

<ResponseField name="version" type="boolean">
  Print the Newt (package) version and exit.
</ResponseField>

<ResponseField name="show-config" type="boolean">
  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`
</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`

  **Config file key**: `preferEndpoint`
</ResponseField>

## Config File

The site 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.

You can use `--config-file` or the `CONFIG_FILE` environment variable to point the site at a specific path. The site 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.

### Default locations

If `--config-file`/`CONFIG_FILE` isn't set, the site reads and writes the config file at a platform-specific default path:

| Platform | Default path |
| --- | --- |
| macOS | `~/.config/pangolin/site.json` |
| Windows | `C:\Users\<Username>\.config\pangolin\site.json` |
| Linux / others | `~/.config/pangolin/site.json` |

### Example

```json
{
  "endpoint": "https://app.pangolin.net",
  "id": "spmzu8rbpzj1qq6",
  "secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
  "name": "my-edge-site",

  "dns": "9.9.9.9",
  "logLevel": "INFO",
  "interface": "pangolin",
  "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": []
}
```

<Note>
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 `pangolin --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.
</Note>

<Warning>
Fields like `secret`, `tlsClientKey`, and `adPreSharedKey` are sensitive. Restrict file permissions on the config file accordingly.
</Warning>

## Docker Socket Integration

The site can integrate with the Docker socket to provide remote inspection of Docker containers. This allows Pangolin to query and retrieve detailed information about containers running on the site, including metadata, network configuration, port mappings, and more.

**Configuration:**

You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET` environment variable. If the Docker socket is not available or accessible, the site will gracefully disable Docker integration and continue normal operation.

Supported values include:

-   Local UNIX socket (default):
    >You must mount the socket file into the container using a volume, so the site can access it.

    `unix:///var/run/docker.sock`

-   TCP socket (e.g., via Docker Socket Proxy):

    `tcp://localhost:2375`

-   HTTP/HTTPS endpoints (e.g., remote Docker APIs):

    `http://your-host:2375`

-   SSH connections (experimental, requires SSH setup):

    `ssh://user@host`


```yaml
services:
    pangolin-site:
        image: fosrl/pangolin-cli
        container_name: pangolin-site
        restart: unless-stopped
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock:ro
        environment:
            - PANGOLIN_ENDPOINT=https://example.com
            - SITE_ID=2ix2t8xk22ubpfy
            - SITE_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
            - DOCKER_SOCKET=unix:///var/run/docker.sock
```

<Note>
If the Docker socket is not available or accessible, the site will gracefully disable Docker integration and continue normal operation.
</Note>

**Hostnames vs IPs**

When the Docker Socket Integration is used, depending on the network which the site is run with, either the hostname (generally considered the container name) or the IP address of the container will be sent to Pangolin:

- **Running in Network Mode 'host'**: IP addresses will be used
- **Running in Network Mode 'bridge'**: IP addresses will be used
- **Running in docker-compose without a network specification**: Docker compose creates a network for the compose by default, hostnames will be used
- **Running on docker-compose with defined network**: Hostnames will be used

**Docker Enforce Network Validation**

When run as a Docker container, the site can validate that the target being provided is on the same network as the site container and only return containers directly accessible by the site. Validation will be carried out against either the hostname/IP Address and the Port number to ensure the running container is exposing the ports to the site.

Validation is `false` by default. It can be enabled via setting the `--docker-enforce-network-validation` CLI argument or by setting the `DOCKER_ENFORCE_NETWORK_VALIDATION` environment variable.

<Warning>
If the site container is run with a network mode of `host`, this feature will not work. Running in `host` mode causes the container to share its resources with the host machine, making it impossible to retrieve specific host container information for network validation.
</Warning>

## Updown Scripts

You can pass in an updown script for the site to call when it is adding or removing a target:

```bash
--updown "python3 test.py"
```

The script will be called with arguments when a target is added or removed:

```bash
python3 test.py add tcp localhost:8556
python3 test.py remove tcp localhost:8556
```

<Info>
Returning a string from the script in the format of a target (`ip:dst` so `10.0.0.1:8080`) will override the target and use this value instead to proxy.
</Info>

<Note>
You can look at `updown.py` as a reference script to get started!
</Note>

## mTLS Authentication

The site supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA.

### Option 1: PKCS12 (Legacy)

<Note>
This is the original method and still supported.
</Note>

**Requirements:**
- File must contain:
  - Client private key
  - Public certificate
  - CA certificate
- Encrypted `.p12` files are **not supported**

**Example:**

```bash
pangolin \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert ./client.p12
```

### Option 2: Split PEM Files (Preferred)

You can now provide separate files for:

- `--tls-client-cert-file`: client certificate (`.crt` or `.pem`)
- `--tls-client-key`: client private key (`.key` or `.pem`)
- `--tls-client-ca`: CA cert to verify the server (can be specified multiple times)

**Example:**

```bash
pangolin \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert-file ./client.crt \
--tls-client-key ./client.key \
--tls-client-ca ./ca.crt
```