diff --git a/content/docs/deploy/k8s/reference.md b/content/docs/deploy/k8s/reference.md index be25b0c8f..dc5990cec 100644 --- a/content/docs/deploy/k8s/reference.md +++ b/content/docs/deploy/k8s/reference.md @@ -167,7 +167,7 @@ PomeriumSpec defines Pomerium-specific configuration parameters.

- PassIdentityHeaders sets the pass identity headers option. + PassIdentityHeaders sets the pass identity headers option.

diff --git a/content/docs/reference/access-log-fields.mdx b/content/docs/reference/access-log-fields.mdx index 3891fbb1e..a4b40856a 100644 --- a/content/docs/reference/access-log-fields.mdx +++ b/content/docs/reference/access-log-fields.mdx @@ -2,6 +2,9 @@ title: Access Log Fields description: Use Access Log Fields to display HTTP request logs from the proxy service. keywords: [access logs, proxy service, pomerium, http] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -15,7 +18,7 @@ The **Access Log Fields** setting controls which fields will be included in the The default log fields should be appropriate for most deployments. -## How to Configure +## How to configure @@ -24,6 +27,31 @@ The default log fields should be appropriate for most deployments. | :-- | :-- | :-- | :-- | | `access_log_fields` | `ACCESS_LOG_FIELDS` | Array of strings | See [Access Fields and Defaults](#access-fields-and-defaults) | +### Examples + +```yaml +access_log_fields: + - authority + - duration + - path +``` + +```bash +ACCESS_LOG_FIELDS=authority,duration,path +``` + +**Custom headers example:** + +```yaml +access_log_fields: + - headers.user-agent + - headers.content-type +``` + +```bash +ACCESS_LOG_FIELDS=headers.user-agent,headers.content-type +``` + @@ -42,10 +70,29 @@ Add **Custom Headers** in the Console: | :-- | :-- | :-- | | `accessLogFields` | Array of strings | See [Access Fields and Defaults](#access-fields-and-defaults) | +### Examples + +```yaml +accessLogFields: + - authority + - duration + - path +``` + +**Custom headers example** + +```yaml +accessLogFields: + - headers.user-agent + - headers.content-type +``` + +See the [Kubernetes Reference](/docs/deploy/k8s/reference#spec) for more information. + -## Access Log Fields and Defaults +## Access log fields and defaults The table below lists all available access log fields: @@ -129,7 +176,7 @@ Your logs would look similar to the below example: } ``` -### Log Custom Headers Fields +### Log custom headers fields The `headers.{CustomHeaderName}` field allows you to enter custom headers. Adding one or multiple custom headers will display only those headers. @@ -155,24 +202,3 @@ The custom headers will appear in the `headers` field: "message": "http-request" } ``` - -### Examples - -```yaml -access_log_fields: - - authority - - duration - - path - -ACCESS_LOG_FIELDS=authority,duration,path -``` - -**`headers.{CustomHeaderName}` example:** - -```yaml -access_log_fields: - - headers.user-agent - - headers.content-type - -ACCESS_LOG_FIELDS=headers.user-agent,headers.content-type -``` diff --git a/content/docs/reference/address.mdx b/content/docs/reference/address.mdx index 1aa2782ae..b61d34969 100644 --- a/content/docs/reference/address.mdx +++ b/content/docs/reference/address.mdx @@ -8,6 +8,7 @@ keywords: - Address pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -34,6 +35,16 @@ In all-in-one deployments, gRPC traffic will be served on loopback on port `:544 | :-- | :-- | :-- | :-- | :-- | | `address` | `ADDRESS` | `string` | **required** | `:443` | +### Examples + +```yaml +address: ':8443' +``` + +```bash +ADDRESS=:8443 +``` + @@ -46,13 +57,3 @@ In all-in-one deployments, gRPC traffic will be served on loopback on port `:544 - -### Examples - -```yaml -# config file key -address: :8443 - -# environment variable -ADDRESS=:8443 -``` diff --git a/content/docs/reference/authenticate-callback-path.mdx b/content/docs/reference/authenticate-callback-path.mdx index 662f949a7..d77f38862 100644 --- a/content/docs/reference/authenticate-callback-path.mdx +++ b/content/docs/reference/authenticate-callback-path.mdx @@ -8,6 +8,7 @@ keywords: - Authenticate Callback Path pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -45,6 +46,16 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen | :-- | :-- | :-- | :-- | :-- | | `authenticate_callback_path` | `AUTHENTICATE_CALLBACK_PATH` | `string` | **optional** | `/oauth2/callback` | +### Examples + +```yaml +authenticate_callback_path: '/custom/callback' +``` + +```bash +AUTHENTICATE_CALLBACK_PATH=/custom/callback +``` + @@ -57,20 +68,14 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen | :-------------------------- | :------- | :----------- | :----------------- | | `authenticate.callbackPath` | `string` | **optional** | `/oauth2/callback` | -See the [Kubernetes Deployment Reference](/docs/deploy/k8s/reference#authenticate) for more information. - - - - ### Examples ```yaml -# config file key -authenticate_callback_path: "/custom/callback" +authenticate: + callbackPath: /custom/callback +``` -# environment variable -AUTHENTICATE_CALLBACK_PATH=/custom/callback +See the [Kubernetes Deployment Reference](/docs/deploy/k8s/reference#authenticate) for more information. -# ingress -authenticate.callbackPath: /custom/callback -``` + + diff --git a/content/docs/reference/authenticate-internal-service-url.mdx b/content/docs/reference/authenticate-internal-service-url.mdx index 204a3d79a..1dcddb720 100644 --- a/content/docs/reference/authenticate-internal-service-url.mdx +++ b/content/docs/reference/authenticate-internal-service-url.mdx @@ -6,6 +6,7 @@ keywords: - Authenticate Internal Service URL pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -38,6 +39,16 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen | :-- | :-- | :-- | :-- | | `authenticate_internal_service_url` | `AUTHENTICATE_INTERNAL_SERVICE_URL` | `URL` | **required** (In [split-service mode](/docs/internals/configuration#all-in-one-vs-split-service-mode) only) | +### Examples + +```yaml +authenticate_internal_service_url: https://authenticate.internal +``` + +```bash +AUTHENTICATE_INTERNAL_SERVICE_URL=https://authenticate.internal +``` + @@ -50,13 +61,3 @@ Kubernetes does not support `authenticate_internal_service_url` - -### Examples - -```yaml -# config file key -authenticate_internal_service_url: https://authenticate.internal - -# environment variable -AUTHENTICATE_INTERNAL_SERVICE_URL=https://authenticate.internal -``` diff --git a/content/docs/reference/authenticate-service-url.mdx b/content/docs/reference/authenticate-service-url.mdx index 809f5eecd..02c7aa2f2 100644 --- a/content/docs/reference/authenticate-service-url.mdx +++ b/content/docs/reference/authenticate-service-url.mdx @@ -8,6 +8,7 @@ keywords: - Authenticate Service URL pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -38,6 +39,16 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen | :-- | :-- | :-- | :-- | | `authenticate_service_url` | `AUTHENTICATE_SERVICE_URL` | `URL` | **required** | +### Examples + +```yaml +authenticate_service_url: https://authenticate.corp.example.com +``` + +```bash +AUTHENTICATE_SERVICE_URL=https://authenticate.corp.example.com +``` + @@ -46,24 +57,18 @@ See [**Self-Hosted Authenticate Service**](/docs/capabilities/self-hosted-authen -| **Name** | **Type** | **Usage** | -| :---------------- | :------- | :----------- | -| `AuthenticateUrl` | `URL` | **required** | - -See [Kubernetes `authenticate.url`](/docs/deploy/k8s/reference#authenticate) reference for more information. - - - +| **Name** | **Type** | **Usage** | +| :----------------- | :------- | :----------- | +| `authenticate.url` | `URL` | **required** | ### Examples ```yaml -# config file key -authenticate_service_url: https://authenticate.corp.example.com +authenticate: + url: https://authenticate.corp.example.com +``` -# environment variable -AUTHENTICATE_SERVICE_URL=https://authenticate.corp.example.com +See the [Kubernetes Reference](/docs/deploy/k8s/reference#authenticate) for more information. -# ingress -authenticate.url: https://authenticate.corp.example.com -``` + + diff --git a/content/docs/reference/authorize-internal-service-url.mdx b/content/docs/reference/authorize-internal-service-url.mdx index 1e49bb2c0..13d00f885 100644 --- a/content/docs/reference/authorize-internal-service-url.mdx +++ b/content/docs/reference/authorize-internal-service-url.mdx @@ -6,6 +6,7 @@ keywords: - Authorize Internal Service URL pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ If included, **Authorize Internal Service URL** will override Authorize Service | :-- | :-- | :-- | :-- | | `authorize_internal_service_url` | `AUTHORIZE_INTERNAL_SERVICE_URL` | `URL` | **required** (Inferred in all-in-one mode to be localhost) | +### Examples + +```yaml +authorize_internal_service_url: https://pomerium-authorize-service.default.svc.cluster.local +``` + +```bash +AUTHORIZE_INTERNAL_SERVICE_URL=https://localhost:5443 +``` + @@ -40,13 +51,3 @@ Kubernetes does not support `authorize_internal_service_url` - -### Examples - -```yaml -# config file key -authorize_internal_service_url: https://pomerium-authorize-service.default.svc.cluster.local - -# environment variable -AUTHORIZE_INTERNAL_SERVICE_URL=https://localhost:5443 -``` diff --git a/content/docs/reference/authorize-log-fields.mdx b/content/docs/reference/authorize-log-fields.mdx index 41a95d1c6..0d95e9d00 100644 --- a/content/docs/reference/authorize-log-fields.mdx +++ b/content/docs/reference/authorize-log-fields.mdx @@ -3,6 +3,9 @@ title: Authorize Log Fields description: Use Authorize Log Fields to display HTTP request logs from the authorize service. keywords: [authorize logs, authorize service, pomerium, http] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -16,7 +19,7 @@ The **Authorize Log Fields** setting controls which fields will be included in t The default log fields should be appropriate for most deployments. -## How to Configure +## How to configure @@ -25,6 +28,42 @@ The default log fields should be appropriate for most deployments. | :-- | :-- | :-- | :-- | | `authorize_log_fields` | `AUTHORIZE_LOG_FIELDS` | Array of strings | See [Authorize Fields and Defaults](#authorize-log-fields-and-defaults) | +### Examples + +```yaml +authorize_log_fields: + - request-id + - path + - ip +``` + +```bash +AUTHORIZE_LOG_FIELDS=request-id,path,ip +``` + +**Headers examples:** + +```yaml +# List all HTTP headers +authorize_log_fields: + - headers +``` + +```bash +AUTHORIZE_LOG_FIELDS=headers +``` + +```yaml +# List custom HTTP headers +authorize_log_fields: + - headers.cookie + - headers.content-type +``` + +```bash +AUTHORIZE_LOG_FIELDS=headers.cookie,headers.content-type +``` + @@ -43,10 +82,19 @@ Add **Custom Headers** in the Console: | :-- | :-- | :-- | | `authorizeLogFields` | Array of strings | See [Authorize Fields and Defaults](#authorize-log-fields-and-defaults) | +### Examples + +```yaml +authorizeLogFields: + - request-id + - path + - ip +``` + -## Authorize Log Fields and Defaults +## Authorize log fields and defaults The table below lists all available authorize log fields: @@ -185,7 +233,7 @@ Your logs would look similar to the example below: } ``` -### Log Custom Headers Fields +### Log custom headers fields The `headers.{CustomHeaderName}` field allows you to enter custom headers. Adding one or multiple custom headers will display only those headers. @@ -267,31 +315,3 @@ Your logs would look similar to the below example: "message": "authorize check" } ``` - -### Examples - -```yaml -authorize_log_fields: - - request-id - - path - - ip - -AUTHORIZE_LOG_FIELDS:request-id,path,ip -``` - -**Headers examples:** - -```yaml -# List all HTTP headers -authorize_log_fields: - - headers - -AUTHORIZE_LOG_FIELDS:headers - -# List custom HTTP headers -authorize_log_fields: - - headers.cookie - - headers.content-type - -AUTHORIZE_LOG_FIELDS:headers.cookie,headers.content-type -``` diff --git a/content/docs/reference/authorize-service-url.mdx b/content/docs/reference/authorize-service-url.mdx index 4f898bf3d..07c9787fe 100644 --- a/content/docs/reference/authorize-service-url.mdx +++ b/content/docs/reference/authorize-service-url.mdx @@ -8,6 +8,7 @@ keywords: - Authorize Service URL pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -39,6 +40,18 @@ If your load balancer does not support gRPC pass-through, you must set this valu | `authorize_service_url` | `AUTHORIZE_SERVICE_URL` | `URL` | **required** (Inferred in all-in-one mode to be localhost) | | `authorize_service_urls` | `AUTHORIZE_SERVICE_URLS` | `URL` | **required** (Inferred in all-in-one mode to be localhost) | +### Examples + +```yaml +authorize_service_urls: + - https://localhost:5443 + - https://authorize.corp.example.com +``` + +```bash +AUTHORIZE_SERVICE_URL=https://pomerium-authorize-service.default.svc.cluster.local +``` + @@ -51,17 +64,3 @@ The `authorize_service_url` is not customizable in all-in-one mode with the CRD - -### Examples - -**Examples:** - -```yaml -# config file key -authorize_service_urls: - - https://localhost:5443 - - https://authorize.corp.example.com - -# environment variable -AUTHORIZE_SERVICE_URL=https://pomerium-authorize-service.default.svc.cluster.local -``` diff --git a/content/docs/reference/autocert.mdx b/content/docs/reference/autocert.mdx index 96f1d3043..9601ae695 100644 --- a/content/docs/reference/autocert.mdx +++ b/content/docs/reference/autocert.mdx @@ -60,6 +60,16 @@ Autocert requires that port `443` be accessible from the internet in order to co | :------------------- | :------------------------ | :-------- | :----------- | | `autocert` | `AUTOCERT` | `boolean` | **optional** | +#### Examples {#autocert-examples} + +```yaml +autocert: true +``` + +```bash +AUTOCERT=TRUE +``` + @@ -73,16 +83,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-examples} - -```yaml -# config file key -autocert: true - -# environment variable -AUTOCERT=TRUE -``` - ## Autocert CA {#autocert-ca} **Autocert CA** is the directory URL of the ACME CA to use when requesting certificates. @@ -102,6 +102,16 @@ If set, Autocert CA will override the [**Autocert Use Staging**](/docs/reference | :------------------- | :------------------------ | :------- | :----------- | | `autocert_ca` | `AUTOCERT_CA` | `string` | **optional** | +#### Examples {#autocert-ca-examples} + +```yaml +autocert_ca: https://acme.zerossl.com/v2/DV90 +``` + +```bash +AUTOCERT_CA=https://acme.zerossl.com/v2/DV90 +``` + @@ -115,16 +125,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-ca-examples} - -```yaml -# config file key -autocert_ca: https://acme.zerossl.com/v2/DV90 - -# environment variable -AUTOCERT_CA=https://acme.zerossl.com/v2/DV90 -``` - ## Autocert Directory {#autocert-directory} **Autocert Directory** is the path where [Autocert](/docs/reference/autocert) stores X.509 Certificate data. @@ -140,6 +140,28 @@ AUTOCERT_CA=https://acme.zerossl.com/v2/DV90 **Note**: `string` must point to the path of the directory, or a URL to an S3 or GCS bucket. +#### Examples {#autocert-directory-examples} + +##### S3 Bucket + +An S3 bucket can be used as storage by using a URL like: + +```yaml +autocert_dir: s3://your-bucket.s3.us-east-1.amazonaws.com/some/prefix +``` + +Credentials are sourced from [the environment](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#EnvConfig). + +##### GCS Bucket + +A Google Cloud Storage bucket can be used as storage by using a URL like: + +```yaml +autocert_dir: gs://your-bucket/some/prefix +``` + +Credentials are sourced from [Google Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials). + @@ -162,28 +184,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ | XDG base directories | [$XDG_DATA_HOME](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) | | Home directories | `$HOME/.local/share/pomerium` | -### Examples {#autocert-directory-examples} - -#### S3 Bucket - -An S3 bucket can be used as storage by using a URL like: - -```yaml -autocert_dir: s3://your-bucket.s3.us-east-1.amazonaws.com/some/prefix -``` - -Credentials are sourced from [the environment](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#EnvConfig). - -#### GCS Bucket - -A Google Cloud Storage bucket can be used as storage by using a URL like: - -```yaml -autocert_dir: gs://your-bucket/some/prefix -``` - -Credentials are sourced from [Google Application Default Credentials](https://cloud.google.com/docs/authentication/application-default-credentials). - ## Autocert EAB Key ID {#autocert-eab-key-id} **Autocert EAB Key ID** is the key identifier when requesting a certificate from a CA with External Account Binding (EAB) enabled. @@ -199,6 +199,16 @@ Credentials are sourced from [Google Application Default Credentials](https://cl See [RFC8555-#7.3.4](https://datatracker.ietf.org/doc/html/rfc8555#section-7.3.4) for more information. +#### Examples {#autocert-eab-key-id-examples} + +```yaml +autocert_eab_key_id: EAB_KID +``` + +```bash +AUTOCERT_EAB_KEY_ID=EAB_KID +``` + @@ -212,16 +222,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-eab-key-id-examples} - -```yaml -# config file key -autocert_eab_key_id: EAB_KID - -# environment variable -AUTOCERT_EAB_KEY_ID=EAB_KID -``` - ## Autocert EAB MAC Key {#autocert-eab-mac-key} **Autocert EAB MAC Key** is the base64-URL-encoded secret key corresponding to the [Autocert EAB Key ID](/docs/reference/autocert). @@ -237,6 +237,16 @@ The Autocert EAB MAC Key setting is required when Autocert EAB Key ID is set. | :--------------------- | :------------------------ | :------- | :----------- | | `autocert_eab_mac_key` | `AUTOCERT_EAB_MAC_KEY` | `string` | **optional** | +#### Examples {#autocert-eab-mac-key-examples} + +```yaml +autocert_eab_key_id: base64-URL-encoded_secret_key +``` + +```bash +AUTOCERT_EAB_KEY_ID=base64-URL-encoded_secret_key +``` + @@ -250,16 +260,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-eab-mac-key-examples} - -```yaml -# config file key -autocert_eab_key_id: base64-URL-encoded_secret_key - -# environment variable -AUTOCERT_EAB_KEY_ID=base64-URL-encoded_secret_key -``` - ## Autocert Email {#autocert-email} **Autocert Email** is the email address to use when requesting certificates from an ACME CA or registering an ACME account. @@ -279,6 +279,16 @@ The CA may contact you at this address when, for example, a certificate expires. | :------------------- | :------------------------ | :------- | :----------- | | `autocert_email` | `AUTOCERT_EMAIL` | `string` | **optional** | +#### Examples {#autocert-email-examples} + +```yaml +autocert_email: example@domain.com +``` + +```bash +AUTOCERT_EMAIL=example@domain.com +``` + @@ -292,16 +302,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-email-examples} - -```yaml -# config file key -autocert_email: example@domain.com - -# environment variable -AUTOCERT_EMAIL=example@domain.com -``` - ## Autocert Must Staple {#autocert-must-staple} If true, **Autocert Must Staple** forces Autocert to request a certificate with the `status_request` extension (commonly called `Must-Staple`). @@ -327,6 +327,16 @@ The Autocert Must Staple setting will only take effect when you request or renew See [RFC7633](https://tools.ietf.org/html/rfc7633) for more information. +#### Examples {#autocert-must-staple-examples} + +```yaml +autocert_must_staple: true +``` + +```bash +AUTOCERT_MUST_STAPLE=true +``` + @@ -340,16 +350,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-must-staple-examples} - -```yaml -# config file key -autocert_must_staple: true - -# environment variable -AUTOCERT_MUST_STAPLE=true -``` - ## Autocert Trusted Certificate Authority {#autocert-trusted-certificate-authority} **Autocert Trusted Certificate Authority** is the X.509 CA (bundle) used when communicating with a CA supporting the ACME protocol. @@ -366,6 +366,24 @@ If not set, the system trusted roots will be used to verify TLS connections to t | `autocert_trusted_ca` | `AUTOCERT_TRUSTED_CA` | `string` | **optional** | | `autocert_trusted_ca_file` | `AUTOCERT_TRUSTED_CA_FILE` | `string` | **optional** | +#### Examples {#autocert-trusted-certificate-authority-examples} + +```yaml +autocert_trusted_ca: base64-encoded-string +``` + +```yaml +autocert_trusted_ca_file: /relative/file/location +``` + +```bash +AUTOCERT_TRUSTED_CA=base64-encoded-string +``` + +```bash +AUTOCERT_TRUSTED_CA_FILE=/relative/file/location +``` + @@ -379,18 +397,6 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ -### Examples {#autocert-trusted-certificate-authority-examples} - -```yaml -# config file key -autocert_trusted_ca: base64-encoded-string -autocert_trusted_ca_file: /relative/file/location - -# environment variable -AUTOCERT_TRUSTED_CA=base64-encoded-string -AUTOCERT_TRUSTED_CA_FILE=/relative/file/location -``` - ## Autocert Use Staging {#autocert-use-staging} **Autocert Use Staging** setting allows you to use Let's Encrypt's [staging environment](https://letsencrypt.org/docs/staging-environment/), which has more lenient [usage limits](https://letsencrypt.org/docs/rate-limits/) than the production environment. @@ -404,6 +410,16 @@ AUTOCERT_TRUSTED_CA_FILE=/relative/file/location | :-- | :-- | :-- | :-- | | `autocert_use_staging` | `AUTOCERT_USE_STAGING` | `boolean` | **optional** | +#### Examples {#autocert-use-staging-examples} + +```yaml +autocert_use_staging: true +``` + +```bash +AUTOCERT_USE_STAGING=true +``` + @@ -416,13 +432,3 @@ Kubernetes users should not use Autocert. See the [cert-manager's guide](https:/ - -### Examples {#autocert-use-staging-examples} - -```yaml -# config file key -autocert_use_staging: true - -# environment variable -AUTOCERT_USE_STAGING=true -``` diff --git a/content/docs/reference/branding/branding.md b/content/docs/reference/branding/branding.md index ae0b5db26..e1eb01067 100644 --- a/content/docs/reference/branding/branding.md +++ b/content/docs/reference/branding/branding.md @@ -3,6 +3,9 @@ id: branding title: Branding Settings sidebar_label: Branding Settings description: Customize your Console with Pomerium's branding settings. +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- # Branding Settings diff --git a/content/docs/reference/certificates.mdx b/content/docs/reference/certificates.mdx index 1a31da1ae..3a8a5bf53 100644 --- a/content/docs/reference/certificates.mdx +++ b/content/docs/reference/certificates.mdx @@ -6,6 +6,7 @@ keywords: - Certificates pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -48,30 +49,6 @@ Pomerium will check your system's trust/key store for valid certificates first. | `certificate` and `certificate_key` | `CERTIFICATE` and `CERTIFICATE_KEY` | `string` (base64-encoded string) | **required** (if insecure not set) | | `certificate_file` and `certificate_key_file` | `CERTIFICATE_FILE` and `CERTIFICATE_KEY_FILE` | `string` (Relative file location for a single certificate) | **required** (if insecure not set) | - - - -Add **Certificates** in the Enterprise Console: - -![Add Certificates in the Enterprise Console](./img/certificates/certs-console.png) - -View **Certificates**: - -![See your Certificates in the Enterprise Console](./img/certificates/certs-console-list.png) - - - - -```yaml -Spec: - Certificates: pomerium/wildcard-localhost -``` - -See Kubernetes [Ingress Configuration](/docs/deploy/k8s/reference#spec) for more information. - - - - ### Examples {#certificates-examples} Specify multiple certificates at once: @@ -95,13 +72,36 @@ certificate_file: '$HOME/.acme.sh/*.example.com/fullchain.crt' certificate_key_file: '$HOME/.acme.sh/*.example.com/*.example.com.key' ``` -:::tip **Note:** + + + +Add **Certificates** in the Enterprise Console: + +![Add Certificates in the Enterprise Console](./img/certificates/certs-console.png) + +View **Certificates**: + +![See your Certificates in the Enterprise Console](./img/certificates/certs-console-list.png) + + + + +```yaml +certificates: pomerium/wildcard-localhost +``` + +See Kubernetes [TLS Certificates](/docs/deploy/k8s/ingress#tls-certificates) for more information. + + + + +:::note All certificates supplied to Pomerium must be in **PEM** format. ::: -## Certificate Authority {#certificate-authority} +## Certificate Authority (CA) {#certificate-authority} **Certificate Authority** defines a set of root certificate authorities (CAs) that Pomerium uses when communicating with other TLS-protected services. @@ -127,6 +127,16 @@ Be sure to include the intermediary certificate. | `certificate_authority` | `CERTIFICATE_AUTHORITY` | `string` | **optional** | | `certificate_authority_file` | `CERTIFICATE_AUTHORITY_FILE` | `string` | **optional** | +### Examples {#certificate-authority-examples} + +```yaml +certificate_authority: 'base64-encoded-string' +``` + +```bash +CERTIFICATE_AUTHORITY_FILE=/relative/file/location +``` + @@ -142,16 +152,6 @@ Kubernetes does not support `certificate_authority` -### Examples {#certificate-authority-examples} - -```yaml -# config file key -certificate_authority: base64-encoded-string - -# environment variable -CERTIFICATE_AUTHORITY_FILE=/relative/file/location -``` - ## Client Certificate Authority {#client-certificate-authority} :::caution @@ -176,6 +176,19 @@ If not set, no client certificate will be required. | `client_ca` | `CLIENT_CA` | `string` | **optional** | | `client_ca_file` | `CLIENT_CA_FILE` | `string` | **optional** | +### Examples {#client-certificate-authority-examples} + +```yaml +client_ca: base64-encoded-string +client_ca_file: base64-encoded-string +``` + +```bash +CLIENT_CA=/relative/file/location + +CLIENT_CA_FILE=/relative/file/location +``` + @@ -188,13 +201,3 @@ Kubernetes does not support `client_certificate_ca` - -### Examples {#client-certificate-authority-examples} - -```yaml -client_ca: base64-encoded-string -client_ca_file: base64-encoded-string - -CLIENT_CA=/relative/file/location -CLIENT_CA_FILE=/relative/file/location -``` diff --git a/content/docs/reference/codec-type.mdx b/content/docs/reference/codec-type.mdx index 1219fe7b5..b8aa2682a 100644 --- a/content/docs/reference/codec-type.mdx +++ b/content/docs/reference/codec-type.mdx @@ -6,6 +6,7 @@ keywords: - Codec Type pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ When `auto` is specified, the codec will be determined via `TLS-ALPN-01` or prot | :------------------- | :------------------------ | :------- | :---------- | | `codec_type` | `CODEC_TYPE` | `string` | `auto` | +### Examples + +```yaml +codec_type: http1 +``` + +```bash +CODEC_TYPE=http2 +``` + @@ -40,13 +51,3 @@ Kubernetes does not support `codec_type` - -### Examples - -```yaml -# config file key -codec_type: http1 - -# environment variable -CODEC_TYPE=http2 -``` diff --git a/content/docs/reference/cookies.mdx b/content/docs/reference/cookies.mdx index 71138a15f..d52241ea7 100644 --- a/content/docs/reference/cookies.mdx +++ b/content/docs/reference/cookies.mdx @@ -3,6 +3,8 @@ id: cookies title: Cookies Settings sidebar_label: Cookies Settings description: Learn how to configure Pomerium's cookies settings. +pagination_prev: null +pagination_next: null --- import Tabs from '@theme/Tabs'; @@ -34,6 +36,16 @@ This reference covers all of Pomerium's **Cookies Settings**: | :------------------- | :------------------------ | :------- | :---------- | | `cookie_name` | `COOKIE_NAME` | `string` | `_pomerium` | +#### Examples {#cookie-name-examples} + +```yaml +cookie_name: cookie_name +``` + +```bash +COOKIE_NAME=cookie_name +``` + @@ -48,22 +60,16 @@ This reference covers all of Pomerium's **Cookies Settings**: See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. - - - -### Examples {#cookie-name-examples} +#### Examples {#cookie-name-examples} ```yaml -# config file key -cookie_name: cookie_name - -# environment variable -COOKIE_NAME=cookie_name - -# ingress -cookie.name: cookie_name +cookie: + name: cookie_name ``` + + + ## Cookie Secret {#cookie-secret} **Cookie Secret** is the secret used to encrypt and sign session cookies. If you don't provide a cookie secret, Pomerium will generate one for you. @@ -77,20 +83,7 @@ cookie.name: cookie_name | :------------------- | :------------------------ | :------- | :----------- | | `cookie_secret` | `COOKIE_SECRET` | `string` | **optional** | - - - -`cookie_secret` is a bootstrap configuration setting and is not configurable in the Console. - - - - -See Kubernetes [bootstrap secrets](/docs/deploy/k8s/configure#bootstrap-secrets) for more information. - - - - -### Examples {#cookie-secret-examples} +#### Examples {#cookie-secret-examples} Generate a random, base64-encoded key: @@ -102,10 +95,25 @@ Add the value to your configuration: ```yaml cookie_secret: tdkuWzUelRukP/6VYzopfh6kis7y5u5Ldl3MrIq9ZR0= +``` +```bash COOKIE_SECRET=tdkuWzUelRukP/6VYzopfh6kis7y5u5Ldl3MrIq9ZR0= ``` + + + +`cookie_secret` is a bootstrap configuration setting and is not configurable in the Console. + + + + +See Kubernetes [bootstrap secrets](/docs/deploy/k8s/configure#bootstrap-secrets) for more information. + + + + ## Cookie Domain {#cookie-domain} **Cookie Domain** sets the scope of session cookies issued by Pomerium. @@ -121,6 +129,16 @@ If you specify the domain explicitly, then subdomains would also be included. | :-- | :-- | :-- | :-- | :-- | | `cookie_domain` | `COOKIE_DOMAIN` | `string` | **optional** | The host that set the cookie | +#### Examples {#cookie-domain-examples} + +```yaml +cookie_domain: localhost.pomerium.io +``` + +```bash +COOKIE_DOMAIN=localhost.pomerium.io +``` + @@ -133,23 +151,17 @@ If you specify the domain explicitly, then subdomains would also be included. | :-------------- | :------- | :----------- | :--------------------------- | | `cookie.domain` | `string` | **optional** | The host that set the cookie | -See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. - - - - -### Examples {#cookie-domain-examples} +#### Examples {#cookie-domain-examples} ```yaml -# config file key -cookie_domain: localhost.pomerium.io +cookie: + domain: localhost.pomerium.io +``` -# environment variable -COOKIE_DOMAIN=localhost.pomerium.io +See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. -# ingress -cookie.domain: localhost.pomerium.io -``` + + ## Cookie Secure {#cookie-secure} @@ -172,6 +184,16 @@ Note: this cannot be set to `false` if [**Cookie SameSite**](#cookie-samesite) i | :------------------- | :------------------------ | :-------- | :---------- | | `cookie_secure` | `COOKIE_SECURE` | `boolean` | `true` | +#### Examples {#cookie-secure-examples} + +```yaml +cookie_secure: false +``` + +```bash +COOKIE_SECURE=false +``` + @@ -190,23 +212,17 @@ Configure **Cookie Secure** with the **HTTPS only** toggle button in the Console | :-------------- | :-------- | :---------- | | `cookie.secure` | `boolean` | `true` | -See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. - - - - -### Examples {#cookie-secure-examples} +#### Examples {#cookie-secure-examples} ```yaml -# config file key -cookie_secure: false +cookie: + secure: false +``` -# environment variable -COOKIE_SECURE=false +See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. -# ingress -cookie.secure: false -``` + + ## Cookie HTTP Only {#cookie-http-only} @@ -221,6 +237,16 @@ If true, **Cookie HTTP Only** forbids JavaScript from accessing the cookie. | :------------------- | :------------------------ | :-------- | :---------- | | `cookie_http_only` | `COOKIE_HTTP_ONLY` | `boolean` | `true` | +#### Examples {#cookie-http-only-examples} + +```yaml +cookie_http_only: false +``` + +```bash +COOKIE_HTTP_ONLY=false +``` + @@ -239,23 +265,17 @@ Configure **Cookie HTTP Only** with the **Javascript Security** toggle button in | :---------------- | :-------- | :---------- | | `cookie.httpOnly` | `boolean` | `true` | -See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. - - - - -### Examples {#cookie-http-only-examples} +#### Examples {#cookie-http-only-examples} ```yaml -# config file key -cookie_http_only: false +cookie: + httpOnly: false +``` -# environment variable -COOKIE_HTTP_ONLY=false +See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. -# ingress -cookie.httpOnly: false -``` + + ## Cookie Expiration {#cookie-expiration} @@ -270,6 +290,16 @@ cookie.httpOnly: false | :-- | :-- | :-- | :-- | | `cookie_expiration` | `COOKIE_EXPIRATION` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `14h` | +#### Examples {#cookie-expiration-examples} + +```yaml +cookie_expiration: 13h15m0.5s +``` + +```bash +COOKIE_EXPIRATION=13h15m0.5s +``` + @@ -280,25 +310,19 @@ Set **Cookie Expiration** in the Console: ![Setting the cookie expiration time i | **Name** | **Type** | **Default** | | :-- | :-- | :-- | -| `authenticate.expiration` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `14h` | +| `cookie.expire` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `14h` | -See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. - - - - -### Examples {#cookie-expiration-examples} +#### Examples {#cookie-expiration-examples} ```yaml -# config file key -cookie_expiration: 13h15m0.5s +cookie: + expire: 13h15m0.5s +``` -# environment variable -COOKIE_EXPIRATION=13h15m0.5s +See Kubernetes [Cookie Reference](/docs/deploy/k8s/reference#cookie) for more information. -# ingress -cookie.expiration: 13h15m0.5s -``` + + ## Cookie SameSite {#cookie-samesite} @@ -313,6 +337,16 @@ cookie.expiration: 13h15m0.5s | :-- | :-- | :-- | :-- | :-- | :-- | | `cookie_same_site` | `COOKIE_SAME_SITE` | `string` | **optional** | ` Lax` (if unset) | See [Cookie SameSite Options](#cookie-samesite-options) | +#### Examples {#cookie-samesite-examples} + +```yaml +cookie_same_site: Lax +``` + +```bash +COOKIE_SAME_SITE=Strict +``` + @@ -329,6 +363,13 @@ See [Cookie SameSite Options](#cookie-samesite-options) for more information. | :-- | :-- | :-- | :-- | :-- | | `cookie.sameSite` | `string` | **optional** | ` Lax` (if unset) | See [Cookie SameSite Options](#cookie-samesite-options) | +#### Examples {#cookie-samesite-examples} + +```yaml +cookie: + sameSite: None +``` + @@ -340,19 +381,6 @@ See [Cookie SameSite Options](#cookie-samesite-options) for more information. | `Strict` | The browser sends the cookie only for same-site requests, that is, requests originating from the same site that set the cookie. | | `None` | The browser sends the cookie with both cross-site and same-site requests. If you set `SameSite=none`, the [HTTPS only](/docs/reference/cookies#cookie-secure) setting must be set to `true`. | | -### Examples {#cookie-samesite-examples} - -```yaml -# config file key -cookie_same_site: Lax - -# environment variable -COOKIE_SAME_SITE=Strict - -# ingress -cookie.sameSite: None -``` - ## Cookie Secret File {#cookie-secret-file} **Cookie Secret File** sets the path to the file containing a secret used to encrypt and sign session cookies. @@ -366,20 +394,7 @@ cookie.sameSite: None | :-- | :-- | :-- | :-- | | `cookie_secret_file` | `COOKIE_SECRET_FILE` | `string` | **required** (for proxy service) | - - - -`cookie_secret_file` is a bootstrap configuration setting and is not configurable in the Console. - - - - -See Kubernetes [Secrets reference](/docs/deploy/k8s/reference#spec) for more information. - - - - -### Examples {#cookie-secret-file-examples} +#### Examples {#cookie-secret-file-examples} Generate a random, base64-encoded key: @@ -391,8 +406,23 @@ Add the value to your configuration: ```yaml cookie_secret_file: '/run/secrets/POMERIUM_COOKIE_SECRET' +``` +```bash COOKIE_SECRET_FILE='/run/secrets/POMERIUM_COOKIE_SECRET' ``` This is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/). + + + + +`cookie_secret_file` is a bootstrap configuration setting and is not configurable in the Console. + + + + +See Kubernetes [Secrets reference](/docs/deploy/k8s/reference#spec) for more information. + + + diff --git a/content/docs/reference/databroker.mdx b/content/docs/reference/databroker.mdx index 5c93f3da9..8568e0dab 100644 --- a/content/docs/reference/databroker.mdx +++ b/content/docs/reference/databroker.mdx @@ -2,6 +2,8 @@ id: databroker title: Databroker Settings sidebar_label: Databroker Settings +pagination_prev: null +pagination_next: null --- import Tabs from '@theme/Tabs'; @@ -49,6 +51,18 @@ For an example implementation, see the in-memory database used by the databroker | `databroker_service_url` | `DATABROKER_SERVICE_URL` | `URL` | `http://localhost:5443` (In all-in-one mode) | | `databroker_service_urls` | `DATABROKER_SERVICE_URLS` | `URL` | `http://localhost:5443` (In all-in-one mode) | +#### Examples {#databroker-service-url-examples} + +```yaml +databroker_service_urls: + - http://databroker.corp.example1.com + - https://databroker.corp.example2.com +``` + +```bash +DATABROKER_SERVICE_URL=https://databroker.corp.example.com +``` + @@ -62,16 +76,6 @@ For an example implementation, see the in-memory database used by the databroker -### Examples {#databroker-service-url-examples} - -```yaml -databroker_service_urls: - - http://databroker.corp.example1.com - - https://databroker.corp.example2.com - -DATABROKER_SERVICE_URL=https://databroker.corp.example.com -``` - ## Databroker Internal Service URL {#databroker-internal-service-url} **Databroker Internal Service URL** overrides [`databroker_service_url`](/docs/reference/databroker) when determining the TLS Certificate for the Databroker service to listen with. @@ -86,6 +90,18 @@ DATABROKER_SERVICE_URL=https://databroker.corp.example.com | `databroker_internal_service_url` | `DATABROKER_INTERNAL_SERVICE_URL` | `URL` | `http://localhost:5443` (In all-in-one mode) | | `databroker_internal_service_urls` | `DATABROKER_INTERNAL_SERVICE_URLS` | `URL` | `http://localhost:5443` (In all-in-one mode) | +#### Examples {#databroker-internal-service-url-examples} + +```yaml +databroker_internal_service_urls: + - http://localhost:5443 + - http://service_url.com +``` + +```bash +DATABROKER_INTERNAL_SERVICE_URL=http://localhost:5443 +``` + @@ -99,16 +115,6 @@ DATABROKER_SERVICE_URL=https://databroker.corp.example.com -### Examples {#databroker-internal-service-url-examples} - -```yaml -databroker_internal_service_urls: - - http://localhost:5443 - - http://service_url.com - -DATABROKER_INTERNAL_SERVICE_URL=http://localhost:5443 -``` - ## Databroker Storage Certificate Authority {#databroker-storage-certificate-authority} **Databroker Storage Certificate Authority** defines the set of root certificates used when verifying storage server connections. @@ -122,6 +128,16 @@ DATABROKER_INTERNAL_SERVICE_URL=http://localhost:5443 | :-- | :-- | :-- | :-- | | `databroker_storage_ca_file` | `DATABROKER_STORAGE_CA_FILE` | `string` | **optional** | +#### Examples {#databroker-storage-certificate-authority-examples} + +```yaml +databroker_storage_ca_file: /relative/file/location +``` + +```bash +DATABROKER_STORAGE_CA_FILE=/relative/file/location +``` + @@ -135,14 +151,6 @@ See Kubernetes [Storage reference](/docs/deploy/k8s/reference#storage) for more -### Examples {#databroker-storage-certificate-authority-examples} - -```yaml -databroker_storage_ca_file: /relative/file/location - -DATABROKER_STORAGE_CA_FILE=/relative/file/location -``` - ## Databroker Storage Certificate File {#databroker-storage-certificate-file} **Databroker Storage Certificate File** stores the certificate used to connect to a storage backend. @@ -156,6 +164,16 @@ DATABROKER_STORAGE_CA_FILE=/relative/file/location | :-- | :-- | :-- | :-- | | `databroker_storage_cert_file` | `DATABROKER_STORAGE_CERT_FILE` | `string` | **optional** | +#### Examples {#databroker-storage-certificate-file-examples} + +```yaml +databroker_storage_cert_file: /relative/file/location +``` + +```bash +DATABROKER_STORAGE_CERT_FILE=/relative/file/location +``` + @@ -169,14 +187,6 @@ See Kubernetes [Storage reference](/docs/deploy/k8s/reference#storage) for more -### Examples {#databroker-storage-certificate-file-examples} - -```yaml -databroker_storage_cert_file: /relative/file/location - -DATABROKER_STORAGE_CERT_FILE=/relative/file/location -``` - ## Databroker Storage Certificate Key File {#databroker-storage-certificate-key-file} **Databroker Storage Certificate Key File** stores the certificate key used to connect to a storage backend. @@ -190,6 +200,16 @@ DATABROKER_STORAGE_CERT_FILE=/relative/file/location | :-- | :-- | :-- | :-- | | `databroker_storage_key_file` | `DATABROKER_STORAGE_KEY_FILE` | `string` | **optional** | +#### Examples {#databroker-storage-certificate-key-file-examples} + +```yaml +databroker_storage_key_file: /relative/file/location +``` + +```bash +DATABROKER_STORAGE_KEY_FILE=/relative/file/location +``` + @@ -203,13 +223,6 @@ See Kubernetes [Storage reference](/docs/deploy/k8s/reference#storage) for more -### Examples {#databroker-storage-certificate-key-file-examples} - -```yaml -databroker_storage_key_file: /relative/file/location -DATABROKER_STORAGE_KEY_FILE=/relative/file/location -``` - ## Databroker Storage Connection String {#databroker-storage-connection-string} **Databroker Storage Connection String** sets the Postgres connection string that the Databroker service uses to connect to storage backend. @@ -230,6 +243,16 @@ See the [PostgreSQL connection URI docs](https://www.postgresql.org/docs/current | :-- | :-- | :-- | :-- | | `databroker_storage_connection_string` | `DATABROKER_STORAGE_CONNECTION_STRING` | `string` | **required** | +#### Examples {#databroker-storage-connection-string-examples} + +```yaml +databroker_storage_connection_string: postgresql://postgres:postgres@database/postgres?sslmode=disable +``` + +```bash +DATABROKER_STORAGE_CONNECTION_STRING=postgresql://postgres:postgres@database/postgres?sslmode=disable +``` + @@ -243,14 +266,6 @@ See Kubernetes [Storage reference](/docs/deploy/k8s/reference#storage) for more -### Examples {#databroker-storage-connection-string-examples} - -```yaml -databroker_storage_connection_string: postgresql://postgres:postgres@database/postgres?sslmode=disable - -DATABROKER_STORAGE_CONNECTION_STRING=postgresql://postgres:postgres@database/postgres?sslmode=disable -``` - :::tip When using multiple hosts make sure to specify `target_session_attrs=read-write` so that the Databroker does not attempt to write to a read-only replica. @@ -270,6 +285,16 @@ If **Databroker Storage TLS Skip Verify** is set, the TLS connection to the stor | :-- | :-- | :-- | :-- | | `databroker_storage_tls_skip_verify` | `DATABROKER_STORAGE_TLS_SKIP_VERIFY` | `string` | **optional** | +#### Examples {#databroker-storage-tls-skip-verify-examples} + +```yaml +databroker_storage_tls_skip_verify: /relative/file/location +``` + +```bash +DATABROKER_STORAGE_TLS_SKIP_VERIFY=/relative/file/location +``` + @@ -283,14 +308,6 @@ See Kubernetes [Storage reference](/docs/deploy/k8s/reference#storage) for more -### Examples {#databroker-storage-tls-skip-verify-examples} - -```yaml -databroker_storage_tls_skip_verify: /relative/file/location - -DATABROKER_STORAGE_TLS_SKIP_VERIFY=/relative/file/location -``` - ## Databroker Storage Type {#databroker-storage-type} **Databroker Storage Type** sets the backend storage that the Databroker server will use. @@ -306,6 +323,16 @@ Only `memory` and `postgres` are supported. | :-- | :-- | :-- | :-- | :-- | | `databroker_storage_type` | `DATABROKER_STORAGE_TYPE` | `string` | **required** | **memory** | +### Examples {#databroker-storage-type-example} + +```yaml +databroker_storage_type: postgres +``` + +```bash +DATABROKER_STORAGE_TYPE=postgres +``` + @@ -318,11 +345,3 @@ See Kubernetes [Storage reference](/docs/deploy/k8s/reference#storage) for more - -### Example {#databroker-storage-type-example} - -```yaml -databroker_storage_type: postgres - -DATABROKER_STORAGE_TYPE=postgres -``` diff --git a/content/docs/reference/debug.mdx b/content/docs/reference/debug.mdx index 48153be9c..0ccb37b15 100644 --- a/content/docs/reference/debug.mdx +++ b/content/docs/reference/debug.mdx @@ -8,6 +8,7 @@ keywords: - Debug pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; diff --git a/content/docs/reference/default-upstream-timeout.mdx b/content/docs/reference/default-upstream-timeout.mdx index 4d112376d..d2bbbbdce 100644 --- a/content/docs/reference/default-upstream-timeout.mdx +++ b/content/docs/reference/default-upstream-timeout.mdx @@ -8,6 +8,7 @@ keywords: - Default Upstream Timeout pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -30,6 +31,16 @@ See [Global Timeouts](/docs/reference/global-timeouts) for more information. | :-- | :-- | :-- | :-- | | `default_upstream_timeout` | `DEFAULT_UPSTREAM_TIMEOUT` | `string` | `30s` ([Go Duration](https://pkg.go.dev/time#Duration) formatting) | +### Examples + +```yaml +default_upstream_timeout: 30s +``` + +```bash +DEFAULT_UPSTREAM_TIMEOUT: 1h45m +``` + @@ -44,11 +55,3 @@ Kubernetes does not support `default_upstream_timeout` - -### Examples - -```yaml -default_upstream_timeout: 30s - -DEFAULT_UPSTREAM_TIMEOUT: 1h45m -``` diff --git a/content/docs/reference/dns-lookup-family.mdx b/content/docs/reference/dns-lookup-family.mdx index 6a91f3221..67ca72f4f 100644 --- a/content/docs/reference/dns-lookup-family.mdx +++ b/content/docs/reference/dns-lookup-family.mdx @@ -8,6 +8,7 @@ keywords: - DNS Lookup Family pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ import TabItem from '@theme/TabItem'; | :------------------- | :------------------------ | :------- | :------------- | | `dns_lookup_family` | `DNS_LOOKUP_FAMILY` | `string` | `V4_PREFERRED` | +### Examples + +```yaml +default_lookup_family: AUTO +``` + +```bash +DEFAULT_LOOKUP_FAMILY=V6_ONLY +``` + @@ -55,11 +66,3 @@ Kubernetes does not support `dns_lookup_family` | `ALL` | DNS resolver will perform a lookup for both IPv4 and IPv6 families, and return all resolved addresses | See the [Envoy docs](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto.html#enum-config-cluster-v3-cluster-dnslookupfamily) for more information about these options. - -### Examples - -```yaml -default_lookup_family: AUTO - -DEFAULT_LOOKUP_FAMILY=V6_ONLY -``` diff --git a/content/docs/reference/downstream-mtls-settings.mdx b/content/docs/reference/downstream-mtls-settings.mdx index c38c760f6..e68c6a244 100644 --- a/content/docs/reference/downstream-mtls-settings.mdx +++ b/content/docs/reference/downstream-mtls-settings.mdx @@ -10,6 +10,7 @@ keywords: - mTLS pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -49,19 +50,6 @@ The CA bundle can be specified inline (with the `ca` key or the `DOWNSTREAM_MTLS | `downstream_mtls.ca` | `DOWNSTREAM_MTLS_CA` | string (base64-encoded PEM certificate bundle) | | `downstream_mtls.ca_file` | `DOWNSTREAM_MTLS_CA_FILE` | string (path to PEM certificate bundle) | - - - -These settings are not configurable in the Enterprise Console. - - - - -The Ingress Controller does not support these settings. - - - - ### Examples {#ca-examples} ```yaml @@ -82,6 +70,19 @@ DOWNSTREAM_MTLS_CA=LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk... DOWNSTREAM_MTLS_CA_FILE=/path/to/trusted/CAs.pem ``` + + + +These settings are not configurable in the Enterprise Console. + + + + +The Ingress Controller does not support these settings. + + + + ## Certificate Revocation List (CRL) {#crl} :::caution @@ -108,19 +109,6 @@ A CRL bundle can be specified inline (with the `crl` key or the `DOWNSTREAM_MTLS | `downstream_mtls.crl` | `DOWNSTREAM_MTLS_CRL` | string (base64-encoded PEM CRL bundle) | | `downstream_mtls.crl_file` | `DOWNSTREAM_MTLS_CRL_FILE` | string (path to PEM CRL bundle) | - - - -These settings are not configurable in the Enterprise Console. - - - - -The Ingress Controller does not support these settings. - - - - ### Examples {#crl-examples} ```yaml @@ -141,6 +129,19 @@ DOWNSTREAM_MTLS_CRL=LS0tLS1CRUdJTiBYNTA5IENSTC0tLS0tCk... DOWNSTREAM_MTLS_CRL_FILE=/path/to/CRLs.pem ``` + + + +These settings are not configurable in the Enterprise Console. + + + + +The Ingress Controller does not support these settings. + + + + ## Enforcement Mode **Enforcement Mode** controls Pomerium's behavior when a client does not present a trusted client certificate. There are three options: @@ -182,6 +183,17 @@ DOWNSTREAM_MTLS_CRL_FILE=/path/to/CRLs.pem | :-- | :-- | :-- | | `downstream_mtls.enforcement` | `DOWNSTREAM_MTLS_ENFORCEMENT` | string (one of `policy_with_default_deny`, `policy`, or `reject_connection`) | +### Examples {#enforcement-mode-examples} + +```yaml +downstream_mtls: + enforcement: reject_connection +``` + +```bash +DOWNSTREAM_MTLS_ENFORCEMENT=reject_connection +``` + @@ -195,17 +207,6 @@ The Ingress Controller does not support this setting. -### Examples {#enforcement-mode-examples} - -```yaml -downstream_mtls: - enforcement: reject_connection -``` - -```bash -DOWNSTREAM_MTLS_ENFORCEMENT=reject_connection -``` - ## Match Subject Alt Names {#match-sans} **Match Subject Alt Names** can be used to add an additional constraint when validating client certificates: each certificate must contain a Subject Alternative Name (SAN) of a particular type, whose value matches the provided regular expression. @@ -232,19 +233,6 @@ SAN IPv4 addresses will be expressed in dotted decimal notation (e.g. "127.0.0.1 | :-- | :-- | :-- | | `downstream_mtls.match_subject_alt_names` | n/a | array of mappings from SAN type to regular expression | - - - -This setting is not configurable in the Enterprise Console. - - - - -The Ingress Controller does not support this setting. - - - - ### Examples {#match-sans-examples} To require that all client certificates have a DNS SAN with a domain name ending in ".corp.example.com": @@ -264,6 +252,19 @@ downstream_mtls: - email: '.*@example\.com' ``` + + + +This setting is not configurable in the Enterprise Console. + + + + +The Ingress Controller does not support this setting. + + + + ## Max Verify Depth **Max Verify Depth** sets a limit on the depth of a certificate chain presented by the client. The depth is defined as the number of certificates in the verified trust chain, _excluding_ the trust anchor. (The trust anchor can be any root or intermediate CA certificate included in the trusted [**CA**](#ca) bundle.) This limit does not override any `pathLenConstraint` set within the CA certificates themselves (see [RFC 5280 §4.2.1.9](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.9)). @@ -306,19 +307,6 @@ Note that a client presenting "Certificate B" must also include the "Intermediat | :-- | :-- | :-- | | `downstream_mtls.max_verify_depth` | `DOWNSTREAM_MTLS_MAX_VERIFY_DEPTH` | unsigned integer | - - - -This setting is not configurable in the Enterprise Console. - - - - -The Ingress Controller does not support this setting. - - - - ### Examples {#max-verify-depth-examples} To allow client certificate chains including the leaf certificate and at most one client-supplied intermediate CA certificate (before a trusted root or intermediate CA): @@ -342,3 +330,16 @@ downstream_mtls: ```bash DOWNSTREAM_MTLS_MAX_VERIFY_DEPTH=0 ``` + + + + +This setting is not configurable in the Enterprise Console. + + + + +The Ingress Controller does not support this setting. + + + diff --git a/content/docs/reference/global-timeouts.mdx b/content/docs/reference/global-timeouts.mdx index 64fbba6cb..40e1bdfe2 100644 --- a/content/docs/reference/global-timeouts.mdx +++ b/content/docs/reference/global-timeouts.mdx @@ -8,6 +8,7 @@ keywords: - Global Timeouts pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -30,6 +31,16 @@ import TabItem from '@theme/TabItem'; | `timeout_write` | `TIMEOUT_WRITE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `0` | The max stream duration is the maximum time that a stream’s lifetime will span. An HTTP request/response exchange fully consumes a single stream. Therefore, this value must be greater than `read_timeout` as it covers both request and response time. | | `timeout_idle` | `TIMEOUT_IDLE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `5m` | The idle timeout is the time at which a downstream or upstream connection will be terminated if there are no active streams. | +### Examples + +```yaml +timeout_read: 30s +``` + +```bash +TIMEOUT_WRITE=0 +``` + @@ -38,17 +49,30 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time -See [`timeouts`](/docs/deploy/k8s/reference#timeouts) section of the global configuration CRD. - - - +| **Annotation name** | **Type** | **Defaults** | **Definition** | +| :-- | :-- | :-- | :-- | +| `timeouts.read` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `30s` | The amount of time for the entire request stream to be received from the client. | +| `timeouts.write` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `0` | The max stream duration is the maximum time that a stream’s lifetime will span. An HTTP request/response exchange fully consumes a single stream. Therefore, this value must be greater than `read_timeout` as it covers both request and response time. | +| `timeouts.idle` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `5m` | The idle timeout is the time at which a downstream or upstream connection will be terminated if there are no active streams. | ### Examples ```yaml -timeout_read: 30s +timeouts: + read: 30s +``` -# Or +```yaml +timeouts: + write: 0 +``` -TIMEOUT_WRITE=0 +```yaml +timeouts: + idle: 5m ``` + +See [`timeouts`](/docs/deploy/k8s/reference#timeouts) section of the global configuration CRD. + + + diff --git a/content/docs/reference/google-cloud-serverless-authentication-service-account.mdx b/content/docs/reference/google-cloud-serverless-authentication-service-account.mdx index 6d353a442..a567143c6 100644 --- a/content/docs/reference/google-cloud-serverless-authentication-service-account.mdx +++ b/content/docs/reference/google-cloud-serverless-authentication-service-account.mdx @@ -7,6 +7,7 @@ keywords: description: Manually set Google Cloud Serverless Authentication Service Account credentials with this setting. pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -31,6 +32,16 @@ If unspecified, the service account credentials will default to ambient credenti See [Enable Google Cloud Serverless Authentication](/docs/reference/routes/enable-google-cloud-serverless-authentication) for more information. +### Examples + +```yaml +google_cloud_serverless_authentication_service_account: base64-encoded-service-account-credentials +``` + +```bash +GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT=base64-encoded-service-account-credentials +``` + @@ -43,13 +54,3 @@ Kubernetes does not support `google_cloud_serverless_authentication_service_acco - -### Examples - -```yaml -# config file key -google_cloud_serverless_authentication_service_account: base64-encoded-service-account-credentials - -# environment variable -GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION_SERVICE_ACCOUNT=base64-encoded-service-account-credentials -``` diff --git a/content/docs/reference/grpc.mdx b/content/docs/reference/grpc.mdx index 863248447..03ccdd315 100644 --- a/content/docs/reference/grpc.mdx +++ b/content/docs/reference/grpc.mdx @@ -3,6 +3,9 @@ title: gRPC Settings sidebar_label: gRPC Settings keywords: [grpc] description: Configure gRPC configuration settings in Pomerium. +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -30,6 +33,16 @@ This reference covers all of Pomerium's **gRPC Settings**: | :-- | :-- | :-- | :-- | | `grpc_address` | `GRPC_ADDRESS` | `string` | `:443` (`:5443` if in [all-in-one](/docs/internals/configuration#all-in-one-vs-split-service-mode) mode) | +### Examples {#examples-grpc-address} + +```yaml +grpc_address: :8443 +``` + +```bash +GRPC_ADDRESS=:8443 +``` + @@ -43,16 +56,6 @@ This reference covers all of Pomerium's **gRPC Settings**: -### Examples {#examples-grpc-address} - -```yaml -# config file key -grpc_address: :8443 - -# environment variable -GRPC_ADDRESS=:8443 -``` - ## gRPC Client DNS RoundRobin {#grpc-client-dns-roundrobin} **gRPC Client DNS RoundRobin** enables DNS-based round-robin load balancing. This method uses DNS to resolve endpoints and distributes load balancing of _all_ addresses returned by the DNS record client side. **Do not disable** unless you have a specific use case. @@ -66,6 +69,16 @@ GRPC_ADDRESS=:8443 | :-- | :-- | :-- | :-- | | `grpc_client_dns_roundrobin` | `GRPC_CLIENT_DNS_ROUNDROBIN` | `boolean` | `true` | +### Examples {#examples-grpc-client-dns-roundrobin} + +```yaml +grpc_client_dns_roundrobin: false +``` + +```bash +GRPC_CLIENT_DNS_ROUNDROBIN=false +``` + @@ -79,16 +92,6 @@ Kubernetes does not support **gRPC Client DNS RoundRobin** -### Examples {#examples-grpc-client-dns-roundrobin} - -```yaml -# config file key -grpc_client_dns_roundrobin: false - -# environment variable -GRPC_CLIENT_DNS_ROUNDROBIN=false -``` - ## gRPC Client Timeout {#grpc-client-timeout} **gRPC Client Timeout** sets the maximum time before canceling an upstream gRPC request. During transient failures, the proxy will retry upstream servers for this duration. You should leave this high enough to handle backend service restart and rediscovery so that client requests do not fail. @@ -102,6 +105,16 @@ GRPC_CLIENT_DNS_ROUNDROBIN=false | :-- | :-- | :-- | :-- | | `grpc_client_timeout` | `GRPC_CLIENT_TIMEOUT` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `10s` | +### Examples {#examples-grpc-client-timeout} + +```yaml +grpc_client_timeout: 15s +``` + +```bash +GRPC_CLIENT_TIMEOUT=15s +``` + @@ -115,16 +128,6 @@ Kubernetes does not support **gRPC Client Timeout** -### Examples {#examples-grpc-client-timeout} - -```yaml -# config file key -grpc_client_timeout: 15s - -# environment variable -GRPC_CLIENT_TIMEOUT=15s -``` - ## gRPC Insecure {#grpc-insecure} **gRPC Insecure** disables transport security for gRPC communication. If running in [all-in-one](/docs/internals/configuration#all-in-one-vs-split-service-mode) mode, defaults to true as communication will run over localhost's own socket. @@ -138,6 +141,16 @@ GRPC_CLIENT_TIMEOUT=15s | :-- | :-- | :-- | :-- | | `grpc_insecure` | `GRPC_INSECURE` | `boolean` | `true` (If in [all-in-one](/docs/internals/configuration#all-in-one-vs-split-service-mode) mode) | +### Examples {#examples-grpc-insecure} + +```yaml +grpc_insecure: false +``` + +```bash +GRPC_INSECURE=false +``` + @@ -150,13 +163,3 @@ GRPC_CLIENT_TIMEOUT=15s - -### Examples {#examples-grpc-insecure} - -```yaml -# config file key -grpc_insecure: false - -# environment variable -GRPC_INSECURE=false -``` diff --git a/content/docs/reference/http-redirect-address.mdx b/content/docs/reference/http-redirect-address.mdx index ae5f69b50..2cc6c0a32 100644 --- a/content/docs/reference/http-redirect-address.mdx +++ b/content/docs/reference/http-redirect-address.mdx @@ -8,6 +8,7 @@ keywords: - HTTP Redirect Address pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ If set, **HTTP Redirect Address** specifies the host and port to redirect HTTP t | :------------------- | :------------------------ | :------- | :----------- | | `http_redirect_addr` | `HTTP_REDIRECT_ADDR` | `string` | **optional** | +### Examples + +```yaml +http_redirect_addr: :80 +``` + +```bash +HTTP_REDIRECT_ADDR=:8080 +``` + @@ -40,13 +51,3 @@ Set **HTTP Redirect Address** in the Console: ![Set HTTP redirect address in the - -### Examples - -```yaml -# config file key -http_redirect_addr: :80 - -# environment variable -HTTP_REDIRECT_ADDR=:8080 -``` diff --git a/content/docs/reference/identity-provider-settings.mdx b/content/docs/reference/identity-provider-settings.mdx index 9fa3c38fc..85cc5b3e9 100644 --- a/content/docs/reference/identity-provider-settings.mdx +++ b/content/docs/reference/identity-provider-settings.mdx @@ -50,6 +50,16 @@ Pomerium can also integrate with any identity provider that supports OAuth 2.0 a | :-- | :-- | :-- | :-- | | `idp_client_id` | `IDP_CLIENT_ID` | `string` | **required** (if self-hosting) | +#### Examples {#identity-provider-client-id-examples} + +```yaml +idp_client_id: idp_client_id +``` + +```bash +IDP_CLIENT_ID=idp_client_id +``` + @@ -65,16 +75,6 @@ See [`identityProvider.secret`](/docs/deploy/k8s/reference#identityprovider) -### Examples {#identity-provider-client-id-examples} - -```yaml -# config file key -idp_client_id: idp_client_id - -# environment variable -IDP_CLIENT_ID=idp_client_id -``` - ## Identity Provider Client Secret {#identity-provider-client-secret} **Identity Provider Client Secret** is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and Pomerium's [identity provider](/docs/identity-providers/) docs for details. @@ -88,6 +88,16 @@ IDP_CLIENT_ID=idp_client_id | :-- | :-- | :-- | :-- | | `idp_client_secret` | `IDP_CLIENT_SECRET` | `string` | **required** (unless using [idp_client_secret_file](#identity-provider-client-secret-file)) | +#### Examples {#identity-provider-client-secret-examples} + +```yaml +idp_client_secret: idp_client_secret +``` + +```bash +IDP_CLIENT_SECRET=idp_client_secret +``` + @@ -103,16 +113,6 @@ See [`identityProvider.secret`](/docs/deploy/k8s/reference#identityprovider) for -### Examples {#identity-provider-client-secret-examples} - -```yaml -# config file key -idp_client_secret: idp_client_secret - -# environment variable -IDP_CLIENT_SECRET=idp_client_secret -``` - ## Identity Provider Client Secret File {#identity-provider-client-secret-file} **Identity Provider Client Secret File** is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and Pomerium's [identity provider](/docs/identity-providers/) docs for details. @@ -128,6 +128,16 @@ The identity provider client secret file points to a file containing the secret. | :-- | :-- | :-- | :-- | | `idp_client_secret_file` | `IDP_CLIENT_SECRET_FILE` | `string` | **required** (unless using [identity_provider_client_secret](#identity-provider-client-secret)) | +#### Examples {#identity-provider-client-secret-file-examples} + +```yaml +idp_client_secret_file: '/run/secrets/POMERIUM_CLIENT_SECRET' +``` + +```bash +IDP_CLIENT_SECRET_FILE='/run/secrets/POMERIUM_CLIENT_SECRET' +``` + @@ -141,16 +151,6 @@ See [`identityProvider.secret`](/docs/deploy/k8s/reference#identityprovider) for -### Examples {#identity-provider-client-secret-file-examples} - -```yaml -# config file key -idp_client_secret_file: '/run/secrets/POMERIUM_CLIENT_SECRET' - -# environment variable -IDP_CLIENT_SECRET_FILE='/run/secrets/POMERIUM_CLIENT_SECRET' -``` - ## Identity Provider Name {#identity-provider-name} **Identity Provider Name** is the short-hand name of a built-in OpenID Connect (OIDC) identity provider used for authentication. @@ -180,6 +180,16 @@ The supported values for this setting are: | :-- | :-- | :-- | :-- | | `idp_provider` | `IDP_PROVIDER` | `string` | **required** (if [self-hosting](/docs/capabilities/self-hosted-authenticate-service)) | +#### Examples {#identity-provider-name-examples} + +```yaml +idp_provider: auth0 +``` + +```bash +IDP_PROVIDER=github +``` + @@ -195,16 +205,6 @@ See [`identityProvider.provider`](/docs/deploy/k8s/reference#identityprovider) f -### Examples {#identity-provider-name-examples} - -```yaml -# config file key -idp_provider: auth0 - -# environment variable -IDP_PROVIDER=github -``` - ## Identity Provider Request Params {#identity-provider-request-params} **Identity Provider Request Params** lists the parameters you want to include as part of a sign-in request using the OAuth 2.0 code flow. @@ -218,6 +218,19 @@ IDP_PROVIDER=github | :-- | :-- | :-- | :-- | | `idp_request_params` | `IDP_REQUEST_PARAMS` | `string` (map of key-value pairs) | **optional** | +#### Examples {#identity-provider-request-params-examples} + +```yaml +idp_request_params: + client_id: client_id + response_type: response_type + redirect_uri: redirect_uri +``` + +```bash +IDP_REQUEST_PARAMS='{"client_id":"client_id", "response_type":"response_type", "redirect_uri":"redirect_uri"}' +``` + @@ -249,21 +262,6 @@ Pomerium includes some default parameters for specific identity providers. Setti ::: -### Examples {#identity-provider-request-params-examples} - -```yaml -# config file key -idp_request_params: - client_id: client_id - response_type: response_type - redirect_uri: redirect_uri -``` - -```yaml -# environment variable -IDP_REQUEST_PARAMS='{"client_id":"client_id", "response_type":"response_type", "redirect_uri":"redirect_uri"}' -``` - For more information, see: - [OIDC Request Parameters](https://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters) @@ -294,6 +292,16 @@ Some providers, like Amazon Cognito, _do not_ support the `offline_access` scope | :-- | :-- | :-- | :-- | | `idp_scopes` | `IDP_SCOPES` | `string` (list) | **optional** (for built-in identity providers) | +#### Examples {#identity-provider-scopes-examples} + +```yaml +idp_scopes: openid, profile, offline_access, email +``` + +```bash +IDP_SCOPES=openid, profile, offline_access, email +``` + @@ -318,16 +326,6 @@ See Kubernetes [`identityProvider.scopes`](/docs/deploy/k8s/reference#identitypr | `email` | | `offline_access` | -### Examples {#identity-provider-scopes-examples} - -```yaml -# config file key -idp_scopes: openid, profile, offline_access, email - -# environment variable -IDP_SCOPES=openid, profile, offline_access, email -``` - ## Identity Provider URL {#identity-provider-url} **Identity Provider URL** is the base path to an identity provider's [OpenID connect discovery document](https://openid.net/specs/openid-connect-discovery-1_0.html). An example Azure URL would be `https://login.microsoftonline.com/common/v2.0` for [their discovery document](https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration). @@ -343,6 +341,16 @@ IDP_SCOPES=openid, profile, offline_access, email | :-- | :-- | :-- | :-- | | `idp_provider_url` | `IDP_PROVIDER_URL` | `string` | **required** (depending on identity provider) | +#### Examples {#identity-provider-url-examples} + +```yaml +idp_provider_url: 'https://awesome-company.auth0.com' +``` + +```bash +IDP_PROVIDER_URL='https://awesome-company.auth0.com' +``` + @@ -358,33 +366,23 @@ See Kubernetes [`identityProvider.url`](/docs/deploy/k8s/reference#identityprovi -### Examples {#identity-provider-url-examples} - -```yaml -# config file key -idp_provider_url: 'https://awesome-company.auth0.com' - -# environment variable -IDP_PROVIDER_URL='https://awesome-company.auth0.com' -``` - ## Identity Provider Polling Min/Max Delay {#identity-provider-polling-minmax-delay} Identity provider **Polling Minimum Delay** and **Polling Maximum Delay** settings define the minimum and maximum delay times between requests to the identity provider data source. A job starts with the **minimum delay** intervals. If the job fails to complete within the minimum delay period, it will be interrupted and the job will restart. If the job is interrupted due to timeout or an error, it will restart with increasing intervals up to the **maximum delay** period. -### How to configure {#identity-provider-polling-minmax-delay-how-to-configure} +:::note -Set the **Identity Provider Max/Min Delay** settings in the Console: +The `minimum_delay` and `maximum_delay` settings are an [**Enterprise Console**](https://www.pomerium.com/enterprise-sales/) feature, and are not configurable in Pomerium Core. -![Set IdP minimum and maximum polling delay settings in the console](./img/idp_options/idp-polling-min-max-delay.png) +::: -:::note +### How to configure {#identity-provider-polling-minmax-delay-how-to-configure} -The `minimum_delay` and `maximum_delay` settings are an [Enterprise Console](https://www.pomerium.com/enterprise-sales/) feature, and are not configurable in Pomerium Core. +Set the **Identity Provider Max/Min Delay** settings in the Console: -::: +![Set IdP minimum and maximum polling delay settings in the console](./img/idp_options/idp-polling-min-max-delay.png) ### Defaults {#identity-provider-polling-minmax-delay-defaults} diff --git a/content/docs/reference/insecure-server.mdx b/content/docs/reference/insecure-server.mdx index 989964ebf..e21e4ea1c 100644 --- a/content/docs/reference/insecure-server.mdx +++ b/content/docs/reference/insecure-server.mdx @@ -8,6 +8,7 @@ keywords: - Insecure Server pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -36,6 +37,16 @@ Pomerium should _never_ be exposed to the internet without TLS encryption. | :-- | :-- | :-- | :-- | | `insecure_server` | `INSECURE_SERVER` | `boolean` | **required** (if [certificates](/docs/reference/certificates) unset) | +### Examples + +```yaml +insecure_server: true +``` + +```bash +INSECURE_SERVER=true +``` + @@ -48,13 +59,3 @@ Kubernetes does not support **Insecure Server** - -### Examples - -```yaml -# config file key -insecure_server: true - -# environment variable -INSECURE_SERVER=true -``` diff --git a/content/docs/reference/jwt-claim-headers.mdx b/content/docs/reference/jwt-claim-headers.mdx index bf2ba6178..c4c84ed54 100644 --- a/content/docs/reference/jwt-claim-headers.mdx +++ b/content/docs/reference/jwt-claim-headers.mdx @@ -9,6 +9,7 @@ keywords: - jwt_claim_headers pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -31,6 +32,14 @@ Forwarding a claim with JWT Claims Headers adds the claim to the X-Pomerium-Jwt- | :------------------- | :------------------------ | :------- | :----------- | | `jwt_claims_headers` | `JWT_CLAIMS_HEADERS` | `string` | **optional** | +### Examples + +```yaml +jwt_claims_headers: + X-Email: email + X-Username: user +``` + @@ -41,9 +50,17 @@ Format **JWT Claims Headers** in the Console: -| **Name** | -| :---------------- | -| `jwtClaimHeaders` | +| **Name** | **Type** | **Usage** | +| :---------------- | :------------- | :----------- | +| `jwtClaimHeaders` | map of strings | **optional** | + +### Examples + +```yaml +jwtClaimHeaders: + X-Email: email + X-Username: user +``` See Kubernetes [jwtClaimHeaders](/docs/deploy/k8s/reference#spec) for more information. @@ -70,7 +87,7 @@ jwt_claims_headers: The JSON payload from this example would look similar to the sample data below: -```JSON +```json "X-Email": [ "user@example.com" ], diff --git a/content/docs/reference/log-level.mdx b/content/docs/reference/log-level.mdx index 04e4a4699..539384b8a 100644 --- a/content/docs/reference/log-level.mdx +++ b/content/docs/reference/log-level.mdx @@ -8,6 +8,7 @@ keywords: - Log Level pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ import TabItem from '@theme/TabItem'; | :------------------- | :------------------------ | :------- | :---------- | | `log_level` | `LOG_LEVEL` | `string` | `debug` | +### Examples + +```yaml +log_level: error +``` + +```bash +LOG_LEVEL=warn +``` + ### Options - `none` @@ -50,13 +61,3 @@ Kubernetes does not support `log_level` - -### Examples - -```yaml -# config file key -log_level: error - -# environment variable -LOG_LEVEL=warn -``` diff --git a/content/docs/reference/metrics.mdx b/content/docs/reference/metrics.mdx index 024829d8e..8dfa08dfc 100644 --- a/content/docs/reference/metrics.mdx +++ b/content/docs/reference/metrics.mdx @@ -3,6 +3,8 @@ title: Metrics Settings sidebar_label: Metrics Settings description: Configure metrics settings in Pomerium. keywords: [metrics] +pagination_prev: null +pagination_next: null --- import Tabs from '@theme/Tabs'; @@ -36,6 +38,16 @@ This reference covers all of Pomerium's **Metrics Settings**: | :-- | :-- | :-- | :-- | :-- | | `metrics_address` | `METRICS_ADDRESS` | `string` | **optional** | `disabled` | +#### Examples {#examples-metrics-address} + +```yaml +metrics_address: :9090 +``` + +```bash +METRICS_ADDRESS: 127.0.0.1:9090 +``` + @@ -49,16 +61,6 @@ See Kubernetes [Metrics](/docs/deploy/k8s/install#metrics) -### Examples {#examples-metrics-address} - -```yaml -# config file key -metrics_address: :9090 - -# environment variable -METRICS_ADDRESS: 127.0.0.1:9090 -``` - ### Pomerium Metrics Tracked Each metric exposed by Pomerium has a `pomerium` prefix, which is omitted in the table below for brevity. @@ -107,7 +109,7 @@ Identity manager metrics have a `pomerium_identity_manager` prefix. | user_refresh_success | Counter | User refresh success counter. | | user_refresh_success_timestamp | Gauge | Timestamp of last successful user refresh. | -### Envoy Proxy Metrics +#### Envoy Proxy Metrics As of `v0.9`, Pomerium uses [Envoy](https://www.envoyproxy.io/) for the data plane. As such, proxy related metrics are sourced from Envoy, and use Envoy's internal [stats data model](https://www.envoyproxy.io/docs/envoy/latest/operations/stats_overview). Please see Envoy's documentation for information about specific metrics. @@ -130,6 +132,18 @@ To support this in Prometheus, consult the `basic_auth` option in the [`scrape_c | :-- | :-- | :-- | :-- | | `metrics_basic_authentication` | `METRICS_BASIC_AUTHENTICATION` | `string` ([base64 encoded](https://en.wikipedia.org/wiki/Base64)) | **optional** | +#### Examples {#examples-metrics-basic-authentication} + +```yaml +# for username: x and password: y +metrics_basic_authentication: eDp5 +``` + +```bash +# for username: x and password: y +METRICS_BASIC_AUTHENTICATION=eDp5 +``` + @@ -143,15 +157,6 @@ Kubernetes does not support `metrics_basic_authentication` -### Examples {#examples-metrics-basic-authentication} - -```yaml -# for username: x and password: y -metrics_basic_authentication: eDp5 - -METRICS_BASIC_AUTHENTICATION=eDp5 -``` - ## Metrics Certificate {#metrics-certificate} **Metrics Certificate** uses a certificate to secure the metrics endpoint. @@ -174,6 +179,18 @@ All certificates supplied to Pomerium must be in **PEM** format. | `metrics_certificate` and `metrics_certificate_key` | `METRICS_CERTIFICATE` and `METRICS_CERTIFICATE_KEY` | `string` | **optional** | | `metrics_certificate_file` and `metrics_certificate_key_file` | `METRICS_CERTIFICATE_FILE` and `METRICS_CERTIFICATE_KEY_FILE` | `string` | **optional** | +#### Examples {#examples-metrics-certificate} + +```yaml +metrics_certificate: base64-encoded-string +metrics_certificate_key: base64-encoded-string +``` + +```bash +METRICS_CERTIFICATE_FILE=/relative/file/location +METRICS_CERTIFICATE_FILE_KEY=/relative/file/location +``` + @@ -187,18 +204,6 @@ Kubernetes does not support **Metrics Certificate** -### Examples {#examples-metrics-certificate} - -```yaml -# config file key -metrics_certificate: base64-encoded-string -metrics_certificate_key: base64-encoded-string - -# environment variable -METRICS_CERTIFICATE_FILE=/relative/file/location -METRICS_CERTIFICATE_FILE_KEY=/relative/file/location -``` - ## Metrics Client Certificate Authority {#metrics-client-certificate-authority} **Metrics Client Certificate Authority** is the X.509 _public-key_ used to validate [mTLS](https://en.wikipedia.org/wiki/Mutual_authentication) client certificates for the metrics endpoint. If not set, no client certificate will be required. @@ -212,6 +217,16 @@ METRICS_CERTIFICATE_FILE_KEY=/relative/file/location | :-- | :-- | :-- | :-- | | `metrics_client_ca` and `metrics_client_ca_file` | `METRICS_CLIENT_CA` and `METRICS_CLIENT_CA_FILE` | `string` | **optional** | +#### Examples {#examples-metrics-client-certificate-authority} + +```yaml +metrics_client_ca: base64-encoded-string +``` + +```bash +METRICS_CLIENT_CA_FILE=/relative/file/location +``` + @@ -224,13 +239,3 @@ Kubernetes does not support **Metrics Client Certificate Authority** - -### Examples {#examples-metrics-client-certificate-authority} - -```yaml -# config file key -metrics_client_ca: base64-encoded-string - -# environment variable -METRICS_CLIENT_CA_FILE=/relative/file/location -``` diff --git a/content/docs/reference/override-certificate-name.mdx b/content/docs/reference/override-certificate-name.mdx index f1c008ac5..69578966a 100644 --- a/content/docs/reference/override-certificate-name.mdx +++ b/content/docs/reference/override-certificate-name.mdx @@ -8,6 +8,7 @@ keywords: - Override Certificate Name pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -30,6 +31,21 @@ Secure service communication can fail if the external certificate does not match | :-- | :-- | :-- | :-- | | `override_certificate_name` | `OVERRIDE_CERTIFICATE_NAME` | `string` | **optional** | +### Examples + +```yaml +override_certificate_name: authorize.corp.example.com +``` + +```bash +OVERRIDE_CERTIFICATE_NAME=authenticate.corp.example.com +``` + +```yaml +# wildcard support +override_certificate_name: *.corp.example.com +``` + @@ -42,16 +58,3 @@ Kubernetes does not support **Override Certificate Name** - -### Examples - -```yaml -# wildcard support -override_certificate_name: *.corp.example.com - -# domain -OVERRIDE_CERTIFICATE_NAME=authenticate.corp.example.com - -# or -override_certificate_name: authorize.corp.example.com -``` diff --git a/content/docs/reference/pass-identity-headers.mdx b/content/docs/reference/pass-identity-headers.mdx index ce4d36231..96a6bac8b 100644 --- a/content/docs/reference/pass-identity-headers.mdx +++ b/content/docs/reference/pass-identity-headers.mdx @@ -4,6 +4,9 @@ title: Pass Identity Headers description: The global Pass Identity Headers setting passes identity headers to all routes by default. keywords: [identity headers, reverse proxy] sidebar_label: Pass Identity Headers +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -31,6 +34,16 @@ Identity headers include: | :------------------------ | :-------- | :----------- | :---------- | | `pass_identity_headers` | `boolean` | **optional** | \*`false` | +### Examples + +```yaml +pass_identity_headers: true + +routes: + - from: https://service.corp.example.io + to: http://localhost:3000 +``` + @@ -51,21 +64,15 @@ The button has three states: | :-------------------- | :-------- | :----------- | :---------- | | `passIdentityHeaders` | `boolean` | **optional** | \*`false` | - - - -\* If neither the **global** _nor_ **route-level** `pass_identity_headers` settings are defined, both settings will default to `false`. - ### Examples ```yaml -pass_identity_headers: true - -routes: - - from: https://service.corp.example.io - to: http://localhost:3000 +passIdentityHeaders: true ``` -```yaml -passIdentityHeaders: 'true' -``` +See the [Kubernetes Reference](/docs/deploy/k8s/reference#spec) for more information. + + + + +\* If neither the **global** _nor_ **route-level** `pass_identity_headers` settings are defined, both settings will default to `false`. diff --git a/content/docs/reference/programmatic-redirect-domain-whitelist.mdx b/content/docs/reference/programmatic-redirect-domain-whitelist.mdx index ac1f76076..6f68512ef 100644 --- a/content/docs/reference/programmatic-redirect-domain-whitelist.mdx +++ b/content/docs/reference/programmatic-redirect-domain-whitelist.mdx @@ -6,6 +6,7 @@ keywords: - Programmatic Redirect Domain Whitelist pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -34,6 +35,18 @@ For example, whitelisting `example.com` will only accept a redirect URL that mat | :-- | :-- | :-- | :-- | :-- | | `programmatic_redirect_domain_whitelist` | `PROGRAMMATIC_REDIRECT_DOMAIN_WHITELIST` | `string` (array) | **optional** | `localhost` | +### Examples + +```yaml +programmatic_redirect_domain_whitelist: + - localhost + - redirect-uri.com +``` + +```bash +PROGRAMMATIC_REDIRECT_DOMAIN_WHITELIST=localhost,redirect-uri.com +``` + @@ -46,12 +59,3 @@ Kubernetes does not support **Programmatic Redirect Domain Whitelist** - -### Examples - -```yaml -# config file key -programmatic_redirect_domain_whitelist: - - localhost - - redirect-uri.com -``` diff --git a/content/docs/reference/proxy-log-level.mdx b/content/docs/reference/proxy-log-level.mdx index 19357f02d..e452d446d 100644 --- a/content/docs/reference/proxy-log-level.mdx +++ b/content/docs/reference/proxy-log-level.mdx @@ -8,6 +8,7 @@ keywords: - Proxy Log Level pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,12 +29,15 @@ import TabItem from '@theme/TabItem'; | :-- | :-- | :-- | :-- | | `proxy_log_level` | `PROXY_LOG_LEVEL` | `string` | `debug` or value of [`log_level`](/docs/reference/log-level) if set | -### Options +### Examples -- `debug` -- `info` -- `warn` -- `error` +```yaml +proxy_log_level: error +``` + +```bash +PROXY_LOG_LEVEL=debug +``` @@ -50,12 +54,9 @@ Kubernetes does not support **Proxy Log Level** -### Examples - -```yaml -# config file key -proxy_log_level: error +### Options -# environment variable -PROXY_LOG_LEVEL=debug -``` +- `debug` +- `info` +- `warn` +- `error` diff --git a/content/docs/reference/routes/allow-any-authenticated-user.mdx b/content/docs/reference/routes/allow-any-authenticated-user.mdx index a44fb6243..3d8017721 100644 --- a/content/docs/reference/routes/allow-any-authenticated-user.mdx +++ b/content/docs/reference/routes/allow-any-authenticated-user.mdx @@ -6,6 +6,7 @@ keywords: - Allow Any Authenticated User pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -30,6 +31,12 @@ Use of this setting means Pomerium **will not enforce your centralized authoriza | :----------------------------- | :-------- | :---------- | :----------- | | `allow_any_authenticated_user` | `boolean` | `false` | **optional** | +### Examples + +```yaml +allow_any_authenticated_user: 'true' +``` + @@ -44,16 +51,13 @@ Enable **Any Authenticated User** in the **Policy Builder** in the Console: | :----------------------------- | :-------- | :---------- | :----------- | | `allow_any_authenticated_user` | `boolean` | `false` | **optional** | -See Kubernetes [Ingress reference](/docs/deploy/k8s/ingress#annotations) for more information. - - - - ### Examples ```yaml -allow_any_authenticated_user: true - -# ingress ingress.pomerium.io/allow_any_authenticated_user: true ``` + +See Kubernetes [Ingress reference](/docs/deploy/k8s/ingress#annotations) for more information. + + + diff --git a/content/docs/reference/routes/cluster-name.mdx b/content/docs/reference/routes/cluster-name.mdx index 91fe5ecfc..7f75b50a6 100644 --- a/content/docs/reference/routes/cluster-name.mdx +++ b/content/docs/reference/routes/cluster-name.mdx @@ -6,6 +6,7 @@ keywords: - Cluster Name pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; diff --git a/content/docs/reference/routes/cors-preflight.mdx b/content/docs/reference/routes/cors-preflight.mdx index ee9806942..7d22f6993 100644 --- a/content/docs/reference/routes/cors-preflight.mdx +++ b/content/docs/reference/routes/cors-preflight.mdx @@ -6,6 +6,7 @@ keywords: - CORS Preflight pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -26,6 +27,12 @@ import TabItem from '@theme/TabItem'; | :------------------------ | :-------- | :---------- | :----------- | | `cors_preflight` | `boolean` | `false` | **optional** | +### Examples + +```yaml +cors_preflight: true +``` + @@ -40,9 +47,3 @@ Enable **CORS Preflight** in the **Policy Builder** in the Console: - -### Examples - -```yaml -cors_preflight: true -``` diff --git a/content/docs/reference/routes/enable-google-cloud-serverless-authentication.mdx b/content/docs/reference/routes/enable-google-cloud-serverless-authentication.mdx index 413469351..58206e135 100644 --- a/content/docs/reference/routes/enable-google-cloud-serverless-authentication.mdx +++ b/content/docs/reference/routes/enable-google-cloud-serverless-authentication.mdx @@ -6,6 +6,7 @@ keywords: - Enable Google Cloud Serverless Authentication pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ This setting requires you to set [Google Cloud Serverless Authentication Service | :-- | :-- | :-- | :-- | | `enable_google_cloud_serverless_authentication` | `ENABLE_GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION` | `boolean` | `false` | +### Examples + +```yaml +enable_google_cloud_serverless_authentication: true +``` + +```bash +ENABLE_GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION=true +``` + @@ -42,11 +53,3 @@ Kubernetes does not support **Enable Google Cloud Serverless Authentication** - -### Examples - -```yaml -enable_google_cloud_serverless_authentication: true - -ENABLE_GOOGLE_CLOUD_SERVERLESS_AUTHENTICATION=true -``` diff --git a/content/docs/reference/routes/from.mdx b/content/docs/reference/routes/from.mdx index 7e4cf8565..979290f25 100644 --- a/content/docs/reference/routes/from.mdx +++ b/content/docs/reference/routes/from.mdx @@ -6,6 +6,7 @@ keywords: - From pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -36,6 +37,21 @@ Only secure schemes (`https` and `tcp+https`) are supported. | :------------------------ | :------- | :------------------- | :----------- | | `from` | `URL` | `https`, `tcp+https` | **required** | +### Examples + +```yaml +routes: + - from: https://verify.corp.example.com + - to: https://example.com +``` + +```yaml +# TCP +routes: + - from: tcp+https://ssh.corp.example.com:22 + - to: tcp://example.com:22 +``` + @@ -51,19 +67,6 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress) for more information. -### Examples - -```yaml -routes: - - from: https://verify.corp.example.com - - to: https://example.com - -# TCP -routes: - - from: tcp+https://ssh.corp.example.com:22 - - to: tcp://example.com:22 -``` - :::note See [**Routing - Route matching order**](/docs/capabilities/routing#route-matching-order) for more information on how Pomerium processes and matches routes. diff --git a/content/docs/reference/routes/headers.mdx b/content/docs/reference/routes/headers.mdx index cb9a47abc..11a9e09c5 100644 --- a/content/docs/reference/routes/headers.mdx +++ b/content/docs/reference/routes/headers.mdx @@ -10,6 +10,9 @@ keywords: set response headers, rewrite response headers, ] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -46,6 +49,12 @@ The **Host Rewrite** setting preserves the **Host** header with the `preserve_ho | `host_path_regex_rewrite_pattern` | `string` | **optional** | | `host_path_regex_rewrite_substitution` | `string` | **optional** | +### Examples {#examples-host-rewrite} + +```yaml +host_rewrite: 'example.com' +``` + @@ -56,7 +65,17 @@ Configure **Host Rewrite** settings in the route **Headers** settings in the Con -**Host Rewrite** settings are not supported in Kubernetes +| **Name** | **Type** | **Usage** | +| :------------- | :------- | :----------- | +| `host_rewrite` | `string` | **optional** | + +### Examples + +```yaml +ingress.pomerium.io/host_rewrite: 'example.com' +``` + +See [Kubernetes Ingress](/docs/deploy/k8s/ingress) for more information. @@ -88,13 +107,7 @@ host_path_regex_rewrite_substitution: \1 This configuration would rewrite the Host header to `example.com` given the path `/example.com/some/path`. -The 2nd, 3rd and 4th options correspond to the Envoy [route action host](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-routeaction) related options. - -### Examples {#examples-host-rewrite} - -```yaml -host_rewrite: 'example.com' -``` +The 2nd, 3rd, and 4th options correspond to the Envoy [route action host](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-routeaction) related options. ## Set Request Headers {#set-request-headers} @@ -119,45 +132,6 @@ Neither HTTP/2 [pseudo-headers](https://www.rfc-editor.org/rfc/rfc9113.html#Pseu | :------------------------ | :--------------------- | :----------- | | `set_request_headers` | map of key-value pairs | **optional** | - - - -Configure **Set Request Headers** in the Console: - -![Set request headers in the console](../img/routes/headers/set-request-headers.png) - - - - -| **Name** | **Type** | **Usage** | -| :-- | :-- | :-- | -| `ingress.pomerium.io/set_request_headers` | map of key-value pairs | **optional** | - -See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information - - - - -### Pass dynamic tokens in headers {#pass-dynamic-tokens-in-headers} - -The following token substitutions are available: - -| **Token** | **Value** | -| :-- | :-- | -| `${pomerium.id_token}` | OIDC ID token from the identity provider\* | -| `${pomerium.access_token}` | OAuth access token from the identity provider\* | -| `${pomerium.client_cert_fingerprint}` | Short form SHA-256 fingerprint of the presented client certificate (if [downstream mTLS](/docs/capabilities/mtls-clients) is enabled) | - -\*The ID token and access token are not available when using the [Hosted Authenticate](/docs/capabilities/hosted-authenticate-service) service. - -**Note:** Token values must use the `${pomerium.}` syntax. To include a literal `$` character in a header value, use `$$`. - -:::warning - -Be very careful when passing access tokens to an upstream application. This may allow the application to make other authenticated requests on behalf of the user. - -::: - ### Examples {#examples-set-request-headers} Pass static header values in the request: @@ -195,38 +169,63 @@ Pass ID token, access token, and client certificate fingerprint (if present) as x-pomerium-client-cert-fingerprint: ${pomerium.client_cert_fingerprint} ``` -## Remove Request Headers {#remove-request-headers} - -**Remove Request Headers** allows you to remove given request headers. This can be useful if you want to prevent privacy information from being passed to downstream applications. - -### How to configure {#how-to-configure-remove-request-headers} - - - - -| **YAML**/**JSON** setting | **Type** | **Usage** | -| :------------------------ | :------- | :----------- | -| `remove_request_headers` | `string` | **optional** | - -Set **Remove Request Headers** in the Console: +Configure **Set Request Headers** in the Console: -![Set remove request headers in the console](../img/routes/headers/remove-request-headers.png) +![Set request headers in the console](../img/routes/headers/set-request-headers.png) -| **Name** | **Type** | **Usage** | -| :----------------------- | :------- | :----------- | -| `remove_request_headers` | `string` | **optional** | +| **Name** | **Type** | **Usage** | +| :-------------------- | :--------------------- | :----------- | +| `set_request_headers` | map of key-value pairs | **optional** | + +```yaml +ingress.pomerium.io/set_request_headers: | + X-Test: X-Value +``` See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information +### Pass dynamic tokens in headers {#pass-dynamic-tokens-in-headers} + +The following token substitutions are available: + +| **Token** | **Value** | +| :-- | :-- | +| `${pomerium.id_token}` | OIDC ID token from the identity provider\* | +| `${pomerium.access_token}` | OAuth access token from the identity provider\* | +| `${pomerium.client_cert_fingerprint}` | Short form SHA-256 fingerprint of the presented client certificate (if [downstream mTLS](/docs/capabilities/mtls-clients) is enabled) | + +\*The ID token and access token are not available when using the [Hosted Authenticate](/docs/capabilities/hosted-authenticate-service) service. + +**Note:** Token values must use the `${pomerium.}` syntax. To include a literal `$` character in a header value, use `$$`. + +:::warning + +Be very careful when passing access tokens to an upstream application. This may allow the application to make other authenticated requests on behalf of the user. + +::: + +## Remove Request Headers {#remove-request-headers} + +**Remove Request Headers** allows you to remove given request headers. This can be useful if you want to prevent privacy information from being passed to downstream applications. + +### How to configure {#how-to-configure-remove-request-headers} + + + + +| **YAML**/**JSON** setting | **Type** | **Usage** | +| :------------------------ | :------- | :----------- | +| `remove_request_headers` | `string` | **optional** | + ### Examples {#examples-remove-request-headers} ```yaml @@ -240,13 +239,33 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more informat remove_request_headers: - X-Email - X-Username +``` + + + + +Set **Remove Request Headers** in the Console: + +![Set remove request headers in the console](../img/routes/headers/remove-request-headers.png) -# ingress + + + +| **Name** | **Type** | **Usage** | +| :----------------------- | :------- | :----------- | +| `remove_request_headers` | `string` | **optional** | + +```yaml ingress.pomerium.io/remove_request_headers: | - X-Email - X-User ``` +See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information + + + + ## Set Response Headers {#set-response-headers} **Set Response Headers** allows you to set static values for the given response headers. These headers will take precedence over the global [`set_response_headers`](/docs/reference/set-response-headers). @@ -260,6 +279,13 @@ ingress.pomerium.io/remove_request_headers: | | :------------------------ | :------- | :----------- | | `set_response_headers` | `string` | **optional** | +### Examples + +```yaml +set_response_headers: + X-Test: X-Value +``` + @@ -274,6 +300,11 @@ Configure **Set Response Headers** in the Console: | :--------------------- | :------- | :----------- | | `set_response_headers` | `string` | **optional** | +```yaml +ingress.pomerium.io/set_response_headers: | + X-Test: X-Value +``` + See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information @@ -292,6 +323,25 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more informat | :------------------------- | :------- | :----------- | | `rewrite_response_headers` | `object` | **optional** | +### Examples {#examples-rewrite-response-headers} + +If the downstream server returns a header: + +```text +Location: http://localhost:8000/two/some/path/ +``` + +And the policy has this config: + +```yaml +rewrite_response_headers: + - header: Location + prefix: http://localhost:8000/two/ + value: http://frontend/one/ +``` + +The browser would be redirected to: `http://frontend/one/some/path/`. This is similar to nginx's [`proxy_redirect` option](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect), but can be used for any header. + @@ -306,12 +356,7 @@ Configure **Rewrite Response Headers** in the Console: | :------------------------- | :------- | :----------- | | `rewrite_response_headers` | `object` | **optional** | -See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information - - - - -### Examples {#examples-rewrite-response-headers} +### Examples If the downstream server returns a header: @@ -319,13 +364,18 @@ If the downstream server returns a header: Location: http://localhost:8000/two/some/path/ ``` -And the policy has this config: +And the Ingress object has this annotation: ```yaml -rewrite_response_headers: +ingress.pomerium.io/rewrite_response_headers: | - header: Location prefix: http://localhost:8000/two/ value: http://frontend/one/ ``` The browser would be redirected to: `http://frontend/one/some/path/`. This is similar to nginx's [`proxy_redirect` option](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_redirect), but can be used for any header. + +See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information + + + diff --git a/content/docs/reference/routes/identity-provider-client-id-per-route.mdx b/content/docs/reference/routes/identity-provider-client-id-per-route.mdx index 92ee8b758..2dd94966c 100644 --- a/content/docs/reference/routes/identity-provider-client-id-per-route.mdx +++ b/content/docs/reference/routes/identity-provider-client-id-per-route.mdx @@ -6,6 +6,7 @@ keywords: - Identity Provider Client ID (per route) pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -26,6 +27,15 @@ When set, **Identity Provider Client ID (per route)** overrides the value of [id | :------------------------ | :------- | :----------- | | `idp_client_id` | `string` | **optional** | +### Examples + +```yaml +routes: + - from: https://verify.localhost.pomerium.io + to: http://verify:8000 + idp_client_id: idp_client_id +``` + @@ -40,12 +50,3 @@ Kubernetes does not support `idp_client_id` (per route) - -### Examples - -```yaml -routes: - - from: https://verify.localhost.pomerium.io - to: http://verify:8000 - idp_client_id: idp_client_id -``` diff --git a/content/docs/reference/routes/identity-provider-client-secret-per-route.mdx b/content/docs/reference/routes/identity-provider-client-secret-per-route.mdx index 89f941c53..9864904ee 100644 --- a/content/docs/reference/routes/identity-provider-client-secret-per-route.mdx +++ b/content/docs/reference/routes/identity-provider-client-secret-per-route.mdx @@ -6,6 +6,7 @@ keywords: - Identity Provider Client Secret (per route) pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -26,6 +27,15 @@ When set, **Identity Provider Client Secret (per route)** overrides the value of | :------------------------ | :------- | :----------- | | `idp_client_secret` | `string` | **optional** | +### Examples + +```yaml +routes: + - from: https://verify.localhost.pomerium.io + to: http://verify:8000 + idp_client_secret: idp_client_secret +``` + @@ -40,12 +50,3 @@ Kubernetes does not support `idp_client_secret` (per route) - -### Examples - -```yaml -routes: - - from: https://verify.localhost.pomerium.io - to: http://verify:8000 - idp_client_secret: idp_client_secret -``` diff --git a/content/docs/reference/routes/kubernetes-service-account-token.mdx b/content/docs/reference/routes/kubernetes-service-account-token.mdx index 1539db864..4fe015d30 100644 --- a/content/docs/reference/routes/kubernetes-service-account-token.mdx +++ b/content/docs/reference/routes/kubernetes-service-account-token.mdx @@ -8,6 +8,7 @@ keywords: - Kubernetes Service Account Token pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -24,23 +25,13 @@ Pomerium will [impersonate](https://kubernetes.io/docs/reference/access-authn-au ## How to configure - - -Set the **Kubernetes Service Account Token** under **General** route settings in the Console: + -![Set k8s service account token in the Console](../img/routes/k8s/kubernetes-bearer-token.png) - - - - -| **YAML**/**JSON** settings | **Type** | **Usage** | +| **Config file key** | **Type** | **Usage** | | :-- | :-- | :-- | | `kubernetes_service_account_token` | `string` | **optional** | | `kubernetes_service_account_token_file` | `bearer token` file path | **optional** | - - - ### Examples ```yaml @@ -48,3 +39,18 @@ kubernetes_service_account_token: eyJ0eXAiOiJKV1QiLCJhbGciOiJ... kubernetes_service_account_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token ``` + + + + +Set the **Kubernetes Service Account Token** under **General** route settings in the Console: + +![Set k8s service account token in the Console](../img/routes/k8s/kubernetes-bearer-token.png) + + + + +This option is not supported in Kubernetes. + + + diff --git a/content/docs/reference/routes/load-balancing.mdx b/content/docs/reference/routes/load-balancing.mdx index 88318f35a..80012a98e 100644 --- a/content/docs/reference/routes/load-balancing.mdx +++ b/content/docs/reference/routes/load-balancing.mdx @@ -3,6 +3,9 @@ title: Load Balancing Settings sidebar_label: Load Balancing Settings description: Configure Load Balancer settings in Pomerium. keywords: [load balancing policy, health checks] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -10,7 +13,7 @@ import TabItem from '@theme/TabItem'; # Load Balancing Settings -This reference covers all of Pomerium's **Load Balancer Settings**: +This reference covers all of Pomerium's **Load Balancing Settings**: - [Load Balancing Policy](#load-balancing-policy) - [Health Checks](#health-checks) @@ -32,6 +35,22 @@ Some policy types support additional [configuration](/docs/reference/routes/load | :------------------- | :------- | :----------- | :------------ | | `lb_policy` | `enum` | **optional** | `ROUND_ROBIN` | +### Examples {#examples-load-balancing-policy} + +```yaml +routes: + - from: https://myapp.localhost.pomerium.io + to: + - http://myapp-srv-1:8080 + - http://myapp-srv-2:8080 + - http://myapp-srv-3:8080 + - http://myapp-srv-4:8080 + - http://myapp-srv-5:8080 + lb_policy: LEAST_REQUEST + least_request_lb_config: + choice_count: 2 # current envoy default +``` + @@ -46,6 +65,13 @@ Set the **Load Balancing Policy** in the Console: | :------------------------------ | :------- | :----------- | :------------ | | `ingress.pomerium.io/lb_policy` | `enum` | **optional** | `ROUND_ROBIN` | +### Examples + +```yaml +ingress.pomerium.io/lb_policy: LEAST_REQUEST +ingress.pomerium.io/least_request_lb_config: '{"choice_count": 2}' +``` + See Kubernetes [Ingress](/docs/deploy/k8s/ingress#load-balancing) for more information @@ -61,22 +87,6 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress#load-balancing) for more infor | [`RANDOM`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#random) | | [`MAGLEV`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/load_balancers#maglev) (may be further configured using [`maglev_lb_config`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/cluster/v3/cluster.proto#envoy-v3-api-msg-config-cluster-v3-cluster-maglevlbconfig) option) | -### Examples {#examples-load-balancing-policy} - -```yaml -routes: - - from: https://myapp.localhost.pomerium.io - to: - - http://myapp-srv-1:8080 - - http://myapp-srv-2:8080 - - http://myapp-srv-3:8080 - - http://myapp-srv-4:8080 - - http://myapp-srv-5:8080 - lb_policy: LEAST_REQUEST - least_request_lb_config: - choice_count: 2 # current envoy default -``` - ## Health Checks {#health-checks} When defined, **Health Checks** will issue periodic health check requests to upstream servers and unhealthy upstream servers won't serve traffic. diff --git a/content/docs/reference/routes/outlier-detection.mdx b/content/docs/reference/routes/outlier-detection.mdx index 72a7c974b..da7639959 100644 --- a/content/docs/reference/routes/outlier-detection.mdx +++ b/content/docs/reference/routes/outlier-detection.mdx @@ -6,6 +6,7 @@ keywords: - Outlier Detection pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,12 @@ See Envoy [documentation](https://www.envoyproxy.io/docs/envoy/latest/intro/arch | :------------------ | :------- | :----------- | | `outlier_detection` | `object` | **optional** | +### Examples + +```yaml +outlier_detection: {'consecutive_5xx': 12} +``` + @@ -40,9 +47,3 @@ See the [Load Balancing](/docs/capabilities/load-balancing#passive-health-checks - -### Examples - -```yaml -outlier_detection: {'consecutive_5xx': 12} -``` diff --git a/content/docs/reference/routes/pass-identity-headers.mdx b/content/docs/reference/routes/pass-identity-headers.mdx index bac9ddca3..e8279bf45 100644 --- a/content/docs/reference/routes/pass-identity-headers.mdx +++ b/content/docs/reference/routes/pass-identity-headers.mdx @@ -6,6 +6,7 @@ keywords: - Pass Identity Headers pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -31,6 +32,15 @@ These headers include: | :------------------------ | :-------- | :----------- | :---------- | | `pass_identity_headers` | `boolean` | **optional** | `false` | +### Examples + +```yaml +routes: + - from: https://verify.localhost.pomerium.io + to: http://verify:8000 + pass_identity_headers: true +``` + @@ -41,16 +51,15 @@ Set **Pass Identity Headers** under **General** route settings in the Console: +| **Annotation name** | **Type** | **Usage** | **Default** | +| :---------------------- | :-------- | :----------- | :---------- | +| `pass_identity_headers` | `boolean` | **optional** | `false` | + +```yaml +ingress.pomerium.io/pass_identity_headers: 'true' +``` + See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information - -### Examples - -```yaml -routes: - - from: https://verify.localhost.pomerium.io - to: http://verify:8000 - pass_identity_headers: true -``` diff --git a/content/docs/reference/routes/path-matching.mdx b/content/docs/reference/routes/path-matching.mdx index fa118b3e0..fcf3f3ae4 100644 --- a/content/docs/reference/routes/path-matching.mdx +++ b/content/docs/reference/routes/path-matching.mdx @@ -3,6 +3,9 @@ title: Path Matching Settings sidebar_label: Path Matching Settings description: Configure Path Matching settings in Pomerium. keywords: [path, prefix, regex] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -29,6 +32,15 @@ If **Path** is set, the route will only match incoming requests with a path that | :------------------------ | :------- | :----------- | | `path` | `string` | **optional** | +### Examples {#examples-path} + +```yaml +routes: + - from: https://verify.localhost.pomerium.io + to: http://verify:8000 + path: /admin/some/exact/path +``` + @@ -44,15 +56,6 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress#regular-expressions-path-match -### Examples {#examples-path} - -```yaml -routes: - - from: https://verify.localhost.pomerium.io - to: http://verify:8000 - path: /admin/some/exact/path -``` - ## Prefix {#prefix} If **Prefix** is set, the route will only match incoming requests with a path that begins with the specified prefix. @@ -66,6 +69,14 @@ If **Prefix** is set, the route will only match incoming requests with a path th | :------------------------ | :------- | :----------- | | `prefix` | `string` | **optional** | +### Examples {#examples-prefix} + +```yaml +from: https://from.example.com +to: https://to.example.com +prefix: /admin +``` + @@ -80,19 +91,7 @@ Set the **Prefix** in **Path Matching** settings: | :------- | :------- | :----------- | | `Prefix` | `string` | **optional** | -See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information - - - - -### Examples {#examples-prefix} - ```yaml -from: https://from.example.com -to: https://to.example.com -prefix: /admin - -# ingress spec: ingressClassName: pomerium rules: @@ -108,6 +107,11 @@ spec: pathType: Prefix ``` +See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information + + + + ## Regex {#regex} If **Regex** is set, the route will only match incoming requests with a path that matches the specified regular expression. The supported syntax is the same as the Go [regexp package](https://golang.org/pkg/regexp/) which is based on [re2](https://github.com/google/re2/wiki/Syntax). @@ -121,6 +125,12 @@ If **Regex** is set, the route will only match incoming requests with a path tha | :------------------------ | :------- | :----------- | | `regex` | `string` | **optional** | +### Examples {#examples-regex} + +```yaml +regex: '^/(admin|superuser)/.*$' +``` + @@ -135,15 +145,9 @@ Set **Regex** in the Console: | :----------- | :------- | :----------- | | `path_regex` | `string` | **optional** | - - - ### Examples {#examples-regex} ```yaml -regex: "^/(admin|superuser)/.*$" - -# ingress ingress.pomerium.io/path_regex: 'true' name: example spec: @@ -160,3 +164,6 @@ spec: path: ^/(admin|superuser)/.*$ pathType: ImplementationSpecific ``` + + + diff --git a/content/docs/reference/routes/path-rewriting.mdx b/content/docs/reference/routes/path-rewriting.mdx index abfaef2d1..4a110605b 100644 --- a/content/docs/reference/routes/path-rewriting.mdx +++ b/content/docs/reference/routes/path-rewriting.mdx @@ -3,6 +3,9 @@ title: Path Rewriting Settings sidebar_label: Path Rewriting Settings description: Configure Path Rewriting settings in Pomerium. keywords: [prefix rewrite, regex rewrite pattern, regex rewrite substitution] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -29,6 +32,15 @@ If set, **Prefix Rewrite** indicates that during forwarding, the matched prefix | :------------------------ | :------- | :----------- | | `prefix_rewrite` | `string` | **optional** | +### Examples {#examples-prefix-rewrite} + +```yaml +from: https://from.example.com +to: https://to.example.com +prefix: /admin +prefix_rewrite: / +``` + @@ -54,15 +66,6 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more informat -### Examples {#examples-prefix-rewrite} - -```yaml -from: https://from.example.com -to: https://to.example.com -prefix: /admin -prefix_rewrite: / -``` - A request to `https://from.example.com/admin` would be forwarded to `https://to.example.com/`. ## Regex Rewrite {#regex-rewrite} @@ -79,6 +82,13 @@ If **Regex Rewrite** or **Regex Rewrite Substitution** are set, the URL path wil | `regex_rewrite_pattern` | `string` | **optional** | | `regex_rewrite_substitution` | `string` | **optional** | +### Examples {#examples-regex-rewrite} + +```yaml +regex_rewrite_pattern: '^/service/([^/]+)(/.*)$' +regex_rewrite_substitution: "\\2/instance/\\1" +``` + @@ -93,10 +103,3 @@ Kubernetes does not support **Regex Rewrite** - -### Examples {#examples-regex-rewrite} - -```yaml -regex_rewrite_pattern: '^/service/([^/]+)(/.*)$' -regex_rewrite_substitution: "\\2/instance/\\1" -``` diff --git a/content/docs/reference/routes/policy.mdx b/content/docs/reference/routes/policy.mdx index 77ccb1a4c..9b4ac4380 100644 --- a/content/docs/reference/routes/policy.mdx +++ b/content/docs/reference/routes/policy.mdx @@ -5,6 +5,7 @@ keywords: - policy pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -27,6 +28,21 @@ See [Pomerium Policy Language](/docs/capabilities/ppl) for a full explanation of | :------------------------ | :------- | :----------- | | `policy` | `string` | **optional** | +### Examples + +```yaml +routes: + - from: https://verify.localhost.pomerium.io + to: http://verify:8000 + policy: + - allow: + and: + - domain: + is: pomerium.com + - user: + is: user +``` + @@ -51,26 +67,9 @@ Edit your policy: | :------- | :------- | :----------- | | `policy` | `string` | **optional** | -See Kubernetes [Ingress](/docs/deploy/k8s/ingress#access-policy-examples) for more information - - - - ### Examples ```yaml -routes: - - from: https://verify.localhost.pomerium.io - to: http://verify:8000 - policy: - - allow: - and: - - domain: - is: pomerium.com - - user: - is: user - -# ingress ingress.pomerium.io/policy: | allow: and: @@ -79,3 +78,8 @@ ingress.pomerium.io/policy: | - user: is: user ``` + +See Kubernetes [Ingress](/docs/deploy/k8s/ingress#access-policy-examples) for more information + + + diff --git a/content/docs/reference/routes/public-access.mdx b/content/docs/reference/routes/public-access.mdx index fee9171a3..d35b8c173 100644 --- a/content/docs/reference/routes/public-access.mdx +++ b/content/docs/reference/routes/public-access.mdx @@ -6,6 +6,7 @@ keywords: - Public Access pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,12 @@ If this setting is enabled, no whitelists (for example, Allowed Users) should be | :-- | :-- | :-- | :-- | | `allow_public_unauthenticated_access` | `boolean` | `false` | **optional** | +### Examples + +```yaml +allow_public_unauthenticated_access: true +``` + @@ -40,15 +47,15 @@ Enable **Public Access** in the **Policy Builder** in the Console: | **Name** | **Type** | **Default** | **Usage** | | :-- | :-- | :-- | :-- | -| `allow_public_unauthenticated_access` | `boolean` | `false` | **optional** | - -See Kubernetes [Ingress](/docs/deploy/k8s/ingress) for more information - - - +| `allow_public_unauthenticated_access` | `boolean`, `string` | `false` | **optional** | ### Examples ```yaml -allow_public_unauthenticated_access: true +ingress.pomerium.io/allow_public_unauthenticated_access: 'true' ``` + +See Kubernetes [Ingress](/docs/deploy/k8s/ingress) for more information + + + diff --git a/content/docs/reference/routes/redirect.mdx b/content/docs/reference/routes/redirect.mdx index 4d3a568e6..a2b60795d 100644 --- a/content/docs/reference/routes/redirect.mdx +++ b/content/docs/reference/routes/redirect.mdx @@ -6,6 +6,7 @@ keywords: - Redirect pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,12 @@ Either `redirect` or [`to`](/docs/reference/routes/to) must be set. | :------------------------ | :------- | :----------- | | `redirect` | `object` | **optional** | +### Examples + +```yaml +redirect: {'host_redirect': 'example.com'} +``` + @@ -57,9 +64,3 @@ The `redirect` field is an object with the following options: | `prefix_rewrite` | `string` | The incoming matched prefix will be swapped with the given value. | | `response_code` | `integer` | The response code to use for the redirect. Defaults to 301. | | `strip_query` | `boolean` | Indicates that during redirection, the query portion of the URL will be removed. Defaults to `false`. | - -### Examples - -```yaml -redirect: {'host_redirect': 'example.com'} -``` diff --git a/content/docs/reference/routes/regex-priority-order.mdx b/content/docs/reference/routes/regex-priority-order.mdx index 842603cf4..774aa06f2 100644 --- a/content/docs/reference/routes/regex-priority-order.mdx +++ b/content/docs/reference/routes/regex-priority-order.mdx @@ -5,6 +5,7 @@ description: If set, the route will only match incoming requests with a path tha keywords: [reference, regex priority order] pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -25,6 +26,13 @@ If **Regex Priority Order** is set, the route will only match incoming requests | :------------------------ | :------- | :----------- | | `regex_priority_order` | `uint32` | **optional** | +### Examples + +```yaml +regex: '^/(admin|superuser)/.*$' +regex_priority_order: 1 +``` + @@ -42,10 +50,3 @@ Kubernetes does not support **Regex Priority Order** - -### Examples - -```yaml -regex: '^/(admin|superuser)/.*$' -regex_priority_order: 1 -``` diff --git a/content/docs/reference/routes/show-error-details.mdx b/content/docs/reference/routes/show-error-details.mdx index 0d93ea68a..7effdfeee 100644 --- a/content/docs/reference/routes/show-error-details.mdx +++ b/content/docs/reference/routes/show-error-details.mdx @@ -4,6 +4,7 @@ title: Show Error Details keywords: [reference, show error details] pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; diff --git a/content/docs/reference/routes/timeouts.mdx b/content/docs/reference/routes/timeouts.mdx index 20553f514..541af72a5 100644 --- a/content/docs/reference/routes/timeouts.mdx +++ b/content/docs/reference/routes/timeouts.mdx @@ -3,8 +3,14 @@ title: Timeouts Settings sidebar_label: Timeouts Settings description: Configure Timeouts settings in Pomerium. keywords: [websocket connections, spdy, route timeout, route idle timeout] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Timeouts Settings This reference covers all of Pomerium's **Timeouts Settings**: @@ -33,6 +39,12 @@ If set, enables proxying of websocket connections. | :------------------------ | :-------- | :---------- | | `allow_websockets` | `boolean` | `false` | +### Examples {#examples-websocket-connections} + +```yaml +allow_websockets: true +``` + @@ -43,21 +55,21 @@ Enable **Allow Websockets** in the Console: -| **Name** | **Type** | **Default** | -| :----------------- | :-------- | :---------- | -| `allow_websockets` | `boolean` | `false` | +| **annotation** | **Type** | **Default** | +| :----------------- | :------------------ | :---------- | +| `allow_websockets` | `boolean`, `string` | `false` | + +### Examples + +```yaml +ingress.pomerium.io/allow_websockets: 'true' +``` See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information -### Examples {#examples-websocket-connections} - -```yaml -allow_websockets: true -``` - ## SPDY {#spdy} If set, **SPDY** enables proxying of SPDY protocol upgrades. @@ -71,6 +83,12 @@ If set, **SPDY** enables proxying of SPDY protocol upgrades. | :------------------------ | :-------- | :---------- | | `allow_spdy` | `boolean` | `false` | +### Examples {#examples-spdy} + +```YAML +allow_spdy: true +``` + @@ -85,17 +103,17 @@ Enable **SPDY** in the Console: | :----------- | :-------- | :---------- | | `allow_spdy` | `boolean` | `false` | +### Examples + +```yaml +ingress.pomerium.io/allow_spdy: 'true' +``` + See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for information -### Examples {#examples-spdy} - -```YAML -allow_spdy: true -``` - ## Route Timeout {#route-timeout} **Route Timeout** establishes the per-route timeout value. Cannot exceed [global timeout](/docs/reference/global-timeouts) values. @@ -109,6 +127,12 @@ allow_spdy: true | :-- | :-- | :-- | :-- | | `timeout` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | **optional** | `30s` | +### Examples {#examples-route-timeout} + +```yaml +timeout: 30s +``` + @@ -123,17 +147,17 @@ Set the **Route Timeout** in the Console: | :-- | :-- | :-- | :-- | | `timeout` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | **optional** | `30s` | +### Examples + +```yaml +ingress.pomerium.io/timeout: '30s' +``` + See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more information -### Examples {#examples-route-timeout} - -```yaml -timeout: 30s -``` - ## Idle Timeout {#idle-timeout} If you are proxying long-lived requests that employ streaming calls such as websockets or gRPC, set **Idle Timeout** to either a maximum value there may be no data exchange over a connection (recommended), or set it to unlimited (`0s`). @@ -149,6 +173,16 @@ If `idle_timeout` is specified, and [route timeout](/docs/reference/routes/timeo | :-- | :-- | :-- | :-- | | `idle_timeout` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | **optional** | `5m` | +### Examples + +```yaml +routes: + - from: https://verify.localhost.pomerium.io + to: http://verify:8000 + timeout: 1m + idle_timeout: 5m +``` + @@ -159,15 +193,18 @@ Set **Idle Timeout** under route **Timeouts** settings in the Console: -See the Kubernetes [Ingress - Pomerium Standard Annotations](/docs/deploy/k8s/ingress) section for more information. +| **Annotation name** | **Type** | **Usage** | **Default** | +| :-- | :-- | :-- | :-- | +| `idle_timeout` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | **optional** | `5m` | - - +### Examples ```yaml -routes: - - from: https://verify.localhost.pomerium.io - to: http://verify:8000 - timeout: 1m - idle_timeout: 5m +ingress.pomerium.io/timeout: '1m' +ingress.pomerium.io/idle_timeout: '5m' ``` + +See the Kubernetes [Ingress - Pomerium Standard Annotations](/docs/deploy/k8s/ingress) section for more information. + + + diff --git a/content/docs/reference/routes/tls.mdx b/content/docs/reference/routes/tls.mdx index 28763be4c..f6bcf3aff 100644 --- a/content/docs/reference/routes/tls.mdx +++ b/content/docs/reference/routes/tls.mdx @@ -3,6 +3,9 @@ title: TLS Settings sidebar_label: TLS Settings description: Configure TLS route settings in Pomerium. keywords: [tls] +pagination_prev: null +pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -36,6 +39,17 @@ For more details, see our [mTLS example repository](https://github.com/pomerium/ | `tls_client_cert` and `tls_client_key` | `string` (base64-encoded) | **optional** | | `tls_client_cert_file` and `tls_client_key_file` | `string` (base64-encoded) | **optional** | +### Examples {#examples-tls-client-certificate} + +```yaml +tls_client_cert: base64-encoded-certificate +tls_client_key: base64-encoded-keywords + +# or +tls_client_cert_file: /relative/file/location +tls_client_key_file: /relative/file/location +``` + @@ -51,17 +65,6 @@ See Kubernetes [TLS Certificates](/docs/deploy/k8s/ingress#tls-certificates) for -### Examples {#examples-tls-client-certificate} - -```yaml -tls_client_cert: base64-encoded-certificate -tls_client_key: base64-encoded-keywords - -# or -tls_client_cert_file: /relative/file/location -tls_client_key_file: /relative/file/location -``` - ## TLS Custom Certificate Authority {#tls-custom-certificate-authority} **TLS Custom Certificate Authority** defines a set of root certificate authorities that the Pomerium Proxy Service uses when verifying upstream server certificates. @@ -77,6 +80,13 @@ tls_client_key_file: /relative/file/location | :-------------------------------------- | :------- | :----------- | | `tls_custom_ca` or `tls_custom_ca_file` | `string` | **optional** | +### Examples {#examples-tls-custom-certificate-authority} + +```yaml +tls_custom_ca: base64-encoded-custom-ca +tls_custom_ca_file: /relative/file/location +``` + @@ -92,13 +102,6 @@ See Kubernetes [TLS Certificates](/docs/deploy/k8s/ingress#tls-certificates) for -### Examples {#examples-tls-custom-certificate-authority} - -```yaml -tls_custom_ca: base64-encoded-custom-ca -tls_custom_ca_file: /relative/file/location -``` - ## TLS Downstream Client Certificate Authority {#tls-downstream-client-certificate-authority} :::caution @@ -126,6 +129,13 @@ See [Client-Side mTLS With Pomerium](/docs/concepts/mutual-auth.md) for more inf | :-- | :-- | :-- | | `tls_downstream_client_ca` or `tls_downstream_client_ca_file` | `string` | **optional** | +### Examples {#examples-tls-downstream-client-certificate-authority} + +```yaml +tls_downstream_client_ca: base64-encoded-client-ca +tls_downstream_client_ca_file: /relative/file/location +``` + @@ -141,13 +151,6 @@ See Kubernetes [TLS Certificates](/docs/deploy/k8s/ingress#tls-certificates) for -### Examples {#examples-tls-downstream-client-certificate-authority} - -```yaml -tls_downstream_client_ca: base64-encoded-client-ca -tls_downstream_client_ca_file: /relative/file/location -``` - ## TLS Downstream Server Name {#tls-downstream-server-name} **TLS Downstream Server Name** overrides the hostname specified in the `from` field. When a connection to Pomerium is made via TLS the `tls_downstream_server_name` will be used as the expected Server Name Indication, whereas the host part of the `from` field, will be expected to match the `Host` or `:authority` headers of the HTTP request. @@ -193,6 +196,12 @@ In this mode, TLS is susceptible to man-in-the-middle attacks. This should be us | :------------------------ | :-------- | :---------- | | `tls_skip_verify` | `boolean` | `false` | +### Examples {#examples-tls-skip-verification} + +```yaml +tls_skip_verify: true +``` + @@ -212,12 +221,6 @@ See Kubernetes [Ingress](/docs/deploy/k8s/ingress#annotations) for more informat -### Examples {#examples-tls-skip-verification} - -```yaml -tls_skip_verify: true -``` - ## TLS Upstream Allow Renegotiation {#tls-upstream-allow-renegotiation} **TLS Upstream Allow Renegotiation** controls whether server-initiated TLS renegotiation is allowed for upstream servers. For more details, see Envoy's documentation on [`allow_renegotiation`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/tls.proto). @@ -237,6 +240,12 @@ TLS renegotiation is considered insecure and shouldn’t be used unless absolute | :--------------------------------- | :-------- | :---------- | | `tls_upstream_allow_renegotiation` | `boolean` | `false` | +### Examples {#examples-tls-upstream-allow-renegotiation} + +```yaml +tls_upstream_allow_renegotiation: true +``` + @@ -252,12 +261,6 @@ Kubernetes does not support **TLS Upstream Allow Renegotiation** -### Examples {#examples-tls-upstream-allow-renegotiation} - -```yaml -tls_upstream_allow_renegotiation: true -``` - ## TLS Upstream Server Name {#tls-upstream-server-name} **TLS Upstream Server Name** overrides the hostname specified in the `to` field. If set, this server name will be used to verify the certificate name. This is useful when the backend of your service is a TLS server with a valid certificate, but mismatched name. diff --git a/content/docs/reference/routes/to.mdx b/content/docs/reference/routes/to.mdx index 289aa16ff..fcbb31041 100644 --- a/content/docs/reference/routes/to.mdx +++ b/content/docs/reference/routes/to.mdx @@ -6,6 +6,7 @@ keywords: - To pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -26,6 +27,22 @@ import TabItem from '@theme/TabItem'; | :------------------------ | :------- | :----------- | :--------------------- | | `to` | `URL` | **optional** | `http`, `https`, `tcp` | +### Examples + +```yaml +- from: https://example.com + to: http://verify + +- from: https://example.com + to: https://192.1.20.12:8080 + +- from: https://example.com + to: http://neverssl.com + +- from: https://example.com + to: https://verify.pomerium.com/anything/ +``` + @@ -66,22 +83,6 @@ A load balancing weight may be associated with a particular upstream by appendin Must be `tcp` if `from` is `tcp+https`. -### Examples - -```yaml -- from: https://example.com - to: http://verify - -- from: https://example.com - to: https://192.1.20.12:8080 - -- from: https://example.com - to: http://neverssl.com - -- from: https://example.com - to: https://verify.pomerium.com/anything/ -``` - :::note See [**Routing - Route matching order**](/docs/capabilities/routing#route-matching-order) for more information on how Pomerium processes and matches routes. diff --git a/content/docs/reference/service-mode.mdx b/content/docs/reference/service-mode.mdx index f13af7bad..be2de6325 100644 --- a/content/docs/reference/service-mode.mdx +++ b/content/docs/reference/service-mode.mdx @@ -8,6 +8,7 @@ keywords: - Service Mode pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -36,6 +37,16 @@ import TabItem from '@theme/TabItem'; - `proxy` - `databroker` +### Examples + +```yaml +service: authorize +``` + +```bash +SERVICE=databroker +``` + @@ -48,12 +59,3 @@ import TabItem from '@theme/TabItem'; - -### Examples - -```yaml -# config file key -service: authorize - -SERVICE=databroker -``` diff --git a/content/docs/reference/set-response-headers.mdx b/content/docs/reference/set-response-headers.mdx index 839b5f227..803fa03b4 100644 --- a/content/docs/reference/set-response-headers.mdx +++ b/content/docs/reference/set-response-headers.mdx @@ -6,6 +6,7 @@ keywords: - Set Response Headers pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -26,6 +27,25 @@ import TabItem from '@theme/TabItem'; | :-- | :-- | :-- | :-- | | `set_response_headers` | `SET_RESPONSE_HEADERS` | `string` | see [Default headers](#default) | +### Examples + +#### JSON + +```json +{ + "set_response_headers": { + "X-Test": "X-Value" + } +} +``` + +#### YAML + +```yaml +set_response_headers: + X-Test: X-Value +``` + @@ -40,6 +60,13 @@ Configure **Response Headers** under **Proxy** settings in the Console: | :--------------------- | :------- | :------------------------------ | | `set_response_headers` | `string` | see [Default headers](#default) | +### Examples + +```yaml +ingress.pomerium.io/set_response_headers: | + X-Test: X-Value +``` + Set per [Ingress](/docs/deploy/k8s/ingress). @@ -78,24 +105,3 @@ To disable `set_response_headers`: set_response_headers: disable: true ``` - -### Examples - -#### Comma separated values (CSV): - -```csv -X-Content-Type-Options:nosniff,X-Frame-Options:SAMEORIGIN -``` - -#### JSON - -```JSON - '{"X-Test": "X-Value"}' -``` - -#### YAML - -```yaml -set_response_headers: - X-Test: X-Value -``` diff --git a/content/docs/reference/shared-secret-file.mdx b/content/docs/reference/shared-secret-file.mdx index e07cdd2e3..e3008e8b5 100644 --- a/content/docs/reference/shared-secret-file.mdx +++ b/content/docs/reference/shared-secret-file.mdx @@ -8,6 +8,7 @@ keywords: - Shared Secret File pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,40 +29,23 @@ import TabItem from '@theme/TabItem'; | :-- | :-- | :-- | :-- | | `shared_secret_file` | `SHARED_SECRET_FILE` | `string` | **required** (unless using [shared_secret]) | -:::tip **Note** +:::tip Pomerium Core configurations do not require a `shared_secret` or `shared_secret_file`. You only need to include a shared secret if you are running the Console. If you are connecting to the Console, your Pomerium Core and Console configurations require the same shared secret. -See the [Enterprise Quickstart](/docs/deploy/enterprise/quickstart) for an example implementation. +See the [**Enterprise Quickstart**](/docs/deploy/enterprise/quickstart) for an example implementation. ::: - - - -`shared_secret_file` is a bootstrap configuration setting and is not configurable in the Console. - - - - -| **Name** | -| :---------------------- | -| `secrets.shared_secret` | - -See Kubernetes [bootstrap secrets](/docs/deploy/k8s/reference#spec) for more information. - - - - ### Examples `shared_secret_file` points to a file containing the secret. This is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/). To generate a key, run the following command: -```sh +```shell head -c32 /dev/urandom | base64 ``` @@ -71,8 +55,25 @@ Place the value in your `shared_secret_file`: shared_secret_file: '/run/secrets/POMERIUM_SHARED_SECRET' ``` -:::tip +:::note -If you adjust your shared secret and/or how it's accessed by Pomerium, you may create a [secret mismatch](/docs/internals/troubleshooting#shared-secret-mismatch). +If you adjust your shared secret and/or how it's accessed by Pomerium, you may create a [**secret mismatch**](/docs/internals/troubleshooting#shared-secret-mismatch). ::: + + + + +`shared_secret_file` is a bootstrap configuration setting and is not configurable in the Console. + + + + +| **Name** | +| :---------------------- | +| `secrets.shared_secret` | + +See Kubernetes [bootstrap secrets](/docs/deploy/k8s/reference#spec) for more information. + + + diff --git a/content/docs/reference/shared-secret.mdx b/content/docs/reference/shared-secret.mdx index 32b7958d6..0781e4c7f 100644 --- a/content/docs/reference/shared-secret.mdx +++ b/content/docs/reference/shared-secret.mdx @@ -8,6 +8,7 @@ keywords: - Shared Secret pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,30 +29,13 @@ import TabItem from '@theme/TabItem'; | :-- | :-- | :-- | :-- | | `shared_secret` | `SHARED_SECRET` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) | - - - -`shared_secret` is a bootstrap configuration setting and is not configurable in the Console. - - - - -| **Name** | **Type** | **Usage** | -| :-- | :-- | :-- | -| `secrets.shared_secret` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) | - -See Kubernetes [bootstrap secrets](/docs/deploy/k8s/reference#spec) for more information. - - - - :::tip **Note** Pomerium Core configurations do not require a `shared_secret` or `shared_secret_file`. You only need to include a shared secret if you are running the Console. If you are connecting to the Console, your Pomerium Core and Console configurations require the same shared secret. -See the [Enterprise Quickstart](/docs/deploy/enterprise/quickstart) for an example implementation. +See the [**Enterprise Quickstart**](/docs/deploy/enterprise/quickstart) for an example implementation. ::: @@ -59,16 +43,33 @@ See the [Enterprise Quickstart](/docs/deploy/enterprise/quickstart) for an examp To generate a key, run the following command: -```sh +```shell head -c32 /dev/urandom | base64 ``` Add the value to your configuration file: ```yaml -# config file key shared_secret: wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs= +``` -# environment variable +```bash SHARED_SECRET=wC4RFsEdM1gHFzvRt3XW+iWw6Ddt/1kKkdh66OKxiqs= ``` + + + + +`shared_secret` is a bootstrap configuration setting and is not configurable in the Console. + + + + +| **Name** | **Type** | **Usage** | +| :-- | :-- | :-- | +| `secrets.shared_secret` | `string` | **required** (unless using [shared_secret_file](/docs/reference/shared-secret-file)) | + +See Kubernetes [bootstrap secrets](/docs/deploy/k8s/reference#spec) for more information. + + + diff --git a/content/docs/reference/signing-key-file.mdx b/content/docs/reference/signing-key-file.mdx index 5bd955aeb..ca7e57501 100644 --- a/content/docs/reference/signing-key-file.mdx +++ b/content/docs/reference/signing-key-file.mdx @@ -8,6 +8,7 @@ keywords: - Signing Key File pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -30,7 +31,21 @@ See [Signing Key](./signing-key) for more information. | **Config file keys** | **Environment variables** | **Type** | **Usage** | | :------------------- | :------------------------ | :------- | :----------- | -| `signing_key_file` | `signing_key_file` | `string` | **optional** | +| `signing_key_file` | `SIGNING_KEY_FILE` | `string` | **optional** | + +### Examples + +Signing Key File is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/). + +For example: + +```yaml +signing_key_file: '/run/secrets/POMERIUM_SIGNING_KEY' +``` + +```bash +SIGNING_KEY_FILE='/run/secrets/POMERIUM_SIGNING_KEY' +``` @@ -48,13 +63,3 @@ See Kubernetes [bootstrap secrets](/docs/deploy/k8s/reference#spec) for more inf - -### Examples - -Signing Key File is useful when deploying in environments that provide secret management like [Docker Swarm](https://docs.docker.com/engine/swarm/secrets/). - -For example: - -```yaml -signing_key_file: '/run/secrets/POMERIUM_SIGNING_KEY' -``` diff --git a/content/docs/reference/signing-key.mdx b/content/docs/reference/signing-key.mdx index a2eaf6cbb..a4f48d2b5 100644 --- a/content/docs/reference/signing-key.mdx +++ b/content/docs/reference/signing-key.mdx @@ -10,6 +10,7 @@ keywords: - Signing Key pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; diff --git a/content/docs/reference/signout-redirect-url.mdx b/content/docs/reference/signout-redirect-url.mdx index 59a85202e..206e39565 100644 --- a/content/docs/reference/signout-redirect-url.mdx +++ b/content/docs/reference/signout-redirect-url.mdx @@ -6,6 +6,7 @@ keywords: - Signout Redirect URL pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ You can overwrite this behavior by passing the query param `pomerium_redirect_ur | :--------------------- | :------------------------ | :------- | :----------- | | `signout_redirect_url` | `SIGNOUT_REDIRECT_URL` | `URL` | **required** | +### Examples + +```yaml +signout_redirect_url: https://signout-redirect-url.corp.example.com +``` + +```bash +SIGNOUT_REDIRECT_URL=https://signout-redirect-url.corp.example.com +``` + @@ -40,11 +51,3 @@ You can overwrite this behavior by passing the query param `pomerium_redirect_ur - -### Examples - -```yaml -signout_redirect_url: https://signout-redirect-url.corp.example.com - -SIGNOUT_REDIRECT_URL=https://signout-redirect-url.corp.example.com -``` diff --git a/content/docs/reference/the-number-of-trusted-hops.mdx b/content/docs/reference/the-number-of-trusted-hops.mdx index d15b2c53b..a81606bfa 100644 --- a/content/docs/reference/the-number-of-trusted-hops.mdx +++ b/content/docs/reference/the-number-of-trusted-hops.mdx @@ -8,6 +8,7 @@ keywords: - The number of trusted hops pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -28,6 +29,16 @@ import TabItem from '@theme/TabItem'; | :--------------------- | :------------------------ | :------- | :----------- | | `xff_num_trusted_hops` | `XFF_NUM_TRUSTED_HOPS` | `uint32` | **optional** | +### Examples + +```yaml +xff_num_trusted_hops: 2 +``` + +```bash +XFF_NUM_TRUSTED_HOPS=2 +``` + @@ -40,11 +51,3 @@ Kubernetes does not support `xff_num_trusted_hops` - -### Examples - -```yaml -xff_num_trusted_hops: 2 - -XFF_NUM_TRUSTED_HOPS=2 -``` diff --git a/content/docs/reference/tls-derive.mdx b/content/docs/reference/tls-derive.mdx index d3764c3a3..76b5cc67c 100644 --- a/content/docs/reference/tls-derive.mdx +++ b/content/docs/reference/tls-derive.mdx @@ -7,6 +7,7 @@ keywords: - reference pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -29,6 +30,16 @@ Auto TLS secures HTTPS and gRPC/TLS endpoints connecting the Console to the Data | :-- | :-- | :-- | :-- | :-- | | `tls_derive` | `TLS_DERIVE` | `FQDL` (fully qualified domain name) | **optional** | none | +### Examples + +```yaml +tls_derive: www.example.domain.com +``` + +```bash +TLS_DERIVE=www.example.domain.com +``` + @@ -49,13 +60,3 @@ When you set `tls_derive`: - A CA is derived from the `shared_secret` and is added to the list of system default CAs - An upstream route (`to`) server certificate signed by such a derived CA would be trusted - The Databroker gRPC server would use a server certificate with a provided domain name and signed by a derived CA - -### Examples - -```yaml -# config file key -tls_derive: www.example.domain.com - -# environment variable -TLS_DERIVE=www.example.domain.com -``` diff --git a/content/docs/reference/tracing.mdx b/content/docs/reference/tracing.mdx index 37fe1fb9c..e378d34a8 100644 --- a/content/docs/reference/tracing.mdx +++ b/content/docs/reference/tracing.mdx @@ -6,6 +6,7 @@ keywords: - Tracing pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; diff --git a/content/docs/reference/use-proxy-protocol.mdx b/content/docs/reference/use-proxy-protocol.mdx index 8f3b40787..cfa432b5a 100644 --- a/content/docs/reference/use-proxy-protocol.mdx +++ b/content/docs/reference/use-proxy-protocol.mdx @@ -6,6 +6,7 @@ keywords: - Use Proxy Protocol pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -26,6 +27,16 @@ Setting **Use Proxy Protocol** will configure Pomerium to require the [HAProxy p | :-- | :-- | :-- | :-- | :-- | | `use_proxy_protocol` | `USE_PROXY_PROTOCOL` | `boolean` | **optional** | `false` | +### Examples + +```yaml +use_proxy_protocol: true +``` + +```bash +USE_PROXY_PROTOCOL=true +``` + @@ -38,15 +49,13 @@ Setting **Use Proxy Protocol** will configure Pomerium to require the [HAProxy p | :----------------- | :-------- | :----------- | :---------- | | `useProxyProtocol` | `boolean` | **optional** | `false` | -See Kubernetes [Reference](/docs/deploy/k8s/reference#spec) for more information. - - - - ### Examples ```yaml -use_proxy_protocol: true - -USE_PROXY_PROTOCOL=true +useProxyProtocol: true ``` + +See Kubernetes [Reference](/docs/deploy/k8s/reference#spec) for more information. + + + diff --git a/content/docs/reference/x-forwarded-for-http-header.mdx b/content/docs/reference/x-forwarded-for-http-header.mdx index 5f1122387..fa01f8772 100644 --- a/content/docs/reference/x-forwarded-for-http-header.mdx +++ b/content/docs/reference/x-forwarded-for-http-header.mdx @@ -8,6 +8,7 @@ keywords: - X-Forwarded-For HTTP Header pagination_prev: null pagination_next: null +toc_max_heading_level: 2 --- import Tabs from '@theme/Tabs'; @@ -34,6 +35,16 @@ See the [Envoy](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/h | :------------------- | :------------------------ | :-------- | :---------- | | `skip_xff_append` | `SKIP_XFF_APPEND` | `boolean` | `false` | +### Examples + +```yaml +skip_xff_append: true +``` + +```bash +SKIP_XFF_APPEND=true +``` + @@ -52,13 +63,3 @@ Kubernetes does not support `skip_xff_append` - -### Examples - -```yaml -# config file key -skip_xff_append: true - -# environment variable -SKIP_XFF_APPEND=true -```