Chapter 3. An Introduction to Jetty Configuration

Chapter 3. An Introduction to Jetty Configuration
Previous	Part I. Getting Started With Jetty Home	Next

Table of Contents

How to Configure Jetty
What to Configure in Jetty

How to Configure Jetty

Jetty POJO Configuration
Jetty Start Configuration Files
A Closer Look
Other Configuration Files
Jetty IoC XML format

To understand Jetty configuration, you need to understand the "How" and the "What". This section covers how to configure Jetty in terms of what mechanisms exist to perform configuration. The next section gives an overview of the action components and fields that you can configure with these mechanisms.

Jetty POJO Configuration

The core components of Jetty are Plain Old Java Objects (POJOs) The process of configuring Jetty is mostly the process of instantiating, assembling and setting fields on the Jetty POJOs. This can be achieved by:

Writing Java code to directly instantiate and assemble Jetty objects. This is referred to as Embedding Jetty.
Using Jetty XML configuration, which is an Inversion of Control (IoC) framework, to instantiate and assemble Jetty objects as XML objects. The etc/jetty.xml file is the main Jetty XML configuration file, but there are many other etc/jetty-__feature__.xml files included in the Jetty distribution.
Using a third party IoC framework like Spring, to instantiate and assemble Jetty objects as Spring beans.

Because the main Jetty configuration is done by IoC, the Jetty API documentation is the ultimate configuration reference.

Jetty Start Configuration Files

The Jetty distribution uses the following configuration files to instantiate, inject and start server via the start.jar mechanism.

ini files

The Jetty Start mechanism uses the command line, the $JETTY_BASE/start.ini and/or $JETTY_BASE/start.d/*.ini files to create an effective command line of arguments. Arguments may be:

Module activations in the form --module=name
Properties in the form of name=value, used to parameterize Jetty IoC XML
XML files in Jetty IoC (or Spring) XML format
A standard Java property file containing additional start properties
Other start.jar options (see java -jar start.jar --help)
Some JVM options in combination with --exec, such as -Xbootclasspath.

Note
It is the ini files located in the Jetty base directory (if different from Jetty home) that are typically edited to change the configuration (e.g. change ports).

mod files

The $JETTY_HOME/modules/*.mod files contain the definition of modules that can be activated by --module=name. Each mod file defines:

Module dependencies for ordering and activation
The libraries needed by the module to be added to the classpath
The XML files needed by the module to be added to the effective command line
Files needed by the activated module
A template ini file to be used when activating the --add-to-start=name option
Typically module files are rarely edited and only then for significant structural changes. The *.mod files are normally located in $JETTY_HOME/modules/, but extra or edited modules may be added to $JETTY_BASE/module. If module changes are required, it is best practice to copy the particular *.mod file from $JETTY_HOME/modules/ to $JETTY_BASE/modules/ before being modified.

XML files

XML files in Jetty IoC XML format or Spring IoC format are listed either on the command line, in ini files, or are added to the effective command line by a module definition. The XML files instantiate and inject the actual Java objects that comprise the server, connectors and contexts. Because Jetty IoC XML files use properties, most common configuration tasks can be accomplished without editing these XML files and can instead be achieved by editing the property in the corresponding ini files. XML files are normally located in $JETTY_HOME/etc/, but extra or edited XML files may be added to $JETTY_BASE/etc/. Note If XML configuration changes are required, it is best practice to copy the XML file from $JETTY_HOME/etc/ to $JETTY_BASE/etc/ before being modified.

Below is an illustration of how the various Jetty configuration files (ini, mod and XML) are related:

A Closer Look

To put it simply: XML files are responsible for instantiating the Jetty POJOs that make up the server. They define properties which users can modify to meet the needs of their server. These XML files are broken up by type in the distribution so they can be consumed as a user/server needs them. For example, a server may need HTTP and HTTPS functionality, but opt out of using HTTP/2 and Websocket.

Module files allow users to enable and remove functionality quickly and easily from their server implementation. They include a template of the different properties included in the associated XML file, as well as a pointer to the XML or JAR file(s) they are referencing. When a module is activated these properties are added to a related ini file where users can configure them to meet their needs. We will discuss modules in further detail in an upcoming chapter.

Ini files are where most users will spend the bulk of their time editing the configuration for their server. As mentioned, they contain properties which were defined in their associated XML files which in turn reference Jetty Java objcts.

This can be a bit overwhelming at first, so let’s look at an example - in this case the http module. We will work backwards from an ini file to the associated module and then the XML file in question.

First up, the http.ini file. If we take a look at it’s contents, we will see the following:

$ cat start.d/http.ini
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
# By default HTTP/1 is support, but HTTP2C can
# be added to the connector with the http2c module.
# ---------------------------------------
--module=http

### HTTP Connector Configuration

## Connector host/address to bind to
# jetty.http.host=0.0.0.0

## Connector port to listen on
# jetty.http.port=8080

## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000

## Number of acceptors (-1 picks default based on number of cores)
# jetty.http.acceptors=-1

## Number of selectors (-1 picks default based on number of cores)
# jetty.http.selectors=-1

## ServerSocketChannel backlog (0 picks platform default)
# jetty.http.acceptorQueueSize=0

## Thread priority delta to give to acceptor threads
# jetty.http.acceptorPriorityDelta=0

## Reserve threads for high priority tasks (-1 use a heuristic, 0 no reserved threads)
# jetty.http.reservedThreads=-1

## Connect Timeout in milliseconds
# jetty.http.connectTimeout=15000

## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230

So what do we see? We have a module name, the module activation (--module=http), as well as a description and what look like properties to configure. Those will some scripting/coding experience might notice that most of the lines are commented out with # and you’d be correct. When a module is enabled and an ini file is created, all of the properties you see here were set to these defaults - the server is already using the values shown If you wanted to change one of the properties though, say jetty.http.port, you’d simply uncomment the line and change the value. For example:

$ cat start.d/http.ini
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
# By default HTTP/1 is support, but HTTP2C can
# be added to the connector with the http2c module.
# ---------------------------------------
--module=http

### HTTP Connector Configuration

## Connector host/address to bind to
# jetty.http.host=0.0.0.0

## Connector port to listen on
jetty.http.port=1234
...

As seen before, these properties were populated in this ini file based on a related module. Standard Jetty modules live in the Home of the Jetty Distribution in the aptly named modules directory. So let’s take a quick look at the associated $JETTY_HOME/modules/http.mod file:

$ cat $JETTY_HOME/modules/http.mod
[description]
Enables a HTTP connector on the server.
By default HTTP/1 is support, but HTTP2C can
be added to the connector with the http2c module.

[tags]
connector
http

[depend]
server

[xml]
etc/jetty-http.xml

[ini-template]
### HTTP Connector Configuration

## Connector host/address to bind to
# jetty.http.host=0.0.0.0

## Connector port to listen on
# jetty.http.port=8080

## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000
...

At first blush, it looks remarkable similar to the ini file we just looked at. We still have a description and the properties we could edit, but now we also have several other sections. These other sections will be looked at further in our chapter on modules, but for now it is worth noting the [xml] and [ini-template] sections. As you could probably have puzzled out, the [ini-template] contains a template (go figure) for properties to be placed in the associated ini file when a module is activated. The [xml] section refers to the file and location of the XML file these properties are based on. It is important to note that not every module file will have the same sections, but most should look structurally the same.

Now that we know what XML file these properties relate to, we can navigate to it and have a look.

$ cat $JETTY_HOME/etc/jetty-http.xml
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<!-- ============================================================= -->
<!-- Configure the Jetty Server instance with an ID "Server"       -->
<!-- by adding a HTTP connector.                                   -->
<!-- This configuration must be used in conjunction with jetty.xml -->
<!-- ============================================================= -->
<Configure id="Server" class="org.eclipse.jetty.server.Server">

  <!-- =========================================================== -->
  <!-- Add a HTTP Connector.                                       -->
  <!-- Configure an o.e.j.server.ServerConnector with a single     -->
  <!-- HttpConnectionFactory instance using the common httpConfig  -->
  <!-- instance defined in jetty.xml                               -->
  <!--                                                             -->
  <!-- Consult the javadoc of o.e.j.server.ServerConnector and     -->
  <!-- o.e.j.server.HttpConnectionFactory for all configuration    -->
  <!-- that may be set here.                                       -->
  <!-- =========================================================== -->
  <Call name="addConnector">
    <Arg>
      <New id="httpConnector" class="org.eclipse.jetty.server.ServerConnector">
        <Arg name="server"><Ref refid="Server" /></Arg>
        <Arg name="acceptors" type="int"><Property name="jetty.http.acceptors" deprecated="http.acceptors" default="-1"/></Arg>
        <Arg name="selectors" type="int"><Property name="jetty.http.selectors" deprecated="http.selectors" default="-1"/></Arg>
        <Arg name="factories">
          <Array type="org.eclipse.jetty.server.ConnectionFactory">
            <Item>
              <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                <Arg name="config"><Ref refid="httpConfig" /></Arg>
                <Arg name="compliance"><Call class="org.eclipse.jetty.http.HttpCompliance" name="valueOf"><Arg><Property name="jetty.http.compliance" default="RFC7230"/></Arg></Call></Arg>
              </New>
            </Item>
          </Array>
        </Arg>
        <Set name="host"><Property name="jetty.http.host" deprecated="jetty.host" /></Set>
        <Set name="port"><Property name="jetty.http.port" deprecated="jetty.port" default="8080" /></Set>
        <Set name="idleTimeout"><Property name="jetty.http.idleTimeout" deprecated="http.timeout" default="30000"/></Set>
        <Set name="acceptorPriorityDelta"><Property name="jetty.http.acceptorPriorityDelta" deprecated="http.acceptorPriorityDelta" default="0"/></Set>
        <Set name="acceptQueueSize"><Property name="jetty.http.acceptQueueSize" deprecated="http.acceptQueueSize" default="0"/></Set>
        <Get name="SelectorManager">
          <Set name="connectTimeout"><Property name="jetty.http.connectTimeout" default="15000"/></Set>
          <Set name="reservedThreads"><Property name="jetty.http.reservedThreads" default="-2"/></Set>
        </Get>
      </New>
    </Arg>
  </Call>

</Configure>

Now we can see where those properties in our ini and module files came from. In Jetty XML files, Jetty objects come to life; defined properties are set which link back to the jar libraries and run the server to a user’s specification.

Important
It is important to remember that you should not modify the XML files in your $JETTY_HOME. If you do for some reason feel you want to change the way an XML file operates, it is best to make a copy of it in your $JETTY_BASE in an /etc directory. Jetty will always look first to the $JETTY_BASE for configuration.

Other Configuration Files

In addition to the configuration files described above, the configuration of the server can use the following file types:

Context XML files

Any XML files in Jetty IoC XML format or Spring IoC format that is discovered in the /webapps directory are used by the deploy module to instantiate and inject HttpContext instances to create a specific context. These may be standard web applications or bespoke contexts created from special purpose handlers.

web.xml

The Servlet Specification defines the web.xml deployment descriptor that defines and configures the filters, servlets and resources a web application uses. The Jetty WebAppContext component uses this XML format to:

Set up the default configuration of a web application context.
Interpret the application-specific configuration supplied with a web application in the WEB-INF/web.xml file.
Interpret descriptor fragments included in the META-INF directory of Jar files within WEB-INF/lib.
Normally the web.xml file for a web application is found in the WEB-INF/web.xml location within the war file/directory or as web.xml fragments with .jar files found in WEB-INF/lib. Jetty also supports multiple web.xml files so that a default descriptor may be applied before WEB-INF/web.xml (typically set to etc/webdefault.xml by the deploy module) and an override descriptor may be applied after WEB-INF/web.xml (typically set by a context XML file see test.xml)

Property Files

Standard Java property files are also used for Jetty configuration in several ways:

To parameterize Jetty IoC XML via the use of the Property element.
To configure the default logging mechanism (StdErrLog). Other logging frameworks can be utilized and also use property files (for example, log4j).
As a simple database for login usernames and credentials.

Jetty IoC XML format

To understand the Jetty IoC XML format, consider the following example of an embedded Jetty server instantiated and configured in Java:

//
//  ========================================================================
//  Copyright (c) 1995-2018 Mort Bay Consulting Pty. Ltd.
//  ------------------------------------------------------------------------
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
//

package org.eclipse.jetty.embedded;

import org.eclipse.jetty.server.Connector;
import org.eclipse.jetty.server.Handler;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.ServerConnector;
import org.eclipse.jetty.server.handler.DefaultHandler;
import org.eclipse.jetty.server.handler.HandlerCollection;
import org.eclipse.jetty.servlet.ServletContextHandler;

public class ExampleServer
{
    public static void main( String[] args ) throws Exception
    {
        Server server = new Server();

        ServerConnector connector = new ServerConnector(server);
        connector.setPort(8080);
        server.setConnectors(new Connector[] { connector });

        ServletContextHandler context = new ServletContextHandler();
        context.setContextPath("/");
        context.addServlet(HelloServlet.class, "/hello");
        context.addServlet(AsyncEchoServlet.class, "/echo/*");

        HandlerCollection handlers = new HandlerCollection();
        handlers.setHandlers(new Handler[] { context, new DefaultHandler() });
        server.setHandler(handlers);

        server.start();
        server.join();
    }
}

Jetty IoC XML format allows you to instantiate and configure the exact same server in XML without writing any java code:

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

<Configure id="ExampleServer" class="org.eclipse.jetty.server.Server">

  <Set name="connectors">
    <Array type="org.eclipse.jetty.server.Connector">
      <Item>
        <New class="org.eclipse.jetty.server.ServerConnector">
          <Arg><Ref refid="ExampleServer"/></Arg>
          <Set name="port">8080</Set>
        </New>
      </Item>
    </Array>
  </Set>

  <New id="context" class="org.eclipse.jetty.servlet.ServletContextHandler">
    <Set name="contextPath">/hello</Set>
    <Call name="addServlet">
      <Arg>org.eclipse.jetty.embedded.HelloServlet</Arg>
      <Arg>/</Arg>
    </Call>
  </New>

  <Set name="handler">
    <New class="org.eclipse.jetty.server.handler.HandlerCollection">
      <Set name="handlers">
        <Array type="org.eclipse.jetty.server.Handler">
          <Item>
            <Ref refid="context" />
          </Item>
          <Item>
            <New class="org.eclipse.jetty.server.handler.DefaultHandler" />
          </Item>
        </Array>
      </Set>
    </New>
  </Set>
</Configure>

Previous	Top	Next
Deploying Web Applications	Home	What to Configure in Jetty