Red Hat SummitDieser Inhalt ist in der von Ihnen ausgewählten Sprache nicht verfügbar.
Chapter 16. Configuring the Web Server (Undertow)
16.1. Undertow Subsystem Overview
In JBoss EAP 7, the undertow subsystem takes the place of the web subsystem from JBoss EAP 6.
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:
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:4.0">
<buffer-cache name="default"/>
<server name="default-server">
<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
<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>
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.
Compared to the web subsystem in JBoss EAP 6, the undertow subsystem in JBoss EAP 7 has different default behaviors of HTTP methods.
16.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:4.0"> <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.
16.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.
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:4.0">
<buffer-cache name="default"/>
<server name="default-server">
<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
<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>
The following examples show how to configure a server using the management CLI. You can also configure a server using the management console by navigating to Configuration
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.
16.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.
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:4.0">
<buffer-cache name="default"/>
<server name="default-server">
...
</server>
<servlet-container name="default">
<jsp-config/>
<websockets/>
</servlet-container>
...
</subsystem>
The following examples show how to configure a servlet container using the management CLI. You can also configure a servlet container using the management console by navigating to Configuration
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.
16.5. Configuring a Servlet Extension
Servlet extensions allow you to hook into the servlet deployment process and modify aspects of a servlet deployment. This can be useful in cases where you need to add additional authentication mechanisms to a deployment or use native Undertow handlers as part of a servlet deployment.
To create a custom servlet extension, it is necessary to implement the io.undertow.servlet.ServletExtension interface and then add the name of your implementation class to the META-INF/services/io.undertow.servlet.ServletExtension file in the deployment. You also need to include the compiled class file of the ServletExtension implementation. When Undertow deploys the servlet, it loads all the services from the deployments class loader and then invokes their handleDeployment methods.
An Undertow DeploymentInfo structure, which contains a complete and mutable description of the deployment, is passed to this method. You can modify this structure to change any aspect of the deployment.
The DeploymentInfo structure is the same structure that is used by the embedded API, so in effect a ServletExtension has the same amount of flexibility that you have when using Undertow in embedded mode.
16.6. 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:4.0">
<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")
If you set a file handler’s path directly to a file instead of a directory, any location elements that reference that file handler must not end with a forward slash (/). Otherwise, the server will return a 404 - Not Found response.
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.
16.7. 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.
A filter is functionally equivalent to a global valve used in JBoss EAP 6.
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:4.0">
<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>
The following examples show how to configure a filter using the management CLI. You can also configure a filter using the management console by navigating to Configuration
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.
16.7.1. Configuring the buffer-request Handler
A request from the client or the browser consists of two parts: the header and the body. In a typical situation, the header and the body are sent to JBoss EAP without any delays in between. However, if the header is sent first and then after few seconds, the body is sent, there is a delay sending the complete request. This scenario creates a thread in JBoss EAP to show as waiting to execute the complete request.
The delay caused in sending the header and the body of the request can be corrected using the buffer-request handler. The buffer-request handler attempts to consume the request from a non-blocking IO thread before allocating it to a worker thread. When no buffer-request handler is added, the thread allocation to the worker thread happens directly. However, when the buffer-request handler is added, the handler attempts to read the amount of data that it can buffer in a non-blocking manner using the IO thread before allocating it to the worker thread.
You can use the following management CLI commands to configure the buffer-request handler:
/subsystem=undertow/configuration=filter/expression-filter=buf:add(expression="buffer-request(buffers=1)") /subsystem=undertow/server=default-server/host=default-host/filter-ref=buf:add
There is a limit to the size of the buffer requests that can be processed. This limit is determined by a combination of the buffer size and the total number of buffers, as shown in the equation below.
Total_size = num_buffers × buffer_size
In the equation above:
-
Total_sizeis the size of data that will be buffered before the request is dispatched to a worker thread. -
num_buffersis the number of buffers. The number of buffers is set by thebuffersparameter on the handler. -
buffer_sizeis the size of each buffer. The buffer size is set in theiosubsystem, and is 16KB by default per request.
Avoid configuring very large buffer requests, or else you might run out of memory.
16.8. 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:4.0">
...
<server name="default-server">
<http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true"/>
<https-listener name="https" socket-binding="https" security-realm="ApplicationRealm" enable-http2="true"/>
<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.
Change the welcome-content File Handler
Modify the existing
welcome-contentfile handler’s path to point to the new deployment./subsystem=undertow/configuration=handler/file=welcome-content:write-attribute(name=path,value="/path/to/content")NoteAlternatively, 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
Change 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
Disable the Default Welcome Web Application
Disable the welcome application by removing the
locationentry/for thedefault-host./subsystem=undertow/server=default-server/host=default-host/location=\/:remove
Reload the server for the changes to take effect.
reload
16.9. Configuring HTTPS
For information on configuring HTTPS for web applications, see Configure One-way and Two-way SSL/TLS for Applications in How to Configure Server Security.
For information on configuring HTTPS for use with the JBoss EAP management interfaces, see How to Secure the Management Interfaces in How to Configure Server Security.
16.10. 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 reauthenticate.
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 is 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
16.11. 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.
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.
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
Configuring host-only for the Servlet Container Session Cookie
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
16.12. 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.
To configure Undertow to use HTTP/2, enable the HTTPS listener in Undertow to use HTTP/2 by setting the enable-http2 attribute to true:
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=enable-http2,value=true)
For more information on the HTTPS listener and configuring Undertow to use HTTPS for web applications, see Configure One-way and Two-way SSL/TLS for Applications in How to Configure Server Security.
When using HTTP/2 over a secured TLS connection, a TLS stack that supports ALPN TLS protocol extension is required. Since ALPN is not available for Java 8, its implementation is introduced directly into JBoss EAP 7.1 with dependencies on Java internals. This ALPN implementation thus works only with Oracle and OpenJDK. It does not work with IBM Java. There is also a slight risk that it might break with some Java updates. Red Hat strongly recommends to utilize ALPN TLS protocol extension support from the OpenSSL provider in JBoss EAP 7.1, with OpenSSL libraries that implement ALPN capability. The supported OpenSSL libraries are the ones from JBoss Core Services, installed and configured.
Instructions for installing OpenSSL are available in Install OpenSSL from JBoss Core Services.
There are multiple ways in which you can configure JBoss EAP to use OpenSSL:
You can reconfigure the
elytronsubsystem to give OpenSSL priority so that it is used in all cases by default.NoteAlthough OpenSSL is installed in the
elytronsubsystem, it is not the default TLS provider./subsystem=elytron:write-attribute(name=initial-providers, value=combined-providers) /subsystem=elytron:undefine-attribute(name=final-providers) reload
In the
elytronsubsystem, the OpenSSL provider can also be specified on thessl-contextresource. That way, the OpenSSL protocol can be selected on a case-by-case basis instead of using the default priority.To create the
ssl-contextresource and use the OpenSSL libraries in your Elytron-based SSL/TLS configuration, use the following command./subsystem=elytron/server-ssl-context=httpsSSC:add(key-manager=localhost-manager, trust-manager=ca-manager, provider-name=openssl) reload
To use the OpenSSL libraries in your legacy
securitysubsystem SSL/TLS configuration:/core-service=management/security-realm=ApplicationRealm/server-identity=ssl:write-attribute(name=protocol,value=openssl.TLSv1.2) reload
The different OpenSSL protocols that can be used are:
- openssl.TLS
- openssl.TLSv1
- openssl.TLSv1.1
- openssl.TLSv1.2
JBoss EAP will automatically try to search for the OpenSSL libraries on the system and use them. You can also specify a custom OpenSSL libraries location by using the org.wildfly.openssl.path property during JBoss EAP startup. Only the OpenSSL library version 1.0.2 or greater provided by JBoss Core Services is supported. OpenSSL usage with JBoss EAP on HP-UX is NOT supported.
If OpenSSL is loaded properly, you will see a message in the server.log during JBoss EAP startup, similar to:
15:37:59,814 INFO [org.wildfly.openssl.SSL] (MSC service thread 1-7) WFOPENSSL0002 OpenSSL Version OpenSSL 1.0.2k-fips 23 Mar 2017
HTTP/2 will only work with browsers that also support the HTTP/2 standard.
If you want to use OpenSSL based security in JBoss EAP 7.1 on Solaris 10 platform, you must set the LD_LIBRARY_PATH environment variable for JBoss EAP to find the proper location of the libgcc library. Red Hat only provides a 64 bit version of wildfly-openssl libraries for Solaris, so you should add /usr/sfw/lib/64 into the LD_LIBRARY_PATH so that appropriate system libraries are utilized during the OpenSSL initialization and JBoss EAP boot.
This modification is necessary only for Solaris 10 platform. Solaris 11 works without such modification.
In order to utilize HTTP/2 with the elytron subsystem, you will need to ensure that the configured ssl-context in the https-listener of the Undertow is configured as modifiable. This can be achieved by setting the wrap attribute of the appropriate server-ssl-context to false. By default, the wrap attribute is set to false. This is required by Undertow to make modifications in the ssl-context about the ALPN. If the provided ssl-context is not writable, ALPN cannot be used and the connection falls back to HTTP/1.1.
Most modern browsers enforce HTTP/2 over a secured TLS connection, known as h2 and may not support HTTP/2 over plain HTTP, known as h2c. It is still possible to configure JBoss EAP to use HTTP/2 with h2c, in other words, without using HTTPS and only using plain HTTP with HTTP upgrade. In that case, you can simply enable HTTP/2 in the HTTP listener Undertow:
/subsystem=undertow/server=default-server/http-listener=default: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, such as :path, :authority, :method and :scheme, when using HTTP/2. Other browsers, for example Firefox and Safari, will report the status or version of the header as HTTP/2.0.
16.13. 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.
While this handler can be useful for debugging, it may also log sensitive information. Please keep this in mind when enabling this handler.
The RequestDumping handler replaces the RequestDumperValve from JBoss EAP 6.
You can configure a RequestDumping handler at either at the server level directly in JBoss EAP or within an individual application.
16.13.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
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.
16.13.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
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.
16.14. Tuning the Undertow Subsystem
For tips on optimizing performance for the undertow subsystem, see the Undertow Subsystem Tuning section of the Performance Tuning Guide.
