Jetty Logo
Version: 9.2.2-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 commingled ${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=<name> syntax on the command line (or start.ini) to enable it + all of its dependant modules.

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

[/home/user]$ mkdir my-base
[/home/user]$ cd my-base
[my-base]$ java -jar ../jetty-distribution/start.jar
WARNING: Nothing to start, exiting ...

Usage: java -jar start.jar [options] [properties] [configs]
       java -jar start.jar --help  # for more information
[my-base]$ java -jar ../jetty-distribution/start.jar --list-config

Java Environment:
-----------------
 java.home=/home/joakim/java/jdk-7u21-x64/jre
 java.vm.vendor=Oracle Corporation
 java.vm.version=23.21-b01
 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.7.0_21-b11
 java.io.tmpdir=/tmp

Jetty Environment:
-----------------
 jetty.home=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO
 jetty.base=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.version=9.1.0-DEMO

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

System Properties:
------------------
 jetty.base = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.home = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO

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

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

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

Can't start, as there is no configuration, yet. Lets use a simple one that will start up support for webapps and hot deployment.

[my-base]$ java -jar ../jetty-distribution/start.jar --module=webapp,deploy
2013-10-16 13:30:45.636:INFO:oejs.Server:main: jetty-9.1.0-DEMO
2013-10-16 13:30:45.656:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps] at interval 1
[Ctrl+C]
[my-base]$ java -jar ../jetty-distribution/start.jar --module=webapp,deploy --list-config
Java Environment:
-----------------
 java.home=/home/joakim/java/jdk-7u21-x64/jre
 java.vm.vendor=Oracle Corporation
 java.vm.version=23.21-b01
 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.7.0_21-b11
 java.io.tmpdir=/tmp

Jetty Environment:
-----------------
 jetty.home=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO
 jetty.base=/home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.version=9.1.0-DEMO

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

System Properties:
------------------
 jetty.base = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO/my-base
 jetty.home = /home/joakim/code/intalio/distros/jetty-distribution-9.1.0-DEMO

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

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.RC0 | ${jetty.home}/lib/jetty-schemas-3.1.jar
 2:               9.1.0-DEMO | ${jetty.home}/lib/jetty-http-9.1.0-DEMO.jar
 3:               9.1.0-DEMO | ${jetty.home}/lib/jetty-continuation-9.1.0-DEMO.jar
 4:               9.1.0-DEMO | ${jetty.home}/lib/jetty-server-9.1.0-DEMO.jar
 5:               9.1.0-DEMO | ${jetty.home}/lib/jetty-xml-9.1.0-DEMO.jar
 6:               9.1.0-DEMO | ${jetty.home}/lib/jetty-util-9.1.0-DEMO.jar
 7:               9.1.0-DEMO | ${jetty.home}/lib/jetty-io-9.1.0-DEMO.jar
 8:               9.1.0-DEMO | ${jetty.home}/lib/jetty-servlet-9.1.0-DEMO.jar
 9:               9.1.0-DEMO | ${jetty.home}/lib/jetty-webapp-9.1.0-DEMO.jar
10:               9.1.0-DEMO | ${jetty.home}/lib/jetty-deploy-9.1.0-DEMO.jar

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

From here, we can see that the Jetty now starts up with basic WebApp support and automatic deployment.

Just create a my-base/webapps/ directory and toss in a simple war file and you now have a functional server.

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

[my-base]$ java -jar ../start.jar --list-modules
Jetty All Available Modules:
----------------------------

 + Module: annotations
   Depend: plus
      LIB: lib/jetty-annotations-${jetty.version}.jar
      LIB: lib/annotations/*.jar
      XML: etc/jetty-annotations.xml
  Enabled: <via transitive reference>

 * Module: client
      LIB: lib/jetty-client-${jetty.version}.jar
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

 * Module: continuation
      LIB: lib/jetty-continuation-${jetty.version}.jar
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

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

 * Module: deploy
   Depend: webapp
      LIB: lib/jetty-deploy-${jetty.version}.jar
      XML: etc/jetty-deploy.xml
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

 * Module: ext
      LIB: lib/ext/**.jar
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

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

 * Module: http
   Depend: server
      XML: etc/jetty-http.xml
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.d/http.ini

 * Module: https
   Depend: ssl
      XML: etc/jetty-https.xml
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.d/https.ini

 - 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: <via> /home/foo/jetty-distribution/demo-base/start.ini

 - Module: jaspi
   Depend: security
      LIB: lib/jetty-jaspi-${jetty.version}.jar
      LIB: lib/jaspi/*.jar
  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: <via transitive reference>

 * Module: jsp
   Depend: jsp-impl
   Depend: servlet
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.d/jsp.ini

 + Module: jsp-impl
      Ref: jsp-impl/apache-jsp
      LIB: lib/apache-jsp/*.jar
  Enabled: <via transitive reference>

 + Module: jstl-impl
      Ref: jsp-impl/apache-jstl
      LIB: lib/apache-jstl/*.jar
  Enabled: <via transitive reference>

 * Module: jstl
   Depend: jsp
   Depend: jstl-impl
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.d/jstl.ini

 - 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: client
   Depend: server
      LIB: lib/monitor/jetty-monitor-${jetty.version}.jar
      XML: etc/jetty-monitor.xml
  Enabled: <not enabled in this configuration>

 + Module: plus
   Depend: webapp
   Depend: server
   Depend: security
   Depend: jndi
      LIB: lib/jetty-plus-${jetty.version}.jar
      XML: etc/jetty-plus.xml
  Enabled: <via transitive reference>

 - Module: protonego
   Depend: protonego-impl/${protonego}
  Enabled: <not enabled in this configuration>

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

 - Module: quickstart
   Depend: plus
   Depend: server
   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: <via> /home/foo/jetty-distribution/demo-base/start.ini

 * Module: rewrite
   Depend: server
      LIB: lib/jetty-rewrite-${jetty.version}.jar
      XML: etc/jetty-rewrite.xml
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

 + Module: security
   Depend: server
      LIB: lib/jetty-security-${jetty.version}.jar
  Enabled: <via transitive reference>

 * 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> /home/foo/jetty-distribution/demo-base/start.ini

 + Module: servlet
   Depend: server
      LIB: lib/jetty-servlet-${jetty.version}.jar
  Enabled: <via transitive reference>

 * Module: servlets
   Depend: servlet
      LIB: lib/jetty-servlets-${jetty.version}.jar
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

 * Module: setuid
   Depend: server
      LIB: lib/setuid/jetty-setuid-java-1.0.1.jar
      XML: etc/jetty-setuid.xml
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

 - Module: spdy
   Depend: protonego
   Depend: ssl
      LIB: lib/spdy/*.jar
      XML: etc/jetty-ssl.xml
      XML: etc/jetty-spdy.xml
  Enabled: <not enabled in this configuration>

 * Module: ssl
   Depend: server
      XML: etc/jetty-ssl.xml
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.d/ssl.ini

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

 + Module: webapp
   Depend: security
   Depend: servlet
      LIB: lib/jetty-webapp-${jetty.version}.jar
  Enabled: <via transitive reference>

 * Module: websocket
   Depend: annotations
      LIB: lib/websocket/*.jar
  Enabled: <via> /home/foo/jetty-distribution/demo-base/start.ini

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

Jetty Active Module Tree:
-------------------------
 + Module: client [enabled]
 + Module: continuation [enabled]
 + Module: ext [enabled]
 + Module: jsp-impl [transitive]
 + Module: jstl-impl [transitive]
 + Module: resources [enabled]
   + Module: server [enabled]
     + Module: http [enabled]
     + Module: jaas [enabled]
     + Module: jndi [transitive]
     + Module: rewrite [enabled]
     + Module: security [transitive]
     + Module: servlet [transitive]
     + Module: setuid [enabled]
     + Module: ssl [enabled]
       + Module: https [enabled]
       + Module: jsp [enabled]
       + Module: servlets [enabled]
       + Module: webapp [transitive]
         + Module: deploy [enabled]
         + Module: jstl [enabled]
         + Module: plus [transitive]
           + Module: annotations [transitive]
             + Module: websocket [enabled]

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-07-23T01:00:30-07:00)