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

Connectors are the mechanism through which Jetty accepts network connections for various protocols. Configuring a connector is a combination of configuring the network parameters on the connector itself (eg port), configuring the services used by the connector (e.g. executors & schedulers) and configuration of the connection factories used to 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 was used to specify both the protocol and the implementation used (eg NIO vs blocking IO). In Jetty-9 the is only an NIO connector and the protocol is now configured by a collection of ConnectionFactory s on the connector. Thus Jetty-9 primarily uses a single connector type: ServerConnector

The standard jetty distribution comes with the following Jetty IoC XML files that create and configure connectors, which should be read in conjunction with this section:

jetty-http.xml

Instantiates a ServerConnector which accepts HTTP connections (which may be upgraded to Websocket).

jetty-https.xml

Instantiates a ServerConnector which accepts SSL (aka TLS) connections and are assumed to carry the HTTP protocol and are thus chained to a HTTP connection.

example-jetty-spdy.xml

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

Typically very little configuration is needed on connectors other than setting the port (see Network settings), and perhaps enabling X-Forwarded customization (see HTTP Configuration). Most other settings should be consider for expert configuration only.

Constructing a Server Connector

The services used by a ServerConnector instance 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 IoC XML (eg. in jetty-http.xml), this can be done with:


<New class="org.eclipse.jetty.server.ServerConnector">
  <Arg name="server"><Ref id="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> 
      
      

The other arguments that can be passed when constructing a Server Connector may be seen in the javadoc. Typically the defaults are sufficient for almost all deployments.

Network settings.

The connector network settings are configured by calling setters on the connector before it is started. For example the port can be set with the Jetty IoC XML:


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

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

Values in Jetty IoC 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 with Jetty IoC XML that uses the Property element:


<New class="org.eclipse.jetty.server.ServerConnector">
  <Arg name="server"><Ref id="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 can be 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, then 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 Connection Factory instance. This defaults to the first ConnectionFactory added to the connector.
stopTimeoutThe time in milliseconds to wait while gently stopping a connector.
acceptQueueSizeThe size of the pending connection backlog. The exact interpretation is JVM and Operating system specific and may be ignored. Higher values allow more connections to be waiting pending and 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 needs to be addressed.
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 may either be created 1:1 with each HTTP/1 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 duplication of configuration, the standard Jetty distribution creates the common HttpConfiguration instance in jetty.xml, which is then used by Ref element 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. The instance created with an ID "httpConfig" can be used by reference by jetty-https.xml:


  <Call name="addConnector">
    <Arg>
      <New class="org.eclipse.jetty.server.ServerConnector">
        <Arg name="server"><Ref id="Server" /></Arg>
        <Arg name="factories">
          <Array type="org.eclipse.jetty.server.ConnectionFactory">
            <Item>
              <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                <Arg name="config"><Ref id="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 id="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 TLS (aka SSL) connectors for HTTPS and SPDY require a certificate to establish a secure connection. Certificates in jetty are held 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) can be seen 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 accepted by the connector. Thus the different instances of connectors in a jetty setup vary mostly in their 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 id="Server" /></Arg>
        <Arg name="factories">
          <Array type="org.eclipse.jetty.server.ConnectionFactory">
            <Item>
              <New class="org.eclipse.jetty.server.HttpConnectionFactory">
                <Arg name="config"><Ref id="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 which will create a 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 id="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 id="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 id="tlsHttpConfig"/>
                                </Arg>
                                <Arg name="pushStrategy">
                                    <Ref id="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 id="tlsHttpConfig"/>
                                </Arg>
                            </New>
                        </Item>

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

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

</Configure>

In this case 5 connection factories are created that are linked together by their protocol names:

"SSL-npn"

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

"npn"

This is the NPNServerConnectionFactory that chained to by the SslConnection. 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 used by NPN Connections if SPDY version 3 is negotiated.

"spdy/2"

The factory used by NPN Connections if SPDY version 2 is negotiated.

"http/1.1"

The factory used by NPN Connections if HTTP version 1.1 is negotiated or if NPN is not supported. Note that HTTP/1.1 can also handle HTTP/1.0 and HTTP/0.

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