Jetty configuration properties

In IDM 8.0, jetty.xml is no longer supported.

When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate’s subject and returns a 400 Bad Request error on a mismatch. If you’re upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.

Learn more in Jetty 12 support.

The configuration for PingIDM’s embedded Jetty web server includes a webserver.json and a webserver.listener-*.json.

By default, the Jetty web server uses the HTTP, SSL, and Mutual Authentication ports defined in IDM.

The default settings are intended for evaluation only. Adjust them according to your production requirements.

Jetty property reference

`webserver.json` reference
Field	Description	Default value
`maxThreads`	The maximum number of threads used to handle requests.	`200`
`maxQueueSize`	The maximum number of requests allowed in the QoSHandler queue. This setting controls readiness probe behavior.	`-1` The default value allows for an unbounded queue.
`maxRequestSuspendTime`	The number of milliseconds a request can remain in the QosHandler queue.	`0` The default value allows requests to remain in the unbounded queue indefinitely.
`gzip`	Contains the settings for the global Gzip compression handler.
`gzip/enabled`	Toggles the Gzip compression handler on or off.	`false`
`gzip/minGzipSize`	The minimum response size in bytes required to enable compression of the response.	`2048`
`gzip/inflateBufferSize`	The size in bytes of the buffer used to inflate compressed requests.	`0`
`gzip/syncFlush`	Toggles the usage of the SYNC_FLUSH mode when compressing responses.	`false`
`gzip/includedMethods`	The allow list of HTTP methods that compression will be applied to.
`gzip/excludedMethods`	The block list of HTTP methods that compression will not be applied to.

`webserver.listener-*.json` properties
Field	Description	Default value
`enabled`	Toggles the listener on or off.	`false`
`port`	The port to listen to.	`8080`
`secure`	Toggles the use of TLS on or off.	`false`
`mutualAuth`	Toggles the use of `mTLS` on or off. Does nothing if secure is false.	`false`
`wantClientAuth`	Toggles the `wantClientAuth` setting on or off. When `true`, the server requests a client certificate but doesn’t require it for the TLS handshake to succeed. If a client provides a certificate, it must be valid. This enables support for mixed traffic, allowing clients with or without certificates to connect on the same port. For proper function, you must set `mutualAuth` to `false`.	`false`
`sslCertAlias`	The key alias IDM uses when choosing the certificate to present for HTTPS connections.	`openidm-localhost`
`includedProtocols`	The allow-list of acceptable TLS protocols.	`TLSv1.3`,`TLSv1.2`
`excludedProtocols`	The block-list of non-acceptable TLS protocols.
`includedCiphers`	The allow-list of acceptable TLS ciphers.	`"TLS_AES_128_GCM_SHA256", "TLS_AES_256_GCM_SHA384", "TLS_CHACHA20_POLY1305_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256", "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256", "TLS_DHE_RSA_WITH_AES_256_GCM_SHA384", "TLS_DHE_RSA_WITH_AES_128_GCM_SHA256"`
`excludedCiphers`	The block-list of non-acceptable TLS ciphers.
`acceptorThreads`	The number of threads used to accept TCP socket connections. Learn more in the Jetty description of acceptor threads.	`1`
`selectorThreads`	The number of threads used to manage the set of accepted TCP sockets. Learn more in the Jetty description of selector threads.	`5`
`timeout`	The amount of time to wait in milliseconds before closing a connection if no data has been sent or received.	`30000`
`outputBufferSize`	The maximum size in bytes of a server response buffer.	`32768`
`inputBufferSize`	The maximum size in bytes of the client request buffer.	`8192`
`headerBufferSize`	The maximum size in bytes of the response and request header buffers.	`16384`
`sniHostCheckEnabled`	Toggles the Jetty SNI host check. When enabled, Jetty checks that the incoming host header matches the server certificate’s subject. This setting does nothing if `secure` is `false`.	`true`
`proxyLoadBalancerConnection`	Toggles the handling of proxied requests. Enable this property when running IDM behind a proxy or load balancer.	`false`

Jetty thread settings and Gzip compression

To change the Jetty thread pool and Gzip compression settings, make changes to your project’s conf/webserver.json file:

{
  "maxThreads": {
    "$int": "&{openidm.webserver.max.threads|&{org.ops4j.pax.web.server.maxThreads|200}}"
  }
}

Jetty QoSHandler

The Jetty QoSHandler limits the number of threads most PingIDM requests can run on. The handler is configured to use all but two threads to ensure requests to critical endpoints are always handled.

The critical endpoints include:

openidm/health/live
openidm/metrics/*

Learn more about these endpoints at Liveness and readiness probes and in the Metrics reference.

The QoSHandler keeps its own queue of requests rather than allowing requests to queue in the Jetty QueuedThreadPool. Because of this, the jetty.thread.queue (API) and the idm_jetty_thread_queue (Prometheus) metric should remain at 0.The queued requests are handled by the jetty.qos.queue.count API metric and the idm_jetty_qos_queue_count gauge metric in Prometheus.