mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-03-11 13:16:44 +00:00
many updates for 1.13
This commit is contained in:
miloschwartz
@@ -1,30 +1,9 @@
|
||||
---
|
||||
title: "Configure Site"
|
||||
title: "Configure Sites"
|
||||
description: "Configure Newt for connecting to Pangolin sites"
|
||||
---
|
||||
Newt is a fully user space [WireGuard](https://www.wireguard.com/) tunnel client and TCP/UDP proxy, designed to securely expose private resources controlled by Pangolin. By using Newt, you don't need to manage complex WireGuard tunnels and NATing.
|
||||
|
||||
## Preview
|
||||
|
||||
<Frame caption="Newt interface preview">
|
||||
<img src="/images/newt-preview.png" alt="Newt Preview"/>
|
||||
</Frame>
|
||||
|
||||
## How Newt Works
|
||||
|
||||
### Registers with Pangolin
|
||||
|
||||
Using the Newt ID and a secret, the client will make HTTP requests to Pangolin to receive a session token. Using that token, it will connect to a websocket and maintain that connection. Control messages will be sent over the websocket.
|
||||
|
||||
### Receives WireGuard Control Messages
|
||||
|
||||
When Newt receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go) fully in user space. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up.
|
||||
|
||||
### Receives Proxy Control Messages
|
||||
|
||||
When Newt receives proxy control messages, it will use the information encoded to create a local low level TCP and UDP proxies attached to the virtual tunnel in order to relay traffic to programmed targets.
|
||||
|
||||
## Configuration Arguments
|
||||
## Flags
|
||||
|
||||
<ResponseField name="id" type="string" required>
|
||||
Newt ID generated by Pangolin to identify the client.
|
||||
@@ -110,8 +89,8 @@ When Newt receives proxy control messages, it will use the information encoded t
|
||||
**Example**: `/path/to/client.p12`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="accept-clients" type="boolean">
|
||||
Enable WireGuard server mode to accept incoming Olm client connections.
|
||||
<ResponseField name="disable-clients" type="boolean">
|
||||
Prevent Pangolin Clients from connecting to resources on this site.
|
||||
|
||||
**Default**: `false`
|
||||
</ResponseField>
|
||||
@@ -144,6 +123,10 @@ When Newt receives proxy control messages, it will use the information encoded t
|
||||
|
||||
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>
|
||||
@@ -240,113 +223,6 @@ All CLI arguments can be set using environment variables as an alternative to co
|
||||
Load the config JSON from this file instead of in the home folder.
|
||||
</ResponseField>
|
||||
|
||||
<Note>
|
||||
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
|
||||
</Note>
|
||||
|
||||
## Basic Configuration Examples
|
||||
|
||||
### Binary Example
|
||||
|
||||
```bash
|
||||
newt \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://example.com
|
||||
```
|
||||
|
||||
### Docker Compose with Environment Variables (Recommended)
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- PANGOLIN_ENDPOINT=https://app.pangolin.net
|
||||
- NEWT_ID=2ix2t8xk22ubpfy
|
||||
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
|
||||
- HEALTH_FILE=/tmp/healthy
|
||||
```
|
||||
|
||||
### Docker Compose with CLI Arguments
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
command:
|
||||
- --id 31frd0uzbjvp721
|
||||
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
|
||||
- --endpoint https://app.pangolin.net
|
||||
- --health-file /tmp/healthy
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Accept Client Connections
|
||||
|
||||
When the `--accept-clients` flag is enabled (or `ACCEPT_CLIENTS=true` environment variable is set), Newt operates as a WireGuard server that can accept incoming client connections from other devices. This enables peer-to-peer connectivity through the Newt instance.
|
||||
|
||||
#### Client Tunneling Modes
|
||||
|
||||
Newt supports two WireGuard tunneling modes:
|
||||
|
||||
##### Userspace Mode (Default)
|
||||
|
||||
By default, Newt uses a fully userspace WireGuard implementation using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go). This mode:
|
||||
|
||||
- **Does not require root privileges**
|
||||
- **Works on all supported platforms** (Linux, Windows, macOS)
|
||||
- **Does not require WireGuard kernel module** to be installed
|
||||
- **Runs entirely in userspace** - no system network interface is created
|
||||
- **Is containerization-friendly** - works seamlessly in Docker containers
|
||||
|
||||
<Note>
|
||||
This is the recommended mode for most deployments, especially containerized environments.
|
||||
</Note>
|
||||
|
||||
##### Native Mode (Linux only)
|
||||
|
||||
When using the `--native` flag or setting `USE_NATIVE_INTERFACE=true`, Newt uses the native WireGuard kernel module. This mode:
|
||||
|
||||
- **Requires root privileges** to create and manage network interfaces
|
||||
- **Only works on Linux** with the WireGuard kernel module installed
|
||||
- **Creates a real network interface** (e.g., `newt0`) on the system
|
||||
- **May offer better performance** for high-throughput scenarios
|
||||
- **Requires proper network permissions** and may conflict with existing network configurations
|
||||
|
||||
<Warning>
|
||||
Native mode requires Linux with WireGuard kernel module and must run as root.
|
||||
</Warning>
|
||||
|
||||
#### Native Mode Requirements
|
||||
|
||||
To use native mode:
|
||||
|
||||
1. Run on a Linux system
|
||||
2. Install the WireGuard kernel module
|
||||
3. Run Newt as root (`sudo`)
|
||||
4. Ensure the system allows creation of network interfaces
|
||||
|
||||
**Docker Compose example:**
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- PANGOLIN_ENDPOINT=https://app.pangolin.net
|
||||
- NEWT_ID=2ix2t8xk22ubpfy
|
||||
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
|
||||
- ACCEPT_CLIENTS=true
|
||||
```
|
||||
|
||||
### 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.
|
||||
@@ -429,32 +305,3 @@ Newt supports mutual TLS (mTLS) authentication if the server has been configured
|
||||
- Public certificate
|
||||
- CA certificate
|
||||
- Encrypted PKCS12 files are currently not supported
|
||||
|
||||
**Binary Example:**
|
||||
|
||||
```bash
|
||||
newt \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://example.com \
|
||||
--tls-client-cert ./client.p12
|
||||
```
|
||||
|
||||
**Docker Compose Example:**
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt
|
||||
container_name: newt
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
- PANGOLIN_ENDPOINT=https://app.pangolin.net
|
||||
- NEWT_ID=2ix2t8xk22ubpfy
|
||||
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
|
||||
- TLS_CLIENT_CERT=./client.p12
|
||||
```
|
||||
|
||||
<Note>
|
||||
Get your `id` and `secret` from the Pangolin dashboard when creating a Newt client.
|
||||
</Note>
|
||||
|
||||
Reference in New Issue
Block a user