![]() Version: 9.4.30.v20200611 |
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development
In addition to the modules that come packaged with the Jetty distribution, users are able to create and define their own custom modules for use with their Jetty implementation. Custom modules can be used for a number of reasons - they can extend features in Jetty, add new features, manage additional libraries available to the server…etc.
At the heart of a Jetty module is the {name}.mod file itself.
A jetty .mod file defines the following:
It is important to note that when creating your own module, none of these sections are required - simply use those which are applicable to your implementation.
[description].mod file itself or using the --list-modules command.[depend]All modules can declare that they depend on other modules with the [depend] section.
The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate.
The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations.
[optional][optional] used to describe structurally dependent modules that are not technically required, but might be of use to your specific configuration.[lib][lib] section declares a set of pathnames that follow the Jetty Base and Jetty Home path resolution rules.[xml][xml] section declares a set of pathnames that follow the Jetty Base and Jetty Home path resolution rules.
Ideally, all XML files are parameterized to accept properties to configure the various elements of the standard configuration.
Allowing for a simplified configuration of Jetty for the vast majority of deployments.
The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the [depend] sections.
If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the ${jetty.base}/etc/ directory, with the same name.
The resolution steps for Jetty Base and Jetty Home will ensure that your copy from ${jetty.base} will be picked up over the default one in ${jetty.home}.[tags]--list-modules command, modules will be groups by the first tag that exists in this section.
Modules can also be listed specifically by these tags using --list-modules=<tag name> on the command line.[ini][ini] section is used to add or change server parameters at startup.
The [ini] section can also include a the path of a file or several files which should be made available to the server only.
This is helpful when you want to control what jars are available to deployed webapps.[ini-template]start.ini or start.d/*.ini files when using the --add-to-start=<name> command line argument in start.jar.
Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.[files]If the activation of a module requires some paths to exist, the [files] section defines them.
There are 2 modes of operation of the entries in this section.
"/" (slash), such as "webapps/", then that directory will be created if it does not yet exist in ${jetty.base}/<pathname> (eg: "webapps/" will result in ${jetty.base}/webapps/ being created).<url>:<pathname>.
Currently, the <url> must be a http:// scheme URL (please let us know if you need more schemes supported).
The <pathname> portion follows the Jetty Base and Jetty Home path resolution rules.
Example: http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar
This will check for the existence of lib/corp-security-policy.jar, and if it doesn’t exist, it will download the jar file from http://repo.corp.com/maven/corp-security-policy-1.0.jar[license][exec][exec] section is used to define additional parameters specific to the module.
These commands are added to the server startup.[jpms][jpms] section is used to add JPMS modules to the module-path for startup when using the --jpms command.Properties are used to parameterize:
<Property name="pname"/> element${pname} syntaxProperties and System Properties may be set on the command line, in a ini file or in a [ini] section of a module using the following syntax.
name=valuename+=valuename+=,valuename?=valueIf any of the previous formats is preceded by -D, then a system property is set as well as a start property.
Jetty comes with dozens of modules as part of the distribution package.
By default these are located in the ${JETTY_HOME}/modules directory.
These modules should not be modified.
In the unlikely circumstance you need to make changes to a stock module, copy it to your ${JETTY_BASE} in a modules directory.
Custom modules should also be maintained separately as part of the ${JETTY_BASE}/modules directory, though you can optionally place them in ${JETTY_HOME}/modules for convenience if you have several {$JETTY_BASE} locations in your implementation.
As shown above, there are several options that can be utilized when creating custom module files. This may seem daunting, but the good news is that creating custom modules is actually quite easy.
For example, here is a look at the http.mod file which defines parameters for enabling HTTP features for the server:
DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html [description] Enables an 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 ## 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 ## The requested maximum length of the queue of incoming connections. # jetty.http.acceptQueueSize=0 ## Enable/disable the SO_REUSEADDR socket option. # jetty.http.reuseAddress=true ## Enable/disable TCP_NODELAY on accepted sockets. # jetty.http.acceptedTcpNoDelay=true ## The SO_RCVBUF option to set on accepted sockets. A value of -1 indicates that it is left to its default value. # jetty.http.acceptedReceiveBufferSize=-1 ## The SO_SNDBUF option to set on accepted sockets. A value of -1 indicates that it is left to its default value. # jetty.http.acceptedSendBufferSize=-1 ## Connect Timeout in milliseconds # jetty.http.connectTimeout=15000 ## HTTP Compliance: RFC7230, RFC7230_LEGACY, RFC2616, RFC2616_LEGACY, LEGACY or CUSTOMn # jetty.http.compliance=RFC7230_LEGACY
You’ll notice that the http.mod file only includes a handful of the possible sections available - [description], [tags], [depend], [xml], and [ini-template].
When configuring your own modules, you are free to pick and choose what you include.
As an example, below is a module file that defines a custom XML and lib, and activates a number of additional modules. A module like this could be used to enable a set of standard modules and resources for a new JETTY_BASE without having to define them all manually.
[description] Enables the standard set of modules and resources for ACME Corp servers. [tags] core [depend] server client http http2 jsp console-capture requestlog stats gzip deploy jmx [files] basehome:modules/acme/acme.xml|etc/acme.xml [lib] lib/acme/ACMECustom.jar
Activating this module will activate all the dependent modules, create any required directories and copy in any required files:
java -jar ../start.jar --add-to-start=acme
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: alpn-impl/alpn-8
+ ALPN is a hosted at github under the GPL v2 with ClassPath Exception.
+ ALPN replaces/modifies OpenJDK classes in the sun.security.ssl package.
+ http://github.com/jetty-project/jetty-alpn
+ http://openjdk.java.net/legal/gplv2+ce.html
Proceed (y/N)? y
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : requestlog transitively enabled, ini template available with --add-to-start=requestlog
INFO : alpn transitively enabled, ini template available with --add-to-start=alpn
INFO : jsp transitively enabled
INFO : servlet transitively enabled
INFO : alpn-impl/alpn-8 dynamic dependency of alpn
INFO : annotations transitively enabled
INFO : gzip transitively enabled, ini template available with --add-to-start=gzip
INFO : ssl transitively enabled, ini template available with --add-to-start=ssl
INFO : plus transitively enabled
INFO : deploy transitively enabled, ini template available with --add-to-start=deploy
INFO : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8
INFO : security transitively enabled
INFO : jmx transitively enabled
INFO : apache-jsp transitively enabled
INFO : stats transitively enabled, ini template available with --add-to-start=stats
INFO : acme initialized in ${jetty.base}/start.d/acme.ini
INFO : jndi transitively enabled
INFO : console-capture transitively enabled, ini template available with --add-to-start=console-capture
INFO : client transitively enabled
INFO : http transitively enabled, ini template available with --add-to-start=http
INFO : http2 transitively enabled, ini template available with --add-to-start=http2
MKDIR : ${jetty.base}/logs
MKDIR : ${jetty.base}/lib
MKDIR : ${jetty.base}/lib/alpn
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
MKDIR : ${jetty.base}/webapps
DOWNLD: https://repo1.maven.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.8.v20160420/alpn-boot-8.1.8.v20160420.jar to ${jetty.base}/lib/alpn/alpn-boot-8.1.8.v20160420.jar
COPY : ${jetty.home}/modules/acme/acme.xml to ${jetty.base}/etc/acme.xml
INFO : Base directory was modifiedWhen dependent modules are enabled, they are done so transitively by default.
This means that any ini files for dependent modules are not created in the ${JETTY_BASE}/start.d directory (or added to ${JETTY_BASE}/start.ini) and are as such not configurable.
For Jetty to create/add the ini-template parameters to start.d or start.ini the associated module must be enabled explicitly.
For example, if I activate the http module, it will be enabled, and the server module will be enabled transitively:
$ java -jar ../start.jar --add-to-start=http
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : http initialized in ${jetty.base}/start.d/http.ini
INFO : Base directory was modifiedYou’ll notice that Jetty informs you of what modules were enabled, and where there associated ini files are located (when applicable).
It also tells the user what command they would need to run to enable any missing or desired ini files for the selected modules, in this case --add-to-start=server.
$ java -jar ../start.jar --add-to-start=server
INFO : server initialized in ${jetty.base}/start.d/server.ini
INFO : Base directory was modifiedNote
It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down. If a dependent module also has dependencies they too will be enabled.