pangolin_mirror/docs-v2
1
0
Fork 0
mirror of https://github.com/fosrl/docs-v2.git synced 2026-02-08 05:56:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

test deploy

Browse Source
This commit is contained in:
miloschwartz
2025-07-31 21:44:10 -07:00
parent b918f105b5
commit 647080c1d5
33 changed files with 2045 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
.DS_Store vendored
View File

Binary file not shown.

140
about/how-pangolin-works.mdx
View File

@@ -1,52 +1,108 @@
---
title: "How Pangolin Works"
description: "Learn about Pangolin's architecture and how its components work together to provide secure application access"
---
## Architecture
## System Overview
Pangolin is an open-source system composed of several interconnected components that work together to provide secure, application-specific access. The central server, often referred to as the point of presence, is the core of the system. In self-hosted deployments, the point of presence typically includes Pangolin, Gerbil, and Traefik with its custom plugin, Badger.
Pangolin operates through a central server (called the point of presence) that manages connections to your edge networks. Each edge network runs a lightweight client that establishes secure tunnels back to the central server.
A site represents a connection to an edge network. Pangolin can manage multiple edge networks simultaneously through its lightweight site client, Newt, which facilitates secure communication between the point of presence and the edge networks.
<Frame caption="System architecture showing Pangolin components and their interactions">
<img src="/images/system-diagram.svg" alt="Pangolin system architecture diagram"/>
</Frame>
## System Diagram
## Core Components
<Card img="/images/system-diagram.svg">
### Pangolin (Control Plane)
Pangolin is the main control center that orchestrates the entire system:
- **Web Interface**: Management dashboard for configuring sites, users, and access policies
- **REST API**: External API for automation and integration
- **WebSocket Server**: Manages real-time connections to edge network clients
- **Authentication System**: Handles user authentication and authorization
- **Database**: Stores configuration, user data, and system state
<Info>
Pangolin acts as the brain of the system, coordinating all other components and managing user access.
</Info>
### Gerbil (Tunnel Manager)
Gerbil manages the secure WireGuard tunnels between your edge networks and the central server:
- **Peer Management**: Creates and maintains WireGuard connections
- **Tunnel Orchestration**: Handles tunnel creation, updates, and cleanup
- **Security**: Ensures all traffic is encrypted using WireGuard's cryptographic protocols
<Check>
WireGuard provides fast, secure, and reliable tunneling with minimal overhead.
</Check>
### Newt (Edge Client)
Newt is a lightweight client that runs on your edge networks (servers, VMs, or containers):
- **Automatic Discovery**: Finds the optimal point of presence for best performance
- **Dual Connection**: Connects to Pangolin via WebSocket and Gerbil via WireGuard
- **Resource Proxy**: Creates TCP/UDP proxies to expose your applications securely
<Tip>
Newt is designed to be resource-efficient and can run on minimal hardware or in containers.
</Tip>
### Reverse Proxy (Router)
The reverse proxy handles incoming requests and routes them to your applications:
- **Request Routing**: Directs traffic to the correct backend services
- **SSL Termination**: Manages HTTPS certificates and encryption
- **Middleware Support**: Integrates with security and monitoring plugins
### Badger (Authentication Middleware)
Badger is Pangolin's middleware that enforces access control:
- **Request Interception**: Catches all incoming requests before they reach your applications
- **Authentication Check**: Verifies user identity and permissions
- **Secure Redirects**: Sends unauthenticated users to Pangolin's login system
<Warning>
Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures.
</Warning>
## How It All Works Together
<Steps>
<Step title="User requests access">
A user tries to access your application through the public domain.
</Step>
<Step title="Badger intercepts the request">
Badger middleware catches the request and checks if the user is authenticated.
</Step>
<Step title="Authentication redirect">
If not authenticated, the user is redirected to Pangolin's login system.
</Step>
<Step title="Secure tunnel access">
Once authenticated, requests flow through the encrypted WireGuard tunnel managed by Gerbil.
</Step>
<Step title="Application delivery">
The reverse proxy routes the request to your application running behind Newt on the edge network.
</Step>
</Steps>
## Deployment Models
<CardGroup cols={2}>
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
Use Cloud for a highly available and access-controllerd ingress service with points of presence all over the world.
</Card>
## Components
### Pangolin
Pangolin serves as the main control plane and orchestrates the system. It includes:
- An external-facing REST API for user interactions.
- A WebSocket server for managing connections to Newt clients.
- An internal REST API for communication between system components.
- A frontend server for the web interface.
- Integration with the main database for data storage.
- A built-in authentication system for Zero Trust Network Access (ZTNA).
### Gerbil
Gerbil is responsible for managing WireGuard tunnels. It acts as a peer management server, creating and maintaining secure, encrypted tunnels between edge networks (sites) and the point of presence.
### Newt
Newt is a lightweight, user-space client designed to run on edge networks. It:
- Searches for the closest point of presence for optimal connectivity.
- Connects to the Pangolin server via WebSocket and to Gerbil using a fully user-space WireGuard implementation.
- Facilitates access to other resources on the edge network by creating TCP/UDP proxies.
### Traefik
Traefik is a high-performance, modular reverse proxy that routes requests to backend resources. It handles middleware, SSL termination, and provides extensibility through its plugin system. Key features include:
- Badger: A custom authentication middleware plugin.
- Compatibility with security plugins like GeoBlock and CrowdSec for enhanced protection.
### Badger
Badger is Pangolin’s custom Traefik middleware plugin that enforces authentication. It:
- Intercepts incoming requests to the Traefik reverse proxy.
- Redirects unauthenticated requests to the Pangolin server for authentication, ensuring secure access to backend resources.
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
All components run on your infrastructure, giving you complete control over security and data.
</Card>
</CardGroup>

129
about/pangolin-vs-traditional-reverse-proxy.mdx
View File

@@ -1,56 +1,117 @@
---
title: "Pangolin vs. Reverse Proxy"
description: "Learn how Pangolin's distributed architecture eliminates single points of failure and provides global, authenticated access to your applications"
---
Pangolin shares many similarities with traditional reverse proxies, as it builds upon the same foundational principles. In fact, Pangolin leverages Traefik, one of the most popular reverse proxies, as its core component.
Like a traditional reverse proxy, Pangolin acts as an intermediary between clients and backend servers. Requests are routed through Pangolin, which determines the appropriate backend server to handle the request. This ensures that clients never directly communicate with backend servers. Pangolin also handles key reverse proxy functionalities, including:
Pangolin builds upon traditional reverse proxy principles but adds distributed architecture, tunneling, and identity-aware access control. While traditional reverse proxies are typically single-server solutions, Pangolin operates as a distributed network of points of presence that provide global, highly-available access to your applications.
- **Routing**: Directing traffic to the appropriate backend service.
- **SSL Termination**: Managing HTTPS encryption and decryption.
- **Logging**: Capturing and storing request/response data.
- **Middleware Management**: Supporting plugins and middleware for additional functionality.
## Traditional Reverse Proxy Limitations
Traditional reverse proxies operate as single-server solutions with inherent limitations:
- **Single Point of Failure**: If the reverse proxy server goes down, all applications become inaccessible
- **Geographic Limitations**: Users far from the server location experience higher latency
- **Network Dependencies**: Requires public IP addresses and open ports on your network
- **Basic Authentication**: Typically relies on network-based trust rather than user identity
## Pangolin's Dual-Layer High Availability
Pangolin provides high availability at two critical layers: ingress points and backend routing.
### Global Points of Presence (Ingress Layer)
Pangolin operates a distributed network of points of presence worldwide that serve as entry points for user traffic:
- **Automatic Failover**: If one point of presence becomes unavailable, traffic automatically routes to the next closest location
- **Geographic Optimization**: Users always connect to the nearest available point of presence for minimal latency
- **Load Distribution**: Traffic is automatically balanced across multiple locations to prevent overload
### Intelligent Backend Routing (Tunnel Layer)
Once traffic reaches a point of presence, Pangolin provides additional high availability for routing to your backend services:
- **Multiple Tunnel Connections**: Each edge network can maintain connections to multiple points of presence simultaneously
- **Automatic Tunnel Failover**: If a tunnel connection fails, traffic automatically switches to an alternative route
- **Load Balanced Tunnels**: Multiple tunnel connections can be used simultaneously to distribute load and improve performance
- **Health Monitoring**: Pangolin continuously monitors tunnel health and automatically routes around failed connections
<Info>
This dual-layer approach ensures your applications remain accessible even if individual points of presence or tunnel connections fail.
</Info>
### How Dual-Layer High Availability Works
When a user requests access to your application:
1. **Ingress Routing**: Request is routed to the closest available point of presence
2. **Authentication**: User identity is verified at the point of presence
3. **Tunnel Selection**: Pangolin selects the optimal tunnel route to your backend service
4. **Failover Handling**: If the primary tunnel fails, traffic automatically switches to an alternative route
5. **Response Delivery**: Response follows the same resilient path back to the user
<Check>
Both ingress points and tunnel connections are automatically managed, providing seamless failover without any manual intervention.
</Check>
## Key Differences
### Tunneling
### Tunneling vs. Direct Network Access
Traditional reverse proxies typically operate on the same network as the backend servers they connect to. This setup requires:
Traditional reverse proxies require direct network connectivity:
- A public IP address for the network.
- Open ports (e.g., TCP 443 and 80) to allow external traffic.
- **Public IP Required**: Your network needs a public IP address
- **Open Ports**: Must expose ports (80, 443) to the internet
- **Network Configuration**: Complex firewall and routing setup required
Pangolin eliminates these requirements by introducing tunneling, which allows it to operate on a completely separate server and network from the backend services. Key benefits of Pangolin's tunneling include:
Pangolin uses secure tunneling:
- **Centralized Management**: Multiple isolated edge networks can connect to a single Pangolin instance, meaning you only need to manage one reverse proxy server.
- **Encrypted Traffic**: All traffic between the edge network and the central Pangolin server is fully encrypted.
- **No Public IP or Open Ports**: Edge networks do not require a public IP address or open ports, reducing the attack surface and simplifying network configurations.
- **No Public IP Needed**: Your applications can run on private networks
- **No Open Ports**: Edge networks don't need to expose any ports
- **Automatic Discovery**: Newt clients automatically find and connect to the optimal point of presence
- **Encrypted Traffic**: All communication is encrypted using WireGuard
This tunneling capability makes Pangolin particularly useful for environments with restrictive network policies, such as those behind Carrier-Grade NAT (CGNAT) or firewalls.
<Tip>
This tunneling capability makes Pangolin ideal for environments behind restrictive firewalls, CGNAT, or corporate networks.
</Tip>
### Identity-Aware Proxy (IAP)
Pangolin incorporates Identity-Aware Proxy (IAP) functionality, enabling zero-trust access to backend services. Unlike traditional reverse proxies, which often rely on network-based trust, Pangolin evaluates every access request based on user identity, device, location, and other contextual factors.
Traditional reverse proxies typically rely on network-based trust, while Pangolin implements zero-trust access control:
#### How IAP Works
#### How Pangolin's IAP Works
1. **User Request**: A user attempts to access a protected internal web app, API, or resource.
2. **Request Interception**: The request is intercepted by Pangolin's IAP instead of being routed directly to the backend.
3. **Authentication & Authorization**: Pangolin verifies the user’s identity using OAuth2/OpenID (e.g., Google, Azure AD, Okta).
4. **Context-Aware Checks**: Additional conditions, such as IP address, group membership, or geographic location, are evaluated.
5. **Access Decision**: If all checks are passed, the request is forwarded to the backend service; otherwise, access is denied.
1. **Request Interception**: Every request is intercepted by the nearest point of presence
2. **Identity Verification**: User identity is verified using OAuth2/OpenID Connect
3. **Context Evaluation**: Additional factors like location, device, and time are assessed
4. **Access Decision**: Access is granted or denied based on identity and context
5. **Secure Delivery**: Authenticated requests are tunneled to your application
#### Access Control Features
#### Advanced Access Control Features
Pangolin provides a robust suite of access control mechanisms, including but not limited to:
Pangolin provides comprehensive access control:
- **User and Role-Based Access Control (RBAC)**: Define granular permissions for users and roles.
- **Resource-Specific Security**:
- PIN codes and passwords for individual resources.
- Shareable links with expiration dates.
- **Authentication Options**:
- Email-based One-Time Passwords (OTP).
- Single Sign-On (SSO) with external identity providers via OIDC.
- Two-Factor Authentication (2FA) and passkeys.
- **Contextual Rules**:
- IP, CIDR, and path-based access rules.
- **Multi-Factor Authentication**: Support for 2FA, passkeys, and OTP
- **Single Sign-On**: Integration with Google, Azure AD, Okta, and other identity providers
- **Granular Permissions**: User and role-based access control (RBAC)
- **Resource-Specific Security**: PIN codes, passwords, and expiring share links
- **Contextual Rules**: IP-based, geographic, and time-based access policies
<Warning>
Unlike traditional reverse proxies, Pangolin authenticates every single request, ensuring that only authorized users can access your applications.
</Warning>
## Benefits Summary
| Feature | Traditional Reverse Proxy | Pangolin |
|---------|--------------------------|----------|
| **Availability** | Single point of failure | Distributed, fault-tolerant |
| **Performance** | Limited by server location | Global, optimized routing |
| **Security** | Network-based trust | Zero-trust, identity-aware |
| **Network Requirements** | Public IP, open ports | No public IP needed |
| **Authentication** | Basic or none | Advanced, multi-factor |
| **Scalability** | Manual scaling | Automatic global distribution |
<Card title="Try Pangolin Cloud" icon="rocket" href="https://pangolin.fossorial.io/auth/signup">
Experience distributed, authenticated access to your applications with Pangolin's global network of points of presence.
</Card>

80
about/pangolin-vs-vpn.mdx
View File

@@ -1,25 +1,85 @@
---
title: "Pangolin vs. VPN"
description: "Learn how Pangolin provides application-specific access with zero-trust security compared to traditional VPNs"
---
Pangolin and VPNs both provide secure remote access, but they differ in functionality and use cases. VPNs grant full network-level access, requiring client-side software to connect, while Pangolin provides application-specific access directly through a web browser with authentication, eliminating the need for additional software on the user’s device.
Pangolin and VPNs both provide secure remote access, but they serve different purposes and offer different levels of security and convenience.
## Traditional VPN Limitations
Traditional VPNs provide full network access but come with significant drawbacks:
- **Over-Permission**: Users get access to entire networks, not just the applications they need
- **Client Software Required**: Users must install and configure VPN client software
- **Network Complexity**: Requires public IP addresses, open ports, and complex network configuration
- **Limited Access Control**: Basic network-level security with few granular controls
- **Single Point of Failure**: If the VPN server goes down, all access is lost
## Pangolin's Application-First Approach
Pangolin provides secure, application-specific access without the limitations of traditional VPNs:
### Zero-Trust Access Control
- **Application-Specific**: Users access only the applications they're authorized to use
- **Browser-Based**: No client software installation required - works with any web browser
- **Granular Permissions**: Role-based access control, path-based rules, and contextual policies
- **Multi-Factor Authentication**: Support for SSO, OIDC, 2FA, and passkeys
### Simplified Infrastructure
- **No Public IPs**: Edge networks don't need public IP addresses
- **No Open Ports**: Eliminates the need to expose ports to the internet
- **Automatic Tunneling**: Secure WireGuard tunnels are established automatically
- **Distributed Architecture**: Multiple points of presence ensure high availability
<Info>
Pangolin's application-specific approach follows the principle of least privilege - users only get access to what they need, when they need it.
</Info>
## Key Differences
### Access Scope
| Feature | Traditional VPN | Pangolin |
|---------|----------------|----------|
| **Access Scope** | Full network access | Application-specific access |
| **Client Software** | Required | Not needed (browser-based) |
| **Network Requirements** | Public IP, open ports | No public IP needed |
| **Access Control** | Network-level | Zero-trust, granular |
| **Authentication** | Basic credentials | Multi-factor, SSO, OIDC |
| **Infrastructure** | Single server | Distributed points of presence |
| **Security Model** | Network-based trust | Identity-based trust |
- **Pangolin**: Exposes specific applications or services securely. Users access resources via a browser, ensuring no full network access is granted.
- **VPN**: Provides unrestricted access to the entire private network, which can increase security risks if a device is compromised.
## Use Cases
### Access Control
### Choose Traditional VPN When:
- You need full network access for all users
- Users are comfortable installing client software
- You have simple access control requirements
- You can manage public IP addresses and open ports
- **Pangolin**: Enforces zero-trust policies with role-based access control (RBAC), path-based rules, and authentication methods like SSO, OIDC, and 2FA.
- **VPN**: Relies on network segmentation or ACLs for security, with fewer granular controls.
### Choose Pangolin When:
- You want to expose specific applications securely
- You prefer browser-based access without client software
- You need granular access control and audit trails
- You want to eliminate network infrastructure complexity
- You need high availability and global distribution
### Deployment
<Warning>
Traditional VPNs provide broad network access, which can be a security risk if user devices are compromised. Pangolin's application-specific approach minimizes this risk.
</Warning>
- **Pangolin**: Operates as a centralized reverse proxy using encrypted WireGuard tunnels, requiring no public IPs or open ports on edge networks.
- **VPN**: Requires a VPN server, public IPs, and open ports for inbound connections.
## Mesh VPN Comparison
Mesh VPNs like Tailscale and Netbird provide peer-to-peer connectivity for full network access. While they offer some advantages over traditional VPNs, they still:
- Require client software installation
- Provide full network access rather than application-specific access
- Lack the granular access control and audit capabilities of Pangolin
- Don't offer the distributed, high-availability architecture
<Card title="Try Pangolin Cloud" icon="rocket" href="https://pangolin.fossorial.io/auth/signup">
Experience application-specific access with zero-trust security and no client software required.
</Card>
# Pangolin vs. Mesh VPN (e.g., Tailscale, Netbird)

44
docs.json
View File

@@ -23,8 +23,48 @@
]
},
{
"group": "Newt Sites",
"pages": ["newt/installation"]
"group": "Manage Pangolin",
"pages": [
"manage/points-of-presence",
"manage/high-availability",
{
"group": "Sites",
"pages": [
"manage/sites/add-site",
"manage/sites/install-newt",
"manage/sites/configure-newt"
]
},
{
"group": "Resources",
"pages": ["manage/resources/tcp-udp-resources"]
},
{
"group": "Clients",
"pages": [
"manage/clients/add-client",
"manage/clients/install-client",
"manage/clients/configure-client"
]
},
{
"group": "Access Control",
"pages": ["manage/access-control/bypass-rules"]
},
{
"group": "Identity Providers",
"pages": [
"manage/identity-providers/add-an-idp",
"manage/identity-providers/auto-provisioning",
"manage/identity-providers/openid-connect",
"manage/identity-providers/google",
"manage/identity-providers/pocket-id",
"manage/identity-providers/zitadel"
]
},
"manage/domains",
"manage/integration-api"
]
},
{
"group": "Fully Self-host Pangolin",

BIN
images/newt-preview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 774 KiB

BIN
images/permissions.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 413 KiB

8
index.mdx
View File

@@ -19,18 +19,22 @@ Pangolin establishes secure connections from edge networks to cloud exit nodes,
</Card>
</Columns>
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
Use Cloud for a highly available and access-controllerd ingress service with points of presence all over the world.
</Card>
<Columns cols={2}>
<Card
title="Self-host Pangolin"
icon="server"
href="/self-host/quick-install"
>
Install and manage the Pangolin server on your own infrastructure.
Install and manage your own single point of presence Pangolin server on your own infrastructure.
</Card>
<Card
title="Install Newt"
icon="sitemap"
href="/essentials/settings"
href="/manage/sites/install-newt"
>
Install Newt, the edge client, almost anywhere.
</Card>

15
lib/fetchLatestRelease.js
View File

@@ -1,15 +0,0 @@
export async function fetchLatestRelease(repo) {
try {
const response = await fetch(
`https://api.github.com/repos/${repo}/releases/latest`,
);
if (!response.ok) {
throw new Error(`Failed to fetch release info: ${response.statusText}`);
}
const data = await response.json();
const latestVersion = data.tag_name;
return latestVersion;
} catch (error) {
console.error("Error fetching latest release:", error);
}
}

130
manage/access-control/bypass-rules.mdx Normal file
View File

@@ -0,0 +1,130 @@
---
title: "Bypass Rules"
description: "Configure rules to allow or deny access to resources without authentication"
---
Rules allow you to either "allow" and bypass the Pangolin auth system (no pin, login, password), or "deny" and fully reject the request. After you create a resource you can select the "Rules" tab on the sidebar and enable rules.
<CardGroup cols={2}>
<Card title="Allow Rules" icon="check">
Bypass authentication completely for matching requests. Users can access resources without any login or PIN.
</Card>
<Card title="Deny Rules" icon="x">
Completely reject requests that match the rule. Useful for blocking admin paths or sensitive endpoints.
</Card>
</CardGroup>
## Types of Rules
Rules are processed from top to bottom in order of their priority. This means you can have multiple rules to bypass auth and to just flat deny users at the end.
Right now you can match on the following items:
### Path
Path match rules allow URL patterns defined with plain text and wildcards (`*`) that match any characters. Patterns and URLs are split into segments (using `/`), and **each segment is matched individually**.
#### Examples:
- `blog/posts`
Matches the exact path `/blog/posts`.
- `blog/*`
Matches any path under `/blog` (e.g., `/blog/travel`).
- `*/2023/*`
Matches paths with `/2023/` as a middle segment (e.g., `/news/2023/summary`).
- `article*`
Matches **segments** starting with "article" (e.g., `/article-123`).
- `*admin*`
Matches **segments** containing "admin" (e.g., `/my-admin-panel`).
- `personal-*/*`
Matches paths where the first segment starts with `personal-` and is followed by any segment (e.g., `/personal-blog/post`).
#### Segment-by-Segment Matching
- **Normalization:**
Both patterns and URLs are split into segments. For example, `/blog/journal/entry` becomes `["blog", "journal", "entry"]`, while `/blog*` becomes `["blog*"]`.
- **Validation:**
Each pattern segment must correspond to a URL segment, and wildcards match zero or more characters within that segment. A pattern like `/blog*` only matches the first segment, so URLs with extra segments require additional placeholders (e.g., `/blog*/*`).
### CIDR
CIDR (Classless Inter-Domain Routing) notation specifies IP address ranges using an IP address and a network prefix length. The format is [IP address]/[prefix length].
**Examples:**
- `144.234.11.22/24` - Matches all 256 IPs from 192.168.1.0 to 192.168.1.255
- `10.0.0.0/8` - Matches any IP starting with 10 (16.7 million addresses)
- `2001:db8::/32` - Matches a range of IPv6 addresses
- `0.0.0.0/0` - Matches all IPv4 addresses
<Note>
The prefix length (1-32 for IPv4, 1-128 for IPv6) determines how many bits from the left are fixed. Smaller prefix numbers match larger ranges.
</Note>
### IP
Pretty simple: you can match on simply an IP address like your home IP to bypass auth. This is the same as entering a /32 CIDR.
**Examples:**
- `23.234.134.32`
- `34.45.245.64`
- `192.168.1.1`
## Rules for Specific Apps
This table compiles paths that need to be allowed for various apps to work with Pangolin authentication.
| App | Required Bypass Rules |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Media Management** | |
| Radarr | `/api/*` |
| Sonarr | `/api/*` |
| Lidarr | `/api/*` |
| **Media Servers** | |
| Jellyfin (iOS) | `/system/info/public` |
| Jellyfin (Roku) | `/System/Info/Public`<br />`/Users/AuthenticateByName`<br />`/Users/Public`<br />`/QuickConnect/Initiate`<br />`/QuickConnect/Connect`<br />`/Users/AuthenticateWithQuickConnect` |
| Audiobookshelf (Android) | `/api/*`<br />`/login*`<br />`/s/*`<br />`/ping*`<br />`/feed/*`<br />`/socket*`<br />`/status` |
| **Management & Monitoring** | |
| Tautulli | `/api/*` |
| Harbour | `/api/*` |
| Hoarder App | `/api/*` |
| Uptime Kuma Manager | `/api/*`<br />`/socket.io/*` |
| MeshCentral | `/api/*`<br />`/meshrelay.ashx`<br />`/agent.ashx` |
| **Security & Privacy** | |
| AdGuard Home | `/api/*` |
| Ente Auth | `*api*` |
| Vaultwarden/Bitwarden | `/api/*`<br />`/identity/*`<br />`/wl/*`<br />Always Deny - Path - `/admin/*` |
| **Cloud & Sync** | |
| Nextcloud | `/` (Main interface)<br />`/index.php` (Core handler)<br />`/remote.php` (Remote access)<br />`/status.php` (Status checks)<br />`/ocs` (Collaboration Services API)<br />`/apps` (Applications)<br />`/remote.php/webdav` (WebDAV endpoint)<br />`/remote.php/dav` (CalDAV/CardDAV)<br />`/remote.php/caldav` (Calendar sync)<br />`/remote.php/carddav` (Contacts sync)<br />`/ocs/v1.php` (API endpoints)<br />`/ocs/v2.php` (API v2 endpoints)<br />`/login` (Authentication)<br />`/.well-known/*` (Service discovery)<br />`/.well-known/webfinger` (WebFinger protocol)<br />`/s/*` (Shared files/folders) |
| Onlyoffice | `/cache/*`<br />`*/CommandService.ashx`<br />`*/converter/*`<br />`*/doc/*`<br />`*/downloadas/*`<br />`/downloadfile/*`<br />`*/fonts/*`<br />`/healthcheck`<br />`/methodology/*`<br />`*/plugins.json`<br />`*/sdkjs/*`<br />`*/sdkjs-plugins/*`<br />`*/themes.json`<br />`*/web-apps/*`
| **Photo Management** | |
| Ente Photos | `*api*` |
| Immich | `/api/*`<br />`/.well-known/immich` |
| **File Management** | |
| Filebrowser | `/static/*`<br />`/share/*` <br/> `/api/public/dl/*` <br/> `/api/public/share/*` |
| **Notes & Knowledge Management** | |
| Joplin Notes Server | `/api/*`<br />`/shares/*`<br />`/css/*`<br />`/images/*`<br />Always Deny - Path - `/login/*` (optional) |
| Erugo | `/api/*`<br />`/shares/*`<br />`/build/*`<br />`/get-logo` |
| Memos | `/api/*`<br />`/assets/*`<br />`/explore*`<br />`/memos.api.v1.*`<br />`/auth/callback*`<br />`/auth`<br />`/site.webmanifest`<br />`/logo.webp`<br />`/full-logo.webp`<br />`/android-chrome-192x192.png` |
| Linkding | `/api/*`<br />`/bookmarks/*`<br />Always Deny - Path - `/admin/*` |
| **Communication** | |
| Matrix/Synapse (Clients) | `/_matrix/*`<br />`/_synapse/client/*` |
| Matrix/Synapse (Federation) | `/_matrix/*` |
| **Notifications** | |
| Gotify | `/version`<br />`/message`<br />`/application`<br />`/client`<br />`/stream`<br />`/plugin`<br />`/health` |
| **Home Automation** | |
| Home Assistant | `/api/*`<br />`/auth/*`<br />`/frontend_latest/*`<br />`/lovelace*`<br />`/static/*`<br />`/hacsfile/*`<br />`/local/*` |
| **Project Management** | |
| Jetbrains Youtrack | `/api/*`<br />`/hub/api/*`<br /> |
<Note>
These rules are examples and may need to be adjusted based on your specific app configuration and version.
</Note>

0
manage/clients/add-client.mdx Normal file
View File

0
manage/clients/configure-olm.mdx Normal file
View File

0
manage/clients/install-olm.mdx Normal file
View File

0
manage/domains.mdx Normal file
View File

29
manage/high-availability.mdx Normal file
View File

@@ -0,0 +1,29 @@
---
title: "High Availability"
description: "Learn about Pangolin's high availability options and how to ensure your applications remain accessible"
---
Pangolin provides multiple deployment options to ensure your applications remain highly available and accessible to users worldwide.
<CardGroup cols={3}>
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
Global network of points of presence with automatic failover and routing to your backend services.
</Card>
<Card title="Hybrid" icon="server" href="mailto:numbat@fossorial.io">
Host your own multiple highly available points of presence with cloud coordination and automatic failover.
</Card>
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
Fully self-hosted, self-contained Pangolin server acting as a single point of presence.
</Card>
</CardGroup>
## How It Works
For detailed information about how points of presence work and their advantages, see our [Points of Presence](/manage/points-of-presence) documentation.
## Contact Us
For hybrid deployments, points of presence, and high availability contact us:
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)

58
manage/identity-providers/add-an-idp.mdx Normal file
View File

@@ -0,0 +1,58 @@
---
title: "Add Identity Providers"
description: "Configure external identity providers for user authentication"
---
<Note>
Identity providers are only available in self-hosted Pangolin instances.
</Note>
Identity providers let you authenticate Pangolin users using external identity providers. This is useful for organizations that want to use their existing identity provider infrastructure to manage user authentication.
For example, you may have users defined in Authentik, and you want these users to be able to log in to Pangolin using their existing credentials.
<CardGroup cols={2}>
<Card title="What it does" icon="users">
Allows users to authenticate using external identity providers instead of Pangolin's built-in authentication.
</Card>
<Card title="When to use" icon="gear">
Useful for organizations with existing identity infrastructure like Authentik, Keycloak, or Okta.
</Card>
</CardGroup>
## Supported Identity Providers
### OAuth2/OIDC
This can be used to connect to any external identity provider that supports the OpenID Connect protocol such as:
- **Authentik**
- **Keycloak**
- **Okta**
- **Other OIDC-compliant providers**
## How to Add an Identity Provider
<Steps>
<Step title="Access Server Admin">
Select the "Identity Providers" tab in the Server Admin UI.
</Step>
<Step title="Add New Provider">
Click on the "Add Identity Provider" button.
</Step>
<Step title="Select Type">
Select the type of identity provider you want to add (OAuth2/OIDC).
</Step>
<Step title="Configure Settings">
Fill in the required fields for the selected identity provider type.
</Step>
</Steps>
## Auto Provisioning
See [Auto Provision](manage/identity-providers/auto-provisioning) for more information on how to automatically provision users and assign orgs and roles in Pangolin when they log in using an external identity provider.

191
manage/identity-providers/auto-provisioning.mdx Normal file
View File

@@ -0,0 +1,191 @@
---
title: "Auto Provisioning"
description: "Automatically create and manage user accounts from external identity providers"
---
Auto provisioning is a feature that allows you to automatically create and manage user accounts in Pangolin when they log in using an external identity provider. This is useful for organizations that want to streamline the onboarding process for new users and ensure that their user accounts are always up-to-date.
You will be able to programmatically decide the roles and organizations for new users based on the information provided by the identity provider.
<CardGroup cols={2}>
<Card title="What it does" icon="users">
Automatically creates user accounts when users log in through external identity providers.
</Card>
<Card title="Benefits" icon="bolt">
Streamlines onboarding and keeps user accounts up-to-date with external identity systems.
</Card>
</CardGroup>
## Enable Auto Provision
Toggle the "Auth Provision Users" switch when creating or editing an identity provider.
## What if Auto Provisioning is Disabled?
If auto provision is disabled, organization admins will need to manually create the user accounts and select the role for each user. When creating a user, you can select the identity provider that the user will be associated with. A user will not be able to log in using the identity provider if a user is not pre-provisioned in the system.
## How Auto Provisioning Works
It is helpful to think of the auto provisioning process as follows:
<Steps>
<Step title="User Login">
User successfully logs in using an identity provider.
</Step>
<Step title="Account Creation">
Pangolin creates a user account for the user.
</Step>
<Step title="Organization Evaluation">
Pangolin will loop through each organization and evaluate the JMESPath expression for the organization. If the expression does not return true or the same ID as the current organization, the user will not be added to the organization.
</Step>
<Step title="Role Assignment">
For each organization, Pangolin will evaluate the JMESPath expression for the role. If no role is found with the exact name in that organization, the user will not be added to the organization.
</Step>
</Steps>
## Configuration Options
### Organization Policies
You can configure policy for each organization with its own roles selector expression and organization selector expression.
### Default (Fallback) Policy
You can optionally configure a default policy for all organizations. This will be used if the organization does not have its own policy configured.
## Selecting Roles
Use JMESPath to map attributes from the identity provider to roles in Pangolin. See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.
The expression will be matched against each organization. Meaning:
- The result of the expression must return the exact string of the role name as it is defined in the organization.
- If no matching role is found, the user will not be added to the organization.
### Example
**Expression:**
```
contains(groups, 'admin') && 'Admin' || 'Member'
```
**Identity Provider Data:**
```json
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
This example will return the string "Admin". If the user is not a member of the "admin" group, it will return "Member".
## Selecting Organizations
Use JMESPath to map attributes from the identity provider to organizations in Pangolin. See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.
The expression will be matched against each organization. Meaning:
- The result of the expression must return true or the organization ID as it is defined in the system.
- If no matching organization is found, the user will not be added to the organization.
You can insert the template variable `{{orgId}}` in the expression. This will be replaced with the organization ID when the expression is evaluated.
### Example 1: Group-based Selection
**Expression:**
```
contains(groups, 'home-lab')
```
**Identity Provider Data:**
```json
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
This example will return true since the user is a member of the "home-lab" group.
### Example 2: Fixed Organization
**Expression:**
```
'home-lab'
```
**Identity Provider Data:**
```json
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
This example will always return 'home-lab' meaning the user will always be added to the "home-lab" organization.
### Example 3: Dynamic Organization Selection
**Expression:**
```
contains(groups, '{{orgId}}')
```
**Identity Provider Data:**
```json
{
...
"sub": "9590c3bfccd1b1a54b35845fb1bb950057dfa50fba43cb8bada58b462c80e207",
"aud": "JJoSvHCZcxnXT2sn6CObj6a21MuKNRXs3kN5wbys",
"exp": 1745790819,
"iat": 1745789019,
"auth_time": 1745789019,
"email": "user@example.com",
"email_verified": true,
"name": "Example User",
"groups": [
"home-lab",
"admin"
]
}
```
When Pangolin evaluates this expression against the "home-lab" organization, it will replace `{{orgId}}` with "home-lab". The result of the expression will return true since the user is a member of the "home-lab" group.

92
manage/identity-providers/google.mdx Normal file
View File

@@ -0,0 +1,92 @@
---
title: "Google SSO"
description: "Configure Google Single Sign-On using OpenID Connect"
---
The following steps will integrate **Google SSO** using **OpenID Connect (OIDC)**.
## Prerequisites
Before you can start, you'll need to create or edit a **Project** in [Google Developers Console](https://console.developers.google.com/).
### Setting up your Project
[Create a new Project](https://console.cloud.google.com/projectcreate), or use an [existing Project](https://console.developers.google.com/) you've already created in the Google Developers Console. Setting the organization isn't required, unless you intend to use SSO for [more than 100 users](https://support.google.com/cloud/answer/13464323) externally (not via Google Workspace).
Once created, or you've opened an existing Project, you may be on the project dashboard, where you will need to open the sidebar. If you are on the welcome page, continue by selecting [OAuth consent screen](https://console.cloud.google.com/auth/overview) in **APIs and services**.
You should see that Google Auth Platform is not configured. Press **Get started** and fill in the relevant information, such as your **App name** and **User support email**. These will be visible when the user is authenticating.
After continuing, you can select an **Audience**. If you are using Pangolin for friends and family, use the **External** Audience. You can only have 100 users authenticated with a "Testing" status.
<Note>
Depending on your use case, you may want to use the **Internal** Audience if you are utilising Google Workspace SSO and paying for access to the [Professional Edition](https://docs.fossorial.io/professional-edition).
</Note>
Once completed, you will then need to open the [Branding](https://console.cloud.google.com/auth/branding) tab.
Locate **Authorized domains**, then press "Add domain" to add an authorized domain. You'll need to authorize the top private (root) domain here, such as `example.com`. Your SSO *may* function without an authorized domain, though setting this field should guarantee functionality.
### Creating an OAuth client ID in your Project
Go to the [Clients](https://console.cloud.google.com/auth/clients) tab, and click "Create client" below the top bar.
<Steps>
<Step title="Select Application Type">
For **Application type**, select `Web application`.
</Step>
<Step title="Set Name">
Any **Name** can be set.
</Step>
<Step title="Leave Redirect URIs Empty">
Leave **Authorised JavaScript origins** and **Authorised redirect URIs** empty.
</Step>
</Steps>
<Note>
We will revisit the **Authorised redirect URIs** field later, as we do not have Pangolin set up for Google yet.
</Note>
After hitting "Create", you will be able to see the **Client ID** and **Client secret**, you may want to copy these somewhere as these will be needed momentarily, though they will still be accessible in the future.
## Configuring Identity Providers in Pangolin
In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button.
**Name** should be set to something memorable. The **Provider Type** should be set to the default `OAuth2/OIDC`.
### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The Client ID from your Web application client.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client secret from your Web application client.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
Set to `https://accounts.google.com/o/oauth2/v2/auth`.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
Set to `https://oauth2.googleapis.com/token`.
</ResponseField>
## Token Configuration
You should leave all of the paths default. In the **Scopes** field, add `openid profile email`.
<Warning>
Currently, the only way to obtain your `sub` identifier attribute via Google is through direct API access. For now, set the **Identifier Path** to `email` and in the **Username** field, and use the associated account's email. We highly recommend increasing the resilience of your Google SSO by setting the optional **Name** field to match the account's (full name attached to their Google account).
</Warning>
When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now need this for your **Web application client**.
## Returning to Google Developers Console
Lastly, you'll need to return to your **Web application client** in order to add the redirect URI created by Pangolin. Add the URI to **Authorized redirect URIs**, then hit "Save"! Your configuration should now be complete. You'll now need to add an external user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Google SSO.

70
manage/identity-providers/openid-connect.mdx Normal file
View File

@@ -0,0 +1,70 @@
---
title: "OAuth2/OIDC"
description: "Configure OpenID Connect identity provider for external authentication"
---
This identity provider follows the OpenID Connect protocol. This means that it can be used to connect to any external identity provider that supports the OpenID Connect protocol such as Authentik, Keycloak, Okta, etc.
<CardGroup cols={2}>
<Card title="What it supports" icon="shield">
Any external identity provider that follows the OpenID Connect standard.
</Card>
<Card title="Common providers" icon="users">
Authentik, Keycloak, Okta, and other OIDC-compliant identity providers.
</Card>
</CardGroup>
## Configuration
You will need to configure the following common settings:
<ResponseField name="Client ID" type="string" required>
The client identifier provided by your identity provider.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The client secret provided by your identity provider.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
The authorization endpoint URL from your identity provider.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
The token endpoint URL from your identity provider.
</ResponseField>
## Token Configuration
Use JMESPath to select attributes from the claims token. See [JMESPath](https://jmespath.org/) for more information on how to use JMESPath.
Determine how to access information from the claims token returned by the identity provider. This is used to map the user information from the identity provider to the user information in Pangolin.
<ResponseField name="Identifier Path" type="string" required>
This must be unique for each user within an identity provider.
**Example**: `sub` or `user_id`
</ResponseField>
<ResponseField name="Email Path" type="string">
Path to the user's email address in the claims token.
**Example**: `email`
</ResponseField>
<ResponseField name="Name Path" type="string">
Path to the user's display name in the claims token.
**Example**: `name` or `preferred_username`
</ResponseField>
<ResponseField name="Scopes" type="string">
The scopes to request from the identity provider (not JMESPath; must be space-delimited strings).
**Default**: `openid profile email`
<Note>
Generally, `openid profile email` is sufficient for most use cases.
</Note>
</ResponseField>

79
manage/identity-providers/pocket-id.mdx Normal file
View File

@@ -0,0 +1,79 @@
---
title: "Pocket ID SSO"
description: "Configure Pocket ID Single Sign-On using OpenID Connect"
---
The following steps will integrate **Pocket ID** with **Pangolin SSO** using OpenID Connect (OIDC).
## Prerequisites
Before you can start, you'll need to have Pocket ID accessible and ensure it's not secured with Pangolin SSO.
### Creating an OIDC Client in Pocket ID
In Pocket ID, create a new OIDC Client.
<Steps>
<Step title="Set Name">
Set the name to something memorable (eg. Pangolin).
</Step>
<Step title="Configure Callback URL">
Set "Callback URLs" to `https://<your-pangolin-domain>/auth/idp/<idp-id>/oidc/callback`.
</Step>
<Step title="Keep Defaults">
All other values can be kept as default.
</Step>
</Steps>
<Note>
The callback URL is displayed in the IdP settings after you create the IdP in Pangolin.
</Note>
After you have created the OIDC Client, take note of the following fields from the top of the page (click "Show more details" to see all of them):
- **Client ID**
- **Client secret**
- **Authorization URL**
- **Token URL**
## Configuring Identity Providers in Pangolin
In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button.
**Name** should be set to something memorable (eg. Pocket ID). The **Provider Type** should be set to the default `OAuth2/OIDC`.
### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The Client ID from your Pocket ID OIDC client.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client secret from your Pocket ID OIDC client.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
The Authorization URL from your Pocket ID OIDC client.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
The Token URL from your Pocket ID OIDC client.
</ResponseField>
## Token Configuration
You should leave all of the paths default. In the **Scopes** field, add `openid profile email`.
<Note>
Set the **Identifier Path** to "preferred_username" for Pocket ID integration.
</Note>
When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now need this for your **Pocket ID OIDC client**.
## Returning to Pocket ID
Lastly, you'll need to return to your **Pocket ID OIDC client** in order to add the redirect URI created by Pangolin. Add the URI to **Callback URLs**, then save your changes! Your configuration should now be complete. You'll now need to add an external user to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Pocket ID SSO.

92
manage/identity-providers/zitadel.mdx Normal file
View File

@@ -0,0 +1,92 @@
---
title: "Zitadel SSO"
description: "Configure Zitadel Single Sign-On using OpenID Connect"
---
The following steps will integrate **Zitadel** with **Pangolin SSO** using OpenID Connect (OIDC).
## Prerequisites
These instructions assume you have a working Zitadel organization and project setup already.
### Creating an Application in Zitadel
You need to configure an application in Zitadel:
<Steps>
<Step title="Create New Application">
Open an existing project and in `Applications` click `New`.
</Step>
<Step title="Configure Application">
Set the name to something memorable (eg. Pangolin).
</Step>
<Step title="Set Application Type">
For `Type of application` choose `Web`.
</Step>
<Step title="Set Authentication Method">
For `Authentication Method` choose `Code`.
</Step>
<Step title="Leave Redirect URIs Blank">
Leave `Redirect URIs` blank for now.
</Step>
</Steps>
<Note>
When you click create, you'll be shown the `ClientSecret` and `ClientId`. Make sure to save these somewhere secure - you won't be able to see the Client Secret again.
</Note>
<Steps>
<Step title="Configure Token Settings">
Click `Token settings` then change `Auth Token Type` to `JWT` and check the `User Info inside ID Token` box finally hit `Save`.
</Step>
<Step title="Note Endpoints">
Open `URLs` and make note of:
- `Authorization Endpoint`
- `Token Endpoint`
</Step>
</Steps>
## Configuring Identity Providers in Pangolin
In Pangolin, go to the **Server Admin** section. Select "Identity Providers" before proceeding with the "Add Identity Provider" button.
**Name** should be set to something memorable (eg. Zitadel). The **Provider Type** should be set to the default `OAuth2/OIDC`.
### OAuth2/OIDC Configuration (Provider Credentials and Endpoints)
In the OAuth2/OIDC Configuration, you'll need the following fields:
<ResponseField name="Client ID" type="string" required>
The Client ID from your Zitadel application.
</ResponseField>
<ResponseField name="Client Secret" type="string" required>
The Client Secret from your Zitadel application.
</ResponseField>
<ResponseField name="Authorization URL" type="string" required>
Use the `Authorization Endpoint` from your Zitadel application.
</ResponseField>
<ResponseField name="Token URL" type="string" required>
Use the `Token Endpoint` from your Zitadel application.
</ResponseField>
## Token Configuration
You should leave all of the paths default. In the **Scopes** field, add `openid profile email`.
<Note>
Set the **Identifier Path** to "preferred_username" for Zitadel integration.
</Note>
When you're done, click "Create Identity Provider"! Then, copy the Redirect URL in the "General" tab as you will now need this for your **Zitadel application**.
## Returning to Zitadel
Lastly, you need to edit your `Redirect Settings` in your Zitadel application. Add the URL you copied to the `Redirect URIs`, then hit the `+` button and finally `Save`. Your configuration should now be complete. You'll now need to add an external user] to Pangolin, or if you have "Auto Provision Users" enabled, you can now log in using Zitadel SSO.

94
manage/integration-api.mdx Normal file
View File

@@ -0,0 +1,94 @@
---
title: "Integration API"
description: "Learn how to use Pangolin's REST API to automate and script operations with fine-grained permissions"
---
The API is REST-based and supports many operations available through the web interface. Authentication uses Bearer tokens, and you can create multiple API keys with specific permissions for different use cases.
<Info>
For Pangolin self-hosted, the integration API must be enabled. Check out [the documentation](self-host/advanced/integration-api) for how to enable the integration API.
</Info>
## Authentication
All API requests require authentication using a Bearer token in the Authorization header:
<CodeGroup>
```bash cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.example.com/v1/
```
```javascript JavaScript
const response = await fetch('https://api.example.com/v1/endpoint', {
headers: {
'Authorization': `Bearer ${apiKey}`
}
});
```
```python Python
import requests
headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get('https://api.example.com/v1/endpoint', headers=headers)
```
</CodeGroup>
## API Key Types
Pangolin supports two types of API keys with different permission levels:
### Organization API Keys
Organization API keys are created by organization admins and have limited scope to perform actions only in that organization.
### Root API Keys
Root API keys have some extra permissions and can execute operations across orgs. They are only available in self-hosted Pangolin:
<Warning>
Root API keys have elevated permissions and should be used carefully. Only create them when you need server-wide access.
</Warning>
## Creating API Keys
<Steps>
<Step title="Access the admin panel">
Navigate to your admin panel:
- **Organization keys**: Organization → API Keys
- **Root keys**: Server Admin → API Keys (self-hosted only)
</Step>
<Step title="Generate a new key">
Click "Create API Key" and provide a descriptive name for the key.
</Step>
<Step title="Configure permissions">
Select the specific permissions your API key needs from the permissions selector.
<Frame caption="API key permissions selector showing available operations">
<img src="/images/permissions.png" alt="API Key Permissions"/>
</Frame>
</Step>
<Step title="Copy and secure your key">
Copy the generated API key immediately. It won't be shown again.
<Warning>
Store API keys securely and never commit them to version control. Use environment variables or secure secret management.
</Warning>
</Step>
</Steps>
## API Documentation
View the Swagger docs here: [https://api.pangolin.fossorial.io/v1/docs](https://api.pangolin.fossorial.io/v1/docs).
Interactive API documentation is available through Swagger UI:
<Frame caption="Swagger UI showing API endpoints and interactive testing">
<img src="/images/swagger.png" alt="Swagger Docs"/>
</Frame>
For self-hosted Pangolin, access the documentation at `https://api.your-domain.com/v1/docs`.

94
manage/integration-api/using-the-integration-api.mdx Normal file
View File

@@ -0,0 +1,94 @@
---
title: "Integration API"
description: "Learn how to use Pangolin's REST API to automate and script operations with fine-grained permissions"
---
The API is REST-based and supports many operations available through the web interface. Authentication uses Bearer tokens, and you can create multiple API keys with specific permissions for different use cases.
<Info>
For Pangolin self-hosted, the integration API must be enabled. Check out [the documentation](self-host/advanced/integration-api) for how to enable the integration API.
</Info>
## Authentication
All API requests require authentication using a Bearer token in the Authorization header:
<CodeGroup>
```bash cURL
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.example.com/v1/
```
```javascript JavaScript
const response = await fetch('https://api.example.com/v1/endpoint', {
headers: {
'Authorization': `Bearer ${apiKey}`
}
});
```
```python Python
import requests
headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get('https://api.example.com/v1/endpoint', headers=headers)
```
</CodeGroup>
## API Key Types
Pangolin supports two types of API keys with different permission levels:
### Organization API Keys
Organization API keys are created by organization admins and have limited scope to perform actions only in that organization.
### Root API Keys
Root API keys have some extra permissions and can execute operations across orgs. They are only available in self-hosted Pangolin:
<Warning>
Root API keys have elevated permissions and should be used carefully. Only create them when you need server-wide access.
</Warning>
## Creating API Keys
<Steps>
<Step title="Access the admin panel">
Navigate to your admin panel:
- **Organization keys**: Organization → API Keys
- **Root keys**: Server Admin → API Keys (self-hosted only)
</Step>
<Step title="Generate a new key">
Click "Create API Key" and provide a descriptive name for the key.
</Step>
<Step title="Configure permissions">
Select the specific permissions your API key needs from the permissions selector.
<Frame caption="API key permissions selector showing available operations">
<img src="/images/permissions.png" alt="API Key Permissions"/>
</Frame>
</Step>
<Step title="Copy and secure your key">
Copy the generated API key immediately. It won't be shown again.
<Warning>
Store API keys securely and never commit them to version control. Use environment variables or secure secret management.
</Warning>
</Step>
</Steps>
## API Documentation
View the Swagger docs here: [https://api.pangolin.fossorial.io/v1/docs](https://api.pangolin.fossorial.io/v1/docs).
Interactive API documentation is available through Swagger UI:
<Frame caption="Swagger UI showing API endpoints and interactive testing">
<img src="/images/swagger.png" alt="Swagger Docs"/>
</Frame>
For self-hosted Pangolin, access the documentation at `https://api.your-domain.com/v1/docs`.

116
manage/points-of-presence.mdx Normal file
View File

@@ -0,0 +1,116 @@
---
title: "Points of Presence"
description: "Learn about Pangolin's global network of points of presence and how they provide highly available, low-latency access to your applications"
---
Pangolin's points of presence (PoPs) are strategically located servers around the world that serve as entry points for user traffic to your applications. They form the foundation of Pangolin's distributed architecture, providing global high availability and optimal performance.
## Contact Us
For hybrid deployments, points of presence, and high availability contact us:
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
## What Are Points of Presence?
Points of presence are geographically distributed servers that:
- **Serve as Entry Points**: Handle incoming user requests before routing them to your applications
- **Provide Global Coverage**: Located worldwide to minimize latency for users in different regions
- **Enable High Availability**: Multiple locations ensure your applications remain accessible even if individual locations fail
- **Handle Authentication**: Verify user identity and enforce access policies before allowing access
<Info>
Think of points of presence as the "front doors" to your applications - users connect to the closest one, and it securely routes their requests to your backend services.
</Info>
## How Points of Presence Work
### Geographic Routing
When a user requests access to your application:
1. **DNS Resolution**: The user's request is automatically routed to the closest available point of presence
2. **Authentication**: The point of presence verifies the user's identity and permissions
3. **Tunnel Routing**: Authenticated requests are sent through secure tunnels to your applications
4. **Response Delivery**: Responses follow the same path back to the user
<Check>
This routing happens automatically and transparently - users always get the best possible performance without any manual configuration.
</Check>
### Automatic Failover
Pangolin's points of presence provide built-in high availability:
- **Health Monitoring**: Each point of presence continuously monitors its health and connectivity
- **Automatic Failover**: If one location becomes unavailable, traffic automatically routes to the next closest location
- **Load Distribution**: Traffic is automatically balanced across multiple locations to prevent overload
- **Global Redundancy**: Multiple points of presence ensure your applications remain accessible during regional outages
## Advantages of Points of Presence
### Global Performance
- **Low Latency**: Users connect to the geographically closest point of presence
- **Optimized Routing**: Automatic selection of the best available location
- **Edge Computing**: Processing happens closer to users for faster response times
### High Availability
- **Fault Tolerance**: No single point of failure - if one location goes down, others remain available
- **Automatic Recovery**: Failed locations are automatically bypassed and traffic is rerouted
- **Regional Redundancy**: Multiple locations per region provide additional redundancy
### Security and Compliance
- **Distributed Security**: Security controls are enforced at every point of presence
- **Regional Compliance**: Points of presence can be configured to meet regional data requirements
- **Encrypted Transit**: All traffic between points of presence and your applications is encrypted
### Scalability
- **Automatic Scaling**: New points of presence are automatically added as needed
- **Load Balancing**: Traffic is distributed across multiple locations to handle high volumes
- **Global Distribution**: Support for applications with users worldwide
## Deployment Models
### Pangolin Cloud
Pangolin Cloud includes a global network of points of presence that provide:
- **Automatic Management**: Points of presence are automatically deployed, monitored, and maintained
- **Global Coverage**: Strategic locations worldwide for optimal performance
- **Built-in High Availability**: Multiple redundant locations ensure 99.9%+ uptime
- **Zero Configuration**: No setup or management required on your part
<Card title="Try Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
Get started with Pangolin Cloud and experience global points of presence with automatic high availability.
</Card>
### Self-Hosted Pangolin
Self-hosted Pangolin operates as a single point of presence:
- **Single Location**: Your Pangolin instance serves as the only entry point
- **Limited Availability**: No built-in redundancy - if your server goes down, access is lost
- **Manual Management**: You're responsible for server maintenance and uptime
- **Regional Limitation**: Performance depends on your server's location
<Warning>
Self-hosted Pangolin provides only a single point of presence and is not highly available. Consider Pangolin Cloud or hybrid deployment for production environments requiring high availability.
</Warning>
### Hybrid Deployment
Hybrid deployment allows you to host your own points of presence while leveraging Pangolin's cloud coordination:
- **Your Infrastructure**: Host points of presence on your own servers or cloud infrastructure
- **Cloud Coordination**: Pangolin Cloud handles failover logic and coordination between your points of presence
- **Automatic Failover**: If your points of presence go down, traffic automatically fails over to Pangolin Cloud
- **Data Control**: Traffic flows through your servers, giving you control over data transit costs and privacy
- **Custom Locations**: Deploy points of presence in specific regions or data centers of your choice
<Tip>
Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit.
</Tip>

116
manage/resources/tcp-udp-resources.mdx Normal file
View File

@@ -0,0 +1,116 @@
---
title: "Raw TCP & UDP"
description: "Configure raw TCP and UDP traffic through Pangolin tunnels"
---
<Note>
This feature is only available in self-hosted Pangolin instances.
</Note>
Pangolin supports raw TCP and UDP traffic because Newt can pass anything through the tunnel.
These resources can either be:
1. **Publically Proxied:** Map the resource to a port on the host Pangolin server, so you can access the resource from `<server-public-ip>:<mapped-port>`. This is useful if you want to access the resource over the public internet, such as exposing a game server like Minecraft.
2. **Internal Exposure:** Map services accessible on the same network as the site to an internal port on the site address. This is useful if you only want internal exposure to a resource when connected with a client.
## Proxied Resources
Proxied resources require extra configuration to expose on the Pangolin server. You'll need to configure firewall rules, Docker port mappings, and Traefik entry points. These steps require a server restart.
<Steps>
<Step title="Create the resource">
In the Pangolin dashboard, go to Resources and click Add Resource. Select "Raw TCP/UDP resource", enable Public Proxy, and enter your desired publicly mapped port. This is the port you'll use to access the proxied resource.
</Step>
<Step title="Configure firewall">
Open your desired ports on your VPS firewall, just like you did for ports 51820, 443, and 80. This is highly OS and VPS dependent.
<Note>
In this example, we're exposing two resources: TCP 1602 and UDP 1704.
</Note>
</Step>
<Step title="Configure Docker">
Add port mappings to your `docker-compose.yml` file:
```yaml title="docker-compose.yml" highlight={4,5}
gerbil:
ports:
# ... existing ports ...
- 1704:1704/udp # ADDED: Your UDP port
- 1602:1602 # ADDED: Your TCP port
```
</Step>
<Step title="Configure Traefik">
Add entry points to your `config/traefik/traefik_config.yml`:
```yaml title="traefik_config.yml" highlight={12-15}
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
http:
tls:
certResolver: letsencrypt
transport:
respondingTimeouts:
readTimeout: 30m
tcp-1602:
address: ":1602/tcp"
udp-1704:
address: ":1704/udp"
```
<Info>
**Important**: Always name your entry points in the format `protocol-port` (e.g., `tcp-1602`, `udp-1704`). This naming is required for Pangolin's dynamic configuration.
</Info>
</Step>
<Step title="Restart the stack">
Restart your Docker stack to apply all changes:
```bash
sudo docker compose down
sudo docker compose up -d
```
</Step>
</Steps>
<Note>
In this example, we expose port 1602 for TCP and port 1704 for UDP. You can use any available ports on your VPS.
</Note>
## Internal Exposure with Clients
Internal exposure resources are only accessible when connected via an Olm client. This approach is perfect for secure access to services without exposing them to the public internet.
When you run Newt with `--accept-clients`, it operates fully in user space without creating a virtual network interface on the host. This means:
- **No special permissions required** for the container or binary
- **No virtual network interface** created on the host
- **Client-only access** through Pangolin's tunnel
- **Secure internal routing** to your services
### Example: SSH Access
Here's how to set up SSH access to your server when connected with a client:
<Steps>
<Step title="Create the resource">
In the Pangolin dashboard, create a new Raw TCP/UDP resource and set the port to `2022` (or any available port).
</Step>
<Step title="Add the target">
Configure the resource to target `localhost:22` (your SSH service).
</Step>
<Step title="Connect and access">
When connected with a Newt client, you can SSH to your server using `<site-address>:2022`.
</Step>
</Steps>
<Note>
This approach is ideal for secure remote access without exposing SSH directly to the internet.
</Note>

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

@@ -0,0 +1,83 @@
---
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="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="Configure site details">
Configure the basic information:
- **Site Name**: A descriptive name for your site
</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="Configure Newt">
Use the generated credentials to configure Newt on the remote network. See [Configure Newt](/manage/sites/configure-newt) for detailed instructions.
</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

464
manage/sites/configure-newt.mdx Normal file
View File

@@ -0,0 +1,464 @@
---
title: "Configure Newt"
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
### Required Arguments
<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>
### Optional Arguments
<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="accept-clients" type="boolean">
Enable WireGuard server mode to accept incoming Olm client connections.
**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.
<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>
<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://example.com
- 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://example.com
- --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://example.com
- 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.
**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://example.com
- 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
**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://example.com
- 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>

0
manage/sites/docker-socket.mdx Normal file
View File

6
newt/installation.mdx → manage/sites/install-newt.mdx
View File

@@ -1,6 +1,6 @@
---
title: "Installation"
description: "Install Newt VPN client as a binary or Docker container"
title: "Install Newt"
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.
@@ -156,7 +156,9 @@ docker compose up -d
Newt is available in the Unraid Community Applications store. Search for "Newt" and follow the installation prompts. Enter the ID, secret, and endpoint from Pangolin in the template fields.
<Frame caption="Newt available in Unraid Community Applications store">
<img src="/images/unraid_store.png" alt="Newt on CA" />
</Frame>
### Portainer and Other UIs

2
self-host/advanced/integration-api.mdx
View File

@@ -64,7 +64,9 @@ Once configured, access the Swagger UI documentation at:
https://api.example.com/v1/docs
```
<Frame caption="Swagger UI documentation interface">
<img src="/images/swagger.png" alt="Swagger UI Preview"/>
</Frame>
<Note>
The Integration API will be accessible at `https://api.example.com/v1` for external applications.

12
self-host/manual/unraid.mdx
View File

@@ -60,10 +60,12 @@ pangolin/
Set the network to the one you created earlier.
<Frame caption="Pangolin configuration settings in Unraid">
<img
src="/images/pangolin_config.png"
alt="Pangolin configuration settings in Unraid"
/>
</Frame>
**Ports:**
@@ -225,18 +227,22 @@ http:
This section will use the Traefik template from the "IBRACORP" repository. If you already have a Traefik installation running, you should manually configure your Traefik config to work with Pangolin.
<Frame caption="Traefik repository selection in Community Apps">
<img
src="/images/traefik_repo.png"
width="400"
alt="Traefik repository selection in Community Apps"
/>
</Frame>
#### 3. Configure Traefik
<Frame caption="Traefik configuration settings in Unraid">
<img
src="/images/traefik_config.png"
alt="Traefik configuration settings in Unraid"
/>
</Frame>
<Info>
Please refer to the official Traefik docs for more information on the Traefik configuration beyond this guide.
@@ -292,10 +298,12 @@ The important concept to understand going forward, is we need to network Traefik
Set the network to the one you created earlier.
<Frame caption="Gerbil configuration settings in Unraid">
<img
src="/images/gerbil_config.png"
alt="Gerbil configuration settings in Unraid"
/>
</Frame>
**Important things to consider:**
@@ -323,10 +331,12 @@ Toggle advanced settings, and add the following to the "Extra Parameters" sectio
Then, set "Network Type" to "None".
<Frame caption="Traefik networking configuration through Gerbil">
<img
src="/images/traefik_networking.png"
alt="Traefik networking configuration through Gerbil"
/>
</Frame>
#### 4. Start the stack
@@ -348,9 +358,11 @@ Your logs for Gerbil should look something like this:
You probably won't have the peer connection messages but in general, you should see the WireGuard interface being started.
</Info>
<Frame caption="Gerbil logs showing WireGuard interface startup">
<img
src="/images/gerbil_logs.png"
alt="Gerbil logs showing WireGuard interface startup"
/>
</Frame>
Log back into the Pangolin dashboard and create a new site with Newt or basic WireGuard. Copy the credentials to your client and connect. You should see the tunnel status change to "Online" after a few moments if the connection is successful. Remember to also monitor the logs on the client and server.

4
self-host/quick-install.mdx
View File

@@ -3,6 +3,10 @@ title: "Quick Install Guide"
description: "Deploy your own Pangolin reverse proxy server in under 10 minutes with our automated installer"
---
<Info>
Fully self-hosted Pangolin provides only one point of presence and is not highly available.
</Info>
## Prerequisites
Before you begin, ensure you have:

4
self-host/supporter-program.mdx
View File

@@ -35,10 +35,12 @@ Pangolin self-hosted will always be free and open source, but maintaining the pr
</Tab>
</Tabs>
<Frame caption="Supporter tier comparison showing Limited vs Full Supporter benefits">
<img
src="/images/supporter-tiers.png"
alt="Supporter tier comparison showing Limited vs Full Supporter benefits"
/>
</Frame>
## How to Get Your Supporter Key
@@ -66,10 +68,12 @@ Pangolin self-hosted will always be free and open source, but maintaining the pr
</Step>
</Steps>
<Frame caption="Pangolin supporter key redemption interface">
<img
src="/images/redeem-key.png"
alt="Pangolin supporter key redemption interface"
/>
</Frame>
## Frequently Asked Questions