Jetty Logo
Version: 9.3.1-SNAPSHOT
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 from 1 day to full product delivery

Managing Startup Modules

Enabling Modules
Listing Available and Active Modules

Starting with Jetty 9.1, a new Module system was introduced. (It replaced the old 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 dependant 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 dependant 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 (file a bug if you want 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 (or start.ini) to enable that module and all of its dependant modules.

An example of this, with a new, empty, base directory.

WARNING: Nothing to start, exiting ...

Usage: java -jar start.jar [options] [properties] [configs]
       java -jar start.jar --help  # for more information

We can see from this output, that the directory is new (it is empty after all).

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-8u45/jre
 java.vm.vendor = Oracle Corporation
 java.vm.version = 25.45-b02
 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_45-b14
 java.io.tmpdir = /tmp
 user.dir = /home/jetty/mybase
 user.language = en
 user.country = US

Jetty Environment:
-----------------
 jetty.version = 9.3.1-SNAPSHOT
 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

That just created what we need in the ${jetty.base} directory. 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.1-SNAPSHOT
 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.1-SNAPSHOT | ${jetty.home}/lib/jetty-http-9.3.1-SNAPSHOT.jar
 3:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-server-9.3.1-SNAPSHOT.jar
 4:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-xml-9.3.1-SNAPSHOT.jar
 5:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-util-9.3.1-SNAPSHOT.jar
 6:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-io-9.3.1-SNAPSHOT.jar
 7:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-security-9.3.1-SNAPSHOT.jar
 8:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-servlet-9.3.1-SNAPSHOT.jar
 9:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-webapp-9.3.1-SNAPSHOT.jar
10:           9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-deploy-9.3.1-SNAPSHOT.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, albiet with no webapps deployed. At this point you can toss a webapp (war file) into mybase/webapps/ directory and and start Jetty

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

Wow, are there really that many modules available?

Yes, the module system has grown a fair bit since it was introduced in Jetty 9

See an error or something missing? Contribute to this documentation at Github!(Generated: 2015-07-29T01:01:16+00:00)