mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-08 05:56:45 +00:00
deploy
This commit is contained in:
miloschwartz
@@ -3,106 +3,72 @@ title: "How Pangolin Works"
|
||||
description: "Learn about Pangolin's architecture and how its components work together to provide secure application access"
|
||||
---
|
||||
|
||||
## System Overview
|
||||
Pangolin provides secure, application-specific ingress to your applications through a global network of points of presence. Users connect to the closest point of presence, which authenticates them and routes their requests through secure tunnels to your applications.
|
||||
|
||||
Pangolin operates through a central server (called the point of presence) that manages connections to your edge networks. Each edge network runs a lightweight client that establishes secure tunnels back to the central server.
|
||||
|
||||
<Frame caption="System architecture showing Pangolin components and their interactions">
|
||||
<img src="/images/system-diagram.svg" alt="Pangolin system architecture diagram"/>
|
||||
<Frame>
|
||||
<img src="/images/diagram.svg" width="400" centered/>
|
||||
</Frame>
|
||||
|
||||
## Core Components
|
||||
|
||||
### Pangolin (Control Plane)
|
||||
|
||||
Pangolin is the main control center that orchestrates the entire system:
|
||||
|
||||
- **Web Interface**: Management dashboard for configuring sites, users, and access policies
|
||||
- **REST API**: External API for automation and integration
|
||||
- **WebSocket Server**: Manages real-time connections to edge network clients
|
||||
- **Authentication System**: Handles user authentication and authorization
|
||||
- **Database**: Stores configuration, user data, and system state
|
||||
|
||||
<Info>
|
||||
Pangolin acts as the brain of the system, coordinating all other components and managing user access.
|
||||
</Info>
|
||||
|
||||
### Gerbil (Tunnel Manager)
|
||||
|
||||
Gerbil manages the secure WireGuard tunnels between your edge networks and the central server:
|
||||
|
||||
- **Peer Management**: Creates and maintains WireGuard connections
|
||||
- **Tunnel Orchestration**: Handles tunnel creation, updates, and cleanup
|
||||
- **Security**: Ensures all traffic is encrypted using WireGuard's cryptographic protocols
|
||||
|
||||
<Check>
|
||||
WireGuard provides fast, secure, and reliable tunneling with minimal overhead.
|
||||
</Check>
|
||||
|
||||
### Newt (Edge Client)
|
||||
|
||||
Newt is a lightweight client that runs on your edge networks (servers, VMs, or containers):
|
||||
|
||||
- **Automatic Discovery**: Finds the optimal point of presence for best performance
|
||||
- **Dual Connection**: Connects to Pangolin via WebSocket and Gerbil via WireGuard
|
||||
- **Resource Proxy**: Creates TCP/UDP proxies to expose your applications securely
|
||||
|
||||
<Tip>
|
||||
Newt is designed to be resource-efficient and can run on minimal hardware or in containers.
|
||||
</Tip>
|
||||
|
||||
### Reverse Proxy (Router)
|
||||
|
||||
The reverse proxy handles incoming requests and routes them to your applications:
|
||||
|
||||
- **Request Routing**: Directs traffic to the correct backend services
|
||||
- **SSL Termination**: Manages HTTPS certificates and encryption
|
||||
- **Middleware Support**: Integrates with security and monitoring plugins
|
||||
|
||||
### Badger (Authentication Middleware)
|
||||
|
||||
Badger is Pangolin's middleware that enforces access control:
|
||||
|
||||
- **Request Interception**: Catches all incoming requests before they reach your applications
|
||||
- **Authentication Check**: Verifies user identity and permissions
|
||||
- **Secure Redirects**: Sends unauthenticated users to Pangolin's login system
|
||||
|
||||
<Warning>
|
||||
Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures.
|
||||
</Warning>
|
||||
|
||||
## How It All Works Together
|
||||
## How It Works
|
||||
|
||||
<Steps>
|
||||
<Step title="User requests access">
|
||||
A user tries to access your application through the public domain.
|
||||
<Step title="User enters through point of presence">
|
||||
DNS automatically routes users to the closest available regional point of presence (PoP). A PoP is always available because the control plane fails over between PoPs.
|
||||
</Step>
|
||||
|
||||
<Step title="Badger intercepts the request">
|
||||
Badger middleware catches the request and checks if the user is authenticated.
|
||||
<Step title="Authentication and authorization">
|
||||
The point of presence 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>
|
||||
|
||||
<Step title="Authentication redirect">
|
||||
If not authenticated, the user is redirected to Pangolin's login system.
|
||||
</Step>
|
||||
|
||||
<Step title="Secure tunnel access">
|
||||
Once authenticated, requests flow through the encrypted WireGuard tunnel managed by Gerbil.
|
||||
<Step 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">
|
||||
The reverse proxy routes the request to your application running behind Newt on the edge network.
|
||||
Your applications receive the requests and respond through the same secure path.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Deployment Models
|
||||
<Info>
|
||||
Points of presence provide global high availability - if one location goes down, traffic automatically routes to the next closest location.
|
||||
</Info>
|
||||
|
||||
## Deployment Options
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Use Cloud for a highly available and access-controllerd ingress service with points of presence all over the world.
|
||||
Global network of points of presence with automatic failover and routing to your backend services.
|
||||
</Card>
|
||||
|
||||
<Card title="Hybrid" icon="circle-nodes" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits yours servers.
|
||||
</Card>
|
||||
|
||||
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
|
||||
All components run on your infrastructure, giving you complete control over security and data.
|
||||
Fully self-hosted, self-contained Pangolin server acting as a single point of presence.
|
||||
</Card>
|
||||
|
||||
<Card title="Learn More" icon="book" href="/manage/points-of-presence">
|
||||
Detailed information about points of presence and high availability options.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Key Benefits
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="No Public IPs or Ports" icon="network-wired">
|
||||
Your applications can run on private networks without exposing ports.
|
||||
</Card>
|
||||
|
||||
<Card title="Ingress Mesh" icon="globe">
|
||||
Users always connect to the closest available point of presence.
|
||||
</Card>
|
||||
|
||||
<Card title="Zero-Trust Security" icon="shield">
|
||||
Every request is authenticated and authorized before reaching your applications.
|
||||
</Card>
|
||||
|
||||
<Card title="High Availability" icon="check-double">
|
||||
Multiple points of presence, failover, and load balancing between tunnels ensures there is always a way for users to access your applications.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -3,73 +3,70 @@ title: "Pangolin vs. Reverse Proxy"
|
||||
description: "Learn how Pangolin's distributed architecture eliminates single points of failure and provides global, authenticated access to your applications"
|
||||
---
|
||||
|
||||
|
||||
Pangolin builds upon traditional reverse proxy principles but adds distributed architecture, tunneling, and identity-aware access control. While traditional reverse proxies are typically single-server solutions, Pangolin operates as a distributed network of points of presence that provide global, highly-available access to your applications.
|
||||
|
||||
## Traditional Reverse Proxy Limitations
|
||||
|
||||
Traditional reverse proxies operate as single-server solutions with inherent 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>
|
||||
|
||||
- **Single Point of Failure**: If the reverse proxy server goes down, all applications become inaccessible
|
||||
- **Geographic Limitations**: Users far from the server location experience higher latency
|
||||
- **Network Dependencies**: Requires public IP addresses and open ports on your network
|
||||
- **Basic Authentication**: Typically relies on network-based trust rather than user identity
|
||||
<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.
|
||||
|
||||
### Global Points of Presence (Ingress Layer)
|
||||
### How It Works
|
||||
|
||||
Pangolin operates a distributed network of points of presence worldwide that serve as entry points for user traffic:
|
||||
<Steps>
|
||||
<Step title="Ingress Routing">
|
||||
Request is routed to the closest available point of presence. If one goes down, there is always another point available.
|
||||
</Step>
|
||||
|
||||
- **Automatic Failover**: If one point of presence becomes unavailable, traffic automatically routes to the next closest location
|
||||
- **Geographic Optimization**: Users always connect to the nearest available point of presence for minimal latency
|
||||
- **Load Distribution**: Traffic is automatically balanced across multiple locations to prevent overload
|
||||
<Step title="Authentication">
|
||||
User identity is verified at the point of presence before getting routed to your backend.
|
||||
</Step>
|
||||
|
||||
### Intelligent Backend Routing (Tunnel Layer)
|
||||
<Step title="Tunnel Selection">
|
||||
Pangolin selects the optimal tunnel route to your backend service.
|
||||
</Step>
|
||||
|
||||
Once traffic reaches a point of presence, Pangolin provides additional high availability for routing to your backend services:
|
||||
<Step title="Failover Handling">
|
||||
If the primary tunnel fails, traffic automatically switches to an alternative route.
|
||||
</Step>
|
||||
|
||||
- **Multiple Tunnel Connections**: Each edge network can maintain connections to multiple points of presence simultaneously
|
||||
- **Automatic Tunnel Failover**: If a tunnel connection fails, traffic automatically switches to an alternative route
|
||||
- **Load Balanced Tunnels**: Multiple tunnel connections can be used simultaneously to distribute load and improve performance
|
||||
- **Health Monitoring**: Pangolin continuously monitors tunnel health and automatically routes around failed connections
|
||||
<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 points of presence or tunnel connections fail.
|
||||
</Info>
|
||||
|
||||
### How Dual-Layer High Availability Works
|
||||
|
||||
When a user requests access to your application:
|
||||
|
||||
1. **Ingress Routing**: Request is routed to the closest available point of presence
|
||||
2. **Authentication**: User identity is verified at the point of presence
|
||||
3. **Tunnel Selection**: Pangolin selects the optimal tunnel route to your backend service
|
||||
4. **Failover Handling**: If the primary tunnel fails, traffic automatically switches to an alternative route
|
||||
5. **Response Delivery**: Response follows the same resilient path back to the user
|
||||
|
||||
<Check>
|
||||
Both ingress points and tunnel connections are automatically managed, providing seamless failover without any manual intervention.
|
||||
</Check>
|
||||
|
||||
## Key Differences
|
||||
|
||||
### Tunneling vs. Direct Network Access
|
||||
|
||||
Traditional reverse proxies require direct network connectivity:
|
||||
|
||||
- **Public IP Required**: Your network needs a public IP address
|
||||
- **Open Ports**: Must expose ports (80, 443) to the internet
|
||||
- **Network Configuration**: Complex firewall and routing setup required
|
||||
|
||||
Pangolin uses secure tunneling:
|
||||
|
||||
- **No Public IP Needed**: Your applications can run on private networks
|
||||
- **No Open Ports**: Edge networks don't need to expose any ports
|
||||
- **Automatic Discovery**: Newt clients automatically find and connect to the optimal point of presence
|
||||
- **Encrypted Traffic**: All communication is encrypted using WireGuard
|
||||
| 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.
|
||||
@@ -77,25 +74,25 @@ This tunneling capability makes Pangolin ideal for environments behind restricti
|
||||
|
||||
### Identity-Aware Proxy (IAP)
|
||||
|
||||
Traditional reverse proxies typically rely on network-based trust, while Pangolin implements zero-trust access control:
|
||||
Traditional reverse proxies rely on network-based trust, while Pangolin implements zero-trust access control:
|
||||
|
||||
#### How Pangolin's IAP Works
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Multi-Factor Authentication" icon="key">
|
||||
Support for 2FA, passkeys, and OTP.
|
||||
</Card>
|
||||
|
||||
1. **Request Interception**: Every request is intercepted by the nearest point of presence
|
||||
2. **Identity Verification**: User identity is verified using OAuth2/OpenID Connect
|
||||
3. **Context Evaluation**: Additional factors like location, device, and time are assessed
|
||||
4. **Access Decision**: Access is granted or denied based on identity and context
|
||||
5. **Secure Delivery**: Authenticated requests are tunneled to your application
|
||||
<Card title="Single Sign-On" icon="users">
|
||||
Integration with Google, Okta, and other identity providers.
|
||||
</Card>
|
||||
|
||||
#### Advanced Access Control Features
|
||||
<Card title="Granular Permissions" icon="shield-check">
|
||||
Role-based access control and path-based rules.
|
||||
</Card>
|
||||
|
||||
Pangolin provides comprehensive access control:
|
||||
|
||||
- **Multi-Factor Authentication**: Support for 2FA, passkeys, and OTP
|
||||
- **Single Sign-On**: Integration with Google, Azure AD, Okta, and other identity providers
|
||||
- **Granular Permissions**: User and role-based access control (RBAC)
|
||||
- **Resource-Specific Security**: PIN codes, passwords, and expiring share links
|
||||
- **Contextual Rules**: IP-based, geographic, and time-based access policies
|
||||
<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.
|
||||
@@ -113,5 +110,5 @@ Unlike traditional reverse proxies, Pangolin authenticates every single request,
|
||||
| **Scalability** | Manual scaling | Automatic global distribution |
|
||||
|
||||
<Card title="Try Pangolin Cloud" icon="rocket" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Experience distributed, authenticated access to your applications with Pangolin's global network of points of presence.
|
||||
Get distributed, authenticated access to your applications with Pangolin's global network of points of presence.
|
||||
</Card>
|
||||
|
||||
@@ -3,39 +3,71 @@ title: "Pangolin vs. VPN"
|
||||
description: "Learn how Pangolin provides application-specific access with zero-trust security compared to traditional VPNs"
|
||||
---
|
||||
|
||||
Pangolin and VPNs both provide secure remote access, but they serve different purposes and offer different levels of security and convenience.
|
||||
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
|
||||
|
||||
Traditional VPNs provide full network access but come with significant drawbacks:
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Over-Permission" icon="key">
|
||||
Users get access to entire networks, not just the applications they need.
|
||||
</Card>
|
||||
|
||||
- **Over-Permission**: Users get access to entire networks, not just the applications they need
|
||||
- **Client Software Required**: Users must install and configure VPN client software
|
||||
- **Network Complexity**: Requires public IP addresses, open ports, and complex network configuration
|
||||
- **Limited Access Control**: Basic network-level security with few granular controls
|
||||
- **Single Point of Failure**: If the VPN server goes down, all access is lost
|
||||
<Card title="Client Software Required" icon="download">
|
||||
Users must install and configure VPN client software.
|
||||
</Card>
|
||||
|
||||
## Pangolin's Application-First Approach
|
||||
<Card title="Network Complexity" icon="network-wired">
|
||||
Requires public IP addresses, open ports, and complex network configuration.
|
||||
</Card>
|
||||
|
||||
Pangolin provides secure, application-specific access without the limitations of traditional VPNs:
|
||||
<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
|
||||
|
||||
- **Application-Specific**: Users access only the applications they're authorized to use
|
||||
- **Browser-Based**: No client software installation required - works with any web browser
|
||||
- **Granular Permissions**: Role-based access control, path-based rules, and contextual policies
|
||||
- **Multi-Factor Authentication**: Support for SSO, OIDC, 2FA, and passkeys
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Application-Specific" icon="window-maximize">
|
||||
Users access only the applications they're authorized to use.
|
||||
</Card>
|
||||
|
||||
### Simplified Infrastructure
|
||||
<Card title="Browser-Based" icon="globe">
|
||||
No client software installation required - works with any web browser.
|
||||
</Card>
|
||||
|
||||
- **No Public IPs**: Edge networks don't need public IP addresses
|
||||
- **No Open Ports**: Eliminates the need to expose ports to the internet
|
||||
- **Automatic Tunneling**: Secure WireGuard tunnels are established automatically
|
||||
- **Distributed Architecture**: Multiple points of presence ensure high availability
|
||||
<Card title="Granular Permissions" icon="shield-check">
|
||||
Role-based access control, path-based rules, and contextual policies.
|
||||
</Card>
|
||||
|
||||
<Info>
|
||||
Pangolin's application-specific approach follows the principle of least privilege - users only get access to what they need, when they need it.
|
||||
</Info>
|
||||
<Card title="Multi-Factor Authentication" icon="key">
|
||||
Support for SSO, OIDC, 2FA, and passkeys.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Simplified Ingess 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/points-of-presence">
|
||||
Multiple points of presence ensure high availability.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Key Differences
|
||||
|
||||
@@ -49,36 +81,8 @@ Pangolin's application-specific approach follows the principle of least privileg
|
||||
| **Infrastructure** | Single server | Distributed points of presence |
|
||||
| **Security Model** | Network-based trust | Identity-based trust |
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Choose Traditional VPN When:
|
||||
- You need full network access for all users
|
||||
- Users are comfortable installing client software
|
||||
- You have simple access control requirements
|
||||
- You can manage public IP addresses and open ports
|
||||
|
||||
### Choose Pangolin When:
|
||||
- You want to expose specific applications securely
|
||||
- You prefer browser-based access without client software
|
||||
- You need granular access control and audit trails
|
||||
- You want to eliminate network infrastructure complexity
|
||||
- You need high availability and global distribution
|
||||
|
||||
<Warning>
|
||||
Traditional VPNs provide broad network access, which can be a security risk if user devices are compromised. Pangolin's application-specific approach minimizes this risk.
|
||||
</Warning>
|
||||
|
||||
## Mesh VPN Comparison
|
||||
|
||||
Mesh VPNs like Tailscale and Netbird provide peer-to-peer connectivity for full network access. While they offer some advantages over traditional VPNs, they still:
|
||||
|
||||
- Require client software installation
|
||||
- Provide full network access rather than application-specific access
|
||||
- Lack the granular access control and audit capabilities of Pangolin
|
||||
- Don't offer the distributed, high-availability architecture
|
||||
|
||||
<Card title="Try Pangolin Cloud" icon="rocket" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Experience application-specific access with zero-trust security and no client software required.
|
||||
Get application-specific access with zero-trust security and no client software required.
|
||||
</Card>
|
||||
|
||||
# Pangolin vs. Mesh VPN (e.g., Tailscale, Netbird)
|
||||
|
||||
13
docs.json
13
docs.json
@@ -31,8 +31,9 @@
|
||||
"group": "Sites",
|
||||
"pages": [
|
||||
"manage/sites/add-site",
|
||||
"manage/sites/install-newt",
|
||||
"manage/sites/configure-newt"
|
||||
"manage/sites/install-site",
|
||||
"manage/sites/configure-site",
|
||||
"manage/sites/update-site"
|
||||
]
|
||||
},
|
||||
{
|
||||
@@ -49,7 +50,10 @@
|
||||
},
|
||||
{
|
||||
"group": "Access Control",
|
||||
"pages": ["manage/access-control/bypass-rules"]
|
||||
"pages": [
|
||||
"manage/access-control/bypass-rules",
|
||||
"manage/access-control/forwarded-headers"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Identity Providers",
|
||||
@@ -67,7 +71,7 @@
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Fully Self-host Pangolin",
|
||||
"group": "Self-host Pangolin",
|
||||
"pages": [
|
||||
"self-host/quick-install",
|
||||
{
|
||||
@@ -81,6 +85,7 @@
|
||||
"self-host/dns-and-networking",
|
||||
"self-host/how-to-update",
|
||||
"self-host/supporter-program",
|
||||
"self-host/system-architecture",
|
||||
{
|
||||
"group": "Advanced Configuration",
|
||||
"pages": [
|
||||
|
||||
BIN
images/.DS_Store
vendored
Normal file
BIN
images/.DS_Store
vendored
Normal file
Binary file not shown.
132
images/diagram.svg
Normal file
132
images/diagram.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 52 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 774 KiB After Width: | Height: | Size: 93 KiB |
BIN
images/remote_subnets.png
Normal file
BIN
images/remote_subnets.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 41 KiB |
BIN
images/ssh_resource.png
Normal file
BIN
images/ssh_resource.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 53 KiB |
BIN
logo/dark.png
BIN
logo/dark.png
Binary file not shown.
|
Before Width: | Height: | Size: 60 KiB After Width: | Height: | Size: 57 KiB |
BIN
logo/light.png
BIN
logo/light.png
Binary file not shown.
|
Before Width: | Height: | Size: 61 KiB After Width: | Height: | Size: 63 KiB |
BIN
manage/.DS_Store
vendored
Normal file
BIN
manage/.DS_Store
vendored
Normal file
Binary file not shown.
50
manage/access-control/forwarded-headers.mdx
Normal file
50
manage/access-control/forwarded-headers.mdx
Normal file
@@ -0,0 +1,50 @@
|
||||
---
|
||||
title: "Forwarded Headers"
|
||||
description: "Learn how Pangolin forwards user identity information to your backend applications through HTTP headers"
|
||||
---
|
||||
|
||||
Pangolin can forward user identity information to your backend applications through custom HTTP headers. This allows your applications to receive user details directly from the request headers, enabling integration with Pangolin's authentication system.
|
||||
|
||||
<Info>
|
||||
Forwarded headers are only available when using authentication methods that provide user identity information.
|
||||
</Info>
|
||||
|
||||
## Supported Headers
|
||||
|
||||
Pangolin forwards the following headers to your backend when user identity is available:
|
||||
|
||||
| Header | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `Remote-User` | Unique username or user ID | `user_123` |
|
||||
| `Remote-Email` | User's email address | `john.doe@example.com` |
|
||||
| `Remote-Name` | User's full name | `John Doe` |
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
### Headers Available
|
||||
|
||||
These authentication methods provide user identity information and will include the forwarded headers:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Single Sign-On (SSO)" icon="users">
|
||||
Full user identity information including username, email, and name.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Headers Not Available
|
||||
|
||||
These authentication methods do not provide user identity information:
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="PIN Code" icon="hashtag">
|
||||
No user identity - only access control.
|
||||
</Card>
|
||||
|
||||
<Card title="Password" icon="lock">
|
||||
No user identity - only access control.
|
||||
</Card>
|
||||
|
||||
<Card title="Shareable Links" icon="link">
|
||||
No user identity - only access control.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,167 @@
|
||||
---
|
||||
title: "Add Client"
|
||||
description: "Create a client to connect to your Pangolin network from a remote computer"
|
||||
---
|
||||
|
||||
<Note>
|
||||
This feature is only available in self-hosted Pangolin instances.
|
||||
</Note>
|
||||
|
||||
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-olm) for detailed instructions.
|
||||
</Step>
|
||||
|
||||
<Step title="Configure resources">
|
||||
Create RAW TCP/UDP 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 raw TCP/UDP resources in Pangolin to configure what ports clients can hit and where they should go.
|
||||
|
||||
For example, if you wanted to SSH into your server you could add a resource for it:
|
||||
|
||||
<Frame caption="Pangolin UI showing example SSH resource.">
|
||||
<img src="/images/ssh_resource.png" alt="SSH Resource"/>
|
||||
</Frame>
|
||||
|
||||
### 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
|
||||
|
||||
Additionally, 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 may require Linux that you have forwarding enabled:
|
||||
|
||||
```bash
|
||||
sysctl -w net.ipv4.ip_forward=1
|
||||
```
|
||||
|
||||
And make it persistent:
|
||||
|
||||
```bash
|
||||
sudo nano /etc/sysctl.conf
|
||||
|
||||
net.ipv4.ip_forward = 1
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
233
manage/clients/configure-client.mdx
Normal file
233
manage/clients/configure-client.mdx
Normal file
@@ -0,0 +1,233 @@
|
||||
---
|
||||
title: "Configure Client"
|
||||
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.
|
||||
|
||||
## How Olm Works
|
||||
|
||||
### Registers with Pangolin
|
||||
|
||||
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.
|
||||
|
||||
### Establishes WireGuard Tunnel
|
||||
|
||||
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.
|
||||
|
||||
### 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
|
||||
|
||||
<ResponseField name="id" type="string" required>
|
||||
Olm ID generated by Pangolin to identify the client.
|
||||
|
||||
**Example**: `31frd0uzbjvp721`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="secret" type="string" required>
|
||||
A unique secret used to authenticate the client ID with the websocket.
|
||||
|
||||
**Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6`
|
||||
|
||||
<Warning>
|
||||
Keep this secret private and secure. It's used for authentication.
|
||||
</Warning>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="endpoint" type="string" required>
|
||||
The endpoint where both Gerbil and Pangolin reside for websocket connections.
|
||||
|
||||
**Example**: `https://pangolin.example.com`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="mtu" type="integer">
|
||||
MTU for the WireGuard interface.
|
||||
|
||||
**Default**: `1280`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="dns" type="string">
|
||||
DNS server to use for resolving the endpoint.
|
||||
|
||||
**Default**: `8.8.8.8`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="log-level" type="string">
|
||||
The log level to use for Olm output.
|
||||
|
||||
**Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`
|
||||
|
||||
**Default**: `INFO`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="ping-interval" type="string">
|
||||
Interval for pinging the server.
|
||||
|
||||
**Default**: `3s`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="ping-timeout" type="string">
|
||||
Timeout for each ping.
|
||||
|
||||
**Default**: `5s`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="holepunch" type="boolean">
|
||||
Enable NAT hole punching mode instead of relaying through the VPS.
|
||||
|
||||
**Default**: `false`
|
||||
|
||||
<Note>
|
||||
This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying.
|
||||
</Note>
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="health-file" type="string">
|
||||
Check if connection to WireGuard server (Pangolin) is ok. Creates a file if ok, removes it if not ok. Can be used with Docker healthcheck to restart Olm.
|
||||
|
||||
**Example**: `/tmp/olm-health`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="config-file" type="string">
|
||||
Path to a configuration file containing the same arguments as command line.
|
||||
|
||||
**Example**: `/etc/olm/config.yaml`
|
||||
</ResponseField>
|
||||
|
||||
## Configuration Examples
|
||||
|
||||
### Basic Configuration
|
||||
|
||||
```bash
|
||||
olm \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://example.com
|
||||
```
|
||||
|
||||
### With Hole Punching
|
||||
|
||||
```bash
|
||||
olm \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://example.com \
|
||||
--holepunch
|
||||
```
|
||||
|
||||
### With Custom MTU and DNS
|
||||
|
||||
```bash
|
||||
olm \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://example.com \
|
||||
--mtu 1400 \
|
||||
--dns 1.1.1.1
|
||||
```
|
||||
|
||||
### With Health Check
|
||||
|
||||
```bash
|
||||
olm \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--endpoint https://example.com \
|
||||
--health-file /tmp/olm-health
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
<ResponseField name="PANGOLIN_ENDPOINT" type="string">
|
||||
Endpoint of your Pangolin server (equivalent to `--endpoint`)
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_ID" type="string">
|
||||
Olm ID generated by Pangolin (equivalent to `--id`)
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_SECRET" type="string">
|
||||
Olm secret for authentication (equivalent to `--secret`)
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_MTU" type="integer">
|
||||
MTU for the 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`)
|
||||
|
||||
**Default**: `8.8.8.8`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_LOG_LEVEL" type="string">
|
||||
Log level (equivalent to `--log-level`)
|
||||
|
||||
**Default**: `INFO`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_PING_INTERVAL" type="string">
|
||||
Interval for pinging the server (equivalent to `--ping-interval`)
|
||||
|
||||
**Default**: `3s`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_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`)
|
||||
|
||||
**Default**: `false`
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_HEALTH_FILE" type="string">
|
||||
Path to health file for connection monitoring (equivalent to `--health-file`)
|
||||
</ResponseField>
|
||||
|
||||
<ResponseField name="OLM_CONFIG_FILE" type="string">
|
||||
Load the config from this file instead of command line arguments (equivalent to `--config-file`)
|
||||
</ResponseField>
|
||||
|
||||
<Note>
|
||||
When both environment variables and CLI arguments are provided, CLI arguments take precedence.
|
||||
</Note>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Issues
|
||||
|
||||
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
|
||||
|
||||
### Permission Issues
|
||||
|
||||
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
|
||||
|
||||
### Performance Issues
|
||||
|
||||
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
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- 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
|
||||
141
manage/clients/install-client.mdx
Normal file
141
manage/clients/install-client.mdx
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: "Install Client"
|
||||
description: "Install Olm as a binary"
|
||||
---
|
||||
|
||||
Olm 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 client and copy the Olm config** in Pangolin before running Olm.
|
||||
</Warning>
|
||||
|
||||
## Binary Installation
|
||||
|
||||
### 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://docs.fossorial.io/get-olm.sh | bash
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
Download and install manually:
|
||||
|
||||
```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>
|
||||
|
||||
### Running Olm
|
||||
|
||||
Run Olm with the configuration from Pangolin:
|
||||
|
||||
```bash
|
||||
olm \
|
||||
--id 31frd0uzbjvp721 \
|
||||
--secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 \
|
||||
--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:
|
||||
|
||||
```ini title="/etc/systemd/system/olm.service"
|
||||
[Unit]
|
||||
Description=Olm
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
ExecStart=/usr/local/bin/olm --id 31frd0uzbjvp721 --secret h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6 --endpoint https://example.com
|
||||
Restart=always
|
||||
User=root
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Make sure to move the binary to `/usr/local/bin/olm` before creating the service!
|
||||
</Warning>
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
# Install the service
|
||||
olm.exe install
|
||||
|
||||
# Start the service
|
||||
olm.exe start
|
||||
|
||||
# Stop the service
|
||||
olm.exe stop
|
||||
|
||||
# Check service status
|
||||
olm.exe status
|
||||
|
||||
# Remove the service
|
||||
olm.exe remove
|
||||
|
||||
# Run in debug mode (console output) with our without id & secret
|
||||
olm.exe debug
|
||||
|
||||
# Show help
|
||||
olm.exe help
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
1. Install the service: `olm.exe install`
|
||||
2. Configure the service with your credentials using Windows Service Manager or by setting system environment variables:
|
||||
- `PANGOLIN_ENDPOINT=https://example.com`
|
||||
- `OLM_ID=your_olm_id`
|
||||
- `OLM_SECRET=your_secret`
|
||||
3. Start the service: `olm.exe start`
|
||||
|
||||
### Service Logs
|
||||
|
||||
When running as a service, logs are written to:
|
||||
|
||||
- Windows Event Log (Application log, source: "OlmWireguardService")
|
||||
- Log files in: `%PROGRAMDATA%\olm\logs\olm.log`
|
||||
|
||||
You can view the Windows Event Log using Event Viewer or PowerShell:
|
||||
|
||||
```powershell
|
||||
Get-EventLog -LogName Application -Source "OlmWireguardService" -Newest 10
|
||||
```
|
||||
|
||||
## 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).
|
||||
- **Linux**: May require root privileges or specific capabilities to create tun interfaces.
|
||||
- **macOS**: May require additional permissions for network interface creation.
|
||||
@@ -0,0 +1,126 @@
|
||||
---
|
||||
title: "Domains"
|
||||
description: "Learn how to configure domains for your Pangolin resources and understand the different domain types available"
|
||||
---
|
||||
|
||||
Domains allow you to access your Pangolin resources through custom URLs. Pangolin supports different domain types depending on your deployment model and requirements.
|
||||
|
||||
## Getting Started
|
||||
|
||||
In Pangolin Cloud, a domain is not required. You can use our provided domain endings like `.hostlocal.app` or `.tunneled.to` for your resources.
|
||||
|
||||
## Domain Types
|
||||
|
||||
<Info>
|
||||
SSL certificates are automatically acquired and managed for both CNAME and NS domain types. No additional certificate configuration is required.
|
||||
</Info>
|
||||
|
||||
### Domain Delegation (NS Records)
|
||||
|
||||
Domain delegation gives Pangolin full DNS control over your domain:
|
||||
|
||||
- **Full Domain Control**: Includes the base domain and all subdomains
|
||||
- **NS Records**: Uses nameserver delegation for complete DNS management
|
||||
- **Automatic Subdomains**: All subdomains work automatically
|
||||
|
||||
<Tip>
|
||||
Domain delegation is ideal when you want Pangolin to manage your entire domain and all its subdomains.
|
||||
</Tip>
|
||||
|
||||
### Single Domain (CNAME Records)
|
||||
|
||||
Single domain is limited to the exact domain you specify:
|
||||
|
||||
- **Exact Domain Only**: Only the specific domain provided works
|
||||
- **CNAME Records**: Uses CNAME records pointing to Pangolin
|
||||
- **No Subdomains**: Subdomains will not work with CNAME domains
|
||||
- **External DNS**: Your domain remains controlled by your existing DNS provider
|
||||
|
||||
<Tip>
|
||||
CNAME domains are useful when your domain is already controlled by another provider but you still want to expose resources via Pangolin.
|
||||
</Tip>
|
||||
|
||||
## Adding Domains
|
||||
|
||||
### Pangolin Cloud
|
||||
|
||||
Domains can be added to an organization via the domains section of the organization settings:
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Organization Settings">
|
||||
Go to your organization settings and select the "Domains" section.
|
||||
</Step>
|
||||
|
||||
<Step title="Choose Domain Type">
|
||||
Select either "Domain Delegation" or "Single Domain" based on your needs.
|
||||
</Step>
|
||||
|
||||
<Step title="Enter Domain">
|
||||
Provide your domain name (e.g., example.com).
|
||||
</Step>
|
||||
|
||||
<Step title="Configure DNS Records">
|
||||
Follow the provided instructions to add the required DNS records to your provider.
|
||||
</Step>
|
||||
|
||||
<Step title="Wait for Verification">
|
||||
DNS changes may take time to propagate. The domain will show as verified once propagation is complete.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Domain delegation and CNAME domains are only available in Pangolin Cloud. Self-hosted Pangolin uses different domain configuration methods.
|
||||
</Warning>
|
||||
|
||||
### Self-Hosted Pangolin
|
||||
|
||||
For self-hosted Pangolin, domains are configured differently, though you can still create domains in the UI.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="System-Wide Domains" icon="gear" href="/self-host/advanced/config-file#domain-configuration">
|
||||
Configure domains via the config file, including certificate resolver settings.
|
||||
</Card>
|
||||
|
||||
<Card title="Wildcard Domains" icon="asterisk" href="/self-host/advanced/wild-card-domains">
|
||||
Set up wildcard domains for flexible subdomain management.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Info>
|
||||
In self-hosted Pangolin, domains do not need individual verification, but you're responsible for ensuring correct DNS records point to your server.
|
||||
</Info>
|
||||
|
||||
## DNS Configuration
|
||||
|
||||
### For Domain Delegation
|
||||
|
||||
When using domain delegation, you'll need to update your domain's nameservers:
|
||||
|
||||
**Example NS Records:**
|
||||
```dns
|
||||
Type: NS
|
||||
Name: test.example.com
|
||||
Value: ns-east.fossorial.io
|
||||
Value: ns-west.fossorial.io
|
||||
```
|
||||
|
||||
### For Single Domain (CNAME)
|
||||
|
||||
When using CNAME domains, you'll need to add CNAME records:
|
||||
|
||||
**Example CNAME Records:**
|
||||
```dns
|
||||
Record 1:
|
||||
Type: CNAME
|
||||
Name: test.example.com
|
||||
Value: 0nbn5rpcq4wthq6.cname.fossorial.io
|
||||
|
||||
Record 2:
|
||||
Type: CNAME
|
||||
Name: _acme-challenge.test.example.com
|
||||
Value: _acme-challenge.0nbn5rpcq4wthq6.cname.fossorial.io
|
||||
```
|
||||
|
||||
<Check>
|
||||
Once DNS is properly configured and propagated, your domain will be verified and ready to use with your Pangolin resources.
|
||||
</Check>
|
||||
|
||||
@@ -5,17 +5,13 @@ description: "Learn about Pangolin's high availability options and how to ensure
|
||||
|
||||
Pangolin provides multiple deployment options to ensure your applications remain highly available and accessible to users worldwide.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Global network of points of presence with automatic failover and routing to your backend services.
|
||||
</Card>
|
||||
|
||||
<Card title="Hybrid" icon="server" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple highly available points of presence with cloud coordination and automatic failover.
|
||||
</Card>
|
||||
|
||||
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
|
||||
Fully self-hosted, self-contained Pangolin server acting as a single point of presence.
|
||||
<Card title="Hybrid" icon="circle-nodes" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits your servers.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -23,6 +19,25 @@ Pangolin provides multiple deployment options to ensure your applications remain
|
||||
|
||||
For detailed information about how points of presence work and their advantages, see our [Points of Presence](/manage/points-of-presence) documentation.
|
||||
|
||||
## Hybrid Deployment
|
||||
|
||||
The hybrid model allows you to host your own points of presence while leveraging Pangolin Cloud's coordination and failover capabilities:
|
||||
|
||||
### How It Works
|
||||
|
||||
- **You Host the Exit Node**: Manage the infrastructure for your points of presence, which connect your Newt tunnels.
|
||||
- **We Handle the Rest**: Pangolin Cloud manages the control plane, DNS, certificate management, database, and backups.
|
||||
- **Failover Made Simple**: Host multiple exit nodes with automatic failover between them. Optionally, if your nodes are unavailable, traffic automatically fails over to our cloud nodes.
|
||||
|
||||
### Benefits
|
||||
|
||||
- **Data Control**: Traffic flows through your servers, giving you control over data transit costs, privacy, and works with your security policies.
|
||||
- **High Availability**: Eliminates the complexity of managing high availability while still owning your own infrastrcture.
|
||||
|
||||
<Tip>
|
||||
Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit.
|
||||
</Tip>
|
||||
|
||||
## Contact Us
|
||||
|
||||
For hybrid deployments, points of presence, and high availability contact us:
|
||||
|
||||
@@ -5,19 +5,25 @@ description: "Learn about Pangolin's global network of points of presence and ho
|
||||
|
||||
Pangolin's points of presence (PoPs) are strategically located servers around the world that serve as entry points for user traffic to your applications. They form the foundation of Pangolin's distributed architecture, providing global high availability and optimal performance.
|
||||
|
||||
## Contact Us
|
||||
|
||||
For hybrid deployments, points of presence, and high availability contact us:
|
||||
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
|
||||
|
||||
## What Are Points of Presence?
|
||||
|
||||
Points of presence are geographically distributed servers that:
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Entry Points" icon="door-open">
|
||||
Handle incoming user requests before routing them to your applications.
|
||||
</Card>
|
||||
|
||||
- **Serve as Entry Points**: Handle incoming user requests before routing them to your applications
|
||||
- **Provide Global Coverage**: Located worldwide to minimize latency for users in different regions
|
||||
- **Enable High Availability**: Multiple locations ensure your applications remain accessible even if individual locations fail
|
||||
- **Handle Authentication**: Verify user identity and enforce access policies before allowing access
|
||||
<Card title="Global Coverage" icon="globe">
|
||||
Located regionally to minimize latency for users in different regions.
|
||||
</Card>
|
||||
|
||||
<Card title="High Availability" icon="shield-check">
|
||||
Multiple locations ensure your applications remain accessible even if individual locations fail.
|
||||
</Card>
|
||||
|
||||
<Card title="Authentication" icon="key">
|
||||
Verify user identity and enforce access policies before allowing access.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Info>
|
||||
Think of points of presence as the "front doors" to your applications - users connect to the closest one, and it securely routes their requests to your backend services.
|
||||
@@ -25,92 +31,79 @@ Think of points of presence as the "front doors" to your applications - users co
|
||||
|
||||
## How Points of Presence Work
|
||||
|
||||
### Geographic Routing
|
||||
<Steps>
|
||||
<Step title="Ingress Routing">
|
||||
Request is routed to the closest available point of presence. If one goes down, there is always another point available.
|
||||
</Step>
|
||||
|
||||
When a user requests access to your application:
|
||||
<Step title="Authentication">
|
||||
User identity is verified at the point of presence before getting routed to your backend.
|
||||
</Step>
|
||||
|
||||
1. **DNS Resolution**: The user's request is automatically routed to the closest available point of presence
|
||||
2. **Authentication**: The point of presence verifies the user's identity and permissions
|
||||
3. **Tunnel Routing**: Authenticated requests are sent through secure tunnels to your applications
|
||||
4. **Response Delivery**: Responses follow the same path back to the user
|
||||
<Step title="Tunnel Selection">
|
||||
Pangolin selects the optimal tunnel route to your backend service. Site tunnel clients (Newt) connect to the optimal point of presence.
|
||||
</Step>
|
||||
|
||||
<Check>
|
||||
This routing happens automatically and transparently - users always get the best possible performance without any manual configuration.
|
||||
</Check>
|
||||
|
||||
### Automatic Failover
|
||||
|
||||
Pangolin's points of presence provide built-in high availability:
|
||||
|
||||
- **Health Monitoring**: Each point of presence continuously monitors its health and connectivity
|
||||
- **Automatic Failover**: If one location becomes unavailable, traffic automatically routes to the next closest location
|
||||
- **Load Distribution**: Traffic is automatically balanced across multiple locations to prevent overload
|
||||
- **Global Redundancy**: Multiple points of presence ensure your applications remain accessible during regional outages
|
||||
<Step title="Failover Handling">
|
||||
If the primary tunnel fails, traffic automatically switches to an alternative route.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Advantages of Points of Presence
|
||||
|
||||
### Global Performance
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Low Latency" icon="bolt">
|
||||
Users connect to the geographically closest point of presence.
|
||||
</Card>
|
||||
|
||||
- **Low Latency**: Users connect to the geographically closest point of presence
|
||||
- **Optimized Routing**: Automatic selection of the best available location
|
||||
- **Edge Computing**: Processing happens closer to users for faster response times
|
||||
<Card title="Optimized Routing" icon="route">
|
||||
Automatic selection of the best available tunnel to route to your backend services.
|
||||
</Card>
|
||||
|
||||
### High Availability
|
||||
<Card title="Edge Computing" icon="microchip">
|
||||
Provide ingress to thin-clients on private networks via tunnels.
|
||||
</Card>
|
||||
|
||||
- **Fault Tolerance**: No single point of failure - if one location goes down, others remain available
|
||||
- **Automatic Recovery**: Failed locations are automatically bypassed and traffic is rerouted
|
||||
- **Regional Redundancy**: Multiple locations per region provide additional redundancy
|
||||
<Card title="Health Monitoring" icon="heart-pulse">
|
||||
Each point of presence continuously monitors its health and connectivity to your backend.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Security and Compliance
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Global Redundancy" icon="check-double">
|
||||
Multiple points of presence ensure your applications remain accessible during regional outages.
|
||||
</Card>
|
||||
|
||||
- **Distributed Security**: Security controls are enforced at every point of presence
|
||||
- **Regional Compliance**: Points of presence can be configured to meet regional data requirements
|
||||
- **Encrypted Transit**: All traffic between points of presence and your applications is encrypted
|
||||
|
||||
### Scalability
|
||||
|
||||
- **Automatic Scaling**: New points of presence are automatically added as needed
|
||||
- **Load Balancing**: Traffic is distributed across multiple locations to handle high volumes
|
||||
- **Global Distribution**: Support for applications with users worldwide
|
||||
<Card title="Fault Tolerance" icon="shield">
|
||||
No single point of failure - if one location goes down, there is always a way back to your application.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Deployment Models
|
||||
|
||||
### Pangolin Cloud
|
||||
|
||||
Pangolin Cloud includes a global network of points of presence that provide:
|
||||
|
||||
- **Automatic Management**: Points of presence are automatically deployed, monitored, and maintained
|
||||
- **Global Coverage**: Strategic locations worldwide for optimal performance
|
||||
- **Built-in High Availability**: Multiple redundant locations ensure 99.9%+ uptime
|
||||
- **Zero Configuration**: No setup or management required on your part
|
||||
|
||||
<Card title="Try Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Get started with Pangolin Cloud and experience global points of presence with automatic high availability.
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Pangolin Cloud" icon="cloud" href="https://pangolin.fossorial.io/auth/signup">
|
||||
Global network of points of presence with automatic failover and routing to your backend services.
|
||||
</Card>
|
||||
|
||||
### Self-Hosted Pangolin
|
||||
<Card title="Hybrid" icon="circle-nodes" href="mailto:numbat@fossorial.io">
|
||||
Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits yours servers.
|
||||
</Card>
|
||||
|
||||
Self-hosted Pangolin operates as a single point of presence:
|
||||
|
||||
- **Single Location**: Your Pangolin instance serves as the only entry point
|
||||
- **Limited Availability**: No built-in redundancy - if your server goes down, access is lost
|
||||
- **Manual Management**: You're responsible for server maintenance and uptime
|
||||
- **Regional Limitation**: Performance depends on your server's location
|
||||
<Card title="Self-Hosted" icon="server" href="/self-host/quick-install">
|
||||
Fully self-hosted, self-contained Pangolin server acting as a single point of presence.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Warning>
|
||||
Self-hosted Pangolin provides only a single point of presence and is not highly available. Consider Pangolin Cloud or hybrid deployment for production environments requiring high availability.
|
||||
</Warning>
|
||||
|
||||
### Hybrid Deployment
|
||||
|
||||
Hybrid deployment allows you to host your own points of presence while leveraging Pangolin's cloud coordination:
|
||||
|
||||
- **Your Infrastructure**: Host points of presence on your own servers or cloud infrastructure
|
||||
- **Cloud Coordination**: Pangolin Cloud handles failover logic and coordination between your points of presence
|
||||
- **Automatic Failover**: If your points of presence go down, traffic automatically fails over to Pangolin Cloud
|
||||
- **Data Control**: Traffic flows through your servers, giving you control over data transit costs and privacy
|
||||
- **Custom Locations**: Deploy points of presence in specific regions or data centers of your choice
|
||||
|
||||
<Tip>
|
||||
Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit.
|
||||
</Tip>
|
||||
|
||||
## Contact Us
|
||||
|
||||
For hybrid deployments, points of presence, and high availability contact us:
|
||||
- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io)
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Configure Newt"
|
||||
title: "Configure Site"
|
||||
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.
|
||||
@@ -26,8 +26,6 @@ When Newt receives proxy control messages, it will use the information encoded t
|
||||
|
||||
## Configuration Arguments
|
||||
|
||||
### Required Arguments
|
||||
|
||||
<ResponseField name="id" type="string" required>
|
||||
Newt ID generated by Pangolin to identify the client.
|
||||
|
||||
@@ -50,8 +48,6 @@ When Newt receives proxy control messages, it will use the information encoded t
|
||||
**Example**: `https://pangolin.example.com`
|
||||
</ResponseField>
|
||||
|
||||
### Optional Arguments
|
||||
|
||||
<ResponseField name="mtu" type="integer">
|
||||
MTU for the internal WireGuard interface.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
title: "Install Newt"
|
||||
title: "Install Site"
|
||||
description: "Install Newt as a binary or Docker container"
|
||||
---
|
||||
|
||||
48
manage/sites/update-site.mdx
Normal file
48
manage/sites/update-site.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: "Update Site"
|
||||
description: "Update Newt to the latest version"
|
||||
---
|
||||
|
||||
The update process depends on how you originally installed Newt.
|
||||
|
||||
Find the lates version in the [GitHub releases](https://github.com/fosrl/newt/releases).
|
||||
|
||||
## Docker Installation
|
||||
|
||||
Update the image version in your `docker-compose.yml`:
|
||||
|
||||
```yaml title="docker-compose.yml"
|
||||
services:
|
||||
newt:
|
||||
image: fosrl/newt:{version} # Replace {version} with the latest version tag
|
||||
# ... rest of config
|
||||
```
|
||||
|
||||
Then pull and restart:
|
||||
|
||||
```bash
|
||||
docker compose pull newt
|
||||
docker compose up -d newt
|
||||
```
|
||||
|
||||
## Binary Installation
|
||||
|
||||
### Auto Installer (Recommended)
|
||||
|
||||
If you used the auto installer, simply run it again.
|
||||
|
||||
```bash
|
||||
curl -fsSL https://docs.fossorial.io/get-newt.sh | bash
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
Download the latest binary for your system from [GitHub releases](https://github.com/fosrl/newt/releases) and replace your existing binary.
|
||||
|
||||
```bash
|
||||
wget -O newt "https://github.com/fosrl/newt/releases/download/{version}/newt_{architecture}" && chmod +x ./newt
|
||||
```
|
||||
|
||||
<Note>
|
||||
Replace `{version}` with the desired version and `{architecture}` with your architecture. Check the [release notes](https://github.com/fosrl/newt/releases) for the latest information.
|
||||
</Note>
|
||||
BIN
self-host/.DS_Store
vendored
BIN
self-host/.DS_Store
vendored
Binary file not shown.
@@ -57,7 +57,7 @@ You'll need to create A (or AAAA for IPv6) records pointing to your VPS IP addre
|
||||
|
||||
Pangolin requires these ports to be open on your VPS:
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<CardGroup cols={2}>
|
||||
<Card title="TCP Port 80">
|
||||
**HTTP/SSL Verification**
|
||||
|
||||
@@ -75,14 +75,22 @@ Pangolin requires these ports to be open on your VPS:
|
||||
</Card>
|
||||
|
||||
<Card title="UDP Port 51820">
|
||||
**WireGuard Tunnel**
|
||||
**Site Tunnels**
|
||||
|
||||
- Newt client connections
|
||||
- Gerbil tunnel endpoint
|
||||
- Secure traffic routing
|
||||
This is the default port for sites (Newt) to establish tunnels to the cloud exit node.
|
||||
</Card>
|
||||
|
||||
<Card title="UDP Port 21820">
|
||||
**Client Tunnels**
|
||||
|
||||
This is the default port for clients relaying through Gerbil to newt. This port is only required for clients.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<Warning>
|
||||
Always verify your exposed ports (e.g., with [nmap](https://nmap.org/) or [RustScan](https://github.com/bee-san/RustScan)) and ensure you expose **only** the ports that are absolutely necessary. By tunneling out to the VPS, you are effectively including the VPS in your security boundary, so you must secure it as part of your overall network strategy. For more details, see [Docker’s port publishing documentation](https://docs.docker.com/engine/network/packet-filtering-firewalls/#port-publishing-and-mapping).
|
||||
</Warning>
|
||||
|
||||
### Docker Port Exposure
|
||||
|
||||
By default, Pangolin exposes these ports on all interfaces:
|
||||
|
||||
@@ -32,6 +32,7 @@ sudo docker compose down
|
||||
- **Pangolin**: [GitHub Releases](https://github.com/fosrl/pangolin/releases)
|
||||
- **Gerbil**: [GitHub Releases](https://github.com/fosrl/gerbil/releases)
|
||||
- **Traefik**: [Docker Hub](https://hub.docker.com/_/traefik)
|
||||
- **Badger**: [GitHub Releases](https://github.com/fosrl/badger/releases)
|
||||
|
||||
<Info>
|
||||
Look for the latest stable release (not pre-release or beta versions).
|
||||
@@ -56,6 +57,16 @@ services:
|
||||
# ... rest of config
|
||||
```
|
||||
|
||||
Increase the Badger version number in `config/traefik_config.yml`:
|
||||
|
||||
```yaml title="traefik_config.yml"
|
||||
experimental:
|
||||
plugins:
|
||||
badger:
|
||||
moduleName: github.com/fosrl/badger
|
||||
version: v1.2.0 # Update to latest version
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Update each service you want to upgrade. You can update them individually or all at once.
|
||||
</Warning>
|
||||
|
||||
@@ -313,6 +313,19 @@ Anywhere you see `http://pangolin:3001` must match. The hostname should be the n
|
||||
|
||||
**WireGuard Port:**
|
||||
|
||||
<Warning>
|
||||
You **must** use the default port of `51822` for WireGuard in the Gerbil container. Using any other port may cause connection issues that are difficult to debug.
|
||||
|
||||
Make sure this is also reflected in your Pangolin `config.yml`:
|
||||
|
||||
```yml
|
||||
gerbil:
|
||||
start_port: 51822
|
||||
```
|
||||
|
||||
See [this GitHub issue comment](https://github.com/fosrl/pangolin/issues/227#issuecomment-2781608815) for more details.
|
||||
</Warning>
|
||||
|
||||
The port you use for WireGuard must also match what you set the port to in the Pangolin config. By default we use a slightly different port than the standard WireGuard port to avoid conflicts with the built in WireGuard server in Unraid.
|
||||
|
||||
**HTTP and HTTPS Ports:**
|
||||
|
||||
66
self-host/system-architecture.mdx
Normal file
66
self-host/system-architecture.mdx
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
"title": "System Architecture"
|
||||
"description": "Learn how the components of the system interact to form Pangolin"
|
||||
---
|
||||
|
||||
### Pangolin (Control Plane)
|
||||
|
||||
Pangolin is the main control center that orchestrates the entire system:
|
||||
|
||||
- **Web Interface**: Management dashboard for configuring sites, users, and access policies
|
||||
- **REST API**: External API for automation and integration
|
||||
- **WebSocket Server**: Manages real-time connections to edge network clients
|
||||
- **Authentication System**: Handles user authentication and authorization
|
||||
- **Database**: Stores configuration, user data, and system state
|
||||
|
||||
<Info>
|
||||
Pangolin acts as the brain of the system, coordinating all other components and managing user access.
|
||||
</Info>
|
||||
|
||||
### Gerbil (Tunnel Manager)
|
||||
|
||||
Gerbil manages the secure WireGuard tunnels between your edge networks and the central server:
|
||||
|
||||
- **Peer Management**: Creates and maintains WireGuard connections
|
||||
- **Tunnel Orchestration**: Handles tunnel creation, updates, and cleanup
|
||||
- **Security**: Ensures all traffic is encrypted using WireGuard's cryptographic protocols
|
||||
|
||||
<Check>
|
||||
WireGuard provides fast, secure, and reliable tunneling with minimal overhead.
|
||||
</Check>
|
||||
|
||||
### Newt (Edge Client)
|
||||
|
||||
Newt is a lightweight client that runs on your edge networks (servers, VMs, or containers):
|
||||
|
||||
- **Automatic Discovery**: Finds the optimal point of presence for best performance
|
||||
- **Dual Connection**: Connects to Pangolin via WebSocket and Gerbil via WireGuard
|
||||
- **Resource Proxy**: Creates TCP/UDP proxies to expose your applications securely
|
||||
|
||||
<Tip>
|
||||
Newt is designed to be resource-efficient and can run on minimal hardware or in containers.
|
||||
</Tip>
|
||||
|
||||
### Reverse Proxy (Router)
|
||||
|
||||
The reverse proxy handles incoming requests and routes them to your applications:
|
||||
|
||||
- **Request Routing**: Directs traffic to the correct backend services
|
||||
- **SSL Termination**: Manages HTTPS certificates and encryption
|
||||
- **Middleware Support**: Integrates with security and monitoring plugins
|
||||
|
||||
### Badger (Authentication Middleware)
|
||||
|
||||
Badger is Pangolin's middleware that enforces access control:
|
||||
|
||||
- **Request Interception**: Catches all incoming requests before they reach your applications
|
||||
- **Authentication Check**: Verifies user identity and permissions
|
||||
- **Secure Redirects**: Sends unauthenticated users to Pangolin's login system
|
||||
|
||||
<Warning>
|
||||
Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures.
|
||||
</Warning>
|
||||
|
||||
<Frame caption="System architecture showing Pangolin components and their interactions">
|
||||
<img src="/images/system-diagram.svg" alt="Pangolin system architecture diagram"/>
|
||||
</Frame>
|
||||
Reference in New Issue
Block a user