Merge pull request #707 from WalkerWatch/jetty-9.3.x
Chapter 6 fixes, removal of Quickstart pieces for #679.
This commit is contained in:
Joakim Erdfelt
GitHub
commit
7f5213e668
|
|
@ -17,7 +17,7 @@
|
|||
[[jetty-connectors]]
|
||||
=== Connector Configuration Overview
|
||||
|
||||
Connectors are the mechanism through which Jetty accepts network connections for various protocols.
|
||||
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).
|
||||
|
|
@ -28,8 +28,8 @@ Jetty primarily uses a single connector type called link:{JDURL}/org/eclipse/jet
|
|||
|
||||
____
|
||||
[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 link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactories`] now configure the protocol on the connector.
|
||||
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 a single selector-based non-blocking I/O connector, and a collection of link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`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:
|
||||
|
|
@ -37,7 +37,7 @@ The standard Jetty distribution comes with the following Jetty XML files that cr
|
|||
link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]::
|
||||
Instantiates a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] that accepts HTTP connections (that may be upgraded to WebSocket connections).
|
||||
link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-ssl.xml[`jetty-ssl.xml`]::
|
||||
Instantiates a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] that accepts SSL/TLS connections.
|
||||
Instantiates a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] 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 link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactories`] to make the connector functional.
|
||||
link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-https.xml[`jetty-https.xml`]::
|
||||
Adds a link:{JDURL}/org/eclipse/jetty/server/HttpConnectionFactory.html[`HttpConnectionFactory`] to the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] configured by `jetty-ssl.xml` which combine to provide support for HTTPS.
|
||||
|
|
@ -46,13 +46,13 @@ link:{SRCDIR}/jetty-http2/http2-server/src/main/config/etc/jetty-http2.xml[`jett
|
|||
link:{SRCDIR}/jetty-alpn/jetty-alpn-server/src/main/config/etc/jetty-alpn.xml[`jetty-alpn.xml`]::
|
||||
Adds an link:{JDURL}/org/eclipse/jetty/alpn/server/ALPNServerConnectionFactory.html[`ALPNServerConnectionFactory`] to the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] configured by `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 link:#jetty-connectors-network-settings[Network Settings]), and perhaps enable `X-Forwarded-For` customization (see link:#jetty-connectors-http-configuration[HTTP Configuration]).
|
||||
Most other settings are for expert configuration only.
|
||||
Typically connectors require very little configuration aside from setting the listening port (see link:#jetty-connectors-network-settings[Network Settings]), and enabling `X-Forwarded-For` customization when applicable. (see link:#jetty-connectors-http-configuration[HTTP Configuration]).
|
||||
Additional settings are for expert configuration only.
|
||||
|
||||
==== Constructing a `ServerConnector`
|
||||
==== Constructing a ServerConnector
|
||||
|
||||
The services a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`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 link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]), you can do this by:
|
||||
The services a link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] instance uses are set by constructor injection and once instantiated cannot be changed.
|
||||
Many 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 link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]) you can do this by:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -64,16 +64,16 @@ Most of the services may be defaulted with null or 0 values so that a reasonable
|
|||
</Array>
|
||||
</Arg>
|
||||
<!-- set connector fields here -->
|
||||
</New>
|
||||
</New>
|
||||
----
|
||||
|
||||
You can see the other arguments that can be passed when constructing a `ServerConnector` in the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html#ServerConnector%28org.eclipse.jetty.server.Server,%20java.util.concurrent.Executor,%20org.eclipse.jetty.util.thread.Scheduler,%20org.eclipse.jetty.io.ByteBufferPool,%20int,%20int,%20org.eclipse.jetty.server.ConnectionFactory...%29[Javadoc].
|
||||
You can see the other arguments that can be passed when constructing a `ServerConnector` in the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html#ServerConnector%28org.eclipse.jetty.server.Server,%20java.util.concurrent.Executor,%20org.eclipse.jetty.util.thread.Scheduler,%20org.eclipse.jetty.io.ByteBufferPool,%20int,%20int,%20org.eclipse.jetty.server.ConnectionFactory...%29[Javadoc].
|
||||
Typically the defaults are sufficient for almost all deployments.
|
||||
|
||||
[[jetty-connectors-network-settings]]
|
||||
==== Network Settings.
|
||||
|
||||
You configure connector network settings by calling setters on the connector before it is started.
|
||||
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:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
@ -83,10 +83,10 @@ For example, you can set the port with the Jetty XML:
|
|||
<Arg name="factories"><!-- insert one or more factories here --></Arg>
|
||||
|
||||
<Set name="port">8080</Set>
|
||||
</New>
|
||||
</New>
|
||||
----
|
||||
|
||||
Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line.
|
||||
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:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
@ -96,7 +96,7 @@ Thus typically the port is set within Jetty XML, but uses the `Property` element
|
|||
<Arg name="factories"><!-- insert one or more factories here --></Arg>
|
||||
|
||||
<Set name="port"><Property name="jetty.http.port" default="8080"/></Set>
|
||||
</New>
|
||||
</New>
|
||||
----
|
||||
|
||||
The network settings that you can set on the link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] include:
|
||||
|
|
@ -105,7 +105,7 @@ The network settings that you can set on the link:{JDURL}/org/eclipse/jetty/serv
|
|||
[width="100%",cols="22%,78%",options="header",]
|
||||
|=======================================================================
|
||||
|Field |Description
|
||||
|host |The network interface this connector binds to as an IP address or a hostname.
|
||||
|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 `getLocalPort()`).
|
||||
|
|
@ -116,23 +116,23 @@ If null or 0.0.0.0, bind to all interfaces.
|
|||
|
||||
|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.
|
||||
|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 http://www.ssfnet.org/Exchange/tcp/tcpTutorialNotes.html[TIME_WAIT].
|
||||
|reuseAddress |Allow the server socket to be rebound even if in http://www.ssfnet.org/Exchange/tcp/tcpTutorialNotes.html[TIME_WAIT].
|
||||
For servers it is typically OK to leave this as the default true.
|
||||
|
||||
|soLingerTime |A value greater than zero sets the socket http://stackoverflow.com/questions/3757289/tcp-option-so-linger-zero-when-its-required[SO_LINGER] value in milliseconds.
|
||||
|soLingerTime |A value greater than zero sets the socket http://stackoverflow.com/questions/3757289/tcp-option-so-linger-zero-when-its-required[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.
|
||||
|=======================================================================
|
||||
|
||||
[[jetty-connectors-http-configuration]]
|
||||
==== HTTP Configuration
|
||||
|
||||
The link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[HttpConfiguration] class holds the configuration for link:{JDURL}/org/eclipse/jetty/server/HttpChannel.html[`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.
|
||||
The link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[HttpConfiguration] class holds the configuration for link:{JDURL}/org/eclipse/jetty/server/HttpChannel.html[`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 `HttpConfiguration` instance in link:{SRCDIR}/jetty-server/src/main/config/etc/jetty.xml[`jetty.xml`], which is a `Ref` element then used in link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`], link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-https.xml[`jetty-https.xml`] and in link:{SRCDIR}/jetty-http2/http2-server/src/main/config/etc/jetty-http2.xml[`jetty-http2.xml`].
|
||||
|
||||
A typical configuration of link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[HttpConfiguration] is:
|
||||
|
|
@ -187,29 +187,29 @@ This adds a `SecureRequestCustomizer` which adds SSL Session IDs and certificate
|
|||
|
||||
==== SSL Context Configuration
|
||||
|
||||
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 link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html[`SslContextFactory`] instance that is injected into an link:{JDURL}/org/eclipse/jetty/server/SslConnectionFactory.html[`SslConnectionFactory`] instance.
|
||||
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 link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html[`SslContextFactory`] instance that is injected into an link:{JDURL}/org/eclipse/jetty/server/SslConnectionFactory.html[`SslConnectionFactory`] instance.
|
||||
An example using the keystore distributed with Jetty (containing a self signed test certificate) is in link:{SRCDIR}/jetty-server/src/main/config/etc/jetty-https.xml[`jetty-https.xml`].
|
||||
Read more about SSL keystores in link:#configuring-ssl[Configuring SSL].
|
||||
|
||||
==== Proxy / Load Balancer Connection Configuration
|
||||
|
||||
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.
|
||||
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.
|
||||
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 `X-Forwarded-For` header and the http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] mechanisms as described below.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
The XML files in the jetty distribution contain commented out examples of both the `X-Forwarded-For` and http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy 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.
|
||||
The XML files in the Jetty distribution contain commented out examples of both the `X-Forwarded-For` and http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy 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.
|
||||
____
|
||||
|
||||
===== X-Forward-for Configuration
|
||||
|
||||
The `X-Forwarded-for` header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection.
|
||||
The `X-Forwarded-for` header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection.
|
||||
These headers can be interpreted by an instance of link:{JDURL}/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] which can be added to a `HttpConfiguration` as follows:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
@ -227,9 +227,9 @@ These headers can be interpreted by an instance of link:{JDURL}/org/eclipse/jett
|
|||
|
||||
===== Proxy Protocol
|
||||
|
||||
The http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] is a de facto 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.
|
||||
The http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt[Proxy Protocol] is a de facto 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 link:{JDURL}/org/eclipse/jetty/server/ProxyConnectionFactory.html[`ProxyConnectionFactory`] which parses the data frame and then instantiates the next `ConnectionFactory` on the connection with an end point that has been customized with the data obtained about the original client connection.
|
||||
The connection factory can be added to any link:{JDURL}/org/eclipse/jetty/server/ServerConnector.html[`ServerConnector`] and should be the first link:{JDURL}/org/eclipse/jetty/server/ConnectionFactory.html[`ConnectionFactory`].
|
||||
|
||||
|
|
|
|||
|
|
@ -24,16 +24,16 @@ This document provides an overview of how to configure SSL and TLS for Jetty.
|
|||
|
||||
Which browser/OS supports which protocols can be https://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers[found on Wikipedia].
|
||||
|
||||
* TLS v1.1 and v1.2: The protocols which should be used wherever possible.
|
||||
* TLS v1.1 and v1.2: The protocols which should be used wherever possible.
|
||||
All CBC based ciphers are supported since Java 7, the new GCM modes are supported since Java 8.
|
||||
* TLS v1.0: still supported but is affected by the POODLE attack.
|
||||
* TLS v1.0: Still supported but is affected by the link:https://cve.mitre.org/cgi-bin/cvename.cgi?name=cve-2014-3566[POODLE attack.]
|
||||
To support older browsers this protocol version is still needed.
|
||||
* SSL v3: is now deprecated and should only be enabled if you still need to support very old browsers like Internet Explorer 6 on Windows XP which does not support TLS 1.0 (or is disabled by default).
|
||||
* SSL v3: is now deprecated and should *only* be enabled if you still need to support very old browsers like Internet Explorer 6 on Windows XP which does not support TLS 1.0 (or is disabled by default).
|
||||
|
||||
[[understanding-certificates-and-keys]]
|
||||
==== Understanding Certificates and Keys
|
||||
|
||||
Configuring SSL can be a confusing experience of keys, certificates, protocols and formats, thus it helps to have a reasonable understanding of the basics.
|
||||
Configuring SSL can be a confusing experience of keys, certificates, protocols and formats, thus it helps to have a reasonable understanding of the basics.
|
||||
The following links provide some good starting points:
|
||||
|
||||
* Certificates:
|
||||
|
|
@ -52,12 +52,10 @@ The following links provide some good starting points:
|
|||
|
||||
For testing, the `keytool` utility bundled with the JDK provides the simplest way to generate the key and certificate you need.
|
||||
|
||||
You can also use the OpenSSL tools to generate keys and certificates, or to convert those that you have used with Apache or other servers.
|
||||
You can also use the OpenSSL tools to generate keys and certificates, or to convert those that you have used with Apache or other servers.
|
||||
Since Apache and other servers commonly use the OpenSSL tool suite to generate and manipulate keys and certificates, you might already have some keys and certificates created by OpenSSL, or you might also prefer the formats OpenSSL produces.
|
||||
|
||||
If you want the option of using the same certificate with Jetty or a web
|
||||
server such as Apache not written in Java, you might prefer to generate
|
||||
your private key and certificate with OpenSSL.
|
||||
If you want the option of using the same certificate with Jetty or a web server such as Apache not written in Java, you might prefer to generate your private key and certificate with OpenSSL.
|
||||
|
||||
[[configuring-jetty-for-ssl]]
|
||||
===== Configuring Jetty for SSL
|
||||
|
|
@ -72,13 +70,13 @@ To configure Jetty for SSL, complete the tasks in the following sections:
|
|||
[[generating-key-pairs-and-certificates]]
|
||||
===== Generating Key Pairs and Certificates
|
||||
|
||||
The simplest way to generate keys and certificates is to use the `keytool` application that comes with the JDK, as it generates keys and certificates directly into the keystore.
|
||||
The simplest way to generate keys and certificates is to use the `keytool` application that comes with the JDK, as it generates keys and certificates directly into the keystore.
|
||||
See xref:generating-key-pairs-and-certificates-JDK-keytool[].
|
||||
|
||||
If you already have keys and certificates, see xref:loading-keys-and-certificates[] to load them into a JSSE keystore.
|
||||
If you already have keys and certificates, see xref:loading-keys-and-certificates[] to load them into a JSSE keystore.
|
||||
This section also applies if you have a renewal certificate to replace one that is expiring.
|
||||
|
||||
The examples below generate only basic keys and certificates.
|
||||
The examples below generate only basic keys and certificates.
|
||||
You should read the full manuals of the tools you are using if you want to specify:
|
||||
|
||||
* The key size
|
||||
|
|
@ -102,8 +100,8 @@ In a browser, it displays a message "Could not establish an encrypted connection
|
|||
The solution is to use RSA for the key algorithm.
|
||||
____
|
||||
|
||||
This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
|
||||
The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt.
|
||||
This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
|
||||
The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt.
|
||||
For example:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
|
|
@ -131,9 +129,9 @@ $ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256with
|
|||
$
|
||||
----
|
||||
|
||||
You now have the minimal requirements to run an SSL connection and could proceed directly to link:#configuring-sslcontextfactory[configure an SSL connector].
|
||||
However, the browser will not trust the certificate you have generated, and prompts the user to this effect.
|
||||
While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, as shown in the section link:#generating-csr-from-keytool[generating a CSR with keytool].
|
||||
You now have the minimal requirements to run an SSL connection and could proceed directly to link:#configuring-sslcontextfactory[configure an SSL connector].
|
||||
However, the browser _will not_ trust the certificate you have generated, and prompts the user to this effect.
|
||||
While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section link:#generating-csr-from-keytool[generating a CSR with keytool].
|
||||
|
||||
If you want to use only a self signed certificate for some kind of internal admin panel add -validity <days> to the keytool call above, otherwise your certificate is only valid for one month.
|
||||
|
||||
|
|
@ -164,10 +162,10 @@ The following command generates a certificate for the key into the file `jetty.c
|
|||
$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt
|
||||
----
|
||||
|
||||
Adding -sha256 ensures to get a certificate with the now recommended SHA-256 signature algorithm.
|
||||
Adding -sha256 ensures to get a certificate with the now recommended SHA-256 signature algorithm.
|
||||
For the those with heightened security in mind, add -b4096 to get a 4069 bit key.
|
||||
|
||||
The next command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
|
||||
The next command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
|
||||
The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
|
|
@ -199,9 +197,9 @@ Email Address []:
|
|||
$
|
||||
----
|
||||
|
||||
You now have the minimal requirements to run an SSL connection and could proceed directly to xref:loading-keys-and-certificates[] to load these keys and certificates into a JSSE keystore.
|
||||
However the browser will not trust the certificate you have generated, and prompts the user to this effect.
|
||||
While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, as shown in the section, xref:generating-csr-from-openssl[] to obtain a certificate.
|
||||
You now have the minimal requirements to run an SSL connection and could proceed directly to xref:loading-keys-and-certificates[] to load these keys and certificates into a JSSE keystore.
|
||||
However the browser _will not_ trust the certificate you have generated, and prompts the user to this effect.
|
||||
While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section, xref:generating-csr-from-openssl[] to obtain a certificate.
|
||||
|
||||
[[using-keys-and-certificates-from-other-sources]]
|
||||
====== Using Keys and Certificates from Other Sources
|
||||
|
|
@ -211,11 +209,11 @@ If you have keys and certificates from other sources, you can proceed directly t
|
|||
[[requesting-trusted-certificate]]
|
||||
===== Requesting a Trusted Certificate
|
||||
|
||||
The keys and certificates generated with JDK's `keytool` and OpenSSL are sufficient to run an SSL connector.
|
||||
The keys and certificates generated with JDK's `keytool` and OpenSSL are sufficient to run an SSL connector.
|
||||
However the browser will not trust the certificate you have generated, and it will prompt the user to this effect.
|
||||
|
||||
To obtain a certificate that most common browsers will trust, you need to request a well-known certificate authority (CA) to sign your key/certificate.
|
||||
Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, and beTRUSTed, among others.
|
||||
To obtain a certificate that most common browsers will trust, you need to request a well-known certificate authority (CA) to sign your key/certificate.
|
||||
Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, and beTRUSTed, among others.
|
||||
Each CA has its own instructions (look for JSSE or OpenSSL sections), but all involve a step that generates a certificate signing request (CSR).
|
||||
|
||||
[[generating-csr-from-keytool]]
|
||||
|
|
@ -249,18 +247,19 @@ Once a CA has sent you a certificate, or if you generated your own certificate w
|
|||
____
|
||||
[NOTE]
|
||||
You need both the private key and the certificate in the JSSE keystore.
|
||||
You should load the certificate into the keystore used to generate the CSR with `keytool`.
|
||||
You should load the certificate into the keystore used to generate the CSR with `keytool`.
|
||||
If your key pair is not already in a keystore (for example, because it has been generated with OpenSSL), you need to use the PKCS12 format to load both key and certificate (see link:#loading-keys-and-certificates-via-pkcks12[PKCKS12 Keys &Certificates]).
|
||||
____
|
||||
|
||||
[[loading-certificates-with-keytool]]
|
||||
====== Loading Certificates with keytool
|
||||
|
||||
You can use `keytool` to load a certificate in PEM form directly into a keystore.
|
||||
The PEM format is a text encoding of certificates; it is produced by OpenSSL, and is returned by some CAs.
|
||||
You can use `keytool` to load a certificate in PEM form directly into a keystore.
|
||||
The PEM format is a text encoding of certificates; it is produced by OpenSSL, and is returned by some CAs.
|
||||
An example PEM file is:
|
||||
|
||||
....
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
jetty.crt
|
||||
-----BEGIN CERTIFICATE-----
|
||||
MIICSDCCAfKgAwIBAgIBADANBgkqhkiG9w0BAQQFADBUMSYwJAYDVQQKEx1Nb3J0
|
||||
|
|
@ -277,7 +276,7 @@ cnRiYXkub3JnggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADQQA6NkaV
|
|||
OtXzP4ayzBcgK/qSCmF44jdcARmrXhiXUcXzjxsLjSJeYPJojhUdC2LQKy+p4ki8
|
||||
Rcz6oCRvCGCe5kDB
|
||||
-----END CERTIFICATE-----
|
||||
....
|
||||
----
|
||||
|
||||
The following command loads a PEM encoded certificate in the `jetty.crt` file into a JSSE keystore:
|
||||
|
||||
|
|
@ -296,7 +295,7 @@ $ openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt
|
|||
[[loading-keys-and-certificates-via-pkcks12]]
|
||||
====== Loading Keys and Certificates via PKCS12
|
||||
|
||||
If you have a key and certificate in separate files, you need to combine them into a PKCS12 format file to load into a new keystore.
|
||||
If you have a key and certificate in separate files, you need to combine them into a PKCS12 format file to load into a new keystore.
|
||||
The certificate can be one you generated yourself or one returned from a CA in response to your CSR.
|
||||
|
||||
The following OpenSSL command combines the keys in `jetty.key` and the certificate in the `jetty.crt` file into the `jetty.pkcs12` file:
|
||||
|
|
@ -314,11 +313,14 @@ $ cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt > cert-cha
|
|||
$ openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12
|
||||
----
|
||||
|
||||
The order of certificates must be from server to rootCA, as per RFC2246 section 7.4.2.
|
||||
____
|
||||
[NOTE]
|
||||
The order of certificates must be from server to rootCA, as per link:https://www.ietf.org/rfc/rfc2246.txt[RFC2246 section 7.4.2.]
|
||||
____
|
||||
|
||||
OpenSSL asks for an __export password__.
|
||||
A non-empty password is required to make the next step work.
|
||||
Then load the resulting PKCS12 file into a JSSE keystore with `keytool`:
|
||||
OpenSSL asks for an __export password__.
|
||||
A non-empty password is required to make the next step work.
|
||||
Load the resulting PKCS12 file into a JSSE keystore with `keytool`:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -328,11 +330,11 @@ $ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destke
|
|||
[[renewing-certificates]]
|
||||
===== Renewing Certificates
|
||||
|
||||
If you are updating your configuration to use a newer certificate, as when the old one is expiring, just load the newer certificate as described in the section, xref:loading-keys-and-certificates[].
|
||||
If you are updating your configuration to use a newer certificate, as when the old one is expiring, just load the newer certificate as described in the section, xref:loading-keys-and-certificates[].
|
||||
If you imported the key and certificate originally using the PKCS12 method, use an alias of "1" rather than "jetty", because that is the alias the PKCS12 process enters into the keystore.
|
||||
|
||||
[[configuring-sslcontextfactory]]
|
||||
==== Configuring the Jetty `SslContextFactory`
|
||||
==== Configuring the Jetty SslContextFactory
|
||||
|
||||
The generated SSL certificates from above are held in the key store are configured in an instance of link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html[SslContextFactory] object.
|
||||
|
||||
|
|
@ -349,26 +351,26 @@ The `SslContextFactory` is responsible for:
|
|||
* https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol[OCSP] Support
|
||||
* Client Authentication Support
|
||||
|
||||
For Jetty Connectors, the configured `SslContextFactory` is injected into a specific `ServerConnector` `SslConnectionFactory`.
|
||||
For Jetty Connectors, the configured `SslContextFactory` is injected into a specific ServerConnector `SslConnectionFactory`.
|
||||
|
||||
For Jetty Clients, the various constructors support using a configured `SslContextFactory`.
|
||||
|
||||
While the `SslContextFactory` can operate without a keystore (this mode is most suitable for the various Jetty Clients) it is best if you at least configure the keystore you are using.
|
||||
While the `SslContextFactory` can operate without a keystore (this mode is most suitable for the various Jetty Clients) it is best practice to at least configure the keystore being used.
|
||||
|
||||
setKeyStorePath::
|
||||
The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client).
|
||||
____
|
||||
[NOTE]
|
||||
As a keystore is vital security information, it can be desirable to locate the file in a directory with very restricted access.
|
||||
As a keystore is vital security information, it can be desirable to locate the file in a directory with *very* restricted access.
|
||||
____
|
||||
|
||||
setKeyStorePassword::
|
||||
The keystore password may be set here in plain text, or as some protection from casual observation, it may be obfuscated using the link:{JDURL}/org/eclipse/jetty/util/security/Password.html[Password] class.
|
||||
The keystore password may be set here in plain text, or as some measure of protection from casual observation, it may be obfuscated using the link:{JDURL}/org/eclipse/jetty/util/security/Password.html[Password] class.
|
||||
setTrustStorePath::
|
||||
This is used if validating client certificates and is typically set to the same path as the keystore.
|
||||
setKeyManagerPassword::
|
||||
Password that is passed to the `KeyManagerFactory.init(...)`.
|
||||
If there is no `keymanagerpassword`, then the `keystorepassword` is used instead.
|
||||
The password that is passed to the `KeyManagerFactory.init(...)`.
|
||||
If there is no `keymanagerpassword`, then the `keystorepassword` is used instead.
|
||||
If there is no `trustmanager` set, then the keystore is used as the trust store and the `keystorepassword` is used as the truststore password.
|
||||
setExcludeCipherSuites / setIncludeCipherSuites::
|
||||
This allows for the customization of the selected Cipher Suites that will be used by SSL/TLS.
|
||||
|
|
@ -425,26 +427,26 @@ jetty.sslContext.keyStorePassword::
|
|||
|
||||
==== Configuring SNI
|
||||
|
||||
From Java 8, the JVM contains support for the http://en.wikipedia.org/wiki/Server_Name_Indication[Server Name Indicator (SNI)] extension, which allows a SSL connection handshake to indicate one or more DNS names that it applies to.
|
||||
To support this, the `ExtendedSslContextFactory` is used that will look for multiple X509 certificates within the keystore, each of which may have multiple DNS names (including wildcards) associated with the http://en.wikipedia.org/wiki/SubjectAltName[Subject Alternate Name] extension.
|
||||
From Java 8, the JVM contains support for the http://en.wikipedia.org/wiki/Server_Name_Indication[Server Name Indicator (SNI)] extension, which allows a SSL connection handshake to indicate one or more DNS names that it applies to.
|
||||
To support this, the `ExtendedSslContextFactory` is used that will look for multiple X509 certificates within the keystore, each of which may have multiple DNS names (including wildcards) associated with the http://en.wikipedia.org/wiki/SubjectAltName[Subject Alternate Name] extension.
|
||||
When using the `ExtendedSSlContextFactory`, the correct certificate is automatically selected if the SNI extension is present in the handshake.
|
||||
|
||||
[[configuring-sslcontextfactory-cipherSuites]]
|
||||
==== Disabling/Enabling Specific Cipher Suites
|
||||
|
||||
For example to avoid the BEAST attack it is necessary to configure a specific set of cipher suites. This can either be done via link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html#setIncludeCipherSuites(java.lang.String...)[SslContext.setIncludeCipherSuites(java.lang.String...)] or vialink:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html#setExcludeCipherSuites(java.lang.String...)[SslContext.setExcludeCipherSuites(java.lang.String...)].
|
||||
As an example, to avoid the BEAST attack it is necessary to configure a specific set of cipher suites. This can either be done via link:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html#setIncludeCipherSuites(java.lang.String...)[SslContext.setIncludeCipherSuites(java.lang.String...)] or vialink:{JDURL}/org/eclipse/jetty/util/ssl/SslContextFactory.html#setExcludeCipherSuites(java.lang.String...)[SslContext.setExcludeCipherSuites(java.lang.String...)].
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
It's crucial that you use the exact names of the cipher suites as used/known by the JDK.
|
||||
It's crucial that you use the _exact_ names of the cipher suites as used/known by the JDK.
|
||||
You can get them by obtaining an instance of SSLEngine and call `getSupportedCipherSuites()`.
|
||||
Tools like ssllabs.com might report slightly different names which will be ignored.
|
||||
____
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
It's recommended to install the Java Cryptography Extension (JCE) Unlimited Strength policy files in your JRE to get full strength ciphers like AES-256.
|
||||
They can be found on the http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java download page].
|
||||
It's recommended to install the Java Cryptography Extension (JCE) Unlimited Strength policy files in your JRE to get full strength ciphers such as AES-256.
|
||||
The files can be found on the http://www.oracle.com/technetwork/java/javase/downloads/index.html[Java download page].
|
||||
Just overwrite the two present JAR files in `<JRE_HOME>/lib/security/`.
|
||||
____
|
||||
|
||||
|
|
@ -452,11 +454,11 @@ Both `setIncludeCipherSuites` and `setExcludeCipherSuites` can be fed by the exa
|
|||
|
||||
If you have a need to adjust the Includes or Excludes, then this is best done with a custom blow-in XML that configures the `SslContextFactory` to suit your needs.
|
||||
|
||||
To do this, first create a new `${jetty.base}/etc/tweak-ssl.xml` (thiscan be any name, just avoid prefixing it with "jetty-").
|
||||
To do this, first create a new `${jetty.base}/etc/tweak-ssl.xml` file (this can be any name, just avoid prefixing it with "jetty-").
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
|
||||
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
|
||||
"http://www.eclipse.org/jetty/configure_9_3.dtd">
|
||||
<!-- Tweak SsslContextFactory Includes / Excludes -->
|
||||
<Configure id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory">
|
||||
|
|
@ -473,10 +475,10 @@ To do this, first create a new `${jetty.base}/etc/tweak-ssl.xml` (thiscan be any
|
|||
</Configure>
|
||||
----
|
||||
|
||||
This new XML will configure the id `sslContextFactory` some more (this id is first created by the `ssl` module and its associated `${jetty.home}/etc/jetty-ssl-context.xml`).
|
||||
This new XML will configure the id `sslContextFactory` further (this id is first created by the `ssl` module and its associated `${jetty.home}/etc/jetty-ssl-context.xml`).
|
||||
You can do anything you want with the `SslContextFactory` in use by the Jetty Distribution from this tweaked XML.
|
||||
|
||||
To make sure that your `${jetty.base}` uses this new XML, add it to the end of your `${jetty.base}/start.ini`
|
||||
To make sure that your `${jetty.base}` uses this new XML, add it to the end of your `${jetty.base}/start.ini` or `${jetty.base}/start.d/server.ini`.
|
||||
|
||||
[source, plain, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -488,14 +490,14 @@ $ tail start.ini
|
|||
# Module: https
|
||||
--module=https
|
||||
etc/tweak-ssl.xml
|
||||
$
|
||||
$
|
||||
----
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
The default `SslContextFactory` implementation applies the latest SSL/TLS recommendations surrounding vulnerabilities in SSL/TLS.
|
||||
Check the release notes (The `VERSION.txt` found in the root of the Jetty Distribution, or the http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.eclipse.jetty%22%20AND%20a%3A%22jetty-project%22[alternate (classified 'version') artifacts for the `jetty-project` component]on Maven Central) for updates.
|
||||
The Java JVM is also applying exclusions at the JVM level, and as such, if you have a need to enable something that is generally accepted by the industry as being insecure or vulnerable you will likely have to enable it in BOTH the Java JVM and the Jetty configuration.
|
||||
Check the release notes (the `VERSION.txt` found in the root of the Jetty Distribution, or the http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.eclipse.jetty%22%20AND%20a%3A%22jetty-project%22[alternate (classified 'version') artifacts for the `jetty-project` component]on Maven Central) for updates.
|
||||
The Java JVM is also applying exclusions at the JVM level and as such if you have a need to enable something that is generally accepted by the industry as being insecure or vulnerable you will likely have to enable it in BOTH the Java JVM and the Jetty configuration.
|
||||
____
|
||||
|
||||
____
|
||||
|
|
@ -503,9 +505,9 @@ ____
|
|||
You can enable the `org.eclipse.jetty.util.ssl` named logger at DEBUG level to see what the list of selected Protocols and Cipher suites are at startup of Jetty.
|
||||
____
|
||||
|
||||
Some other Include / Exclude examples:
|
||||
Additional Include / Exclude examples:
|
||||
|
||||
Example: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex:
|
||||
*Example*: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex:
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -516,7 +518,7 @@ Example: Include all ciphers which support https://en.wikipedia.org/wiki/Forward
|
|||
<Item>TLS_DHE_RSA.*</Item>
|
||||
<Item>TLS_ECDHE.*</Item>
|
||||
</Array>
|
||||
</Set>
|
||||
</Set>
|
||||
----
|
||||
|
||||
*Example*: Exclude all old, insecure or anonymous cipher suites:
|
||||
|
|
@ -534,7 +536,7 @@ Example: Include all ciphers which support https://en.wikipedia.org/wiki/Forward
|
|||
<Item>.*DSS.*</Item>
|
||||
</Array>
|
||||
</Arg>
|
||||
</Call>
|
||||
</Call>
|
||||
----
|
||||
|
||||
*Example*: Since 2014 SSLv3 is considered insecure and should be disabled.
|
||||
|
|
@ -551,7 +553,7 @@ Example: Include all ciphers which support https://en.wikipedia.org/wiki/Forward
|
|||
<Item>SSLv3</Item>
|
||||
</Array>
|
||||
</Arg>
|
||||
</Call>
|
||||
</Call>
|
||||
----
|
||||
|
||||
____
|
||||
|
|
@ -563,5 +565,5 @@ ____
|
|||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
----
|
||||
<Set name="renegotiationAllowed">FALSE</Set>
|
||||
<Set name="renegotiationAllowed">FALSE</Set>
|
||||
----
|
||||
|
|
|
|||
|
|
@ -17,28 +17,28 @@
|
|||
[[setting-port80-access]]
|
||||
=== Setting Port 80 Access for a Non-Root User
|
||||
|
||||
On Unix-based systems, port 80 is protected; typically only the superuser root can open it. For security reasons, it is not desirable to run the server as root.
|
||||
This page presents several options to access port 80 as a non-root user, including using ipchains, iptables, Jetty's SetUID feature, xinetd, and the Solaris 10 User Rights Management Framework.
|
||||
On Unix-based systems, port 80 is protected; typically only the superuser `root` can open it. For security reasons, it is not desirable to run the server as `root`.
|
||||
This page presents several options to access port 80 as a non-root user, including using `ipchains`, `iptables`, Jetty's SetUID feature, `xinetd`, and the Solaris 10 User Rights Management Framework.
|
||||
|
||||
[[using-ipchains]]
|
||||
==== Using ipchains
|
||||
|
||||
On some Linux systems you can use the _ipchains REDIRECT_ mechanism to redirect from one port to another inside the kernel (if ipchains is not available, then usually iptables is):
|
||||
On some Linux systems you can use the _ipchains REDIRECT_ mechanism to redirect from one port to another inside the kernel (if `ipchains` is not available, then `iptables` usually is):
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
# /sbin/ipchains -I input --proto TCP --dport 80 -j REDIRECT 8080
|
||||
----
|
||||
|
||||
This command instructs the system as follows: "Insert into the kernel's packet filtering the following as the first rule to check on incoming packets: if the protocol is TCP and the destination port is 80, redirect the packet to port 8080".
|
||||
Be aware that your kernel must be compiled with support for ipchains (virtually all stock kernels are).
|
||||
You must also have the ipchains command-line utility installed.
|
||||
This command instructs the system as follows: "Insert into the kernel's packet filtering the following as the first rule to check on incoming packets: if the protocol is TCP and the destination port is 80, redirect the packet to port 8080".
|
||||
Be aware that your kernel must be compiled with support for `ipchains` (virtually all stock kernels are).
|
||||
You must also have the `ipchains` command-line utility installed.
|
||||
You can run this command at any time, preferably just once, since it inserts another copy of the rule every time you run it.
|
||||
|
||||
[[using-iptables]]
|
||||
==== Using iptables
|
||||
|
||||
On many Linux systems you can use the iptables REDIRECT mechanism to redirect from one port to another inside the kernel (if iptables is not available, then usually ipchains is).
|
||||
On many Linux systems you can use the `iptables` REDIRECT mechanism to redirect from one port to another inside the kernel (if `iptables` is not available, then usually `ipchains` is).
|
||||
|
||||
You need to add something like the following to the startup scripts or your firewall rules:
|
||||
|
||||
|
|
@ -47,26 +47,26 @@ You need to add something like the following to the startup scripts or your fire
|
|||
# /sbin/iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080
|
||||
----
|
||||
|
||||
The underlying model of iptables is different from ipchains, so the forwarding normally happens only to packets originating off-box.
|
||||
You also need to allow incoming packets to port 8080 if you use iptables as a local firewall.
|
||||
The underlying model of `iptables` is different from `ipchains`, so the forwarding normally happens only to packets originating outside of the server itself.
|
||||
You also need to allow incoming packets to port 8080 if you use `iptables` as a local firewall.
|
||||
|
||||
Be careful to place rules like this one early in your _input_ chain.
|
||||
Such rules must precede any rule that accepts the packet, otherwise the redirection won't occur.
|
||||
Be careful to place rules like this one early in your _input_ chain.
|
||||
Such rules must precede any rule that accepts the packet, otherwise the redirection won't occur.
|
||||
You can insert as many rules as required if your server needs to listen on multiple ports, as for HTTPS.
|
||||
|
||||
[[configuring-jetty-setuid-feature]]
|
||||
==== Configuring Jetty's SetUID Feature
|
||||
|
||||
http://en.wikipedia.org/wiki/Setuid[SetUID] is a technique that uses Unix-like file system access right to allow users to run an executable that would otherwise require higher privileges.
|
||||
http://en.wikipedia.org/wiki/Setuid[SetUID] is a technique that uses Unix-like file system access rights to allow users to run an executable that would otherwise require higher privileges.
|
||||
|
||||
Jetty's `SetUID` module allows you to run Jetty as a normal user even when you need to run Jetty on port 80 or 443.
|
||||
|
||||
To use it with the Jetty distribution:
|
||||
|
||||
1. Ensure that you have the `http.mod` (and link:#quickstart-starting-https[https.mod] if you are using SSL) link:#startup-modules[modules enabled] for the link:#creating-jetty-base[base] you are using.
|
||||
. Ensure that you have the `http.mod` (and link:#quickstart-starting-https[https.mod] if you are using SSL) link:#startup-modules[modules enabled] for the link:#creating-jetty-base[base] you are using.
|
||||
The `http.mod` is enabled by default in the distribution, while the link:#quickstart-starting-https[https.mod] is only enabled in the link:#demo-webapps-base[demo-base] directory.
|
||||
2. Ensure that you have link:#quickstart-changing-jetty-port[changed the http port] to 80 (and link:#quickstart-changing-https-port[changed the https port] to 443 if you are using SSL).
|
||||
3. Enable the `setuid.mod` module:
|
||||
. Ensure that you have link:#quickstart-changing-jetty-port[changed the http port] to 80 (and link:#quickstart-changing-https-port[changed the https port] to 443 if you are using SSL).
|
||||
. Enable the `setuid.mod` module:
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -76,16 +76,17 @@ The `http.mod` is enabled by default in the distribution, while the link:#quicks
|
|||
____
|
||||
[NOTE]
|
||||
The --add-to-start command will enable the setuid module for this and all subsequent executions of jetty.
|
||||
There are other ways to enable the module, such as just for this execution.
|
||||
There are other ways to enable the module, such as for a single execution.
|
||||
For more information on the alternatives see the section on link:#startup-modules[Managing Startup Modules].
|
||||
____
|
||||
4. Edit the configuration for the `setuid` module to substitute the `userid` and `groupid` of the user to switch to after starting.
|
||||
If you used the `--add-to-start` command, this configuration is in the `start.ini` file.
|
||||
If you used the `--add-to-startd` command instead, this configuration is in the `start.d/setuid.ini `file instead.
|
||||
|
||||
Here are the lines to configure:
|
||||
. Edit the configuration for the `setuid` module to substitute the `userid` and `groupid` of the user to switch to after starting.
|
||||
If you used the `--add-to-start` command, this configuration is in the `start.ini` file.
|
||||
If you used the `--add-to-startd` command instead, this configuration is in the `start.d/setuid.ini` file instead.
|
||||
|
||||
Below are the lines to configure:
|
||||
+
|
||||
[source,text]
|
||||
[source, text, subs="{sub-order}"]]
|
||||
----
|
||||
jetty.startServerAsPrivileged=false
|
||||
jetty.username=foo
|
||||
|
|
@ -95,12 +96,12 @@ jetty.umask=002
|
|||
+
|
||||
____
|
||||
[NOTE]
|
||||
As well as opening the connectors as root, you can also have jetty start the Server as root before changing to the non-root user.
|
||||
As well as opening the connectors as `root`, you can also have Jetty start the Server as `root` before changing to the non-`root` user.
|
||||
____
|
||||
|
||||
5. You now need a native code library to do the user switching.
|
||||
This code is hosted as part of the Jetty ToolChain project and it is released independently from Jetty itself.
|
||||
You can find the source code https://github.com/eclipsejetty.toolchain[here] in the https://github.com/eclipse/jetty.toolchain/jetty-setuid[jetty-setuid] project.
|
||||
. A native code library is required to perform user switching.
|
||||
This code is hosted as part of the Jetty ToolChain project and is released independently from Jetty itself.
|
||||
You can find the source code https://github.com/eclipsejetty.toolchain[here] in the https://github.com/eclipse/jetty.toolchain/jetty-setuid[jetty-setuid] project.
|
||||
Build it locally, which will produce a native library appropriate for the operating system:
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
|
|
@ -108,11 +109,12 @@ Build it locally, which will produce a native library appropriate for the operat
|
|||
# mvn clean install
|
||||
----
|
||||
+
|
||||
If you built on a linux machine you will find the native library in `jetty-setuid/libsetuid-linux/target/libsetuid-linux.so`.
|
||||
If you built on a linux machine you will find the native library in `jetty-setuid/libsetuid-linux/target/libsetuid-linux.so`.
|
||||
If you built on a different operating system you will find the library in a different subdirectory, with the name containing the name of the operating system.
|
||||
You might like to copy this file into your jetty distribution's lib directory.
|
||||
6. Start jetty as the root user in your base directory, providing the location of the native library to java.
|
||||
Here's an example of how to do it on the command line, assuming were are in the link:#demo-webapps-base[demo-base] directory:
|
||||
You may want copy this file into your Jetty distribution's lib directory.
|
||||
|
||||
. Start Jetty as the `root` user in your base directory, providing the location of the native library to Java.
|
||||
Below is an example of how to do it from the command line, assuming you are in the link:#demo-webapps-base[demo-base] directory:
|
||||
+
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
|
|
@ -120,6 +122,7 @@ Here's an example of how to do it on the command line, assuming were are in the
|
|||
----
|
||||
|
||||
[[using-solaris10-user-rights-management-framework]]
|
||||
|
||||
==== Using the Solaris 10 User Rights Management Framework
|
||||
|
||||
Solaris 10 provides a User Rights Management framework that can permit users and processes superuser-like abilities:
|
||||
|
|
|
|||
|
|
@ -17,25 +17,25 @@
|
|||
[[quickstart-webapp]]
|
||||
=== Quickstart Webapps
|
||||
|
||||
The auto discovery features of the Servlet specification can make deployments slow and uncertain.
|
||||
The auto discovery features of the Servlet specification can make deployments slow and uncertain.
|
||||
Auto discovery of Web Application configuration can be useful during the development of a webapp as it allows new features and frameworks to be enabled simply by dropping in a jar file.
|
||||
However, for deployment, the need to scan the contents of many jars can have a significant impact of the start time of a webapp.
|
||||
|
||||
From Jetty release 9.2.0.v20140526, the included quickstart module allows a webapp to be pre-scanned and preconfigured.
|
||||
This means that all the scanning is done prior to deployment and all configuration is encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed before deploying.
|
||||
From Jetty release 9.2.0.v20140526, the included quickstart module allows a webapp to be pre-scanned and preconfigured.
|
||||
This means that all the scanning is done prior to deployment and all configuration is encoded into an effective `web.xml`, called `WEB-INF/quickstart-web.xml`, which can be inspected to understand what will be deployed before deploying.
|
||||
Not only does the `quickstart-web.xml` contain all the discovered Servlets, Filters and Constraints, but it also encodes as context parameters all discovered:
|
||||
|
||||
* ServletContainerInitializers
|
||||
* HandlesTypes classes
|
||||
* Taglib Descriptors
|
||||
|
||||
With the quickstart mechanism, Jetty is able to entirely bypass all scanning and discovery modes and start a webapp in a predictable and fast way.
|
||||
With the quickstart mechanism, Jetty is able to entirely bypass all scanning and discovery modes and start a webapp in a predictable and fast way.
|
||||
Tests have shown that webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds.
|
||||
|
||||
==== Setting up Quickstart
|
||||
|
||||
To use quickstart the module has to be available to the Jetty instance.
|
||||
In a maven project this is done by adding a dependency on the artifact ID `jetty-quickstart`.
|
||||
In a maven project this is done by adding a dependency on the artifact ID `jetty-quickstart`.
|
||||
In a standard Jetty distribution it can be configured with the following command:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
|
|
@ -43,7 +43,7 @@ In a standard Jetty distribution it can be configured with the following command
|
|||
$ java -jar $JETTY_HOME/start.jar --add-to-startd=quickstart
|
||||
----
|
||||
|
||||
Deployed webapps need to be instances of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.webapp.WebAppContext`.
|
||||
Deployed webapps need to be instances of link:{JDURL}/org/eclipse/jetty/quickstart/QuickStartWebApp.html[`org.eclipse.jetty.quickstart.QuickStartWebApp`] rather than the normal `org.eclipse.jetty.webapp.WebAppContext`.
|
||||
If a web application already has a `webapps/myapp.xml` file, simply change the class in the Configure element.
|
||||
Otherwise, create a `webapps/myapp.xml` file as follows:
|
||||
|
||||
|
|
@ -58,26 +58,26 @@ Otherwise, create a `webapps/myapp.xml` file as follows:
|
|||
</Configure>
|
||||
----
|
||||
|
||||
==== Preconfiguring the web application
|
||||
|
||||
If the `QuickStateWebApp` method `setAutoPreconfigure(true)` is called (see example in myapp.xml above), then the first time the webapp is deployed a `WEB-INF/quickstart-web.xml` file will be generated that contains the effective `web.xml` for all the discovered configuration.
|
||||
On subsequent deployments, all the discovery steps are skipped and the `quickstart-web.xml` is used directly to configure the web application.
|
||||
|
||||
It is also possible to preconfigure a war file manually by running the class link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[org.eclipse.jetty.quickstart.PreconfigureQuickStartWar] with the jetty-all-uber (aggregate) jar:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
----
|
||||
$ java -cp jetty-all-{VERSION}-uber.jar org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
|
||||
----
|
||||
|
||||
This will create the `quickstart-web.xml` file before the first deployment.
|
||||
Note that this can also be a good debugging tool for discovered configuration and if run with debug turned on the origin of every element is included in the `quickstart-web.xml` file.
|
||||
Run the class with no arguments to see other runtime options.
|
||||
// ==== Preconfiguring the web application
|
||||
//
|
||||
// If the `QuickStateWebApp` method `setAutoPreconfigure(true)` is called (see example in myapp.xml above), then the first time the webapp is deployed a `WEB-INF/quickstart-web.xml` file will be generated that contains the effective `web.xml` for all the discovered configuration.
|
||||
// On subsequent deployments, all the discovery steps are skipped and the `quickstart-web.xml` is used directly to configure the web application.
|
||||
//
|
||||
// It is also possible to preconfigure a war file manually by running the class link:{JDURL}/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html[org.eclipse.jetty.quickstart.PreconfigureQuickStartWar] with the jetty-all-uber (aggregate) jar:
|
||||
//
|
||||
// [source, screen, subs="{sub-order}"]
|
||||
// ----
|
||||
// $ java -cp jetty-all-{VERSION}-uber.jar org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
|
||||
// ----
|
||||
//
|
||||
// This will create the `quickstart-web.xml` file before the first deployment.
|
||||
// Note that this can also be a good debugging tool for discovered configuration and if run with debug turned on the origin of every element is included in the `quickstart-web.xml` file.
|
||||
// Run the class with no arguments to see other runtime options.
|
||||
|
||||
==== Avoiding TLD Scans with precompiled JSPs
|
||||
|
||||
Of course precompiling JSPs is an excellent way to improve the start time of a web application.
|
||||
Since jetty 9.2.0, the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped.
|
||||
Of course precompiling JSPs is an excellent way to improve the start time of a web application.
|
||||
Since jetty 9.2.0, the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped.
|
||||
This can be done by adding a `context-param` to the `web.xml` file (this is done automatically by the Jetty Maven JSPC plugin):
|
||||
|
||||
[source, xml, subs="{sub-order}"]
|
||||
|
|
@ -90,8 +90,8 @@ This can be done by adding a `context-param` to the `web.xml` file (this is done
|
|||
|
||||
==== Bypassing start.jar
|
||||
|
||||
The Jetty `start.jar` mechanism is a very powerful and flexible mechanism for constructing a `classpath` and executing a configuration encoded in Jetty XML format.
|
||||
However, this mechanism does take some time to build the `classpath`.
|
||||
The Jetty `start.jar` mechanism is a very powerful and flexible mechanism for constructing a `classpath` and executing a configuration encoded in Jetty XML format.
|
||||
However, this mechanism does take some time to build the `classpath`.
|
||||
The start.jar mechanism can be bypassed by using the `–dry-run` option to generate and reuse a complete command line to start Jetty at a later time:
|
||||
|
||||
[source, screen, subs="{sub-order}"]
|
||||
|
|
@ -100,5 +100,5 @@ $ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
|
|||
$ eval $RUN
|
||||
----
|
||||
|
||||
Note that `--dry-run` may create a properties file in the temp directory and include it on the generated command line.
|
||||
Note that `--dry-run` may create a properties file in the temp directory and include it on the generated command line.
|
||||
If so, then a copy of the temporary properties file should be taken and the command line updated with it's new persistent location.
|
||||
|
|
|
|||
Loading…
Reference in New Issue