From e1b4f61051cc20631263f868e44805b85bc8f96e Mon Sep 17 00:00:00 2001 From: Wei Wang <62213594+weiw11@users.noreply.github.com> Date: Wed, 26 Nov 2025 12:46:11 -0500 Subject: [PATCH 01/20] docs: clarify blueprint behavior with docker --- manage/blueprints.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/manage/blueprints.mdx b/manage/blueprints.mdx index 97917d1..10edf3d 100644 --- a/manage/blueprints.mdx +++ b/manage/blueprints.mdx @@ -177,6 +177,10 @@ client-resources: For containerized applications, you can define blueprints using Docker labels. + +Blueprints will **continuously apply** from changes in the docker stack, newt restarting, or when viewing the resource in the dashboard. + + ### Enabling Docker Socket Access To use Docker labels, enable the Docker socket when running Newt: @@ -193,6 +197,10 @@ DOCKER_SOCKET=/var/run/docker.sock ### Docker Compose Example + +The compose file will be the source of truth, any edits through the resources dashboard will be **overwritten** by the blueprint labels defined in the compose stack. + + ```yaml services: newt: From 7c3462d7ac55556978c132e49bb16b3e9d620110 Mon Sep 17 00:00:00 2001 From: Wei Wang <62213594+weiw11@users.noreply.github.com> Date: Fri, 28 Nov 2025 21:31:19 -0500 Subject: [PATCH 02/20] docs: fix system diagram in dark mode --- images/system-diagram.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/images/system-diagram.svg b/images/system-diagram.svg index 8f1fb2d..5945064 100644 --- a/images/system-diagram.svg +++ b/images/system-diagram.svg @@ -1,4 +1,4 @@ -
Pangolin
      Gerbil
Newt
http 80
https 443
http 8080
         Traefik
User
User
Edge Server
Cloud VPS
Badger
Websocket
WireGuard
Container
Server
VPN
HTTP
KEY:
 +
Pangolin
Pangolin
      Gerbil
      Gerbil
Newt
Newt
http 80
http 80
https 443
https 443
http 8080
http 8080
         Traefik
         Traefik
User
User
User
User
Edge Server
Edge Server
Cloud VPS
Cloud VPS
Badger
Badger
Websocket
Websocket
WireGuard
WireGuard
Container
Container
Server
Server
VPN
VPN
HTTP
HTTP
KEY:
KEY:Text is not SVG - cannot display \ No newline at end of file From 881d85aad98f680c515507256075b1f915c75311 Mon Sep 17 00:00:00 2001 From: Romain Morlevat <19805656+RomainMorlevat@users.noreply.github.com> Date: Sun, 30 Nov 2025 15:07:48 +0100 Subject: [PATCH 03/20] Fix port number for newt client Screenshot and text are referring to port number 2022 but command line is using port 22. --- manage/resources/client-resources.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage/resources/client-resources.mdx b/manage/resources/client-resources.mdx index 344c0aa..881d3f7 100644 --- a/manage/resources/client-resources.mdx +++ b/manage/resources/client-resources.mdx @@ -65,7 +65,7 @@ Here's how to set up SSH access to your server when connected with a client: When connected with a Olm client, you can SSH to your server using `:2022`. ```bash -ssh user@100.90.128.0 -p 22 +ssh user@100.90.128.0 -p 2022 ``` When accessing a site resource, you use the IP of the site found in the dashboard and the local port you configured for the resource. From 00b7ead6ec366f4cd173da687de2090ff79a974b Mon Sep 17 00:00:00 2001 From: Owen Date: Wed, 3 Dec 2025 13:36:48 -0500 Subject: [PATCH 04/20] Remove volumes from manual docker page --- self-host/manual/docker-compose.mdx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/self-host/manual/docker-compose.mdx b/self-host/manual/docker-compose.mdx index 5cb68b3..03aa833 100644 --- a/self-host/manual/docker-compose.mdx +++ b/self-host/manual/docker-compose.mdx @@ -144,8 +144,6 @@ services: restart: unless-stopped volumes: - ./config:/app/config - - pangolin-data:/var/certificates - - pangolin-data:/var/dynamic healthcheck: test: ["CMD", "curl", "-f", "http://localhost:3001/api/v1/"] interval: "3s" @@ -187,17 +185,12 @@ services: volumes: - ./config/traefik:/etc/traefik:ro # Volume to store the Traefik configuration - ./config/letsencrypt:/letsencrypt # Volume to store the Let's Encrypt certificates - # Shared volume for certificates and dynamic config in file mode - - pangolin-data:/var/certificates:ro - - pangolin-data:/var/dynamic:ro + - ./config/traefik/logs:/var/log/traefik # Volume to store Traefik logs networks: default: driver: bridge name: pangolin - -volumes: - pangolin-data: ``` ## Traefik Static Configuration From b41d2cb4bd7a43eba94941936c61de630caf1466 Mon Sep 17 00:00:00 2001 From: Owen Date: Sat, 6 Dec 2025 17:29:46 -0500 Subject: [PATCH 05/20] Update to usernames --- manage/blueprints.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage/blueprints.mdx b/manage/blueprints.mdx index 10edf3d..ae5dd31 100644 --- a/manage/blueprints.mdx +++ b/manage/blueprints.mdx @@ -356,7 +356,7 @@ Not allowed on TCP/UDP resources. | `basic-auth` | object | No | Basic authentication configuration | Requires `user` and `password` fields | | `sso-enabled` | boolean | No | Enable SSO authentication | Defaults to `false` | | `sso-roles` | array | No | Allowed SSO roles | Cannot include "Admin" role | -| `sso-users` | array | No | Allowed SSO user emails | Must be valid email addresses | +| `sso-users` | array | No | Allowed SSO usernames | Must be valid usernames | | `whitelist-users` | array | No | Whitelisted user emails | Must be valid email addresses | ### Rules Configuration From 97ff3c4d9dd811e7c16ed88ab293f2ad50032eff Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Thu, 11 Dec 2025 17:43:00 -0500 Subject: [PATCH 06/20] update icon --- index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.mdx b/index.mdx index 1ee76a1..98b289c 100644 --- a/index.mdx +++ b/index.mdx @@ -20,7 +20,7 @@ Users access public resources through any web browser with authentication. Users Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access. - + What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs? From 7a06b57ab407a0aa0123cc6242fb81b733938812 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Thu, 11 Dec 2025 21:34:56 -0500 Subject: [PATCH 07/20] remove native --- manage/sites/configure-site.mdx | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/manage/sites/configure-site.mdx b/manage/sites/configure-site.mdx index 361f8cb..2a413d8 100644 --- a/manage/sites/configure-site.mdx +++ b/manage/sites/configure-site.mdx @@ -107,12 +107,6 @@ description: "Configure Newt for connecting to Pangolin sites" **Default**: `false` (clients enabled) - - Use native WireGuard interface (requires WireGuard kernel module and Linux, must run as root). - - **Default**: `false` (uses userspace netstack) - - Name of the WireGuard interface. @@ -277,12 +271,6 @@ When both environment variables and CLI arguments are provided, CLI arguments ta **Default**: `false` - - Use native WireGuard interface (Linux only, equivalent to `--native`) - - **Default**: `false` - - Name of the WireGuard interface (equivalent to `--interface`) From 87437268dc8731c260edbaa96db37b67c1e6858b Mon Sep 17 00:00:00 2001 From: Owen Date: Thu, 11 Dec 2025 23:17:33 -0500 Subject: [PATCH 08/20] Note unicast and ICMP not available --- manage/resources/private/destinations.mdx | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/manage/resources/private/destinations.mdx b/manage/resources/private/destinations.mdx index 81f582e..b67cbc4 100644 --- a/manage/resources/private/destinations.mdx +++ b/manage/resources/private/destinations.mdx @@ -24,4 +24,12 @@ When defining a Resource with a CIDR range, all IP addresses within that range w Pangolin smooths away overlapping networks and arbitrarily chooses a single site to resolve the IP address or range to. This is because we want connection requests to any Resource to be as simple as possible for the end users: when they connect to a particular IP address or FQDN, Pangolin figures out which site to send it to and the end user never needs to figure this out. -It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly defined which host should be used for a given FQDN or IP address and use the alias to connect. \ No newline at end of file +It is recommended that you create overlapping resources only if absolutely required. If you do, use [Aliases](/manage/resources/private/alias) to explicitly defined which host should be used for a given FQDN or IP address and use the alias to connect. + +## Why is ICMP Pinging Not Working? + +Because Newt sites are proxying traffic out of the secure tunnel, ICMP needs to be handled specially just like UDP and TCP. Right now, ICMP **is not supported** through the Pangolin client. If you need to ping hosts on the remote network, consider using TCP or UDP-based tools like `hping3` or `nping` as alternatives. We plan to add ICMP support in a future release. + +## Unicast Only? + +Right now unicast TCP and UDP traffic is supported through the Pangolin client. Multicast and broadcast traffic is not supported at this time. From 9aab7a32347e58436892259d05ba8cbcc3031467 Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Fri, 12 Dec 2025 10:15:48 -0500 Subject: [PATCH 09/20] update nat explanation --- manage/clients/understanding-clients.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 5c7752d..2bced33 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -61,7 +61,9 @@ Clients can relay traffic through a Pangolin server - through Gerbil specificall ### NAT Hole Punching -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. +NAT hole punching establishes a direct peer-to-peer connection between the client and site, bypassing the need to route traffic through the Pangolin server. The server coordinates the initial connection by helping both peers discover each other's network addresses, allowing them to establish a direct tunnel through their respective NATs and firewalls. + +If the site and client are unable to hole punch, they fall back to relaying through your Pangolin server. Take a look at [some things you can do to improve reliability](/manage/sites/configure-site#nat-traversal-tweaks) if you are not getting reliable hole punching. From 2dc9bc14fd2f94bc2ff1ea2db33c7e8a877a9891 Mon Sep 17 00:00:00 2001 From: buildplan <170122315+buildplan@users.noreply.github.com> Date: Sat, 13 Dec 2025 11:37:40 +0000 Subject: [PATCH 10/20] docs: Add missing cap_add configuration to Olm Docker Compose example --- manage/clients/install-client.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index ed21841..94575d5 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -190,6 +190,8 @@ services: container_name: olm restart: unless-stopped network_mode: host + cap_add: + - NET_ADMIN devices: - /dev/net/tun:/dev/net/tun environment: @@ -207,6 +209,8 @@ services: container_name: olm restart: unless-stopped network_mode: host + cap_add: + - NET_ADMIN devices: - /dev/net/tun:/dev/net/tun command: From 8deeb56cbfe8fdb2fe3bef26ed00261cd42c2e10 Mon Sep 17 00:00:00 2001 From: buildplan <170122315+buildplan@users.noreply.github.com> Date: Sat, 13 Dec 2025 15:33:35 +0000 Subject: [PATCH 11/20] fix: extra space before cap_add removed. --- manage/clients/install-client.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 94575d5..474f6c2 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -190,8 +190,8 @@ services: container_name: olm restart: unless-stopped network_mode: host - cap_add: - - NET_ADMIN + cap_add: + - NET_ADMIN devices: - /dev/net/tun:/dev/net/tun environment: @@ -209,8 +209,8 @@ services: container_name: olm restart: unless-stopped network_mode: host - cap_add: - - NET_ADMIN + cap_add: + - NET_ADMIN devices: - /dev/net/tun:/dev/net/tun command: From eb5632b87de01eeeb303b735402f93583f9a61e6 Mon Sep 17 00:00:00 2001 From: buildplan <170122315+buildplan@users.noreply.github.com> Date: Sat, 13 Dec 2025 15:39:39 +0000 Subject: [PATCH 12/20] docs: explain why NET_ADMIN capability is required --- manage/clients/install-client.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 474f6c2..105289c 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -222,6 +222,7 @@ services: **Docker Configuration Notes:** - `network_mode: host` brings the olm network interface to the host system, allowing the WireGuard tunnel to function properly +- `cap_add: - NET_ADMIN` is required to grant the container permission to manage network interfaces - `devices: - /dev/net/tun:/dev/net/tun` is required to give the container access to the TUN device for creating WireGuard interfaces ### Windows Service From bc2da9aa46506e918e2116cfad315d0ce4b1a34d Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Sun, 14 Dec 2025 15:17:20 -0500 Subject: [PATCH 13/20] fix broken link --- index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.mdx b/index.mdx index 98b289c..f36d7ef 100644 --- a/index.mdx +++ b/index.mdx @@ -20,7 +20,7 @@ Users access public resources through any web browser with authentication. Users Learn about the fundamentals of Pangolin and how they work together to provide simple and secure remote access. - + What are the similarities and differences between Pangolin and traditional reverse proxies and VPNs? From 030c2fb7e16fe4d54af26ae2fd0e7bf67a075f9b Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Mon, 15 Dec 2025 22:02:34 -0500 Subject: [PATCH 14/20] add cf ip --- self-host/advanced/cloudflare-proxy.mdx | 34 +++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/self-host/advanced/cloudflare-proxy.mdx b/self-host/advanced/cloudflare-proxy.mdx index 1a40a37..63729b3 100644 --- a/self-host/advanced/cloudflare-proxy.mdx +++ b/self-host/advanced/cloudflare-proxy.mdx @@ -54,3 +54,37 @@ 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. + +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). + +Add the plugin to your Traefik configuration: + +```yaml +experimental: + plugins: + cloudflarewarp: + moduleName: github.com/BetterCorp/cloudflarewarp + version: v1.3.0 + +entryPoints: + websecure: + address: ':443' + http: + middlewares: + - cloudflarewarp@file +``` + +This creates a middleware called `cloudflarewarp` and applies it to the `websecure` entrypoint. + +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 +``` + +After making these changes, restart both Traefik and Pangolin for the configuration to take effect. From c204f971219ec87543e1b05b80b7ad22fbb85792 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20J=C3=BClich?= <63878623+fabianjuelich@users.noreply.github.com> Date: Tue, 16 Dec 2025 21:29:00 +0100 Subject: [PATCH 15/20] Fix typo in Home Assistant path rule --- 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 8e2f471..f45f67a 100644 --- a/manage/access-control/rules.mdx +++ b/manage/access-control/rules.mdx @@ -134,7 +134,7 @@ This table compiles paths that need to be allowed for various apps to work with | **Notifications** | | | Gotify | `/version`
`/message`
`/application`
`/client`
`/stream`
`/plugin`
`/health` | | **Home Automation** | | -| Home Assistant | `/api/*`
`/auth/*`
`/frontend_latest/*`
`/lovelace*`
`/static/*`
`/hacsfiles/*`
`/local/*` | +| Home Assistant | `/api/*`
`/auth/*`
`/frontend_latest/*`
`/lovelace/*`
`/static/*`
`/hacsfiles/*`
`/local/*` | | n8n | `/webhook-test/*/webhook`
`/webhook/*/webhook` | | **Project Management** | | | Jetbrains Youtrack | `/api/*`
`/hub/api/*`
| From e3ad995976cc22d55a2f9cd851f2663842b854e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20J=C3=BClich?= <63878623+fabianjuelich@users.noreply.github.com> Date: Tue, 16 Dec 2025 21:36:01 +0100 Subject: [PATCH 16/20] Add additional Home Assistant path rules Required for proper Home Assistant frontend and mobile app behavior. --- 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 8e2f471..ad808de 100644 --- a/manage/access-control/rules.mdx +++ b/manage/access-control/rules.mdx @@ -134,7 +134,7 @@ This table compiles paths that need to be allowed for various apps to work with | **Notifications** | | | Gotify | `/version`
`/message`
`/application`
`/client`
`/stream`
`/plugin`
`/health` | | **Home Automation** | | -| Home Assistant | `/api/*`
`/auth/*`
`/frontend_latest/*`
`/lovelace*`
`/static/*`
`/hacsfiles/*`
`/local/*` | +| Home Assistant | `/api/*`
`/auth/*`
`/frontend_latest/*`
`/lovelace*`
`/static/*`
`/hacsfiles/*`
`/local/*`
`/manifest.json`
`/sw-modern.js` | | n8n | `/webhook-test/*/webhook`
`/webhook/*/webhook` | | **Project Management** | | | Jetbrains Youtrack | `/api/*`
`/hub/api/*`
| From b8375dd5b16c865d1f61f01292e13e8a5a69092e Mon Sep 17 00:00:00 2001 From: miloschwartz Date: Tue, 16 Dec 2025 23:06:54 -0500 Subject: [PATCH 17/20] add raw resources redirect --- docs.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 44c2839..6fcc451 100644 --- a/docs.json +++ b/docs.json @@ -278,6 +278,10 @@ { "source": "/community/:slug*", "destination": "/self-host/:slug*" + }, + { + "source": "/manage/resources/tcp-udp-resources", + "destination": "/manage/resources/public/raw-resources" } ], "seo": { @@ -285,4 +289,4 @@ "canonical": "https://docs.pangolin.net" } } -} \ No newline at end of file +} From 4c9654a9ee082b930246181ad8a63f92ca45af4f Mon Sep 17 00:00:00 2001 From: R2-D2 Date: Sat, 20 Dec 2025 02:04:33 +0500 Subject: [PATCH 18/20] Fix typo reccomend -> recommend --- manage/clients/understanding-clients.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage/clients/understanding-clients.mdx b/manage/clients/understanding-clients.mdx index 2bced33..7dd7e1b 100644 --- a/manage/clients/understanding-clients.mdx +++ b/manage/clients/understanding-clients.mdx @@ -47,7 +47,7 @@ Examples include: - **CICD**: Access remote resources like a database in an automated deployment pipeline. - **Servers**: Provide a VPS with access to a resource running in a different network. -Though you may connect a server via a user account using a CLI client, we reccomend you specifically use a machine client. +Though you may connect a server via a user account using a CLI client, we recommend you specifically use a machine client. Machine clients authenticate with an ID and secret string. These credentials are passed via arguments into one of the supported Pangolin CLI clients. They can be revoked and rotated. From 2a2a211866483fa520f2be256803368326573d0c Mon Sep 17 00:00:00 2001 From: Owen Date: Sat, 20 Dec 2025 21:06:09 -0500 Subject: [PATCH 19/20] Update to put --- manage/blueprints.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage/blueprints.mdx b/manage/blueprints.mdx index abbdb08..cc8892f 100644 --- a/manage/blueprints.mdx +++ b/manage/blueprints.mdx @@ -49,7 +49,7 @@ YAML config can be applied using Docker labels, API, from a Newt site, or in the You can also apply blueprints directly through the Pangolin API with an API key. [Take a look at the API documentation for more details.](https://api.pangolin.net/v1/docs/#/Organization/put_org__orgId__blueprint) - POST to `/org/{orgId}/blueprint` with a base64 encodes JSON body like the following: + PUT to `/org/{orgId}/blueprint` with a base64 encodes JSON body like the following: ```json { From 7c02b9165062f8993252cfe89f43a50962ba1863 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joda=20St=C3=B6=C3=9Fer?= Date: Mon, 22 Dec 2025 03:53:28 +0800 Subject: [PATCH 20/20] docs: remove superfluous character from install-client.mdx --- manage/clients/install-client.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/manage/clients/install-client.mdx b/manage/clients/install-client.mdx index 105289c..631e6fd 100644 --- a/manage/clients/install-client.mdx +++ b/manage/clients/install-client.mdx @@ -130,7 +130,7 @@ curl -fsSL https://static.pangolin.net/get-olm.sh | bash #### Windows -If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest).V +If you would like to use Olm on Windows, wintun.dll is required. Please use latest installer from [GitHub releases](https://github.com/fosrl/olm/releases/latest). #### Manual Download