mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-23 13:26:47 +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)
|
||||
|
||||
Reference in New Issue
Block a user