From 2e78175d1a4f944ecb70076610ae18ccbe226fd9 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Sun, 21 Dec 2025 16:41:54 -0500 Subject: [PATCH 01/13] update cloudflare proxy docs --- self-host/advanced/cloudflare-proxy.mdx | 77 +++++++++++++++++++------ 1 file changed, 60 insertions(+), 17 deletions(-) diff --git a/self-host/advanced/cloudflare-proxy.mdx b/self-host/advanced/cloudflare-proxy.mdx index 63729b3..96ef504 100644 --- a/self-host/advanced/cloudflare-proxy.mdx +++ b/self-host/advanced/cloudflare-proxy.mdx @@ -57,34 +57,77 @@ gerbil: ### Getting the Real Client IP -Pangolin needs to know the original client IP address for features like rate limiting. When Cloudflare proxy is enabled, the API server sees Cloudflare's IP instead of the real client IP. +Pangolin needs to know the original client IP address for features like rate limiting and logging. When Cloudflare proxy is enabled, the API server sees Cloudflare's IP instead of the real client IP. -Cloudflare sets special headers with the real IP that need to be processed by Traefik before forwarding to Pangolin. Configure Traefik to parse these headers using a community plugin for Traefik: [Real IP from Cloudflare Proxy Tunnel](https://plugins.traefik.io/plugins/62e97498e2bf06d4675b9443/real-ip-from-cloudflare-proxy-tunnel). +**Badger**, Pangolin's middleware for Traefik, automatically handles Cloudflare proxy IP extraction. Badger versions 1.3.0 and later automatically: +- Trust Cloudflare IP ranges +- Extract the real client IP from the `CF-Connecting-IP` header +- Set `X-Real-IP` and `X-Forwarded-For` headers for downstream services -Add the plugin to your Traefik configuration: + +**Automatic Configuration**: Pangolin installer versions 1.14.0 and greater automatically add Badger to all Pangolin routes in Traefik. If you're using a newer installer, no manual configuration is needed. + -```yaml -experimental: - plugins: - cloudflarewarp: - moduleName: github.com/BetterCorp/cloudflarewarp - version: v1.3.0 +#### Manual Configuration -entryPoints: - websecure: - address: ':443' - http: +If you're using an older installer or need to manually configure Badger, add it to your Traefik configuration. Badger must be applied to all routers that handle Pangolin traffic (API, dashboard, and WebSocket routes): + +```yaml title="dynamic_config.yml" +http: + middlewares: + badger: + plugin: + badger: + disableForwardAuth: true + + routers: + # Next.js router (handles dashboard) + next-router: + rule: "Host(`pangolin.example.com`) && !PathPrefix(`/api/v1`)" + service: next-service + entryPoints: + - websecure middlewares: - - cloudflarewarp@file + - badger + tls: + certResolver: letsencrypt + + # API router (handles /api/v1 paths) + api-router: + rule: "Host(`pangolin.example.com`) && PathPrefix(`/api/v1`)" + service: api-service + entryPoints: + - websecure + middlewares: + - badger + tls: + certResolver: letsencrypt + + # WebSocket router + ws-router: + rule: "Host(`pangolin.example.com`)" + service: api-service + entryPoints: + - websecure + middlewares: + - badger + tls: + certResolver: letsencrypt ``` -This creates a middleware called `cloudflarewarp` and applies it to the `websecure` entrypoint. +**Why Badger is needed**: When `disableForwardAuth: true` is set, Badger extracts the real client IP from Cloudflare proxy headers without performing authentication. This is necessary because forward authentication is only needed for resources controlled by Pangolin, not for the main application routes. However, the main Pangolin containers and APIs still need the real client IP for proper rate limiting and IP tracking. + +#### Pangolin Configuration + +Set `trust_proxy: 2` in your Pangolin config file. This tells Pangolin to trust the second-level proxy (Traefik is proxy 1, Cloudflare is proxy 2): -Then set `trust_proxy: 2` in your Pangolin config file. This tells Pangolin to trust the second-level proxy (Traefik is proxy 1, Cloudflare is proxy 2): -1 ```yaml server: trust_proxy: 2 ``` + +**Update Badger**: Ensure you're running Badger version 1.3.0 or later to get real IP addresses in logs for Public resources. Update Badger if you're using an older version. + + After making these changes, restart both Traefik and Pangolin for the configuration to take effect. From 4258fd03aa54ce8d4b3a1cfa0b9b33310f9fb3ad Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Mon, 22 Dec 2025 12:23:30 -0500 Subject: [PATCH 02/13] fix broken clients link --- about/how-pangolin-works.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/about/how-pangolin-works.mdx b/about/how-pangolin-works.mdx index 6e7a254..75cbc1f 100644 --- a/about/how-pangolin-works.mdx +++ b/about/how-pangolin-works.mdx @@ -66,7 +66,7 @@ Users authenticate through the client using their accounts. Machines connect wit Clients are available for Mac, Windows, and Linux. They work transparently with applications, so no application configuration is required. - + Learn about clients and where to download them for Mac, Windows, and Linux. From cb561922ca04f140dcbd41832d7bb490780d6f0b Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 23 Dec 2025 11:52:23 -0500 Subject: [PATCH 03/13] Add node about remote nodes --- manage/resources/public/maintenance.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/manage/resources/public/maintenance.mdx b/manage/resources/public/maintenance.mdx index 2fc4e38..31db1e3 100644 --- a/manage/resources/public/maintenance.mdx +++ b/manage/resources/public/maintenance.mdx @@ -36,3 +36,7 @@ In forced mode, the maintenance page is displayed to all users regardless of the #### Automatic In automatic mode, the maintenance page is shown only when all targets associated with the resource are unhealthy or all of the sites are offline. This is useful for unplanned outages and can be used to inform the user that the resource is temporarily unavailable by customizing the above settings. + +## Remote Nodes + +Maintenance pages do not work on remote nodes at this time. From 7f561fc01692d7e5d4fa120018149814f143b12f Mon Sep 17 00:00:00 2001 From: Milo Schwartz Date: Thu, 25 Dec 2025 22:45:54 -0500 Subject: [PATCH 04/13] Update README.md --- README.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/README.md b/README.md index cf983ec..9850e31 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,5 @@ # Pangolin Documentation -Welcome to the official documentation for [Pangolin](https://github.com/fosrl/pangolin), a modern reverse proxy and networking solution. This documentation site is hosted at [docs.pangolin.net](https://docs.pangolin.net) and provides comprehensive guides, API references, and resources for getting started with Pangolin. - -## About This Documentation - -This documentation covers everything you need to know about Pangolin, including: -- Installation and setup guides -- Configuration options -- API reference -- Self-hosting instructions -- Development and contribution guidelines - -All contributions to improve this documentation are welcome! Feel free to submit issues or pull requests to help make these docs better for everyone. - -## Development & Contributing - This documentation site is built using [Mintlify](https://mintlify.com). If you'd like to contribute to the documentation or run it locally for development, follow the instructions below. ### Local Development From 1facaf44f02acf43d4ba735ca8c141dc59f82368 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Mon, 29 Dec 2025 10:20:57 -0500 Subject: [PATCH 05/13] add missing badger middlwares --- self-host/advanced/integration-api.mdx | 1 + self-host/manual/docker-compose.mdx | 11 +++++++++++ self-host/manual/unraid.mdx | 11 +++++++++++ 3 files changed, 23 insertions(+) diff --git a/self-host/advanced/integration-api.mdx b/self-host/advanced/integration-api.mdx index 207707d..b804467 100644 --- a/self-host/advanced/integration-api.mdx +++ b/self-host/advanced/integration-api.mdx @@ -35,6 +35,7 @@ Add the following configuration to your `config/traefik/dynamic_config.yml` to e - web middlewares: - redirect-to-https + - badger # If you have Badger >=1.3.0 and it's enabled in the middlewares section of the dynamic config int-api-router: rule: "Host(`api.example.com`)" diff --git a/self-host/manual/docker-compose.mdx b/self-host/manual/docker-compose.mdx index 9954d1a..ae6ed4f 100644 --- a/self-host/manual/docker-compose.mdx +++ b/self-host/manual/docker-compose.mdx @@ -254,6 +254,10 @@ Create `config/traefik/dynamic_config.yml`: ```yaml title="config/traefik/dynamic_config.yml" http: middlewares: + badger: + plugin: + badger: + disableForwardAuth: true redirect-to-https: redirectScheme: scheme: https @@ -267,6 +271,7 @@ http: - web middlewares: - redirect-to-https + - badger # Next.js router (handles everything except API and WebSocket paths) next-router: @@ -274,6 +279,8 @@ http: service: next-service entryPoints: - websecure + middlewares: + - badger tls: certResolver: letsencrypt @@ -283,6 +290,8 @@ http: service: api-service entryPoints: - websecure + middlewares: + - badger tls: certResolver: letsencrypt @@ -292,6 +301,8 @@ http: service: api-service entryPoints: - websecure + middlewares: + - badger tls: certResolver: letsencrypt diff --git a/self-host/manual/unraid.mdx b/self-host/manual/unraid.mdx index 79e29f1..61e8b37 100644 --- a/self-host/manual/unraid.mdx +++ b/self-host/manual/unraid.mdx @@ -170,6 +170,10 @@ The domain you enter here is what will be used to access the main Pangolin dashb ```yaml title="pangolin/config/traefik/dynamic_config.yml" http: middlewares: + badger: + plugin: + badger: + disableForwardAuth: true redirect-to-https: redirectScheme: scheme: https @@ -183,6 +187,7 @@ http: - web middlewares: - redirect-to-https + - badger # Next.js router (handles everything except API and WebSocket paths) next-router: @@ -190,6 +195,8 @@ http: service: next-service entryPoints: - websecure + middlewares: + - badger tls: certResolver: letsencrypt @@ -199,6 +206,8 @@ http: service: api-service entryPoints: - websecure + middlewares: + - badger tls: certResolver: letsencrypt @@ -208,6 +217,8 @@ http: service: api-service entryPoints: - websecure + middlewares: + - badger tls: certResolver: letsencrypt From 55cfa50fd64d1a2f3dec99bc1b2a8b025595d8d7 Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 30 Dec 2025 16:43:56 -0500 Subject: [PATCH 06/13] Fix bad link --- additional-resources/trust-center.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/additional-resources/trust-center.mdx b/additional-resources/trust-center.mdx index ce9df79..5be1101 100644 --- a/additional-resources/trust-center.mdx +++ b/additional-resources/trust-center.mdx @@ -6,4 +6,4 @@ icon: "scale-balanced" - [Terms of Service](https://pangolin.net/terms-of-service.html) - [Privacy Policy](https://pangolin.net/privacy-policy.html) - [AGLPv3](https://www.gnu.org/licenses/gpl-3.0.en.html) -- [Fossorial Commercial License (FCL)](https://pangolin.net/fcl.hmtl) +- [Fossorial Commercial License (FCL)](https://pangolin.net/fcl.html) From 894b991b74c190e448d1c2ce065211dc0e669c42 Mon Sep 17 00:00:00 2001 From: Owen Date: Sun, 11 Jan 2026 13:26:50 -0800 Subject: [PATCH 07/13] Clarify donations --- self-host/supporter-program.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-host/supporter-program.mdx b/self-host/supporter-program.mdx index d6348a5..e432e91 100644 --- a/self-host/supporter-program.mdx +++ b/self-host/supporter-program.mdx @@ -79,7 +79,7 @@ Pangolin self-hosted will always be free and open source, but maintaining the pr -Github sponsors does not currently support other payment methods but we can process these things manually and send you a key. Please reach out to contact@pangolin.net and we will get you sorted. +Github sponsors does not currently support other payment methods. We hope to add more options in the future. **Unlimited usage** From ec2dae303c2ab8d147cebece17ded6df4873c9c5 Mon Sep 17 00:00:00 2001 From: Owen Date: Tue, 13 Jan 2026 11:32:07 -0800 Subject: [PATCH 08/13] Add role to forwarded headers --- manage/access-control/forwarded-headers.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/manage/access-control/forwarded-headers.mdx b/manage/access-control/forwarded-headers.mdx index bdc5a1f..7e2d695 100644 --- a/manage/access-control/forwarded-headers.mdx +++ b/manage/access-control/forwarded-headers.mdx @@ -18,6 +18,7 @@ Pangolin forwards the following headers to your backend when user identity is av | `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` | +| `Remote-Role` | User's role or group membership | `admin` | ## Authentication Methods From bc3f0bc529a00f1107167243d85a616ffcc1f59c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Anto=20Kein=C3=A4nen?= Date: Thu, 15 Jan 2026 19:37:15 +0200 Subject: [PATCH 09/13] Fix: broken yaml indentation --- manage/sites/install-kubernetes.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/manage/sites/install-kubernetes.mdx b/manage/sites/install-kubernetes.mdx index 12c5cc2..f0fb719 100644 --- a/manage/sites/install-kubernetes.mdx +++ b/manage/sites/install-kubernetes.mdx @@ -41,13 +41,13 @@ All Fossorial Helm charts are available on Artifact Hub. See From 25fa50866ecb19c50e82a60bcbed72cc8cc816d9 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Thu, 15 Jan 2026 21:39:35 -0800 Subject: [PATCH 10/13] remove dns from config file --- self-host/advanced/config-file.mdx | 32 ------------------------------ 1 file changed, 32 deletions(-) diff --git a/self-host/advanced/config-file.mdx b/self-host/advanced/config-file.mdx index 1b22786..7af91be 100644 --- a/self-host/advanced/config-file.mdx +++ b/self-host/advanced/config-file.mdx @@ -791,38 +791,6 @@ This section contains the complete reference for all configuration options in `c -### DNS Configuration - - - DNS settings for domain name resolution and CNAME extensions. - - - - List of nameservers used for DNS resolution. - - **Example**: `["ns1.example.com", "ns2.example.com"]` - - **Default**: `["ns1.pangolin.net", "ns2.pangolin.net", "ns3.pangolin.net"]` - - - These nameservers are used for DNS queries and domain resolution. - - - - - Domain extension used for CNAME record management. - - **Example**: `cname.example.com` - - **Default**: `cname.pangolin.net` - - - Used for creating CNAME records for dynamic domain routing. - - - - - ## Environment Variables Some configuration values can be set using environment variables for enhanced security: From 9c48b125ae15bea177e559607d41c72cc55db255 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Fri, 16 Jan 2026 20:36:43 -0800 Subject: [PATCH 11/13] update ee --- self-host/enterprise-edition.mdx | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/self-host/enterprise-edition.mdx b/self-host/enterprise-edition.mdx index 8f3c5ab..18c5821 100644 --- a/self-host/enterprise-edition.mdx +++ b/self-host/enterprise-edition.mdx @@ -27,7 +27,7 @@ The Enterprise Edition is distributed under the **Fossorial Commercial License** **Free for individuals and small businesses** - - **Revenue threshold**: Less than $100,000 USD annual revenue + - **Revenue threshold**: Less than $100,000 USD gross annual revenue - **License cost**: Free - **Features**: Full access to all "Paid Features" - **Usage**: Personal and small business use allowed @@ -40,7 +40,7 @@ The Enterprise Edition is distributed under the **Fossorial Commercial License** **Larger businesses require a paid license** - - **Revenue threshold**: $100,000+ USD annual revenue + - **Revenue threshold**: $100,000+ USD gross annual revenue - **License cost**: Paid license required - **Features**: Full access to all "Paid Features" - **Usage**: Business use with commercial terms @@ -189,4 +189,14 @@ Include your organization details and use case for faster assistance. Personal use is explicitly allowed under the free license terms. + + + **No exceptions - same license terms apply** + + Educational institutions, non-profit organizations, and government entities are subject to the same license terms as all other organizations. There are no special exceptions or discounts for these groups. + + + If you have questions about how your organization's revenue is calculated for licensing purposes, contact [sales@pangolin.net](mailto:sales@pangolin.net). + + From d19a0705b792b0a822e3560fd9bb8f19228d5050 Mon Sep 17 00:00:00 2001 From: Floordb <100075319+Floordb@users.noreply.github.com> Date: Sat, 17 Jan 2026 08:19:39 +0100 Subject: [PATCH 12/13] Correct CIDR example IP address in documentation --- manage/access-control/rules.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage/access-control/rules.mdx b/manage/access-control/rules.mdx index b7993e7..052053f 100644 --- a/manage/access-control/rules.mdx +++ b/manage/access-control/rules.mdx @@ -71,7 +71,7 @@ CIDR (Classless Inter-Domain Routing) notation specifies IP address ranges using **Examples:** -- `144.234.11.22/24` - Matches all 256 IPs from 192.168.1.0 to 192.168.1.255 +- `192.168.1.0/0` - Matches all 256 IPs from 192.168.1.0 to 192.168.1.255 - `10.0.0.0/8` - Matches any IP starting with 10 (16.7 million addresses) - `2001:db8::/32` - Matches a range of IPv6 addresses - `0.0.0.0/0` - Matches all IPv4 addresses From 276538471abf0f837900af74947d11be64c96f3e Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 19 Jan 2026 17:03:34 -0800 Subject: [PATCH 13/13] Add min windows version Fixes https://github.com/fosrl/olm/issues/45 --- manage/clients/install-client.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 631e6fd..b6391d9 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -227,7 +227,9 @@ services: ### 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: +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. + +Minimum Windows version: Windows 10 #### Service Management Commands