Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 17. Configuring the Web Server (Undertow)

17.1. Undertow Subsystem Overview

Important

In JBoss EAP 7, the undertow subsystem takes the place of the web subsystem from previous versions of JBoss EAP.

The undertow subsystem allows you to configure the web server and servlet container settings. It implements the Java Servlet 3.1 Specification as well as websockets and supports HTTP Upgrade and using high performance non-blocking handlers in servlet deployments. The undertow subsystem also has the ability to act as a high performance reverse proxy which supports mod_cluster.

Within the undertow subsystem, there are five main components to configure:

Note

While JBoss EAP does offer the ability to update the configuration for each of these components, the default configuration is suitable for most use cases and provides reasonable performance settings.

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
      </host>
  </server>
  <servlet-container name="default">
      <jsp-config/>
      <websockets/>
  </servlet-container>
  <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
  </handlers>
  <filters>
      <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
      <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
  </filters>
</subsystem>
Important

The undertow subsystem also relies on the io subsystem to provide XNIO workers and buffer pools. The io subsystem is configured separately and provides a default configuration which should give optimal performance in most cases.

Note

Compared to the web subsystem in previous JBoss EAP releases, the undertow subsystem in JBoss EAP 7 has different default behaviors of HTTP methods.

17.2. Configuring Buffer Caches

The buffer cache is used to cache static resources. JBoss EAP enables multiple caches to be configured and referenced by deployments, allowing different deployments to use different cache sizes. Buffers are allocated in regions and are a fixed size. 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. The default size of a buffer cache is 10MB.

JBoss EAP provides a single cache by default:

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  ....
</subsystem>

Updating an Existing Buffer Cache

To update an existing buffer cache:

/subsystem=undertow/buffer-cache=default/:write-attribute(name=buffer-size,value=2048)
reload

Creating a New Buffer Cache

To create a new buffer cache:

/subsystem=undertow/buffer-cache=new-buffer:add

Deleting a Buffer Cache

To delete a buffer cache:

/subsystem=undertow/buffer-cache=new-buffer:remove
reload

For a full list of the attributes available for configuring buffer caches, please see the Undertow Subsystem Attributes section.

17.3. Configuring a Server

A server represents an instance of Undertow and consists of several elements:

  • host
  • http-listener
  • https-listener
  • ajp-listener

The host element provides a virtual host configuration while the three listeners provide connections of that type to the Undertow instance.

Note

Multiple servers may be configured, which allow deployments and servers to be completely isolated. This may be useful in certain scenarios such as multi-tenant environments

JBoss EAP provides a server by default:

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
      </host>
  </server>
  ...
</subsystem>

Updating an Existing Server

To update an existing server:

/subsystem=undertow/server=default-server:write-attribute(name=default-host,value=default-host)
reload

Creating a New Server

To create a new server:

/subsystem=undertow/server=new-server:add
reload

Deleting a Server

To delete a server:

/subsystem=undertow/server=new-server:remove
reload

For a full list of the attributes available for configuring servers, see the Undertow Subsystem Attributes section.

17.4. Configuring a Servlet Container

A servlet container provides all servlet, JSP and websocket-related configuration, including session-related configuration. While most servers will only need a single servlet container, it is possible to configure multiple servlet containers by adding an additional servlet-container element. Having multiple servlet containers enables behavior such as allowing multiple deployments to be deployed to the same context path on different virtual hosts.

Note

Much of the configuration provided in by servlet container can be individually overridden by deployed applications using their web.xml file.

JBoss EAP provides a servlet container by default:

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
    ...
  </server>
  <servlet-container name="default">
      <jsp-config/>
      <websockets/>
  </servlet-container>
...
</subsystem>

Updating an Existing Servlet Container

To update an existing servlet container:

/subsystem=undertow/servlet-container=default:write-attribute(name=ignore-flush,value=true)
reload

Creating a New Servlet Container

To create a new servlet container:

/subsystem=undertow/servlet-container=new-servlet-container:add
reload

Deleting a Servlet Container

To delete a servlet container:

/subsystem=undertow/servlet-container=new-servlet-container:remove
reload

For a full list of the attributes available for configuring servlet containers, see the Undertow Subsystem Attributes section.

17.5. Configuring Handlers

JBoss EAP allows for two types of handlers to be configured:

  • file handlers
  • reverse-proxy handlers

File handlers serve static files. Each file handler must be attached to a location in a virtual host. Reverse-proxy handlers allow JBoss EAP to serve as a high performance reverse-proxy.

JBoss EAP provides a file handler by default:

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
      ...
  </server>
  <servlet-container name="default">
      ...
  </servlet-container>
  <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
  </handlers>
  ...
</subsystem>

Using WebDAV for Static Resources

Previous versions of JBoss EAP allowed for using WebDAV with the web subsystem, by way of the WebdavServlet, to host static resources and enable additional HTTP methods for accessing and manipulating those files. In JBoss EAP 7, the undertow subsystem does provide a mechanism for serving static files using a file handler, but the undertow subsystem does not support WebDAV. If you want to use WebDAV with JBoss EAP 7, you can write a custom WebDAV servlet.

Updating an Existing File Handler

To update an existing file handler:

/subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=case-sensitive,value=true)
reload

Creating a New File Handler

To create a new file handler:

/subsystem=undertow/configuration=handler/file=new-file-handler:add(path="${jboss.home.dir}/welcome-content")

Deleting a File Handler

To delete a file handler

/subsystem=undertow/configuration=handler/file=new-file-handler:remove
reload

For a full list of the attributes available for configuring handlers, see the Undertow Subsystem Attributes section.

17.6. Configuring Filters

A filter enables some aspect of a request to be modified and can use predicates to control when a filter executes. Some common use cases for filters include setting headers or doing GZIP compression.

Note

A filter is functionally equivalent to a global valve used in previous versions of JBoss EAP.

The following types of filters can be defined:

  • custom-filter
  • error-page
  • expression-filter
  • gzip
  • mod-cluster
  • request-limit
  • response-header
  • rewrite

JBoss EAP provides two filters by default:

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  <buffer-cache name="default"/>
  <server name="default-server">
    ...
  </server>
  <servlet-container name="default">
    ...
  </servlet-container>
  <handlers>
      ...
  </handlers>
  <filters>
      <response-header name="server-header" header-name="Server" header-value="JBoss-EAP/7"/>
      <response-header name="x-powered-by-header" header-name="X-Powered-By" header-value="Undertow/1"/>
  </filters>
</subsystem>

Updating an Existing Filter

To update an existing filter:

/subsystem=undertow/configuration=filter/response-header=server-header:write-attribute(name=header-value,value="JBoss-EAP")
reload

Creating a New Filter

To create a new filter:

/subsystem=undertow/configuration=filter/response-header=new-response-header:add(header-name=new-response-header,header-value="My Value")

Deleting a Filter

To delete a filter:

/subsystem=undertow/configuration=filter/response-header=new-response-header:remove
reload

For a full list of the attributes available for configuring filters, see the Undertow Subsystem Attributes section.

17.7. Configure the Default Welcome Web Application

JBoss EAP includes a default Welcome application, which displays at the root context on port 8080 by default.

There is a default server preconfigured in Undertow that serves up the welcome content.

Default Undertow Subsystem Configuration

<subsystem xmlns="urn:jboss:domain:undertow:3.1">
  ...
  <server name="default-server">
      <http-listener name="default" socket-binding="http" redirect-socket="https"/>
      <host name="default-host" alias="localhost">
          <location name="/" handler="welcome-content"/>
          <filter-ref name="server-header"/>
          <filter-ref name="x-powered-by-header"/>
      </host>
  </server>
  ...
  <handlers>
      <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
  </handlers>
  ...
</subsystem>

The default server (default-server) has a default host (default-host) configured. The default host is configured to handle requests to the server’s root, using the <location> element, with the welcome-content file handler. The welcome-content handler serves up the content in the location specified in the path property.

This default Welcome application can be replaced with your own web application. This can be configured in one of two ways:

You can also disable the welcome content.

Changing the welcome-content File Handler

Modify the existing welcome-content file handler’s path to point to the new deployment.

/subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=path,value="/path/to/content")
Note

Alternatively, you could create a different file handler to be used by the server’s root.

/subsystem=undertow/configuration=handler/file=NEW_FILE_HANDLER:add(path="/path/to/content")
/subsystem=undertow/server=default-server/host=default-host/location=\/:write-attribute(name=handler,value=NEW_FILE_HANDLER)

Reload the server for the changes to take effect.

reload

Changing the default-web-module

Map a deployed web application to the server’s root.

/subsystem=undertow/server=default-server/host=default-host:write-attribute(name=default-web-module,value=hello.war)

Reload the server for the changes to take effect.

reload

Disabling the Default Welcome Web Application

Disable the welcome application by removing the location entry (/) for the default-host.

/subsystem=undertow/server=default-server/host=default-host/location=\/:remove

Reload the server for the changes to take effect.

reload

17.8. Configuring HTTPS

For more details on configuring HTTPS for use with both web applications as well as the management interfaces please see the How to Configure Server Security Guide.

17.9. Configuring HTTP Session Timeout

The HTTP session timeout defines the period of inactive time needed to declare an HTTP session invalid. For example, a user accesses an application deployed to JBoss EAP which creates an HTTP session. If that user then attempts to access that application again after the HTTP session timeout, the original HTTP session will be invalidated and the user will be forced to create a new HTTP session. This may result in the loss of unpersisted data or the user having to re-authenticate.

The HTTP session timeout is configured in an application’s web.xml file, but a default HTTP session timeout can be specified within JBoss EAP. The server’s timeout value will apply to all deployed applications, but an application’s web.xml will override the server’s value.

The server value is specified in the default-session-timeout property which is found in the servlet-container section of the undertow subsystem. The value of default-session-timeout is specified in minutes and the default 30.

Configuring the Default Session Timeout

To configure the default-session-timeout:

/subsystem=undertow/servlet-container=default:write-attribute(name=default-session-timeout, value=60)
reload
Important

Changing the HTTP session timeout requires that all affected JBoss EAP instances be restarted. Until that is done, the original HTTP session timeout value applies.

17.10. Configuring HTTP-Only Session Management Cookies

Session management cookies can be accessed by both HTTP APIs and non-HTTP APIs such as JavaScript. JBoss EAP offers the ability to send the HttpOnly header as part of the Set-Cookie response header to the client, usually a browser. In supported browsers, enabling this header tells the browser that it should prevent accessing session management cookies through non-HTTP APIs. Restricting session management cookies to only HTTP APIs can help to mitigate the threat of session cookie theft via cross-site scripting attacks. To enable this behavior, the http-only attribute should be set to true.

Important

Using the HttpOnly header does not actually prevent cross-site scripting attacks by itself, it merely notifies the browser. The browser must also support HttpOnly for this behavior to take affect.

Important

Using the http-only attribute only applies the restriction to session management cookies and not other browser cookies.

The http-only attribute is set in two places in the undertow subsystem:

  • In the servlet container as a session cookie setting
  • In the host section of the server as a single sign-on property

To configure the host-only property for the servlet container session cookie:

/subsystem=undertow/servlet-container=default/setting=session-cookie:add
/subsystem=undertow/servlet-container=default/setting=session-cookie:write-attribute(name=http-only,value=true)
reload

Configuring host-only for the Host Single Sign-On

To configure the host-only property for the host single sign-on:

/subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:add
/subsystem=undertow/server=default-server/host=default-host/setting=single-sign-on:write-attribute(name=http-only,value=true)
reload

17.11. Configuring HTTP/2

Undertow allows for the use of the HTTP/2 standard, which reduces latency by compressing headers and multiplexing many streams over the same TCP connection. It also provides the ability for a server to push resources to the client before it has requested them, leading to faster page loads. Undertow is also compatible with SPDY, the predecessor to HTTP/2, in order to support clients that have not yet updated to the new specification.

Important

HTTP/2 is supported as Technology Preview only for JBoss EAP 7.0 and will only work with browsers that also support the HTTP/2 standard.

Important

Using HTTP/2 requires the use of Java 8 as well as setting up ALPN on the classpath. This is due to the fact that HTTP/2 requires a TLS stack that supports ALPN, which is not provided by the default installation of Java 8.

17.11.1. Configuring Undertow to use HTTP/2

To configure Undertow to use HTTP/2, the following must be done:

Configure Undertow to use HTTPS

Please see the How to Configure Server Security Guide for configuring Undertow to use HTTPS for web applications.

Note

It is possible to use HTTP/2 without using HTTPS, in other words, only plain HTTP using HTTP upgrade. In that case, you do not need to install ALPN and can simply enable HTTP/2 in Undertow:

/subsystem=undertow/server=default-server/http-listener=default:write-attribute(name=enable-http2,value=true)
Download the ALPN JAR

Start by determining the specific version of Java you have. Run the following command from the terminal to print the version of Java you have installed:

java -version

Based on your version, consult this page to determine the correct version of the ALPN JAR to download from this page. For example, if you were running Java version 1.8.0_51, you would use ALPN version 8.1.4.v20150727 and download alpn-boot-8.1.4.v20150727.jar.

Add the ALPN JAR to the Boot Classpath

Once you have downloaded the correct version of the ALPN JAR, copy it to EAP_HOME/bin. You also must add the following to bin/standalone.conf (or bin/domain.conf if running in a managed domain) replacing $JBOSS_HOME and $ALPN_VERSION with the appropriate values.

JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:$JBOSS_HOME/bin/alpn-boot-$ALPN_VERSION.jar"
Important

You must restart JBoss EAP for the classpath changes to take affect.

Enable HTTP/2 in the HTTPS Listener

To enable the HTTPS listener in Undertow to use HTTP/2, you must set the enable-http2 attribute to true:

/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enable-http2,value=true)
Verify HTTP/2 is Being Used

To verify that Undertow is using HTTP/2, you will need to inspect the headers coming from Undertow. Navigate to your JBoss EAP instance using https, for example https://localhost:8443, and use your browser’s developer tools to inspect the headers. Some browsers, for example Google Chrome, will show HTTP/2 pseudo headers (:path, :authority, :method and :scheme) when using HTTP/2, while other browsers, for example Firefox and Safari, will report the status or version of the header as HTTP/2.0.

17.12. Configuring a RequestDumping Handler

The RequestDumping handler (io.undertow.server.handlers.RequestDumpingHandler) logs the details of a request and corresponding response objects handled by Undertow within JBoss EAP.

Important

While this handler can be useful for debugging, it may also log sensitive information. Please keep this in mind when enabling this handler.

Note

The RequestDumping handler replaces the RequestDumperValve from previous versions of JBoss EAP.

You can configure a RequestDumping handler at either at the server level directly in JBoss EAP or within an individual application.

17.12.1. Configuring a RequestDumping Handler on the Server

A RequestDumping handler should be configured as an expression filter. To configure a RequestDumping handler as an expression filter, you need to do the following:

Create a new Expression Filter with the RequestDumping Handler
/subsystem=undertow/configuration=filter/expression-filter=requestDumperExpression:add(expression="dump-request")
Enable the Expression Filter in the Undertow Web Server
/subsystem=undertow/server=default-server/host=default-host/filter-ref=requestDumperExpression:add
Important

All requests and corresponding responses handled by the Undertow web server will be logged when enabling the RequestDumping handler as a expression filter in this manner.

Configuring a RequestDumping Handler for Specific URLs

In addition to logging all requests, you can also use an expression filter to only log requests and corresponding responses for specific URLs. This can be accomplished using a predicate in your expression such as path, path-prefix, or path-suffix. For example, if you want to log all requests and corresponding responses to /myApplication/test, you can use the expression "path(/myApplication/test) -> dump-request" instead of the expression "dump-request" when creating your expression filter. This will only direct requests with a path exactly matching /myApplication/test to the RequestDumping handler.

17.12.2. Configuring a RequestDumping Handler within an Application

In addition to configuring a RequestDumping handler at the server, you can also configure it within individual applications. This will limit the scope of the handler to only that specific application. A RequestDumping handler should be configured in WEB-INF/undertow-handlers.conf.

To configure the RequestDumping handler in WEB-INF/undertow-handlers.conf to log all requests and corresponding responses for this application, add the following expression to WEB-INF/undertow-handlers.conf:

Example WEB-INF/undertow-handlers.conf

dump-request

To configure the RequestDumping handler in WEB-INF/undertow-handlers.conf to only log requests and corresponding responses to specific URLs within this application, you can use a predicate in your expression such as path, path-prefix, or path-suffix. For example, to log all requests and corresponding responses to test in your application, the following expression with the path predicate could be used:

Example WEB-INF/undertow-handlers.conf

path(/test) -> dump-request

Note

When using the predicates such as path, path-prefix, or path-suffix in expressions defined in the application’s WEB-INF/undertow-handlers.conf, the value used will be relative to the context root of the application. For example, if the application’s context root is myApplication with an expression path(/test) -> dump-request configured in WEB-INF/undertow-handlers.conf, it will only log requests and corresponding responses to /myApplication/test.