Version: 9.3.16.v20170120 |

Managing Startup Modules
Previous | Chapter 9. Starting Jetty Home | Next

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

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.16.v20170120
     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.16.v20170120
     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.16.v20170120 | ${jetty.home}/lib/jetty-http-9.3.16.v20170120.jar
     3:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-server-9.3.16.v20170120.jar
     4:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-xml-9.3.16.v20170120.jar
     5:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-util-9.3.16.v20170120.jar
     6:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-io-9.3.16.v20170120.jar
     7:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-security-9.3.16.v20170120.jar
     8:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-servlet-9.3.16.v20170120.jar
     9:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-webapp-9.3.16.v20170120.jar
    10:           9.3.16.v20170120 | ${jetty.home}/lib/jetty-deploy-9.3.16.v20170120.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.

Previous | Top | Next
Managing Server Classpath | Home | Startup a Unix Service using jetty.sh

See an error or something missing? Contribute to this documentation at Github!(Generated: 2017-01-20)