pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-07 21:46:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync with newt and olm readme

Browse Source
This commit is contained in:
Owen
2025-12-10 16:24:42 -05:00
parent c31b0cecde
commit 00b0150fea
4 changed files with 442 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
manage/clients/add-client.mdx
View File

@@ -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. 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 Tailscale's recommendations [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.
This should help to: This should help to:
- Increase performance (speed/bandwidth) - Increase performance (speed/bandwidth)

179
manage/clients/configure-client.mdx
View File

@@ -41,18 +41,32 @@ Refer to the [documentation in the official repository](https://github.com/fosrl
**Example**: `https://pangolin.example.com` **Example**: `https://pangolin.example.com`
</ResponseField> </ResponseField>
<ResponseField name="org" type="string">
Organization ID to connect to.
</ResponseField>
<ResponseField name="user-token" type="string">
User authentication token.
</ResponseField>
<ResponseField name="mtu" type="integer"> <ResponseField name="mtu" type="integer">
MTU for the WireGuard interface. MTU for the internal WireGuard interface.
**Default**: `1280` **Default**: `1280`
</ResponseField> </ResponseField>
<ResponseField name="dns" type="string"> <ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint. DNS server to use to resolve the endpoint.
**Default**: `8.8.8.8` **Default**: `8.8.8.8`
</ResponseField> </ResponseField>
<ResponseField name="upstream-dns" type="string">
Upstream DNS server(s), comma-separated.
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="log-level" type="string"> <ResponseField name="log-level" type="string">
The log level to use for Olm output. The log level to use for Olm output.
@@ -73,16 +87,46 @@ Refer to the [documentation in the official repository](https://github.com/fosrl
**Default**: `5s` **Default**: `5s`
</ResponseField> </ResponseField>
<ResponseField name="holepunch" type="boolean"> <ResponseField name="interface" type="string">
Enable NAT hole punching mode instead of relaying through the VPS. Name of the WireGuard interface.
**Default**: `olm`
</ResponseField>
<ResponseField name="enable-api" type="boolean">
Enable API server for receiving connection requests.
**Default**: `false` **Default**: `false`
</ResponseField> </ResponseField>
<ResponseField name="config-file" type="string"> <ResponseField name="http-addr" type="string">
Path to a configuration file containing the same arguments as command line. HTTP server address (e.g., ':9452').
**Example**: `/etc/olm/config.yaml` **Default**: `:9452`
</ResponseField>
<ResponseField name="socket-path" type="string">
Unix socket path (or named pipe on Windows).
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
<ResponseField name="disable-holepunch" type="boolean">
Disable hole punching.
**Default**: `false`
</ResponseField>
<ResponseField name="override-dns" type="boolean">
Override system DNS settings.
**Default**: `false`
</ResponseField>
<ResponseField name="disable-relay" type="boolean">
Disable relay connections.
**Default**: `false`
</ResponseField> </ResponseField>
### Environment Variables ### Environment Variables
@@ -105,46 +149,141 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
Olm secret for authentication (equivalent to `--secret`) Olm secret for authentication (equivalent to `--secret`)
</ResponseField> </ResponseField>
<ResponseField name="OLM_MTU" type="integer"> <ResponseField name="ORG" type="string">
MTU for the WireGuard interface (equivalent to `--mtu`) Organization ID to connect to (equivalent to `--org`)
</ResponseField>
<ResponseField name="USER_TOKEN" type="string">
User authentication token (equivalent to `--user-token`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
**Default**: `1280` **Default**: `1280`
</ResponseField> </ResponseField>
<ResponseField name="OLM_DNS" type="string"> <ResponseField name="DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`) DNS server to use to resolve the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8` **Default**: `8.8.8.8`
</ResponseField> </ResponseField>
<ResponseField name="OLM_LOG_LEVEL" type="string"> <ResponseField name="UPSTREAM_DNS" type="string">
Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`) Log level (equivalent to `--log-level`)
**Default**: `INFO` **Default**: `INFO`
</ResponseField> </ResponseField>
<ResponseField name="OLM_PING_INTERVAL" type="string"> <ResponseField name="PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`) Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s` **Default**: `3s`
</ResponseField> </ResponseField>
<ResponseField name="OLM_PING_TIMEOUT" type="string"> <ResponseField name="PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`) Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s` **Default**: `5s`
</ResponseField> </ResponseField>
<ResponseField name="OLM_HOLEPUNCH" type="boolean"> <ResponseField name="INTERFACE" type="string">
Enable NAT hole punching mode (equivalent to `--holepunch`) Name of the WireGuard interface (equivalent to `--interface`)
**Default**: `olm`
</ResponseField>
<ResponseField name="ENABLE_API" type="boolean">
Enable API server for receiving connection requests (equivalent to `--enable-api`)
Set to "true" to enable
**Default**: `false` **Default**: `false`
</ResponseField> </ResponseField>
<ResponseField name="OLM_HEALTH_FILE" type="string"> <ResponseField name="HTTP_ADDR" type="string">
Path to health file for connection monitoring (equivalent to `--health-file`) HTTP server address (equivalent to `--http-addr`)
**Default**: `:9452`
</ResponseField> </ResponseField>
<ResponseField name="OLM_CONFIG_FILE" type="string"> <ResponseField name="SOCKET_PATH" type="string">
Load the config from this file instead of command line arguments (equivalent to `--config-file`) Unix socket path or Windows named pipe (equivalent to `--socket-path`)
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField> </ResponseField>
<ResponseField name="DISABLE_HOLEPUNCH" type="boolean">
Disable hole punching (equivalent to `--disable-holepunch`)
Set to "true" to disable
**Default**: `false`
</ResponseField>
<ResponseField name="OVERRIDE_DNS" type="boolean">
Override system DNS settings (equivalent to `--override-dns`)
Set to "true" to enable
**Default**: `false`
</ResponseField>
<ResponseField name="DISABLE_RELAY" type="boolean">
Disable relay connections (equivalent to `--disable-relay`)
Set to "true" to disable
**Default**: `false`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Set to the location of a JSON file to load secret values
</ResponseField>
### Loading secrets from files
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
```
$ cat ~/.config/olm-client/config.json
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"org": "",
"userToken": "",
"mtu": 1280,
"dns": "8.8.8.8",
"upstreamDNS": ["8.8.8.8:53"],
"interface": "olm",
"logLevel": "INFO",
"enableApi": false,
"httpAddr": "",
"socketPath": "/var/run/olm.sock",
"pingInterval": "3s",
"pingTimeout": "5s",
"disableHolepunch": false,
"overrideDNS": false,
"disableRelay": false,
"tlsClientCert": ""
}
```
This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!
Default locations:
- **macOS**: `~/Library/Application Support/olm-client/config.json`
- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json`
- **Linux/Others**: `~/.config/olm-client/config.json`
### API
Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details.

55
manage/clients/install-client.mdx
View File

@@ -49,7 +49,7 @@ If you're looking for a CLI interface for a client, we recommend using Pangolin
Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user. Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user.
### Binary Installation ### Binary Installation (Linux)
#### Quick Install (Recommended) #### Quick Install (Recommended)
@@ -118,6 +118,47 @@ WantedBy=multi-user.target
Make sure to move the binary to `/usr/local/bin/olm` before creating the service! Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
</Warning> </Warning>
### Docker
You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended):
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://example.com
- OLM_ID=31frd0uzbjvp721
- OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
```
You can also pass the CLI args to the container:
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
devices:
- /dev/net/tun:/dev/net/tun
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
```
**Docker Configuration Notes:**
- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
### Windows Service ### Windows Service
On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool. You can also run the following: On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool. You can also run the following:
@@ -175,6 +216,16 @@ Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes: Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:
- **Windows**: Olm will run as a service. You can use the commands described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the background if needed! - **Windows**: Olm will run as a service. You can use the commands described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the background if needed!
- **LXC containers**: Need to be configured to allow tun access. See [Tailscale's guide](https://tailscale.com/kb/1130/lxc-unprivileged). - **LXC containers**: Need to be configured to allow tun access. See below.
- **Linux**: May require root privileges or specific capabilities to create tun interfaces. - **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **macOS**: May require additional permissions for network interface creation. - **macOS**: May require additional permissions for network interface creation.
#### LXC Container Configuration
1. Create your LXC container.
2. Go to the Resources tab of the container.
3. Select Add. Then select Device Passthrough.
4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
5. If the container is running, shut it down and start it up again.
Once /dev/net/tun is available, the olm can run within the LXC.

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

@@ -36,7 +36,7 @@ description: "Configure Newt for connecting to Pangolin sites"
<ResponseField name="dns" type="string"> <ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint. DNS server to use for resolving the endpoint.
**Default**: `8.8.8.8` **Default**: `9.9.9.9`
</ResponseField> </ResponseField>
<ResponseField name="log-level" type="string"> <ResponseField name="log-level" type="string">
@@ -83,42 +83,102 @@ description: "Configure Newt for connecting to Pangolin sites"
**Example**: `/path/to/updown.sh` **Example**: `/path/to/updown.sh`
</ResponseField> </ResponseField>
<ResponseField name="tls-client-cert" type="string"> <ResponseField name="blueprint-file" type="string">
Client certificate (p12 or pfx) for mutual TLS (mTLS) authentication. Path to blueprint file to define Pangolin resources and configurations.
**Example**: `/path/to/client.p12` **Example**: `/path/to/blueprint.yaml`
</ResponseField> </ResponseField>
<ResponseField name="disable-clients" type="boolean"> <ResponseField name="no-cloud" type="boolean">
Prevent Pangolin Clients from connecting to resources on this site. Don't fail over to the cloud when using managed nodes in Pangolin Cloud.
**Default**: `false` **Default**: `false`
</ResponseField> </ResponseField>
<ResponseField name="generateAndSaveKeyTo" type="string"> <ResponseField name="disable-clients" type="boolean">
Path to save generated private key (used with accept-clients). Disable clients on the WireGuard interface.
**Example**: `/var/key` **Default**: `false` (clients enabled)
</ResponseField> </ResponseField>
<ResponseField name="native" type="boolean"> <ResponseField name="native" type="boolean">
Use native WireGuard interface when accepting clients (requires WireGuard kernel module and Linux, must run as root). Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root).
**Default**: `false` (uses userspace netstack) **Default**: `false` (uses userspace netstack)
</ResponseField> </ResponseField>
<ResponseField name="interface" type="string"> <ResponseField name="interface" type="string">
Name of the WireGuard interface (used with native mode). Name of the WireGuard interface.
**Default**: `newt` **Default**: `newt`
</ResponseField> </ResponseField>
<ResponseField name="keep-interface" type="boolean"> <ResponseField name="metrics" type="boolean">
Keep the WireGuard interface after shutdown (used with native mode). Enable Prometheus /metrics exporter.
**Default**: `true`
</ResponseField>
<ResponseField name="otlp" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.
**Default**: `false` **Default**: `false`
</ResponseField> </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>
## Environment Variables ## 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. 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.
@@ -148,7 +208,21 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
<ResponseField name="DNS" type="string"> <ResponseField name="DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`) DNS server to use for resolving the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8` **Default**: `9.9.9.9`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Load the config JSON from this file instead of in the home folder.
</ResponseField>
<ResponseField name="BLUEPRINT_FILE" type="string">
Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
</ResponseField>
<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>
<ResponseField name="LOG_LEVEL" type="string"> <ResponseField name="LOG_LEVEL" type="string">
@@ -177,10 +251,6 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
Path to updown script for target add/remove events (equivalent to `--updown`) Path to updown script for target add/remove events (equivalent to `--updown`)
</ResponseField> </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"> <ResponseField name="DOCKER_ENFORCE_NETWORK_VALIDATION" type="boolean">
Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`) Validate container targets are on same network (equivalent to `--docker-enforce-network-validation`)
@@ -191,16 +261,12 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
Path to health file for connection monitoring (equivalent to `--health-file`) Path to health file for connection monitoring (equivalent to `--health-file`)
</ResponseField> </ResponseField>
<ResponseField name="ACCEPT_CLIENTS" type="boolean"> <ResponseField name="DISABLE_CLIENTS" type="boolean">
Enable WireGuard server mode (equivalent to `--accept-clients`) Disable clients on the WireGuard interface (equivalent to `--disable-clients`).
**Default**: `false` **Default**: `false`
</ResponseField> </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"> <ResponseField name="USE_NATIVE_INTERFACE" type="boolean">
Use native WireGuard interface (Linux only, equivalent to `--native`) Use native WireGuard interface (Linux only, equivalent to `--native`)
@@ -213,37 +279,119 @@ When both environment variables and CLI arguments are provided, CLI arguments ta
**Default**: `newt` **Default**: `newt`
</ResponseField> </ResponseField>
<ResponseField name="KEEP_INTERFACE" type="boolean"> <ResponseField name="NEWT_METRICS_PROMETHEUS_ENABLED" type="boolean">
Keep the WireGuard interface after shutdown (equivalent to `--keep-interface`) 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` **Default**: `false`
</ResponseField> </ResponseField>
<ResponseField name="CONFIG_FILE" type="string"> <ResponseField name="NEWT_ADMIN_ADDR" type="string">
Load the config JSON from this file instead of in the home folder. Admin/metrics bind address (equivalent to `--metrics-admin-addr`).
**Default**: `127.0.0.1:2112`
</ResponseField> </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>
<ResponseField name="NEWT_REGION" type="string">
Optional region resource attribute for telemetry and metrics (equivalent to `--region`).
</ResponseField>
<ResponseField name="ENFORCE_HC_CERT" type="boolean">
Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).
**Default**: `false`
</ResponseField>
<ResponseField name="TLS_CLIENT_CERT" type="string">
Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`)
</ResponseField>
<ResponseField name="TLS_CLIENT_KEY" type="string">
Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`)
</ResponseField>
<ResponseField name="TLS_CLIENT_CAS" type="string">
Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags)
</ResponseField>
<ResponseField name="TLS_CLIENT_CERT_PKCS12" type="string">
Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead
</ResponseField>
## Loading secrets from files
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
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"tlsClientCert": ""
}
```
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:
- **macOS**: `~/Library/Application Support/newt-client/config.json`
- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
- **Linux/Others**: `~/.config/newt-client/config.json`
### Docker Socket Integration ### 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. 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:** **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. 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, Newt will gracefully disable Docker integration and continue normal operation.
```yaml title="docker-compose.yml" Supported values include:
- Local UNIX socket (default):
>You must mount the socket file into the container using a volume, so Newt 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: services:
newt: newt:
image: fosrl/newt image: fosrl/newt
container_name: newt container_name: newt
restart: unless-stopped restart: unless-stopped
volumes: volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro - /var/run/docker.sock:/var/run/docker.sock:ro
environment: environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net - PANGOLIN_ENDPOINT=https://example.com
- NEWT_ID=2ix2t8xk22ubpfy - NEWT_ID=2ix2t8xk22ubpfy
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2 - NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
- DOCKER_SOCKET=/var/run/docker.sock - DOCKER_SOCKET=unix:///var/run/docker.sock
``` ```
<Note> <Note>
@@ -296,12 +444,47 @@ You can look at `updown.py` as a reference script to get started!
### mTLS Authentication ### mTLS Authentication
Newt supports mutual TLS (mTLS) authentication if the server has been configured to request a client certificate. Newt 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:** **Requirements:**
- Only PKCS12 (.p12 or .pfx) file format is accepted - File must contain:
- The PKCS12 file must contain: - Client private key
- Private key
- Public certificate - Public certificate
- CA certificate - CA certificate
- Encrypted PKCS12 files are currently not supported - Encrypted `.p12` files are **not supported**
**Example:**
```bash
newt \
--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
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert-file ./client.crt \
--tls-client-key ./client.key \
--tls-client-ca ./ca.crt
```