Complete configuration catalog
This reference is generated from Clearplane's validated configuration catalog. Each directive lists its supported sources, defaults, validation, apply behavior, and UI location.
Resolution and ownership
Runtime values resolve independently per setting in this order: environment variable → validated Clearplane container label → saved UI value → built-in default.
Environment variables carry bootstrap settings and secrets only. Every other runtime setting uses its documented container label or the UI; a label makes the matching UI field read-only until the label is removed. The MaxMind license key is the one runtime setting that also accepts an environment variable, because it is a secret.
Operator-supplied secret environment settings also accept the listed _FILE twin, which is read from a file mounted into the container; setting both forms is an error. Core-generated secrets have no twin because Core and Edge read them from the data volumes. Bootstrap settings are read once at process start, so every bootstrap change needs a restart, and an invalid bootstrap value stops the process with a message naming the variable. Container-discovered resources are read only from Docker labels; Clearplane never reads the labeled container's environment variables.
- Bootstrap: environment-only and applied at process startup.
- Runtime: may be changed through its documented sources and reports the effective source.
- Service resource: label-only configuration attached to a discovered proxy route or standalone redirect container.
- Immediate: consumed without an explicit Edge apply. Validated: accepted only after validation succeeds. Staged: saved until Edge configuration is applied. Restart required: effective after the owning process restarts.
Warning
Docker labels are visible through container inspection. Clearplane accepts secret labels because every supported label has the same configuration semantics, but the _FILE environment twin or the encrypted UI field are safer for credentials. APIs, diagnostics, logs, and this document never render secret values.
Label values
- Names are the API field names in kebab-case. Related fields share dotted groups such as
brotli.*orwaf.challenge.*. Boolean subfeatures end inenabledthe way their API field does, such asbrotli.enabledorwaf.websocket.inspection-enabled. Proxy policy families use their root label withInherit,OnorOff; they do not have an.enabledlabel. Units end the name:-seconds,-days,-bytes,-megabytes. - Enumerations are written like the REST API and the UI, for example
On,PreventionorMemoryOnly. Matching ignores case; numeric backing values are not accepted. Fields documented with literal numeric choices, such as redirect status codes, accept those listed numbers instead. - Booleans are
trueorfalse, ignoring case. - Lists are whitespace-delimited. YAML's folded form works because line breaks become spaces.
- Invalid owner-runtime values under
clearplane.core.*,clearplane.edge.*,clearplane.ui.*orclearplane.container-proxy.*are reported as warnings. The setting retains its previous valid label value; when none exists, the invalid label supplies no value and normal source resolution applies. Invalid service-resource values reject the discovered container and keep its previous route. - Unknown owner-runtime keys under those prefixes are reported as warnings and ignored. An unknown key does not preserve the override from a known runtime label it replaced; normal label-removal fallback still applies. Unknown service-resource keys reject the discovered container, except under
clearplane.proxy.cache.*(but notcache.key.*),compression.*,error-page.*,group.*,redirect.*andclearplane.redirect.group.*. Those families cannot weaken protection, so an unknown key there is also reported as a warning and ignored.
Each semantic collection uses indexed structured labels shaped as <semantic-collection>.<index>.<field>. Indices are one-based, may contain gaps, and are ordered numerically. Every indexed item must include its required fields; malformed, incomplete, duplicate, unknown, or out-of-range entries are rejected.
Every proxy policy family has the same envelope. The root label clearplane.proxy.<family> is Inherit (the default, which applies the family's enabled Global policies), On (the route's own policies, which replace the Global ones) or Off (no policy, even when a Global policy exists). Other family labels require the root label and reject the container without it; under Inherit or Off they are kept without validation. With On, clearplane.proxy.<family>.policy selects one existing policy by system name, and clearplane.proxy.<family>.policies selects several for access control, authentication, auto-ban and rate limit; otherwise the family's labels create an inline route-scoped policy and every omitted field takes its documented default. Named and inline fields cannot be combined. Authentication has no defaults to fall back on, so an inline authentication policy needs type and its credentials or keys.
Core directives
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|---|---|---|---|---|---|---|---|---|---|---|
clearplane.core.acme.email-address |
String | Valid email address, 1-320 characters | (empty) |
— | clearplane.core.acme.email-address |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Certificates → Let's Encrypt account | Required contact email address registered with the selected Let's Encrypt account. |
clearplane.core.acme.environment |
AcmeEnvironment | Production, Staging | Production |
— | clearplane.core.acme.environment |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Certificates → Let's Encrypt account | Let's Encrypt environment used for ACME accounts and certificate orders. |
clearplane.core.acme.terms-of-service-agreed |
Boolean | — | false |
— | clearplane.core.acme.terms-of-service-agreed |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Certificates → Let's Encrypt account | Must be true to confirm acceptance of the Let's Encrypt terms before saving the account configuration. |
clearplane.core.analytics.daily-retention-days |
Integer | Positive integer no less than hourly-retention-days | 90 |
— | clearplane.core.analytics.daily-retention-days |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Analytics | Days of daily analytics rollups retained before pruning. |
clearplane.core.analytics.hourly-retention-days |
Integer | Positive integer no greater than daily-retention-days | 14 |
— | clearplane.core.analytics.hourly-retention-days |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Analytics | Days of hourly analytics rollups retained before compaction into daily rollups. |
clearplane.core.bootstrap.acme-dns-profiles.<index>.api-token |
String | Non-blank value, up to 4096 characters | (empty) |
CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_<INDEX>API_TOKENCLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES<INDEX>_API_TOKEN_FILE |
— | Environment | Bootstrap | Secret | Restart required | — | Required API token for this numbered DNS profile. May be injected directly from a deployment secret or through its _FILE environment twin. |
clearplane.core.bootstrap.acme-dns-profiles.<index>.name |
String | Trimmed unique name, 1-200 characters | (empty) |
CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_<INDEX>_NAME |
— | Environment | Bootstrap | Public | Restart required | — | Required case-insensitively unique name for this numbered DNS profile. Indices start at 1 and may contain gaps. Certificate labels select this name. |
clearplane.core.bootstrap.acme-dns-profiles.<index>.propagation-seconds |
Integer (optional) | 1-3600, or empty for the provider default | (empty) |
CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_<INDEX>_PROPAGATION_SECONDS |
— | Environment | Bootstrap | Public | Restart required | — | Optional DNS propagation delay in seconds for this numbered DNS profile. |
clearplane.core.bootstrap.acme-dns-profiles.<index>.provider |
AcmeDnsProvider | Cloudflare | Cloudflare |
CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_<INDEX>_PROVIDER |
— | Environment | Bootstrap | Public | Restart required | — | DNS provider for this numbered DNS profile. |
clearplane.core.bootstrap.compose-project-name |
String | — | (empty) |
CLEARPLANE_CORE_BOOTSTRAP_COMPOSE_PROJECT_NAME |
— | Environment | Bootstrap | Public | Restart required | — | Compose project owning the Clearplane containers. When omitted, Core resolves the project from its runtime container identity. |
clearplane.core.bootstrap.waf-ruleset-signing-keys |
String | Whitespace-delimited <key-id>|<not-before UTC ISO8601>|<not-after UTC ISO8601>|<base64 P-521 SubjectPublicKeyInfo> entries | (empty) |
CLEARPLANE_CORE_BOOTSTRAP_WAF_RULESET_SIGNING_KEYS |
— | Environment | Bootstrap | Public | Restart required | — | Trusted WAF ruleset signing keys. When set, these replace the signing keys built into this Clearplane version instead of adding to them. Invalid entries stop the service from starting. Leave empty to trust only the built-in keys. Installed releases stay trusted only while their key ID still names the same public key. |
clearplane.core.container-discovery.enabled |
Boolean | — | true |
— | clearplane.core.container-discovery.enabled |
Container label | Runtime | Public | Immediate | — | Enable reconciliation of proxied services from container labels. |
clearplane.core.geo-ip.enabled |
Boolean | — | true |
— | clearplane.core.geo-ip.enabled |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Country geolocation | Enable country geolocation and enforcement of country-dependent access control policies. |
clearplane.core.geo-ip.license-key |
String | Up to 512 characters | (empty) |
CLEARPLANE_CORE_GEO_IP_LICENSE_KEYCLEARPLANE_CORE_GEO_IP_LICENSE_KEY_FILE |
clearplane.core.geo-ip.license-key |
Environment, Container label, UI/API | Runtime | Secret | Validated | System → Settings → Country geolocation | MaxMind license key. It is required only when country geolocation is effectively enabled with the MaxMind provider; empty is allowed when geolocation is disabled or DbIp is effective. |
clearplane.core.geo-ip.provider |
GeoIpProvider | DbIp, MaxMind, IpLocate | DbIp |
— | clearplane.core.geo-ip.provider |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Country geolocation | GeoIP country database provider. DbIp and IpLocate need no key; MaxMind needs a license key. |
clearplane.core.logs.indexed-retention-days |
Integer | Positive integer | 30 |
— | clearplane.core.logs.indexed-retention-days |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Logs | Days of queryable indexed logs retained before pruning. |
clearplane.core.logs.raw-retention-days |
Integer | Non-negative integer | 1 |
— | clearplane.core.logs.raw-retention-days |
Container label, UI/API | Runtime | Public | Validated | System → Settings → Logs | Days of fully ingested raw JSONL files retained. Zero removes rolled files after ingestion. |
Edge directives
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|---|---|---|---|---|---|---|---|---|---|---|
clearplane.edge.analytics-flush-interval-seconds |
Integer | 1-3600 | 30 |
— | clearplane.edge.analytics-flush-interval-seconds |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Analytics | Seconds between Edge analytics counter flushes to Core. Edge reads this once at startup, so a change takes effect when Edge restarts. |
clearplane.edge.automatic-apply.discovered-changes |
Boolean | — | true |
— | clearplane.edge.automatic-apply.discovered-changes |
Container label, UI/API | Runtime | Public | Immediate | System → Settings → Edge → Configuration delivery | Apply configuration changes discovered from container labels automatically. |
clearplane.edge.automatic-apply.saved-changes |
Boolean | — | false |
— | clearplane.edge.automatic-apply.saved-changes |
Container label, UI/API | Runtime | Public | Immediate | System → Settings → Edge → Configuration delivery | Apply saved configuration changes to Edge automatically. |
clearplane.edge.bootstrap.waf-memory-admission-percent |
Integer | 10-100 | 85 |
CLEARPLANE_EDGE_BOOTSTRAP_WAF_MEMORY_ADMISSION_PERCENT |
— | Environment | Bootstrap | Public | Restart required | — | Share of the managed heap ceiling a compiled WAF ruleset set may occupy. A configuration revision whose projected cost exceeds this share is refused and the previously published rulesets keep serving. A value outside the accepted range stops Edge at startup. |
clearplane.edge.cache.memory.maximum-size-megabytes |
Integer | 1-1048576 | 1024 |
— | clearplane.edge.cache.memory.maximum-size-megabytes |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → Capacity | Combined memory pools of all enabled cache policies, in megabytes. Edge also keeps the memory tier within half the container's memory limit and what the shared memory budget leaves free. |
clearplane.edge.cache.persistent.maximum-size-megabytes |
Integer | 1-1048576 | 8192 |
— | clearplane.edge.cache.persistent.maximum-size-megabytes |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → Capacity | Combined persistent pools of all enabled cache policies, in megabytes. |
clearplane.edge.client-ip-headers |
Whitespace list of string values | Ordered whitespace-delimited list of unique HTTP header names, up to 256 characters each | X-Forwarded-For |
— | clearplane.edge.client-ip-headers |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → Network | Client IP headers in priority order, accepted only from trusted proxies. The first non-empty header wins. X-Forwarded-For uses right-to-left proxy-chain resolution; other headers require exactly one IP address. A malformed selected header keeps the peer address and logs a warning without trying later headers. If no configured header is present, the peer address is retained; custom header lists also log a warning. Every listed header must be trustworthy from every trusted proxy. Untrusted peers have all configured headers removed before forwarding upstream. |
clearplane.edge.http1.enabled |
Boolean | — | true |
— | clearplane.edge.http1.enabled |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → HTTPS protocols | Accept HTTP/1.1 connections on the public HTTPS listener. The clearplane.edge.http1.enabled label on the Edge container overrides the saved UI value. Keep at least one HTTPS protocol enabled. Changes require an Edge restart; the plain HTTP listener retains HTTP/1.1 for redirects, ACME, and health checks. |
clearplane.edge.http2.enabled |
Boolean | — | true |
— | clearplane.edge.http2.enabled |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → HTTPS protocols | Accept HTTP/2 connections on the public HTTPS listener. The clearplane.edge.http2.enabled label on the Edge container overrides the saved UI value. Keep at least one HTTPS protocol enabled. Changes require an Edge restart; the plain HTTP listener retains HTTP/1.1 for redirects, ACME, and health checks. |
clearplane.edge.http3.enabled |
Boolean | — | true |
— | clearplane.edge.http3.enabled |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → HTTPS protocols | Accept HTTP/3 connections on the public HTTPS listener when QUIC is supported. The clearplane.edge.http3.enabled label on the Edge container overrides the saved UI value. Keep at least one HTTPS protocol enabled. HTTP/3 alone requires clients that can discover or directly request it and a QUIC-capable runtime. Changes require an Edge restart. |
clearplane.edge.maximum-concurrent-connections-per-address |
Integer (optional) | Positive integer or empty for unlimited | 100 |
— | clearplane.edge.maximum-concurrent-connections-per-address |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Maximum concurrent connections per client address. |
clearplane.edge.maximum-request-body-size-bytes |
Long integer (optional) | Positive integer or empty for unlimited | 30000000 |
— | clearplane.edge.maximum-request-body-size-bytes |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Maximum request-body size in bytes for routes without their own clearplane.proxy.maximum-request-body-size-bytes. |
clearplane.edge.maximum-request-headers-total-size-bytes |
Integer | 1024-1048576 | 32768 |
— | clearplane.edge.maximum-request-headers-total-size-bytes |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Maximum combined request-header size in bytes. |
clearplane.edge.maximum-total-connections |
Integer (optional) | Positive integer or empty for unlimited | 10000 |
— | clearplane.edge.maximum-total-connections |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Maximum concurrent connections accepted by Edge. |
clearplane.edge.maximum-tracked-partitions |
Integer | 1000-10000000 | 100000 |
— | clearplane.edge.maximum-tracked-partitions |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → Capacity | Maximum in-memory partitions retained for rate-limit counting and auto-ban tracking. Unrelated to the response cache. |
clearplane.edge.maximum-uri-size-bytes |
Integer | 256-16384 | 8192 |
— | clearplane.edge.maximum-uri-size-bytes |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Maximum request URI size in bytes. |
clearplane.edge.minimum-request-body-data-rate-bytes-per-second |
Integer (optional) | Positive integer or empty to disable | 240 |
— | clearplane.edge.minimum-request-body-data-rate-bytes-per-second |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Minimum request-body data rate in bytes per second. |
clearplane.edge.minimum-request-body-data-rate-grace-period-seconds |
Integer | 1-60 | 5 |
— | clearplane.edge.minimum-request-body-data-rate-grace-period-seconds |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Grace period in seconds for the minimum request-body data rate. |
clearplane.edge.minimum-tls-version |
String | 1.2, 1.3 | 1.2 |
— | clearplane.edge.minimum-tls-version |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → HTTPS protocols | Minimum TLS version accepted on the public HTTPS listener. TLS 1.0 and 1.1 are unavailable. Changes require an Edge restart. |
clearplane.edge.request-headers-timeout-seconds |
Integer | 1-300 | 30 |
— | clearplane.edge.request-headers-timeout-seconds |
Container label, UI/API | Runtime | Public | Restart required | System → Settings → Edge → Request safety | Seconds allowed for receiving request headers. |
clearplane.edge.restricted-destination-classes |
Whitespace list of UpstreamDestinationRestrictionClass values | Loopback, PrivateNetwork, LinkLocal, CloudMetadata, ControlPlaneNetwork | (empty) |
— | clearplane.edge.restricted-destination-classes |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → Network | Unique whitespace-delimited destination address classes denied for upstream proxy connections. Empty allows all classes. ControlPlaneNetwork may be selected only when control-plane ranges exist. Edge's own mTLS connections to Core and the UI are not restricted. |
clearplane.edge.trusted-proxies |
Whitespace list of string values | Canonical IPv4 or IPv6 addresses or CIDR ranges; /0 is forbidden | (empty) |
— | clearplane.edge.trusted-proxies |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → Network | Addresses or CIDR ranges trusted to supply forwarded client information; an empty list trusts none. Never list the Docker bridge gateway address: with Docker's userland proxy or IPv6 published ports every external client arrives from it, and trusting it lets any client choose its own client address. |
clearplane.edge.waf.regex.engine |
WafRegexEngine | Linear, Backtracking | Linear |
— | clearplane.edge.waf.regex.engine |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → WAF regex engine | How WAF rules match regular expressions. Linear guarantees matching time grows only with input length, but compiled rules use far more memory: all Clearplane rulesets together need roughly 775 MB. Backtracking uses a few MB, but a crafted request can make a pattern slow, so every request gets regex.time-limit-milliseconds of regex time. |
clearplane.edge.waf.regex.time-limit-action |
WafRegexTimeLimitAction | Block, Allow | Block |
— | clearplane.edge.waf.regex.time-limit-action |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → WAF regex engine | What happens to a request that uses up its regex time under the Backtracking engine. Block rejects it on routes whose WAF policy can block, like any exhausted inspection budget. Allow forwards it uninspected by the remaining rules and logs it, which lets an attacker who can trigger the limit skip rules. Ignored by the Linear engine. |
clearplane.edge.waf.regex.time-limit-milliseconds |
Integer | 1-1000 | 50 |
— | clearplane.edge.waf.regex.time-limit-milliseconds |
Container label, UI/API | Runtime | Public | Staged | System → Settings → Edge → WAF regex engine | Regex time each request may use under the Backtracking engine. A single slow match can overrun it once, so a request uses at most about twice this value. Ignored by the Linear engine. |
UI directives
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|
ContainerProxy directives
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|
Proxy directives
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|---|---|---|---|---|---|---|---|---|---|---|
clearplane.proxy.access-control |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.access-control |
Container label | Service resource | Public | Immediate | — | Inherit the Global access control policies, turn on this proxy route's own access control policies, or turn the feature off for this route. |
clearplane.proxy.access-control.allowed-addresses |
Whitespace list of string values | IP addresses or CIDR ranges | (empty) |
— | clearplane.proxy.access-control.allowed-addresses |
Container label | Service resource | Public | Immediate | — | Addresses allowed by the generated inline access control policy. |
clearplane.proxy.access-control.allowed-countries |
Whitespace list of string values | ISO alpha-2 country codes | (empty) |
— | clearplane.proxy.access-control.allowed-countries |
Container label | Service resource | Public | Immediate | — | Countries allowed by the generated inline access control policy. |
clearplane.proxy.access-control.blocked-addresses |
Whitespace list of string values | IP addresses or CIDR ranges | (empty) |
— | clearplane.proxy.access-control.blocked-addresses |
Container label | Service resource | Public | Immediate | — | Addresses blocked by the generated inline access control policy. |
clearplane.proxy.access-control.blocked-countries |
Whitespace list of string values | ISO alpha-2 country codes | (empty) |
— | clearplane.proxy.access-control.blocked-countries |
Container label | Service resource | Public | Immediate | — | Countries blocked by the generated inline access control policy. |
clearplane.proxy.access-control.default-action |
AccessControlAction | Allow, Block | Allow |
— | clearplane.proxy.access-control.default-action |
Container label | Service resource | Public | Immediate | — | Default action for the generated inline access control policy. |
clearplane.proxy.access-control.policies |
Whitespace list of string values | Unique policy system names | — | — | clearplane.proxy.access-control.policies |
Container label | Service resource | Public | Immediate | — | Existing Route-scoped access control policies, each using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.access-control is On. Without it, the route's labels create an inline policy; references cannot be mixed with inline access-control fields. |
clearplane.proxy.additional-hosts |
Whitespace list of string values | Unique exact DNS hosts or single-label wildcards such as *.example.com, each up to 253 characters without the *. prefix | (empty) |
— | clearplane.proxy.additional-hosts |
Container label | Service resource | Public | Immediate | — | Additional public hosts matched by the generated route. They are compared case-insensitively, must not repeat the primary host, and should list a wildcard's base domain explicitly when it should also match. |
clearplane.proxy.authentication |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.authentication |
Container label | Service resource | Public | Immediate | — | Turn on this proxy route's own authentication policies. Authentication has no Global policy, so Inherit and Off both leave the route without authentication. |
clearplane.proxy.authentication.basic.realm |
String | Non-empty string, up to 200 characters | — | — | clearplane.proxy.authentication.basic.realm |
Container label | Service resource | Public | Immediate | — | Required realm shown by the generated Basic authentication challenge. |
clearplane.proxy.authentication.combine-mode |
AuthenticationCombineMode | Or, And | Or |
— | clearplane.proxy.authentication.combine-mode |
Container label | Service resource | Public | Immediate | — | How the route combines several authentication policies. Or accepts a request that satisfies any policy; And requires every policy. |
clearplane.proxy.authentication.jwt.audiences |
Whitespace list of string values | 1-20 unique values, each up to 400 characters | — | — | clearplane.proxy.authentication.jwt.audiences |
Container label | Service resource | Public | Immediate | — | Required accepted JWT audiences for the generated policy. |
clearplane.proxy.authentication.jwt.clock-skew-seconds |
Integer | 0-300 | 60 |
— | clearplane.proxy.authentication.jwt.clock-skew-seconds |
Container label | Service resource | Public | Immediate | — | JWT expiry and not-before tolerance in seconds. |
clearplane.proxy.authentication.jwt.issuer |
String | Non-empty string, up to 400 characters | — | — | clearplane.proxy.authentication.jwt.issuer |
Container label | Service resource | Public | Immediate | — | Required expected JWT issuer claim for the generated policy. |
clearplane.proxy.authentication.key-location |
AuthenticationKeyLocation | Edge, Core | Edge |
— | clearplane.proxy.authentication.key-location |
Container label | Service resource | Public | Immediate | — | Where the generated inline policy verifies credentials. Edge keeps the keys on Edge, which is fastest and keeps working while Core is unreachable. Core keeps the keys off the internet-facing Edge, which then verifies each request through Core at a cost of about 2-10 ms. |
clearplane.proxy.authentication.policies |
Whitespace list of string values | Unique policy system names | — | — | clearplane.proxy.authentication.policies |
Container label | Service resource | Public | Immediate | — | Existing authentication policies, each using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.authentication is On. Without it, the route's authentication labels create an inline policy; a reference cannot be mixed with inline authentication fields. |
clearplane.proxy.authentication.type |
AuthenticationType | Basic, Jwt | — | — | clearplane.proxy.authentication.type |
Container label | Service resource | Public | Immediate | — | Authentication method for the generated inline policy. Required when clearplane.proxy.authentication is On without a policy reference. |
clearplane.proxy.auto-ban |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.auto-ban |
Container label | Service resource | Public | Immediate | — | Inherit the Global auto-ban policies, turn on this proxy route's own auto-ban policies, or turn the feature off for this route. |
clearplane.proxy.auto-ban.client-error-response.enabled |
Boolean | — | true |
— | clearplane.proxy.auto-ban.client-error-response.enabled |
Container label | Service resource | Public | Immediate | — | Ban clients that exceed the configured 4xx-response threshold. Proxied 400–499 responses count, as does Edge's own 401 when presented credentials fail authentication. Server failures never count. |
clearplane.proxy.auto-ban.client-error-response.status-codes |
Whitespace list of integer values | Unique HTTP status codes 400-499 | (empty) |
— | clearplane.proxy.auto-ban.client-error-response.status-codes |
Container label | Service resource | Public | Immediate | — | Proxied client-error status codes counted by the client-error-response trigger. Empty counts every 400-499 response. |
clearplane.proxy.auto-ban.client-error-response.threshold |
Integer | Positive integer | 100 |
— | clearplane.proxy.auto-ban.client-error-response.threshold |
Container label | Service resource | Public | Immediate | — | Proxied HTTP 400–499 responses permitted during the tracking window before a ban. |
clearplane.proxy.auto-ban.client-error-response.window-seconds |
Integer | Positive integer | 60 |
— | clearplane.proxy.auto-ban.client-error-response.window-seconds |
Container label | Service resource | Public | Immediate | — | Proxied 4xx-response tracking window in seconds. |
clearplane.proxy.auto-ban.duration-seconds |
Integer | Positive integer | 600 |
— | clearplane.proxy.auto-ban.duration-seconds |
Container label | Service resource | Public | Immediate | — | Initial automatic ban duration in seconds. |
clearplane.proxy.auto-ban.escalation.enabled |
Boolean | — | false |
— | clearplane.proxy.auto-ban.escalation.enabled |
Container label | Service resource | Public | Immediate | — | Increase repeat ban durations within the escalation window. |
clearplane.proxy.auto-ban.escalation.maximum-duration-seconds |
Integer | Positive integer no less than duration-seconds when escalation is enabled | 86400 |
— | clearplane.proxy.auto-ban.escalation.maximum-duration-seconds |
Container label | Service resource | Public | Immediate | — | Maximum escalated ban duration in seconds. Applies only when escalation is enabled; a policy without escalation always uses the initial duration. |
clearplane.proxy.auto-ban.escalation.multiplier |
Integer | Positive integer; at least 2 when escalation is enabled | 2 |
— | clearplane.proxy.auto-ban.escalation.multiplier |
Container label | Service resource | Public | Immediate | — | Multiplier applied to repeat automatic bans. |
clearplane.proxy.auto-ban.escalation.window-seconds |
Integer | Positive integer | 86400 |
— | clearplane.proxy.auto-ban.escalation.window-seconds |
Container label | Service resource | Public | Immediate | — | Repeat-ban escalation window in seconds. |
clearplane.proxy.auto-ban.policies |
Whitespace list of string values | Unique policy system names | — | — | clearplane.proxy.auto-ban.policies |
Container label | Service resource | Public | Immediate | — | Existing Route-scoped auto-ban policies, each using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.auto-ban is On. Without it, the route's labels create an inline policy; references cannot be mixed with inline auto-ban fields. |
clearplane.proxy.auto-ban.rate-limit-violation.enabled |
Boolean | — | true |
— | clearplane.proxy.auto-ban.rate-limit-violation.enabled |
Container label | Service resource | Public | Immediate | — | Ban clients that exceed the rate-limit violation threshold. Only rejections by an address-keyed rate limit policy count as violations. |
clearplane.proxy.auto-ban.rate-limit-violation.threshold |
Integer | Positive integer | 50 |
— | clearplane.proxy.auto-ban.rate-limit-violation.threshold |
Container label | Service resource | Public | Immediate | — | Rate-limit violations permitted during the violation window before a ban. |
clearplane.proxy.auto-ban.rate-limit-violation.window-seconds |
Integer | Positive integer | 60 |
— | clearplane.proxy.auto-ban.rate-limit-violation.window-seconds |
Container label | Service resource | Public | Immediate | — | Rate-limit violation tracking window in seconds. |
clearplane.proxy.cache |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.cache |
Container label | Service resource | Public | Immediate | — | Inherit the Global cache policy, turn on this proxy route's own cache policy, or turn caching off for this route. |
clearplane.proxy.cache.bypass-cookies |
Whitespace list of string values | Unique cookie names, name prefixes ending in *, or * alone | (empty) |
— | clearplane.proxy.cache.bypass-cookies |
Container label | Service resource | Public | Immediate | — | Request cookies that make a request bypass the cache. Other request cookies are ignored for caching and still forwarded upstream. |
clearplane.proxy.cache.default-time-to-live-seconds |
Integer | 1-31536000 | 7200 |
— | clearplane.proxy.cache.default-time-to-live-seconds |
Container label | Service resource | Public | Immediate | — | Fresh cache lifetime in seconds when the upstream declares none and no per-status lifetime applies. Must be between the minimum and maximum lifetimes. |
clearplane.proxy.cache.downstream-cache-control |
DownstreamCacheControl | Preserve, Override, Remove | Preserve |
— | clearplane.proxy.cache.downstream-cache-control |
Container label | Service resource | Public | Immediate | — | Cache-Control sent to the client. |
clearplane.proxy.cache.downstream-maximum-age-seconds |
Integer | 0-31536000 | 0 |
— | clearplane.proxy.cache.downstream-maximum-age-seconds |
Container label | Service resource | Public | Immediate | — | Client max-age in seconds when the downstream cache control is overridden. |
clearplane.proxy.cache.eligibility |
CacheEligibility | StaticFiles, Everything | StaticFiles |
— | clearplane.proxy.cache.eligibility |
Container label | Service resource | Public | Immediate | — | Requests that use the cache. StaticFiles caches only paths ending in one of the file extensions; Everything caches any path. |
clearplane.proxy.cache.file-extensions |
Whitespace list of string values | Unique extensions of letters and digits without the leading dot, each up to 32 characters | 7z avi apk avif bin bmp bz2 class css csv dat doc docx dmg ejs eot eps exe flac gif gz ico iso jar jpeg jpg js map mid midi mjs mkv mp3 mp4 ogg otf pdf pict pls png ppt pptx ps rar svg svgz swf tar tif tiff ttf wasm webm webmanifest webp woff woff2 xls xlsx zip zst |
— | clearplane.proxy.cache.file-extensions |
Container label | Service resource | Public | Immediate | — | File extensions cached when eligibility is StaticFiles. Matching ignores case. |
clearplane.proxy.cache.honor-cdn-cache-control |
Boolean | — | true |
— | clearplane.proxy.cache.honor-cdn-cache-control |
Container label | Service resource | Public | Immediate | — | Prefer the CDN-Cache-Control header over Cache-Control. |
clearplane.proxy.cache.ignore-request-no-cache |
Boolean | — | true |
— | clearplane.proxy.cache.ignore-request-no-cache |
Container label | Service resource | Public | Immediate | — | Serve a stored response despite a client request no-cache directive, so a browser reload cannot force an upstream fetch. |
clearplane.proxy.cache.ignore-request-no-store |
Boolean | — | true |
— | clearplane.proxy.cache.ignore-request-no-store |
Container label | Service resource | Public | Immediate | — | Allow serving and storing a response despite a client request no-store directive. This overrides the client's strongest cache privacy directive. |
clearplane.proxy.cache.ignore-upstream-cache-control |
Boolean | — | false |
— | clearplane.proxy.cache.ignore-upstream-cache-control |
Container label | Service resource | Public | Immediate | — | Discard the lifetime declared by the upstream and use the default lifetime. Cannot be true together with require-upstream-cache-control. |
clearplane.proxy.cache.ignore-upstream-no-cache |
Boolean | — | false |
— | clearplane.proxy.cache.ignore-upstream-no-cache |
Container label | Service resource | Public | Immediate | — | Serve cached responses despite an upstream no-cache directive. |
clearplane.proxy.cache.key.header-names |
Whitespace list of string values | Unique HTTP header names, each up to 200 characters | (empty) |
— | clearplane.proxy.cache.key.header-names |
Container label | Service resource | Public | Immediate | — | Request headers included in cache keys. Authorization, Proxy-Authorization and Cookie are forbidden. |
clearplane.proxy.cache.key.include-host |
Boolean | — | true |
— | clearplane.proxy.cache.key.include-host |
Container label | Service resource | Public | Immediate | — | Include the request host in cache keys. |
clearplane.proxy.cache.key.include-path |
Boolean | — | true |
— | clearplane.proxy.cache.key.include-path |
Container label | Service resource | Public | Immediate | — | Include the request path in cache keys. |
clearplane.proxy.cache.key.query-parameter-names |
Whitespace list of string values | Unique non-blank names, each up to 200 characters | (empty) |
— | clearplane.proxy.cache.key.query-parameter-names |
Container label | Service resource | Public | Immediate | — | Query parameters included or excluded by the query-string mode. Include and Exclude require at least one name. |
clearplane.proxy.cache.key.query-string-mode |
CacheQueryStringMode | All, None, Include, Exclude | All |
— | clearplane.proxy.cache.key.query-string-mode |
Container label | Service resource | Public | Immediate | — | Query-string contribution to cache keys. |
clearplane.proxy.cache.maximum-response-size-megabytes |
Integer | 1-256 | 64 |
— | clearplane.proxy.cache.maximum-response-size-megabytes |
Container label | Service resource | Public | Immediate | — | Largest response cached at all, in megabytes. Edge holds each response in memory until it is stored, so larger responses cannot be cached. Must not exceed persistent.maximum-total-size-megabytes when the storage mode uses the persistent tier, or memory.maximum-total-size-megabytes under MemoryOnly. |
clearplane.proxy.cache.maximum-time-to-live-seconds |
Integer | 1-31536000 | 31536000 |
— | clearplane.proxy.cache.maximum-time-to-live-seconds |
Container label | Service resource | Public | Immediate | — | Ceiling applied to a lifetime declared by the upstream, in seconds. Must not be less than the minimum or default lifetime. |
clearplane.proxy.cache.memory.maximum-response-size-megabytes |
Integer | 1-256 | 8 |
— | clearplane.proxy.cache.memory.maximum-response-size-megabytes |
Container label | Service resource | Public | Immediate | — | Largest response kept in memory under MemoryWithPersistentFallback, in megabytes. Larger responses are stored on disk only and stream from it. Capped by maximum-response-size-megabytes and memory.maximum-total-size-megabytes. Other storage modes ignore it. |
clearplane.proxy.cache.memory.maximum-total-size-megabytes |
Integer | 1-1048576 | 256 |
— | clearplane.proxy.cache.memory.maximum-total-size-megabytes |
Container label | Service resource | Public | Immediate | — | Memory pool in megabytes shared by every route that uses this policy. PersistentOnly ignores it. |
clearplane.proxy.cache.minimum-time-to-live-seconds |
Integer | 0-31536000 | 0 |
— | clearplane.proxy.cache.minimum-time-to-live-seconds |
Container label | Service resource | Public | Immediate | — | Floor applied to a lifetime declared by the upstream, in seconds. Must not exceed the default or maximum lifetime. |
clearplane.proxy.cache.path-rules |
Whitespace list of string values | Up to 32 unique pattern=action[,time-to-live-seconds=N][,ignore-upstream-cache-control][,downstream-maximum-age-seconds=N] rules; action is cache or bypass; a pattern starts with / and contains no whitespace, =, comma, ? or # | (empty) |
— | clearplane.proxy.cache.path-rules |
Container label | Service resource | Public | Immediate | — | Ordered path rules; the first rule whose pattern matches the request path applies, and * matches any characters including /. cache caches the path whatever the eligibility and extensions, optionally with its own lifetime (time-to-live-seconds), without the upstream's lifetime (ignore-upstream-cache-control) and with a client max-age (downstream-maximum-age-seconds); bypass never caches it. For example: /_framework/=cache,time-to-live-seconds=31536000 /api/=bypass /=cache. |
clearplane.proxy.cache.persistent.maximum-total-size-megabytes |
Integer | 1-1048576 | 1024 |
— | clearplane.proxy.cache.persistent.maximum-total-size-megabytes |
Container label | Service resource | Public | Immediate | — | Persistent pool in megabytes shared by every route that uses this policy. MemoryOnly ignores it. |
clearplane.proxy.cache.policy |
String | One policy system name | — | — | clearplane.proxy.cache.policy |
Container label | Service resource | Public | Immediate | — | One existing Route-scoped cache policy using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.cache is On. Without it, the route's labels create an inline policy; the reference cannot be mixed with inline cache fields. |
clearplane.proxy.cache.purge-on-redeploy |
Boolean | — | true |
— | clearplane.proxy.cache.purge-on-redeploy |
Container label | Service resource | Public | Immediate | — | Purge this route's cached responses when discovery sees its container recreated, for example after a deploy. |
clearplane.proxy.cache.require-upstream-cache-control |
Boolean | — | false |
— | clearplane.proxy.cache.require-upstream-cache-control |
Container label | Service resource | Public | Immediate | — | Cache only responses that declare a cache lifetime. Cannot be true together with ignore-upstream-cache-control. |
clearplane.proxy.cache.stale-if-error-seconds |
Integer | 0-31536000 | 300 |
— | clearplane.proxy.cache.stale-if-error-seconds |
Container label | Service resource | Public | Immediate | — | Stale-if-error window in seconds. |
clearplane.proxy.cache.stale-while-revalidate-seconds |
Integer | 0-31536000 | 30 |
— | clearplane.proxy.cache.stale-while-revalidate-seconds |
Container label | Service resource | Public | Immediate | — | Stale-while-revalidate window in seconds. |
clearplane.proxy.cache.status-codes |
Whitespace list of integer values | Unique HTTP status codes 100-599 | 200 301 302 303 404 410 |
— | clearplane.proxy.cache.status-codes |
Container label | Service resource | Public | Immediate | — | Response status codes eligible for caching. |
clearplane.proxy.cache.status-codes-time-to-live |
Whitespace list of string values | Non-overlapping code[-code]=seconds entries; codes 100-599 and seconds 0-31536000 | 302-303=1200 404=180 410=180 |
— | clearplane.proxy.cache.status-codes-time-to-live |
Container label | Service resource | Public | Immediate | — | Per-status cache lifetimes that replace the default lifetime when the upstream declares none. |
clearplane.proxy.cache.storage-mode |
CacheStorageMode | MemoryOnly, PersistentOnly, MemoryWithPersistentFallback | MemoryWithPersistentFallback |
— | clearplane.proxy.cache.storage-mode |
Container label | Service resource | Public | Immediate | — | Cache storage mode. |
clearplane.proxy.cache.vary-handling |
CacheVaryHandling | Honor, Ignore | Honor |
— | clearplane.proxy.cache.vary-handling |
Container label | Service resource | Public | Immediate | — | Honor stores a separate copy per value of each header the upstream lists in Vary; Ignore stores one copy regardless of Vary. Vary: *, Cookie or Authorization is never stored. |
clearplane.proxy.certificate.additional-domains |
Whitespace list of string values | Unique exact DNS hosts or single-label wildcards such as *.example.com, each up to 253 characters without the *. prefix | (empty) |
— | clearplane.proxy.certificate.additional-domains |
Container label | Service resource | Public | Immediate | — | Extra certificate domains beyond the route's hosts and redirect sources. The final certificate may have at most 99 subject alternative names. Wildcards require a DNS profile or inline credentials. |
clearplane.proxy.certificate.dns.api-token |
String | Non-empty single-line value, up to 4096 characters | — | — | clearplane.proxy.certificate.dns.api-token |
Container label | Service resource | Secret | Immediate | — | Required whenever any inline DNS field is present. Core encrypts the token before persistence. Inline DNS fields cannot be combined with dns.profile-name. |
clearplane.proxy.certificate.dns.profile-name |
String | Trimmed non-empty profile name, up to 200 characters | — | — | clearplane.proxy.certificate.dns.profile-name |
Container label | Service resource | Public | Immediate | — | Named DNS profile used for DNS-01 validation. Cannot be combined with the dns.provider, dns.api-token, or dns.propagation-seconds fields. Without either form of DNS configuration, HTTP-01 is used. |
clearplane.proxy.certificate.dns.propagation-seconds |
Integer (optional) | 1-3600, or empty for the provider default | — | — | clearplane.proxy.certificate.dns.propagation-seconds |
Container label | Service resource | Public | Immediate | — | Optional propagation delay in seconds for this route's inline DNS credentials. Requires dns.api-token. |
clearplane.proxy.certificate.dns.provider |
AcmeDnsProvider | Cloudflare | Cloudflare |
— | clearplane.proxy.certificate.dns.provider |
Container label | Service resource | Public | Immediate | — | Provider for this route's inline DNS credentials. Requires dns.api-token and cannot be combined with the dns.profile-name field. |
clearplane.proxy.certificate.domain |
String | Exact DNS host, up to 253 characters | — | — | clearplane.proxy.certificate.domain |
Container label | Service resource | Public | Immediate | — | Primary certificate domain. Defaults to the route host or the base of a covering wildcard route host. An explicit domain must not be covered by a requested wildcard. Wildcard route hosts are included in the certificate and require a DNS profile. |
clearplane.proxy.certificate.enabled |
Boolean | — | false |
— | clearplane.proxy.certificate.enabled |
Container label | Service resource | Public | Immediate | — | Request and renew an ACME certificate for this proxy route. |
clearplane.proxy.certificate.wildcard |
Boolean | — | false |
— | clearplane.proxy.certificate.wildcard |
Container label | Service resource | Public | Immediate | — | Include a one-label wildcard for the primary certificate domain. Enabling it requires a named DNS profile or inline DNS credentials. |
clearplane.proxy.compression |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.compression |
Container label | Service resource | Public | Immediate | — | Inherit the Global compression policy, turn on this proxy route's own compression policy, or turn the feature off for this route. |
clearplane.proxy.compression.brotli.enabled |
Boolean | — | true |
— | clearplane.proxy.compression.brotli.enabled |
Container label | Service resource | Public | Immediate | — | Enable Brotli response compression in the generated inline policy. At least one of Brotli, Zstandard, or gzip must be enabled. |
clearplane.proxy.compression.brotli.level |
Integer | 0-11 | 4 |
— | clearplane.proxy.compression.brotli.level |
Container label | Service resource | Public | Immediate | — | Brotli quality level for the generated inline policy. |
clearplane.proxy.compression.content-types |
Whitespace list of string values | Up to 256 unique media-type selectors, each up to 200 characters; prefix exclusions with ! | text/* application/json application/+json application/javascript application/x-javascript application/xml application/+xml application/wasm image/svg+xml font/* application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype application/x-font-ttf !text/event-stream !font/woff !font/woff2 |
— | clearplane.proxy.compression.content-types |
Container label | Service resource | Public | Immediate | — | Response content types eligible for compression. Selectors may be exact, type/, type/+suffix, or /. Exclusions always win, the combined selectors must leave at least one included type, and HTTP request methods are not filtered. |
clearplane.proxy.compression.gzip.enabled |
Boolean | — | true |
— | clearplane.proxy.compression.gzip.enabled |
Container label | Service resource | Public | Immediate | — | Enable gzip response compression in the generated inline policy. At least one of Brotli, Zstandard, or gzip must be enabled. |
clearplane.proxy.compression.gzip.level |
Integer | 1-9 | 6 |
— | clearplane.proxy.compression.gzip.level |
Container label | Service resource | Public | Immediate | — | gzip compression level for the generated inline policy. |
clearplane.proxy.compression.minimum-response-size-bytes |
Integer | 0-1048576 | 1024 |
— | clearplane.proxy.compression.minimum-response-size-bytes |
Container label | Service resource | Public | Immediate | — | Minimum identity response body size in bytes before compression is applied. |
clearplane.proxy.compression.policy |
String | One policy system name | — | — | clearplane.proxy.compression.policy |
Container label | Service resource | Public | Immediate | — | One existing Route-scoped compression policy using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.compression is On. Without it, the route's labels create an inline policy; the reference cannot be mixed with inline compression fields. |
clearplane.proxy.compression.zstandard.enabled |
Boolean | — | false |
— | clearplane.proxy.compression.zstandard.enabled |
Container label | Service resource | Public | Immediate | — | Enable Zstandard response compression in the generated inline policy. At least one of Brotli, Zstandard, or gzip must be enabled. |
clearplane.proxy.compression.zstandard.level |
Integer | 1-22 | 3 |
— | clearplane.proxy.compression.zstandard.level |
Container label | Service resource | Public | Immediate | — | Zstandard quality level for the generated inline policy. |
clearplane.proxy.cors |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.cors |
Container label | Service resource | Public | Immediate | — | Inherit the Global CORS policy, turn on this proxy route's own CORS policy, or turn the feature off for this route. |
clearplane.proxy.cors.allow-any-header |
Boolean | — | true |
— | clearplane.proxy.cors.allow-any-header |
Container label | Service resource | Public | Immediate | — | Allow any request header. |
clearplane.proxy.cors.allow-any-method |
Boolean | — | true |
— | clearplane.proxy.cors.allow-any-method |
Container label | Service resource | Public | Immediate | — | Allow any request method. |
clearplane.proxy.cors.allow-credentials |
Boolean | — | false |
— | clearplane.proxy.cors.allow-credentials |
Container label | Service resource | Public | Immediate | — | Allow credentialed cross-origin requests. Cannot be combined with the wildcard origin. |
clearplane.proxy.cors.allowed-headers |
Whitespace list of string values | Unique HTTP header names, each up to 200 characters; non-empty when allow-any-header is false | (empty) |
— | clearplane.proxy.cors.allowed-headers |
Container label | Service resource | Public | Immediate | — | Request headers allowed when allow-any-header is false. |
clearplane.proxy.cors.allowed-methods |
Whitespace list of string values | Unique HTTP method tokens; non-empty when allow-any-method is false | (empty) |
— | clearplane.proxy.cors.allowed-methods |
Container label | Service resource | Public | Immediate | — | Methods allowed when allow-any-method is false. |
clearplane.proxy.cors.allowed-origins |
Whitespace list of string values | Unique HTTP origins, or * by itself | (empty) |
— | clearplane.proxy.cors.allowed-origins |
Container label | Service resource | Public | Immediate | — | Origins allowed by the generated inline CORS policy. Credentials cannot be enabled with the wildcard origin. |
clearplane.proxy.cors.exposed-headers |
Whitespace list of string values | Unique HTTP header names, each up to 200 characters | (empty) |
— | clearplane.proxy.cors.exposed-headers |
Container label | Service resource | Public | Immediate | — | Response headers exposed to the browser. |
clearplane.proxy.cors.policy |
String | One policy system name | — | — | clearplane.proxy.cors.policy |
Container label | Service resource | Public | Immediate | — | One existing Route-scoped CORS policy using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.cors is On. Without it, the route's labels create an inline policy; the reference cannot be mixed with inline CORS fields. |
clearplane.proxy.cors.preflight-maximum-age-seconds |
Integer | 0-86400 | 0 |
— | clearplane.proxy.cors.preflight-maximum-age-seconds |
Container label | Service resource | Public | Immediate | — | Preflight cache lifetime in seconds. |
clearplane.proxy.cors.upstream-header-mode |
CorsUpstreamHeaderMode | Override, Preserve | Override |
— | clearplane.proxy.cors.upstream-header-mode |
Container label | Service resource | Public | Immediate | — | Override replaces the proxied service's CORS headers with this policy's. Preserve forwards preflights and applies this policy only when the service returned no Access-Control-Allow-Origin, so it cannot deny an origin the service allows — the service's own headers win whenever it sends them. If the service does not answer OPTIONS, Preserve forwards the preflight and the service's 404/405 reaches the browser, failing every non-simple cross-origin request to that route. |
clearplane.proxy.enabled |
Boolean | — | false |
— | clearplane.proxy.enabled |
Container label | Service resource | Public | Immediate | — | Publish this container through Clearplane. |
clearplane.proxy.error-page.enabled |
Boolean | — | true |
— | clearplane.proxy.error-page.enabled |
Container label | Service resource | Public | Immediate | — | Replace selected error responses with Clearplane's branded HTML page for clients that accept HTML. |
clearplane.proxy.error-page.status-codes |
Whitespace list of integer values | HTTP status codes and inclusive ranges within 400-599; prefix exclusions with ! (for example, 400-599 !404) | 502 503 504 |
— | clearplane.proxy.error-page.status-codes |
Container label | Service resource | Public | Immediate | — | Error response status codes eligible for branded replacement. At least one inclusion is required, included codes and ranges cannot overlap, and exclusions must leave a non-empty result. |
clearplane.proxy.group.collapsed-by-default |
Boolean | — | false |
— | clearplane.proxy.group.collapsed-by-default |
Container label | Service resource | Public | Immediate | — | Collapse this resource group by default in route and cluster overviews. Ignored when group.name is absent. |
clearplane.proxy.group.name |
String | Trimmed non-blank name, up to 200 characters | — | — | clearplane.proxy.group.name |
Container label | Service resource | Public | Immediate | — | Optional resource group assigned to the generated route and cluster. The order and collapsed fields are ignored with a warning when this name label is absent. |
clearplane.proxy.group.order |
Integer | — | 0 |
— | clearplane.proxy.group.order |
Container label | Service resource | Public | Immediate | — | Resource group display order. Any signed integer is accepted and lower values appear first. Ignored when group.name is absent. |
clearplane.proxy.host |
String | Exact DNS host or single-label wildcard such as *.example.com, up to 253 characters without the *. prefix | — | — | clearplane.proxy.host |
Container label | Service resource | Public | Immediate | — | Required public host matched by the generated route. A wildcard such as '*.example.com' excludes its base domain; canonical host redirects require an exact host. |
clearplane.proxy.maximum-request-body-size-bytes |
Long integer (optional) | Positive integer | — | — | clearplane.proxy.maximum-request-body-size-bytes |
Container label | Service resource | Public | Immediate | — | Maximum request-body size in bytes for the generated route. Replaces Edge's global clearplane.edge.maximum-request-body-size-bytes for this route only, so it can raise or lower the limit; requests with a larger body receive 413. Omit it to use the global limit. |
clearplane.proxy.methods |
Whitespace list of string values | Unique HTTP method tokens | (empty) |
— | clearplane.proxy.methods |
Container label | Service resource | Public | Immediate | — | HTTP methods matched by the generated route. Values are normalized to uppercase; duplicates after normalization are rejected. Empty matches every method. |
clearplane.proxy.name |
String | Non-blank name within the generated resource limits | — | — | clearplane.proxy.name |
Container label | Service resource | Public | Immediate | — | Optional base name for the generated route, cluster, and inline access control, authentication, auto-ban, cache, compression, CORS, rate limit, request headers, response headers and WAF policies. Defaults to the container discovery key. The maximum depends on which generated resources are enabled, and an overlong name reports the exact applicable limit. |
clearplane.proxy.order |
Integer | Signed integer from -2147483638 to 2147483647 | 0 |
— | clearplane.proxy.order |
Container label | Service resource | Public | Immediate | — | Route match order. Lower values are evaluated first; the ten lowest signed integers are reserved for Clearplane management and guard routes. |
clearplane.proxy.path |
String | Non-empty complete route path pattern other than /_clearplane/challenge, up to 2000 characters | /{**catch-all} |
— | clearplane.proxy.path |
Container label | Service resource | Public | Immediate | — | Complete public path pattern matched by the generated route, using the same route-template syntax as the UI and REST API. Use '/api/{**catch-all}' to match /api and every path below it; use '/api' to match only that literal path. |
clearplane.proxy.path-rewrite |
String | Valid route path pattern, up to 500 characters | — | — | clearplane.proxy.path-rewrite |
Container label | Service resource | Public | Immediate | — | Optional ASP.NET route pattern written before forwarding to the upstream service. Relative and slash-prefixed patterns are accepted; empty or whitespace disables rewriting. |
clearplane.proxy.port |
Integer | 1-65535 | — | — | clearplane.proxy.port |
Container label | Service resource | Public | Immediate | — | Container port reached by Edge. |
clearplane.proxy.preserve-host-header |
Boolean | — | false |
— | clearplane.proxy.preserve-host-header |
Container label | Service resource | Public | Immediate | — | Forward the incoming Host header, including its port, to the upstream service. Enable for upstreams that validate the public hostname. Independent of X-Forwarded-Host. |
clearplane.proxy.rate-limit |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.rate-limit |
Container label | Service resource | Public | Immediate | — | Inherit the Global rate limit policies, turn on this proxy route's own rate limit policies, or turn the feature off for this route. |
clearplane.proxy.rate-limit.action |
RateLimitAction | Reject, Challenge | Reject |
— | clearplane.proxy.rate-limit.action |
Container label | Service resource | Public | Immediate | — | What the generated inline rate limit policy does when a client exceeds the limit. Reject returns 429. Challenge asks eligible browsers to complete proof of work and returns 429 to other clients; the route must enable bot challenges. |
clearplane.proxy.rate-limit.header-name |
String | Non-empty header name, up to 200 characters | — | — | clearplane.proxy.rate-limit.header-name |
Container label | Service resource | Public | Immediate | — | Required partition header when the generated rate limit policy key type is Header; otherwise it is optional and unused. |
clearplane.proxy.rate-limit.key-type |
RateLimitKeyType | Address, Path, Header | Address |
— | clearplane.proxy.rate-limit.key-type |
Container label | Service resource | Public | Immediate | — | Partition key for the generated inline rate limit policy. |
clearplane.proxy.rate-limit.policies |
Whitespace list of string values | Unique policy system names | — | — | clearplane.proxy.rate-limit.policies |
Container label | Service resource | Public | Immediate | — | Existing Route-scoped rate limit policies, each using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.rate-limit is On. Without it, the route's labels create an inline policy; references cannot be mixed with inline rate-limit fields. |
clearplane.proxy.rate-limit.request-limit |
Integer | Positive integer | 100 |
— | clearplane.proxy.rate-limit.request-limit |
Container label | Service resource | Public | Immediate | — | Requests permitted in each generated rate-limit window. |
clearplane.proxy.rate-limit.window-seconds |
Integer | Positive integer | 60 |
— | clearplane.proxy.rate-limit.window-seconds |
Container label | Service resource | Public | Immediate | — | Window length in seconds for the generated rate limit policy. |
clearplane.proxy.redirect.http-to-https |
Boolean (optional) | — | — | — | clearplane.proxy.redirect.http-to-https |
Container label | Service resource | Public | Immediate | — | Redirect HTTP requests to HTTPS after the canonical host certificate is ready. Defaults to certificate.enabled. |
clearplane.proxy.redirect.source-hosts |
Whitespace list of string values | Case-insensitively unique exact DNS hosts, each up to 253 characters | (empty) |
— | clearplane.proxy.redirect.source-hosts |
Container label | Service resource | Public | Immediate | — | Exact source hosts redirected to the route host. The primary route host must be exact rather than wildcard, and these sources must differ from it and not overlap any additional forwarding host. |
clearplane.proxy.redirect.status-code |
RedirectStatusCode | 301, 302, 307, 308 | 308 |
— | clearplane.proxy.redirect.status-code |
Container label | Service resource | Public | Immediate | — | Status code used by host and scheme redirects on this route. |
clearplane.proxy.request-headers |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.request-headers |
Container label | Service resource | Public | Immediate | — | Inherit the Global request headers policy, turn on this proxy route's own request headers policy, or turn the feature off for this route. |
clearplane.proxy.request-headers.forward-x-forwarded-for |
Boolean | — | true |
— | clearplane.proxy.request-headers.forward-x-forwarded-for |
Container label | Service resource | Public | Immediate | — | Forward X-Forwarded-For in the generated inline policy. |
clearplane.proxy.request-headers.forward-x-forwarded-host |
Boolean | — | true |
— | clearplane.proxy.request-headers.forward-x-forwarded-host |
Container label | Service resource | Public | Immediate | — | Forward X-Forwarded-Host in the generated inline policy. |
clearplane.proxy.request-headers.forward-x-forwarded-proto |
Boolean | — | true |
— | clearplane.proxy.request-headers.forward-x-forwarded-proto |
Container label | Service resource | Public | Immediate | — | Forward X-Forwarded-Proto in the generated inline policy. |
clearplane.proxy.request-headers.forward-x-real-ip |
Boolean | — | true |
— | clearplane.proxy.request-headers.forward-x-real-ip |
Container label | Service resource | Public | Immediate | — | Forward X-Real-IP in the generated inline policy. |
clearplane.proxy.request-headers.forward-x-request-id |
Boolean | — | true |
— | clearplane.proxy.request-headers.forward-x-request-id |
Container label | Service resource | Public | Immediate | — | Send Edge's request ID upstream as X-Request-ID in the generated inline policy, replacing any client value. Off removes the header. |
clearplane.proxy.request-headers.policy |
String | One policy system name | — | — | clearplane.proxy.request-headers.policy |
Container label | Service resource | Public | Immediate | — | One existing Route-scoped request headers policy using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.request-headers is On. Without it, the route's labels create an inline policy; the reference cannot be mixed with inline request-header fields. |
clearplane.proxy.response-headers |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.response-headers |
Container label | Service resource | Public | Immediate | — | Inherit the Global response headers policy, turn on this proxy route's own response headers policy, or turn the feature off for this route. |
clearplane.proxy.response-headers.content-security-policy |
String | Value without CR or LF, up to 4000 characters; or empty | (empty) |
— | clearplane.proxy.response-headers.content-security-policy |
Container label | Service resource | Public | Immediate | — | Content-Security-Policy value for the generated inline policy. Empty keeps the upstream service's own header. |
clearplane.proxy.response-headers.permissions-policy |
String | Value without CR or LF, up to 2000 characters; or empty | camera=(), microphone=(), geolocation=() |
— | clearplane.proxy.response-headers.permissions-policy |
Container label | Service resource | Public | Immediate | — | Permissions-Policy value for the generated inline policy. Empty leaves the header unset. |
clearplane.proxy.response-headers.policy |
String | One policy system name | — | — | clearplane.proxy.response-headers.policy |
Container label | Service resource | Public | Immediate | — | One existing Route-scoped response headers policy using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.response-headers is On. Without it, the route's labels create an inline policy; the reference cannot be mixed with inline response-header fields. |
clearplane.proxy.response-headers.referrer-policy |
String | no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, same-origin, strict-origin, strict-origin-when-cross-origin, unsafe-url, or empty | strict-origin-when-cross-origin |
— | clearplane.proxy.response-headers.referrer-policy |
Container label | Service resource | Public | Immediate | — | Referrer-Policy value for the generated inline policy, up to 200 characters. Empty leaves the header unset. |
clearplane.proxy.response-headers.remove-server-header |
Boolean | — | true |
— | clearplane.proxy.response-headers.remove-server-header |
Container label | Service resource | Public | Immediate | — | Remove the Server response header in the generated inline policy. |
clearplane.proxy.response-headers.remove-x-aspnet-version-header |
Boolean | — | true |
— | clearplane.proxy.response-headers.remove-x-aspnet-version-header |
Container label | Service resource | Public | Immediate | — | Remove the X-AspNet-Version response header in the generated inline policy. |
clearplane.proxy.response-headers.remove-x-powered-by-header |
Boolean | — | true |
— | clearplane.proxy.response-headers.remove-x-powered-by-header |
Container label | Service resource | Public | Immediate | — | Remove the X-Powered-By response header in the generated inline policy. |
clearplane.proxy.response-headers.strict-transport-security |
String | One numeric max-age plus optional unique includeSubDomains and preload directives, up to 4000 characters; or empty | max-age=31536000; includeSubDomains |
— | clearplane.proxy.response-headers.strict-transport-security |
Container label | Service resource | Public | Immediate | — | Strict-Transport-Security value for the generated inline policy. Directives are semicolon-delimited, CR/LF is forbidden, and empty leaves the header unset. |
clearplane.proxy.response-headers.x-content-type-options-no-sniff |
Boolean | — | true |
— | clearplane.proxy.response-headers.x-content-type-options-no-sniff |
Container label | Service resource | Public | Immediate | — | Set X-Content-Type-Options to nosniff in the generated inline policy. |
clearplane.proxy.response-headers.x-frame-options |
String | DENY, SAMEORIGIN, or empty | DENY |
— | clearplane.proxy.response-headers.x-frame-options |
Container label | Service resource | Public | Immediate | — | X-Frame-Options value for the generated inline policy. Empty leaves the header unset. |
clearplane.proxy.strip-prefix |
String | Path prefix beginning with /, up to 500 characters | — | — | clearplane.proxy.strip-prefix |
Container label | Service resource | Public | Immediate | — | Optional path prefix removed before forwarding to the upstream service. Empty or whitespace disables stripping. |
clearplane.proxy.upstream.activity-timeout-seconds |
Integer (optional) | 1-86400 | 60 |
— | clearplane.proxy.upstream.activity-timeout-seconds |
Container label | Service resource | Public | Immediate | — | Maximum upstream inactivity in seconds while sending the request or reading the response. Resets whenever data moves. |
clearplane.proxy.upstream.protocol |
UpstreamProtocol | Auto, Http2 | Auto |
— | clearplane.proxy.upstream.protocol |
Container label | Service resource | Public | Immediate | — | Protocol Edge uses to reach the upstream. Http2 forces HTTP/2 exactly, including prior-knowledge h2c to plain-HTTP upstreams, as gRPC requires; Auto negotiates. |
clearplane.proxy.waf |
PolicyState | Inherit, On, Off | Inherit |
— | clearplane.proxy.waf |
Container label | Service resource | Public | Immediate | — | Inherit the Global WAF policy, turn on this proxy route's own WAF policy, or turn the feature off for this route. |
clearplane.proxy.waf.additional-allowed-methods |
Whitespace list of string values | Up to 32 unique uppercase HTTP method names, each up to 32 characters | (empty) |
— | clearplane.proxy.waf.additional-allowed-methods |
Container label | Service resource | Public | Immediate | — | Methods the route's inline policy allows in addition to the WAF rulesets' defaults (GET, HEAD, POST, OPTIONS, PUT, PATCH, DELETE), such as PROPFIND MKCOL. Values start with A-Z and then use A-Z, digits, underscore or dash. |
clearplane.proxy.waf.additional-allowed-request-content-types |
Whitespace list of string values | Up to 32 unique lowercase media types without parameters, each up to 255 characters | (empty) |
— | clearplane.proxy.waf.additional-allowed-request-content-types |
Container label | Service resource | Public | Immediate | — | Request body media types the route's inline policy allows in addition to the WAF rulesets' defaults, such as text/plain. Bodies are still inspected as raw text. |
clearplane.proxy.waf.challenge.clearance-seconds |
Integer | 300-86400 | 1800 |
— | clearplane.proxy.waf.challenge.clearance-seconds |
Container label | Service resource | Public | Immediate | — | How long a passed challenge lasts, in seconds. |
clearplane.proxy.waf.challenge.difficulty |
Integer | 12-24 | 18 |
— | clearplane.proxy.waf.challenge.difficulty |
Container label | Service resource | Public | Immediate | — | Proof-of-work difficulty in leading zero bits. |
clearplane.proxy.waf.challenge.mode |
WafChallengeMode | Off, ProofOfWork | Off |
— | clearplane.proxy.waf.challenge.mode |
Container label | Service resource | Public | Immediate | — | Serve proof-of-work bot challenges on the route. Requires Prevention; routes without redirect.http-to-https never challenge. Eligible browser requests can be challenged by WAF rules, Combined scores or Challenge rate limits. |
clearplane.proxy.waf.challenge.threshold |
Integer | 1 to clearplane.proxy.waf.threshold minus 1 | 3 |
— | clearplane.proxy.waf.challenge.threshold |
Container label | Service resource | Public | Immediate | — | Combined blocking score at which an eligible browser is challenged. Must stay below clearplane.proxy.waf.threshold, the score at which the request is blocked. |
clearplane.proxy.waf.detection-paranoia-level |
Integer (optional) | paranoia-level to 4, or empty | — | — | clearplane.proxy.waf.detection-paranoia-level |
Container label | Service resource | Public | Immediate | — | Rules above the blocking paranoia level, up to and including this level, score in Detection only. It may equal the blocking level; empty disables the additional detection-only band. |
clearplane.proxy.waf.disabled-rulesets |
Whitespace list of string values | Up to 256 unique ruleset IDs, each up to 200 characters | (empty) |
— | clearplane.proxy.waf.disabled-rulesets |
Container label | Service resource | Public | Immediate | — | Active WAF rulesets the route's inline policy does not use. IDs start with a lowercase letter or digit and then contain lowercase letters, digits, dots or dashes. |
clearplane.proxy.waf.exclusion-rulesets |
Whitespace list of string values | Up to 256 unique ruleset IDs, each up to 200 characters | (empty) |
— | clearplane.proxy.waf.exclusion-rulesets |
Container label | Service resource | Public | Immediate | — | Exclusion rulesets the route's inline policy opts into. IDs start with a lowercase letter or digit and then contain lowercase letters, digits, dots or dashes. Exclusion rulesets never apply without opting in. |
clearplane.proxy.waf.grpc.message-inspection-limit-bytes |
Integer | 1024-16777216 | 4194304 |
— | clearplane.proxy.waf.grpc.message-inspection-limit-bytes |
Container label | Service resource | Public | Immediate | — | Largest gRPC message the route's inline policy inspects. |
clearplane.proxy.waf.grpc.stream-inspection-limit-messages |
Integer | 1-1024 | 16 |
— | clearplane.proxy.waf.grpc.stream-inspection-limit-messages |
Container label | Service resource | Public | Immediate | — | gRPC messages inspected per stream by the route's inline policy. |
clearplane.proxy.waf.mode |
WafMode | Detection, Prevention | Detection |
— | clearplane.proxy.waf.mode |
Container label | Service resource | Public | Immediate | — | WAF mode of the route's inline policy. Detection records findings without blocking; Prevention blocks when the policy reaches its blocking decision. |
clearplane.proxy.waf.paranoia-level |
Integer | 1-4 | 1 |
— | clearplane.proxy.waf.paranoia-level |
Container label | Service resource | Public | Immediate | — | Paranoia level. Rules at or below this level can block. |
clearplane.proxy.waf.policy |
String | One policy system name | — | — | clearplane.proxy.waf.policy |
Container label | Service resource | Public | Immediate | — | One existing Route-scoped WAF policy using lowercase letters, digits, and single dashes between words with a 200-character maximum. Used only when clearplane.proxy.waf is On. Without it, the route's labels create an inline policy; the reference cannot be mixed with inline WAF fields. |
clearplane.proxy.waf.profile |
WafProfile | Standard, Management | Standard |
— | clearplane.proxy.waf.profile |
Container label | Service resource | Public | Immediate | — | WAF profile of the route's inline policy. |
clearplane.proxy.waf.request-body.inspection-limit-bytes |
Long integer (optional) | 1-104857600 | — | — | clearplane.proxy.waf.request-body.inspection-limit-bytes |
Container label | Service resource | Public | Immediate | — | Request body bytes the route's inline policy inspects. Defaults to 1048576, or 262144 with the Management profile. With Block, active ruleset profiles can lower this limit. |
clearplane.proxy.waf.request-body.inspection-mode |
WafBodyInspectionMode | MetadataOnly, MemoryBuffered, DiskSpool | MemoryBuffered |
— | clearplane.proxy.waf.request-body.inspection-mode |
Container label | Service resource | Public | Immediate | — | How the route's inline policy reads ordinary request bodies. MetadataOnly skips them; MemoryBuffered buffers up to request-body.inspection-limit-bytes; DiskSpool spools larger bodies to disk. WebSocket and gRPC use their own limits. |
clearplane.proxy.waf.request-body.oversize-action |
WafOversizeBodyAction | Block, InspectPrefix | Block |
— | clearplane.proxy.waf.request-body.oversize-action |
Container label | Service resource | Public | Immediate | — | What happens to a request body above the inspection limit. Block rejects it in Prevention; InspectPrefix inspects its first bytes, and with disk spooling its raw content up to request-body.spooled-inspection-limit-bytes, then forwards it. |
clearplane.proxy.waf.request-body.spooled-inspection-limit-bytes |
Long integer | request-body.inspection-limit-bytes to 1073741824 | 104857600 |
— | clearplane.proxy.waf.request-body.spooled-inspection-limit-bytes |
Container label | Service resource | Public | Immediate | — | Raw request body bytes inspected from disk under DiskSpool with InspectPrefix. |
clearplane.proxy.waf.request-context.capture-enabled |
Boolean | — | true |
— | clearplane.proxy.waf.request-context.capture-enabled |
Container label | Service resource | Public | Immediate | — | Record the redacted query string, request headers and matched values of the route's WAF detections. System → Settings → Firewall defines what is redacted and can turn capture off everywhere. |
clearplane.proxy.waf.request-context.header-capture-mode |
WafHeaderCaptureMode | Allowlist, RedactSensitive | Allowlist |
— | clearplane.proxy.waf.request-context.header-capture-mode |
Container label | Service resource | Public | Immediate | — | Which request header values a detection records. Allowlist records only the values of the headers listed under System → Settings → Firewall and redacts the rest; RedactSensitive records every value except the sensitive headers listed there. |
clearplane.proxy.waf.response.body-inspection-limit-bytes |
Integer | 1024-16777216 | 1048576 |
— | clearplane.proxy.waf.response.body-inspection-limit-bytes |
Container label | Service resource | Public | Immediate | — | Response body bytes buffered for inspection under HeadersAndBody. |
clearplane.proxy.waf.response.inspection-mode |
WafResponseInspectionMode | Off, Headers, HeadersAndBody | Off |
— | clearplane.proxy.waf.response.inspection-mode |
Container label | Service resource | Public | Immediate | — | Inspect upstream responses under the route's inline policy. Headers inspects status and headers before any byte is sent; HeadersAndBody also buffers text, JSON, XML and JavaScript bodies up to response.body-inspection-limit-bytes, which adds latency. Streaming responses are never held. |
clearplane.proxy.waf.response.threshold |
Integer | 1-100 | 4 |
— | clearplane.proxy.waf.response.threshold |
Container label | Service resource | Public | Immediate | — | Response blocking score at which the route's inline policy blocks in Prevention. |
clearplane.proxy.waf.scoring-mode |
WafScoringMode | Combined, PerRuleset | Combined |
— | clearplane.proxy.waf.scoring-mode |
Container label | Service resource | Public | Immediate | — | Scoring mode of the route's inline policy. Combined adds the Prevention rulesets' scores against one threshold; PerRuleset gives each ruleset its own threshold. |
clearplane.proxy.waf.threshold |
Integer | 5-100 | 5 |
— | clearplane.proxy.waf.threshold |
Container label | Service resource | Public | Immediate | — | Combined blocking score at which the route's inline policy blocks in Prevention. |
clearplane.proxy.waf.websocket.inspection-enabled |
Boolean | — | true |
— | clearplane.proxy.waf.websocket.inspection-enabled |
Container label | Service resource | Public | Immediate | — | Inspect client-to-server WebSocket messages under the route's inline policy. Each message is scored on its own; in Prevention a blocking message closes the connection with status 1008. |
clearplane.proxy.waf.websocket.message-inspection-limit-bytes |
Integer | 1024-16777216 | 1048576 |
— | clearplane.proxy.waf.websocket.message-inspection-limit-bytes |
Container label | Service resource | Public | Immediate | — | Largest WebSocket message the route's inline policy inspects. |
clearplane.proxy.authentication.basic.credentials.<index>.password |
String | Non-empty string, up to 400 characters | — | — | clearplane.proxy.authentication.basic.credentials.<index>.password |
Container label | Service resource | Secret | Immediate | — | Required plaintext credential password. Clearplane hashes the value before persistence. |
clearplane.proxy.authentication.basic.credentials.<index>.user-name |
String | Non-empty string, up to 200 characters | — | — | clearplane.proxy.authentication.basic.credentials.<index>.user-name |
Container label | Service resource | Public | Immediate | — | Required credential username. Usernames must be unique across the indexed entries. |
clearplane.proxy.authentication.jwt.required-claims.<index>.claim |
String | Non-empty string, up to 200 characters | — | — | clearplane.proxy.authentication.jwt.required-claims.<index>.claim |
Container label | Service resource | Public | Immediate | — | JWT claim name required on accepted tokens. A claim/value pair cannot duplicate an earlier entry. |
clearplane.proxy.authentication.jwt.required-claims.<index>.value |
String | Non-empty string, up to 200 characters | — | — | clearplane.proxy.authentication.jwt.required-claims.<index>.value |
Container label | Service resource | Public | Immediate | — | Required value for the indexed JWT claim. A claim/value pair cannot duplicate an earlier entry. |
clearplane.proxy.authentication.jwt.signing-keys.<index>.material |
String | Symmetric secret of 32-8192 characters or valid RSA/EC public-key PEM up to 8192 characters | — | — | clearplane.proxy.authentication.jwt.signing-keys.<index>.material |
Container label | Service resource | Secret | Immediate | — | Required JWT signing-key material valid for the indexed type. Symmetric values are encrypted before persistence. |
clearplane.proxy.authentication.jwt.signing-keys.<index>.type |
JwtKeyType | Symmetric, RsaPublic, EcPublic | — | — | clearplane.proxy.authentication.jwt.signing-keys.<index>.type |
Container label | Service resource | Public | Immediate | — | JWT signing-key type. |
clearplane.proxy.request-headers.entries.<index>.action |
HeaderTransformAction | Set, Append, Remove | — | — | clearplane.proxy.request-headers.entries.<index>.action |
Container label | Service resource | Public | Immediate | — | Transformation action for the indexed request header entry. |
clearplane.proxy.request-headers.entries.<index>.header-name |
String | Valid non-reserved HTTP header name, up to 200 characters | — | — | clearplane.proxy.request-headers.entries.<index>.header-name |
Container label | Service resource | Public | Immediate | — | Required request header transformed by the indexed entry. |
clearplane.proxy.request-headers.entries.<index>.value |
String | Header value without CR or LF, up to 4000 characters | — | — | clearplane.proxy.request-headers.entries.<index>.value |
Container label | Service resource | Public | Immediate | — | Value required by Set or Append and forbidden by Remove. |
clearplane.proxy.response-headers.entries.<index>.action |
HeaderTransformAction | Set, Append, Remove | — | — | clearplane.proxy.response-headers.entries.<index>.action |
Container label | Service resource | Public | Immediate | — | Transformation action for the indexed response header entry. |
clearplane.proxy.response-headers.entries.<index>.condition |
ResponseHeaderCondition | Always, Success, Failure | Always |
— | clearplane.proxy.response-headers.entries.<index>.condition |
Container label | Service resource | Public | Immediate | — | Response condition for the indexed entry. |
clearplane.proxy.response-headers.entries.<index>.header-name |
String | Valid non-reserved HTTP header name, up to 200 characters | — | — | clearplane.proxy.response-headers.entries.<index>.header-name |
Container label | Service resource | Public | Immediate | — | Required response header transformed by the indexed entry. |
clearplane.proxy.response-headers.entries.<index>.value |
String | Header value without CR or LF, up to 4000 characters | — | — | clearplane.proxy.response-headers.entries.<index>.value |
Container label | Service resource | Public | Immediate | — | Value required by Set or Append and forbidden by Remove. |
Redirect directives
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|---|---|---|---|---|---|---|---|---|---|---|
clearplane.redirect.additional-source-hosts |
Whitespace list of string values | Unique exact DNS hosts, each up to 253 characters | (empty) |
— | clearplane.redirect.additional-source-hosts |
Container label | Service resource | Public | Immediate | — | Additional public hosts matched by the generated redirect route. Values are normalized to lowercase and must not repeat the primary source host. |
clearplane.redirect.certificate.additional-domains |
Whitespace list of string values | Unique exact DNS hosts or single-label wildcards such as *.example.com, each up to 253 characters without the *. prefix | (empty) |
— | clearplane.redirect.certificate.additional-domains |
Container label | Service resource | Public | Immediate | — | Extra certificate domains beyond the redirect's source hosts. The final certificate may have at most 99 subject alternative names. Wildcards require a DNS profile or inline credentials. |
clearplane.redirect.certificate.dns.api-token |
String | Non-empty single-line value, up to 4096 characters | — | — | clearplane.redirect.certificate.dns.api-token |
Container label | Service resource | Secret | Immediate | — | Required whenever any inline DNS field is present. Core encrypts the token before persistence. Inline DNS fields cannot be combined with dns.profile-name. |
clearplane.redirect.certificate.dns.profile-name |
String | Trimmed non-empty profile name, up to 200 characters | — | — | clearplane.redirect.certificate.dns.profile-name |
Container label | Service resource | Public | Immediate | — | Named DNS profile used for DNS-01 validation. Cannot be combined with the dns.provider, dns.api-token, or dns.propagation-seconds fields. Without either form of DNS configuration, HTTP-01 is used. |
clearplane.redirect.certificate.dns.propagation-seconds |
Integer (optional) | 1-3600, or empty for the provider default | — | — | clearplane.redirect.certificate.dns.propagation-seconds |
Container label | Service resource | Public | Immediate | — | Optional propagation delay in seconds for this route's inline DNS credentials. Requires dns.api-token. |
clearplane.redirect.certificate.dns.provider |
AcmeDnsProvider | Cloudflare | Cloudflare |
— | clearplane.redirect.certificate.dns.provider |
Container label | Service resource | Public | Immediate | — | Provider for this route's inline DNS credentials. Requires dns.api-token and cannot be combined with the dns.profile-name field. |
clearplane.redirect.certificate.domain |
String | Exact DNS host, up to 253 characters | — | — | clearplane.redirect.certificate.domain |
Container label | Service resource | Public | Immediate | — | Primary certificate domain. Defaults to the redirect source host and must not be covered by a requested wildcard. |
clearplane.redirect.certificate.enabled |
Boolean | — | false |
— | clearplane.redirect.certificate.enabled |
Container label | Service resource | Public | Immediate | — | Request and renew an ACME certificate for this redirect. |
clearplane.redirect.certificate.wildcard |
Boolean | — | false |
— | clearplane.redirect.certificate.wildcard |
Container label | Service resource | Public | Immediate | — | Include a one-label wildcard for the primary certificate domain. Enabling it requires a named DNS profile or inline DNS credentials. |
clearplane.redirect.enabled |
Boolean | — | false |
— | clearplane.redirect.enabled |
Container label | Service resource | Public | Immediate | — | Publish a standalone external redirect from this container. |
clearplane.redirect.group.collapsed-by-default |
Boolean | — | false |
— | clearplane.redirect.group.collapsed-by-default |
Container label | Service resource | Public | Immediate | — | Collapse this resource group by default in redirect overviews. Ignored when group.name is absent. |
clearplane.redirect.group.name |
String | Trimmed non-blank name, up to 200 characters | — | — | clearplane.redirect.group.name |
Container label | Service resource | Public | Immediate | — | Optional resource group assigned to the generated redirect route. The order and collapsed fields are ignored with a warning when this name label is absent. |
clearplane.redirect.group.order |
Integer | — | 0 |
— | clearplane.redirect.group.order |
Container label | Service resource | Public | Immediate | — | Resource group display order. Any signed integer is accepted and lower values appear first. Ignored when group.name is absent. |
clearplane.redirect.methods |
Whitespace list of string values | Unique HTTP method tokens | (empty) |
— | clearplane.redirect.methods |
Container label | Service resource | Public | Immediate | — | Optional HTTP methods matched by the generated redirect route. Values are normalized to uppercase; duplicates after normalization are rejected. Empty matches every method. |
clearplane.redirect.name |
String | Non-blank name, up to 200 characters; up to 191 with inline DNS credentials | — | — | clearplane.redirect.name |
Container label | Service resource | Public | Immediate | — | Optional name for the generated redirect route. Defaults to the container discovery key. Inline DNS credentials append '-acme-dns' to create a DNS profile name, reducing the maximum base name to 191 characters. |
clearplane.redirect.order |
Integer | Signed integer from -2147483638 to 2147483647 | 0 |
— | clearplane.redirect.order |
Container label | Service resource | Public | Immediate | — | Route match order. Lower values are evaluated first; the ten lowest signed integers are reserved for Clearplane management and guard routes. |
clearplane.redirect.path |
String | Non-empty complete route path pattern, up to 2000 characters | /{**catch-all} |
— | clearplane.redirect.path |
Container label | Service resource | Public | Immediate | — | Complete public path pattern matched by the generated redirect route, using the same route-template syntax as the UI and REST API. Use '/api/{**catch-all}' to match /api and every path below it; use '/api' to match only that literal path. |
clearplane.redirect.preserve-path-and-query |
Boolean | — | false |
— | clearplane.redirect.preserve-path-and-query |
Container label | Service resource | Public | Immediate | — | Append the matched request path and query string to the target URI. |
clearplane.redirect.source-host |
String | Exact DNS host, up to 253 characters | — | — | clearplane.redirect.source-host |
Container label | Service resource | Public | Immediate | — | Required primary public host matched by the generated redirect route. Schemes, ports, paths, wildcards and IP literals are rejected. |
clearplane.redirect.status-code |
RedirectStatusCode | 301, 302, 307, 308 | 308 |
— | clearplane.redirect.status-code |
Container label | Service resource | Public | Immediate | — | HTTP status code returned by the redirect. |
clearplane.redirect.target-uri |
String | Absolute HTTP/HTTPS URI, up to 2000 characters | — | — | clearplane.redirect.target-uri |
Container label | Service resource | Public | Immediate | — | Required redirect target. User information, fragments, control characters, backslashes, and a target that loops to a source host are rejected; preserving the path also restricts the target path and query shape. |
Development-only settings
These bootstrap settings exist for running a service outside its published container, in local development and tests. Production deployments leave them unset: the built-in defaults match the published images, and changing a container path, internal address or listen port there breaks health checks and internal connections. Generated secrets accept a direct value only in Development.
| Directive | Type | Accepted values | Built-in default | Environment variable | Docker label | Sources | Lifecycle | Sensitivity | Apply | UI location | Description |
|---|---|---|---|---|---|---|---|---|---|---|---|
clearplane.container-proxy.bootstrap.data-path |
String | — | /app/data |
CLEARPLANE_CONTAINER_PROXY_BOOTSTRAP_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Read-only persistent ContainerProxy data directory. |
clearplane.container-proxy.bootstrap.logs-path |
String | — | /app/logs |
CLEARPLANE_CONTAINER_PROXY_BOOTSTRAP_LOGS_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Base directory for ContainerProxy logs. |
clearplane.container-proxy.bootstrap.socket-path |
String | — | /var/run/docker.sock |
CLEARPLANE_CONTAINER_PROXY_BOOTSTRAP_SOCKET_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Container-runtime Unix socket path inside the ContainerProxy container. The shipped Compose file mounts the host's Docker socket here; for another local socket, change the host side of that mount. |
clearplane.core.bootstrap.analytics-path |
String | — | /app/analytics |
CLEARPLANE_CORE_BOOTSTRAP_ANALYTICS_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Persistent Core analytics data directory. |
clearplane.core.bootstrap.cloud-uri |
String | Absolute HTTPS base URI with path / or /api/ | https://cloud.clearplane.net/api/ |
CLEARPLANE_CORE_BOOTSTRAP_CLOUD_URI |
— | Environment | Bootstrap | Public | Restart required | — | Clearplane Cloud API base URI. Used only when Cloud integration is enabled. Credentials, queries and fragments are rejected. |
clearplane.core.bootstrap.container-proxy-data-path |
String | — | /app/container-proxy-data |
CLEARPLANE_CORE_BOOTSTRAP_CONTAINER_PROXY_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Persistent data directory published to ContainerProxy. |
clearplane.core.bootstrap.container-proxy-uri |
String | Absolute HTTPS origin | https://clearplane-container-proxy:8443 |
CLEARPLANE_CORE_BOOTSTRAP_CONTAINER_PROXY_URI |
— | Environment | Bootstrap | Public | Restart required | — | Internal ContainerProxy origin. Credentials, paths, queries and fragments are rejected. |
clearplane.core.bootstrap.data-path |
String | — | /app/data |
CLEARPLANE_CORE_BOOTSTRAP_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Persistent Core data directory. |
clearplane.core.bootstrap.edge-data-path |
String | — | /app/edge-data |
CLEARPLANE_CORE_BOOTSTRAP_EDGE_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Persistent data directory published to Edge. |
clearplane.core.bootstrap.logs-path |
String | — | /app/logs |
CLEARPLANE_CORE_BOOTSTRAP_LOGS_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Base directory for Core logs. |
clearplane.core.bootstrap.session-jwt-audience |
String | — | clearplane |
CLEARPLANE_CORE_BOOTSTRAP_SESSION_JWT_AUDIENCE |
— | Environment | Bootstrap | Public | Restart required | — | JWT audience written to and accepted from Core session tokens. |
clearplane.core.bootstrap.session-jwt-issuer |
String | — | clearplane |
CLEARPLANE_CORE_BOOTSTRAP_SESSION_JWT_ISSUER |
— | Environment | Bootstrap | Public | Restart required | — | JWT issuer written to and accepted from Core session tokens. |
clearplane.core.bootstrap.session-jwt-signing-key |
String | — | (redacted) | CLEARPLANE_CORE_BOOTSTRAP_SESSION_JWT_SIGNING_KEY |
— | Environment | Bootstrap | Secret | Restart required | — | Signing key for Core session tokens. Core generates it in its data volume and reads it from there; a direct value is accepted only in Development. |
clearplane.core.bootstrap.stored-certificate-password |
String | — | (empty) |
CLEARPLANE_CORE_BOOTSTRAP_STORED_CERTIFICATE_PASSWORD |
— | Environment | Bootstrap | Secret | Restart required | — | Password protecting stored certificates. Core generates it in the Edge data volume and reads it from there; a direct value is accepted only in Development. |
clearplane.core.bootstrap.ui-data-path |
String | — | /app/ui-data |
CLEARPLANE_CORE_BOOTSTRAP_UI_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Persistent data directory published to UI. |
clearplane.core.bootstrap.ui-uri |
String | Absolute HTTPS origin | https://clearplane-ui:8443 |
CLEARPLANE_CORE_BOOTSTRAP_UI_URI |
— | Environment | Bootstrap | Public | Restart required | — | Internal UI origin. Credentials, paths, queries and fragments are rejected. |
clearplane.edge.bootstrap.cache-path |
String | — | /app/cache |
CLEARPLANE_EDGE_BOOTSTRAP_CACHE_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Persistent response-cache directory. |
clearplane.edge.bootstrap.challenge-clearance-key |
String | Canonical 43-character base64url encoding of 32 bytes, or empty to disable issuance | (empty) |
CLEARPLANE_EDGE_BOOTSTRAP_CHALLENGE_CLEARANCE_KEY |
— | Environment | Bootstrap | Secret | Restart required | — | Machine key for bot-challenge tokens and clearance cookies. Core generates it in the Edge data volume and Edge reads it once at startup; empty disables issuance, while malformed material stops Edge at startup. A direct value is accepted only in Development. |
clearplane.edge.bootstrap.core-uri |
String | Absolute HTTPS origin | https://clearplane-core:8443 |
CLEARPLANE_EDGE_BOOTSTRAP_CORE_URI |
— | Environment | Bootstrap | Public | Restart required | — | Internal Core HTTPS origin used for the mutually authenticated control-plane connection. Credentials, paths, queries and fragments are rejected. |
clearplane.edge.bootstrap.data-path |
String | — | /app/data |
CLEARPLANE_EDGE_BOOTSTRAP_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Read-only shared data directory. |
clearplane.edge.bootstrap.http-port |
Integer | 1-65535 | 8080 |
CLEARPLANE_EDGE_BOOTSTRAP_HTTP_PORT |
— | Environment | Bootstrap | Public | Restart required | — | HTTP listen port inside the Edge container. |
clearplane.edge.bootstrap.https-port |
Integer | 1-65535 | 8443 |
CLEARPLANE_EDGE_BOOTSTRAP_HTTPS_PORT |
— | Environment | Bootstrap | Public | Restart required | — | HTTPS listen port inside the Edge container. |
clearplane.edge.bootstrap.instance-id |
String | — | (empty) |
CLEARPLANE_EDGE_BOOTSTRAP_INSTANCE_ID |
— | Environment | Bootstrap | Public | Restart required | — | Stable Edge instance identifier; defaults to the machine name when empty. |
clearplane.edge.bootstrap.logs-path |
String | — | /app/logs |
CLEARPLANE_EDGE_BOOTSTRAP_LOGS_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Base directory for Edge logs. |
clearplane.edge.bootstrap.stored-certificate-password |
String | — | (empty) |
CLEARPLANE_EDGE_BOOTSTRAP_STORED_CERTIFICATE_PASSWORD |
— | Environment | Bootstrap | Secret | Restart required | — | Password used to read stored certificates. Core generates it in the Edge data volume and Edge reads it from there; a direct value is accepted only in Development. |
clearplane.ui.bootstrap.data-path |
String | — | /app/data |
CLEARPLANE_UI_BOOTSTRAP_DATA_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Read-only persistent UI data directory. |
clearplane.ui.bootstrap.logs-path |
String | — | /app/logs |
CLEARPLANE_UI_BOOTSTRAP_LOGS_PATH |
— | Environment | Bootstrap | Public | Restart required | — | Base directory for UI logs. |
clearplane.ui.bootstrap.public-core-uri |
String | Empty or absolute HTTP/HTTPS origin | (empty) |
CLEARPLANE_UI_BOOTSTRAP_PUBLIC_CORE_URI |
— | Environment | Bootstrap | Public | Restart required | — | Public Core origin for split-port development; empty uses the browser origin. Credentials, paths, queries and fragments are rejected. |
Compose-only and framework settings
These values are outside Clearplane's typed application catalog because Docker Compose or ASP.NET Core consumes them before Clearplane configuration binding. Set Compose inputs in the invoking shell, a sibling .env file, or a file passed with --env-file.
| Key | Consumer | Default | Purpose |
|---|---|---|---|
COMPOSE_PROJECT_NAME |
Docker Compose | clearplane |
Compose project name. Core reads the project from its own container to verify first-party container ownership. |
CLEARPLANE_IMAGE_TAG |
Docker Compose | the release version | Image tag for all four services. This does not provide database rollback. |
ASPNETCORE_ENVIRONMENT |
ASP.NET Core host | Production |
Selects the hosting environment. Clearplane permits development-only credentials and relaxed local behavior only in Development. |
Clearplane UI and API proxy routes
Core and UI are ordinary discovered services. The shipped Compose file gives both containers one YAML anchor, x-clearplane-management-labels, with ordinary route policy labels: access control that blocks every address not listed in clearplane.proxy.access-control.allowed-addresses, a 600-request rate limit, automatic bans, request and response headers with the management Content-Security-Policy, the WAF in Detection with the Management profile, branded 403/502/503/504 error pages, and caching off. Each route owns its inline policies, placed in the System resource group.
The routes ship disabled and allow no address. Enable them, set the public host and allow your administrator addresses on both services, in the Compose file itself or an override:
services:
clearplane-core:
labels:
clearplane.proxy.enabled: "true"
clearplane.proxy.host: "waf.example.com"
clearplane.proxy.access-control.allowed-addresses: "203.0.113.10/32"
clearplane-ui:
labels:
clearplane.proxy.enabled: "true"
clearplane.proxy.host: "waf.example.com"
clearplane.proxy.access-control.allowed-addresses: "203.0.113.10/32"
Change any management policy by overriding its label on both containers; these are secure defaults, not immutable behavior.
Examples
Core configuration
Runtime Core settings use validated labels on the Core container or the UI. The MaxMind license key is the only runtime setting that also accepts an environment variable and _FILE twin:
services:
clearplane-core:
environment:
CLEARPLANE_CORE_GEO_IP_LICENSE_KEY: "replace-with-your-key"
The non-secret MaxMind settings can be labels on the Core container:
services:
clearplane-core:
labels:
clearplane.core.geo-ip.enabled: "true"
clearplane.core.geo-ip.provider: "MaxMind"
Edge configuration
Edge bootstrap settings are environment-only and default to the values the published image needs, so set one only to override it. Runtime Edge settings use validated labels on the Edge container or the UI:
services:
clearplane-edge:
environment:
CLEARPLANE_EDGE_BOOTSTRAP_WAF_MEMORY_ADMISSION_PERCENT: "75"
labels:
clearplane.edge.maximum-concurrent-connections-per-address: "100"
HTTP/1.1, HTTP/2, and HTTP/3 default to enabled on public HTTPS, with HTTP/3 available when QUIC is supported. Select any nonempty combination through System → Settings → Edge, or set it with labels on the Edge container, which lock the UI fields. This example disables HTTP/1.1 on HTTPS while allowing HTTP/2 and HTTP/3. The plain HTTP listener retains HTTP/1.1 for redirects, ACME, and health checks. Changes require an Edge restart; HTTP/3 also requires UDP port 443. HTTP/3 alone requires a QUIC-capable runtime and clients that can discover or directly request it, because the usual HTTP/1.1 or HTTP/2 discovery response is unavailable.
services:
clearplane-edge:
labels:
clearplane.edge.http1.enabled: "false"
clearplane.edge.http2.enabled: "true"
clearplane.edge.http3.enabled: "true"
Upstream destination restrictions are opt-in. This label blocks selected address classes globally while preserving Docker's ordinary private-network upstreams:
services:
clearplane-edge:
labels:
clearplane.edge.restricted-destination-classes: "Loopback LinkLocal CloudMetadata ControlPlaneNetwork"
A proxy policy family takes effect on a route only with its root label set to On. Set policy to the SystemName of an existing policy (lowercase ASCII letters, digits, and single internal dashes), or policies to a space-separated list for access control, authentication, auto-ban and rate limit. Without a reference, the family creates an inline policy. Set the root label to Off to opt the route out of a Global policy while retaining the family's other labels. Generated names use clearplane.proxy.name (or the discovery key) plus the family suffix:
services:
app:
labels:
clearplane.proxy.response-headers: "On"
clearplane.proxy.response-headers.policy: "shared-security-headers"
clearplane.proxy.cors: "Off"
api:
labels:
clearplane.proxy.name: "api"
clearplane.proxy.response-headers: "On"
clearplane.proxy.response-headers.content-security-policy: "default-src 'self'"
UI configuration
The UI has no production settings. Its bootstrap settings are development-only.
ContainerProxy configuration
ContainerProxy settings are bootstrap settings with built-in defaults. The shipped Compose file mounts the host's Docker socket at the default socket path, so another local socket needs only a different host side on that mount:
services:
clearplane-container-proxy:
volumes:
- /run/user/1000/docker.sock:/var/run/docker.sock:ro
Standalone external redirect
A container can declare a redirect without publishing an upstream port or joining the proxy network. Set clearplane.redirect.certificate.enabled to request a certificate whose domain defaults to the source host. Additional source hosts become certificate identifiers. A container must not enable both clearplane.proxy.enabled and clearplane.redirect.enabled.
services:
drive-redirect:
image: alpine:latest
command: ["sleep", "infinity"]
labels:
clearplane.redirect.enabled: "true"
clearplane.redirect.name: "sharepoint-drive"
clearplane.redirect.source-host: "drive.example.com"
clearplane.redirect.certificate.enabled: "true"
clearplane.redirect.target-uri: "https://target.example.com"
clearplane.redirect.status-code: "308"
Inline access control
With clearplane.proxy.access-control: "On" and no policies, the access-control labels create an inline policy. Country codes are normalized to uppercase. default-action: Block blocks everything the allowlists do not name, so this example permits only the listed address and countries:
services:
app:
image: example/app
labels:
clearplane.proxy.enabled: "true"
clearplane.proxy.name: "sample-app"
clearplane.proxy.host: "app.example.com"
clearplane.proxy.port: "8080"
clearplane.proxy.access-control: "On"
clearplane.proxy.access-control.default-action: "Block"
clearplane.proxy.access-control.allowed-addresses: "203.0.113.10"
clearplane.proxy.access-control.allowed-countries: "NL CW"
Whitespace lists may also use YAML's folded form. Line breaks become spaces, so this is equivalent to one quoted whitespace-delimited value:
services:
app:
labels:
clearplane.proxy.access-control: "On"
clearplane.proxy.access-control.allowed-countries: >-
NL
CW
clearplane.proxy.cache: "On"
clearplane.proxy.cache.key.header-names: >-
Accept-Language
X-Tenant
Inline policy labels are reconciled transactionally with the discovered route. The container owns its inline policies: their labelled settings are read-only in the API and UI, and discovery recreates a deleted inline policy on its next pass. Invalid labels leave the last accepted configuration in place. Set the family's policy label instead of inline fields to reference an existing policy.
Inline Basic authentication
Basic authentication uses complete indexed credential entries. Password label values are hashed before persistence and never rendered by APIs, diagnostics, logs, or this reference:
services:
app:
labels:
clearplane.proxy.authentication: "On"
clearplane.proxy.authentication.type: "Basic"
clearplane.proxy.authentication.key-location: "Edge"
clearplane.proxy.authentication.basic.realm: "Restricted"
clearplane.proxy.authentication.basic.credentials.1.user-name: "alice"
clearplane.proxy.authentication.basic.credentials.1.password: "replace-with-a-password"
Inline JWT authentication
JWT signing-key material is always treated as secret metadata. Symmetric material is encrypted before persistence; RSA and EC public keys use PEM block values:
services:
api:
labels:
clearplane.proxy.authentication: "On"
clearplane.proxy.authentication.type: "Jwt"
clearplane.proxy.authentication.jwt.issuer: "https://identity.example.com"
clearplane.proxy.authentication.jwt.audiences: "clearplane-api account-api"
clearplane.proxy.authentication.jwt.signing-keys.1.type: "Symmetric"
clearplane.proxy.authentication.jwt.signing-keys.1.material: "a-secret-signing-key-at-least-32-characters"
clearplane.proxy.authentication.jwt.required-claims.1.claim: "scope"
clearplane.proxy.authentication.jwt.required-claims.1.value: "clearplane.read"
Warning
Docker labels remain visible through container inspection and Compose source. If credentials cannot be stored in Docker metadata, create the authentication policy through the UI/API and reference it with clearplane.proxy.authentication.policies.
The shipped docker-compose.yml sets no Clearplane environment variables; every bootstrap setting defaults to its production value. Deployment changes, both environment: entries and labels, go on the service in the Compose file itself or an override file. A sibling .env file feeds only Compose interpolation and never reaches the containers. Runtime settings use validated labels or the UI; only documented secret runtime settings have environment-variable twins. Container-resource labels are label-only.