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

test deploy

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

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

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

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

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

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

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