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

Merge branch 'dev'

Browse Source
This commit is contained in:
miloschwartz
2025-12-11 16:32:06 -05:00
parent b41d2cb4bd e76c2417c7
commit d98336f688
44 changed files with 1821 additions and 1600 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,66 +1,81 @@
---
title: "How Pangolin Works"
description: "Learn about Pangolin's architecture and how its components work together to provide secure application access"
icon: "brain"
description: "Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access."
---
Pangolin provides secure, application-specific ingress to your applications through a network of nodes. Users connect to the closest node, which authenticates them and routes their requests through secure tunnels to your backend.
<Frame>
<img src="/images/diagram.svg" width="400" centered/>
</Frame>
## How It Works
## Basic Steps
<Steps>
<Step title="User enters through node">
DNS automatically routes users to the closest available regional node. A node is always available because the control plane fails over between nodes.
<Step title="Link remote networks with sites">
Join remote networks together using site connectors. Pangolin's lightweight connectors use intelligent routing and NAT traversal to make any network anywhere available.
</Step>
<Step title="Authentication and authorization">
The node verifies the user's identity, checks access permissions, and applies context aware rules such as IP and path based filters, geoblocking, and rate limiting.
<Step title="Define resources">
Create resources that represent services or entire network ranges available for remote access. Resources can be public or fully private.
</Step>
<Step title="Secure tunnel routing">
Authenticated requests are routed and flow through encrypted WireGuard tunnels to your applications with optional load balancing and failover for your backend servers.
</Step>
<Step title="Application delivery">
Your applications receive the requests and respond through the same secure path.
<Step title="Users access resources">
Authenticated users can access resources anywhere using a web browser or when connected with a Pangolin client on their device.
</Step>
</Steps>
## Deployment Options
## Key Concepts
<CardGroup cols={2}>
<Card title="Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup">
Large network of nodes with automatic failover and routing to your backend services. We host the Pangolin server for you.
Pangolin relies on several components that work together to provide secure remote access. Each component has a specific role in ensuring that only authenticated users can access the resources they are authorized to use.
### Pangolin Server
The Pangolin server is the central coordination component for your network. It stores configuration changes, manages access policies, and coordinates connections between clients and sites. The server handles user authentication and generates access control lists that determine what resources each user can reach.
You can use Pangolin Cloud, which is fully managed, or you can self-host your own Pangolin server for complete control over your infrastructure and data.
<Card title="Read about how to self-host Pangolin" icon="server" href="/self-host/quick-install">
Learn how to deploy your own self-hosted Pangolin server or use Pangolin Cloud.
</Card>
<Card title="Self-host Pangolin" icon="server" href="/self-host/quick-install">
Fully self-hosted, self-contained Pangolin server acting as a single node.
### Sites
Sites connect remote networks to your Pangolin server. They use Newt connectors to create secure tunnels from remote networks back to Pangolin. Sites let you expose resources on those networks to authorized users.
Sites run behind firewalls on remote networks. They maintain outbound connections to the Pangolin server. By default, sites block all traffic until you define resources and grant access. This ensures that just deploying a site does not expose any network resources.
The Newt connector handles tunnel creation, NAT traversal, and routing. It makes remote networks available without requiring complex firewall rules or public IP addresses.
<Card title="Read more about sites" icon="plug" href="/manage/sites/understanding-sites">
Learn about sites, how they work, and how to install and configure them.
</Card>
<Card title="Remote Nodes" icon="circle-nodes" href="/manage/remote-node/ha">
Self-host your own Pangolin node with cloud coordination for high availability and automatic failover. Data always transits your servers.
</Card>
</CardGroup>
### Resources
## Key Benefits
Resources are the applications, hosts, or network ranges you make available to users. They exist on sites and represent what users can access. Users connect to resources, not to sites directly.
<CardGroup cols={2}>
<Card title="No Public IPs or Ports" icon="network-wired">
Your applications can run on private networks without exposing ports.
There are two types of resources. Public resources work through web browsers and act as reverse proxies to backend services. Private resources require a client connection and function like a zero-trust VPN.
You must define resources and assign access before users can reach them. By default, no resources are available on sites. This ensures that only explicitly defined resources can be accessed.
<Card title="Read more about resources" icon="link" href="/manage/resources/understanding-resources">
Learn about public and private resources and how to create them.
</Card>
<Card title="Ingress Mesh" icon="globe">
Users always connect to the closest available node.
### Clients
Clients are software components installed on user devices or machines. They let users and automated systems connect to your Pangolin network and access private resources through a secure tunnel.
Users authenticate through the client using their accounts. Machines connect with credentials. Once connected, users can reach all resources their account has access to. The client handles routing decisions and establishes encrypted tunnels to the appropriate sites.
Clients are available for Mac, Windows, and Linux. They work transparently with applications, so no application configuration is required.
<Card title="Read more about clients" icon="desktop" href="/manage/clients/add-client">
Learn about clients and where to download them for Mac, Windows, and Linux.
</Card>
<Card title="Zero-Trust Security" icon="shield">
Every request is authenticated and authorized before reaching your applications.
</Card>
### Remote Nodes
<Card title="High Availability" icon="check-double">
Multiple nodes, failover, and load balancing between tunnels ensures there is always a way for users to access your applications.
Remote nodes are self-hosted Pangolin servers that you control while using Pangolin Cloud or enterprise for management and coordination. You maintain complete control over your infrastructure and data flow, while the cloud handles the control plane, DNS, certificate management, and backups.
You can deploy multiple remote nodes for high availability and automatic failover. If your nodes become unavailable, traffic can optionally fail over to cloud infrastructure until you restore service.
<Card title="Read more about remote nodes" icon="circle-nodes" href="/manage/remote-node/nodes">
Learn about remote nodes and how they provide high availability and simplified operations.
</Card>
</CardGroup>

55
about/pangolin-vs-reverse-proxy-vs-vpn.mdx Normal file
View File

@@ -0,0 +1,55 @@
---
title: "Pangolin vs. Reverse Proxy vs. VPN"
icon: "book"
description: "What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs?"
---
Pangolin combines the capabilities of both a reverse proxy and a VPN into a single platform. It provides reverse proxy functionality through public resources and VPN functionality through private resources, all with zero-trust access control and distributed architecture.
## What Each Solution Provides
**Reverse Proxies** expose web applications to the internet. They handle SSL termination, load balancing, and basic authentication. Users access applications through web browsers using domain names.
**VPNs** create encrypted tunnels that give users access to entire private networks. Users install client software and connect to a VPN server. Once connected, they can access any resource on the network they have network-level access to.
**Pangolin** provides both capabilities. Public resources work like a reverse proxy, allowing browser-based access to specific applications. Private resources work like a zero-trust VPN, giving users access to specific hosts or network ranges when connected with a client.
## Reverse Proxy Capabilities
Pangolin's public resources function as reverse proxies. They expose web applications through domain names with automatic SSL certificates. Users access these resources through web browsers without installing any software.
Public resources support identity-aware access control. You can require authentication, enforce multi-factor authentication, and create rules based on user identity, roles, geographic location, IP addresses, and URL paths. This goes beyond what traditional reverse proxies offer.
Unlike traditional reverse proxies, Pangolin does not require public IP addresses or open ports on your network. Sites create outbound tunnels to Pangolin, so your applications remain behind firewalls.
## VPN Capabilities
Pangolin's private resources function like a zero-trust VPN. Users install a Pangolin client on their device and connect to your organization. Once connected, they can access the specific hosts or network ranges you have granted them access to.
Private resources provide granular access control. Users only get access to the specific resources you define, not entire networks. This reduces the risk of over-permission that comes with traditional VPNs.
Clients work transparently with applications. No application configuration is required. Users connect once and can access all their authorized resources. The client handles routing and establishes encrypted tunnels automatically.
## Why Pangolin Combines Both
Many organizations need both reverse proxy and VPN capabilities. You might want to expose web applications to users through browsers while also providing secure access to databases, SSH servers, or internal services that require a VPN-like connection.
With Pangolin, you use one platform for both use cases. Public resources handle web application access. Private resources handle VPN-like access. Both use the same authentication system, access control policies, and infrastructure.
This unified approach simplifies management. You configure users, roles, and access policies once. Those policies apply to both public and private resources. You do not need to maintain separate systems for reverse proxy and VPN access.
## Infrastructure and Availability
Traditional reverse proxies and VPNs typically run on a single server. If that server fails, all access is lost. They also require public IP addresses and open ports, which adds complexity and security concerns.
Pangolin uses a distributed architecture with multiple nodes. If one node fails, traffic automatically routes to another node. Sites create outbound tunnels, so your networks do not need public IP addresses or open ports.
You can deploy multiple remote nodes for high availability. If your nodes become unavailable, traffic can optionally fail over to cloud infrastructure until you restore service. This provides redundancy that single-server solutions cannot match.
## When to Use Each Solution
Use a traditional reverse proxy if you only need to expose web applications, you have a public IP address, and you do not need advanced access control or high availability.
Use a traditional VPN if you need full network access, you can accept the security risks of broad access, and you do not need application-specific access control.
Use Pangolin if you need both reverse proxy and VPN capabilities, you want granular access control, you need high availability, or you want to avoid public IP addresses and open ports.

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

@@ -1,114 +0,0 @@
---
title: "Pangolin vs. Reverse Proxy"
description: "Learn how Pangolin's distributed architecture eliminates single points of failure and provides authenticated access to your applications"
---
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 nodes that provide highly-available access to your applications.
## Traditional Reverse Proxy Limitations
<CardGroup cols={2}>
<Card title="Single Point of Failure" icon="triangle-exclamation">
If the reverse proxy server goes down, all applications become inaccessible.
</Card>
<Card title="Geographic Limitations" icon="globe">
Users far from the server location experience higher latency.
</Card>
<Card title="Network Dependencies" icon="network-wired">
Requires public IP addresses and open ports on your network.
</Card>
<Card title="Basic Authentication" icon="shield">
Typically relies on network-based trust rather than user identity.
</Card>
</CardGroup>
## Pangolin's Dual-Layer High Availability
Pangolin provides high availability at two critical layers: ingress points and backend routing.
### How It Works
<Steps>
<Step title="Ingress Routing">
Request is routed to the closest available node. If one goes down, there is always another point available.
</Step>
<Step title="Authentication">
User identity is verified at the node before getting routed to your backend.
</Step>
<Step title="Tunnel Selection">
Pangolin selects the optimal tunnel route to your backend service.
</Step>
<Step title="Failover Handling">
If the primary tunnel fails, traffic automatically switches to an alternative route.
</Step>
<Step title="Response Delivery">
Response follows the same resilient path back to the user.
</Step>
</Steps>
<Info>
This dual-layer approach ensures your applications remain accessible even if individual nodes or tunnel connections fail.
</Info>
## Key Differences
### Tunneling vs. Direct Network Access
| Traditional Reverse Proxy | Pangolin |
|--------------------------|----------|
| **Public IP Required** | **No Public IP Needed** |
| **Open Ports (80, 443)** | **No Open Ports** |
| **Complex Network Setup** | **Automatic Discovery** |
| **Network-Based Security** | **Encrypted WireGuard Tunnels** |
<Tip>
This tunneling capability makes Pangolin ideal for environments behind restrictive firewalls, CGNAT, or corporate networks.
</Tip>
### Identity-Aware Proxy (IAP)
Traditional reverse proxies rely on network-based trust, while Pangolin implements zero-trust access control:
<CardGroup cols={2}>
<Card title="Multi-Factor Authentication" icon="key">
Support for 2FA, passkeys, and OTP.
</Card>
<Card title="Single Sign-On" icon="users">
Integration with Google, Okta, and other identity providers.
</Card>
<Card title="Granular Permissions" icon="shield-check">
Role-based access control and path-based rules.
</Card>
<Card title="Contextual Rules" icon="map-pin">
IP-based, path-based, and geographic access policies.
</Card>
</CardGroup>
<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 | Regionally, 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 regional distribution |
<Card title="Try Pangolin Cloud" icon="rocket" href="https://app.pangolin.net/auth/signup">
Get distributed, authenticated access to your applications with Pangolin's regional network of nodes.
</Card>

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

@@ -1,92 +0,0 @@
---
title: "Pangolin vs. VPN"
description: "Learn how Pangolin provides application-specific access with zero-trust security compared to traditional VPNs"
---
Pangolin and VPNs serve different purposes: Pangolin focuses on secure ingress and application routing, while VPNs provide remote access to internal networks. They offer different approaches to secure connectivity.
## Traditional VPN Limitations
<CardGroup cols={2}>
<Card title="Over-Permission" icon="key">
Users get access to entire networks, not just the applications they need.
</Card>
<Card title="Client Software Required" icon="download">
Users must install and configure VPN client software.
</Card>
<Card title="Network Complexity" icon="network-wired">
Requires public IP addresses, open ports, and complex network configuration.
</Card>
<Card title="Limited Access Control" icon="shield">
Basic network-level security with few granular controls or complicated ACLs.
</Card>
<Card title="Single Point of Failure" icon="heart-crack">
If the VPN server goes down, all access is lost.
</Card>
<Card title="Security Risk" icon="triangle-exclamation">
Broad network access can be risky if user devices are compromised.
</Card>
</CardGroup>
## Pangolin's Ingress-First Approach
Pangolin provides secure, application-specific ingress and routing without the limitations of traditional VPNs:
### Zero-Trust Access Control
<CardGroup cols={2}>
<Card title="Application-Specific" icon="window-maximize">
Users access only the applications they're authorized to use.
</Card>
<Card title="Browser-Based" icon="globe">
No client software installation required - works with any web browser.
</Card>
<Card title="Granular Permissions" icon="shield-check">
Role-based access control, path-based rules, and contextual policies.
</Card>
<Card title="Multi-Factor Authentication" icon="key">
Support for SSO, OIDC, 2FA, and passkeys.
</Card>
</CardGroup>
### Simplified Ingress Infrastructure
<CardGroup cols={2}>
<Card title="No Public IPs" icon="network-wired">
Edge networks don't need public IP addresses.
</Card>
<Card title="Highly Available Mesh" icon="circle-nodes" href="/manage/remote-node/ha">
Multiple nodes ensure high availability.
</Card>
</CardGroup>
## Key Differences
| 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 nodes |
| **Security Model** | Network-based trust | Identity-based trust |
<Card title="Try Pangolin Cloud" icon="rocket" href="https://app.pangolin.net/auth/signup">
Get application-specific access with zero-trust security and no client software required.
</Card>
# Pangolin vs. Mesh VPN (e.g., Tailscale, Netbird)
Pangolin and mesh VPNs like Tailscale or Netbird both provide secure remote access, but they differ in their approach and functionality. Mesh VPNs focus on creating peer-to-peer connections between devices for full network access, while Pangolin is designed to expose specific applications or services securely through nodes, with no need for client-side software on user devices.
Pangolin is a better choice for application-specific access with zero-trust security and no client-side software requirements. Mesh VPNs like Tailscale or Netbird are more suitable for full network access and peer-to-peer connectivity. For environments prioritizing granular access control and simplicity, Pangolin offers a more focused and secure solution.

7
additional-resources/changelog.mdx Normal file
View File

@@ -0,0 +1,7 @@
---
title: "Changelog"
icon: "clipboard-list"
---
To view the complete changelog, please visit our [GitHub Releases
page](https://github.com/fosrl/pangolin/releases).

9
additional-resources/trust-center.mdx Normal file
View File

@@ -0,0 +1,9 @@
---
title: "Trust Center"
icon: "scale-balanced"
---
- [Terms of Service](https://pangolin.net/terms-of-service.html)
- [Privacy Policy](https://pangolin.net/privacy-policy.html)
- [AGLPv3](https://www.gnu.org/licenses/gpl-3.0.en.html)
- [Fossorial Commercial License (FCL)](https://pangolin.net/fcl.hmtl)

12
development/contributing.mdx
View File

@@ -7,9 +7,9 @@ This guide describes how to set up your local development environment for contri
## Prerequisites
- NodeJS v20.10.0
- NPM v10.2.3 (or similar)
- Go v1.23.1
- Node 24
- NPM 11 or similar
- Go 1.25
- Git
- Docker & Docker Compose
@@ -280,7 +280,7 @@ Windows users with Docker Desktop + WSL2: File change detection may not work pro
### Gerbil
- Go v1.23.1
- Go 1.25
```bash
make local
@@ -288,7 +288,7 @@ make local
### Newt
- Go v1.23.1
- Go 1.25
```bash
make local
@@ -296,7 +296,7 @@ make local
### Olm
- Go v1.23.1
- Go 1.25
```bash
make local

537
docs.json
View File

@@ -1,257 +1,288 @@
{
"$schema": "https://mintlify.com/docs.json",
"theme": "aspen",
"name": "Pangolin Docs",
"description": "Pangolin is a self-hosted alternative to Cloudflare Tunnels, designed to provide secure and highly-available ingress access to applications.",
"colors": {
"primary": "#F36117",
"light": "#F36117",
"dark": "#F36117"
},
"favicon": "/favicon.svg",
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "About",
"pages": [
"about/pangolin-vs-traditional-reverse-proxy",
"about/pangolin-vs-vpn"
]
},
{
"group": "Manage Pangolin",
"pages": [
{
"group": "Sites",
"pages": [
"manage/sites/add-site",
"manage/sites/install-site",
"manage/sites/install-kubernetes",
"manage/sites/configure-site",
"manage/sites/update-site"
]
},
{
"group": "Resources",
"pages": [
"manage/resources/targets",
"manage/resources/tcp-udp-resources",
"manage/resources/client-resources"
]
},
{
"group": "Access Control",
"pages": [
"manage/access-control/create-user",
"manage/access-control/rules",
"manage/access-control/forwarded-headers",
"manage/access-control/login-page",
"manage/geoblocking",
"manage/access-control/mfa",
"manage/access-control/password-rotation",
"manage/access-control/session-length",
"manage/access-control/change-password",
"manage/access-control/security-keys"
]
},
{
"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/azure",
"manage/identity-providers/pocket-id",
"manage/identity-providers/zitadel"
]
},
{
"group": "Clients",
"pages": [
"manage/clients/add-client",
"manage/clients/install-client",
"manage/clients/configure-client"
]
},
"manage/healthchecks-failover",
"manage/blueprints",
{
"group": "Remote Nodes",
"pages": [
"manage/remote-node/ha",
"manage/remote-node/nodes",
"manage/remote-node/quick-install-remote",
"manage/remote-node/convert-remote",
"manage/remote-node/config-file"
]
},
{
"group": "Analytics",
"pages": [
"manage/analytics/request",
"manage/analytics/access",
"manage/analytics/action"
]
},
"manage/domains",
"manage/integration-api",
"manage/branding"
]
},
{
"group": "Self-host Pangolin",
"pages": [
"self-host/quick-install",
{
"group": "Manual Installation",
"pages": [
"self-host/manual/docker-compose",
"self-host/manual/unraid"
]
},
"self-host/dns-and-networking",
"self-host/choosing-a-vps",
"self-host/how-to-update",
"self-host/supporter-program",
{
"group": "Advanced Configuration",
"pages": [
"self-host/advanced/config-file",
"self-host/advanced/wild-card-domains",
"self-host/advanced/cloudflare-proxy",
"self-host/advanced/without-tunneling",
"self-host/advanced/container-cli-tool",
"self-host/advanced/database-options",
"self-host/advanced/integration-api",
"self-host/advanced/enable-geoblocking",
"self-host/advanced/metrics"
]
},
{
"group": "Community Guides",
"pages": [
"self-host/community-guides/overview",
"self-host/community-guides/crowdsec",
"self-host/community-guides/metrics",
"self-host/community-guides/homeassistant",
"self-host/community-guides/middlewaremanager",
"self-host/community-guides/traefiklogsdashboard",
"self-host/community-guides/geolite2automation"
]
},
"self-host/telemetry",
"self-host/enterprise-edition"
]
},
{
"group": "Development",
"pages": [
"development/system-architecture",
"development/contributing",
"development/feature-requests-and-bug-reports"
]
},
{
"group": "Careers",
"pages": [
"careers/join-us",
"careers/software-engineer-full-stack",
"careers/software-engineer-go"
]
}
]
},
{
"tab": "Blog",
"href": "https://pangolin.net/blog"
},
{
"tab": "Website",
"href": "https://pangolin.net/"
}
],
"global": {
"anchors": [
{
"anchor": "GitHub",
"href": "https://github.com/fosrl/pangolin",
"icon": "github"
},
{
"anchor": "Slack",
"href": "https://pangolin.net/slack",
"icon": "slack"
},
{
"anchor": "Discord",
"href": "https://pangolin.net/discord",
"icon": "discord"
}
]
}
},
"logo": {
"light": "/logo/light.png",
"dark": "/logo/dark.png",
"href": "https://docs.pangolin.net"
},
"navbar": {
"links": [
{
"label": "Contact Us",
"href": "mailto:numbat@pangolin.net"
}
],
"primary": {
"type": "button",
"label": "Pangolin Dashboard",
"href": "https://app.pangolin.net"
}
},
"footer": {
"socials": {
"github": "https://github.com/fosrl/pangolin",
"linkedin": "https://linkedin.com/company/digpangolin"
}
},
"integrations": {
"posthog": {
"apiKey": "phc_RIHQ7o2Y2hf8qms2nP62vpoJHEvsrw6TieflQGQO7yI",
"apiHost": "https://pangolin.net/relay-O7yI"
}
},
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude",
"perplexity",
{
"title": "Request a feature",
"description": "Open a GitHub discussion to request a new feature",
"icon": "plus",
"href": "https://github.com/fosrl/pangolin/discussions"
}
]
},
"redirects": [
{
"source": "/telemetry",
"destination": "/self-host/telemetry"
"$schema": "https://mintlify.com/docs.json",
"theme": "aspen",
"name": "Pangolin Docs",
"description": "Pangolin is the easiest to use identity-based remote access platform based on WireGuard.",
"colors": {
"primary": "#F36117",
"light": "#F36117",
"dark": "#F36117"
},
{
"source": "/community/:slug*",
"destination": "/self-host/:slug*"
"favicon": "/favicon.svg",
"navigation": {
"tabs": [
{
"tab": "Docs",
"groups": [
{
"group": "About",
"pages": [
"about/how-pangolin-works",
"about/pangolin-vs-reverse-proxy-vs-vpn"
]
},
{
"group": "Manage Pangolin",
"pages": [
{
"group": "Sites",
"icon": "plug",
"pages": [
"manage/sites/understanding-sites",
"manage/sites/install-site",
"manage/sites/install-kubernetes",
"manage/sites/configure-site",
"manage/sites/update-site",
"manage/sites/credentials"
]
},
{
"group": "Resources",
"icon": "link",
"pages": [
"manage/resources/understanding-resources",
{
"group": "Public Resources",
"pages": [
"manage/resources/public/authentication",
"manage/resources/public/targets",
"manage/healthchecks-failover",
"manage/resources/public/raw-resources"
]
},
{
"group": "Private Resources",
"pages": [
"manage/resources/private/authentication",
"manage/resources/private/destinations",
"manage/resources/private/alias"
]
}
]
},
{
"group": "Clients",
"icon": "desktop",
"pages": [
"manage/clients/understanding-clients",
"manage/clients/install-client",
"manage/clients/configure-client",
"manage/clients/update-client",
"manage/clients/credentials"
]
},
"manage/domains",
{
"group": "Access Control",
"icon": "user-group",
"pages": [
"manage/access-control/create-user",
"manage/access-control/rules",
"manage/access-control/forwarded-headers",
"manage/access-control/login-page",
"manage/geoblocking",
"manage/access-control/mfa",
"manage/access-control/password-rotation",
"manage/access-control/session-length",
"manage/access-control/change-password",
"manage/access-control/security-keys"
]
},
{
"group": "Identity Providers",
"icon": "id-card",
"pages": [
"manage/identity-providers/add-an-idp",
"manage/identity-providers/auto-provisioning",
"manage/identity-providers/openid-connect",
"manage/identity-providers/google",
"manage/identity-providers/azure",
"manage/identity-providers/pocket-id",
"manage/identity-providers/zitadel"
]
},
{
"group": "Logs & Analytics",
"icon": "chart-bar",
"pages": [
"manage/analytics/request",
"manage/analytics/access",
"manage/analytics/action"
]
},
"manage/blueprints",
{
"group": "Remote Nodes",
"icon": "circle-nodes",
"pages": [
"manage/remote-node/ha",
"manage/remote-node/nodes",
"manage/remote-node/quick-install-remote",
"manage/remote-node/convert-remote",
"manage/remote-node/config-file"
]
},
"manage/integration-api",
"manage/branding"
]
},
{
"group": "Self-host Pangolin",
"pages": [
"self-host/quick-install",
"self-host/choosing-a-vps",
{
"group": "Manual Installation",
"pages": [
"self-host/manual/docker-compose",
"self-host/manual/unraid"
]
},
"self-host/dns-and-networking",
{
"group": "Advanced Configuration",
"pages": [
"self-host/advanced/config-file",
"self-host/advanced/wild-card-domains",
"self-host/advanced/cloudflare-proxy",
"self-host/advanced/without-tunneling",
"self-host/advanced/container-cli-tool",
"self-host/advanced/database-options",
"self-host/advanced/integration-api",
"self-host/advanced/enable-geoblocking",
"self-host/advanced/metrics",
"self-host/telemetry"
]
},
"self-host/how-to-update",
{
"group": "Community Guides",
"pages": [
"self-host/community-guides/overview",
"self-host/community-guides/crowdsec",
"self-host/community-guides/metrics",
"self-host/community-guides/homeassistant",
"self-host/community-guides/middlewaremanager",
"self-host/community-guides/traefiklogsdashboard",
"self-host/community-guides/geolite2automation"
]
},
"self-host/supporter-program",
"self-host/enterprise-edition"
]
},
{
"group": "Development",
"pages": [
"development/system-architecture",
"development/contributing",
"development/feature-requests-and-bug-reports"
]
},
{
"group": "Additional Resources",
"pages": [
"additional-resources/changelog",
"additional-resources/trust-center"
]
}
]
},
{
"tab": "Blog",
"href": "https://pangolin.net/blog"
},
{
"tab": "Website",
"href": "https://pangolin.net/"
}
],
"global": {
"anchors": [
{
"anchor": "GitHub",
"href": "https://github.com/fosrl/pangolin",
"icon": "github"
},
{
"anchor": "Slack",
"href": "https://pangolin.net/slack",
"icon": "slack"
},
{
"anchor": "Discord",
"href": "https://pangolin.net/discord",
"icon": "discord"
}
]
}
},
"interaction": {
"drilldown": true
},
"logo": {
"light": "/logo/light.png",
"dark": "/logo/dark.png",
"href": "https://docs.pangolin.net"
},
"navbar": {
"links": [
{
"label": "Log In",
"href": "https://app.pangolin.net/auth/login"
},
{
"label": "Contact Us",
"icon": "envelope",
"href": "mailto:contact@pangolin.net"
}
],
"primary": {
"type": "button",
"label": "Pangolin Dashboard",
"href": "https://app.pangolin.net/auth/signup"
}
},
"footer": {
"socials": {
"github": "https://github.com/fosrl/pangolin",
"linkedin": "https://linkedin.com/company/digpangolin"
}
},
"integrations": {
"posthog": {
"apiKey": "phc_RIHQ7o2Y2hf8qms2nP62vpoJHEvsrw6TieflQGQO7yI",
"apiHost": "https://pangolin.net/relay-O7yI"
}
},
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude",
"perplexity",
{
"title": "Request a feature",
"description": "Open a GitHub discussion to request a new feature",
"icon": "plus",
"href": "https://github.com/fosrl/pangolin/discussions"
}
]
},
"redirects": [
{
"source": "/telemetry",
"destination": "/self-host/telemetry"
},
{
"source": "/community/:slug*",
"destination": "/self-host/:slug*"
}
],
"seo": {
"metatags": {
"canonical": "https://docs.pangolin.net"
}
}
],
"seo": {
"metatags": {
"canonical": "https://docs.pangolin.net"
}
}
}

BIN
images/hero-dark.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 108 KiB

BIN
images/hero.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 484 KiB

BIN
images/mac-client-preferences.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 471 KiB

BIN
images/private_access_controls.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 27 KiB

26
index.mdx
View File

@@ -2,24 +2,40 @@
title: "Introduction to Pangolin"
---
Pangolin is an open-source and identity-aware tunneled reverse proxy server. Pangolin's distributed architecture with nodes provide highly available ingress to ensure applications always remain accessible.
Pangolin is an open-source, identity-based remote access platform built on WireGuard that enables secure, seamless connectivity to private and public resources.
<Frame caption="Screenshot of resources page from the Pangolin Dashboard.">
<img src="/images/fossorial-dashboard.png" alt="Pangolin Dashboard"/>
<img src="/images/hero.png" alt="Pangolin Dashboard"/>
</Frame>
Pangolin establishes secure connections from edge networks to nodes, bypassing the need for public inbound ports and complex firewall configurations. Pangolin is incredibly useful for exposing local services, IoT devices, or internal applications to the internet without direct exposure, enhancing security by reducing attack surface and simplifying network management. Additionally, Pangolin acts as an identity-aware proxy by authenticating every request against admin-defined access controls and rules.
Pangolin combines reverse proxy and VPN capabilities into one platform. It provides browser-based access to web applications and client-based access to private resources like databases and SSH servers, all with zero-trust security and granular access control.
Pangolin connects remote networks using lightweight software connectors called sites. Sites create secure tunnels without requiring public IP addresses or open ports. Admins define specific resources that users can access, not entire networks. This gives users only the access they need while keeping everything else secure.
Users access public resources through any web browser with authentication. Users access private resources by connecting with a Pangolin client on their device. Both methods use the same identity-based access control, so you manage users and permissions in one place.
## Keep Reading
<Card title="How Pangolin Works" icon="brain" href="/about/how-pangolin-works">
Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access.
</Card>
<Card title="Pangolin vs. Reverse Proxy vs. VPN" icon="brain" href="/about/how-pangolin-works">
What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs?
</Card>
## Deployment Options
<Columns cols={2}>
<Card title="Pangolin Cloud" icon="cloud" href="https://app.pangolin.net/auth/signup">
Use Cloud for a highly available and access-controlled ingress service with nodes all over the world. Optionally self-host a node to keep your traffic private.
Use Cloud for low-maintenance, highly available remote access. Optionally self-host a node to keep your traffic private.
</Card>
<Card title="Self-host Pangolin" icon="server" href="self-host/quick-install">
Self-host a fully isolated Pangolin server. Install the Community Edition or Enterprise Edition easily using the quick installer.
</Card>
</Columns>
## What is a fossorial animal?
## What is a Fossorial Animal?
The Pangolin system is made up of many components, all with unique animal names. These animals are called fossorial animals.

6
manage/access-control/rules.mdx
View File

@@ -5,12 +5,12 @@ description: "Configure rules to allow or deny access to resources without authe
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">
<CardGroup cols={3}>
<Card title="Bypass Auth" icon="check">
Bypass authentication completely for matching requests. Users can access resources without any login or PIN.
</Card>
<Card title="Deny Rules" icon="x">
<Card title="Block Access" icon="x">
Completely reject requests that match the rule. Useful for blocking admin paths or sensitive endpoints.
</Card>

120
manage/blueprints.mdx
View File

@@ -1,5 +1,6 @@
---
title: "Blueprints"
icon: "file-code"
description: "Pangolin Blueprints are declarative configurations that allow you to define your resources and their settings in a structured format"
---
@@ -60,12 +61,12 @@ YAML config can be applied using Docker labels, API, from a Newt site, or in the
</Card>
### Proxy Resources
### Public Resources
Proxy resources are used to expose HTTP, TCP, or UDP services through Pangolin. Below is an example configuration for proxy resources:
Public resources are used to expose HTTP, TCP, or UDP services through Pangolin. Below is an example configuration for public resources:
```yaml
proxy-resources:
public-resources:
resource-nice-id-uno:
name: this is a http resource
protocol: http
@@ -115,7 +116,7 @@ Authentication is off by default. You can enable it by adding the relevant field
</Note>
```yaml
proxy-resources:
public-resources:
secure-resource:
name: Secured Resource
protocol: http
@@ -141,7 +142,7 @@ proxy-resources:
You can define simplified resources that contain only target configurations. This is useful for adding targets to existing resources or for simple configurations:
```yaml
proxy-resources:
public-resources:
additional-targets:
targets:
- site: another-site
@@ -158,19 +159,32 @@ proxy-resources:
When using targets-only resources, the `name` and `protocol` fields are not required. All other resource-level validations are skipped for these simplified configurations.
</Note>
### Client Resources
### Private Resources
Client resources define proxied resources accessible when connected via an Olm client:
Private resources define proxied resources accessible when connected via an client:
```yaml
client-resources:
client-resource-nice-id-uno:
name: this is my resource
protocol: tcp
proxy-port: 3001
hostname: localhost
internal-port: 3000
private-resources:
private-resource-nice-id-uno:
name: SSH Server
mode: host
destination: 192.168.1.100
site: lively-yosemite-toad
roles:
- Developer
- DevOps
users:
- user@example.com
machines:
- machine-id-1
- machine-id-2
private-resource-nice-id-duo:
name: Internal Network
mode: cidr
destination: 10.0.0.0/24
site: lively-yosemite-toad
users:
- admin@example.com
```
## Docker Labels Format
@@ -219,25 +233,25 @@ services:
image: nginxdemos/hello
container_name: nginx1
labels:
# Proxy Resource Configuration
- pangolin.proxy-resources.nginx.name=nginx
- pangolin.proxy-resources.nginx.full-domain=nginx.fosrl.io
- pangolin.proxy-resources.nginx.protocol=http
- pangolin.proxy-resources.nginx.headers[0].name=X-Example-Header
- pangolin.proxy-resources.nginx.headers[0].value=example-value
# Public Resource Configuration
- pangolin.public-resources.nginx.name=nginx
- pangolin.public-resources.nginx.full-domain=nginx.fosrl.io
- pangolin.public-resources.nginx.protocol=http
- pangolin.public-resources.nginx.headers[0].name=X-Example-Header
- pangolin.public-resources.nginx.headers[0].value=example-value
# Target Configuration - the port and hostname will be auto-detected
- pangolin.proxy-resources.nginx.targets[0].method=http
- pangolin.proxy-resources.nginx.targets[0].path=/path
- pangolin.proxy-resources.nginx.targets[0].path-match=prefix
- pangolin.public-resources.nginx.targets[0].method=http
- pangolin.public-resources.nginx.targets[0].path=/path
- pangolin.public-resources.nginx.targets[0].path-match=prefix
nginx2:
image: nginxdemos/hello
container_name: nginx2
labels:
# Additional target for the same resource where the port and hostname are explicit
- pangolin.proxy-resources.nginx.targets[1].method=http
- pangolin.proxy-resources.nginx.targets[1].hostname=nginx2
- pangolin.proxy-resources.nginx.targets[1].port=80
- pangolin.public-resources.nginx.targets[1].method=http
- pangolin.public-resources.nginx.targets[1].hostname=nginx2
- pangolin.public-resources.nginx.targets[1].port=80
networks:
default:
@@ -266,14 +280,14 @@ This will create a resource that looks like the following:
## Configuration Properties
### Proxy Resources
### Public Resources
| Property | Type | Required | Description | Constraints |
|----------|------|----------|-------------|-------------|
| `name` | string | Conditional | Human-readable name for the resource | Required unless targets-only resource |
| `protocol` | string | Conditional | Protocol type (`http`, `tcp`, or `udp`) | Required unless targets-only resource |
| `full-domain` | string | HTTP only | Full domain name for HTTP resources | Required for HTTP protocol, must be unique |
| `proxy-port` | number | TCP/UDP only | Port for raw TCP/UDP resources | Required for TCP/UDP, 1-65535, must be unique within proxy-resources |
| `proxy-port` | number | TCP/UDP only | Port for raw TCP/UDP resources | Required for TCP/UDP, 1-65535, must be unique within public-resources |
| `ssl` | boolean | No | Enable SSL/TLS for the resource | - |
| `enabled` | boolean | No | Whether the resource is enabled | Defaults to `true` |
| `host-header` | string | No | Custom Host header for requests | - |
@@ -305,7 +319,7 @@ This will create a resource that looks like the following:
Health checks can be configured for individual targets to monitor their availability. Add a `healthcheck` object to any target:
```yaml
proxy-resources:
public-resources:
monitored-service:
name: Monitored Service
protocol: http
@@ -358,6 +372,7 @@ Not allowed on TCP/UDP resources.
| `sso-roles` | array | No | Allowed SSO roles | Cannot include "Admin" role |
| `sso-users` | array | No | Allowed SSO usernames | Must be valid usernames |
| `whitelist-users` | array | No | Whitelisted user emails | Must be valid email addresses |
| `auto-login-idp` | number | No | Automatic login identity provider ID | Must be a positive integer |
### Rules Configuration
@@ -367,19 +382,20 @@ Not allowed on TCP/UDP resources.
| `match` | string | Yes | Match type (`cidr`, `path`, `ip`, or `country`) | - |
| `value` | string | Yes | Value to match against | Format depends on match type. For `country` match, use `ALL` to match all countries |
### Client Resources
### Private Resources
These are resources used with Pangolin Olm clients (e.g., SSH, RDP).
These are resources used with Pangolin clients (e.g., SSH, RDP).
| Property | Type | Required | Description | Constraints |
|----------|------|----------|-------------|-------------|
| `name` | string | Yes | Human-readable name for the resource | 2-100 characters |
| `protocol` | string | Yes | Protocol type (`tcp` or `udp`) | - |
| `proxy-port` | number | Yes | Port accessible to clients | 1-65535, must be unique within client-resources |
| `hostname` | string | Yes | Target hostname or IP address | 1-255 characters |
| `internal-port` | number | Yes | Port on the target system | 1-65535 |
| `site` | string | No | Site identifier where the resource is located | 2-100 characters |
| `enabled` | boolean | No | Whether the resource is enabled | Defaults to `true` |
| `name` | string | Yes | Human-readable name for the resource | 1-255 characters |
| `mode` | string | Yes | Resource mode (`host` or `cidr`) | - |
| `destination` | string | Yes | Target IP address, hostname, or CIDR block | For `host` mode: IP address or domain. For `cidr` mode: valid CIDR notation |
| `site` | string | Yes | Site identifier where the resource is located | - |
| `alias` | string | No | Fully qualified domain name alias | Must be a valid FQDN (e.g., example.com). Required when destination is a domain in `host` mode |
| `roles` | array | No | Allowed SSO roles | Cannot include "Admin" role |
| `users` | array | No | Allowed user emails | Must be valid email addresses |
| `machines` | array | No | Allowed machine identifiers | Array of strings |
## Validation Rules and Constraints
@@ -392,14 +408,13 @@ These are resources used with Pangolin Olm clients (e.g., SSH, RDP).
- **TCP/UDP Protocol**: Must have `proxy-port` and targets must NOT have `method` field
- **TCP/UDP Protocol**: Cannot have `auth` configuration
3. **Port Uniqueness**:
- `proxy-port` values must be unique within `proxy-resources`
- `proxy-port` values must be unique within `client-resources`
- Cross-validation between proxy and client resources is not enforced
3. **Alias Uniqueness**: `alias` values must be unique across all private resources within the same blueprint and in the org
4. **Domain Uniqueness**: `full-domain` values must be unique across all proxy resources
4. **Domain Uniqueness**: `full-domain` values must be unique across all public resources
5. **Target Method Requirements**: When protocol is `http`, all non-null targets must specify a `method`
5. **Proxy Port Uniqueness**: `proxy-port` values must be unique per protocol within public resources (e.g., TCP port 3000 and UDP port 3000 can coexist)
6. **Target Method Requirements**: When protocol is `http`, all non-null targets must specify a `method`
## Common Validation Errors
@@ -409,10 +424,10 @@ When working with blueprints, you may encounter these validation errors:
The `Admin` role is reserved and cannot be included in the `sso-roles` array for authentication configuration.
### "Duplicate 'full-domain' values found"
Each `full-domain` must be unique across all proxy resources. If you need multiple resources for the same domain, use different subdomains or paths.
Each `full-domain` must be unique across all public resources. If you need multiple resources for the same domain, use different subdomains or paths.
### "Duplicate 'proxy-port' values found"
Port numbers in `proxy-port` must be unique within their resource type (proxy-resources or client-resources separately).
### "Duplicate 'proxy-port' values found in public-resources"
Port numbers in `proxy-port` must be unique per protocol within public-resources (e.g., you can't have two TCP resources using port 3000, but TCP port 3000 and UDP port 3000 can coexist).
### "When protocol is 'http', all targets must have a 'method' field"
All targets in HTTP proxy resources must specify whether they use `http`, `https`, or `h2c`.
@@ -425,3 +440,14 @@ Authentication is only supported for HTTP resources, not TCP or UDP.
### "Resource must either be targets-only or have both 'name' and 'protocol' fields"
Resources must either contain only the `targets` field (targets-only) or include both `name` and `protocol` for complete resource definitions.
### "Duplicate 'alias' values found in private-resources"
Alias values in private resources must be unique within the blueprint.
### "Destination must be a valid IP address or valid domain AND alias is required"
For private resources in `host` mode, the destination must be a valid IP address or domain. When using a domain, an `alias` field is required.
### "Destination must be a valid CIDR notation for cidr mode"
For private resources in `cidr` mode, the destination must be a valid CIDR notation (e.g., 10.0.0.0/24).
### "Admin role cannot be included in roles"
The `Admin` role is reserved and cannot be included in the `roles` array for private resource configuration.

37
manage/branding.mdx
View File

@@ -1,5 +1,6 @@
---
title: "Branding"
icon: "brush"
description: "Learn how to customize the look your Pangolin dashboard and login pages with custom branding"
---
@@ -25,8 +26,6 @@ branding:
light_path: "/branding/logo-light.svg"
dark_path: "/branding/logo-dark.svg"
favicon_path: "/branding/favicon.ico"
colors:
light:
primary: "hsl(212, 65%, 35%)"
@@ -73,6 +72,16 @@ All branding configuration options are optional. Only specify the sections you w
**Example**: `"MyApp"`
</ResponseField>
### Favicon
To customize the favicon, mount your favicon to `/app/public/favicon.ico` in the container.
```yaml title="docker-compose.yml"
volumes:
- ./config:/app/config
- ./branding/favicon.ico:/app/public/favicon.ico
```
### Background Image
<ResponseField name="background_image_path" type="string">
@@ -168,18 +177,6 @@ All branding configuration options are optional. Only specify the sections you w
</Expandable>
</ResponseField>
### Favicon
<ResponseField name="favicon_path" type="string">
Path to a custom favicon.
**Example**: `"/branding/favicon.ico"`
<Note>
Requires mounting a volume to `/app/public`.
</Note>
</ResponseField>
### Footer
<ResponseField name="footer" type="array of objects">
@@ -209,12 +206,6 @@ All branding configuration options are optional. Only specify the sections you w
Custom text for the login page.
<Expandable title="Login Page">
<ResponseField name="title_text" type="string">
The main title text displayed on the login page.
**Example**: `"Welcome Back!"`
</ResponseField>
<ResponseField name="subtitle_text" type="string">
The subtitle text displayed below the title.
@@ -229,12 +220,6 @@ All branding configuration options are optional. Only specify the sections you w
Custom text for the signup page.
<Expandable title="Signup Page">
<ResponseField name="title_text" type="string">
The main title text displayed on the signup page.
**Example**: `"Create Your Account"`
</ResponseField>
<ResponseField name="subtitle_text" type="string">
The subtitle text displayed below the title.

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

@@ -1,180 +0,0 @@
---
title: "Add Client"
description: "Create a client to connect to your Pangolin network from a remote computer"
---
A client in Pangolin is a way to create a traditional VPN tunnel from your remote computer to your Newt site on your private network. Clients allow you to tunnel your computer back into your whole network and remotely access non-HTTP resources like file shares or use it as a bastion host to manage servers.
<Note>
Client support in Pangolin is still in beta - things may not perform as expected. If you encounter bugs please report them on [GitHub in an issue](https://github.com/fosrl/pangolin).
</Note>
## How Clients Work
### The Connection Process
1. **Client Creation**: You create a client in Pangolin's dashboard
2. **Olm Registration**: Olm registers with Pangolin using the client credentials
3. **Tunnel Establishment**: Olm establishes a WireGuard tunnel to your network
4. **Resource Access**: You can access resources on your private network through the tunnel
### What Clients Are
- A way to tunnel your computer back into your whole network
- Remotely access non HTTP resources like file shares
- A bastion host or "jump box" to manage servers
### What Pangolin Clients Are Not (Yet)
- A mesh VPN like Tailscale, Netbird, or Netmaker
- A slick desktop UI (coming soon)
You can install the [Olm](https://github.com/fosrl/olm) client on your computer and run it with the ID and secret values you generate in the dashboard. When it connects, it will create a virtual network adapter on your computer just like a traditional VPN.
[Take a look at a quick video about clients](https://youtu.be/jg8Bb05hlnI)
## Prerequisites
Before adding a client, ensure you have:
1. **Updated Components**: Make sure you have the required versions:
- Pangolin ^1.8.0
- Gerbil ^1.1.0
- Newt ^1.4.0
2. **Site Configuration**: Your Newt site must be configured to accept clients with the `--accept-clients` flag or `ACCEPT_CLIENTS=true` environment variable.
3. **Port Configuration**: Ensure port 21820 is open on your VPS and added to your `docker-compose.yml`:
```yml title="docker-compose.yml" highlight={4}
gerbil:
ports:
- 51820:51820/udp
- 21820:21820/udp
- 443:443
- 80:80
```
## Adding a Client
<Steps>
<Step title="Navigate to Clients">
In the Pangolin dashboard, go to the **Clients** section and click **Add Client**.
</Step>
<Step title="Configure client details">
Configure the basic information:
- **Client Name**: A descriptive name for your client
</Step>
<Step title="Generate Olm credentials">
Pangolin will generate:
- **Client ID**: Unique identifier for the Olm client
- **Secret**: Authentication secret for secure connection
- **Endpoint**: The Pangolin server endpoint
</Step>
<Step title="Install Olm">
Use the generated credentials to install and configure Olm on your remote computer. See [Install Olm](/manage/clients/install-client) for detailed instructions.
</Step>
<Step title="Configure resources">
Create [client resources](/manage/resources/client-resources) for what you would like to access through the client. For example, to SSH into a server, create a resource like `22:localhost:22`.
</Step>
<Step title="Verify connection">
Once Olm is running, the client status should show as "Online" in the dashboard. You can then connect to your network using the site's IP address.
</Step>
</Steps>
## Client Modalities
Clients have two major operation modalities:
### Relaying (Default)
By default, Olm will relay traffic through your Pangolin VPS - through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of Newt.
### NAT Hole Punching (Experimental)
<Note>
Right now NAT hole punching is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats.
Take a look at [Tailscale docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make to improve HP performance.
</Note>
This mode can be activated by using `--holepunch` in Olm. Instead of immediately relaying through the VPS, this will attempt to connect directly to the Newt site across NAT routers.
This should help to:
- Increase performance (speed/bandwidth)
- Reduce VPS transit costs
## Site Modalities
Sites have two operating modalities when accepting clients:
### Proxy Mode
When you run Newt with `--accept-clients` it will run fully in user space. This means you do not need to give the container or binary any special permissions. It will NOT create a virtual network interface on the host. Instead you should create [client resources](/manage/resources/client-resources) in Pangolin to configure what ports clients can hit and where they should go.
### Native Mode
<Note>
Right now native mode only works on Linux.
</Note>
In native mode with both `--accept-clients` and `--native`, Newt will create a native Linux tunnel interface on the host. This means that all traffic destined for the site can access anything on the host.
#### Remote Subnets
In native mode, you can add remote subnets to the site settings in Pangolin to forward remote networks through Newt. This can let Newt act as a traditional VPN server to route to anything on your local network.
<Frame caption="Pangolin UI showing remote subnets for clients.">
<img src="/images/remote_subnets.png" alt="Remote Subnets"/>
</Frame>
This will configure a route on the Olm side of the tunnel to route this subnet down the tunnel. When it reaches the other end, can be routed to the appropriate destination by the host.
This requires proper Linux routing configuration. Here's what happens in native mode:
1. **Olm forwards packets**: Your computer running Olm blindly forwards all packets destined for the remote subnet (e.g., 192.168.0.x) over the tunnel
2. **Newt receives packets**: Newt creates a WireGuard network interface on the Linux host and receives these packets
3. **Linux must route packets**: The Linux machine needs to know what to do with packets destined for 192.168.0.x
#### Required Configuration
**Enable IP forwarding:**
```bash
sudo nano /etc/sysctl.conf
net.ipv4.ip_forward = 1
```
**Setup NAT masquerading:**
```bash
sudo iptables -t nat -A POSTROUTING -j MASQUERADE
```
This rewrites the source address of packets from the tunnel to be the 192.168.0.x address of the Linux instance when packets leave the instance. This way, when devices on 192.168.0.x reply to the Olm client, they know to send the response back through the tunnel.
#### Troubleshooting Routing Issues
If you can connect to Newt (peer shows as connected in logs) but can't reach remote subnet resources:
1. **Check if packets reach the destination**: The connection to Newt is working, so this is likely a routing issue
2. **Verify forwarding is enabled**: Use `sysctl net.ipv4.ip_forward` to confirm it's set to 1
3. **Check iptables rules**: Ensure NAT masquerading is configured
4. **Consider using proxy mode**: [Client resources](/manage/resources/client-resources) can be easier as Newt handles the proxying, though you'll need to address everything as the Newt IP and assign specific ports
<Note>
NAT masquerading can affect other services on the Linux instance, so be aware of potential conflicts with existing network configurations.
</Note>
## Notes
- Clients require Olm to be running on the remote computer
- Each client can access multiple resources on the site
- Connection status is monitored automatically
- Olm creates a native tun interface and usually requires sudo/admin permissions
- On Windows: Olm will run as a service
- LXC containers need to be configured to allow tun access

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

@@ -1,25 +1,23 @@
---
title: "Configure Client"
title: "Configure Clients"
description: "Configure Olm for connecting to Pangolin clients"
---
Olm is a WireGuard client designed to securely connect your remote computer to your Pangolin network. By using Olm, you can create a traditional VPN tunnel that allows you to access resources on your private network from anywhere.
## Mac and Windows
## How Olm Works
Each respective client has a preferences window with all currently available configuration parameters like DNS override and preferred DNS servers. In your desktop client, click the menu bar or system tray icon, select More in the menu, and click Preferences.
### Registers with Pangolin
<Frame caption="Screenshot of how to access preferences window on Mac client. The steps are the same on Windows.">
<img src="/images/mac-client-preferences.png" centered/>
</Frame>
Using the Olm 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.
## Pangolin CLI
### Establishes WireGuard Tunnel
Refer to the [documentation in the official repository](https://github.com/fosrl/cli/blob/main/docs/pangolin.md) for the available commands, default values, and more.
When Olm receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using native system interfaces. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up.
## Olm CLI
### Creates Virtual Network Interface
Olm creates a virtual network adapter on your computer just like a traditional VPN. This allows you to access resources on your private network as if you were physically connected to it.
## Configuration Arguments
### Flags
<ResponseField name="id" type="string" required>
Olm ID generated by Pangolin to identify the client.
@@ -43,18 +41,32 @@ Olm creates a virtual network adapter on your computer just like a traditional V
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="org" type="string">
Organization ID to connect to.
</ResponseField>
<ResponseField name="user-token" type="string">
User authentication token.
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the WireGuard interface.
MTU for the internal WireGuard interface.
**Default**: `1280`
</ResponseField>
<ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint.
DNS server to use to resolve the endpoint.
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="upstream-dns" type="string">
Upstream DNS server(s), comma-separated.
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="log-level" type="string">
The log level to use for Olm output.
@@ -75,68 +87,56 @@ Olm creates a virtual network adapter on your computer just like a traditional V
**Default**: `5s`
</ResponseField>
<ResponseField name="holepunch" type="boolean">
Enable NAT hole punching mode instead of relaying through the VPS.
<ResponseField name="interface" type="string">
Name of the WireGuard interface.
**Default**: `olm`
</ResponseField>
<ResponseField name="enable-api" type="boolean">
Enable API server for receiving connection requests.
**Default**: `false`
<Note>
This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying.
</Note>
</ResponseField>
<ResponseField name="config-file" type="string">
Path to a configuration file containing the same arguments as command line.
<ResponseField name="http-addr" type="string">
HTTP server address (e.g., ':9452').
**Example**: `/etc/olm/config.yaml`
**Default**: `:9452`
</ResponseField>
## Configuration Examples
<ResponseField name="socket-path" type="string">
Unix socket path (or named pipe on Windows).
### Basic Configuration
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
```
<ResponseField name="disable-holepunch" type="boolean">
Disable hole punching.
### With Hole Punching
**Default**: `false`
</ResponseField>
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--holepunch
```
<ResponseField name="override-dns" type="boolean">
Override system DNS settings.
### With Custom MTU and DNS
**Default**: `false`
</ResponseField>
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--mtu 1400 \
--dns 1.1.1.1
```
<ResponseField name="disable-relay" type="boolean">
Disable relay connections.
### With Health Check
**Default**: `false`
</ResponseField>
```bash
olm \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--health-file /tmp/olm-health
```
## Environment Variables
### Environment Variables
All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Olm in containerized environments.
<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>
<ResponseField name="PANGOLIN_ENDPOINT" type="string">
Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>
@@ -149,79 +149,141 @@ All CLI arguments can be set using environment variables as an alternative to co
Olm secret for authentication (equivalent to `--secret`)
</ResponseField>
<ResponseField name="OLM_MTU" type="integer">
MTU for the WireGuard interface (equivalent to `--mtu`)
<ResponseField name="ORG" type="string">
Organization ID to connect to (equivalent to `--org`)
</ResponseField>
<ResponseField name="USER_TOKEN" type="string">
User authentication token (equivalent to `--user-token`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
**Default**: `1280`
</ResponseField>
<ResponseField name="OLM_DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`)
<ResponseField name="DNS" type="string">
DNS server to use to resolve the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8`
</ResponseField>
<ResponseField name="OLM_LOG_LEVEL" type="string">
<ResponseField name="UPSTREAM_DNS" type="string">
Upstream DNS server(s), comma-separated (equivalent to `--upstream-dns`)
**Default**: `8.8.8.8:53`
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
Log level (equivalent to `--log-level`)
**Default**: `INFO`
</ResponseField>
<ResponseField name="OLM_PING_INTERVAL" type="string">
<ResponseField name="PING_INTERVAL" type="string">
Interval for pinging the server (equivalent to `--ping-interval`)
**Default**: `3s`
</ResponseField>
<ResponseField name="OLM_PING_TIMEOUT" type="string">
<ResponseField name="PING_TIMEOUT" type="string">
Timeout for each ping (equivalent to `--ping-timeout`)
**Default**: `5s`
</ResponseField>
<ResponseField name="OLM_HOLEPUNCH" type="boolean">
Enable NAT hole punching mode (equivalent to `--holepunch`)
<ResponseField name="INTERFACE" type="string">
Name of the WireGuard interface (equivalent to `--interface`)
**Default**: `olm`
</ResponseField>
<ResponseField name="ENABLE_API" type="boolean">
Enable API server for receiving connection requests (equivalent to `--enable-api`)
Set to "true" to enable
**Default**: `false`
</ResponseField>
<ResponseField name="OLM_HEALTH_FILE" type="string">
Path to health file for connection monitoring (equivalent to `--health-file`)
<ResponseField name="HTTP_ADDR" type="string">
HTTP server address (equivalent to `--http-addr`)
**Default**: `:9452`
</ResponseField>
<ResponseField name="OLM_CONFIG_FILE" type="string">
Load the config from this file instead of command line arguments (equivalent to `--config-file`)
<ResponseField name="SOCKET_PATH" type="string">
Unix socket path or Windows named pipe (equivalent to `--socket-path`)
**Default**: `/var/run/olm.sock` (Linux/macOS) or `olm` (Windows)
</ResponseField>
<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>
<ResponseField name="DISABLE_HOLEPUNCH" type="boolean">
Disable hole punching (equivalent to `--disable-holepunch`)
## Troubleshooting
Set to "true" to disable
### Connection Issues
**Default**: `false`
</ResponseField>
1. **Check credentials**: Ensure the ID and secret are correct
2. **Verify endpoint**: Make sure the endpoint URL is accessible
3. **Check firewall**: Ensure port 21820 is open on your VPS
4. **Verify site configuration**: Make sure your Newt site has `--accept-clients` enabled
<ResponseField name="OVERRIDE_DNS" type="boolean">
Override system DNS settings (equivalent to `--override-dns`)
### Permission Issues
Set to "true" to enable
1. **Linux/macOS**: Run with sudo or ensure proper capabilities
2. **Windows**: Run as administrator or install as a service
3. **LXC containers**: Configure tun device access
**Default**: `false`
</ResponseField>
### Performance Issues
<ResponseField name="DISABLE_RELAY" type="boolean">
Disable relay connections (equivalent to `--disable-relay`)
1. **Try hole punching**: Use `--holepunch` for better performance
2. **Adjust MTU**: Try different MTU values if experiencing packet loss
3. **Check network**: Ensure stable internet connection
Set to "true" to disable
## Security Considerations
**Default**: `false`
</ResponseField>
- Keep your client secret secure and private
- Use HTTPS endpoints only
- Regularly rotate client credentials
- Monitor client connections in the dashboard
- Use firewall rules to restrict access to specific resources
<ResponseField name="CONFIG_FILE" type="string">
Set to the location of a JSON file to load secret values
</ResponseField>
### Loading secrets from files
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
```
$ cat ~/.config/olm-client/config.json
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"org": "",
"userToken": "",
"mtu": 1280,
"dns": "8.8.8.8",
"upstreamDNS": ["8.8.8.8:53"],
"interface": "olm",
"logLevel": "INFO",
"enableApi": false,
"httpAddr": "",
"socketPath": "/var/run/olm.sock",
"pingInterval": "3s",
"pingTimeout": "5s",
"disableHolepunch": false,
"overrideDNS": false,
"disableRelay": false,
"tlsClientCert": ""
}
```
This file is also written to when olm first starts up. So you do not need to run every time with --id and secret if you have run it once!
Default locations:
- **macOS**: `~/Library/Application Support/olm-client/config.json`
- **Windows**: `%PROGRAMDATA%\olm\olm-client\config.json`
- **Linux/Others**: `~/.config/olm-client/config.json`
### API
Olm can be started with a HTTP or socket API to configure and manage it. See the [API documentation](https://github.com/fosrl/olm/blob/main/API.md) for more details.

52
manage/clients/credentials.mdx Normal file
View File

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

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

@@ -1,25 +1,138 @@
---
title: "Install Client"
description: "Install Olm as a binary"
title: "Install Clients"
description: "Install native clients for Mac, Windows, and Linux"
---
Olm can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases.
## Windows
<Warning>
You **must first create a client and copy the Olm config** in Pangolin before running Olm.
</Warning>
- [Pangolin for Windows Installer](https://pangolin.net/downloads/windows) - This is the official page to download the latest installer file for Windows.
- [All Versions](https://github.com/fosrl/windows/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.
## Binary Installation
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .msi installer from the download button above.
2. **Launch Pangolin**
Open Pangolin from the Start menu or the shortcut on your Desktop.
3. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
- Click the Pangolin icon in the task bar's system tray and select Log in.
## Mac
- [Pangolin for macOS Installer](https://pangolin.net/downloads/mac) - This is the official page to download the latest installer file for macOS.
- [All Versions](https://github.com/fosrl/apple/releases) - The releases section of this repository contains release notes and download artifacts for the latest version and all older versions.
### Installation Steps
1. **Download and install the Pangolin client**
Download and install the Pangolin client using the official .dmg installer from the download button above.
- Open the downloaded .dmg file
- Drag and drop Pangolin.app into your Applications folder
2. **Launch Pangolin**
Open Pangolin from your Applications folder.
3. **Install the VPN configuration**
Follow the Pangolin onboarding flow, which will guide you to install the Pangolin VPN configuration.
- Select Open System Settings on startup when it asks to install a network extension.
- In System Settings, under General > Login Items & Extension > By Category > Network Extensions, ensure that Pangolin.app is toggled on.
- Select Allow when Pangolin asks to add a VPN configuration.
4. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance.
- Click the Pangolin icon in the menu bar and select Log in.
## Pangolin CLI (Linux)
Pangolin CLI is the recommended way to run a client using a command line interface on Mac or Linux. Support for Windows is coming soon.
Pangolin CLI supports running as user device with authentication or a machine client.
### Quick Install (Recommended)
Use this command to automatically install Pangolin CLI. It detects your system architecture automatically and always pulls the latest version, adding `pangolin` to your PATH:
```bash
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
### Manual Download
Binaries for Linux and macOS are available in the [GitHub releases](https://github.com/fosrl/cli/releases) for ARM and AMD64 (x86_64) architectures.
Download and install manually:
```bash
wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
```
<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
</Note>
### Installation Steps
1. **Download and install the Pangolin client**
Install Pangolin using the installation script:
```bash
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
2. **Log in with your Pangolin account**
Log in on your Pangolin Cloud account or your self-hosted Pangolin instance:
```bash
pangolin login
```
3. **Start Pangolin**
Connect Pangolin by running:
```bash
pangolin up
```
## Olm CLI
Olm CLI is the most basic form of a client. All other clients implement Olm under the hood in some form.
If you're looking for a CLI interface for a client, we recommend using Pangolin CLI where possible.
Olm CLI is mainly only used for machine clients. Though the Pangolin CLI can also be used for machine clients, use Pangolin CLI if you expect to log in as a user.
### Binary Installation (Linux)
#### Quick Install (Recommended)
Use this command to automatically install Olm. It detects your system architecture automatically and always pulls the latest version, adding Olm to your PATH:
```bash
curl -fsSL https://pangolin.net/get-olm.sh | bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
### Manual Download
#### Windows
If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest).V
#### Manual Download
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/olm/releases) for ARM and AMD64 (x86_64) architectures.
@@ -44,18 +157,6 @@ olm \
--endpoint https://example.com
```
### Permanent Installation
Install to your PATH (may need to run as root):
```bash
mv ./olm /usr/local/bin
```
<Note>
The quick installer will do this step for you.
</Note>
### Systemd Service
Create a basic systemd service:
@@ -78,11 +179,52 @@ WantedBy=multi-user.target
Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
</Warning>
## Windows Service
### Docker
You can also run it with Docker compose. For example, a service in your `docker-compose.yml` might look like this using environment vars (recommended):
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
devices:
- /dev/net/tun:/dev/net/tun
environment:
- PANGOLIN_ENDPOINT=https://example.com
- OLM_ID=31frd0uzbjvp721
- OLM_SECRET=h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
```
You can also pass the CLI args to the container:
```yaml
services:
olm:
image: fosrl/olm
container_name: olm
restart: unless-stopped
network_mode: host
devices:
- /dev/net/tun:/dev/net/tun
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
```
**Docker Configuration Notes:**
- `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly
- `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces
### Windows Service
On Windows, olm has to be installed and run as a Windows service. When running it with the cli args, it will attempt to install and run the service to function like a cli tool. You can also run the following:
### Service Management Commands
#### Service Management Commands
```
# Install the service
@@ -109,7 +251,7 @@ olm.exe help
Note running the service requires credentials in `%PROGRAMDATA%\olm\olm-client\config.json`.
### Service Configuration
#### Service Configuration
When running as a service, Olm will read configuration from environment variables or you can modify the service to include command-line arguments:
@@ -117,7 +259,7 @@ When running as a service, Olm will read configuration from environment variable
2. Set the credentials in `%PROGRAMDATA%\olm\olm-client\config.json`. Hint: if you run olm once with --id and --secret this file will be populated!
3. Start the service: `olm.exe start`
### Service Logs
#### Service Logs
When running as a service, logs are written to:
@@ -130,11 +272,21 @@ You can view the Windows Event Log using Event Viewer or PowerShell:
Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
```
## Gotchas
### Gotchas
Olm creates a native tun interface. This usually requires sudo / admin permissions. Some notes:
- **Windows**: Olm will run as a service. You can use the commands described [Configure Client](/manage/clients/configure-client) to manage it. You can use this to run it in the background if needed!
- **LXC containers**: Need to be configured to allow tun access. See [Tailscale's guide](https://tailscale.com/kb/1130/lxc-unprivileged).
- **LXC containers**: Need to be configured to allow tun access. On Proxmox see below.
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
- **macOS**: May require additional permissions for network interface creation.
#### LXC Proxmox
1. Create your LXC container.
2. Go to the Resources tab of the container.
3. Select Add. Then select Device Passthrough.
4. On the Add Device prompt, enter dev/net/tun in the Device Path field and select Add.
5. If the container is running, shut it down and start it up again.
Once /dev/net/tun is available, the olm can run within the LXC.

70
manage/clients/understanding-clients.mdx Normal file
View File

@@ -0,0 +1,70 @@
---
title: "Understanding Clients"
description: "Create a client to connect to your Pangolin network from a remote computer"
---
A client is a way to access resources on sites remotely and privately via a virtual private network. Clients are used with private resources to faciliate zero-trust network access.
By default a client does not have access to any hosts on the local network of the site. Admins must explicitely define resources on the site and give specific users and roles access to the resources.
Users must log in and connect from a Pangolin client for [Window, Mac, and Linux](/manage/clients/install-client). Machine (automated systems and servers) connect with an ID and secret.
## Client Types
There are two types of clients: user devices and machines.
<CardGroup cols={2}>
<Card title="User Devices">
- Associated with a user in your Pangolin organization
- Requires login to connect (password, 2fa, etc)
- Available for download on Mac, Windows, and Linux
</Card>
<Card title="Machines">
- Represent a server or automated system instead of a user
- Connect with an ID and secret
- Available in CLI form with Pangolin CLI or Olm CLI
</Card>
</CardGroup>
### User Devices
A user may download a client for their specific system. Before they can connect, they must select a Pangolin server to authenticate to using their provided Pangolin account. Users can log in as a Pangolin user or with your attached external identity provider.
Examples include:
- **SSH**: Admins and developers can connect with their client to specific hosts for SSH.
- **RDP**: Users can connect to a remote host using familiar remote desktop software.
Then, just like in the Pangolin dashboard, a user selects the organization to connect to. Once connected, all resources made available to the user in that organization become available via the tunnel.
### Machines
Machine clients are for servers and automated systems that are not associated with a specific user.
Examples include:
- **CICD**: Access remote resources like a database in an automated deployment pipeline.
- **Servers**: Provide a VPS with access to a resource running in a different network.
Though you may connect a server via a user account using a CLI client, we reccomend you specifically use a machine client.
Machine clients authenticate with an ID and secret string. These credentials are passed via arguments into one of the supported Pangolin CLI clients. They can be revoked and rotated.
## Client Modalities
Clients have two major operation modalities. A client will first attempt to hole punch before falling back to relaying.
### Relaying
Clients can relay traffic through a Pangolin server - through Gerbil specifically. Gerbil listens on UDP port 21820 for new WireGuard connections and forwards the packets down the Newt site tunnels to the right peers. This means your connections back to your site do not require firewall config and uses the existing NAT holepunching capabilities of Newt.
### NAT Hole Punching
While functional, it does not always connect reliably and can fall back to relaying. We plan to work to improve the reliability over time by implementing more methods for those behind CGNAT or hard nats.
Take a look at [some things you can do to improve reliability](/manage/sites/configure-site#nat-traversal-tweaks) if you are not getting reliable hole punching.
This should help to:
- Increase performance (speed/bandwidth)
- Reduce VPS transit costs

73
manage/clients/update-client.mdx Normal file
View File

@@ -0,0 +1,73 @@
---
title: "Update Clients"
description: "Update your installed client to the latest version"
---
## Mac and Windows
### Automatic Updates (Recommended)
The desktop clients for Mac and Windows will periodically check for updates in the background. When an update is available, they will request permission to update. However, you can manually check for updates in the menu bar or system tray menu, or by restarting the application.
Once you accept the update, these clients will automatically download the latest version and replace itself on your computer.
### Manual Updates
- **Mac**: Find the latest version in the [GitHub releases](https://github.com/fosrl/apple/releases).
- **Windows**: Find the latest version in the [GitHub releases](https://github.com/fosrl/windows/releases).
You can download the latest installer files and restart the installation process to install the latest version. Visit [https://pangolin.net/downloads](https://pangolin.net/downloads) to find the latest official installers for your platform.
## Pangolin CLI
Find the latest version in the [GitHub releases](https://github.com/fosrl/cli/releases).
### Automatic Updates (Recommended)
If you already have Pangolin CLI installed, use the update command:
```bash
pangolin update
```
Or you can re-run the installation script:
```bash
curl -fsSL https://static.pangolin.net/get-cli.sh | bash
```
### Manual Updates
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/cli/releases) and replace your existing binary.
```bash
wget -O pangolin "https://github.com/fosrl/cli/releases/download/{version}/pangolin-cli_{architecture}" && chmod +x ./pangolin
```
<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/cli/releases) for the latest information.
</Note>
## Olm CLI
Find the latest version in the [GitHub releases](https://github.com/fosrl/olm/releases).
### Automatic Updates (Recommended)
If you used the auto installer, simply run it again:
```bash
curl -fsSL https://static.pangolin.net/get-olm.sh | bash
```
### Manual Updates
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/olm/releases) and replace your existing binary.
```bash
wget -O olm "https://github.com/fosrl/olm/releases/download/{version}/olm_{architecture}" && chmod +x ./olm
```
<Note>
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/olm/releases) for the latest information.
</Note>

9
manage/domains.mdx
View File

@@ -1,5 +1,6 @@
---
title: "Domains"
icon: "globe"
description: "Learn how to configure domains for your Pangolin resources and understand the different domain types available"
---
@@ -72,6 +73,10 @@ You then access your resources via subdomains like `app.example.com` or `db.exam
### For Domain Delegation
<Warning>
Some domain providers, namely Cloudflare, do not allow adding NS records for the root of your domain. This would prevent you from delegating all `*.example` to Pangolin. However, you can usually delegate everything after the first level, like `*.subdomain.example.com`. If your provider restricts you in this way, you could either move your domain, or use CNAME records for individual subdomains of the root domain.
</Warning>
When using domain delegation, you'll need to update your domain's nameservers:
**Example NS Records:**
@@ -99,7 +104,3 @@ Type: CNAME
Name: _acme-challenge.test.example.com
Value: _acme-challenge.0nbn5rpcq4wthq6.cname.pangolin.net
```
<Check>
Once DNS is properly configured and propagated, your domain will be verified and ready to use with your Pangolin resources.
</Check>

143
manage/healthchecks-failover.mdx
View File

@@ -1,20 +1,9 @@
---
title: "Health Checks"
description: "Configure automated health monitoring and failover for high availability"
description: "Configure automated health monitoring and failover for resources"
---
<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/Xdme_2-AMas"
title="YouTube video player"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>
## Overview
Pangolin provides automated health checking for [targets](/manage/resources/targets) to ensure traffic is only routed to healthy services. Health checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic routing and load balancing.
Pangolin provides automated health checking for targets to ensure traffic is only routed to healthy services. Health checks are essential for building highly available services, as they automatically remove unhealthy targets from traffic routing and load balancing.
## How Health Checks Work
@@ -22,16 +11,10 @@ Pangolin provides automated health checking for [targets](/manage/resources/targ
Health checks operate continuously in the background:
1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals
2. **Status Evaluation**: Responses are evaluated against your configured criteria
3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded
4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again
### Health Check vs Target Endpoint
<Card title="Flexible Monitoring">
The health check endpoint can be the same as your target, but you can also monitor a different endpoint. This allows you to create dedicated health check endpoints that provide more detailed service status information.
</Card>
1. **Periodic Checks**: Pangolin sends requests to your target endpoints at configured intervals.
2. **Status Evaluation**: Responses are evaluated against your configured criteria.
3. **Traffic Management**: Healthy targets receive traffic, unhealthy targets are excluded.
4. **Automatic Recovery**: Targets are automatically re-enabled when they become healthy again.
## Target Health States
@@ -87,109 +70,45 @@ Targets can exist in three distinct states that determine how traffic is routed:
### Endpoint Configuration
<Card title="Health Check Target">
**Target Endpoint**: The URL or address to monitor for health status
**Default Behavior**: Usually the same as your target endpoint
**Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`)
</Card>
- **Target Endpoint**: The URL or address to monitor for health status
- **Default Behavior**: Usually the same as your target endpoint
- **Custom Endpoints**: Can monitor different endpoints (e.g., `/health`, `/status`)
### Timing Configuration
<CardGroup cols={2}>
<Card title="Healthy Interval">
**Purpose**: How often to check targets that are currently healthy
#### Healthy Interval
**Typical Range**: 30-60 seconds
- **Purpose**: How often to check targets that are currently healthy
- **Typical Range**: 30-60 seconds
- **Consideration**: Less frequent checks reduce overhead
**Consideration**: Less frequent checks reduce overhead
</Card>
#### Unhealthy Interval
<Card title="Unhealthy Interval">
**Purpose**: How often to check targets that are currently unhealthy
**Typical Range**: 10-30 seconds
**Consideration**: More frequent checks enable faster recovery
</Card>
</CardGroup>
- **Purpose**: How often to check targets that are currently unhealthy
- **Typical Range**: 10-30 seconds
- **Consideration**: More frequent checks enable faster recovery
### Response Configuration
<Card title="Timeout Settings">
**Request Timeout**: Maximum time to wait for a health check response
#### Timeout Settings
**Default Behavior**: Requests exceeding timeout are considered failed
- **Request Timeout**: Maximum time to wait for a health check response
- **Default Behavior**: Requests exceeding timeout are considered failed
- **Recommended**: Set based on your service's typical response time
**Recommended**: Set based on your service's typical response time
</Card>
#### HTTP Response Codes
<Card title="HTTP Response Codes">
**Healthy Codes**: Which HTTP status codes indicate a healthy target
**Common Settings**: 200, 201, 202, 204
**Custom Codes**: Configure based on your service's health endpoint behavior
</Card>
## Failover Behavior
### Automatic Traffic Exclusion
When a target becomes unhealthy:
<Steps>
<Step title="Health Check Failure">
Target fails to meet health check criteria (response code, timeout, etc.)
</Step>
<Step title="Status Update">
Target status changes from "Healthy" to "Unhealthy"
</Step>
<Step title="Traffic Removal">
Target is immediately removed from traffic routing configuration
</Step>
<Step title="Load Balancer Update">
Load balancing configuration is updated to exclude the unhealthy target
</Step>
<Step title="Continued Monitoring">
Health checks continue at the unhealthy interval for recovery detection
</Step>
</Steps>
### Automatic Recovery
When an unhealthy target recovers:
<Steps>
<Step title="Successful Health Check">
Target begins responding correctly to health checks
</Step>
<Step title="Status Update">
Target status changes from "Unhealthy" to "Healthy"
</Step>
<Step title="Traffic Restoration">
Target is automatically added back to traffic routing
</Step>
<Step title="Load Balancer Update">
Load balancing resumes including the recovered target
</Step>
</Steps>
- **Healthy Codes**: Which HTTP status codes indicate a healthy target
- **Common Settings**: 200, 201, 202, 204
- **Custom Codes**: Configure based on your service's health endpoint behavior
## High Availability Strategies
### Multi-Target Redundancy
<Card title="Service Redundancy">
Deploy multiple instances of your service across different targets to ensure availability even when some targets fail.
</Card>
#### Service Redundancy
Deploy multiple instances of your service across different targets to ensure availability even when some targets fail.
```
Resource: web-application
@@ -202,9 +121,9 @@ Traffic routes to: Target 1 & Target 3 only
### Cross-Site Failover
<Card title="Geographic Distribution">
Distribute targets across multiple sites to protect against site-level failures.
</Card>
#### Geographic Distribution
Distribute targets across multiple sites to protect against site-level failures.
```
Resource: api-service

7
manage/integration-api.mdx
View File

@@ -1,13 +1,16 @@
---
title: "Integration API"
icon: "cube"
description: "Learn how to use Pangolin's REST API to automate and script operations with fine-grained permissions"
---
<Warning>
Pangolin is in heavy development. The REST API routes and behavior may include braking changes between updates. We will do our best to document large changes.
</Warning>
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 Community Edition, the integration API must be enabled. Check out [the documentation](/self-host/advanced/integration-api) for how to enable the integration API.
</Info>
## Authentication

2
manage/remote-node/quick-install-remote.mdx
View File

@@ -39,7 +39,7 @@ Before installing Pangolin, ensure you've opened the required port on your firew
Connect to your server via SSH and download the installer:
```bash
curl -fsSL https://pangolin.net/get-node-installer.sh | bash
curl -fsSL https://static.pangolin.net/get-node-installer.sh | bash
```
The installer supports both AMD64 (x86_64) and ARM64 architectures.

79
manage/resources/client-resources.mdx
View File

@@ -1,79 +0,0 @@
---
title: "Client Resources"
description: "Configure resources for Olm clients to access on a Newt site"
---
## Overview
Site resources in Pangolin allow you to define specific ports and a destination that can be accessed through the VPN tunnel when using [Olm clients](/manage/clients/add-client). This is useful for exposing internal services to your remote clients securely.
<Note>
Site resources are only for exposing services on a Newt site to Olm clients running remotely and do not get proxied.
</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
## Configuring Site Resources
To configure site resources:
<Steps>
<Step title="Navigate to Resources">
Navigate to the **Resources** section in the Pangolin dashboard.
</Step>
<Step title="Select Site Resources">
In the toggle at the top of the table, select "Site Resources".
</Step>
<Step title="Add Resource">
Click **Add Resource**.
</Step>
<Step title="Choose Resource Type">
Choose the resource type (TCP or UDP).
</Step>
<Step title="Configure Port and Target">
Specify the local port and the target address.
</Step>
</Steps>
## Accessing Site Resources
Once configured, you can access these resources from your remote clients using the Olm tunnel.
### 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 client resource and set the port to `2022` (or any available port).
<Frame>
<img src="/images/client_resource.png" width="400" centered/>
</Frame>
</Step>
<Step title="Connect and access">
When connected with a Olm client, you can SSH to your server using `<site-address>:2022`.
```bash
ssh user@100.90.128.0 -p 2022
```
<Note>
When accessing a site resource, you use the IP of the site found in the dashboard and the local port you configured for the resource.
</Note>
</Step>
</Steps>
<Note>
This approach is ideal for secure remote access without exposing SSH directly to the internet.
</Note>

24
manage/resources/private/alias.mdx Normal file
View File

@@ -0,0 +1,24 @@
---
title: "Aliases"
description: "Set a friendly alias hostname that resolves to a host"
---
Aliases provide a secondary, user-friendly address for any of your Resources, allowing users to access the Resource using this alternate name in addition to the original address.
For instance, a router with the address `10.0.0.1` could be assigned the alias `router.internal`, and users could connect using either. Aliases are accessible to anyone who has access to the Resource, and they are exclusively accessible when connected with a Pangolin client, meaning they function without requiring any external DNS record setup. Furthermore, aliases are protocol agnostic, which means they will work with any network protocol, essentially acting as a pseudo-A record for an address that is only functional within the Pangolin environment.
## CIDRs Vs. IPs
A alias can only be created for a Resource that is a single host (IP or FQDN). Aliases cannot be created for Resources that are CIDR ranges because it would be ambiguous which host within the range the alias should point to.
## Domain Structure
Since aliases cannot be single-label domains, you must avoid using domain names that do not contain a dot (e.g., `pangolin`). A domain like `pangolin.net`, which includes a dot, is acceptable. Instead of a single-label domain, you should consider using a subdomain of a domain you control, such as `router.mywebsite.com`, or an existing private/internal domain name, like `router.internal` or `router.corp`.
## Custom Upstream DNS
Aliases work by overriding the DNS of your computer running the client so that all DNS requests are sent to the Pangolin client for resolution. The dns server on your computer is typically `100.96.128.1` which will forward request to an upstream server. By default, we use `9.9.9.9`, but this upstream address can be configured using [the flag](/manage/clients/configure-client) in the CLI / Olm or in the client settings.
## Disable Aliases
If you wish to disable this behavior and prevent aliases from being resolved and leave your DNS alone, you can do so by adding [the flag](/manage/clients/configure-client) to the CLI / Olm or disable override dns in the client settings.

18
manage/resources/private/authentication.mdx Normal file
View File

@@ -0,0 +1,18 @@
---
title: "Authentication"
description: "Only allow access to Resources to specific users, roles, and machines"
---
When a client connects into an organization they will **NOT** have access to any Resources by default. Access must be explicitly granted to users, roles, or machines for a WireGuard tunnel to be established to the site hosting the Resource. The Client will show no peers unless access is granted.
Access can be granted in several ways:
* **Roles:** Assign access to Resources to specific roles. Any user or machine with that role will gain access to the Resource when they connect.
* **Users:** Assign access to Resources to specific users. Only those users will gain access to the Resource when they connect.
* **Machines:** Assign access to Resources to specific machines. Only those machines will gain access to the Resource when they connect. Note that machines can not be put into roles.
When removing access to a resource, the client will automatically tear down the WireGuard tunnel to that Resource if there are no other Resources accessible on that site.
<Frame>
<img src="/images/private_access_controls.png" centered/>
</Frame>

27
manage/resources/private/destinations.mdx Normal file
View File

@@ -0,0 +1,27 @@
---
title: "Destinations"
description: "Understand connection options to the remote network"
---
A Resource's **destination** can be defined in several ways:
* **Fully Qualified Domain Name (FQDN):** For example, `host.autoco.internal`.
* **IP Address:** For example, `10.1.0.35`.
* **IP CIDR Range:** For example, `10.1.0.0/16`.
When defining a Resource with an FQDN, the Pangolin site will resolve the FQDN to an IP address on the remote network. This allows you to create Resources that point to hosts whose IP addresses may change over time, as long as the FQDN remains consistent.
When defining a Resource with an IP address, the Pangolin client will connect directly to that specific IP address on the remote network. It will insert routes for that single IP address into the network route table of the host when users connect with the client.
When defining a Resource with a CIDR range, all IP addresses within that range will be accessible to users who have been granted access to the Resource. This is useful for providing access to entire subnets or network segments. It will insert routes for that single IP address into the network route table of the host when users connect with the client.
### Additional Notes on Resource Destinations
* **Reserved IP Addresses:** The Pangolin client reserves the CGNAT subnet 100.96.128.0/24. Accessing resources via an IP address within this reserved range will be blocked by the client, though its use is uncommon. This range can be configured for newly created orgs in the self-hosted Pangolin configuration file.
* **Resource Destination Resolution:** The configured address of the Resource is resolved by the site the resource points to. Make sure the site can resolve the address correctly.
### What about overlaps?
Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to. This is because we want connection requests to any Resource to be as simple as possible for the end users: when they connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs to figure this out.
It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly defined which host should be used for a given FQDN or IP address and use the alias to connect.

36
manage/resources/public/authentication.mdx Normal file
View File

@@ -0,0 +1,36 @@
---
title: "Authentication"
description: "Create identity and context aware rules to allow access"
---
Though public resources are public and accessible to via a web browser, admins can create rules to enable a layer of authenticated protection in front of public resources. By default, all public resources have Pangolin auth (Platform SSO) enabled, but a number of other authentication methods are available.
When an unauthenticated user visits a resource in their web browser, they will be redirected to a Pangolin-controlled authentication page where they must complete authentication.
## User Login
- **Pangolin (Platform) SSO** - Users must log in with a valid Pangolin account before they can log in.
- **External Identity Provider** - Enable log in to resoruces via your organization's identity provider of choice (Google, Azure, Okta, etc).
- **Users and Roles** - Assign specific users accesss to resources. Group users by roles and assign entire roles access to resources.
## PIN and Passcode
Add simple PIN or passcode authentication to resources. Similarly to user login, users will need to first enter a PIN or passcode before they can gain access to the resource.
## Shareable Links and Access Tokens
Generate temporary self-destructing links that provide authenticated access to resources. Set specific expiration times for when all users who used the link will lose access and when the link becomes invalid. Links can optionally grant more permanent access with no expiration. Delete links when you want to revoke access.
You can also pass access tokens via query params or headers to resources to enable programmatic access.
## Email-based One Time Passcode (OTP)
First whitelist specific emails or wildcards, like `*@.example.com`. When users visit the resource, they will be prompted to enter an email. If the email they enter is on the whitelist, a temporary one time passcode will be sent to their email. Users can then enter this OTP to gain access to the resource.
## Rules to Access or Deny
Define ranked rules to either block or allow access from specific IPs, geolocation, URL paths, and more.
## More
Read about more authentication options and specific settings in [Access Control](/manage/access-control/) and [Identity Providers](/manage/identity-providers/).

3
manage/resources/tcp-udp-resources.mdx → manage/resources/public/raw-resources.mdx
View File

@@ -1,5 +1,5 @@
---
title: "Raw TCP & UDP"
title: "TCP & UDP"
description: "Configure raw TCP and UDP traffic through Pangolin tunnels"
---
@@ -15,6 +15,7 @@ In Pangolin Community Edition, ensure you have the flag enabled in the config fi
flags:
allow_raw_resources: true
```
You 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.
## Proxied Resources

100
manage/resources/targets.mdx → manage/resources/public/targets.mdx
View File

@@ -3,14 +3,8 @@ title: "Targets"
description: "Configure destination endpoints for resource routing and load balancing"
---
## Overview
When you create a resource in Pangolin, you define different targets that specify where traffic should be routed within your network. Each target represents a specific destination that the resource can proxy to when handling incoming requests.
<Note>
Targets are created on the Newt tunnel, enabling traffic to reach destinations on the remote network without requiring additional routing configuration.
</Note>
## How Targets Work
### Target Routing
@@ -22,9 +16,9 @@ Targets function as destination endpoints for your resources:
3. **Network Access**: Newt proxy routes traffic to the local network through the tunnel
4. **Direct Connection**: No additional routing is necessary on the remote network
## Multi-Site Targets (v1.9.0+)
## Multi-Site Targets
With the introduction of update 1.9.0, targets now have sites associated with them. This enhancement provides significant benefits for reliability and load distribution.
Targets have sites associated with them. This provides significant benefits for reliability and load distribution described below.
### Site-Distributed Resources
@@ -38,11 +32,15 @@ You can now configure targets across different sites for the same resource:
Set up load balancing across sites to distribute traffic in a round-robin fashion between all available targets.
</Card>
### Load Balancing Requirements
### Distributing Sites Load Across Servers
<Warning>
Load balancing between different targets only works when sites are connected to the same node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node.
</Warning>
<Note>
This is an Enterprise Edition only feature.
</Note>
This refers to having more than on Pangolin server node that a site can connect to. If one of the server nodes goes down, the site moves to another node. This has some implications for site-based load balancing, because DNS must can only route a FQDN to one Pangolin server node at a time.
Load balancing between different targets only works when sites are connected to the same Pangolin node. In Pangolin instances with multiple remote nodes, ensure load balancing occurs on the same node.
To ensure effective load balancing in multi-node environments:
@@ -50,10 +48,6 @@ To ensure effective load balancing in multi-node environments:
newt --prefer-endpoint <specific-endpoint> <other-args>
```
<Note>
Pangolin currently does not load balance between nodes, only between targets on the same node.
</Note>
## Path-Based Routing
Path-based routing allows you to direct traffic to different targets based on the request path. This enables sophisticated routing scenarios where different services can handle different parts of your application.
@@ -71,23 +65,23 @@ When a request comes in, Pangolin evaluates the path against all targets and rou
Pangolin supports three different matching strategies:
<Card title="Exact Match">
**exact**: The request path must match the configured path exactly.
#### Exact Match
Example: Path `/api/users` with exact match only matches `/api/users`
</Card>
**exact**: The request path must match the configured path exactly.
<Card title="Prefix Match">
**prefix**: The request path must start with the configured path.
Example: Path `/api/users` with exact match only matches `/api/users`
Example: Path `/api` with prefix match matches `/api/users`, `/api/orders`, `/api/users/123`, etc.
</Card>
#### Prefix Match
<Card title="Regex Match">
**regex**: The request path is matched against a regular expression pattern.
**prefix**: The request path must start with the configured path.
Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` but not `/api/users/abc`
</Card>
Example: Path `/api` with prefix match matches `/api/users`, `/api/orders`, `/api/users/123`, etc.
#### Regex Match
**regex**: The request path is matched against a regular expression pattern.
Example: Path `^/api/users/[0-9]+$` with regex match matches `/api/users/123` but not `/api/users/abc`
<Frame caption="Pangolin UI showing targets with path-based routing configuration">
<img src="/images/targets_config_path_match.png" alt="Targets example"/>
@@ -127,41 +121,41 @@ The rewriting happens after the path match evaluation but before the request rea
Pangolin supports four different rewriting strategies:
<Card title="Prefix Rewrite">
**prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path.
#### Prefix Rewrite
- With Prefix Match: `/api` → `/v2/api` transforms `/api/users` into `/v2/api/users`
- With Exact Match: `/old` → `/new` transforms `/old` into `/new`
- With Regex Match: Uses the regex pattern with the rewrite value as replacement
</Card>
**prefix**: Replaces the matched portion with a new prefix, preserving the rest of the path.
<Card title="Exact Rewrite">
**exact**: Replaces the matched path with the exact rewrite path.
- With Prefix Match: `/api` → `/v2/api` transforms `/api/users` into `/v2/api/users`
- With Exact Match: `/old` → `/new` transforms `/old` into `/new`
- With Regex Match: Uses the regex pattern with the rewrite value as replacement
Example: Match path `/api/users` → Rewrite to `/users` transforms `/api/users` into `/users`
</Card>
#### Exact Rewrite
<Card title="Regex Rewrite">
**regex**: Uses regular expression substitution to transform the path. Works with any match type.
**exact**: Replaces the matched path with the exact rewrite path.
- With Regex Match: Uses the regex pattern directly
- With Prefix Match: Automatically captures everything after the prefix with `(.*)`
- With Exact Match: Matches the exact path
Example: Match path `/api/users` → Rewrite to `/users` transforms `/api/users` into `/users`
Example: Match path `^/api/v1/(.*)` (regex) → Rewrite to `/api/v2/$1` transforms `/api/v1/users` into `/api/v2/users`
</Card>
#### Regex Rewrite
<Card title="Strip Prefix">
**stripPrefix**: Removes the matched prefix from the path.
**regex**: Uses regular expression substitution to transform the path. Works with any match type.
- With Prefix Match: Efficiently strips the prefix using Traefik's stripPrefix middleware
- With Exact/Regex Match: Uses regex replacement to remove the matched portion
- Optionally add a new prefix after stripping by providing a rewrite value
- With Regex Match: Uses the regex pattern directly
- With Prefix Match: Automatically captures everything after the prefix with `(.*)`
- With Exact Match: Matches the exact path
Example: Match path `/api` (prefix) → Strip Prefix transforms `/api/users` into `/users`
Example: Match path `^/api/v1/(.*)` (regex) → Rewrite to `/api/v2/$1` transforms `/api/v1/users` into `/api/v2/users`
Example with new prefix: Match path `/old` (prefix) → Strip Prefix + Rewrite to `/new` transforms `/old/users` into `/new/users`
</Card>
#### Strip Prefix
**stripPrefix**: Removes the matched prefix from the path.
- With Prefix Match: Efficiently strips the prefix using Traefik's stripPrefix middleware
- With Exact/Regex Match: Uses regex replacement to remove the matched portion
- Optionally add a new prefix after stripping by providing a rewrite value
Example: Match path `/api` (prefix) → Strip Prefix transforms `/api/users` into `/users`
Example with new prefix: Match path `/old` (prefix) → Strip Prefix + Rewrite to `/new` transforms `/old/users` into `/new/users`
<Frame caption="Pangolin UI showing path rewriting configuration">
<img src="/images/targets_config_path_rewrite.png" alt="Targets with path rewriting"/>

52
manage/resources/understanding-resources.mdx Normal file
View File

@@ -0,0 +1,52 @@
---
title: "Understanding Resources"
description: "Resources are any network address you want to make available to users"
---
Resources respresent the applications, hosts, or ranges you make available for remote access to users. Resources exist on the remote networks of your sites. Users only ever think about connecting to resources and not specific sites.
By default, no resources are made available on sites. Admins must define resources with backend targets, and assign specific access policies before any users can gain access.
## Resources Types
There are two types of resources: public resources and private resources.
<CardGroup cols={2}>
<Card title="Public Resources">
- Reverse proxies to backend services
- Optionally have authentication
- Anyone with web browser can access
</Card>
<Card title="Private Resources">
- Zero-trust VPN
- Access to every resources requires authentication
- Users and machines access when connected with a client
</Card>
</CardGroup>
### Public Resources
Public resources are protocol-aware and TCP/UDP proxies to services that are made available to the public internet.
#### HTTPS Resources
Examples of HTTP resources include, APIs, websites, and dashboards. These are served with a fully qualified domain name and HTTPS with a valid SSL certificate.
All requests go through an authenticated reverse proxy. **Thus, public resources do not require client-side software to be installed on user devices for access. Anyone with a web browser can access public resources.**
HTTP resources are also identity and context aware, meaning you can create policies and rules to only let certain users, roles, countries, IPs, CIDRs, etc have access. When users visit an authenticated public resource, they are greeted with a Pangolin login page where they must complete authentication in order to get to the underlying resource. Therefore, Pangolin acts as a frontdoor barrier to these resources.
#### Raw TCP/UDP Resources
Raw resources are a way to proxy any TCP and UDP traffic through the Pangolin reverse proxy. Instead of a fully qualified domain name and certificate, these resources are bound to one or more ports on the Pangolin host.
Since these resources are not protocol aware and are publicly proxied, they do not support identity and context policies and rules.
### Private Resources
Private resources require users to be connected with Pangolin client in order for them to be accessed. Any TCP and UDP traffic can be made available.
**Private resources function like a zero-trust virtual private network (VPN).** Explicit access to resources must be granted for users and roles to be able to access them. For this reason, we recommend using private resources for all raw TCP/UDP traffic that doesn't need a public proxy, instead of relying on raw TCP/UDP public resources (as discussed above).
Private resources support single hosts or entire network ranges (CIDR). Private resources can also have internal DNS alias hostnames assigned for easy, human-readable naming. Users don't choose to connect to specific resources; rather, when they connect via a client to your organization, they can access all resources their account has access to at once.

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

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

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

@@ -1,30 +1,9 @@
---
title: "Configure Site"
title: "Configure Sites"
description: "Configure Newt for connecting to Pangolin sites"
---
Newt is a fully user space [WireGuard](https://www.wireguard.com/) tunnel client and TCP/UDP proxy, designed to securely expose private resources controlled by Pangolin. By using Newt, you don't need to manage complex WireGuard tunnels and NATing.
## Preview
<Frame caption="Newt interface preview">
<img src="/images/newt-preview.png" alt="Newt Preview"/>
</Frame>
## How Newt Works
### Registers with Pangolin
Using the Newt ID and a secret, the client will make HTTP requests to Pangolin to receive a session token. Using that token, it will connect to a websocket and maintain that connection. Control messages will be sent over the websocket.
### Receives WireGuard Control Messages
When Newt receives WireGuard control messages, it will use the information encoded (endpoint, public key) to bring up a WireGuard tunnel using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go) fully in user space. It will ping over the tunnel to ensure the peer on the Gerbil side is brought up.
### Receives Proxy Control Messages
When Newt receives proxy control messages, it will use the information encoded to create a local low level TCP and UDP proxies attached to the virtual tunnel in order to relay traffic to programmed targets.
## Configuration Arguments
## Flags
<ResponseField name="id" type="string" required>
Newt ID generated by Pangolin to identify the client.
@@ -48,6 +27,12 @@ When Newt receives proxy control messages, it will use the information encoded t
**Example**: `https://pangolin.example.com`
</ResponseField>
<ResponseField name="port" type="integer">
Port for the peers to connect to Newt on. This can be used to keep a static port open in firewalls instead of default random ports.
**Example**: `34534`
</ResponseField>
<ResponseField name="mtu" type="integer">
MTU for the internal WireGuard interface.
@@ -57,7 +42,7 @@ When Newt receives proxy control messages, it will use the information encoded t
<ResponseField name="dns" type="string">
DNS server to use for resolving the endpoint.
**Default**: `8.8.8.8`
**Default**: `9.9.9.9`
</ResponseField>
<ResponseField name="log-level" type="string">
@@ -104,46 +89,110 @@ When Newt receives proxy control messages, it will use the information encoded t
**Example**: `/path/to/updown.sh`
</ResponseField>
<ResponseField name="tls-client-cert" type="string">
Client certificate (p12 or pfx) for mutual TLS (mTLS) authentication.
<ResponseField name="blueprint-file" type="string">
Path to blueprint file to define Pangolin resources and configurations.
**Example**: `/path/to/client.p12`
**Example**: `/path/to/blueprint.yaml`
</ResponseField>
<ResponseField name="accept-clients" type="boolean">
Enable WireGuard server mode to accept incoming Olm client connections.
<ResponseField name="no-cloud" type="boolean">
Don't fail over to the cloud when using managed nodes in Pangolin Cloud.
**Default**: `false`
</ResponseField>
<ResponseField name="generateAndSaveKeyTo" type="string">
Path to save generated private key (used with accept-clients).
<ResponseField name="disable-clients" type="boolean">
Disable clients on the WireGuard interface.
**Example**: `/var/key`
**Default**: `false` (clients enabled)
</ResponseField>
<ResponseField name="native" type="boolean">
Use native WireGuard interface when accepting clients (requires WireGuard kernel module and Linux, must run as root).
Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root).
**Default**: `false` (uses userspace netstack)
</ResponseField>
<ResponseField name="interface" type="string">
Name of the WireGuard interface (used with native mode).
Name of the WireGuard interface.
**Default**: `newt`
</ResponseField>
<ResponseField name="keep-interface" type="boolean">
Keep the WireGuard interface after shutdown (used with native mode).
<ResponseField name="metrics" type="boolean">
Enable Prometheus /metrics exporter.
**Default**: `true`
</ResponseField>
<ResponseField name="otlp" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT.
**Default**: `false`
</ResponseField>
<ResponseField name="metrics-admin-addr" type="string">
Admin/metrics bind address.
**Default**: `127.0.0.1:2112`
</ResponseField>
<ResponseField name="metrics-async-bytes" type="boolean">
Enable async bytes counting (background flush; lower hot path overhead).
**Default**: `false`
</ResponseField>
<ResponseField name="region" type="string">
Optional region resource attribute for telemetry and metrics.
**Example**: `us-west-2`
</ResponseField>
<ResponseField name="enforce-hc-cert" type="boolean">
Enforce certificate validation for health checks.
**Default**: `false` (accepts any cert)
</ResponseField>
<ResponseField name="tls-client-cert-file" type="string">
Path to client certificate file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.crt`
</ResponseField>
<ResponseField name="tls-client-key" type="string">
Path to client private key file (PEM/DER format) for mTLS.
**Example**: `/path/to/client.key`
</ResponseField>
<ResponseField name="tls-client-ca" type="string">
Path to CA certificate file for validating remote certificates (can be specified multiple times).
**Example**: `/path/to/ca.crt`
</ResponseField>
<ResponseField name="tls-client-cert" type="string">
Path to client certificate (PKCS12 format) - DEPRECATED: use `--tls-client-cert-file` and `--tls-client-key` instead.
**Example**: `/path/to/client.p12`
</ResponseField>
<ResponseField name="prefer-endpoint" type="string">
Prefer this endpoint for the connection (if set, will override the endpoint from the server).
**Example**: `https://preferred.endpoint.com`
</ResponseField>
## Environment Variables
All CLI arguments can be set using environment variables as an alternative to command line flags. Environment variables are particularly useful when running Newt in containerized environments.
<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>
<ResponseField name="PANGOLIN_ENDPOINT" type="string">
Endpoint of your Pangolin server (equivalent to `--endpoint`)
</ResponseField>
@@ -156,6 +205,10 @@ All CLI arguments can be set using environment variables as an alternative to co
Newt secret for authentication (equivalent to `--secret`)
</ResponseField>
<ResponseField name="PORT" type="integer">
Port for the peers to connect to Newt on (equivalent to `--port`)
</ResponseField>
<ResponseField name="MTU" type="integer">
MTU for the internal WireGuard interface (equivalent to `--mtu`)
@@ -165,7 +218,21 @@ All CLI arguments can be set using environment variables as an alternative to co
<ResponseField name="DNS" type="string">
DNS server to use for resolving the endpoint (equivalent to `--dns`)
**Default**: `8.8.8.8`
**Default**: `9.9.9.9`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Load the config JSON from this file instead of in the home folder.
</ResponseField>
<ResponseField name="BLUEPRINT_FILE" type="string">
Path to blueprint file to define Pangolin resources and configurations (equivalent to `--blueprint-file`).
</ResponseField>
<ResponseField name="NO_CLOUD" type="boolean">
Don't fail over to the cloud when using managed nodes in Pangolin Cloud (equivalent to `--no-cloud`).
**Default**: `false`
</ResponseField>
<ResponseField name="LOG_LEVEL" type="string">
@@ -194,10 +261,6 @@ All CLI arguments can be set using environment variables as an alternative to co
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`)
@@ -208,16 +271,12 @@ All CLI arguments can be set using environment variables as an alternative to co
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`)
<ResponseField name="DISABLE_CLIENTS" type="boolean">
Disable clients on the WireGuard interface (equivalent to `--disable-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`)
@@ -230,151 +289,126 @@ All CLI arguments can be set using environment variables as an alternative to co
**Default**: `newt`
</ResponseField>
<ResponseField name="KEEP_INTERFACE" type="boolean">
Keep the WireGuard interface after shutdown (equivalent to `--keep-interface`)
<ResponseField name="NEWT_METRICS_PROMETHEUS_ENABLED" type="boolean">
Enable Prometheus /metrics exporter (equivalent to `--metrics`).
**Default**: `true`
</ResponseField>
<ResponseField name="NEWT_METRICS_OTLP_ENABLED" type="boolean">
Enable OTLP exporters (metrics/traces) to OTEL_EXPORTER_OTLP_ENDPOINT (equivalent to `--otlp`).
**Default**: `false`
</ResponseField>
<ResponseField name="CONFIG_FILE" type="string">
Load the config JSON from this file instead of in the home folder.
<ResponseField name="NEWT_ADMIN_ADDR" type="string">
Admin/metrics bind address (equivalent to `--metrics-admin-addr`).
**Default**: `127.0.0.1:2112`
</ResponseField>
<Note>
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
</Note>
<ResponseField name="NEWT_METRICS_ASYNC_BYTES" type="boolean">
Enable async bytes counting (background flush; lower hot path overhead, equivalent to `--metrics-async-bytes`).
## Basic Configuration Examples
**Default**: `false`
</ResponseField>
### Binary Example
<ResponseField name="NEWT_REGION" type="string">
Optional region resource attribute for telemetry and metrics (equivalent to `--region`).
</ResponseField>
```bash
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
<ResponseField name="ENFORCE_HC_CERT" type="boolean">
Enforce certificate validation for health checks (equivalent to `--enforce-hc-cert`).
**Default**: `false`
</ResponseField>
<ResponseField name="TLS_CLIENT_CERT" type="string">
Path to client certificate file (PEM/DER format) for mTLS (equivalent to `--tls-client-cert-file`)
</ResponseField>
<ResponseField name="TLS_CLIENT_KEY" type="string">
Path to client private key file (PEM/DER format) for mTLS (equivalent to `--tls-client-key`)
</ResponseField>
<ResponseField name="TLS_CLIENT_CAS" type="string">
Comma-separated list of CA certificate file paths for validating remote certificates (equivalent to multiple `--tls-client-ca` flags)
</ResponseField>
<ResponseField name="TLS_CLIENT_CERT_PKCS12" type="string">
Path to client certificate (PKCS12 format) - DEPRECATED: use `TLS_CLIENT_CERT` and `TLS_CLIENT_KEY` instead
</ResponseField>
## Loading secrets from files
You can use `CONFIG_FILE` to define a location of a config file to store the credentials between runs.
```
$ cat ~/.config/newt-client/config.json
{
"id": "spmzu8rbpzj1qq6",
"secret": "f6v61mjutwme2kkydbw3fjo227zl60a2tsf5psw9r25hgae3",
"endpoint": "https://app.pangolin.net",
"tlsClientCert": ""
}
```
### Docker Compose with Environment Variables (Recommended)
This file is also written to when newt first starts up. So you do not need to run every time with --id and secret if you have run it once!
```yaml title="docker-compose.yml"
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- NEWT_ID=2ix2t8xk22ubpfy
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
- HEALTH_FILE=/tmp/healthy
```
Default locations:
### Docker Compose with CLI Arguments
- **macOS**: `~/Library/Application Support/newt-client/config.json`
- **Windows**: `%PROGRAMDATA%\newt\newt-client\config.json`
- **Linux/Others**: `~/.config/newt-client/config.json`
```yaml title="docker-compose.yml"
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://app.pangolin.net
- --health-file /tmp/healthy
```
## Advanced Features
### Accept Client Connections
When the `--accept-clients` flag is enabled (or `ACCEPT_CLIENTS=true` environment variable is set), Newt operates as a WireGuard server that can accept incoming client connections from other devices. This enables peer-to-peer connectivity through the Newt instance.
#### Client Tunneling Modes
Newt supports two WireGuard tunneling modes:
##### Userspace Mode (Default)
By default, Newt uses a fully userspace WireGuard implementation using [netstack](https://github.com/WireGuard/wireguard-go/blob/master/tun/netstack/examples/http_server.go). This mode:
- **Does not require root privileges**
- **Works on all supported platforms** (Linux, Windows, macOS)
- **Does not require WireGuard kernel module** to be installed
- **Runs entirely in userspace** - no system network interface is created
- **Is containerization-friendly** - works seamlessly in Docker containers
<Note>
This is the recommended mode for most deployments, especially containerized environments.
</Note>
##### Native Mode (Linux only)
When using the `--native` flag or setting `USE_NATIVE_INTERFACE=true`, Newt uses the native WireGuard kernel module. This mode:
- **Requires root privileges** to create and manage network interfaces
- **Only works on Linux** with the WireGuard kernel module installed
- **Creates a real network interface** (e.g., `newt0`) on the system
- **May offer better performance** for high-throughput scenarios
- **Requires proper network permissions** and may conflict with existing network configurations
<Warning>
Native mode requires Linux with WireGuard kernel module and must run as root.
</Warning>
#### Native Mode Requirements
To use native mode:
1. Run on a Linux system
2. Install the WireGuard kernel module
3. Run Newt as root (`sudo`)
4. Ensure the system allows creation of network interfaces
**Docker Compose example:**
```yaml title="docker-compose.yml"
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- NEWT_ID=2ix2t8xk22ubpfy
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
- ACCEPT_CLIENTS=true
```
### Docker Socket Integration
## 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.
You can specify the Docker socket path using the `--docker-socket` CLI argument or by setting the `DOCKER_SOCKET` environment variable. If the Docker socket is not available or accessible, Newt will gracefully disable Docker integration and continue normal operation.
```yaml title="docker-compose.yml"
Supported values include:
- Local UNIX socket (default):
>You must mount the socket file into the container using a volume, so Newt can access it.
`unix:///var/run/docker.sock`
- TCP socket (e.g., via Docker Socket Proxy):
`tcp://localhost:2375`
- HTTP/HTTPS endpoints (e.g., remote Docker APIs):
`http://your-host:2375`
- SSH connections (experimental, requires SSH setup):
`ssh://user@host`
```yaml
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- NEWT_ID=2ix2t8xk22ubpfy
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
- DOCKER_SOCKET=/var/run/docker.sock
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=unix:///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
**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:
@@ -383,19 +417,17 @@ When the Docker Socket Integration is used, depending on the network which Newt
- **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
**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.
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.
<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
## Updown Scripts
You can pass in an updown script for Newt to call when it is adding or removing a target:
@@ -418,19 +450,24 @@ Returning a string from the script in the format of a target (`ip:dst` so `10.0.
You can look at `updown.py` as a reference script to get started!
</Note>
### mTLS Authentication
## mTLS Authentication
Newt supports mutual TLS (mTLS) authentication if the server has been configured to request a client certificate.
Newt supports mutual TLS (mTLS) authentication if the server is configured to request a client certificate. You can use either a PKCS12 (.p12/.pfx) file or split PEM files for the client cert, private key, and CA.
### Option 1: PKCS12 (Legacy)
<Note>
This is the original method and still supported.
</Note>
**Requirements:**
- Only PKCS12 (.p12 or .pfx) file format is accepted
- The PKCS12 file must contain:
- Private key
- File must contain:
- Client private key
- Public certificate
- CA certificate
- Encrypted PKCS12 files are currently not supported
- Encrypted `.p12` files are **not supported**
**Binary Example:**
**Example:**
```bash
newt \
@@ -440,21 +477,30 @@ newt \
--tls-client-cert ./client.p12
```
**Docker Compose Example:**
### Option 2: Split PEM Files (Preferred)
```yaml title="docker-compose.yml"
services:
newt:
image: fosrl/newt
container_name: newt
restart: unless-stopped
environment:
- PANGOLIN_ENDPOINT=https://app.pangolin.net
- NEWT_ID=2ix2t8xk22ubpfy
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
- TLS_CLIENT_CERT=./client.p12
You can now provide separate files for:
- `--tls-client-cert-file`: client certificate (`.crt` or `.pem`)
- `--tls-client-key`: client private key (`.key` or `.pem`)
- `--tls-client-ca`: CA cert to verify the server (can be specified multiple times)
**Example:**
```bash
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com \
--tls-client-cert-file ./client.crt \
--tls-client-key ./client.key \
--tls-client-ca ./ca.crt
```
<Note>
Get your `id` and `secret` from the Pangolin dashboard when creating a Newt client.
</Note>
## NAT Traversal Tweaks
Newt supports NAT traversal to allow clients to connect directly to Newt sites without relaying through the Pangolin server, improving performance and reducing latency.
In some environment depending on the NAT type and firewall, you may need to tweak some settings to get optimal connectivity in the firewall itself. Take a look at [these docs](https://tailscale.com/kb/1361/firewall) for some firewall changes you might be able to make.
Another option is to keep newt listening for client connections on a static port. This allows you to open a specific port in your firewall for Newt client connections instead of random high ports. You can do this by setting the `--port` flag or `PORT` environment variable and then opening this port in the your firewall to DNAT to Newt.

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

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

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

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

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

@@ -1,29 +1,9 @@
---
title: "Install Site"
title: "Install Sites"
description: "Install Newt as a binary or Docker container"
---
Newt can be installed as either a static binary executable or a Docker container. Configuration is passed via CLI arguments in both cases.
<Warning>
You **must first create a site and copy the Newt config** in Pangolin before running Newt.
</Warning>
<CardGroup cols={2}>
<Card title="Binary Installation" icon="download">
- Static executable
- Cross-platform support
- Easy to install and run
- Systemd service support
</Card>
<Card title="Docker Installation" icon="docker">
- Containerized deployment
- Environment variables
- Docker Compose support
- Easy management
</Card>
</CardGroup>
Newt can be installed as either a static binary executable or a Docker container. You must first create a site and copy the Newt config in Pangolin before running Newt.
## Binary Installation
@@ -32,12 +12,16 @@ You **must first create a site and copy the Newt config** in Pangolin before run
Use this command to automatically install Newt. It detects your system architecture automatically and always pulls the latest version, adding Newt to your PATH:
```bash
curl -fsSL https://pangolin.net/get-newt.sh | bash
curl -fsSL https://static.pangolin.net/get-newt.sh | bash
```
#### Windows
If you would like to use Newt on Windows as a service or with clients, wintun.dll is sometimes required. Please use latest installer from [GitHub releases](https://github.com/fosrl/newt/releases/latest).
### Manual Download
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases) for ARM and AMD64 (x86_64) architectures.
Binaries for Linux, macOS, and Windows are available in the [GitHub releases](https://github.com/fosrl/newt/releases/latest) for ARM and AMD64 (x86_64) architectures.
Download and install manually:
@@ -57,21 +41,9 @@ Run Newt with the configuration from Pangolin:
newt \
--id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
--endpoint https://app.pangolin.net
```
### Permanent Installation
Install to your PATH (may need to run as root):
```bash
mv ./newt /usr/local/bin
```
<Note>
The quick installer will do this step for you.
</Note>
### Systemd Service
Create a basic systemd service:
@@ -82,7 +54,7 @@ Description=Newt
After=network.target
[Service]
ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
ExecStart=/usr/local/bin/newt --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://app.pangolin.net
Restart=always
User=root
@@ -111,7 +83,7 @@ Run Newt with CLI arguments from Pangolin:
```bash
docker run -it fosrl/newt --id 31frd0uzbjvp721 \
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
--endpoint https://example.com
--endpoint https://app.pangolin.net
```
### Docker Compose
@@ -130,7 +102,7 @@ services:
- NEWT_SECRET=nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2
```
#### Config file injected as Compose Secret
#### Config File Injected as Compose Secret
A safer but slightly more complex way is to use [Compose Secrets](https://docs.docker.com/compose/how-tos/use-secrets/). First, create a `JSON` file containing your configuration:
@@ -138,7 +110,7 @@ A safer but slightly more complex way is to use [Compose Secrets](https://docs.d
{
"id": "2ix2t8xk22ubpfy",
"secret": "nnisrfsdfc7prqsp9ewo1dvtvci50j5uiqotez00dgap0ii2",
"endpoint": "https://example.com",
"endpoint": "https://app.pangolin.net",
"tlsClientCert": ""
}
```
@@ -174,7 +146,7 @@ services:
command:
- --id 31frd0uzbjvp721
- --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6
- --endpoint https://example.com
- --endpoint https://app.pangolin.net
```
Start the service:
@@ -196,3 +168,52 @@ Newt is available in the Unraid Community Applications store. Search for "Newt"
### Portainer and Other UIs
Container management UIs like Portainer typically allow passing commands and environment variables to containers similar to Docker Compose. Look for a commands or arguments configuration section and follow the relevant guides.
### Windows Service
On Windows, newt can to be installed and run as a Windows service to remain persistent.
#### Service Management Commands
```
# Install the service
newt.exe install
# Start the service
newt.exe start
# Stop the service
newt.exe stop
# Check service status
newt.exe status
# Remove the service
newt.exe remove
# Show help
newt.exe service-help
```
Note running the service requires credentials in `%PROGRAMDATA%\newt\newt-client\config.json`.
#### Service Configuration
When running as a service, newt will read configuration from environment variables or you can modify the service to include command-line arguments:
1. Install the service: `newt.exe install`
2. Set the credentials in `%PROGRAMDATA%\newt\newt-client\config.json`. Hint: if you run newt once with --id and --secret this file will be populated!
3. Start the service: `newt.exe start`
#### Service Logs
When running as a service, logs are written to:
- Windows Event Log (Application log, source: "newtWireguardService")
- Log files in: `%PROGRAMDATA%\newt\logs\newt.log`
You can view the Windows Event Log using Event Viewer or PowerShell:
```powershell
Get-EventLog -LogName Application -Source "newtWireguardService" -Newest 10
```

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

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

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

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

10
self-host/advanced/config-file.mdx
View File

@@ -714,16 +714,6 @@ This section contains the complete reference for all configuration options in `c
When enabled, only domains created through the UI are allowed.
</Note>
</ResponseField>
<ResponseField name="enable_clients" type="boolean">
Whether to enable client functionality.
**Default**: `true`
<Note>
Controls access to client-related features and endpoints.
</Note>
</ResponseField>
</Expandable>
</ResponseField>

2
self-host/advanced/enable-geoblocking.mdx
View File

@@ -17,7 +17,7 @@ Have a look at this [Community guide](/self-host/community-guides/geolite2automa
You can use the installer to download and place the database for you, just grab the latest installer:
```bash
curl -fsSL https://pangolin.net/get-installer.sh | bash
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
```
Then run the installer again:

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

@@ -41,7 +41,7 @@ Before installing Pangolin, ensure you've set up DNS for your domain(s) and open
Connect to your server via SSH and download the installer:
```bash
curl -fsSL https://pangolin.net/get-installer.sh | bash
curl -fsSL https://static.pangolin.net/get-installer.sh | bash
```
The installer supports both AMD64 (x86_64) and ARM64 architectures.
@@ -143,8 +143,8 @@ https://pangolin.example.com/auth/initial-setup
<Step title="Create your first organization">
After logging in:
1. Click "Create Organization"
2. Enter organization name and description
1. Enter organization name and description
2. Click "Create Organization"
<Check>
You're now ready to start adding applications and configuring your reverse proxy!