MITM Configuration Reference

MITM (man-in-the-middle) TLS interception configuration.

When enabled, the proxy terminates TLS from clients using a dynamically generated leaf certificate signed by a local Certificate Authority, then re-establishes a separate TLS connection to the upstream. This allows the proxy to inspect, record, and modify HTTPS traffic that would otherwise be opaque.

If no caCertFile is provided, an ephemeral CA key pair is generated on every startup. Clients must trust this CA for interception to work without TLS errors. Export the CA certificate and install it in system or browser trust stores:

pkl

elide fwd --export-ca > elide-proxy-ca.pem

For persistent trust across restarts, supply your own CA files via caCertFile and caKeyFile.

> This page is auto-generated from the PKL schema. See the guide for usage examples.

`MitmConfig`

Certificate Authority and interception settings for MITM TLS proxying.

A minimal mitm {} block with all defaults generates an ephemeral CA on startup and intercepts every CONNECT tunnel. Use include and exclude to control which hosts are intercepted.

Field	Type	Default	Description
`caCertFile`	String?	`null`	Path to a PEM-encoded certificate file for the CA used to sign
`caKeyFile`	String?	`null`	Path to a PEM-encoded private key file for the CA. Required when
`caName`	String	`"Elide Proxy CA"`	Subject Common Name (CN) embedded in the auto-generated CA certificate.
`caValidity`	Duration	`365.d`	How long the auto-generated CA certificate remains valid. Has no effect
`leafValidity`	Duration	`30.d`	How long each dynamically generated leaf certificate remains valid.
`include`	Listing?	`null`	Hostname patterns to intercept via MITM. Uses glob syntax
`exclude`	Listing?	`null`	Hostname patterns to exclude from MITM interception. Evaluated before
`cacheCertificates`	Boolean	`true`	Whether to cache dynamically generated leaf certificates in memory.
`maxCachedCerts`	UInt	`1024`	Maximum number of leaf certificates held in the in-memory cache.

`caCertFile`

Path to a PEM-encoded certificate file for the CA used to sign intercepted leaf certificates. When omitted, an ephemeral CA key pair is generated on each startup. Providing a persistent CA file avoids the need to re-trust the CA after every restart.

pkl

caCertFile = "/etc/elide/proxy-ca.pem"

`caKeyFile`

Path to a PEM-encoded private key file for the CA. Required when caCertFile is set; ignored otherwise. The key must correspond to the certificate in caCertFile.

`caName`

Subject Common Name (CN) embedded in the auto-generated CA certificate. Has no effect when caCertFile is provided. Default: "Elide Proxy CA".

`caValidity`

How long the auto-generated CA certificate remains valid. Has no effect when caCertFile is provided. Default: 365.d (one year).

`leafValidity`

How long each dynamically generated leaf certificate remains valid. Shorter periods reduce risk if a leaf key is compromised; longer periods reduce certificate generation frequency. Default: 30.d.

`include`

Hostname patterns to intercept via MITM. Uses glob syntax (e.g., "*.example.com"). When null (the default), all CONNECT tunnels are intercepted. When non-null, only matching hostnames are intercepted; all others pass through as opaque TCP relays.

pkl

include { "*.example.com"; "api.stripe.com" }

`exclude`

Hostname patterns to exclude from MITM interception. Evaluated before include — a host matching both exclude and include is excluded. Use this for services with certificate pinning that reject proxy-issued certificates (e.g., OS update servers, banking sites, mobile app backends).

pkl

exclude { "*.apple.com"; "*.googleapis.com" }

`cacheCertificates`

Whether to cache dynamically generated leaf certificates in memory. Caching avoids repeated RSA/EC key generation for the same hostname across multiple requests. Default: true.

`maxCachedCerts`

Maximum number of leaf certificates held in the in-memory cache. When the cache is full, least-recently-used entries are evicted. Default: 1024.

---