jetty.project Documentation

Jetty will automatically bind this transaction manager to the web application's JNDI namespace at java:comp/UserTransaction.

[[link]]
=== org.eclipse.jetty.plus.jndi.Link

Usually, the name you provide for the org.eclipse.jetty.plus.jndi.Resource is the same name you reference in web.xml.
This ensures that the two are linked together and thus accessible to your web application.

However, if the names cannot be the same, then it is possible to effectively alias one to another using an org.eclipse.jetty.plus.jndi.Link.

Suppose you have a definition for a Datasource named jdbc/workforce in a Jetty context XML file, but your web.xml wants to link to a <resource-ref> named jdbc/employees, and you cannot edit the web.xml.
You can create a WEB-INF/jetty-{ee-all}-env.xml file with an org.eclipse.jetty.plus.jndi.Link that ties together the names jdbc/workforce and jdbc/employees:

The Jetty Context XML file defines jdbc/workforce:

[,xml,subs=attributes+] Copy Chapter

The web.xml refers to it as jdbc/employees:

[,xml,subs=attributes+] Copy Chapter

Create a WEB-INF/jetty-{ee-all}-env.xml file with a org.eclipse.jetty.plus.jndi.Link to link these names together:

[,xml,subs=attributes+] Copy Chapter

[[xml]]
=== Jetty XML files

You can define naming resources in three places:

Server XML file::
Resources defined in a server XML file are <<scope,scoped>> at the JVM, org.eclipse.jetty.server.Server or xref:deploy/index.adoc[environment] level.
Note that the classes for the resource must be accessible at the time that the XML is processed.
+
For example, environment resources that depend on an external library should be defined in an XML file that is processed after the environment class-path has been properly configured.
This can be achieved by using the {ee-all}-ext module, with the external library in the $JETTY_BASE/lib/{ee-all}/ext/ directory, or with a xref:modules/custom.adoc[custom module] that contains an [environment] clause and a [lib] clause.

Context XML file::
Resources defined in a context XML file should be <<scope,scoped>> at the level of the web application to which they apply (it is possible to use a less strict scoping level of Server or JVM, but not recommended).
As the Context XML file executes before the web application classes are available, the classes for your resource must be external to the web application, either on the container or on environment class-path.

WEB-INF/jetty-{ee-all}-env.xml::
Resources defined in a WEB-INF/jetty-{ee-all}-env.xml file are <<scope,scoped>> to the web application in which the file resides.
The resources defined by this file may use classes from inside your web application.

WEB-INF/jetty-{ee-all}-web.xml::
Resources defined in a WEB-INF/jetty-{ee-all}-web.xml file are <<scope,scoped>> to the web application in which the file resides.
The resources defined by this file may use classes from inside your web application.
This file is processed after WEB-INF/jetty-{ee-all}-env.xml.

[[scope]]
=== Resource scoping

Resources within Jetty are defined in different scopes, in increasing order of restrictiveness:

JVM scope:: The resource is unique across the JVM instance, and is visible to all application code. This scope is represented by a `null` first parameter to the resource definition. For example: + [,xml,subs=attributes+] Copy Chapter

Environment scope:: The resource is unique within a Jetty _environment_. The scope is represented by referencing the name of the environment as the first parameter to the resource definition. For example: + [,xml,subs=attributes+] Copy Chapter

Web application scope:: The resource is unique to the `org.eclipse.jetty.{ee-all}.webapp.WebAppContext` instance, and is only visible to that application. The scope is represented by referencing the context instance as the first parameter to the resource definition. For example: + [,xml,subs=attributes+] Copy Chapter

Documentation Jetty Modules Operations Guide Pages Jsf Taglibs Index (`documentation/jetty/modules/operations-guide/pages/jsf-taglibs/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Jakarta Faces TagLibs

If you want to use Jakarta Faces with your Jakarta EE web application, you should enable the xref:modules/standard.adoc#eeN-ext[{ee-all}-ext] Jetty module, and copy the relevant Jakarta Faces API jar files, and the Jakarta Faces implementation jar files of your choice into the $JETTY_BASE/lib/{ee-all}/ext directory created by the {ee-all}-ext module you enabled.

Then you will need to tell Jetty which of those jar files contains the +*.tld+ files.
To accomplish that, you need to specify either the name of the file or a pattern that matches the name of the file(s) as the org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern context attribute.
You will need to preserve the existing value of the attribute, and add in your extra pattern.

Below you can find an example of using a Jetty context XML file to add a pattern to match files starting with jsf-, which contain the +*.tld+ files:

[,xml,subs=+attributes] Copy Chapter

Documentation Jetty Modules Operations Guide Pages Jsp Index (`documentation/jetty/modules/operations-guide/pages/jsp/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Java Server Pages

Jetty supports JSP via the {ee-all}-jsp modules, which are based on Apache Jasper:

[source,subs=attributes+] Copy Chapter

include::{jetty-home}/modules/ee11-jsp.mod[] Copy Chapter

Logging has been bridged to Jetty logging, so you can enable logging for the org.apache.jasper package, subpackages and classes as usual.

== Configuration of the JSP Servlet

The org.eclipse.jetty.jsp.JettyJspServlet is the servlet responsible for serving JSPs.

It is configured as the default jsp servlet in the $JETTY_HOME/etc/webdefault.xml file.
Notice that Jetty identifies the jsp servlet by the presence of the id="jsp" attribute in the <servlet> declaration.

That file maps the org.eclipse.jetty.jsp.JettyJspServlet to the following partial urls:

• +*.jsp+
• +*.jspf+
• +*.jspx+
• +*.xsp+
• +*.JSP+
• +*.JSPF+
• +*.JSPX+
• +*.XSP+

You can change to a different servlet, change or add ````s or add extra <servlet-mapping>s in your web.xml file.

Here's an example of adding an `` to augment the definitions from the standard webdefault.xml file:

[,xml] Copy Chapter

keepgenerated 
true

Another element you might consider adding to the default setup is async-supported:

[,xml] Copy Chapter

There are many configuration parameters for the Apache Jasper JSP Servlet, here are some of them:

.JSP Servlet Parameters
[cols=",,,",options="header"]
|===
|init param |Description |Default |webdefault.xml

|checkInterval |If non-zero and development is false, background jsp recompilation is enabled. This value is the interval in seconds between background recompile checks.
|0 |–
|classpath |The classpath is dynamically generated if the context has a URL classloader. The org.apache.catalina.jsp_classpath
context attribute is used to add to the classpath, but if this is not set, this classpath configuration item is added to the classpath instead.` |- |–

|classdebuginfo |Include debugging info in class file. |true |–

|compilerClassName |If not set, defaults to the Eclipse jdt compiler. |- |–

|compiler |Used if the Eclipse jdt compiler cannot be found on the
classpath. It is the classname of a compiler that Ant should invoke. |–
|–

|compilerTargetVM |Target vm to compile for. |1.8 |1.8

|compilerSourceVM |Sets source compliance level for the jdt compiler.
|1.8 |1.8

|development |If true recompilation checks occur at the frequency governed by modificationTestInterval. |true |–

|displaySourceFragment |Should a source fragment be included in
exception messages |true |–

|dumpSmap |Dump SMAP JSR45 info to a file. |false |–

|enablePooling |Determines whether tag handler pooling is enabled. |true |–

|engineOptionsClass |Allows specifying the Options class used to
configure Jasper. If not present, the default EmbeddedServletOptions
will be used. |- |–

|errorOnUseBeanInvalidClassAttribute |Should Jasper issue an error when
the value of the class attribute in an useBean action is not a valid
bean class |true |–

|fork |Only relevant if you use Ant to compile JSPs: by default Jetty will use the Eclipse jdt compiler.|true |-

|genStrAsCharArray |Option for generating Strings as char arrays. |false |–

|ieClassId |The class-id value to be sent to Internet Explorer when
using jsp:plugin tags. |clsid:8AD9C840-044E-11D1-B3E9-00805F499D93 |–

|javaEncoding |Pass through the encoding to use for the compilation.
|UTF8 |–

|jspIdleTimeout |The amount of time in seconds a JSP can be idle before
it is unloaded. A value of zero or less indicates never unload. |-1 |–

|keepgenerated |Do you want to keep the generated Java files around?
|true |–

|mappedFile |Support for mapped Files. Generates a servlet that has a
print statement per line of the JSP file |true |–

|maxLoadedJsps |The maximum number of JSPs that will be loaded for a web
application. If more than this number of JSPs are loaded, the least
recently used JSPs will be unloaded so that the number of JSPs loaded at
any one time does not exceed this limit. A value of zero or less
indicates no limit. |-1 |–

|modificationTestInterval |If development=true, interval between
recompilation checks, triggered by a request. |4 |–

|quoteAttributeEL | When EL is used in an attribute value on a JSP page, should the rules for quoting of attributes described in JSP.1.6 be applied to the expression
|true |-

|recompileOnFail |If a JSP compilation fails should the
modificationTestInterval be ignored and the next access trigger a
re-compilation attempt? Used in development mode only and is disabled by
default as compilation may be expensive and could lead to excessive
resource usage. |false |–

|scratchDir |Directory where servlets are generated. The default is the value of the context attribute javax.servlet.context.tempdir, or the system property java.io.tmpdir if the context attribute is not set. |– |–

|strictQuoteEscaping |Should the quote escaping required by section JSP.1.6 of the JSP specification be applied to scriplet expression.
|true|-

|suppressSmap |Generation of SMAP info for JSR45 debugging. |false |–

|trimSpaces |Should template text that consists entirely of whitespace be removed from the output (true), replaced with a single space (single) or left unchanged (false)? Note that if a JSP page or tag file specifies a trimDirectiveWhitespaces value of true, that will take precedence over this configuration setting for that page/tag.
trimmed? |false |–

|xpoweredBy |Generate an X-Powered-By response header. |false |false

|===

[NOTE]

If the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as Jasper is inconsistent in its parameter naming strategy.

Documentation Jetty Modules Operations Guide Pages Jstl Index (`documentation/jetty/modules/operations-guide/pages/jstl/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= JavaServer Pages Standard Tag Libraries

The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the {ee-all}-jstl modules:

[source,subs=attributes+] Copy Chapter

include::{jetty-home}/modules/ee11-jstl.mod[] Copy Chapter

When enabled, Jetty will make the JSTL tags available for your web applications.

Documentation Jetty Modules Operations Guide Pages Keystore Index (`documentation/jetty/modules/operations-guide/pages/keystore/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Configuring SSL/TLS KeyStores

A KeyStore is a file on the file system that contains a private key and a public certificate, along with the certificate chain of the certificate authorities that issued the certificate.
The private key, the public certificate and the certificate chain, but more generally the items present in a KeyStore, are typically referred to as "cryptographic material".

Keystores may encode the cryptographic material with different encodings, the most common being https://en.wikipedia.org/wiki/PKCS_12[PKCS12], and are typically protected by a password.

Refer to the xref:protocols/index.adoc#ssl[secure protocols section] for more information about how to configure a secure connector using a KeyStore.

[[create]]
== Creating a KeyStore

KeyStores are created with the JDK tool $JAVA_HOME/bin/keytool.

The following command creates a KeyStore file containing a private key and a self-signed certificate:

[source] Copy Chapter

keytool
-genkeypair <1>
-alias mykey <2>
-validity 90 <3>
-keyalg RSA <4>
-keysize 2048 <5>
-keystore /path/to/keystore.p12 <6>
-storetype pkcs12 <7>
-dname "CN=domain.com, OU=Unit, O=Company, L=City, S=State, C=Country" <8>
-ext san=dns:www.domain.com,dns:domain.org <9>
-v <10>

<1> the command to generate a key and certificate pair
<2> the alias name of the key and certificate pair
<3> specifies the number of days after which the certificate expires
<4> the algorithm must be RSA (the DSA algorithm does not work for web sites)
<5> indicates the strength of the key
<6> the KeyStore file
<7> the KeyStore type, stick with the standard PKCS12
<8> the distinguished name (more below) -- customize it with your values for CN, OU, O, L, S and C
<9> the extension with the subject alternative names (more below)
<10> verbose output

The command prompts for the KeyStore password that you must choose to protect the access to the KeyStore.

[IMPORTANT]

The important parts of the command above are the Common Name (CN) part of the distinguished name, and the subject alternative names (SAN).

The CN value must be the main domain you own and that you want to use for your web applications.
For example, if you have bought domains domain.com and domain.org, you want to specify CN=domain.com as your main domain.

Furthermore, to specify additional domains or subdomains within the same certificate, you must specify the SAN extension.
In the example above, san=dns:www.domain.com,dns:domain.org specifies www.domain.com and domain.org as alternative names for your web applications (that you can configure using xref:deploy/index.adoc#virtual-hosts[virtual hosts]).

In rare cases, you may want to specify IP addresses, rather than domains, in the SAN extension. The syntax in such case is `san=ip:127.0.0.1,ip:[::1]`, which specifies as subject alternative names IPv4 `127.0.0.1` and IPv6 `[::1]`.

[[create-many]]
=== KeyStores with Multiple Entries

A single KeyStore may contain multiple key/certificate pairs.
This is useful when you need to support multiple domains on the same Jetty server (typically accomplished using xref:deploy/index.adoc#virtual-hosts[virtual hosts]).

You can create multiple key/certificate pairs as detailed in the <<create,previous section>>, provided that you assign each one to a different alias.

Compliant TLS clients will send the xref:protocols/index.adoc#ssl-sni[TLS SNI extension] when creating new connections, and Jetty will automatically choose the right certificate by matching the SNI name sent by the client with the CN or SAN of certificates present in the KeyStore.

[[csr]]
== Creating a Certificate Signing Request

Self-signed certificates are not trusted by browsers and generic clients: you need to establish a trust chain by having your self-signed certificate signed by a certificate authority (CA).

Browsers and generic clients (e.g. Java clients) have an internal list of trusted certificate authorities root certificates; they use these trusted certificates to verify the certificate they received from the server when they connect to your web applications.

To have your self-signed certificate signed by a certificate authority you first need to produce a certificate signing request (CSR):

[source] Copy Chapter

keytool
-certreq <1>
-file domain.com.csr <2>
-keystore keystore.p12 <3>

<1> the command to generate a certificate signing request
<2> the file to save the CSR
<3> the keystore that contains the self-signed certificate

Then, you have to send the CSR file to the certificate authority of your choice, and wait for their reply (they will probably require a proof that you really own the domains indicated in your certificate).

Eventually, the certificate authority will reply to you with one or more files containing the CA certificate chain, and your certificate signed by their certificate chain.

[[csr-import]]
== Importing the Signed Certificate

The file you receive from the CA is typically in PEM format, and you must import it back into the same KeyStore file you used to generate the CSR.
You must import both the certificate chain and your signed certificate.

First, import the certificate chain:

[source] Copy Chapter

keytool
-importcert <1>
-alias ca <2>
-file chain_from_ca.pem <3>
-keystore keystore.p12 <4>
-trustcacerts <5>
-v <6>

<1> the command to import certificates
<2> use the ca alias to differentiate from the alias of the server certificate
<3> the file containing the certificate chain received from the CA
<4> your KeyStore file
<5> specify that you trust CA certificates
<6> verbose output

Then, import the signed certificate:

keytool
-importcert
-file signed_certificate.pem
-keystore keystore.p12
-trustcacerts
-v

Now you have a trusted certificate in your KeyStore that you can use for the domains of your web applications.

// TODO: add a section about renewal?

Refer to the section about configuring xref:protocols/index.adoc#ssl[secure protocols] to configure the secure connector with your newly created KeyStore.

[[client-authn]]
== Creating a KeyStore for Client Certificate Authentication

For the majority of secure web sites, it is the client (typically the browser) that validates the certificate sent by the server (by verifying the certificate chain).
This is the server domain certificate.

However, the TLS protocol supports a mutual authentication mode where also the client must send a certificate to the server, that the server validates.

You typically want to sign the client certificate(s) with a server certificate that you control, and you must distribute the client certificate(s) to all the clients that need it, and redistribute the client certificates when they expire.
The server authentication certificate may be different from the server domain certificate, but it's typically stored in the same KeyStore for simplicity (although under a different alias).

First, you want to create the private key and server authentication certificate that you will use to sign client certificates:

[source] Copy Chapter

keytool
-genkeypair
-alias server_authn <1>
-validity 90
-keyalg RSA
-keysize 2048
-keystore keystore.p12 <2>
-storetype pkcs12
-dname "CN=server_authn, OU=Unit, O=Company, L=City, S=State, C=Country" <3>
-ext bc=ca:true <4>
-v

<1> use the server_authn alias to differentiate from the alias of the server certificate
<2> the KeyStore file
<3> the CN is not that important, since this certificate will not be validated by clients
<4> the extension with the basic constraints (more below)

IMPORTANT: The important difference with the <<create,creation of a server certificate>> is the basic constraints extension (bc) that indicates that this certificates acts as a certificate authority (ca:true).

Now you want to export both the private key and server authentication certificate.
Unfortunately, the keytool program cannot export private keys, so you need to use a different command line program like openssl, or a graphical program like https://keystore-explorer.org/[KeyStore Explorer].

Let's use openssl to export the server authentication private key:

openssl
pkcs12
-in keystore.p12
-nodes
-nocerts
-out server_authn.key

Now let's export the server authentication certificate:

keytool
-exportcert
-keystore keystore.p12
-rfc
-file server_authn.crt
-v

At this point, you want to create a client KeyStore, so that you can sign the client certificate with the server authentication cryptographic material:

[source] Copy Chapter

keytool
-genkeypair
-validity 90
-keyalg RSA
-keysize 2048
-keystore client_keystore.p12 <1>
-storetype pkcs12
-dname "CN=client, OU=Unit, O=Company, L=City, S=State, C=Country" <2>
-v

<1> the client KeyStore file
<2> the CN is not that important, since it will not be validated by the server

Now produce a certificate signing request (CSR):

keytool
-certreq
-file client.csr
-keystore client_keystore.p12

Now you need to sign the CSR, but again the keytool program does not have this functionality, and you must resort again to use openssl:

openssl
x509
-req
-days 90
-in client.csr
-CA server_authn.crt
-CAkey server_authn.key
-CAcreateserial
-sha256
-out signed.crt

Now you need to import the server authentication certificate and the signed client certificate into the client KeyStore.

First, the server authentication certificate:

keytool
-importcert
-alias ca
-file server_authn.crt
-keystore client_keystore.p12
-v

Then, the signed client certificate:

keytool
-importcert
-file signed.crt
-keystore client_keystore.p12
-v

Now you can distribute client_keystore.p12 to your client(s).

// TODO: add a section about renewal?

Refer to the section about configuring xref:protocols/index.adoc#ssl[secure protocols] to configure the secure connector to require client authentication.

Documentation Jetty Modules Operations Guide Pages Modules Custom (`documentation/jetty/modules/operations-guide/pages/modules/custom.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Custom Jetty Modules

In addition to the modules that come packaged with Jetty, you can create your own custom modules.

NOTE: Make sure you have read the xref:modules/index.adoc[Jetty modules section] if you are not familiar with the concepts used in this section.

Custom modules can be used for a number of reasons -- they can extend Jetty features, or add new features, or make additional libraries available to the server, etc.

[[modify]]
== Modifying an Existing Module

The standard Jetty modules typically come with a number of configurable properties that can be easily customized without the need of writing a custom module.

However, there may be cases where the customization is more complex than a simple property, and a custom module is necessary.

For example, let's assume that you want to modify the order of the TLS cipher suites offered by the server when a client connects, using the https://www.openssl.org/docs/man1.1.0/man1/ciphers.html[OpenSSL cipher list format].

The Jetty class that handles the TLS configuration is SslContextFactory, and it already has a method setCipherComparator(Comparator<String>); however, you need to pass your custom implementation, which cannot be represented with a simple module property.

The SslContextFactory component is already allocated by the standard Jetty module ssl, so what you need to do is the following:

• Write the custom cipher Comparator and package it into a +*.jar+ file (exercise left to reader).
• Write a custom Jetty XML file that calls the SslContextFactory.setCipherComparator(Comparator<String>) method.
• Write a custom Jetty module file that depends on the standard ssl module.

Start with the custom Jetty XML file, $JETTY_BASE/etc/custom-ssl.xml:

.custom-ssl.xml [,xml] Copy Chapter

<Default>ECDH+AESGCM:ECDH+AES256:!aNULL:!MD5:!DSS:!ADH</Default>
      
    </Arg>
  </New>
</Set>

CAUTION: The cipher list used above may not be secure -- it's just an example.

Then write your custom module in the $JETTY_BASE/modules/custom-ssl.mod file:

.custom-ssl.mod [source] Copy Chapter

[description]
Customizes the standard ssl module.

[tags] <1>
acme

[depends] <2>
ssl

[lib] <3>
lib/custom-cipher-comparator.jar

[xml] <4>
etc/custom-ssl.xml

[ini-template] <5>

The cipher list in OpenSSL format. Copy Chapter

com.acme.ssl.cipherList=ECDH+AESGCM:ECDH+AES256:!aNULL:!MD5:!DSS:!ADH

<1> A tag that characterizes this custom module (see xref:modules/index.adoc#directive-tags[here]).
<2> This custom module depends on the standard ssl module.
<3> The custom cipher comparator class is compiled and packaged into this +*.jar+ file.
<4> The custom Jetty XML file from above.
<5> The text that will be copied in the custom-ssl.ini file when this custom module will be enabled.

Now you can xref:start/index.adoc#configure-enable[enable] the custom module with the following command issued from the $JETTY_BASE directory:

$ java -jar $JETTY_HOME/start.jar --add-modules=https,custom-ssl Copy Chapter

The command above will produce the following $JETTY_BASE directory structure:

[source,subs=+quotes] Copy Chapter

$JETTY_BASE
├── etc
│ └── custom-ssl.xml
├── modules
│ └── custom-ssl.mod
├── resources
│ └── jetty-logging.properties
└── start.d
├── https.ini
└── ##custom-ssl.ini##

In the custom XML file you have used a custom module property to parametrize your custom cipher comparator.
This custom module property was then referenced in the [ini-template] section of the custom module file, so that when the custom module is enabled, a correspondent custom-ssl.ini file is created.

In this way, updating the cipher list won't require you to update the XML file, but just the custom-ssl.ini file.

[[create]]
== Creating a New Module

In the cases where you need to enhance Jetty with a custom functionality, you can write a new Jetty module that provides it.

For example, let's assume that you need to add a custom auditing component that integrates with the auditing tools used by your company.
This custom auditing component should measure the HTTP request processing times and record them (how they are recorded is irrelevant here -- could be in a local log file or sent via network to an external service).

The Jetty libraries already provide a way to measure HTTP request processing times via xref:programming-guide:server/http.adoc#handler-use-events[EventsHandler]: you write a custom EventsHandler subclass that overrides the methods corresponding to the events you are interested in.

The steps to create a Jetty module are similar to those necessary to <<modify,modify an existing module>>:

• Write the auditing component and package it into a +*.jar+ file.
• Write a custom Jetty XML file that wires the auditing component to the Handler tree.
• Write a custom Jetty module file that puts everything together.

Let's start with the auditing component, sketched below:

[,java] Copy Chapter

package com.acme.audit;

public class AuditingEventsHandler extends EventsHandler {
// Auditing is implemented here.

} Copy Chapter

Let's assume that this class is compiled and packaged into acme-audit.jar, and that it has a dependency on acme-util.jar.
Both +*.jar+ files will be put in the $JETTY_BASE/lib/ directory.

Next, let's write the Jetty XML file that wires the auditing component to the ServerConnector, $JETTY_BASE/etc/acme-audit.xml:

.acme-audit.xml [,xml,options=nowrap] Copy Chapter

</Set>
    </New>
  </Arg>
</Call>

The last step is to create the custom Jetty module file for the auditing component, $JETTY_BASE/modules/acme-audit.mod:

.acme-audit.mod Copy Chapter

[description]
Adds ACME auditing to the Jetty Server.

[tags] <1>
acme
audit

[depends] <2>
server

[libs] <3>
lib/acme-audit.jar
lib/acme-util.jar

[xml] <4>
etc/acme-audit.xml

[ini-template] <5>

An auditing property. Copy Chapter

com.acme.audit.some.property=42

<1> The tags that characterize this custom module (see xref:modules/index.adoc#directive-tags[here]).
<2> This custom module depends on the standard server module.
<3> The +*.jar+ files that contains the custom auditing component, and its dependencies.
<4> The custom Jetty XML file from above.
<5> The text that will be copied in the acme-audit.ini file when this custom module will be enabled.

Now you can xref:start/index.adoc#configure-enable[enable] the custom auditing module with the following command issued from the $JETTY_BASE directory:

[source] Copy Chapter

$ java -jar $JETTY_HOME/start.jar --add-modules=http,acme-audit Copy Chapter

The command above will produce the following $JETTY_BASE directory structure:

[source,subs=+quotes] Copy Chapter

$JETTY_BASE
├── etc
│ └── acme-audit.xml
├── modules
│ └── acme-audit.mod
├── resources
│ └── jetty-logging.properties
└── start.d
├── http.ini
└── ##acme-audit.ini##

Enabling the custom auditing component will create the $JETTY_BASE/start.d/acme-audit.ini module configuration file that you can edit to configure auditing properties.

Documentation Jetty Modules Operations Guide Pages Modules Index (`documentation/jetty/modules/operations-guide/pages/modules/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Jetty Modules

A Jetty module provides one or more Java components that work together to implement one or more features.
Such features could be listening for clear-text HTTP/1.1 requests, exposing Jetty components to JMX, provide hot-deployment of web applications, etc.

Every Jetty feature is provided by a Jetty module.

A Jetty module is defined in a <name>.mod file, where <name> is the module name (see also the <<names,section about module names>>).

Jetty module files are read from the typical xref:start/index.adoc#configure[configuration source directories], under the modules/ subdirectory; from higher priority to lower priority:

• The $JETTY_BASE/modules/ directory.
• If a directory is specified with the --add-config-dir option, its modules/ subdirectory.
• The $JETTY_HOME/modules/ directory.

The standard Jetty modules that Jetty provides out-of-the-box are under $JETTY_HOME/modules/.

xref:modules/custom.adoc[Custom Jetty modules] should be put under $JETTY_BASE/modules/.

[[names]]
== Module Names

A Jetty module has a unique name.
The module name is by default derived from the file name, so module file acme.mod identifies a module named acme.

However, a module file may specify a <<directive-provides,+[provides]+>> directive for a virtual module, so that many modules may provide a different implementation for the same feature.

For example, among the standard modules provided by Jetty, the server module depends on the logging module, but there is no correspondent logging.mod file.

However, the logging-jetty.mod file has, among others, this section:

.logging-jetty.mod Copy Chapter

[provides] logging|default Copy Chapter

This section means that the logging-jetty.mod file provides the virtual module logging, and it is the default provider.

The logging-log4j2.mod file has a similar section:

.logging-log4j2.mod Copy Chapter

[provides] logging Copy Chapter

If there are no enabled modules that provide the logging virtual module, either explicitly or transitively, then the default provider is used, in this case logging-jetty.mod.

Otherwise, a module that provides the logging virtual module is explicitly or transitively enabled, and the default provider is not used.

[[components]]
== Module Components

A Jetty module may provide one or more Java components that implement a feature.
These Java components are nothing more than regular Java classes that are instantiated and configured via xref:xml/index.adoc[Jetty XML] files.

The Jetty XML file of a Jetty module may instantiate and assemble together its own components, or reference existing components from other Jetty modules to enhance or reconfigure them.

The Jetty module's XML files are read from the typical xref:start/index.adoc#configure[configuration source directories], under the etc/ subdirectory; from higher priority to lower priority:

• The $JETTY_BASE/etc/ directory.
• If a directory is specified with the --add-config-dir option, its etc/ subdirectory.
• The $JETTY_HOME/etc/ directory.

The standard Jetty modules XML files that Jetty provides out-of-the-box are under $JETTY_HOME/etc/.

For example, a Jetty XML file that allocates Jetty's QueuedThreadPool could be as simple as:

[,xml] .jetty-threadpool.xml Copy Chapter

</Set>

Note how the Jetty XML file above is allocating (with the <New> element) a QueuedThreadPool instance, giving it the unique id of threadPool (so that other modules can reference it, if they need to).
It is then calling the setter method QueuedThreadPool.setMaxThreads(int) with the value defined by the <> jetty.threadPool.maxThreads; if the property value is not defined, it will have the default value of 256.

This is nothing more than Java code in XML format with configurable properties support that can be leveraged by the xref:start/index.adoc[Jetty start mechanism].

The Jetty module's XML files make easy to instantiate and assemble Java components (just write the equivalent Java code in XML format), and make easy to configure them by declaring module properties that can be easily customized elsewhere (for example, in +*.ini+ files as described in xref:start/index.adoc#configure-enable[this section], or on the command line as described in xref:start/index.adoc#start[this section]).

[IMPORTANT]

Remember that the standard Jetty XML files in $JETTY_HOME/etc/ should not be modified.

Even if you need to modify a standard Jetty component, write a new Jetty XML file, save it under `$JETTY_BASE/etc/`, and create a xref:modules/custom.adoc[custom Jetty module] so that it gets processed when Jetty starts.

[[properties]]
== Module Properties

A Jetty module property is declared in the <<components,module XML file(s)>> via the `` element.
Modules properties are used to parametrize Jetty components so that you can customize their values when Jetty starts, rather than hard-coding it in the XML files.

NOTE: You can declare your own properties, but the +jetty.*+ namespace is reserved.

A module property can be given a value in a Jetty module [ini] section (see <<directive-ini,here>>), in a +*.ini+ file as described in xref:start/index.adoc#configure-enable[this section], or on the command line as described in xref:start/index.adoc#start[this section].

The syntax to specify a property value is the following:

=:: Sets the property value unconditionally. +=:: Appends the value to the existing value. This is useful to append a value to properties that accept a comma separated list of values, for example: + Copy Chapter

jetty.webapp.addProtectedClasses+=,com.acme. Copy Chapter

// TODO: check what happens if the property is empty and +=,value is done: is the comma stripped? If so add a sentence about this. ?=:: Sets the property value only if it is not already set. This is useful to define default values, for example for "version" properties, where the "version" property can be explicitly configured to a newer version, but if it is not explicitly configured it will have a default version (see also xref:start/index.adoc#configure-custom-module[here]). For example: + Copy Chapter

conscrypt.version?=2.5.1 jetty.sslContext.provider?=Conscrypt Copy Chapter

[[directives]]
== Module Directives

Lines that start with # are comments.

[[directive-description]]
=== [description]

A text that describes the module.

This text will be shown by the xref:start/index.adoc#configure[Jetty start mechanism] when using the --list-modules command.

[[directive-tags]]
=== [tags]

A list of words that characterize the module.

Modules that have the same tags will be shown by the Jetty start mechanism when using the --list-modules=<tag> command.

.example.mod Copy Chapter

[tags] demo webapp jsp Copy Chapter

[[directive-provides]]
=== [provides]

A module name with an optional default specifier.

As explained in the <<names,module name section>>, there can be many module files each providing a different implementation for the same feature.

The format is:

[provides] [|default] Copy Chapter

where the |default part is optional and specifies that the module is the default provider.

[[directive-depends]]
=== [depends]

A list of module names that this module depends on.

For example, the standard module http depends on module server.
Enabling the http module also enables, transitively, the server module, since the http module cannot work without the server module; when the server module is transitively enabled, the modules it depends on will be transitively enabled, and so on recursively.

The [depends] directive establishes a https://en.wikipedia.org/wiki/Partially_ordered_set[_partial order_] relationship among modules so that enabled modules can be sorted and organized in a graph.
Circular dependencies are not allowed.

The order of the enabled modules is used to determine the processing of the configuration, for example the order of processing of the <<directive-files,+[files]+>> section, the order of processing of XML files defined in the <<directive-xml,+[xml]+>> section, etc.

[[directive-after]]
=== [after]

This directive indicates that this module is ordered after the listed module names, if they are enabled.

For example, module https is [after] module http2.
Enabling the https module does not enable the http2 module.

However, if the http2 module is enabled (explicitly or transitively), then the https module is <<directive-depends,sorted>> after the http2 module.
In this way, you are guaranteed that the https module is processed after the http2 module.

[[directive-before]]
=== [before]

This directive indicates that this module is ordered before the listed module names, if they are enabled.

For example, module test-keystore is [before] module ssl-context.
Enabling the test-keystore module does not enable the ssl-context module.

This directive is used to create a prerequisite module without the need to modify the depends directive of an existing module.

For example, you want to create a custom org.eclipse.jetty.server.Server subclass instance to be used by the standard server module, but without modifying the existing server.mod file nor the jetty.xml file that server.mod uses.

This can be achieved by creating the following custom-server xref:modules/custom.adoc[Jetty custom module]:

.custom-server.mod Copy Chapter

[description]
This module creates a custom Server subclass instance.

[before]
server

[xml] etc/custom-server.xml Copy Chapter

The custom-server.xml file is the following:

.custom-server.xml [,xml] Copy Chapter

The presence of the [before] directive in custom-server.mod causes the processing of the custom-server.xml file to happen before the processing of the standard jetty.xml file referenced by the standard server.mod Jetty module.

Thus, the instance assigned to the Server identifier is your custom com.acme.server.CustomJettyServer instance from the custom-server.xml file; this instance is then used while processing the jetty.xml file.

[[directive-files]]
=== [files]

A list of paths (directories and/or files) that are necessary for the module, created or resolved when the module is enabled.

Each path may be of the following types:

Path Name:: A path name representing a file, or a directory if the path name ends with `/`, such as `webapps/`. The file or directory will be created relative to `$JETTY_BASE`, if not already present. + For example: + Copy Chapter

[files] logs/ Copy Chapter

Maven Artifact:: An URI representing a Maven artifact to be downloaded from Maven Central, if not already present. Property expansion is supported. + The format is: + Copy Chapter

[files] maven:////[/]| Copy Chapter

where `` is optional, and `` after the `|` is the path under `$JETTY_BASE` where the downloaded file should be saved. + For example: + [,options=nowrap] Copy Chapter

[files] maven://org.postgresql/postgresql/${postgresql-version}|lib/postgresql-${postgresql-version}.jar Copy Chapter

BaseHome:: An URI representing a `$JETTY_HOME` resource to be copied in `$JETTY_BASE`, if not already present. URIs of this type are typically only used by standard Jetty modules; custom modules should not need to use it. + The format is: + Copy Chapter

[files] basehome:| Copy Chapter

For example: + Copy Chapter

[files] basehome:modules/demo.d/demo-moved-context.xml|webapps/demo-moved-context.xml Copy Chapter

HTTP URL::

An `http://` or `https://` URL to be downloaded, if not already present. + The format is: + Copy Chapter

[files] | Copy Chapter

For example: + Copy Chapter

[files] https://acme.com/favicon.ico|webapps/acme/favicon.ico Copy Chapter

[[directive-libs]]
=== [libs]

A list of paths, relative to the xref:start/index.adoc#configure[configuration source directories], of +*.jar+ library files and/or directories that are added to the server class-path (or module-path when xref:start/start-jpms.adoc[running in JPMS mode]).

The [libs] section if often used in conjunction with the [files] section.

For example:

[files]
maven://org.postgresql/postgresql/${postgresql-version}|lib/postgresql-${postgresql-version}.jar

[libs] lib/postgresql-${postgresql-version}.jar Copy Chapter

The postgresql-<version>.jar artifact is downloaded from Maven Central, if not already present, into the $JETTY_BASE/lib/ directory when the module is enabled.

When Jetty starts, the $JETTY_BASE/lib/postgresql-<version>.jar will be in the server class-path (or module-path).

[[directive-xml]]
=== [xml]

A list of paths, relative to the xref:start/index.adoc#configure[configuration source directories], of Jetty +*.xml+ files that are passed as program arguments to be processed when Jetty starts (see the xref:start/index.adoc#start-xml[section about assembling Jetty components]).

Jetty XML files are read from the typical xref:start/index.adoc#configure[configuration source directories], under the etc/ subdirectory.
Standard Jetty XML files are under $JETTY_HOME/etc/, while custom Jetty XML files are typically under $JETTY_BASE/etc/.

For example:

[xml] etc/custom/components.xml Copy Chapter

[[directive-ini]]
=== [ini]

A list of program arguments to pass to the command line when Jetty is started.

The program arguments may include any command line option (see xref:start/index.adoc#reference[here] for the list of command line options), <> and/or <<components,module XML files>>.

A property defined in the [ini] section is available in the +*.mod+ module file for property expansion, for example:

[ini]
postgresql-version?=42.6.0

[lib] lib/postgresql-${postgresql-version}.jar Copy Chapter

In the example above, the [lib] section contains $\{postgresql-version}, a reference to property postgresql-version whose value is defined in the [ini] section.
The expression ${} expands the property replacing the expression with the property value.

See also the xref:start/start-jpms.adoc[JPMS section] for additional examples about the [ini] section.

[[directive-ini-template]]
=== [ini-template]

A list of properties to be copied in the +*.ini+ file generated when xref:start/index.adoc#configure-enable[the module is enabled], either explicitly or transitively.

The list of properties is derived from the <<components,module XML file(s)>> that declare them.

The properties are typically assigned their default value and commented out, so that it is evident which properties have been uncommented and customized with a non-default value.

[[directive-exec]]
=== [exec]

A list of JVM command line options and/or system properties passed to a forked JVM.

When the [exec] section is present, the JVM running the Jetty start mechanism will fork another JVM, passing the JVM command line options and system properties listed in the [exec] sections of the enabled modules.

This is necessary because JVM options such as -Xmx (that specifies the max JVM heap size) cannot be changed in a running JVM.
For an example, see xref:start/index.adoc#configure-custom-module-exec[this section].

You can avoid that the Jetty start mechanism forks the second JVM, as explained in xref:start/index.adoc#configure-dry-run[this section].

[[directive-jpms]]
=== [jpms]

A list of JVM command line options related to the Java Module System.

This section is processed only when Jetty is xref:start/start-jpms.adoc[started in JPMS mode].

The directives are:

add-modules:: Equivalent to the JVM option `--add-modules`. The format is: + Copy Chapter

[jpms] add-modules: (,)* Copy Chapter

where module is a JPMS module name.

patch-module:: Equivalent to the JVM option `--patch-module`. The format is: + Copy Chapter

[jpms] patch-module: =(:)* Copy Chapter

where module is a JPMS module name.

add-opens:: Equivalent to the JVM option `--add-opens`. The format is: + Copy Chapter

[jpms] add-opens: /=(,)* Copy Chapter

where module and target-module are a JPMS module names.

add-exports:: Equivalent to the JVM option `--add-exports`. The format is: + Copy Chapter

[jpms] add-exports: /=(,)* Copy Chapter

where module and target-module are a JPMS module names.

add-reads:: Equivalent to the JVM option `--add-exports`. The format is: + Copy Chapter

[jpms] add-reads: =(,)* Copy Chapter

where module and target-module are a JPMS module names.

[[directive-license]]
=== [license]

The license under which the module is released.

A Jetty module may be released under a license that is different from Jetty's, or use libraries that require end-users to accept their licenses in order to be used.

You can put the license text in the [license] section, and when the Jetty module is enabled the license text will be printed on the terminal, and the user prompted to accept the license.
If the user does not accept the license, the module will not be enabled.

For example:

[license] Acme Project is an open source project hosted on GitHub and released under the Apache 2.0 license. https://www.apache.org/licenses/LICENSE-2.0.txt Copy Chapter

[[directive-version]]
=== [version]

The minimum Jetty version for which this module is valid.

For example, a module may only be valid for Jetty 10 and later, but not for earlier Jetty versions (because it references components that have been introduced in Jetty 10).

For example:

[version] 10.0 Copy Chapter

A Jetty module with such a section will only work for Jetty 10.0.x or later.

Documentation Jetty Modules Operations Guide Pages Modules Standard (`documentation/jetty/modules/operations-guide/pages/modules/standard.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Standard Modules

[[alpn]]
== Module alpn

The alpn module enables support for the ALPN negotiation mechanism of the TLS protocol.

You can configure the list of application protocols negotiated by the ALPN mechanism, as well as the default protocol to use if the ALPN negotiation fails (for example, the client does not support ALPN).

The module properties are:

include::{jetty-home}/modules/alpn.mod[tags=documentation] Copy Chapter

[[accept-rate-limit]]
== Module accept-rate-limit

The accept-rate-limit module limits the rate of new connections accepted by the server, across all connectors.

Once the configured accept rate has been reached, Jetty will not accept more connections.
Existing, established connections will work normally.

Once accepting new connections has been suspended, Jetty will periodically check whether the rate has returned withing the limits, and if so, accepting new connections will be resumed.

This module is often used in conjunction with the xref:network-connection-limit[network-connection-limit] module.

NOTE: The number of connections seen at the JVM level may be different from the number of connections seen at the OS level.
For more information, refer to xref:programming-guide:server/http.adoc#connector-limiting[this section].

The module file is $JETTY_HOME/modules/accept-rate-limit.mod:

include::{jetty-home}/modules/accept-rate-limit.mod[tags=documentation] Copy Chapter

[[bytebufferpool]]
== Module bytebufferpool

The bytebufferpool module allows you to configure the server-wide ByteBuffer pool.
Pooling ByteBuffers results in less memory usage and less pressure on the Garbage Collector.

ByteBuffers are pooled in buckets; each bucket as a capacity that is a multiple of a capacity factor that you can configure.
For example, if a request for a ByteBuffer of capacity 2000 is requested, and the capacity factor is 1024, then the pool will allocate a buffer from the second bucket, of capacity 2048 (1024 * 2).

Applications that need to sustain many concurrent requests -- or load spikes -- may require many buffers during peak load. These buffers will remain pooled once the system transitions to a lighter load (or becomes idle), and it may be undesirable to retain a lot of memory for an idle system.

It is possible to configure the max heap memory and the max direct memory that the pool retains.
Excess buffers will not be pooled and will be eventually garbage collected.

The module file is $JETTY_HOME/modules/bytebufferpool.mod:

include::{jetty-home}/modules/bytebufferpool.mod[] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.byteBufferPool.maxHeapMemory::
This property allows you to cap the max heap memory retained by the pool.

jetty.byteBufferPool.maxDirectMemory::
This property allows you to cap the max direct memory retained by the pool.

[[compression]]
== Compression Modules

The compression modules allow you to configure server-wide request decompression and response compression by installing the org.eclipse.jetty.compression.server.CompressionHandler at the root of the Handler tree (see also xref:programming-guide:server/http.adoc#handler-use-compression[this section] for further details).

The supported algorithms are the following:

• brotli, via the <<compression-brotli,compression-brotli>> module
• gzip, via the <<compression-gzip,compression-gzip>> module
• zstandard, via the <<compression-zstandard,compression-zstandard>> module

You can explicitly enable one or more of the compression modules, or all of them with the <<compression-all,compression-all>> module.

[[compression-all]]
=== Module compression-all

This module enables request decompression and response compression for all the currently supported algorithms listed in <<compression,this section>>.

[[compression-brotli]]
=== Module compression-brotli

This module enables request decompression and response compression with the link:https://github.com/google/brotli[brotli] algorithm.

The module properties are:

include::{jetty-home}/modules/compression-brotli.mod[tags=documentation] Copy Chapter

[[compression-gzip]]
=== Module compression-gzip

This module enables request decompression and response compression with the link:https://en.wikipedia.org/wiki/Gzip[gzip] algorithm.

The module properties are:

include::{jetty-home}/modules/compression-gzip.mod[tags=documentation] Copy Chapter

[[compression-zstandard]]
=== Module compression-zstandard

This module enables request decompression and response compression with the link:https://github.com/facebook/zstd[zstdandard] algorithm.

The module properties are:

include::{jetty-home}/modules/compression-zstandard.mod[tags=documentation] Copy Chapter

[[network-connection-limit]]
== Module network-connection-limit

The network-connection-limit module limits the number of network connections accepted by the server, across all connectors.

Once the configured maximum number of network connections is reached, Jetty will not accept more network connections.
Existing, established network connections will work normally.
When existing network connections are closed, accepting new network connections will be resumed.

This module is often used in conjunction with the xref:accept-rate-limit[accept-rate-limit] module.

NOTE: The number of network connections seen at the JVM level may be different from the number of network connections seen at the OS level.
For more information, refer to xref:programming-guide:server/http.adoc#connector-limiting[this section].

The module file is $JETTY_HOME/modules/network-connection-limit.mod:

include::{jetty-home}/modules/network-connection-limit.mod[tags=documentation] Copy Chapter

[[console-capture]]
== Module console-capture

The console-capture module captures System.out and System.err output and appends it to a rolling file.

The file is rolled every day at the midnight of the configured timezone.
Old, rolled files are kept for the number of days specified by the jetty.console-capture.retainDays property.

The module properties are:

include::{jetty-home}/modules/console-capture.mod[tags=documentation] Copy Chapter

[[core-deploy]]
== Module core-deploy

The core-deploy module enables deployment of web applications that only use the Jetty Core APIs, as described in xref:deploy/index.adoc[this section].

See also the <<static-deploy,static-deploy>> module for Jetty static deployment, and the <<eeN-deploy,{ee-all}-deploy>> modules for Jakarta EE deployment environments.

[[cross-origin]]
== Module cross-origin

The cross-origin module provides support for the https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS[CORS protocol] implemented by browsers when performing cross-origin requests.

This module installs the xref:programming-guide:server/http.adoc#handler-use-cross-origin[CrossOriginHandler] in the Handler tree; CrossOriginHandler inspects cross-origin requests and adds the relevant CORS response headers.

CrossOriginHandler should be used when an application performs cross-origin requests to your domain, to protect from https://owasp.org/www-community/attacks/csrf[cross-site request forgery] attacks.

The module properties are:

include::{jetty-home}/modules/cross-origin.mod[tags=documentation] Copy Chapter

[[debuglog]]
== Module debuglog

The debuglog module logs extra information about request processing.

This module installs the DebugHandler into the handler tree and logs information into a rollover log file.
By default, the location of the log file is $JETTY_BASE/logs, although this can be configured via the jetty.debuglog.dir.
The name of the log file is of the form: yyyy_mm_dd.debug.log, for example 2024-10-01.debug.log.
All deployed contexts will write to the same log file.

Note that if a request uses asynchronous processing, the log event for the completion of handling may occur out of order with the log event for the continuation of processing.

If more precise logging of request processing is required - including well-ordered async processing events - or you wish to constrain request debug logging to particular contexts only, then configure an ee-specific DebugListener for each context instead of using this module.

The module properties are:

include::{jetty-home}/modules/debuglog.mod[tags=documentation] Copy Chapter

[[deployment-scanner]]
== Module deployment-scanner

The deployment-scanner module installs the org.eclipse.jetty.deploy.DeploymentScanner component that watches web application deploy directories for changes, to deploy/redeploy/undeploy web applications that are present in those directories.

This module is a dependency for all the deploy modules such as <<static-deploy,static-deploy>>, <<core-deploy,core-deploy>> and <<eeN-deploy,{ee-all}-deploy.

There is only one DeploymentScanner for all the deploy modules that are enabled.

The module properties are:

include::{jetty-home}/modules/deployment-scanner.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.deploy.webappsDir::
The name of the directory, or a comma-separated list of directories, that is scanned to deploy web applications.
jetty.deploy.scanInterval::
The scan period in seconds, that is how frequently the DeploymentScanner wakes up to scan the monitored directories for changes.
By default, jetty.deploy.scanInterval=0 so that hot deployment is disabled and only cold deployment is possible (see also xref:deploy/index.adoc#hot-cold[here] for more information).

[[dos]]
== Module dos

The dos module installs the org.eclipse.jetty.server.handler.DoSHandler at the root of the Handler tree.

The DoSHandler limits the rate of requests per remote client, as explained in xref:programming-guide:server/http.adoc#handler-use-dos[this section].

The module properties are:

include::{jetty-home}/modules/dos.mod[tags=documentation] Copy Chapter

[[eager-content]]
== Module eager-content

The eager-content module installs the org.eclipse.jetty.server.handler.EagerContentHandler at the root of the Handler tree.

The EagerContentHandler can eagerly load request content, asynchronously, before calling the next Handler.
For more information see xref:programming-guide:server/http.adoc#handler-use-eager[this section].

EagerContentHandler can eagerly load content for form uploads, multipart uploads and any request content, and you can configure it with different properties for these three cases.

The module properties are:

include::{jetty-home}/modules/eager-content.mod[tags=documentation] Copy Chapter

[[eeN-deploy]]
== Module {ee-all}-deploy

The {ee-all}-deploy modules enable deployment of corresponding Java/Jakarta EE web applications, as described in xref:deploy/index.adoc[this section].

Each eeN-deploy module supports the correspondent Java/Jakarta EE specification.

Multiple eeN-deploy modules may be enabled at the same time, allowing deployment of, for example, old Java EE 8 web applications alongside new Jakarta {ee-current-caps} web applications, in the same server.

The module configuration properties are nearly identical across the EE versions.
The module configuration properties for the {ee-current}-deploy Jetty module are:

[,properties,subs=+attributes] Copy Chapter

include::{jetty-home}/modules/{ee-current}-deploy.mod[tags=ini-template] Copy Chapter

See also the <<static-deploy,static-deploy>> module and the <<core-deploy,core-deploy>> module for Jetty specific deployment environments.

[[eeN-ext]]
== Module {ee-all}-ext

The {ee-all}-ext modules allow to add libraries to the environment class-path or module-path, for example to provide implementations of Jakarta APIs such as a Jakarta Mail implementation or Jakarta Transaction implementation.

The libraries must be in +*.jar+ format, and must be placed in $JETTY_BASE/lib/{ee-all}/ext.

Refer also to the server specific <<ext,ext>> module.

[[eeN-proxy]]
== Module {ee-all}-proxy

The {ee-all}-proxy module adds a simple reverse proxy service that proxies incoming requests to a backend server.
Each module targets the corresponding Jakarta EE platform version.

The module properties are:

include::{jetty-home}/modules/{ee-current}-proxy.mod[tags=documentation] Copy Chapter

Among the configurable properties, the only mandatory one is:

jetty.proxy.proxyTo::
The URI of the backend server, in absolute form, for example +http://backend:9090/path+.
+
The path in context of the incoming request is appended to the jetty.proxy.proxyTo property to obtain the URI to proxy to.
For example, for the incoming URI +http://proxy:8080/ctx/foo/bar+, the path in context (assuming the context path is /ctx) is /foo/bar, therefore the request is proxied to +http://backend:9090/path/foo/bar+.

[[eeN-webapp]]
== Module {ee-all}-webapp

The {ee-all}-webapp module adds support for Jakarta {ee-all-caps} web applications.

Multiple versions of this module exist ({ee-all}-webapp) to support each Jakarta EE platform's version of the Java Servlet specification.

The module configuration properties are identical across all versions of this module, and are as follows:

include::{jetty-home}/modules/{ee-current}-webapp.mod[tags=ini-template] Copy Chapter

Configuration of protected and hidden classes, if necessary, is explained in xref:programming-guide:server/http.adoc#handler-use-webapp-context-class-loading[this section].
Refer also to the module properties syntax, detailed xref:modules/index.adoc#properties[here].

[[ext]]
== Module ext

The ext module allows to add libraries to the server class-path or module-path, for example for custom classes that extend Jetty classes, for server-wide logging libraries, for JDBC drivers, etc.

The libraries must be in +*.jar+ format, and must be placed in $JETTY_BASE/lib/ext.

Refer also to the environment specific <<eeN-ext,{ee-all}-ext>> modules.

[[graceful]]
== Module graceful

The graceful module allows to shut down gracefully the Jetty server when it is stopped (see xref:start/index.adoc#stop[this section] for more information about stopping Jetty).

The graceful module installs the GracefulHandler at the root of the Handler tree; the GracefulHandler rejects new requests, but allows current requests to terminate within a configurable timeout, as explained in xref:programming-guide:server/http.adoc#handler-use-graceful[this section].

The module properties are:

include::{jetty-home}/modules/graceful.mod[tags=documentation] Copy Chapter

[[http]]
== Module http

The http module provides the clear-text connector and support for the clear-text HTTP/1.1 protocol, and depends on the <<server,server module>>.

The module properties to configure the clear-text connector are:

include::{jetty-home}/modules/http.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.http.port::
The network port that Jetty listens to for clear-text HTTP/1.1 connections -- default 8080.
jetty.http.idleTimeout::
The amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources -- default 30 seconds.
jetty.http.acceptors::
The number of threads that compete to accept connections -- default 1. Use -1 to let the accept heuristic decides the value; the current heuristic calculates a value based on the number of cores).
Refer to <<http-acceptors,this section>> for more information about acceptor threads.
jetty.http.selectors::
The number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value; the current heuristic calculates a value based on the number of cores).

[[http-acceptors]]
=== Configuration of Acceptors

Accepting connections from remote clients may be configured as a blocking operation, or a non-blocking operation.

When accepting connections is configured as a blocking operation (the number of acceptors is greater than zero), a thread is blocked in the accept() call until a connection is accepted, and other acceptor threads (if any) are blocked on the lock acquired by the accepting thread just before the accept() call.

When the accepting thread accepts a connection, it performs a little processing of the just accepted connection, before forwarding it to other components.

During this little processing other connections may be established; if there is only one accepting thread, the newly established connections are waiting for the accepting thread to finish the processing of the previously accepted connection and call again accept().

Servers that manage a very high number of connections that may (naturally) come and go, or that handle inefficient protocols that open and close connections very frequently (such as HTTP/1.0) may benefit of an increased number of acceptor threads, so that when one acceptor thread processes a just accepted connection, another acceptor thread can immediately take over accepting connections.

When accepting connections is configured as a non-blocking operation (the number of acceptors is zero), then the server socket is set in non-blocking mode and added to a NIO selector.
In this way, no dedicated acceptor threads exist: the work of accepting connections is performed by the selector thread.

[[http-selectors]]
=== Configuration of Selectors

Performing a NIO select() call is a blocking operation, where the selecting thread is blocked in the select() call until at least one connection is ready to be processed for an I/O operation.
There are 4 I/O operations: ready to be accepted, ready to be connected, ready to be read and ready to be written.

A single NIO selector can manage thousands of connections, with the assumption that not many of them will be ready at the same time.

For a single NIO selector, the ratio between the average number of selected connections over the total number of connections for every select() call depends heavily on the protocol but also on the application.

Multiplexed TCP protocols such as HTTP/2 tend to be busier than duplex protocols such as HTTP/1.1, leading to a higher ratio.

REST applications that exchange many little JSON messages tend to be busier than file server applications, leading to a higher ratio.

The higher the ratio, the higher the number of selectors you want to have, compatibly with the number of cores -- there is no point in having 64 selector threads on a single core hardware.

[[http2]]
== Module http2

The http2 module enables support for the secure HTTP/2 protocol.

The module properties are:

include::{jetty-home}/modules/http2.mod[tags=documentation] Copy Chapter

// tag::rate-control[]
The jetty.http2.rateControl.maxEventsPerSecond property controls the number of "bad" or "unnecessary" frames that a client may send before the server closes the connection (with code https://tools.ietf.org/html/rfc7540#section-7[`ENHANCE_YOUR_CALM`]) to avoid a denial of service.

For example, an attacker may send empty SETTINGS frames to a server in a tight loop.
While the SETTINGS frames don't change the server configuration and each of them is somehow harmless, the server will be very busy processing them because they are sent by the attacker one after the other, causing a CPU spike and eventually a denial of service (as all CPUs will be busy processing empty SETTINGS frames).

The same attack may be performed with PRIORITY frames, empty DATA frames, PING frames, etc.

[[http2c]]
== Module http2c

The http2c module enables support for the clear-text HTTP/2 protocol.

The module properties are:

include::{jetty-home}/modules/http2c.mod[tags=documentation] Copy Chapter

The jetty.http2.rateControl.maxEventsPerSecond property controls the number of "bad" or "unnecessary" frames that a client may send before the server closes the connection (with code https://tools.ietf.org/html/rfc7540#section-7[`ENHANCE_YOUR_CALM`]) to avoid a denial of service.

For example, an attacker may send empty SETTINGS frames to a server in a tight loop.
While the SETTINGS frames don't change the server configuration and each of them is somehow harmless, the server will be very busy processing them because they are sent by the attacker one after the other, causing a CPU spike and eventually a denial of service (as all CPUs will be busy processing empty SETTINGS frames).

The same attack may be performed with PRIORITY frames, empty DATA frames, PING frames, etc.

[[http3]]
== Module http3

The http3 module enables support for the HTTP/3 protocol.

Support for the QUIC protocol underlying HTTP/3 is provided by default via the http3-quiche module that uses the link:https://github.com/cloudflare/quiche[Quiche] native library.

The http3-quiche module properties are:

include::{jetty-home}/modules/http3-quiche.mod[tags=documentation] Copy Chapter

[[http-config]]
== Module http-config

The http-config module provides HTTP configuration parameters that describe the HTTP semantic, and therefore do not depend on a specific HTTP protocol version.

This module creates an instance of HttpConfiguration for clear-text HTTP.
For secure HTTP, the <<ssl,ssl>> module creates a copy of the HttpConfiguration created by this module.

The module properties are:

include::{jetty-home}/modules/http-config.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.httpConfig.requestHeaderSize::
The maximum size of the request headers, beyond which the request is rejected with the HTTP status code 431 Request Header Fields Too Large.

jetty.httpConfig.headerCacheSize::
The header cache is used when parsing HTTP/1 to more efficiently handle fields that are repeated in every request on a connection. If the server does not receive persistent connection or infrequent repeated fields, then there may be a performance gain in reducing the cache size. If large fields are frequently repeated, then a large cache may be beneficial.

jetty.httpConfig.outputAggregationSize::
The size of the buffer that aggregates response writes that are not explicitly flushed.
This is used only at the Servlet layer, to buffer writes performed with ServletOutputStream.

`jetty.httpConfig.sendServerVersion`:: Whether you want to send the `Server` header in every HTTP response: + [source,subs=attributes+] Copy Chapter

HTTP/1.1 200 OK Content-Length: 0 Server: Jetty({jetty-version}) Copy Chapter

=== Server Compliance Properties

The Jetty server strives to keep up with the latest https://en.wikipedia.org/wiki/Request_for_Comments[IETF RFC]s for compliance with internet specifications, which are periodically updated.

When possible, Jetty will support backwards compatibility by providing compliance modes that can be configured to allow violations of the current specifications that may have been allowed in obsoleted specifications.

The module properties to configure the Jetty server compliance are:

include::{jetty-home}/modules/http-config.mod[tags=documentation-compliance] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.httpConfig.compliance::
Configures the compliance to HTTP specifications, see also xref:programming-guide:server/compliance.adoc#http[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html[HttpCompliance] constants, such as RFC9110, RFC7230 or RFC2616; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/HttpCompliance.html#from(java.lang.String)[HttpCompliance.from(String)] method.
+
For example, jetty.httpConfig.compliance=RFC9110,MULTIPLE_CONTENT_LENGTHS means that the HTTP compliance is that defined by RFC9110, but also allows the HttpCompliance.Violation.MULTIPLE_CONTENT_LENGTHS, so that requests that have multiple Content-Length headers are accepted (they would be rejected when using just HttpCompliance.RFC9110).

jetty.httpConfig.uriCompliance::
Configures the compliance to URI specifications, see also xref:programming-guide:server/compliance.adoc#uri[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html[UriCompliance] constants, such as DEFAULT or RFC3986; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/UriCompliance.html#from(java.lang.String)[UriCompliance.from(String)] method.
+
For example, jetty.httpConfig.uriCompliance=RFC3986,-AMBIGUOUS_PATH_SEPARATOR means that the URI compliance is that defined by RFC3986, but also does not allow the UriCompliance.Violation.AMBIGUOUS_PATH_SEPARATOR, so that requests that have URIs such as /foo/bar%2Fbaz (where %2F is the URL-encoded / character) are rejected (they would be accepted when using just UriCompliance.RFC3986).

jetty.httpConfig.requestCookieCompliance::
jetty.httpConfig.responseCookieCompliance::
Configure the compliance to HTTP cookie specifications, respectively for requests and responses, see also xref:programming-guide:server/compliance.adoc#cookie[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html[CookieCompliance] constants, such as RFC6265; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/CookieCompliance.html#from(java.lang.String)[CookieCompliance.from(String)] method.
+
For example, jetty.httpConfig.requestCookieCompliance=RFC6265,-RESERVED_NAMES_NOT_DOLLAR_PREFIXED means that the cookie compliance is that defined by RFC6265, but also does not allow the CookieCompliance.Violation.RESERVED_NAMES_NOT_DOLLAR_PREFIXED, so that requests that have cookie headers such as Cookie: $foo=bar are rejected (they would be accepted when using just CookieCompliance.RFC6265).

jetty.httpConfig.multiPartCompliance::
Configures the compliance to MultiPart specifications, see also xref:programming-guide:server/compliance.adoc#multiPart[this section].
+
The value could be: one of the predefined link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html[MultiPartCompliance] constants, such as RFC7578_STRICT or RFC7578; or a comma-separated list of violations to allow or forbid, as specified by the link:{javadoc-url}/org/eclipse/jetty/http/MultiPartCompliance.html#from(java.lang.String)[MultiPartCompliance.from(String)] method.
+
For example, jetty.httpConfig.multiPartCompliance=RFC7578,-CONTENT_TRANSFER_ENCODING means that the MultiPart compliance is that defined by RFC7578, but also does not allow the MultiPartCompliance.Violation.CONTENT_TRANSFER_ENCODING, so that parts that specify the Content-Transfer-Encoding header are rejected (they would be accepted when using just MultiPartCompliance.RFC7578).

[[forwarded]]
== Module forwarded

The forwarded module provides support for processing the Forwarded HTTP header (defined in https://tools.ietf.org/html/rfc7239[RFC 7239]) and the now obsoleted X-Forwarded-* HTTP headers.

The module properties are:

include::{jetty-home}/modules/forwarded.mod[tags=documentation] Copy Chapter

[[https]]
== Module https

The https module provides the HTTP/1.1 protocol to the <<ssl,ssl module>>.

The module file is $JETTY_HOME/modules/https.mod:

include::{jetty-home}/modules/https.mod[] Copy Chapter

[[jmx]]
== Module jmx

include::{jetty-home}/modules/jmx.mod[tags=description]

This configuration is useful for xref:jmx/index.adoc#local[local development and testing].
If you need to xref:jmx/index.adoc#remote[enable remote access], use the xref:jmx/index.adoc#remote[jmx-remote module].

[[jmx-remote]]
== Module jmx-remote

The jmx-remote module provides remote access to JMX clients.

The module properties to configure remote JMX connector are:

include::{jetty-home}/modules/jmx-remote.mod[tags=documentation] Copy Chapter

The system property java.rmi.server.hostname is specified with the usual notation, prepending a -D in front of the system property name.

The system property java.rmi.server.hostname is uncommented because it is necessary in the default configuration -- most systems do not have the local name resolution configured properly for remote access.

As an example, in a Linux machine named beryl, the /etc/hosts file may contain these entries:

127.0.0.1 localhost 127.0.1.1 beryl Copy Chapter

If the system property java.rmi.server.hostname is not specified, the RMI implementation uses the host name beryl to figure out the IP address to store in the RMI stub, in this case 127.0.1.1.
However, the RMI server is configured to bind to localhost, i.e. 127.0.0.1.

If the system property java.rmi.server.hostname is not specified, the RMI client will try to connect to 127.0.1.1 (because that's what in the RMI stub) and fail because nothing is listening on that address.

[[loginservice-hash]]
== Module loginservice-hash

The loginservice-hash module creates a HashLoginService and adds it as a bean on the Server.
A SecurityHandler uses it by matching its configured realm name.

The HashLoginService reads users, their credentials and their roles from a properties file, where each line has the format : [,<rolename>...].
Enabling the module copies a template etc/realm.properties file into the $JETTY_BASE directory that you can edit to define your users.

The jetty.hashLoginService.name property sets the realm name, which must match the realm name expected by the Authenticator.
It defaults to default, the realm name used by web applications that declare a <login-config> without an explicit <realm-name>.
Set it to match the <realm-name> in a web application's web.xml when a specific realm is used.

The module properties are:

include::{jetty-home}/modules/loginservice-hash.mod[tags=documentation] Copy Chapter

See also xref:programming-guide:security/index.adoc[this section] for more information about Jetty's security features.

[[min-data-rate]]
== Module min-data-rate

The min-data-rate installs the MinimumDataRateHandler at the root of the Handler tree.
MinimumDataRateHandler enables support to enforce minimum data rates for reading request content and writing response content, as explained in xref:programming-guide:server/http.adoc#handler-use-min-data-rate[this section].

The module properties are:

include::{jetty-home}/modules/min-data-rate.mod[tags=documentation] Copy Chapter

[[openid]]
== Module openid

The openid module enables support for OpenID Connect (OIDC) authentication in Jetty, as detailed in xref:security/openid-support.adoc#openid-support[this section].

This module allows Jetty to authenticate users via an OpenID Connect identity provider, making possible to integrate features like "Sign in with Google" or "Sign in with Microsoft", among others.

This simplifies user authentication while leveraging the security and convenience of external identity providers.

The module properties are:

include::{jetty-home}/modules/openid.mod[tags=documentation] Copy Chapter

Among the configurable properties, the only required properties are:

jetty.openid.provider::
The issuer identifier of the OpenID Provider, which is the base URL before .well-known/openid-configuration. It must match the issuer field in the provider's configuration and is case-sensitive.
jetty.openid.clientId::
The Client Identifier assigned to your application by the OpenID Provider, used to uniquely identify your app during authentication requests.
jetty.openid.clientSecret::
The Client Secret issued by the OpenID Provider, used to verify your application's identity during the authentication process. This must be kept confidential.

[[qos]]
== Module qos

The qos module installs the QoSHandler at the root of the Handler tree; the QoSHandler applies limits to the number of concurrent requests, as explained in xref:programming-guide:server/http.adoc#handler-use-qos[this section].

The module properties are:

include::{jetty-home}/modules/qos.mod[tags=documentation] Copy Chapter

[[requestlog]]
== Module requestlog

The requestlog module provides HTTP request/response logging in the standard https://en.wikipedia.org/wiki/Common_Log_Format[NCSA format], or in a custom format of your choice.

The module properties are:

include::{jetty-home}/modules/requestlog.mod[tags=documentation] Copy Chapter

The property jetty.requestlog.formatString can be customized using format codes.

javadoc::code:partial$org/eclipse/jetty/server/CustomRequestLog.java[]

[[requestlog-slf4j]]
== Module requestlog-slf4j

The requestlog-slf4j module provides HTTP request/response logging to the SLF4J logging framework, as an alternative to the file-based <<requestlog,requestlog>> module.

Request logs are written to a configurable SLF4J logger at INFO level, allowing integration with any SLF4J-compatible logging framework (Logback, Log4j2, etc.).

The module properties are:

include::{jetty-home}/modules/requestlog-slf4j.mod[tags=documentation] Copy Chapter

The property jetty.requestlog.formatString uses the same format codes as the <<requestlog,requestlog>> module.

javadoc::code:partial$org/eclipse/jetty/server/CustomRequestLog.java[]

[NOTE]

Unlike the `requestlog` module, `requestlog-slf4j` does not create a `logs/` directory or write to files. All log output is handled by your SLF4J logging configuration.

[[resources]]
== Module resources

include::{jetty-home}/modules/resources.mod[tags=description]

A common use-case for this module is to provide resources for third-party libraries via the xref:start/index.adoc#start-class-path[server classpath].
For instance, many logging libraries (including https://logging.apache.org/log4j/2.x/[Log4j2] and https://logback.qos.ch/[Logback]) look for their configuration files on the classpath.

Jetty provides a logging library implementation -- enabled via the logging-jetty module -- whose configuration file is $JETTY_BASE/resources/jetty-logging.properties.

[[rewrite]]
== Module rewrite

The rewrite module inserts the RewriteHandler at the beginning of the Handler chain, providing URI-rewriting features similar to the https://httpd.apache.org/docs/current/mod/mod_rewrite.html[Apache's mod_rewrite] or the https://nginx.org/en/docs/http/ngx_http_rewrite_module.html[Nginx rewrite module].

The module properties are:

include::{jetty-home}/modules/rewrite.mod[tags=documentation] Copy Chapter

A common use of the rewrite module is to redirect/rewrite old URI paths that have been renamed, for example from +/old/*+ to +/new/*+; in this way, the old paths will not result in a 404 response, but rather be redirected/rewritten to the new paths.

RewriteHandler matches incoming requests against a set of rules that you can specify in the $JETTY_BASE/etc/jetty-rewrite-rules.xml file.

Rules can be matched against request data such as the request URI or the request headers; if there is a match, the rule is applied.

The rule file $JETTY_BASE/etc/jetty-rewrite-rules.xml is initially empty, but contains commented examples of rules that you can add.

The list of available rules can be found link:{javadoc-url}/org/eclipse/jetty/rewrite/handler/package-summary.html[here].

An example of jetty-rewrite-rules.xml is the following:

[,xml] .jetty-rewrite-rules.xml Copy Chapter

<Arg>
  <New class="org.eclipse.jetty.rewrite.handler.RedirectRegexRule">
    <Set name="statusCode">301</Set>
    <Set name="pattern">/old/(.*)</Set>
    <Set name="location">/new/$1</Set>
  </New>
</Arg>

Rules can be scoped to a specific virtual host.
In the example below, the rule will only be evaluated if the virtual host matches example.com:

[,xml] .jetty-rewrite-rules.xml Copy Chapter

<Arg>example.com</Arg>
    </Call>
    <Call name="addRule">
      <Arg>
        <New class="org.eclipse.jetty.rewrite.handler.RedirectPatternRule">
          <Set name="pattern">/advice</Set>
          <Set name="location">/support</Set>
        </New>
      </Arg>
    </Call>
  </New>
</Arg>

[[scheduler]]
== Module scheduler

The scheduler module allows you to configure the server-wide scheduler.

The scheduler is used to schedule tasks that must run at a later time, for example the tasks that perform actions when timeouts expire, in particular idle timeouts.

The module properties to configure the scheduler are:

include::{jetty-home}/modules/scheduler.mod[tags=documentation] Copy Chapter

[[server]]
== Module server

The server module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.

[NOTE]

The server module configures the shared parameters for generic HTTP handling, but does not enable any specific network protocol.

You have to explicitly enable the protocols you want to support by enabling, for example, the <<http,http module>> for clear-text HTTP/1.1 support, or the <<http2,http2 module>> for secure HTTP/2 support, etc.

See also the xref:protocols/index.adoc[protocols section] for more information about the supported protocols.

[[server-config]]
=== Server Configuration Properties

The module properties to configure the Jetty server are:

include::{jetty-home}/modules/server.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.server.dumpAfterStart::
Whether to perform a Server.dump() operation after the Server has started.
The output of the dump operation is sent to System.err.
See also the xref:troubleshooting/index.adoc#dump[Jetty Server Dump] section for more information.

jetty.server.dumpBeforeStop::
Whether to perform a Server.dump() operation before the Server stops.
The output of the dump operation is sent to System.err.
See also the xref:troubleshooting/index.adoc#dump[Jetty Server Dump] section for more information.

jetty.server.stopAtShutdown::
Whether to call Server.stop() through a JVM shutdown hook when the JVM exits.

[[size-limit]]
== Module size-limit

The size-limit module installs the SizeLimitHandler at the root of the Handler tree; the SizeLimitHandler applies limits to the request content and the response content, as explained in xref:programming-guide:server/http.adoc#handler-use-size-limit[this section].

The module properties are:

include::{jetty-home}/modules/size-limit.mod[tags=documentation] Copy Chapter

[[ssl]]
== Module ssl

The ssl module provides the secure connector, and allows you to configure the KeyStore properties and the TLS parameters, and depends on the <<server,server module>>.

For more information about securing a connector and supporting secure protocols, refer to xref:protocols/index.adoc#ssl[this section].

The module properties to configure the secure connector are:

include::{jetty-home}/modules/ssl.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.ssl.port::
The network port that Jetty listens to for secure connections -- default 8443.
jetty.ssl.idleTimeout::
The amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources -- default 30000 milliseconds.
jetty.ssl.acceptors::
The number of threads that compete to accept connections -- default 1. Use -1 to let the accept heuristic decides the value; the current heuristic calculates a value based on the number of cores).
Refer to <<http-acceptors,this section>> for more information about acceptor threads.
jetty.ssl.selectors::
The number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value; the current heuristic calculates a value based on the number of cores).
Refer to <<http-selectors,this section>> for more information about selector threads.

[[ssl-context]]
== Module ssl-context

The ssl-context module provides the KeyStore, TrustStore and TLS configuration necessary to the ssl module.

The Jetty component that manages the KeyStore, that contains the cryptographic material and the TLS configuration is an instance of SslContextFactory.Server.

The module properties to configure the KeyStore and TLS parameters are:

include::{jetty-home}/modules/ssl-context.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.sslContext.keyStorePath::
The KeyStore path on the file system, either an absolute path or a relative path to $JETTY_BASE -- defaults to $JETTY_BASE/etc/keystore.p12.
jetty.sslContext.keyStorePassword::
The KeyStore password, which you want to explicitly configure.
The password may be obfuscated with the xref:tools/index.adoc#password[Jetty Password tool].

If you need to configure client certificate authentication, you want to configure one of these properties (they are mutually exclusive):

jetty.sslContext.needClientAuth::
Whether client certificate authentication should be required.
jetty.sslContext.wantClientAuth::
Whether client certificate authentication should be requested.

Configuring SslContextFactory.Server using properties is sufficient for most cases.
For the cases where Jetty module properties are not defined, or when you need more advanced configuration, you can refer to xref:protocols/index.adoc#ssl-customize[this section].

If you configure client certificate authentication, you need to configure and distribute a client KeyStore as explained in xref:keystore/index.adoc#client-authn[this section].

[[ssl-reload]]
== Module ssl-reload

The ssl-reload module provides a periodic scanning of the directory where the KeyStore file resides.
When the scanning detects a change to the KeyStore file, the correspondent SslContextFactory.Server component is reloaded with the new KeyStore configuration.

The module properties are:

include::{jetty-home}/modules/ssl-reload.mod[tags=documentation] Copy Chapter

[[state-tracking]]
== Module state-tracking

The state-tracking Jetty module inserts the StateTrackingHandler at the beginning of the Handler chain.

StateTrackingHandler is a xref:troubleshooting/index.adoc[troubleshooting] Handler that tracks usages of Handler/Request/Response asynchronous APIs, and logs at warning level invalid usages of the APIs that may lead to blockages, deadlocks, or missing completion of Callbacks.

This module can be enabled to troubleshoot web applications that do not behave as expected, for example:

• That consume a lot of threads (possibly because they block).
• That do not send responses (or send only partial responses) to clients.
• That timeout when apparently they have received or have sent all data.

The module properties are:

include::{jetty-home}/modules/state-tracking.mod[tags=documentation] Copy Chapter

[[static-deploy]]
== Module static-deploy

The static-deploy module enables deployment of web applications that consist only of static files, as described in xref:deploy/index.adoc[this section].

See also the <<core-deploy,core-deploy>> module for Jetty core deployment, and the <<eeN-deploy,{ee-all}-deploy>> modules for Jakarta EE deployment environments.

[[test-keystore]]
== Module test-keystore

The test-keystore module creates on-the-fly a KeyStore containing a self-signed certificate for domain localhost.
The KeyStore file is automatically deleted when the JVM exits, and re-created when you restart Jetty, to enforce the fact that it is a test KeyStore that should not be reused if not for testing.

The module file is $JETTY_HOME/modules/test-keystore.mod:

include::{jetty-home}/modules/test-keystore.mod[] Copy Chapter

Note how properties jetty.sslContext.keyStorePath and jetty.sslContext.keyStorePassword are configured, only if not already set (via the ?= operator), directly in the module file, rather than in a +*.ini+ file.
This is done to avoid that these properties accidentally overwrite a real KeyStore configuration.

[[thread-limit]]
== Module thread-limit

The thread-limit module installs the ThreadLimitHandler at the root of the Handler tree; the ThreadLimitHandler applies limits to the number of concurrent threads per remote IP address, as explained in xref:programming-guide:server/http.adoc#handler-use-thread-limit[this section].

The module properties are:

include::{jetty-home}/modules/thread-limit.mod[tags=documentation] Copy Chapter

[[threadpool]]
== Module threadpool

The threadpool module allows you to configure the server-wide thread pool.

The thread pool creates threads on demand up to maxThreads, and idles them out if they are not used.

Since Jetty uses the thread pool internally to execute critical tasks, it is not recommended to constrain the thread pool to small values of maxThreads with the purpose of limiting HTTP request concurrency, as this could very likely cause a server lockup when Jetty needs to run a critical task but there are no threads available.
Start with the default value of maxThreads, and tune for larger values if needed.

The module properties to configure the thread pool are:

include::{jetty-home}/modules/threadpool.mod[tags=documentation] Copy Chapter

Among the configurable properties, the most relevant are:

jetty.threadPool.namePrefix::
The name prefix to use for the thread names.

jetty.threadPool.detailedDump::
Whether the thread pool should dump the whole stack trace of each thread, or just the topmost stack frame -- defaults to false.

jetty.threadPool.idleTimeout::
The time, in milliseconds, after which an idle thread is released from the pool -- defaults to 60000, i.e. 60 seconds.

jetty.threadPool.maxThreads::
The max number of threads pooled by the thread pool -- defaults to 200.

If you want to use virtual threads, introduced as a preview feature in Java 19 and Java 20, and become an official feature since Java 21, use the following modules:

• The <> Jetty module for Java 21 or later.
• The <> Jetty module for Java 19 and Java 20.

See also the xref:server/index.adoc#threadpool[section about configuring the thread pool].

[[threadpool-all-virtual]]
== Module threadpool-all-virtual

The threadpool-all-virtual module allows you to configure the server-wide thread pool, similarly to what you can do with the <> Jetty module, so that all threads are virtual threads, introduced as an official feature since Java 21.

CAUTION: Only use this module if you are using Java 21 or later.

The module properties to configure the thread pool are:

include::{jetty-home}/modules/threadpool-all-virtual.mod[tags=documentation] Copy Chapter

The property jetty.threadpool.maxThreads limits, using a Semaphore, the number of current virtual threads in use.

Please refer to the xref:programming-guide:arch/threads.adoc#thread-pool-virtual-threads[virtual threads section] of the Jetty Threading Architecture for more information about virtual threads and their pitfalls.

[[threadpool-virtual]]
== Module threadpool-virtual

The threadpool-virtual module allows you to configure the server-wide thread pool, similarly to what you can do with the <> Jetty module, but also specify to use virtual threads, introduced as an official feature since Java 21.

CAUTION: Only use this module if you are using Java 21 or later.
If you are using Java 19 or Java 20, use the <> Jetty module instead.

Refer to the <> Jetty module for the general features provided by that Jetty module that also this Jetty module provides.

The module properties to configure the thread pool are:

include::{jetty-home}/modules/threadpool-virtual.mod[tags=documentation] Copy Chapter

The specific properties to configure virtual threads are:

jetty.threadPool.virtual.namePrefix::
The name prefix to use for the virtual thread names.

jetty.threadPool.virtual.tracking::
Whether to track virtual threads so that they appear in a xref:troubleshooting/index.adoc#dump[Server Dump] even when they are unmounted.

jetty.threadPool.virtual.maxConcurrentTasks::
The number of concurrent tasks run by virtual threads.
This property limits resource usage, avoiding that virtual threads run an unlimited number of concurrent tasks when the system is under load.

[[threadpool-virtual-preview]]
== Module threadpool-virtual-preview

The threadpool-virtual-preview module allows you to configure the server-wide thread pool, similarly to what you can do with the <> Jetty module, but also specify to use virtual threads, introduced as a preview feature in Java 19 and in Java 20.

CAUTION: Only use this module if you are using Java 19 or Java 20.
If you are using Java 21 or later, use the <> Jetty module instead.

NOTE: To enable preview features, this module needs to specify the +--enable-preview+ command line option using the xref:modules/index.adoc#directive-exec[[exec] directive], and as such it will fork another JVM.

Refer to the <> Jetty module for the general features provided by that Jetty module that also this Jetty module provides.

The module properties to configure the thread pool are:

include::{jetty-home}/modules/threadpool-virtual-preview.mod[tags=documentation] Copy Chapter

The specific properties to configure virtual threads are:

jetty.threadPool.virtual.namePrefix::
The name prefix to use for the virtual thread names.

jetty.threadPool.virtual.allowSetThreadLocals::
Whether virtual threads are allowed to set thread locals.

jetty.threadPool.virtual.inheritInheritableThreadLocals::
Whether virtual threads inherit the values of InheritableThreadLocal variables.

[[well-known]]
== Module well-known

The well-known Jetty module creates a ResourceHandler deployed at the /.well-known context path which serves files from a directory.
By default, the directory created at $JETTY_BASE/.well-known is used, but it can be configured from well-known.ini to anywhere in the filesystem.
Note that the .well-known directory may be seen as a hidden directory by the filesystem.

The concept of well-known URIs has been defined in https://datatracker.ietf.org/doc/html/rfc5785[RFC5785].
This module can be used for things like the automatic renewal of https://letsencrypt.org/[Let's Encrypt] certificates.
See https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml[IANA Well-Known URIs] for more possible examples of how this can be used.

The module properties are:

include::{jetty-home}/modules/well-known.mod[tags=documentation] Copy Chapter

Documentation Jetty Modules Operations Guide Pages Protocols Index (`documentation/jetty/modules/operations-guide/pages/protocols/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Jetty Connectors and Protocols

Connectors are the network components through which Jetty accepts incoming network connections.

Each connector listens on a network port and can be configured with ConnectionFactory components that understand one or more network protocols.

Understanding a protocol means that the connector is able to interpret incoming network bytes (for example, the bytes that represent an HTTP/1.1 request) and convert them into more abstract objects (for example an HttpServletRequest object) that are then processed by applications.
Conversely, an abstract object (for example an HttpServletResponse) is converted into the correspondent outgoing network bytes (the bytes that represent an HTTP/1.1 response).

Like other Jetty components, connectors are enabled and configured by enabling and configuring the correspondent Jetty module.

IMPORTANT: Recall that you must always issue the commands to enable Jetty modules from within the $JETTY_BASE directory, and that the Jetty module configuration files are in the $JETTY_BASE/start.d/ directory.

You can obtain the list of connector-related modules in this way:

$ java -jar $JETTY_HOME/start.jar --list-modules=connector Copy Chapter

[[http]]
== Clear-Text HTTP/1.1

Clear text HTTP/1.1 is enabled with the http Jetty module with the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=http Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=http
....

After having enabled the http module, the $JETTY_BASE directory looks like this:

[source,subs=+quotes] Copy Chapter

JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
└── #http.ini#

The http.ini file is the file that you want to edit to configure network and protocol parameters -- for more details see xref:modules/standard.adoc#http[this section].

Note that the http Jetty module depends on the server Jetty module.

Some parameters that you may want to configure are in fact common HTTP parameters that are applied not only for clear-text HTTP/1.1, but also for secure HTTP/1.1 or for clear-text HTTP/2 or for encrypted HTTP/2, or for HTTP/3, and these configuration parameters may be present in the server module configuration file.

You can force the creation of the server.ini file via:

$ java -jar $JETTY_HOME/start.jar --add-modules=server Copy Chapter

Now the $JETTY_BASE directory looks like this:

[source] Copy Chapter

JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
├── http.ini
└── server.ini

Now you can edit the server.ini file -- for more details see xref:modules/standard.adoc#server[this section].

[[https]]
== Secure HTTP/1.1

Secure HTTP/1.1 is enabled with both the ssl and https Jetty modules with the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,https Copy Chapter

[jetty%nowrap]
....
[jetty]
args=--add-modules=ssl,https
....

The command above enables the ssl module, that provides the secure network connector, the KeyStore configuration and TLS configuration -- for more details see <<ssl,this section>>.
Then, the xref:modules/standard.adoc#https[https module] adds HTTP/1.1 as the protocol secured by TLS.

The $JETTY_BASE directory looks like this:

[source] Copy Chapter

$JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
├── https.ini
└── ssl-context.ini

Note that the KeyStore file is missing, because you have to provide one with the cryptographic material you want (read xref:keystore/index.adoc[this section] to create your own KeyStore).
You need to configure these two properties by editing ssl-context.ini:

• jetty.sslContext.keyStorePath
• jetty.sslContext.keyStorePassword

As a quick example, you can enable the xref:modules/standard.adoc#test-keystore[test-keystore module], that creates on-the-fly a KeyStore containing a self-signed certificate:

$ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=ssl,https
args=--add-modules=test-keystore
....

The $JETTY_BASE directory is now:

[source,subs=+quotes] Copy Chapter

├── etc
│ └── #test-keystore.p12#
├── resources
│ └── jetty-logging.properties
└── start.d
├── https.ini
├── ssl-context.ini
└── test-keystore.ini

Starting Jetty yields:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=ssl,https,test-keystore
highlight=({.*:8443})
....

Note how Jetty is listening on port 8443 for the secure HTTP/1.1 protocol.

[WARNING]

If you point your browser at +https://localhost:8443/+ you will get a warning from the browser about a "potential security risk ahead", or that "your connection is not private", or similar message depending on the browser.

This is normal because the certificate contained in `test-keystore.p12` is self-signed -- and as such not signed by a recognized certificate authority -- and therefore browsers do not trust it.

[[http2]]
== Configuring HTTP/2

https://tools.ietf.org/html/rfc7540[HTTP/2] is the successor of the HTTP/1.1 protocol, but it is quite different from HTTP/1.1: where HTTP/1.1 is a duplex, text-based protocol, HTTP/2 is a multiplex, binary protocol.

Because of these fundamental differences, a client and a server need to negotiate what version of the HTTP protocol they speak, based on what versions each side supports.

To ensure maximum compatibility, and reduce the possibility that an intermediary that only understands HTTP/1.1 will close the connection when receiving unrecognized HTTP/2 bytes, HTTP/2 is typically deployed over secure connections, using the TLS protocol to wrap HTTP/2.

IMPORTANT: Browsers only support secure HTTP/2.

The protocol negotiation is performed by the https://tools.ietf.org/html/rfc7301[ALPN TLS extension]: the client advertises the list of protocols it can speak, and the server communicates to the client the protocol chosen by the server.

For example, you can have a client that only supports HTTP/1.1 and a server that supports both HTTP/1.1 and HTTP/2:

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false

participant "client\nsupports\nhttp/1.1" as client
participant "server\nsupports\nhttp/1.1 & http/2" as server

group TLS handshake client -> server : ClientHello (alpn=[http/1.1]) server -> server : picks http/1.1 server -> client : ServerHello (alpn=http/1.1) ...rest of TLS handshake... end group TLS HTTP/1.1 client -> server : HTTP/1.1 GET server -> client : HTTP/1.1 200 end Copy Chapter

Nowadays, it's common that both clients and servers support HTTP/2, so servers prefer HTTP/2 as the protocol to speak:

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false

participant "client\nsupports\nhttp/1.1 & http/2" as client
participant "server\nsupports\nhttp/1.1 & http/2" as server

group TLS handshake client -> server : ClientHello (alpn=[http/1.1,h2]) server -> server : picks http/2 server -> client : ServerHello (alpn=h2) ...rest of TLS handshake... end group TLS HTTP/2 client -> server : HTTP/2 GET server -> client : HTTP/2 200 end Copy Chapter

When you configure a connector with the HTTP/2 protocol, you typically want to also configure the HTTP/1.1 protocol.
The reason to configure both protocols is that you typically do not control the clients: for example an old browser that does not support HTTP/2, or a monitoring console that performs requests using HTTP/1.1, or a heartbeat service that performs a single HTTP/1.0 request to verify that the server is alive.

== Secure vs Clear-Text HTTP/2

Deciding whether you want to configure Jetty with <<http2s,secure HTTP/2>> or <<http2c,clear-text HTTP/2>> depends on your use case.

You want to configure secure HTTP/2 when Jetty is exposed directly to browsers, because browsers only support secure HTTP/2.

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false
skinparam roundCorner 10

rectangle browser
cloud internet
rectangle jetty

jetty <--> internet : TLS+HTTP/2 internet <--> browser : TLS+HTTP/2 Copy Chapter

You may configure clear-text HTTP/2 (mostly for performance reasons) if you offload TLS at a load balancer (for example, https://haproxy.org/[HAProxy]) or at a reverse proxy (for example, https://nginx.org/[nginx]).

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false
skinparam roundCorner 10

rectangle browser
cloud internet
rectangle haproxy
rectangle jetty

note right of haproxy: TLS offload

jetty <--> haproxy : HTTP/2 (clear-text) haproxy <--> internet : TLS+HTTP/2 internet <--> browser : TLS+HTTP/2 Copy Chapter

You may configure clear-text HTTP/2 (mostly for performance reasons) to call microservices deployed to different Jetty servers (although you may want to use secure HTTP/2 for confidentiality reasons).

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false
skinparam roundCorner 10

rectangle browser
cloud internet
rectangle haproxy
rectangle jetty
rectangle microservice1
rectangle microservice2
rectangle microservice3

note right of haproxy: TLS offload

internet <--> browser : TLS+HTTP/2 haproxy <--> internet : TLS+HTTP/2 jetty <--> haproxy : HTTP/2 (clear-text) microservice1 <--> jetty : HTTP/2 microservice2 <--> jetty : HTTP/2 microservice3 <--> jetty : HTTP/2 microservice2 <--> microservice3 : HTTP/2 microservice1 <--> microservice3 : HTTP/2 Copy Chapter

[[http2s]]
== Secure HTTP/2

When you enable secure HTTP/2 you typically want to enable also secure HTTP/1.1, for backwards compatibility reasons: in this way, old browsers or other clients that do not support HTTP/2 will be able to connect to your server.

You need to enable:

• the ssl Jetty module, which provides the secure connector and the KeyStore and TLS configuration
• the http2 Jetty module, which adds ALPN handling and adds the HTTP/2 protocol to the secured connector
• optionally, the https Jetty module, which adds the HTTP/1.1 protocol to the secured connector

Use the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,http2,https Copy Chapter

As when enabling the https Jetty module, you need a valid KeyStore (read xref:keystore/index.adoc[this section] to create your own KeyStore).

As a quick example, you can enable the xref:modules/standard.adoc#test-keystore[test-keystore module], that creates on-the-fly a KeyStore containing a self-signed certificate:

$ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore Copy Chapter

Starting Jetty yields:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=ssl,http2,https,test-keystore
highlight=({.*:8443})
....

Note how Jetty is listening on port 8443 and the protocols supported are the sequence (ssl, alpn, h2, http/1.1).

The (ordered) list of protocols after alpn are the application protocols, in the example above (h2, http/1.1).

When a new connection is accepted by the connector, Jetty first interprets the TLS bytes, then it handles the ALPN negotiation knowing that the application protocols are (in order) h2 and then http/1.1.

You can customize the list of application protocols and the default protocol to use in case the ALPN negotiation fails by editing the xref:modules/standard.adoc#alpn[alpn module] properties.

The HTTP/2 protocol parameters can be configured by editing the xref:modules/standard.adoc#http2[http2 module] properties.

[[http2c]]
== Clear-Text HTTP/2

When you enable clear-text HTTP/2 you typically want to enable also clear-text HTTP/1.1, for backwards compatibility reasons and to allow clients to https://tools.ietf.org/html/rfc7540#section-3.2[upgrade] from HTTP/1.1 to HTTP/2.

You need to enable:

• the http Jetty module, which provides the clear-text connector and adds the HTTP/1.1 protocol to the clear-text connector
• the http2c Jetty module, which adds the HTTP/2 protocol to the clear-text connector

$ java -jar $JETTY_HOME/start.jar --add-modules=http,http2c Copy Chapter

Starting Jetty yields:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=http,http2c
highlight=({.+:8080})
....

Note how Jetty is listening on port 8080 and the protocols supported are HTTP/1.1 and h2c (i.e. clear-text HTTP/2).

With this configuration, browsers and client applications will be able to connect to port 8080 using:

• HTTP/1.1 directly (e.g. curl --http1.1 ++http://localhost:8080++):

GET / HTTP/1.1 Host: localhost:8080 Copy Chapter

• HTTP/1.1 with upgrade to HTTP/2 (e.g. curl --http2 ++http://localhost:8080++):

GET / HTTP/1.1 Host: localhost:8080 Connection: Upgrade, HTTP2-Settings Upgrade: h2c HTTP2-Settings: Copy Chapter

• HTTP/2 directly (e.g. curl --http2-prior-knowledge ++http://localhost:8080++):

50 52 49 20 2a 20 48 54 54 50 2f 32 2e 30 0d 0a 0d 0a 53 4d 0d 0a 0d 0a 00 00 12 04 00 00 00 00 00 00 03 00 00 00 64 00 04 40 00 00 00 00 02 00 00 00 00 00 00 1e 01 05 00 00 00 01 82 84 86 41 8a a0 e4 1d 13 9d 09 b8 f0 1e 07 7a 88 25 b6 50 c3 ab b8 f2 e0 53 03 2a 2f 2a Copy Chapter

The HTTP/2 protocol parameters can be configured by editing the xref:modules/standard.adoc#http2c[http2c module] properties.

[[http3]]
== HTTP/3

When you enable support for the HTTP/3 protocol, by default the secure HTTP/2 protocol is also enabled, so that browsers or clients that do not support HTTP/3 will be able to connect to your server.

You need to enable:

• the ssl Jetty module, which provides the KeyStore and TLS configuration
• the http3 Jetty module, which adds the HTTP/3 protocol on the HTTP/3 connector

Use the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,http3 Copy Chapter

Enabling any module Jetty module that supports secure network communication requires a valid KeyStore (read xref:keystore/index.adoc[this section] to create your own KeyStore), that, as a quick example, you can enable with the xref:modules/standard.adoc#test-keystore[test-keystore module], that creates on-the-fly a KeyStore containing a self-signed certificate:

$ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore Copy Chapter

Starting Jetty yields:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--approve-all-licenses --add-modules=ssl,http3,test-keystore
highlight=({.*:8444})
....

Note how Jetty is listening on port 8443 for HTTP/2 and on port 8444 for HTTP/3.

The HTTP/3 protocol parameters can be configured by editing the xref:modules/standard.adoc#http3[http3 module] properties.

[[websocket]]
== WebSocket

WebSocket is a network protocol for bidirectional data communication, initiated via HTTP and then upgraded to WebSocket.
WebSocket provides a simple, low-level, framing protocol layered over the underlying transport protocol, typically TCP.
One or more WebSocket data frames compose a WebSocket message that is either a UTF-8 text message or binary message.

Jetty provides an implementation of the following standards and specifications.

http://tools.ietf.org/html/rfc6455[RFC-6455] - The WebSocket Protocol::
Jetty supports version 13 of the released and final specification.

http://www.jcp.org/en/jsr/detail?id=356[JSR-356] - The Java WebSocket API (javax.websocket)::
This is the official Java API for working with WebSockets.

https://tools.ietf.org/html/rfc7692[RFC-7692] - WebSocket Per-Message Deflate Extension::
This is the replacement for perframe-compression, switching the compression to being based on the entire message, not the individual frames.

https://tools.ietf.org/html/rfc8441[RFC-8441] - Bootstrapping WebSockets with HTTP/2::
Allows a single stream of an HTTP/2 connection to be upgraded to WebSocket.
This allows one TCP connection to be shared by both protocols and extends HTTP/2's more efficient use of the network to WebSockets.

[[websocket-configure]]
=== Configuring WebSocket

Jetty provides two WebSocket implementations: one based on the Jakarta EE WebSocket APIs defined by JSR 356, provided by module {ee-current}-websocket-jakarta (for Java EE 8, the module is called ee8-websocket-javax), and one based on Jetty specific WebSocket APIs, provided by module websocket-jetty.

NOTE: Remember that a WebSocket connection is always initiated from the HTTP protocol (either an HTTP/1.1 upgrade or an HTTP/2 connect), therefore to enable WebSocket you need to enable HTTP.

To enable WebSocket support, you also need to decide what version of the HTTP protocol you want WebSocket to be initiated from, and whether you want secure HTTP.

For example, to enable clear-text WebSocket from HTTP/1.1, using the Jakarta {ee-current-caps} implementation, use the following command (issued from within the $JETTY_BASE directory):

[,shell,subs=+attributes] Copy Chapter

$ java -jar $JETTY_HOME/start.jar --add-modules=http,{ee-current}-websocket-jakarta Copy Chapter

To enable secure WebSocket from HTTP/2, using the Jetty implementation, use the following command (issued from within the $JETTY_BASE directory):

[,shell] Copy Chapter

$ java -jar $JETTY_HOME/start.jar --add-modules=http2,websocket-jetty Copy Chapter

When enabling secure protocols you need a valid KeyStore (read xref:keystore/index.adoc[this section] to create your own KeyStore).
As a quick example, you can enable the xref:modules/standard.adoc#test-keystore[test-keystore module], that creates on-the-fly a KeyStore containing a self-signed certificate:

$ java -jar $JETTY_HOME/start.jar --add-modules=test-keystore Copy Chapter

To enable WebSocket on both HTTP/1.1 and HTTP/2, both clear-text and secure, using the Jakarta {ee-current-caps} implementation, use the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=http,https,http2c,http2,{ee-current}-websocket-jakarta Copy Chapter

[[websocket-disable]]
=== Selectively Disabling WebSocket

Enabling the Jakarta EE WebSocket Jetty modules comes with a startup cost because Jetty must perform two steps:

. Scan Jakarta EE web applications +*.war+ files (and all the jars and classes inside it) looking for WebSocket EndPoint classes (either annotated with the Jakarta EE WebSocket API annotations or extending/implementing Jakarta EE WebSocket API classes/interfaces).
This can be a significant cost if your web application contains a lot of classes and/or jar files.
. Configure and wire WebSocket EndPoints so that WebSocket messages are delivered to the correspondent WebSocket EndPoint.

WebSocket support is by default enabled for all Jakarta EE web applications.

For a specific Jakarta EE web application, you can disable step 2 for Jakarta EE WebSocket support (when the {ee-current}-websocket-jakarta module is enabled) by setting the context attribute org.eclipse.jetty.websocket.jakarta to false:

[,xml] Copy Chapter

...

NOTE: For Java EE 8, the parameter name is org.eclipse.jetty.websocket.javax.

Furthermore, for a specific web application, you can disable step 1 (and therefore also step 2) as described in the xref:annotations/index.adoc[annotations processing section].

[[websocket-webapp-client]]
=== Using WebSocket Client in Web Applications

Web applications may need to use a WebSocket client to communicate with third party WebSocket services.

If the web application uses the Jakarta EE WebSocket APIs, the Jakarta EE WebSocket client APIs are provided by Jetty and are available to the web application as long as the {ee-current}-websocket-jakarta Jetty module is enabled.

However, the Jakarta EE WebSocket Client APIs are quite limited (for example, they do not support secure WebSocket).
For this reason, web applications may want to use the Jetty WebSocket Client APIs.

When using the Jetty WebSocket Client APIs, Jakarta EE web applications should include the required jars and their dependencies in the WEB-INF/lib directory of the +*.war+ file.
Alternatively, when deploying your Jakarta EE web applications in Jetty, you can enable the websocket-jetty-client Jetty module to allow Jakarta EE web applications to use the Jetty WebSocket Client APIs provided by Jetty, without the need to include jars and their dependencies in the +*.war+ file.

[[fcgi]]
== FastCGI

FastCGI is a network protocol primarily used by a web server to communicate to a FastCGI server.

FastCGI servers are typically used to serve web content generated by dynamic web languages, primarily http://www.php.net/[PHP], but also Python, Ruby, Perl and others.

Web servers that supports FastCGI are, among others, http://httpd.apache.org/[Apache], http://nginx.org/[Nginx], and Jetty.
Web servers typically act as reverse proxies, converting HTTP requests that they receive from clients (browsers) to FastCGI requests that are forwarded to the FastCGI server.
The FastCGI server spawns the dynamic web language interpreter, passing it the information contained in the FastCGI request and a dynamic web language script is executed, producing web content, typically HTML.
The web content is then formatted into a FastCGI response that is returned to the web server, which converts it to an HTTP response that is then returned to the client.

The most well known FastCGI server is the http://php-fpm.org/[PHP FastCGI Process Manager], or php-fpm.
In the following we will assume that php-fpm is used as FastCGI server.

This is a diagram of what described above:

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false

Browser -> Jetty : GET /path (HTTP)
Jetty -> "php-fpm" : GET /path (FastCGI)
"php-fpm" -> PHP : spawn PHP interpreter
PHP -> "index.php" : execute PHP script
"index.php" -> "php-fpm" : HTML
"php-fpm" -> Jetty : 200 OK + HTML (FastCGI)
Jetty -> Browser : 200 OK + HTML (HTTP)

Jetty can be configured to act as a web server that supports FastCGI, replacing the functionality that is normally provided by Apache or Nginx.
This allows users to leverage Jetty features such as the support for HTTP/1.1, HTTP/2 and HTTP/3, Jetty's scalability, and of course Jetty's native support for Jakarta EE Web Standards such as Servlets, JSPs, etc.

With such configuration, users can not only deploy their Jakarta EE web applications in Jetty, but also serve their http://wordpress.com/[WordPress] site or blog or their https://drupal.org/[Drupal] site without having to install and manage multiple web servers.

[[fcgi-configure]]
=== Configuring WordPress

This section explains how to configure Jetty to serve your https://wordpress.com/[WordPress] site.

The prerequisites are:

• Have php-fpm installed on your server host, and configured to listen either on a Unix-Domain socket (such as /run/php/php-fpm.sock), or on a TCP socket (such as localhost:9000).
• Have WordPress installed on your server host, for example under /var/www/wordpress.
  For more information about how to install WordPress and the necessary PHP modules, please refer to the https://wordpress.org/support/article/how-to-install-wordpress/[WordPress Installation Guide].

Then, the <<https,secure HTTP>> and/or the <<http2,secure HTTP/2>> Jetty modules should be enabled to allow browsers to connect to Jetty.

Lastly, enable the fcgi-proxy module to provide FastCGI support (to convert HTTP requests from browsers to FastCGI for php-fpm and vice versa), and the core-deploy module to deploy your WordPress web application as a xref:deploy/index.adoc#jetty[Jetty context XML file].

For example:

$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,https,fcgi-proxy,core-deploy Copy Chapter

TIP: The https Jetty module requires a KeyStore. If you do not already have one configured, you can add the test-keystore Jetty module to the command line above to create a KeyStore on-the-fly.

Now you can deploy a Jetty context XML file that represents your WordPress web application.

Use the following file as example, copy it as $JETTY_BASE/webapps/wordpress.xml and customize it as necessary:

[,xml,options=nowrap] Copy Chapter

<Set name="handler">
    <New class="org.eclipse.jetty.server.handler.PathMappingsHandler">
      <Call name="addMapping">
        <Arg>
          <New class="org.eclipse.jetty.http.pathmap.ServletPathSpec"><Arg>*.php</Arg></New>
        </Arg>
        <Arg>
          <New class="org.eclipse.jetty.fcgi.proxy.FastCGIProxyHandler"> 
            <Arg>(https?)://([^/]+)(.*)</Arg> 
            <Arg>http://localhost:9000$3</Arg> 
            <Arg><Ref refid="root" /></Arg>

            <Set name="originalPathAttribute">wordpress.originalPath</Set>
            <Set name="originalQueryAttribute">wordpress.originalQuery</Set>
            <Set name="scriptPattern"><Call class="java.util.regex.Pattern" name="compile"><Arg>(.+?\\.php)</Arg></Call></Set>
            <Set name="fastCGISecure">true</Set>
            <Set name="unixDomainPath"><Call class="java.nio.file.Path" name="of"><Arg>/run/php/php-fpm.sock</Arg></Call></Set> 
          </New>
        </Arg>
      </Call>
      <Call name="addMapping">
        <Arg>
          <New class="org.eclipse.jetty.http.pathmap.ServletPathSpec"><Arg>/</Arg></New>
        </Arg>
        <Arg>
          <New class="org.eclipse.jetty.server.handler.ResourceHandler"> 
            <Set name="welcomeFiles"><Call class="java.util.List" name="of"><Arg>/index.php</Arg></Call></Set>
            <Set name="welcomeMode"><Call class="org.eclipse.jetty.server.ResourceService$WelcomeMode" name="valueOf"><Arg>REHANDLE</Arg></Call></Set>
            <Set name="dirAllowed">false</Set>
          </New>
        </Arg>
      </Call>
    </New>
  </Set>
</New>

Now you can start Jetty and navigate to +http://localhost:8080+ with your browser to enjoy WordPress:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[[ssl]]
== Configuring Secure Protocols

Secure protocols are normal protocols such as HTTP/1.1, HTTP/2 or WebSocket that are wrapped by the https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS protocol].
Any network protocol based on TCP can be wrapped with TLS.

QUIC, the protocol based on UDP that transports HTTP/3, uses TLS messages but not the TLS protocol framing.

The https scheme used in URIs really means tls+http/1.1 (or tls+http/2, or quic+http/3) and similarly the wss scheme used in URIs really means tls+websocket, etc.
Senders wrap the underlying protocol bytes (e.g. HTTP bytes or WebSocket bytes) with the TLS protocol, while receivers first interpret the TLS protocol to obtain the underlying protocol bytes, and then interpret the wrapped bytes.

The xref:modules/standard.adoc#ssl[ssl Jetty module] allows you to configure a secure network connector; if other modules require encryption, they declare a dependency on the ssl module.

It is the job of other Jetty modules to configure the wrapped protocol.
For example, it is the <<https,https module>> that configures the wrapped protocol to be HTTP/1.1.
Similarly, it is the <<http2,http2 module>> that configures the wrapped protocol to be HTTP/2.
If you enable both the https and the http2 module, you will have a single secure connector that will be able to interpret both HTTP/1.1 and HTTP/2.

[[ssl-customize]]
=== Customizing KeyStore and SSL/TLS Configuration

Secure protocols have a slightly more complicated configuration since they require to configure a KeyStore.
Refer to the xref:keystore/index.adoc[KeyStore section] for more information about how to create and manage a KeyStore.

For simple cases, you only need to configure the KeyStore path and KeyStore password as explained in xref:modules/standard.adoc#ssl-context[this section].

For more advanced configuration, for example where Jetty module properties are not defined, or the values for those properties need to be fetched from external sources, you can follow the steps below.

First, create a custom xref:xml/index.adoc[Jetty XML file] and reference it in $JETTY_BASE/start.d/ssl-context.ini:

.ssl-context.ini [source,subs="verbatim,quotes"] Copy Chapter

--module=ssl-context *etc/tls-config.xml* <1> ... Copy Chapter

<1> The path to the custom XML file, relative to $JETTY_BASE.

The ssl-context.ini file above only shows the lines that are not commented out (you can leave the lines that are commented unmodified for future reference).

You want to create the $JETTY_BASE/etc/tls-config.xml with the following template content:

.tls-config.xml [,xml] Copy Chapter

The tls-config.xml file references the sslContextFactory component (created by the ssl-context Jetty module) that configures the KeyStore and TLS parameters, so that you can now call its APIs via XML (using the syntax described in xref:xml/index.adoc[this section]), and you will have full flexibility for any advanced configuration you want (see below for few examples).

Refer to the link:{javadoc-url}/org/eclipse/jetty/util/ssl/SslContextFactory.Server.html[SslContextFactory.Server javadocs] for the list of methods that you can call through the Jetty XML file.

CAUTION: Use module properties whenever possible, and only resort to use a Jetty XML file for advanced configuration that you cannot do using module properties.

[[ssl-customize-versions]]
==== Customizing SSL/TLS Protocol Versions

By default, the SSL protocols (SSL, SSLv2, SSLv3, etc.) are already excluded because they are vulnerable.
To explicitly add the exclusion of TLSv1.0 and TLSv1.1 (that are also vulnerable -- which leaves only TLSv1.2 and TLSv1.3 available), you want to use this XML:

.tls-config.xml [,xml] Copy Chapter

[[ssl-customize-ciphers]]
==== Customizing SSL/TLS Ciphers

By default, certain cipher suites are already excluded because they are either weak or vulnerable.
To explicitly exclude more cipher suites in addition to those excluded by default, you can use this XML:

.tls-config.xml [,xml] Copy Chapter

Note how each array item specifies a regular expression that matches multiple ciphers, or specifies a precise cipher to exclude.

You can choose to create multiple XML files, and reference them all from $JETTY_BASE/start.d/ssl-context.ini, or put all your custom configurations in a single XML file.

[[ssl-renew]]
=== Renewing the Certificates

When you create a certificate, you must specify for how many days it is valid.

The typical validity is 90 days, and while this period may seem short, it has two advantages:

• Reduces the risk in case of compromised/stolen keys.
• Encourages automation, i.e. certificate renewal performed by automated tools (rather than manually) at scheduled times.

To renew a certificate, you must go through the xref:keystore/index.adoc#create[same steps] you followed to create the certificate the first time, and then you can <<ssl-reload,reload the KeyStore>> without the need to stop Jetty.

[[ssl-reload]]
=== Watching and Reloading the KeyStore

Jetty can be configured to monitor the directory of the KeyStore file, and reload the SslContextFactory component if the KeyStore file changed.

This feature can be enabled by activating the ssl-reload Jetty module:

$ java -jar $JETTY_HOME/start.jar --add-modules=ssl-reload Copy Chapter

For more information about the configuration of the ssl-reload Jetty module, see xref:modules/standard.adoc#ssl-reload[this section].

[[ssl-conscrypt]]
=== Using Conscrypt as SSL/TLS Provider

If not explicitly configured, the TLS implementation is provided by the JDK you are using at runtime.

OpenJDK's vendors may replace the default TLS provider with their own, but you can also explicitly configure an alternative TLS provider.

The standard TLS provider from OpenJDK is implemented in Java (no native code), and its performance is not optimal, both in CPU usage and memory usage.

A faster alternative, implemented natively, is Google's https://github.com/google/conscrypt/[Conscrypt], which is built on https://boringssl.googlesource.com/boringssl/[BoringSSL], which is Google's fork of https://www.openssl.org/[OpenSSL].

CAUTION: As Conscrypt eventually binds to a native library, there is a higher risk that a bug in Conscrypt or in the native library causes a JVM crash, while the Java implementation will not cause a JVM crash.

To use Conscrypt as the TLS provider just enable the conscrypt Jetty module:

$ java -jar $JETTY_HOME/start.jar --add-modules=conscrypt Copy Chapter

[[ssl-bouncycastle]]
=== Using Bouncy Castle as SSL/TLS Provider

If not explicitly configured, the TLS implementation is provided by the JDK you are using at runtime.

OpenJDK's vendors may replace the default TLS provider with their own, but you can also explicitly configure an alternative TLS provider.

link:https://www.bouncycastle.org/[Bouncy Castle] is a pure Java alternative provider for the Java security APIs, and includes a TLS provider.

To use Bouncy Castle as the TLS provider just enable the bouncycastle Jetty module:

$ java -jar $JETTY_HOME/start.jar --add-modules=bouncycastle Copy Chapter

[[ssl-sni]]
=== Configuring SNI

Server Name Indication (SNI) is a TLS extension that clients send to indicate what domain they want to connect to during the initial TLS handshake.

Modern TLS clients (e.g. browsers) always send the SNI extension; however, older TLS clients may not send the SNI extension.

Being able to handle the SNI is important when you have xref:deploy/index.adoc#virtual-hosts[virtual hosts] and a KeyStore with multiple certificates, one for each domain.

For example, you may have deployed over a secure connector two web applications, both at context path /, one at virtual host one.com and one at virtual host two.net.
The KeyStore contains two certificates, one for one.com and one for two.net.

There are three ssl module properties that control the SNI behavior on the server: one that works at the TLS level, and two that works at the HTTP level.

The property that works at the TLS level is:

jetty.sslContext.sniRequired::
Whether SNI is required at the TLS level, defaults to false.
Its behavior is explained by the following table:
+
.Behavior of the jetty.sslContext.sniRequired property
[cols="3*a"]
|===
|
| sniRequired=false
| sniRequired=true

| SNI = null
| client receives default certificate
| client receives TLS failure

| SNI = wrong.org
| client receives default certificate
| client receives TLS failure

| SNI = `one.com` | client receives `one.com` certificate | client receives `one.com` certificate |=== + [WARNING]

The default certificate is the certificate returned by the TLS implementation in case there is no SNI match, and you should not rely on this certificate to be the same across Java vendors and versions, or Jetty versions, or TLS provider vendors and versions.

In the example above it could be either the `one.com` certificate or the `two.net` certificate.

When jetty.sslContext.sniRequired=true, clients that don't send a valid SNI receive a TLS failure, and their attempt to connect to the server fails.
The details of this failure may not be reported and could be difficult to figure out that the failure is related to an invalid SNI.

For this reason, other two properties are defined at the HTTP level, so that clients can received an HTTP 400 response with more details about what went wrong while trying to connect to the server:

jetty.ssl.sniRequired::
Whether SNI is required at the HTTP level, defaults to false.
Its behavior is similar to the jetty.sslContext.sniRequired property above, and is explained by the following table:
+
.Behavior of the jetty.ssl.sniRequired property
[cols=3*a]
|===
|
| sniRequired=false
| sniRequired=true

| SNI = null
| Accept
| Reject: 400 Bad Request

| SNI = wrong.org
| Accept
| Reject: 400 Bad Request

| SNI = one.com
| Accept
| Accept
|===

When jetty.ssl.sniRequired=true, the SNI is matched against the certificate sent to the client, and only if there is a match the request is accepted.

When the request is accepted, there could be an additional check controlled by the following property:

jetty.ssl.sniHostCheck::
Whether the certificate sent to the client matches the Host header, defaults to true.
Its behavior is explained by the following table:
+
.Behavior of the jetty.ssl.sniHostCheck property
[cols="3*a"]
|===
|
| sniHostCheck=false
| sniHostCheck=true

| certificate = one.com +
Host: wrong.org
| Accept
| Reject: 400 Bad Request

| certificate = one.com +
Host: one.com
| Accept
| Accept
|===

In the normal case with the default server configuration, for a TLS clients that sends SNI, and then sends an HTTP request with the correct Host header, Jetty will pick the correct certificate from the KeyStore based on the SNI received from the client, and accept the request.

Accepting the request does not mean that the request is responded with an HTTP 200 OK, but just that the request passed successfully the SNI checks and will be processed by the server.
If the request URI is for a resource that does not exist, the response will likely be a 404 Not Found.

You may modify the default values of the SNI properties if you want stricter control over old/broken TLS clients or bad HTTP requests.

[[proxy]]
== Jetty Behind a Load Balancer or Reverse Proxy

You may need to configure one or more Jetty instances behind an intermediary, typically a load balancer such as https://haproxy.org[HAProxy], or a reverse proxy such as https://httpd.apache.org[Apache HTTP Server] or https://nginx.org[Nginx].

[plantuml] Copy Chapter

skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false
skinparam padding 5

scale 1.5

rectangle client
rectangle proxy
rectangle "Jetty" as jetty1
rectangle "Jetty" as jetty2

client -- proxy proxy -- jetty1 proxy -- jetty2 Copy Chapter

[WARNING]

HAProxy can communicate either HTTP/1.1 or HTTP/2 to backend servers such as Jetty.

Apache HTTP Server and Nginx can only speak HTTP/1.1 to backend servers such as Jetty, and have no plans to support HTTP/2 towards backend servers.

In these setups, typically the proxy performs TLS offloading, and the communication with backend servers happens in clear-text.
It is possible, however, to configure the proxy so that all the bytes arriving from the client are tunnelled opaquely to the backend Jetty server (that therefore needs to perform the TLS offloading) and vice versa the bytes arriving from the Jetty server are tunnelled opaquely to the client.

Also in these setups, the TCP/IP connection terminating on the Jetty servers does not originate from the client, but from the proxy, so that the remote IP address and port number may be reported incorrectly in backend server logs, or worse applications may not work because they need to be able to differentiate different clients based on the client IP address.

For this reason, intermediaries typically implement at least one of several de facto standards to communicate information about the original client connection to the backend Jetty server.

Jetty supports two methods to process client information sent by intermediaries:

• The Forwarded HTTP header, defined in https://tools.ietf.org/html/rfc7239[RFC 7239] and replacing the old X-Forwarded-* headers, defined in <>.
• The https://www.haproxy.org/download/2.2/doc/proxy-protocol.txt[Proxy Protocol], defined in <>.

In both methods, web applications asking for the remote client IP address will receive the remote client IP address as specified by the client information sent by the intermediary, not the physical IP address of TCP connection with the intermediary.
Likewise, web applications asking for the remote client IP port will receive the remote client IP port as specified by the client information sent by the intermediary.
Finally, web applications asking whether the remote request was secure will receive whether the remote client made a secure request using the https scheme as specified by the client information sent by the intermediary.

[[proxy-forwarded]]
=== Configuring the Forwarded Header

The Forwarded HTTP header is added by the intermediary with information about the client and the client request, for example:

GET / HTTP/1.1 Host: domain.com Forwarded: for=2.36.72.144:21216;proto=https Copy Chapter

In the example above, the intermediary added the Forwarded header specifying that the client remote address is 2.36.72.144:21216 and that the request was made with the https scheme.

Let's assume you have already configured Jetty with the HTTP/1.1 protocol with the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=http Copy Chapter

Support for the Forwarded HTTP header (and its predecessor X-Forwarded-* headers) is enabled with the forwarded Jetty module:

$ java -jar $JETTY_HOME/start.jar --add-modules=forwarded Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=http
args=--add-modules=forwarded
....

With the forwarded Jetty module enabled, Jetty interprets the Forwarded header and makes its information available to web applications.

For further information about configuring the forwarded Jetty module, see xref:modules/standard.adoc#forwarded[this section].

[[proxy-protocol]]
=== Configuring the Proxy Protocol

The https://www.haproxy.org/download/2.2/doc/proxy-protocol.txt[Proxy Protocol] is the de facto standard, introduced by https://haproxy.org[HAProxy], to communicate client information to backend servers via the TCP connection, rather than via HTTP headers.

The information about the client connection is sent as a small data frame on each newly established connection.
This mechanism is therefore independent of any protocol, so it can be used for TLS, HTTP/1.1, HTTP/2, etc.

[NOTE]

There are 2 versions of the proxy protocol: v1 and v2, both supported by Jetty.

Proxy protocol v1 is human readable, but it only carries information about the client TCP connection (IP address and IP port).

Proxy protocol v2 has a binary format, carries the information about the client TCP connection, and can carry additional arbitrary information encoded in pairs `(type, value)` where `type` is a single byte that indicates the value's meaning, and `value` is a variable length byte array that can encode user-defined data.

Support for the proxy protocol can be enabled for the clear-text connector or for the secure connector (or both).

Let's assume you have already configured Jetty with the HTTP/1.1 clear-text protocol with the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=http Copy Chapter

To enable proxy protocol support for the clear-text connector, enable the proxy-protocol Jetty module:

$ java -jar $JETTY_HOME/start.jar --add-modules=proxy-protocol Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=http
args=--add-modules=proxy-protocol
....

Starting Jetty yields:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[jetty%nowrap]
....
[jetty]
args=--module=proxy-protocol
highlight=({.*:8080})
....

Note how in the example above the list of protocols for the clear-text connector is first proxy and then http/1.1.
For every new TCP connection, Jetty first interprets the proxy protocol bytes with the client information; after this initial proxy protocol processing, Jetty interprets the incoming bytes as HTTP/1.1 bytes.

Enabling proxy protocol support for the secure connector is similar.

Let's assume you have already configured Jetty with the HTTP/1.1 secure protocol and the test KeyStore with the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=https,test-keystore Copy Chapter

Enable the proxy-protocol-ssl Jetty module with the following command (issued from within the $JETTY_BASE directory):

$ java -jar $JETTY_HOME/start.jar --add-modules=proxy-protocol-ssl Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=https
args=--add-modules=proxy-protocol-ssl
....

Starting Jetty yields:

$ java -jar $JETTY_HOME/start.jar Copy Chapter

[jetty%nowrap]
....
[jetty]
setupArgs=--add-modules=https,test-keystore,proxy-protocol-ssl
highlight=({.*:8443})
....

Note how in the example above the list of protocols for the secure connector is first proxy, then ssl and then http/1.1.

[[proxy-haproxy]]
=== HAProxy and Jetty with HTTP/1.1 and HTTP/2

https://haproxy.org[HAProxy] is an open source solution that offers load balancing and proxying for TCP and HTTP based application, and can be used as a replacement for Apache or Nginx when these are used as reverse proxies.

The deployment proposed here has HAProxy playing the role that Apache and Nginx usually do: to perform the TLS offloading (that is, decrypt incoming bytes and encrypt outgoing bytes) and then forwarding the now clear-text traffic to a backend Jetty server, speaking either HTTP/1.1 or HTTP/2.
Since HAProxy's TLS offloading is based on OpenSSL, it is much more efficient than the Java implementation shipped with OpenJDK.

After you have installed HAProxy on your system, you want to configure it so that it can perform TLS offloading.

HAProxy will need a single file containing the X509 certificates and the private key, all in https://en.wikipedia.org/wiki/X.509[PEM format], with the following order:

1. The site certificate; this certificate's Common Name refers to the site domain (for example: CN=*.webtide.com) and is signed by Certificate Authority #1.
2. The Certificate Authority #1 certificate; this certificate may be signed by Certificate Authority #2.
3. The Certificate Authority #2 certificate; this certificate may be signed by Certificate Authority #3; and so on until the Root Certificate Authority.
4. The Root Certificate Authority certificate.
5. The private key corresponding to the site certificate.

Refer to the xref:keystore/index.adoc[section about KeyStores] for more information about generating the required certificates and private key.

Now you can create the HAProxy configuration file (in Linux it's typically /etc/haproxy/haproxy.cfg).
This is a minimal configuration:

.haproxy.cfg [source] Copy Chapter

global
tune.ssl.default-dh-param 1024

defaults
timeout connect 10000ms
timeout client 60000ms
timeout server 60000ms

frontend fe_http <1>
mode http
bind *:80

Redirect to https

redirect scheme https code 301

frontend fe_https <2>
mode tcp
bind *:443 ssl no-sslv3 crt /path/to/domain.pem ciphers TLSv1.2 alpn h2,http/1.1
default_backend be_http

backend be_http <3> mode tcp server domain 127.0.0.1:8282 send-proxy-v2 Copy Chapter

<1> The fe_http front-end accepts connections on port 80 and redirects them to use the https scheme.
<2> The fe_https front-end accepts connections on port 443, and it is where the TLS decryption/encryption happens.
You must specify the path to the PEM file containing the TLS key material (the crt /path/to/domain.pem part), the ciphers that are suitable for HTTP/2 (ciphers TLSv1.2), and the ALPN protocols supported (alpn h2,http/1.1).
This front-end then forwards the now decrypted bytes to the backend in mode tcp.
The mode tcp says that HAProxy will not try to interpret the bytes but instead opaquely forwards them to the backend.
<3> The be_http backend will forward (again in mode tcp) the clear-text bytes to a Jetty connector that talks clear-text HTTP/2 and HTTP/1.1 on port 8282.
The send-proxy-v2 directive sends the proxy protocol v2 bytes to the backend server.

On the Jetty side, you need to enable the following modules:

$ java -jar $JETTY_HOME/start.jar --add-modules=proxy-protocol,http2c,http,deploy Copy Chapter

You need to specify the host (127.0.0.1) and port (8282) you have configured in HAProxy when you start Jetty:

$ java -jar $JETTY_HOME/start.jar jetty.http.host=127.0.0.1 jetty.http.port=8282 Copy Chapter

[NOTE]

You want the Jetty connector that listens on port 8282 to be available only to HAProxy, and not to remote clients.

For this reason, you want to specify the jetty.http.host property on the command line (or in $JETTY_BASE/start.d/http.ini to make this setting persistent) to bind the Jetty connector only on the loopback interface (127.0.0.1), making it available to HAProxy but not to remote clients.

If your Jetty instance runs on a different machine and/or on a different (sub)network, you may want to adjust both the back-end section of the HAProxy configuration file and the `jetty.http.host` property to match accordingly.

With this configuration for HAProxy and Jetty, browsers supporting HTTP/2 will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
Likewise, HTTP/1.1 clients will connect to HAProxy, which will decrypt the traffic and send it to Jetty.

The Jetty connector, configured with the http2c and the http modules is able to distinguish whether the incoming bytes are HTTP/2 or HTTP/1.1 and will handle the request accordingly.

The response is relayed back to HAProxy, which will encrypt it and send it back to the remote client.

This configuration offers you efficient TLS offloading, HTTP/2 support and transparent fallback to HTTP/1.1 for clients that don't support HTTP/1.1.

Documentation Jetty Modules Operations Guide Pages Quickstart Index (`documentation/jetty/modules/operations-guide/pages/quickstart/index.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= Faster Jakarta EE Web Application Deployment

The auto discovery features of the Servlet specification can make deployments slow and uncertain.

Auto discovery of Jakarta EE web application configuration can be useful during the development as it allows new features and frameworks to be enabled simply by dropping in a jar file.
However, for production deployment, the need to scan the contents of many jars can have a significant impact at startup time.

The {ee-all}-quickstart modules allows a Jakarta EE web application to be pre-scanned, making startup predictable and faster.
During the pre-scanning all declarative configuration (from web.xml, web-fragment.xml and annotations) are encoded into an effective web.xml, called WEB-INF/quickstart-web.xml, which can be inspected to understand what will be deployed.

[NOTE]

Programmatic configuration is _not_ encoded into the generated `quickstart-web.xml` file.

With the {ee-all}-quickstart modules, web applications that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds.

== Enabling

You can enable the {ee-current}-quickstart module in this way:

[,shell,subs=+attributes] Copy Chapter

$ cd $JETTY_BASE $ java -jar $JETTY_HOME/start.jar --add-modules={ee-current}-quickstart Copy Chapter

The $JETTY-BASE/start.d/quickstart.ini file contains these configurable parameters:

jetty.quickstart.mode::
The values are:
GENERATE:::
In this mode, the quickstart-web.xml file are generated and then the Jetty Server is stopped.
Use this mode first before changing to either AUTO or QUICKSTART.
AUTO:::
Allows to deploy the Jakarta EE web application either with or without a quickstart-web.xml file.
If the quickstart-web.xml file is present, then it will be used, otherwise the web application is deployed normally.
QUICKSTART:::
In this mode, if the quickstart-web.xml file is not present, then the web application deployment will fail.

jetty.quickstart.origin::
Use this parameter to set the name of the attribute in the quickstart-web.xml file that contains the origin of each element.
Knowing the descriptor or annotation from which each element derives can be useful for debugging.
Note that the origin attribute does not conform to the web xml schema, so if you deploy with xml validation, you'll see errors.
It is probably best to do a few trial runs with the attribute set, then turn it off for final generation.

jetty.quickstart.xml::
Use this parameter to change the name of the generated file.
By default this is quickstart-web.xml in the Jakarta EE web application's WEB-INF directory.
The file named by this parameter will always be interpreted relative to the WEB-INF directory.

If your Jakarta EE web application is a +*.war+ file, you will need to either first unpack it yourself, or use a Jetty context XML file (or code equivalent) that calls WebAppContext.setExtractWAR(true).
If you allow Jetty to do the unpacking, it will use the usual mechanisms to find the location where to unpack.
Note that by default Jetty unpacks to a temporary location which is not reused between executions.
You must either specify the directory where to unpack, or make a work directory in your $JETTY_BASE to ensure the unpacked war is preserved and reused across restarts.

Documentation Jetty Modules Operations Guide Pages Security Configuring Form Size (`documentation/jetty/modules/operations-guide/pages/security/configuring-form-size.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

[[limit-form-content]]
= Limiting Form Content

Forms can be a vector for denial-of-service attacks, like explained in xref:programming-guide:security/configuring-form-size.adoc[this section] of the Programming Guide.

== Configuring Form Limits for a Web Application

To configure the form limits for a Jakarta EE web application, the WebAppContext instance can be configured from a Jetty context XML file or from a WEB-INF/jetty-{ee-all}-web.xml file:

[,xml,subs=attributes+] Copy Chapter

Setting the form limits can also be done, for both Jakarta EE web applications and Jetty Core web applications, by setting the following Context attributes.

• org.eclipse.jetty.server.Request.maxFormKeys
• org.eclipse.jetty.server.Request.maxFormContentSize

For Jakarta EE web applications, these attributes can be set in web.xml via the <context-param> element.

For Jakarta EE and Jetty web applications, these attributes can be set in the Jetty context XML file.

For Jakarta EE web applications:

[,xml,subs=attributes+] Copy Chapter

For Jetty Core web applications:

[,xml] Copy Chapter

Documentation Jetty Modules Operations Guide Pages Security Jaas Support (`documentation/jetty/modules/operations-guide/pages/security/jaas-support.adoc`) Copy Section

//
// ========================================================================
// Copyright (c) 1995 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//

= JAAS

JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework.

JAAS can be used for two purposes:

• for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet
• for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed

JAAS authentication is performed in a pluggable fashion.
This permits applications to remain independent from underlying authentication technologies.
New or updated authentication technologies can be plugged under an application without requiring modifications to the application itself.

See Java Authentication and Authorization Service (JAAS) http://java.sun.com/javase/7/docs/technotes/guides/security/jaas/JAASRefGuide.html[Reference Guide] for more information about JAAS.

The Jetty JAAS support aims to dictate as little as possible whilst providing a sufficiently flexible infrastructure to allow users to drop either one of the <<loginmodules,JAAS Login Modules that ships with Jetty>>, or their
own custom https://docs.oracle.com/javase/7/docs/api/javax/security/auth/spi/LoginModule.html[LoginModule]s.

[[configuration]]
== Configuration

[[module]]
=== The jaas module

Enable the jaas module.

[source] Copy Chapter

include::{jetty-home}/modules/jaas.mod[] Copy Chapter

The configurable items in the resulting $JETTY_BASE/start.d/jaas.ini file are:

jetty.jaas.login.conf::
This is the location of the file that will be referenced by the system property java.security.auth.login.config: Jetty sets this system property for you based on the value of this property.
The value of this property is assumed to be relative to $JETTY_BASE.
The default value is etc/login.conf, which resolves to $JETTY_BASE/etc/login.conf.
If you don't want to put your login module configuration file here, you can change this property to point to where it is.

See more about the contents of this file in the <<loginconf,Configuring JAAS>> section.

[[webapp]]
=== Configure the Jakarta EE web application for JAAS

The <realm-name> in web.xml will be used to identify the org.eclipse.jetty.security.jaas.JAASLoginService declaration that integrates JAAS with Jetty.

For example, this web.xml contains a realm called Test JAAS Realm:

[,xml] Copy Chapter

We now need to declare an org.eclipse.jetty.security.jaas.JAASLoginService that references the realm name of Test JAAS Realm.
Here's an example of a suitable XML snippet:

[,xml] Copy Chapter