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
Table of Contents
This chapter discusses various options for configuring Jetty connectors.
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.
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
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:
that accepts HTTP connections (that may be upgraded to WebSocket
that accepts SSL/TLS connections. On it's own, this connector is not
functional and requires one or more of the following files to also be
configured to add
to make the connector functional.
jetty-ssl.xml to support the http2
protocol. Also prepends either
protonego-npn.xml so that the next protocol can be
negotiated, which allows the same SSL port to handle multiple
jetty-ssl.xml which allows the one SSL
connector to support multiple protocols with the ALPN extension used
to select the protocol to be used for each connection.
Typically you need to configure very little on connectors other than
set the listening port (see Network Settings), and
X-Forwarded-For customization (see HTTP Configuration).
Most other settings are for expert configuration only.
The services a
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
you can do this with:
You can see the other arguments that can be passed when constructing
ServerConnector in the Javadoc.
Typically the defaults are sufficient for almost all deployments.
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
to be customizable:
The network settings that you can set on the
Table 6.1. Connector Configuration
|host||The network interface this connector binds to as an IP address or a hostname. If null or 0.0.0.0, bind to all interfaces.|
|port||The configured port for the connector or 0 a random
available port may be used (selected port available via
|idleTimeout||The time in milliseconds that the connection can be idle before it is closed.|
|defaultProtocol||The name of the default protocol used to select a
|stopTimeout||The time in milliseconds to wait before gently stopping a connector.|
|acceptQueueSize||The 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.|
|reuseAddress||Allow the server socket to be rebound even if in TIME_WAIT. For servers it is typically OK to leave this as the default true.|
|soLingerTime||A 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.|
class holds the configuration for
HTTPChannel s, which you can create 1:1 with each HTTP
connection or 1:n on a multiplexed HTTP/2 connection. Thus a
HTTPConfiguration object is injected into both the HTTP and
HTTP/2 connection factories. To avoid duplicate configuration, the standard
Jetty distribution creates the common
jetty.xml , which is a
element then used in
A typical configuration of HttpConfiguration is:
This example HttpConfiguration may be used by reference to the ID "httpConfig":
For SSL based connectors (in
jetty-http2.xml), the common "httpConfig"
instance is used as the basis to create an SSL specific configuration with
This adds a
which adds SSL Session IDs and certificate information as request
The SSL/TLS connectors for HTTPS and HTTP/2 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. Read more about SSL
keystores in Configuring
Often a Connector needs to be configured to accept connections from an intermediary such as a Reverse Proxy and/or Load Balancer deployed in front of the server. In such environments, the TCP/IP connection terminating on the server does not originate from the client, but from the intermediary, so that the Remote IP and port number can be reported incorrectly in logs and in some circumstances the incorrect server address and port may be used.
Thus Intermediaries typically implement one of several de facto
standards to communicate to the server information about the orginal
client connection terminating on the intermediary. Jetty supports the
header and the Proxy
Protocol mechanisms as described below.
The XML files in the jetty distribution contain commented out
examples of both the
Protocol mechanisms. When using those examples, it is recommended
that the XML in the jetty distribution is not edited. Rather the files
should be copied into a jetty base directory and then modified.
header and associated headers are a defacto standard where
intermediaries add HTTP headers to each request they forward to describe
the originating connection. These headers can be interpreted by an
which can be added to a HttpConfiguration as follows:
Protocol is a defacto standard created by HAProxy and used by
environments such as Amazon Elastic Cloud. This mechanism is independent
of any protocol, so it can be used for HTTP2, TLS etc. The
information about the client connection is sent as a small data frame on
each newly established connection. In Jetty, this protocol can be
handled by the
which parses the data frame and then instantiates the next
ConnectionFactory on the connection with and EndPoint that has been
customized with the data obtained about the orginal client connection.
The connection factory can be added to any
and should be the first
An example of adding the factory to a HTTP connector is: