From 85cf81cbe038c65793dfd75f31f9c7fadab98d03 Mon Sep 17 00:00:00 2001 From: Christopher Agocs Date: Tue, 20 Jan 2026 12:10:27 -0800 Subject: [PATCH 1/5] docs: add documentation for v0.32.0 new configuration settings Add documentation for new settings introduced in Pomerium v0.32.0: - Add `dns_resolvers` setting to DNS documentation - Create new debug.mdx with `debug_address` documentation - Add missing DNS settings to reference.json (dns-failure-refresh-rate, dns-query-timeout, dns-query-tries, dns-refresh-rate, dns-resolvers, dns-udp-max-queries, dns-use-tcp, dns-settings) - Add `debug-address` to reference.json - Add `mcp-allowed-client-id-domains` to reference.json - Fix dns-lookup-family path in reference.json to point to dns.mdx Co-Authored-By: Claude Opus 4.5 --- content/docs/reference/debug.mdx | 74 ++++++++++++++++++++++++ content/docs/reference/dns.mdx | 45 +++++++++++++++ content/docs/reference/reference.json | 82 ++++++++++++++++++++++++++- 3 files changed, 200 insertions(+), 1 deletion(-) create mode 100644 content/docs/reference/debug.mdx diff --git a/content/docs/reference/debug.mdx b/content/docs/reference/debug.mdx new file mode 100644 index 000000000..de07ef8d0 --- /dev/null +++ b/content/docs/reference/debug.mdx @@ -0,0 +1,74 @@ +--- +title: Debug Settings +sidebar_label: Debug Settings +description: Configure debug settings in Pomerium. +keywords: [debug, debug address, config dump] +pagination_prev: null +pagination_next: null +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Debug Settings + +This reference covers Pomerium's **Debug Settings**: + +- [Debug Address](#debug-address) + +## Debug Address {#debug-address} + +**Debug Address** exposes a debug endpoint on the specified address. This endpoint provides access to debugging information such as configuration dumps. + +:::warning + +**Use with caution:** the debug endpoint can expose sensitive configuration values. Do not externally expose this endpoint. + +::: + +By default, the debug server starts on a random port accessible only to localhost. Setting this option allows you to explicitly configure the address. + +### How to configure {#how-to-configure-debug-address} + + + + +| **Config file keys** | **Environment variables** | **Type** | **Usage** | **Default** | +| :-- | :-- | :-- | :-- | :-- | +| `debug_address` | `DEBUG_ADDRESS` | `string` | **optional** | Random localhost port | + +#### Examples {#examples-debug-address} + +```yaml +debug_address: :6060 +``` + +```bash +DEBUG_ADDRESS=127.0.0.1:6060 +``` + + + + +`debug_address` is a bootstrap configuration setting and is not configurable in the Console. + + + + +Kubernetes does not support `debug_address`. + + + + +### Available Endpoints + +When the debug address is configured, the following endpoints are available: + +| Endpoint | Description | +| :-- | :-- | +| `/` | Index page listing available debug endpoints | +| `/config_dump` | Dumps the current Pomerium configuration | + +### Security Considerations + +The debug endpoint exposes sensitive configuration information. Only enable this setting in controlled environments and ensure the endpoint is not accessible from untrusted networks. diff --git a/content/docs/reference/dns.mdx b/content/docs/reference/dns.mdx index 519fe4f6d..06eda7ebd 100644 --- a/content/docs/reference/dns.mdx +++ b/content/docs/reference/dns.mdx @@ -23,6 +23,7 @@ This reference covers all of Pomerium's **DNS Settings**: - [Query Timeout](#query-timeout) - [Query Tries](#query-tries) - [Refresh Rate](#refresh-rate) +- [Resolvers](#resolvers) - [UDP Max Queries](#udp-max-queries) - [Use TCP](#use-tcp) @@ -228,6 +229,50 @@ dns: +## Resolvers + +**Resolvers** allows you to specify a list of custom DNS resolvers for Pomerium to use instead of the system default. Each resolver should be specified as a URL in the format `udp://:` or `tcp://:`. + +### How to Configure + + + + +| **Config file keys** | **Environment variables** | **Type** | **Default** | +| :-- | :-- | :-- | :-- | +| `dns_resolvers` | `DNS_RESOLVERS` | `array of strings` | System DNS resolvers | + +#### Examples + +```yaml +dns_resolvers: + - udp://1.1.1.1:53 + - udp://8.8.8.8:53 +``` + +```yaml +dns_resolvers: + - tcp://1.1.1.1:53 +``` + + + + +`dns_resolvers` is a bootstrap configuration setting and is not configurable in the Console. + + + + +```yaml +dns: + resolvers: + - udp://1.1.1.1:53 + - udp://8.8.8.8:53 +``` + + + + ## UDP Max Queries **UDP Max Queries** sets the maximum number of queries before a new UDP port is opened. diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index 9d37f745a..8c6b73837 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -299,6 +299,14 @@ "title": "Default Upstream Timeout", "type": "" }, + "debug-address": { + "description": "Exposes a debug endpoint on the specified address for accessing debugging information such as configuration dumps.", + "id": "debug-address", + "path": "/debug#debug-address", + "services": [], + "title": "Debug Address", + "type": "string" + }, "description": { "description": "An optional description for this route. Displayed on the Routes Portal.", "id": "description", @@ -326,14 +334,78 @@ "services": ["proxy"], "title": "Direct Response" }, + "dns-settings": { + "description": "Configure DNS settings in Pomerium.", + "id": "dns-settings", + "path": "/dns", + "services": [], + "title": "DNS Settings", + "type": "string" + }, + "dns-failure-refresh-rate": { + "description": "Sets the DNS refresh rate when requests are failing.", + "id": "dns-failure-refresh-rate", + "path": "/dns#failure-refresh-rate", + "services": [], + "title": "DNS Failure Refresh Rate", + "type": "string" + }, "dns-lookup-family": { "description": "Sets the DNS IP address resolution policy.", "id": "dns-lookup-family", - "path": "/dns-lookup-family", + "path": "/dns#lookup-family", "services": [], "title": "DNS Lookup Family", "type": "string" }, + "dns-query-timeout": { + "description": "Sets the timeout for DNS queries.", + "id": "dns-query-timeout", + "path": "/dns#query-timeout", + "services": [], + "title": "DNS Query Timeout", + "type": "string" + }, + "dns-query-tries": { + "description": "Sets the number of times a DNS query will be re-tried.", + "id": "dns-query-tries", + "path": "/dns#query-tries", + "services": [], + "title": "DNS Query Tries", + "type": "integer" + }, + "dns-refresh-rate": { + "description": "Sets the DNS refresh rate.", + "id": "dns-refresh-rate", + "path": "/dns#refresh-rate", + "services": [], + "title": "DNS Refresh Rate", + "type": "string" + }, + "dns-resolvers": { + "description": "Specifies a list of custom DNS resolvers for Pomerium to use instead of the system default.", + "id": "dns-resolvers", + "path": "/dns#resolvers", + "services": [], + "title": "DNS Resolvers", + "type": "array of strings" + }, + "dns-udp-max-queries": { + "description": "Sets the maximum number of queries before a new UDP port is opened.", + "id": "dns-udp-max-queries", + "path": "/dns#udp-max-queries", + "services": [], + "title": "DNS UDP Max Queries", + "type": "integer" + }, + "dns-use-tcp": { + "description": "Configures Pomerium to use TCP instead of UDP for DNS queries.", + "id": "dns-use-tcp", + "path": "/dns#use-tcp", + "services": [], + "title": "DNS Use TCP", + "type": "boolean" + }, "downstream-mtls-client-certificate-authority": { "description": "A bundle of PEM-encoded X.509 certificates that will be treated as trust anchors when verifying client certificates", "id": "downstream-mtls-client-certificate-authority", @@ -965,6 +1037,14 @@ "path": "/../capabilities/device-identity", "title": "Manage Devices" }, + "mcp-allowed-client-id-domains": { + "description": "List of allowed domain patterns for MCP client ID metadata URLs. Supports wildcard patterns (e.g., *.example.com). Required when using URL-based client IDs.", + "id": "mcp-allowed-client-id-domains", + "path": "/../capabilities/mcp#allowed-client-id-domains", + "services": [], + "title": "MCP Allowed Client ID Domains", + "type": "array of strings" + }, "mcp-server-max-request-bytes": { "description": "Maximum MCP request size in bytes. Adjust if you are passing some large payloads that cause errors.", "id": "mcp-server-max-request-bytes", From aaaad03d7fa3c127dbf7879fecafe635ebf6ee69 Mon Sep 17 00:00:00 2001 From: Christopher Agocs Date: Tue, 20 Jan 2026 12:19:02 -0800 Subject: [PATCH 2/5] Prettier --- content/docs/reference/debug.mdx | 8 +++---- content/docs/reference/reference.json | 32 +++++++++++++-------------- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/content/docs/reference/debug.mdx b/content/docs/reference/debug.mdx index de07ef8d0..f438cb303 100644 --- a/content/docs/reference/debug.mdx +++ b/content/docs/reference/debug.mdx @@ -64,10 +64,10 @@ Kubernetes does not support `debug_address`. When the debug address is configured, the following endpoints are available: -| Endpoint | Description | -| :-- | :-- | -| `/` | Index page listing available debug endpoints | -| `/config_dump` | Dumps the current Pomerium configuration | +| Endpoint | Description | +| :------------- | :------------------------------------------- | +| `/` | Index page listing available debug endpoints | +| `/config_dump` | Dumps the current Pomerium configuration | ### Security Considerations diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index 8c6b73837..78dc62a00 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -291,14 +291,6 @@ "services": ["databroker"], "title": "Databroker Settings" }, - "default-upstream-timeout": { - "description": "Sets the default timeout applied to a proxied route when no timeout key is specified by the policy.", - "id": "default-upstream-timeout", - "path": "/default-upstream-timeout", - "services": [], - "title": "Default Upstream Timeout", - "type": "" - }, "debug-address": { "description": "Exposes a debug endpoint on the specified address for accessing debugging information such as configuration dumps.", "id": "debug-address", @@ -307,6 +299,14 @@ "title": "Debug Address", "type": "string" }, + "default-upstream-timeout": { + "description": "Sets the default timeout applied to a proxied route when no timeout key is specified by the policy.", + "id": "default-upstream-timeout", + "path": "/default-upstream-timeout", + "services": [], + "title": "Default Upstream Timeout", + "type": "" + }, "description": { "description": "An optional description for this route. Displayed on the Routes Portal.", "id": "description", @@ -334,14 +334,6 @@ "services": ["proxy"], "title": "Direct Response" }, - "dns-settings": { - "description": "Configure DNS settings in Pomerium.", - "id": "dns-settings", - "path": "/dns", - "services": [], - "title": "DNS Settings", - "type": "string" - }, "dns-failure-refresh-rate": { "description": "Sets the DNS refresh rate when requests are failing.", "id": "dns-failure-refresh-rate", @@ -390,6 +382,14 @@ "title": "DNS Resolvers", "type": "array of strings" }, + "dns-settings": { + "description": "Configure DNS settings in Pomerium.", + "id": "dns-settings", + "path": "/dns", + "services": [], + "title": "DNS Settings", + "type": "string" + }, "dns-udp-max-queries": { "description": "Sets the maximum number of queries before a new UDP port is opened.", "id": "dns-udp-max-queries", From 6cf086fcf2816cb44f8da0384e56b6e9e9ff344a Mon Sep 17 00:00:00 2001 From: Christopher Agocs Date: Tue, 20 Jan 2026 12:25:57 -0800 Subject: [PATCH 3/5] Remove dns-settings --- content/docs/reference/reference.json | 8 -------- 1 file changed, 8 deletions(-) diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index 78dc62a00..22c791170 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -382,14 +382,6 @@ "title": "DNS Resolvers", "type": "array of strings" }, - "dns-settings": { - "description": "Configure DNS settings in Pomerium.", - "id": "dns-settings", - "path": "/dns", - "services": [], - "title": "DNS Settings", - "type": "string" - }, "dns-udp-max-queries": { "description": "Sets the maximum number of queries before a new UDP port is opened.", "id": "dns-udp-max-queries", From 0b0abae566c3ef14a8c6567acfdf354316f51bc2 Mon Sep 17 00:00:00 2001 From: Christopher Agocs Date: Tue, 20 Jan 2026 12:27:04 -0800 Subject: [PATCH 4/5] Revert "Remove dns-settings" This reverts commit 6cf086fcf2816cb44f8da0384e56b6e9e9ff344a. --- content/docs/reference/reference.json | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/content/docs/reference/reference.json b/content/docs/reference/reference.json index 22c791170..78dc62a00 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -382,6 +382,14 @@ "title": "DNS Resolvers", "type": "array of strings" }, + "dns-settings": { + "description": "Configure DNS settings in Pomerium.", + "id": "dns-settings", + "path": "/dns", + "services": [], + "title": "DNS Settings", + "type": "string" + }, "dns-udp-max-queries": { "description": "Sets the maximum number of queries before a new UDP port is opened.", "id": "dns-udp-max-queries", From e56d640309d66b4994539d7ba61cee33f7741d51 Mon Sep 17 00:00:00 2001 From: Christopher Agocs Date: Tue, 20 Jan 2026 13:46:23 -0800 Subject: [PATCH 5/5] Cautioned Enterprise users to upgrade Console before Core --- content/docs/deploy/upgrading.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/content/docs/deploy/upgrading.mdx b/content/docs/deploy/upgrading.mdx index 19bef5869..a9b41dbd6 100644 --- a/content/docs/deploy/upgrading.mdx +++ b/content/docs/deploy/upgrading.mdx @@ -25,6 +25,12 @@ Changelog notes for Pomerium Core can be found on [GitHub](https://github.com/po This page contains the list of deprecations and important or breaking changes for Pomerium Core. Please read it carefully before upgrading. +### 0.32.0 + +#### Upgrade Enterprise Console before Core + +**Enterprise Console users only:** There is a breaking change in Pomerium Core databroker that will cause the Enterprise Console to crash if Core is upgraded before the Enterprise Console. Upgrade the Enterprise Console to v0.32.0 before upgrading Core to v0.32.0. + ### 0.31.0 #### Removed Authenticate Callback Path Setting @@ -340,6 +346,12 @@ In case of trouble during the upgrade process, follow these steps to **roll back 1. Downgrade Pomerium Core to the previous version. 1. Start the previous version of Pomerium Enterprise. +### v0.32.0 + +#### Upgrade Enterprise Console before Core + +There is a breaking change in Pomerium Core databroker that will cause the Enterprise Console to crash if Core is upgraded before the Enterprise Console. Upgrade the Enterprise Console to v0.32.0 before upgrading Core to v0.32.0. + ### v0.31.0 There are no breaking changes in the Pomerium Console, but be sure to review the changes to Pomerium Core before upgrading.