mirror of
https://github.com/jetty/jetty.project.git
synced 2025-03-01 11:29:29 +00:00
Improvements to the Jetty documentation.
Ported and updated the documentation about configuring Jetty behind a load balancer. Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet
parent
6d9e9e7d0a
commit
e99f5835e9
@ -20,4 +20,3 @@
|
||||
== HTTP/2
|
||||
|
||||
include::configuring-push.adoc[]
|
||||
include::configuring-haproxy.adoc[]
|
||||
|
||||
@ -1,193 +0,0 @@
|
||||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under
|
||||
// the terms of the Eclipse Public License 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0
|
||||
//
|
||||
// This Source Code may also be made available under the following
|
||||
// Secondary Licenses when the conditions for such availability set
|
||||
// forth in the Eclipse Public License, v. 2.0 are satisfied:
|
||||
// the Apache License v2.0 which is available at
|
||||
// https://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[http2-configuring-haproxy]]
|
||||
=== Configuring HAProxy and Jetty
|
||||
|
||||
Typical website deployments have Apache (or Nginx) configured as reverse proxy to talk to one or more backend Jetty instances.
|
||||
This configuration cannot be used for HTTP/2 because Apache does not yet support HTTP/2 (nor does Nginx).
|
||||
|
||||
http://haproxy.org[HAProxy] is an open source solution that offers load balancing and proxying for TCP and HTTP based application, and can be used as a replacement for Apache or Nginx when these are used as reverse proxies and has the major benefit that supports HTTP/2.
|
||||
It also offers load balancing and several other features which can position it as a complete replacement for Apache or Nginx.
|
||||
|
||||
The deployment proposed here will have HAProxy play the role that Apache and Nginx usually do: to perform the TLS offloading (that is, decrypt and encrypt TLS) and then forwarding the now clear-text traffic to a backend Jetty server, speaking either HTTP/1.1 or HTTP/2.
|
||||
|
||||
The instructions that follow are for Linux.
|
||||
|
||||
[[http2-haproxy-install]]
|
||||
==== Installing HAProxy
|
||||
|
||||
You will need HAProxy 1.5 or later, because it provides support for SSL and ALPN, both required by HTTP/2. Most Linux distributions have the HAProxy package available to be installed out of the box. For example on Ubuntu 15.04:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ sudo apt-get install haproxy
|
||||
....
|
||||
|
||||
Alternatively you can download the HAProxy source code and build it on your environment by following the README bundled with the HAProxy source code tarball.
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
HAProxy supports ALPN only if built with OpenSSL 1.0.2 or greater.
|
||||
Use `haproxy -vv` to know with which OpenSSL version HAProxy has been built.
|
||||
____
|
||||
|
||||
[[http2-haproxy-ssl]]
|
||||
==== Setup SSL for HAProxy
|
||||
|
||||
HAProxy will perform the TLS decryption and encryption much more efficiently than a Java implementation.
|
||||
|
||||
HAProxy will need a single file containing the X509 certificates and the private key, all in https://en.wikipedia.org/wiki/X.509[PEM format], with the following order:
|
||||
|
||||
1. The site certificate; this certificate's Common Name refers to the site domain (for example: CN=*.webtide.com) and is signed by Certificate Authority #1.
|
||||
2. The Certificate Authority #1 certificate; this certificate may be signed by Certificate Authority #2.
|
||||
3. The Certificate Authority #2 certificate; this certificate may be signed by Certificate Authority #3; and so on until the Root Certificate Authority.
|
||||
4. The Root Certificate Authority certificate.
|
||||
5. The private key corresponding to the site certificate.
|
||||
|
||||
Let's use `keytool` to generate a self signed certificate:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ keytool -genkeypair -keyalg RSA -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -ext SAN=DNS:domain.com
|
||||
What is your first and last name?
|
||||
[Unknown]: *.domain.com
|
||||
What is the name of your organizational unit?
|
||||
[Unknown]: Unit
|
||||
What is the name of your organization?
|
||||
[Unknown]: Domain
|
||||
What is the name of your City or Locality?
|
||||
[Unknown]: Torino
|
||||
What is the name of your State or Province?
|
||||
[Unknown]: TO
|
||||
What is the two-letter country code for this unit?
|
||||
[Unknown]: IT
|
||||
Is CN=*.domain.com, OU=Unit, O=Domain, L=Torino, ST=TO, C=IT correct?
|
||||
[no]: yes
|
||||
....
|
||||
|
||||
The above command will generate a self signed certificate and private key for `domain.com` and subdomains, stored in the `keystore.p12` file in PKCS#12 format.
|
||||
We need to extract the certificate and the private key in PEM format.
|
||||
|
||||
To extract the certificate into `certificate.pem`:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ keytool -exportcert -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -rfc -file certificate.pem
|
||||
....
|
||||
|
||||
To export the private key into `private_key.pem`:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ openssl pkcs12 -in keystore.p12 -nodes -nocerts -out private_key.pem -passin pass:storepwd
|
||||
....
|
||||
|
||||
At this point you just need to concatenate the two files into one, in the correct order:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ cat certificate.pem private_key.pem > domain.pem
|
||||
....
|
||||
|
||||
The `domain.pem` file will be used later by HAProxy.
|
||||
|
||||
[[http2-haproxy-cfg]]
|
||||
==== HAProxy Configuration File
|
||||
|
||||
Now we can setup `haproxy.cfg` to configure HAProxy.
|
||||
This is a minimal configuration:
|
||||
|
||||
[source, ,subs="{sub-order}"]
|
||||
....
|
||||
global
|
||||
tune.ssl.default-dh-param 1024
|
||||
|
||||
defaults
|
||||
timeout connect 10000ms
|
||||
timeout client 60000ms
|
||||
timeout server 60000ms
|
||||
|
||||
frontend fe_http
|
||||
mode http
|
||||
bind *:80
|
||||
# Redirect to https
|
||||
redirect scheme https code 301
|
||||
|
||||
frontend fe_https
|
||||
mode tcp
|
||||
bind *:443 ssl no-sslv3 crt domain.pem ciphers TLSv1.2 alpn h2,http/1.1
|
||||
default_backend be_http
|
||||
|
||||
backend be_http
|
||||
mode tcp
|
||||
server domain 127.0.0.1:8282
|
||||
....
|
||||
|
||||
The HAProxy configuration file works in the following way.
|
||||
The `fe_http` front-end accepts connections on port 80 and redirects them to use the `https` scheme.
|
||||
|
||||
The `fe_https` front-end accepts connections on port 443 and it is where the TLS decryption/encryption happens.
|
||||
You must specify the path to the PEM file containing the TLS key material (the `crt domain.pem` part), the ciphers that are suitable for HTTP/2 (the `ciphers TLSv1.2`), and the ALPN protocols supported (the `alpn h2,http/1.1` ).
|
||||
This front-end then forwards the now decrypted bytes to the back-end in `mode tcp`. The `mode tcp` says that HAProxy will not try to interpret the bytes as HTTP/1.1 but instead opaquely forward them to the back-end.
|
||||
|
||||
The `be_http` back-end will forward (again in `mode tcp`) the clear-text bytes to a Jetty connector that talks clear-text HTTP/2 and HTTP/1.1 on port 8282.
|
||||
|
||||
[[http2-haproxy-jetty]]
|
||||
==== Setup Jetty for HTTP/2 and HTTP/1.1
|
||||
|
||||
The Jetty setup follows the steps of having Jetty installed in the `JETTY_HOME` directory, creating a `JETTY_BASE` directory and initializing it using Jetty's command line tools.
|
||||
You must enable the `http2c` module, that is the module that speaks clear-text HTTP/2.
|
||||
Since the `http2c` module depends on the `http` module, the `http` module will be enabled transitively, and the final setup will therefore support both HTTP/2 and HTTP/1.1 in clear text.
|
||||
|
||||
Additionally, you will also enable the `deploy` module to be able to deploy a sample web application:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ JETTY_BASE=haproxy-jetty-http2
|
||||
$ mkdir $JETTY_BASE
|
||||
$ cd $JETTY_BASE
|
||||
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c,deploy
|
||||
....
|
||||
|
||||
Now let's deploy a demo web application and start Jetty:
|
||||
|
||||
[source,screen, subs="{sub-order}"]
|
||||
....
|
||||
$ cd $JETTY_BASE
|
||||
$ cp $JETTY_HOME/demo-base/webapps/async-rest.war $JETTY_BASE/webapps/
|
||||
$ java -jar $JETTY_HOME/start.jar jetty.http.host=127.0.0.1 jetty.http.port=8282
|
||||
....
|
||||
|
||||
Now you can browse https://domain.com/async-rest (replace `domain.com` with your own domain, or with `localhost`, to make this example work).
|
||||
|
||||
____
|
||||
[NOTE]
|
||||
You want the Jetty connector that listens on port 8282 to be available only to HAProxy, and not to remote clients.
|
||||
For this reason, you want to specify the `jetty.http.host` property on the command line (or in `start.ini`/ `start.d/http.ini` to make this setting persistent) to bind the Jetty connector only on the loopback interface (127.0.0.1), making it available to HAProxy but not to remote clients.
|
||||
If your Jetty instance runs on a different machine and/or on a different (sub)network, you may want to adjust both the back-end section of the HAProxy configuration file and the `jetty.http.host` property to match accordingly.
|
||||
____
|
||||
|
||||
Browsers supporting HTTP/2 will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
|
||||
Likewise, HTTP/1.1 clients will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
|
||||
|
||||
The Jetty connector, configured with the `http2c` module (and therefore transitively with the `http` module) is able to distinguish whether the incoming bytes are HTTP/2 or HTTP/1.1 and will handle the request accordingly.
|
||||
|
||||
The response is relayed back to HAProxy, which will encrypt it and send it back to the remote client.
|
||||
|
||||
This configuration offers you efficient TLS offloading, HTTP/2 support and transparent fallback to HTTP/1.1 for clients that don't support HTTP/1.1.
|
||||
@ -47,6 +47,7 @@ TODO
|
||||
* xref:og-protocols-https[Configure Secure HTTP/1.1 (https)]
|
||||
* xref:og-protocols-http2c[Configure Clear-Text HTTP/2]
|
||||
* xref:og-protocols-http2s[Configure Secure HTTP/2]
|
||||
* xref:og-protocols-proxy[Configure Jetty Behind a Load Balancer or Reverse Proxy]
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
@ -20,5 +20,12 @@ include::modules.adoc[]
|
||||
include::module-bytebufferpool.adoc[]
|
||||
include::module-deploy.adoc[]
|
||||
include::module-http.adoc[]
|
||||
include::module-http2.adoc[]
|
||||
include::module-http2c.adoc[]
|
||||
include::module-http-forwarded.adoc[]
|
||||
include::module-https.adoc[]
|
||||
include::module-server.adoc[]
|
||||
include::module-ssl.adoc[]
|
||||
include::module-ssl-reload.adoc[]
|
||||
include::module-test-keystore.adoc[]
|
||||
include::module-threadpool.adoc[]
|
||||
|
||||
@ -0,0 +1,28 @@
|
||||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under
|
||||
// the terms of the Eclipse Public License 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0
|
||||
//
|
||||
// This Source Code may also be made available under the following
|
||||
// Secondary Licenses when the conditions for such availability set
|
||||
// forth in the Eclipse Public License, v. 2.0 are satisfied:
|
||||
// the Apache License v2.0 which is available at
|
||||
// https://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[og-module-http-forwarded]]
|
||||
==== Module `http-forwarded`
|
||||
|
||||
The `http-forwarded` module provides support for processing the `Forwarded` HTTP header (defined in link:https://tools.ietf.org/html/rfc7239[RFC 7239]) and the now obsoleted `X-Forwarded-*` HTTP headers.
|
||||
|
||||
The module properties are:
|
||||
|
||||
----
|
||||
include::{JETTY_HOME}/modules/http-forwarded.mod[tags=documentation]
|
||||
----
|
||||
@ -40,5 +40,6 @@ include::protocols-http.adoc[]
|
||||
include::protocols-https.adoc[]
|
||||
include::protocols-http2.adoc[]
|
||||
include::protocols-ssl.adoc[]
|
||||
include::protocols-proxy.adoc[]
|
||||
|
||||
// TODO: old_docs/connectors/*.adoc
|
||||
|
||||
@ -0,0 +1,248 @@
|
||||
//
|
||||
// ========================================================================
|
||||
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
|
||||
//
|
||||
// This program and the accompanying materials are made available under
|
||||
// the terms of the Eclipse Public License 2.0 which is available at
|
||||
// https://www.eclipse.org/legal/epl-2.0
|
||||
//
|
||||
// This Source Code may also be made available under the following
|
||||
// Secondary Licenses when the conditions for such availability set
|
||||
// forth in the Eclipse Public License, v. 2.0 are satisfied:
|
||||
// the Apache License v2.0 which is available at
|
||||
// https://www.apache.org/licenses/LICENSE-2.0
|
||||
//
|
||||
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
|
||||
// ========================================================================
|
||||
//
|
||||
|
||||
[[og-protocols-proxy]]
|
||||
==== Configuring Eclipse Jetty Behind a Load Balancer or Reverse Proxy
|
||||
|
||||
You may need to configure one or more Jetty instances behind an _intermediary_, typically a load balancer such as link:https://haproxy.org[HAProxy], or a reverse proxy such as link:https://httpd.apache.org[Apache HTTP Server] or link:https://nginx.org[Nginx].
|
||||
|
||||
[plantuml]
|
||||
----
|
||||
skinparam backgroundColor transparent
|
||||
skinparam monochrome true
|
||||
skinparam shadowing false
|
||||
skinparam padding 5
|
||||
|
||||
scale 1.5
|
||||
|
||||
rectangle client
|
||||
rectangle proxy
|
||||
rectangle "Jetty" as jetty1
|
||||
rectangle "Jetty" as jetty2
|
||||
|
||||
client -- proxy
|
||||
proxy -- jetty1
|
||||
proxy -- jetty2
|
||||
----
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
HAProxy can communicate either HTTP/1.1 or HTTP/2 to backend servers such as Jetty.
|
||||
|
||||
Apache HTTP Server and Nginx can only speak HTTP/1.1 to backend servers such as Jetty, and have no plans to support HTTP/2 towards backend servers.
|
||||
====
|
||||
|
||||
In these setups, typically the proxy performs TLS offloading, and the communication with backend servers happens in clear-text.
|
||||
It is possible, however, to configure the proxy so that all the bytes arriving from the client are tunnelled opaquely to the backend Jetty server (that therefore needs to perform the TLS offloading) and viceversa the bytes arriving from the Jetty server are tunnelled opaquely to the client.
|
||||
|
||||
Also in these setups, the TCP/IP connection terminating on the Jetty servers does not originate from the client, but from the proxy, so that the remote IP address and port number may be reported incorrectly in backend server logs, or worse applications may not work because they need to be able to differentiate different clients based on the client IP address.
|
||||
|
||||
For this reason, intermediaries typically implement at least one of several _de facto_ standards to communicate information about the original client connection to the backend Jetty server.
|
||||
|
||||
Jetty supports two methods to process client information sent by intermediaries:
|
||||
|
||||
* The `Forwarded` HTTP header, defined in link:https://tools.ietf.org/html/rfc7239[RFC 7239] and replacing the old `X-Forwarded-*` headers, defined in xref:og-protocols-proxy-forwarded[this section].
|
||||
* The link:https://www.haproxy.org/download/2.2/doc/proxy-protocol.txt[Proxy Protocol], defined in xref:og-protocols-proxy-protocol[this section].
|
||||
|
||||
In both methods, web applications that call `HttpServletRequest.getRemoteAddr()` will receive the remote client IP address as specified by the client information sent by the intermediary, not the physical IP address of TCP connection with the intermediary.
|
||||
Likewise, `HttpServletRequest.getRemotePort()` will return the remote client IP port as specified by the client information sent by the intermediary, and `HttpServletRequest.isSecure()` will return whether the client made a secure request using the `https` scheme as specified by the client information sent by the intermediary.
|
||||
|
||||
[[og-protocols-proxy-forwarded]]
|
||||
===== Configuring Jetty for the Forwarded Header
|
||||
|
||||
The `Forwarded` HTTP header is added by the intermediary with information about the client and the client request, for example:
|
||||
|
||||
----
|
||||
GET / HTTP/1.1
|
||||
Host: domain.com
|
||||
Forwarded: for=2.36.72.144:21216;proto=https
|
||||
----
|
||||
|
||||
In the example above, the intermediary added the `Forwarded` header specifying that the client remote address is `2.36.72.144:21216` and that the request was made with the `https` scheme.
|
||||
|
||||
Support for the `Forwarded` HTTP header (and its predecessor `X-Forwarded-*` headers) is enabled with the `http-forwarded` Jetty module with the following command (issued from within the `$JETTY_BASE` directory):
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-module=http-forwarded
|
||||
----
|
||||
----
|
||||
INFO : http-forwarded initialized in ${jetty.base}/start.d/http-forwarded.ini
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
With the `http-forwarded` Jetty module enabled, Jetty interprets the `Forwarded` header and makes its information available to web applications via the standard Servlet APIs.
|
||||
|
||||
For further information about configuring the `http-forwarded` Jetty module, see xref:og-module-http-forwarded[this section].
|
||||
|
||||
[[og-protocols-proxy-protocol]]
|
||||
===== Configuring Jetty for the Proxy Protocol
|
||||
|
||||
The link:https://www.haproxy.org/download/2.2/doc/proxy-protocol.txt[Proxy Protocol] is the _de facto_ standard, introduced by link:https://haproxy.org[HAProxy], to communicate client information to backend servers via the TCP connection, rather than via HTTP headers.
|
||||
|
||||
The information about the client connection is sent as a small data frame on each newly established connection.
|
||||
This mechanism is therefore independent of any protocol, so it can be used for TLS, HTTP/1.1, HTTP/2, etc.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
There are 2 versions of the proxy protocol: v1 and v2, both supported by Jetty.
|
||||
|
||||
Proxy protocol v1 is human readable, but it only carries information about the client TCP connection (IP address and IP port).
|
||||
|
||||
Proxy protocol v2 has a binary format, carries the information about the client TCP connection, and can carry additional arbitrary information encoded in pairs `(type, value)` where `type` is a single byte that indicates the value's meaning, and `value` is a variable length byte array that can encode user-defined data.
|
||||
====
|
||||
|
||||
Support for the proxy protocol can be enabled for the clear-text connector or for the secure connector (or both).
|
||||
|
||||
To enable proxy protocol support for the clear-text connector, enable the `proxy-protocol` Jetty module with the following command (issued from within the `$JETTY_BASE` directory):
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-module=proxy-protocol
|
||||
----
|
||||
----
|
||||
INFO : proxy-protocol initialized in ${jetty.base}/start.d/proxy-protocol.ini
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
Starting Jetty yields:
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar
|
||||
----
|
||||
[source,subs=quotes]
|
||||
----
|
||||
2020-10-12 18:44:25.246:INFO :oejs.Server:main: jetty-10.0.0-SNAPSHOT; built: 2020-10-12T13:49:35.796Z; git: 1cd15e8d85feb308527c3df560734fc2ca1bc13c; jvm 15+36-1562
|
||||
2020-10-12 18:44:25.267:INFO :oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/jetty.base/webapps/]
|
||||
2020-10-12 18:44:25.276:INFO :oejs.AbstractConnector:main: Started ServerConnector@7a8c8dcf{[proxy], ##([proxy], http/1.1)##}{0.0.0.0:8080}
|
||||
2020-10-12 18:44:25.285:INFO :oejs.Server:main: Started Server@5c5eefef{STARTING}[10.0.0-SNAPSHOT,sto=5000] @486ms
|
||||
----
|
||||
|
||||
Note how in the example above the list of protocols for the clear-text connector is first `proxy` and then `http/1.1`.
|
||||
For every new TCP connection, Jetty first interprets the proxy protocol bytes with the client information; after this initial proxy protocol processing, Jetty interprets the incoming bytes as HTTP/1.1 bytes.
|
||||
|
||||
Similarly, to enable proxy protocol support for the secure connector, enable the `proxy-protocol-ssl` Jetty module with the following command (issued from within the `$JETTY_BASE` directory):
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-module=proxy-protocol-ssl
|
||||
----
|
||||
----
|
||||
INFO : proxy-protocol-ssl initialized in ${jetty.base}/start.d/proxy-protocol-ssl.ini
|
||||
INFO : Base directory was modified
|
||||
----
|
||||
|
||||
Starting Jetty yields:
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar
|
||||
----
|
||||
[source,subs=quotes]
|
||||
----
|
||||
2020-10-12 19:09:38.397:INFO :oejs.Server:main: jetty-10.0.0-SNAPSHOT; built: 2020-10-12T13:49:35.796Z; git: 1cd15e8d85feb308527c3df560734fc2ca1bc13c; jvm 15+36-1562
|
||||
2020-10-12 19:09:38.417:INFO :oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/jetty.base/webapps/]
|
||||
2020-10-12 19:09:38.605:INFO :oejus.SslContextFactory:main: x509=X509@4a7f959b(mykey,h=[localhost],w=[]) for Server@5403f35f[provider=null,keyStore=file:///tmp/jetty.base/etc/test-keystore.p12,trustStore=file:///tmp/jetty.base/etc/test-keystore.p12]
|
||||
2020-10-12 19:09:38.697:INFO :oejs.AbstractConnector:main: Started ServerConnector@5afa3c9{[proxy], ##([proxy], ssl, http/1.1)##}{0.0.0.0:8443}
|
||||
2020-10-12 19:09:38.705:INFO :oejs.Server:main: Started Server@54d9d12d{STARTING}[10.0.0-SNAPSHOT,sto=5000] @785ms
|
||||
----
|
||||
|
||||
Note how in the example above the list of protocols for the secure connector is first `proxy`, then `ssl` and then `http/1.1`.
|
||||
|
||||
[[og-protocols-proxy-haproxy]]
|
||||
===== Configuring HAProxy and Jetty for HTTP/1.1 and HTTP/2
|
||||
|
||||
link:https://haproxy.org[HAProxy] is an open source solution that offers load balancing and proxying for TCP and HTTP based application, and can be used as a replacement for Apache or Nginx when these are used as reverse proxies.
|
||||
|
||||
The deployment proposed here has HAProxy playing the role that Apache and Nginx usually do: to perform the TLS offloading (that is, decrypt incoming bytes and encrypt outgoing bytes) and then forwarding the now clear-text traffic to a backend Jetty server, speaking either HTTP/1.1 or HTTP/2.
|
||||
Since HAProxy's TLS offloading is based on OpenSSL, it is much more efficient than the Java implementation shipped with OpenJDK.
|
||||
|
||||
After you have installed HAProxy on your system, you want to configure it so that it can perform TLS offloading.
|
||||
|
||||
HAProxy will need a single file containing the X509 certificates and the private key, all in link:https://en.wikipedia.org/wiki/X.509[PEM format], with the following order:
|
||||
|
||||
1. The site certificate; this certificate's Common Name refers to the site domain (for example: CN=*.webtide.com) and is signed by Certificate Authority #1.
|
||||
2. The Certificate Authority #1 certificate; this certificate may be signed by Certificate Authority #2.
|
||||
3. The Certificate Authority #2 certificate; this certificate may be signed by Certificate Authority #3; and so on until the Root Certificate Authority.
|
||||
4. The Root Certificate Authority certificate.
|
||||
5. The private key corresponding to the site certificate.
|
||||
|
||||
Refer to the xref:og-keystore[section about KeyStores] for more information about generating the required certificates and private key.
|
||||
|
||||
Now you can create the HAProxy configuration file (in Linux it's typically `/etc/haproxy/haproxy.cfg).
|
||||
This is a minimal configuration:
|
||||
|
||||
.haproxy.cfg
|
||||
[source,subs=verbatim]
|
||||
----
|
||||
global
|
||||
tune.ssl.default-dh-param 1024
|
||||
|
||||
defaults
|
||||
timeout connect 10000ms
|
||||
timeout client 60000ms
|
||||
timeout server 60000ms
|
||||
|
||||
frontend fe_http <1>
|
||||
mode http
|
||||
bind *:80
|
||||
# Redirect to https
|
||||
redirect scheme https code 301
|
||||
|
||||
frontend fe_https <2>
|
||||
mode tcp
|
||||
bind *:443 ssl no-sslv3 crt /path/to/domain.pem ciphers TLSv1.2 alpn h2,http/1.1
|
||||
default_backend be_http
|
||||
|
||||
backend be_http <3>
|
||||
mode tcp
|
||||
server domain 127.0.0.1:8282 send-proxy-v2
|
||||
----
|
||||
<1> The `fe_http` front-end accepts connections on port 80 and redirects them to use the `https` scheme.
|
||||
<2> The `fe_https` front-end accepts connections on port 443, and it is where the TLS decryption/encryption happens.
|
||||
You must specify the path to the PEM file containing the TLS key material (the `crt /path/to/domain.pem` part), the ciphers that are suitable for HTTP/2 (`ciphers TLSv1.2`), and the ALPN protocols supported (`alpn h2,http/1.1`).
|
||||
This front-end then forwards the now decrypted bytes to the backend in `mode tcp`.
|
||||
The `mode tcp` says that HAProxy will not try to interpret the bytes but instead opaquely forwards them to the backend.
|
||||
<3> The `be_http` backend will forward (again in `mode tcp`) the clear-text bytes to a Jetty connector that talks clear-text HTTP/2 and HTTP/1.1 on port 8282.
|
||||
The `send-proxy-v2` directive sends the proxy protocol v2 bytes to the backend server.
|
||||
|
||||
On the Jetty side, you need to enable the following modules:
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar --add-modules=proxy-protocol,http2c,http,deploy
|
||||
----
|
||||
|
||||
You need to specify the host (`127.0.0.1`) and port (`8282`) you have configured in HAProxy when you start Jetty:
|
||||
|
||||
----
|
||||
$ java -jar $JETTY_HOME/start.jar jetty.http.host=127.0.0.1 jetty.http.port=8282
|
||||
----
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
You want the Jetty connector that listens on port `8282` to be available only to HAProxy, and not to remote clients.
|
||||
|
||||
For this reason, you want to specify the `jetty.http.host` property on the command line (or in `$JETTY_BASE/start.d/http.ini` to make this setting persistent) to bind the Jetty connector only on the loopback interface (`127.0.0.1`), making it available to HAProxy but not to remote clients.
|
||||
|
||||
If your Jetty instance runs on a different machine and/or on a different (sub)network, you may want to adjust both the back-end section of the HAProxy configuration file and the `jetty.http.host` property to match accordingly.
|
||||
====
|
||||
|
||||
With this configuration for HAProxy and Jetty, browsers supporting HTTP/2 will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
|
||||
Likewise, HTTP/1.1 clients will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
|
||||
|
||||
The Jetty connector, configured with the `http2c` and the `http` modules is able to distinguish whether the incoming bytes are HTTP/2 or HTTP/1.1 and will handle the request accordingly.
|
||||
|
||||
The response is relayed back to HAProxy, which will encrypt it and send it back to the remote client.
|
||||
|
||||
This configuration offers you efficient TLS offloading, HTTP/2 support and transparent fallback to HTTP/1.1 for clients that don't support HTTP/1.1.
|
||||
@ -1,8 +1,6 @@
|
||||
# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
|
||||
|
||||
[description]
|
||||
Adds a forwarded request customizer to the HTTP Connector.
|
||||
Processes forwarded-for style headers from a proxy.
|
||||
Enables processing of the "Forwarded" HTTP header (and its predecessors "X-Forwarded-*" HTTP headers).
|
||||
The "Forwarded" HTTP header is added by intermediaries to provide information about the clients.
|
||||
|
||||
[tags]
|
||||
connector
|
||||
@ -14,24 +12,45 @@ http
|
||||
etc/jetty-http-forwarded.xml
|
||||
|
||||
[ini-template]
|
||||
# tag::documentation[]
|
||||
### ForwardedRequestCustomizer Configuration
|
||||
|
||||
## If true, only the RFC7239 Forwarded header is accepted
|
||||
## Whether to process only the RFC7239 "Forwarded" header.
|
||||
## "X-Forwarded-*" headers are not processed.
|
||||
# jetty.httpConfig.forwardedOnly=false
|
||||
|
||||
## if true, the proxy address obtained from X-Forwarded-Server or RFC7239 is used as the request authority.
|
||||
## Whether the address obtained from "Forwarded: by=" or
|
||||
## "X-Forwarded-Server" is used in the request authority.
|
||||
# jetty.httpConfig.forwardedProxyAsAuthority=false
|
||||
|
||||
## if true, the X-Forwarded-Port header applies to the authority, else it applies to the remote client address
|
||||
## Whether the "X-Forwarded-Port" header is used in the request authority,
|
||||
## or else it is the remote client port.
|
||||
# jetty.httpConfig.forwardedPortAsAuthority=true
|
||||
|
||||
## The name of the RFC 7239 HTTP header.
|
||||
# jetty.httpConfig.forwardedHeader=Forwarded
|
||||
# jetty.httpConfig.forwardedHostHeader=X-Forwarded-Host
|
||||
# jetty.httpConfig.forwardedServerHeader=X-Forwarded-Server
|
||||
# jetty.httpConfig.forwardedProtoHeader=X-Forwarded-Proto
|
||||
# jetty.httpConfig.forwardedForHeader=X-Forwarded-For
|
||||
# jetty.httpConfig.forwardedPortHeader=X-Forwarded-Port
|
||||
# jetty.httpConfig.forwardedHttpsHeader=X-Proxied-Https
|
||||
# jetty.httpConfig.forwardedSslSessionIdHeader=Proxy-ssl-id
|
||||
# jetty.httpConfig.forwardedCipherSuiteHeader=Proxy-auth-cert
|
||||
|
||||
## The name of the obsolete forwarded host HTTP header.
|
||||
# jetty.httpConfig.forwardedHostHeader=X-Forwarded-Host
|
||||
|
||||
## The name of the obsolete forwarded server HTTP header.
|
||||
# jetty.httpConfig.forwardedServerHeader=X-Forwarded-Server
|
||||
|
||||
## The name of the obsolete forwarded scheme HTTP header.
|
||||
# jetty.httpConfig.forwardedProtoHeader=X-Forwarded-Proto
|
||||
|
||||
## The name of the obsolete forwarded for HTTP header.
|
||||
# jetty.httpConfig.forwardedForHeader=X-Forwarded-For
|
||||
|
||||
## The name of the obsolete forwarded port HTTP header.
|
||||
# jetty.httpConfig.forwardedPortHeader=X-Forwarded-Port
|
||||
|
||||
## The name of the obsolete forwarded https HTTP header.
|
||||
# jetty.httpConfig.forwardedHttpsHeader=X-Proxied-Https
|
||||
|
||||
## The name of the obsolete forwarded SSL session ID HTTP header.
|
||||
# jetty.httpConfig.forwardedSslSessionIdHeader=Proxy-ssl-id
|
||||
|
||||
## The name of the obsolete forwarded SSL cipher HTTP header.
|
||||
# jetty.httpConfig.forwardedCipherSuiteHeader=Proxy-auth-cert
|
||||
# end::documentation[]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user