Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improvements to the Jetty documentation. 

Documented the Jetty modules.

Improved the TOC javascript, as it was not working if the link had sub-elements.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2021-02-17 15:58:29 +01:00
parent 4cfe7b9e3b
commit 322d1018a7
38 changed files with 546 additions and 1674 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/configuring/chapter.adoc
View File

@ -14,5 +14,4 @@
[[quick-start-configure]]
== An Introduction to Jetty Configuration
include::how-to-configure.adoc[]
include::what-to-configure.adoc[]

327
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/configuring/how-to-configure.adoc
View File

@ -1,327 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-config-how]]
=== How to Configure Jetty
To understand Jetty configuration, you need to understand the "How" and the "What".
This section covers how to configure Jetty in terms of what mechanisms exist to perform configuration.
The link:#quickstart-config-what[next section] gives an overview of the action components and fields that you can configure with these mechanisms.
==== Jetty POJO Configuration
The core components of Jetty are Plain Old Java Objects (http://en.wikipedia.org/wiki/Plain_Old_Java_Object[POJOs])
The process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs.
This can be achieved by:
* Writing Java code to directly instantiate and assemble Jetty objects.
This is referred to as xref:embedding-jetty[].
* Using Jetty XML configuration, which is an http://en.wikipedia.org/wiki/Inversion_of_Control[Inversion of Control (IoC)] framework, to instantiate and assemble Jetty objects as XML objects.
The `etc/jetty.xml` file is the main Jetty XML configuration file, but there are many other `etc/jetty-__feature__.xml` files included in the Jetty distribution.
* Using a third party http://en.wikipedia.org/wiki/Inversion_of_Control[IoC] framework like http://en.wikipedia.org/wiki/Spring_Framework[Spring], to instantiate and assemble Jetty objects as Spring beans.
Because the main Jetty configuration is done by IoC, the link:{JDURL}/[Jetty API documentation] is the ultimate configuration reference.
==== Jetty Start Configuration Files
The Jetty distribution uses the following configuration files to instantiate, inject and start server via the `start.jar` mechanism.
`ini` files::
The Jetty Start mechanism uses the command line, the `$JETTY_BASE/start.ini` and/or `$JETTY_BASE/start.d/*.ini` files to create an effective command line of arguments.
Arguments may be:
* Module activations in the form `--module=name`
* Properties in the form of `name=value`, used to parameterize Jetty IoC XML
* XML files in Jetty IoC (or Spring) XML format
* A standard http://en.wikipedia.org/wiki/Java_properties[Java property file] containing additional start properties
* Other start.jar options (see `java -jar start.jar --help`)
* Some JVM options in combination with `--exec`, such as `-Xbootclasspath`.
____
[NOTE]
--
It is the `ini` files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).
--
____
`mod` files::
The `$JETTY_HOME/modules/*.mod` files contain the definition of modules that can be activated by `--module=name`.
Each `mod` file defines:
* Module dependencies for ordering and activation
* The libraries needed by the module to be added to the classpath
* The XML files needed by the module to be added to the effective command line
* Files needed by the activated module
* A template `ini` file to be used when activating the `--add-to-start=name` option
+
Typically module files are rarely edited and only then for significant structural changes.
The `*.mod` files are normally located in `$JETTY_HOME/modules/`, but extra or edited modules may be added to `$JETTY_BASE/module`.
If module changes are required, it is best practice to copy the particular `*.mod` file from `$JETTY_HOME/modules/` to `$JETTY_BASE/modules/` before being modified.
XML files::
XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format are listed either on the command line, in `ini` files, or are added to the effective command line by a module definition.
The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts.
Because Jetty IoC XML files use properties, most common configuration tasks can be accomplished without editing these XML files and can instead be achieved by editing the property in the corresponding `ini` files.
XML files are normally located in `$JETTY_HOME/etc/`, but extra or edited XML files may be added to `$JETTY_BASE/etc/`.
*Note* If XML configuration changes are required, it is best practice to copy the XML file from `$JETTY_HOME/etc/` to `$JETTY_BASE/etc/` before being modified.
Below is an illustration of how the various Jetty configuration files (`ini`, `mod` and XML) are related:
image:Jetty_Configuration_File_Relationships.png[image,width=693]
==== A Closer Look
To put it simply: XML files are responsible for instantiating the Jetty POJOs that make up the server.
They define properties which users can modify to meet the needs of their server.
These XML files are broken up by type in the distribution so they can be consumed as a user/server needs them.
For example, a server may need HTTP and HTTPS functionality, but opt out of using HTTP/2 and Websocket.
Module files allow users to enable and remove functionality quickly and easily from their server implementation.
They include a template of the different properties included in the associated XML file, as well as a pointer to the XML or JAR file(s) they are referencing.
When a module is activated these properties are added to a related `ini` file where users can configure them to meet their needs.
We will discuss modules in further detail in an upcoming chapter.
Ini files are where most users will spend the bulk of their time editing the configuration for their server.
As mentioned, they contain properties which were defined in their associated XML files which in turn reference Jetty Java objcts.
This can be a bit overwhelming at first, so let's look at an example - in this case the `http` module.
We will work backwards from an ini file to the associated module and then the XML file in question.
First up, the `http.ini` file.
If we take a look at it's contents, we will see the following:
[source, screen, subs="{sub-order}"]
----
$ cat start.d/http.ini
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
# By default HTTP/1 is support, but HTTP2C can
# be added to the connector with the http2c module.
# ---------------------------------------
--module=http
### HTTP Connector Configuration
## Connector host/address to bind to
# jetty.http.host=0.0.0.0
## Connector port to listen on
# jetty.http.port=8080
## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000
## Number of acceptors (-1 picks default based on number of cores)
# jetty.http.acceptors=-1
## Number of selectors (-1 picks default based on number of cores)
# jetty.http.selectors=-1
## ServerSocketChannel backlog (0 picks platform default)
# jetty.http.acceptQueueSize=0
## Thread priority delta to give to acceptor threads
# jetty.http.acceptorPriorityDelta=0
## Reserve threads for high priority tasks (-1 use a heuristic, 0 no reserved threads)
# jetty.http.reservedThreads=-1
## Connect Timeout in milliseconds
# jetty.http.connectTimeout=15000
## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230
----
So what do we see?
We have a module name, the module activation (`--module=http`), as well as a description and what look like properties to configure.
Those will some scripting/coding experience might notice that most of the lines are commented out with `#` and you'd be correct.
When a module is enabled and an `ini` file is created, all of the properties you see here were set to these defaults - the server is already using the values shown
If you wanted to change one of the properties though, say `jetty.http.port`, you'd simply uncomment the line and change the value.
For example:
[source, screen, subs="{sub-order}"]
----
$ cat start.d/http.ini
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
# By default HTTP/1 is support, but HTTP2C can
# be added to the connector with the http2c module.
# ---------------------------------------
--module=http
### HTTP Connector Configuration
## Connector host/address to bind to
# jetty.http.host=0.0.0.0
## Connector port to listen on
jetty.http.port=1234
...
----
As seen before, these properties were populated in this ini file based on a related module.
Standard Jetty modules live in the Home of the Jetty Distribution in the aptly named `modules` directory.
So let's take a quick look at the associated `$JETTY_HOME/modules/http.mod` file:
[source, screen, subs="{sub-order}"]
----
$ cat $JETTY_HOME/modules/http.mod
[description]
Enables a HTTP connector on the server.
By default HTTP/1 is support, but HTTP2C can
be added to the connector with the http2c module.
[tags]
connector
http
[depend]
server
[xml]
etc/jetty-http.xml
[ini-template]
### HTTP Connector Configuration
## Connector host/address to bind to
# jetty.http.host=0.0.0.0
## Connector port to listen on
# jetty.http.port=8080
## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000
...
----
At first blush, it looks remarkable similar to the `ini` file we just looked at.
We still have a description and the properties we could edit, but now we also have several other sections.
These other sections will be looked at further in our chapter on modules, but for now it is worth noting the `[xml]` and `[ini-template]` sections.
As you could probably have puzzled out, the `[ini-template]` contains a template (go figure) for properties to be placed in the associated `ini` file when a module is activated.
The `[xml]` section refers to the file and location of the XML file these properties are based on.
It is important to note that not every module file will have the same sections, but most should look structurally the same.
Now that we know what XML file these properties relate to, we can navigate to it and have a look.
[source, xml, subs="{sub-order}"]
----
$ cat $JETTY_HOME/etc/jetty-http.xml
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<!-- ============================================================= -->
<!-- Configure the Jetty Server instance with an ID "Server" -->
<!-- by adding a HTTP connector. -->
<!-- This configuration must be used in conjunction with jetty.xml -->
<!-- ============================================================= -->
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<!-- =========================================================== -->
<!-- Add a HTTP Connector. -->
<!-- Configure an o.e.j.server.ServerConnector with a single -->
<!-- HttpConnectionFactory instance using the common httpConfig -->
<!-- instance defined in jetty.xml -->
<!-- -->
<!-- Consult the javadoc of o.e.j.server.ServerConnector and -->
<!-- o.e.j.server.HttpConnectionFactory for all configuration -->
<!-- that may be set here. -->
<!-- =========================================================== -->
<Call name="addConnector">
<Arg>
<New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
<Arg name="acceptors" type="int"><Property name="jetty.http.acceptors" deprecated="http.acceptors" default="-1"/></Arg>
<Arg name="selectors" type="int"><Property name="jetty.http.selectors" deprecated="http.selectors" default="-1"/></Arg>
<Arg name="factories">
<Array type="org.eclipse.jetty.server.ConnectionFactory">
<Item>
<New class="org.eclipse.jetty.server.HttpConnectionFactory">
<Arg name="config"><Ref refid="httpConfig" /></Arg>
<Arg name="compliance"><Call class="org.eclipse.jetty.http.HttpCompliance" name="valueOf"><Arg><Property name="jetty.http.compliance" default="RFC7230"/></Arg></Call></Arg>
</New>
</Item>
</Array>
</Arg>
<Set name="host"><Property name="jetty.http.host" deprecated="jetty.host" /></Set>
<Set name="port"><Property name="jetty.http.port" deprecated="jetty.port" default="8080" /></Set>
<Set name="idleTimeout"><Property name="jetty.http.idleTimeout" deprecated="http.timeout" default="30000"/></Set>
<Set name="acceptorPriorityDelta"><Property name="jetty.http.acceptorPriorityDelta" deprecated="http.acceptorPriorityDelta" default="0"/></Set>
<Set name="acceptQueueSize"><Property name="jetty.http.acceptQueueSize" deprecated="http.acceptQueueSize" default="0"/></Set>
<Get name="SelectorManager">
<Set name="connectTimeout"><Property name="jetty.http.connectTimeout" default="15000"/></Set>
<Set name="reservedThreads"><Property name="jetty.http.reservedThreads" default="-2"/></Set>
</Get>
</New>
</Arg>
</Call>
</Configure>
----
Now we can see where those properties in our `ini` and module files came from.
In Jetty XML files, Jetty objects come to life; defined properties are set which link back to the jar libraries and run the server to a user's specification.
____
[IMPORTANT]
It is important to remember that you should *not* modify the XML files in your `$JETTY_HOME`.
If you do for some reason feel you want to change the way an XML file operates, it is best to make a copy of it in your `$JETTY_BASE` in an `/etc` directory.
Jetty will always look first to the `$JETTY_BASE` for configuration.
____
==== Other Configuration Files
In addition to the configuration files described above, the configuration of the server can use the following file types:
Context XML files::
Any XML files in link:#jetty-xml-syntax[Jetty IoC XML format] or Spring IoC format that is discovered in the `/webapps` directory are used by the deploy module to instantiate and inject `HttpContext` instances to create a specific context.
These may be standard web applications or bespoke contexts created from special purpose handlers.
web.xml::
The http://en.wikipedia.org/wiki/Servlet[Servlet] Specification defines the http://en.wikipedia.org/wiki/Web.xml[`web.xml`] deployment descriptor that defines and configures the filters, servlets and resources a http://en.wikipedia.org/wiki/Web_application[web application] uses.
The Jetty `WebAppContext` component uses this XML format to:
* Set up the default configuration of a web application context.
* Interpret the application-specific configuration supplied with a web application in the `WEB-INF/web.xml` file.
* Interpret descriptor fragments included in the `META-INF` directory of Jar files within `WEB-INF/lib.`
+
Normally the `web.xml` file for a web application is found in the `WEB-INF/web.xml` location within the war file/directory or as `web.xml` fragments with `.jar` files found in `WEB-INF/lib`.
Jetty also supports multiple `web.xml` files so that a default descriptor may be applied before `WEB-INF/web.xml` (typically set to `etc/webdefault.xml` by the deploy module) and an override descriptor may be applied after `WEB-INF/web.xml` (typically set by a context XML file see `test.xml`)
Property Files::
Standard http://en.wikipedia.org/wiki/Java_properties[Java property files] are also used for Jetty configuration in several ways:
+
* To parameterize Jetty IoC XML via the use of the `Property` element.
* To configure the default logging mechanism (`StdErrLog`). Other logging frameworks can be utilized and also use property files (for example, `log4j`).
* As a simple database for login usernames and credentials.
==== Jetty IoC XML format
To understand the link:#jetty-xml-syntax[Jetty IoC XML format], consider the following example of an embedded Jetty server instantiated and configured in Java:
[source, java, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ExampleServer.java[]
----
link:#jetty-xml-syntax[Jetty IoC XML format] allows you to instantiate and configure the exact same server in XML without writing any java code:
[source, xml, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/resources/exampleserver.xml[]
----
//In practice, most commonly used Jetty features have XML files that are included in the standard distribution in the `/etc` directory.
//Thus configuring Jetty is often a matter of just editing existing XML files and altering the property values injected into them.

BIN
documentation/jetty-documentation/src/main/asciidoc/old_docs/gettingstarted/images/Jetty_Configuration_File_Relationships.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 33 KiB

2
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/chapter.adoc
View File

@ -14,8 +14,6 @@
[[startup]]
== Starting Jetty
include::startup-modules.adoc[]
include::custom-modules.adoc[]
include::startup-xml-config.adoc[]
include::startup-unix-service.adoc[]
include::startup-windows-service.adoc[]

65
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/screen-empty-base-listconfig.adoc
View File

@ -1,65 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-config
Java Environment:
-----------------
java.home = /Library/Java/JavaVirtualMachines/jdk1.8.0_92.jdk/Contents/Home/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.92-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
user.dir = /var/my-jetty-base
user.language = en
user.country = US
Jetty Environment:
-----------------
jetty.version = {VERSION}
jetty.tag.version = master
jetty.home = /Users/staff/installs/repository/jetty-home-{VERSION}
jetty.base = /var/my-jetty-base
Config Search Order:
--------------------
<command-line>
${jetty.base} -> /var/my-jetty-base
${jetty.home} -> /Users/staff/installs/repository/jetty-home-{VERSION}
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
(no system properties specified)
Properties:
-----------
java.version = 1.8.0_92
Jetty Server Classpath:
-----------------------
No classpath entries and/or version information available show.
Jetty Active XMLs:
------------------
(no xml files specified)
....

80
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/screen-http-webapp-deploy-listconfig.adoc
View File

@ -1,80 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-config
Java Environment:
-----------------
java.home = /Library/Java/JavaVirtualMachines/jdk1.8.0_92.jdk/Contents/Home/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.92-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
user.dir = /var/my-jetty-base
user.language = en
user.country = US
Jetty Environment:
-----------------
jetty.version = {VERSION}
jetty.tag.version = master
jetty.home = /Users/staff/installs/repository/jetty-home-{VERSION}
jetty.base = /var/my-jetty-base
Config Search Order:
--------------------
<command-line>
${jetty.base} -> /var/my-jetty-base
${jetty.home} -> /Users/staff/installs/repository/jetty-home-{VERSION}
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
(no system properties specified)
Properties:
-----------
java.version = 1.8.0_92
Jetty Server Classpath:
-----------------------
Version Information on 11 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: 3.1.0 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
2: {VERSION} | ${jetty.home}/lib/jetty-http-{VERSION}.jar
3: {VERSION} | ${jetty.home}/lib/jetty-server-{VERSION}.jar
4: {VERSION} | ${jetty.home}/lib/jetty-xml-{VERSION}.jar
5: {VERSION} | ${jetty.home}/lib/jetty-util-{VERSION}.jar
6: {VERSION} | ${jetty.home}/lib/jetty-io-{VERSION}.jar
7: {VERSION} | ${jetty.home}/lib/jetty-security-{VERSION}.jar
8: {VERSION} | ${jetty.home}/lib/jetty-servlet-{VERSION}.jar
9: {VERSION} | ${jetty.home}/lib/jetty-webapp-{VERSION}.jar
10: {VERSION} | ${jetty.home}/lib/jetty-deploy-{VERSION}.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.xml
....

25
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/screen-http-webapp-deploy.adoc
View File

@ -1,25 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=http,webapp,deploy
INFO : webapp initialized in ${jetty.base}/start.ini
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : security transitively enabled
INFO : servlet transitively enabled
INFO : http initialized in ${jetty.base}/start.ini
INFO : deploy initialized in ${jetty.base}/start.ini
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified
....

89
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/screen-list-logging-modules.adoc
View File

@ -1,89 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-modules=logging,-internal
Available Modules:
==================
tags: [logging, -internal]
Modules for tag 'logging':
--------------------------
Module: console-capture
: Redirects JVMs console stderr and stdout to a log file,
: including output from Jetty's default StdErrLog logging.
Tags: logging
LIB: resources/
XML: etc/console-capture.xml
Module: logging-jcl [logging]
: Configure jetty logging to use Java Commons Logging (jcl)
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: jcl-impl, slf4j-jcl
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-jetty [logging]
: Configure jetty logging mechanism.
: Provides a ${jetty.base}/resources/jetty-logging.properties.
Tags: logging
Depend: console-capture, resources
Module: logging-jul [logging]
: Configure jetty logging to use Java Util Logging (jul)
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: jul-impl, slf4j-jul
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j [logging]
: Configure jetty logging to use Log4j Logging
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: log4j-impl, slf4j-log4j
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j2 [logging]
: Configure jetty logging to use log4j version 2
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-log4j2, log4j2-impl
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-logback [logging]
: Configure jetty logging to use Logback Logging.
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: logback-impl, slf4j-logback
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-slf4j [logging]
: Configure jetty logging to use slf4j.
: Any slf4j-impl implementation is used
Tags: logging
Depend: slf4j-api, slf4j-impl
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Modules for tag 'requestlog':
-----------------------------
Module: logback-access [requestlog]
: Enables logback request log.
Tags: requestlog, logging, logback
Depend: server, logback-core, resources
LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml
....

725
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/screen-list-modules.adoc
View File

@ -1,725 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-modules
Available Modules:
==================
tags: [-internal]
Modules for tag '*':
--------------------
Module: alpn
: Enables the ALPN (Application Layer Protocol Negotiation) TLS extension.
Depend: ssl, alpn-impl
LIB: lib/jetty-alpn-client-${jetty.version}.jar
LIB: lib/jetty-alpn-server-${jetty.version}.jar
XML: etc/jetty-alpn.xml
Module: alpn-impl
: Selects an ALPN (Application Layer Protocol Negotiation) implementation by java version.
Depend: alpn-impl/alpn-${java.version.platform}
Module: annotations
: Enables Annotation scanning for deployed webapplications.
Depend: plus
LIB: lib/jetty-annotations-${jetty.version}.jar
LIB: lib/annotations/*.jar
XML: etc/jetty-annotations.xml
Enabled: ${jetty.base}\start.d\annotations.ini
Module: apache-jsp
: Enables use of the apache implementation of JSP
LIB: lib/apache-jsp/*.jar
Enabled: transitive provider of apache-jsp for jsp
Module: apache-jstl
: Enables the apache version of JSTL
LIB: lib/apache-jstl/*.jar
Enabled: transitive provider of apache-jstl for jstl
Module: cdi2
: Jetty setup to support Weld/CDI2 with WELD inside the webapp
Depend: deploy
XML: etc/cdi2/jetty-cdi2.xml
Module: client
: Adds the Jetty HTTP client to the server classpath.
LIB: lib/jetty-client-${jetty.version}.jar
Enabled: ${jetty.base}\start.d\client.ini
Module: continuation
: Enables support for Continuation style asynchronous
: Servlets. Now deprecated in favour of Servlet 3.1
: API
LIB: lib/jetty-continuation-${jetty.version}.jar
Enabled: ${jetty.base}\start.d\continuation.ini
Module: deploy
: Enables webapplication deployment from the webapps directory.
Depend: webapp
LIB: lib/jetty-deploy-${jetty.version}.jar
XML: etc/jetty-deploy.xml
Enabled: ${jetty.base}\start.d\deploy.ini
Module: fcgi
: Adds the FastCGI implementation to the classpath.
Depend: servlet, client
LIB: lib/jetty-proxy-${jetty.version}.jar
LIB: lib/fcgi/*.jar
Module: flight-recorder
Depend: server
JVM: -XX:+UnlockCommercialFeatures
JVM: -XX:+FlightRecorder
Module: global-webapp-common
: Enables Deployer to apply common configuration to all webapp deployments
Depend: deploy
XML: etc/global-webapp-common.xml
Module: hazelcast-embedded-sessions
Depend: annotations, webapp
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/default.xml
Module: hazelcast-remote-sessions
Depend: annotations, webapp
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/remote.xml
Module: home-base-warning
: Generates a warning that server has been run from $JETTY_HOME
: rather than from a $JETTY_BASE.
XML: etc/home-base-warning.xml
Module: jaas
: Enable JAAS for deployed webapplications.
Depend: server
LIB: lib/jetty-jaas-${jetty.version}.jar
XML: etc/jetty-jaas.xml
Enabled: ${jetty.base}\start.d\demo.ini
Module: jaspi
: Enable JASPI authentication for deployed webapplications.
Depend: security
LIB: lib/jetty-jaspi-${jetty.version}.jar
LIB: lib/jaspi/*.jar
Module: jmx
: Enables JMX instrumentation for server beans and
: enables JMX agent.
Depend: server
LIB: lib/jetty-jmx-${jetty.version}.jar
XML: etc/jetty-jmx.xml
Module: jmx-remote
: Enables remote RMI access to JMX
Depend: jmx
XML: etc/jetty-jmx-remote.xml
Module: jndi
: Adds the Jetty JNDI implementation to the classpath.
Depend: server, mail
LIB: lib/jetty-jndi-${jetty.version}.jar
LIB: lib/jndi/*.jar
Enabled: ${jetty.base}\start.d\jndi.ini
Module: jsp
: Enables JSP for all webapplications deployed on the server.
Depend: servlet, annotations, apache-jsp
Enabled: ${jetty.base}\start.d\jsp.ini
Module: jstl
: Enables JSTL for all webapplications deployed on the server
Depend: jsp, apache-jstl
Enabled: ${jetty.base}\start.d\jstl.ini
Module: jvm
: A noop module that creates an ini template useful for
: setting JVM arguments (eg -Xmx )
Module: lowresources
: Enables a low resource monitor on the server
: that can take actions if threads and/or connections
: cross configured threshholds.
Depend: server
XML: etc/jetty-lowresources.xml
Module: mail
: Adds the javax.mail implementation to the classpath.
LIB: lib/mail/*.jar
Enabled: transitive provider of mail for jndi
Module: plus
: Enables JNDI and resource injection for webapplications
: and other servlet 3.x features not supported in the core
: jetty webapps module.
Depend: server, security, jndi, webapp, transactions
LIB: lib/jetty-plus-${jetty.version}.jar
XML: etc/jetty-plus.xml
Enabled: transitive provider of plus for annotations
Module: proxy
: Enable the Jetty Proxy, that allows the server to act
: as a non-transparent proxy for browsers.
Depend: servlet, client
LIB: lib/jetty-proxy-${jetty.version}.jar
XML: etc/jetty-proxy.xml
Module: proxy-protocol
: Enables the Proxy Protocol on the HTTP Connector.
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows a proxy operating in TCP mode to
: transport details of the proxied connection to
: the server.
: Both V1 and V2 versions of the protocol are supported.
Depend: http
XML: etc/jetty-proxy-protocol.xml
Module: quickstart
: Enables the Jetty Quickstart module for rapid
: deployment of preconfigured webapplications.
Depend: server, plus, annotations
LIB: lib/jetty-quickstart-${jetty.version}.jar
Module: rewrite
: Enables the jetty-rewrite handler. Specific rewrite
: rules must be added to either to etc/jetty-rewrite.xml or a custom xml/module
Depend: server
LIB: lib/jetty-rewrite-${jetty.version}.jar
XML: etc/jetty-rewrite.xml
Enabled: ${jetty.base}\start.d\demo.ini
Module: rewrite-compactpath
: Add a rule to the rewrite module to compact paths so that double slashes
: in the path are treated as a single slash.
Depend: rewrite
XML: etc/rewrite-compactpath.xml
Module: rewrite-customizer [rewrite]
: Enables a rewrite Rules container as a request customizer on
: the servers default HttpConfiguration instance
Depend: server
LIB: lib/jetty-rewrite-${jetty.version}.jar
XML: etc/jetty-rewrite-customizer.xml
Module: security
: Adds servlet standard security handling to the classpath.
Depend: server
LIB: lib/jetty-security-${jetty.version}.jar
Enabled: transitive provider of security for webapp
Enabled: transitive provider of security for plus
Module: server
: Enables the core Jetty server on the classpath.
Depend: threadpool
Optional: jvm, ext, resources, logging
LIB: lib/jetty-servlet-api-4.0.2.jar
LIB: lib/jetty-http-${jetty.version}.jar
LIB: lib/jetty-server-${jetty.version}.jar
LIB: lib/jetty-xml-${jetty.version}.jar
LIB: lib/jetty-util-${jetty.version}.jar
LIB: lib/jetty-io-${jetty.version}.jar
XML: etc/jetty.xml
Enabled: ${jetty.base}\start.d\server.ini
Module: servlet
: Enables standard Servlet handling.
Depend: server
LIB: lib/jetty-servlet-${jetty.version}.jar
Enabled: transitive provider of servlet for webapp
Enabled: transitive provider of servlet for servlets
Enabled: transitive provider of servlet for jsp
Module: servlets
: Puts a collection of jetty utility servlets and filters
: on the server classpath (CGI, CrossOriginFilter, DosFilter,
: MultiPartFilter, PushCacheFilter, QoSFilter, etc.) for
: use by all webapplications.
Depend: servlet
LIB: lib/jetty-servlets-${jetty.version}.jar
Enabled: ${jetty.base}\start.d\servlets.ini
Module: setuid
: Enables the unix setUID configuration so that the server
: may be started as root to open privileged ports/files before
: changing to a restricted user (eg jetty).
Depend: server
LIB: lib/setuid/jetty-setuid-java-1.0.3.jar
XML: etc/jetty-setuid.xml
Module: spring
: Enable spring configuration processing so all jetty style
: xml files can optionally be written as spring beans
Depend: server
LIB: lib/spring/*.jar
Module: stop
: This module causes jetty to stop immediately after starting. This is good for testing configuration and/or precompiling quickstart webapps
XML: etc/jetty-stop.xml
Module: threadpool
: Enables the Server thread pool.
XML: etc/jetty-threadpool.xml
Enabled: ${jetty.base}\start.d\threadpool.ini
Module: transactions
: Puts javax.transaction api on the classpath
LIB: lib/transactions/*.jar
Enabled: transitive provider of transactions for plus
Module: webapp
: Adds support for servlet specification webapplication to the server
: classpath. Without this, only Jetty specific handlers may be deployed.
Depend: servlet, security
LIB: lib/jetty-webapp-${jetty.version}.jar
XML: etc/jetty-webapp.xml
Enabled: transitive provider of webapp for plus
Enabled: transitive provider of webapp for deploy
Module: websocket
: Enable websockets for deployed web applications
Depend: client, annotations
LIB: lib/websocket/*.jar
Enabled: ${jetty.base}\start.d\demo.ini
Modules for tag '3rdparty':
---------------------------
Module: conscrypt [alpn-impl]
: Installs the Conscrypt JSSE provider
Tags: 3rdparty
Depend: ssl
LIB: lib/conscrypt/**.jar
LIB: lib/jetty-alpn-conscrypt-server-${jetty.version}.jar
XML: etc/conscrypt.xml
Module: gcloud
: Control GCloud API classpath
Tags: 3rdparty, gcloud
LIB: lib/gcloud/*.jar
Module: gcloud-datastore
: Enables GCloud Datastore API and implementation
Tags: 3rdparty, gcloud
Depend: gcloud, jcl-slf4j, jul-impl
Module: hawtio
: Deploys the Hawtio console as a webapplication.
Tags: 3rdparty
Depend: stats, deploy, jmx
XML: etc/hawtio.xml
Module: jamon
: Deploys the JAMon webapplication
Tags: 3rdparty
Depend: stats, deploy, jmx, jsp
LIB: lib/jamon/**.jar
XML: etc/jamon.xml
Module: jminix
: Deploys the Jminix JMX Console within the server
Tags: 3rdparty
Depend: stats, jmx, jcl-api, jcl-impl
LIB: lib/jminix/**.jar
XML: etc/jminix.xml
Module: jolokia
: Deploys the Jolokia console as a web application.
Tags: 3rdparty
Depend: stats, deploy, jmx
XML: etc/jolokia.xml
Modules for tag 'classpath':
----------------------------
Module: ext
: Adds all jar files discovered in $JETTY_HOME/lib/ext
: and $JETTY_BASE/lib/ext to the servers classpath.
Tags: classpath
LIB: lib/ext/**.jar
Enabled: ${jetty.base}\start.d\ext.ini
Module: resources
: Adds the $JETTY_HOME/resources and/or $JETTY_BASE/resources
: directory to the server classpath. Useful for configuration
: property files (eg jetty-logging.properties)
Tags: classpath
LIB: resources/
Enabled: ${jetty.base}\start.d\resources.ini
Modules for tag 'connector':
----------------------------
Module: acceptratelimit
: Enable a server wide accept rate limit
Tags: connector
Depend: server
XML: etc/jetty-acceptratelimit.xml
Module: connectionlimit
: Enable a server wide connection limit
Tags: connector
Depend: server
XML: etc/jetty-connectionlimit.xml
Module: http
: Enables a HTTP connector on the server.
: By default HTTP/1 is support, but HTTP2C can
: be added to the connector with the http2c module.
Tags: connector, http
Depend: server
XML: etc/jetty-http.xml
Enabled: ${jetty.base}\start.d\http.ini
Module: http-forwarded
: Adds a forwarded request customizer to the HTTP Connector
: to process forwarded-for style headers from a proxy.
Tags: connector
Depend: http
XML: etc/jetty-http-forwarded.xml
Module: http2
: Enables HTTP2 protocol support on the TLS(SSL) Connector,
: using the ALPN extension to select which protocol to use.
Tags: connector, http2, http, ssl
Depend: ssl, alpn
LIB: lib/http2/*.jar
XML: etc/jetty-http2.xml
Module: http2c
: Enables the HTTP2C protocol on the HTTP Connector
: The connector will accept both HTTP/1 and HTTP/2 connections.
Tags: connector, http2, http
Depend: http
LIB: lib/http2/*.jar
XML: etc/jetty-http2c.xml
Module: https
: Adds HTTPS protocol support to the TLS(SSL) Connector
Tags: connector, https, http, ssl
Depend: ssl
Optional: http-forwarded, http2
XML: etc/jetty-https.xml
Enabled: ${jetty.base}\start.d\https.ini
Module: proxy-protocol-ssl
: Enables the Proxy Protocol on the TLS(SSL) Connector.
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows a Proxy operating in TCP mode to transport
: details of the proxied connection to the server.
: Both V1 and V2 versions of the protocol are supported.
Tags: connector, ssl
Depend: ssl
XML: etc/jetty-proxy-protocol-ssl.xml
Module: ssl
: Enables a TLS(SSL) Connector on the server.
: This may be used for HTTPS and/or HTTP2 by enabling
: the associated support modules.
Tags: connector, ssl
Depend: server
XML: etc/jetty-ssl.xml
XML: etc/jetty-ssl-context.xml
Enabled: transitive provider of ssl for https
Module: unixsocket
: Enables a Unix Domain Socket Connector that can receive
: requests from a local proxy and/or SSL offloader (eg haproxy) in either
: HTTP or TCP mode. Unix Domain Sockets are more efficient than
: localhost TCP/IP connections as they reduce data copies, avoid
: needless fragmentation and have better dispatch behaviours.
: When enabled with corresponding support modules, the connector can
: accept HTTP, HTTPS or HTTP2C traffic.
Tags: connector
Depend: server
LIB: lib/jetty-unixsocket-${jetty.version}.jar
LIB: lib/jnr/*.jar
XML: etc/jetty-unixsocket.xml
Module: unixsocket-forwarded
: Adds a forwarded request customizer to the HTTP configuration used
: by the Unix Domain Socket connector, for use when behind a proxy operating
: in HTTP mode that adds forwarded-for style HTTP headers. Typically this
: is an alternate to the Proxy Protocol used mostly for TCP mode.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-forwarded.xml
Module: unixsocket-http
: Adds a HTTP protocol support to the Unix Domain Socket connector.
: It should be used when a proxy is forwarding either HTTP or decrypted
: HTTPS traffic to the connector and may be used with the
: unix-socket-http2c modules to upgrade to HTTP/2.
Tags: connector, http
Depend: unixsocket
XML: etc/jetty-unixsocket-http.xml
Module: unixsocket-http2c
: Adds a HTTP2C connetion factory to the Unix Domain Socket Connector
: It can be used when either the proxy forwards direct
: HTTP/2C (unecrypted) or decrypted HTTP/2 traffic.
Tags: connector, http2
Depend: unixsocket-http
LIB: lib/http2/*.jar
XML: etc/jetty-unixsocket-http2c.xml
Module: unixsocket-proxy-protocol
: Enables the proxy protocol on the Unix Domain Socket Connector
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows information about the proxied connection to be
: efficiently forwarded as the connection is accepted.
: Both V1 and V2 versions of the protocol are supported and any
: SSL properties may be interpreted by the unixsocket-secure
: module to indicate secure HTTPS traffic. Typically this
: is an alternate to the forwarded module.
Tags: connector
Depend: unixsocket
XML: etc/jetty-unixsocket-proxy-protocol.xml
Module: unixsocket-secure
: Enable a secure request customizer on the HTTP Configuration
: used by the Unix Domain Socket Connector.
: This looks for a secure scheme transported either by the
: unixsocket-forwarded, unixsocket-proxy-protocol or in a
: HTTP2 request.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml
Modules for tag 'debug':
------------------------
Module: debug
: Enables the DebugListener to generate additional
: logging regarding detailed request handling events.
: Renames threads to include request URI.
Tags: debug
Depend: deploy
XML: etc/jetty-debug.xml
Module: debuglog
: Deprecated Debug Log using the DebugHandle.
: Replaced with the debug module.
Tags: debug
Depend: server
XML: etc/jetty-debuglog.xml
Modules for tag 'handler':
--------------------------
Module: gzip
: Enable GzipHandler for dynamic gzip compression
: for the entire server.
Tags: handler
Depend: server
XML: etc/jetty-gzip.xml
Module: ipaccess
: Enable the ipaccess handler to apply a white/black list
: control of the remote IP of requests.
Tags: handler
Depend: server
XML: etc/jetty-ipaccess.xml
Module: stats
: Enable detailed statistics collection for the server,
: available via JMX.
Tags: handler
Depend: server
XML: etc/jetty-stats.xml
Module: threadlimit
Tags: handler
Depend: server
XML: etc/jetty-threadlimit.xml
Modules for tag 'logging':
--------------------------
Module: console-capture
: Redirects JVMs console stderr and stdout to a log file,
: including output from Jetty's default StdErrLog logging.
Tags: logging
LIB: resources/
XML: etc/console-capture.xml
Module: logging-jetty [logging]
: Configure jetty logging mechanism.
: Provides a ${jetty.base}/resources/jetty-logging.properties.
Tags: logging
Depend: resources
Module: logging-jul [logging]
: Configure jetty logging to use Java Util Logging (jul)
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-jul, jul-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j [logging]
: Configure jetty logging to use Log4j Logging
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-log4j, log4j-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j2 [logging]
: Configure jetty logging to use log4j version 2
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-log4j2, log4j2-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-logback [logging]
: Configure jetty logging to use Logback Logging.
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-logback, logback-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-slf4j [logging]
: Configure jetty logging to use slf4j.
: Any slf4j-impl implementation is used
Tags: logging
Depend: slf4j-api, slf4j-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Modules for tag 'requestlog':
-----------------------------
Module: logback-access [requestlog]
: Enables logback request log.
Tags: requestlog, logging, logback
Depend: server, logback-impl, resources
LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml
Module: requestlog
: Enables a NCSA style request log.
Tags: requestlog
Depend: server
XML: etc/jetty-requestlog.xml
Modules for tag 'session':
--------------------------
Module: session-cache-hash [session-cache]
: Enable first level session cache in ConcurrentHashMap.
: If not enabled, sessions will use a HashSessionCache by default, so enabling
: via this module is only needed if the configuration properties need to be
: changed.
Tags: session
Depend: sessions
XML: etc/sessions/session-cache-hash.xml
Module: session-cache-null [session-cache]
: A trivial SessionCache that does not actually cache sessions.
Tags: session
Depend: sessions
XML: etc/sessions/session-cache-null.xml
Module: session-store-cache
: Enables caching of SessionData in front of a SessionDataStore.
Tags: session
Depend: session-store, sessions/session-data-cache/${session-data-cache}
XML: etc/sessions/session-data-cache/session-caching-store.xml
Module: session-store-file [session-store]
: Enables session persistent storage in files.
Tags: session
Depend: sessions
XML: etc/sessions/file/session-store.xml
Module: session-store-gcloud [session-store]
: Enables GCloudDatastore session management.
Tags: session, gcloud
Depend: gcloud-datastore, annotations, webapp, sessions
LIB: lib/jetty-gcloud-session-manager-${jetty.version}.jar
XML: etc/sessions/gcloud/session-store.xml
Module: session-store-hazelcast-embedded [session-store]
: Enables session data store in an embedded Hazelcast Map
Tags: session
Depend: sessions
LIB: lib/jetty-hazelcast-${jetty.version}.jar
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/default.xml
Module: session-store-hazelcast-remote [session-store]
: Enables session data store in a remote Hazelcast Map
Tags: session
Depend: sessions
LIB: lib/jetty-hazelcast-${jetty.version}.jar
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/remote.xml
Module: session-store-infinispan-embedded [session-store-infnispan-embedded, session-store]
: Enables session data store in a local Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/default.xml
Module: session-store-infinispan-embedded-910 [session-store-infinispan-embedded, session-store]
: Enables session data store in a local Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/default.xml
Module: session-store-infinispan-remote [session-store]
: Enables session data store in a remote Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/remote.xml
Module: session-store-infinispan-remote-910 [session-store-infinispan-remote, session-store]
: Enables session data store in a remote Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/remote.xml
Module: session-store-jdbc [session-store]
: Enables JDBC persistent/distributed session storage.
Tags: session
Depend: sessions, sessions/jdbc/${db-connection-type}
XML: etc/sessions/jdbc/session-store.xml
Module: session-store-mongo [session-store]
: Enables NoSql session management with a MongoDB driver.
Tags: session
Depend: sessions, sessions/mongo/${connection-type}
LIB: lib/jetty-nosql-${jetty.version}.jar
LIB: lib/nosql/*.jar
Module: sessions
: The session management. By enabling this module, it allows
: session management to be configured via the ini templates
: created or by enabling other session-cache or session-store
: modules. Without this module enabled, the server may still
: use sessions, but their management cannot be configured.
Tags: session
Depend: server
XML: etc/sessions/id-manager.xml
....

232
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-modules.adoc
View File

@ -1,232 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[startup-modules]]
=== Managing Startup Modules
The standard Jetty Distribution ships with several modules defined in `${jetty.home}/modules/`.
Modules interact with Jetty XML files to configure options and parameters for the server and are the primary configuration method for Jetty distributions.
Modules allow flexibility for implementations and their plug-and-play nature makes adding or removing server functionality virtually painless.
[[enabling-modules]]
==== Enabling Modules
____
[TIP]
The default distribution has a co-mingled `${jetty.home}` and `${jetty.base}` where the directories for `${jetty.home}` and `${jetty.base}` point to the same location.
It is highly encouraged that you learn about the differences in link:#startup-base-and-home[Jetty Base vs Jetty Home] and take full advantage of this setup.
____
Enabling a module is a simple process: simply add the `--add-to-start=<module-name1>,<module-name2>,...etc.` syntax on the command line.
Doing this will enable the specified module and any dependent modules.
An example of this with a new, empty, base directory:
If we try to start the Jetty server with no configuration or modules enabled, it will promptly exit:
include::screen-empty-base.adoc[]
By using the `--list-config` parameter to our startup command, we can see that there are no modules enabled and no Jetty XML files are active:
include::screen-empty-base-listconfig.adoc[]
Let's try adding some basic support for webapps, with automatic deploy (hot deploy), and a single basic HTTP/1.1 connector.
include::screen-http-webapp-deploy.adoc[]
This creates the webapps directory in our `mybase` directory and appended the `start.ini` file with the ini template arguments from the associated module files.
Additionally, where needed, Jetty enabled any module dependencies.
Now that we have added some modules to our server, let's run `--list-config` again to review our new configuration.
include::screen-http-webapp-deploy-listconfig.adoc[]
You now have a configured and functional server, albeit with no webapps deployed.
At this point you can place a webapp (war file) in the `mybase/webapps/` directory and and start Jetty.
[[start-vs-startd]]
==== Start.ini vs. Start.d
In the above example, when a module is activated the contents of that module file are added in `${jetty.base}/start.ini`.
As additional modules are added, their contents are appended to this file.
This can be beneficial if you want all of your module configurations in a single file, but for large server instances with lots of modules it can pose a challenge to quickly find and make changes or to remove a module.
As an alternative to a single `start.ini` file you can opt to house modules in a `${jetty.base}/start.d` directory.
Modules activated when a `start.d` directory exists will be stored as a single file per module.
Below is an example of a fresh `${jetty.base}` that will create a `start.d` directory and activate several modules.
[source,screen,subs="{sub-order}"]
....
[jetty.home]$ mkdir mybase
[jetty.home]$ cd mybase/
[my-base]$ java -jar /path/to/jetty-home/start.jar --create-startd
INFO : Base directory was modified
[mybase]$ ls -all
total 0
drwxr-xr-x 3 staff staff 102 Aug 29 15:16 .
drwxr-xr-x@ 26 staff staff 884 Aug 29 15:16 ..
drwxr-xr-x 6 staff staff 204 Aug 29 15:19 start.d
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.d/webapp.ini
INFO : server initialised in ${jetty.base}/start.d/server.ini
INFO : websocket initialised in ${jetty.base}/start.d/websocket.ini
INFO : client initialised in ${jetty.base}/start.d/client.ini
INFO : Base directory was modified
[mybase]$ cd start.d/
[mybase]$ ls -all
total 32
drwxr-xr-x 6 staff staff 204 Aug 29 15:19 .
drwxr-xr-x 3 staff staff 102 Aug 29 15:16 ..
-rw-r--r-- 1 staff staff 175 Aug 29 15:19 client.ini
-rw-r--r-- 1 staff staff 2250 Aug 29 15:19 server.ini
-rw-r--r-- 1 staff staff 265 Aug 29 15:19 webapp.ini
-rw-r--r-- 1 staff staff 177 Aug 29 15:19 websocket.ini
....
In the example, we first create a new `${jetty.base}` and then create the `start.d` directory with the `--create-startd` command.
Next, we use the `--add-to-start` command which activates the modules and creates their respective ini files in the `start.d` directory.
If you have an existing `start.ini` file but would like to use the `start.d` structure for additional modules, you can use the `--create-startd` command as well.
Doing this will create the `start.d` directory and copy your existing `start.ini` file in to it.
Any new modules added to the server will have their own `<module name>.ini` file created in the `start.d` directory.
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.ini
INFO : server initialised in ${jetty.base}/start.ini
INFO : websocket initialised in ${jetty.base}/start.ini
INFO : client initialised in ${jetty.base}/start.ini
INFO : Base directory was modified
[my-base]$ java -jar /path/to/jetty-home/start.jar --create-startd
INFO : Base directory was modified
[mybase]$ tree
.
└── start.d
└── start.ini
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=ssl
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini
INFO : Base directory was modified
[mybase]$ tree
.
├── etc
│   └── keystore
└── start.d
├── ssl.ini
└── start.ini
....
[NOTE]
--
It is *not* recommended to use both a `${jetty.base}/start.ini` file and a `${jetty.base}/start.d` directory at the same time and doing so can cause issues.
--
[[startup-configuring-modules]]
==== Configuring Modules
Once a module has been enabled for the server, it can be further configured to meet your needs.
This is done by editing the associated ini file for the module.
If your server setup is using a centralized ini configuration, you will edit the `${jetty.base}/server.ini` file.
If you have elected to manage each module within it's own ini file, you can find these files in the `${jetty.base}/start.d` directory.
____
[IMPORTANT]
It is important that you *do not* modify the module files in the `$JETTY_HOME/modules` directory.
$JETTY_HOME should always remain a standard of truth.
If you want to make a change to an actual module file (not the values in its `ini-template`), either edit its associated `ini` file in the `$JETTY_BASE/start.d` directory or make a copy of the desired module file and copy it to the `$JETTY_BASE` directory and edit it there.
The start.jar reads local `$JETTY_BASE/modules` files (if they exist) before scanning `$JETTY_HOME`.
____
When a module is activated, a number of properties are set by default.
To view these defaults, open up the associated ini file.
Listed in the ini file is the associated module file and any properties that can be set.
Below is an example of the `requestlog.ini` file:
[source, screen, subs="{sub-order}"]
....
# ---------------------------------------
# Module: requestlog
--module=requestlog
## Logging directory (relative to $jetty.base)
# jetty.requestlog.dir=logs
## File path
# jetty.requestlog.filePath=${jetty.requestlog.dir}/yyyy_mm_dd.request.log
## Date format for rollovered files (uses SimpleDateFormat syntax)
# jetty.requestlog.filenameDateFormat=yyyy_MM_dd
## How many days to retain old log files
# jetty.requestlog.retainDays=90
## Whether to append to existing file
# jetty.requestlog.append=true
## Whether to use the extended log output
# jetty.requestlog.extended=true
## Whether to log http cookie information
# jetty.requestlog.cookies=true
## Timezone of the log entries
# jetty.requestlog.timezone=GMT
## Whether to log LogLatency
# jetty.requestlog.loglatency=false
....
The first lines name the module file being called (located in `{$jetty.home/modules}`).
Subsequent lines list properties that can be changed as well as a description for each property.
To edit a property, first un-comment the line by deleting the `#` at the start of the line, then make the change after `=` sign (such as changing a `true` value to `false`).
[[startup-disable-module]]
==== Disabling Modules
Disabling a module is an easy process.
To disable a module, comment out the `--module=` line in the associated ini file.
Deleting the ini file associated with module is another option, but may not be practical in all situations.
[[startup-listing-modules]]
==== Listing Available and Active Modules
To see which modules are __available__, use the `--list-modules` command line argument.
This command will also show you which modules are __enabled__.
Modules are sorted by the value in the `[tags]` section of the associated `.mod` file.
If there are multiple entries in the `[tags]` section, it sorts by the first tag in the list.
____
[NOTE]
By default, the `--list-modules` command line argument shows all modules that do not include `internal` in the `[tags]` section of the associated `.mod` file.
If you would like to see *all* modules, use `--list-all-modules`
____
Here's an example of the `--list-modules` command:
include::screen-list-modules.adoc[]
===== Searching Modules
Since the introduction of the module system, many new modules have been added.
As a result, looking at the module list as a whole can be somewhat overwhelming.
To narrow down which modules you would like to choose from, you can search by values listed under the `[tags]` section.
Note that when you search this way, all modules that include your criteria in it's `[tags]` section, including internal modules, will be shown.
To filter out internal modules when searching a specific module tag, simply add `-internal` to the command line.
For example, if you wanted to look at only the logging modules (excluding the internal implementation modules), you would use `--list-modules=logging,-internal`.
include::screen-list-logging-modules.adoc[]

22
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-xml-config.adoc
View File

@ -1,22 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[startup-xml-config]]
=== Managing XML Based Startup Configuration
When you see XML files on the command line for startup of Jetty, they are always part of the Jetty IoC Configuration mechanism.
Internally, Jetty uses these XML files to build up Jetty with the features that you wan to use.
The module mechanism present in Jetty determines the load order of the XML files.
The Jetty Base and Jetty Home resolution logic also applies, which allows you to override a XML file declared by a module with your XML by simply having the same named XML in your `${jetty.base}/etc` directory location.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/architecture.adoc
View File

@ -50,7 +50,7 @@ For more detailed information about the Jetty module system, see xref:og-modules
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_HOME`, and the customizations for your specific environment(s), known as `$JETTY_BASE`.
This separation between the binary installation directory and the specific configuration directory allows to manage multiple, different, server configurations, and allows for quick, drop-in upgrades of Jetty.
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_HOME` (per version of Jetty), but there can be many `$JETTY_BASE` directories that reference it.

4
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc
View File

@ -14,10 +14,6 @@
[[og-begin-start]]
==== Starting Jetty
// TODO: Consider: old_docs/startup/*.adoc
// So far, what below is the content of old_docs/startup/startup-modules.adoc
Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line.
Recall from the xref:og-arch[architecture section] that Jetty is based on xref:og-modules[modules], that provides features, and on xref:og-arch-jetty-base[`$JETTY_BASE`], the place where you configure which module (and therefore which feature) you want to enable, and where you configure module parameters.

1
documentation/jetty-documentation/src/main/asciidoc/operations-guide/index-docinfo.html
View File

@ -1,2 +1,3 @@
<link rel="stylesheet" href="../styles.css">
<link rel="stylesheet" href="../toc.css">
<script src="../toc.js"></script>

3
documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
View File

@ -25,11 +25,10 @@ include::architecture/chapter.adoc[]
include::features.adoc[]
include::howtos.adoc[]
include::start/chapter.adoc[]
include::modules/chapter.adoc[]
include::deploy/chapter.adoc[]
include::protocols/chapter.adoc[]
include::keystore/chapter.adoc[]
include::modules/chapter.adoc[]
include::xml/chapter.adoc[]
include::sessions/chapter.adoc[]
include::quickstart/chapter.adoc[]

14
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/chapter.adoc
View File

@ -12,15 +12,5 @@
//
include::modules.adoc[]
include::module-bytebufferpool.adoc[]
include::module-deploy.adoc[]
include::module-http.adoc[]
include::module-http2.adoc[]
include::module-http2c.adoc[]
include::module-http-forwarded.adoc[]
include::module-https.adoc[]
include::module-server.adoc[]
include::module-ssl.adoc[]
include::module-ssl-reload.adoc[]
include::module-test-keystore.adoc[]
include::module-threadpool.adoc[]
include::modules-custom.adoc[]
include::modules-standard.adoc[]

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-bytebufferpool.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-bytebufferpool]]
==== Module `bytebufferpool`
===== Module `bytebufferpool`
The `bytebufferpool` module allows you to configure the server-wide `ByteBuffer` pool.
Pooling ``ByteBuffer``s results in less memory usage and less pressure on the Garbage Collector.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-deploy.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-deploy]]
==== Module `deploy`
===== Module `deploy`
The `deploy` module provides the deployment feature through a `DeploymentManager` component that watches a directory for changes (see xref:og-deploy[how to deploy web applications] for more information).

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http-forwarded.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-http-forwarded]]
==== Module `http-forwarded`
===== Module `http-forwarded`
The `http-forwarded` module provides support for processing the `Forwarded` HTTP header (defined in link:https://tools.ietf.org/html/rfc7239[RFC 7239]) and the now obsoleted `X-Forwarded-*` HTTP headers.

6
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-http]]
==== Module `http`
===== Module `http`
The `http` module provides the clear-text connector and support for the clear-text HTTP/1.1 protocol, and depends on the xref:og-module-server[`server` module].
@ -34,7 +34,7 @@ The number of threads that compete to accept connections -- default -1 (i.e. an
The number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value based on the number of cores).
[[og-module-http-acceptors]]
===== Configuration of Acceptors
====== Configuration of Acceptors
Accepting connections is a blocking operation, so a thread is blocked in the `accept()` call until a connection is accepted, and other threads are blocked on the lock acquired just before the `accept()` call.
@ -47,7 +47,7 @@ Servers that manage a very high number of connections that may (naturally) come
// TODO: expand on acceptors=0 and non-blocking accepts
[[og-module-http-selectors]]
===== Configuration of Selectors
====== Configuration of Selectors
Performing a NIO `select()` call is a blocking operation, where the selecting thread is blocked in the `select()` call until at least one connection is ready to be processed for an I/O operation.
There are 4 I/O operations: ready to be accepted, ready to be connected, ready to be read and ready to be written.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http2.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-http2]]
==== Module `http2`
===== Module `http2`
The `http2` module enables support for the secure HTTP/2 protocol.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http2c.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-http2c]]
==== Module `http2c`
===== Module `http2c`
The `http2c` module enables support for the clear-text HTTP/2 protocol.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-https.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-https]]
==== Module `https`
===== Module `https`
The `https` module provides the HTTP/1.1 protocol to the xref:og-module-ssl[`ssl` module].

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-jmx-remote.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-jmx-remote]]
==== Module `jmx-remote`
===== Module `jmx-remote`
The `jmx-remote` module provides remote access to JMX clients.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-server]]
==== Module `server`
===== Module `server`
The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl-reload.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-ssl-reload]]
==== Module `ssl-reload`
===== Module `ssl-reload`
The `ssl-reload` module provides a periodic scanning of the directory where the KeyStore file resides.
When the scanning detects a change to the KeyStore file, the correspondent `SslContextFactory.Server` component is reloaded with the new KeyStore configuration.

6
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc
View File

@ -12,12 +12,12 @@
//
[[og-module-ssl]]
==== Module `ssl`
===== Module `ssl`
The `ssl` module provides the secure connector, and allows you to configure the KeyStore properties and the TLS parameters, and depends on the xref:og-module-server[`server` module].
[[og-module-ssl-connector]]
===== Secure Connector Properties
====== Secure Connector Properties
The module properties to configure the secure connector are:
@ -45,7 +45,7 @@ include::{JETTY_HOME}/modules/ssl.mod[tags=documentation-ssl-context]
----
[[og-module-ssl-keystore-tls]]
===== KeyStore Properties and TLS Properties
====== KeyStore Properties and TLS Properties
Among the configurable properties, the most relevant are:

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-test-keystore]]
==== Module `test-keystore`
===== Module `test-keystore`
The `test-keystore` module creates on-the-fly a KeyStore containing a self-signed certificate for domain `localhost`.
The KeyStore file is automatically deleted when the JVM exits, and re-created when you restart Jetty, to enforce the fact that it is a _test_ KeyStore that should not be reused if not for testing.

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc
View File

@ -12,7 +12,7 @@
//
[[og-module-threadpool]]
==== Module `threadpool`
===== Module `threadpool`
The `threadpool` module allows you to configure the server-wide thread pool.

6
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-troubleshooting.adoc → documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-custom.adoc
View File

@ -11,7 +11,7 @@
// ========================================================================
//
[[startup-troubleshooting]]
=== Startup Troubleshooting
[[og-modules-custom]]
==== Custom Jetty Modules
[troubleshooting startup]
TODO

28
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/screen-empty-base.adoc → documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules-standard.adoc
View File

@ -11,18 +11,18 @@
// ========================================================================
//
[source,screen,subs="{sub-order}"]
....
[jetty]$ mkdir mybase
[jetty]$ cd mybase
[mybase]$ ls -la
total 0
drwxr-xr-x 2 staff staff 68 Jul 12 17:29 .
drwxr-xr-x 20 staff staff 680 Jul 12 17:29 ..
[[og-modules-standard]]
==== Standard Modules
[my-base]$ java -jar /path/to/jetty-home/start.jar
WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs]
java -jar start.jar --help # for more information
....
include::module-bytebufferpool.adoc[]
include::module-deploy.adoc[]
include::module-http.adoc[]
include::module-http2.adoc[]
include::module-http2c.adoc[]
include::module-http-forwarded.adoc[]
include::module-https.adoc[]
include::module-server.adoc[]
include::module-ssl.adoc[]
include::module-ssl-reload.adoc[]
include::module-test-keystore.adoc[]
include::module-threadpool.adoc[]

459
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc
View File

@ -12,28 +12,445 @@
//
[[og-modules]]
==== Jetty Modules
=== Jetty Modules
TODO
// Consider:
// * old_docs/gettingstarted/configuring/*.adoc
// * old_docs/startup/startup-modules.adoc
// * old_docs/startup/custom-modules.adoc
//
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.
[[og-modules-custom]]
==== Custom Jetty Modules
Every Jetty feature is provided by a Jetty module.
TODO
A Jetty module is defined in a `<name>.mod` file, where `<name>` is the module name (see also the xref:og-modules-names[section about module names]).
//The `[jpms]` section has the following format:
//
//[source, screen, subs="{sub-order}"]
//....
//[jpms]
//add-modules: <module name>(,<module name>)*
//patch-module: <module>=<file>(:<file>)*
//add-opens: <module>/<package>=<target-module>(,<target-module>)*
//add-exports: <module>/<package>=<target-module>(,<target-module>)*
//add-reads: <module>=<target-module>(,<target-module>)*
//....
Jetty module files are read from the typical xref:og-start-configure[configuration source directories], under the `modules/` subdirectory; from higher priority to lower priority:
* The `$JETTY_BASE/modules/` directory.
* If a directory is specified with the `--include-jetty-dir` option, its `modules/` subdirectory.
* The `$JETTY_HOME/modules/` directory.
The standard Jetty modules that Jetty provides out-of-the-box are under `$JETTY_HOME/modules/`.
xref:og-modules-custom[Custom Jetty modules] should be put under `$JETTY_BASE/modules/`.
[[og-modules-names]]
==== Module Names
A Jetty module has a unique name.
The module name is by default derived from the file name, so module file `acme.mod` identifies a module named `acme`.
However, a module file may specify a xref:og-modules-directive-provides[+[provides]+] directive for a _virtual_ module, so that many modules may provide a different implementation for the same feature.
For example, among the standard modules provided by Jetty, the `server` module depends on the `logging` module, but there is no correspondent `logging.mod` file.
However, the `logging-jetty.mod` file has, among others, this section:
.logging-jetty.mod
----
[provides]
logging|default
----
This section means that the `logging-jetty.mod` file provides the virtual module `logging`, and it is the default provider.
The `logging-log4j2.mod` file has a similar section:
.logging-log4j2.mod
----
[provides]
logging
----
If there are no enabled modules that provide the `logging` virtual module, either explicitly or transitively, then the default provider is used, in this case `logging-jetty.mod`.
Otherwise, a module that provides the `logging` virtual module is explicitly or transitively enabled, and the default provider is not used.
[[og-modules-components]]
==== Module Components
A Jetty module may provide one or more Java components that implement a feature.
These Java components are nothing more than regular Java classes that are instantiated and configured via xref:og-xml[Jetty XML] files.
The Jetty XML file of a Jetty module may instantiate and assemble together its own components, or reference existing components from other Jetty modules to enhance or reconfigure them.
The Jetty module's XML files are read from the typical xref:og-start-configure[configuration source directories], under the `etc/` subdirectory; from higher priority to lower priority:
* The `$JETTY_BASE/etc/` directory.
* If a directory is specified with the `--include-jetty-dir` option, its `etc/` subdirectory.
* The `$JETTY_HOME/etc/` directory.
The standard Jetty modules XML files that Jetty provides out-of-the-box are under `$JETTY_HOME/etc/`.
For example, a Jetty XML file that allocates Jetty's `QueuedThreadPool` could be as simple as:
[source,xml]
.jetty-threadpool.xml
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure>
<New id="threadPool" class="org.eclipse.jetty.util.thread.QueuedThreadPool">
<Set name="maxThreads" type="int">
<Property name="jetty.threadPool.maxThreads" default="256"/>
</Set>
</New>
</Configure>
----
Note how the Jetty XML file above is allocating (with the `<New>` element) a `QueuedThreadPool` instance, giving it the unique `id` of `threadPool` (so that other modules can reference it, if they need to).
It is then calling the setter method `QueuedThreadPool.setMaxThreads(int)` with the value defined by the xref:og-modules-properties[module property] `jetty.threadPool.maxThreads`; if the property value is not defined, it will have the default value of `256`.
This is nothing more than Java code in XML format with configurable properties support that can be leveraged by the xref:og-start[Jetty start mechanism].
The Jetty module's XML files make easy to instantiate and assemble Java components (just write the equivalent Java code in XML format), and make easy to configure them by declaring module properties that can be easily customized elsewhere (for example, in `+*.ini+` files as described in xref:og-start-configure-enable[this section], or on the command line as described in xref:og-start-start[this section]).
[IMPORTANT]
====
Remember that the standard Jetty XML files in `$JETTY_HOME/etc/` should not be modified.
Even if you need to modify a standard Jetty component, write a new Jetty XML file, save it under `$JETTY_BASE/etc/`, and create a xref:og-modules-custom[custom Jetty module] so that it gets processed when Jetty starts.
====
[[og-modules-properties]]
==== Module Properties
A Jetty module property is declared in the xref:og-modules-components[module XML file(s)] via the `<Property>` element.
Modules properties are used to parametrize Jetty components so that you can customize their values when Jetty starts, rather than hard-coding it in the XML files.
NOTE: You can declare your own properties, but the `+jetty.*+` namespace is reserved.
A module property can be given a value in a Jetty module `[ini]` section (see xref:og-modules-directive-ini[here]), in a `+*.ini+` file as described in xref:og-start-configure-enable[this section], or on the command line as described in xref:og-start-start[this section].
The syntax to specify a property value is the following:
<name>=<value>::
Sets the property value unconditionally.
<name>+=<value>::
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:
+
----
jetty.webapp.addServerClasses+=,com.acme
----
+
<name>?=<value>::
Sets the property value only if it is not already set.
This is useful to define default values, for example for "version" properties, where the "version" property can be explicitly configured to a newer version, but if it is not explicitly configured it will have a default version (see also xref:og-start-configure-custom-module[here]).
For example:
+
----
conscrypt.version?=2.5.1
jetty.sslContext.provider?=Conscrypt
----
[[og-modules-directives]]
==== Module Directives
Lines that start with `#` are comments.
[[og-modules-directive-description]]
===== [description]
A text that describes the module.
This text will be shown by the xref:og-start-configure[Jetty start mechanism] when using the `--list-modules` command.
[[og-modules-directive-tags]]
===== [tags]
A list of words that characterize the module.
Modules that have the same tags will be shown by the Jetty start mechanism when using the `--list-modules=<tag>` command.
.example.mod
----
[tags]
demo
webapp
jsp
----
[[og-modules-directive-provides]]
===== [provides]
A module name with an optional `default` specifier.
As explained in the xref:og-modules-names[module name section], there can be many module files each providing a different implementation for the same feature.
The format is:
----
[provides]
<module_name>[|default]
----
where the `|default` part is optional and specifies that the module is the default provider.
[[og-modules-directive-depends]]
===== [depends]
A list of module names that this module depends on.
For example, the standard module `http` depends on module `server`.
Enabling the `http` module also enables, transitively, the `server` module, since the `http` module cannot work without the `server` module; when the `server` module is transitively enabled, the modules it depends on will be transitively enabled, and so on recursively.
The `[depends]` directive establishes a link:https://en.wikipedia.org/wiki/Partially_ordered_set[_partial order_] relationship among modules so that enabled modules can be sorted and organized in a graph.
Circular dependencies are not allowed.
The order of the enabled modules is used to determine the processing of the configuration, for example the order of processing of the xref:og-modules-directive-files[+[files]+] section, the order of processing of XML files defined in the xref:og-modules-directive-xml[+[xml]+] section, etc.
[[og-modules-directive-optional]]
===== [optional]
A list of module names that this module depends on, if they are explicitly enabled.
For example, the module `https` has an optional dependency on `http2`.
Enabling the `https` modules _does not_ enable the `http2` module.
However, if the `http2` module is explicitly enabled, then the `https` module depends on it, and therefore the `http2` module is xref:og-modules-directive-depends[sorted] _before_ the `https` module.
In this way, you are guaranteed that the `http2` module is processed before the `https` module.
[[og-modules-directive-files]]
===== [files]
A list of paths (directories and/or files) that are necessary for the module, created or resolved when the module is enabled.
Each path may be of the following types:
Path Name::
A path name representing a file, or a directory if the path name ends with `/`, such as `webapps/`.
The file or directory will be created relative to `$JETTY_BASE`, if not already present.
+
For example:
+
----
[files]
logs/
----
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:
+
----
[files]
maven://<groupId>/<artifactId>/<version>[/<type>]|<pathName>
----
+
where `<type>` is optional, and `<pathName>` after the `|` is the path under `$JETTY_BASE` where the downloaded file should be saved.
+
For example:
+
[source,options=nowrap]
----
[files]
maven://org.postgresql/postgresql/${postgresql-version}|lib/postgresql-${postgresql-version}.jar
----
BaseHome::
An URI representing a `$JETTY_HOME` resource to be copied in `$JETTY_BASE`, if not already present.
URIs of this type are typically only used by standard Jetty modules; custom modules should not need to use it.
+
The format is:
+
----
[files]
basehome:<jettyHomePathName>|<pathName>
----
+
For example:
+
----
[files]
basehome:modules/demo.d/demo-moved-context.xml|webapps/demo-moved-context.xml
----
HTTP URL::
An `http://` or `https://` URL to be downloaded, if not already present.
+
The format is:
+
----
[files]
<httpURL>|<pathName>
----
+
For example:
+
----
[files]
https://acme.com/favicon.ico|webapps/acme/favicon.ico
----
[[og-modules-directive-libs]]
===== [libs]
A list of paths, relative to the xref:og-start-configure[configuration source directories], of `+*.jar+` library files and/or directories that are added to the server class-path (or module-path when xref:og-start-start-jpms[running in JPMS mode]).
The `[libs]` section if often used in conjunction with the `[files]` section.
For example:
----
[files]
maven://org.postgresql/postgresql/${postgresql-version}|lib/postgresql-${postgresql-version}.jar
[libs]
lib/postgresql-${postgresql-version}.jar
----
The `postgresql-<version>.jar` artifact is downloaded from Maven Central, if not already present, into the `$JETTY_BASE/lib/` directory when the module is enabled.
When Jetty starts, the `$JETTY_BASE/lib/postgresql-<version>.jar` will be in the server class-path (or module-path).
[[og-modules-directive-xml]]
===== [xml]
A list of paths, relative to the xref:og-start-configure[configuration source directories], of Jetty `+*.xml+` files that are passed as program arguments to be processed when Jetty starts (see the xref:og-start-start-xml[section about assembling Jetty components]).
Jetty XML files are read from the typical xref:og-start-configure[configuration source directories], under the `etc/` subdirectory.
Standard Jetty XML files are under `$JETTY_HOME/etc/`, while custom Jetty XML files are typically under `$JETTY_BASE/etc/`.
For example:
----
[xml]
etc/custom/components.xml
----
[[og-modules-directive-ini]]
===== [ini]
A list of program arguments to pass to the command line when Jetty is started.
The program arguments may include any command line option (see xref:og-start-reference[here] for the list of command line options), xref:og-modules-properties[module properties] and/or xref:og-modules-components[module XML files].
A property defined in the `[ini]` section is available in the `+*.mod+` module file for property expansion, for example:
----
[ini]
postgresql-version?=42.2.18
[lib]
lib/postgresql-${postgresql-version}.jar
----
In the example above, the `[lib]` section contains `${postgresql-version}`, a reference to property `postgresql-version` whose value is defined in the `[ini]` section.
The expression `${<property>}` _expands_ the property replacing the expression with the property value.
See also the xref:og-start-start-jpms[JPMS section] for additional examples about the `[ini]` section.
[[og-modules-directive-ini-template]]
===== [ini-template]
A list of properties to be copied in the `+*.ini+` file generated when xref:og-start-configure-enable[the module is enabled].
The list of properties is derived from the xref:og-modules-components[module XML file(s)] that declare them.
The properties are typically assigned their default value and commented out, so that it is evident which properties have been uncommented and customized with a non-default value.
[[og-modules-directive-exec]]
===== [exec]
A list of JVM command line options and/or system properties passed to a forked JVM.
When the `[exec]` section is present, the JVM running the Jetty start mechanism will fork another JVM, passing the JVM command line options and system properties listed in the `[exec]` sections of the enabled modules.
This is necessary because JVM options such as `-Xmx` (that specifies the max JVM heap size) cannot be changed in a running JVM.
For an example, see xref:og-start-configure-custom-module-exec[this section].
[[og-modules-directive-jpms]]
===== [jpms]
A list of JVM command line options related to the Java Module System.
This section is processed only when Jetty is xref:og-start-start-jpms[started in JPMS mode].
The directives are:
add-modules::
Equivalent to the JVM option `--add-modules`.
The format is:
+
----
[jpms]
add-modules: <module>(,<module>)*
----
+
where `module` is a JPMS module name.
patch-module::
Equivalent to the JVM option `--patch-module`.
The format is:
+
----
[jpms]
patch-module: <module>=<file>(:<file>)*
----
where `module` is a JPMS module name.
add-opens::
Equivalent to the JVM option `--add-opens`.
The format is:
+
----
[jpms]
add-opens: <module>/<package>=<target-module>(,<target-module>)*
----
where `module` and `target-module` are a JPMS module names.
add-exports::
Equivalent to the JVM option `--add-exports`.
The format is:
+
----
[jpms]
add-exports: <module>/<package>=<target-module>(,<target-module>)*
----
where `module` and `target-module` are a JPMS module names.
add-reads::
Equivalent to the JVM option `--add-exports`.
The format is:
+
----
[jpms]
add-reads: <module>=<target-module>(,<target-module>)*
----
where `module` and `target-module` are a JPMS module names.
[[og-modules-directive-license]]
===== [license]
The license under which the module is released.
A Jetty module may be released under a license that is different from Jetty's, or use libraries that require end-users to accept their licenses in order to be used.
You can put the license text in the `[license]` section, and when the Jetty module is enabled the license text will be printed on the terminal, and the user prompted to accept the license.
If the user does not accept the license, the module will not be enabled.
For example:
----
[license]
Acme Project is an open source project hosted on GitHub
and released under the Apache 2.0 license.
https://www.apache.org/licenses/LICENSE-2.0.txt
----
[[og-modules-directive-version]]
===== [version]
The minimum Jetty version for which this module is valid.
For example, a module may only be valid for Jetty 10 and later, but not for earlier Jetty versions (because it references components that have been introduced in Jetty 10).
For example:
----
[version]
10.0
----
A Jetty module with such a section will only work for Jetty 10.0.x or later.

17
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc
View File

@ -21,6 +21,9 @@ Within the Jetty start mechanism, the source of configurations is layered in thi
* The directory specified with the `--include-jetty-dir` option, and its files.
* The `$JETTY_HOME` directory, and its files.
[[og-start-configure-enable]]
===== Enabling Modules
You can enable Jetty modules with the `--add-modules` command:
----
@ -40,10 +43,7 @@ The content of these `+*.ini+` files is copied from the `[ini-template]` section
This may simply create a file or a directory, or download files from the Internet.
This step is performed transitively for all module dependencies.
The fact that there exist a `+$JETTY_BASE/start.d/*.ini+` file means that the module is enabled.
To disable the module, simply delete the `+$JETTY_BASE/start.d/*.ini+` file.
In the example above, enabling the `server` and `http` modules results in the `$JETTY_BASE` directory to have the following structure:
For example, enabling the `server` and `http` modules results in the `$JETTY_BASE` directory to have the following structure:
----
$JETTY_BASE
@ -56,6 +56,15 @@ $JETTY_BASE
The `$JETTY_BASE/resources/jetty-logging.properties` is created by the `[files]` directives of the `logging-jetty` module, which is a transitive dependency of the `server` module.
[[og-start-configure-disable]]
===== Disabling Modules
A module is enabled because the correspondent `+$JETTY_BASE/start.d/*.ini+` file contains a `--module=<name>` directive.
Commenting out the `--module=<name>` directive effectively disables the module.
Deleting the correspondent `+$JETTY_BASE/start.d/*.ini+` file also disables the module.
[[og-start-configure-edit-ini]]
===== Editing `+*.ini+` Files

6
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-jpms.adoc
View File

@ -45,11 +45,9 @@ Create the `$JETTY_BASE/modules/jpms.mod` file:
include::jpms.mod[]
----
The `[ini]` section with `--jpms` is equivalent to passing the `--jpms` option to the command line.
The `[ini]` section with `--jpms` is equivalent to passing the `--jpms` option to the command line (see also xref:og-modules-directive-ini[this section]).
The `[jpms]` section allows you to specify additional JPMS configuration, for example additional `--add-modules` options, or `--add-opens` options, etc.
// TODO: add a link to the custom module section and the [jpms] section in there, see old_docs/startup/startup-jpms.adoc.
The `[jpms]` section allows you to specify additional JPMS configuration, for example additional `--add-modules` options, or `--add-opens` options, etc. (see also xref:og-modules-directive-jpms[this section]).
Then enable it:

16
documentation/jetty-documentation/src/main/asciidoc/styles.css Normal file
View File

@ -0,0 +1,16 @@
/*
* ========================================================================
* Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0 which is available at
* https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
* which is available at https://www.apache.org/licenses/LICENSE-2.0.
*
* SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
* ========================================================================
*/
.listingblock > .title {
font-style: normal;
}

2
documentation/jetty-documentation/src/main/asciidoc/toc.css
View File

@ -14,7 +14,7 @@
.hidden {
display: none;
}
.toc-current {
.toc-current, .toc-current * {
font-weight: bold;
}
.toc-item {

15
documentation/jetty-documentation/src/main/asciidoc/toc.js
View File

@ -18,14 +18,14 @@ function dynamicTOC() {
// Bind a click listener to all section titles.
const sectionTitles = content.querySelectorAll('a.link');
for (const sectionTitle of sectionTitles) {
sectionTitle.addEventListener('click', event => collapseThenExpand(event.target.hash));
sectionTitle.addEventListener('click', event => collapseThenExpand(hash(event.target)));
}
// Bind a click listener to all inline links to documentation sections.
const inlineLinks = content.querySelectorAll('p > a');
for (const inlineLink of inlineLinks) {
const hash = inlineLink.hash || '';
if (hash.startsWith('#')) {
inlineLink.addEventListener('click', event => collapseThenExpand(event.target.hash));
const linkHash = inlineLink.hash || '';
if (linkHash.startsWith('#')) {
inlineLink.addEventListener('click', event => collapseThenExpand(hash(event.target)));
}
}
@ -33,7 +33,7 @@ function dynamicTOC() {
const toc = document.getElementById('toc');
const tocTitles = toc.querySelectorAll('a');
for (const tocTitle of tocTitles) {
tocTitle.addEventListener('click', event => collapseThenExpand(event.target.hash));
tocTitle.addEventListener('click', event => collapseThenExpand(hash(event.target)));
}
// Add the icons to TOC nodes.
@ -58,6 +58,11 @@ function dynamicTOC() {
collapseThenExpand(document.location.hash);
}
function hash(element) {
const a = element.closest('a');
return a ? a.hash : null;
}
function collapseThenExpand(hash) {
const toc = document.getElementById('toc');
if (hash) {

45
jetty-start/src/main/resources/org/eclipse/jetty/start/usage.txt
View File

@ -18,22 +18,22 @@ Report Commands:
dependent jars, then exits.
--list-classpath
Prints the classpath information that will be used to
start Jetty.
Prints the class-path (or module-path) information that
will be used to start Jetty.
--list-config
Lists the resolved configuration that will be used to
start Jetty.
Output includes:
o Enabled jetty modules
o Java Environment
o Jetty Environment
o Enabled Jetty modules
o Java environment
o Jetty environment
o Config file search order
o JVM Arguments
o System Properties
o JVM arguments
o System properties
o Properties
o Java Classpath
o XML Configuration files
o Java class-path or module-path
o XML configuration files
--list-modules
Lists the modules defined in ${jetty.base}/modules/*.mod
@ -75,7 +75,7 @@ Report Commands:
Configure Commands:
-------------------
--add-modules=<modulename>(,<modulename>)*
--add-modules=<moduleName>(,<moduleName>)*
Adds the given modules to the list of modules enabled at
when Jetty starts.
Transitive dependencies are followed and dependent
@ -133,7 +133,7 @@ Configure Commands:
Options:
--------
--module=<modulename>(,<modulename>)*
--module=<moduleName>(,<moduleName>)*
Enables a module for this execution.
To enable a module for all future executions, use the
--add-modules command.
@ -142,8 +142,8 @@ Options:
the --add-modules command.
--lib=<classpath>
Adds the specified classpath entries to the the server
classpath.
Adds the specified class-path entries to the the server
class-path (or module-path).
--download=<http-uri>|<location>
Downloads a file from the given HTTP URI, if it does
@ -153,8 +153,8 @@ Options:
some shell environments.
--exec
Executes the generated command line (see --dry-run) in
a sub process.
Executes the generated command line in a forked JVM
(see the --dry-run command).
This can be used when ${jetty.base}/start.d/*.ini files
contain -D, -X or -XX arguments, but creates an extra
JVM process.
@ -169,6 +169,15 @@ Options:
Uses each line of the specified file as arguments on the
JVM command line.
--jpms
Starts Jetty in JPMS mode in a forked JVM (see also the
--dry-run command).
The library *.jar files are set on the forked JVM module-path
(rather than the forked JVM class-path), while directories
are set on the forked JVM class-path.
The main class is specified with the JPMS option
--module <moduleName>/<mainClassName>.
--debug
Enables debug output of the startup execution.
Note: this does not setup debug logging for Jetty itself,
@ -188,7 +197,7 @@ Options:
Useful for enabling modules from a script, so that it
does not require user interaction.
--skip-file-validation=<modulename>(,<modulename>)*
--skip-file-validation=<moduleName>(,<moduleName>)*
Disables the creation of files as specified by the
[files] section of the specified modules.
Useful if a logging module specifies a *.properties
@ -241,11 +250,11 @@ Options:
or in the [ini] section of a *.mod file.
<name>=<value>
Sets the property unconditionally.
Sets the property value unconditionally.
<name>+=<value>
Appends the given value to the existing value.
<name>?=<value>
Sets the property only if it is not already set.
Sets the property value only if it is not already set.
-D<name>=<value>
Specifies a system property, as well as a start property.