Jetty Logo
Version: 9.2.2-SNAPSHOT
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 6. 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 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:

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:

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:

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

Table 6.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:

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":

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":

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

SSL Context Configuration

The SSL/TLS 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 :

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:

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.

See an error or something missing? Contribute to this documentation at Github!(Generated: 2014-07-21T01:00:33-07:00)