Eclipse
/
jetty.project
mirror of https://github.com/jetty/jetty.project.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Issue #5603 - Single page documentation (#5636) 

* First pass of single page doc generation for 9.4.x

* Updates to POM and HTML assembly

* Update snapshot version

* Removing deprecated Docbook assets

* Moving asciidoc config to main pom,  removing sub-order references

* Fixing image links

* Cleaning up code reference formatting

* Fixing missed source formatting

* Flipping Admonitions MK. I

* Replacing underscores for admonitions

* Converting .... to ---- for code blocks

* Reverting accidentally changed KEYS.txt

Signed-off-by: Joakim Erdfelt <joakim.erdfelt@gmail.com>

* Clean up

* Fixing icons

Co-authored-by: Joakim Erdfelt <joakim.erdfelt@gmail.com>
This commit is contained in:
Chris Walker 2020-11-20 13:05:42 -06:00 committed by GitHub
parent fcfa72ee40
commit 41bf9534eb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
215 changed files with 1712 additions and 7177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

213
jetty-documentation/pom.xml
View File

@ -1,145 +1,21 @@
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-project</artifactId>
<version>9.4.35-SNAPSHOT</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>jetty-documentation</artifactId>
<name>Jetty :: Documentation</name>
<packaging>pom</packaging>
<properties>
<html.directory>${project.build.directory}/current</html.directory>
<javadoc.version>${project.version}</javadoc.version>
</properties>
<build>
<plugins>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-assets</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>src/main/resources</directory>
<includes>
<include>**</include>
</includes>
</resource>
</resources>
<outputDirectory>${html.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<executions>
<execution>
<id>output-html</id>
<phase>compile</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>docbook</backend>
<doctype>book</doctype>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<sub-order>attributes+</sub-order>
<imagesdir />
<linkcss>true</linkcss>
<allow-uri-read>true</allow-uri-read>
<toc>true</toc>
<revnumber>${project.version}</revnumber>
<JDURL>https://eclipse.org/jetty/javadoc/${javadoc.version}</JDURL>
<JXURL>https://download.eclipse.org/jetty/stable-9/xref</JXURL>
<SRCDIR>${basedir}/..</SRCDIR>
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/jetty-9.4.x</GITBROWSEURL>
<MVNCENTRAL>https://repo1.maven.org/maven2</MVNCENTRAL>
<VERSION>${project.version}</VERSION>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<version>2.0.17</version>
<executions>
<execution>
<id>html</id>
<phase>compile</phase>
<goals>
<goal>generate-html</goal>
</goals>
<configuration>
<htmlStylesheet>css/docbook.css</htmlStylesheet>
<htmlCustomization>${project.basedir}/src/main/docbkx-stylesheet/html/docbook.xsl</htmlCustomization>
<preProcess>
<!-- pull over the images from the source material -->
<copy todir="target/docbkx/html/images" flatten="true">
<fileset dir="src/main/asciidoc">
<include name="**/*.png" />
<include name="**/*.jpg" />
<include name="**/*.svg" />
<include name="**/*.dot" />
</fileset>
</copy>
<copy todir="target/docbkx/html/images">
<fileset dir="src/main/docbkx-resources/images" />
</copy>
<copy todir="target/docbkx/html/css">
<fileset dir="src/main/docbkx-resources/css" />
</copy>
<copy todir="target/docbkx/html/fonts">
<fileset dir="src/main/docbkx-resources/fonts" />
</copy>
<copy todir="target/docbkx/html/js">
<fileset dir="src/main/docbkx-resources/js" />
</copy>
</preProcess>
</configuration>
</execution>
</executions>
<configuration>
<!-- shared configuration -->
<sourceDirectory>${project.build.directory}/generated-docs</sourceDirectory>
<includes>index.xml</includes>
<generatedSourceDirectory>${project.build.directory}/docbkx/generated</generatedSourceDirectory>
<chunkedOutput>true</chunkedOutput>
<highlightSource>true</highlightSource>
</configuration>
<dependencies>
<dependency>
<groupId>net.sf.docbook</groupId>
<artifactId>docbook-xml</artifactId>
<version>5.1b4-all</version>
<classifier>resources</classifier>
<type>zip</type>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>net.sf.xslthl</groupId>
<artifactId>xslthl</artifactId>
<version>2.1.3</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.eclipse.jetty.toolchain</groupId>
<artifactId>jetty-xslt-tools</artifactId>
<version>1.3</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</plugin>
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
@ -160,85 +36,4 @@
</plugin>
</plugins>
</build>
<profiles>
<!--
Couple of different approaches to generating pdf's
-->
<profile>
<id>generate-pdf</id>
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-pdf</id>
<phase>compile</phase>
<goals>
<goal>generate-pdf</goal>
</goals>
<configuration>
<includes>index.xml</includes>
<fop1Extensions>1</fop1Extensions>
<paperType>A4</paperType>
<foCustomization>src/main/docbkx-stylesheet/fo/docbook.xsl</foCustomization>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>net.sf.offo</groupId>
<artifactId>fop-hyph</artifactId>
<version>1.2</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.11</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>output-pdf</id>
<phase>generate-sources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceHighlighter>rouge</sourceHighlighter>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<imagesdir />
<version>${project.version}</version>
<linkcss>true</linkcss>
<allow-uri-read>true</allow-uri-read>
<toc>true</toc>
<revnumber>${project.version}</revnumber>
<JDURL>https://download.eclipse.org/jetty/stable-9/apidocs</JDURL>
<JXURL>https://download.eclipse.org/jetty/stable-9/xref</JXURL>
<SRCDIR>${basedir}/../jetty.project/</SRCDIR>
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/jetty-9.4.x</GITBROWSEURL>
<icons>font</icons>
<pagenums />
<toc />
<idprefix />
<idseparator>-</idseparator>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>
</project>

43
jetty-documentation/src/main/asciidoc/administration/alpn/alpn.adoc
View File

@ -90,19 +90,18 @@ or alternatively you need the link:#alpn-openjdk8-agent[Jetty ALPN agent].
In the case of the Jetty ALPN boot library, start the JVM as follows:
[source, plain, subs="{sub-order}"]
[source, plain]
----
java -Xbootclasspath/p:<path_to_alpn_boot_jar> ...
----
Where `path_to_alpn_boot_jar` is the path on the file system for the `alpn-boot` artifact, such as the one at the Maven coordinates `org.mortbay.jetty.alpn:alpn-boot`.
____
[IMPORTANT]
====
Be certain to get the
link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE].
____
====
[[alpn-openjdk8-agent]]
==== ALPN agent and OpenJDK 8
@ -121,13 +120,13 @@ transforms, if necessary, the relevant OpenJDK classes to provide the ALPN suppo
To use the Jetty ALPN agent, start the JVM as follows:
[source, plain, subs="{sub-order}"]
[source, plain]
----
java -javaagent:<path_to_alpn_agent_jar> ...
----
____
[NOTE]
====
The Jetty ALPN agent works with any Java 8 version. It is _required_ if you use
an OpenJDK version up to `1.8.0_242` included, and it is _optional_ if you use an
OpenJDK version equal or greater than `1.8.0_252`.
@ -135,8 +134,7 @@ OpenJDK version equal or greater than `1.8.0_252`.
The Jetty ALPN agent can be left on the command line even when using an OpenJDK version
equal or greater than `1.8.0_252` but we recommend to remove it from the command line
when you use OpenJDK `1.8.0_252` or later.
____
====
[[alpn-conscrypt]]
==== ALPN and Conscrypt
@ -166,19 +164,18 @@ This jar contains a `Fragment-Host` directive that ensures the ALPN classes will
You can download the https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-alpn/[jetty-osgi-alpn jar] from Maven Central.
____
[NOTE]
====
OSGi *requires* a `ServiceLoader` implementation for Jetty to function properly.
OSGi leverages http://aries.apache.org/modules/spi-fly.html[Apache Aries SPI Fly] for this functionality.
You can read more about OSGi and `ServiceLoader` http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html[here.]
____
====
[[alpn-troubleshooting]]
==== ALPN Troubleshooting
When starting the Jetty server, especially when using Jetty embedded, it may be possible that you see an error similar to this:
[source, plain, subs="{sub-order}"]
[source, plain]
----
IllegalStateException: no ALPN processor
----
@ -217,7 +214,7 @@ Refer to `ALPN` Javadocs and to the examples below for further details about cli
[[alpn-openjdk8-client-example]]
==== Client Example
[source, java, subs="{sub-order}"]
[source, java]
----
SSLContext sslContext = ...;
SSLSocket sslSocket = (SSLSocket)context.getSocketFactory().createSocket("localhost", server.getLocalPort());
@ -257,7 +254,7 @@ The ALPN implementation calls `ALPN.ClientProvider` methods `protocols()`, `unsu
The example for `SSLEngine` is identical, and you just need to replace the `SSLSocket` instance with an `SSLEngine` instance.
[source, java, subs="{sub-order}"]
[source, java]
----
SSLEngine sslEngine = ...;
ALPN.put(sslEngine, new ALPN.ServerProvider()
@ -294,7 +291,7 @@ Failing to do so will cause a memory leak.
You can write and run unit tests that use the ALPN implementation.
The solution that we use with Maven is to specify an additional command line argument to the Surefire plugin:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<project>
@ -328,9 +325,9 @@ The solution that we use with Maven is to specify an additional command line arg
You can enable debug logging for the ALPN implementation in this way:
....
----
ALPN.debug = true;
....
----
Since the ALPN class is in the boot classpath, we chose not to use logging libraries because we do not want to override application logging library choices; therefore the logging is performed directly on `System.err`.
@ -427,20 +424,20 @@ This section is for Jetty developers that need to update the ALPN implementation
Clone the OpenJDK repository with the following command:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ hg clone https://hg.openjdk.java.net/jdk8u/jdk8u jdk8u
$ cd !$
$ ./get_source.sh
....
----
To update the source to a specific tag, use the following command:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ ./make/scripts/hgforest.sh update <tag-name>
....
----
The list of OpenJDK tags can be obtained from this page:
https://hg.openjdk.java.net/jdk8u/jdk8u/tags[OpenJDK 8 Tags].

2
jetty-documentation/src/main/asciidoc/administration/annotations/quick-annotations-setup.adoc
View File

@ -39,7 +39,7 @@ Below is an example application that sets up the standard `test-spec.war` webapp
It can also be found in the Jetty GitHub repository on the examples/embedded page as link:{GITBROWSEURL}/examples/embedded/src/main/java/org/eclipse/jetty/embedded[`ServerWithAnnotations.java`.]
Note that the `test-spec.war` uses not only annotations, but also link:#jndi[JNDI], so this example also enables their processing (via the link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.EnvConfiguration], link:#jndi-configuration-classes[org.eclipse.jetty.plus.webapp.PlusConfiguration] and their related jars).
[source, java, subs="{sub-order}"]
[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/ServerWithAnnotations.java[]
----

8
jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations-embedded.adoc
View File

@ -24,10 +24,10 @@
You will need to place the following Jetty jar files onto the classpath of your application.
You can obtain them from the https://www.eclipse.org/jetty/download.html[Jetty distribution], or the https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-annotations[Maven repository]:
....
----
jetty-plus.jar
jetty-annotations.jar
....
----
You will also need the http://asm.ow2.org/[asm] jar, which you can obtain from link:{MVNCENTRAL}/org/eclipse/jetty/orbit/org.objectweb.asm/3.3.1.v201105211655/org.objectweb.asm-3.3.1.v201105211655.jar[this link.]
@ -39,7 +39,7 @@ The example also adds in the configuration classes that are responsible for JNDI
The code is as follows:
[source, java, subs="{sub-order}"]
[source, java]
----
import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server;
@ -101,7 +101,7 @@ On lines 30, 33 and 37 JNDI resources that we will be able to reference with @Re
With the setup above, a servlet that uses annotations and Jetty will honour the annotations when the webapp is deployed can be created:
[source, java, subs="{sub-order}"]
[source, java]
----
import javax.annotation.security.DeclareRoles;
import javax.annotation.security.RunAs;

9
jetty-documentation/src/main/asciidoc/administration/annotations/using-annotations.adoc
View File

@ -119,13 +119,12 @@ By default Jetty will call them in the following order:
As is the case with annotation scanning, the link:#using-extra-classpath-method[extraClasspath] is fully considered for `ServletContainerInitializer` callbacks. `ServletContainerInitializer` derived from a classes directory on the `extraClasspath` and jars from an `extraClasspath` for the webapp are called in step 2 and 3, respectively.
____
[NOTE]
====
As of Jetty-9.4.4, unless the `web.xml` is version 3.0 or greater, only `ServletContainerInitializers` that are on the container classpath will be discovered.
Users wishing to use `ServletContainerInitializers` from within the webapp with older versions of `web.xml` must either upgrade their `web.xml` version, or call `WebAppContext.setConfigurationDiscovered(true)` either programmatically or in xml.
Upgrading the `web.xml` version is preferable.
____
====
===== Controlling the order of ServletContainerInitializer invocation
If you need `ServletContainerInitializer` classes called in a specific order that is different from that outlined above, you can use the link:#context_attributes[context attribute] `org.eclipse.jetty.containerInitializerOrder`.
@ -135,7 +134,7 @@ It will match all `ServletContainerInitializer` classed not explicitly named in
Here is an example, setting the context attribute in code (although you can also do the link:#intro-jetty-configuration-webapps[same in xml]):
[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder",
@ -154,7 +153,7 @@ In this case, you can define the `org.eclipse.jetty.containerInitializerExclusio
This is a regular expression that defines http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html[patterns] of classnames that you want to exclude.
Here's an example, setting the context attribute in code, although you may do exactly the link:#intro-jetty-configuration-webapps[same in xml]:
[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",

2
jetty-documentation/src/main/asciidoc/administration/extras/cross-origin-filter.adoc
View File

@ -79,7 +79,7 @@ Default value is the empty list.
A typical configuration could be:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<web-app>

2
jetty-documentation/src/main/asciidoc/administration/extras/debug-handler.adoc
View File

@ -38,7 +38,7 @@ The debug handler can be added to Jetty by activating the debug module.
==== Embedded usage
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server(8080);
RolloverFileOutputStream outputStream = new RolloverFileOutputStream("MeinLogPfad/yyyy_mm_dd.request.log", true,10);

6
jetty-documentation/src/main/asciidoc/administration/extras/default-handler.adoc
View File

@ -34,12 +34,12 @@ As in the example below, if a resource to be served is not matched within the re
This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs.
There is also an link:#error-handler[Error Handler] that services errors related to the servlet api specification, so it is best to not get the two confused.
_____
[NOTE]
====
The `DefaultHandler` will also handle serving out the `flav.ico` file should a request make it through all of the other handlers without being resolved.
_____
====
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();

2
jetty-documentation/src/main/asciidoc/administration/extras/dos-filter.adoc
View File

@ -55,7 +55,7 @@ Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
This example allow 30 requests at a time:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<filter>
<filter-name>DoSFilter</filter-name>

11
jetty-documentation/src/main/asciidoc/administration/extras/gzip-filter.adoc
View File

@ -37,12 +37,11 @@ Some user-agents might be excluded from compression to avoid common browser bugs
The `GzipHandler` can be added to the entire server by enabling the `gzip.mod` module.
It may also be added to individual contexts in a context xml file.
____
[NOTE]
====
Jetty 9 only compresses using GZip.
Using deflate HTTP compression is not supported and will not function.
____
====
[[gzip-filter-rules]]
==== Gzip Rules
@ -63,13 +62,11 @@ The link:#default-servlet[DefaultServlet] is capable of serving pre-compressed s
The `GzipHandler` installs an output interceptor which passes through to the `DefaultServlet`.
If the content served by `DefaultServlet` is already compressed, the `GzipHandler` does nothing; if it is not compressed, the content is compressed on-the-fly.
____
[NOTE]
====
Automatic precompression by the `DefaultServlet` can be configured.
Read more about the `DefaultServlet` link:#default-servlet[here.]
____
====
[[gzip-filter-init]]
==== Gzip Configuration

7
jetty-documentation/src/main/asciidoc/administration/extras/header-filter.adoc
View File

@ -50,12 +50,11 @@ This filter will perform the following actions on each response:
* Set the Expires header to approximately one year in the future.
* Add a Date header with the current system time.
____
[NOTE]
====
Each action must be separated by a comma.
____
[source, xml, subs="{sub-order}"]
====
[source, xml]
----
<filter>
<filter-name>HeaderFilter</filter-name>

2
jetty-documentation/src/main/asciidoc/administration/extras/moved-context-handler.adoc
View File

@ -45,7 +45,7 @@ You create a new xref:configuring-contexts[context xml] file in `{$jetty/.base}/
Below is an example.
This is a permanent redirection, which also preserves `pathinfo` and query strings on the redirect:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

6
jetty-documentation/src/main/asciidoc/administration/extras/qos-filter.adoc
View File

@ -83,7 +83,7 @@ Place the configuration in a webapp's `web.xml` or `jetty-web.xml`.
The default configuration processes ten requests at a time, servicing more important requests first and queuing up the rest.
This example processes fifty requests at a time:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<filter>
<filter-name>QoSFilter</filter-name>
@ -126,7 +126,7 @@ This allows a context external mechanism (for example, JMX via `ContextHandler.M
You can use the `<filter-mapping>` syntax to map the QoSFilter to a servlet, either by using the servlet name, or by using a URL pattern.
In this example, a URL pattern applies the QoSFilter to every request within the web application context:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<filter-mapping>
<filter-name>QoSFilter</filter-name>
@ -147,7 +147,7 @@ To customize the priority, subclass QoSFilter and then override the `getPriority
You can then use this subclass as your QoS filter.
Here's an example:
[source, java, subs="{sub-order}"]
[source, java]
----
public class ParsePriorityQoSFilter extends QoSFilter
{

12
jetty-documentation/src/main/asciidoc/administration/extras/resource-handler.adoc
View File

@ -31,16 +31,14 @@
This handler will serve static content and handle If-Modified-Since headers and is suitable for simple serving of static content.
____
[IMPORTANT]
====
There is no caching done with this handler, so if you are looking for a more fully featured way of serving static content look to the xref:default-servlet[].
____
____
====
[NOTE]
====
Requests for resources that do not exist are let pass (Eg no 404's).
____
====
==== Improving the Look and Feel
The resource handler has a default stylesheet which you can change by calling `setStyleSheet(String location)` with the location of a file on the system that it can locate through the resource loading system.
@ -51,7 +49,7 @@ The default css is called `jetty-dir.css` and is located in the `jetty-util` pac
The following is an example of a split fileserver, able to serve static content from multiple directory locations.
Since this handler does not return 404's on content you are able to iteratively try multiple resource handlers to resolve content.
[source, java, subs="{sub-order}"]
[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SplitFileServer.java[]
----

16
jetty-documentation/src/main/asciidoc/administration/extras/rewrite-handler.adoc
View File

@ -31,21 +31,21 @@ The most common use is to rewrite request URIs, but it is capable of much more:
The standard Jetty distribution bundle contains the `jetty-rewrite` link:#startup-modules[module], so all you need to do is to enable it using one of the link:#start-jar[module commands], eg:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ java -jar start.jar --add-to-start=rewrite
....
----
_____
[NOTE]
====
If you are running the standard Jetty distribution with the sample test webapp, there will be a demo of the rewrite module at http://localhost:8080/test/rewrite/
_____
====
==== Usage
The rewrite module enables the following Jetty xml config file on the execution path:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/jetty-rewrite/src/main/config/etc/jetty-rewrite.xml[]
----
@ -54,7 +54,7 @@ As the commented out code shows, you configure the `RewriteHandler` by adding va
There is an example of link:#rewrite-rules[rules] configuration in the standard distribution in the `demo-base/etc/demo-rewrite-rules.xml` file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/etc/demo-rewrite-rules.xml[]
----
@ -63,7 +63,7 @@ include::{SRCDIR}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base
This is an example for embedded Jetty, which does something similar to the configuration file example above:
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server();

4
jetty-documentation/src/main/asciidoc/administration/extras/shutdown-handler.adoc
View File

@ -36,7 +36,7 @@ If `_exitJvm` is set to true a hard `System.exit()` call is being made.
This is an example of how you can setup this handler directly with the Server.
It can also be added as a part of handler chain or collection.
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server(8080);
HandlerList handlers = new HandlerList();
@ -48,7 +48,7 @@ It can also be added as a part of handler chain or collection.
This is an example that you can use to call the shutdown handler from within java.
[source, java, subs="{sub-order}"]
[source, java]
----
public static void attemptShutdown(int port, String shutdownCookie) {
try {

16
jetty-documentation/src/main/asciidoc/administration/extras/statistics-handler.adoc
View File

@ -35,18 +35,18 @@ Jetty currently has two main statistics collection mechanisms:
* The `StatisticsHandler` class may be used to collect statistics for HTTP requests.
The `StatisticsHandler` and `ConnectionStatistics` are not included in the default Jetty configuration, these need to be configured manually or enabled using the Jetty `stats` module on the command line.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ java -jar {$jetty.home}/start.jar --add-to-start=stats
....
----
In addition to these, the `SessionHandler` and `DefaultSessionCache` classes collect statistics for sessions.
These statistics are enabled by default and are accessible via JMX interface.
_____
[NOTE]
====
To view statistics, you have to be able to connect to Jetty using either JConsole or some other JMX agent. See xref:using-jmx[] for more information.
_____
====
[[request-statistics]]
==== Request Statistics
@ -58,7 +58,7 @@ You can enable the `StatisticsHandler` by activating the `stats` modules on the
Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own Jetty xml configuration.
The following fragment shows how to configure a top level statistics handler:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="insertHandler">
@ -77,7 +77,7 @@ The current and maximum number of connections are the only "live" statistics.
The following example shows how to turn on connection statistics in the Jetty XML format.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBeanToAllConnectors">
@ -91,7 +91,7 @@ The following example shows how to turn on connection statistics in the Jetty XM
A special variant of `ConnectionStatistics` called `IncludeExcludeConnectionStatistics` allows you to refine which types of connection you want to collect statistics for.
The following example shows how this can be used to record statistics only for WebSocket connections.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBeanToAllConnectors">

26
jetty-documentation/src/main/asciidoc/administration/fastcgi/configuring-fastcgi.adoc
View File

@ -31,12 +31,12 @@ Refer to xref:jetty-downloading[] for more information about how to install Jett
The fourth step is to create a Jetty base directory (see xref:startup-base-and-home[]), called in the following `$JETTY_BASE`, where you setup the configuration needed to support FastCGI in Jetty, and configure the `fcgi`, `http` and `deploy` modules, so that Jetty will be able to accept HTTP requests from browsers, convert them in FastCGI, and proxy them to `php-fpm`:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ mkdir -p /usr/jetty/wordpress
$ cd /usr/jetty/wordpress
$ java -jar $JETTY_HOME/start.jar --add-to-start=fcgi,http,deploy
....
----
Therefore `$JETTY_BASE=/usr/jetty/wordpress`.
@ -46,7 +46,7 @@ For FastCGI there is no web application that needs developed - all the work has
As such you only need to deploy a Jetty context XML file that configures the web application directly.
Copy and paste the following content as `$JETTY_BASE/webapps/jetty-wordpress.xml`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -138,11 +138,11 @@ Refer to the link:{JDURL}/org/eclipse/jetty/fcgi/server/proxy/FastCGIProxyServle
The last step is to start Jetty (see xref:startup[]) and navigate to `http://localhost:8080` with your browser and enjoy WordPress:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ cd $JETTY_BASE
$ java -jar /opt/jetty/start.jar
....
----
[[configuring-fastcgi-http2]]
==== Configuring Jetty to Proxy HTTP/2 to FastCGI
@ -151,11 +151,11 @@ In order to configure Jetty to listen for HTTP/2 requests from clients that are
Enabling the `http2` is easy; in additions to the modules you have enabled above, add the `http2` module:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2
....
----
The command above adds the `http2` module (and its dependencies) to the existing modules and uses the default Jetty keystore to provide the key material required by TLS.
You will want to use your own keystore with your own private key and certificate for your own domain.
@ -171,10 +171,10 @@ These will setup a clear text connector on port 8080 for HTTP/1.1 and a TLS conn
At this point, you can start Jetty (see xref:startup[]), hit `http://localhost:8080` with your browser and enjoy WordPress via HTTP/2 using a HTTP/2 enabled browser:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar
....
----
If you don't have a HTTP/2 enabled browser, WordPress will still be available over HTTP/1.1.

58
jetty-documentation/src/main/asciidoc/administration/http2/configuring-haproxy.adoc
View File

@ -34,19 +34,18 @@ The instructions that follow are for Linux.
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}"]
....
[source,screen]
----
$ 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
@ -62,8 +61,8 @@ HAProxy will need a single file containing the X509 certificates and the private
Let's use `keytool` to generate a self signed certificate:
[source,screen, subs="{sub-order}"]
....
[source,screen]
----
$ 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
@ -79,31 +78,31 @@ 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}"]
....
[source,screen]
----
$ 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}"]
....
[source,screen]
----
$ 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}"]
....
[source,screen]
----
$ cat certificate.pem private_key.pem > domain.pem
....
----
The `domain.pem` file will be used later by HAProxy.
@ -113,8 +112,8 @@ The `domain.pem` file will be used later by HAProxy.
Now we can setup `haproxy.cfg` to configure HAProxy.
This is a minimal configuration:
[source, ,subs="{sub-order}"]
....
[source]
----
global
tune.ssl.default-dh-param 1024
@ -137,7 +136,7 @@ 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.
@ -157,32 +156,31 @@ Since the `http2c` module depends on the `http` module, the `http` module will b
Additionally, you will also enable the `deploy` module to be able to deploy a sample web application:
[source,screen, subs="{sub-order}"]
....
[source,screen]
----
$ 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}"]
....
[source,screen]
----
$ 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.

11
jetty-documentation/src/main/asciidoc/administration/http2/configuring-http2.adoc
View File

@ -24,8 +24,8 @@ existing connector.
Thus configuring HTTP/2 is a combination of configuring common properties on the connector and HTTP/2 specific properties on the connection factory.
The modules and XML files involved can be seen with the following commands:
[source,screen, subs="{sub-order}"]
....
[source,screen]
----
$ java -jar $JETTY_HOME/start.jar --list-modules
...
1) alpn-impl <transitive>
@ -48,17 +48,16 @@ $ java -jar $JETTY_HOME/start.jar --list-config
...
${jetty.home}/etc/jetty-http2.xml
${jetty.home}/etc/jetty-https.xml
....
----
The common properties associated with connectors (host,port, timeouts, etc.) can be set in the module ini files (or `start.ini` if `--add-to-start` was used): `${jetty.base}/start.d/http.ini` and `${jetty.base}/start.d/ssl.ini`.
These properties are instantiated in the associated XML files: `${jetty.home}/etc/jetty-http.xml`; `${jetty.home}/etc/jetty-ssl.xml`, plus the SSL keystore is instantiated in `${jetty.home}/etc/jetty-ssl-context.xml`.
____
[NOTE]
====
If you are planning to edit XML files, make sure to copy them to your `{$jetty.base}/etc/` directory before doing so.
The XML files that come with the Jetty distribution should *not* be modified directly.
____
====
HTTP/2 specific properties can be set in the module ini files: `${jetty.base}/start.d/http2.ini` and `${jetty.base}/start.d/http2c.ini`, which are instantiated in the associated XML files: `${jetty.home}/etc/jetty-http2.xml`; `${jetty.home}/etc/jetty-http2c.xml`, respectively.
Currently there are very few HTTP/2 configuration properties and the default values are reasonable:

2
jetty-documentation/src/main/asciidoc/administration/http2/configuring-push.adoc
View File

@ -24,7 +24,7 @@ This will reduce the amount of round-trips necessary to retrieve all the resourc
HTTP/2 Push can be automated in your application by configuring a link:{JDURL}/org/eclipse/jetty/servlets/PushCacheFilter.html[`PushCacheFilter`] in the `web.xml`, in this way:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app

18
jetty-documentation/src/main/asciidoc/administration/http2/enabling-http2.adoc
View File

@ -22,29 +22,29 @@
This section is written assuming that a link:#startup-base-and-home[Jetty base directory] is being used.
A demo Jetty base that supports HTTP/1, HTTPS/1 and deployment from a webapps directory can be created with the commands:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ JETTY_BASE=http2-demo
$ mkdir $JETTY_BASE
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,https,deploy
....
----
The commands above create a `$JETTY_BASE` directory called `http2-demo`, and initializes the `http,` `https` and `deploy` modules (and their dependencies) to run a typical Jetty Server on port 8080 (for HTTP/1) and 8443 (for HTTPS/1).
Note that the HTTPS module downloads a demo keystore file with a self signed certificate, which needs to be replaced by a Certificate Authority issued certificate for real deployment.
To add HTTP/2 to this demo base, it is just a matter of enabling the `http2` module with the following command:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2
....
----
This command does not create a new connector, but instead simply adds the HTTP/2 protocol to the existing HTTPS/1 connector, so that it now supports both protocols on port 8443.
To do this, it also transitively enables the ALPN module for protocol negotiation.
The support for each protocol can be seen in the info logging when the server is started:
[source,screen, subs="{sub-order}"]
[source,screen]
----
$ java -jar $JETTY_HOME/start.jar
...
@ -62,13 +62,13 @@ Note that a browser pointed at this server with URL starting with `http://localh
HTTP/2 can be enabled on the plain text connector and the server restarted with the following command:
[source,screen]
....
----
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c
$ java -jar $JETTY_HOME/start.jar
..
2015-06-17 14:16:12.549:INFO:oejs.ServerConnector:main: Started ServerConnector@6f32cd1e{HTTP/1.1,[http/1.1, h2c, h2c-17]}{0.0.0.0:8080}
2015-06-17 14:16:12.782:INFO:oejs.ServerConnector:main: Started ServerConnector@711f39f9{SSL,[ssl, alpn, h2, h2-17, http/1.1]}{0.0.0.0:8443}
..
....
----
No major browser currently supports plain text HTTP/2, so the 8080 port will only be able to use HTTP/2 with specific clients (eg `curl`) that use the upgrade mechanism or assume HTTP/2.

5
jetty-documentation/src/main/asciidoc/administration/http2/introduction.adoc
View File

@ -25,12 +25,11 @@ The requirements for running HTTP/2 are JDK 8 or greater, and typically also ALP
A server deployed over TLS (SSL) normally advertises the HTTP/2 protocol via the TLS extension Application Layer Protocol Negotiation link:#alpn[(ALPN)].
____
[NOTE]
====
To use HTTP/2 in Jetty via a TLS connector you need to add the link:#alpn-starting[ALPN boot jar] in the boot classpath.
This is done automatically when using the Jetty distribution's start.jar link:#startup-modules[module system], but must be configured directly otherwise.
____
====
[[http2-security-update]]
==== Jetty HTTP/2 Security Update

34
jetty-documentation/src/main/asciidoc/administration/jmx/jetty-jconsole.adoc
View File

@ -26,17 +26,17 @@ When following the instructions given below, please also ensure that you make an
The simplest way to enable support is to add the JMX-Remote support module to your `{$jetty.base}`.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java /opt/jetty-dist/start.jar --add-to-start=jmx-remote, jmx
INFO: jmx-remote initialised in ${jetty.base}/start.ini
INFO: jmx initialised in ${jetty.base}/start.ini
....
----
Then open the `{$jetty.base}/start.ini` (or `{$jetty.base}/start.d/jmx-remote.ini`) file and edit the properties to suit your needs:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
#
# Initialize module jmx-remote
#
@ -45,7 +45,7 @@ Then open the `{$jetty.base}/start.ini` (or `{$jetty.base}/start.d/jmx-remote.in
## Enable for an open port accessible by remote machines
jetty.jmxrmihost=localhost
jetty.jmxrmiport=1099
....
----
[[jetty-jconsole-monitoring]]
==== Monitoring Jetty with JConsole
@ -57,18 +57,17 @@ To monitor Jetty's server status with JConsole, start Jetty and then start JCons
After you start Jetty, you will see a dialog box in JConsole with a list of running processes to which you can connect.
It should look something like so:
image:images/jconsole1.jpg[image,width=576]
image:administration/jmx/images/jconsole1.jpg[image,width=576]
____
[IMPORTANT]
====
If you don't see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
This forces JConsole to refresh the list, and recognize your newly-started Jetty process.
____
====
Select the start.jar entry and click the "Connect" button.
A new JConsole window opens:
image:images/jconsole2.jpg[image,width=576]
image:administration/jmx/images/jconsole2.jpg[image,width=576]
From this window you can monitor memory usage, thread usage, classloading and VM statistics.
You can also perform operations such as a manual garbage collect.
@ -80,7 +79,7 @@ The MBean tab of JConsole allows access to managed objects within the Java appli
If you also want to interact with the Jetty JMX implementation via JConsole, you need to start Jetty JMX in a form that JConsole can access.
See xref:using-jmx[] for more information.
image:images/jconsole3.png[image,width=576]
image:administration/jmx/images/console3.png[image,width=576]
[[jetty-jmc-monitoring]]
==== Monitoring Jetty with JMC
@ -92,18 +91,17 @@ To monitor Jetty's server status with JMC, start Jetty and then start JMC by typ
After you start Jetty, you will see a dialog box in JMC with a list of running processes to which you can connect.
It should look something like so:
image:images/jmc1.png[image,width=576]
image:administration/jmx/images/jmc1.png[image,width=576]
____
[IMPORTANT]
====
If you don't see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
This forces JMC to refresh the list, and recognize your newly-started Jetty process.
____
====
Double-click the start.jar entry or right-click the start.jar entry and select "Start JMX Console".
A new JMC window opens on the right:
image:images/jmc2.png[image,width=576]
image:administration/jmx/images/jmc2.png[image,width=576]
From this window you can monitor memory usage, thread usage, classloading and VM statistics.
You can also perform operations such as a manual garbage collect.
@ -115,4 +113,4 @@ The MBean tab of JMC allows access to managed objects within the Java applicatio
If you also want to interact with the Jetty JMX implementation via JMC, you need to start Jetty JMX in a form that JMC can access.
See xref:using-jmx[] for more information.
image:images/jmc3.png[image,width=576]
image:administration/jmx/images/jmc3.png[image,width=576]

2
jetty-documentation/src/main/asciidoc/administration/jmx/jetty-jmx-annotations.adoc
View File

@ -105,7 +105,7 @@ description::
The following is an example of each of the annotations mentioned above in practice.
[source, java, subs="{sub-order}"]
[source, java]
----
package com.acme;

28
jetty-documentation/src/main/asciidoc/administration/jmx/using-jmx.adoc
View File

@ -48,7 +48,7 @@ In these cases, you have to enable link:#jmx-remote-access[JMX Remote Access].
JMX is not enabled by default in the Jetty distribution.
To enable JMX in the Jetty distribution run the following, where `{$jetty.home}` is the directory where you have the Jetty distribution installed, and `${jetty.base}` is the directory where you have your Jetty configuration (see link:#startup-base-and-home[the documentation for Jetty base vs. home examples]):
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx
@ -80,7 +80,7 @@ Because logging is initialized prior to the `MBeanContainer` (even before the `S
If you are using the link:#jetty-maven-plugin[Jetty Maven plugin] you should copy the `${jetty.home}/etc/jetty-jmx.xml` file into your webapp project somewhere, such as `src/main/config/etc/`, then add a `<jettyXml>` element to the `<configuration>` element of the Jetty Maven Plugin:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<plugin>
<groupid>org.eclipse.jetty</groupid>
@ -124,14 +124,14 @@ Connecting to the remote JVM is a two step process:
The configuration for the RMI registry and the RMI server is specified by a `JMXServiceURL`.
The string format of an RMI `JMXServiceURL` is:
[source, screen, subs="{sub-order}"]
[source, screen]
----
service:jmx:rmi://<rmi_server_host>:<rmi_server_port>/jndi/rmi://<rmi_registry_host>:<rmi_registry_port>/jmxrmi
----
Default values are:
[source, screen, subs="{sub-order}"]
[source, screen]
----
rmi_server_host = localhost
rmi_server_port = 1099
@ -149,7 +149,7 @@ If you need to allow JMX remote access through a firewall, you must open both th
Examples:
[source, screen, subs="{sub-order}"]
[source, screen]
----
service:jmx:rmi:///jndi/rmi:///jmxrmi
rmi_server_host = local host address
@ -183,7 +183,7 @@ This is especially important when binding the RMI server host to the loopback ad
Similarly to link:#jmx-standalone-jetty[enabling JMX in a standalone Jetty server], you enable the `jmx-remote` module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx-remote
@ -193,7 +193,7 @@ $ java -jar {$jetty.home}/start.jar --add-to-start=jmx-remote
When running Jetty embedded into an application, create and configure a `ConnectorServer`:
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server();
@ -217,7 +217,7 @@ For a complete guide to controlling authentication and authorization in JMX, see
To authorize access to the `JMXConnectorServer` you can use this configuration, where the `jmx.password` and `jmx.access` files have the format specified in the blog entry above:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
<Arg>
@ -251,7 +251,7 @@ To authorize access to the `JMXConnectorServer` you can use this configuration,
Similarly, in code:
[source, java, subs="{sub-order}"]
[source, java]
----
JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi:///jmxrmi");
Map<String, Object> env = new HashMap<>();
@ -269,7 +269,7 @@ The JMX communication via RMI happens by default in clear-text.
It is possible to configure the `ConnectorServer` with a `SslContextFactory` so that the JMX communication via RMI is encrypted:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
<Arg>
@ -288,7 +288,7 @@ It is possible to configure the `ConnectorServer` with a `SslContextFactory` so
Similarly, in code:
[source, java, subs="{sub-order}"]
[source, java]
----
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setKeyStorePath("/path/to/keystore");
@ -313,7 +313,7 @@ If that is not the case (for example the certificate is self-signed), then you n
For example, trying to connect using the JDK standard `JMXConnector` with both the RMI server and the RMI registry to `domain.com`:
[source, java, subs="{sub-order}"]
[source, java]
----
// System properties necessary for an RMI client to trust a self-signed certificate.
System.setProperty("javax.net.ssl.trustStore", "/path/to/trustStore");
@ -331,7 +331,7 @@ try (JMXConnector client = JMXConnectorFactory.connect(jmxURL, clientEnv))
Similarly, to launch JMC:
[source, java, subs="{sub-order}"]
[source, java]
----
$ jmc -vmargs -Djavax.net.ssl.trustStore=/path/to/trustStore -Djavax.net.ssl.trustStorePassword=secret
----
@ -347,7 +347,7 @@ In this case you want to configure the `ConnectorServer` with a `JMXServiceURL`
Then you setup the local port forwarding with the SSH tunnel:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ ssh -L 1099:localhost:1099 <user>@<machine_host>
----

38
jetty-documentation/src/main/asciidoc/administration/jndi/jndi-configuration.adoc
View File

@ -25,7 +25,7 @@
Sometimes it is useful to pass configuration information to a webapp at runtime that you either cannot or cannot conveniently code into a `web.xml` env-entry.
In such cases, you can use the `org.eclipse.jetty.plus.jndi.EnvEntry` class, and even override an entry of the same name in `web.xml`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.plus.jndi.EnvEntry">
<Arg></Arg>
@ -57,7 +57,7 @@ Be aware that if you take advantage of this feature, your web application is __n
To use the `env-entry` configured above, use code in your `servlet/filter/etc.`, such as:
[source, java, subs="{sub-order}"]
[source, java]
----
import javax.naming.InitialContext;
@ -103,7 +103,7 @@ Jetty can use any DataSource implementation available on its classpath.
In this example, the DataSource is from the http://db.apache.org/derby[Derby] relational database, but you can use any implementation of a `javax.sql.DataSource`.
This example configures it as scoped to a web app with the id of __wac__:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="myds" class="org.eclipse.jetty.plus.jndi.Resource">
@ -124,7 +124,7 @@ If you do not have the appropriate `resource-ref` set up in your `web.xml`, it i
Here's an example `web.xml` declaration for the datasource above:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<resource-ref>
<res-ref-name>jdbc/myds</res-ref-name>
@ -135,7 +135,7 @@ Here's an example `web.xml` declaration for the datasource above:
To look up your DataSource in your `servlet/filter/etc.`:
[source, java, subs="{sub-order}"]
[source, java]
----
import javax.naming.InitialContext;
import javax.sql.DataSource;
@ -152,12 +152,11 @@ public class MyClass {
}
----
____
[NOTE]
====
Careful! When configuring Resources, ensure that the type of object you configure matches the type of object you expect to look up in `java:comp/env`.
For database connection factories, this means that the object you register as a Resource _must_ implement the `javax.sql.DataSource` interface.
____
====
For more examples of datasource configurations, see xref:jndi-datasource-examples[].
[[configuring-jms-queues-topics-connectionfactories]]
@ -167,7 +166,7 @@ Jetty can bind any implementation of the JMS destinations and connection factori
You just need to ensure the implementation Jars are available on Jetty's classpath.
Here is an example of binding an http://activemq.apache.org[ActiveMQ] in-JVM connection factory:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
@ -184,7 +183,7 @@ Here is an example of binding an http://activemq.apache.org[ActiveMQ] in-JVM con
The entry in `web.xml` would be:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<resource-ref>
<res-ref-name>jms/connectionFactory</res-ref-name>
@ -200,7 +199,7 @@ TODO: put in an example of a QUEUE from progress demo
Jetty also provides infrastructure for access to `javax.mail.Sessions` from within an application:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="mail" class="org.eclipse.jetty.plus.jndi.Resource">
@ -226,12 +225,11 @@ Jetty also provides infrastructure for access to `javax.mail.Sessions` from with
This setup creates an instance of the `org.eclipse.jetty.jndi.factories.MailSessionReference` class, calls it's setter methods to set up the authentication for the mail system, and populates a set of Properties, setting them on the `MailSessionReference` instance.
The result is that an application can look up `java:comp/env/mail/Session` at runtime and obtain access to a `javax.mail.Session` that has the necessary configuration to permit it to send email via SMTP.
____
[TIP]
====
You can set the password to be plain text, or use Jetty's link:#configuring-security-secure-passwords[Secure Password Obfuscation] (OBF:) mechanism to make the config file a little more secure from prying eyes.
Remember that you cannot use the other Jetty encryption mechanisms of MD5 and Crypt because they do not allow you to recover the original password, which the mail system requires.
____
====
[[configuring-xa-transactions]]
==== Configuring XA Transactions
@ -240,7 +238,7 @@ Jetty does not ship with one as standard, but you can plug in the one you prefer
You can configure a transaction manager using the link:{JDURL}/org/eclipse/jetty/plus/jndi/Transaction.html[JNDI Transaction] object in a Jetty config file.
The following example configures the http://www.atomikos.com/[Atomikos] transaction manager:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="tx" class="org.eclipse.jetty.plus.jndi.Transaction">
<Arg>
@ -257,7 +255,7 @@ For example:
In a context xml file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="myds" class="org.eclipse.jetty.plus.jndi.Resource">
@ -275,7 +273,7 @@ In a context xml file:
In a `web.xml` file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<resource-ref>
<res-ref-name>jdbc/mydatasource</res-ref-name>
@ -293,7 +291,7 @@ For the example above, you can refer to the `jdbc/mydatasource` resource as `jdb
In a context xml file declare `jdbc/mydatasource`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="myds" class="org.eclipse.jetty.plus.jndi.Resource">
@ -312,7 +310,7 @@ In a context xml file declare `jdbc/mydatasource`:
Then in a `WEB-INF/jetty-env.xml` file, link the name `jdbc/mydatasource` to the name you want to reference it as in
`web.xml`, which in this case is `jdbc/mydatasource1`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="map1" class="org.eclipse.jetty.plus.jndi.Link">
<Arg><Ref refid='wac'/></Arg>
@ -323,7 +321,7 @@ Then in a `WEB-INF/jetty-env.xml` file, link the name `jdbc/mydatasource` to the
Now you can refer to `jdbc/mydatasource1` in the `web.xml` like this:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<resource-ref>
<res-ref-name>jdbc/mydatasource1</res-ref-name>

38
jetty-documentation/src/main/asciidoc/administration/jndi/jndi-datasources.adoc
View File

@ -21,14 +21,13 @@
Here are examples of configuring a JNDI datasource for various databases.
____
[NOTE]
====
Read xref:configuring-datasources[] in xref:jndi-configuration[] for more information about configuring datasources.
____
====
All of these examples correspond to a `resource-ref` in `web.xml`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<resource-ref>
<description>My DataSource Reference</description>
@ -42,11 +41,10 @@ These examples assume that all of the datasources are declared at the JVM scope,
You can configure all JNDI resources in a `jetty.xml` file, a `WEB-INF/jetty-env.xml` file, or a context XML file.
See the section xref:jndi-where-to-declare[] for more information.
____
[IMPORTANT]
====
You must provide Jetty with the libraries necessary to instantiate the datasource you have configured by putting the corresponding Jar in `JETTY_HOME/lib/ext`.
____
====
[[pooling-datasources]]
==== Pooling DataSources
@ -71,7 +69,7 @@ The following is a list of the pooled datasource examples we have worked with in
Connection pooling, available at http://search.maven.org/remotecontent?filepath=com/zaxxer/HikariCP/1.4.0/HikariCP-1.4.0.jar[HikariCP Download].
All configuration options for HikariCP are described here: https://github.com/brettwooldridge/HikariCP[HikariCP documentation].
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -102,7 +100,7 @@ All configuration options for HikariCP are described here: https://github.com/br
Connection pooling, available at http://jolbox.com/index.html?page=http://jolbox.com/download.html[BoneCP Download].
All configuration options for BoneCP are described here: http://jolbox.com/bonecp/downloads/site/apidocs/com/jolbox/bonecp/BoneCPDataSource.html[BoneCP API].
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
@ -128,7 +126,7 @@ All configuration options for BoneCP are described here: http://jolbox.com/bonec
Connection pooling, available at https://repo1.maven.org/maven2/c3p0/c3p0/0.9.1.2/c3p0-0.9.1.2.jar[c3p0 Jar].
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -149,7 +147,7 @@ Connection pooling, available at https://repo1.maven.org/maven2/c3p0/c3p0/0.9.1.
Connection pooling, available at https://repo1.maven.org/maven2/commons-dbcp/commons-dbcp/1.2/commons-dbcp-1.2.jar[dbcp Jar].
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -171,7 +169,7 @@ Connection pooling, available at https://repo1.maven.org/maven2/commons-dbcp/com
Connection pooling + XA transactions.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -206,7 +204,7 @@ Connection pooling + XA transactions.
Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -226,7 +224,7 @@ Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
Implements `javax.sql.ConnectionPoolDataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
@ -252,7 +250,7 @@ Implements `javax.sql.ConnectionPoolDataSource`.
Implements `javax.sql.ConnectionPoolDataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -288,7 +286,7 @@ The following is a list of the non-pooled datasource examples:
Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -310,7 +308,7 @@ Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -343,7 +341,7 @@ For more information, refer to: http://docs.oracle.com/cd/B14117_01/java.101/b10
Implements `javax.sql.DataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -365,7 +363,7 @@ Implements `javax.sql.DataSource`.
Implements `javax.sql.DataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>
@ -387,7 +385,7 @@ Implements `javax.sql.DataSource`.
Implements `javax.sql.DataSource`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg>

6
jetty-documentation/src/main/asciidoc/administration/jndi/jndi-embedded.adoc
View File

@ -23,10 +23,10 @@
In addition to the jars that you require for your application, and the jars needed for core Jetty, you will need to place the following jars onto your classpath:
....
----
jetty-jndi.jar
jetty-plus.jar
....
----
If you are using transactions, you will also need the `javax.transaction` api.
You can obtain this jar link:{MVNCENTRAL}/org/eclipse/jetty/orbit/javax.transaction/1.1.1.v201105210645/javax.transaction-1.1.1.v201105210645.jar[here.]
@ -39,7 +39,7 @@ Note that this jar also requires the `javax.activation` classes, which is availa
Here is an example class that sets up some JNDI entries and deploys a webapp that references these JNDI entries in code.
We'll use some mocked up classes for the transaction manager and the DataSource in this example for simplicity:
[source, java, subs="{sub-order}"]
[source, java]
----
import java.util.Properties;
import org.eclipse.jetty.server.Server;

12
jetty-documentation/src/main/asciidoc/administration/jndi/quick-jndi-setup.adoc
View File

@ -23,12 +23,12 @@ If you are using the standard distribution of Jetty, you must enable the _JNDI_
As the _plus_ module depends on the _JNDI_ module, you only need to enable the _plus_ module to enable both.
Assuming you have Jetty installed in `/opt/jetty`, and you have made a link:#startup-base-and-home[jetty base] in `/opt/jetty/my-base`, do:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
cd /opt/jetty
cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=plus
....
----
You can now start Jetty and use JNDI within your webapps.
See link:#using-jndi[Using JNDI] for information on how to add entries to the JNDI environment that Jetty can look up within webapps.
@ -37,9 +37,9 @@ If you have extra jars associated with your JNDI resources, for example a databa
You will then need to enable the _ext_ module to ensure the jars in the `ext/` directory are on the classpath.
Assuming you have Jetty installed in `/opt/jetty`, and you have made a link:#startup-base-and-home[jetty base] in `/opt/jetty/my-base`, do:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
cd /opt/jetty
cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=ext
....
----

10
jetty-documentation/src/main/asciidoc/administration/jndi/using-jndi.adoc
View File

@ -24,7 +24,7 @@
You can configure naming resources to reference in a `web.xml` file and access from within the `java:comp/env` naming environment of the webapp during execution.
Specifically, you can configure support for the following `web.xml` elements:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<env-entry/>
<resource-ref/>
@ -52,7 +52,7 @@ For the link between a `web.xml` resource name and a naming entry
Declarations of each of these types follow the same general pattern:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.plus.jndi.xxxx">
<Arg><!-- scope --></Arg>
@ -91,7 +91,7 @@ The name is unique across the JVM instance, and is visible to all application co
You represent this scope by a `null` first parameter to the resource declaration.
For example:
+
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
@ -109,7 +109,7 @@ The name is unique to a Server instance, and is only visible to code associated
You represent this scope by referencing the Server instance as the first parameter to the resource declaration.
For example:
+
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.Server">
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">
@ -128,7 +128,7 @@ The name is unique to the WebAppContext instance, and is only visible to code as
You represent this scope by referencing the `WebAppContext` instance as the first parameter to the resource declaration.
For example:
+
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource">

10
jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-logging.adoc
View File

@ -34,11 +34,10 @@ DEBUG::
IGNORE::
Exception events that you can safely ignore, but useful for some people.
You might see this level as DEBUG under some Java logging framework configurations, where it retains the _ignore_ phrase somewhere in the logging.
____
[NOTE]
====
Jetty logging produces no FATAL or SEVERE events.
____
====
[[selecting-log-framework]]
==== Selecting the Log Framework
@ -51,12 +50,11 @@ Configure the Jetty logging layer via the `org.eclipse.jetty.util.log.Log` class
* If property `org.eclipse.jetty.util.log.class` is defined, load the class it defines as the logger implementation from the server `classpath`.
* If the class `org.slf4j.Logger` exists in server classpath, the Jetty implementation becomes `org.eclipse.jetty.util.log.Slf4jLog`.
* If no logger implementation is specified, default to `org.eclipse.jetty.util.log.StdErrLog`.
____
[NOTE]
====
You can create your own custom logging by providing an implementation of the link:{JDURL}org/eclipse/jetty/util/log/Logger.html[Jetty Logger API].
For an example of a custom logger, see link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/log/JavaUtilLog.java[JavaUtilLog.java].
____
====
[[configuring-jetty-stderrlog]]
==== The jetty-logging.properties file

15
jetty-documentation/src/main/asciidoc/administration/logging/configuring-jetty-request-logs.adoc
View File

@ -28,12 +28,12 @@ There is one entry per request received, and commonly in the standard NCSA forma
A standard request log entry includes the client IP address, date, method, URL, result, size, referrer, user agent and latency.
For example:
....
----
123.4.5.6 - - [20/Jul/2016:10:16:17 +0000]
"GET /jetty/tut/XmlConfiguration.html HTTP/1.1"
200 76793 "http://localhost:8080/jetty/tut/logging.html"
"Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8" 342
....
----
[[implementing-request-log]]
==== Implementing a Request Log
@ -49,7 +49,7 @@ If neither of these options meets your needs, you can implement a custom request
To enable the Request Log module for the entire server via the Jetty distribution, it first needs to be enabled on the command line:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --add-to-start=requestlog
@ -60,15 +60,14 @@ INFO: Base directory was modified
The above command will add a new `requestlog.ini` file to your link:#start-vs-startd[`{$jetty.base}/start.d` directory].
____
[NOTE]
====
By default, request logs are not set to be appended, meaning a the log file is wiped clean upon sever restart.
You can change this setting by editing the `requestlog.ini` and un-commenting the line that reads `jetty.requestlog.append=true`.
____
====
The equivalent code for embedded usages of Jetty is:
[source, java, subs="{sub-order}"]
[source, java]
----
NCSARequestLog requestLog = new NCSARequestLog("/var/logs/jetty/jetty-yyyy_mm_dd.request.log");
requestLog.setAppend(true);
@ -120,7 +119,7 @@ Both timezones are set to GMT by default.
To configure a separate request log for specific a web application, add the following to the context XML file.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
...

60
jetty-documentation/src/main/asciidoc/administration/logging/configuring-logging-modules.adoc
View File

@ -26,15 +26,15 @@ Please note that enabling these modules provides typical and basic functionality
Enabling these frameworks in the Jetty distribution is as easy as activating any other module, by adding `--add-to-start=<module name>` to the start command for your server, such as:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/logging-jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified
....
----
As noted above, Jetty supports a wide array of logging technologies.
If a particular logging framework requires additional jar files, Jetty will automatically download these as part of enabling the associated module and any dependent modules will be transitively enabled.
@ -83,8 +83,8 @@ Jetty uses the SLF4J api as a binding to provide logging information to addition
It can also be used on it's own to provide simple server logging.
To enable the SLF4J framework, you need to activate the `logging-slf4j` module.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-slf4j
ALERT: There are enabled module(s) with licenses.
@ -126,14 +126,14 @@ ERROR : Unsatisfied module dependencies: logging-slf4j
Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
java -jar $JETTY_HOME/start.jar --help # for more information
....
----
As you probably noticed, the system gives an `ERROR` when trying to enable the `logging-slf4j` on it's own.
The `logging-slf4j` module itself provides the SLF4J api, but as SLF4J is often used as a binding for other logging frameworks does not by default provide an implementation.
To enable the simple SLF4J implementation, we will also need to activate the `slf4j-simple-impl` module.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=slf4j-simple-impl
INFO : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
INFO : resources transitively enabled
@ -153,7 +153,7 @@ INFO : Base directory was modified
└── start.d
├── logging-slf4j.ini
└── slf4j-simple-impl.ini
....
----
Jetty is now configured to log using the SLF4J framework.
A standard SLF4J properties file is located in `${jetty.base}/resources/simplelogger.properties`.
@ -165,8 +165,8 @@ It is possible to have the Jetty Server logging configured so that Log4j or Log4
This is accomplished by configuring Jetty for logging to http://logging.apache.org/log4j/[Apache Log4j] via http://slf4j.org/manual.html[Slf4j] and the http://slf4j.org/manual.html#swapping[Slf4j binding layer for Log4j].
Implementation of Log4j can be done by enabling the `logging-log4j` module.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-log4j
ALERT: There are enabled module(s) with licenses.
@ -227,15 +227,15 @@ INFO : Base directory was modified
│   └── log4j.xml
└── start.d
└── logging-log4j.ini
....
----
Jetty is now configured to log using the Log4j framework.
A standard Log4j configuration file is located in `${jetty.base}/resources/log4j.xml`.
Or, to set up Log4j2, enable the `logging-log4j2` module.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-log4j2
ALERT: There are enabled module(s) with licenses.
@ -299,7 +299,7 @@ INFO : Base directory was modified
│   └── log4j2.xml
└── start.d
└── logging-log4j2.ini
....
----
At this point Jetty is configured so that the Jetty server itself will log using Log4j2, using the Log4j2 configuration found in `{$jetty.base}/resources/log4j2.xml`.
@ -311,8 +311,8 @@ This is accomplished by configuring Jetty for logging to `Logback`, which uses h
To set up Jetty logging via Logback, enable the `logging-logback` module.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-logback
ALERT: There are enabled module(s) with licenses.
@ -382,7 +382,7 @@ INFO : Base directory was modified
│   └── logback.xml
└── start.d
└── logging-logback.ini
....
----
At this point Jetty is configured so that the Jetty server itself will log using Logback, using the Logback configuration found in `{$jetty.base}/resources/logback.xml`.
@ -394,8 +394,8 @@ It is possible to have the Jetty Server logging configured so that `java.util.lo
This example demonstrates how to configuring Jetty for logging to `java.util.logging` via http://slf4j.org/manual.html[SLF4J] as a binding layer.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-jul
ALERT: There are enabled module(s) with licenses.
@ -448,7 +448,7 @@ INFO : Base directory was modified
│   └── slf4j-jdk14-1.7.21.jar
└── start.d
└── logging-jul.ini
....
----
Jetty is now configured to log using the JUL framework.
A standard JUL properties file is located in `${jetty.base}/etc/java-util-logging.properties`.
@ -459,8 +459,8 @@ By default, enabling the above modules will output log information to the consol
Included in the distribution is the `console-capture` module, which can be used in lieu of additional configuration to the selected logging module to capture this output to a `logs` directory in your `${jetty.base}`.
To enable this functionality, activate the `console-capture` module.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs
@ -471,24 +471,24 @@ INFO : Base directory was modified
├── logs
└── start.d
└── console-capture.ini
....
----
As an example, here is the output from Logback before using the `console-capture` module:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar
419 [main] INFO org.eclipse.jetty.util.log - Logging initialized @508ms to org.eclipse.jetty.util.log.Slf4jLog
540 [main] INFO org.eclipse.jetty.server.Server - jetty-9.4.0-SNAPSHOT
575 [main] INFO o.e.jetty.server.AbstractConnector - Started ServerConnector@3c0ecd4b{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
575 [main] INFO org.eclipse.jetty.server.Server - Started @668ms
....
----
After enabling `console-capture`, the output is as follows, which displays the location the log is being saved to:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar
151 [main] INFO org.eclipse.jetty.util.log - Logging initialized @238ms to org.eclipse.jetty.util.log.Slf4jLog
196 [main] INFO org.eclipse.jetty.util.log - Console stderr/stdout captured to /installs/jetty-distribution/mybase/logs/2016_10_21.jetty.log
....
----

36
jetty-documentation/src/main/asciidoc/administration/logging/default-logging-with-stderrlog.adoc
View File

@ -31,8 +31,8 @@ Included in the Jetty distribution is a logging module named `console-capture` t
To enable this feature, simply activate the `console-capture` module on the command line:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs
@ -43,23 +43,21 @@ INFO : Base directory was modified
├── logs
└── start.d
└── console-capture.ini
....
----
The default configuration for logging output will create a file `${jetty.base}/logs/yyyy_mm_dd.stderrout.log` which allows configuration of the output directory by setting the `jetty.logs` property.
____
[NOTE]
====
By default, logs are not set to be appended, meaning a the log file is wiped clean upon sever restart.
You can change this setting by editing the `console-capture.ini` and un-commenting the line that reads `jetty.console-capture.append=true`.
____
====
Just enabling the `console-capture` will simply output the values of STDERR and STDOUT to a log file.
To customize the log further, a module named `logging-jetty` is available to provides a default properties file to configure.
As with `console-capture`, you activate the `logging-jetty` on the command line.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled
@ -75,14 +73,14 @@ INFO : Base directory was modified
└── start.d
├── console-capture.ini
└── logging-jetty.ini
....
----
Once activated, you can find the properties file at `${jetty.base}/resources/jetty-logging.properties`.
By default, the following parameters are defined.
To change them, un-comment the line and substitute your naming scheme and configuration choices.
[source, properties, subs="{sub-order}"]
....
[source, properties]
----
## Force jetty logging implementation
#org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog
@ -95,7 +93,7 @@ To change them, un-comment the line and substitute your naming scheme and config
## Show the source file of a log location?
#com.example.SOURCE=false
....
----
There are a number of properties that can be defined in the configuration that will affect the behavior of StdErr logging with `console-capture`.
@ -125,23 +123,23 @@ There are a number of properties that can be defined in the configuration that w
+
* Example when set to false:
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
2016-10-21 15:31:01.248:INFO::main: Logging initialized @332ms to org.eclipse.jetty.util.log.StdErrLog
2016-10-21 15:31:01.370:INFO:oejs.Server:main: jetty-9.4.0-SNAPSHOT
2016-10-21 15:31:01.400:INFO:oejs.AbstractConnector:main: Started ServerConnector@2c330fbc{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-10-21 15:31:01.400:INFO:oejs.Server:main: Started @485ms
....
----
+
* Example when set to true:
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
2016-10-21 15:31:35.020:INFO::main: Logging initialized @340ms to org.eclipse.jetty.util.log.StdErrLog
2016-10-21 15:31:35.144:INFO:org.eclipse.jetty.server.Server:main: jetty-9.4.0-SNAPSHOT
2016-10-21 15:31:35.174:INFO:org.eclipse.jetty.server.AbstractConnector:main: Started ServerConnector@edf4efb{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-10-21 15:31:35.175:INFO:org.eclipse.jetty.server.Server:main: Started @495ms
....
----
[[deprecated-parameters]]
==== Deprecated Parameters

6
jetty-documentation/src/main/asciidoc/administration/logging/example-apache-log4j.adoc
View File

@ -23,8 +23,8 @@ This is accomplished by configuring Jetty for logging to http://logging.apache.o
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with log4j.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ mkdir modules
[mybase]$ cd modules
@ -46,7 +46,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar
....
----
The replacement `logging.mod` performs a number of tasks.

15
jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging-native.adoc
View File

@ -25,16 +25,15 @@ Jetty.
This example demonstrates how to configuring Jetty for logging to
`java.util.logging` via Jetty's own JavaUtilLog implementation.
____
[IMPORTANT]
====
While this is a valid setup, the Jetty project recommends always using the link:#example-logging-java-util-logging[slf4j to java.util.logging configuration] for memory and performance reasons.
This native implementation is very non-performant and is not guaranteed to exist in the future.
____
====
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with `java.util.logging`.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ mkdir modules
[mybase]$ cd modules
@ -54,7 +53,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/${jetty.base}
[mybase]$ java -jar /opt/jetty-dist/start.jar
....
----
The replacement `logging.mod` performs a number of tasks.
@ -78,8 +77,8 @@ In essence, Jetty is now configured to use `org.eclipse.jetty.util.log.JavaUtilL
If there any custom `java.util.logging` handlers to be used, put the implementation jar in the `${jetty.base}/lib/logging/` directory and reference them in the `${jetty.base}/resources/logging.properties` file.
____
[NOTE]
====
`java.util.logging` is configured via the `${jetty.base}/resources/logging.properties` file during a valid startup of Jetty.
This means that if there is any startup errors that occur before `java.util.logging` is configured, they will likely be lost and/or not routed through your configuration.
@ -88,4 +87,4 @@ Other logging frameworks are more reliable in that they always initialize and co
* While it is possible to configure `java.util.logging` sooner, even at JVM startup, the example demonstrated here does not show this technique.
For more information consult the official `java.util.logging.LogManager` javadoc http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html[documentation from Oracle].
____
====

10
jetty-documentation/src/main/asciidoc/administration/logging/example-java-util-logging.adoc
View File

@ -25,8 +25,8 @@ If you want to use the built-in native `JavaUtilLog` implementation, see #exampl
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for logging with `java.util.logging`.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ mkdir modules
[mybase]$ cd modules
@ -48,7 +48,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar
....
----
The replacement `logging.mod` performs a number of tasks.
@ -73,8 +73,8 @@ In essence, Jetty is now configured to emit its own logging events to slf4j, and
If there any custom `java.util.logging` handlers to be used, put the implementation jar in the `${jetty.base}/lib/logging/` directory and reference them in the `${jetty.base}/resources/logging.properties` file.
____
[NOTE]
====
`java.util.logging` is configured via the `${jetty.base}/resources/logging.properties` file during a valid startup of Jetty.
This means that if there is any startup errors that occur before `java.util.logging` is configured, they will likely be lost and/or not routed through your configuration.
@ -83,4 +83,4 @@ Other logging frameworks are more reliable in that they always initialize and co
* While it is possible to configure `java.util.logging` sooner, even at JVM startup, the example demonstrated here does not show this technique.
For more information consult the official `java.util.logging.LogManager` javadoc http://docs.oracle.com/javase/7/docs/api/java/util/logging/LogManager.html[documentation from Oracle].
____
====

11
jetty-documentation/src/main/asciidoc/administration/logging/example-logback-centralized-logging.adoc
View File

@ -24,12 +24,11 @@ It routes all logging events from the web applications to a single configuration
The example below shows how to accomplish this with Jetty and Slf4j, using `Logback` to manage the final writing of logs to disk.
____
[IMPORTANT]
====
This mechanism forces all webapps to use the server's configuration for logging, something that isn't 100% appropriate for all webapps.
An example would be having Jenkins-CI deployed as an webapp, if you force its logging configuration to the server side, you lose the ability on http://jenkins-ci.org/[Jenkins-CI] to see the logs from the various builds (as now those logs are actually going to the main server log).
____
====
This configuration is essentially the multiple logger configuration with added configuration to the deployers to force a `WebAppClassLoader` change to use the server classpath over the webapps classpath for the logger specific classes.
The technique used by this configuration is to provide an link:{JDURL}org/eclipse/jetty/deploy/AppLifeCycle.Binding.html[AppLifeCycle.Binding] against the link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[`"deploying"`node] that modifies the
@ -38,8 +37,8 @@ See https://github.com/jetty-project/jetty-webapp-logging/blob/master/jetty-weba
A convenient replacement `logging` module has been created to bootstrap your `${jetty.base}` directory for capturing all Jetty server logging from multiple logging frameworks into a single logging output file managed by Logback.
[source,screen,subs="{sub-order}"]
....
[source,screen,]
----
[mybase]$ curl -O https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-webapp-logging/9.4.27/jetty-webapp-logging-9.4.27-config.jar
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
@ -114,7 +113,7 @@ DOWNLD: https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-webapp-logging/9.
INFO : Base directory was modified
$
....
----
This replacement `centralized-webapp-logging.mod` performs a number of tasks.

4
jetty-documentation/src/main/asciidoc/administration/logging/example-logback-sifting.adoc
View File

@ -23,9 +23,9 @@ This page describes how to create log files at the server level and name them ba
This can be done with SLF4J + Logback + Jetty Webapp Logging in the mix.
Find example projects for this feature at github:
....
----
https://github.com/jetty-project/jetty-and-logback-example
....
----
.GitHub Example Project
[cols=",",options="header",]

6
jetty-documentation/src/main/asciidoc/administration/logging/example-logback.adoc
View File

@ -23,8 +23,8 @@ This is accomplished by configuring Jetty for logging to `Logback`, which uses h
A convenient replacement `logging` module has been created to bootstrap the `${jetty.base}` directory for logging with logback.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ mkdir modules
[mybase]$ cd modules
@ -44,7 +44,7 @@ DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/logback/jetty-logging.properties to resources/jetty-logging.properties
[mybase]$ java -jar /opt/jetty-dist/start.jar
....
----
The replacement `logging.mod` performs a number of tasks.

16
jetty-documentation/src/main/asciidoc/administration/logging/example-slf4j-multiple-loggers.adoc
View File

@ -34,19 +34,17 @@ Logging APIs that Slf4j supports:
To accomplish this configuration a single underlying logging framework should first be chosen.
This decision guides the rest of the choices about jar files to place on the server classpath.
____
[CAUTION]
====
There MUST NOT be multiple underlying logging frameworks on the classpath.
If there are, the Slf4j framework fails to load.
____
____
====
[NOTE]
====
Some third party libraries provide their own implementations of common logging APIs; be careful not to accidentally include an underlying logging framework.
For example, if you are using SpringSource you likely have a `com.springsource.org.apache.log4j.jar` along with a `log4j.jar`, which have the same classes in them.
In this example, use the `com.springsource.org.apache.log4j.jar` version and exclude the `log4j.jar`, as the SpringSource version includes extra metadata suitable for using SpringSource.
____
====
.Slf4j Logging Grid
[width="100%",cols="25%,25%,25%,25%",options="header",]
|=======================================================================
@ -88,8 +86,8 @@ It also requires including the other Slf4j binding JARs in the classpath, along
A convenient replacement `logging` module has been created to bootstrap the `${jetty.base}` directory for capturing all Jetty server logging from multiple logging frameworks into a single logging output file managed by logback.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ mkdir modules
[mybase]$ cd modules
@ -115,7 +113,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar
....
----
The replacement `logging.mod` performs a number of tasks.

4
jetty-documentation/src/main/asciidoc/administration/logging/jetty-server-dump.adoc
View File

@ -79,7 +79,7 @@ The Server MBean has a `dump()` method, which dumps everything, plus a `dumpStdE
This is a dump of the OneServletContext embedded example with extra threadpool information:
....
----
Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED
+= QueuedThreadPool[qtp488044861]@1d16f93d{STARTED,8<=8<=200,i=2,r=4,q=0}[ReservedThreadExecutor@16267862{s=2/4,p=0}] - STARTED
| += ReservedThreadExecutor@16267862{s=2/4,p=0} - STARTED
@ -221,4 +221,4 @@ Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED
+> jdk.internal.loader.ClassLoaders$AppClassLoader@2c13da15
+> jdk.internal.loader.ClassLoaders$PlatformClassLoader@7364985f
key: +- bean, += managed, +~ unmanaged, +? auto, +: iterable, +] array, +@ map, +> undefined
....
----

2
jetty-documentation/src/main/asciidoc/administration/part.adoc
View File

@ -18,7 +18,7 @@
[[jetty-admin-guide]]
= Jetty Administration Guide
== Jetty Administration Guide
include::startup/chapter.adoc[]
include::sessions/chapter.adoc[]

149
jetty-documentation/src/main/asciidoc/administration/runner/jetty-runner.adoc
View File

@ -34,33 +34,32 @@ You will need the `jetty-runner` jar:
Let's assume we have a very simple webapp that does not need any resources from its environment, nor any configuration apart from the defaults.
Starting it is as simple as performing the following:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar simple.war
....
----
This will start Jetty on port 8080, and deploy the webapp to `/`.
Your webapp does not have to be packed into a war, you can deploy a webapp that is a directory instead in the same way:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar simple
....
----
In fact, the webapp does not have to be a war or even a directory, it can simply be a Jetty link:#using-context-provider[context xml] file that describes your webapp:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar simple-context.xml
....
----
____
[NOTE]
====
When using a context xml file, the application being deployed is not even required to be a fully-fledged webapp.
It can simply be a Jetty link:#what-is-a-context[context].
____
====
By default, `jetty-runner` implements all Configuration Classes so that users can set up and deploy new instances with as little configuration as possible.
If you wish to only implement certain Configuration Classes, they will need to be defined in the context xml for the webapp/context.
The default Configuration Classes are:
@ -82,60 +81,58 @@ If you have more than one webapp that must be deployed, simply provide them all
You can control the context paths for them using the `--path` parameter.
Here's an example of deploying 2 wars (although either or both of them could be unpacked directories instead):
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --path /one my1.war --path /two my2.war
....
----
If you have context xml files that describe your webapps, you can fully configure your webapps in them and hence you won't need to use the command line switches.
Just provide the list of context files like so:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar my-first-context.xml my-second-context.xml my-third-context.xml
....
----
____
[NOTE]
====
Switched used on the command line override configuration file settings.
So, for example, you could set the context path for the webapp inside the context xml file, and use the `--path` switch to override it on the command line.
____
====
===== Changing the Default Port
By default the `jetty-runner` will listen on port 8080.
You can easily change this on the command line using the `--port` command.
Here's an example that runs our simple.war on port 9090:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --port 9090 simple.war
....
----
===== Using jetty.xml Files
Instead of, or in addition to, using command line switches, you can use one or more `jetty.xml` files to configure the environment for your webapps.
Here's an example where we apply two different `jetty.xml` files:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war
....
----
[[runner-configuration-reference]]
==== Full Configuration Reference
You can see the fill set of configuration options using the `--help` switch:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --help
....
----
Here's what the output will look like:
[source, plain, subs="{sub-order}"]
[source, plain]
----
Usage: java [-Djetty.home=dir] -jar jetty-runner.jar [--help|--version] [ server opts] [[ context opts] context ...]
@ -159,66 +156,66 @@ Context opts:
===== Printing the Version
Print out the version of Jetty and then exit immediately.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --version
....
----
===== Configuring a Request Log
Cause Jetty to write a request log with the given name.
If the file is prefixed with `yyyy_mm_dd` then the file will be automatically rolled over.
Note that for finer grained configuration of the link:{JDURL}/org/eclipse/jetty/server/NCSARequestLog.html[request log], you will need to use a Jetty xml file instead.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log my.war
....
----
===== Configuring the Output Log
Redirect the output of jetty logging to the named file.
If the file is prefixed with `yyyy_mm_dd` then the file will be automatically rolled over.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war
....
----
===== Configuring the Interface for HTTP
Like Jetty standalone, the default is for the connectors to listen on all interfaces on a machine.
You can control that by specifying the name or ip address of the particular interface you wish to use with the `--host` argument:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --host 192.168.22.19 my.war
....
----
===== Configuring the Port for HTTP
The default port number is 8080.
To link:#how-to-configure-connectors[configure a https connector], use a Jetty xml config file instead.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --port 9090 my.war
....
----
===== Configuring Stop
You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the `--stop-port` and `--stop-key` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively) parameters as arguments to the `jetty-runner`:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --stop-port 8181 --stop-key abc123
....
----
Then, to stop Jetty from a different terminal, you need to supply the same port and key information.
For this you'll either need a local installation of Jetty, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class.
Here's how to use a Jetty installation to perform a stop:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar start.jar -DSTOP.PORT=8181 -DSTOP.KEY=abc123 --stop
....
----
===== Configuring the Container Classpath
With a local installation of Jetty, you add jars and classes to the container's classpath by putting them in the `{$jetty.base}/lib` directory.
@ -228,52 +225,50 @@ With the `jetty-runner`, you can use the `--lib`, `--jar` and `--classes` argume
You can add 1 or more.
Here's an example of configuring 2 directories:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --lib /usr/local/external/lib --lib $HOME/external-other/lib my.war
....
----
`--jar` adds a single jar file to the container classpath.
You can add 1 or more.
Here's an example of configuring 3 extra jars:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --jar /opt/stuff/jars/jar1.jar --jar $HOME/jars/jar2.jar --jar /usr/local/proj/jars/jar3.jar my.war
....
----
`--classes` add the location of a directory containing classes to add to the container classpath.
You can add 1 or more.
Here's an example of configuring a single extra classes dir:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --classes /opt/stuff/classes my.war
....
----
____
[NOTE]
====
When using the `--jar` and/or `--lib` arguments, by default these will *not* be inspected for `META-INF` information such as `META-INF/resources`, `META-INF/web-fragment.xml`, or `META-INF/taglib.tld`.
If you require these jar files inspected you will need to define the link:https://www.eclipse.org/jetty/documentation/current/configuring-webapps.html#webapp-context-attributes[jar pattern in your context xml file].
Jetty-Runner automatically provides and appends a suitable pattern for jtsl taglibs (this pattern is different than the one in the standard Jetty distribution).
____
====
===== Gathering Statistics
If statistics gathering is enabled, then they are viewable by surfing to the context `/stats`.
You may optionally protect access to that context with a password.
Here's an example of enabling statistics, with no password protection:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --stats unsecure my.war
....
----
If we wished to protect access to the `/stats` context, we would provide the location of a Jetty realm configuration file containing authentication and authorization information.
For example, we could use the following example realm file from the Jetty distribution:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
jetty: MD5:164c88b302622e17050af52c89945d44,user
admin: CRYPT:adpexzg3FUZAk,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq,user
@ -281,18 +276,18 @@ plain: plain,user
user: password,user
# This entry is for digest auth. The credential is a MD5 hash of username:realmname:password
digest: MD5:6e120743ad67abfbc385bc2bb754e297,user
....
----
Assuming we've copied it into the local directory, we would apply it like so
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar jetty-runner.jar --stats realm.properties my.war
....
----
After navigating to http://localhost:8080/ a few times, we can point to the stats servlet on http://localhost:8080/stats to see the output:
....
----
Statistics:
Statistics gathering started 1490627ms ago
@ -346,4 +341,4 @@ Total messages out: 7
Memory:
Heap memory usage: 49194840 bytes
Non-heap memory usage: 12611696 bytes
....
----

10
jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-gcloud-datastore.adoc
View File

@ -50,7 +50,7 @@ To do that, you can use `--skip-file-validation=glcoud-sessions` argument to sta
The gcloud-sessions module will have installed file called `${jetty.home}/etc/jetty-gcloud-sessions.xml`.
This file configures an instance of the `GCloudSessionIdManager` that will be shared across all webapps deployed on that server. It looks like this:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/jetty-gcloud/jetty-gcloud-session-manager/src/main/config/etc/jetty-gcloud-sessions.xml[]
----
@ -105,7 +105,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Get a reference to the GCloudSessionIdManager -->
<Ref id="Server">
@ -129,7 +129,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Reference the server directly -->
<Get name="server">
@ -202,7 +202,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Get a reference to the GCloudSessionIdManager -->
<Ref id="Server">
@ -229,7 +229,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Reference the server directly -->
<Get name="server">

14
jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-infinispan.adoc
View File

@ -47,10 +47,10 @@ To do that, you can use `--skip-file-validation=infinispan` argument to start.ja
You will also find the following properties, either in your base's `start.d/infinispan.ini` file or appended to your `start.ini`, depending on how you enabled the module:
....
----
## Unique identifier for this node in the cluster
jetty.infinispanSession.workerName=node1
....
----
jetty.infinispanSession.workerName::
The name that uniquely identifies this node in the cluster.
@ -65,7 +65,7 @@ The Infinispan module will have installed file called `$\{jetty.home}/etc/jetty-
This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-infinispan.xml[]
----
@ -91,7 +91,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Expose the jetty infinispan classes for session serialization -->
<Get name="serverClasspathPattern">
@ -132,7 +132,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Expose the jetty infinispan classes for session serialization -->
<Get name="serverClasspathPattern">
@ -187,6 +187,6 @@ To do this, firstly ensure that you have included the lines containing the `getS
Then, create the file `${jetty.base}/resources/hotrod-client.properties`.
Add the following line to this file:
....
----
infinispan.client.hotrod.marshaller=org.eclipse.jetty.session.infinispan.WebAppMarshaller
....
----

16
jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-jdbc.adoc
View File

@ -46,7 +46,7 @@ When using the jetty distribution, to enable jdbc session persistence, you will
You will also find the following properties, either in your base's start.d/jdbc-session.ini file or appended to your start.ini, depending on how you enabled the module:
[source, java, subs="{sub-order}"]
[source, java]
----
## Unique identifier for this node in the cluster
jetty.jdbcSession.workerName=node1
@ -80,7 +80,7 @@ The jdbc-session module will have installed file called `$\{jetty.home}/etc/jett
This file configures an instance of the `JDBCSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-jdbc-sessions.xml[]
----
@ -89,7 +89,7 @@ As well as uncommenting and setting up appropriate values for the properties dis
As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server();
...
@ -129,7 +129,7 @@ These classes have getter/setter methods for the table name and all columns.
Here's an example of changing the name of `JettySessionsId` table and its single column.
This example will use java code, but as explained above, you may also do this via a Jetty xml configuration file:
[source, java, subs="{sub-order}"]
[source, java]
----
JDBCSessionIdManager idManager = new JDBCSessionIdManager(server);
@ -142,7 +142,7 @@ idManager.setSessionIdTableSchema(idTableSchema);
In a similar fashion, you can change the names of the table and columns for the `JettySessions` table.
*Note* that both the `SessionIdTableSchema` and the `SessionTableSchema` instances are set on the `JDBCSessionIdManager` class.
[source, java, subs="{sub-order}"]
[source, java]
----
JDBCSessionIdManager idManager = new JDBCSessionIdManager(server);
@ -172,7 +172,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Ref id="Server">
<Call id="idMgr" name="getSessionIdManager"/>
@ -192,7 +192,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Get name="server">
@ -213,7 +213,7 @@ From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance direc
If you're embedding this in code:
[source, java, subs="{sub-order}"]
[source, java]
----
//assuming you have already set up the JDBCSessionIdManager as shown earlier

14
jetty-documentation/src/main/asciidoc/administration/sessions/legacy/session-clustering-mongodb.adoc
View File

@ -53,7 +53,7 @@ To do that, you can use `--skip-file-validation=nosql` argument to start.jar on
You will also find the following properties, either in your base's `start.d/nosql.ini` file or appended to your `start.ini`, depending on how you enabled the module:
[source, xml, subs="{sub-order}"]
[source, xml]
----
## Unique identifier for this node in the cluster
jetty.nosqlSession.workerName=node1
@ -77,7 +77,7 @@ The nosql module will have installed file called `$\{jetty.home}/etc/jetty-nosql
This file configures an instance of the `MongoSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/jetty-nosql/src/main/config/etc/jetty-nosql.xml[]
----
@ -86,7 +86,7 @@ The `MongoSessionIdManager` needs access to a MongoDB cluster, and the `jetty-no
If you need to configure something else, you will need to edit this file.
Here's an example of a more complex setup to use a remote MongoDB instance:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="mongodb" class="com.mongodb.Mongo">
<Arg>
@ -130,7 +130,7 @@ Here's an example of a more complex setup to use a remote MongoDB instance:
As Jetty configuration files are direct mappings of XML to Java, it is straight forward to do this in code:
[source, java, subs="{sub-order}"]
[source, java]
----
Server server = new Server();
@ -186,7 +186,7 @@ The basic difference is how you get a reference to the Jetty `org.eclipse.jetty.
From a context xml file, you reference the Server instance as a Ref:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Ref name="Server" id="Server">
<Call id="mongoIdMgr" name="getSessionIdManager"/>
@ -207,7 +207,7 @@ From a context xml file, you reference the Server instance as a Ref:
From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance directly:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Get name="server">
<Get id="mongoIdMgr" name="sessionIdManager"/>
@ -227,7 +227,7 @@ From a `WEB-INF/jetty-web.xml` file, you can reference the Server instance direc
If you're embedding this in code:
[source, java, subs="{sub-order}"]
[source, java]
----
//assuming you have already set up the MongoSessionIdManager as shown earlier
//and have a reference to the Server instance:

18
jetty-documentation/src/main/asciidoc/administration/sessions/legacy/setting-session-characteristics.adoc
View File

@ -74,7 +74,7 @@ The following sections provide examples of how to apply the init parameters.
You can set these parameters as context parameters in a web application's `WEB-INF/web.xml` file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
@ -103,7 +103,7 @@ You can set these parameters as context parameters in a web application's `WEB-I
You can configure init parameters on a web application, either in code, or in a Jetty context xml file equivalent:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -130,7 +130,7 @@ You can configure init parameters on a web application, either in code, or in a
You can configure init parameters directly on a `SessionManager` instance, either in code or the equivalent in xml:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -165,7 +165,7 @@ For full details, consult the http://docs.oracle.com/javaee/6/api/javax/servlet/
Below is an example of this implementation: a `ServletContextListener` retrieves the `SessionCookieConfig` and sets up some new values when the context is being initialized:
[source, java, subs="{sub-order}"]
[source, java]
----
import javax.servlet.SessionCookieConfig;
import javax.servlet.ServletContextEvent;
@ -205,7 +205,7 @@ public class TestListener implements ServletContextListener
You can also use `web.xml` to configure the session handling characteristics instead: here's an example doing exactly the same as above instead of using code:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app
@ -236,7 +236,7 @@ In addition to the configuration of link:#session-cookie-configuration[session c
To determine what are the _default_ session tracking characteristics used by the container, call:
[source, java, subs="{sub-order}"]
[source, java]
----
javax.servlet.SessionContext.getDefaultSessionTrackingModes();
----
@ -249,21 +249,21 @@ _default_ session tracking modes for Jetty are:
To see which session tracking modes are actually in effect for this Context, the following call returns a `java.util.Set` of `javax.servlet.SessionTrackingMode`:
[source, java, subs="{sub-order}"]
[source, java]
----
javax.servlet.SessionContext.getEffectiveSessionTrackingModes();
----
To change the session tracking modes, call:
[source, java, subs="{sub-order}"]
[source, java]
----
javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>);
----
You may also set the tracking mode in `web.xml`, e.g.:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app

6
jetty-documentation/src/main/asciidoc/administration/sessions/legacy/using-persistent-sessions.adoc
View File

@ -31,7 +31,7 @@ A `SessionManager` does just what its name suggests – it manages the lifecycle
Each webapp must have its own unique `SessionManager` instance.
Enabling persistence is as simple as configuring the `HashSessionManager` as the `SessionManager` for a webapp and telling it where on disk to store the sessions:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -75,7 +75,7 @@ For example, the Wicket web framework requires the servlet environment to be ava
Using `SessionManager.setLazyLoad(true)`, Jetty loads sessions lazily either when it receives the first request for a session, or the session scavenger runs for the first time, whichever happens first.
Here's how the configuration looks in XML:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Set name="sessionHandler">
<New class="org.eclipse.jetty.server.session.SessionHandler">
@ -93,7 +93,7 @@ Here's how the configuration looks in XML:
To enable session persistence for the Jetty Maven plugin, set up the `HashSessionManager` in the configuration section like so:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>

13
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-file-system.adoc
View File

@ -26,7 +26,7 @@ Note: Persisting sessions to the local file system should *not* be used in a clu
When using the Jetty distribution, you will first need to enable the `session-store-file` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@ -48,17 +48,16 @@ By default Session files will be saved to this directory.
In addition to adding these modules to the classpath of the server, several ini configuration files were added to the `${jetty.base}/start.d` directory.
____
[NOTE]
====
Session data is now only loaded when requested.
Previous functionality such as `setLazyLoad` has been removed.
____
====
==== Configuring File System Session Properties
Opening `start.d/session-store-file.ini` will show a list of all the configurable options for the file system session module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-file
@ -80,10 +79,10 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
____
====

16
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-gcloud.adoc
View File

@ -66,7 +66,7 @@ To enable communication using the GCloud Emulator:
When using the Jetty distribution, you will first need to enable the `session-store-gcloud` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@ -191,7 +191,7 @@ It does *not*, however, configure a SLF4J implementation for the users.
As such, you will also need to enable one of the SLF4J implementation modules listed.
In this example, we will enable the `slf4j-simple-impl` module to provide a SLF4J implementation.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --add-to-start=slf4j-simple-impl
INFO : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
@ -206,16 +206,15 @@ When the `--add-to-start` argument was added to the command line the first time,
In addition to adding these modules to the classpath of the server it also added the respective configuration files to the `${jetty.base}start.d` directory.
____
[NOTE]
====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
____
====
==== Configuring GCloud Session Properties
Opening the `start.d/session-store-gcloud.ini` will display a list of all the configurable properties for the Google Cloud DataStore module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-gcloud
@ -250,14 +249,13 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
____
====
jetty.session.gcloud.maxRetries::
Maxmium number of tries to connect to GCloud DataStore to write sessions.
jetty.session.gcloud.backoffMs::

22
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-hazelcast.adoc
View File

@ -24,7 +24,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-hazelcast-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
@ -64,16 +64,15 @@ It also downloaded the needed Hazelcast-specific jar files and created a directo
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
____
[NOTE]
====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
____
====
==== Configuring Hazelcast Remote Properties
Opening the `start.d/session-store-hazelcast-remote.ini` will show a list of all the configurable options for the Hazelcast module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-hazelcast-remote
@ -103,22 +102,21 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
Be aware using the `scavengeZombies` option that if your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances.
____
====
==== Configuring Embedded Hazelcast Clustering
During testing, it can be helpful to run an in-process instance of Hazelcast.
To enable this you will first need to enable the `session-store-hazelcast-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
@ -160,7 +158,7 @@ In addition to adding these modules to the classpath of the server it also added
Opening the `start.d/start.d/session-store-hazelcast-embedded.ini` will show a list of all the configurable options for the Hazelcast module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-hazelcast-embedded
@ -186,12 +184,12 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
Be aware using the `scavengeZombies` option that if your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances. In the cast of embedded hazelcast, as it is started before your webapp, it will NOT have access to your webapp's classes - you will need to extract these classes and put them onto the jetty server's classpath.
____
====

42
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-infinispan.adoc
View File

@ -25,7 +25,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-infinispan-remote` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@ -63,16 +63,15 @@ It also downloaded the needed Infinispan-specific jar files and created a direct
In addition to adding these modules to the classpath of the server it also added several ini configuration files to the `${jetty.base}/start.d` directory.
____
[NOTE]
====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
____
====
==== Configuring Inifinspan Remote Properties
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-infinispan-remote
@ -100,20 +99,19 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
____
====
==== Configuring the Remote Infinispan Query Module
Enabling this module allows jetty to search infinispan for expired sessions that are no longer being referenced by any jetty node.
Note that this is an *additional* module, to be used in conjuction with the `session-store-infinispan-remote` module.
[source, screen, subs="{sub-order}"]
[source, screen]
----
java -jar ../start.jar --add-to-start=infinispan-remote-query
----
@ -126,12 +124,11 @@ There are no configuration properties associated with this module.
During testing, it can be helpful to run an in-process instance of Infinispan.
To enable this you will first need to enable the `session-store-infinispan-embedded` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
____
[IMPORTANT]
====
If you are running Jetty with JDK 9 or greater, enable `session-store-infinispan-embedded-910.mod` instead.
____
[source, screen, subs="{sub-order}"]
====
[source, screen]
----
java -jar ../start.jar --add-to-start=session-store-infinispan-embedded
@ -167,7 +164,7 @@ In addition to adding these modules to the classpath of the server it also added
Opening the `start.d/session-store-infinispan-remote.ini` will show a list of all the configurable options for the JDBC module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-infinispan-embedded
@ -185,20 +182,18 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
____
====
==== Configuring Inifinspan Embedded Query
Similarly to the `session-store-infinispan-remote` module, the `session-store-infinispan-embedded` module has an adjunct module `infinispan-embedded-query`, which when enabled, will allow jetty to detect and properly scavenge defunct sessions stranded in infinispan.
[source, screen, subs="{sub-order}"]
[source, screen]
----
java -jar ../start.jar --add-to-start=infinispan-embedded-query
----
@ -213,14 +208,13 @@ Prior to release 9.4.13 we used the default Infinispan serialization, however th
See issue https://github.com/eclipse/jetty.project/issues/2919 for more background.
We have provided a conversion program which will convert any sessions stored in Infinispan to the new format.
____
[IMPORTANT]
====
We recommend that you backup your stored sessions before running the conversion program.
____
====
How to use the converter:
[source, screen, subs="{sub-order}"]
[source, screen]
----
java -cp servlet-api-3.1.jar:jetty-util-9.4.13.jar:jetty-server-9.4.13.jar:infinispan-remote-9.1.0.Final.jar:jetty-infinispan-9.4.13.jar:[other classpath] org.eclipse.jetty.session.infinispan.InfinispanSessionLegacyConverter
@ -240,7 +234,7 @@ When used with no arguments the usage message is printed. When used with the `ca
To perform the conversion, run the InfinispanSessionLegacyConverter with just the `cache-name`, and optionally the `host` system property.
The following command will attempt to convert all sessions in the cached named `my-remote-cache` on the machine `myhost`, ensuring that application classes in the `/my/custom/classes` directory are on the classpath:
[source, screen, subs="{sub-order}"]
[source, screen]
----
java -cp servlet-api-3.1.jar:jetty-util-9.4.13.jar:jetty-server-9.4.13.jar:infinispan-remote-9.1.0.Final.jar:jetty-infinispan-9.4.13.jar:/my/custom/classes org.eclipse.jetty.session.infinispan.InfinispanSessionLegacyConverter -Dhost=myhost my-remote-cache
----

9
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-jdbc.adoc
View File

@ -24,7 +24,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-jdbc` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@ -48,7 +48,7 @@ In addition to adding these modules to the classpath of the server, several ini
Opening the `start.d/session-store-jdbc.ini` will show a list of all the configurable options for the JDBC module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-jdbc
@ -103,14 +103,13 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
____
====
db-connection-type::
Set to either `datasource` or `driver` depending on the type of connection being used.
jetty.session.jdbc.datasourceName::

2
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-memcachedsessiondatastore.adoc
View File

@ -31,7 +31,7 @@ To enable it with the Jetty distribution, enable the `session-store-cache` link:
After enabling, the `$jetty.base/start.d/session-store-cache.ini` file will be generated:
[source, screen, subs="{sub-order}"]
[source, screen]
----
--module=session-store-cache

18
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-mongodb.adoc
View File

@ -24,7 +24,7 @@
When using the Jetty distribution, you will first need to enable the `session-store-mongo` link:#startup-modules[module] for your link:#startup-base-and-home[Jetty base] using the `--add-to-start` argument on the command line.
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
@ -61,16 +61,15 @@ It also downloaded the needed Mongo-specific jar file and created a directory na
In addition to adding these modules to the classpath of the server, several ini configuration files were added to the `${jetty.base}/start.d` directory.
____
[NOTE]
====
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated `${jetty.base}/lib/` directory and use the `--skip-file-validation=<module name>` command line option to prevent errors when starting your server.
____
====
==== Configuring MongoDB Session Properties
Opening the `start.d/session-store-mongo.ini` will show a list of all the configurable options for the MongoDB module:
[source, screen, subs="{sub-order}"]
[source, screen]
----
# ---------------------------------------
# Module: session-store-mongo
@ -97,14 +96,13 @@ jetty.session.savePeriod.seconds=0::
By default whenever the last concurrent request leaves a session, that session is always persisted via the `SessionDataStore`, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the `SessionDataStore` will skip persisting the session if only the access time changed, and it has been less than `savePeriod` seconds since the last time the session was written.
+
____
[NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to `savePeriod` seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the `maxIdleTime` of the session when setting the `savePeriod` is imperative - there is no point in setting a `savePeriod` that is larger than the `maxIdleTime`.
____
====
jetty.session.mongo.dbName::
Name of the database in Mongo used to store the Session collection.
jetty.session.mongo.collectionName::
@ -123,9 +121,9 @@ jetty.session.mongo.connectionString;;
The string defining the MongoURI value, such as `mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]`.
More information on how to format the MongoURI string can be found in the https://docs.mongodb.com/manual/reference/connection-string/[official documentation for mongo.]
+
____
[NOTE]
====
You will only use *one* `connection-type` at a time, `address` or `uri`.
If both are utilized in your `session-store-mongo.ini`, only the last `connection-type` configured in the file will be used.
By default, the `connection-type` of `address` is used.
____
====

7
jetty-documentation/src/main/asciidoc/administration/sessions/session-configuration-sessioncache.adoc
View File

@ -26,7 +26,7 @@ If you wish to change any of the default values, you need to enable the `session
Once the `session-cache-hash` module has been enabled, you can view a list of all the configurable values by opening `start.d/session-cache-hash.ini`:
[source, screen, subs="{sub-order}"]
[source, screen]
----
--module=session-cache-hash
@ -47,11 +47,10 @@ Values are:
* 0 : sessions are evicted from the cache as soon as the last active request for it finishes
* >= 1 : any positive number is the time in seconds after which a session that is in the cache but has not experienced any activity will be evicted
____
[NOTE]
====
If you are not using a `SessionDataStore` that persists sessions, be aware that evicted sessions will be lost.
____
====
jetty.session.saveOnInactiveEvict::
Boolean, default `false`.
Controls whether a session will be saved to the `SessionDataStore` just prior to its eviction.

2
jetty-documentation/src/main/asciidoc/administration/sessions/session-hierarchy.adoc
View File

@ -47,7 +47,7 @@ There is only one (1) `SessionDataStore` per `SessionCache`.
Visually the session architecture can be represented like this:
image::images/SessionsHierarchy.png[]
image::administration/sessions/images/SessionsHierarchy.png[]
==== Configuring Sessions in the Jetty Distribution

6
jetty-documentation/src/main/asciidoc/administration/sessions/sessions-usecases.adoc
View File

@ -68,7 +68,7 @@ That said, if a user wishes to configure sessions this way, it is possible using
Below is an example of how you could configure a the link:#configuring-sessions-file-system[`FileSessionDataStore`], but the same concept would apply to any of the *SessionDataStores discussed in this chapter:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Call id="sh" name="getSessionHandler">
@ -88,8 +88,8 @@ Below is an example of how you could configure a the link:#configuring-sessions-
The example above functions in either a `jetty-web.xml` file or a link:#using-basic-descriptor-files[context xml descriptor file.]
____
[NOTE]
====
If you explicitly configure the `SessionCache` and `SessionDataStore` for a `SessionHandler` in a context xml file or `jetty-web.xml` file, any session modules you already have enabled are ignored.
So, for example, if you had enabled the `session-store-gcloud module` for your sever, you could force a particular webapp to use the `FileSessionDataStore` by explicitly configuring it in either a context xml file or a `jetty-web.xml` file as shown above.
____
====

4
jetty-documentation/src/main/asciidoc/administration/startup/custom-modules.adoc
View File

@ -240,8 +240,8 @@ INFO : server initialized in ${jetty.base}/start.d/server.ini
INFO : Base directory was modified
----
____
[NOTE]
====
It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down.
If a dependent module also has dependencies they too will be enabled.
____
====

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base-listconfig.adoc
View File

@ -16,8 +16,8 @@
// ========================================================================
//
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
@ -67,4 +67,4 @@ No classpath entries and/or version information available show.
Jetty Active XMLs:
------------------
(no xml files specified)
....
----

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-empty-base.adoc
View File

@ -16,8 +16,8 @@
// ========================================================================
//
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty]$ mkdir mybase
[jetty]$ cd mybase
[mybase]$ ls -la
@ -30,4 +30,4 @@ WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs]
java -jar start.jar --help # for more information
....
----

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy-listconfig.adoc
View File

@ -16,8 +16,8 @@
// ========================================================================
//
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
@ -83,4 +83,4 @@ ${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.xml
....
----

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-http-webapp-deploy.adoc
View File

@ -16,8 +16,8 @@
// ========================================================================
//
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar $JETTY_HOME/start.jar --add-to-start=http,webapp,deploy
INFO : webapp initialized in ${jetty.base}/start.ini
INFO : server transitively enabled, ini template available with --add-to-start=server
@ -27,4 +27,4 @@ INFO : http initialized in ${jetty.base}/start.ini
INFO : deploy initialized in ${jetty.base}/start.ini
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified
....
----

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-list-logging-modules.adoc
View File

@ -16,8 +16,8 @@
// ========================================================================
//
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=logging,-internal
Available Modules:
@ -91,4 +91,4 @@ Modules for tag 'requestlog':
Depend: server, logback-core, resources
LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml
....
----

6
jetty-documentation/src/main/asciidoc/administration/startup/screen-list-modules.adoc
View File

@ -16,8 +16,8 @@
// ========================================================================
//
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar ../start.jar --list-modules
Available Modules:
@ -728,4 +728,4 @@ Modules for tag 'session':
Tags: session
Depend: server
XML: etc/sessions/id-manager.xml
....
----

76
jetty-documentation/src/main/asciidoc/administration/startup/start-jar.adoc
View File

@ -21,12 +21,12 @@
The most basic way of starting the Jetty standalone server is to execute the `start.jar`, which is a bootstrap for starting Jetty with the configuration you want.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ java -jar start.jar
2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-{VERSION}
...
....
----
Jetty is a highly modularized web server container.
Very little is mandatory and required, and most components are optional; you enable or disable them according to the needs of your environment.
@ -90,10 +90,10 @@ Lists the resolved configuration that will start Jetty.
* Server XML configuration files
--dry-run::
Print the command line that the start.jar generates, then exit. This may be used to generate command lines when the start.ini includes -X or -D arguments:
....
----
$ java -jar start.jar --dry-run > jetty.sh
$ . jetty.sh
....
----
--dry-run=<parts>::
Print specific parts of the command line. The parts are a comma separated list of:
@ -104,17 +104,17 @@ Print specific parts of the command line. The parts are a comma separated list o
* "args" - the arguments passed to the main class
It is possible to decompose the start command:
....
----
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
....
----
Alternatively to create an args file for java:
....
----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
....
----
--exec::
Forces the start to use a forked instance of java to run Jetty.
Some modules include `--exec` in order to set java command line options.
@ -163,25 +163,25 @@ Note: Transitive modules are also appended.
If a module contains an .ini template with properties, you can also edit these properties when activating the module.
To do this, simply list the property and its value after the `-add-to-start` command, such as in the following example:
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ java -jar start.jar --add-to-start=http jetty.http.port=8379 jetty.http.host=1.2.3.4
....
----
+
Doing this will uncomment the property in the associated .ini file and set it to the value specified.
--update-ini::
Used to update a specified property or properties that exist in an existing .ini file.
Jetty scans the command line, `${jetty.base}` and `${jetty.home}` for .ini files that have the specified property and update it accordingly.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ java -jar ../start.jar --update-ini jetty.http.port=8417
ConfigSource <command-line>
ConfigSource ${jetty.base}
INFO : http property updated jetty.http.port=8417
INFO : http updated ${jetty.base}/start.d/http.ini
ConfigSource ${jetty.home}
....
----
+
--create-startd::
Creates a `${jetty.base}/start.d/` directory.
@ -197,14 +197,14 @@ Please see link:#start-vs-startd[Start.ini vs. Start.d] for more information.
--write-module-graph=<filename>::
Advanced feature: Creates a graphviz http://graphviz.org/content/dot-language[dot file] of the module graph as it exists for the active `${jetty.base}`.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# generate module.dot
$ java -jar start.jar --module=websocket --write-module-graph=modules.dot
# post process to a PNG file
$ dot -Tpng -o modules.png modules.dot
....
----
+
See http://graphviz.org/[graphviz.org] for details on http://graphviz.org/content/command-line-invocation[how to post-process this dotty file] into the output best suited for your needs.
@ -216,11 +216,10 @@ This may download a file from the network if the module provides a URL.
Disable the [files] section validation of content in the `${jetty.base}` directory for a specific module.
Useful for modules that have downloadable content that is being overridden with alternatives in the `${jetty.base}`` directory.
____
[CAUTION]
====
This advanced option is for administrators that fully understand the configuration of their `${jetty.base}` and are willing to forego some of the safety checks built into the jetty-start mechanism.
____
====
--approve-all-licenses::
Approve all license questions.
Useful for enabling modules from a script that does not require user interaction.
@ -252,25 +251,24 @@ You can configure a port number for Jetty to listen on for a stop command, so yo
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the `STOP.PORT` and `STOP.KEY` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively, which will set these as system parameters) parameters as arguments to the `start.jar`:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar ${JETTY_HOME}/start.jar STOP.PORT=1234 STOP.KEY=secretpassword
....
----
Then, to stop Jetty from a different terminal, you need to supply this port and key information.
You can either use a copy of the Jetty distribution, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class to accomplish this.
Here's how to use the Jetty distribution, leveraging `start.jar`, to perform a stop:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
> java -jar start.jar STOP.PORT=8181 STOP.KEY=abc123 --stop
....
----
____
[NOTE]
====
To perform a graceful shutdown of Jetty, the `stats` link:#startup-modules[module] *must* be enabled.
____
====
===== Advanced Commands
--lib=<classpath>::
@ -293,34 +291,34 @@ Default is https://repo1.maven.org/maven2/.
==== Shaded Start.jar
If you have a need for a shaded version of `start.jar` (such as for Gradle), you can achieve this via a Maven dependency.
[source, xml, subs="{sub-order}"]
....
[source, xml]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-start</artifactId>
<version>{VERSION}</version>
<classifier>shaded</classifier>
</dependency>
....
----
==== Start.jar without exec or forking.
Some Jetty modules include the `--exec` option so that java command line options can be set.
Also some `start.jar` options (eg. `--jpms`) include an implicit `--exec`.
To start jetty without forking a new JVM instance from the start JVM, the `--dry-run` option can be used to generate a command line:
....
----
$ CMD=$(java -jar start.jar --dry-run)
$ $CMD
....
----
It is possible to decompose the start command so that it can be modified:
....
----
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
....
----
Alternatively to create an args file for java:
....
----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
....
----

45
jetty-documentation/src/main/asciidoc/administration/startup/startup-base-vs-home.adoc
View File

@ -30,12 +30,11 @@ Jetty Home::
* Also known as the `${jetty.home}` property.
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
____
[IMPORTANT]
====
Jetty Home should always be treated as a standard of truth.
All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.
____
====
[[base-vs-home-resolution]]
Potential configuration is resolved from these 2 directory locations.
@ -55,8 +54,8 @@ For more details on how startup with start.jar works, see link:#executing-startj
The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ ls -la
total 496
@ -86,12 +85,12 @@ drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-distribution-{VERSION}/demo-base/webapps/] at interval 1
2013-10-16 09:08:48.072:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
...
....
----
If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration by using the `--list-config` command.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[demo-base]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
@ -213,7 +212,7 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-rewrite.xml
${jetty.base}/etc/demo-rewrite-rules.xml
${jetty.base}/etc/test-realm.xml
....
----
The `--list-config` command line option displays what the configuration will look like when starting Jetty.
This includes information on the Java environment to the system properties, the classpath and the Active Jetty IoC XML used to build up the Jetty server configuration.
@ -222,8 +221,8 @@ Of note, is that the output will make it known where the configuration elements
If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ cat start.ini
# Enable security via jaas, and configure it
@ -257,7 +256,7 @@ jetty.dump.stop=false
--module=resources
--module=client
--module=annotations
....
----
In this example, `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
You will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
@ -274,8 +273,8 @@ The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and
You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
@ -286,14 +285,14 @@ You can opt to manually define the `${jetty.home}` and `${jetty.base}` directori
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
----
Alternately, you can declare one directory and let the other one be discovered.
The following example uses default discovery of `${jetty.home}` by using the parent directory of wherever `start.jar` itself is, and a manual declaration of `${jetty.base}`.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
@ -302,15 +301,15 @@ The following example uses default discovery of `${jetty.home}` by using the par
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
----
But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing
the `start.jar` in your `{$jetty.home}` remotely.
The following demonstrates this by allowing default discovery of `${jetty.home}` via locating the `start.jar`, and using the `user.dir` System Property for `${jetty.base}`.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION}
@ -320,10 +319,10 @@ The following demonstrates this by allowing default discovery of `${jetty.home}`
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
----
____
[IMPORTANT]
====
Be aware of the `user.dir` system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property.
It is strongly recommended that you sit in the directory that is your desired `${jetty.base}` when starting Jetty to have consistent behavior and use of the `user.dir` system property.
____
====

11
jetty-documentation/src/main/asciidoc/administration/startup/startup-classpath.adoc
View File

@ -42,11 +42,10 @@ Of special note, there are 2 structural modules defined to ease some of this for
+
Logging libraries often have classpath lookup of their configuration files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so this would be the ideal setup for this sort of configuration demand.
____
[NOTE]
====
Both the `ext` and `resources` modules declare relative paths that follow link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
____
====
==== Interrogating the Server Classpath
The Jetty `start.jar` has the ability to resolve the classpath from the command line, modules and configuration, and to list the classpath entries it will use to start jetty.
@ -55,8 +54,8 @@ The `--list-classpath` command line option is used as such.
(Demonstrated with the link:#demo-base[demo-base from the Jetty Distribution])
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[demo-base]$ java -jar $JETTY_HOME/start.jar --list-classpath
Jetty Server Classpath:
@ -106,6 +105,6 @@ Note: order presented here is how they would appear on the classpath.
39: {VERSION} | ${jetty.home}/lib/websocket/websocket-common-{VERSION}.jar
40: {VERSION} | ${jetty.home}/lib/websocket/websocket-server-{VERSION}.jar
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
....
----
Of note is that an attempt is made to list the internally declared version of each artifact on the Server Classpath, which can potentially help when diagnosing classpath issues.

54
jetty-documentation/src/main/asciidoc/administration/startup/startup-jpms.adoc
View File

@ -36,8 +36,8 @@ or greater, and explicitly referencing the "enterprise" classes as dependencies,
To start Jetty on the module-path rather than the class-path, it is enough to add the `--jpms` option to the command line, for example:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ mkdir my-jetty-base
$ cd my-jetty-base
$ java -jar $JETTY_HOME/start.jar --add-to-start=http
@ -46,7 +46,7 @@ INFO : http initialized in ${jetty.base}/start.ini
INFO : threadpool transitively enabled, ini template available with --add-to-start=threadpool
INFO : Base directory was modified
$ java -jar $JETTY_HOME/start.jar --jpms
....
----
The example above creates a link:#startup-base-and-home[Jetty base directory] and enables the `http` module using the `--add-to-start` command.
The server then starts Jetty on the module-path using the `--jpms` option.
@ -59,20 +59,20 @@ You will have two JVMs running: one that runs `start.jar` and one that runs Jett
If you are interested in the details of how the command line to run Jetty on the module-path looks like, you can add the `--dry-run` option:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ java -jar $JETTY_HOME/start.jar --jpms --dry-run
....
----
This will give an output looking something like this (broken in sections for clarity):
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
/opt/openjdk-11+28/bin/java
--module-path /opt/jetty/lib/servlet-api-3.1.jar:/opt/jetty/lib/jetty-schemas-3.1.jar:/opt/jetty/lib/jetty-http-9.4.13-SNAPSHOT.jar:...
--patch-module servlet.api=/opt/jetty/lib/jetty-schemas-3.1.jar
--module org.eclipse.jetty.xml/org.eclipse.jetty.xml.XmlConfiguration /opt/jetty/etc/jetty-threadpool.xml /opt/jetty/etc/jetty.xml ...
....
----
The `--module-path` option specifies the list of Jetty jars.
This list depends on the Jetty modules that have been enabled via the link:#startup-modules[`--add-to-start`] command.
@ -94,15 +94,15 @@ Jetty needs to be able to instantiate those classes and therefore needs to be ab
When Jetty runs on the class-path, this is easily achieved by using a link:#custom-modules[custom module]:
[source, screen, subs="{sub-order}"]
[source, screen]
.mysql.mod
....
----
[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
....
----
However, when running on the module-path, things are quite different.
@ -111,9 +111,9 @@ Because it is not an automatic module, it is not added to the module graph, and
To add the JPMS module `java.sql` to the module graph, you need to modify your custom module in the following way, using our `mysql.mod` as an example:
[source, screen, subs="{sub-order}"]
[source, screen]
.mysql.mod
....
----
[description]
MySQL module
@ -122,7 +122,7 @@ lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: java.sql
....
----
The new `[jpms]` section is only used when Jetty is started on the module-path via the `--jpms` command line option.
@ -130,9 +130,9 @@ Assuming that `mysql-connector-java-*.jar` is a non JPMS modular jar, or an auto
If `mysql-connector-java-*.jar` were a proper JPMS modular jar with name (for example) `com.mysql.jdbc`, then it would need to be explicitly added to the module graph, in this way:
[source, screen, subs="{sub-order}"]
[source, screen]
.mysql.mod
....
----
[description]
MySQL module
@ -141,21 +141,21 @@ lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: com.mysql.jdbc
....
----
The JPMS module `java.sql` does not need to be explicitly added because it would be a dependency of the `com.mysql.jdbc` module and therefore automatically added to the module graph.
The `[jpms]` section has the following format:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jpms]
add-modules: <module name>(,<module name>)*
patch-module: <module>=<file>(:<file>)*
add-opens: <module>/<package>=<target-module>(,<target-module>)*
add-exports: <module>/<package>=<target-module>(,<target-module>)*
add-reads: <module>=<target-module>(,<target-module>)*
....
----
[[jpms-module-path-alternative]]
==== Alternative way to start Jetty on the module-path
@ -164,22 +164,22 @@ The section above uses the `--jpms` command line option to start Jetty on the mo
An alternative way of achieving the same result is to use a Jetty module, `$JETTY_BASE/modules/jpms.mod`,
that specifies that you want to run using JPMS (and possibly add some JPMS specific configuration).
[source, screen, subs="{sub-order}"]
[source, screen]
.jpms.mod
....
----
[ini]
--jpms
[jpms]
# Additional JPMS configuration.
....
----
The `[ini]` section is equivalent to passing the `--jpms` option to the command line.
The `[jpms]` section (see also the link:#jpms-advanced-config[advanced JPMS configuration section])
allows you specify additional JPMS configuration.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ mkdir jetty-base-jpms
$ cd jetty-base-jpms
$ mkdir modules
@ -189,4 +189,4 @@ $ cp /tmp/jpms.mod modules/
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,jpms
# Jetty will start on the module-path.
$ java -jar $JETTY_HOME/start.jar
....
----

33
jetty-documentation/src/main/asciidoc/administration/startup/startup-modules.adoc
View File

@ -25,12 +25,11 @@ Modules allow flexibility for implementations and their plug-and-play nature mak
[[enabling-modules]]
==== Enabling Modules
____
[TIP]
====
The default distribution has a co-mingled `${jetty.home}` and `${jetty.base}` where the directories for `${jetty.home}` and `${jetty.base}` point to the same location.
It is highly encouraged that you learn about the differences in link:#startup-base-and-home[Jetty Base vs Jetty Home] and take full advantage of this setup.
____
====
Enabling a module is a simple process: simply add the `--add-to-start=<module-name1>,<module-name2>,...etc.` syntax on the command line.
Doing this will enable the specified module and any dependent modules.
@ -70,8 +69,8 @@ As an alternative to a single `start.ini` file you can opt to house modules in a
Modules activated when a `start.d` directory exists will be stored as a single file per module.
Below is an example of a fresh `${jetty.base}` that will create a `start.d` directory and activate several modules.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty.home]$ mkdir mybase
[jetty.home]$ cd mybase/
[mybase]$ java -jar ../start.jar --create-startd
@ -97,7 +96,7 @@ drwxr-xr-x 3 staff staff 102 Aug 29 15:16 ..
-rw-r--r-- 1 staff staff 2250 Aug 29 15:19 server.ini
-rw-r--r-- 1 staff staff 265 Aug 29 15:19 webapp.ini
-rw-r--r-- 1 staff staff 177 Aug 29 15:19 websocket.ini
....
----
In the example, we first create a new `${jetty.base}` and then create the `start.d` directory with the `--create-startd` command.
Next, we use the `--add-to-start` command which activates the modules and creates their respective ini files in the `start.d` directory.
@ -106,8 +105,8 @@ If you have an existing `start.ini` file but would like to use the `start.d` str
Doing this will create the `start.d` directory and copy your existing `start.ini` file in to it.
Any new modules added to the server will have their own `<module name>.ini` file created in the `start.d` directory.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar ../start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.ini
INFO : server initialised in ${jetty.base}/start.ini
@ -132,7 +131,7 @@ INFO : Base directory was modified
└── start.d
├── ssl.ini
└── start.ini
....
----
[NOTE]
--
@ -148,22 +147,21 @@ This is done by editing the associated ini file for the module.
If your server setup is using a centralized ini configuration, you will edit the `${jetty.base}/server.ini` file.
If you have elected to manage each module within it's own ini file, you can find these files in the `${jetty.base}/start.d` directory.
____
[IMPORTANT]
====
It is important that you *do not* modify the module files in the `$JETTY_HOME/modules` directory.
$JETTY_HOME should always remain a standard of truth.
If you want to make a change to an actual module file (not the values in its `ini-template`), either edit its associated `ini` file in the `$JETTY_BASE/start.d` directory or make a copy of the desired module file and copy it to the `$JETTY_BASE` directory and edit it there.
The start.jar reads local `$JETTY_BASE/modules` files (if they exist) before scanning `$JETTY_HOME`.
____
====
When a module is activated, a number of properties are set by default.
To view these defaults, open up the associated ini file.
Listed in the ini file is the associated module file and any properties that can be set.
Below is an example of the `requestlog.ini` file:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# ---------------------------------------
# Module: requestlog
--module=requestlog
@ -194,7 +192,7 @@ Below is an example of the `requestlog.ini` file:
## Whether to log LogLatency
# jetty.requestlog.loglatency=false
....
----
The first lines name the module file being called (located in `{$jetty.home/modules}`).
Subsequent lines list properties that can be changed as well as a description for each property.
@ -215,12 +213,11 @@ This command will also show you which modules are __enabled__.
Modules are sorted by the value in the `[tags]` section of the associated `.mod` file.
If there are multiple entries in the `[tags]` section, it sorts by the first tag in the list.
____
[NOTE]
====
By default, the `--list-modules` command line argument shows all modules that do not include `internal` in the `[tags]` section of the associated `.mod` file.
If you would like to see *all* modules, use `--list-all-modules`
____
====
Here's an example of the `--list-modules` command:
include::screen-list-modules.adoc[]

42
jetty-documentation/src/main/asciidoc/administration/startup/startup-overview.adoc
View File

@ -71,17 +71,17 @@ XML Files::
The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080
....
----
This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module.
Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ cat modules/http.mod
[depend]
server
@ -92,15 +92,15 @@ etc/jetty-http.xml
[ini-template]
jetty.http.port=8080
http.timeout=30000
....
----
The `http` module declares that `http` depends on the server module, uses the `jetty-http.xml` file, and can be parameterized with `jetty.http.port` and `http.timeout` parameters.
The INI-template section is not actually used by the command above, so the `jetty.http.port` must still be defined on the command line.
Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ cat modules/server.mod
[lib]
lib/servlet-api-3.1.jar
@ -116,15 +116,15 @@ etc/jetty.xml
[ini-template]
threads.min=10
threads.max=200
....
----
The `server` module declares the libraries the server needs and to use `jetty.xml` file.
The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.
Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config
Java Environment:
@ -174,7 +174,7 @@ Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-http.xml
....
----
This represents the entirety of the configuration that is applied to start Jetty.
@ -182,8 +182,8 @@ If you don't want to use the `start.jar` bootstrap, you can start Jetty using a
The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ echo jetty.http.port=8080 > /tmp/jetty.properties
[jetty-distribution-{VERSION}]$ export JETTY_HOME=`pwd`
@ -203,14 +203,14 @@ org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml
....
----
The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the `jetty.properties` file.
You can further simplify the startup of this server by using the INI template defined by the modules to create a `start.ini` file with the command:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ mkdir example-base
[example-base]$ cd example-base
@ -231,11 +231,11 @@ total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini
....
----
Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[example-base]$ java -jar $JETTY_HOME/start.jar
....
----

78
jetty-documentation/src/main/asciidoc/administration/startup/startup-unix-service.adoc
View File

@ -27,8 +27,8 @@ This script is suitable for setting up Jetty as a service in Unix.
The minimum steps to get Jetty to run as a Service include:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[/opt/jetty]# tar -zxf /home/user/downloads/jetty-distribution-{VERSION}.tar.gz
[/opt/jetty]# cd jetty-distribution-{VERSION}/
[/opt/jetty/jetty-distribution-{VERSION}]# ls
@ -43,7 +43,7 @@ JETTY_HOME=/opt/jetty/jetty-distribution-{VERSION}
[/opt/jetty/jetty-distribution-{VERSION}]# service jetty start
Starting Jetty: OK Wed Nov 20 10:26:53 MST 2013
....
----
From this demonstration we can see that Jetty started successfully as a Unix Service from the `/opt/jetty/jetty-distribution-{VERSION}` directory.
@ -57,12 +57,12 @@ The techniques outlined here assume an installation on Linux (demonstrated on Ub
Prepare some empty directories to work with.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# mkdir -p /opt/jetty
# mkdir -p /opt/web/mybase
# mkdir -p /opt/jetty/temp
....
----
The directory purposes are as follows:
@ -79,15 +79,15 @@ It is our experience that the standard temp directory is often managed by variou
Jetty 9.3 requires Java 8 (or greater) to run.
Make sure you have it installed.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# apt-get install openjdk-8-jdk
....
----
Or download Java 8 from: http://www.oracle.com/technetwork/java/javase/downloads/index.html
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# java -version
java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2)
@ -113,15 +113,15 @@ update-alternatives: using /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java to pro
java version "1.7.0_25"
OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1ubuntu0.12.04.2)
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)
....
----
It is recommended that you create a user to specifically run Jetty.
This user should have the minimum set of privileges needed to run Jetty.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# useradd --user-group --shell /bin/false --home-dir /opt/jetty/temp jetty
....
----
This will create a user called `jetty`, belonging to the group called `jetty`, with no shell access (aka `/bin/false`), and home directory at `/opt/jetty/temp`.
@ -129,13 +129,13 @@ Download a copy of the Jetty distribution from the link:#jetty-downloading[Offic
Unpack it into place.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[/opt/jetty]# tar -zxf /home/user/Downloads/jetty-distribution-{VERSION}.tar.gz
[/opt/jetty]# ls -F
jetty-distribution-{VERSION}/
[/opt/jetty]# mkdir /opt/jetty/temp
....
----
It might seem strange or undesirable to unpack the first portion of the jetty-distribution directory name too.
But starting with Jetty 9 the split between `${jetty.home}` and `${jetty.base}` allows for easier upgrades of Jetty itself while isolating your webapp specific configuration.
@ -153,8 +153,8 @@ In past versions of Jetty, you would configure / modify / add to the `jetty-dist
While this is still supported, we encourage you to setup a proper `${jetty.base}` directory, as it will benefit you with easier `jetty-distribution` upgrades in the future.
--
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# cd /opt/web/mybase/
[/opt/web/mybase]# ls
[/opt/web/mybase]# java -jar /opt/jetty/jetty-distribution-{VERSION}/start.jar \
@ -171,7 +171,7 @@ While this is still supported, we encourage you to setup a proper `${jetty.base}
INFO : Base directory was modified
[/opt/web/mybase]# ls -F
start.ini webapps/
....
----
At this point you have configured your `/opt/web/mybase` to enable the following modules:
@ -191,44 +191,44 @@ See xref:start-jar[] for more details and options on setting up and configuring
Copy your war file into place.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# cp /home/user/projects/mywebsite.war /opt/web/mybase/webapps/
....
----
Most service installations will want Jetty to run on port 80, now is the opportunity to change this from the default value of `8080` to `80`.
Edit the `/opt/web/mybase/start.ini` and change the `jetty.http.port` value.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# grep jetty.http.port /opt/web/mybase/start.ini
jetty.port=80
....
----
Change the permissions on the Jetty distribution and webapp directories so that the user you created can access it.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# chown --recursive jetty /opt/jetty
# chown --recursive jetty /opt/web/mybase
....
----
Next we need to make the Unix System aware that we have a new Jetty Service that can be managed by the standard `service` calls.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# cp /opt/jetty/jetty-distribution-{VERSION}/bin/jetty.sh /etc/init.d/jetty
# echo "JETTY_HOME=/opt/jetty/jetty-distribution-{VERSION}" > /etc/default/jetty
# echo "JETTY_BASE=/opt/web/mybase" >> /etc/default/jetty
# echo "JETTY_USER=jetty" >> /etc/default/jetty
# echo "TMPDIR=/opt/jetty/temp" >> /etc/default/jetty
....
----
Test out the configuration:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# service jetty status
Checking arguments to Jetty:
START_INI = /opt/web/mybase/start.ini
@ -254,14 +254,14 @@ RUN_CMD = /usr/bin/java
-jar /opt/jetty/jetty-distribution-{VERSION}/start.jar
console-capture.xml
jetty-started.xml
....
----
You now have a configured `${jetty.base}` in `/opt/web/mybase` and a `${jetty.home}` in `/opt/jetty/jetty-distribution-{VERSION}`, along with the service level files necessary to start the service.
Test the service to make sure it starts up and runs successfully.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# service jetty start
Starting Jetty: OK Wed Nov 20 12:35:28 MST 2013
@ -272,6 +272,6 @@ Jetty running pid=2958
[/opt/web/mybase]# ps u 2958
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
jetty 2958 5.3 0.1 11179176 53984 ? Sl 12:46 0:00 /usr/bin/java -Djetty...
....
----
You should now have your server running.

38
jetty-documentation/src/main/asciidoc/administration/startup/startup-windows-service.adoc
View File

@ -27,8 +27,8 @@ The techniques outlined here are based on Windows 7 (64-bit), using JDK 8 (64-bi
Prepare some empty directories to work with.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
C:\> mkdir opt
C:\> cd opt
C:\opt> mkdir jetty
@ -48,7 +48,7 @@ C:\opt> dir
11/21/2013 04:06 PM <DIR> myappbase
11/21/2013 04:06 PM <DIR> temp
0 File(s) 0 bytes
....
----
The directory purposes are as follows:
@ -69,13 +69,13 @@ This is intentionally kept separate from the standard temp directories of Window
Or download Java 8 from: http://www.oracle.com/technetwork/java/javase/downloads/index.html
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
C:\opt>java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)
....
----
Download a copy of the ZIP distribution from the link:#jetty-downloading[Official Eclipse Download Site]
@ -83,8 +83,8 @@ Extract the contents of the `jetty-distribution-{VERSION}` directory to `C:\opt\
Once complete, the contents of the `C:\opt\jetty` directory should look like this:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
C:\opt\jetty>dir
Volume in drive C has no label.
Volume Serial Number is C8CF-820B
@ -110,7 +110,7 @@ C:\opt\jetty>dir
11/21/2013 12:13 PM <DIR> webapps
6 File(s) 453,659 bytes
11 Dir(s) 306,711,420,928 bytes free
....
----
Download a copy of the https://commons.apache.org/proper/commons-daemon/binaries.html[Apache ProcRun] native binaries.
@ -122,8 +122,8 @@ The ZIP file has both 32 bit and 64 bit versions of this file.
Once you are complete, the contents of `C:\opt` directory should look like this:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
C:\opt> dir
Volume in drive C has no label.
Volume Serial Number is DEAD-BEEF
@ -139,14 +139,14 @@ C:\opt> dir
11/21/2013 04:11 PM 104,448 prunmgr.exe
11/21/2013 04:11 PM 80,896 prunsrv.exe
2 File(s) 185,344 bytes
....
----
Now it's time to setup your new `${jetty.base}` directory to have all of your WebApps and the configurations that they need.
We'll start by specifying which modules we want to use (this will create a start.ini file and also create a few empty directories for you)
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
C:\opt\myappbase>java -jar ..\jetty\start.jar --add-to-start=deploy,http,console-capture
WARNING: deploy initialised in ${jetty.base}\start.ini (appended)
@ -174,7 +174,7 @@ C:\opt\myappbase>dir
11/21/2013 12:49 PM <DIR> webapps
1 File(s) 1,355 bytes
4 Dir(s) 306,711,064,576 bytes free
....
----
At this point you have configured your `C:\opt\myappbase` to enable the following modules:
@ -192,10 +192,10 @@ See the section on xref:start-jar[] for more details and options on setting up a
At this point you merely have to copy your WAR files into the `{$jetty.base}/webapps` directory.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
C:\opt\myappbase> copy C:\projects\mywebsite.war webapps\
....
----
At this point you should have your directories, Java, the Jetty distribution, and your webapp specifics setup and ready for operation.
@ -295,4 +295,4 @@ Once you have run `prunsrv.exe //IS/<service-name>` (done for you in the above b
Open the Service View and start your service.
image:images/windows-service-jetty.png[image,width=576]
image:administration/strartup/images/windows-service-jetty.png[image,width=576]

18
jetty-documentation/src/main/asciidoc/administration/tuning/garbage-collection.adoc
View File

@ -31,8 +31,8 @@ These options are general to OpenJDK (and therefore also for the Oracle JVM).
They provide good information about the GC activity of your JVM, producing logs that can later be analyzed to perform finer tuning.
.JDK 8 Garbage Collection Logging Configuration
[source,screen, subs="{sub-order}"]
....
[source,screen]
----
-Xloggc:/path/to/myjettybase/logs/gc.log
-XX:+PrintGCDateStamps
-XX:+PrintGCDetails
@ -40,18 +40,18 @@ They provide good information about the GC activity of your JVM, producing logs
-XX:+PrintReferenceGC
-XX:+PrintTenuringDistribution
-XX:+PrintAdaptiveSizePolicy
....
----
.JDK 9 Garbage Collection Logging Configuration
[source,screen, subs="{sub-order}"]
....
[source,screen]
----
Xlog:gc*,ergo*=trace,ref*=debug,age*=trace:file=/path/to/myjettybase/logs/gc.log:time,level,tags
....
----
There are not many recommended options for GC that can apply to all users.
However, the most obvious one is to disable explicit GC (this is performed regularly by RMI and can introduce an abnormal amount of GC pauses).
[source,screen, subs="{sub-order}"]
....
[source,screen]
----
-XX:+DisableExplicitGC
....
----

40
jetty-documentation/src/main/asciidoc/administration/tuning/high-load.adoc
View File

@ -54,13 +54,13 @@ You can configure most of these in `/etc/security/limits.conf` or via `sysctl`.
You should increase TCP buffer sizes to at least 16MB for 10G paths and tune the auto-tuning (keep in mind that you need to consider buffer bloat).
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ sysctl -w net.core.rmem_max=16777216
$ sysctl -w net.core.wmem_max=16777216
$ sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216"
$ sysctl -w net.ipv4.tcp_wmem="4096 16384 16777216"
....
----
====== Queue Sizes
@ -69,59 +69,59 @@ The default value is 128.
If you are running a high-volume server and connections are getting refused at a TCP level, you need to increase this value.
This setting can take a bit of finesse to get correct: if you set it too high, resource problems occur as it tries to notify a server of a large number of connections, and many remain pending, but if you set it too low, refused connections occur.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ sysctl -w net.core.somaxconn=4096
....
----
The `net.core.netdev_max_backlog` controls the size of the incoming packet queue for upper-layer (Java) processing.
The default (2048) may be increased and other related parameters adjusted with:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ sysctl -w net.core.netdev_max_backlog=16384
$ sysctl -w net.ipv4.tcp_max_syn_backlog=8192
$ sysctl -w net.ipv4.tcp_syncookies=1
....
----
====== Ports
If many outgoing connections are made (for example, on load generators), the operating system might run low on ports.
Thus it is best to increase the port range, and allow reuse of sockets in `TIME_WAIT`:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ sysctl -w net.ipv4.ip_local_port_range="1024 65535"
$ sysctl -w net.ipv4.tcp_tw_recycle=1
....
----
====== File Descriptors
Busy servers and load generators may run out of file descriptors as the system defaults are normally low.
These can be increased for a specific user in `/etc/security/limits.conf`:
....
----
theusername hard nofile 40000
theusername soft nofile 40000
....
----
====== Congestion Control
Linux supports pluggable congestion control algorithms.
To get a list of congestion control algorithms that are available in your kernel run:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ sysctl net.ipv4.tcp_available_congestion_control
....
----
If cubic and/or htcp are not listed, you need to research the control algorithms for your kernel.
You can try setting the control to cubic with:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
$ sysctl -w net.ipv4.tcp_congestion_control=cubic
....
----
====== Mac OS

2
jetty-documentation/src/main/asciidoc/administration/tuning/limit-load.adoc
View File

@ -26,7 +26,7 @@ To achieve optimal fair handling for all users of a server, it can be necessary
An instance of link:{JDURL}/org/eclipse/jetty/server/LowResourceMonitor.html[LowResourceMonitor] may be added to a Jetty server to monitor for low resources situations and to take action to limit the number of idle connections on the server.
To configure the low resources monitor, you can enable the the `lowresources.mod` on the command line, which has the effect of including the following XML configuration:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-lowresources.xml[]
----

62
jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-connectors.adoc
View File

@ -34,8 +34,8 @@ Additional settings, including construction your own constructor Jetty XML files
Out of the box, Jetty provides several link:#startup-modules[modules] for enabling different types of connectors, from HTTP to HTTPS, HTTP/2, and others.
If you startup Jetty with the `--list-modules=connector` command, you can see a list of all available connector modules:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=connector
Available Modules:
@ -178,13 +178,13 @@ Modules for tag 'connector':
Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml
...
....
----
To enable a connector, simply activate the associated module.
Below is an example of activating both the `http` and `https` modules in a fresh link:#startup-base-and-home[Jetty base] using the link:#start-vs-startd[start.d directory]:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase] java -jar $JETTY_HOME/start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
@ -204,14 +204,14 @@ INFO : Base directory was modified
└── start.d
├── http.ini
└── https.ini
....
----
When the `http` and `https` modules were activated, so too were any modules they were dependent on, in this case `server` and `ssl`, as well as any dependencies for those modules, such as the `etc` and `ketystore` directories for `ssl`.
At this point the server has been configured with connectors for both HTTP and HTTPS and can be started:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase] java -jar $JETTY_HOME/start.jar
2017-08-31 10:19:58.855:INFO::main: Logging initialized @372ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:19:59.076:INFO:oejs.Server:main: jetty-9.4.6.v20170531
@ -220,14 +220,14 @@ At this point the server has been configured with connectors for both HTTP and H
2017-08-31 10:19:59.151:INFO:oejus.SslContextFactory:main: x509=X509@5d624da6(mykey,h=[],w=[]) for SslContextFactory@2ef9b8bc(file:///Users/staff/installs/repository/jetty-distribution-{VERSION}/mybase/etc/keystore,file:///Users/staff/installs/repository/jetty-distribution-{VERSION}/mybase/etc/keystore)
2017-08-31 10:19:59.273:INFO:oejs.AbstractConnector:main: Started ServerConnector@2b98378d{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-08-31 10:19:59.274:INFO:oejs.Server:main: Started @791ms
....
----
When modules are enabled, they are loaded with several default options.
These can be changed by editing the associated module ini file in the `start.d` directory (or the associated lines in `server.ini` if your implementation does not use `start.d`).
For example, if we examine the `http.ini` file in our `start.d` directory created above, we will see the following settings:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
@ -261,41 +261,40 @@ For example, if we examine the `http.ini` file in our `start.d` directory create
## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230
....
----
To make a change to these settings, uncomment the line (by removing the #) and change the property to the desired value.
For example, if you wanted to change the HTTP port to 5231, you would edit the line as follows:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
...
## Connector port to listen on
jetty.http.port=5231
...
....
----
Now when the server is started, HTTP connections will enter on port 5231:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[mybase] java -jar ../start.jar
2017-08-31 10:31:32.955:INFO::main: Logging initialized @366ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:31:33.109:INFO:oejs.Server:main: jetty-9.4.6.v20170531
2017-08-31 10:31:33.146:INFO:oejs.AbstractConnector:main: Started ServerConnector@2ef9b8bc{HTTP/1.1,[http/1.1]}{0.0.0.0:5231}
...
2017-08-31 10:31:33.263:INFO:oejs.Server:main: Started @675ms
....
----
Every module has their own set of configuration options, and reviewing them all is recommended.
For additional information on the module system, please refer to our documentation on link:#startup-modules[Startup Modules].
____
[NOTE]
====
Editing these module files is the recommended way to edit the configuration of your server.
Making changes to the associated Jetty XML file for connectors is *not* recommended, and is for advanced users only.
If you do wish to edit Jetty XML, please see our section on managing link:#[Jetty Home and Jetty Base] to ensure your Jetty Home remains a standard of truth for your implementation.
____
====
==== Limiting Connections
Jetty also provides the means by which to limit connections to the server and/or contexts.
@ -338,7 +337,7 @@ link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-server/src/main/config/etc/jetty-alpn.
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:{GITBROWSEURL}/jetty-server/src/main/config/etc/jetty-http.xml[`jetty-http.xml`]) you can do this by:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
@ -360,7 +359,7 @@ Typically the defaults are sufficient for almost all deployments.
You can 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}"]
[source, xml]
----
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
@ -373,7 +372,7 @@ For example, you can set the port with the Jetty XML:
Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line.
Thus typically the port is set within Jetty XML, but uses the `Property` element to be customizable:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg>
@ -418,7 +417,7 @@ To avoid duplicate configuration, the standard Jetty distribution creates the co
A typical configuration of link:{JDURL}/org/eclipse/jetty/server/HttpConfiguration.html[HttpConfiguration] is:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Set name="secureScheme">https</Set>
@ -431,7 +430,7 @@ A typical configuration of link:{JDURL}/org/eclipse/jetty/server/HttpConfigurati
This example HttpConfiguration may be used by reference to the ID "`httpConfig`":
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Call name="addConnector">
<Arg>
@ -457,7 +456,7 @@ Please note that if your `httpConfig` does not include a `secureScheme` or `secu
For SSL-based connectors (in `jetty-https.xml` and `jetty-http2.xml`), the common "`httpConfig`" instance is used as the basis to create an SSL specific configuration with ID "`sslHttpConfig`":
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Arg><Ref refid="httpConfig"/></Arg>
@ -484,19 +483,18 @@ In such environments, the TCP/IP connection terminating on the server does not o
Thus Intermediaries typically implement one of several de facto standards to communicate to the server information about the original 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.
____
====
===== 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.
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}"]
[source, xml]
----
<New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Set name="outputBufferSize">32768</Set>
@ -519,7 +517,7 @@ The connection factory can be added to any link:{JDURL}/org/eclipse/jetty/server
An example of adding the factory to a HTTP connector is shown below:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Call name="addConnector">
<Arg>

6
jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl-distribution.adoc
View File

@ -27,7 +27,7 @@ provider and the https://github.com/google/conscrypt/[Conscrypt] provider as SSL
For the default SSL support, simply activate the `ssl` link:#startup-modules[module]:
[source, plain, subs="{sub-order}"]
[source, plain]
----
$ cd /path/to/mybase
$ java -jar ${JETTY_HOME}/start.jar --add-to-startd=ssl
@ -63,7 +63,7 @@ jetty.sslContext.keyStorePassword::
Enabling Conscrypt SSL is just as easy as default SSL - enable both the `conscrypt` and `ssl` link:#startup-modules[modules]:
[source, plain, subs="{sub-order}"]
[source, plain]
----
$ cd ${JETTY_HOME}
$ java -jar ../start.jar --add-to-start=ssl,conscrypt
@ -98,7 +98,7 @@ SSL-specific parameters, like `keyStorePath` and `keyStorePassword` can still co
To enable client certificate authentication in the Jetty Distribution, you need to enable the both the `ssl` and `https` modules.
[source, plain, subs="{sub-order}"]
[source, plain]
----
$ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https

130
jetty-documentation/src/main/asciidoc/configuring/connectors/configuring-ssl.adoc
View File

@ -43,17 +43,16 @@ All CBC based ciphers are supported since Java 7, the new GCM modes are supporte
TLS v1.0, v1.1 and SSL v3 are no longer supported by default. If your Jetty implementation requires these protocols for legacy support, they can be enabled manually.
____
[NOTE]
====
Once TLS v1.3 is released, there will be no workaround available for TLS v1.0 or v1.1.
Plans for TLS v1.3 include banning ciphers with known vulnerabilities from being present at any level.
It is recommended to upgrade any clients using these ciphers as soon as possible or face being locked into a outdated version of Jetty, Java or even OS.
____
====
By default, Jetty excludes these ciphers in the link:{GITBROWSEURL}/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java#L249-L256[`SslContextFactory`.]
You can re-enable these by re-declaring the ciphers you want excluded in code:
[source, java, subs="{sub-order}"]
[source, java]
----
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setExcludeCipherSuites("^.*_(MD5|SHA|SHA1)$");
@ -110,23 +109,22 @@ You should read the full manuals of the tools you are using if you want to speci
The following command generates a key pair and certificate directly into file `keystore`:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA
----
____
[NOTE]
====
The DSA key algorithm certificate produces an error after loading several pages.
In a browser, it displays a message "Could not establish an encrypted connection because certificate presented by localhost as an invalid signature."
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.
For example:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA
Enter keystore password: password
@ -159,7 +157,7 @@ If you want to use only a self signed certificate for some kind of internal admi
If you are using Java 8 or later, then you may also use the SAN extension to set one or more names that the certificate applies to:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA -ext 'SAN=dns:jetty.eclipse.org,dns:*.jetty.org'
...
@ -170,7 +168,7 @@ $ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256with
The following command generates a key pair in the file `jetty.key`:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ openssl genrsa -aes128 -out jetty.key
----
@ -179,7 +177,7 @@ You might also want to use the `-rand` file argument to provide an arbitrary fil
The following command generates a certificate for the key into the file `jetty.crt`:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt
----
@ -190,7 +188,7 @@ 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 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}"]
[source, screen]
----
$ openssl genrsa -aes128 -out jetty.key
Generating RSA private key, 2048 bit long modulus
@ -243,7 +241,7 @@ Each CA has its own instructions (look for JSSE or OpenSSL sections), but all in
The following command generates the file `jetty.csr` using `keytool` for a key/cert already in the keystore:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ keytool -certreq -alias jetty -keystore keystore -file jetty.csr
----
@ -253,7 +251,7 @@ $ keytool -certreq -alias jetty -keystore keystore -file jetty.csr
The following command generates the file `jetty.csr` using OpenSSL for a key in the file `jetty.key`:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ openssl req -new -key jetty.key -out jetty.csr
----
@ -266,13 +264,12 @@ You need to enter the details for the certificate again.
Once a CA has sent you a certificate, or if you generated your own certificate without `keytool`, you need to load it into a JSSE keystore.
____
[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`.
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
@ -280,7 +277,7 @@ 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}"]
[source, screen]
----
jetty.crt
-----BEGIN CERTIFICATE-----
@ -302,14 +299,14 @@ Rcz6oCRvCGCe5kDB
The following command loads a PEM encoded certificate in the `jetty.crt` file into a JSSE keystore:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts
----
If the certificate you receive from the CA is not in a format that `keytool` understands, you can use the `openssl` command to convert formats:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt
----
@ -322,29 +319,28 @@ The certificate can be one you generated yourself or one returned from a CA in r
The following OpenSSL command combines the keys in `jetty.key` and the certificate in the `jetty.crt` file into the `jetty.pkcs12` file:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12
----
If you have a chain of certificates, because your CA is an intermediary, build the PKCS12 file as follows:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt > cert-chain.txt
$ openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12
----
____
[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.
Load the resulting PKCS12 file into a JSSE keystore with `keytool`:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore
----
@ -361,11 +357,11 @@ If you imported the key and certificate originally using the PKCS12 method, use
The `keystore` only contains the server's private key and certificate.
[[img-certificate-chain]]
image::images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"]
image::configuring/connectors/images/certificate-chain.png[title="Certificate chain", alt="Certificate chain"]
[literal]
.The structure of KeyStore file:
....
----
├── PrivateKeyEntry
│   ├── PrivateKey
│   ├── Certificate chain
@ -376,13 +372,12 @@ image::images/certificate-chain.png[title="Certificate chain", alt="Certificate
│   └── Intermediary CA certificate
└── TrustedCertEntry
   └── Root CA certificate
....
----
____
[NOTE]
====
Both the `Intermediary CA certificate` and `Root CA certificate` are optional.
____
====
[source%nowrap,plain,linenums]
----
$ cd $JETTY_BASE
@ -644,21 +639,21 @@ the other is `$JETTY/etc/truststore` which contains intermediary CA and root CA.
[literal]
.The structure of `$JETTY/etc/keystore`
....
----
└── PrivateKeyEntry
   ├── PrivateKey
   └── Certificate chain
      └── Server certificate (end entity)
....
----
[literal]
.The structure of `$JETTY/etc/truststore`
....
----
├── TrustedCertEntry
│   └── Intermediary CA certificate
└── TrustedCertEntry
   └── Root CA certificate
....
----
[[configuring-sslcontextfactory]]
==== Configuring the Jetty SslContextFactory
@ -686,11 +681,10 @@ While the `SslContextFactory` can operate without a keystore (this mode is most
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.
____
====
setKeyStorePassword::
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::
@ -704,26 +698,24 @@ setExcludeCipherSuites / setIncludeCipherSuites::
setExcludeProtocols / setIncludeProtocols::
This allows for the customization of the selected Protocols that will be used by SSL/TLS.
____
[NOTE]
====
When working with Includes / Excludes, it is important to know that *Excludes will always win.*
The selection process is to process the JVM list of available Cipher Suites or Protocols against the include list, then remove the excluded ones.
Be aware that each Include / Exclude list has a Set method (replace the list) or Add method (append the list).
____
____
====
[CAUTION]
====
The keystore and truststore passwords may also be set using the system properties: `org.eclipse.jetty.ssl.keypassword` `org.eclipse.jetty.ssl.password`.
This is _not_ a recommended usage.
____
====
[[conscrypt]]
==== Conscrypt SSL
Jetty includes support for Google's https://github.com/google/conscrypt/[Conscrypt SSL], which is built on their fork of https://www.openssl.org/[OpenSSL], https://boringssl.googlesource.com/boringssl/[BoringSSL].
Implementing Conscrypt for the link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-conscrypt-server/src/test/java/org/eclipse/jetty/alpn/conscrypt/server/ConscryptHTTP2Server.java[server] or link:{GITBROWSEURL}/jetty-alpn/jetty-alpn-conscrypt-client/src/test/java/org/eclipse/jetty/alpn/java/client/ConscryptHTTP2Client.java[client] is very straightforward process - simply instantiate an instance of Conscrypt's `OpenSSLProvider` and set `Conscrypt` as a provider for Jetty's `SslContextFactory`:
[source, java, subs="{sub-order}"]
[source, java]
----
...
Security.addProvider(new OpenSSLProvider());
@ -760,31 +752,28 @@ It's crucial that you use the _exact_ names of the cipher suites as used/known b
You can get them by obtaining an instance of SSLEngine and call `getSupportedCipherSuites()`.
Tools like https://www.ssllabs.com/[ssllabs.com] might report slightly different names which will be ignored.
____
[IMPORTANT]
====
It is important to stay up-to-date with the latest supported cipher suites.
Be sure to consult Oracle's link:https://java.com/en/jre-jdk-cryptoroadmap.html[JRE and JDK Cryptographic Roadmap] frequently for recent and upcoming changes to supported ciphers.
____
____
====
[IMPORTANT]
====
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/`.
____
====
Both `setIncludeCipherSuites` and `setExcludeCipherSuites` can be fed by the exact cipher suite name used in the JDK or by using regular expressions.
If you have a need to adjust the Includes or Excludes, then this is best done with a custom XML that configures the `SslContextFactory` to suit your needs.
____
[NOTE]
====
Jetty *does* allow users to enable weak/deprecated cipher suites (or even no cipher suites at all).
By default, if you have these suites enabled warning messages will appear in the server logs.
____
====
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}"]
[source, xml]
----
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
"http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -808,7 +797,7 @@ You can do anything you want with the `SslContextFactory` in use by the Jetty Di
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}"]
[source, plain]
----
$ cd /path/to/mybase
$ ls -l
@ -821,23 +810,21 @@ 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 also applies 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 your Jetty configuration.
____
____
====
[TIP]
====
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.
____
====
Additional Include / Exclude examples:
*Example*: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Enable Forward Secrecy Ciphers.
Note: this replaces the default Include Cipher list -->
@ -851,7 +838,7 @@ Additional Include / Exclude examples:
*Example*: Exclude all old, insecure or anonymous cipher suites:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Eliminate Old / Insecure / Anonymous Ciphers -->
<Call name="addExcludeCipherSuites">
@ -869,7 +856,7 @@ Additional Include / Exclude examples:
*Example*: Since 2014 SSLv3 is considered insecure and should be disabled.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<!-- Eliminate Insecure Protocols -->
<Call name="addExcludeProtocols">
@ -884,14 +871,13 @@ Additional Include / Exclude examples:
</Call>
----
____
[NOTE]
====
Note that disabling SSLv3 prevents very old browsers like Internet Explorer 6 on Windows XP from connecting.
____
====
*Example*: TLS renegotiation could be disabled too to prevent an attack based on this feature.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Set name="renegotiationAllowed">FALSE</Set>
----
@ -905,7 +891,7 @@ You can also dump the server when shutting down the server instance by adding `j
Specifically, you will want to look for the `SslConnectionFactory` portion of the dump.
[source, screen, subs="{sub-order}"]
[source, screen]
----
[my-base]$ java -jar ${JETTY_HOME}/start.jar jetty.server.dumpAfterStart=true

10
jetty-documentation/src/main/asciidoc/configuring/contexts/configuring-virtual-hosts.adoc
View File

@ -62,7 +62,7 @@ You supply a list of IP addresses and names at which the web application is reac
Suppose you have a webapp called `blah.war`, that you want all of the above names and addresses to be served at path "`/blah`".
Here's how you would configure the virtual hosts with a link:#deployable-descriptor-file[context XML] file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -102,7 +102,7 @@ Using the method of preparing link:#deployable-descriptor-file[contextXML] files
For `blah` webapp:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -128,7 +128,7 @@ These URLs now resolve to the blah context (ie `blah.war`):
For `other` webapp:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -177,7 +177,7 @@ To achieve this, we simply use the same context path of `/` for each of our weba
For foo webapp:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -197,7 +197,7 @@ For foo webapp:
For bar webapp:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

12
jetty-documentation/src/main/asciidoc/configuring/contexts/custom-error-pages.adoc
View File

@ -32,7 +32,7 @@ This element creates a mapping between the error-code or exception-type to the l
Error code example:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<error-page>
<error-code>404</error-code>
@ -43,7 +43,7 @@ Error code example:
Exception example:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<error-page>
<exception-type>java.io.IOException</exception-type>
@ -74,7 +74,7 @@ javax.servlet.error.status_code::
You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with `web.xml`, specifically with the support of error code ranges.
Context files are normally located in `${jetty.base}/webapps/` (see `DeployerManager` for more details) and an example of more flexible error page mapping is below:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -122,7 +122,7 @@ Context files are normally located in `${jetty.base}/webapps/` (see `DeployerMan
If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of `ErrorHandler` configured either the Context or the Server.
An `ErrorHandler` may extend the `ErrorHandler` class and may totally replace the handle method to generate an error page, or it can implement some or all of the following methods to partially modify the error pages:
[source, java, subs="{sub-order}"]
[source, java]
----
void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException
void handleErrorPage(HttpServletRequest request, Writer writer, int code, String message) throws IOException
@ -136,7 +136,7 @@ void writeErrorPageStacks(HttpServletRequest request, Writer writer) throws IOEx
An `ErrorHandler` instance may be set on a Context by calling the `ContextHandler.setErrorHandler` method. This can be done by embedded code or via context IoC XML.
For example:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.server.handler.ContextHandler">
...
@ -150,7 +150,7 @@ For example:
An `ErrorHandler` instance may be set on the entire server by setting it as a dependent bean on the Server instance.
This can be done by calling `Server.addBean(Object)` via embedded code or in `jetty.xml` IoC XML:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
...

8
jetty-documentation/src/main/asciidoc/configuring/contexts/serving-webapp-from-particular-port.adoc
View File

@ -35,14 +35,14 @@ When creating new configurations for alternative server:
* Change all `id="Server"` to the new server name:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">
----
* For all connectors for the new server change the `refid` in the server argument:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Arg name="server"><Ref refid="OtherServer" /></Arg>
----
@ -55,14 +55,14 @@ When creating new configurations for alternative server:
The following example creates another server instance and configures it with a connector and deployer:
[source, xml, subs="{sub-order}"]
[source, xml]
----
include::{SRCDIR}/examples/embedded/src/main/resources/jetty-otherserver.xml[]
----
To run the other server, add the extra configuration file(s) to the command line:
[source, screen, subs="{sub-order}"]
[source, screen]
----
java -jar start.jar jetty-otherserver.xml
----

2
jetty-documentation/src/main/asciidoc/configuring/contexts/setting-context-path.adoc
View File

@ -45,7 +45,7 @@ If a web application is deployed using the WebAppProvider of the DeploymentManag
If a web application is deployed using the `WebAppProvider` of the `DeploymentManager` with an XML IoC file to configure the context, then the `setContextPath` method can be called within that file.
For example:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/test</Set>

11
jetty-documentation/src/main/asciidoc/configuring/contexts/setting-form-size.adoc
View File

@ -32,7 +32,7 @@ This can be done either in a context XML deployment descriptor external to the w
In either case the syntax of the XML file is the same:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
@ -46,7 +46,7 @@ In either case the syntax of the XML file is the same:
Set an attribute in `jetty.xml` on the Server instance for which you want to modify the maximum form content size:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.server.Server">
<Call name="setAttribute">
@ -56,20 +56,19 @@ Set an attribute in `jetty.xml` on the Server instance for which you want to mod
</Configure>
----
____
[IMPORTANT]
====
It is important to remember that you should *not* modify the XML files in your `$JETTY_HOME`.
If you do for some reason feel you want to change the way an XML file operates, it is best to make a copy of it in your `$JETTY_BASE` in an `/etc` directory.
Jetty will always look first to the `$JETTY_BASE` for configuration.
____
====
==== For All Apps in the JVM
Use the system property `org.eclipse.jetty.server.Request.maxFormContentSize`.
This can be set on the command line or in the `$JETTY_BASE\start.ini` or any `$JETTY_BASE\start.d\*.ini` link:#startup-modules[module ini file.]
Using `$JETTY_BASE\start.d\server.ini` as an example:
[source, console, subs="{sub-order}"]
[source, console]
----
# ---------------------------------------
# Module: server

37
jetty-documentation/src/main/asciidoc/configuring/contexts/temporary-directories.adoc
View File

@ -27,15 +27,15 @@ Whether you set the location of the temporary directory - or you let Jetty creat
By default, Jetty will create a temporary directory for each web application. The name of the directory will be of the form:
....
----
"jetty-"+host+"-"+port+"-"+resourceBase+"-_"+context+"-"+virtualhost+"-"+randomdigits+".dir"
....
----
For example:
....
----
jetty-0.0.0.0-8080-test.war-_test-any-8900275691885214790.dir
....
----
Where `0.0.0.0` is the host address, `8080` is the port, `test.war` is the resourceBase, `test` is the context path (with / converted to _), `any` is the virtual host, and `randomdigits` are a string of digits guaranteed to be unique.
@ -51,7 +51,7 @@ As usual with Jetty, you can either set this attribute in a context xml file, or
Here's an example of setting it in an xml file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -67,7 +67,7 @@ Here's an example of setting it in an xml file:
The equivalent in code is:
[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
@ -83,7 +83,7 @@ There are several ways to use a particular directory as the temporary directory:
As before this can be accomplished with an XML file or directly in code.
Here is an example of setting the temp directory in XML:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -96,7 +96,7 @@ Here is an example of setting the temp directory in XML:
And here is an example of doing it with java code:
[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
@ -108,7 +108,7 @@ context.setTempDirectory(new File("/some/dir/foo"));
You should set this context attribute with the name of directory you want to use as the temp directory.
Again, you can do this in XML:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -125,7 +125,7 @@ Again, you can do this in XML:
Or in java:
[source, java, subs="{sub-order}"]
[source, java]
----
WebAppContext context = new WebAppContext();
context.setContextPath("/test");
@ -135,17 +135,16 @@ context.setAttribute("javax.servlet.context.tempdir", "/some/dir/foo");
Once a temporary directory has been created by either of these methods, a file instance for it is set as the value of the `javax.servlet.context.tempdir` attribute of the web application.
____
[NOTE]
====
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
There is a JVM bug concerning link:http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421[caching of jar contents.]
____
====
===== Setting the Temp Directory on the Command Line
You can set the location of the temp directory on the command line when Jetty starts up in two ways.
First is the most straightforward, simply add it to your command line when starting Jetty.
[source, screen, subs="{sub-order}"]
[source, screen]
----
java -jar ../start.jar -Djava.io.tmpdir=/path/to/desired/directory
----
@ -156,8 +155,8 @@ After enabling the module (using the `--add-to-start=jvm` command), edit the `jv
You will also need verify the line including the `--exec` command is not commented out, as this is required for Jetty to start a new, forked JVM.
Below is an example of the standard `jvm.ini` file altered to include a reference to a temp directory.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
# ---------------------------------------
# Module: jvm
# A noop module that creates an ini template useful for
@ -187,7 +186,7 @@ Below is an example of the standard `jvm.ini` file altered to include a referenc
# -XX:+PrintCommandLineFlags
# -XX:+DisableExplicitGC
-Djava.io.tmpdir=/path/to/desired/directory
....
----
==== The "work" Directory
@ -204,7 +203,7 @@ Sometimes it is useful to keep the contents of the temporary directory between r
By default, Jetty will *not* persist the temp directory.
To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].
____
[NOTE]
====
Be aware that if you call `setPersistTempDirectory(true)`, but let Jetty create a new temp directory each time (i.e. you do NOT set an explicit temp directory), then you will accumulate temp directories in your chosen temp directory location.
____
====

17
jetty-documentation/src/main/asciidoc/configuring/deploying/configuring-specific-webapp-deployment.adoc
View File

@ -43,7 +43,7 @@ contextPath::
For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.war` to the context path `/wiki`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -57,7 +57,7 @@ For example, here is a descriptor file that deploys the file `/opt/myapp/myapp.w
Both `SystemProperty` and `Property` elements can be used in the descriptor file.
For example, if the system property is set to `myapp.home=/opt/myapp`, the previous example can be rewritten as:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -71,11 +71,10 @@ For example, if the system property is set to `myapp.home=/opt/myapp`, the previ
If the home path for an application needs altered, only the system property needs changed.
This is useful if the version of an app is frequently changed.
____
[NOTE]
====
To ensure your `web.xml` files are validated, you will need to set the `validateXml` attribute to true as described link:#jetty-xml-dtd[here.]
____
====
[[configuring-advanced-descriptor-files]]
==== Configuring Advanced Descriptor Files
@ -85,7 +84,7 @@ Here are some examples that configure advanced options in the descriptor file.
This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -101,7 +100,7 @@ The next example retrieves the JavaEE Servlet context and sets an initialization
The `setAttribute` method can also be used to set a Servlet context attribute.
However, since the `web.xml` for the web application is processed after the deployment descriptor, the `web.xml` values overwrite identically named attributes from the deployment descriptor.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -122,7 +121,7 @@ The following example sets a special `web.xml` override descriptor.
This descriptor is processed after the web application's `web.xml`, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -137,7 +136,7 @@ This feature is useful when adding parameters or additional Servlet mappings wit
The next example configures not only the web application context, but also a database connection pool (see xref:jndi-datasource-examples[]) that the application can then use.
If the `web.xml` does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

10
jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-architecture.adoc
View File

@ -27,7 +27,7 @@ The Jetty distribution contains example `DeploymentManager` configurations to de
The `DeploymentManager` is the heart of the typical webapp deployment mechanism; it operates as a combination of an Application LifeCycle Graph, Application Providers that find and provide Applications into the Application LifeCycle Graph, and a set of bindings in the graph that control the deployment process.
image:images/Jetty_DeployManager_DeploymentManager_Roles.png[image,width=195]
image:configuring/deploying/images/Jetty_DeployManager_DeploymentManager_Roles.png[image,width=195]
[[udm-application-providers]]
==== Application Providers
@ -40,7 +40,7 @@ The main `AppProvider` with the Jetty distribution is the link:{JDURL}/org/eclip
The core feature of the `DeploymentManager` is the link:{JDURL}/org/eclipse/jetty/deploy/AppLifeCycle.html[Application LifeCycle Graph].
image:images/Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
image:configuring/deploying/images/Jetty_DeployManager_AppLifeCycle-1.png[image,width=340]
The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).
@ -68,7 +68,7 @@ There are four default bindings:
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardStopper.html[`StandardStopper`] — Stops the ContextHandler and stops accepting incoming requests.
* link:{JDURL}/org/eclipse/jetty/deploy/bindings/StandardUndeployer.html[`StandardUndeployer`] — Removes the ContextHandler from Jetty.
image:images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png[image,width=851]
image:configuring/deploying/images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png[image,width=851]
A fifth, non-standard binding, called link:{JDURL}/org/eclipse/jetty/deploy/bindings/DebugBinding.html[DebugBinding], is also available for debugging reasons; it logs the various transitions through the Application LifeCycle.
@ -81,7 +81,7 @@ The format for the XML file is the same as any context XML file and can be used
To use this binding, you can either modify the existing `jetty-deploy.xml` which comes with the Jetty distribution (be sure to link:#startup-base-and-home[copy it to your $JETTY_BASE/etc directory first]), or by link:#custom-modules[creating a new module] file which calls to an additional XML file.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Call name="addLifeCycleBinding">
<Arg>
@ -101,7 +101,7 @@ It supports hot (re)deployment.
The basic operation of the `WebAppProvider` is to periodically scan a directory for deployables.
In the standard Jetty Distribution, this is configured in the `${jetty.home}/etc/jetty-deploy.xml` file.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

10
jetty-documentation/src/main/asciidoc/configuring/deploying/deployment-processing-webapps.adoc
View File

@ -132,7 +132,7 @@ If you have only one webapp that you wish to affect, this may be the easiest opt
You will, however, either need to have a context xml file that represents your web app, or you need to call the equivalent in code.
Let's see an example of how we would add in the Configurations for both JNDI _and_ annotations:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -164,7 +164,7 @@ Of course, you can also use this method to reduce the Configurations applied to
If you use the link:#deployment-architecture[deployer], you can set up the list of Configuration classes on the link:#default-web-app-provider[WebAppProvider].
They will then be applied to each `WebAppContext` deployed by the deployer:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -208,7 +208,7 @@ Instead of having to enumerate the list in its entirety, you can simply nominate
Let's look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
This example uses an xml file, in fact it is the `$JETTY_HOME/etc/jetty-plus.xml` file from the Jetty distribution:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -258,7 +258,7 @@ The value of this attribute is a regexp that defines which _jars_ and _class dir
Here's an example from a context xml file (although as always, you could have accomplished the same in code), which would match any jar whose name starts with "foo-" or "bar-", or a directory named "classes":
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -284,7 +284,7 @@ This can be particularly useful when you have dozens of jars in `WEB-INF/lib`, b
Here's an example in a xml file of a pattern that matches any jar that starts with `spring-`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

2
jetty-documentation/src/main/asciidoc/configuring/deploying/hot-deployment.adoc
View File

@ -36,7 +36,7 @@ The default location for this configuration is in the `${jetty.home}/etc/jetty-d
To modify it as part of the Jetty distribution, first enable the `deploy` module.
Once it is enabled, you can edit these properties in either the `$JETTY_BASE/start.d/deploy.ini` or `$JETTY_BASE/start.ini` file, depending on link:#start-vs-startd[how your implementation is configured.]
[source, screen, subs="{sub-order}"]
[source, screen]
----
<?xml version="1.0"?>
# ---------------------------------------

19
jetty-documentation/src/main/asciidoc/configuring/deploying/quickstart-webapp.adoc
View File

@ -42,7 +42,7 @@ Tests have shown that webapps that took many seconds to scan and deploy can now
In a standard Jetty distribution the quickstart module can be configured with the following command:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart
----
@ -51,7 +51,7 @@ $ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart
In a Maven project you add a dependency on the artifact `jetty-quickstart`.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
@ -81,16 +81,15 @@ generateOrigin::
If true, the origin attribute will be inserted into each element in quickstart-web.xml.
Note that origin attributes will also be generated if debug log level is enabled.
____
[NOTE]
====
If you are using Spring-Boot you must set `generateOrigin` to true.
____
====
The origin is either a descriptor eg web.xml,web-fragment.xml,override-web.xml file, or an annotation eg @WebServlet.
For xml validation each attribute must be unique, and therefore an integer counter is appended to each value.
Some examples of elements with origin attribute information are:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<listener origin="DefaultsDescriptor(file:///path/to/distro/etc/webdefault.xml):21">
<listener origin="WebDescriptor(file:///path/to/base/webapps/test-spec/WEB-INF/web.xml):22">
@ -102,7 +101,7 @@ Some examples of elements with origin attribute information are:
If a web application already has a context xml file, eg `webapps/myapp.xml` file, simply change the class in the `Configure` element.
Otherwise, create a context xml file with the following information (in addition to the usual setting of contextPath, war etc):
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
@ -131,7 +130,7 @@ Note that you will need to provide all necessary jetty jars on the command line
This will unpack the war if necessary, and create the `quickstart-web.xml` before the first deployment:
[source, screen, subs="{sub-order}"]
[source, screen]
----
$ java -cp [jetty classpath] org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war
----
@ -158,7 +157,7 @@ Of course precompiling JSPs is an excellent way to improve the start time of a w
As of Jetty 9.2 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}"]
[source, xml]
----
<context-param>
<param-name>org.eclipse.jetty.jsp.precompiled</param-name>
@ -172,7 +171,7 @@ The Jetty `start.jar` mechanism is a very powerful and flexible mechanism for co
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}"]
[source, screen]
----
$ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
$ eval $RUN

2
jetty-documentation/src/main/asciidoc/configuring/deploying/static-content-deployment.adoc
View File

@ -22,7 +22,7 @@
To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal `ResourceHandler` can be used.
Create a file called `scratch.xml` in the `${jetty.base}/webapps` directory and paste the following file contents in it.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">

26
jetty-documentation/src/main/asciidoc/configuring/jsp/configuring-jsp.adoc
View File

@ -28,7 +28,7 @@ Jetty uses Jasper from http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html
By default the Jetty distribution enables the JSP link:#startup-modules[module], and by default, this module is set to Apache Jasper.
[source, plain, subs="{sub-order}"]
[source, plain]
----
include::{SRCDIR}/jetty-home/src/main/resources/modules/jsp.mod[]
----
@ -55,7 +55,7 @@ You can do this using a servlet context init-param called `org.eclipse.jetty.ser
For example, suppose you have precompiled your JSPs with the custom package prefix of `com.acme`, then you would add the following lines to your `web.xml` file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<context-param>
<param-name>org.eclipse.jetty.servlet.jspPackagePrefix</param-name>
@ -63,11 +63,10 @@ For example, suppose you have precompiled your JSPs with the custom package pref
</context-param>
----
____
[NOTE]
====
Both Jetty Maven plugins - link:#jetty-jspc-maven-plugin[jetty-jspc-maven-plugin] and the link:#jetty-maven-plugin[jetty-maven-plugin] - will only use Apache Jasper.
____
====
[[compiling-jsps]]
===== Apache JSP Container
@ -161,11 +160,10 @@ Parameters also differ among the various versions of the JSP engine.
This page lists the configuration parameters, their meanings, and their default settings.
Set all parameters on the `org.apache.jasper.servlet.JspServlet` instance defined in the link:#webdefault-xml[`webdefault.xml`] file.
____
[NOTE]
====
Be careful: for all of these parameters, if the value you set doesn't take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as JSP is inconsistent in its parameter naming strategy.
____
====
[[modifying-configuration]]
==== Modifying Configuration
@ -175,7 +173,7 @@ ____
You can make a copy of the link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] that ships with Jetty, apply your changes, and use it instead of the shipped version.
The example below shows how to do this when using the Jetty Maven plugin.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>
@ -189,7 +187,7 @@ The example below shows how to do this when using the Jetty Maven plugin.
If you are using the Jetty distribution, and you want to change the JSP settings for just one or a few of your webapps, copy the `{$jetty.home}/etc/webdefault.xml` file somewhere, modify it, and then use a link:#intro-jetty-configuration-contexts[context xml] file to set this file as the `defaultsDescriptor` for your webapp. Here's a snippet:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/foo</Set>
@ -207,7 +205,7 @@ Another option is to add an entry for the JSPServlet to the `WEB-INF/web.xml` fi
You may also add (but not remove) servlet-mappings.
You can use the entry in link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml] as a starting point.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<servlet id="jsp">
<servlet-name>jsp</servlet-name>
@ -253,7 +251,7 @@ You can use the entry in link:#webdefault-xml[{$jetty.home}/etc/webdefault.xml]
By default, Jetty does not enable async support for the JSP servlet.
Configuring the JSP servlet for async is relatively easy - simply define the `async-supported` parameter as `true` in either your `webdefault.xml` or the `web.xml` for a specific context.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<servlet id="jsp">
<servlet-name>jsp</servlet-name>
@ -284,7 +282,7 @@ To take advantage of this efficiency enhancement, set up the link:#container-inc
The link:#embedded-examples[Embedded Examples] section includes a link:#embedded-webapp-jsp[worked code example] of how to do this.
Below is a snippet from the example:
[source, java, subs="{sub-order}"]
[source, java]
----
webapp.setAttribute("org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern",".*/[^/]*taglibs.*\\.jar$");
----
@ -306,7 +304,7 @@ You can either put them into the lib directory for Apache `{$jetty.home}/lib/apa
You should make your JSF jars dependencies of the plugin and _not_ the webapp itself.
For example:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<plugin>
<groupId>org.eclipse.jetty</groupId>

2
jetty-documentation/src/main/asciidoc/configuring/part.adoc
View File

@ -18,7 +18,7 @@
[[jetty-config-guide]]
= Jetty Configuration Guide
== Jetty Configuration Guide
include::deploying/chapter.adoc[]
include::contexts/chapter.adoc[]

32
jetty-documentation/src/main/asciidoc/configuring/security/authentication.adoc
View File

@ -35,7 +35,7 @@ Internally, configuring an authentication mechanism is done by setting an instan
Below is an example taken from the link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB-INF/web.xml?h=release-9[jetty-test-webapp web.xml] that configures BASIC authentication:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<login-config>
<auth-method>BASIC</auth-method>
@ -46,7 +46,7 @@ Below is an example taken from the link:{GITBROWSEURL}/tests/test-webapps/test-j
The link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB-INF/web.xml?h=release-9[jetty-test-webapp web.xml] also includes commented out examples of other DIGEST and FORM configuration:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<login-config>
<auth-method>FORM</auth-method>
@ -62,7 +62,7 @@ The link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB
With FORM Authentication, you must also configure URLs of pages to generate a login form and handle errors.
Below is a simple HTML form from the link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/webapp/logon.html?h=release-9[test webapp logon.html]:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<HTML>
<H1>FORM Authentication demo</H1>
@ -129,7 +129,7 @@ A LoginService is available to all web applications on a Server instance if you
Such a definition would go into an xml file in your `${jetty.base}/etc` directory, e.g. `${jetty.base}/etc/my-realm.xml` and you would add this xml file to the execution path via `start.ini` or `start.d` (you may want to review the material in the link:#startup[Starting Jetty] chapter).
Here's an example of an xml file that defines an in-memory type of LoginService called the link:{JDURL}/org/eclipse/jetty/security/HashLoginService.html[HashLoginService]:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
@ -151,7 +151,7 @@ If you define more than one `LoginService` on a Server, you will need to specify
You can do that by telling the context the name of the `LoginService`, or passing it the `LoginService` instance.
Here's an example of doing both of these, using a link:#deployable-descriptor-file[context xml file]:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -176,7 +176,7 @@ Here's an example of doing both of these, using a link:#deployable-descriptor-fi
Alternatively, you can define a `LoginService` for just a single web application.
Here's how to define the same HashLoginService, but inside a link:#deployable-descriptor-file[context xml file]:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -254,7 +254,7 @@ guest: guest,read-only
You configure the `HashLoginService` with a name and a reference to the location of the properties file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Item>
@ -268,7 +268,7 @@ You configure the `HashLoginService` with a name and a reference to the location
You can also configure it to reload the configuration file when changes to it are detected.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.security.HashLoginService">
@ -362,7 +362,7 @@ If you want to use obfuscated, MD5 hashed or encrypted passwords the `pwd` colum
You define a `JDBCLoginService` with the name of the realm and the location of the properties file describing the database:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.security.JDBCLoginService">
<Set name="name">Test JDBC Realm</Set>
@ -380,7 +380,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access granted to a set of named roles:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<security-constraint>
<web-resource-collection>
@ -396,7 +396,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access totally forbidden, regardless of role:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<security-constraint>
<web-resource-collection>
@ -410,7 +410,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access granted to a user in any of the roles defined in the effective `web.xml`.
This is indicated by the special value of `*` for the `<role-name>` of a `<auth-constraint>` in the `<security-constraint>`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<security-constraint>
<web-resource-collection>
@ -428,7 +428,7 @@ Servlet 3.1 introduced an additional authorization:
* Access granted to any user who is authenticated, regardless of roles.
This is indicated by the special value of `**` for the `<role-name>` of a `<auth-constraint>` in the `<security-constraint>`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<security-constraint>
<web-resource-collection>
@ -445,7 +445,7 @@ Additionally, when configuring your security constraints you can protect various
This is done by adding the method you want to protect as a `<http-method>` in the `<web-resource-collection>`.
You can then define roles that should be able to perform these protected methods in an `<auth-constraint>`:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<security-constraint>
<web-resource-collection>
@ -470,7 +470,7 @@ This is especially helpful if authorization needs change over time and need upda
To do this, we add a section for security constraints into the context xml file for our web app as part of the `securityHandler`.
In the example below, a `HashLoginService` is defined with authorization being granted too `foo/*` paths to users with the `admin` and `manager` roles.
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="testWebapp" class="org.eclipse.jetty.webapp.WebAppContext">
<Get name="securityHandler">
@ -512,7 +512,7 @@ If roles changed in the future, administrators could easily change this context
In addition to the distribution, security can be defined as part of an embedded implementation as well.
Below is an example which, like the one above, sets up a server with a `HashLoginService` and adds security constraints to restrict access based on roles.
[source, java, subs="{sub-order}"]
[source, java]
----
include::{SRCDIR}/examples/embedded/src/main/java/org/eclipse/jetty/embedded/SecuredHelloHandler.java[]
----

8
jetty-documentation/src/main/asciidoc/configuring/security/configuring-form-size.adoc
View File

@ -35,7 +35,7 @@ There exists 2 system properties that will adjust the default maximum form sizes
Used from command line as such:
[source,shell,subs="{sub-order}"]
[source,shell]
----
$ java -Dorg.eclipse.jetty.server.Request.maxFormKeys=200 -jar ...
@ -45,7 +45,7 @@ $ java -Dorg.eclipse.jetty.server.Request.maxFormContentSize=400000 -jar ...
Or via Java code (make sure you do this before you instantiate any `ContextHandler`, `ServletContextHandler`, or `WebAppContext`)
[source,java,subs="{sub-order}"]
[source,java]
----
System.setProperty(ContextHandler.MAX_FORM_KEYS_KEY, "200");
System.setProperty(ContextHandler.MAX_FORM_CONTENT_SIZE_KEY, "400000");
@ -56,7 +56,7 @@ System.setProperty(ContextHandler.MAX_FORM_CONTENT_SIZE_KEY, "400000");
To configure the form limits for a single web application, the context handler (or webappContext) instance must be configured using the following methods:
[source,java,subs="{sub-order}"]
[source,java]
----
ContextHandler.setMaxFormContentSize(int maxSizeInBytes);
ContextHandler.setMaxFormKeys(int formKeys);
@ -65,7 +65,7 @@ ContextHandler.setMaxFormKeys(int formKeys);
These methods may be called directly when embedding Jetty, but more commonly are configured from a context XML file or WEB-INF/jetty-web.xml file:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">

38
jetty-documentation/src/main/asciidoc/configuring/security/jaas-support.adoc
View File

@ -54,7 +54,7 @@ Let's look at an example.
Configure a Jetty `org.eclipse.jetty.jaas.JAASLoginService` to match the `<realm-name>` in your `web.xml` file. For example, if the `web.xml` contains a realm called "Test JAAS Realm" like so:
[source, xml, subs="{sub-order}"]
[source, xml]
----
<login-config>
<auth-method>FORM</auth-method>
@ -68,7 +68,7 @@ Configure a Jetty `org.eclipse.jetty.jaas.JAASLoginService` to match the `<realm
then you need to create a `JAASLoginService` with the matching realm name of "Test JAAS Realm":
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.jaas.JAASLoginService">
<Set name="Name">Test JAAS Realm</Set>
@ -77,17 +77,16 @@ then you need to create a `JAASLoginService` with the matching realm name of "Te
----
The `LoginModuleName` must match the name of your LoginModule as declared in your login module configuration file (see <<jaas-step-2,Step 2>>).
____
[CAUTION]
====
The name of the realm-name that you declare in `web.xml` must match *exactly* the `Name` field of your `JAASLoginService`.
____
====
You can declare your `JAASLoginService` in a couple of different ways:
1. If you have more than one webapp that you would like to use the same security infrastructure, then you can declare your `JAASLoginService` in a top-level Jetty xml file as a bean that is added to the `org.eclipse.jetty.server.Server`.
An example:
+
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure id="Server" class="org.eclipse.jetty.server.Server">
@ -104,7 +103,7 @@ An example:
----
2. Alternatively, you can use a `JAASLoginService` with just a specific webapp by creating a link:#deployable-descriptor-file[context xml] file for the webapp, and specifying the `JAASLoginService` in it:
+
[source, xml, subs="{sub-order}"]
[source, xml]
----
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -134,11 +133,10 @@ xyz {
};
----
____
[CAUTION]
====
It is imperative that the application name on the first line is *exactly* the same as the `LoginModuleName` of your `JAASLoginService`.
____
====
You may find it convenient to name this configuration file as `etc/login.conf` because, as we will see below, some of the wiring up for JAAS has been done for you.
===== Step 3
@ -151,17 +149,16 @@ There are 2 aspects to this:
To accomplish the above, use the Jetty link:#startup-overview[startup] link:#startup-modules[modules mechanism] to add the JAAS link:#startup-modules[module]:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
java -jar start.jar --add-to-start=jaas
....
----
____
[NOTE]
====
The top level of the distribution does not have the JAAS module enabled by default.
However, there are several link:#demo-webapps-base[demo webapps] - including a JAAS webapp - available in the `demo-base` directory of the distribution which has pre-enabled the JAAS module.
____
====
Now you will have a file named `start.d/jaas.ini`, which contains:
[source,ini]
@ -185,7 +182,7 @@ However, should you need to, you can configure:
Here's an example of setting each of these (to their default values):
[source, xml, subs="{sub-order}"]
[source, xml]
----
<New class="org.eclipse.jetty.jaas.JAASLoginService">
<Set name="Name">Test JAAS Realm</Set>
@ -220,13 +217,12 @@ As `LoginModules` are free to use their own implementation of the JAAS Principal
* link:{JDURL}/org/eclipse/jetty/jaas/spi/DataSourceLoginModule.html[`org.eclipse.jetty.jaas.spi.DataSourceLoginModule`]
* link:{JDURL}/org/eclipse/jetty/jaas/spi/LdapLoginModule.html[`org.eclipse.jetty.jaas.ldap.LdapLoginModule`]
____
[NOTE]
====
Passwords can be stored in clear text, obfuscated or checksummed.
The class link:{JDURL}/org/eclipse/jetty/util/security/Password.html[`org.eclipse.jetty.util.security.Password`] should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables.
See more on this under the Configuration section on link:#configuring-security-secure-passwords[securing passwords].
____
====
===== JDBCLoginModule
The `JDBCLoginModule` stores user passwords and roles in a database that are accessed via JDBC calls.
@ -376,7 +372,7 @@ This callback gives you access to all parameters that were passed in the form su
To use it, in the `login()` method of your custom login module, add the `RequestParameterCallback` to the list of callback handlers the login module uses, tell it which params you are interested in, and then get the value of the parameter back.
Here is an example:
[source, java, subs="{sub-order}"]
[source, java]
----
public class FooLoginModule extends AbstractLoginModule

111
jetty-documentation/src/main/asciidoc/configuring/security/jetty-home-and-jetty-base.adoc
View File

@ -53,16 +53,16 @@ It also assumes you are using `start.ini` to configure your server features.
1. Create a base directory anywhere.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[/home/user]$ mkdir my-base
[/home/user]$ cd my-base
....
----
2. Add the modules for SSL, HTTP, and webapp deployment.
Adding modules in this way will append the associated module properties to the `${jetty.base}/start.ini` file.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --add-to-start=http,https,deploy
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
@ -79,11 +79,11 @@ MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified
....
----
3. Look at your directory.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ ls -la
total 20
drwxrwxr-x 4 user group 4096 Oct 8 06:55 ./
@ -91,52 +91,52 @@ drwxr-xr-x 103 user group 4096 Oct 8 06:53 ../
drwxrwxr-x 2 user group 4096 Oct 8 06:55 etc/
-rw-rw-r-- 1 user group 815 Oct 8 06:55 start.ini
drwxrwxr-x 2 user group 4096 Oct 8 06:55 webapps/
....
----
4. Copy your WAR files into webapps.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ ls -la
[my-base]$ cp ~/code/project/target/gadget.war webapps/
....
----
5. Copy your keystore into place.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ cp ~/code/project/keystore etc/keystore
....
----
6. Edit the `start.ini` to configure your SSL settings.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ cat start.ini
....
----
7. Initialize module ssl.
+
....
----
--module=ssl
....
----
8. Define the port to use for secure redirection.
+
....
----
jetty.secure.port=8443
....
----
9. Set up a demonstration keystore and truststore.
+
....
----
jetty.keystore=etc/keystore
jetty.truststore=etc/keystore
....
----
10. Set the demonstration passwords.
+
....
----
jetty.keystore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
jetty.keymanager.password=OBF:1u2u1wml1z7s1z7a1wnl1u2g
jetty.truststore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
....
----
11. Initialize the module server.
+
....
----
--module=server
threads.min=10
threads.max=200
@ -144,24 +144,24 @@ threads.timeout=60000
#jetty.host=myhost.com
jetty.dump.start=false
jetty.dump.stop=false
....
----
12. Initialize module http.
+
....
----
--module=http
jetty.http.port=8080
http.timeout=30000
....
----
13. Initialize module deploy.
+
....
----
--module=deploy
....
----
Look at the configuration you have at this point.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-config
Java Environment:
@ -229,17 +229,17 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-http.xml
${jetty.home}/etc/jetty-ssl.xml
${jetty.home}/etc/jetty-deploy.xml
....
----
Now start Jetty.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
2013-10-08 07:06:55.837:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-08 07:06:55.853:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
2013-10-08 07:06:55.872:INFO:oejs.ServerConnector:main: Started ServerConnector@72974691{HTTP/1.1}{0.0.0.0:8080}
....
----
[[reviewing-ssl-config]]
==== Reviewing the Configuration
@ -261,8 +261,8 @@ Notice that you have `--module=<name>` here and there; you have wrapped up the g
You can see the list of modules:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-modules
Jetty All Available Modules:
@ -440,7 +440,7 @@ Jetty Active Module Tree:
+ Module: ssl [enabled]
+ Module: webapp [transitive]
+ Module: deploy [enabled]
....
----
These are the modules by name, the libraries they bring in, the XML configurations they use, the other modules they depend on (even optional ones), and if the module is in use, where it was enabled.
@ -448,18 +448,17 @@ While you can manage the list of active modules yourself, it is much easier to e
If you want to start using a new module:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --add-to-start=https
....
----
This adds the `--module=` lines and associated properties (the parameterized values mentioned above), to your `start.ini`.
____
[IMPORTANT]
====
Do not edit the modules and XML files in the `${jetty.home}` directory; there is no need to be moving or copying them unless you want to make your own modules or override the behavior of an existing module.
____
====
Notice that your `${jetty.base}/start.ini` has no references to the XML files.
That's because the module system and its graph of dependencies now dictate all of the XML files, and their load order.
@ -482,10 +481,10 @@ For more information on the `start.jar` in 9.1, see xref:start-jar[].
1. Download and unpack Jetty into `/home/user/jetty-distribution-{VERSION}`.
2. Go to your base directory and just use the distribution, no editing.
+
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar
....
----
* The Jetty distribution provides, out of the box, the XML configuration files, in this case `jetty-http.xml` and `jetty-ssl.xml`.
These can be found in the `${jetty.home}/etc/` directory.
* We have parameterized all of the configurable values in those XMLs.
@ -506,10 +505,10 @@ By default, the module system keeps things sane, and transitively includes all d
You can see what the configuration looks like, after all of the modules are resolved, without starting Jetty via:
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base] $ java -jar ../jetty-distribution-{VERSION}/start.jar --list-config
....
----
Just because the JARs exist on disk does not mean that they are in use.
The configuration controls what is used.
@ -518,7 +517,7 @@ Use the `--list-config` to see the configuration.
Notice that only a subset of the JARs from the distribution are in use.
The modules you have enabled determine that subset.
[source, screen, subs="{sub-order}"]
....
[source, screen]
----
[my-base]$ java -jar ~/jetty-distribution-{VERSION}/start.jar --list-config
....
----

Some files were not shown because too many files have changed in this diff Show More