Skip to end of metadata
Go to start of metadata

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:

Basic subsystem configuration example:

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.

Attribute Description
buffer-size The size of the buffers. Smaller buffers allow space to be utilised more effectively
buffers-per-region The numbers of buffers per region
max-regions 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.

Attribute Description
default-host the virtual host that will be used if an incoming request as no Host: header
servlet-container 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:

Attribute Description
socket-binding The socket binding to use. This determines the address and port the listener listens on.
worker 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.
buffer-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.
enabled If the connector is enabled.
max-post-size The maximum size of incoming post requests that is allowed.
buffer-pipelined-data 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.
max-header-size 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.
max-parameters The maximum number of query or path parameters that are allowed. This limit exists to prevent hash collision based DOS attacks.
max-headers The maximum number of headers that are allowed. This limit exists to prevent hash collision based DOS attacks.
max-cookies The maximum number of cookies that are allowed. This limit exists to prevent hash collision based DOS attacks.
allow-encoded-slash 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.
decode-url 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.
url-charset The charset to decode the URL to.
always-set-keep-alive If the 'Connection: keep-alive' header should be added to all responses, even if not required by spec.
HTTP Connector
Attribute Description
certificate-forwarding 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.
redirect-socket The socket binding to redirect requests that require security too.
proxy-address-forwarding 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.

Attribute Description
security-realm The security realm to use for the SSL configuration. See Security realm examples for how to configure it: Examples
verify-client One of either NOT_REQUESTED, REQUESTED or REQUIRED. If client cert auth is in use this should be either REQUESTED or REQUIRED.
enabled-cipher-suites A list of cypher suit names that are allowed.
AJP listener

Host configuration

The host element corresponds to a virtual host.

Attribute Description
name The virtual host name
alias A whitespace separated list of additional host names that should be matched
default-web-module 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).

Attribute Description
allow-non-standard-wrappers 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.
default-buffer-cache The buffer cache that is used to cache static resources in the default Servlet.
stack-trace-on-error 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.
default-encoding The default encoding to use for requests and responses.
use-listener-encoding 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.

Attribute Description
name The cookie name
domain The cookie domain
comment The cookie comment
http-only If the cookie is HTTP only
secure If the cookie is marked secure
max-age 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.

Attribute Description
path The path to the persistent sessions data
relative-to The location that the path is relevant to
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. May 12, 2014

    When you define a new host and no handler, wildfly will use some other handler (e.g. the welcome-content handler) from a different host.

  2. May 11, 2014

    Hi, is there any way to config "max-post-size" in web admin console(9990)?