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

many updates for 1.13

Browse Source
This commit is contained in:
miloschwartz
2025-12-10 15:20:41 -05:00
parent 5c2de2a7ab
commit c31b0cecde
36 changed files with 705 additions and 912 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
manage/sites/add-site.mdx
View File

@@ -1,83 +0,0 @@
---
title: "Add Site"
description: "Create a site to connect to a remote network and expose resources"
---
A site is a connection to a remote network that allows Pangolin to establish a tunnel to that network. Sites are the foundation for exposing resources because all resources exist on a site. Newt is the software connector that facilitates the connection and addresses the targets on the remote networks.
## How Sites Work
### The Connection Process
1. **Site Creation**: You create a site in Pangolin's dashboard
2. **Newt Registration**: Newt registers with Pangolin using the site credentials
3. **Tunnel Establishment**: Newt establishes a WireGuard tunnel to the remote network
4. **Resource Exposure**: Resources on the remote network become accessible through the tunnel
### Why Sites Matter
Sites are the first step to exposing resources with Pangolin because:
- **Resources exist on sites**: All resources must be associated with a site
- **Newt addresses targets**: Newt is what actually connects to the targets on remote networks
- **Tunnel enables access**: The tunnel allows Pangolin to expose resources without opening ports or needing a public IP
- **Secure communication**: All traffic flows through encrypted WireGuard tunnels
## Site Types
Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios.
<Card title="Newt Tunnel (Recommended)">
This site allows you to expose resources on a remote network via a fully managed tunnel. This requires the Newt connector to be running on the remote network. It's the easiest to use and requires the least amount of setup. No NAT configuration required.
</Card>
<CardGroup cols={2}>
<Card title="Local Site">
Use this if you want to expose resources on the same host as the Pangolin server (this is for self-hosted Pangolin only). No tunnels are created. Ports must be opened on the host running Pangolin (this has to happen anyway for Pangolin to work).
</Card>
<Card title="Basic WireGuard">
This is self-hosted only. This uses a raw WireGuard connection without Newt, thus there is no websocket connection, requiring more manual management. These sites require NAT to address targets running on other hosts on the remote network. Otherwise, you can only expose resources on the remote WireGuard peer itself.
</Card>
</CardGroup>
## Adding a Site
<Steps>
<Step title="Navigate to Sites">
In the Pangolin dashboard, go to the **Sites** section and click **Add Site**.
</Step>
<Step title="Configure site details">
Configure the basic information:
- **Site Name**: A descriptive name for your site
</Step>
<Step title="Choose site type">
Select the appropriate site type based on your needs:
- **Newt Tunnel**: For remote networks with Newt connector
- **Local Site**: For resources on the same host as Pangolin
- **Basic WireGuard**: For direct WireGuard connections
</Step>
<Step title="Generate Newt credentials">
Pangolin will generate:
- **Newt ID**: Unique identifier for the Newt client
- **Secret**: Authentication secret for secure connection
- **Endpoint**: The Pangolin server endpoint
</Step>
<Step title="Install Site">
Use the generated credentials to configure the site on the remote network. See [Install Site](/manage/sites/install-site) for detailed instructions on how to install Newt.
</Step>
<Step title="Verify connection">
Once Newt is running, the site status should show as "Online" in the dashboard. Sometimes it takes a few moments for the status to update.
</Step>
</Steps>
## Notes
- Sites require Newt to be running on the remote network
- Each site can host multiple resources
- Connection status is monitored automatically

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

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

50
manage/sites/credentials.mdx Normal file
View File

@@ -0,0 +1,50 @@
---
title: "Site Credentials"
description: "Understanding how site credentials work and how they can be rotated & regenerated"
---
## Understanding Credentials
Every site is provisioned with a unique identifier (ID), secret, and endpoint. The site uses the combination of these three to establish a secure, encrypted connection to the server.
### ID
Example: `ln8yqs6w85la5zg`
The ID represents the site connection type in the system. Every Newt site has an ID.
This value is not a secret and it is okay if made publically available.
### Secret
Example: `tfpwoc580jf1l1glfagix0o97p8kirjogdflqg604n0tr3to`
The secret represents the "password" of the site. This secret must match the secret hashed in the system for the relevant ID.
<Note>
This is a _secret_! Only share it with trusted people and be sure to store it safely and securely.
</Note>
When the site connects, it uses this secret as a first handshake with the server. The server then passes temporary session credentials back to the site before it can initiate a websocket connection. Once the websocket connection is established, ephemeral keys are used to establish tunnels using WireGuard.
### Endpoint
Example: `https://app.pangolin.net` or `https://pangolin.my-server.com`
The endpoint is how the site knows which server to connect to. This is the fully qualified hostname of the Pangolin server (the URL you use to access the dashboard). For Pangolin cloud, the endpoint is `https://app.pangolin.net`. The site uses this endpoint ot establish a websocket connection and receive control messages from the server.
## Rotating and Regenerating Credentials
<Note>
This is an Enterprise Edition only feature.
</Note>
Site credentials can be regenerated. Regenerating credentials will completely invalidate the previous ID and secret. Use this feature if you have lost the secret and need to reset the credentials, or if you wish to rotate credentials on a regular basis for extra security.
To regenerate credentials, visit Sites > Your Site > Credentials in the Pangolin admin dashboard.
### Regenerate vs. Regenerate and Disconnect
Regenerate simply recreates the credentials and invalidates the old ones. The site will remain connected until you restart it with the new credentials.
Regenerate and Disconnect recreates the credentials and invalides the old ones. The site will instantly disconnect and will require you to restart it with the new credentials.

135
manage/sites/install-kubernetes.mdx
View File

@@ -9,95 +9,76 @@ This guide assumes you already are familiar with Kubernetes concepts and you ful
## Global Prerequisites
<Check>
- Kubernetes Cluster (v1.28.15+)
- Access to the Kubernetes Cluster
- Helm (v3.0+) installed, see <Link href="https://helm.sh/docs/intro/install/">Helm install docs</Link>
</Check>
<Tip>
**Recommended**: Helm Chart Installation.
</Tip>
## Helm Installation
---
All Fossorial Helm charts are available on Artifact Hub. See <Link href="https://artifacthub.io/packages/search?org=fosrl">Fossorial Charts</Link>.
<Tabs>
<Tab title="Helm">
<Steps>
<Step title="Add Fossorial Helm repo">
```bash
helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial
helm search repo fossorial
```
</Step>
<Step title="Prepare Installation files">
# Helm Installation
Prepare your Newt credentials:
```env title="newt-cred.env"
PANGOLIN_ENDPOINT=<your-endpoint>
NEWT_ID=<your-id>
NEWT_SECRET=<your-secret>
```
<Tip>
All Fossorial Helm charts are available on Artifact Hub. See <Link href="https://artifacthub.io/packages/search?org=fosrl">Fossorial Charts</Link>.
</Tip>
Prepare a values file with your desired configuration.
## Install Newt
<Tip>See <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt chart values configuration options</Link>.</Tip>
<Steps>
<Step title="Add Fossorial Helm repo">
```bash
helm repo add fossorial https://charts.fossorial.io
helm repo update fossorial
helm search repo fossorial
```
</Step>
<Step title="Prepare Installation files">
```yaml title="values-newt.yaml"
newtInstances:
- name: main
enabled: true
auth:
existingSecretName: newt-cred
keys:
endpointKey: PANGOLIN_ENDPOINT
idKey: NEWT_ID
secretKey: NEWT_SECRET
```
</Step>
<Step title="Newt Installation">
Prepare your Newt credentials:
```env title="newt-cred.env"
PANGOLIN_ENDPOINT=<your-endpoint>
NEWT_ID=<your-id>
NEWT_SECRET=<your-secret>
```
Create a Kubernetes Secret from the env file created earlier:
```bash
kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env
```
Prepare a values file with your desired configuration.
Install Newt with Helm:
```bash
helm install my-newt fossorial/newt \
-n newt --create-namespace \
-f values-newt.yaml
```
<Tip>See <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt chart values configuration options</Link>.</Tip>
```yaml title="values-newt.yaml"
newtInstances:
- name: main
enabled: true
auth:
existingSecretName: newt-cred
keys:
endpointKey: PANGOLIN_ENDPOINT
idKey: NEWT_ID
secretKey: NEWT_SECRET
```
</Step>
<Step title="Newt Installation">
Create a Kubernetes Secret from the env file created earlier:
```bash
kubectl create secret generic newt-cred -n newt --from-env-file=newt-cred.env
```
Install Newt with Helm:
```bash
helm install my-newt fossorial/newt \
-n newt --create-namespace \
-f values-newt.yaml
```
Change the release name (`my-newt`), namespace (`newt`), and values filename as needed.
</Step>
<Step title="Upgrade or rollback">
```bash
# Update repo to get latest charts
helm repo update fossorial
# Upgrade Newt (after editing values)
helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml
```
```bash
# Roll back to a previous revision
helm rollback my-newt 1 -n newt
```
</Step>
</Steps>
</Tab>
</Tabs>
---
Change the release name (`my-newt`), namespace (`newt`), and values filename as needed.
</Step>
<Step title="Upgrade or rollback">
```bash
# Update repo to get latest charts
helm repo update fossorial
# Upgrade Newt (after editing values)
helm upgrade my-newt fossorial/newt -n newt -f values-newt.yaml
```
```bash
# Roll back to a previous revision
helm rollback my-newt 1 -n newt
```
</Step>
</Steps>
## Customizing Your Values
@@ -105,8 +86,6 @@ All configuration options are documented in the respective repositories:
- <Link href="https://github.com/fosrl/helm-charts/tree/main/charts/newt">Newt Helm chart values</Link>
---
## References
- <Link href="https://github.com/fosrl/helm-charts">All Fossorial Helm Charts repo</Link>

37
manage/sites/install-site.mdx
View File

@@ -1,29 +1,9 @@
---
title: "Install Site"
title: "Install Sites"
description: "Install Newt as a binary or Docker container"
---
Newt can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases.
<Warning>
You **must first create a site and copy the Newt config** in Pangolin before running Newt.
</Warning>
<CardGroup cols={2}>
<Card title="Binary Installation" icon="download">
- Static executable
- Cross-platform support
- Easy to install and run
- Systemd service support
</Card>
<Card title="Docker Installation" icon="docker">
- Containerized deployment
- Environment variables
- Docker Compose support
- Easy management
</Card>
</CardGroup>
Newt can be installed as either a static binary executable or a Docker container. You must first create a site and copy the Newt config in Pangolin before running Newt.
## Binary Installation
@@ -32,7 +12,7 @@ You **must first create a site and copy the Newt config** in Pangolin before run
Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the latest version, adding Newt to your PATH:
```bash
curl -fsSL https://pangolin.net/get-newt.sh | bash
curl -fsSL https://static.pangolin.net/get-newt.sh | bash
```
### Manual Download
@@ -59,15 +39,6 @@ newt \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
```
### Permanent Installation
Install to your PATH (may need to run as root):
```bash
mv ./newt /usr/local/bin
```
<Note>
The quick installer will do this step for you.
</Note>
@@ -130,7 +101,7 @@ services:
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
```
#### Config file injected as Compose Secret
#### Config File Injected as Compose Secret
A safer but slightly more complex way is to use [Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/). First, create a `JSON` file containing your configuration:

55
manage/sites/understanding-sites.mdx Normal file
View File

@@ -0,0 +1,55 @@
---
title: "Understanding Sites"
description: "Create a site to connect to a remote network and expose resources"
---
A site is a connection to a remote network that allows Pangolin to provide access to resources, whether public or private, to users anywhere. Sites are the foundation for exposing resources because all resources exist on one or more sites. Newt is Pangolin's custom software connector that facilitates the connection and addresses the targets on the remote networks.
## The Basics
- **Tunneled sites should always run behind a firewall.** Never provide public access to a site.
- **Users do not connect to a site directly.** Instead, admins define public (browser-based) or private resources on the local network of the site and Pangolin provides acess to these resources.
- **You can run one or multiple sites per network.** You need at least on site to facilitate access to resources, but you can run more than one site in the same network for redundancy, for example. It's up to your preferred deployment method.
- **Sites are software-defined proxies and deny all traffic by default.** Just because a site is deployed to a network doesn't mean users have access to resources on the network. By default, sites don't allow any traffic to hosts on the network. Admins must define explicit resources and delegate access to users.
## Site Types
Pangolin supports three different types of sites, each designed for different use cases and deployment scenarios.
### Newt Site (Recommended)
This site allows you to expose resources on a remote network via a fully managed tunnel and websocket. This requires the Newt connector to be running on the remote network. It's the easiest to use and requires the least amount of setup. No NAT configuration required.
We recommend using Newt sites in almost all cases. Newt is the primary connector type and supports the most features.
Newt sites support:
- Public HTTPS proxied resources
- Private resources
- Load balancing
- Health checking
- Docker socket scanning
- And more...
### Local Site
Use this if you want to expose resources on the same host as the Pangolin server (this is for self-hosted Pangolin only). No tunnels are created. Ports must be opened on the host running Pangolin (this has to happen anyway for Pangolin to work).
Use local sites if you want to expose a public resource on the same host as your self-hosted Pangolin server.
Local sites do not support:
- Private resources
- Health checking
- Docker socket scanning
### Basic WireGuard Site
This is self-hosted only. This uses a raw WireGuard connection without Newt, thus there is no websocket connection, requiring more manual management. These sites require NAT to address targets running on other hosts on the remote network. Otherwise, you can only expose resources on the remote WireGuard peer itself.
Generally, we do not reccomend you use basic WireGuard sites unless you have a specific use case.
Basic WireGuard sites do not support:
- Using LAN-style addresses as targets
- Private resources
- Health checking
- Docker socket scanning

4
manage/sites/update-site.mdx
View File

@@ -1,5 +1,5 @@
---
title: "Update Site"
title: "Update Sites"
description: "Update Newt to the latest version"
---
@@ -32,7 +32,7 @@ docker compose up -d newt
If you used the auto installer, simply run it again.
```bash
curl -fsSL https://pangolin.net/get-newt.sh | bash
curl -fsSL https://static.pangolin.net/get-newt.sh | bash
```
### Manual Installation