Configuring the Undertow Runtime

Overview

This section is for configuring the Undertow runtime used for the CXF standalone model. The Undertow runtime is used by HTTP servers using a decoupled endpoint. The Undertow runtime's thread pool and handlers can be configured. You can also set a number of the security settings for an HTTP service provider through the Undertow runtime.

Namespace

The elements used to configure the Undertow runtime are defined in the namespace http://cxf.apache.org/transports/http-undertow/configuration. It is commonly referred to using the prefix httpu. In order to use the Undertow configuration elements you will need to add the lines shown below to the beans element of your endpoint's configuration file. In addition, you will need to add the configuration elements' namespace to the xsi:schemaLocation attribute.

<beans ...
  xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration
  ...
  xsi:schemaLocation="...
                      http://cxf.apache.org/transports/http-undertow/configuration
                      http://cxf.apache.org/schemas/configuration/http-undertow.xsd
                      ...>

The engine-factory element

The httpu:engine-factory element is the root element used to configure the Undertow runtime used by an application. It has a single required attribute, bus, whose value is the name of the Bus that manages the Undertow instances being configured.

The value is typically cxf which is the name of the default Bus instance.

The httpu:engine-factory element has three children that contain the information used to configure the HTTP ports instantiated by the Undertow runtime factory. The children are described below.

ElementDescription

httpu:engine

Specifies the configuration for a particular Undertow runtime instance.

httpu:identifiedTLSServerParameters

Specifies a reusable set of properties for securing an HTTP server. It has a single attribute, id, that specifies a unique identifier by which the property set can be referred.

httpu:identifiedThreadingParameters

Specifies a reusable set of properties for controlling a Undertow instance's thread & IO pools. It has a single attribute, id, that specifies a unique identifier by which the property set can be referred.

The engine element

The httpu:engine element is used to configure specific instances of the Undertow runtime. It has a single attribute, port, that specifies the number of the port being managed by the Undertow instance.

You can specify a value of 0 for the port attribute. Any threading properties specified in an httpu:engine element with its port attribute set to 0 are used as the configuration for all Undertow listeners that are not explicitly configured.

Each httpu:engine element can have two children: one for configuring security properties and one for configuring the Undertow instance's thread & IO pools. For each type of configuration you can either directly provide the configuration information or provide a reference to a set of configuration properties defined in the parent httpu:engine-factory element.

The child elements used to provide the configuration properties are described below.

ElementDescription

httpu:tlsServerParameters

Specifies a set of properties for configuring the security used for the specific Undertow instance. See the TLS Configuration page for more information.

httpu:tlsServerParametersRef

Refers to a set of security properties defined by a identifiedTLSServerParameters element. The id attribute provides the id of the referred identifiedTLSServerParameters element.

httpu:threadingParameters

Specifies the size of the thread & IO pools used by the specific Undertow instance.

httpu:threadingParametersRef

Refers to a set of properties defined by a identifiedThreadingParameters element. The id attribute provides the id of the referred identifiedThreadingParameters element.

httpu:handlers

You can use Spring Beans syntax to instantiate a Undertow handler list and set these handlers' properties , the Undertow's handlers will be set to the Undertow server engine

Configuring the thread & IO pools

You can configure the size of a Undertow instance's thread & IO pools by either:

  • Specifying the size of thread pool using a identifiedThreadingParameters element in the engine-factory element. You then refer to the element using a threadingParametersRef element.

  • Specify the size of the of thread pool directly using a threadingParameters element.
    The threadingParameters has four attributes to specify the size of a thread & IO worker pools. The attributes are described below. 

    The httpu:identifiedThreadingParameters element has a single child threadingParameters element

AttributeDescription

minThreads

Specifies the minimum number of threads available to the Undertow instance for processing requests.

maxThreads

Specifies the maximum number of threads available to the Undertow instance for processing requests.

workerIOThreadsSpecifies the number of worker threads available to the Undertow instance for I/O processing.
workerIONameSpecifies the name of the Undertow instance worker thread pool.

HTTP/2 support

If HttpServerEngineSupport#ENABLE_HTTP2  bus property is set, Undertow engine will enable the HTTP/2 support as well: HTTP/2 over cleartext (h2c) if TLS is not configured, regular HTTP/2 otherwise.

Example: https://github.com/apache/cxf/tree/master/distribution/src/main/release/samples/jax_rs/basic_http2_undertow

Example

The example below shows a configuration fragment that configures a Jetty instance on port number 9001.

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:sec="http://cxf.apache.org/configuration/security"
    xmlns:http="http://cxf.apache.org/transports/http/configuration"
    xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration"
    xsi:schemaLocation="http://cxf.apache.org/configuration/security
        http://cxf.apache.org/schemas/configuration/security.xsd
        http://cxf.apache.org/transports/http/configuration
        http://cxf.apache.org/schemas/configuration/http-conf.xsd
        http://cxf.apache.org/transports/http-undertow/configuration
        http://cxf.apache.org/schemas/configuration/http-undertow.xsd
        http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans.xsd">
    <httpu:engine-factory bus="cxf">
        <httpu:engine port="9001">
            <httpu:tlsServerParameters>
                <sec:keyManagers keyPassword="skpass">
                    <sec:keyStore file="src/main/config/serviceKeystore.jks" password="sspass" type="JKS"/>
                </sec:keyManagers>
                <sec:trustManagers>
                    <sec:keyStore file="src/main/config/serviceKeystore.jks" password="sspass" type="JKS"/>
                </sec:trustManagers>
            </httpu:tlsServerParameters>
        </httpu:engine>
    </httpu:engine-factory>
</beans>