Jetty Logo
Version: 9.3.14.v20161028
Contact the core Jetty developers at www.webtide.com

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

Managing Startup Modules

Enabling Modules
Configuring Modules
Disabling Modules
Listing Available and Active Modules

Starting with Jetty 9.1, a new Module system was introduced, replacing the previous start.config + OPTIONS techniques from past Jetty Distributions.

The standard Jetty Distribution ships with several modules defined in ${jetty.home}/modules/.

What a Jetty Startup Module Defines:

A Module Name
The name of the module is the keyword used by the --module=<name> command line argument to activate/enable modules, and also find dependent modules. The filename of the module defines its name (eg: server.mod becomes the module named "server").
List of Dependant Modules
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. Of note: there is a special section [optional] used to describe structurally dependent modules that are not technically required, but might be of use to your specific configuration.
List of Libraries
Module can optionally declare that they have libraries that they need to function properly. The [lib] section declares a set of pathnames that follow the Jetty Base and Jetty Home path resolution rules.
List of Jetty IoC XML Configurations
A Module can optionally declare a list of Jetty IoC XML configurations used to wire up the functionality that this module defines. The [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}.
Jetty INI Template
Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the start.ini or start.d/*.ini files when using the --add-to-start=<name> or --add-to-startd=<name> command line arguments 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. The [ini-template] section declares this section of sample configuration.
Required Files and Directories

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.

Ensure Directory Exists
If you add a pathname that ends in "/" (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).
Download File
There is a special syntax to allow you to download a file into a specific location if it doesn’t exist yet: <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

Enabling Modules

Jetty ships with many modules defined, and a small subset predefined in the start.ini found in the jetty distribution.

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 Jetty Base vs Jetty Home and take full advantage of this setup.

When you want enable a module, you can use the --module=<modulename> syntax on the command line to enable that module and all of its dependent modules.

An example of this, with a new, empty, base directory. We can see from this output, that the directory is new.

[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 ..

[mybase]$ java -jar $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

Lets see what the configuration looks like so far:

[mybase]$ java -jar /opt/jetty-distribution/start.jar --list-config

Java Environment:
-----------------
 java.home = /lib/jvm/jdk-8u92/jre
 java.vm.vendor = Oracle Corporation
 java.vm.version = 25.45-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 = /tmp
 user.dir = /home/jetty/mybase
 user.language = en
 user.country = US

Jetty Environment:
-----------------
 jetty.version = 9.3.14.v20161028
 jetty.home = /opt/jetty-distribution
 jetty.base = /home/jetty/mybase

Config Search Order:
--------------------
 <command-line>
 ${jetty.base} -> /home/jetty/mybase
 ${jetty.home} -> /opt/jetty-distribution


JVM Arguments:
--------------
 (no jvm args specified)

System Properties:
------------------
 (no system properties specified)

Properties:
-----------
 (no properties specified)

Jetty Server Classpath:
-----------------------
No classpath entries and/or version information available show.

Jetty Active XMLs:
------------------
 (no xml files specified)

Lets try adding some basic support for webapps, with automatic deploy (hot deploy), and a single basic HTTP/1.1 connector.

[mybase]$ java -jar /opt/jetty-distribution/start.jar --add-to-start=http,webapp,deploy

INFO: server          initialised (transitively) in ${jetty.base}/start.ini
INFO: http            initialised in ${jetty.base}/start.ini
INFO: security        initialised (transitively) in ${jetty.base}/start.ini
INFO: servlet         initialised (transitively) in ${jetty.base}/start.ini
INFO: webapp          initialised in ${jetty.base}/start.ini
INFO: deploy          initialised in ${jetty.base}/start.ini
MKDIR: ${jetty.base}/webapps
INFO: Base directory was modified

This created 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 and added their module ini template properties.

Lets see what it looks like configuration wise.

[mybase]$ java -jar /opt/jetty-distribution/start.jar --list-config

Java Environment:
-----------------
 java.home = /lib/jvm/jdk-8u31-x64/jre
 java.vm.vendor = Oracle Corporation
 java.vm.version = 25.31-b07
 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_31-b13
 java.io.tmpdir = /tmp
 user.dir = /home/jetty/mybase
 user.language = en
 user.country = US

Jetty Environment:
-----------------
 jetty.version = 9.3.14.v20161028
 jetty.home = /opt/jetty-distribution
 jetty.base = /home/jetty/mybase

Config Search Order:
--------------------
 <command-line>
 ${jetty.base} -> /home/jetty/mybase
 ${jetty.home} -> /opt/jetty-distribution


JVM Arguments:
--------------
 (no jvm args specified)

System Properties:
------------------
 (no system properties specified)

Properties:
-----------
 jetty.http.port = 8080

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/servlet-api-3.1.jar
 1:                 3.1.0.M0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
 2:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-http-9.3.14.v20161028.jar
 3:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-server-9.3.14.v20161028.jar
 4:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-xml-9.3.14.v20161028.jar
 5:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-util-9.3.14.v20161028.jar
 6:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-io-9.3.14.v20161028.jar
 7:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-security-9.3.14.v20161028.jar
 8:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-servlet-9.3.14.v20161028.jar
 9:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-webapp-9.3.14.v20161028.jar
10:           9.3.14.v20161028 | ${jetty.home}/lib/jetty-deploy-9.3.14.v20161028.jar

Jetty Active XMLs:
------------------
 ${jetty.home}/etc/jetty.xml
 ${jetty.home}/etc/jetty-http.xml
 ${jetty.home}/etc/jetty-deploy.xml

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.

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.

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:

# ---------------------------------------
# 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).

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.

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. Here’s an example:

[mybase]$ java -jar /opt/jetty-distribution/start.jar --list-modules

Jetty All Available Modules:
----------------------------

 [ ] Module: alpn
     Depend: ssl
     Depend: alpn-impl/alpn-${java.version}
        LIB: lib/jetty-alpn-client-${jetty.version}.jar
        LIB: lib/jetty-alpn-server-${jetty.version}.jar
        XML: etc/jetty-alpn.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: protonego-boot
        Ref: alpn-impl/alpn-1.8.0_45
    Enabled: <not enabled in this configuration>

 [ ] Module: annotations
     Depend: plus
        LIB: lib/jetty-annotations-${jetty.version}.jar
        LIB: lib/annotations/*.jar
        XML: etc/jetty-annotations.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: apache-jsp
        LIB: lib/apache-jsp/*.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: apache-jstl
        LIB: lib/apache-jstl/*.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: cdi
     Depend: deploy
     Depend: annotations
     Depend: plus
     Depend: jsp
        LIB: lib/cdi/*.jar
        LIB: lib/cdi-core-${jetty.version}.jar
        LIB: lib/cdi-servlet-${jetty.version}.jar
        XML: etc/jetty-cdi.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: client
        LIB: lib/jetty-client-${jetty.version}.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: continuation
        LIB: lib/jetty-continuation-${jetty.version}.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: debuglog
     Depend: server
        XML: etc/jetty-debug.xml
    Enabled: <not enabled in this configuration>

 [x] Module: deploy
     Depend: webapp
        LIB: lib/jetty-deploy-${jetty.version}.jar
        XML: etc/jetty-deploy.xml
    Enabled: <via> ${jetty.base}/start.ini

 [ ] Module: ext
        LIB: lib/ext/**.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: fcgi
     Depend: servlet
     Depend: client
        LIB: lib/jetty-proxy-${jetty.version}.jar
        LIB: lib/fcgi/*.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: gzip
     Depend: server
        XML: etc/jetty-gzip.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: hawtio
     Depend: stats
     Depend: deploy
     Depend: jmx
        XML: etc/hawtio.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: home-base-warning
        XML: etc/home-base-warning.xml
    Enabled: <not enabled in this configuration>

 [x] Module: http
     Depend: server
        XML: etc/jetty-http.xml
    Enabled: <via> ${jetty.base}/start.ini

 [ ] Module: http2
     Depend: ssl
     Depend: alpn
        LIB: lib/http2/*.jar
        XML: etc/jetty-http2.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: http2c
     Depend: http
        LIB: lib/http2/*.jar
        XML: etc/jetty-http2c.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: https
     Depend: ssl
        XML: etc/jetty-https.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: infinispan
     Depend: annotations
     Depend: webapp
        LIB: lib/jetty-infinispan-${jetty.version}.jar
        LIB: lib/infinispan/*.jar
        XML: etc/jetty-infinispan.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: ipaccess
     Depend: server
        XML: etc/jetty-ipaccess.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jaas
     Depend: server
        LIB: lib/jetty-jaas-${jetty.version}.jar
        XML: etc/jetty-jaas.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jamon
     Depend: stats
     Depend: deploy
     Depend: jmx
     Depend: jsp
        LIB: lib/jamon/**.jar
        XML: etc/jamon.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jaspi
     Depend: security
        LIB: lib/jetty-jaspi-${jetty.version}.jar
        LIB: lib/jaspi/*.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: jdbc-sessions
     Depend: annotations
     Depend: webapp
        XML: etc/jetty-jdbc-sessions.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jminix
     Depend: stats
     Depend: jmx
        LIB: lib/jminix/**.jar
        XML: etc/jminix.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jmx
     Depend: server
        LIB: lib/jetty-jmx-${jetty.version}.jar
        XML: etc/jetty-jmx.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jmx-remote
     Depend: jmx
        XML: etc/jetty-jmx-remote.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jndi
     Depend: server
        LIB: lib/jetty-jndi-${jetty.version}.jar
        LIB: lib/jndi/*.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: jolokia
     Depend: stats
     Depend: deploy
     Depend: jmx
        XML: etc/jolokia.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: jsp
     Depend: servlet
     Depend: annotations
     Depend: apache-jsp
    Enabled: <not enabled in this configuration>

 [ ] Module: jstl
     Depend: jsp
     Depend: apache-jstl
    Enabled: <not enabled in this configuration>

 [ ] Module: jvm
    Enabled: <not enabled in this configuration>

 [ ] Module: logging
        LIB: lib/logging/**.jar
        LIB: resources/
        XML: etc/jetty-logging.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: lowresources
     Depend: server
        XML: etc/jetty-lowresources.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: monitor
     Depend: server
     Depend: client
        LIB: lib/monitor/jetty-monitor-${jetty.version}.jar
        XML: etc/jetty-monitor.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: nosql
     Depend: webapp
        LIB: lib/jetty-nosql-${jetty.version}.jar
        LIB: lib/nosql/*.jar
        XML: etc/jetty-nosql.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: plus
     Depend: server
     Depend: security
     Depend: jndi
     Depend: webapp
        LIB: lib/jetty-plus-${jetty.version}.jar
        XML: etc/jetty-plus.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: proxy
     Depend: servlet
     Depend: client
        LIB: lib/jetty-proxy-${jetty.version}.jar
        XML: etc/jetty-proxy.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: quickstart
     Depend: server
     Depend: plus
     Depend: annotations
        LIB: lib/jetty-quickstart-${jetty.version}.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: requestlog
     Depend: server
        XML: etc/jetty-requestlog.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: resources
        LIB: resources/
    Enabled: <not enabled in this configuration>

 [ ] Module: rewrite
     Depend: server
        LIB: lib/jetty-rewrite-${jetty.version}.jar
        XML: etc/jetty-rewrite.xml
    Enabled: <not enabled in this configuration>

 [x] Module: security
     Depend: server
        LIB: lib/jetty-security-${jetty.version}.jar
    Enabled: <via> <transitive from> ${jetty.base}/start.ini
    Enabled: <via> ${jetty.base}/start.ini

 [x] Module: server
        LIB: lib/servlet-api-3.1.jar
        LIB: lib/jetty-schemas-3.1.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: <via> <transitive from> ${jetty.base}/start.ini
    Enabled: <via> ${jetty.base}/start.ini

 [x] Module: servlet
     Depend: server
        LIB: lib/jetty-servlet-${jetty.version}.jar
    Enabled: <via> <transitive from> ${jetty.base}/start.ini
    Enabled: <via> ${jetty.base}/start.ini

 [ ] Module: servlets
     Depend: servlet
        LIB: lib/jetty-servlets-${jetty.version}.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: setuid
     Depend: server
        LIB: lib/setuid/jetty-setuid-java-1.0.3.jar
        XML: etc/jetty-setuid.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: spring
     Depend: server
        LIB: lib/spring/*.jar
    Enabled: <not enabled in this configuration>

 [ ] Module: ssl
     Depend: server
        XML: etc/jetty-ssl.xml
        XML: etc/jetty-ssl-context.xml
    Enabled: <not enabled in this configuration>

 [ ] Module: stats
     Depend: server
        XML: etc/jetty-stats.xml
    Enabled: <not enabled in this configuration>

 [x] Module: webapp
     Depend: servlet
     Depend: security
        LIB: lib/jetty-webapp-${jetty.version}.jar
    Enabled: <via> ${jetty.base}/start.ini
    Enabled: <via> <transitive from> ${jetty.base}/start.ini

 [ ] Module: websocket
     Depend: annotations
        LIB: lib/websocket/*.jar
    Enabled: <not enabled in this configuration>

Jetty Selected Module Ordering:
-------------------------------
    1) server          ${jetty.base}/start.ini
    2) http            ${jetty.base}/start.ini
    2) security        ${jetty.base}/start.ini
    2) servlet         ${jetty.base}/start.ini
    3) webapp          ${jetty.base}/start.ini
    4) deploy          ${jetty.base}/start.ini

Since being introduced in Jetty 9.1 the modules provided in the Jetty distribution has expanded greatly. Below is a graphical representation of the standard modules and their dependencies.

image

See an error or something missing? Contribute to this documentation at Github!(Generated: 2016-10-28)