Jetty Logo
Chapter 4. Configuring Jetty Connectors
Prev Part II. Jetty Configuration Guide 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 from 1 day to full product delivery

Chapter 4. Configuring Jetty Connectors

Table of Contents

Connector Configuration Overview
Configuring SSL
Setting Port 80 Access for a Non-Root User

This chapter discusses various options for configuring Jetty connectors.

Connector Configuration Overview

Constructing a ServerConnector
Network Settings.
HTTP Configuration
SSL Context Configuration
Configuring Connection Factories

Connectors are the mechanism through which Jetty accepts network connections for various protocols. Configuring a connector is a combination of configuring the following:

  • Network parameters on the connector itself (for example: the listening port).

  • Services the connector uses (for example: executors, schedulers).

  • Connection factories that instantiate and configure the protocol for an accepted connection.

Jetty primarily uses a single connector type called ServerConnector.

Note

Prior to Jetty 9, the type of the connector specified both the protocol and the implementation used (for example, selector-based non blocking I/O vs blocking I/O, or SSL connector vs non-SSL connector). Jetty 9 has only a selector-based non blocking I/O connector, and a collection of ConnectionFactories now configure the protocol on the connector.

The standard Jetty distribution comes with the following Jetty XML files that create and configure connectors; you should examine them as you read this section:

jetty-http.xml

Instantiates a ServerConnector that accepts HTTP connections (that may be upgraded to WebSocket connections).

jetty-https.xml

Instantiates a ServerConnector that accepts SSL/TLS connections. The ConnectionFactory configured after the SSL one is a HTTP ConnectionFactories, and therefore the SSL/TLS connections will carry the HTTP protocol.

example-jetty-spdy.xml

Instantiates a ServerConnector that accepts SSL connections that carry either HTTP or SPDY traffic. Initially the SSL connection is chained to a Next Protocol Negotiation (NPN) connection, which eventually replaces itself with a connection for a protocol it negotiates with the client; this protocol may be a version of SPDY or HTTP. If the client does not support NPN, HTTP is assumed.

Typically you need to configure very little on connectors other than set the listening port (see Network Settings), and perhaps enable X-Forwarded-For customization (see HTTP Configuration). Most other settings are for expert configuration only.

Constructing a ServerConnector

The services a ServerConnector instance uses are set by constructor injection and once instantiated cannot be changed. Most of the services may be defaulted with null or 0 values so that a reasonable default is used, thus for most purposes only the Server and the connection factories need to be passed to the connector constructor. In Jetty XML (that is, in jetty-http.xml ), you can do this with:

<New class="org.eclipse.jetty.server.ServerConnector">
  <Arg name="server"><Ref refid="Server" /></Arg>
  <Arg name="factories">
    <Array type="org.eclipse.jetty.server.ConnectionFactory">
      <!-- insert one or more factories here -->
    </Array>
  </Arg>
  <!-- set connector fields here -->
</New>

You can see the other arguments that can be passed when constructing a ServerConnector in the Javadoc. Typically the defaults are sufficient for almost all deployments.

Network Settings.

You configure connector network settings by calling setters on the connector before it is started. For example, you can set the port with the Jetty XML:

<New class="org.eclipse.jetty.server.ServerConnector">
  <Arg name="server"><Ref refid="Server" /></Arg>
  <Arg name="factories"><!-- insert one or more factories here --></Arg>

  <Set name="port">8080</Set>
</New>

Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line. Thus typically the port is set within Jetty XML, but uses the Property element to be customizable:

<New class="org.eclipse.jetty.server.ServerConnector">
  <Arg name="server"><Ref refid="Server" /></Arg>
  <Arg name="factories"><!-- insert one or more factories here --></Arg>

  <Set name="port"><Property name="jetty.port" default="8080"/></Set>
</New>

The network settings that you can set on the ServerConnector include:

Table 4.1. Connector Configuration

FieldDescription
hostThe network interface this connector binds to as an IP address or a hostname. If null or 0.0.0.0, bind to all interfaces.
portThe configured port for the connector or 0 a random available port may be used (selected port available via getLocalPort()).
idleTimeoutThe time in milliseconds that the connection can be idle before it is closed.
defaultProtocolThe name of the default protocol used to select a ConnectionFactory instance. This defaults to the first ConnectionFactory added to the connector.
stopTimeoutThe time in milliseconds to wait before gently stopping a connector.
acceptQueueSizeThe size of the pending connection backlog. The exact interpretation is JVM and operating system specific and you can ignore it. Higher values allow more connections to wait pending an acceptor thread. Because the exact interpretation is deployment dependent, it is best to keep this value as the default unless there is a specific connection issue for a specific OS that you need to address.
reuseAddressAllow the server socket to be rebound even if in TIME_WAIT. For servers it is typically OK to leave this as the default true.
soLingerTimeA value >=0 set the socket SO_LINGER value in milliseconds. Jetty attempts to gently close all TCP/IP connections with proper half close semantics, so a linger timeout should not be required and thus the default is -1.

HTTP Configuration

The HttpConfiguration class holds the configuration for HTTPChannel s, which you can create 1:1 with each HTTP connection or 1:n on a multiplexed SPDY connection. Thus a HTTPConfiguration object is injected into both the HTTP and SPDY connection factories. To avoid duplicate configuration, the standard Jetty distribution creates the common HttpConfiguration instance in jetty.xml , which is a Ref element then used in jetty-http.xml , jetty-https.xml and example-jetty-spdy.xml .

A typical configuration of HttpConfiguration is:

<New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
  <Set name="secureScheme">https</Set>
  <Set name="securePort"><Property name="jetty.tls.port" default="8443" /></Set>
  <Set name="outputBufferSize">32768</Set>
  <Set name="requestHeaderSize">8192</Set>
  <Set name="responseHeaderSize">8192</Set>

  <Call name="addCustomizer">
    <Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
  </Call>
</New>

This example adds a ForwardedRequestCustomizer to process the X-Forward-For and related proxy headers. jetty-https.xml can, by reference, use the instance created with an ID "httpConfig":

<Call name="addConnector">
  <Arg>
    <New class="org.eclipse.jetty.server.ServerConnector">
      <Arg name="server"><Ref refid="Server" /></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>
            </New>
          </Item>
        </Array>
      </Arg>
      <!-- ... -->
    </New>
  </Arg>
</Call>

For SSL based connectors (in jetty-https.xml and jetty-spdy.xml), the common "httpConfig" instance is used as the basis to create an SSL specific configuration with ID "tlsHttpConfig":

<New id="tlsHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
  <Arg><Ref refid="httpConfig"/></Arg>
  <Call name="addCustomizer">
    <Arg><New class="org.eclipse.jetty.server.SecureRequestCustomizer"/></Arg>
  </Call>
</New>

This adds a SecureRequestCustomizer which adds SSL Session IDs and certificate information as request attributes.

SSL Context Configuration

The SSL/TSL connectors for HTTPS and SPDY require a certificate to establish a secure connection. Jetty holds certificates in standard JVM keystores and are configured as keystore and truststores on a SslContextFactory instance that is injected into an SslConnectionFactory instance. An example using the keystore distributed with Jetty (containing a self signed test certificate) is in jetty-https.xml and example-jetty-spdy.xml . Read more about SSL keystores in Configuring SSL.

Configuring Connection Factories

It is the ConnectionFactory instances injected into a ServerConnector that create the protocol handling Connection instances for the network endpoints the connector accepts. Thus the different instances of connectors in a Jetty setup vary mostly in the configuration of the factories for the protocols they support. Other than selecting which factories to use, there is typically very little factory configuration required other than injecting the HTTPConfiguration or SslContextFactory instances.

The simplest example in the Jetty distribution is jetty-http.xml :

<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.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 class="org.eclipse.jetty.server.ServerConnector">
        <Arg name="server"><Ref refid="Server" /></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>
              </New>
            </Item>
          </Array>
        </Arg>
        <Set name="host"><Property name="jetty.host" /></Set>
        <Set name="port"><Property name="jetty.port" default="8080" /></Set>
        <Set name="idleTimeout">30000</Set>
      </New>
    </Arg>
  </Call>

</Configure>

Here the connector has only a single ConnectionFactory, and when a new connection is accepted, it is the HttpConnectionFactory that creates an HttpConnection.

A more complex example involving multiple connection factories is jetty-spdy.xml:

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

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

    <New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
        <Set name="keyStorePath">src/main/resources/keystore.jks</Set>
        <Set name="keyStorePassword">storepwd</Set>
        <Set name="trustStorePath">src/main/resources/truststore.jks</Set>
        <Set name="trustStorePassword">storepwd</Set>
        <Set name="protocol">TLSv1</Set>
    </New>

    <New id="tlsHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
        <Arg>
            <New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
                <Set name="secureScheme">https</Set>
                <Set name="securePort">
                    <Property name="jetty.tls.port" default="8443"/>
                </Set>
                <Set name="outputBufferSize">32768</Set>
                <Set name="requestHeaderSize">8192</Set>
                <Set name="responseHeaderSize">8192</Set>

                <!-- Uncomment to enable handling of X-Forwarded- style headers
                <Call name="addCustomizer">
                    <Arg><New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/></Arg>
                </Call>
                -->
            </New>
        </Arg>
        <Call name="addCustomizer">
            <Arg>
                <New class="org.eclipse.jetty.server.SecureRequestCustomizer"/>
            </Arg>
        </Call>
    </New>

    <New id="pushStrategy" class="org.eclipse.jetty.spdy.server.http.ReferrerPushStrategy">
        <!-- Uncomment to blacklist browsers for this push strategy. If one of the blacklisted Strings occurs in the
             user-agent header sent by the client, push will be disabled for this browser. This is case insensitive" -->
        <!--
        <Set name="UserAgentBlacklist">
            <Array type="String">
                <Item>.*(?i)firefox/14.*</Item>
                <Item>.*(?i)firefox/15.*</Item>
                <Item>.*(?i)firefox/16.*</Item>
            </Array>
        </Set>
        -->

        <!-- Uncomment to override default file extensions to push -->
        <!--
        <Set name="PushRegexps">
            <Array type="String">
               <Item>.*\.css</Item>
               <Item>.*\.js</Item>
               <Item>.*\.png</Item>
               <Item>.*\.jpg</Item>
               <Item>.*\.gif</Item>
           </Array>
        </Set>
        -->
        <Set name="referrerPushPeriod">5000</Set>
        <Set name="maxAssociatedResources">32</Set>
    </New>

    <Call id="sslConnector" name="addConnector">
        <Arg>
            <New class="org.eclipse.jetty.server.ServerConnector">
                <Arg name="server"><Ref refid="Server"/></Arg>
                <Arg name="factories">
                    <Array type="org.eclipse.jetty.server.ConnectionFactory">

                        <!-- SSL Connection factory with NPN as next protocol -->
                        <Item>
                            <New class="org.eclipse.jetty.server.SslConnectionFactory">
                                <Arg name="next">npn</Arg>
                                <Arg name="sslContextFactory">
                                    <Ref refid="sslContextFactory"/>
                                </Arg>
                            </New>
                        </Item>

                        <!-- NPN Connection factory with HTTP as default protocol -->
                        <Item>
                            <New class="org.eclipse.jetty.spdy.server.NPNServerConnectionFactory">
                                <Arg name="protocols">
                                    <Array type="String">
                                        <Item>spdy/3</Item>
                                        <Item>spdy/2</Item>
                                        <Item>http/1.1</Item>
                                    </Array>
                                </Arg>
                                <Set name="defaultProtocol">http/1.1</Set>
                            </New>
                        </Item>

                        <!-- SPDY/3 Connection factory -->
                        <Item>
                            <New class="org.eclipse.jetty.spdy.server.http.HTTPSPDYServerConnectionFactory">
                                <Arg name="version" type="int">3</Arg>
                                <Arg name="config">
                                    <Ref refid="tlsHttpConfig"/>
                                </Arg>
                                <Arg name="pushStrategy">
                                    <Ref refid="pushStrategy"/>
                                </Arg>
                            </New>
                        </Item>

                        <!-- SPDY/2 Connection factory -->
                        <Item>
                            <New class="org.eclipse.jetty.spdy.server.http.HTTPSPDYServerConnectionFactory">
                                <Arg name="version" type="int">2</Arg>
                                <Arg name="config">
                                    <Ref refid="tlsHttpConfig"/>
                                </Arg>
                            </New>
                        </Item>

                        <!-- HTTP Connection factory -->
                        <Item>
                            <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                                <Arg name="config">
                                    <Ref refid="tlsHttpConfig"/>
                                </Arg>
                            </New>
                        </Item>
                    </Array>
                </Arg>

                <Set name="port">8443</Set>
            </New>
        </Arg>
    </Call>

</Configure>

In this case five connection factories are created and linked together by their protocol names:

"SSL-npn"

The default protocol is identified by the first connection factory, which in this case is a SslConnectionFactory instantiated with "npn" as the next protocol. Thus accepted endpoints are associated with an SslConnection instance that is chained to an NextProtoNegoServerConnection instance created by the "npn" connection factory.

"npn"

This is the NPNServerConnectionFactory chained to the SslConnectionFactory. The NPN connections negotiate with the client for the next protocol and then a factory of that name is looked up to create a connection to replace the NPN connection. If NPN is not supported, the defaultProtocol is configured as "http/1.1".

"spdy/3"

The factory NPN connections use if SPDY version 3 is negotiated.

"spdy/2"

The factory NPN connections use if SPDY version 2 is negotiated.

"http/1.1"

The factory NPN connections use if HTTP version 1.1 is negotiated or if NPN is not supported. Note that HTTP/1.1 can also handle HTTP/1.0.

Prev Up Next
Part II. Jetty Configuration Guide Home Configuring SSL

See an error or something missing? Contribute to this documentation at Github!