Jetty Logo
Version: 9.3.1-SNAPSHOT
Contact the core Jetty developers at

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

Chapter 7. Configuring Security

Table of Contents

Using the ${jetty.home} and ${jetty.base} Concepts to Configure Security
Limiting Form Content
Aliased Files and Symbolic links
Secure Password Obfuscation
JAAS Support
Spnego Support

Using the ${jetty.home} and ${jetty.base} Concepts to Configure Security

Jetty 9.1 introduces ${jetty.base} and ${jetty.home}.

  • ${jetty.home} is the directory location for the jetty distribution (the binaries).

  • ${jetty.base} is the directory location for your customizations to the distribution.

This separation:

  • Allows you to manage multiple Jetty installations.

  • Makes it simple to retain your current configuration when you upgrade your Jetty distribution.

For more information, see Managing Jetty Base and Jetty Home.

Further, Jetty 9.1 parameterizes all of the standard configuration XMLs. For SSL, parameters are now just properties in the start.ini, reducing to eliminating the need to edit XML files.

Jetty 9.1 also introduces modules. Instead of explicitly listing all the libraries, properties, and XML files for a feature, Jetty includes software modules, and the start.jar mechanism allows you to create new modules. You define a module in a modules/*.mod file, including the libraries, dependencies, XML, and template INI files for a Jetty feature. Thus you can use a single --module=name command line option as the equivalent of specifying many --lib=location, feature.xml, name=value arguments for a feature and all its dependencies. Modules use their dependencies to control the ordering of libraries and XML files. For more information, see Managing Startup Modules.

Configuring SSL in with modules

This page describes how to configure SSL in Jetty with modules. It provides an example of using the ${jetty.home} and ${jetty.base} to maximum effect. It also includes a detailed explanation of how modules work.

This example assumes you have the jetty-distribution unpacked in /home/user/jetty-distribution-9.3.1-SNAPSHOT.


OBF passwords are not secure, just protected from casual observation.

  1. Create a base directory anywhere.

    [/home/user]$ mkdir my-base
    [/home/user]$ cd my-base
  2. Add the modules for SSL, HTTP, and webapp deployment.

    [my-base]$ java -jar /home/user/jetty-distribution-9.3.1-SNAPSHOT/start.jar --add-to-start=http,https,deploy
    ssl             initialised in ${jetty.base}/start.ini (appended)
    ssl             enabled in     ${jetty.base}/start.ini
    DOWNLOAD: to etc/keystore
    server          initialised in ${jetty.base}/start.ini (appended)
    server          enabled in     ${jetty.base}/start.ini
    http            initialised in ${jetty.base}/start.ini (appended)
    http            enabled in     ${jetty.base}/start.ini
    server          enabled in     ${jetty.base}/start.ini
    deploy          initialised in ${jetty.base}/start.ini (appended)
    deploy          enabled in     ${jetty.base}/start.ini
    MKDIR: ${jetty.base}/webapps
    server          enabled in     ${jetty.base}/start.ini
  3. Look at your directory.

    [my-base]$ ls -la
    total 20
    drwxrwxr-x   4 user group 4096 Oct  8 06:55 ./
    drwxr-xr-x 103 user group 4096 Oct  8 06:53 ../
    drwxrwxr-x   2 user group 4096 Oct  8 06:55 etc/
    -rw-rw-r--   1 user group  815 Oct  8 06:55 start.ini
    drwxrwxr-x   2 user group 4096 Oct  8 06:55 webapps/
  4. Copy your WAR files into webapps.

    [my-base]$ ls -la
    [my-base]$ cp ~/code/project/target/gadget.war webapps/
  5. Copy your keystore into place.

    [my-base]$ cp ~/code/project/keystore etc/keystore
  6. Edit the start.ini to configure your SSL settings.

    [my-base]$ cat start.ini
  7. Initialize module ssl.

  8. Define the port to use for secure redirection.
  9. Set up a demonstration keystore and truststore.

  10. Set the demonstration passwords.

  11. Initialize the module server.

  12. Initialize module http.

  13. Initialize module deploy.


Look at the configuration you have at this point.

[my-base]$ java -jar /home/user/jetty-distribution-9.3.1-SNAPSHOT/start.jar --list-config

Java Environment:
 java.vm.vendor=Oracle Corporation
 java.vm.version=23.21-b01 HotSpot(TM) 64-Bit Server VM mode SE Runtime Environment

Jetty Environment:

JVM Arguments:
 (no jvm args specified)

System Properties:
 jetty.base = /home/user/my-base
 jetty.home = /home/user/jetty-distribution-9.3.1-SNAPSHOT

 http.timeout = 30000
 jetty.dump.start = false
 jetty.dump.stop = false
 jetty.keymanager.password = OBF:1u2u1wml1z7s1z7a1wnl1u2g
 jetty.keystore = etc/keystore
 jetty.keystore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
 jetty.http.port = 8080 = 8443
 jetty.truststore = etc/keystore
 jetty.truststore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
 threads.max = 200
 threads.min = 10
 threads.timeout = 60000

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.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-http-9.3.1-SNAPSHOT.jar
 3:                9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-continuation-9.3.1-SNAPSHOT.jar
 4:                9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-server-9.3.1-SNAPSHOT.jar
 5:                9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-xml-9.3.1-SNAPSHOT.jar
 6:                9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-util-9.3.1-SNAPSHOT.jar
 7:                9.3.1-SNAPSHOT | ${jetty.home}/lib/jetty-io-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:

Now start Jetty.

[my-base]$ java -jar /home/user/jetty-distribution-9.3.1-SNAPSHOT/start.jar
2013-10-08 07:06:55.837:INFO:oejs.Server:main: jetty-9.3.1-SNAPSHOT
2013-10-08 07:06:55.853:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
2013-10-08 07:06:55.872:INFO:oejs.ServerConnector:main: Started ServerConnector@72974691{HTTP/1.1}{}

Reviewing the Configuration

The following sections review this configuration.

${jetty.base} and ${jetty.home}

First notice the separation of ${jetty.base} and ${jetty.home}.

  • ${jetty.home} is where your distribution lies, unchanged, unedited.

  • ${jetty.base} is where your customizations are.


Notice that you have --module=<name> here and there; you have wrapped up the goal of a module (libs, configuration XMLs, and properties) into a single unit, with dependencies on other modules.

You can see the list of modules:

[my-base]$ java -jar /home/user/jetty-distribution-9.3.1-SNAPSHOT/start.jar --list-modules

Jetty All Available Modules:

Module: annotations
      LIB: lib/jetty-annotations-${jetty.version}.jar
      LIB: lib/annotations/*.jar
      XML: etc/jetty-annotations.xml
  depends: [plus]

Module: client
      LIB: lib/jetty-client-${jetty.version}.jar
  depends: []

Module: debug
      XML: etc/jetty-debug.xml
  depends: [server]

Module: deploy
      LIB: lib/jetty-deploy-${jetty.version}.jar
      XML: etc/jetty-deploy.xml
  depends: [webapp]
  enabled: ${jetty.base}/start.ini

Module: ext
      LIB: lib/ext/*.jar
  depends: []

Module: http
      XML: etc/jetty-http.xml
  depends: [server]
  enabled: ${jetty.base}/start.ini

Module: http2
      LIB: lib/http2/*.jar
      XML: etc/jetty-http2.xml
  depends: [ssl, alpn]

Module: http2c
     LIB: lib/http2/*.jar
     XML: etc/jetty-http2c.xml
 depends: [http]

Module: https
      XML: etc/jetty-https.xml
  depends: [ssl]

Module: ipaccess
      XML: etc/jetty-ipaccess.xml
  depends: [server]

Module: jaas
      LIB: lib/jetty-jaas-${jetty.version}.jar
      XML: etc/jetty-jaas.xml
  depends: [server]

Module: jaspi
      LIB: lib/jetty-jaspi-${jetty.version}.jar
      LIB: lib/jaspi/*.jar
  depends: [security]

Module: jmx
      LIB: lib/jetty-jmx-${jetty.version}.jar
      XML: etc/jetty-jmx.xml
  depends: []

Module: jndi
      LIB: lib/jetty-jndi-${jetty.version}.jar
      LIB: lib/jndi/*.jar
  depends: [server]

Module: jsp
      LIB: lib/jsp/*.jar
  depends: [servlet]

Module: jvm
  depends: []

Module: logging
      XML: etc/jetty-logging.xml
  depends: []

Module: lowresources
      XML: etc/jetty-lowresources.xml
  depends: [server]

Module: monitor
      LIB: lib/jetty-monitor-${jetty.version}.jar
      XML: etc/jetty-monitor.xml
  depends: [client, server]

Module: npn
  depends: []

Module: plus
      LIB: lib/jetty-plus-${jetty.version}.jar
      XML: etc/jetty-plus.xml
  depends: [server, security, jndi]

Module: proxy
      LIB: lib/jetty-proxy-${jetty.version}.jar
      XML: etc/jetty-proxy.xml
  depends: [client, server]

Module: requestlog
      XML: etc/jetty-requestlog.xml
  depends: [server]

Module: resources
      LIB: resources
  depends: []

Module: rewrite
      LIB: lib/jetty-rewrite-${jetty.version}.jar
      XML: etc/jetty-rewrite.xml
  depends: [server]

Module: security
      LIB: lib/jetty-security-${jetty.version}.jar
  depends: [server]

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-continuation-${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
  depends: []
  enabled: ${jetty.base}/start.ini

Module: servlet
      LIB: lib/jetty-servlet-${jetty.version}.jar
  depends: [server]

Module: servlets
      LIB: lib/jetty-servlets-${jetty.version}.jar
  depends: [servlet]

Module: setuid
      LIB: lib/setuid/jetty-setuid-java-1.0.1.jar
      XML: etc/jetty-setuid.xml
  depends: [server]

Module: ssl
      XML: etc/jetty-ssl.xml
  depends: [server]
  enabled: ${jetty.base}/start.ini

Module: stats
      XML: etc/jetty-stats.xml
  depends: [server]

Module: webapp
      LIB: lib/jetty-webapp-${jetty.version}.jar
  depends: [servlet]

Module: websocket
      LIB: lib/websocket/*.jar
  depends: [annotations]

Module: xinetd
      XML: etc/jetty-xinetd.xml
  depends: [server]

Jetty Active Module Tree:
 + Module: server [enabled]
   + Module: http [enabled]
   + Module: servlet [transitive]
   + Module: ssl [enabled]
     + Module: webapp [transitive]
       + Module: deploy [enabled]

These are the modules by name, the libraries they bring in, the XML configurations they use, the other modules they depend on (even optional ones), and if the module is in use, where it was enabled.

While you can manage the list of active modules yourself, it is much easier to edit the ${jetty.base}/start.ini.

If you want to start using a new module:

[my-base] $ java -jar ../jetty-distribution-9.3.1-SNAPSHOT/start.jar --add-to-start=https

This adds the --module= lines and associated properties (the parameterized values mentioned above), to your start.ini.


Leave the modules and XML files alone in the ${jetty.home} directory; there is no need to be moving or copying them unless you want to make your own modules or override the behavior of an existing module.

Notice that your ${jetty.base}/start.ini has no references to the XML files. That's because the module system and its graph of dependencies now dictate all of the XML files, and their load order.


Next is parameterizing all of the standard configuration XMLs. In this example all of the SSL parameters are now just properties in the start.ini, reducing or eliminating the need to edit XML files.

Overriding ${jetty.home} in ${jetty.base}

Finally, you can override anything you see in ${jetty.home} in ${jetty.base}, even XML configurations and libraries.

For more information on the start.jar in 9.1, see Using start.jar.

Summary of Configuring SSL in Jetty 9.1

  1. Download and unpack Jetty 9.1 into /home/user/jetty-distribution-9.3.1-SNAPSHOT.

  2. Go to your base directory and just use the distribution, no editing.

    [my-base]$ java -jar /home/user/jetty-distribution-9.3.1-SNAPSHOT/start.jar
    • The Jetty 9.1 distribution provides, out of the box, the XML configuration files, in this case jetty-http.xml and jetty-ssl.xml. You can find them in ${jetty.home}/etc/ directory.

    • We have parameterized all of the configurable values in those XMLs. You can now set the values using simple properties, either on the command line, or within the ${jetty.base}/start.ini.

    • When you activate the module for HTTP or HTTPs, Jetty automatically adds the appropriate libraries and XML to start Jetty. Unless you have a highly custom setup (such as listening on two different ports, using SSL on each, each with its own keystore and configuration), you should have no need to be mucking around in XML files.

  3. Use modules to configure HTTPS:

    • http -> server

    • https -> ssl -> server

    You can find the details about the modules in ${jetty.home}/modules/. For SSL they include modules/http.mod, modules/https.mod, modules/ssl.mod, and modules/server.mod.

    Ideally, this level of detail is not important to you. What is important is that you want to use HTTPS and want to configure it. You accomplish that by adding the --module=https to your start.ini. By default, the module system keeps things sane, and transitively includes all dependent modules as well.

You can see what the configuration looks like, after all of the modules are resolved, without starting Jetty via:

[my-base] $ java -jar ../jetty-distribution-9.3.1-SNAPSHOT/start.jar --list-config

Just because the JARs exist on disk does not mean that they are in use. The configuration controls what is used.

Use the --list-config to see the configuration. Notice that only a subset of the JARs from the distribution are in use. The modules you have anabled determine that subset.

[my-base]$ java -jar ~/jetty-distribution-9.3.1-SNAPSHOT/start.jar --list-config

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