From 94e991525bc07e81ba7c2740e804e64f6a595f8c Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Fri, 10 Oct 2025 17:14:39 -0400 Subject: [PATCH 1/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 154 +++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 self-host/advanced/proxyprotocol.mdx diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx new file mode 100644 index 0000000..ddb0a13 --- /dev/null +++ b/self-host/advanced/proxyprotocol.mdx @@ -0,0 +1,154 @@ +--- +title: "New file" +description: "Description of your new file." +--- + +# Proxy Protocol (Advanced) + +In Pangolin, make a TCP resource or UDP resource. + +> **Note:** Not all applications support Proxy Protocol. If you send Proxy Protocol headers to an application that isn't configured for it or doesn't support it, the connection will fail entirely. + +--- + +## Creating the Resource + +In Pangolin, go into **Resources** and create a TCP or UDP route like you normally would — pointing it to your resource which accepts Proxy Protocol. + +Say I'm using `tcp-8888` with Pangolin. + +I configure it to hit my Proxy Protocol–enabled service such as Minecraft Paper or Velocity. + +It'll give you a **port** to put into the compose file and an **entryPoint** to add into the `traefik_config.yml`. + +Only do the second, not the first. + +--- + +## Add the EntryPoint + +Add an entrypoint in `traefik_config.yml` for the port you intend to use. + +```yaml +entryPoints: + tcp-22000: + address: ":22000/tcp" +``` + +I'm going to use `tcp-22000` for this, and in Traefik under **Gerbil**, I'm going to add the same mapping: + +```yaml + gerbil: + image: fosrl/gerbil + container_name: gerbil + restart: unless-stopped + ports: + - 51820:51820/udp + - 21820:21820/udp + - 443:443/tcp + - 80:80/tcp + - 22000:22000/tcp +``` + +--- + +## Find the Service Address + +Run the following command: + +```bash +docker exec pangolin curl http://localhost:3001/api/v1/traefik-config | jq +``` + +Look for the entry that resembles: + +```json + "tcp": { + "routers": { + "43-router": { + "entryPoints": [ + "tcp-8888" + ], + "service": "43-service", + "rule": "HostSNI(`*`)" +``` + +Follow this down further until you reach the service line — `43-service` in this example: + +```json + "services": { + "43-service": { + "loadBalancer": { + "servers": [ + { + "address": "100.89.128.4:58655" + } + ] + } + }, +``` + +Make a note of the address there. + +--- + +## Update Dynamic Configuration + +Go into `config/traefik_dynamic.yml` and add: + +### TCP Example + +```yaml +tcp: + routers: + minecraft-rtr: + rule: "HostSNI(`*`)" + entryPoints: + - "tcp-22000" + service: minecraft-svc + services: + minecraft-svc: + loadBalancer: + serversTransport: proxy-protocol-v1 # Can be named anything really as long as it matches the defined transport. + servers: + - address: "100.89.128.4:58655" + serversTransports: + proxy-protocol-v1: + proxyProtocol: + version: 1 +``` + +### UDP Example + +```yaml +tcp: + routers: + servicename-rtr: + entryPoints: + - "udp-22000" + service: servicename-svc + services: + servicename-svc: + loadBalancer: + serversTransport: proxyprotocol-udp + servers: + - address: "100.89.128.4:58655" + serversTransports: + proxyprotocol-udp: + proxyProtocol: + version: 1 +``` + +--- + +## Downstream Applications + +For downstream applications, you'll need to configure them to trust Proxy Protocol connections originating from the system where **Newt** connects to the service. + +For example: + +If the Newt is running on **Host B** at `192.168.1.5`, + +your service on **Host A** at `192.168.1.4` needs to trust `192.168.1.5` as a trusted Proxy Protocol source. + +Once Proxy Protocol is in play, the connection between Traefik and the backend **must** speak Proxy Protocol — otherwise it will refuse to connect. \ No newline at end of file From 80fb604a97ecac96fae5a13a9d4cd49d285a45dc Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Fri, 10 Oct 2025 17:28:10 -0400 Subject: [PATCH 2/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx index ddb0a13..5572980 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/advanced/proxyprotocol.mdx @@ -115,7 +115,7 @@ tcp: serversTransports: proxy-protocol-v1: proxyProtocol: - version: 1 + version: 1 # Velocity can handle v2 also but in in doubt use version over version 2. ``` ### UDP Example From b717bacc7f8d5fcb61a664d5e59d114de4136696 Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Fri, 10 Oct 2025 17:34:40 -0400 Subject: [PATCH 3/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx index 5572980..2649d82 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/advanced/proxyprotocol.mdx @@ -138,9 +138,12 @@ tcp: proxyProtocol: version: 1 ``` +--- +Also do note.. If you change the dummy (8888) info at all for the destination or the port or the site.. you will need to repopulate the info all over again. Starting from the JQ line above. --- + ## Downstream Applications For downstream applications, you'll need to configure them to trust Proxy Protocol connections originating from the system where **Newt** connects to the service. From f1d928d14cf390b1ae20a561e38d780694c6a89c Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Fri, 10 Oct 2025 17:41:35 -0400 Subject: [PATCH 4/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx index 2649d82..048ac08 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/advanced/proxyprotocol.mdx @@ -5,6 +5,8 @@ description: "Description of your new file." # Proxy Protocol (Advanced) +Did you ever want to get the real ip instead of newt's IP or traefik's IP for TCP/UDP applications? Then follow below, Just be warned this is not a begineer guide. + In Pangolin, make a TCP resource or UDP resource. > **Note:** Not all applications support Proxy Protocol. If you send Proxy Protocol headers to an application that isn't configured for it or doesn't support it, the connection will fail entirely. From a470e625b4031e2ea0df9d49e3925a9f30baa8c0 Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Fri, 10 Oct 2025 17:47:11 -0400 Subject: [PATCH 5/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx index 048ac08..08b6a43 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/advanced/proxyprotocol.mdx @@ -7,6 +7,10 @@ description: "Description of your new file." Did you ever want to get the real ip instead of newt's IP or traefik's IP for TCP/UDP applications? Then follow below, Just be warned this is not a begineer guide. +This guide shows how to enable Proxy Protocol manually until a GUI option becomes available. + +⚠️ It’s an advanced setup, so you’ll be editing configuration files and running cli commands. ⚠️ + In Pangolin, make a TCP resource or UDP resource. > **Note:** Not all applications support Proxy Protocol. If you send Proxy Protocol headers to an application that isn't configured for it or doesn't support it, the connection will fail entirely. From 8656085124e029a02ed74c359b539b9458fbe594 Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Fri, 10 Oct 2025 18:43:42 -0400 Subject: [PATCH 6/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx index 08b6a43..9cd2d4e 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/advanced/proxyprotocol.mdx @@ -1,17 +1,17 @@ --- -title: "New file" -description: "Description of your new file." +title: "Proxy Protocol" +description: "Using Proxy Protocol to Preserve Client IPs for TCP/UDP backends" --- # Proxy Protocol (Advanced) -Did you ever want to get the real ip instead of newt's IP or traefik's IP for TCP/UDP applications? Then follow below, Just be warned this is not a begineer guide. +Did you ever want to get the real ip instead of newt's IP or traefik's IP for TCP/UDP applications? Then follow below, Just be warned this is not a begineer guide. This guide shows how to enable Proxy Protocol manually until a GUI option becomes available. ⚠️ It’s an advanced setup, so you’ll be editing configuration files and running cli commands. ⚠️ -In Pangolin, make a TCP resource or UDP resource. +In Pangolin, make a TCP resource or UDP resource. > **Note:** Not all applications support Proxy Protocol. If you send Proxy Protocol headers to an application that isn't configured for it or doesn't support it, the connection will fail entirely. @@ -21,11 +21,11 @@ In Pangolin, make a TCP resource or UDP resource. In Pangolin, go into **Resources** and create a TCP or UDP route like you normally would — pointing it to your resource which accepts Proxy Protocol. -Say I'm using `tcp-8888` with Pangolin. +Say I'm using `tcp-8888` with Pangolin. I configure it to hit my Proxy Protocol–enabled service such as Minecraft Paper or Velocity. -It'll give you a **port** to put into the compose file and an **entryPoint** to add into the `traefik_config.yml`. +It'll give you a **port** to put into the compose file and an **entryPoint** to add into the `traefik_config.yml`. Only do the second, not the first. @@ -144,19 +144,20 @@ tcp: proxyProtocol: version: 1 ``` + --- + Also do note.. If you change the dummy (8888) info at all for the destination or the port or the site.. you will need to repopulate the info all over again. Starting from the JQ line above. --- - ## Downstream Applications For downstream applications, you'll need to configure them to trust Proxy Protocol connections originating from the system where **Newt** connects to the service. -For example: +For example: -If the Newt is running on **Host B** at `192.168.1.5`, +If the Newt is running on **Host B** at `192.168.1.5`, your service on **Host A** at `192.168.1.4` needs to trust `192.168.1.5` as a trusted Proxy Protocol source. From 4474f5f2ac50a88a6807dcf7ab566f2f54ff2224 Mon Sep 17 00:00:00 2001 From: AstralDestiny Date: Sat, 11 Oct 2025 15:56:56 -0400 Subject: [PATCH 7/8] Documentation edits made through Mintlify web editor --- self-host/advanced/proxyprotocol.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/advanced/proxyprotocol.mdx index 9cd2d4e..6efbadb 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/advanced/proxyprotocol.mdx @@ -1,10 +1,8 @@ --- -title: "Proxy Protocol" +title: "Proxy Protocol (Advanced)" description: "Using Proxy Protocol to Preserve Client IPs for TCP/UDP backends" --- -# Proxy Protocol (Advanced) - Did you ever want to get the real ip instead of newt's IP or traefik's IP for TCP/UDP applications? Then follow below, Just be warned this is not a begineer guide. This guide shows how to enable Proxy Protocol manually until a GUI option becomes available. @@ -127,7 +125,7 @@ tcp: ### UDP Example ```yaml -tcp: +udp: routers: servicename-rtr: entryPoints: From e83b9755a5e2d964dc102416286308eef1d4e9c2 Mon Sep 17 00:00:00 2001 From: Owen Date: Sat, 11 Oct 2025 14:29:00 -0700 Subject: [PATCH 8/8] Add to docs.json and small tweaks --- docs.json | 429 +++++++++--------- .../proxyprotocol.mdx | 4 +- 2 files changed, 218 insertions(+), 215 deletions(-) rename self-host/{advanced => community-guides}/proxyprotocol.mdx (94%) diff --git a/docs.json b/docs.json index 3e7d94e..c7621d6 100644 --- a/docs.json +++ b/docs.json @@ -1,216 +1,219 @@ { - "$schema": "https://mintlify.com/docs.json", - "theme": "aspen", - "name": "Pangolin Docs", - "description": "Pangolin is a self-hosted alternative to Cloudflare Tunnels, designed to provide secure and highly-available ingress access to applications.", - "colors": { - "primary": "#F36117", - "light": "#F36117", - "dark": "#F36117" - }, - "banner": { - "content": "We're hiring software engineers! [Click here](https://click.fossorial.io/L0OXr) to get in touch.", - "dismissible": true - }, - "favicon": "/favicon.svg", - "navigation": { - "tabs": [ - { - "tab": "Docs", - "groups": [ - { - "group": "About", - "pages": [ - "about/how-pangolin-works", - "about/pangolin-vs-traditional-reverse-proxy", - "about/pangolin-vs-vpn" + "$schema": "https://mintlify.com/docs.json", + "theme": "aspen", + "name": "Pangolin Docs", + "description": "Pangolin is a self-hosted alternative to Cloudflare Tunnels, designed to provide secure and highly-available ingress access to applications.", + "colors": { + "primary": "#F36117", + "light": "#F36117", + "dark": "#F36117" + }, + "banner": { + "content": "We're hiring software engineers! [Click here](https://click.fossorial.io/L0OXr) to get in touch.", + "dismissible": true + }, + "favicon": "/favicon.svg", + "navigation": { + "tabs": [ + { + "tab": "Docs", + "groups": [ + { + "group": "About", + "pages": [ + "about/how-pangolin-works", + "about/pangolin-vs-traditional-reverse-proxy", + "about/pangolin-vs-vpn" + ] + }, + { + "group": "Pangolin", + "pages": [ + "manage/nodes", + "manage/managed", + { + "group": "Sites", + "pages": [ + "manage/sites/add-site", + "manage/sites/install-site", + "manage/sites/install-kubernetes", + "manage/sites/configure-site", + "manage/sites/update-site" + ] + }, + { + "group": "Resources", + "pages": [ + "manage/resources/targets", + "manage/resources/tcp-udp-resources", + "manage/resources/client-resources" + ] + }, + "manage/healthchecks-failover", + "manage/geoblocking", + "manage/blueprints", + { + "group": "Clients", + "pages": [ + "manage/clients/add-client", + "manage/clients/install-client", + "manage/clients/configure-client" + ] + }, + { + "group": "Access Control", + "pages": [ + "manage/access-control/rules", + "manage/access-control/forwarded-headers", + "manage/access-control/login-page" + ] + }, + { + "group": "Identity Providers", + "pages": [ + "manage/identity-providers/add-an-idp", + "manage/identity-providers/auto-provisioning", + "manage/identity-providers/openid-connect", + "manage/identity-providers/google", + "manage/identity-providers/azure", + "manage/identity-providers/pocket-id", + "manage/identity-providers/zitadel" + ] + }, + "manage/domains", + "manage/integration-api" + ] + }, + { + "group": "Self-host Managed Pangolin", + "pages": [ + "self-host/quick-install-managed", + { + "group": "Manual Installation", + "pages": [ + "self-host/manual/managed" + ] + }, + "self-host/choosing-a-vps", + "self-host/how-to-update" + ] + }, + { + "group": "Community Edition", + "pages": [ + "self-host/quick-install", + { + "group": "Manual Installation", + "pages": [ + "self-host/manual/docker-compose", + "self-host/manual/unraid" + ] + }, + "self-host/dns-and-networking", + "self-host/convert-managed", + "self-host/supporter-program", + "self-host/system-architecture", + { + "group": "Advanced Configuration", + "pages": [ + "self-host/advanced/config-file", + "self-host/advanced/wild-card-domains", + "self-host/advanced/cloudflare-proxy", + "self-host/advanced/without-tunneling", + "self-host/advanced/container-cli-tool", + "self-host/advanced/database-options", + "self-host/advanced/integration-api" + ] + }, + { + "group": "Community Guides", + "pages": [ + "self-host/community-guides/overview", + "self-host/community-guides/proxyprotocol", + "self-host/community-guides/geoblock", + "self-host/community-guides/crowdsec", + "self-host/community-guides/metrics", + "self-host/community-guides/homeassistant", + "self-host/community-guides/middlewaremanager", + "self-host/community-guides/traefiklogsdashboard" + ] + }, + "self-host/telemetry" + ] + }, + { + "group": "Development", + "pages": [ + "development/contributing", + "development/feature-requests-and-bug-reports" + ] + } + ] + }, + { + "tab": "Blog", + "href": "https://digpangolin.com/blog" + } + ], + "global": { + "anchors": [ + { + "anchor": "GitHub", + "href": "https://github.com/fosrl/pangolin", + "icon": "github" + }, + { + "anchor": "Slack", + "href": "https://digpangolin.com/slack", + "icon": "slack" + }, + { + "anchor": "Discord", + "href": "https://digpangolin.com/discord", + "icon": "discord" + }, + { + "anchor": "Support Plans", + "href": "https://digpangolin.com/support", + "icon": "life-ring" + } ] - }, - { - "group": "Pangolin", - "pages": [ - "manage/nodes", - "manage/managed", - { - "group": "Sites", - "pages": [ - "manage/sites/add-site", - "manage/sites/install-site", - "manage/sites/install-kubernetes", - "manage/sites/configure-site", - "manage/sites/update-site" - ] - }, - { - "group": "Resources", - "pages": [ - "manage/resources/targets", - "manage/resources/tcp-udp-resources", - "manage/resources/client-resources" - ] - }, - "manage/healthchecks-failover", - "manage/geoblocking", - "manage/blueprints", - { - "group": "Clients", - "pages": [ - "manage/clients/add-client", - "manage/clients/install-client", - "manage/clients/configure-client" - ] - }, - { - "group": "Access Control", - "pages": [ - "manage/access-control/rules", - "manage/access-control/forwarded-headers", - "manage/access-control/login-page" - ] - }, - { - "group": "Identity Providers", - "pages": [ - "manage/identity-providers/add-an-idp", - "manage/identity-providers/auto-provisioning", - "manage/identity-providers/openid-connect", - "manage/identity-providers/google", - "manage/identity-providers/azure", - "manage/identity-providers/pocket-id", - "manage/identity-providers/zitadel" - ] - }, - "manage/domains", - "manage/integration-api" - ] - }, - { - "group": "Self-host Managed Pangolin", - "pages": [ - "self-host/quick-install-managed", - { - "group": "Manual Installation", - "pages": ["self-host/manual/managed"] - }, - "self-host/choosing-a-vps", - "self-host/how-to-update" - ] - }, - { - "group": "Community Edition", - "pages": [ - "self-host/quick-install", - { - "group": "Manual Installation", - "pages": [ - "self-host/manual/docker-compose", - "self-host/manual/unraid" - ] - }, - "self-host/dns-and-networking", - "self-host/convert-managed", - "self-host/supporter-program", - "self-host/system-architecture", - { - "group": "Advanced Configuration", - "pages": [ - "self-host/advanced/config-file", - "self-host/advanced/wild-card-domains", - "self-host/advanced/cloudflare-proxy", - "self-host/advanced/without-tunneling", - "self-host/advanced/container-cli-tool", - "self-host/advanced/database-options", - "self-host/advanced/integration-api" - ] - }, - { - "group": "Community Guides", - "pages": [ - "self-host/community-guides/overview", - "self-host/community-guides/geoblock", - "self-host/community-guides/crowdsec", - "self-host/community-guides/metrics", - "self-host/community-guides/homeassistant", - "self-host/community-guides/middlewaremanager", - "self-host/community-guides/traefiklogsdashboard" - ] - }, - "self-host/telemetry" - ] - }, - { - "group": "Development", - "pages": [ - "development/contributing", - "development/feature-requests-and-bug-reports" - ] - } - ] - }, - { - "tab": "Blog", - "href": "https://digpangolin.com/blog" - } - ], - "global": { - "anchors": [ - { - "anchor": "GitHub", - "href": "https://github.com/fosrl/pangolin", - "icon": "github" - }, - { - "anchor": "Slack", - "href": "https://digpangolin.com/slack", - "icon": "slack" - }, - { - "anchor": "Discord", - "href": "https://digpangolin.com/discord", - "icon": "discord" - }, - { - "anchor": "Support Plans", - "href": "https://digpangolin.com/support", - "icon": "life-ring" } - ] - } - }, - "logo": { - "light": "/logo/light.png", - "dark": "/logo/dark.png", - "href": "https://docs.digpangolin.com" - }, - "navbar": { - "links": [ - { - "label": "Contact Us", - "href": "mailto:numbat@fossorial.io" - } - ], - "primary": { - "type": "button", - "label": "Pangolin Dashboard", - "href": "https://pangolin.fossorial.io" - } - }, - "footer": { - "socials": { - "github": "https://github.com/fosrl/pangolin", - "linkedin": "https://linkedin.com/company/digpangolin" - } - }, - "integrations": { - "posthog": { - "apiKey": "phc_RIHQ7o2Y2hf8qms2nP62vpoJHEvsrw6TieflQGQO7yI", - "apiHost": "https://digpangolin.com/relay-O7yI" - } - }, - "redirects": [ - { - "source": "/telemetry", - "destination": "/self-host/telemetry" - } - ] -} + }, + "logo": { + "light": "/logo/light.png", + "dark": "/logo/dark.png", + "href": "https://docs.digpangolin.com" + }, + "navbar": { + "links": [ + { + "label": "Contact Us", + "href": "mailto:numbat@fossorial.io" + } + ], + "primary": { + "type": "button", + "label": "Pangolin Dashboard", + "href": "https://pangolin.fossorial.io" + } + }, + "footer": { + "socials": { + "github": "https://github.com/fosrl/pangolin", + "linkedin": "https://linkedin.com/company/digpangolin" + } + }, + "integrations": { + "posthog": { + "apiKey": "phc_RIHQ7o2Y2hf8qms2nP62vpoJHEvsrw6TieflQGQO7yI", + "apiHost": "https://digpangolin.com/relay-O7yI" + } + }, + "redirects": [ + { + "source": "/telemetry", + "destination": "/self-host/telemetry" + } + ] +} \ No newline at end of file diff --git a/self-host/advanced/proxyprotocol.mdx b/self-host/community-guides/proxyprotocol.mdx similarity index 94% rename from self-host/advanced/proxyprotocol.mdx rename to self-host/community-guides/proxyprotocol.mdx index 6efbadb..dc984ca 100644 --- a/self-host/advanced/proxyprotocol.mdx +++ b/self-host/community-guides/proxyprotocol.mdx @@ -1,5 +1,5 @@ --- -title: "Proxy Protocol (Advanced)" +title: "Proxy Protocol" description: "Using Proxy Protocol to Preserve Client IPs for TCP/UDP backends" --- @@ -92,7 +92,7 @@ Follow this down further until you reach the service line — `43-service` in th }, ``` -Make a note of the address there. +Make a note of the address there. Keep in mind that _this address will change if you update the site on the target or change information about the target like the port or IP address or delete the target._ ---