Page Comparison

...

Code Block

	xml
	xml

<undertow xmlns="urn:org.ops4j.pax.web:undertow:1.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:w="urn:jboss:domain:4.2"
        xmlns:io="urn:jboss:domain:io:3.0"
        xsi:schemaLocation="
            urn:jboss:domain:undertowio:3.10 http://www.jboss.org/schema/jbossas/wildfly-undertowio_3_10.xsd
            urn:jboss:domain:undertow:4.20 http://www.jboss.org/schema/jbossas/wildfly-configundertow_4_20.xsd">
            <!-- httpsurn:jboss:domain:5.0 http://docswww.jboss.org/authorschema/display/WFLY10/Undertow+subsystem+configuration -->
    <subsystem xmlns="urn:jboss:domain:undertow:3.1jbossas/wildfly-config_5_0.xsd">

       <!-- org.wildfly.extension.undertow.BufferCacheDefinition -->
        <buffer-cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10" />Only "default" worker and buffer-pool are supported and can be used to override the defaults
        buffer-pool:
<server name="default-server">        - buffer-size defaults to:
 <!-- HTTP(S) Listener references Socket Binding    (and indirectly - Interfaces) --> when < 64MB of Xmx: 512
            <http-listener name="http" socket-binding="http" />- when < 128MB of Xmx: 1024
            <!-- verify-client: org.xnio.SslClientAuthMode.NOT_REQUESTED, org.xnio.SslClientAuthMode.REQUESTED, org.xnio.SslClientAuthMode.REQUIRED -->
 - when >= 128MB of Xmx: 16K - 20
         - direct-buffers defaults to:
          <!--<https-listener name="https" socket-binding="https"-->
      when < 64MB of Xmx: false
            -  <!--security-realm="https" verify-client="NOT_REQUESTED" />-->
 when >= 64MB of Xmx: true
        worker:
 <host name="default-host" alias="localhost">      - io-threads defaults to   Math.max(Runtime.getRuntime().availableProcessors(), 2);
    <!--<location name="/" handler="welcome-content" />-->
           - task-core-threads and task-max-threads default to io-threads * 8
    -->
    <!--<location name="/docs" handler="docs-content" />-->
    <subsystem xmlns="urn:jboss:domain:io:3.0">
          <access<buffer-logpool directoryname="${karaf.data}/logdefault" patternbuffer-size="common" prefix="access_log." suffix="log" rotate16364" direct-buffers="true" />
                <filter-ref <worker name="server-header" />
                <filter-ref name="x-powered-by-headerdefault" io-threads="8" task-core-threads="64" task-max-threads="64" task-keepalive="60000" />
    </subsystem>
    -->

 </host>   <!-- https://docs.jboss.org/author/display/WFLY10/Undertow+subsystem+configuration -->
   </server> <subsystem xmlns="urn:jboss:domain:undertow:3.1">
      <servlet-container name="default">
   <!-- org.wildfly.extension.undertow.BufferCacheDefinition -->
         <jsp<buffer-config />
   cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10" />
        <websockets /<server name="default-server">
            <welcome-files>
        <!-- HTTP(S) Listener references Socket Binding (and indirectly - Interfaces) -->
       <welcome-file     <http-listener name="index.html"http" socket-binding="http" />
            <!-- verify-client: org.xnio.SslClientAuthMode.NOT_REQUESTED,  <welcome-file name="index.txt" /org.xnio.SslClientAuthMode.REQUESTED, org.xnio.SslClientAuthMode.REQUIRED -->
            </welcome-files>
        </servlet-container>!--<https-listener name="https" socket-binding="https"-->
        <handlers>             <file name="welcome-content" path="${karaf.home}/welcome<!--security-realm="https" verify-client="NOT_REQUESTED" />-->
             <!--<file name<host name="docsdefault-contenthost" pathalias="${karaf.home}/docs" />-->localhost">
        </handlers>         <filters>
<!--<location name="/" handler="welcome-content" />-->
           <!-- filters for reference from /host/filter-ref and /host/location/filter-ref  <!--<location name="/docs" handler="docs-content" />-->
            <response-header name="server-header" header-name="Server" header-value="Pax-HTTP-Undertow" />
    <access-log directory="${karaf.data}/log" pattern="common" prefix="access_log." suffix="log" rotate="true" />
             <response-header name="x-powered-by-header" header-   <filter-ref name="X-Powered-By" header-value="Pax-HTTP-Undertow/${project.version}server-header" />
        </filters>     </subsystem>      <!-- https://docs.jboss.org/author/display/WFLY10/Security+Realms --<filter-ref name="x-powered-by-header" />
    <!--        </host>
we'll use "default" security realm by default to configure jaas</propertiesserver>
authentication         (io.undertow.security.idm.IdentityManager):<servlet-container name="default">
          - w:jaas <jsp- org.ops4j.pax.web.service.undertow.internal.security.JaasIdentityManagerconfig />
         - w:properties - org.ops4j.pax.web.service.undertow.internal.security.PropertiesIdentityManager
 <websockets />
   -->     <security-realm name="default">   <welcome-files>
     <w:authentication>           <welcome-file  <!-- JaasIdentityManager for given realm -->name="index.html" />
                 <w:jaas <welcome-file name="karafindex.txt" />
            <!-- OR PropertiesIdentityManager (mutually exclusive with <w:jaas>) -->/welcome-files>
        </servlet-container>
        <handlers>
      <!--<w:properties      <file name="welcome-content" path="users.properties${karaf.home}/welcome" />-->
            </w:authentication>!--<file name="docs-content" path="${karaf.home}/docs" />-->
        <user-principal-class-name>org.apache.karaf.jaas.boot.principal.UserPrincipal</user-principal-class-name></handlers>
        <filters>
   <role-principal-class-name>org.apache.karaf.jaas.boot.principal.RolePrincipal</role-principal-class-name>         <!--<role-principal-class-name>...</role-principal-class-name>--> filters for reference from /host/filter-ref and /host/location/filter-ref -->
       </security-realm>     <!--
  <response-header name="server-header" header-name="Server" header-value="Pax-HTTP-Undertow" />
     Any security realm may be referenced by https<response-listener to define trust/keystore, protocols and cipher suitesheader name="x-powered-by-header" header-name="X-Powered-By" header-value="Pax-HTTP-Undertow/${project.version}" />
       --> </filters>
   <security-realm name="https"> </subsystem>

    <!-- https://docs.jboss.org/author/display/WFLY10/Security+Realms  <w:server-identities>-->
    <!--
        <w:ssl>
         we'll use "default" security realm by default to configure jaas/properties authentication
      <!-- sun.  (io.undertow.security.sslidm.ProtocolVersion -->IdentityManager):
         -        <!-- sun.security.ssl.CipherSuite -->w:jaas - org.ops4j.pax.web.service.undertow.internal.security.JaasIdentityManager
         -        <!-- openssl ciphers 'ALL:eNULL' | sed -e 's/:/\n/g' | sort --w:properties - org.ops4j.pax.web.service.undertow.internal.security.PropertiesIdentityManager
    -->
    <security-realm name="default">
         <w:authentication>
      <w:engine      <!-- JaasIdentityManager for given realm -->
             enabled-cipher-suites="TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384"
<w:jaas name="karaf" />
            <!-- OR PropertiesIdentityManager (mutually exclusive with <w:jaas>) -->
   enabled-protocols="TLSv1 TLSv1.1 TLSv1.2" />                 <!--<w:keystoreproperties path="${karaf.etc}/certs/server.keystore" provider="JKS" alias="server"users.properties" />-->
        </w:authentication>
                keystore-password="secret" key-password="secret"<user-principal-class-name>org.apache.karaf.jaas.boot.principal.UserPrincipal</user-principal-class-name>
        <role-principal-class-name>org.apache.karaf.jaas.boot.principal.RolePrincipal</role-principal-class-name>
               generate-self-signed-certificate-host="localhost" /<!--<role-principal-class-name>...</role-principal-class-name>-->
       </security-realm>
    </w:ssl>!--
        </w:server-identities>
        <w:authentication>
    Any security realm may be referenced by https-listener to define trust/keystore, protocols and cipher suites
    -->
  <w:truststore path="${karaf.etc}/certs/server.truststore" provider="JKS" keystore-password="secret" / <security-realm name="https">
        </w:authentication><w:server-identities>
    </security-realm>      <!-- Interface lists<w:ssl>
IP addresses to bind to -->     <interface name="default">         <w:inet-address value="0.0.0.0" /><!-- sun.security.ssl.ProtocolVersion -->
                <!--<w:inet-address value="127.0.0.1" /> sun.security.ssl.CipherSuite -->
    </interface>     <interface name="secure">      <!-- openssl ciphers <w:inet-address value="127.0.0.1" />
    </interface>'ALL:eNULL' | sed -e 's/:/\n/g' | sort -->
       <!-- Socket Binding adds port for each IP from referenced<w:engine
Interface -->     <socket-binding name="http" interface="default" port="${org.osgi.service.http.port}" />            <socket-binding name="https" interface="secure" port="${org.osgi.service.http.port.secure}" />

</undertow>

Comments in the above example provide some explanation, but here’s the summary of options. We’ll start from the low level options.

Note
All values may use property placeholders (like `${org.osgi.service.http.port}`) that will be resolved with properties available in configuration or bundle context.

Networking options

Basic networking configuration requires two elements:

<interface>/<w:inet-address> defines networking addresses that will be used for socket binding. Typical settings are 0.0.0.0 (all interfaces), 127.0.0.1 (loopback interface) or any interface address bound to network device
<socket-binding> adds port information to binding address

Undertow server listener configuration

Having address/port options configured, we can specify configuration for http(s) listener in Undertow embedded server.

<subsystem>/<server>/<http[s]-listener> configures embedded server to listen on given address/port.

For <https-listener> we can use realm to point to security configuration and verify-client attribute with one of these values: NOT_REQUESTED, REQUESTED, REQUIRED.

Security configuration

XML configuration may specify multiple <security-realm name="name"> elements.

Special <security-realm name="default"> realm is used to configure io.undertow.security.idm.IdentityManager.

<security-realm name="default">/<w:authentication>/<w:jaas name="karaf" /> defines JAAS authentication and elements <user-principal-class-name> and <role-principal-class-name> are required.
<security-realm name="default">/<w:authentication>/<w:properties path="users.properties" /> switches to simple authentication where users are specified in simple properties file.

When security realm has different name (dedicated, but default may also be referenced), it can be referenced from <subsystem>/<server>/<https-listener> to define additional TLS configuration:

<security-realm name="https">/<w:server-identities>/<w:ssl>/<w:engine> allows to configure these XML attributes:
- enabled-cipher-suites (for example TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, ... - see source code of sun.security.ssl.CipherSuite to check available cipher suites - for standard security engine)
- enabled-protocols (for example TLSv1, TLSv1.1, TLSv1.2 - see source code of sun.security.ssl.ProtocolVersion to check available protocol identifiers - for standard security engine)
<security-realm name="https">/<w:server-identities>/<w:ssl>/<w:keystore> configures keystore that contains server certificate and private key
<security-realm name="https">/<w:authentication>/<w:truststore> configures truststore that contains trusted (CA) certificates

HTTP server configuration

Having networking elements configured, <subsystem>/<server> is used to create actual instance of embedded Undertow server.

<subsystem>/<server>/<http[s]-listener> is a reference to already defined listener
<subsystem>/<server>/<host> currently only one virtual host is supported
<subsystem>/<server>/<host>/<location> maps referenced <subsystem>/<handler> to given HTTP request path
<subsystem>/<server>/<host>/<access-log> configures access logging
<subsystem>/<server>/<host>/<filter-ref> configures additional filters to be used for all requests handled by this virtual host. Filters are defined in <subsystem>/<filters> sub elements

Filter and Handler configuration

Filters and handlers handle HTTP requests. Filters pass the request further down the chain, and handlers are actual endpoints that do something (e.g., servlets).

Filters:

<subsystem>/<filters>/<response-header> adds some HTTP header to response and proceeds
<subsystem>/<filters>/<filter> not implemented yet
<subsystem>/<filters>/<error-page> not implemented yet

Handlers:

<subsystem>/<handlers>/<file> configures resource handler that simply serves static resources from given location. Usually "welcome" handler is configured this way, to serve some initial resources for e.g., Apache Karaf.

Servlet container configuration

Last and highest level of configuration is servlet container - how Undertow handles servlets.

...

  enabled-cipher-suites="TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384"
                        enabled-protocols="TLSv1 TLSv1.1 TLSv1.2" />
                <w:keystore path="${karaf.etc}/certs/server.keystore" provider="JKS" alias="server"
                        keystore-password="secret" key-password="secret"
                        generate-self-signed-certificate-host="localhost" />
            </w:ssl>
        </w:server-identities>
        <w:authentication>
            <w:truststore path="${karaf.etc}/certs/server.truststore" provider="JKS" keystore-password="secret" />
        </w:authentication>
    </security-realm>

    <!-- Interface lists IP addresses to bind to -->
    <interface name="default">
        <w:inet-address value="0.0.0.0" />
        <!--<w:inet-address value="127.0.0.1" />-->
    </interface>
    <interface name="secure">
        <w:inet-address value="127.0.0.1" />
    </interface>

    <!-- Socket Binding adds port for each IP from referenced Interface -->
    <socket-binding name="http" interface="default" port="${org.osgi.service.http.port}" />
    <socket-binding name="https" interface="secure" port="${org.osgi.service.http.port.secure}" />

</undertow>

Comments in the above example provide some explanation, but here’s the summary of options. We’ll start from the low level options.

Note
All values may use property placeholders (like `${org.osgi.service.http.port}`) that will be resolved with properties available in configuration or bundle context.

Networking options

Basic networking configuration requires two elements:

<interface>/<w:inet-address> defines networking addresses that will be used for socket binding. Typical settings are 0.0.0.0 (all interfaces), 127.0.0.1 (loopback interface) or any interface address bound to network device
<socket-binding> adds port information to binding address

Undertow server listener configuration

Having address/port options configured, we can specify configuration for http(s) listener in Undertow embedded server.

<subsystem>/<server>/<http[s]-listener> configures embedded server to listen on given address/port.

For <https-listener> we can use realm to point to security configuration and verify-client attribute with one of these values: NOT_REQUESTED, REQUESTED, REQUIRED.

Security configuration

XML configuration may specify multiple <security-realm name="name"> elements.

Special <security-realm name="default"> realm is used to configure io.undertow.security.idm.IdentityManager.

<security-realm name="default">/<w:authentication>/<w:jaas name="karaf" /> defines JAAS authentication and elements <user-principal-class-name> and <role-principal-class-name> are required.
<security-realm name="default">/<w:authentication>/<w:properties path="users.properties" /> switches to simple authentication where users are specified in simple properties file.

When security realm has different name (dedicated, but default may also be referenced), it can be referenced from <subsystem>/<server>/<https-listener> to define additional TLS configuration:

<security-realm name="https">/<w:server-identities>/<w:ssl>/<w:engine> allows to configure these XML attributes:
- enabled-cipher-suites (for example TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, ... - see source code of sun.security.ssl.CipherSuite to check available cipher suites - for standard security engine)
- enabled-protocols (for example TLSv1, TLSv1.1, TLSv1.2 - see source code of sun.security.ssl.ProtocolVersion to check available protocol identifiers - for standard security engine)
<security-realm name="https">/<w:server-identities>/<w:ssl>/<w:keystore> configures keystore that contains server certificate and private key
<security-realm name="https">/<w:authentication>/<w:truststore> configures truststore that contains trusted (CA) certificates

HTTP server configuration

Having networking elements configured, <subsystem>/<server> is used to create actual instance of embedded Undertow server.

<subsystem>/<server>/<http[s]-listener> is a reference to already defined listener
<subsystem>/<server>/<host> currently only one virtual host is supported
<subsystem>/<server>/<host>/<location> maps referenced <subsystem>/<handler> to given HTTP request path
<subsystem>/<server>/<host>/<access-log> configures access logging
<subsystem>/<server>/<host>/<filter-ref> configures additional filters to be used for all requests handled by this virtual host. Filters are defined in <subsystem>/<filters> sub elements

Filter and Handler configuration

Filters and handlers handle HTTP requests. Filters pass the request further down the chain, and handlers are actual endpoints that do something (e.g., servlets).

Filters:

<subsystem>/<filters>/<response-header> adds some HTTP header to response and proceeds
<subsystem>/<filters>/<filter> not implemented yet
<subsystem>/<filters>/<error-page> not implemented yet

Handlers:

<subsystem>/<handlers>/<file> configures resource handler that simply serves static resources from given location. Usually "welcome" handler is configured this way, to serve some initial resources for e.g., Apache Karaf.

Servlet container configuration

Last and highest level of configuration is servlet container - how Undertow handles servlets.

<subsystem>/<servlet-container>/<welcome-files>/<welcome-file> configures default files that are returned in case there’s no match for any configured servlets, filters or resources (same configuration as in WEB-INF/web.xml)

IO configuration

Since PAXWEB-1255 we can alter configuration of XNIO worker and buffer pool used by the listeners. In undertow.xml template there's a section that specified default values of some IO-related parameters:

Code Block

language	xml

    <!-- Only "default" worker and buffer-pool are supported and can be used to override the defaults
        buffer-pool:
         - buffer-size defaults to:
            - when < 64MB of Xmx: 512
            - when < 128MB of Xmx: 1024
            - when >= 128MB of Xmx: 16K - 20
         - direct-buffers defaults to:
            - when < 64MB of Xmx: false
            - when >= 64MB of Xmx: true
        worker:
         - io-threads defaults to Math.max(Runtime.getRuntime().availableProcessors(), 2);
         - task-core-threads and task-max-threads default to io-threads * 8
    -->
    <!--
    <subsystem xmlns="urn:jboss:domain:io:3.0">
        <buffer-pool name="default" buffer-size="16364" direct-buffers="true" />
        <worker name="default" io-threads="8" task-core-threads="64" task-max-threads="64" task-keepalive="60000" />
    </subsystem>
    -->

Buffer pool:

buffer-size specifies size of the buffer used for IO operations. When not specified, size is calculated depending on available memory.
direct-buffers determines whether java.nio.ByteBuffer#allocateDirect or java.nio.ByteBuffer#allocate should be used.

Worker:

io-threads - The number of I/O threads to create for the worker. If not specified, the number of threads is set to the number of CPUs × 2.
task-core-threads - The number of threads for the core task thread pool.
task-max-threads - The maximum number of threads for the worker task thread pool. If not specified, the maximum number of threads is set to the number of CPUs × 16.

Versions Compared

Old Version 2

New Version 3

Key

Networking options

Undertow server listener configuration

Security configuration

HTTP server configuration

Filter and Handler configuration

Servlet container configuration

Networking options

Undertow server listener configuration

Security configuration

HTTP server configuration

Filter and Handler configuration

Servlet container configuration

IO configuration