diff --git a/.DS_Store b/.DS_Store index ce2db26..335be74 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/about/how-pangolin-works.mdx b/about/how-pangolin-works.mdx index 5875a14..ef4d35e 100644 --- a/about/how-pangolin-works.mdx +++ b/about/how-pangolin-works.mdx @@ -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. - - -Pangolin system architecture diagram + + -## 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 - - -Pangolin acts as the brain of the system, coordinating all other components and managing user access. - - -### 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 - - -WireGuard provides fast, secure, and reliable tunneling with minimal overhead. - - -### 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 - - -Newt is designed to be resource-efficient and can run on minimal hardware or in containers. - - -### 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 - - -Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures. - - -## How It All Works Together +## How It Works - - A user tries to access your application through the public domain. + + 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. - - Badger middleware catches the request and checks if the user is authenticated. + + 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. - - If not authenticated, the user is redirected to Pangolin's login system. - - - - Once authenticated, requests flow through the encrypted WireGuard tunnel managed by Gerbil. + + Authenticated requests are routed and flow through encrypted WireGuard tunnels to your applications with optional load balancing and failover for your backend servers. - 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. -## Deployment Models + +Points of presence provide global high availability - if one location goes down, traffic automatically routes to the next closest location. + + +## Deployment Options - 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. + + + + Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits yours servers. - 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. + + + + Detailed information about points of presence and high availability options. + + + +## Key Benefits + + + + Your applications can run on private networks without exposing ports. + + + + Users always connect to the closest available point of presence. + + + + Every request is authenticated and authorized before reaching your applications. + + + + Multiple points of presence, failover, and load balancing between tunnels ensures there is always a way for users to access your applications. diff --git a/about/pangolin-vs-traditional-reverse-proxy.mdx b/about/pangolin-vs-traditional-reverse-proxy.mdx index d56ff21..3af3d05 100644 --- a/about/pangolin-vs-traditional-reverse-proxy.mdx +++ b/about/pangolin-vs-traditional-reverse-proxy.mdx @@ -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: + + + If the reverse proxy server goes down, all applications become inaccessible. + -- **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 + + Users far from the server location experience higher latency. + + + + Requires public IP addresses and open ports on your network. + + + + 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) +### How It Works -Pangolin operates a distributed network of points of presence worldwide that serve as entry points for user traffic: + + + Request is routed to the closest available point of presence. If one goes down, there is always another point available. + -- **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 + + User identity is verified at the point of presence before getting routed to your backend. + -### Intelligent Backend Routing (Tunnel Layer) + + Pangolin selects the optimal tunnel route to your backend service. + -Once traffic reaches a point of presence, Pangolin provides additional high availability for routing to your backend services: + + If the primary tunnel fails, traffic automatically switches to an alternative route. + -- **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 + + Response follows the same resilient path back to the user. + + This dual-layer approach ensures your applications remain accessible even if individual points of presence or tunnel connections fail. -### 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 - - -Both ingress points and tunnel connections are automatically managed, providing seamless failover without any manual intervention. - - ## 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** | 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 + + + Support for 2FA, passkeys, and OTP. + -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 + + Integration with Google, Okta, and other identity providers. + -#### Advanced Access Control Features + + Role-based access control and path-based rules. + -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 + + IP-based, path-based, and geographic access policies. + + 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 | - 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. diff --git a/about/pangolin-vs-vpn.mdx b/about/pangolin-vs-vpn.mdx index 313d45d..c07cb17 100644 --- a/about/pangolin-vs-vpn.mdx +++ b/about/pangolin-vs-vpn.mdx @@ -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: + + + Users get access to entire networks, not just the applications they need. + -- **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 + + Users must install and configure VPN client software. + -## Pangolin's Application-First Approach + + Requires public IP addresses, open ports, and complex network configuration. + -Pangolin provides secure, application-specific access without the limitations of traditional VPNs: + + Basic network-level security with few granular controls or complicated ACLs. + + + + If the VPN server goes down, all access is lost. + + + + Broad network access can be risky if user devices are compromised. + + + +## 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 + + + Users access only the applications they're authorized to use. + -### Simplified Infrastructure + + No client software installation required - works with any web browser. + -- **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 + + Role-based access control, path-based rules, and contextual policies. + - -Pangolin's application-specific approach follows the principle of least privilege - users only get access to what they need, when they need it. - + + Support for SSO, OIDC, 2FA, and passkeys. + + + +### Simplified Ingess Infrastructure + + + + Edge networks don't need public IP addresses. + + + +Multiple points of presence ensure high availability. + + ## 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 - - -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. - - -## 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 - - 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. # Pangolin vs. Mesh VPN (e.g., Tailscale, Netbird) diff --git a/docs.json b/docs.json index ba51592..194deb6 100644 --- a/docs.json +++ b/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": [ diff --git a/images/.DS_Store b/images/.DS_Store new file mode 100644 index 0000000..5008ddf Binary files /dev/null and b/images/.DS_Store differ diff --git a/images/diagram.svg b/images/diagram.svg new file mode 100644 index 0000000..58e44f3 --- /dev/null +++ b/images/diagram.svg @@ -0,0 +1,132 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/newt-preview.png b/images/newt-preview.png index c6a8cd8..ac83f8f 100644 Binary files a/images/newt-preview.png and b/images/newt-preview.png differ diff --git a/images/remote_subnets.png b/images/remote_subnets.png new file mode 100644 index 0000000..756e172 Binary files /dev/null and b/images/remote_subnets.png differ diff --git a/images/ssh_resource.png b/images/ssh_resource.png new file mode 100644 index 0000000..42e6297 Binary files /dev/null and b/images/ssh_resource.png differ diff --git a/logo/dark.png b/logo/dark.png index c45cb47..2b33779 100644 Binary files a/logo/dark.png and b/logo/dark.png differ diff --git a/logo/light.png b/logo/light.png index b8a19a9..d3fddfe 100644 Binary files a/logo/light.png and b/logo/light.png differ diff --git a/manage/.DS_Store b/manage/.DS_Store new file mode 100644 index 0000000..fa3f2d7 Binary files /dev/null and b/manage/.DS_Store differ diff --git a/manage/access-control/forwarded-headers.mdx b/manage/access-control/forwarded-headers.mdx new file mode 100644 index 0000000..bdc5a1f --- /dev/null +++ b/manage/access-control/forwarded-headers.mdx @@ -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. + + +Forwarded headers are only available when using authentication methods that provide user identity information. + + +## 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: + + + + Full user identity information including username, email, and name. + + + +### Headers Not Available + +These authentication methods do not provide user identity information: + + + + No user identity - only access control. + + + + No user identity - only access control. + + + + No user identity - only access control. + + diff --git a/manage/clients/add-client.mdx b/manage/clients/add-client.mdx index e69de29..2d76703 100644 --- a/manage/clients/add-client.mdx +++ b/manage/clients/add-client.mdx @@ -0,0 +1,167 @@ +--- +title: "Add Client" +description: "Create a client to connect to your Pangolin network from a remote computer" +--- + + +This feature is only available in self-hosted Pangolin instances. + + +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. + + +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). + + +## 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 + + + + In the Pangolin dashboard, go to the **Clients** section and click **Add Client**. + + + + Configure the basic information: + - **Client Name**: A descriptive name for your client + + + + Pangolin will generate: + - **Client ID**: Unique identifier for the Olm client + - **Secret**: Authentication secret for secure connection + - **Endpoint**: The Pangolin server endpoint + + + + Use the generated credentials to install and configure Olm on your remote computer. See [Install Olm](/manage/clients/install-olm) for detailed instructions. + + + + 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`. + + + + 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. + + + +## 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) + + +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. + + +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: + + + SSH Resource + + +### Native Mode + + +Right now native mode only works on Linux. + + +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. + + + Remote Subnets + + +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 diff --git a/manage/clients/configure-client.mdx b/manage/clients/configure-client.mdx new file mode 100644 index 0000000..ec4ef4e --- /dev/null +++ b/manage/clients/configure-client.mdx @@ -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 + + + Olm ID generated by Pangolin to identify the client. + + **Example**: `31frd0uzbjvp721` + + + + A unique secret used to authenticate the client ID with the websocket. + + **Example**: `h51mmlknrvrwv8s4r1i210azhumt6isgbpyavxodibx1k2d6` + + + Keep this secret private and secure. It's used for authentication. + + + + + The endpoint where both Gerbil and Pangolin reside for websocket connections. + + **Example**: `https://pangolin.example.com` + + + + MTU for the WireGuard interface. + + **Default**: `1280` + + + + DNS server to use for resolving the endpoint. + + **Default**: `8.8.8.8` + + + + The log level to use for Olm output. + + **Options**: `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` + + **Default**: `INFO` + + + + Interval for pinging the server. + + **Default**: `3s` + + + + Timeout for each ping. + + **Default**: `5s` + + + + Enable NAT hole punching mode instead of relaying through the VPS. + + **Default**: `false` + + + This is EXPERIMENTAL. While functional, it does not always connect reliably and can fall back to relaying. + + + + + 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` + + + + Path to a configuration file containing the same arguments as command line. + + **Example**: `/etc/olm/config.yaml` + + +## 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. + + + Endpoint of your Pangolin server (equivalent to `--endpoint`) + + + + Olm ID generated by Pangolin (equivalent to `--id`) + + + + Olm secret for authentication (equivalent to `--secret`) + + + + MTU for the WireGuard interface (equivalent to `--mtu`) + + **Default**: `1280` + + + + DNS server to use for resolving the endpoint (equivalent to `--dns`) + + **Default**: `8.8.8.8` + + + + Log level (equivalent to `--log-level`) + + **Default**: `INFO` + + + + Interval for pinging the server (equivalent to `--ping-interval`) + + **Default**: `3s` + + + + Timeout for each ping (equivalent to `--ping-timeout`) + + **Default**: `5s` + + + + Enable NAT hole punching mode (equivalent to `--holepunch`) + + **Default**: `false` + + + + Path to health file for connection monitoring (equivalent to `--health-file`) + + + + Load the config from this file instead of command line arguments (equivalent to `--config-file`) + + + +When both environment variables and CLI arguments are provided, CLI arguments take precedence. + + +## 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 diff --git a/manage/clients/configure-olm.mdx b/manage/clients/configure-olm.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx new file mode 100644 index 0000000..c096761 --- /dev/null +++ b/manage/clients/install-client.mdx @@ -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. + + +You **must first create a client and copy the Olm config** in Pangolin before running Olm. + + +## 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 +``` + + +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. + + +### 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 +``` + + +The quick installer will do this step for you. + + +### 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 +``` + + +Make sure to move the binary to `/usr/local/bin/olm` before creating the service! + + +## 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. diff --git a/manage/clients/install-olm.mdx b/manage/clients/install-olm.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/manage/domains.mdx b/manage/domains.mdx index e69de29..359f83c 100644 --- a/manage/domains.mdx +++ b/manage/domains.mdx @@ -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 + + +SSL certificates are automatically acquired and managed for both CNAME and NS domain types. No additional certificate configuration is required. + + +### 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 + + +Domain delegation is ideal when you want Pangolin to manage your entire domain and all its subdomains. + + +### 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 + + +CNAME domains are useful when your domain is already controlled by another provider but you still want to expose resources via Pangolin. + + +## Adding Domains + +### Pangolin Cloud + +Domains can be added to an organization via the domains section of the organization settings: + + + + Go to your organization settings and select the "Domains" section. + + + + Select either "Domain Delegation" or "Single Domain" based on your needs. + + + + Provide your domain name (e.g., example.com). + + + + Follow the provided instructions to add the required DNS records to your provider. + + + + DNS changes may take time to propagate. The domain will show as verified once propagation is complete. + + + + +Domain delegation and CNAME domains are only available in Pangolin Cloud. Self-hosted Pangolin uses different domain configuration methods. + + +### Self-Hosted Pangolin + +For self-hosted Pangolin, domains are configured differently, though you can still create domains in the UI. + + + + Configure domains via the config file, including certificate resolver settings. + + + + Set up wildcard domains for flexible subdomain management. + + + + +In self-hosted Pangolin, domains do not need individual verification, but you're responsible for ensuring correct DNS records point to your server. + + +## 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 +``` + + +Once DNS is properly configured and propagated, your domain will be verified and ready to use with your Pangolin resources. + diff --git a/manage/high-availability.mdx b/manage/high-availability.mdx index 33d9bdc..a9183dc 100644 --- a/manage/high-availability.mdx +++ b/manage/high-availability.mdx @@ -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. - + Global network of points of presence with automatic failover and routing to your backend services. - - Host your own multiple highly available points of presence with cloud coordination and automatic failover. - - - - Fully self-hosted, self-contained Pangolin server acting as a single point of presence. + + Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits your servers. @@ -23,7 +19,26 @@ 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. + + +Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit. + + ## Contact Us For hybrid deployments, points of presence, and high availability contact us: -- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io) \ No newline at end of file +- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io) diff --git a/manage/points-of-presence.mdx b/manage/points-of-presence.mdx index ecf2ee3..fd29728 100644 --- a/manage/points-of-presence.mdx +++ b/manage/points-of-presence.mdx @@ -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: + + + Handle incoming user requests before routing them to your applications. + -- **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 + + Located regionally to minimize latency for users in different regions. + + + + Multiple locations ensure your applications remain accessible even if individual locations fail. + + + + Verify user identity and enforce access policies before allowing access. + + 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 + + + Request is routed to the closest available point of presence. If one goes down, there is always another point available. + -When a user requests access to your application: + + User identity is verified at the point of presence before getting routed to your backend. + -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 + + Pangolin selects the optimal tunnel route to your backend service. Site tunnel clients (Newt) connect to the optimal point of presence. + - -This routing happens automatically and transparently - users always get the best possible performance without any manual configuration. - - -### 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 + + If the primary tunnel fails, traffic automatically switches to an alternative route. + + ## Advantages of Points of Presence -### Global Performance + + + Users connect to the geographically closest point of presence. + -- **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 + + Automatic selection of the best available tunnel to route to your backend services. + -### High Availability + + Provide ingress to thin-clients on private networks via tunnels. + -- **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 + + Each point of presence continuously monitors its health and connectivity to your backend. + + -### Security and Compliance + + + Multiple points of presence ensure your applications remain accessible during regional outages. + -- **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 + + No single point of failure - if one location goes down, there is always a way back to your application. + + ## 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 - - - Get started with Pangolin Cloud and experience global points of presence with automatic high availability. + + + Global network of points of presence with automatic failover and routing to your backend services. -### Self-Hosted Pangolin + + Host your own multiple points of presence with cloud coordination and automatic failover. Data always transits yours servers. + -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 + + Fully self-hosted, self-contained Pangolin server acting as a single point of presence. + + 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. -### 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 - Hybrid deployment is ideal for organizations that need high availability while maintaining control over their infrastructure and data transit. + +## Contact Us + +For hybrid deployments, points of presence, and high availability contact us: +- **Email**: [numbat@fossorial.io](mailto:numbat@fossorial.io) diff --git a/manage/sites/configure-newt.mdx b/manage/sites/configure-site.mdx similarity index 99% rename from manage/sites/configure-newt.mdx rename to manage/sites/configure-site.mdx index 3b5f971..4a01e8a 100644 --- a/manage/sites/configure-newt.mdx +++ b/manage/sites/configure-site.mdx @@ -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 - 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` -### Optional Arguments - MTU for the internal WireGuard interface. diff --git a/manage/sites/docker-socket.mdx b/manage/sites/docker-socket.mdx deleted file mode 100644 index e69de29..0000000 diff --git a/manage/sites/install-newt.mdx b/manage/sites/install-site.mdx similarity index 99% rename from manage/sites/install-newt.mdx rename to manage/sites/install-site.mdx index ca312e1..899a3dc 100644 --- a/manage/sites/install-newt.mdx +++ b/manage/sites/install-site.mdx @@ -1,5 +1,5 @@ --- -title: "Install Newt" +title: "Install Site" description: "Install Newt as a binary or Docker container" --- diff --git a/manage/sites/update-site.mdx b/manage/sites/update-site.mdx new file mode 100644 index 0000000..9f3fc42 --- /dev/null +++ b/manage/sites/update-site.mdx @@ -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 +``` + + +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. + diff --git a/self-host/.DS_Store b/self-host/.DS_Store index 19e3519..5e7a3f6 100644 Binary files a/self-host/.DS_Store and b/self-host/.DS_Store differ diff --git a/self-host/dns-and-networking.mdx b/self-host/dns-and-networking.mdx index 05cab75..53c5a74 100644 --- a/self-host/dns-and-networking.mdx +++ b/self-host/dns-and-networking.mdx @@ -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: - + **HTTP/SSL Verification** @@ -75,14 +75,22 @@ Pangolin requires these ports to be open on your VPS: - **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. + + + + **Client Tunnels** + + This is the default port for clients relaying through Gerbil to newt. This port is only required for clients. + +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). + + ### Docker Port Exposure By default, Pangolin exposes these ports on all interfaces: diff --git a/self-host/how-to-update.mdx b/self-host/how-to-update.mdx index 58acda7..53d8a8a 100644 --- a/self-host/how-to-update.mdx +++ b/self-host/how-to-update.mdx @@ -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) Look for the latest stable release (not pre-release or beta versions). @@ -55,6 +56,16 @@ services: image: traefik:v3.4.0 # Update if needed # ... 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 + ``` Update each service you want to upgrade. You can update them individually or all at once. diff --git a/self-host/manual/unraid.mdx b/self-host/manual/unraid.mdx index 7d648e0..dbf8349 100644 --- a/self-host/manual/unraid.mdx +++ b/self-host/manual/unraid.mdx @@ -313,6 +313,19 @@ Anywhere you see `http://pangolin:3001` must match. The hostname should be the n **WireGuard Port:** + +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. + + 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:** diff --git a/self-host/system-architecture.mdx b/self-host/system-architecture.mdx new file mode 100644 index 0000000..cb16800 --- /dev/null +++ b/self-host/system-architecture.mdx @@ -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 + + +Pangolin acts as the brain of the system, coordinating all other components and managing user access. + + +### 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 + + +WireGuard provides fast, secure, and reliable tunneling with minimal overhead. + + +### 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 + + +Newt is designed to be resource-efficient and can run on minimal hardware or in containers. + + +### 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 + + +Badger ensures that only authenticated and authorized users can access your applications, even if they bypass other security measures. + + + +Pangolin system architecture diagram +