JBoss Community Archive (Read Only)

WildFly 10

Undertow subsystem configuration

Web subsystem was replaced in WildFly 8 with Undertow.

There are two main parts to the undertow subsystem, which are server and Servlet container configuration, as well as some ancillary items. Advanced topics like load balancing and failover are covered on the "High Availability Guide". The default configuration does is suitable for most use cases and provides reasonable performance settings.

Required extension:

<extension module="org.wildfly.extension.undertow" />

Basic subsystem configuration example:

<subsystem xmlns="urn:jboss:domain:undertow:1.0">
            <buffer-cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10"/>
        <server name="default-server">
            <http-listener name="default" socket-binding="http" />
            <host name="default-host" alias="localhost">
                <location name="/" handler="welcome-content" />
        <servlet-container name="default" default-buffer-cache="default" stack-trace-on-error="local-only" >
            <file name="welcome-content" path="${jboss.home.dir}/welcome-content" directory-listing="true"/>

Dependencies on other subsystems:

IO Subsystem

Buffer cache configuration

The buffer cache is used for caching content, such as static files. Multiple buffer caches can be configured, which allows for separate servers to use different sized caches.

Buffers are allocated in regions, and are of a fixed size. If you are caching many small files then using a smaller buffer size will be better.

The total amount of space used can be calculated by multiplying the buffer size by the number of buffers per region by the maximum number of regions.

    <buffer-cache name="default" buffer-size="1024" buffers-per-region="1024" max-regions="10"/>




The size of the buffers. Smaller buffers allow space to be utilised more effectively


The numbers of buffers per region


The maximum number of regions. This controls the maximum amount of memory that can be used for caching

Server configuration

A server represents an instance of Undertow. Basically this consists of a set of connectors and some configured handlers.

<server name="default-server" default-host="default-host" servlet-container="default" >




the virtual host that will be used if an incoming request as no Host: header


the servlet container that will be used by this server, unless is is explicitly overriden by the deployment

Connector configuration

Undertow provides HTTP, HTTPS and AJP connectors, which are configured per server.

Common settings

The following settings are common to all connectors:




The socket binding to use. This determines the address and port the listener listens on.


A reference to an XNIO worker, as defined in the IO subsystem. The worker that is in use controls the IO and blocking thread pool.


A reference to a buffer pool as defined in the IO subsystem. These buffers are used internally to read and write requests. In general these should be at least 8k, unless you are in a memory constrained environment.


If the connector is enabled.


The maximum size of incoming post requests that is allowed.


If responses to HTTP pipelined requests should be buffered, and send out in a single write. This can improve performance if HTTP pipe lining is in use and responses are small.


The maximum size of a HTTP header block that is allowed. Responses with to much data in their header block will have the request terminated and a bad request response send.


The maximum number of query or path parameters that are allowed. This limit exists to prevent hash collision based DOS attacks.


The maximum number of headers that are allowed. This limit exists to prevent hash collision based DOS attacks.


The maximum number of cookies that are allowed. This limit exists to prevent hash collision based DOS attacks.


Set this to true if you want the server to decode percent encoded slash characters. This is probably a bad idea, as it can have security implications, due to different servers interpreting the slash differently. Only enable this if you have a legacy application that requires it.


If the URL should be decoded. If this is not set to true then percent encoded characters in the URL will be left as is.


The charset to decode the URL to.


If the 'Connection: keep-alive' header should be added to all responses, even if not required by spec.

HTTP Connector

<http-listener name="default" socket-binding="http"  />




If this is set to true then the HTTP listener will read a client certificate from the SSL_CLIENT_CERT header. This allows client cert authentication to be used, even if the server does not have a direct SSL connection to the end user. This should only be enabled for servers behind a proxy that has been configured to always set these headers.


The socket binding to redirect requests that require security too.


If this is enabled then the X-Forwarded-For and X-Forwarded-Proto headers will be used to determine the peer address. This allows applications that are behind a proxy to see the real address of the client, rather than the address of the proxy.

HTTPS listener

Https listener provides secure access to the server. The most important configuration option is security realm which defines SSL secure context.

<https-listener name="default" socket-binding="https" security-realm="ssl-realm" />




The security realm to use for the SSL configuration. See Security realm examples for how to configure it: Examples


One of either NOT_REQUESTED, REQUESTED or REQUIRED. If client cert auth is in use this should be either REQUESTED or REQUIRED.


A list of cypher suit names that are allowed.

AJP listener

<ajp-listener name="default" socket-binding="ajp" />

Host configuration

The host element corresponds to a virtual host.




The virtual host name


A whitespace separated list of additional host names that should be matched


The name of a deployment that should be used to serve up requests that do not match anything.

Servlet container configuration

The servlet-container element corresponds to an instance of an Undertow Servlet container. Most servers will only need a single servlet container, however there may be cases where it makes sense to define multiple containers (in particular if you want applications to be isolated, so they cannot dispatch to each other using the RequestDispatcher. You can also use multiple Servlet containers to serve different applications from the same context path on different virtual hosts).




The Servlet specification requires applications to only wrap the request/response using wrapper classes that extend from the ServletRequestWrapper and ServletResponseWrapper classes. If this is set to true then this restriction is relaxed.


The buffer cache that is used to cache static resources in the default Servlet.


Can be either all, none, or local-only. When set to none Undertow will never display stack traces. When set to All Undertow will always display them (not recommended for production use). When set to local-only Undertow will only display them for requests from local addresses, where there are no headers to indicate that the request has been proxied. Note that this feature means that the Undertow error page will be displayed instead of the default error page specified in web.xml.


The default encoding to use for requests and responses.


If this is true then the default encoding will be the same as that used by the listener that received the request.

JSP configuration

Session Cookie Configuration

This allows you to change the attributes of the session cookie.




The cookie name


The cookie domain


The cookie comment


If the cookie is HTTP only


If the cookie is marked secure


The max age of the cookie

Persistent Session Configuration

Persistent sessions allow session data to be saved across redeploys and restarts. This feature is enabled by adding the persistent-sessions element to the server config. This is mostly intended to be a development time feature.

If the path is not specified then session data is stored in memory, and will only be persistent across redeploys, rather than restarts.




The path to the persistent sessions data


The location that the path is relevant to

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 13:40:35 UTC, last content change 2016-12-09 04:02:30 UTC.