TLS

Working example configs for every TLS scenario live in examples/configs/protocols/:

Listener TLS

Add tls to any listener. PEM format; the cert file may include the full chain. See tls-termination for a complete example.

tls:
  certificates:
    - cert_path: /etc/praxis/tls/cert.pem
      key_path: /etc/praxis/tls/key.pem

SNI and Multiple Certificates

Multiple certificates on a single listener enable SNI-based selection. Entries with server_names match those hostnames; wildcard entries like *.example.com match single-level subdomains. Mark exactly one entry with default: true to serve as the fallback for unmatched SNI. An entry without server_names that is not marked default: true is rejected as ambiguous. If no entry has default: true, unmatched SNI is rejected (no fallback). See tls-multi-cert.

Certificate Hot-Reload

Certificate hot-reload is enabled by default. Cert and key files are watched for changes. When modified (e.g. by certbot, cert-manager, or Vault PKI), the proxy atomically picks up the new certificate within 500ms. Existing connections are unaffected; only new TLS handshakes use the rotated certificate.

To explicitly disable hot-reload, set hot_reload: false. Multi-cert SNI configs auto-disable hot-reload.

Hot-reload is compiled in by the config-reload build feature (on by default); a binary built without it serves the certificate statically. See Build Features.

Constraints:

• Hot-reload applies only to single-cert listeners. Multi-cert SNI configs are automatically excluded.
• If the new certificate fails to parse, the proxy logs a warning and continues serving the previous valid certificate. A failed reload is retried on a timer even without a further file change, backing off exponentially up to 60s between attempts, so a file caught mid-write is picked up once it is complete.

Debounce behavior: filesystem events are debounced by 500ms to handle atomic rename patterns used by Kubernetes secret mounts, certbot, and cert-manager. A cert-manager rotation that writes a temp file and then renames it over the original triggers a single reload after the rename completes.

Alternative: graceful restart. Pingora supports graceful restart via SIGHUP with FD passing. This reloads all configuration including certificates, but drains in-flight connections. Use graceful restart when hot-reload is not needed or for config changes beyond certificate rotation.

Minimum TLS Version

min_version restricts the minimum protocol version: tls12 (default) or tls13. See tls-version-constraint.

Listener mTLS

Require or request client certificates with client_ca and client_cert_mode.

client_ca is required when mode is request or require, and client_ca requires client_cert_mode: setting client_ca with mode none is rejected at validation instead of silently ignoring the CA. See tls-mtls-listener and tls-mtls-listener-request.

Certificate Revocation Lists (CRL)

Add crl_paths to client_ca to reject client certificates that appear on a Certificate Revocation List. Each path must point to a PEM-encoded CRL file. Paths containing .. are rejected at validation to prevent directory traversal.

tls:
  client_cert_mode: require
  client_ca:
    ca_path: /etc/praxis/tls/client-ca.pem
    crl_paths:
      - /etc/praxis/tls/client-ca.crl
  certificates:
    - cert_path: /etc/praxis/tls/cert.pem
      key_path: /etc/praxis/tls/key.pem

CRL checking applies only to listener client authentication. Upstream (cluster) CRL checking is not implemented, so tls.ca.crl_paths on a cluster definition is rejected at config validation rather than silently ignored.

A CA/CRL reload invalidates all cached TLS sessions on that listener, so resumed sessions are re-verified against the new CA and CRLs.

CRL and CA files reload only on listeners with exactly one certificate and hot_reload not set to false. Every other listener needs a restart to pick up a new CRL.

Revocation policy:

• CRLs are checked for the whole chain, not only the leaf certificate.
• When CRLs are configured, a certificate whose issuer has no CRL is rejected (unknown revocation status is denied).
• A CRL past its nextUpdate is still accepted, so operators must refresh CRL files themselves.

After a CA replacement (not a CRL update), the CertificateRequest still advertises the old CA names until restart. Clients that filter their certificates by CA name (browsers, Java) may then offer no certificate. During rotation, use a CA bundle that holds both the old and the new CA.

Local dev with mkcert

mkcert -install
mkcert localhost 127.0.0.1

Point cert_path and key_path at the generated files.

Cluster TLS

Add tls: to a cluster to TLS-connect to endpoints. sni sets the backend SNI hostname. verify controls certificate verification (default: true). See upstream-tls and tls-verify-disabled.

A verifying cluster without sni needs authority: { from: endpoint }, which verifies each endpoint against its own hostname, or an IP endpoint against the certificate’s IP SAN. The alternative, insecure_options.allow_tls_without_sni, takes the name from the cluster’s fixed authority or the client’s Host header instead; see Security Hardening.

Upstream mTLS (Client Certificate)

Present a client certificate to upstream servers. See tls-mtls-upstream and tls-mtls-both.

CA Trust

Three levels of CA trust, evaluated in order:

1. Per-cluster CA (tls.ca.ca_path): applies to one cluster only.
2. Global CA (runtime.upstream_ca_file): applies to all clusters without their own tls.ca.
3. System trust store: used when neither of the above is set.

The global CA replaces the system trust store (not additive). If backends use both a private CA and public CAs, create a combined PEM bundle. See upstream-ca-file.

Timeouts

Pingora enforces a 60-second TLS handshake timeout (hardcoded). For total connection budgets (TCP + TLS), use total_connection_timeout_ms on the cluster. See configuration.md for details.

Certificate and Key Security

Private keys should have restrictive file permissions. Praxis warns at startup if keys are group or world readable.

chmod 600 /etc/praxis/tls/key.pem
chown praxis:praxis /etc/praxis/tls/key.pem

Don’t store private keys in version control or unencrypted on disk. Use a secrets manager or encrypted storage solution.

Cipher Suites

Praxis uses rustls, which supports TLS 1.2 and 1.3 only. No weak cipher suites are available.

By default, rustls selects cipher suites automatically. To restrict the set, specify cipher_suites on the listener TLS block. When set, only the listed suites are offered during the TLS handshake. An empty list is rejected at validation.

Available Suites

TLS 1.3:

TLS 1.2:

TLS 1.2 suites cannot be used when min_version is tls13. See tls-cipher-suites.

tls:
  cipher_suites:
    - tls13_aes_256_gcm_sha384
    - tls13_chacha20_poly1305_sha256
  certificates:
    - cert_path: /etc/praxis/tls/cert.pem
      key_path: /etc/praxis/tls/key.pem

Active health probes

Enable the experimental tls-health-check feature to verify upstream TLS identities or probe HTTPS endpoints using the cluster TLS settings. See TLS and HTTPS probes for trust, server-name selection and the TLS 1.3 client-authentication limitation.