Lỗi wordpress php incomplete class in home content online 848 năm 2024
|
The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications. Show If you are new to Eclipse Jetty, read on to download, install, start and deploy web applications to Jetty. Jetty is distributed in an artifact that expands in a directory called $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, which should not be modified. Configuration for Jetty is typically done in a directory called $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34. There may be more than one $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directories with different configurations. Jetty supports the deployment of EE8, EE9 and EE10 standard web applications, as well as the deployment of Jetty-specific web applications. For example, the following commands can be used to set up a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory that supports deployment of EE10 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 files and a clear-text HTTP connector: $ export JETTY_HOME=/path/to/jetty-home $ mkdir /path/to/jetty-base $ cd /path/to/jetty-base $ java -jar $JETTY_HOME/start.jar --add-modules=server,http,ee10-deploy The last command creates a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 38 directory and other directories that contain the configuration of the server, including the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 39 directory, in which standard EE10 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 files can be deployed. To deploy Jetty’s demo web applications, run this command: $ java -jar $JETTY_HOME/start.jar --add-module=demos Now you can start the Jetty server with: $ java -jar $JETTY_HOME/start.jar Point your browser at $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 41 to see the demo web applications deployed in Jetty. The Jetty server can be stopped with $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 42 in the terminal window. Read the for more information about Jetty modules, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 and how to customize and start Jetty. The Jetty distribution is available in both $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 45 and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 46 formats; download the one most appropriate for your system, typically $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 45 for Windows and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 46 for other operating systems. After the download, unpacking Jetty will extract the files into a directory called $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 49, where $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 50 is the version of Jetty that you downloaded. For example, installing Jetty 12.0.6 will create a directory called $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 51. It is important that only stable release versions are used in production environments. Versions that have been deprecated or are released as Milestones (M), Alpha, Beta or Release Candidates (RC) are not suitable for production as they may contain security flaws or incomplete/non-functioning feature sets. Unpack Jetty file into a convenient location, such as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 52. The rest of the instructions in this documentation will refer to this location as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, or $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 54. For Windows users, you should unpack Jetty to a path that does not contain spaces. Jetty as a standalone server has no graphical user interface; configuring and running the server is done from the command line. First, create a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE You will typically start Jetty by executing $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 56 from this directory. However, if you try to start Jetty from an empty $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, it will complain that you haven’t enabled any modules: $ java -jar $JETTY_HOME/start.jar Jetty uses a to configure and assemble the server; these modules are enabled and configured in . Since the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory you just created is empty, Jetty has no configuration it can use to assemble the server. See the of this document for more information on the design of Jetty’s module system. You can explore what modules are available with the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 60 flag: $ java -jar $JETTY_HOME/start.jar --list-modules=* Now try to enable the module. If you want to enable support for protocols like secure HTTP/1.1 or HTTP/2 or HTTP/3, or want to configure Jetty behind a load balancer, read . $ java -jar $JETTY_HOME/start.jar --add-modules=http When Jetty enables the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module, it also automatically enables a number of transitive dependencies of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module, such as the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module, the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 65 module, and so on. You can now start Jetty: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar --add-module=demos 0 Jetty is listening on port $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 66 for clear-text HTTP/1.1 connections. But since it has no web applications deployed, it will just reply with $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 67 to every request. Before you , take a moment to see what happened to the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory once you enabled the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module: $ java -jar $JETTY_HOME/start.jar --add-module=demos 1 1 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 70 file configures the server’s logging level; this file was auto-generated when the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 71 module was activated as a transitive dependency of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module. 2 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 73 directory contains the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 configuration files for any modules you have explicitly activated. 3 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 75 file is the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module configuration file, where you can specify values for the . By default, Jetty does not generate $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 configuration files in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 73 for modules activated as transitive dependencies. To manually configure such modules, you should activate them directly via Jetty’s $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 80 flag. In the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 81 file you can find the following (among other contents): http.ini $ java -jar $JETTY_HOME/start.jar --add-module=demos 2 1 This line enables the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module and should not be modified. 2 This commented line specifies the default value for the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 83 property, which is the network port that Jetty uses to listen for clear-text HTTP connections. Try changing the default port. Open $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 81, uncomment the line containing $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 85, and change its value to $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 86: http.ini $ java -jar $JETTY_HOME/start.jar --add-module=demos 3 If you restart Jetty, it will use this new value: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar --add-module=demos 5 You can also specify the value of a module property when you start up Jetty. A property value specified on the command-line in this way will override the value configured in a module’s $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 file. $ java -jar $JETTY_HOME/start.jar --add-module=demos 6 $ java -jar $JETTY_HOME/start.jar --add-module=demos 7 For more detailed information about the Jetty start mechanism, you can read the section. You can deploy two types of web application resources with Jetty:
Jetty supports the deployment of both standard web applications and Jetty context XML files in a specific EE environment, such as the old Java EE 8, or Jakarta EE 9, or Jakarta EE 10. Jetty supports simultaneous deployment of web applications each to a possibly different environment, for example an old Java EE 8 web application alongside a new Jakarta EE 10 web application. Refer to the section about for further information about how to deploy to different environments. In the following sections you can find simple examples of deployments of Jakarta EE 10 web applications. A standard Servlet web application is packaged in either a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file or in a directory with the structure of a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file. Recall that the structure of a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file is as follows: $ java -jar $JETTY_HOME/start.jar --add-module=demos 8 1 Publicly accessible resources such as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 92, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 93, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 94, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 95 files, etc. are placed in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 or in sub-directories of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37. 2 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 98 is a special directory used to store anything related to the web application that must not be publicly accessible, but may be accessed by other resources. 3 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 99 stores the web application’s compiled $ java -jar $JETTY_HOME/start.jar 00 files 4 $ java -jar $JETTY_HOME/start.jar 01 stores the web application’s $ java -jar $JETTY_HOME/start.jar 02 files 5 $ java -jar $JETTY_HOME/start.jar 03 is the web application deployment descriptor, which defines the components and the configuration of your web application. To deploy a standard web application, you need to enable the . The following examples assume you’re deploying a Jakarta EE 10 application; for other versions of Jakarta EE, make sure to activate the corresponding $ java -jar $JETTY_HOME/start.jar 05 module. Refer to the section about for further information about how to deploy to different environments. $ java -jar $JETTY_HOME/start.jar --add-module=demos 9 $ java -jar $JETTY_HOME/start.jar 0 The $ java -jar $JETTY_HOME/start.jar 04 module creates $ java -jar $JETTY_HOME/start.jar 07, which is the directory where Jetty looks for any $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 files or web application directories to deploy. Activating one of Jetty’s $ java -jar $JETTY_HOME/start.jar 05 modules enables web application deployment. Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2, or HTTP/3 (or even all of these protocols) depends on whether the correspondent Jetty protocol modules have been enabled. Refer to the for further information. Now you’re ready to copy a web application to the $ java -jar $JETTY_HOME/start.jar 07 directory. You can use one of the demos shipped with Jetty: $ java -jar $JETTY_HOME/start.jar 1 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory is now: $ java -jar $JETTY_HOME/start.jar 2 Now start Jetty: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar 4 Note the highlighted line that logs the deployment of $ java -jar $JETTY_HOME/start.jar 12. Now you can access the web application by pointing your browser to $ java -jar $JETTY_HOME/start.jar 13. If you want to customize the deployment of your web application — for example, by specifying a $ java -jar $JETTY_HOME/start.jar 14 different from the file/directory name, or by specifying JNDI entries, or by specifying virtual hosts — read . Jetty is an HTTP server and Servlet Container, and supports deployments of web applications. Clients send HTTP requests for specific URIs, such as $ java -jar $JETTY_HOME/start.jar 15. The HTTP requests arrive to the connectors through the network; the Jetty server processes the requests and, based on their URIs, forwards them to the appropriate . There are three main concepts on which the Jetty standalone server is based:
The Jetty standalone server is made of Java components that are assembled together, configured and started to provide different features. A Jetty module provides one or more components that work together to provide typically one feature, although they may provide more than one feature. A Jetty module is nothing more than Jetty components assembled together like you would do using Java APIs, just done in a declarative way using configuration files. What you can do in Java code to assemble Jetty components can be done using Jetty modules. A Jetty module may be dependent on other Jetty modules: for example, the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 Jetty module depends on the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 Jetty module which in turn depends on the $ java -jar $JETTY_HOME/start.jar 19 and $ java -jar $JETTY_HOME/start.jar 20 Jetty modules. Every feature in a Jetty server is enabled by enabling the corresponding Jetty module(s). For example, if you enable only the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 Jetty module, then your Jetty standalone server will only be able to listen to a network port for clear-text HTTP requests. It will not be able to process secure HTTP (i.e. $ java -jar $JETTY_HOME/start.jar
You can even start a Jetty server without listening on a network port — for example because you have enabled a custom module you wrote that provides the features you need. This allows the Jetty standalone server to be as small as necessary: modules that are not enabled are not loaded, don’t waste memory, and you don’t risk a client using a module that you did not know was even there. For more detailed information about the Jetty module system, see . Instead of managing multiple Jetty distributions out of many locations, it is possible to maintain a separation between the binary installation of the standalone Jetty, known as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, and the customizations for your specific environment(s), known as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34. This separation between the binary installation directory and the specific configuration directory allows managing multiple, different, server configurations, and allows for quick, drop-in upgrades of Jetty. There should always only be one $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 (per version of Jetty), but there can be many $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directories that reference it. This separation between $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 allows Jetty upgrades without affecting your web applications. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 contains the Jetty runtime and libraries and the default configuration, while a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 contains your web applications and any override of the default configuration. For example, with the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 installation the default value for the network port for clear-text HTTP is $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 66. However, you may want that port to be $ java -jar $JETTY_HOME/start.jar 35, because that is configured to forward to the backend on port $ java -jar $JETTY_HOME/start.jar 35. In this case, you configure the clear-text HTTP port in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, not in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33. When you upgrade Jetty, you will upgrade only the files in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, and all the configuration in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 will remain unchanged, keeping your clear-text HTTP port at $ java -jar $JETTY_HOME/start.jar 35. Installing the Jetty runtime and libraries in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 also allows you to leverage file system permissions: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 may be owned by an administrator user (so that only administrators can upgrade it), while $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directories may be owned by a less privileged user. If you had changed the default configuration in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, when you upgrade Jetty, say from version $ java -jar $JETTY_HOME/start.jar 46 to version $ java -jar $JETTY_HOME/start.jar 47, your changes would be lost. Maintaining all the changes in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, and having to reconfigure these with each upgrade results in a massive commitment of time and effort. To recap: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 This is the location for the Jetty binaries. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 This is the location for your configurations and customizations to the Jetty binaries. The Jetty start mechanism provides two features:
The Jetty start mechanism is invoked by executing $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 56 from within your $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, and you can think of it as the Jetty command line program, similar to many Unix/Windows command line programs. For example, you can ask for help: $ java -jar $JETTY_HOME/start.jar 5 Or you can list all available modules (or only those with a specific tag): $ java -jar $JETTY_HOME/start.jar 6 You can enable a module, for example the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module: $ java -jar $JETTY_HOME/start.jar --add-modules=http Once you have one or more module enabled, you can display the current configuration, to verify that the configuration is correct: $ java -jar $JETTY_HOME/start.jar 8 You can enable a Jetty demo module, which will deploy a demo web application: $ java -jar $JETTY_HOME/start.jar 9 Finally, you can start Jetty: $ java -jar $JETTY_HOME/start.jar The Jetty start mechanism is invoked by executing $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 56, from within a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory, with zero or more command line options: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 1 The Jetty start mechanism has two main modes of operation:
Within the Jetty start mechanism, the source of configurations is layered in this order, from higher priority to lower priority:
You can enable Jetty modules persistently across restarts with the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 80 command: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 2 The Jetty start mechanism will look for the specified modules following the order specified above. In the common case (without a $ java -jar $JETTY_HOME/start.jar 63 directory), it will look in $ java -jar $JETTY_HOME/start.jar 67 first and then in $ java -jar $JETTY_HOME/start.jar 68. Since the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 modules are standard Jetty modules, they are present in $ java -jar $JETTY_HOME/start.jar 68 and loaded from there. When you enable a Jetty module, the Jetty start mechanism:
For example, enabling the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 modules results in the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory to have the following structure: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 3 The $ java -jar $JETTY_HOME/start.jar 81 is created by the $ java -jar $JETTY_HOME/start.jar 76 directives of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 65 module, which is a transitive dependency of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module. A module is enabled because the correspondent $ java -jar $JETTY_HOME/start.jar 72 file contains a $ java -jar $JETTY_HOME/start.jar 86 directive. Commenting out the $ java -jar $JETTY_HOME/start.jar 86 directive effectively disables the module. Deleting the correspondent $ java -jar $JETTY_HOME/start.jar 72 file also disables the module. You can now edit the $ java -jar $JETTY_HOME/start.jar 72 configuration files, typically by uncommenting properties to change their default value. The $ java -jar $JETTY_HOME/start.jar 72 configuration file may be missing, if the correspondent module is a transitive dependency. You can easily generate the configuration file by explicitly enabling the module, for example to generate the $ java -jar $JETTY_HOME/start.jar 92 configuration file you would issue the following command (the module order does not matter): $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 4 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory structure is now: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 5 You want to edit the $ java -jar $JETTY_HOME/start.jar 72 configuration files so that the configuration is applied every time Jetty is started (or re-started). For example, $ java -jar $JETTY_HOME/start.jar 95 contains the following property, commented out: You can change the clear-text HTTP port Jetty listens to by uncommenting that property and changing its value: When Jetty is started (or re-started) this configuration is applied and Jetty will listen for clear-text HTTP/1.1 on port $ java -jar $JETTY_HOME/start.jar 96. You can also enable a module transiently, only for the current execution of the $ java -jar $JETTY_HOME/start.jar 60 command. If you have an empty $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, the following command enables the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 modules, but does not create any $ java -jar $JETTY_HOME/start.jar 72 files. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 6 Since there are no $ java -jar $JETTY_HOME/start.jar 72 files, you can only customize the properties via the command line, for example: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 7 Enabling modules on the command line is useful to verify that the modules work as expected, or to try different configurations. It is possible to enable some module persistently via $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 80 and some other module transiently via 04. Remember that once the current execution terminates, the modules enabled transiently on the command line via 04 and their configuration are not saved and will not be enabled on the next execution (unless you specify them again on the command line). You can add your own modules by adding a 06 file. For example, you may want to add a Postgres JDBC driver to the server class-path, to avoid that each deployed web application bring its own version. This allows you to control the exact Postgres JDBC driver version for all web applications. Create the 07 file: postgresql.mod $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 8 Then enable it: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 9 Enabling the 08 module will execute the $ java -jar $JETTY_HOME/start.jar 76 directive (downloading the $ java -jar $JETTY_HOME/start.jar 02 file from Maven Central if not already present) and create the 11 with the content of the $ java -jar $JETTY_HOME/start.jar 74 section. The 13 section ensures that the specified file is in the server class-path when Jetty is started. Using a custom Jetty module, you can customize the JVM startup options. This is useful if you need to start Jetty and want to specify JVM options such as:
Start by creating 19: jvm.mod $ java -jar $JETTY_HOME/start.jar 0 Enable it: $ java -jar $JETTY_HOME/start.jar 1 Since the module defines an 20 section, it will fork another JVM when Jetty is started. This means that when you start Jetty, there will be two JVMs running: one created by you when you run $ java -jar $JETTY_HOME/start.jar 60, and another forked by the Jetty start mechanism with the JVM options you specified (that cannot be applied to an already running JVM). The second JVM forked by the Jetty start mechanism when one of the modules requires forking, for example a module that contains an 20 section, may not be desirable, and may be avoided as explained in . Once you have enabled and configured the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, you can display the configuration to verify that it is correct. Using the standard $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 and $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 Jetty modules, and the 08 and 27 custom Jetty module defined above, you obtain: $ java -jar $JETTY_HOME/start.jar 8 $ java -jar $JETTY_HOME/start.jar 3 Note how the configuration displayed above includes:
The Jetty start mechanism can display a full JVM command line that will start Jetty with the configuration you specified, with the 33 option: $ java -jar $JETTY_HOME/start.jar 4 The full JVM command line generated by 33 can be split in various parts that can be used individually, for example in scripts. Furthermore, Jetty modules may specify the 35 option that will fork a second JVM to start Jetty, which may not be desirable. Some option, such as 36, imply 35, as it won’t be possible to modify the module-path in the already started JVM. To start Jetty without forking a second JVM, the 33 option can be used to generate a command line that is then executed so that starting Jetty only spawns one JVM. You can use the 33 option as explained below to avoid forking a second JVM when using modules that have the 20 section, or the 35 option, or when using the 36 option. For example, using the 33 option with the 44 introduced in produces the following command line: $ java -jar $JETTY_HOME/start.jar 4 $ java -jar $JETTY_HOME/start.jar 6 You can then run the generated command line. For example, in the Linux 45 shell you can run it by wrapping it into 46: $ java -jar $JETTY_HOME/start.jar 7 The 33 option is quite flexible and below you can find a few examples of how to use it to avoid forking a second JVM, or generating scripts or creating an arguments file that can be passed to (a possibly alternative) 48 executable. To display the 48 executable used to start Jetty: $ java -jar $JETTY_HOME/start.jar 8 $ java -jar $JETTY_HOME/start.jar 9 To display the JVM options: 0 1 To display the JVM class-path: 2 3 To display the JVM class-path and module-path, if you want to with the 36 option: 4 5 To display the JVM main class: 6 7 8 9 The main class is typically Jetty’s 51 class that accepts, as program arguments, a list of properties and a list of Jetty XML files to process. The Jetty XML files compose together the Jetty components that are then configured with the values from the command line properties. To display the program arguments passed to the main class: $ java -jar $JETTY_HOME/start.jar --list-modules=* 0 $ java -jar $JETTY_HOME/start.jar --list-modules=* 1 Note how the program arguments are a list of properties in the form 52 and a list of Jetty XML files. The various parts of the full JVM command line can be combined to leverage the arguments file feature (that is, specify the JVM options in a file rather than on the command line) that is built-in in the 48 executable: $ java -jar $JETTY_HOME/start.jar --list-modules=* 2 Using 54 can be used to avoid that the Jetty start mechanism forks a second JVM when using modules that require forking: $ java -jar $JETTY_HOME/start.jar --list-modules=* 3 The output of different 33 executions can be creatively combined in a shell script: $ java -jar $JETTY_HOME/start.jar --list-modules=* 4 After you have configured the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory, as explained in , you can start Jetty as a standalone server. In the start mode, the Jetty start mechanism computes a JVM command line with JVM options, system properties, class-path, module-path, main class and program arguments, and then executes it, forking a new JVM if necessary. The Jetty start mechanism performs these steps:
When the Jetty server is started in-JVM, the server class-path gathered by processing the enabled modules is organized in a 63, the Jetty Start ClassLoader, that is a child of the System ClassLoader: The System ClassLoader only has $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 56 in its class-path, since the JVM was started with $ java -jar $JETTY_HOME/start.jar 60. The Jetty Start ClassLoader has in its class-path the $ java -jar $JETTY_HOME/start.jar 02 files gathered by processing the enabled modules, typically from 67, but possibly also from 68 if custom modules extend the server class-path with their own $ java -jar $JETTY_HOME/start.jar 02 files. When the Jetty server is started in a forked JVM, there will be two JVMs: one started by you with $ java -jar $JETTY_HOME/start.jar 60 and one forked by the Jetty start mechanism. In the forked JVM, the System ClassLoader has the server class-path and/or module-path in its class-path, since the forked JVM is started with 71: It is worth mentioning that there are two standard Jetty modules that allow you to easily add entries to the Jetty server class-path:
The Jetty start mechanism eventually invokes, by default, main class 89, passing properties and as program arguments. The Jetty XML files are nothing more than Java code in XML format. The XML files are processed to instantiate Jetty components such as 90 or 91. The components are then assembled together to provide the configured Jetty features. The Jetty XML files are parametrized using properties, and a property is just a name/value pair. This parametrization of the XML files allows an XML file that resides in 92 to declare a property such as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 83, and allow this property to be set in a $ java -jar $JETTY_HOME/start.jar 95 file, so that you don’t need to change the XML files in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33, but only change files in your $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34. You can write your own with your own Jetty XML files, and your own properties, to further customize Jetty. Jetty modules are proper JPMS modules: each Jetty module has a 97 file. This makes possible to run Jetty from the module-path, rather than the class-path. To start Jetty on the module-path rather than the class-path, it is enough to add the 36 option to the command line, for example: $ java -jar $JETTY_HOME/start.jar --list-modules=* 5 The 36 option implies the 35 option. When running on the module-path using the 36 option, the Jetty start mechanism will fork a second JVM passing it the right JVM options to run on the module-path. Therefore, you will have two JVMs running: one that runs $ java -jar $JETTY_HOME/start.jar --list-modules=* 02 and one that runs Jetty on the module-path. Forking a second JVM may be avoided as explained in . When Jetty is started in JPMS mode, all JPMS modules in the module-path are added to the set of JPMS root modules through the JVM option $ java -jar $JETTY_HOME/start.jar --list-modules=* 03. For a $ java -jar $JETTY_HOME/start.jar 02 file that is not a JPMS module, but is on the module-path, the JVM will assume internally it is an automatic JPMS module, with a JPMS module name derived from the $ java -jar $JETTY_HOME/start.jar 02 file name. Rather than adding the 36 option to the command line, you can use a custom Jetty module to centralize your JPMS configuration, where you can specify additional JPMS directives. Create the $ java -jar $JETTY_HOME/start.jar --list-modules=* 07 file: jpms.mod $ java -jar $JETTY_HOME/start.jar --list-modules=* 6 The $ java -jar $JETTY_HOME/start.jar --list-modules=* 08 section with 36 is equivalent to passing the 36 option to the command line (see also ). The $ java -jar $JETTY_HOME/start.jar --list-modules=* 11 section allows you to specify additional JPMS configuration, for example additional $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 80 options, or $ java -jar $JETTY_HOME/start.jar --list-modules=* 13 options, etc. (see also ). Then enable it: $ java -jar $JETTY_HOME/start.jar --list-modules=* 7 Now you can start Jetty without extra command line options, and it will start in JPMS mode because you have enabled the $ java -jar $JETTY_HOME/start.jar --list-modules=* 14 module. Web applications may need additional services from the Servlet Container, such as JDBC $ java -jar $JETTY_HOME/start.jar --list-modules=* 15 references or JTA $ java -jar $JETTY_HOME/start.jar --list-modules=* 16 references. For example, for JDBC it is typical to store, in JNDI, a reference to the connection pool’s $ java -jar $JETTY_HOME/start.jar --list-modules=* 15 or directly a reference to the JDBC driver’s $ java -jar $JETTY_HOME/start.jar --list-modules=* 15 (for example, $ java -jar $JETTY_HOME/start.jar --list-modules=* 19). Jetty needs to be able to instantiate those classes and therefore needs to be able to load those classes and all their super-classes, among which includes $ java -jar $JETTY_HOME/start.jar --list-modules=* 20. When Jetty runs on the class-path, this is easily achieved by using a as explained in . However, when running on the module-path, things are quite different. When Jetty tries to load, for example, class $ java -jar $JETTY_HOME/start.jar --list-modules=* 19, it must be in a JPMS module that is resolved in the run-time module graph. Furthermore, any dependency, for example classes from the $ java -jar $JETTY_HOME/start.jar --list-modules=* 22 JPMS module, must also be in a module present in the resolved module graph. Thanks to the fact that when Jetty starts in JPMS mode the $ java -jar $JETTY_HOME/start.jar --list-modules=* 03 option is added to the JVM command line, every $ java -jar $JETTY_HOME/start.jar 02 file in the module-path is also present in the module graph. There are now two cases for the $ java -jar $JETTY_HOME/start.jar --list-modules=* 25 file: either it is a proper JPMS module, or it is an automatic JPMS module (either an explicit automatic JPMS module with the $ java -jar $JETTY_HOME/start.jar --list-modules=* 26 attribute in the manifest, or an implicit automatic JPMS module whose name is derived from the $ java -jar $JETTY_HOME/start.jar 02 file name). If the $ java -jar $JETTY_HOME/start.jar --list-modules=* 25 file is a proper JPMS module, then there is nothing more that you should do: the $ java -jar $JETTY_HOME/start.jar --list-modules=* 25 file is in the module-path, and all the modules in the module-path are in the module graph, and any dependency declared in the 97 will be added to the module graph. Otherwise, $ java -jar $JETTY_HOME/start.jar --list-modules=* 25 file is an automatic module, and will likely have a dependency on the JDK-bundled $ java -jar $JETTY_HOME/start.jar --list-modules=* 22 JPMS module. However, the $ java -jar $JETTY_HOME/start.jar --list-modules=* 22 JPMS module is not in the module graph, because automatic modules do not have a way to declare their dependencies. For this reason, you have to manually add the $ java -jar $JETTY_HOME/start.jar --list-modules=* 22 dependency to the module graph. Using the $ java -jar $JETTY_HOME/start.jar --list-modules=* 35 introduced in as an example, modify your custom module in the following way: postgresql.mod $ java -jar $JETTY_HOME/start.jar --list-modules=* 8 The $ java -jar $JETTY_HOME/start.jar --list-modules=* 11 section is only used when Jetty is started on the module-path. When Jetty is started, the Jetty components that you have configured by enabling Jetty modules are assembled and started. If you have started Jetty from a terminal, you can exit the Jetty JVM by hitting Ctrl+C on the same terminal. Similarly, from a different terminal, you can exit the Jetty JVM using $ java -jar $JETTY_HOME/start.jar --list-modules=* 37 or $ java -jar $JETTY_HOME/start.jar --list-modules=* 38. In the three cases above, the JVM is exited, but by default Jetty components are not stopped. If you want to stop the Jetty components, to stop Jetty more gracefully, you can start Jetty with this property: $ java -jar $JETTY_HOME/start.jar --list-modules=* 9 This property can also be set in $ java -jar $JETTY_HOME/start.jar --list-modules=* 39 so that it is persistently configured across Jetty restarts (see also ). The $ java -jar $JETTY_HOME/start.jar --list-modules=* 41 property configures a JVM shutdown hook that is run, stopping the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 instance, when the JVM exits. Obviously, the JVM can also be stopped with $ java -jar $JETTY_HOME/start.jar --list-modules=* 43 that exits the process abruptly without running the JVM shutdown hooks. You can configure a Jetty server so that it can be stopped by remote clients using a command sent through a TCP socket. You can start Jetty with the following properties:
$ java -jar $JETTY_HOME/start.jar --add-modules=http 0 $ java -jar $JETTY_HOME/start.jar --add-modules=http 1 In the example above, Jetty is started with just the $ java -jar $JETTY_HOME/start.jar --list-modules=* 46 property, and the $ java -jar $JETTY_HOME/start.jar --list-modules=* 48 is printed on the terminal when Jetty starts. You can choose your own $ java -jar $JETTY_HOME/start.jar --list-modules=* 48, but make sure it’s a strong password. A remote client can now use the Jetty start mechanism to stop the remote Jetty server: $ java -jar $JETTY_HOME/start.jar --add-modules=http 2 Note the $ java -jar $JETTY_HOME/start.jar --list-modules=* 52 command along with the $ java -jar $JETTY_HOME/start.jar --list-modules=* 46 and $ java -jar $JETTY_HOME/start.jar --list-modules=* 48 properties. The $ java -jar $JETTY_HOME/start.jar --list-modules=* 48 must be the same as the one of remote Jetty server, either the one you chose, or the one printed on the terminal when Jetty starts. Remote clients can wait for the remote Jetty server to shut down by specifying the $ java -jar $JETTY_HOME/start.jar --list-modules=* 56 property with the number of seconds to wait: $ java -jar $JETTY_HOME/start.jar --add-modules=http 3 If the time specified elapses, without the confirmation that the remote Jetty server stopped, then the $ java -jar $JETTY_HOME/start.jar --list-modules=* 52 command exits with a non-zero return code. The steps performed by the Jetty start mechanism are logged by the $ java -jar $JETTY_HOME/start.jar --list-modules=* 58 class, that outputs directly, by default, to $ java -jar $JETTY_HOME/start.jar --list-modules=* 59. This is necessary to avoid that the Jetty start mechanism depend on logging libraries that may clash with those defined by Jetty logging modules, when Jetty is started in-VM. This section is about the logging performed by the Jetty start mechanism before it configures and starts Jetty. See the for information about logging when Jetty starts. You can enable DEBUG level logging with the $ java -jar $JETTY_HOME/start.jar --list-modules=* 60 command line option, for both the tool and start modes: $ java -jar $JETTY_HOME/start.jar --add-modules=http 4 You can send the start log output to a file, by default relative to $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, with the $ java -jar $JETTY_HOME/start.jar --list-modules=* 62 option: $ java -jar $JETTY_HOME/start.jar --add-modules=http 5 This is useful for capturing startup issues where the Jetty-specific logger has not yet kicked in due to a possible startup configuration error. $ java -jar $JETTY_HOME/start.jar --add-modules=http 6 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 $ java -jar $JETTY_HOME/start.jar --list-modules=* 63 file, where $ java -jar $JETTY_HOME/start.jar --list-modules=* 64 is the module name (see also the ). Jetty module files are read from the typical , under the 58 subdirectory; from higher priority to lower priority:
The standard Jetty modules that Jetty provides out-of-the-box are under $ java -jar $JETTY_HOME/start.jar 68. A Jetty module has a unique name. The module name is by default derived from the file name, so module file $ java -jar $JETTY_HOME/start.jar --list-modules=* 71 identifies a module named $ java -jar $JETTY_HOME/start.jar --list-modules=* 72. However, a module file may specify a 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 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module depends on the $ java -jar $JETTY_HOME/start.jar 20 module, but there is no correspondent $ java -jar $JETTY_HOME/start.jar --list-modules=* 75 file. However, the $ java -jar $JETTY_HOME/start.jar --list-modules=* 76 file has, among others, this section: logging-jetty.mod $ java -jar $JETTY_HOME/start.jar --add-modules=http 7 This section means that the $ java -jar $JETTY_HOME/start.jar --list-modules=* 76 file provides the virtual module $ java -jar $JETTY_HOME/start.jar 20, and it is the default provider. The $ java -jar $JETTY_HOME/start.jar --list-modules=* 79 file has a similar section: If there are no enabled modules that provide the $ java -jar $JETTY_HOME/start.jar 20 virtual module, either explicitly or transitively, then the default provider is used, in this case $ java -jar $JETTY_HOME/start.jar --list-modules=* 76. Otherwise, a module that provides the $ java -jar $JETTY_HOME/start.jar 20 virtual module is explicitly or transitively enabled, and the default provider is not used. 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 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 , under the $ java -jar $JETTY_HOME/start.jar --list-modules=* 83 subdirectory; from higher priority to lower priority:
The standard Jetty modules XML files that Jetty provides out-of-the-box are under 92. For example, a Jetty XML file that allocates Jetty’s $ java -jar $JETTY_HOME/start.jar --list-modules=* 89 could be as simple as: jetty-threadpool.xml $ java -jar $JETTY_HOME/start.jar --add-modules=http 8 Note how the Jetty XML file above is allocating (with the $ java -jar $JETTY_HOME/start.jar --list-modules=* 90 element) a $ java -jar $JETTY_HOME/start.jar --list-modules=* 89 instance, giving it the unique $ java -jar $JETTY_HOME/start.jar --list-modules=* 92 of $ java -jar $JETTY_HOME/start.jar --list-modules=* 93 (so that other modules can reference it, if they need to). It is then calling the setter method $ java -jar $JETTY_HOME/start.jar --list-modules=* 94 with the value defined by the $ java -jar $JETTY_HOME/start.jar --list-modules=* 95; if the property value is not defined, it will have the default value of $ java -jar $JETTY_HOME/start.jar --list-modules=* 96. This is nothing more than Java code in XML format with configurable properties support that can be leveraged by the . 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 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 files as described in , or on the command line as described in ). Remember that the standard Jetty XML files in 92 should not be modified. Even if you need to modify a standard Jetty component, write a new Jetty XML file, save it under $ java -jar $JETTY_HOME/start.jar --list-modules=* 84, and create a so that it gets processed when Jetty starts. A Jetty module property is declared in the via the $ java -jar $JETTY_HOME/start.jar --add-modules=http 00 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. You can declare your own properties, but the $ java -jar $JETTY_HOME/start.jar --add-modules=http 01 namespace is reserved. A module property can be given a value in a Jetty module $ java -jar $JETTY_HOME/start.jar --list-modules=* 08 section (see ), in a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 file as described in , or on the command line as described in . 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: $ java -jar $JETTY_HOME/start.jar --add-modules=http 9 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 ). For example: 0 Lines that start with $ java -jar $JETTY_HOME/start.jar --add-modules=http 04 are comments. 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 $ java -jar $JETTY_HOME/start.jar --add-modules=http 05 command. A module name with an optional $ java -jar $JETTY_HOME/start.jar --add-modules=http 06 specifier. As explained in the , there can be many module files each providing a different implementation for the same feature. The format is: 1 where the $ java -jar $JETTY_HOME/start.jar --add-modules=http 07 part is optional and specifies that the module is the default provider. A list of module names that this module depends on. For example, the standard module $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 depends on module $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64. Enabling the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module also enables, transitively, the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module, since the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module cannot work without the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module; when the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module is transitively enabled, the modules it depends on will be transitively enabled, and so on recursively. The $ java -jar $JETTY_HOME/start.jar --add-modules=http 15 directive establishes a 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 section, the order of processing of XML files defined in the section, etc. This directive indicates that this module is ordered after the listed module names, if they are enabled. For example, module $ java -jar $JETTY_HOME/start.jar 22 is $ java -jar $JETTY_HOME/start.jar --add-modules=http 17 module $ java -jar $JETTY_HOME/start.jar --add-modules=http 18. Enabling the $ java -jar $JETTY_HOME/start.jar 22 module does not enable the $ java -jar $JETTY_HOME/start.jar --add-modules=http 18 module. However, if the $ java -jar $JETTY_HOME/start.jar --add-modules=http 18 module is enabled (explicitly or transitively), then the $ java -jar $JETTY_HOME/start.jar 22 module is after the $ java -jar $JETTY_HOME/start.jar --add-modules=http 18 module. In this way, you are guaranteed that the $ java -jar $JETTY_HOME/start.jar 22 module is processed after the $ java -jar $JETTY_HOME/start.jar --add-modules=http 18 module. This directive indicates that this module is ordered before the listed module names, if they are enabled. One use of this directive is to create a prerequisite module without the need to modify the $ java -jar $JETTY_HOME/start.jar --add-modules=http 26 directive of an existing module. For example, to create a custom 90 subclass instance to be used by the standard $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module, without modifying the existing $ java -jar $JETTY_HOME/start.jar --add-modules=http 29 file nor the $ java -jar $JETTY_HOME/start.jar --add-modules=http 30 file that it uses. This can be achieved by creating the $ java -jar $JETTY_HOME/start.jar --add-modules=http 31 : custom-server.mod 2 The $ java -jar $JETTY_HOME/start.jar --add-modules=http 32 file is the following: custom-server.xml 3 The presence of the $ java -jar $JETTY_HOME/start.jar --add-modules=http 33 directive in $ java -jar $JETTY_HOME/start.jar --add-modules=http 34 causes the processing of the $ java -jar $JETTY_HOME/start.jar --add-modules=http 32 file to happen before the processing of the standard $ java -jar $JETTY_HOME/start.jar --add-modules=http 30 file referenced by the standard $ java -jar $JETTY_HOME/start.jar --add-modules=http 29 Jetty module. Thus, the instance assigned to the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 identifier is your custom $ java -jar $JETTY_HOME/start.jar --add-modules=http 39 instance from the $ java -jar $JETTY_HOME/start.jar --add-modules=http 32 file; this instance is then used while processing the $ java -jar $JETTY_HOME/start.jar --add-modules=http 30 file. 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 $ java -jar $JETTY_HOME/start.jar --add-modules=http 42, such as $ java -jar $JETTY_HOME/start.jar --add-modules=http 43. The file or directory will be created relative to $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, if not already present. For example: 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: 4 where $ java -jar $JETTY_HOME/start.jar --add-modules=http 45 is optional, and $ java -jar $JETTY_HOME/start.jar --add-modules=http 46 after the $ java -jar $JETTY_HOME/start.jar --add-modules=http 47 is the path under $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 where the downloaded file should be saved. For example: 5 BaseHome An URI representing a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 33 resource to be copied in $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34, 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: 6 For example: 7 HTTP URL An $ java -jar $JETTY_HOME/start.jar --add-modules=http 51 or $ java -jar $JETTY_HOME/start.jar --add-modules=http 52 URL to be downloaded, if not already present. The format is: 8 For example: 9 The $ java -jar $JETTY_HOME/start.jar --add-modules=http 53 section if often used in conjunction with the $ java -jar $JETTY_HOME/start.jar 76 section. For example: $ java -jar $JETTY_HOME/start.jar 0 The $ java -jar $JETTY_HOME/start.jar --list-modules=* 25 artifact is downloaded from Maven Central, if not already present, into the $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory when the module is enabled. When Jetty starts, the $ java -jar $JETTY_HOME/start.jar --add-modules=http 57 will be in the server class-path (or module-path). Jetty XML files are read from the typical , under the $ java -jar $JETTY_HOME/start.jar --list-modules=* 83 subdirectory. Standard Jetty XML files are under 92, while custom Jetty XML files are typically under $ java -jar $JETTY_HOME/start.jar --list-modules=* 84. For example: $ java -jar $JETTY_HOME/start.jar 1 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 for the list of command line options), and/or . A property defined in the $ java -jar $JETTY_HOME/start.jar --list-modules=* 08 section is available in the $ java -jar $JETTY_HOME/start.jar 75 module file for property expansion, for example: $ java -jar $JETTY_HOME/start.jar 2 In the example above, the 13 section contains $ java -jar $JETTY_HOME/start.jar --add-modules=http 64, a reference to property $ java -jar $JETTY_HOME/start.jar --add-modules=http 65 whose value is defined in the $ java -jar $JETTY_HOME/start.jar --list-modules=* 08 section. The expression $ java -jar $JETTY_HOME/start.jar --add-modules=http 67 expands the property replacing the expression with the property value. See also the for additional examples about the $ java -jar $JETTY_HOME/start.jar --list-modules=* 08 section. A list of properties to be copied in the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 file generated when . The list of properties is derived from the 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. A list of JVM command line options and/or system properties passed to a forked JVM. When the 20 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 20 sections of the enabled modules. This is necessary because JVM options such as 14 (that specifies the max JVM heap size) cannot be changed in a running JVM. For an example, see . You can avoid that the Jetty start mechanism forks the second JVM, as explained in . A list of JVM command line options related to the Java Module System. The directives are: add-modules Equivalent to the JVM option $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 80. The format is: $ java -jar $JETTY_HOME/start.jar 3 where $ java -jar $JETTY_HOME/start.jar --add-modules=http 74 is a JPMS module name. patch-module Equivalent to the JVM option $ java -jar $JETTY_HOME/start.jar --add-modules=http 75. The format is: $ java -jar $JETTY_HOME/start.jar 4 where $ java -jar $JETTY_HOME/start.jar --add-modules=http 74 is a JPMS module name. add-opens Equivalent to the JVM option $ java -jar $JETTY_HOME/start.jar --list-modules=* 13. The format is: $ java -jar $JETTY_HOME/start.jar 5 where $ java -jar $JETTY_HOME/start.jar --add-modules=http 74 and $ java -jar $JETTY_HOME/start.jar --add-modules=http 79 are a JPMS module names. add-exports Equivalent to the JVM option $ java -jar $JETTY_HOME/start.jar --add-modules=http 80. The format is: $ java -jar $JETTY_HOME/start.jar 6 where $ java -jar $JETTY_HOME/start.jar --add-modules=http 74 and $ java -jar $JETTY_HOME/start.jar --add-modules=http 79 are a JPMS module names. add-reads Equivalent to the JVM option $ java -jar $JETTY_HOME/start.jar --add-modules=http 80. The format is: $ java -jar $JETTY_HOME/start.jar 7 where $ java -jar $JETTY_HOME/start.jar --add-modules=http 74 and $ java -jar $JETTY_HOME/start.jar --add-modules=http 79 are a JPMS module names. 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 $ java -jar $JETTY_HOME/start.jar --add-modules=http 86 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: $ java -jar $JETTY_HOME/start.jar 8 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: A Jetty module with such a section will only work for Jetty 10.0.x or later. In addition to the modules that come packaged with Jetty, you can create your own custom modules. Make sure you have read the 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. 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 OpenSSL cipher list format. The Jetty class that handles the TLS configuration is $ java -jar $JETTY_HOME/start.jar --add-modules=http 87, and it already has a method $ java -jar $JETTY_HOME/start.jar --add-modules=http 88; however, you need to pass your custom implementation, which cannot be represented with a simple module property. The $ java -jar $JETTY_HOME/start.jar --add-modules=http 87 component is already allocated by the standard Jetty module $ java -jar $JETTY_HOME/start.jar --add-modules=http 90, so what you need to do is the following:
Start with the custom Jetty XML file, $ java -jar $JETTY_HOME/start.jar --add-modules=http 95: custom-ssl.xml $ java -jar $JETTY_HOME/start.jar 9 1 Reference the existing $ java -jar $JETTY_HOME/start.jar --add-modules=http 87 object created by the standard $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 module using its $ java -jar $JETTY_HOME/start.jar --list-modules=* 92. 2 Call the $ java -jar $JETTY_HOME/start.jar --add-modules=http 99 method. 3 Instantiate your custom cipher comparator. 4 Pass to the constructor the ordering string in OpenSSL format, reading it from the module property 00. The cipher list used above may not be secure — it’s just an example. Then write your custom module in the 01 file: custom-ssl.mod $ java -jar $JETTY_HOME/start.jar --add-module=demos 00 1 A tag that characterizes this custom module (see ). 2 This custom module depends on the standard $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 module. 3 The custom cipher comparator class is compiled and packaged into this $ java -jar $JETTY_HOME/start.jar 02 file. 4 The custom Jetty XML file from above. 5 The text that will be copied in the 04 file when this custom module will be enabled. Now you can the custom module with the following command issued from the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory: $ java -jar $JETTY_HOME/start.jar --add-module=demos 01 The command above will produce the following $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory structure: $ java -jar $JETTY_HOME/start.jar --add-module=demos 02 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 $ java -jar $JETTY_HOME/start.jar 74 section of the custom module file, so that when the custom module is enabled, a correspondent 04 file is created. In this way, updating the cipher list won’t require you to update the XML file, but just the 04 file. 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 : you write a custom 10 subclass that overrides the methods corresponding to the events you are interested in.
Let’s start with the auditing component, sketched below: $ java -jar $JETTY_HOME/start.jar --add-module=demos 03 Let’s assume that this class is compiled and packaged into 14, and that it has a dependency on 15. Both $ java -jar $JETTY_HOME/start.jar 02 files will be put in the $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory. Next, let’s write the Jetty XML file that wires the auditing component to the 18, 19: acme-audit.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 04 1 Reference $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 instance. 2 Call 21 on the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 so that the auditing component will be inserted just after the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 and just before its child 13. 3 Instantiate the auditing component. 4 Configure the auditing component with a property. The last step is to create the custom Jetty module file for the auditing component, 25: acme-audit.mod $ java -jar $JETTY_HOME/start.jar --add-module=demos 05 1 The tags that characterize this custom module (see ). 2 This custom module depends on the standard $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module. 3 The $ java -jar $JETTY_HOME/start.jar 02 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 28 file when this custom module will be enabled. Now you can the custom auditing module with the following command issued from the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory: $ java -jar $JETTY_HOME/start.jar --add-module=demos 06 The command above will produce the following $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory structure: $ java -jar $JETTY_HOME/start.jar --add-module=demos 07 Enabling the custom auditing component will create the 31 module configuration file that you can edit to configure auditing properties. The 32 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 08 The 34 module allows you to configure the server-wide 36 pool. Pooling 36s results in less memory usage and less pressure on the Garbage Collector. 36s 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 36 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 40: $ java -jar $JETTY_HOME/start.jar --add-module=demos 09 Among the configurable properties, the most relevant are: 41 This property allows you to cap the max heap memory retained by the pool. 42 This property allows you to cap the max direct memory retained by the pool. The 43 module captures 45 and $ java -jar $JETTY_HOME/start.jar --list-modules=* 59 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 47 property. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 10 This module enables webapp deployment from the $ java -jar $JETTY_HOME/start.jar 07 directory. Deployment is managed via a 50 component that watches a directory for changes. See for more information. TODO The 51 module provides support for the CORS protocol implemented by browsers when performing cross-origin requests. This module installs the in the 13 tree; 53 inspects cross-origin requests and adds the relevant CORS response headers. 53 should be used when an application performs cross-origin requests to your server, to protect from cross-site request forgery attacks. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 11 This module enables webapp deployment from the $ java -jar $JETTY_HOME/start.jar 07 directory. Deployment is managed via a 50 component that watches a directory for changes. See for more information. Adding files or directories to this monitored directory will cause the 50 to deploy them as web applications; updating files already existing in this monitored directory will cause the 50 to re-deploy the corresponding web application; removing files in this monitored directory will cause the 50 to "undeploy" the corresponding web application. (You can find a more detailed discussion of these rules in the section.) Multiple versions of this module exist ( $ java -jar $JETTY_HOME/start.jar
$ java -jar $JETTY_HOME/start.jar 04 Jetty module are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 12 Among the configurable properties, the most relevant are: 65 The name of the monitored directory. 66 The scan period in seconds, that is how frequently the 50 wakes up to scan the monitored directory for changes. Setting 68 disabled hot deployment so that only static deployment will be possible (see also for more information). The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module provides the clear-text connector and support for the clear-text HTTP/1.1 protocol, and depends on the . The module properties to configure the clear-text connector are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 13 Among the configurable properties, the most relevant are: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 83 The network port that Jetty listens to for clear-text HTTP/1.1 connections — default $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 66. 74 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 75 seconds. 76 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 for more information about acceptor threads. 77 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). 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 78 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 78 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 78. 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. Performing a NIO 81 call is a blocking operation, where the selecting thread is blocked in the 81 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 81 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. The $ java -jar $JETTY_HOME/start.jar --add-modules=http 18 module enables support for the secure HTTP/2 protocol. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 14 The 86 property controls the number of "bad" or "unnecessary" frames that a client may send before the server closes the connection (with code ) to avoid a denial of service. For example, an attacker may send empty 88 frames to a server in a tight loop. While the 88 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 88 frames). The same attack may be performed with 91 frames, empty 92 frames, 93 frames, etc. The 94 module enables support for the clear-text HTTP/2 protocol. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 15 The 86 property controls the number of "bad" or "unnecessary" frames that a client may send before the server closes the connection (with code ) to avoid a denial of service. For example, an attacker may send empty 88 frames to a server in a tight loop. While the 88 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 88 frames). The same attack may be performed with 91 frames, empty 92 frames, 93 frames, etc. The $ java -jar $JETTY_HOME/start.jar 04 module enables support for the HTTP/3 protocol. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 16 The $ java -jar $JETTY_HOME/start.jar 06 module provides support for processing the $ java -jar $JETTY_HOME/start.jar 08 HTTP header (defined in RFC 7239) and the now obsoleted $ java -jar $JETTY_HOME/start.jar 09 HTTP headers. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 17 The $ java -jar $JETTY_HOME/start.jar 22 module provides the HTTP/1.1 protocol to the . The module file is $ java -jar $JETTY_HOME/start.jar 13: $ java -jar $JETTY_HOME/start.jar --add-module=demos 18 This module enables deployment of Java Servlet web applications. The $ java -jar $JETTY_HOME/start.jar 15 module provides remote access to JMX clients. The module properties to configure remote JMX connector are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 19 The system property $ java -jar $JETTY_HOME/start.jar 17 is specified with the usual notation, prepending a $ java -jar $JETTY_HOME/start.jar 18 in front of the system property name. The system property $ java -jar $JETTY_HOME/start.jar 17 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 $ java -jar $JETTY_HOME/start.jar 20, the $ java -jar $JETTY_HOME/start.jar 21 file may contain these entries: $ java -jar $JETTY_HOME/start.jar --add-module=demos 20 If the system property $ java -jar $JETTY_HOME/start.jar 17 is not specified, the RMI implementation uses the host name $ java -jar $JETTY_HOME/start.jar 20 to figure out the IP address to store in the RMI stub, in this case $ java -jar $JETTY_HOME/start.jar 24. However, we the RMI server is configured to bind to $ java -jar $JETTY_HOME/start.jar 25, i.e. $ java -jar $JETTY_HOME/start.jar --list-modules=* 45. If the system property $ java -jar $JETTY_HOME/start.jar 17 is not specified, the RMI client will try to connect to $ java -jar $JETTY_HOME/start.jar 24 (because that’s what in the RMI stub) and fail because nothing is listening on that address. The $ java -jar $JETTY_HOME/start.jar 29 module provides HTTP request/response logging in the standard NCSA format, or in a custom format of your choice. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 21 The property $ java -jar $JETTY_HOME/start.jar 31 can be customized using format codes. Format codes are specified with the syntax $ java -jar $JETTY_HOME/start.jar 32 as follows: $ java -jar $JETTY_HOME/start.jar 33 Optional list of comma separated HTTP status codes which may be preceded by a single "!" to indicate negation. If the status code is not in the list the literal string "-" will be logged instead of the resulting value from the percent code. $ java -jar $JETTY_HOME/start.jar 34 Parameter string which may be optional depending on the percent code used. $ java -jar $JETTY_HOME/start.jar 35 A one or two character code specified by the table of format codes below. Table 1. Format Codes Format String Description X The X character. %% The percent character. %{format}a The address or host name. Valid format values are: "server", "client", "local", "remote". The format parameter is optional and defaults to "server". Values "server" and "client" are the logical addresses which can be modified in the request headers, while "local" and "remote" are the physical addresses so may be the addresses of a proxy between the end-user and the server. %{format}p The port. Valid format values are: "server", "client", "local", "remote". The format parameter is optional and defaults to "server". Values "server" and "client" are the logical ports which can be modified in the request headers, while "local" and "remote" are the physical ports so may be the ports of a proxy between the end-user and the server. %{CLF}I The size of request in bytes, excluding HTTP headers. The parameter is optional. When the parameter value is "CLF" the Common Log Format is used, i.e. a $ java -jar $JETTY_HOME/start.jar 36 rather than a $ java -jar $JETTY_HOME/start.jar 37 when no bytes are present. %{CLF}O The size of response in bytes, excluding HTTP headers. The parameter is optional. When the parameter value is "CLF" the Common Log Format is used, i.e. a $ java -jar $JETTY_HOME/start.jar 36 rather than a $ java -jar $JETTY_HOME/start.jar 37 when no bytes are present. %{CLF}S The bytes transferred (received and sent). This is the combination of $ java -jar $JETTY_HOME/start.jar 40 and $ java -jar $JETTY_HOME/start.jar 41. The parameter is optional. When the parameter value is "CLF" the Common Log Format is used, i.e. a $ java -jar $JETTY_HOME/start.jar 36 rather than a $ java -jar $JETTY_HOME/start.jar 37 when no bytes are present. %{VARNAME}C The value of the request cookie VARNAME. The parameter is optional. Only version 0 cookies are fully supported. When the parameter is missing, all request cookies will be logged. %D The time taken to serve the request, in microseconds. %{VARNAME}e The value of the environment variable VARNAME. %f The file system path of the requested resource. %H The name and version of the request protocol, such as "HTTP/1.1". %{VARNAME}i The value of the VARNAME request header. %k The number of requests handled on a connection. The initial request on a connection yields a value 0, the first request after the initial on the same connection yields the value 1, the second request on the same connection yields the value 2, etc. %m The HTTP request method. %{VARNAME}o The value of the VARNAME response header. %q The query string, prepended with a ? if a query string exists, otherwise an empty string. %r First line of an HTTP/1.1 request (or equivalent information for HTTP/2 or later). %R The name of the Handler or Servlet generating the response (if any). %s The HTTP response status code. %{format|timeZone|locale}t The time at which the request was received. The parameter is optional and may have the following values: {format}, {format|timeZone} or {format|timeZone|locale}. $ java -jar $JETTY_HOME/start.jar 44 Default is e.g. [18/Sep/2011:19:18:28 -0400] where the last number indicates the timezone offset from GMT. Must be in a format supported by the $ java -jar $JETTY_HOME/start.jar 45 package. $ java -jar $JETTY_HOME/start.jar 46 Default is GMT. Must be in a format supported by the $ java -jar $JETTY_HOME/start.jar 45 package. $ java -jar $JETTY_HOME/start.jar 48 Default is the JVM default locale. Must be in a format supported by $ java -jar $JETTY_HOME/start.jar 49. %{UNIT}T The time taken to serve the request. The parameter UNIT is optional and defaults to "s". The parameter UNIT indicates the unit of time: "s" for seconds, "ms" for milliseconds, "us" for microseconds. $ java -jar $JETTY_HOME/start.jar 50 is identical to $ java -jar $JETTY_HOME/start.jar 51. %{d}u The remote user if the request was authenticated with servlet authentication. May be an invalid value if response status code ( $ java -jar $JETTY_HOME/start.jar
The parameter is optional. When the parameter value is "d", deferred authentication will also be checked. %U The URL path requested, not including any query string. %X The connection status when response is completed: $ java -jar $JETTY_HOME/start.jar 53 The connection is aborted before the response completed. $ java -jar $JETTY_HOME/start.jar 54 The connection may be kept alive after the response is sent. $ java -jar $JETTY_HOME/start.jar 36 The connection will be closed after the response is sent. %{VARNAME}ti The value of the VARNAME request trailer. %{VARNAME}to The value of the VARNAME response trailer. This module adds the 73 directory to the server’s classpath. A common use-case for this module is to provide resources for third-party libraries via the . For instance, many logging libraries (including Log4j2 and Logback) look for their configuration files on the classpath. Jetty provides a logging library implementation — enabled via the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 65 module — whose configuration file is $ java -jar $JETTY_HOME/start.jar 81. The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties. The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 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 for clear-text HTTP/1.1 support, or the for secure HTTP/2 support, etc. See also the for more information about the supported protocols. The module properties to configure generic HTTP properties are listed below. Mostly they frequently apply to HTTP/1, HTTP/2 and HTTP/3, but some parameters are version specific: $ java -jar $JETTY_HOME/start.jar --add-module=demos 22 Among the configurable properties, the most relevant are: $ java -jar $JETTY_HOME/start.jar 65 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. $ java -jar $JETTY_HOME/start.jar 66 It is not uncommon for the network packets containing a request header to arrive before packets that contain the data of any request body. In such cases it may be beneficial for overall performance to delay dispatching the request to be handled until the first data packet arrives, as this may avoid blocking the handling thread. However, if minimum latency for receiving the request without content is important, then this parameter can be set to false. $ java -jar $JETTY_HOME/start.jar 67 Whether you want to send the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 header in every HTTP response: $ java -jar $JETTY_HOME/start.jar --add-module=demos 23 The module properties to configure the Jetty server are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 24 Among the configurable properties, the most relevant are: $ java -jar $JETTY_HOME/start.jar 69 Whether to perform a $ java -jar $JETTY_HOME/start.jar 70 operation after the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 has started. The output of the dump operation is sent to $ java -jar $JETTY_HOME/start.jar --list-modules=* 59. See also the section for more information. $ java -jar $JETTY_HOME/start.jar 73 Whether to perform a $ java -jar $JETTY_HOME/start.jar 70 operation before the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 stops. The output of the dump operation is sent to $ java -jar $JETTY_HOME/start.jar --list-modules=* 59. See also the section for more information. $ java -jar $JETTY_HOME/start.jar --list-modules=* 41 Whether to call $ java -jar $JETTY_HOME/start.jar 78 through a JVM shutdown hook when the JVM exits. The Jetty server strives to keep up with the latest IETF RFCs 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 25 Among the configurable properties, the most relevant are: $ java -jar $JETTY_HOME/start.jar 79 Configures the compliance to HTTP specifications. The value could be:
$ java -jar $JETTY_HOME/start.jar 91 Configures the compliance to URI specifications. The value could be:
$ java -jar $JETTY_HOME/start.jar --add-module=demos 005 $ java -jar $JETTY_HOME/start.jar --add-module=demos 006 Configures the compliance to HTTP cookie specifications. The value could be:
The module properties to configure the Jetty server scheduler are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 26 The $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 module provides the secure connector, and allows you to configure the KeyStore properties and the TLS parameters, and depends on the . The module properties to configure the secure connector are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 27 Among the configurable properties, the most relevant are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 020 The network port that Jetty listens to for secure connections — default $ java -jar $JETTY_HOME/start.jar --add-module=demos 021. $ java -jar $JETTY_HOME/start.jar --add-module=demos 022 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 023 milliseconds. $ java -jar $JETTY_HOME/start.jar --add-module=demos 024 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 for more information about acceptor threads. $ java -jar $JETTY_HOME/start.jar --add-module=demos 025 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 for more information about selector threads. The module properties to configure the KeyStore and TLS parameters are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 28 Among the configurable properties, the most relevant are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 026 The KeyStore path on the file system, either an absolute path or a relative path to $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 — defaults to $ java -jar $JETTY_HOME/start.jar --add-module=demos 028. $ java -jar $JETTY_HOME/start.jar --add-module=demos 029 The KeyStore password, which you want to explicitly configure. The password may be obfuscated with the . If you need to configure client certificate authentication, you want to configure one of these properties (they are mutually exclusive): $ java -jar $JETTY_HOME/start.jar --add-module=demos 030 Whether client certificate authentication should be required. $ java -jar $JETTY_HOME/start.jar --add-module=demos 031 Whether client certificate authentication should be requested. If you configure client certificate authentication, you need to configure and distribute a client KeyStore as explained in . The $ java -jar $JETTY_HOME/start.jar --add-module=demos 032 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 034 component is reloaded with the new KeyStore configuration. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 29 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 035 module creates on-the-fly a KeyStore containing a self-signed certificate for domain $ java -jar $JETTY_HOME/start.jar 25. 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 038: $ java -jar $JETTY_HOME/start.jar --add-module=demos 30 Note how properties $ java -jar $JETTY_HOME/start.jar --add-module=demos 026 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 029 are configured, only if not already set (via the $ java -jar $JETTY_HOME/start.jar --add-module=demos 041 operator), directly in the module file, rather than in a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 74 file. This is done to avoid that these properties accidentally overwrite a real KeyStore configuration. The $ java -jar $JETTY_HOME/start.jar 19 module allows you to configure the server-wide thread pool. The thread pool creates threads on demand up to $ java -jar $JETTY_HOME/start.jar --add-module=demos 045, 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 045 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 045, and tune for larger values if needed. The module properties to configure the thread pool are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 31 Among the configurable properties, the most relevant are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 048 The name prefix to use for the thread names. $ java -jar $JETTY_HOME/start.jar --add-module=demos 049 Whether the thread pool should dump the whole stack trace of each thread, or just the topmost stack frame — defaults to $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. $ java -jar $JETTY_HOME/start.jar --add-module=demos 051 The time, in milliseconds, after which an idle thread is released from the pool — defaults to 60000, i.e. 60 seconds. $ java -jar $JETTY_HOME/start.jar --list-modules=* 95 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 053 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. 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 32 The specific properties to configure virtual threads are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 060 The name prefix to use for the virtual thread names. $ java -jar $JETTY_HOME/start.jar --add-module=demos 061 Whether virtual threads inherit the values of $ java -jar $JETTY_HOME/start.jar --add-module=demos 062 variables. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 054 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. 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. To enable preview features, this module needs to specify the 18 command line option using the , 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 33 The specific properties to configure virtual threads are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 060 The name prefix to use for the virtual thread names. $ java -jar $JETTY_HOME/start.jar --add-module=demos 070 Whether virtual threads are allowed to set thread locals. $ java -jar $JETTY_HOME/start.jar --add-module=demos 061 Whether virtual threads inherit the values of $ java -jar $JETTY_HOME/start.jar --add-module=demos 062 variables. This module enables deployment of Java Servlet web applications. Multiple versions of this module exist ( $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --add-module=demos 34 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 075 Jetty module creates a $ java -jar $JETTY_HOME/start.jar --add-module=demos 077 deployed at the $ java -jar $JETTY_HOME/start.jar --add-module=demos 078 context path which serves files from a directory. By default, the directory created at $ java -jar $JETTY_HOME/start.jar --add-module=demos 079 is used, but it can be configured from $ java -jar $JETTY_HOME/start.jar --add-module=demos 080 to anywhere in the filesystem. Note that the $ java -jar $JETTY_HOME/start.jar --add-module=demos 081 directory may be seen as a hidden directory by the filesystem. The concept of well-known URIs has been defined in RFC5785. This module can be used for things like the automatic renewal of Let’s Encrypt certificates. See IANA Well-Known URIs for more possible examples of how this can be used. The module properties are: $ java -jar $JETTY_HOME/start.jar --add-module=demos 35 Most of the time you want to be able to customize the deployment of your web applications, for example by changing the $ java -jar $JETTY_HOME/start.jar 14, or by adding JNDI entries, or by configuring virtual hosts, etc. Jetty supports the deployment of each web application to a specific environment. The available environments are:
This means that you can simultaneously deploy an old Java EE 8 web application, say $ java -jar $JETTY_HOME/start.jar --add-module=demos 087, alongside a new Jakarta EE 10 web application, say $ java -jar $JETTY_HOME/start.jar --add-module=demos 088, alongside a web application that only uses the Jetty 13 APIs, say $ java -jar $JETTY_HOME/start.jar --add-module=demos 090. The customization of the deployment (for example, web application context path, etc.) is performed by processing . The $ java -jar $JETTY_HOME/start.jar --add-module=demos 091 module contains the 50 component that scans the $ java -jar $JETTY_HOME/start.jar 07 directory for changes, following the deployment rules described in . For each specific environment there is a specific deploy module that you must enable:
Each of these modules provide the environment specific features, and depend on the $ java -jar $JETTY_HOME/start.jar --add-module=demos 091 module that provides the scanning features. The 50 scans the $ java -jar $JETTY_HOME/start.jar 07 directory for changes every $ java -jar $JETTY_HOME/start.jar --add-module=demos 101 seconds, where $ java -jar $JETTY_HOME/start.jar --add-module=demos 101 is configured via the 66 property. By default, the scan interval is $ java -jar $JETTY_HOME/start.jar --add-module=demos 104 second, which means that hot deployment is enabled: if a file is added/changed/removed from the $ java -jar $JETTY_HOME/start.jar 07 directory, the 50 will notice the change and respectively deploy/redeploy/undeploy the web application. Setting the scan interval to $ java -jar $JETTY_HOME/start.jar 37 means that static deployment is enabled, and the 50 will not scan the $ java -jar $JETTY_HOME/start.jar 07 directory for changes. This means that to deploy/redeploy/undeploy a web application you will need to stop and restart Jetty. The following command line disables hot deployment by specifying the 66 property on the command line, and therefore only for this particular run: $ java -jar $JETTY_HOME/start.jar --add-module=demos 36 To make static deployment persistent, you need to edit the $ java -jar $JETTY_HOME/start.jar --add-module=demos 091 module configuration file, $ java -jar $JETTY_HOME/start.jar --add-module=demos 112, uncomment the module property 66 and change its value to $ java -jar $JETTY_HOME/start.jar 37: deploy.ini $ java -jar $JETTY_HOME/start.jar --add-module=demos 37 Adding a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file, a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 directory, a Jetty context XML file or a normal directory to $ java -jar $JETTY_HOME/start.jar 07 causes the 50 to deploy the new web application. Updating a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file or a Jetty context XML file causes the 50 to redeploy the web application, which means that the Jetty context component representing the web application is stopped, then reconfigured, and then restarted. Removing a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file, a $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 directory, a Jetty context XML file or a normal directory from $ java -jar $JETTY_HOME/start.jar 07 causes the 50 to undeploy the web application, which means that the Jetty context component representing the web application is stopped and removed from the Jetty server. When a file or directory is added to $ java -jar $JETTY_HOME/start.jar 07, the 50 derives the web application $ java -jar $JETTY_HOME/start.jar 14 from the file or directory name, with the following rules:
A web application is always deployed to a specific environment, which is either configured for the deployed application or set to the default environment. If only a single specific deployer module is enabled, for example $ java -jar $JETTY_HOME/start.jar 04, then it is the default environment and applications will be deployed to it without any additional configuration. If multiple deployer modules are enabled, then the default environment is:
For example, if 48, $ java -jar $JETTY_HOME/start.jar --add-module=demos 095 and the $ java -jar $JETTY_HOME/start.jar 04 modules are enabled, then $ java -jar $JETTY_HOME/start.jar --add-module=demos 162 is the default environment, to which applications will be deployed unless otherwise configured (see below). To configure a specific environment for an application, you add a $ java -jar $JETTY_HOME/start.jar --add-module=demos 163 file with the same name of the web application. For example, an application deployed to $ java -jar $JETTY_HOME/start.jar --add-module=demos 164 is configured with the file $ java -jar $JETTY_HOME/start.jar --add-module=demos 165, with the following content: In case of simultaneous multiple deployer environments, it is good practice to always specify the $ java -jar $JETTY_HOME/start.jar --add-module=demos 163 file for your web applications. If you do not specify the $ java -jar $JETTY_HOME/start.jar --add-module=demos 163 file for your web applications, then the deployer for the default environment will be used. For example, if you have enabled the deployer Jetty module for all Jakarta EE versions, and you deploy an EE 9 web application without the $ java -jar $JETTY_HOME/start.jar --add-module=demos 163 file, then it will be deployed by the EE 10 deployer, with unspecified results. This unspecified deployment may not work as the EE 9 web application may use APIs that have been removed in EE 10, causing an error at runtime. A Jetty context XML file is a that allows you to customize the deployment of web applications. Recall that the 50 component of the Jetty $ java -jar $JETTY_HOME/start.jar --add-module=demos 091 module to Jetty context XML files over $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 files or directories. To deploy a web application using a Jetty context XML file, simply place the file in the $ java -jar $JETTY_HOME/start.jar 07 directory. A simple Jetty context XML file, for example named $ java -jar $JETTY_HOME/start.jar --add-module=demos 173 is the following: wiki.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 38 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies the web application $ java -jar $JETTY_HOME/start.jar 14, which may be different from the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file name. 3 Specifies the file system path of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file. The Jetty content XML file may be accompanied by a $ java -jar $JETTY_HOME/start.jar --add-module=demos 163 file that specifies the to use for the deployment: Refer to for more information about specifying the environment. The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory would look like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 39 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file may be placed anywhere in the file system and does not need to be placed in the $ java -jar $JETTY_HOME/start.jar 07 directory. If you place both the Jetty context XML file and the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file in the $ java -jar $JETTY_HOME/start.jar 07 directory, remember that they must have the same file name, for example $ java -jar $JETTY_HOME/start.jar --add-module=demos 173 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 185, so that the 50 deploys the web application only once using the Jetty context XML file (and not the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file). You can use the features of to avoid to hard-code file system paths or other configurations in your Jetty context XML files, for example by using system properties: wiki.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 40 Note how the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file path is now obtained by resolving the system property $ java -jar $JETTY_HOME/start.jar --add-module=demos 189 that you can specify on the command line when you start Jetty: $ java -jar $JETTY_HOME/start.jar --add-module=demos 41 A web application may reference a JNDI entry, such as a JDBC $ java -jar $JETTY_HOME/start.jar --list-modules=* 15 from the web application $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 file. The JNDI entry must be defined in a , for example a context XML like so: mywebapp.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 42 For more information and examples on how to use JNDI in Jetty, refer to the feature section. Class $ java -jar $JETTY_HOME/start.jar --add-module=demos 192 is present in the MySQL JDBC driver file, $ java -jar $JETTY_HOME/start.jar --add-module=demos 193, which must be available on the server’s classpath . If the class is instead present within the web application, then the JNDI entry must be declared in a $ java -jar $JETTY_HOME/start.jar --add-module=demos 194 file - see the feature section for more information and examples. A virtual host is an internet domain name, registered in the Domain Name Server (DNS), for an IP address such that multiple virtual hosts will resolve to the same IP address of a single server instance. If you have multiple web applications deployed on the same Jetty server, by using virtual hosts you will be able to target a specific web application. For example, you may have a web application for your business and a web application for your hobbies , both deployed in the same Jetty server. By using virtual hosts, you will be able to have the first web application available at $ java -jar $JETTY_HOME/start.jar --add-module=demos 195, and the second web application available at $ java -jar $JETTY_HOME/start.jar --add-module=demos 196. Another typical case is when you want to use different subdomains for different web application, for example a project website is at $ java -jar $JETTY_HOME/start.jar --add-module=demos 197 and the project documentation is at $ java -jar $JETTY_HOME/start.jar --add-module=demos 198. Virtual hosts can be used with any context that is a subclass of ContextHandler. Jetty supports the following variants to be specified as virtual host names: $ java -jar $JETTY_HOME/start.jar --add-module=demos 199 A fully qualified domain name. It is important to list all variants as a site may receive traffic for both $ java -jar $JETTY_HOME/start.jar --add-module=demos 199 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 201. $ java -jar $JETTY_HOME/start.jar --add-module=demos 202 A wildcard domain name which will match only one level of arbitrary subdomains. *.foo.com will match www.foo.com and m.foo.com, but not www.other.foo.com. $ java -jar $JETTY_HOME/start.jar --add-module=demos 203 An IP address may be set as a virtual host to indicate that a web application should handle requests received on the network interface with that IP address for protocols that do not indicate a host name such as HTTP/0.9 or HTTP/1.0. $ java -jar $JETTY_HOME/start.jar --add-module=demos 204 A Jetty server $ java -jar $JETTY_HOME/start.jar --add-module=demos 205 name to indicate that a web application should handle requests received on the server $ java -jar $JETTY_HOME/start.jar --add-module=demos 205 with that name, and therefore received on a specific socket address (either an IP port for 18, or a Unix-Domain path for $ java -jar $JETTY_HOME/start.jar --add-module=demos 208). A server $ java -jar $JETTY_HOME/start.jar --add-module=demos 205 name can be set via . $ java -jar $JETTY_HOME/start.jar --add-module=demos 210 Non-ASCII and IDN domain names can be set as virtual hosts using Puny Code equivalents that may be obtained from a Punycode/IDN converters. For example if the non-ASCII domain name $ java -jar $JETTY_HOME/start.jar --add-module=demos 210 is given to a browser, then the browser will make a request that uses the domain name $ java -jar $JETTY_HOME/start.jar --add-module=demos 212, which is the name that should be added as the virtual host name. If you have a web application $ java -jar $JETTY_HOME/start.jar --add-module=demos 140 you can configure its virtual hosts in this way: $ java -jar $JETTY_HOME/start.jar --add-module=demos 43 Your web application will be available at:
You configured the $ java -jar $JETTY_HOME/start.jar 14 of your web application to $ java -jar $JETTY_HOME/start.jar --add-module=demos 131. As such, a request to $ java -jar $JETTY_HOME/start.jar --add-module=demos 220 will not match your web application because the $ java -jar $JETTY_HOME/start.jar 14 does not match. Likewise, a request to $ java -jar $JETTY_HOME/start.jar --add-module=demos 222 will not match your web application because the virtual host does not match. If you want to deploy different web applications to the same context path, typically the root context path $ java -jar $JETTY_HOME/start.jar --add-modules=http 42, you must use virtual hosts to differentiate among web applications. You have $ java -jar $JETTY_HOME/start.jar --add-module=demos 224 that you want to deploy at $ java -jar $JETTY_HOME/start.jar --add-module=demos 195 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 226 that you want to deploy at $ java -jar $JETTY_HOME/start.jar --add-module=demos 227. To achieve this, you simply use the same context path of $ java -jar $JETTY_HOME/start.jar --add-modules=http 42 for each of your webapps, while specifying different virtual hosts for each of your webapps: domain.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 44 hobby.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 45 Sometimes it is required to serve different web applications from different socket addresses (either different IP ports, or different Unix-Domain paths), and therefore from different server $ java -jar $JETTY_HOME/start.jar --add-module=demos 205s. For example, you want requests to $ java -jar $JETTY_HOME/start.jar --add-module=demos 136 to be served by one web application, but requests to $ java -jar $JETTY_HOME/start.jar --add-module=demos 231 to be served by another web application. This configuration may be useful when Jetty sits behind a load balancer. In this case, you want to , each with a different name, and then reference the connector name in the web application virtual host configuration: domain.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 46 hobby.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 47 Web application $ java -jar $JETTY_HOME/start.jar --add-module=demos 224 has a virtual host of $ java -jar $JETTY_HOME/start.jar --add-module=demos 233, where $ java -jar $JETTY_HOME/start.jar --add-module=demos 234 is the name of a Jetty connector. Likewise, web application $ java -jar $JETTY_HOME/start.jar --add-module=demos 226 has a virtual host of $ java -jar $JETTY_HOME/start.jar --add-module=demos 236, where $ java -jar $JETTY_HOME/start.jar --add-module=demos 237 is the name of another Jetty connector. See for further information about how to configure connectors. By default, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 files are uncompressed and its content extracted in a temporary directory. The web application resources are served by Jetty from the files extracted in the temporary directory, not from the files within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file, for performance reasons. If you do not want Jetty to extract the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 files, you can disable this feature, for example: mywebapp.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 48 You can configure an additional $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 that complements the $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 file that is present in the web application $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file. This additional $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 is processed after the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file $ java -jar $JETTY_HOME/start.jar --add-module=demos 191. This allows you to add host specific configuration or server specific configuration without having to extract the web application $ java -jar $JETTY_HOME/start.jar --add-module=demos 191, modify it, and repackage it in the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file. mywebapp.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 49 The format of the additional $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 is exactly the same as a standard $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 file, for example: mywebapp-web.xml $ java -jar $JETTY_HOME/start.jar --add-module=demos 50 $ java -jar $JETTY_HOME/start.jar --add-module=demos 51 In the example above, you configured the $ java -jar $JETTY_HOME/start.jar --add-module=demos 252 Servlet (defined in the web application $ java -jar $JETTY_HOME/start.jar --add-module=demos 191), adding a host specific $ java -jar $JETTY_HOME/start.jar --add-module=demos 254 with the IP address of the host. The Jetty $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 object is the central component that links protocol connectors to web applications. The $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 component is defined by the , that in turn depends on other Jetty modules that provide key functionalities, in particular: You can configure two types of logging in Jetty: server logging and request logging.
Jetty uses the SLF4J API for its logging. SLF4J is a generic abstraction layer that is supported by many different logging frameworks (or SLF4J bindings). Jetty provides a default binding via the $ java -jar $JETTY_HOME/start.jar --add-module=demos 260 Maven artifact, but you can plug in the SLF4J binding provided by other logging frameworks. Jetty’s server logging is enabled by default with the $ java -jar $JETTY_HOME/start.jar 20 Jetty module. You typically won’t have to enable the $ java -jar $JETTY_HOME/start.jar 20 module directly, since it is a transitive dependency of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module, and thus pulled in by many of the most commonly used modules. The $ java -jar $JETTY_HOME/start.jar 20 module is a and its default implementation is provided by the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 65 Jetty module, which uses the Jetty SLF4J binding. Jetty’s default SLF4J binding uses an appender ( $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --list-modules=* 59. The default $ java -jar $JETTY_HOME/start.jar --add-module=demos 268 format is: $ java -jar $JETTY_HOME/start.jar --add-module=demos 52 where $ java -jar $JETTY_HOME/start.jar --add-module=demos 269 is a timestamp with the format $ java -jar $JETTY_HOME/start.jar --add-module=demos 270. You can configure the appender via a file named $ java -jar $JETTY_HOME/start.jar --add-module=demos 271, which must be found in the server . When you enable the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 65 module — either directly or by transitive dependency, as in the following example — Jetty automatically generates a $ java -jar $JETTY_HOME/start.jar --add-module=demos 271 file in 74: $ java -jar $JETTY_HOME/start.jar --add-modules=http You can specify the following configuration options in $ java -jar $JETTY_HOME/start.jar --add-module=demos 271: $ java -jar $JETTY_HOME/start.jar --add-module=demos 276 Sets the logging level for the logger tree based at $ java -jar $JETTY_HOME/start.jar --add-module=demos 277. You can specify any of the usual SLF4J logging levels — $ java -jar $JETTY_HOME/start.jar --add-module=demos 278, $ java -jar $JETTY_HOME/start.jar --add-module=demos 279, $ java -jar $JETTY_HOME/start.jar --add-module=demos 280 (default), $ java -jar $JETTY_HOME/start.jar --add-module=demos 281 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 282 — plus two additional levels: $ java -jar $JETTY_HOME/start.jar --add-module=demos 283 (an alias for $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --add-module=demos 285 (disables logging entirely). You can also configure a default logging level for specific loggers, or arbitrary logger trees:
$ java -jar $JETTY_HOME/start.jar --add-module=demos 292 Specifies whether to hide stack traces for some arbitrary logger tree $ java -jar $JETTY_HOME/start.jar --add-module=demos 290. The exception type and message are logged normally; only stack traces are hidden. Default value is $ java -jar $JETTY_HOME/start.jar --add-module=demos 050 $ java -jar $JETTY_HOME/start.jar --add-module=demos 295 Specifies whether to condense logger names, so that for example $ java -jar $JETTY_HOME/start.jar --add-module=demos 296 becomes $ java -jar $JETTY_HOME/start.jar --add-module=demos 297. Default value is $ java -jar $JETTY_HOME/start.jar --add-module=demos 298. $ java -jar $JETTY_HOME/start.jar --add-module=demos 299 Specifies the column at which the logging $ java -jar $JETTY_HOME/start.jar --add-module=demos 300 should be printed. The value $ java -jar $JETTY_HOME/start.jar 37 specifies no alignment. Default value is $ java -jar $JETTY_HOME/start.jar 37. $ java -jar $JETTY_HOME/start.jar --add-module=demos 303 Specifies whether to escape ISO control characters such as $ java -jar $JETTY_HOME/start.jar --add-module=demos 304 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 305 present in the message. Character $ java -jar $JETTY_HOME/start.jar --add-module=demos 304 is replaced with $ java -jar $JETTY_HOME/start.jar --add-module=demos 307 and character $ java -jar $JETTY_HOME/start.jar --add-module=demos 305 is replaced with $ java -jar $JETTY_HOME/start.jar --add-modules=http 47; all other ISO control characters are replaced with $ java -jar $JETTY_HOME/start.jar --add-module=demos 310. Default value is $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. $ java -jar $JETTY_HOME/start.jar --add-module=demos 312 Specifies the timezone ID (such as $ java -jar $JETTY_HOME/start.jar --add-module=demos 313, or $ java -jar $JETTY_HOME/start.jar --add-module=demos 314 or $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --add-module=demos 269 part of the logging line. The empty string specifies the $ java -jar $JETTY_HOME/start.jar --add-module=demos 317 timezone. Default value is the local timezone. When using the Jetty SLF4J binding, the logging levels can be dynamically changed via JMX, see for more information. Logging to $ java -jar $JETTY_HOME/start.jar --list-modules=* 59 may be fine at development time, but you will typically want to capture logs on disk for later inspection, or if you don’t have a terminal access (for example, if you started Jetty as a service). The 43 Jetty module allows you to capture what is written to 45 and $ java -jar $JETTY_HOME/start.jar --list-modules=* 59 and write it to a log file. By default, 43 logs to a file in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 323 directory. The 43 Jetty module should be used only in conjunction with the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 65 module, as other SLF4J bindings such as LogBack or Log4j2 have their own, more sophisticated, rolling file appenders. You can use a different SLF4J binding if you are more familiar with other logging libraries, or if you need custom logging appenders. There are a number of out-of-the-box Jetty modules that you can use:
To enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 326 module, run: $ java -jar $JETTY_HOME/start.jar --add-module=demos 55 Since LogBack is released under a license that is different from Jetty’s, you will be prompted to accept the LogBack license. Once you accept the LogBack license, your $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory will have the following structure. $ java -jar $JETTY_HOME/start.jar --add-module=demos 56 Jetty downloaded the required LogBack $ java -jar $JETTY_HOME/start.jar 02 files, and created a $ java -jar $JETTY_HOME/start.jar --add-module=demos 335 file for configuring your LogBack logging. Please refer to the LogBack configuration manual for more information about how to configure LogBack. To enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 327 module, run: $ java -jar $JETTY_HOME/start.jar --add-module=demos 57 After accepting the Log4j2 license, you will have the following directory structure: $ java -jar $JETTY_HOME/start.jar --add-module=demos 58 Jetty downloaded the required Log4j2 $ java -jar $JETTY_HOME/start.jar 02 files, and created a $ java -jar $JETTY_HOME/start.jar --add-module=demos 338 file that you can configure to customize your Log4j2 logging. When you use libraries that provide the features you need (for example, JDBC drivers), it may be possible that those libraries use a different logging framework than SLF4J. SLF4J provides bridges for legacy logging APIs that allows you to bridge logging from one of these legacy logging frameworks to SLF4J. Once the logging is bridged to SLF4J, you can use Jetty’s or a so that your logging is centralized in one place. Jetty provides the $ java -jar $JETTY_HOME/start.jar --add-module=demos 339 module for bridging from $ java -jar $JETTY_HOME/start.jar --add-module=demos 330 to SLF4J. The modules $ java -jar $JETTY_HOME/start.jar --add-module=demos 341 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 342 similarly provide bridges from Jakarta Commons Logging (JCL) and Apache Log4j, respectively; however, these modules are obsolete and should not be used anymore. For libraries that use $ java -jar $JETTY_HOME/start.jar --add-module=demos 330 as their logging framework, you can enable Jetty’s $ java -jar $JETTY_HOME/start.jar --add-module=demos 339 module: $ java -jar $JETTY_HOME/start.jar --add-module=demos 59 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 339 module implies 35 and therefore because it needs to provide the system property $ java -jar $JETTY_HOME/start.jar --add-module=demos 348 (so that $ java -jar $JETTY_HOME/start.jar --add-module=demos 330 can read the configuration from the specified file), and because it needs to make available on the System ClassLoader the class $ java -jar $JETTY_HOME/start.jar --add-module=demos 350. For example, a library that uses $ java -jar $JETTY_HOME/start.jar --add-module=demos 330 as its logging library is the Postgresql JDBC driver. With the $ java -jar $JETTY_HOME/start.jar --add-module=demos 339 Jetty module, the logging follows this diagram: Note how Jetty logs directly to SLF4J, while the Postgresql JDBC driver logs to SLF4J through the $ java -jar $JETTY_HOME/start.jar --add-module=demos 353. They both arrive to the SLF4J binding, in this case the Jetty SLF4J binding (but could be any other SLF4J binding such as LogBack). HTTP requests and responses can be logged to provide data that can be later analyzed with other tools, that can provide information such as the most frequently accessed request URIs, the response status codes, the request/response content lengths, geographical information about the clients, etc. Request logging is enabled by enabling the $ java -jar $JETTY_HOME/start.jar 29 Jetty module. In the example below, both the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 Jetty module and the $ java -jar $JETTY_HOME/start.jar 29 module are enabled, so that you can make HTTP requests to the server and have them logged: $ java -jar $JETTY_HOME/start.jar --add-module=demos 60 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 61 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 358 file is the Jetty module configuration file that allows you to configure the $ java -jar $JETTY_HOME/start.jar 29 module, see for more details. By default the $ java -jar $JETTY_HOME/start.jar 29 Jetty module produces the $ java -jar $JETTY_HOME/start.jar --add-module=demos 361, where the pattern $ java -jar $JETTY_HOME/start.jar --add-module=demos 362 is replaced with the current date, for example $ java -jar $JETTY_HOME/start.jar --add-module=demos 363. The format of the request log lines is the result of a format string that uses formatting symbols to log relevant request/response data. The default format is the NCSA Format extended with referrer data and user-agent data. A typical log line looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 62 The line above (that uses fake values) shows $ java -jar $JETTY_HOME/start.jar --add-module=demos 364 for the client IP address, a hard-coded $ java -jar $JETTY_HOME/start.jar 36 for the identity, $ java -jar $JETTY_HOME/start.jar 36 for the authenticated user name, $ java -jar $JETTY_HOME/start.jar --add-module=demos 367 for the date and time with timezone, $ java -jar $JETTY_HOME/start.jar --add-module=demos 368 for the HTTP request line, $ java -jar $JETTY_HOME/start.jar --add-module=demos 369 for the HTTP response status code, $ java -jar $JETTY_HOME/start.jar --add-module=demos 370 for the HTTP response content length, $ java -jar $JETTY_HOME/start.jar --add-module=demos 371 for the referrer and $ java -jar $JETTY_HOME/start.jar --add-module=demos 372 for the user-agent. The format string can be customized as described in . Request log files are rolled every day, and retained for customizable number of days, by default 90 days. When Jetty is behind a load balancer, you want to log the remote client IP address, not the load balancer IP address. Refer to to configure the load balancer and Jetty to retain the remote client IP address information. Jetty uses thread pooling to efficiently execute tasks that provide Jetty functionalities. Like any other component, the Jetty thread pool is configured and enabled via the , that is transitively enabled by the which, in turn, is transitively enabled by a protocol module such as the : $ java -jar $JETTY_HOME/start.jar --add-modules=http The command above gives you the default configuration for the thread pool. If you want to explicitly configure the thread pool, it is enough to explicitly specify the module: $ java -jar $JETTY_HOME/start.jar --add-module=demos 64 After the command above, the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 65 Now you can customize the $ java -jar $JETTY_HOME/start.jar --add-module=demos 378 file to explicitly configure the thread pool. Virtual threads have been introduced as a preview feature in Java 19 and Java 20, and have become an official feature since Java 21. The Jetty module provides support for virtual threads in Java 19 and Java 20, and it is mutually exclusive with the $ java -jar $JETTY_HOME/start.jar 19 Jetty module. The Jetty module provides support for virtual threads in Java 21 or later, and it is mutually exclusive with the $ java -jar $JETTY_HOME/start.jar 19 Jetty module. If you have already enabled the $ java -jar $JETTY_HOME/start.jar 19 Jetty module, it is sufficient to remove it by removing the $ java -jar $JETTY_HOME/start.jar --add-module=demos 384 file. When using Java 21 or later, you can enable the module: $ java -jar $JETTY_HOME/start.jar --add-module=demos 66 After the command above, the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 67 Now you can customize the $ java -jar $JETTY_HOME/start.jar --add-module=demos 387 file to explicitly configure the thread pool and the virtual threads and then start Jetty: $ java -jar $JETTY_HOME/start.jar --add-module=demos 68 Connectors are the network components through which Jetty accepts incoming network connections. Each connector listens on a network port and can be configured with $ java -jar $JETTY_HOME/start.jar --add-module=demos 388 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 389 object) that are then processed by applications. Conversely, an abstract object (for example an $ java -jar $JETTY_HOME/start.jar --add-module=demos
Like other Jetty components, connectors are enabled and configured by enabling and configuring the correspondent Jetty module. Recall that you must always issue the commands to enable Jetty modules from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory, and that the Jetty module configuration files are in the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 38 directory. You can obtain the list of connector-related modules in this way: $ java -jar $JETTY_HOME/start.jar --add-module=demos 69 Clear text HTTP/1.1 is enabled with the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 Jetty module with the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-modules=http $ java -jar $JETTY_HOME/start.jar --add-module=demos 71 After having enabled the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 module, the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 72 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 81 file is the file that you want to edit to configure network and protocol parameters — for more details see . Note that the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 Jetty module depends on the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 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 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 module configuration file. You can force the creation of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 401 file via: $ java -jar $JETTY_HOME/start.jar --add-module=demos 73 Now the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 74 Now you can edit the $ java -jar $JETTY_HOME/start.jar --add-module=demos 401 file — for more details see . Secure HTTP/1.1 is enabled with both the $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 and $ java -jar $JETTY_HOME/start.jar 22 Jetty modules with the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-module=demos 75 $ java -jar $JETTY_HOME/start.jar --add-module=demos 76 The command above enables the $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 module, that provides the secure network connector, the KeyStore configuration and TLS configuration — for more details see . Then, the adds HTTP/1.1 as the protocol secured by TLS. The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory looks like this: $ java -jar $JETTY_HOME/start.jar --add-module=demos 77 Note that the KeyStore file is missing, because you have to provide one with the cryptographic material you want (read to create your own KeyStore). You need to configure these two properties by editing $ java -jar $JETTY_HOME/start.jar --add-module=demos 410:
As a quick example, you can enable the , that creates on-the-fly a KeyStore containing a self-signed certificate: $ java -jar $JETTY_HOME/start.jar --add-module=demos 78 $ java -jar $JETTY_HOME/start.jar --add-module=demos 79 The $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory is now: $ java -jar $JETTY_HOME/start.jar --add-module=demos 80 Starting Jetty yields: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar --add-module=demos 82 Note how Jetty is listening on port $ java -jar $JETTY_HOME/start.jar --add-module=demos 021 for the secure HTTP/1.1 protocol. If you point your browser at $ java -jar $JETTY_HOME/start.jar --add-module=demos 416 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 417 is self-signed — and as such not signed by a recognized certificate authority — and therefore browsers do not trust it. 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. Browsers only support secure HTTP/2. The protocol negotiation is performed by the 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: Nowadays, it’s common that both clients and servers support HTTP/2, so servers prefer HTTP/2 as the protocol to speak: 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. You want to configure secure HTTP/2 when Jetty is exposed directly to browsers, because browsers only support secure HTTP/2. You may configure clear-text HTTP/2 (mostly for performance reasons) if you offload TLS at a load balancer (for example, HAProxy) or at a reverse proxy (for example, nginx). 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). 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:
Use the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-module=demos 83 As when enabling the $ java -jar $JETTY_HOME/start.jar 22 Jetty module, you need a valid KeyStore (read to create your own KeyStore). As a quick example, you can enable the , that creates on-the-fly a KeyStore containing a self-signed certificate: $ java -jar $JETTY_HOME/start.jar --add-module=demos 78 Starting Jetty yields: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar --add-module=demos 86 Note how Jetty is listening on port $ java -jar $JETTY_HOME/start.jar --add-module=demos 021 and the protocols supported are the sequence $ java -jar $JETTY_HOME/start.jar --add-module=demos 425. The (ordered) list of protocols after 32 are the application protocols, in the example above $ java -jar $JETTY_HOME/start.jar --add-module=demos 427. 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) $ java -jar $JETTY_HOME/start.jar --add-module=demos 428 and then $ java -jar $JETTY_HOME/start.jar --add-module=demos 429. You can customize the list of application protocols and the default protocol to use in case the ALPN negotiation fails by editing the properties. The HTTP/2 protocol parameters can be configured by editing the properties. 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 from HTTP/1.1 to HTTP/2. You need to enable:
$ java -jar $JETTY_HOME/start.jar --add-module=demos 87 Starting Jetty yields: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar --add-module=demos 89 Note how Jetty is listening on port $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 66 and the protocols supported are HTTP/1.1 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 435 (i.e. clear-text HTTP/2). With this configuration, browsers and client applications will be able to connect to port $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 66 using:
$ java -jar $JETTY_HOME/start.jar --add-module=demos 90
$ java -jar $JETTY_HOME/start.jar --add-module=demos 91
$ java -jar $JETTY_HOME/start.jar --add-module=demos 92 The HTTP/2 protocol parameters can be configured by editing the properties. 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:
Use the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-module=demos 93 Enabling any module Jetty module that supports secure network communication requires a valid KeyStore (read to create your own KeyStore), that, as a quick example, you can enable with the , that creates on-the-fly a KeyStore containing a self-signed certificate: $ java -jar $JETTY_HOME/start.jar --add-module=demos 78 Starting Jetty yields: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar --add-module=demos 96 Note how Jetty is listening on port $ java -jar $JETTY_HOME/start.jar --add-module=demos 021 for HTTP/2 and on port $ java -jar $JETTY_HOME/start.jar --add-module=demos 446 for HTTP/3. The HTTP/3 protocol parameters can be configured by editing the properties. WebSocket is a network protocol for bidirectional data communication initiated via the . WebSocket provides a simple, low-level, framing protocol layered over TCP. One or more WebSocket 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. RFC-6455 - The WebSocket Protocol Jetty supports version 13 of the released and final specification. JSR-356 - The Java WebSocket API ( $ java -jar $JETTY_HOME/start.jar --add-module=demos 448) This is the official Java API for working with WebSockets. 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. 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. Jetty provides two WebSocket implementations: one based on the Java WebSocket APIs defined by JSR 356, provided by module $ java -jar $JETTY_HOME/start.jar --add-module=demos 449, and one based on Jetty specific WebSocket APIs, provided by module $ java -jar $JETTY_HOME/start.jar --add-module=demos 450. The Jetty $ java -jar $JETTY_HOME/start.jar --add-module=demos 451 module enables both implementations, but each implementation can be enabled independently. 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, use the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-module=demos 97 To enable secure WebSocket from HTTP/2, use the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-module=demos 98 When enabling secure protocols you need a valid KeyStore (read to create your own KeyStore). As a quick example, you can enable the , that creates on-the-fly a KeyStore containing a self-signed certificate: $ java -jar $JETTY_HOME/start.jar --add-module=demos 78 To enable WebSocket on both HTTP/1.1 and HTTP/2, both clear-text and secure, use the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar 00 Enabling the WebSocket Jetty modules comes with a startup cost because Jetty must perform two steps:
WebSocket support is by default enabled for all web applications. For a specific web application, you can disable step 2 for Java WebSocket support (i.e. when the $ java -jar $JETTY_HOME/start.jar --add-module=demos 449 module is enabled) by setting the context attribute $ java -jar $JETTY_HOME/start.jar --add-module=demos 458 to $ java -jar $JETTY_HOME/start.jar --add-module=demos 050: $ java -jar $JETTY_HOME/start.jar 01 Furthermore, for a specific web application, you can disable step 1 (and therefore also step 2) as described in the . Web applications may need to use a WebSocket client to communicate with third party WebSocket services. If the web application uses the Java WebSocket APIs, the WebSocket client APIs are provided by the Servlet Container and are available to the web application by enabling the WebSocket server APIs, and therefore you must enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 449 Jetty module. However, the Java 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, web applications should include the required jars and their dependencies in the $ java -jar $JETTY_HOME/start.jar 01 directory of the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file. Alternatively, when deploying your web applications in Jetty, you can enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 463 Jetty module to allow web applications to use the Jetty WebSocket Client APIs provided by Jetty, without the need to include jars and their dependencies in the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 37 file. 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 PHP, but also Python, Ruby, Perl and others. Web servers that supports FastCGI are, among others, Apache, 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 PHP FastCGI Process Manager, or $ java -jar $JETTY_HOME/start.jar --add-module=demos 465. In the following we will assume that $ java -jar $JETTY_HOME/start.jar --add-module=demos 465 is used as FastCGI server. This is a diagram of what described above: 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 Java Web Standards such as Servlets, JSPs, etc. With such configuration, users can not only deploy their Java Web Applications in Jetty, but also serve their WordPress site or blog or their Drupal site without having to install and manage multiple web servers. This section explains how to configure Jetty to serve your WordPress site. The prerequisites are:
Then, the and/or the Jetty modules should be enabled to allow browsers to connect to Jetty. Lastly, enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 471 module to provide FastCGI support (to convert HTTP requests from browsers to FastCGI for $ java -jar $JETTY_HOME/start.jar --add-module=demos 465 and vice versa), and the 48 module to deploy your WordPress web application as a . For example: $ java -jar $JETTY_HOME/start.jar 02 The $ java -jar $JETTY_HOME/start.jar 22 Jetty module requires a KeyStore. If you do not already have one configured, you can add the $ java -jar $JETTY_HOME/start.jar --add-module=demos 035 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 476 and customize it as necessary: $ java -jar $JETTY_HOME/start.jar 03 1 Specify the WordPress installation path. 2 Specify the context path of your web application. 3 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 477 forwards requests whose URI path matches $ java -jar $JETTY_HOME/start.jar --add-module=demos 478 to $ java -jar $JETTY_HOME/start.jar --add-module=demos 465. 4 The client URI regex pattern to match. 5 The URI used to forward the request to $ java -jar $JETTY_HOME/start.jar --add-module=demos 465, where $ java -jar $JETTY_HOME/start.jar --add-module=demos 481 is the 3rd matching group of the client URI regex pattern (int this example, the client URI path). If $ java -jar $JETTY_HOME/start.jar --add-module=demos 465 is configured to listen on a TCP socket, the host and port must match the listening TCP socket. If $ java -jar $JETTY_HOME/start.jar --add-module=demos 465 is configured to listen on a Unix-Domain socket, the host and port values are ignored but must be present. 6 If $ java -jar $JETTY_HOME/start.jar --add-module=demos 465 is configured to listen on a Unix-Domain socket, specify the Unix-Domain socket path, otherwise omit this line. 7 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 077 serves static files from WordPress, such as $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 94, $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 95 and image files. Now you can start Jetty and navigate to $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 41 with your browser to enjoy WordPress: $ java -jar $JETTY_HOME/start.jar Secure protocols are normal protocols such as HTTP/1.1, HTTP/2 or WebSocket that are wrapped by the 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 $ java -jar $JETTY_HOME/start.jar 22 scheme used in URIs really means $ java -jar $JETTY_HOME/start.jar --add-module=demos 490 (or $ java -jar $JETTY_HOME/start.jar --add-module=demos 491, or $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --add-module=demos 493 scheme used in URIs really means $ java -jar $JETTY_HOME/start.jar --add-module=demos 494, 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 allows you to configure a secure network connector; if other modules require encryption, they declare a dependency on the $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 module. It is the job of other Jetty modules to configure the wrapped protocol. For example, it is the that configures the wrapped protocol to be HTTP/1.1. Similarly, it is the that configures the wrapped protocol to be HTTP/2. If you enable both the $ java -jar $JETTY_HOME/start.jar 22 and the $ java -jar $JETTY_HOME/start.jar --add-modules=http 18 module, you will have a single secure connector that will be able to interpret both HTTP/1.1 and HTTP/2. Recall from the , that only modules that are explicitly enabled get their module configuration file ( $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE
$ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 38, and you want $ java -jar $JETTY_HOME/start.jar --add-module=demos 503 to be present so that you can configure the connector properties, the KeyStore properties and the TLS properties. Secure protocols have a slightly more complicated configuration since they require to configure a KeyStore. Refer to the 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 . For more advanced configuration you may want to configure the TLS protocol versions, or the ciphers to include/exclude, etc. The correct way of doing this is to create a custom and reference it in $ java -jar $JETTY_HOME/start.jar --add-module=demos 503: ssl.ini $ java -jar $JETTY_HOME/start.jar 05 1 Configures the $ java -jar $JETTY_HOME/start.jar --add-module=demos 029 property with the KeyStore password. 2 References your newly created $ java -jar $JETTY_HOME/start.jar --add-module=demos 506. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 410 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 506 with the following template content: tls-config.xml $ java -jar $JETTY_HOME/start.jar 06 1 Here goes your advanced configuration. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 509 file references the $ java -jar $JETTY_HOME/start.jar --add-module=demos 510 component (created by the $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 Jetty module) that configures the KeyStore and TLS parameters, so that you can now call its APIs via XML, and you will have full flexibility for any advanced configuration you want (see below for few examples). Use module properties whenever possible, and only resort to use a Jetty XML file for advanced configuration that you cannot do using module properties. 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 $ java -jar $JETTY_HOME/start.jar 07 You can precisely set the list of excluded ciphers, completely overriding Jetty’s default, with this XML: tls-config.xml $ java -jar $JETTY_HOME/start.jar 08 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 503, or put all your custom configurations in a single XML file. 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:
To renew a certificate, you must go through the you followed to create the certificate the first time, and then you can without the need to stop Jetty. Jetty can be configured to monitor the directory of the KeyStore file, and reload the $ java -jar $JETTY_HOME/start.jar --add-modules=http 87 component if the KeyStore file changed. This feature can be enabled by activating the $ java -jar $JETTY_HOME/start.jar --add-module=demos 032 Jetty module: $ java -jar $JETTY_HOME/start.jar 09 For more information about the configuration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 032 Jetty module, see . 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 Conscrypt, which is built on BoringSSL, which is Google’s fork of OpenSSL. 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 516 Jetty module: $ java -jar $JETTY_HOME/start.jar 10 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 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 $ java -jar $JETTY_HOME/start.jar --add-modules=http 42, one at virtual host $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 and one at virtual host $ java -jar $JETTY_HOME/start.jar --add-module=demos 519. The KeyStore contains two certificates, one for $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 and one for $ java -jar $JETTY_HOME/start.jar --add-module=demos 519. There are three $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 523 Whether SNI is required at the TLS level, defaults to $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Its behavior is explained by the following table: Table 2. Behavior of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 523 property $ java -jar $JETTY_HOME/start.jar --add-module=demos 526 $ java -jar $JETTY_HOME/start.jar --add-module=demos 527 SNI = $ java -jar $JETTY_HOME/start.jar --add-module=demos 528 client receives default certificate client receives TLS failure SNI = $ java -jar $JETTY_HOME/start.jar --add-module=demos 529 client receives default certificate client receives TLS failure SNI = $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 client receives $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 certificate client receives $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 certificate 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 certificate or the $ java -jar $JETTY_HOME/start.jar --add-module=demos 519 certificate. When $ java -jar $JETTY_HOME/start.jar --add-module=demos 535, 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 536 Whether SNI is required at the HTTP level, defaults to $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Its behavior is similar to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 523 property above, and is explained by the following table: Table 3. Behavior of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 536 property $ java -jar $JETTY_HOME/start.jar --add-module=demos 526 $ java -jar $JETTY_HOME/start.jar --add-module=demos 527 SNI = $ java -jar $JETTY_HOME/start.jar --add-module=demos 528 Accept Reject: 400 Bad Request SNI = $ java -jar $JETTY_HOME/start.jar --add-module=demos 529 Accept Reject: 400 Bad Request SNI = $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 Accept Accept When $ java -jar $JETTY_HOME/start.jar --add-module=demos 545, 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: $ java -jar $JETTY_HOME/start.jar --add-module=demos 546 Whether the certificate sent to the client matches the $ java -jar $JETTY_HOME/start.jar --add-module=demos 547 header, defaults to $ java -jar $JETTY_HOME/start.jar --add-module=demos 298. Its behavior is explained by the following table: Table 4. Behavior of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 546 property $ java -jar $JETTY_HOME/start.jar --add-module=demos 550 $ java -jar $JETTY_HOME/start.jar --add-module=demos 551 certificate = $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 $ java -jar $JETTY_HOME/start.jar --add-module=demos 553 Accept Reject: 400 Bad Request certificate = $ java -jar $JETTY_HOME/start.jar --add-module=demos 518 $ java -jar $JETTY_HOME/start.jar --add-module=demos 555 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 547 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. You may need to configure one or more Jetty instances behind an intermediary, typically a load balancer such as HAProxy, or a reverse proxy such as Apache HTTP Server or Nginx. 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:
In both methods, web applications that call $ java -jar $JETTY_HOME/start.jar --add-module=demos 559 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, $ java -jar $JETTY_HOME/start.jar --add-module=demos 560 will return the remote client IP port as specified by the client information sent by the intermediary, and $ java -jar $JETTY_HOME/start.jar --add-module=demos 561 will return whether the client made a secure request using the $ java -jar $JETTY_HOME/start.jar 22 scheme as specified by the client information sent by the intermediary. The $ java -jar $JETTY_HOME/start.jar 08 HTTP header is added by the intermediary with information about the client and the client request, for example: $ java -jar $JETTY_HOME/start.jar 11 In the example above, the intermediary added the $ java -jar $JETTY_HOME/start.jar 08 header specifying that the client remote address is $ java -jar $JETTY_HOME/start.jar --add-module=demos 565 and that the request was made with the $ java -jar $JETTY_HOME/start.jar 22 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=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-modules=http Support for the $ java -jar $JETTY_HOME/start.jar 08 HTTP header (and its predecessor $ java -jar $JETTY_HOME/start.jar 09 headers) is enabled with the $ java -jar $JETTY_HOME/start.jar 06 Jetty module: $ java -jar $JETTY_HOME/start.jar 13 $ java -jar $JETTY_HOME/start.jar 14 With the $ java -jar $JETTY_HOME/start.jar 06 Jetty module enabled, Jetty interprets the $ java -jar $JETTY_HOME/start.jar 08 header and makes its information available to web applications via the standard Servlet APIs. For further information about configuring the $ java -jar $JETTY_HOME/start.jar 06 Jetty module, see . The Proxy Protocol is the de facto standard, introduced by 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. 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 574 where $ java -jar $JETTY_HOME/start.jar --add-module=demos 575 is a single byte that indicates the value’s meaning, and $ java -jar $JETTY_HOME/start.jar --add-module=demos 576 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=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar --add-modules=http To enable proxy protocol support for the clear-text connector, enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 578 Jetty module: $ java -jar $JETTY_HOME/start.jar 16 $ java -jar $JETTY_HOME/start.jar 17 Starting Jetty yields: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar 19 Note how in the example above the list of protocols for the clear-text connector is first $ java -jar $JETTY_HOME/start.jar --add-module=demos 579 and then $ java -jar $JETTY_HOME/start.jar --add-module=demos 429. 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=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar 20 Enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 582 Jetty module with the following command (issued from within the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory): $ java -jar $JETTY_HOME/start.jar 21 $ java -jar $JETTY_HOME/start.jar 22 Starting Jetty yields: $ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar 24 Note how in the example above the list of protocols for the secure connector is first $ java -jar $JETTY_HOME/start.jar --add-module=demos 579, then $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 and then $ java -jar $JETTY_HOME/start.jar --add-module=demos 429. 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 PEM format, with the following order:
Refer to the for more information about generating the required certificates and private key. Now you can create the HAProxy configuration file (in Linux it’s typically $ java -jar $JETTY_HOME/start.jar --add-module=demos 587). This is a minimal configuration: haproxy.cfg $ java -jar $JETTY_HOME/start.jar 25 1 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 588 front-end accepts connections on port 80 and redirects them to use the $ java -jar $JETTY_HOME/start.jar 22 scheme. 2 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 590 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 591 part), the ciphers that are suitable for HTTP/2 ( $ java -jar $JETTY_HOME/start.jar --add-module=demos 592), and the ALPN protocols supported ( $ java -jar $JETTY_HOME/start.jar --add-module=demos 593). This front-end then forwards the now decrypted bytes to the backend in $ java -jar $JETTY_HOME/start.jar --add-module=demos 594. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 594 says that HAProxy will not try to interpret the bytes but instead opaquely forwards them to the backend. 3 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 596 backend will forward (again in $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --add-module=demos 598 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 26 You need to specify the host ( $ java -jar $JETTY_HOME/start.jar --list-modules=*
$ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar 27 You want the Jetty connector that listens on port $ java -jar $JETTY_HOME/start.jar --add-module=demos 600 to be available only to HAProxy, and not to remote clients. For this reason, you want to specify the $ java -jar $JETTY_HOME/start.jar --add-module=demos 602 property on the command line (or in $ java -jar $JETTY_HOME/start.jar 95 to make this setting persistent) to bind the Jetty connector only on the loopback interface ( $ java -jar $JETTY_HOME/start.jar --list-modules=* 45), 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 602 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 94 and the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 61 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. 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 PKCS12, and are typically protected by a password. Refer to the for more information about how to configure a secure connector using a KeyStore. KeyStores are created with the JDK tool $ java -jar $JETTY_HOME/start.jar --add-module=demos 608. The following command creates a KeyStore file containing a private key and a self-signed certificate: $ java -jar $JETTY_HOME/start.jar 28 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. 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 609 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 610, you want to specify $ java -jar $JETTY_HOME/start.jar --add-module=demos 611 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, $ java -jar $JETTY_HOME/start.jar --add-module=demos 612 specifies $ java -jar $JETTY_HOME/start.jar --add-module=demos 613 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 610 as alternative names for your web applications (that you can configure using ). In rare cases, you may want to specify IP addresses, rather than domains, in the SAN extension. The syntax in such case is $ java -jar $JETTY_HOME/start.jar --add-module=demos 615, which specifies as subject alternative names IPv4 $ java -jar $JETTY_HOME/start.jar --list-modules=* 45 and IPv6 $ java -jar $JETTY_HOME/start.jar --add-module=demos 617. 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 ). You can create multiple key/certificate pairs as detailed in the , provided that you assign each one to a different alias. Compliant TLS clients will send the 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. 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): $ java -jar $JETTY_HOME/start.jar 29 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. 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: $ java -jar $JETTY_HOME/start.jar 30 1 the command to import certificates 2 use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 618 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: $ java -jar $JETTY_HOME/start.jar 31 Now you have a trusted certificate in your KeyStore that you can use for the domains of your web applications. Refer to the section about configuring to configure the secure connector with your newly created KeyStore. 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: $ java -jar $JETTY_HOME/start.jar 32 1 use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 619 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) The important difference with the is the basic constraints extension ( $ java -jar $JETTY_HOME/start.jar --add-module=demos
$ java -jar $JETTY_HOME/start.jar --add-module=demos 621). Now you want to export both the private key and server authentication certificate. Unfortunately, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 622 program cannot export private keys, so you need to use a different command line program like $ java -jar $JETTY_HOME/start.jar --add-module=demos 623, or a graphical program like KeyStore Explorer. Let’s use $ java -jar $JETTY_HOME/start.jar --add-module=demos 623 to export the server authentication private key: $ java -jar $JETTY_HOME/start.jar 33 Now let’s export the server authentication certificate: $ java -jar $JETTY_HOME/start.jar 34 At this point, you want to create a client KeyStore, so that you can sign the client certificate with the server authentication cryptographic material: $ java -jar $JETTY_HOME/start.jar 35 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): $ java -jar $JETTY_HOME/start.jar 36 Now you need to sign the CSR, but again the $ java -jar $JETTY_HOME/start.jar --add-module=demos 622 program does not have this functionality, and you must resort again to use $ java -jar $JETTY_HOME/start.jar --add-module=demos 623: $ java -jar $JETTY_HOME/start.jar 37 Now you need to import the server authentication certificate and the signed client certificate into the client KeyStore. First, the server authentication certificate: $ java -jar $JETTY_HOME/start.jar 38 Then, the signed client certificate: $ java -jar $JETTY_HOME/start.jar 39 Now you can distribute $ java -jar $JETTY_HOME/start.jar --add-module=demos 627 to your client(s). Refer to the section about configuring to configure the secure connector to require client authentication. HTTP sessions are a concept within the Servlet API which allow requests to store and retrieve information across the time a user spends in an application. Jetty offers a number of pluggable alternatives for managing and distributing/persisting sessions. Choosing the best alternative is an important consideration for every application as is the correct configuration to achieve optimum performance. Before diving into the specifics of how to plug-in and configure various alternative HTTP session management modules, let’s review some useful terminology: Session is a means of retaining information across requests for a particular user. The Servlet Specification defines the semantics of sessions. Some of the most important characteristics of sessions is that they have a unique id and that their contents cannot be shared between different contexts (although the id can be): if a session is invalidated in one context, then all other sessions that share the same id in other contexts will also be invalidated. Sessions can expire or they can be explicitly invalidated. SessionIdManager is responsible for allocating session ids. A Jetty server can have at most 1 SessionIdManager. HouseKeeper is responsible for periodically orchestrating the removal of expired sessions. This process is referred to as . SessionHandler is responsible for managing the lifecycle of sessions. A context can have at most 1 $ java -jar $JETTY_HOME/start.jar --add-module=demos 628. SessionCache is a L1 cache of in-use session objects. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 629 is used by the $ java -jar $JETTY_HOME/start.jar --add-module=demos 628. SessionDataStore is responsible for all clustering/persistence operations on sessions. A $ java -jar $JETTY_HOME/start.jar --add-module=demos 629 uses a $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 as a backing store. CachingSessionDataStore is an L2 cache of session data. A $ java -jar $JETTY_HOME/start.jar --add-module=demos 629 can use a $ java -jar $JETTY_HOME/start.jar --add-module=demos 634 as its backing store. More details on these concepts can be found in the . $ java -jar $JETTY_HOME/start.jar --add-module=demos 632s implementations interact with other, usually third party, systems responsible for storing and/or distributing session information. Sessions can be distributed without being persisted. They can also be persisted without being distributed. Because persisting session information to a shared store is a very common way of distributing (also known as "clustering") sessions, in the documentation we will often refer to just "persisting". The $ java -jar $JETTY_HOME/start.jar --add-module=demos 636 module is the base module that all other session modules depend upon. As such it will be transitively enabled if you enable any of the other session modules: you need to explicitly enable it if you wish to change any settings from their defaults. Enabling the $ java -jar $JETTY_HOME/start.jar --add-module=demos 636 module puts the $ java -jar $JETTY_HOME/start.jar --add-module=demos 638 file onto the execution path and generates a $ java -jar $JETTY_HOME/start.jar --add-module=demos 639 file. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 640 file instantiates a $ java -jar $JETTY_HOME/start.jar --add-module=demos 641 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 642. The former is used to generate and manage session ids whilst the latter is responsible for periodic of expired sessions. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 639 file contains these configuration properties: jetty.sessionIdManager.workerName This uniquely identifies the jetty server instance and is applied to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 644. You can either provide a value for this property, or you can allow Jetty to try and synthesize a $ java -jar $JETTY_HOME/start.jar --add-module=demos 645 - the latter option is only advisable in the case of a single, non-clustered deployment. There are two ways a default $ java -jar $JETTY_HOME/start.jar --add-module=demos 645 can be synthesized:
So, if you’re not running on Google AppEngine, and you haven’t configured one, the workerName will always be: $ java -jar $JETTY_HOME/start.jar --add-module=demos 653. If you have more than one Jetty instance, it is crucial that you configure the $ java -jar $JETTY_HOME/start.jar --add-module=demos 645 differently for each instance. jetty.sessionScavengeInterval.seconds This is the period in seconds between runs of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 642, responsible for orchestrating the removal of expired sessions. By default it will run approximately every 600 secs (ie 10 mins). As a rule of thumb, you should ensure that the interval is shorter than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 656 of your sessions to ensure that they are promptly scavenged. On the other hand, if you have a backend store configured for your sessions, too frequently can increase the load on it. Don’t forget that the $ java -jar $JETTY_HOME/start.jar --add-module=demos 656 is specified in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 in minutes and the value of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 659 is in seconds. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 642 is responsible for the periodic initiation of session scavenge cycles. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 659 property in $ java -jar $JETTY_HOME/start.jar --add-module=demos 639 controls the periodicity of the cycle. The HouseKeeper semi-randomly adds an additional 10% to the configured $ java -jar $JETTY_HOME/start.jar --add-module=demos 663. This is to prevent multiple nodes in a cluster that are all started at once from syncing up scavenge cycles and placing extra load on the configured persistence mechanism. A session whose expiry time has been exceeded is considered eligible for scavenging. The session might be present in a $ java -jar $JETTY_HOME/start.jar --add-module=demos 629 and/or present in the session persistence/clustering mechanism. Scavenging occurs for all contexts on a server at every cycle. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 642 sequentially asks the $ java -jar $JETTY_HOME/start.jar --add-module=demos 628 in each context to find and remove expired sessions. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 628 works with the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 to evaluate candidates for expiry held in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 629, and also to sweep the persistence mechanism to find expired sessions. The sweep takes two forms: once per cycle the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 searches for sessions for its own context that have expired; infrequently, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 will widen the search to expired sessions in all contexts. The former finds sessions that are no longer in this context’s $ java -jar $JETTY_HOME/start.jar --add-module=demos 629, and using some heuristics, are unlikely to be in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 629 of the same context on another node either. These sessions will be loaded and fully expired, meaning that $ java -jar $JETTY_HOME/start.jar --add-module=demos 674 will be called for them. The latter finds sessions that have not been disposed of by scavenge cycles on any other context/node. As these will be sessions that expired a long time ago, and may not be appropriate to load by the context doing the scavenging, these are summarily deleted without $ java -jar $JETTY_HOME/start.jar --add-module=demos 674 being called. A combination of these sweeps should ensure that the persistence mechanism does not fill over time with expired sessions. As aforementioned, the sweep period needs to be short enough to find expired sessions in a timely fashion, but not so often that it overloads the persistence mechanism. In this section we will look at the alternatives for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 629, i.e. the L1 cache of in-use session objects. Jetty ships with 2 alternatives: an in-memory cache, and a null cache. The latter does not actually do any caching of sessions, and can be useful if you either want to minimize your support for sessions, or you are in a clustered deployment without a sticky loadbalancer. The go into more detail on this. If you wish to change any of the default configuration values you should enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 677 . The name $ java -jar $JETTY_HOME/start.jar --add-module=demos 678 harks back to historical Jetty session implementations, whereby sessions were kept in memory using a HashMap. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 679 contains the following configurable properties: jetty.session.evictionPolicy Integer, default -1. This controls whether session objects that are held in memory are subject to eviction from the cache. Eviction means that the session is removed from the cache. This can reduce the memory footprint of the cache and can be useful if you have a lot of sessions. Eviction is usually used in conjunction with a $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 that persists sessions. The eviction strategies and their corresponding values are: -1 (NO EVICTION) sessions are never evicted from the cache. The only way they leave are via expiration or invalidation. 0 (EVICT AFTER USE) sessions are evicted from the cache as soon as the last active request for it finishes. The session will be passed to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 to be written out before eviction. \>= 1 (EVICT ON INACTIVITY) any positive number is the time in seconds after which a session that is in the cache but has not experienced any activity will be evicted. Use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 682 property to force a session write before eviction. If you are not using one of the session store modules, ie one of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 683s, then sessions will be lost when the context is stopped, or the session is evicted. jetty.session.saveOnInactiveEvict Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. This controls whether a session will be persisted to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 if it is being evicted due to the EVICT ON INACTIVITY policy. Usually sessions will be written to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 whenever the last simultaneous request exits the session. However, as $ java -jar $JETTY_HOME/start.jar --add-module=demos 687 can be configured to skip some writes (see the documentation for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 688 module that you are using), this option is provided to ensure that the session will be written out. Be careful with this option, as in clustered scenarios it would be possible to "re-animate" a session that has actually been deleted by another node. jetty.session.saveOnCreate Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Controls whether a session that is newly created will be immediately saved to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 or lazily saved as the last request for the session exits. This can be useful if the request dispatches to another context and needs to re-use the same session id. jetty.session.removeUnloadableSessions Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Controls whether the session cache should ask a $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 to delete a session that cannot be restored - for example because it is corrupted. jetty.session.flushOnResponseCommit Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. If true, if a session is "dirty" - ie its attributes have changed - it will be written to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 as the response is about to commit. This ensures that all subsequent requests whether to the same or different node will see the updated session data. If false, a dirty session will only be written to the backing store when the last simultaneous request for it leaves the session. jetty.session.invalidateOnShutdown Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. If true, when a context is shutdown, all sessions in the cache are invalidated and deleted both from the cache and from the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632. You may need to use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 697 module if your clustering setup does not have a sticky load balancer, or if you want absolutely minimal support for sessions. If you enable this module, but you don’t enable a module that provides session persistence (ie one of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 688 modules), then sessions will neither be retained in memory nor persisted. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 699 contains the following configurable properties: jetty.session.saveOnCreate Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Controls whether a session that is newly created will be immediately saved to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 or lazily saved as the last request for the session exits. This can be useful if the request dispatches to another context and needs to re-use the same session id. jetty.session.removeUnloadableSessions Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Controls whether the session cache should ask a $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 to delete a session that cannot be restored - for example because it is corrupted. jetty.session.flushOnResponseCommit Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. If true, if a session is "dirty" - ie its attributes have changed - it will be written to the backing store as the response is about to commit. This ensures that all subsequent requests whether to the same or different node will see the updated session data. If false, a dirty session will only be written to the backing store when the last simultaneous request for it leaves the session. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 705 Jetty module supports persistent storage of session data in a filesystem. Persisting sessions to the local file system should never be used in a clustered environment. Enabling this module creates the $ java -jar $JETTY_HOME/start.jar --add-module=demos 706 directory. By default session data will be saved to this directory, one file representing each session. File names follow this pattern: $ java -jar $JETTY_HOME/start.jar --add-module=demos 707 expiry This is the expiry time in milliseconds since the epoch. contextpath This is the context path with any special characters, including $ java -jar $JETTY_HOME/start.jar --add-modules=http 42, replaced by the $ java -jar $JETTY_HOME/start.jar --add-module=demos 709 underscore character. For example, a context path of $ java -jar $JETTY_HOME/start.jar --add-module=demos 710 would become $ java -jar $JETTY_HOME/start.jar --add-module=demos 711. A context path of simply $ java -jar $JETTY_HOME/start.jar --add-modules=http 42 becomes just $ java -jar $JETTY_HOME/start.jar --add-module=demos 713. virtualhost This is the first virtual host associated with the context and has the form of 4 digits separated by $ java -jar $JETTY_HOME/start.jar --add-module=demos 714 characters: $ java -jar $JETTY_HOME/start.jar --add-module=demos 715. If there are no virtual hosts associated with a context, then $ java -jar $JETTY_HOME/start.jar --add-module=demos 716 is used. id This is the unique id of the session. Putting all of the above together as an example, a session with an id of $ java -jar $JETTY_HOME/start.jar --add-module=demos 717 for the context with path $ java -jar $JETTY_HOME/start.jar --add-module=demos 718 with no virtual hosts and an expiry of $ java -jar $JETTY_HOME/start.jar --add-module=demos 719 would have a file name of: $ java -jar $JETTY_HOME/start.jar --add-module=demos 720 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 639 file contains the following properties which may be modified to customise filesystem session storage: jetty.session.storeDir The default is $ java -jar $JETTY_HOME/start.jar --add-module=demos 706. This is a path that defines the location for storage of session files. jetty.session.file.deleteUnrestorableFiles Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. If set to $ java -jar $JETTY_HOME/start.jar --add-module=demos 298, unreadable files will be deleted. This is useful to prevent repeated logging of the same error when the scavenger periodically (re-)attempts to load the corrupted information for a session in order to expire it. jetty.session.gracePeriod.seconds Integer, default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. Enabling the $ java -jar $JETTY_HOME/start.jar --add-module=demos 735 module configures Jetty to persist session data in a relational database. After enabling the module, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 736 file contains the following customizable properties: jetty.session.gracePeriod.seconds Integer, default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. db-connection-type Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 747. Set to either $ java -jar $JETTY_HOME/start.jar --add-module=demos 747 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 749 depending on the type of connection being used. Depending which you select, there are additional properties available: $ java -jar $JETTY_HOME/start.jar --add-module=demos 747 jetty.session.jdbc.datasourceName Name of the remote datasource. $ java -jar $JETTY_HOME/start.jar --add-module=demos 749 jetty.session.jdbc.driverClass Name of the JDBC driver that controls access to the remote database, such as $ java -jar $JETTY_HOME/start.jar --add-module=demos 752 jetty.session.jdbc.driverUrl URL of the database which includes the driver type, host name and port, service name and any specific attributes unique to the database, such as a username. As an example, here is a mysql connection with the username appended: $ java -jar $JETTY_HOME/start.jar --add-module=demos 753. jetty.session.jdbc.blobType Optional. Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 754 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 755 for Postgres. This is the keyword used by the particular database to identify the blob data type. If netiher default is suitable you can set this value explicitly. jetty.session.jdbc.longType Optional. Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 756 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 757 for Oracle. This is the keyword used by the particular database to identify the long integer data type. Set this explicitly if neither of the default values is appropriate. jetty.session.jdbc.stringType Optional. Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 758. This is the keyword used by the particular database to identify character type. If the default is not suitable, you can set this value explicitly. jetty.session.jdbc.schema.schemaName jetty.session.jdbc.schema.catalogName Optional. The exact meaning of these two properties is dependent on your database vendor, but can broadly be described as further scoping for the session table name. See https://en.wikipedia.org/wiki/Database_schema and https://en.wikipedia.org/wiki/Database_catalog. These extra scoping names can come into play at startup time when Jetty determines if the session table already exists, or otherwise creates it on-the-fly. If you have employed either of these concepts when you pre-created the session table, or you want to ensure that Jetty uses them when it auto-creates the session table, then you have two options: either set them explicitly, or let Jetty infer them from a database connection (obtained using either a Datasource or Driver according to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 759 you have configured). To set them explicitly, uncomment and supply appropriate values for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 760 and/or $ java -jar $JETTY_HOME/start.jar --add-module=demos 761 properties. Alternatively, to allow Jetty to infer them from a database connection, use the special string $ java -jar $JETTY_HOME/start.jar --add-module=demos 762 instead. If you leave them blank or commented out, then the sessions table will not be scoped by schema or catalog name. jetty.session.jdbc.schema.table Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 763. This is the name of the table in which session data is stored. jetty.session.jdbc.schema.accessTimeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 764. This is the name of the column that stores the time - in ms since the epoch - at which a session was last accessed jetty.session.jdbc.schema.contextPathColumn Default $ java -jar $JETTY_HOME/start.jar 14. This is the name of the column that stores the $ java -jar $JETTY_HOME/start.jar 14 of a session. jetty.session.jdbc.schema.cookieTimeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 767. This is the name of the column that stores the time - in ms since the epoch - that the cookie was last set for a session. jetty.session.jdbc.schema.createTimeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 768. This is the name of the column that stores the time - in ms since the epoch - at which a session was created. jetty.session.jdbc.schema.expiryTimeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 769. This is name of the column that stores - in ms since the epoch - the time at which a session will expire. jetty.session.jdbc.schema.lastAccessTimeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 726. This is the name of the column that stores the time - in ms since the epoch - that a session was previously accessed. jetty.session.jdbc.schema.lastSavedTimeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 771. This is the name of the column that stores the time - in ms since the epoch - at which a session was last written. jetty.session.jdbc.schema.idColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 772. This is the name of the column that stores the id of a session. jetty.session.jdbc.schema.lastNodeColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 773. This is the name of the column that stores the $ java -jar $JETTY_HOME/start.jar --add-module=demos 645 of the last node to write a session. jetty.session.jdbc.schema.virtualHostColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 775. This is the name of the column that stores the first virtual host of the context of a session. jetty.session.jdbc.schema.maxIntervalColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 776. This is the name of the column that stores the interval - in ms - during which a session can be idle before being considered expired. jetty.session.jdbc.schema.mapColumn Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 777. This is the name of the column that stores the serialized attributes of a session. Enabling the $ java -jar $JETTY_HOME/start.jar --add-module=demos 778 module configures Jetty to store session data in MongoDB. Because MongoDB is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case) during the install. Jars needed by MongoDB are downloaded and stored into a directory named $ java -jar $JETTY_HOME/start.jar --add-module=demos 779. If you want to use updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory and use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 781 command line option to prevent errors when starting your server. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 782 file contains these configurable properties: jetty.session.mongo.dbName Default is "HttpSessions". This is the name of the database in MongoDB used to store the session collection. jetty.session.mongo.collectionName Default is "jettySessions". This is the name of the collection in MongoDB used to store all of the sessions. The connection type- You can connect to MongoDB either using a host/port combination, or a URI. By default, the host/port method is selected, but you can change this by commenting out the unwanted method, and uncommenting the other one. connection-type=address Used when utilizing a direct connection to the MongoDB server. jetty.session.mongo.host Host name or address for the remote MongoDB instance. jetty.session.mongo.port Port number for the remote MongoDB instance. connection-type=uri Used when utilizing MongoURI for secured connections. jetty.session.mongo.connectionString The string defining the MongoURI value, such as $ java -jar $JETTY_HOME/start.jar --add-module=demos 783. More information on how to format the MongoURI string can be found in the official documentation for mongo. You will only use one $ java -jar $JETTY_HOME/start.jar --add-module=demos 784 at a time, either $ java -jar $JETTY_HOME/start.jar --add-module=demos 785 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 786. If both are utilized in your $ java -jar $JETTY_HOME/start.jar --add-module=demos 787, only the last $ java -jar $JETTY_HOME/start.jar --add-module=demos 784 configured in the file will be used. jetty.session.gracePeriod.seconds Integer, in seconds. Default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. In order to persist/cluster sessions using Infinispan, Jetty needs to know how to contact Infinispan. There are two options: a remote Infinispan instance, or an in-process Infinispan instance. The former is referred to as "remote" Infinispan and the latter as "embedded" Infinispan. If you wish Jetty to be able to expired sessions, you will also need to enable the appropriate $ java -jar $JETTY_HOME/start.jar --add-module=demos 799 module. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 800 module configures Jetty to talk to an external Infinispan instance to store session data. Because Infinispan is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case). Infinispan-specific jar files are download to the directory named $ java -jar $JETTY_HOME/start.jar --add-module=demos 801. In addition to adding these modules to the classpath of the server it also added several ini configuration files to the $ java -jar $JETTY_HOME/start.jar --add-module=demos 802 directory. If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory and use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 781 command line option to prevent errors when starting your server. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 805 contains the following configurable properties: jetty.session.infinispan.remoteCacheName Default $ java -jar $JETTY_HOME/start.jar --add-module=demos 806. This is the name of the cache in Infinispan where sessions will be stored. jetty.session.infinispan.idleTimeout.seconds Integer, in seconds, default $ java -jar $JETTY_HOME/start.jar 37. This is the amount of time, in seconds, that a session entry in Infinispan can be idle (ie neither read nor written) before Infinispan will delete its entry. Usually, you do not want to set a value for this, as you want Jetty to manage all session expiration (and call any HttpSessionListeners). You should enable the to allow jetty to for expired sessions. If you do not, then there is the possibility that sessions can be left in Infinispan but no longer referenced by any Jetty node (so called "zombie" or "orphan" sessions), in which case you can use this feature to ensure their removal. You should make sure that the number of seconds you specify is larger than the configured $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 for sessions. jetty.session.gracePeriod.seconds Integer, default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 819 module allows Jetty to expired sessions. Note that this is an additional module, to be used in conjunction with the $ java -jar $JETTY_HOME/start.jar --add-module=demos 800 module. There are no configuration properties associated with this module. Enabling the $ java -jar $JETTY_HOME/start.jar --add-module=demos 821 module runs an in-process instance of Infinispan. Because Infinispan is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case). Infinispan-specific jar files will be downloaded and saved to a directory named $ java -jar $JETTY_HOME/start.jar --add-module=demos 801. If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory and use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 781 command line option to prevent errors when starting your server. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 825 contains the following configurable properties: jetty.session.infinispan.idleTimeout.seconds Integer, in seconds, default $ java -jar $JETTY_HOME/start.jar 37. This is the amount of time, in seconds, that a session entry in Infinispan can be idle (ie neither read nor written) before Infinispan will delete its entry. Usually, you do not want to set a value for this, as you want Jetty to manage all session expiration (and call any HttpSessionListeners). You should enable the to allow Jetty to for expired sessions. If you do not, then there is the possibility that expired sessions can be left in Infinispan. You should make sure that the number of seconds you specify is larger than the configured $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 for sessions. jetty.session.gracePeriod.seconds Integer, default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. From Jetty-9.4.13 onwards, we have changed the format of the serialized session when using a remote cache (ie using hotrod). Prior to release 9.4.13 we used the default Infinispan serialization, however this was not able to store sufficient information to allow Jetty to properly deserialize session attributes in all circumstances. See issue https://github.com/eclipse/jetty.project/issues/2919 for more background. We have provided a conversion program which will convert any sessions stored in Infinispan to the new format. We recommend that you backup your stored sessions before running the conversion program. How to use the converter: $ java -jar $JETTY_HOME/start.jar 40 The classpath Must contain the servlet-api, jetty-util, jetty-server, jetty-infinispan and infinispan-remote jars. If your sessions contain attributes that use application classes, you will also need to also put those classes onto the classpath. If your session has been authenticated, you may also need to include the jetty-security and jetty-http jars on the classpath. Parameters When used with no arguments the usage message is printed. When used with the $ java -jar $JETTY_HOME/start.jar --add-module=demos 837 parameter the conversion is performed. When used with both $ java -jar $JETTY_HOME/start.jar --add-module=demos 837 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 839 parameters, sessions are checked for whether or not they are converted. -Dhost you can optionally provide a system property with the address of your remote Infinispan server. Defaults to the localhost. -Dverbose defaults to false. If true, prints more comprehensive stacktrace information about failures. Useful to diagnose why a session is not converted. cache-name the name of the remote cache containing your sessions. This is mandatory. check the optional check command will verify sessions have been converted. Use it after doing the conversion. To perform the conversion, run the InfinispanSessionLegacyConverter with just the $ java -jar $JETTY_HOME/start.jar --add-module=demos 837, and optionally the $ java -jar $JETTY_HOME/start.jar --add-module=demos 841 system property. The following command will attempt to convert all sessions in the cached named $ java -jar $JETTY_HOME/start.jar --add-module=demos 842 on the machine $ java -jar $JETTY_HOME/start.jar --add-module=demos 843, ensuring that application classes in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 844 directory are on the classpath: $ java -jar $JETTY_HOME/start.jar 41 If the converter fails to convert a session, an error message and stacktrace will be printed and the conversion will abort. The failed session should be untouched, however it is prudent to take a backup of your cache before attempting the conversion. Hazelcast can be used to cluster session information in one of two modes: either remote or embedded. Remote mode means that Hazelcast will create a client to talk to other instances, possibly on other nodes. Embedded mode means that Hazelcast will start a local instance and communicate with that. Enabling the $ java -jar $JETTY_HOME/start.jar --add-module=demos 845 module allows jetty to communicate with a remote Hazelcast instance to cluster session data. Because Hazelcast is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case). Hazelcast-specific jar files will be downloaded and saved to a directory named $ java -jar $JETTY_HOME/start.jar --add-module=demos 846. If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory and use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 781 command line option to prevent errors when starting your server. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 849 contains a list of all the configurable options for the Hazelcast module: jetty.session.hazelcast.mapName The default is "jetty-distributed-session-map". This is the name of the Map in Hazelcast where sessions will be stored. jetty.session.hazelcast.onlyClient Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 298. The Hazelcast instance will be configured in client mode. jetty.session.hazelcast.configurationLocation Optional. This is the path to an external Hazelcast xml configuration file. jetty.session.hazelcast.useQueries Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. If $ java -jar $JETTY_HOME/start.jar --add-module=demos 298, Jetty will use Hazelcast queries to find sessions to . If $ java -jar $JETTY_HOME/start.jar --add-module=demos 050 sessions that are not currently in a cannot be , and will need to be removed by some external process. jetty.session.hazelcast.addresses Optional. These are the addresses of remote Hazelcast instances with which to communicate. jetty.session.gracePeriod.seconds Integer, in seconds. Default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. Be aware that if your session attributes contain classes from inside your webapp (or Jetty classes) then you will need to put these classes onto the classpath of all of your Hazelcast instances. This will run an in-process instance of Hazelcast. This can be useful for example during testing. To enable this you enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 864 module. Because Hazelcast is not a technology provided by the Eclipse Foundation, you will be prompted to assent to the licenses of the external vendor (Apache in this case). Hazelcast-specific jar files will be downloaded to a directory named $ java -jar $JETTY_HOME/start.jar --add-module=demos 846. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 866 contains a list of all the configurable options for the Hazelcast module: jetty.session.hazelcast.mapName The default is "jetty-distributed-session-map". This is the name of the Map in Hazelcast where sessions will be stored. jetty.session.hazelcast.hazelcastInstanceName Default is "JETTY_DISTRIBUTED_SESSION_INSTANCE". This is the unique name of the Hazelcast instance that will be created. jetty.session.hazelcast.configurationLocation Optional. This is the path to an external Hazelcast xml configuration file. jetty.session.hazelcast.useQueries Boolean, default $ java -jar $JETTY_HOME/start.jar --add-module=demos 867, Jetty will use Hazelcast queries to find expired sessions to . If $ java -jar $JETTY_HOME/start.jar --add-module=demos 050 sessions that are not currently in a cannot be , and will need to be removed by some external process. jetty.session.gracePeriod.seconds Integer, in seconds. Default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. If your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances. In the case of embedded hazelcast, as it is started before your webapp, it will NOT have access to your webapp’s classes - you will need to extract these classes and put them onto the jetty server’s classpath. Jetty can store http session information into GCloud by enabling the $ java -jar $JETTY_HOME/start.jar --add-module=demos 879 module. Before running Jetty, you will need to choose one of the following methods to set up the local environment to enable remote GCloud DataStore communications.
Using some special, composite indexes can speed up session search operations, although it may make write operations slower. By default, indexes will not be used. In order to use them, you will need to manually upload a file that defines the indexes. This file is named $ java -jar $JETTY_HOME/start.jar --add-module=demos 884 and you can find it in your distribution in $ java -jar $JETTY_HOME/start.jar --add-module=demos 885. Follow the instructions to upload the pre-generated $ java -jar $JETTY_HOME/start.jar --add-module=demos 884 file. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 879 module provides GCloud support for storing session data. Because the Google Cloud DataStore is not a technology provided by the Eclipse Foundation, when enabling the module you will be prompted to assent to the licenses of the external vendor. As GCloud requires certain Java Commons Logging features to work correctly, Jetty routes these through SLF4J. By default, Jetty implements the SLF4J api, but you can choose a different logging implementation by following the instructions If you want to use updated versions of the jar files automatically downloaded during the module enablement, you can place them in the associated $ java -jar $JETTY_HOME/start.jar --add-modules=http 56 directory and use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 781 command line option to prevent errors when starting your server. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 890 file contains all of the configurable properties for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 879 module: jetty.session.gcloud.maxRetries Integer. Default 5. Maximum number of retries to connect to GCloud DataStore to write a session. jetty.session.gcloud.backoffMs Integer in milliseconds. Default 1000. Number of milliseconds between successive attempts to connect to the GCloud DataStore to write a session. jetty.session.gracePeriod.seconds Integer, in seconds. Default 3600. Used during session . Multiples of this period are used to define how long ago a stored session must have expired before it should be . jetty.session.savePeriod.seconds Integer, in seconds, default is $ java -jar $JETTY_HOME/start.jar 37. Whenever a session is accessed by a request, its $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 are updated. Even if your sessions are read-mostly, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 726 and $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 will always change. For heavily-used, read-mostly sessions you can save some time by skipping some writes for sessions for which only these fields have changed (ie no session attributes changed). The value of this property is used to skip writes for these kinds of sessions: the session will only be written out if the time since the last write exceeds the value of this property. You should be careful in the use of this property in clustered environments: if you set too large a value for this property, the session may not be written out sufficiently often to update its $ java -jar $JETTY_HOME/start.jar --add-module=demos 727 time thus making it appear to other nodes that it has expired. Thorough consideration of the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731 of the session when setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 is imperative - it would be undesirable to set a $ java -jar $JETTY_HOME/start.jar --add-module=demos 732 that is larger than the $ java -jar $JETTY_HOME/start.jar --add-module=demos 731. jetty.session.gcloud.namespace Optional. Sets the namespace for GCloud Datastore to use. If set, partitions the visibility of session data between webapps, which is helpful for multi-tenant deployments. More information can be found here. Configuration of the stored session object and its fields names- You should very rarely, if ever, need to change these defaults. jetty.session.gcloud.model.kind The default is "GCloudSession". This is the type of the object that is stored in GCloud. jetty.session.gcloud.model.id The default is "id". This is the session id. jetty.session.gcloud.model.contextPath The default is "contextPath". This is the canonicalized context path of the context to which the session belongs. jetty.session.gcloud.model.vhost The default is "vhost". This is the canonicalized virtual host of the context to which the session belongs. jetty.session.gcloud.model.accessed The default is "accessed". This is the current access time of the session. jetty.session.gcloud.model.lastAccessed The default is "lastAccessed". This is the last access time of the session. jetty.session.gcloud.model.createTime The default is "createTime". This is the time, in ms since the epoch, at which the session was created. jetty.session.gcloud.model.cookieSetTime The default is "cookieSetTime". This is the time at which the session cookie was last set. jetty.session.gcloud.model.lastNode The default is "lastNode". This is the $ java -jar $JETTY_HOME/start.jar --add-module=demos 645 of the last node to manage the session. jetty.session.gcloud.model.expiry The default is "expiry". This is the time, in ms since the epoch, at which the session will expire. jetty.session.gcloud.model.maxInactive The default is "maxInactive". This is the session timeout in ms. jetty.session.gcloud.model.attributes The default is "attributes". This is a map of all the session attributes. If your chosen persistence technology is slow, it can be helpful to locally cache the session data. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 634 is a special type of $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 that locally caches session data, which makes reads faster. It writes-through to your chosen type of $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 when session data changes. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 906 uses $ java -jar $JETTY_HOME/start.jar --add-module=demos 907 to perform caching of $ java -jar $JETTY_HOME/start.jar --add-module=demos 908. To enable it with the Jetty distribution, enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 909 module, along with your chosen $ java -jar $JETTY_HOME/start.jar --add-module=demos 683 module. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 911 contains the following configurable properties: jetty.session.memcached.host Default value is $ java -jar $JETTY_HOME/start.jar 25. This is the host on which the memcached server resides. jetty.session.memcached.port Default value is $ java -jar $JETTY_HOME/start.jar --add-module=demos 913. This is the port on which the memcached server is listening. jetty.session.memcached.expirySec Default value $ java -jar $JETTY_HOME/start.jar 37. This is the length of time in seconds that an item can remain in the memcached cache, where 0 indicates indefinitely. jetty.session.memcached.heartbeats Default value $ java -jar $JETTY_HOME/start.jar --add-module=demos 298. Whether the memcached system should generate heartbeats. Preferably, your cluster will utilize a sticky load balancer. This will route requests for the same session to the same Jetty instance. In this case, the can be used to keep in-use session objects . You can fine-tune the cache by controlling how long session objects remain in memory with the . If you have a large number of sessions or very large session objects, then you may want to manage your memory allocation by controlling the amount of time session objects spend in the cache. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 917 eviction policy will remove a session object from the cache as soon as the last simultaneous request referencing it exits. Alternatively, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 918 policy will remove a session object from the cache after a configurable amount of time has passed without a request referencing it. If your sessions are very long lived and infrequently referenced, you might use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 919 to control the size of the cache. If your sessions are small, or relatively few or stable in number or they are read-mostly, then you might select the $ java -jar $JETTY_HOME/start.jar --add-module=demos 920 policy. With this policy, session objects will remain in the cache until they either expire or are explicitly invalidated. If you have a high likelihood of simultaneous requests for the same session object, then the $ java -jar $JETTY_HOME/start.jar --add-module=demos 917 policy will ensure the session object stays in the cache as long as it is needed. Without a sticky load balancer requests for the same session may arrive on any node in the cluster. This means it is likely that the copy of the session object in any $ java -jar $JETTY_HOME/start.jar --add-module=demos 629 is likely to be out-of-date, as the session was probably last accessed on a different node. In this case, your choices are to use either the or to de-tune the . If you use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 923 all session object caching is avoided. This means that every time a request references a session it must be read in from persistent storage. It also means that there can be no sharing of session objects for multiple requests for the same session: each will have their own independent session object. Furthermore, the outcome of session writes are indeterminate because the Servlet Specification does not mandate ACID transactions for sessions. If you use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 916, there is a risk that the caches on some nodes will contain out-of-date session information as simultaneous requests for the same session are scattered over the cluster. To mitigate this somewhat you can use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 917 eviction policy: this will ensure that the session is removed from the cache as soon as the last simultaneous request for it exits. Again, due to the lack of session transactionality, the ordering outcome of write operations cannot be guaranteed. As the session is cached while at least one request is accessing it, it is possible for multiple simultaneous requests to share the same session object. For various reasons it might not be possible for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 632 to re-read a stored session. One scenario is that the session stores a serialized object in its attributes, and after a re-deployment there in an incompatible class change. Setting the $ java -jar $JETTY_HOME/start.jar --add-module=demos 679 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 699 property $ java -jar $JETTY_HOME/start.jar --add-module=demos 931 to $ java -jar $JETTY_HOME/start.jar --add-module=demos 298 will allow the unreadable session to be removed from persistent storage. This can be useful for preventing the from continually generating errors on the same expired, but un-readable session. The auto discovery features of the Servlet Specification can make deployments slow and uncertain. Auto discovery of 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 933 module allows a webapp to be pre-scanned, making startup predictable and faster. During scanning all declarative configuration (ie from web.xml, web-fragment.xml and annotations) are encoded into an effective $ java -jar $JETTY_HOME/start.jar --add-module=demos 191, called $ java -jar $JETTY_HOME/start.jar --add-module=demos 935, which can be inspected to understand what will be deployed. Programmatic configuration is not encoded into the generated $ java -jar $JETTY_HOME/start.jar --add-module=demos 936 file. With $ java -jar $JETTY_HOME/start.jar --add-module=demos 933, webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds. Enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 933 module for your jetty base: $ java -jar $JETTY_HOME/start.jar 42 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 939 file contains these configurable parameters: jetty.quickstart.mode The values are: AUTO Allows jetty to run either with or without a $ java -jar $JETTY_HOME/start.jar --add-module=demos 936 file. If jetty detects the file, then it will be used, otherwise the app is started normally. GENERATE In this mode, jetty will generate a $ java -jar $JETTY_HOME/start.jar --add-module=demos 936 file and then terminate. Use this mode first before changing to either $ java -jar $JETTY_HOME/start.jar --add-module=demos 942 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 943. QUICKSTART In this mode, if jetty does not detect a $ java -jar $JETTY_HOME/start.jar --add-module=demos 936 file then jetty will not start. jetty.quickstart.origin Use this parameter to set the name of the attribute in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 936 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 936 in the webapp’s $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 98 directory. The file named by this parameter will always be interpreted relative to $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 98. If your webapp is a war file, you will need to either first unpack it yourself, or use a context xml file (or code equivalent) that calls $ java -jar $JETTY_HOME/start.jar --add-module=demos 949. If you allow Jetty to do the unpacking, it will use the usual mechanisms to find the location to which to unpack. Note that by default Jetty unpacks to a temporary location which is not reused between executions. So either specify the directory to which to unpack, or make a $ java -jar $JETTY_HOME/start.jar --add-module=demos 950 directory in your base to ensure the unpacked war is preserved and reused across restarts. Enable the $ java -jar $JETTY_HOME/start.jar --add-module=demos 951 module if your webapp - or any of its third party libraries - uses any of the following:
According to more recent versions of the Jakarta Servlet Specification, the $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 file can contain the attribute $ java -jar $JETTY_HOME/start.jar --add-module=demos 953. If this is set to $ java -jar $JETTY_HOME/start.jar --add-module=demos 298, then no annotation scanning takes place, and your descriptor must contain the equivalent xml statements of any annotations. If it is $ java -jar $JETTY_HOME/start.jar --add-module=demos 955, or your $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 predates the inclusion of this attribute, annotation scanning is required to take place. To prevent annotation scanning you can use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 957 method. Here’s an example context XML file that calls this method: $ java -jar $JETTY_HOME/start.jar 43 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies that scanning should not take place. However, despite $ java -jar $JETTY_HOME/start.jar --add-module=demos 959, scanning of classes may still occur because of $ java -jar $JETTY_HOME/start.jar --add-module=demos 960. Classes implementing this interface are found by Jetty using the javax.util.ServiceLoader mechanism, and if one is present and it includes the $ java -jar $JETTY_HOME/start.jar --add-module=demos 961 annotation, then Jetty must scan the class hierarchy of the web application. This may be very time-consuming if you have many jars. Jetty can reduce the time taken by limiting the jars that are scanned. By default, Jetty will not scan any classes that are on the container’s classpath. Sometimes, you may have third party libraries on the container’s classpath that you need to be scanned. In this case, use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 962 context attribute to define which container jars and class directories to scan. The value of this attribute is a regular expression. Here’s an example from a context XML file that includes any jar whose name starts with $ java -jar $JETTY_HOME/start.jar --add-module=demos 963 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 964, or a directory named $ java -jar $JETTY_HOME/start.jar --add-module=demos 965: $ java -jar $JETTY_HOME/start.jar 44 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies a context attribute. 3 Specifies the name of the context attribute. 4 Specifies the value of the context attribute. Note that the order of the patterns defines the ordering of the scanning of the jars or class directories. By default, Jetty will scan all classes from $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 99 and all jars from $ java -jar $JETTY_HOME/start.jar 01 according to the order, if any, established by absolute or relative ordering clauses in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191. If your webapp contains many jar files that you know do not contain any annotations, you can significantly speed up deployment by omitting them from scanning. However, be careful if your webapp uses a $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 with a $ java -jar $JETTY_HOME/start.jar --add-module=demos 961 annotation that you don’t exclude jars that contain classes matching the annotation. Use the $ java -jar $JETTY_HOME/start.jar --add-module=demos 972 context attribute to define a regular expression for jars and class directories to select for scanning. Here’s an example of a context XML file that sets a pattern that matches any jar on the webapp’s classpath that starts with $ java -jar $JETTY_HOME/start.jar --add-module=demos 973: $ java -jar $JETTY_HOME/start.jar 45 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies a context attribute. 3 Specifies the name of the context attribute. 4 Specifies the value of the context attribute. By default, Jetty performs annotation scanning in a multi-threaded manner in order to complete it in the minimum amount of time. If you don’t want multi-threaded scanning, you can configure Jetty to revert to single-threaded scanning. There are several options to configure this:
Method 1 will only affect the current webapp. Method 2 will affect all webapps deployed to the same Server instance. Method 3 will affect all webapps deployed in the same JVM. By default, Jetty will wait a maximum of 60 seconds for all of the scanning threads to complete. You can set this to a higher or lower number of seconds by doing one of the following:
Method 1 will only affect the current webapp. Method 2 will affect all webapps deployed to the same Server instance. Method 3 will affect all webapps deployed in the same JVM. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 class can exist in: the container’s classpath, the webapp’s $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 99 directory, the webapp’s $ java -jar $JETTY_HOME/start.jar 01 jars, or any external extraClasspath that you have configured on the webapp. The Jakarta Servlet Specification does not define any order in which a $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 must be called when the webapp starts. By default, Jetty will call them in the following order:
By default, as according to the Jakarta Servlet Specification, all $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 instances that are discovered are invoked. Sometimes, depending on your requirements, you may need to prevent some being called at all. In this case, you can define the $ java -jar $JETTY_HOME/start.jar --add-module=demos 995 context attribute. This is a regular expression that defines patterns of classnames that you want to exclude. Here’s an example of setting the context attribute in a context XML file: $ java -jar $JETTY_HOME/start.jar 46 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies a context attribute. 3 Specifies the name of the context attribute. 4 Specifies the value of the context attribute. In this example we exclude all $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 instances in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 998, and the specific class $ java -jar $JETTY_HOME/start.jar --add-module=demos 999. It is possible to use exclusion and ordering together to control $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 invocation - the exclusions will be applied before the ordering. If you need $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 classes called in a specific order, you can use the context attribute $ java -jar $JETTY_HOME/start.jar 002. Set it to a list of comma separated $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 class names in the order that you want them applied. You may optionally use the wildcard character $ java -jar $JETTY_HOME/start.jar 004 once in the list. It will match all $ java -jar $JETTY_HOME/start.jar --add-module=demos 960 classes not explicitly named in the list. Here is an example context XML file that ensures the $ java -jar $JETTY_HOME/start.jar 006 will be called first, followed by the $ java -jar $JETTY_HOME/start.jar 007, then all other SCIs: $ java -jar $JETTY_HOME/start.jar 47 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies a context attribute. 3 Specifies the name of the context attribute. 4 Specifies the value of the context attribute. Jetty supports JSP via the $ java -jar $JETTY_HOME/start.jar 009 modules, which are based on Apache Jasper: $ java -jar $JETTY_HOME/start.jar 48 Logging has been bridged to Jetty logging, so you can enable logging for the $ java -jar $JETTY_HOME/start.jar 010 package, subpackages and classes as usual. The $ java -jar $JETTY_HOME/start.jar 011 is the servlet responsible for serving JSPs. It is configured as the default jsp servlet in the $ java -jar $JETTY_HOME/start.jar 012 file. Notice that Jetty identifies the jsp servlet by the presence of the $ java -jar $JETTY_HOME/start.jar 013 attribute in the $ java -jar $JETTY_HOME/start.jar 014 declaration. That file maps the $ java -jar $JETTY_HOME/start.jar 011 to the following partial urls:
You can change to a different servlet, change or add $ java -jar $JETTY_HOME/start.jar 024s or add extra $ java -jar $JETTY_HOME/start.jar 025s in your $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 file. Here’s an example of adding an $ java -jar $JETTY_HOME/start.jar 024 to augment the definitions from the standard $ java -jar $JETTY_HOME/start.jar 028 file: $ java -jar $JETTY_HOME/start.jar 49 1 This identifies this servlet as the jsp servlet to Jetty. 2 This identifies this declaration as augmenting the already-defined servlet called $ java -jar $JETTY_HOME/start.jar 029. 3 This init param controls whether the jsp servlet retains the $ java -jar $JETTY_HOME/start.jar 030 files generated during jsp compilation. 4 This sets the value of the init param Another element you might consider adding to the default setup is $ java -jar $JETTY_HOME/start.jar 031: $ java -jar $JETTY_HOME/start.jar 50 1 This identifies this servlet as the jsp servlet to Jetty. 2 This identifies this declaration as augmenting the already-defined servlet called $ java -jar $JETTY_HOME/start.jar 029. 3 By default, the jsp servlet does not support async. There are many configuration parameters for the Apache Jasper JSP Servlet, here are some of them: Table 5. JSP Servlet Parameters init param Description Default $ java -jar $JETTY_HOME/start.jar 028 checkInterval If non-zero and $ java -jar $JETTY_HOME/start.jar 034 is $ java -jar $JETTY_HOME/start.jar --add-module=demos 050, 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 $ java -jar $JETTY_HOME/start.jar 036 context attribute is used to add to the classpath, but if this is not set, this $ java -jar $JETTY_HOME/start.jar 037 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 $ java -jar $JETTY_HOME/start.jar --add-module=demos 298 recompilation checks occur at the frequency governed by $ java -jar $JETTY_HOME/start.jar 039. 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 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 $ java -jar $JETTY_HOME/start.jar 040, 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 $ java -jar $JETTY_HOME/start.jar 041, or the system property $ java -jar $JETTY_HOME/start.jar 042 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 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. The JavaServer Pages Standard Tag Library (JSTL) is part of the Jetty distribution, and is available via the $ java -jar $JETTY_HOME/start.jar 043 modules: $ java -jar $JETTY_HOME/start.jar 51 When enabled, Jetty will make the JSTL tags available for your webapps. If you want to use JSF with your webapp, you should copy the relevant jars from your implementation of choice into your $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory, ideally into $ java -jar $JETTY_HOME/start.jar 045. If that directory does not exist, enable the 80 module, which will create the directory and ensure all jars within it are put onto the container classpath. Then you will need to tell Jetty which of those jars contains the $ java -jar $JETTY_HOME/start.jar 047 files. To accomplish that, you need to specify either the name of the file or a pattern that matches the name/s of the file/s as the $ java -jar $JETTY_HOME/start.jar --add-module=demos 962 context attribute. You will need to preserve the existing value of the attribute, and add in your extra pattern. Here’s an example of using a context xml file to add in a pattern to match files starting with $ java -jar $JETTY_HOME/start.jar 049, which contain the $ java -jar $JETTY_HOME/start.jar 047 files: $ java -jar $JETTY_HOME/start.jar 52 1 Configures a $ java -jar $JETTY_HOME/start.jar --add-module=demos 174, which is the Jetty component that represents a standard Servlet web application. 2 Specifies a context attribute. 3 Specifies the name of the context attribute. 4 Adds the additional pattern $ java -jar $JETTY_HOME/start.jar 052 to those already existing. For each specific Jakarta EE environment there is a specific $ java -jar $JETTY_HOME/start.jar 053 module that you must enable in order to use JNDI resources in your webapp:
If you have already enabled an module suitable for your environment, an appropriate $ java -jar $JETTY_HOME/start.jar 053 module will already have been enabled and you do not need to explicitly enable a $ java -jar $JETTY_HOME/start.jar 053 module. If you have extra jars associated with your JNDI resources, eg database drivers etc, that are not located inside your webapp then you must ensure they are on either the container classpath or a Jakarta EE environment classpath. You can enable the 80 module and place your jars in $ java -jar $JETTY_HOME/start.jar 061 to make them visible on the container classpath. To make them visible on an environment classpath you should create a custom, environment-specific module. You can now declare JNDI resources and reference them within your webapps. You must declare the objects you want bound into the environment so that you can then hook them into your webapp via $ java -jar $JETTY_HOME/start.jar 062, $ java -jar $JETTY_HOME/start.jar 063 and $ java -jar $JETTY_HOME/start.jar 064 in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191, $ java -jar $JETTY_HOME/start.jar 066 or $ java -jar $JETTY_HOME/start.jar 067. You make these declarations in Jetty XML files that are either external or internal to your webapp. A server or context XML file is external to your webapp. The special $ java -jar $JETTY_HOME/start.jar --add-module=demos 194 file is internal to your webapp. See the section on for more information on how to choose in which XML file to place your declarations. Regardless of its location, the XML file contains declarations of JNDI resources that can be referenced later within your webapp. The declarations are new instances of the following types: Declarations of each of these types follow a similar pattern: wiki.xml $ java -jar $JETTY_HOME/start.jar 53 1 Defines a resource to Jetty. 2 Specifies the of the resource. 3 Specifies the name of the resource which will be looked up by the webapp relative to the $ java -jar $JETTY_HOME/start.jar 069 or $ java -jar $JETTY_HOME/start.jar 070 namespace. 4 Specifies the value of the resource. Sometimes it is useful to pass configuration information to a webapp at runtime that you either cannot or cannot conveniently code into a $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 $ java -jar $JETTY_HOME/start.jar 072. In such cases, you can use the $ java -jar $JETTY_HOME/start.jar 073 class, and optionally even override an entry of the same name in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191. Here’s an example that defines the equivalent of an $ java -jar $JETTY_HOME/start.jar 062 called $ java -jar $JETTY_HOME/start.jar 076 with value $ java -jar $JETTY_HOME/start.jar 077 that overrides an $ java -jar $JETTY_HOME/start.jar 072 declaration of the same name in web.xml: wiki.xml $ java -jar $JETTY_HOME/start.jar 54 1 Define an $ java -jar $JETTY_HOME/start.jar 079 that corresponds to an $ java -jar $JETTY_HOME/start.jar 072. 2 at the JVM level. 3 The name of the entry, corresponding to a lookup by the webapp of $ java -jar $JETTY_HOME/start.jar 081. 4 The value of the entry, in this case the integer value $ java -jar $JETTY_HOME/start.jar 077. 5 $ java -jar $JETTY_HOME/start.jar --add-module=demos 298 means to override the value of an $ java -jar $JETTY_HOME/start.jar 072 of the same name in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191. Note that if you don’t want to override the $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 value, simply omit the last argument, or set it to $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. The Servlet Specification allows binding only the following object types to an $ java -jar $JETTY_HOME/start.jar 062:
Jetty is a little more flexible and allows you to also bind:
Be aware that if you take advantage of this feature, your web application is not portable. You can configure any type of resource that you want to refer to in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 via a $ java -jar $JETTY_HOME/start.jar 063 or $ java -jar $JETTY_HOME/start.jar 093 by using the $ java -jar $JETTY_HOME/start.jar 094 type of naming entry. You provide the scope, the name of the object (relative to $ java -jar $JETTY_HOME/start.jar
$ java -jar $JETTY_HOME/start.jar 096 or $ java -jar $JETTY_HOME/start.jar 097 instance. This example configures a Derby DataSource named $ java -jar $JETTY_HOME/start.jar 098: wiki.xml $ java -jar $JETTY_HOME/start.jar 55 This would be linked into the webapp’s JNDI namespace via an entry in a $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 like so: $ java -jar $JETTY_HOME/start.jar 56 When configuring Resources, ensure that the type of object you configure matches the type of object you expect to look up in $ java -jar $JETTY_HOME/start.jar 070. For database connection factories, this means that the object you register as a Resource must implement the $ java -jar $JETTY_HOME/start.jar --list-modules=* 20 interface. Also note that the J2EE Specification recommends storing DataSources relative to $ java -jar $JETTY_HOME/start.jar 102 and thus looked up by the application as $ java -jar $JETTY_HOME/start.jar 103. Eg The Datasource bound in Jetty as $ java -jar $JETTY_HOME/start.jar 104 would be looked up by the application as $ java -jar $JETTY_HOME/start.jar 105 Jetty can bind any implementation of the JMS destinations and connection factories. Here is an example of binding an ActiveMQ in-JVM connection factory: wiki.xml $ java -jar $JETTY_HOME/start.jar 57 The corresponding entry in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 to bind the ConnectionFactory into the webapp’s JNDI namespace would be: wiki.xml $ java -jar $JETTY_HOME/start.jar 58 The J2EE Specification recommends storing JMS connection factories under $ java -jar $JETTY_HOME/start.jar 107. Eg The ConnectionFactory bound in Jetty as $ java -jar $JETTY_HOME/start.jar 108 would be looked up by the application as $ java -jar $JETTY_HOME/start.jar 109. To configure access to $ java -jar $JETTY_HOME/start.jar 110 from within a webapp, declare an $ java -jar $JETTY_HOME/start.jar 094 with an $ java -jar $JETTY_HOME/start.jar 112 that will hold the mail configuration and create the instance of the $ java -jar $JETTY_HOME/start.jar 113 when it is referenced: wiki.xml $ java -jar $JETTY_HOME/start.jar 59 1 Use the $ java -jar $JETTY_HOME/start.jar 114 class to hold the configuration. 2 Set the username for the mail instance. 3 Set the password for the mail instance — use the to obfuscate the password. 4 Set all other applicable properties. The webapp performs a lookup for $ java -jar $JETTY_HOME/start.jar 115 at runtime and obtains a $ java -jar $JETTY_HOME/start.jar 110 that has the correct configuration to permit it to send email via SMTP. Jetty does not provide the $ java -jar $JETTY_HOME/start.jar 117 and $ java -jar $JETTY_HOME/start.jar 118 jars. Note also that the J2EE Specification recommends storing JavaMail connection factories under $ java -jar $JETTY_HOME/start.jar 119. Eg The $ java -jar $JETTY_HOME/start.jar 120 bound to jetty as $ java -jar $JETTY_HOME/start.jar 121 would be looked up by the application as $ java -jar $JETTY_HOME/start.jar 122. To perform distributed transactions with your resources, a transaction manager that supports the JTA interfaces is required. The transaction manager is looked up by the application as $ java -jar $JETTY_HOME/start.jar 123. Jetty does not ship with a JTA manager, but does provide the infrastructure to plug in the JTA manager of your choice. If your JTA library’s implementation of $ java -jar $JETTY_HOME/start.jar --list-modules=* 16 implements $ java -jar $JETTY_HOME/start.jar 096, then you should use the $ java -jar $JETTY_HOME/start.jar 126 object in a to register it in JNDI: wiki.xml $ java -jar $JETTY_HOME/start.jar 60 If your JTA library’s implementation of $ java -jar $JETTY_HOME/start.jar --list-modules=* 16 does not implement $ java -jar $JETTY_HOME/start.jar 096, then you should use the Jakarta EE specific Jetty class to register it in JNDI: wiki.xml $ java -jar $JETTY_HOME/start.jar 61 Jetty will automatically bind this JTA manager to the webapp’s JNDI namespace at $ java -jar $JETTY_HOME/start.jar 123. Usually, the name you provide for the $ java -jar $JETTY_HOME/start.jar 094 is the same name you reference in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191. This ensures that the two are linked together and thus accessible to your webapp. However, if the names cannot be the same, then it is possible to effectively alias one to another using an $ java -jar $JETTY_HOME/start.jar 132. Supposing you have a declaration for a Datasource named $ java -jar $JETTY_HOME/start.jar 133 in a Jetty context XML file, but your web.xml wants to link to a $ java -jar $JETTY_HOME/start.jar 134 named $ java -jar $JETTY_HOME/start.jar 135, and you cannot edit the web.xml. You can create a $ java -jar $JETTY_HOME/start.jar --add-module=demos 194 file with an $ java -jar $JETTY_HOME/start.jar 137 that ties together the names $ java -jar $JETTY_HOME/start.jar 133 and $ java -jar $JETTY_HOME/start.jar 135: The context XML file declares $ java -jar $JETTY_HOME/start.jar 133: wiki.xml $ java -jar $JETTY_HOME/start.jar 62 The $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 refers to it as $ java -jar $JETTY_HOME/start.jar 135: wiki.xml $ java -jar $JETTY_HOME/start.jar 63 Create a $ java -jar $JETTY_HOME/start.jar --add-module=demos 194 file with a $ java -jar $JETTY_HOME/start.jar 132 to link these names together: wiki.xml $ java -jar $JETTY_HOME/start.jar 64 1 The name as referenced in the $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 file. 2 The name as referenced in the context XML file. You can define naming resources in three places: Server XML file Naming resources defined in a server XML file are at the JVM, 90 or environment level. Note that the classes for the resource must be visible at the point in time that the XML executes. For example, environment level resources should be declared in an XML file that is referenced by a custom module that contains an $ java -jar $JETTY_HOME/start.jar 147 clause at the matching environment level to ensure the classpath for that environment is available. Context XML file Entries in a context XML file should be at the level of the webapp to which they apply (it is possible to use a less strict scoping level of Server or JVM, but not recommended). As a context XML file executes before the webapp’s classes are available, the classes for your resource must be external to the webapp and on either the container or environment classpath. WEB-INF/jetty-env.xml Naming resources in a $ java -jar $JETTY_HOME/start.jar --add-module=demos 194 file are to the webapp in which the file resides. The resources defined here may use classes from inside your webapp. Naming resources within Jetty belong to different scopes, in increasing order of restrictiveness: JVM scope: The name is unique across the JVM instance, and is visible to all application code. This scope is represented by a $ java -jar $JETTY_HOME/start.jar --add-module=demos 528 first parameter to the resource declaration. For example: wiki.xml $ java -jar $JETTY_HOME/start.jar 65 1 Empty first arg equates to JVM scope for the object bound to name $ java -jar $JETTY_HOME/start.jar 150. Environment scope: The name is unique within a Jetty environment. It is represented by referencing the name of the Jakarta EE environment as the first parameter to the resource declaration. For example: wiki.xml $ java -jar $JETTY_HOME/start.jar 66 Webapp scope: The name is unique to the $ java -jar $JETTY_HOME/start.jar 151 instance, and is only visible to that application. This scope is represented by referencing the instance as the first parameter to the resource declaration. For example: wiki.xml $ java -jar $JETTY_HOME/start.jar 67 JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework. JAAS can be used for two purposes:
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) 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 , or their own custom LoginModules. Enable the $ java -jar $JETTY_HOME/start.jar 153 module appropriate for your EE platform: $ java -jar $JETTY_HOME/start.jar 68 The configurable items in the resulting $ java -jar $JETTY_HOME/start.jar 154 file are: jetty.jaas.login.conf This is the location of the file that will be referenced by the system property $ java -jar $JETTY_HOME/start.jar 155: 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=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34. The default value is $ java -jar $JETTY_HOME/start.jar 157, which resolves to $ java -jar $JETTY_HOME/start.jar 158. 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 section. The $ java -jar $JETTY_HOME/start.jar 159 in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 will be used to identify the $ java -jar $JETTY_HOME/start.jar 161 declaration that integrates JAAS with Jetty. For example, this $ java -jar $JETTY_HOME/start.jar --add-module=demos 191 contains a realm called $ java -jar $JETTY_HOME/start.jar 163: $ java -jar $JETTY_HOME/start.jar 69 1 The name of the realm, which must be identical to the name of an $ java -jar $JETTY_HOME/start.jar 161 declaration. We now need to declare an $ java -jar $JETTY_HOME/start.jar 161 that references the realm name of $ java -jar $JETTY_HOME/start.jar 163. Here’s an example of a suitable XML snippet: $ java -jar $JETTY_HOME/start.jar 70 1 The name is the same as that declared in the $ java -jar $JETTY_HOME/start.jar 159 in $ java -jar $JETTY_HOME/start.jar --add-module=demos 191. 2 The name that identifies a set of $ java -jar $JETTY_HOME/start.jar 169 configurations that comprise the identified in the $ java -jar $JETTY_HOME/start.jar 170 property of the . The $ java -jar $JETTY_HOME/start.jar 161 can be declared in a couple of different places, pick whichever suits your purposes best:
We now need to setup the contents of the file we specified as the $ java -jar $JETTY_HOME/start.jar 170 property when we . Refer to the syntax rules of this file for a full description. Remembering the example we set up , the contents of the $ java -jar $JETTY_HOME/start.jar 179 file could look as follows: $ java -jar $JETTY_HOME/start.jar 73 1 The name of the configuration exactly as specified in your $ java -jar $JETTY_HOME/start.jar 161 declaration. 2 The first $ java -jar $JETTY_HOME/start.jar 181 declaration, containing the classname of the $ java -jar $JETTY_HOME/start.jar 181 and its configuration properties. 3 A second $ java -jar $JETTY_HOME/start.jar 181 declaration. You can provide as many $ java -jar $JETTY_HOME/start.jar 181 alternatives as you like, with a minimum of one. Refer to the JAAS documentation for more information on the standard configuration properties, and how JAAS interprets this file.
The $ java -jar $JETTY_HOME/start.jar 185 stores user passwords and roles in a database accessed via JDBC calls. You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the names of the table and columns storing the roles. $ java -jar $JETTY_HOME/start.jar 74 1 The name of the configuration. 2 The name of the $ java -jar $JETTY_HOME/start.jar 181 class. 3 A standard JAAS flag making successful authentication via this $ java -jar $JETTY_HOME/start.jar 181 mandatory. 4 The JDBC url used to connect to the database. 5 The name of the JDBC user to use for the connection. 6 The name of the JDBC Driver class. 7 The name of the table holding the user authenication information. 8 The name of the column holding the user name. 9 The name of the column holding the user credential. 10 The name of the table holding the user authorization information. 11 The name of the column holding the user name. 12 The name of the column holding the user role. The properties 7-12 are used to format the following queries: $ java -jar $JETTY_HOME/start.jar 75 Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication. Note that this information is only cached for the length of the authenticated session. When the user logs out or the session expires, the information is flushed from memory. Note that passwords can be stored in the database in plain text or encoded formats — see the note on "Passwords/Credentials" above. Similar to the $ java -jar $JETTY_HOME/start.jar 185, but using a $ java -jar $JETTY_HOME/start.jar --list-modules=* 20 to connect to the database instead of a JDBC driver. The $ java -jar $JETTY_HOME/start.jar --list-modules=* 20 is obtained at runtime by performing a JNDI lookup on $ java -jar $JETTY_HOME/start.jar 195. A sample login module configuration for this $ java -jar $JETTY_HOME/start.jar 181: $ java -jar $JETTY_HOME/start.jar 76 1 The name of the configuration. 2 The name of the $ java -jar $JETTY_HOME/start.jar 181 class. 3 A standard JAAS flag making successful authentication via this $ java -jar $JETTY_HOME/start.jar 181 mandatory. 4 The JNDI name, relative to $ java -jar $JETTY_HOME/start.jar 199 to lookup to obtain the $ java -jar $JETTY_HOME/start.jar --list-modules=* 20. 5 The name of the table holding the user authenication information. 6 The name of the column holding the user name. 7 The name of the column holding the user credential. 8 The name of the table holding the user authorization information. 9 The name of the column holding the user name. 10 The name of the column holding the user role. With this login module implementation, the authentication and role information is read from a property file. $ java -jar $JETTY_HOME/start.jar 77 1 The name of the configuration. 2 The name of the $ java -jar $JETTY_HOME/start.jar 181 class. 3 A standard JAAS flag making successful authentication via this $ java -jar $JETTY_HOME/start.jar 181 mandatory. 4 The location of a properties file containing the authentication and authorization information. The property file must be of the format: $ java -jar $JETTY_HOME/start.jar 78 Here’s an example: $ java -jar $JETTY_HOME/start.jar 79 The contents of the file are fully read in and cached in memory the first time a user requests authentication. The $ java -jar $JETTY_HOME/start.jar 203 uses LDAP to access authentication and authorization information stored in a directory. The LDAP connection information and structure of the authentication/authorization data can be configured. Here’s an example: $ java -jar $JETTY_HOME/start.jar 80 1 The name of the configuration. 2 The name of the $ java -jar $JETTY_HOME/start.jar 181 class. 3 A standard JAAS flag making successful authentication via this $ java -jar $JETTY_HOME/start.jar 181 mandatory. 4 The name of the context factory to use for the LDAP connection. 5 The hostname for the LDAP connection. Optional. 6 The port for the LDAP connection. Optional. 7 The caller security Principal. Optional. 8 The caller security credential. Optional. 9 The security level for the LDAP connection environment. Optional. 10 If true, use $ java -jar $JETTY_HOME/start.jar 206 instead of $ java -jar $JETTY_HOME/start.jar 207 for the connection url. 11 The distinguished name of the directory to search for user information. 12 The name of the attribute for the user roles. 13 The name of the attribute for the user id. 14 The name of the attribute for the user password. 15 The $ java -jar $JETTY_HOME/start.jar 208 for users. 16 The distinguished name of the directory to search for role information. 17 The name of the attribute for roles. 18 The name of the attribute storing the user for the roles $ java -jar $JETTY_HOME/start.jar 208. 19 The name of the $ java -jar $JETTY_HOME/start.jar 208 for roles. 20 If true, the authentication proceeds on the basis of a successful LDAP binding using the username and credential provided by the user. If false, then authentication proceeds based on username and password information retrieved from LDAP. 21 If true, failed login attempts are logged on the server. Enabling this module allows Jetty to utilize authentication modules that implement the Jakarta Authentication (JASPI) specification. JASPI provides an SPI (Service Provider Interface) for pluggable, portable, and standardized authentication modules. Compatible modules are portable between servers that support the JASPI specification. This module provides a bridge from Jakarta Authentication to the Jetty Security framework. Only modules conforming to the "Servlet Container Profile" with the ServerAuthModule interface within the JakartaAuthentication are supported. These modules must be configured before start-up. Operations for runtime registering or de-registering authentication modules are not supported. Enable the $ java -jar $JETTY_HOME/start.jar 211 module: $ java -jar $JETTY_HOME/start.jar 81 Activate either the $ java -jar $JETTY_HOME/start.jar 213 or $ java -jar $JETTY_HOME/start.jar 214 module, whichever matches your EE platform version. $ java -jar $JETTY_HOME/start.jar 82 You can then register a $ java -jar $JETTY_HOME/start.jar 215 onto the static $ java -jar $JETTY_HOME/start.jar 216 obtained with $ java -jar $JETTY_HOME/start.jar 217. This registration can be done in the XML configuration file which will be copied to $ java -jar $JETTY_HOME/start.jar 218 when the module is enabled. The $ java -jar $JETTY_HOME/start.jar 219 and $ java -jar $JETTY_HOME/start.jar 220 modules illustrate setting up HTTP Basic Authentication using the EE9 and EE 10 Jakarta Authentication modules that come packaged with Jetty. The following example uses Jetty’s EE 10 implementation of $ java -jar $JETTY_HOME/start.jar 215 to register a $ java -jar $JETTY_HOME/start.jar 222 directly. $ java -jar $JETTY_HOME/start.jar 83 Other custom or 3rd party modules that are compatible with the $ java -jar $JETTY_HOME/start.jar 222 interface in JASPI can be registered in the same way. To integrate with Jetty authentication mechanisms you must add a $ java -jar $JETTY_HOME/start.jar 224 to your context. The $ java -jar $JETTY_HOME/start.jar 224 provides a way for you to obtain a $ java -jar $JETTY_HOME/start.jar 226 from a username and credentials. JASPI can interact with this Jetty $ java -jar $JETTY_HOME/start.jar 224 by using the $ java -jar $JETTY_HOME/start.jar 228. The $ java -jar $JETTY_HOME/start.jar 229 and $ java -jar $JETTY_HOME/start.jar 230 do not require use of a Jetty $ java -jar $JETTY_HOME/start.jar 224. The principal from the $ java -jar $JETTY_HOME/start.jar 229 will be used directly with the $ java -jar $JETTY_HOME/start.jar 233 to produce a $ java -jar $JETTY_HOME/start.jar 226. Jetty provides an implementation of the $ java -jar $JETTY_HOME/start.jar 216 interface which is used to register $ java -jar $JETTY_HOME/start.jar 236. This can be replaced by a custom implementation by adding a custom module which provides $ java -jar $JETTY_HOME/start.jar 237. This custom module must reference an XML file which sets a new instance of the $ java -jar $JETTY_HOME/start.jar 216 with the static method $ java -jar $JETTY_HOME/start.jar 239. For an example of this see the $ java -jar $JETTY_HOME/start.jar 240 module, which provides the default implementation used by Jetty. $ java -jar $JETTY_HOME/start.jar 84 Monitoring and management of a Jetty server is important because it allows you to monitor the status of the server ("Is the server processing requests?") and to manage — i.e. read and possibly change — its configuration. The ability to read and change the Jetty configuration is very important for troubleshooting Jetty — please refer to the for more information. Jetty relies on the Java Management Extensions (JMX) APIs included in OpenJDK to provide monitoring and management. The JMX APIs support a JVM-local $ java -jar $JETTY_HOME/start.jar 241, accessible only from within the JVM itself (or by tools that can attach to a running JVM), and a way to expose the $ java -jar $JETTY_HOME/start.jar 241 to remote clients via Java’s RMI (Remote Method Invocation). As with many other Jetty features, local JMX support is enabled with the : $ java -jar $JETTY_HOME/start.jar 85 With the $ java -jar $JETTY_HOME/start.jar 14 Jetty module enabled, Jetty components will be exported as JMX MBeans to the JVM platform $ java -jar $JETTY_HOME/start.jar 241, so that they can be accessed by JMX compliant tools. Each Jetty component will export to its correspondent MBean relevant configuration parameters, so that a JMX tool can read and possibly change the component configuration through the MBean. Note that the Jetty MBeans are registered into the platform $ java -jar $JETTY_HOME/start.jar 241, but are not available to remote clients: they are local to the JVM. This configuration is useful when you develop and test your Jetty server locally. JMX compliant tools such as Java Mission Control (JMC) can be started locally on your machine and can attach to other JVMs running on your machine, showing you the registered MBeans among which you will find the Jetty MBeans. Enabling only the local JMX support is the most secure option for monitoring and management, but only users that have local access to the JVM will be able to browse the MBeans. If you need to access the MBeans from a remote machine, read . There are two ways to configure a Jetty server so that it is possible to access the JVM platform MBeans from remote clients:
Both ways use Java’s Remote Method Invocation (RMI) to communicate between the client and the server. Refresher: How RMI Works A server application that wants to make an object available to remote clients must export the object. Exporting an object creates an RMI stub that contains the host/port of the RMI server that accepts incoming invocations from clients and forwards them to the object. During the creation of the RMI stub, the host stored in the RMI stub is retrieved from the local name resolution system (for example, in Linux, from $ java -jar $JETTY_HOME/start.jar 21). The RMI stub is then sent, along with a name that uniquely identifies the object, to the RMI registry. The RMI registry is a service that maps names to RMI stubs; it may be external to both clients and server, although often it is part of the server JVM. When a client application wants to connect to the server object using RMI, it first connects to the RMI registry to download the RMI stub for the RMI server; recall that the RMI stub contains the host/port to connect to the RMI server. Then, the client uses the RMI stub to connect to the RMI server, typically to a host/port that may be different from the RMI registry host/port (in particular, by default the RMI server port will be different from the RMI registry port). Remote access to the platform MBeans, and therefore the Jetty MBeans, is enabled by the $ java -jar $JETTY_HOME/start.jar 15 Jetty module: $ java -jar $JETTY_HOME/start.jar 86 This command creates the $ java -jar $JETTY_HOME/start.jar 251 file: $ java -jar $JETTY_HOME/start.jar 87 Enabling the $ java -jar $JETTY_HOME/start.jar 15 module transitively enables the as well. The configuration for the RMI registry and the RMI server is specified by a $ java -jar $JETTY_HOME/start.jar 254. The string format of an RMI $ java -jar $JETTY_HOME/start.jar 254 is the following: $ java -jar $JETTY_HOME/start.jar 88 Below you can find examples of $ java -jar $JETTY_HOME/start.jar 254s: $ java -jar $JETTY_HOME/start.jar 89 The default $ java -jar $JETTY_HOME/start.jar 254 configured by the $ java -jar $JETTY_HOME/start.jar 15 module is the following: $ java -jar $JETTY_HOME/start.jar 90 With the default configuration, only clients that are local to the server machine can connect to the RMI registry and RMI server - this is done for security reasons. However, even with this local-only configuration, it would still be possible to access the MBeans from remote using an SSH tunnel, as explained in . By specifying an appropriate $ java -jar $JETTY_HOME/start.jar 254, you can fine tune the network address the RMI registry and the RMI server bind to, and the ports that the RMI registry and the RMI server listen to. The RMI server and RMI registry hosts and ports can be the same (as in the default configuration) because RMI is able to multiplex traffic arriving to one port to multiple RMI objects. If you need to allow JMX remote access through a firewall, you must open both the RMI registry and the RMI server ports. The default configuration simplifies the firewall configuration because you only need to open port $ java -jar $JETTY_HOME/start.jar 260. When Jetty is started with the $ java -jar $JETTY_HOME/start.jar 15 module enabled, the RMI stub of the Jetty component that provides access to the MBeans is exported to the RMI registry. The RMI stub contains the host/port to connect to the RMI server, but the host is typically the machine host name, not the host specified in the $ java -jar $JETTY_HOME/start.jar 254 (the latter is only used to specify the network address the RMI server binds to). To control the host stored in the RMI stub you need to set the system property $ java -jar $JETTY_HOME/start.jar 17 with the desired value in the module configuration file, $ java -jar $JETTY_HOME/start.jar 251. If your client cannot connect to the server, the most common cause is a mismatch between the RMI server host of the $ java -jar $JETTY_HOME/start.jar 254 and the RMI server host of the RMI stub. You can customize the RMI server host/port, the RMI registry host/port and the system property $ java -jar $JETTY_HOME/start.jar 17 by editing the $ java -jar $JETTY_HOME/start.jar 251 configuration file. Further information about the $ java -jar $JETTY_HOME/start.jar 15 module configuration can be found . You can access JMX MBeans on a remote machine when the RMI ports are not open, for example because of firewall policies, but you have SSH access to the machine, using local port forwarding via an SSH tunnel. In this case you want to configure the $ java -jar $JETTY_HOME/start.jar 254 that binds the RMI server and the RMI registry to the loopback interface only and to the same port: $ java -jar $JETTY_HOME/start.jar 90 You must set the system property $ java -jar $JETTY_HOME/start.jar 270 so that the RMI stub contains $ java -jar $JETTY_HOME/start.jar 25 as the host name to connect to. This is, incidentally, the default configuration of the $ java -jar $JETTY_HOME/start.jar 15 module. Then you set up the local port forwarding with the SSH tunnel: $ java -jar $JETTY_HOME/start.jar 92 Thanks to the local port forwarding of the SSH tunnel, when the client connects to $ java -jar $JETTY_HOME/start.jar 273 on your local computer, the traffic will be forwarded to $ java -jar $JETTY_HOME/start.jar 274 and when there, the SSH daemon will forward the traffic to $ java -jar $JETTY_HOME/start.jar 273 on $ java -jar $JETTY_HOME/start.jar 274, which is exactly where the RMI server and the RMI registry listens to. The client first contacts the RMI registry, so it connects to $ java -jar $JETTY_HOME/start.jar 273 on your local computer; the traffic is forwarded to $ java -jar $JETTY_HOME/start.jar 274 through the SSH tunnel, connects to the RMI registry and the RMI stub is downloaded to the client. Then the client uses the RMI stub to connect to the RMI server. The RMI stub contains $ java -jar $JETTY_HOME/start.jar 25 as the RMI server host because that is what you have configured with the system property $ java -jar $JETTY_HOME/start.jar 17. The client will connect again to $ java -jar $JETTY_HOME/start.jar 273 on your local computer, this time to contact the RMI server; the traffic is forwarded to $ java -jar $JETTY_HOME/start.jar 274 through the SSH tunnel, arrives to $ java -jar $JETTY_HOME/start.jar 274 and connects to the RMI server. The standard $ java -jar $JETTY_HOME/start.jar 284 class, used by the $ java -jar $JETTY_HOME/start.jar 15 module to provide remote JMX access to Jetty MBeans, provides several options to authenticate and authorize users. For a complete guide to controlling authentication and authorization in JMX, see the official JMX documentation. The simplest way to control JMX authentication and authorization is to specify two files: one contains username and password pairs, and the other contains username and permission pairs. This is achieved by enabling the $ java -jar $JETTY_HOME/start.jar 286 Jetty module: $ java -jar $JETTY_HOME/start.jar 93 Enabling the $ java -jar $JETTY_HOME/start.jar 286 Jetty module creates the following files: $ java -jar $JETTY_HOME/start.jar 94 Then you edit the $ java -jar $JETTY_HOME/start.jar 288 file, adding the username/password pairs that you need: $JETTY_BASE/etc/jmxremote.password $ java -jar $JETTY_HOME/start.jar 95 You must also edit the $ java -jar $JETTY_HOME/start.jar 289 file to give permissions to your users: $JETTY_BASE/etc/jmxremote.access $ java -jar $JETTY_HOME/start.jar 96 The above files define user $ java -jar $JETTY_HOME/start.jar 290 with password $ java -jar $JETTY_HOME/start.jar 291 to have $ java -jar $JETTY_HOME/start.jar 292 access, and user $ java -jar $JETTY_HOME/start.jar 293 with password $ java -jar $JETTY_HOME/start.jar 294 to have $ java -jar $JETTY_HOME/start.jar 295 access. The JMX communication via RMI happens by default in clear-text, but it is possible to secure the JMX communication via RMI with TLS. If you want to reuse the configuration that you are using for the , you can just enable the $ java -jar $JETTY_HOME/start.jar 297 Jetty module: $ java -jar $JETTY_HOME/start.jar 97 The $ java -jar $JETTY_HOME/start.jar 298 Jetty module depends on the $ java -jar $JETTY_HOME/start.jar --add-modules=http 90 Jetty module that in turn requires a KeyStore (read for more information). The KeyStore must contain a valid certificate signed by a Certification Authority. Having certificates signed by a Certification Authority simplifies by a lot the configuration needed to get the RMI communication over TLS working properly. The RMI mechanic is the usual one: the RMI client (typically a monitoring console) will connect first to the RMI registry (using TLS), download the RMI stub that contains the address and port of the RMI server to connect to, then connect to the RMI server (using TLS). This also mean that if the RMI registry and the RMI server are on different hosts, the RMI client must have available the cryptographic material to validate the certificates from both hosts. This is where having certificates signed by a Certification Authority simplifies the configuration: if they are signed by a well known Certification Authority, the client does not need any extra configuration — everything will be handled by the Java runtime. If the certificates are not signed by a Certification Authority (for example the certificate is self-signed), then you need to specify the TLS system properties that allow RMI (especially when acting as an RMI client) to retrieve the cryptographic material necessary to establish the TLS connection. When the RMI server exports the $ java -jar $JETTY_HOME/start.jar 300 it acts as an RMI client towards the RMI registry, and as such you must specify the TLS system properties as detailed below. You must edit the $ java -jar $JETTY_HOME/start.jar 301 file and add the TrustStore path and password: $JETTY_BASE/start.d/jmx-remote-ssl.ini $ java -jar $JETTY_HOME/start.jar 98 The TrustStore must contain the certificate you want to trust. If you are using self-signed certificates, the KeyStore already contains the self-signed certificate and therefore the KeyStore can be used as a TrustStore, and the system properties above can refer to the KeyStore path and password. JMX compliant tools that offer a graphical user interface also must be started specifying the TrustStore path and password. $ java -jar $JETTY_HOME/start.jar 99 There are many cases where you might need to provide credentials such as usernames and passwords to authenticate your access to certain services, for example KeyStore and TrustStore passwords, JDBC credentials, Basic or Digest authentication credentials, etc. Passwords are typically stored in clear-text in configuration files, because a program such as Jetty reading the configuration file must be able to retrieve the original password to authenticate with the service. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 00 1 Hit Enter to specify a blank user. 2 Enter the password you want to obfuscate. 3 The obfuscated password. 4 The MD5 checksum of the password. The $ java -jar $JETTY_HOME/start.jar 302 tool produced an obfuscated string for the password $ java -jar $JETTY_HOME/start.jar 303, namely $ java -jar $JETTY_HOME/start.jar 304 (the prefix $ java -jar $JETTY_HOME/start.jar 305 must be retained). The obfuscated string can be de-obfuscated to obtain the original password. Now you can use the obfuscated password in Jetty configuration files, for example to specify the KeyStore password in $ java -jar $JETTY_HOME/start.jar --add-module=demos 410 when configuring secure connectors, as explained . For example: ssl.ini $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 01 Remember that password obfuscation only protects from casual view — it can be de-obfuscated to obtain the original password. You can also use the obfuscated password in your Java source code. You can also use obfuscated passwords in Jetty XML files where a clear-text password is usually required. Here is an example, setting an obfuscated password for a JDBC $ java -jar $JETTY_HOME/start.jar --list-modules=* 15: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 02 1 Note the usage of $ java -jar $JETTY_HOME/start.jar 308 to avoid storing the clear-text password in the XML file. To troubleshoot Jetty when used as a production server, there are two main tools: the Jetty Server Dump and enabling DEBUG level logging. Jetty is based on components organized as a tree, with the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 instance at the root of the tree. As explained in the , these components can be exported as JMX MBeans and therefore be accessible from JMX Consoles such as Java Missions Control (JMC). Being able to take a snapshot of the state of Jetty while it is running is the most useful information that can be attached when reporting an issue. Such state includes:
The prerequisite for troubleshooting is to enable JMX, so that Jetty — possibly a production server — can be accessed from a remote location to obtain the information exported via JMX, and possibly be able to reconfigure Jetty to solve the issue. Make sure you read about how to secure the access to Jetty when using . The Jetty Server Dump is obtained by invoking, via JMX, the $ java -jar $JETTY_HOME/start.jar 70 operation, as shown below. Find the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 MBean in the MBean Tree, under $ java -jar $JETTY_HOME/start.jar 313. Then click on the "Operations" tab, select the $ java -jar $JETTY_HOME/start.jar 314 operation, and then click the $ java -jar $JETTY_HOME/start.jar 315 button. In the bottom panel you will see the result of the invocation, that you can copy into a text editor and save to your file system. Taking a Jetty Server Dump is a relatively expensive operation, as it dumps the state of all connections (which can be thousands), and the state of all threads. The result of the invocation may produce a large string, possibly few MiB, that may impact the server memory usage. Furthermore, dumping the state of the I/O Jetty components takes a little CPU time off the handling of the actual I/O, possibly slowing it down temporarily. While the slow-down caused by taking the Jetty Server Dump may be noticeable on highly loaded systems, it is typically a very small price to pay to obtain the information about the Jetty state that may be critical to the resolution of an issue. The format of the Jetty Server Dump output is subject to change at any time, as Jetty developers modify the Jetty code and decide to include more state, or remove state that is no longer relevant. The Jetty Server Dump is organized in a tree whose structure is similar to the runtime Jetty component tree. At the end of the dump output there is a legend that explains the type of tree node: whether it is a node that represent a managed component, or an array node (or a map node) that represent some component state, etc. The $ java -jar $JETTY_HOME/start.jar 70 operation may also be invoked just after the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 starts (to log the state of the freshly started server), and just before the $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 stops (which may be useful to log the state of server that is not working properly). You can temporarily enable the Jetty Server Dump at start time by overriding the $ java -jar $JETTY_HOME/start.jar 69 property on the command line: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 03 To make this change persistent across server restarts, see the configuration for more information about how to configure the server to dump at start/stop time. By default, the dump of the thread pool will only dump the topmost stack frame of each thread. It is possible to configure the thread pool to dump the whole stack trace for each thread; while this may be a little more expensive, it provides complete information about the state of each thread, which may be important to diagnose the issue. See the configuration for more information about how to configure the thread pool to dump detailed thread information. Detailed thread pool information can also be turned on/off on-the-fly via JMX, by finding the $ java -jar $JETTY_HOME/start.jar 322 MBean under $ java -jar $JETTY_HOME/start.jar 323, then selecting the $ java -jar $JETTY_HOME/start.jar 324 attribute and setting it to $ java -jar $JETTY_HOME/start.jar --add-module=demos 298. You can now perform the $ java -jar $JETTY_HOME/start.jar 70 operation as explained above, and then set $ java -jar $JETTY_HOME/start.jar 324 back to $ java -jar $JETTY_HOME/start.jar --add-module=demos 050. Below you can find a simple example of a Jetty Server Dump, with annotations for the principal components: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 04 1 The $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 instance at the root of the tree 2 The thread pool component 3 The root of the 13 structure 4 The connector listening on port $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 66 for the HTTP/1.1 protocol 5 A selector component that manages connections 6 The connections currently managed by the selector component 7 The server $ java -jar $JETTY_HOME/start.jar 332 and its classpath 8 The legend for the dump nodes Enabling DEBUG level logging for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 277 logger name provides the maximum amount of information to troubleshoot Jetty issues. Refer to the for more information about how to configure logging in Jetty. Enabling DEBUG level logging for $ java -jar $JETTY_HOME/start.jar --add-module=demos 277 is very, very expensive. Your server could be slowed down to almost a halt, especially if it is under heavy load. Furthermore, the log file could quickly fill up the entire filesystem (unless configured to roll over), so you want to be really careful using DEBUG logging. For production servers, consider using the first, and enable DEBUG logging only as a last resort. However, sometimes issues are such that only DEBUG logging can really tell what’s going on in the system, and enabling DEBUG logging is your best chance to figure the issue out. Below you can find few suggestions that can help you reduce the impact when you have to enable DEBUG logging. If Jetty instances are behind a load balancer, you may configure the load balancer to send less load to a particular Jetty instance, and enable DEBUG logging in that instance only. In certain cases the issue can be reproduced reliably, but only in the production environment. You can use JMX to temporarily enable DEBUG logging, reproduce the issue, and then disable DEBUG logging. Alternatively, if you cannot reliably reproduce the issue, but you know it is happening, you can temporarily enable DEBUG logging for a small period of time, let’s say 10-60 seconds, and then disable DEBUG logging. Changing the log level at runtime is a feature of the logging implementation that you are using. The Jetty SLF4J implementation, used by default, exposes via JMX method $ java -jar $JETTY_HOME/start.jar 335 that you can invoke via a JMX console to change the level for the specified logger name. The method returns $ java -jar $JETTY_HOME/start.jar --add-module=demos 298 if the logger level was successfully changed. For example, you can pass the string $ java -jar $JETTY_HOME/start.jar --add-module=demos 277 as the first parameter, and the string $ java -jar $JETTY_HOME/start.jar --add-module=demos 279 (upper case) as the second parameter. You can then use the string $ java -jar $JETTY_HOME/start.jar --add-module=demos 280 or $ java -jar $JETTY_HOME/start.jar --add-module=demos 281 (upper case) to restore the logging level to its previous value. Enabling DEBUG logging for the $ java -jar $JETTY_HOME/start.jar --add-module=demos 277 logger name implies that all children logger names, recursively, inherit the DEBUG level. Processing a single HTTP request involves many Jetty components: the I/O subsystem (under $ java -jar $JETTY_HOME/start.jar 342), the thread pool (under $ java -jar $JETTY_HOME/start.jar 343), the HTTP/1.1 parsing (under $ java -jar $JETTY_HOME/start.jar 344), etc. If you can cut the amount of DEBUG logging to just what you need to troubleshoot the issue, the impact of enabling DEBUG logging will be much less than enabling it for all Jetty components. For example, if you need to troubleshoot a client that sends bad HTTP/1.1 requests, it may be enough to enable only the $ java -jar $JETTY_HOME/start.jar 344 logger name, therefore saving the large amount of DEBUG logging produced by the I/O subsystem and by the thread pool. In another case, you may need to troubleshoot only HTTP/2 requests, and therefore enabling only the $ java -jar $JETTY_HOME/start.jar 346 logger name could be enough. The Java Virtual Machines allows remote processes on different hosts to connect for debugging purposes, by using specific command line options. While it is possible to enable remote debugging on a Jetty server, it is typically not recommended for security and performance reasons. Only enable remote debugging on a Jetty server as a last resort to troubleshoot issues that could not be troubleshot otherwise. You can easily create a custom Jetty module (see ) with the following content: remote-debug.mod $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 05 The 20 directive (documented ) is necessary to pass the $ java -jar $JETTY_HOME/start.jar 348 JVM option to the forked JVM that runs Jetty, so that you can attach with a debugger. The $ java -jar $JETTY_HOME/start.jar --add-module=demos 785 parameter of the $ java -jar $JETTY_HOME/start.jar 348 command line option specifies the network address and port the Jetty JVM listens on for remote debugging. You can now enable the $ java -jar $JETTY_HOME/start.jar 351 Jetty module with the following command issued from the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 06 The command above minimally adds a Jetty server without connectors (via the $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 64 Jetty module) and the $ java -jar $JETTY_HOME/start.jar 351 Jetty module, and produces the following $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 34 directory structure: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 07 You can easily disable the $ java -jar $JETTY_HOME/start.jar 351 Jetty module as explained in . Alternatively, you can enable the $ java -jar $JETTY_HOME/start.jar 351 module on the command line, as explained in . Starting the Jetty server with the $ java -jar $JETTY_HOME/start.jar 351 module enabled yields: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 08 Note how the JVM is listening on port $ java -jar $JETTY_HOME/start.jar 359 to allow remote debuggers to connect. If you want to avoid to fork a second JVM to pass the $ java -jar $JETTY_HOME/start.jar 348 JVM option, please read . The Jetty XML format is a straightforward mapping of XML elements to Java APIs so that any object can be instantiated and getters, setters, and methods can be called. The Jetty XML format is very similar to that of frameworks like Spring or Plexus, although it predates all of them and it’s typically more powerful as it can invoke any Java API. The Jetty XML format is used in to create the Jetty server components, as well as in to configure web applications, but it can be used to call any Java API. The Jetty XML syntax defines XML element that allow you to call any Java API and that allow you to interact in a simpler way with the and the . The Jetty XML elements define attributes such as $ java -jar $JETTY_HOME/start.jar --list-modules=* 92, $ java -jar $JETTY_HOME/start.jar 362, $ java -jar $JETTY_HOME/start.jar 363, etc. that may be replaced by correspondent elements, so that these XML documents are equivalent: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 09 $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 10 The version using attributes is typically shorter and nicer to read, but sometimes the attribute value cannot be a literal string (for example, it could be the value of a system property) and that’s where elements gives you the required flexibility. Element $ java -jar $JETTY_HOME/start.jar 365 must be the root element of the XML document. The following Jetty XML creates an empty $ java -jar $JETTY_HOME/start.jar 366 and assigns it the id $ java -jar $JETTY_HOME/start.jar 367: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 11 This is equivalent to the following Java code: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 12 If an object with the id $ java -jar $JETTY_HOME/start.jar 367 already exists, then it is not created again but rather just referenced. Within element $ java -jar $JETTY_HOME/start.jar 364, the created object (if any) is in and may be the implicit target of other, nested, elements. Typically the $ java -jar $JETTY_HOME/start.jar 364 element is used to configure a $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 instance or $ java -jar $JETTY_HOME/start.jar 372 subclasses such as $ java -jar $JETTY_HOME/start.jar --add-module=demos 174 that represent web applications. The following example creates a minimal Jetty $ java -jar $JETTY_HOME/start.jar --list-modules=* 42: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 13 Arguments may have a $ java -jar $JETTY_HOME/start.jar --add-module=demos 575 attribute that explicitly performs . Arguments may also have a $ java -jar $JETTY_HOME/start.jar 362 attribute, which is matched with the corresponding Java annotation in the source class, that helps to identify arguments: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 14 Element $ java -jar $JETTY_HOME/start.jar --list-modules=* 90 creates a new object of the type specified by the mandatory $ java -jar $JETTY_HOME/start.jar 363 attribute. A sequence of $ java -jar $JETTY_HOME/start.jar 381 elements, that must be contiguous and before other elements, may be present to specify the constructor arguments. Within element $ java -jar $JETTY_HOME/start.jar --list-modules=* 90 the newly created object is in and may be the implicit target of other, nested, elements. The following example creates an $ java -jar $JETTY_HOME/start.jar 383: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 15 This is equivalent to the following Java code: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 16 Element $ java -jar $JETTY_HOME/start.jar 384 invokes a method specified by the mandatory $ java -jar $JETTY_HOME/start.jar 362 attribute. A sequence of $ java -jar $JETTY_HOME/start.jar 381 elements, that must be contiguous and before other elements, may be present to specify the method arguments. Within element $ java -jar $JETTY_HOME/start.jar 384 the return value, if the return type is not $ java -jar $JETTY_HOME/start.jar 389, is in and may be the implicit target of other, nested, elements. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 17 This is equivalent to the following Java code: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 18 It is possible to call $ java -jar $JETTY_HOME/start.jar 390 methods by specifying the $ java -jar $JETTY_HOME/start.jar 363 attribute: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 19 This is equivalent to the following Java code: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 20 The $ java -jar $JETTY_HOME/start.jar 363 attribute (or $ java -jar $JETTY_HOME/start.jar 393 element) can also be used to specify the Java class or interface to use to lookup the non- $ java -jar $JETTY_HOME/start.jar 390 method name. This is necessary when the object in scope, onto which the $ java -jar $JETTY_HOME/start.jar 384 would be applied, is an instance of a class that is not visible to Jetty classes, or not accessible because it is not $ java -jar $JETTY_HOME/start.jar 396. For example: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 21 In the example above, $ java -jar $JETTY_HOME/start.jar 397 returns an object whose class is a private JDK implementation class. Without an explicit $ java -jar $JETTY_HOME/start.jar 363 attribute (or $ java -jar $JETTY_HOME/start.jar 393 element), it is not possible to invoke the method $ java -jar $JETTY_HOME/start.jar 400 when it is obtained via reflection from the private JDK implementation class, because while the method is $ java -jar $JETTY_HOME/start.jar 396, the private JDK implementation class is not, therefore this exception is thrown: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 22 The solution is to explicitly use the $ java -jar $JETTY_HOME/start.jar 363 attribute (or $ java -jar $JETTY_HOME/start.jar 393 element) of the $ java -jar $JETTY_HOME/start.jar 384 element that is invoking the $ java -jar $JETTY_HOME/start.jar 400 method, specifying a publicly accessible class or interface that the object in scope extends or implements (in the example above $ java -jar $JETTY_HOME/start.jar 406). Element $ java -jar $JETTY_HOME/start.jar 407 retrieves the value of a JavaBean property specified by the mandatory $ java -jar $JETTY_HOME/start.jar 362 attribute. If the JavaBean property is $ java -jar $JETTY_HOME/start.jar 410 (or $ java -jar $JETTY_HOME/start.jar 411), $ java -jar $JETTY_HOME/start.jar 407 first attempts to invoke method $ java -jar $JETTY_HOME/start.jar 413 or method $ java -jar $JETTY_HOME/start.jar 414; failing that, attempts to retrieve the value from field $ java -jar $JETTY_HOME/start.jar 410 (or $ java -jar $JETTY_HOME/start.jar 411). $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 23 The $ java -jar $JETTY_HOME/start.jar 363 attribute (or $ java -jar $JETTY_HOME/start.jar 393 element) allows to perform $ java -jar $JETTY_HOME/start.jar 390 calls, or to lookup the getter method from the specified class, as described in the . Element $ java -jar $JETTY_HOME/start.jar 421 stores the value of a JavaBean property specified by the mandatory $ java -jar $JETTY_HOME/start.jar 362 attribute. If the JavaBean property is $ java -jar $JETTY_HOME/start.jar 410 (or $ java -jar $JETTY_HOME/start.jar 411), $ java -jar $JETTY_HOME/start.jar 421 first attempts to invoke method $ java -jar $JETTY_HOME/start.jar 427 with the value in the as argument; failing that, attempts to store the value in the scope to field $ java -jar $JETTY_HOME/start.jar 410 (or $ java -jar $JETTY_HOME/start.jar 411). $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 24 The $ java -jar $JETTY_HOME/start.jar 363 attribute (or $ java -jar $JETTY_HOME/start.jar 393 element) allows to perform $ java -jar $JETTY_HOME/start.jar 390 calls, or to lookup the setter method from the specified class, as described in the . Element $ java -jar $JETTY_HOME/start.jar 434 allows the creation of a new $ java -jar $JETTY_HOME/start.jar 437 implementation, specified by the $ java -jar $JETTY_HOME/start.jar 363 attribute — by default a $ java -jar $JETTY_HOME/start.jar 439. The map entries are specified with a sequence of $ java -jar $JETTY_HOME/start.jar 435 elements, each with exactly 2 $ java -jar $JETTY_HOME/start.jar 441 elements, for example: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 25 Element $ java -jar $JETTY_HOME/start.jar 442 is a convenience element that puts a key/value pair into objects that implement $ java -jar $JETTY_HOME/start.jar 437. You can only specify the key value via the $ java -jar $JETTY_HOME/start.jar 362 attribute, so the key can only be a literal string (for keys that are not literal strings, use the $ java -jar $JETTY_HOME/start.jar 384 element). $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 26 Element $ java -jar $JETTY_HOME/start.jar 447 creates a new array, whose component type may be specified by the $ java -jar $JETTY_HOME/start.jar --add-module=demos 575 attribute, or by a $ java -jar $JETTY_HOME/start.jar 451 child element. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 27 Element $ java -jar $JETTY_HOME/start.jar 452 allows you to reference an object via the $ java -jar $JETTY_HOME/start.jar 454 attribute`, putting it into so that nested elements can operate on it. You must give a unique $ java -jar $JETTY_HOME/start.jar --list-modules=* 92 attribute to the objects you want to reference. $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 28 Element $ java -jar $JETTY_HOME/start.jar --add-modules=http 00 retrieves the value of the Jetty module property specified by the $ java -jar $JETTY_HOME/start.jar 362 attribute, and it is mostly used when creating or when using . The $ java -jar $JETTY_HOME/start.jar 459 attribute allows you to specify a comma separated list of old, deprecated, property names for backward compatibility. The $ java -jar $JETTY_HOME/start.jar --add-modules=http 06 attribute allows you to specify a default value for the property, if it has not been explicitly defined. For example, you may want to configure the context path of your web application in this way: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 29 The $ java -jar $JETTY_HOME/start.jar 14 value is resolved by looking for the Jetty module property $ java -jar $JETTY_HOME/start.jar 462; if this property is not set, then the default value of $ java -jar $JETTY_HOME/start.jar 463 is used. Element $ java -jar $JETTY_HOME/start.jar 464 retrieves the value of the JVM system property specified by the $ java -jar $JETTY_HOME/start.jar 362 attribute, via $ java -jar $JETTY_HOME/start.jar 467. The $ java -jar $JETTY_HOME/start.jar 459 attribute allows you to specify a comma separated list of old, deprecated, system property names for backward compatibility. The $ java -jar $JETTY_HOME/start.jar --add-modules=http 06 attribute allows you to specify a default value for the system property value, if it has not been explicitly defined. The following example creates a minimal Jetty $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 that listens on a port specified by the $ java -jar $JETTY_HOME/start.jar 471 system property: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 30 Element $ java -jar $JETTY_HOME/start.jar 472 retrieves the value of the environment variable specified by the $ java -jar $JETTY_HOME/start.jar 362 attribute, via $ java -jar $JETTY_HOME/start.jar 475. The $ java -jar $JETTY_HOME/start.jar 459 attribute allows you to specify a comma separated list of old, deprecated, environment variable names for backward compatibility. The $ java -jar $JETTY_HOME/start.jar --add-modules=http 06 attribute allows you to specify a default value for the environment variable value, if it has not been explicitly defined. The following example creates a minimal Jetty $ java -jar $JETTY_HOME/start.jar --list-modules=* 42 that listens on a port specified by the $ java -jar $JETTY_HOME/start.jar 479 environment variable: $ JETTY_BASE=/path/to/jetty.base $ mkdir $JETTY_BASE $ cd $JETTY_BASE 31 Elements that have the $ java -jar $JETTY_HOME/start.jar --add-module=demos 575 attribute explicitly perform the type coercion of the string value present in the XML document to the Java type specified by the $ java -jar $JETTY_HOME/start.jar --add-module=demos 575 attribute. Supported types are the following:
Elements that create new objects or that return a value create a scope. Within these elements there may be nested elements that will operate on that scope, i.e. on the new object or returned value. |
