---
title: "Configure Sites"
description: "Configure Newt for connecting to Pangolin sites"
---

## Flags

<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>
</ResponseField>

<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="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**: `8.8.8.8`
</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="tls-client-cert" type="string">
  Client certificate (p12 or pfx) for mutual TLS (mTLS) authentication.
  
  **Example**: `/path/to/client.p12`
</ResponseField>

<ResponseField name="disable-clients" type="boolean">
  Prevent Pangolin Clients from connecting to resources on this site.
  
  **Default**: `false`
</ResponseField>

<ResponseField name="generateAndSaveKeyTo" type="string">
  Path to save generated private key (used with accept-clients).
  
  **Example**: `/var/key`
</ResponseField>

<ResponseField name="native" type="boolean">
  Use native WireGuard interface when accepting clients (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 (used with native mode).
  
  **Default**: `newt`
</ResponseField>

<ResponseField name="keep-interface" type="boolean">
  Keep the WireGuard interface after shutdown (used with native mode).
  
  **Default**: `false`
</ResponseField>

## Environment Variables

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.

<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>

<ResponseField name="PANGOLIN_ENDPOINT" type="string">
  Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>

<ResponseField name="NEWT_ID" type="string">
  Newt ID generated by Pangolin (equivalent to `--id`)
</ResponseField>

<ResponseField name="NEWT_SECRET" type="string">
  Newt secret for authentication (equivalent to `--secret`)
</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**: `8.8.8.8`
</ResponseField>

<ResponseField name="LOG_LEVEL" type="string">
  Log level (equivalent to `--log-level`)
  
  **Default**: `INFO`
</ResponseField>

<ResponseField name="DOCKER_SOCKET" type="string">
  Path to Docker socket for container discovery (equivalent to `--docker-socket`)
</ResponseField>

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

<ResponseField name="UPDOWN_SCRIPT" type="string">
  Path to updown script for target add/remove events (equivalent to `--updown`)
</ResponseField>

<ResponseField name="TLS_CLIENT_CERT" type="string">
  Path to client certificate for mTLS (equivalent to `--tls-client-cert`)
</ResponseField>

<ResponseField name="DOCKER_ENFORCE_NETWORK_VALIDATION" type="boolean">
  Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)
  
  **Default**: `false`
</ResponseField>

<ResponseField name="HEALTH_FILE" type="string">
  Path to health file for connection monitoring (equivalent to `--health-file`)
</ResponseField>

<ResponseField name="ACCEPT_CLIENTS" type="boolean">
  Enable WireGuard server mode (equivalent to `--accept-clients`)
  
  **Default**: `false`
</ResponseField>

<ResponseField name="GENERATE_AND_SAVE_KEY_TO" type="string">
  Path to save generated private key (equivalent to `--generateAndSaveKeyTo`)
</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="KEEP_INTERFACE" type="boolean">
  Keep the WireGuard interface after shutdown (equivalent to `--keep-interface`)
  
  **Default**: `false`
</ResponseField>

<ResponseField name="CONFIG_FILE" type="string">
  Load the config JSON from this file instead of in the home folder.
</ResponseField>

### Docker Socket Integration

Newt 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 Newt client, 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. On most Linux systems the socket is `/var/run/docker.sock`. When deploying Newt as a container, you need to mount the host socket as a volume for the Newt container to access it.

```yaml title="docker-compose.yml"
services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - PANGOLIN_ENDPOINT=https://app.pangolin.net
      - NEWT_ID=2ix2t8xk22ubpfy
      - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
      - DOCKER_SOCKET=/var/run/docker.sock
```

<Note>
If the Docker socket is not available or accessible, Newt 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 Newt 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, Newt can validate that the target being provided is on the same network as the Newt container and only return containers directly accessible by Newt. 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 Newt.

<Warning>
If the Newt 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>

**Configuration:**

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.

### Updown Scripts

You can pass in an updown script for Newt 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

Newt supports mutual TLS (mTLS) authentication if the server has been configured to request a client certificate.

**Requirements:**
- Only PKCS12 (.p12 or .pfx) file format is accepted
- The PKCS12 file must contain:
  - Private key
  - Public certificate
  - CA certificate
- Encrypted PKCS12 files are currently not supported