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. diff --git a/content/docs/reference/debug.mdx b/content/docs/reference/debug.mdx new file mode 100644 index 000000000..f438cb303 --- /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..78dc62a00 100644 --- a/content/docs/reference/reference.json +++ b/content/docs/reference/reference.json @@ -291,6 +291,14 @@ "services": ["databroker"], "title": "Databroker Settings" }, + "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" + }, "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", @@ -326,14 +334,78 @@ "services": ["proxy"], "title": "Direct Response" }, + "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-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", + "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",