Improvements to the Jetty documentation.

Ported the HTTP/2 documentation.

Signed-off-by: Simone Bordet <[email protected]>

jetty-alpn/jetty-alpn-server/src/main/config/modules/alpn.mod

@@ -1,7 +1,5 @@
-# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
-
 [description]
-Enables the ALPN (Application Layer Protocol Negotiation) TLS extension.
+Enables the handling of the ALPN (Application Layer Protocol Negotiation) TLS extension.
 
 [tag]
 connector
@@ -20,11 +18,12 @@ lib/jetty-alpn-server-${jetty.version}.jar
 etc/jetty-alpn.xml
 
 [ini-template]
-## Overrides the order protocols are chosen by the server.
-## The default order is that specified by the order of the
-## modules declared in start.ini.
+# tag::documentation[]
+## Specifies the ordered list of application protocols supported by the server.
+## The default list is specified by the list of the protocol modules that have
+## been enabled, and the order is specified by the module dependencies.
 # jetty.alpn.protocols=h2,http/1.1
 
-## Specifies what protocol to use when negotiation fails.
+## Specifies the protocol to use when the ALPN negotiation fails.
 # jetty.alpn.defaultProtocol=http/1.1
-
+# end::documentation[]

jetty-documentation/src/main/asciidoc/old_docs/http2/chapter.adoc

@@ -19,8 +19,5 @@
 [[http2]]
 == HTTP/2
 
-include::introduction.adoc[]
-include::enabling-http2.adoc[]
-include::configuring-http2.adoc[]
 include::configuring-push.adoc[]
 include::configuring-haproxy.adoc[]

jetty-documentation/src/main/asciidoc/operations-guide/introduction.adoc

@@ -30,6 +30,7 @@ If you are new to Eclipse Jetty, read xref:og-begin[here] to download, install,
 If you know Eclipse Jetty already, jump to a feature:
 
 * xref:og-sessions[HTTP Session Caching and Clustering]
+* xref:og-protocols-http2[HTTP/2 Support]
 
 TODO
 
@@ -41,6 +42,8 @@ TODO
 
 * xref:og-protocols-http[Configure Clear-Text HTTP/1.1]
 * 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]
 
 TODO
 

jetty-documentation/src/main/asciidoc/operations-guide/keystore/chapter.adoc

@@ -0,0 +1,23 @@
+//
+// ========================================================================
+// 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-keystore]]
+=== Configuring KeyStores
+
+TODO
+// TODO: see old_docs/connectors/configuring-ssl.adoc

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-alpn.adoc

@@ -0,0 +1,30 @@
+//
+// ========================================================================
+// 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-alpn]]
+==== Module `alpn`
+
+The `alpn` module enables support for the ALPN negotiation mechanism of the TLS protocol.
+
+You can configure the list of application protocols negotiated by the ALPN mechanism, as well as the default protocol to use if the ALPN negotiation fails (for example, the client does not support ALPN).
+
+The module properties are:
+
+----
+include::{JETTY_HOME}/modules/alpn.mod[tags=documentation]
+----

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http2.adoc

@@ -0,0 +1,37 @@
+//
+// ========================================================================
+// 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-http2]]
+==== Module `http2`
+
+The `http2` module enables support for the secure HTTP/2 protocol.
+
+The module properties are:
+
+----
+include::{JETTY_HOME}/modules/http2.mod[tags=documentation]
+----
+
+// tag::rate-control[]
+The `jetty.http2.rateControl.maxEventsPerSecond` property controls the number of "bad" or "unnecessary" frames that a client may send before the server closes the connection (with code link:https://tools.ietf.org/html/rfc7540#section-7[`ENHANCE_YOUR_CALM`]) to avoid a denial of service.
+
+For example, an attacker may send empty `SETTINGS` frames to a server in a tight loop.
+While the `SETTINGS` frames don't change the server configuration and each of them is somehow harmless, the server will be very busy processing them because they are sent by the attacker one after the other, causing a CPU spike and eventually a denial of service (as all CPUs will be busy processing empty `SETTINGS` frames).
+
+The same attack may be performed with `PRIORITY` frames, empty `DATA` frames, `PING` frames, etc.
+// end::rate-control[]

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http2c.adoc

@@ -0,0 +1,30 @@
+//
+// ========================================================================
+// 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-http2c]]
+==== Module `http2c`
+
+The `http2c` module enables support for the clear-text HTTP/2 protocol.
+
+The module properties are:
+
+----
+include::{JETTY_HOME}/modules/http2c.mod[tags=documentation]
+----
+
+include::module-http2.adoc[tags=rate-control]

jetty-documentation/src/main/asciidoc/operations-guide/protocols/chapter.adoc

@@ -38,6 +38,7 @@ $ java -jar $JETTY_HOME/start.jar --list-modules=connector
 
 include::protocols-http.adoc[]
 include::protocols-https.adoc[]
+include::protocols-http2.adoc[]
 include::protocols-ssl.adoc[]
 
 // TODO: old_docs/connectors/*.adoc

jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http.adoc

@@ -63,7 +63,7 @@ $ java -jar $JETTY_HOME/start.jar --add-module=server
 
 Now the `$JETTY_BASE` directory looks like this:
 
-[source,subs=quotes]
+[source]
 ----
 JETTY_BASE
 ├── resources