mirror of
https://github.com/fosrl/docs-v2.git
synced 2026-02-08 05:56:45 +00:00
109 lines
4.0 KiB
Plaintext
109 lines
4.0 KiB
Plaintext
---
|
|
title: "How Pangolin Works"
|
|
description: "Learn about Pangolin's architecture and how its components work together to provide secure application access"
|
|
---
|
|
|
|
## System Overview
|
|
|
|
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>
|
|
|
|
## 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
|
|
|
|
<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>
|
|
|
|
<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>
|