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`

Graceful shutdown

When IDM shuts down, whether triggered by a SIGTERM signal, a shutdown command, or a platform-specific stop mechanism such as a Windows service shutdown, the embedded Jetty web server shuts down gracefully:

IDM adds a Connection: close header to in-flight HTTP responses, signaling clients to close keep-alive connections.
IDM tells Jetty to stop accepting new connections.
IDM waits, up to a configurable timeout, for Jetty’s in-flight requests to complete (idm.shutdown.jetty.timeout.seconds).
IDM forcefully closes any remaining active Jetty connections and completes the shutdown.

This behavior prevents clients from receiving abrupt connection failures or 404 responses while IDM is shutting down, which is especially important in clustered or load-balanced deployments.

Graceful shutdown timeout

The idm.shutdown.jetty.timeout.seconds system property controls how long IDM waits for Jetty’s in-flight requests to complete before stopping connections.

Default

20 (seconds)

Positive integer

Wait up to this many seconds for in-flight requests to complete, then stop connections.

0 or negative

Skip the wait. IDM stops Jetty immediately on a shutdown signal, without waiting for in-flight requests to complete.

If your deployment enforces a shutdown deadline, set it to at least idm.shutdown.jetty.timeout.seconds plus any pre-stop sleep so IDM can finish draining before it’s terminated. For example, in Kubernetes, set terminationGracePeriodSeconds to that value.

You can set the property using:

.properties file
OPENIDM_OPTS environment variable

idm.shutdown.jetty.timeout.seconds=30

export OPENIDM_OPTS="-Xmx4096m -Xms4096m -Didm.shutdown.jetty.timeout.seconds=30"

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.