[PR #2490] (feat) DNS Authority #25471

New Issue

2026-06-07T20:01:42-05:00

GiteaMirror commented

2026-06-07 20:01:42 -05:00

📋 Pull Request Information

Original PR: https://github.com/fosrl/pangolin/pull/2490
Author: @mattv8
Created: 2/17/2026
Status: 🔄 Open

Base: dev ← Head: dns-authority

📝 Commits (10+)

527d4cc Merge pull request #3215 from fosrl/dev
8b50f1f Merge pull request #3218 from fosrl/dev
7fa1180 Merge pull request #3221 from fosrl/dev
dacdcf4 DNS authority management and features
90a1c24 Add TLS certificate handling to auth proxy configuration
d1440b5 Update target URL scheme to use method from target configuration
18ac6ad Add multi-target, path routing, and proxy settings to auth config
b8b69a5 Add targetUrl for backward compatibility in ResourceAuthConfig
0fdaf3e feat(dns): include sticky metadata in authority config
7eb86df feat(dns): persist target latency and fold migration into 1.16.0

📊 Changes

39 files changed (+2820 additions, -40 deletions)

View changed files

📝 messages/en-US.json (+42 -0)
📝 package.json (+3 -3)
📝 server/db/pg/schema/schema.ts (+13 -1)
📝 server/db/sqlite/schema/schema.ts (+17 -1)
📝 server/internalServer.ts (+9 -2)
➕ server/lib/jwtKeypair.ts (+131 -0)
📝 server/lib/readConfigFile.ts (+1 -0)
📝 server/lib/traefik/TraefikConfigManager.ts (+223 -0)
📝 server/openApi.ts (+2 -1)
➕ server/routers/auth/authProxy.ts (+413 -0)
📝 server/routers/auth/index.ts (+3 -1)
➕ server/routers/auth/validateSession.ts (+132 -0)
➕ server/routers/dns/dnsAuthority.ts (+713 -0)
📝 server/routers/external.ts (+3 -0)
📝 server/routers/internal.ts (+9 -0)
📝 server/routers/newt/getNewtToken.ts (+71 -1)
➕ server/routers/newt/handleAuthProxyStatusMessage.ts (+41 -0)
➕ server/routers/newt/handleDnsStatusMessage.ts (+57 -0)
📝 server/routers/newt/handleNewtRegisterMessage.ts (+58 -0)
📝 server/routers/newt/index.ts (+2 -0)

...and 19 more files

📄 Description

Community Contribution License Agreement

By creating this pull request, I grant the project maintainers an unlimited,
perpetual license to use, modify, and redistribute these contributions under any terms they
choose, including both the AGPLv3 and the Fossorial Commercial license terms. I
represent that I have the right to grant this license for all contributed content.

Description

This adds DNS Authority and Auth Proxy support to Pangolin. The companion Newt PR is https://github.com/fosrl/newt/pull/236. I opened a discussion about this beforehand. Read more about my motivation for building this feature there.

What this does

Pangolin builds authoritative DNS zone configs and pushes them to Newt over WebSocket. Newt binds port 53 and serves A/NS/SOA responses. The DNS answers use the Site's public IP (not the internal target IP); the idea is that DNS controls which site the user's traffic reaches, and then Traefik/the tunnel handles proxying to the actual backend.

There are two layers, and they can operate independently or together:

Domain-level zones: work with existing wildcard domains. When you enable DNS Authority on a Site and set its public IP, Pangolin finds every wildcard domain that has Resources with Targets on that Site. For each domain it builds a *.baseDomain zone containing all DNS-Authority-enabled Sites as targets. Health is aggregated at the Site level a Site is considered healthy for a domain if any of its Targets across Resources on that domain are healthy. This is the "just turn it on" mode: no per-Resource config needed, and it covers every subdomain under the wildcard automatically.

Per-resource zones: give finer control. Enabling dnsAuthorityEnabled on a specific Resource creates a zone for that Resource's fullDomain (e.g., app.docker.example.com). Unlike domain-level, health is tracked per-Target (not per-Site), and the user can configure a custom TTL (10–86400s) and routing policy (failover, round-robin, or priority). This works with any domain type, not just wildcards.

Zone configs are rebuilt and pushed to each Newt agent: Site DNS Authority toggle, Resource update, Target create/update/delete, health check status change, and Newt reconnect (which gets the full set of zones immediately).

Auth Proxy: Pangolin also pushes auth proxy configs so Newt can enforce SSO at the edge. Newt tries local JWT verification first using an RSA public key from Pangolin (sub-ms), then falls back to the Pangolin session validation API if needed.

How it works

graph LR
    %% Layout Adjustment
    User((User))

    subgraph "Central Control Plane"
        P[Pangolin Dashboard]
        DB[(PostgreSQL)]
        P <--> DB
    end

    subgraph "Site A (Primary Network)"
        direction LR
        N1[Newt Agent A]
        S1[App Service]
        N1 -- "Health Check" --> S1
    end

    subgraph "Site B (Redundant Network)"
        direction LR
        N2[Newt Agent B]
        S2[Redundant App Service]
        N2 -- "Health Check" --> S2
    end

    %% State Sync (Hidden/Top)
    P ==>|"WebSocket Sync"| N1
    P ==>|"WebSocket Sync"| N2

    %% Step 1 & 2: DNS Resolution
    User -- "1. DNS Query" --> N1
    N1 -- "2. IP Resolution" --> User

    %% Step 3 & 4: Traffic Flow
    User -- "3. HTTPS Request" --> N1
    User -.-> |"Failover Request"| N2
    N1 -- "4. Auth Proxy" --> S1
    N2 -- "4. Auth Proxy" --> S2

Schema changes

Migration 1.16.0 (I am assuming this warrants a version up) adds columns to sites (publicIp, dnsAuthorityEnabled, dnsStatus, dnsError) and resources (dnsAuthorityEnabled, dnsAuthorityTtl, dnsAuthorityRoutingPolicy). Both PG and SQLite migrations are included. Everything defaults to off (backwards compatibility).

Backward compatibility

All new behavior is behind dnsAuthorityEnabled toggles on both sites and resources. Existing deployments are unaffected; nothing activates until a user explicitly enables it.

Documentation

This feature will need docs at https://docs.pangolin.net/manage/dns-authority (placeholder links are in the code). I'm happy to write those once (if) the approach is agreed upon.

How to test?

Option 1: Full local test stack

There's a complete end-to-end test stack in mattv8/pangolin-testing that spins up PostgreSQL, Pangolin, Gerbil, two Newt instances, two backends, and a test client on a Docker bridge network.

git clone https://github.com/mattv8/pangolin-testing testing
cd testing/
sudo modprobe wireguard    # required for Gerbil
docker compose down -v && docker compose up -d
docker compose ps          # wait for all services healthy
bash scripts/bootstrap.sh  # creates admin, org, sites, resource, targets

The bootstrap script enables DNS Authority, creates two sites with public IPs, and verifies resolution:

dig @localhost -p 5353 app.test.dev A +short       # 172.28.0.10
dig @localhost -p 5354 app.test.dev A +short       # 172.28.0.10
dig @localhost -p 5353 anything.test.dev A +short  # 172.28.0.10 (wildcard)

Failover test:

docker compose stop backend
dig @localhost -p 5353 app.test.dev A +short       # secondary IP
docker compose start backend

Auth proxy test:

curl -sI http://localhost:8080/ | grep Location    # 302 redirect to login

See the testing README for the full architecture diagram and service map.

Option 2: Drop-in to an existing stack

Pangolin swap the image in your docker-compose.yml:

image: hub.docker.visnovsky.us/library/pangolin:dns-authority-dev

docker compose pull pangolin && docker compose up -d pangolin

Newt install the pre-compiled binary:

sudo cp /usr/local/bin/newt /usr/local/bin/newt.official
curl -fsSL https://raw.githubusercontent.com/mattv8/pangolin-testing/main/scripts/get-newt.sh | bash
sudo systemctl restart newt

Rollback:

sudo cp /usr/local/bin/newt.official /usr/local/bin/newt && sudo systemctl restart newt

Then enable DNS Authority on a site (set public IP), and optionally on individual resources, through the UI.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/fosrl/pangolin/pull/2490 **Author:** [@mattv8](https://github.com/mattv8) **Created:** 2/17/2026 **Status:** 🔄 Open **Base:** `dev` ← **Head:** `dns-authority` --- ### 📝 Commits (10+) - [`527d4cc`](https://github.com/fosrl/pangolin/commit/527d4cc7774eee79aa497ec2ed518e1b6451fa7a) Merge pull request #3215 from fosrl/dev - [`8b50f1f`](https://github.com/fosrl/pangolin/commit/8b50f1fb65d384639cad231eb3ea0675e53664ef) Merge pull request #3218 from fosrl/dev - [`7fa1180`](https://github.com/fosrl/pangolin/commit/7fa1180d102be2abc89c44c528a209e1f0a4b834) Merge pull request #3221 from fosrl/dev - [`dacdcf4`](https://github.com/fosrl/pangolin/commit/dacdcf438bdcaf786a60f3e0c0c538b6d9964bbe) DNS authority management and features - [`90a1c24`](https://github.com/fosrl/pangolin/commit/90a1c246ea6840fa21327ff503770b5792f44c66) Add TLS certificate handling to auth proxy configuration - [`d1440b5`](https://github.com/fosrl/pangolin/commit/d1440b5d3ecf3c6296409950f381f5591e61a7a2) Update target URL scheme to use method from target configuration - [`18ac6ad`](https://github.com/fosrl/pangolin/commit/18ac6ad55a2364fcf8c2ea0cdd55b829ccecfbb7) Add multi-target, path routing, and proxy settings to auth config - [`b8b69a5`](https://github.com/fosrl/pangolin/commit/b8b69a5b4af56c205869b3f930c742de879eccb0) Add targetUrl for backward compatibility in ResourceAuthConfig - [`0fdaf3e`](https://github.com/fosrl/pangolin/commit/0fdaf3ed353d61b3cba47ae9d58370466302e8d4) feat(dns): include sticky metadata in authority config - [`7eb86df`](https://github.com/fosrl/pangolin/commit/7eb86dfafa66326513bc6101bdd552175dd58520) feat(dns): persist target latency and fold migration into 1.16.0 ### 📊 Changes **39 files changed** (+2820 additions, -40 deletions) <details> <summary>View changed files</summary> 📝 `messages/en-US.json` (+42 -0) 📝 `package.json` (+3 -3) 📝 `server/db/pg/schema/schema.ts` (+13 -1) 📝 `server/db/sqlite/schema/schema.ts` (+17 -1) 📝 `server/internalServer.ts` (+9 -2) ➕ `server/lib/jwtKeypair.ts` (+131 -0) 📝 `server/lib/readConfigFile.ts` (+1 -0) 📝 `server/lib/traefik/TraefikConfigManager.ts` (+223 -0) 📝 `server/openApi.ts` (+2 -1) ➕ `server/routers/auth/authProxy.ts` (+413 -0) 📝 `server/routers/auth/index.ts` (+3 -1) ➕ `server/routers/auth/validateSession.ts` (+132 -0) ➕ `server/routers/dns/dnsAuthority.ts` (+713 -0) 📝 `server/routers/external.ts` (+3 -0) 📝 `server/routers/internal.ts` (+9 -0) 📝 `server/routers/newt/getNewtToken.ts` (+71 -1) ➕ `server/routers/newt/handleAuthProxyStatusMessage.ts` (+41 -0) ➕ `server/routers/newt/handleDnsStatusMessage.ts` (+57 -0) 📝 `server/routers/newt/handleNewtRegisterMessage.ts` (+58 -0) 📝 `server/routers/newt/index.ts` (+2 -0) _...and 19 more files_ </details> ### 📄 Description ## Community Contribution License Agreement By creating this pull request, I grant the project maintainers an unlimited, perpetual license to use, modify, and redistribute these contributions under any terms they choose, including both the AGPLv3 and the Fossorial Commercial license terms. I represent that I have the right to grant this license for all contributed content. ## Description This adds DNS Authority and Auth Proxy support to Pangolin. The companion Newt PR is https://github.com/fosrl/newt/pull/236. I opened [a discussion](https://github.com/orgs/fosrl/discussions/2423) about this beforehand. Read more about my motivation for building this feature there. ### What this does Pangolin builds authoritative DNS zone configs and pushes them to Newt over WebSocket. Newt binds port 53 and serves A/NS/SOA responses. The DNS answers use the **Site's public IP** (not the internal target IP); the idea is that DNS controls which site the user's traffic reaches, and then Traefik/the tunnel handles proxying to the actual backend. There are two layers, and they can operate independently or together: **Domain-level zones:** work with existing wildcard domains. When you enable DNS Authority on a Site and set its public IP, Pangolin finds every wildcard domain that has Resources with Targets on that Site. For each domain it builds a `*.baseDomain` zone containing all DNS-Authority-enabled Sites as targets. Health is aggregated at the Site level a Site is considered healthy for a domain if *any* of its Targets across Resources on that domain are healthy. This is the "just turn it on" mode: no per-Resource config needed, and it covers every subdomain under the wildcard automatically. **Per-resource zones:** give finer control. Enabling `dnsAuthorityEnabled` on a specific Resource creates a zone for that Resource's `fullDomain` (e.g., `app.docker.example.com`). Unlike domain-level, health is tracked per-Target (not per-Site), and the user can configure a custom TTL (10–86400s) and routing policy (failover, round-robin, or priority). This works with any domain type, not just wildcards. Zone configs are rebuilt and pushed to each Newt agent: Site DNS Authority toggle, Resource update, Target create/update/delete, health check status change, and Newt reconnect (which gets the full set of zones immediately). **Auth Proxy:** Pangolin also pushes auth proxy configs so Newt can enforce SSO at the edge. Newt tries local JWT verification first using an RSA public key from Pangolin (sub-ms), then falls back to the Pangolin session validation API if needed. ### How it works ```mermaid graph LR %% Layout Adjustment User((User)) subgraph "Central Control Plane" P[Pangolin Dashboard] DB[(PostgreSQL)] P <--> DB end subgraph "Site A (Primary Network)" direction LR N1[Newt Agent A] S1[App Service] N1 -- "Health Check" --> S1 end subgraph "Site B (Redundant Network)" direction LR N2[Newt Agent B] S2[Redundant App Service] N2 -- "Health Check" --> S2 end %% State Sync (Hidden/Top) P ==>|"WebSocket Sync"| N1 P ==>|"WebSocket Sync"| N2 %% Step 1 & 2: DNS Resolution User -- "1. DNS Query" --> N1 N1 -- "2. IP Resolution" --> User %% Step 3 & 4: Traffic Flow User -- "3. HTTPS Request" --> N1 User -.-> |"Failover Request"| N2 N1 -- "4. Auth Proxy" --> S1 N2 -- "4. Auth Proxy" --> S2 ``` ### Schema changes Migration `1.16.0` (I am assuming this warrants a version up) adds columns to `sites` (`publicIp`, `dnsAuthorityEnabled`, `dnsStatus`, `dnsError`) and `resources` (`dnsAuthorityEnabled`, `dnsAuthorityTtl`, `dnsAuthorityRoutingPolicy`). Both PG and SQLite migrations are included. Everything defaults to `off` (backwards compatibility). ### Backward compatibility All new behavior is behind `dnsAuthorityEnabled` toggles on both sites and resources. Existing deployments are unaffected; nothing activates until a user explicitly enables it. ### Documentation This feature will need docs at https://docs.pangolin.net/manage/dns-authority (placeholder links are in the code). I'm happy to write those once (if) the approach is agreed upon. ## How to test? ### Option 1: Full local test stack There's a complete end-to-end test stack in [`mattv8/pangolin-testing`](https://github.com/mattv8/pangolin-testing) that spins up PostgreSQL, Pangolin, Gerbil, two Newt instances, two backends, and a test client on a Docker bridge network. ```bash git clone https://github.com/mattv8/pangolin-testing testing cd testing/ sudo modprobe wireguard # required for Gerbil docker compose down -v && docker compose up -d docker compose ps # wait for all services healthy bash scripts/bootstrap.sh # creates admin, org, sites, resource, targets ``` The bootstrap script enables DNS Authority, creates two sites with public IPs, and verifies resolution: ```bash dig @localhost -p 5353 app.test.dev A +short # 172.28.0.10 dig @localhost -p 5354 app.test.dev A +short # 172.28.0.10 dig @localhost -p 5353 anything.test.dev A +short # 172.28.0.10 (wildcard) ``` Failover test: ```bash docker compose stop backend dig @localhost -p 5353 app.test.dev A +short # secondary IP docker compose start backend ``` Auth proxy test: ```bash curl -sI http://localhost:8080/ | grep Location # 302 redirect to login ``` See the [testing README](https://github.com/mattv8/pangolin-testing/blob/main/README.md) for the full architecture diagram and service map. ### Option 2: Drop-in to an existing stack **Pangolin** swap the image in your `docker-compose.yml`: ```yaml image: hub.docker.visnovsky.us/library/pangolin:dns-authority-dev ``` ```bash docker compose pull pangolin && docker compose up -d pangolin ``` **Newt** install the pre-compiled binary: ```bash sudo cp /usr/local/bin/newt /usr/local/bin/newt.official curl -fsSL https://raw.githubusercontent.com/mattv8/pangolin-testing/main/scripts/get-newt.sh | bash sudo systemctl restart newt ``` Rollback: ```bash sudo cp /usr/local/bin/newt.official /usr/local/bin/newt && sudo systemctl restart newt ``` Then enable DNS Authority on a site (set public IP), and optionally on individual resources, through the UI. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-06-07 20:01:42 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/pangolin#25471