Traffic

TLS and ACME

A TLS listener uses either the global managed SNI store or an inline certificate pair. Validate all certificate and key paths on the target host before restart.

Managed TLS with HTTP-01

tls:
  min_version: tls1.2
  certs: []
  acme:
    enabled: true
    contacts: ["mailto:ops@example.com"]
    terms_of_service_agreed: true
    domains: [app.example.com]
    cache_dir: /var/lib/omlb/acme
    http01_address: "0.0.0.0:80"
    renew_before_days: 30

listeners:
  - name: https
    address: "0.0.0.0:443"
    tls: { managed: true }
    http2: true
    http3: true

managed: true selects the global SNI store, which combines static entries and ACME-issued certificates. HTTP-01 runs a challenge responder at http01_address; arrange firewall and DNS so the CA can reach it on port 80. When domains is empty, OMLB derives names from route hosts on managed listeners.

http3: true is valid only on a TLS listener. It adds QUIC/UDP HTTP/3 on the listener address and port while TCP HTTP/1.1 and HTTP/2 remain available. Allow both TCP and UDP in the firewall. Only one HTTP/3 listener is permitted.

DNS-01 wildcard certificates

tls:
  acme:
    enabled: true
    contacts: ["mailto:ops@example.com"]
    terms_of_service_agreed: true
    domains: ["*.example.com", example.com]
    cache_dir: /var/lib/omlb/acme
    challenge:
      dns-01:
        provider: cloudflare
        zone_id: "0123456789abcdef0123456789abcdef"
        credential_file: /run/secrets/cloudflare-api-token
        propagation_timeout: 120s
        poll_interval: 5s

DNS-01 currently supports the Cloudflare provider. Give the token file minimal zone authority, make it readable by the OMLB service account, and keep it outside YAML. OMLB waits for public DNS visibility before requesting validation and retains provider-issued record identifiers for cleanup.

Static SNI certificates

tls:
  min_version: tls1.2
  certs:
    - sni: [app.example.com]
      cert: /etc/omlb/certs/app.pem
      key: /etc/omlb/certs/app-key.pem
    - sni: []                         # fallback certificate
      cert: /etc/omlb/certs/default.pem
      key: /etc/omlb/certs/default-key.pem

listeners:
  - name: https
    address: "0.0.0.0:443"
    tls: { managed: true }
    http2: true

Static certificate files are loaded at startup. SNI resolution prefers an exact hostname, then a wildcard match, then the empty sni fallback entry. The global minimum version defaults to TLS 1.2; set max_version: tls1.3 only when intentionally capping negotiation.

Downstream mTLS

listeners:
  - name: partner-api
    address: "0.0.0.0:8443"
    tls:
      cert: /etc/omlb/certs/partner.pem
      key: /etc/omlb/certs/partner-key.pem
      client_auth:
        mode: require
        ca_file: /etc/omlb/certs/partner-client-ca.pem

Client authentication is per listener and happens during the TLS handshake, before HTTP routing. mode: require requires a client certificate trusted by ca_file. It is off by default. This is downstream client authentication; configure upstream encryption independently with backend tls and sni.