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"?> <?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"> <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> <parent>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-project</artifactId> <artifactId>jetty-project</artifactId>
<version>9.4.35-SNAPSHOT</version> <version>9.4.35-SNAPSHOT</version>
</parent> </parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>jetty-documentation</artifactId> <artifactId>jetty-documentation</artifactId>
<name>Jetty :: Documentation</name> <name>Jetty :: Documentation</name>
<packaging>pom</packaging> <packaging>pom</packaging>
<properties>
<html.directory>${project.build.directory}/current</html.directory>
<javadoc.version>${project.version}</javadoc.version>
</properties>
<build> <build>
<plugins> <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> <plugin>
<groupId>org.asciidoctor</groupId> <groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <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>
<plugin> <plugin>
<artifactId>maven-assembly-plugin</artifactId> <artifactId>maven-assembly-plugin</artifactId>
@ -160,85 +36,4 @@
</plugin> </plugin>
</plugins> </plugins>
</build> </build>
<profiles> </project>
<!--
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>

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: 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> ... 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`. 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] [IMPORTANT]
====
Be certain to get the Be certain to get the
link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE]. link:#alpn-versions[ALPN boot artifact version that matches the version of your JRE].
____ ====
[[alpn-openjdk8-agent]] [[alpn-openjdk8-agent]]
==== ALPN agent and OpenJDK 8 ==== 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: 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> ... java -javaagent:<path_to_alpn_agent_jar> ...
---- ----
____
[NOTE] [NOTE]
====
The Jetty ALPN agent works with any Java 8 version. It is _required_ if you use 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 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`. 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 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 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. when you use OpenJDK `1.8.0_252` or later.
____ ====
[[alpn-conscrypt]] [[alpn-conscrypt]]
==== ALPN and 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. You can download the https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-alpn/[jetty-osgi-alpn jar] from Maven Central.
____
[NOTE] [NOTE]
====
OSGi *requires* a `ServiceLoader` implementation for Jetty to function properly. 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. 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.] You can read more about OSGi and `ServiceLoader` http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html[here.]
____ ====
[[alpn-troubleshooting]] [[alpn-troubleshooting]]
==== 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: 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 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]] [[alpn-openjdk8-client-example]]
==== Client Example ==== Client Example
[source, java, subs="{sub-order}"] [source, java]
---- ----
SSLContext sslContext = ...; SSLContext sslContext = ...;
SSLSocket sslSocket = (SSLSocket)context.getSocketFactory().createSocket("localhost", server.getLocalPort()); 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. 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 = ...; SSLEngine sslEngine = ...;
ALPN.put(sslEngine, new ALPN.ServerProvider() 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. 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: 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> <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: You can enable debug logging for the ALPN implementation in this way:
.... ----
ALPN.debug = true; 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`. 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: 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 $ hg clone https://hg.openjdk.java.net/jdk8u/jdk8u jdk8u
$ cd !$ $ cd !$
$ ./get_source.sh $ ./get_source.sh
.... ----
To update the source to a specific tag, use the following command: 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> $ ./make/scripts/hgforest.sh update <tag-name>
.... ----
The list of OpenJDK tags can be obtained from this page: The list of OpenJDK tags can be obtained from this page:
https://hg.openjdk.java.net/jdk8u/jdk8u/tags[OpenJDK 8 Tags]. 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`.] 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). 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[] 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 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]: 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-plus.jar
jetty-annotations.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.] 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: The code is as follows:
[source, java, subs="{sub-order}"] [source, java]
---- ----
import org.eclipse.jetty.security.HashLoginService; import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server; 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: 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.DeclareRoles;
import javax.annotation.security.RunAs; 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. 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] [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. 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. 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. Upgrading the `web.xml` version is preferable.
____ ====
===== Controlling the order of ServletContainerInitializer invocation ===== 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`. 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]): 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(); WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder", 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. 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]: 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(); WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern", 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: A typical configuration could be:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<web-app> <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 ==== Embedded usage
[source, java, subs="{sub-order}"] [source, java]
---- ----
Server server = new Server(8080); Server server = new Server(8080);
RolloverFileOutputStream outputStream = new RolloverFileOutputStream("MeinLogPfad/yyyy_mm_dd.request.log", true,10); 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. 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. 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] [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. 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); Server server = new Server(8080);
HandlerList handlers = new HandlerList(); 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. 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: This example allow 30 requests at a time:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<filter> <filter>
<filter-name>DoSFilter</filter-name> <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. 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. It may also be added to individual contexts in a context xml file.
____
[NOTE] [NOTE]
====
Jetty 9 only compresses using GZip. Jetty 9 only compresses using GZip.
Using deflate HTTP compression is not supported and will not function. Using deflate HTTP compression is not supported and will not function.
____ ====
[[gzip-filter-rules]] [[gzip-filter-rules]]
==== Gzip 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`. 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. 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] [NOTE]
====
Automatic precompression by the `DefaultServlet` can be configured. Automatic precompression by the `DefaultServlet` can be configured.
Read more about the `DefaultServlet` link:#default-servlet[here.] Read more about the `DefaultServlet` link:#default-servlet[here.]
____ ====
[[gzip-filter-init]] [[gzip-filter-init]]
==== Gzip Configuration ==== 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. * Set the Expires header to approximately one year in the future.
* Add a Date header with the current system time. * Add a Date header with the current system time.
____
[NOTE] [NOTE]
====
Each action must be separated by a comma. Each action must be separated by a comma.
____ ====
[source, xml]
[source, xml, subs="{sub-order}"]
---- ----
<filter> <filter>
<filter-name>HeaderFilter</filter-name> <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. Below is an example.
This is a permanent redirection, which also preserves `pathinfo` and query strings on the redirect: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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: This example processes fifty requests at a time:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<filter> <filter>
<filter-name>QoSFilter</filter-name> <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. 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: 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-mapping>
<filter-name>QoSFilter</filter-name> <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. You can then use this subclass as your QoS filter.
Here's an example: Here's an example:
[source, java, subs="{sub-order}"] [source, java]
---- ----
public class ParsePriorityQoSFilter extends QoSFilter 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. This handler will serve static content and handle If-Modified-Since headers and is suitable for simple serving of static content.
____
[IMPORTANT] [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[]. 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] [NOTE]
====
Requests for resources that do not exist are let pass (Eg no 404's). Requests for resources that do not exist are let pass (Eg no 404's).
____ ====
==== Improving the Look and Feel ==== 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. 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. 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. 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[] 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: 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 $ java -jar start.jar --add-to-start=rewrite
.... ----
_____
[NOTE] [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/ 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 ==== Usage
The rewrite module enables the following Jetty xml config file on the execution path: 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[] 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: 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[] 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: 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(); 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. 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. 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); Server server = new Server(8080);
HandlerList handlers = new HandlerList(); 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. 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) { public static void attemptShutdown(int port, String shutdownCookie) {
try { 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` 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. 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 $ java -jar {$jetty.home}/start.jar --add-to-start=stats
.... ----
In addition to these, the `SessionHandler` and `DefaultSessionCache` classes collect statistics for sessions. 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. These statistics are enabled by default and are accessible via JMX interface.
_____
[NOTE] [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. 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]]
==== 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. 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: 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"> <Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="insertHandler"> <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. 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"> <Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBeanToAllConnectors"> <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. 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. 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"> <Configure id="Server" class="org.eclipse.jetty.server.Server">
<Call name="addBeanToAllConnectors"> <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`: 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 $ mkdir -p /usr/jetty/wordpress
$ cd /usr/jetty/wordpress $ cd /usr/jetty/wordpress
$ java -jar $JETTY_HOME/start.jar --add-to-start=fcgi,http,deploy $ java -jar $JETTY_HOME/start.jar --add-to-start=fcgi,http,deploy
.... ----
Therefore `$JETTY_BASE=/usr/jetty/wordpress`. 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. 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`: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: 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 $ cd $JETTY_BASE
$ java -jar /opt/jetty/start.jar $ java -jar /opt/jetty/start.jar
.... ----
[[configuring-fastcgi-http2]] [[configuring-fastcgi-http2]]
==== Configuring Jetty to Proxy HTTP/2 to FastCGI ==== 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: 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 $ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2 $ 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. 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. 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: 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 $ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar $ 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. 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: 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 $ 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. 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] [NOTE]
====
HAProxy supports ALPN only if built with OpenSSL 1.0.2 or greater. 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. Use `haproxy -vv` to know with which OpenSSL version HAProxy has been built.
____ ====
[[http2-haproxy-ssl]] [[http2-haproxy-ssl]]
==== Setup SSL for HAProxy ==== 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: 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 $ keytool -genkeypair -keyalg RSA -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -ext SAN=DNS:domain.com
What is your first and last name? What is your first and last name?
[Unknown]: *.domain.com [Unknown]: *.domain.com
@ -79,31 +78,31 @@ What is the two-letter country code for this unit?
[Unknown]: IT [Unknown]: IT
Is CN=*.domain.com, OU=Unit, O=Domain, L=Torino, ST=TO, C=IT correct? Is CN=*.domain.com, OU=Unit, O=Domain, L=Torino, ST=TO, C=IT correct?
[no]: yes [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. 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. We need to extract the certificate and the private key in PEM format.
To extract the certificate into `certificate.pem`: 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 $ keytool -exportcert -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -rfc -file certificate.pem
.... ----
To export the private key into `private_key.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 $ 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: 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 $ cat certificate.pem private_key.pem > domain.pem
.... ----
The `domain.pem` file will be used later by HAProxy. 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. Now we can setup `haproxy.cfg` to configure HAProxy.
This is a minimal configuration: This is a minimal configuration:
[source, ,subs="{sub-order}"] [source]
.... ----
global global
tune.ssl.default-dh-param 1024 tune.ssl.default-dh-param 1024
@ -137,7 +136,7 @@ default_backend be_http
backend be_http backend be_http
mode tcp mode tcp
server domain 127.0.0.1:8282 server domain 127.0.0.1:8282
.... ----
The HAProxy configuration file works in the following way. The HAProxy configuration file works in the following way.
The `fe_http` front-end accepts connections on port 80 and redirects them to use the `https` scheme. The `fe_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: 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 $ JETTY_BASE=haproxy-jetty-http2
$ mkdir $JETTY_BASE $ mkdir $JETTY_BASE
$ cd $JETTY_BASE $ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c,deploy $ java -jar $JETTY_HOME/start.jar --add-to-start=http2c,deploy
.... ----
Now let's deploy a demo web application and start Jetty: Now let's deploy a demo web application and start Jetty:
[source,screen, subs="{sub-order}"] [source,screen]
.... ----
$ cd $JETTY_BASE $ cd $JETTY_BASE
$ cp $JETTY_HOME/demo-base/webapps/async-rest.war $JETTY_BASE/webapps/ $ 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 $ 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). 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] [NOTE]
====
You want the Jetty connector that listens on port 8282 to be available only to HAProxy, and not to remote clients. 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. 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. 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. 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. 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. 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: 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 $ java -jar $JETTY_HOME/start.jar --list-modules
... ...
1) alpn-impl <transitive> 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-http2.xml
${jetty.home}/etc/jetty-https.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`. 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`. 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] [NOTE]
====
If you are planning to edit XML files, make sure to copy them to your `{$jetty.base}/etc/` directory before doing so. 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. 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. 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: 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: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<web-app <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. 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: 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 $ JETTY_BASE=http2-demo
$ mkdir $JETTY_BASE $ mkdir $JETTY_BASE
$ cd $JETTY_BASE $ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,https,deploy $ 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). 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. 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: 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 $ 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. 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. 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: 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 $ 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: HTTP/2 can be enabled on the plain text connector and the server restarted with the following command:
[source,screen] [source,screen]
.... ----
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c $ java -jar $JETTY_HOME/start.jar --add-to-start=http2c
$ java -jar $JETTY_HOME/start.jar $ 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.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} 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. 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)]. A server deployed over TLS (SSL) normally advertises the HTTP/2 protocol via the TLS extension Application Layer Protocol Negotiation link:#alpn[(ALPN)].
____
[NOTE] [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. 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. 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]] [[http2-security-update]]
==== Jetty HTTP/2 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}`. 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 [mybase]$ java /opt/jetty-dist/start.jar --add-to-start=jmx-remote, jmx
INFO: jmx-remote initialised in ${jetty.base}/start.ini INFO: jmx-remote initialised in ${jetty.base}/start.ini
INFO: jmx 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: 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 # 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 ## Enable for an open port accessible by remote machines
jetty.jmxrmihost=localhost jetty.jmxrmihost=localhost
jetty.jmxrmiport=1099 jetty.jmxrmiport=1099
.... ----
[[jetty-jconsole-monitoring]] [[jetty-jconsole-monitoring]]
==== Monitoring Jetty with JConsole ==== 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. 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: It should look something like so:
image:images/jconsole1.jpg[image,width=576] image:administration/jmx/images/jconsole1.jpg[image,width=576]
____
[IMPORTANT] [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. 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. This forces JConsole to refresh the list, and recognize your newly-started Jetty process.
____ ====
Select the start.jar entry and click the "Connect" button. Select the start.jar entry and click the "Connect" button.
A new JConsole window opens: 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. 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. 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. 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. 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]] [[jetty-jmc-monitoring]]
==== Monitoring Jetty with JMC ==== 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. 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: It should look something like so:
image:images/jmc1.png[image,width=576] image:administration/jmx/images/jmc1.png[image,width=576]
____
[IMPORTANT] [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. 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. 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". 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: 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. 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. 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. 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. 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. The following is an example of each of the annotations mentioned above in practice.
[source, java, subs="{sub-order}"] [source, java]
---- ----
package com.acme; 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. 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]): 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} $ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx $ 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: 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> <plugin>
<groupid>org.eclipse.jetty</groupid> <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 configuration for the RMI registry and the RMI server is specified by a `JMXServiceURL`.
The string format of an RMI `JMXServiceURL` is: 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 service:jmx:rmi://<rmi_server_host>:<rmi_server_port>/jndi/rmi://<rmi_registry_host>:<rmi_registry_port>/jmxrmi
---- ----
Default values are: Default values are:
[source, screen, subs="{sub-order}"] [source, screen]
---- ----
rmi_server_host = localhost rmi_server_host = localhost
rmi_server_port = 1099 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: Examples:
[source, screen, subs="{sub-order}"] [source, screen]
---- ----
service:jmx:rmi:///jndi/rmi:///jmxrmi service:jmx:rmi:///jndi/rmi:///jmxrmi
rmi_server_host = local host address 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: 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} $ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx-remote $ 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`: When running Jetty embedded into an application, create and configure a `ConnectorServer`:
[source, java, subs="{sub-order}"] [source, java]
---- ----
Server server = new Server(); 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: 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"> <New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
<Arg> <Arg>
@ -251,7 +251,7 @@ To authorize access to the `JMXConnectorServer` you can use this configuration,
Similarly, in code: Similarly, in code:
[source, java, subs="{sub-order}"] [source, java]
---- ----
JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi:///jmxrmi"); JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi:///jmxrmi");
Map<String, Object> env = new HashMap<>(); 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: 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"> <New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer">
<Arg> <Arg>
@ -288,7 +288,7 @@ It is possible to configure the `ConnectorServer` with a `SslContextFactory` so
Similarly, in code: Similarly, in code:
[source, java, subs="{sub-order}"] [source, java]
---- ----
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server(); SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setKeyStorePath("/path/to/keystore"); 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`: 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 properties necessary for an RMI client to trust a self-signed certificate.
System.setProperty("javax.net.ssl.trustStore", "/path/to/trustStore"); System.setProperty("javax.net.ssl.trustStore", "/path/to/trustStore");
@ -331,7 +331,7 @@ try (JMXConnector client = JMXConnectorFactory.connect(jmxURL, clientEnv))
Similarly, to launch JMC: 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 $ 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: 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> $ 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. 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`. 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"> <New class="org.eclipse.jetty.plus.jndi.EnvEntry">
<Arg></Arg> <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: 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; 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`. 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__: 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"> <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="myds" class="org.eclipse.jetty.plus.jndi.Resource"> <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: Here's an example `web.xml` declaration for the datasource above:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<resource-ref> <resource-ref>
<res-ref-name>jdbc/myds</res-ref-name> <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.`: To look up your DataSource in your `servlet/filter/etc.`:
[source, java, subs="{sub-order}"] [source, java]
---- ----
import javax.naming.InitialContext; import javax.naming.InitialContext;
import javax.sql.DataSource; import javax.sql.DataSource;
@ -152,12 +152,11 @@ public class MyClass {
} }
---- ----
____
[NOTE] [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`. 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 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[]. For more examples of datasource configurations, see xref:jndi-datasource-examples[].
[[configuring-jms-queues-topics-connectionfactories]] [[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. 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: 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"> <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"> <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: The entry in `web.xml` would be:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<resource-ref> <resource-ref>
<res-ref-name>jms/connectionFactory</res-ref-name> <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: 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"> <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="mail" class="org.eclipse.jetty.plus.jndi.Resource"> <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. 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. 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] [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. 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. 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]]
==== 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. 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: 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"> <New id="tx" class="org.eclipse.jetty.plus.jndi.Transaction">
<Arg> <Arg>
@ -257,7 +255,7 @@ For example:
In a context xml file: In a context xml file:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"> <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="myds" class="org.eclipse.jetty.plus.jndi.Resource"> <New id="myds" class="org.eclipse.jetty.plus.jndi.Resource">
@ -275,7 +273,7 @@ In a context xml file:
In a `web.xml` file: In a `web.xml` file:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<resource-ref> <resource-ref>
<res-ref-name>jdbc/mydatasource</res-ref-name> <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`: In a context xml file declare `jdbc/mydatasource`:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"> <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="myds" class="org.eclipse.jetty.plus.jndi.Resource"> <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 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`: `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"> <New id="map1" class="org.eclipse.jetty.plus.jndi.Link">
<Arg><Ref refid='wac'/></Arg> <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: Now you can refer to `jdbc/mydatasource1` in the `web.xml` like this:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<resource-ref> <resource-ref>
<res-ref-name>jdbc/mydatasource1</res-ref-name> <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. Here are examples of configuring a JNDI datasource for various databases.
____
[NOTE] [NOTE]
====
Read xref:configuring-datasources[] in xref:jndi-configuration[] for more information about configuring datasources. 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`. All of these examples correspond to a `resource-ref` in `web.xml`.
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<resource-ref> <resource-ref>
<description>My DataSource Reference</description> <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. 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. See the section xref:jndi-where-to-declare[] for more information.
____
[IMPORTANT] [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`. 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]]
==== 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]. 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]. 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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <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]. 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]. 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"> <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]. 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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <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]. 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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <Arg></Arg>
@ -171,7 +169,7 @@ Connection pooling, available at https://repo1.maven.org/maven2/commons-dbcp/com
Connection pooling + XA transactions. Connection pooling + XA transactions.
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <Arg></Arg>
@ -206,7 +204,7 @@ Connection pooling + XA transactions.
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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <Arg></Arg>
@ -226,7 +224,7 @@ Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
@ -252,7 +250,7 @@ Implements `javax.sql.ConnectionPoolDataSource`.
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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <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`. 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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <Arg></Arg>
@ -310,7 +308,7 @@ Implements `javax.sql.DataSource` and `javax.sql.ConnectionPoolDataSource`.
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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <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`. Implements `javax.sql.DataSource`.
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <Arg></Arg>
@ -365,7 +363,7 @@ Implements `javax.sql.DataSource`.
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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <Arg></Arg>
@ -387,7 +385,7 @@ Implements `javax.sql.DataSource`.
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"> <New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource">
<Arg></Arg> <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: 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-jndi.jar
jetty-plus.jar jetty-plus.jar
.... ----
If you are using transactions, you will also need the `javax.transaction` api. 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.] 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. 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: 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 java.util.Properties;
import org.eclipse.jetty.server.Server; 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. 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: 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 /opt/jetty
cd my-base cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=plus java -jar $JETTY_HOME/start.jar --add-to-start=plus
.... ----
You can now start Jetty and use JNDI within your webapps. 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. 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. 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: 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 /opt/jetty
cd my-base cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=ext 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. 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: Specifically, you can configure support for the following `web.xml` elements:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<env-entry/> <env-entry/>
<resource-ref/> <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: 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"> <New class="org.eclipse.jetty.plus.jndi.xxxx">
<Arg><!-- scope --></Arg> <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. You represent this scope by a `null` first parameter to the resource declaration.
For example: For example:
+ +
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"> <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. You represent this scope by referencing the Server instance as the first parameter to the resource declaration.
For example: For example:
+ +
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure id="Server" class="org.eclipse.jetty.Server"> <Configure id="Server" class="org.eclipse.jetty.Server">
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"> <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. You represent this scope by referencing the `WebAppContext` instance as the first parameter to the resource declaration.
For example: For example:
+ +
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"> <Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext">
<New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"> <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:: IGNORE::
Exception events that you can safely ignore, but useful for some people. 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. You might see this level as DEBUG under some Java logging framework configurations, where it retains the _ignore_ phrase somewhere in the logging.
____
[NOTE] [NOTE]
====
Jetty logging produces no FATAL or SEVERE events. Jetty logging produces no FATAL or SEVERE events.
____ ====
[[selecting-log-framework]] [[selecting-log-framework]]
==== Selecting the 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 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 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`. * If no logger implementation is specified, default to `org.eclipse.jetty.util.log.StdErrLog`.
____
[NOTE] [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]. 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]. 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]] [[configuring-jetty-stderrlog]]
==== The jetty-logging.properties file ==== 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. A standard request log entry includes the client IP address, date, method, URL, result, size, referrer, user agent and latency.
For example: For example:
.... ----
123.4.5.6 - - [20/Jul/2016:10:16:17 +0000] 123.4.5.6 - - [20/Jul/2016:10:16:17 +0000]
"GET /jetty/tut/XmlConfiguration.html HTTP/1.1" "GET /jetty/tut/XmlConfiguration.html HTTP/1.1"
200 76793 "http://localhost:8080/jetty/tut/logging.html" 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 "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8" 342
.... ----
[[implementing-request-log]] [[implementing-request-log]]
==== Implementing a 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: 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 $ 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]. The above command will add a new `requestlog.ini` file to your link:#start-vs-startd[`{$jetty.base}/start.d` directory].
____
[NOTE] [NOTE]
====
By default, request logs are not set to be appended, meaning a the log file is wiped clean upon sever restart. 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`. 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: 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"); NCSARequestLog requestLog = new NCSARequestLog("/var/logs/jetty/jetty-yyyy_mm_dd.request.log");
requestLog.setAppend(true); 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. 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"> <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: 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled INFO : resources transitively enabled
MKDIR : ${jetty.base}/resources MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/logging-jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties COPY : ${jetty.home}/modules/logging-jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified INFO : Base directory was modified
.... ----
As noted above, Jetty supports a wide array of logging technologies. 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. 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. 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. 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-slf4j
ALERT: There are enabled module(s) with licenses. 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] Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
java -jar $JETTY_HOME/start.jar --help # for more information 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. 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. 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. 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 [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 : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
INFO : resources transitively enabled INFO : resources transitively enabled
@ -153,7 +153,7 @@ INFO : Base directory was modified
└── start.d └── start.d
├── logging-slf4j.ini ├── logging-slf4j.ini
└── slf4j-simple-impl.ini └── slf4j-simple-impl.ini
.... ----
Jetty is now configured to log using the SLF4J framework. Jetty is now configured to log using the SLF4J framework.
A standard SLF4J properties file is located in `${jetty.base}/resources/simplelogger.properties`. 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]. 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. 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-log4j
ALERT: There are enabled module(s) with licenses. ALERT: There are enabled module(s) with licenses.
@ -227,15 +227,15 @@ INFO : Base directory was modified
│   └── log4j.xml │   └── log4j.xml
└── start.d └── start.d
└── logging-log4j.ini └── logging-log4j.ini
.... ----
Jetty is now configured to log using the Log4j framework. Jetty is now configured to log using the Log4j framework.
A standard Log4j configuration file is located in `${jetty.base}/resources/log4j.xml`. A standard Log4j configuration file is located in `${jetty.base}/resources/log4j.xml`.
Or, to set up Log4j2, enable the `logging-log4j2` module. 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-log4j2
ALERT: There are enabled module(s) with licenses. ALERT: There are enabled module(s) with licenses.
@ -299,7 +299,7 @@ INFO : Base directory was modified
│   └── log4j2.xml │   └── log4j2.xml
└── start.d └── start.d
└── logging-log4j2.ini └── 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`. 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. 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-logback
ALERT: There are enabled module(s) with licenses. ALERT: There are enabled module(s) with licenses.
@ -382,7 +382,7 @@ INFO : Base directory was modified
│   └── logback.xml │   └── logback.xml
└── start.d └── start.d
└── logging-logback.ini └── 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`. 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. 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-jul
ALERT: There are enabled module(s) with licenses. ALERT: There are enabled module(s) with licenses.
@ -448,7 +448,7 @@ INFO : Base directory was modified
│   └── slf4j-jdk14-1.7.21.jar │   └── slf4j-jdk14-1.7.21.jar
└── start.d └── start.d
└── logging-jul.ini └── logging-jul.ini
.... ----
Jetty is now configured to log using the JUL framework. 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`. 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}`. 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. 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 [my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs MKDIR : ${jetty.base}/logs
@ -471,24 +471,24 @@ INFO : Base directory was modified
├── logs ├── logs
└── start.d └── start.d
└── console-capture.ini └── console-capture.ini
.... ----
As an example, here is the output from Logback before using the `console-capture` module: 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 [my-base]$ java -jar ../start.jar
419 [main] INFO org.eclipse.jetty.util.log - Logging initialized @508ms to org.eclipse.jetty.util.log.Slf4jLog 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 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 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 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: 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 [my-base]$ java -jar ../start.jar
151 [main] INFO org.eclipse.jetty.util.log - Logging initialized @238ms to org.eclipse.jetty.util.log.Slf4jLog 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 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: 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 [my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs MKDIR : ${jetty.base}/logs
@ -43,23 +43,21 @@ INFO : Base directory was modified
├── logs ├── logs
└── start.d └── start.d
└── console-capture.ini └── 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. 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] [NOTE]
====
By default, logs are not set to be appended, meaning a the log file is wiped clean upon sever restart. 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`. 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. 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. 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. 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 [my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled INFO : resources transitively enabled
@ -75,14 +73,14 @@ INFO : Base directory was modified
└── start.d └── start.d
├── console-capture.ini ├── console-capture.ini
└── logging-jetty.ini └── logging-jetty.ini
.... ----
Once activated, you can find the properties file at `${jetty.base}/resources/jetty-logging.properties`. Once activated, you can find the properties file at `${jetty.base}/resources/jetty-logging.properties`.
By default, the following parameters are defined. By default, the following parameters are defined.
To change them, un-comment the line and substitute your naming scheme and configuration choices. 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 ## Force jetty logging implementation
#org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog #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? ## Show the source file of a log location?
#com.example.SOURCE=false #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`. 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: * 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.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.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.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 2016-10-21 15:31:01.400:INFO:oejs.Server:main: Started @485ms
.... ----
+ +
* Example when set to true: * 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.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.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.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 2016-10-21 15:31:35.175:INFO:org.eclipse.jetty.server.Server:main: Started @495ms
.... ----
[[deprecated-parameters]] [[deprecated-parameters]]
==== 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. 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]$ mkdir modules
[mybase]$ cd modules [mybase]$ cd modules
@ -46,7 +46,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar [mybase]$ java -jar /opt/jetty-dist/start.jar
.... ----
The replacement `logging.mod` performs a number of tasks. 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 This example demonstrates how to configuring Jetty for logging to
`java.util.logging` via Jetty's own JavaUtilLog implementation. `java.util.logging` via Jetty's own JavaUtilLog implementation.
____
[IMPORTANT] [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. 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. 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`. 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]$ mkdir modules
[mybase]$ cd modules [mybase]$ cd modules
@ -54,7 +53,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/${jetty.base} INFO: resources enabled in ${jetty.base}/${jetty.base}
[mybase]$ java -jar /opt/jetty-dist/start.jar [mybase]$ java -jar /opt/jetty-dist/start.jar
.... ----
The replacement `logging.mod` performs a number of tasks. 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. 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] [NOTE]
====
`java.util.logging` is configured via the `${jetty.base}/resources/logging.properties` file during a valid startup of Jetty. `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. 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. * 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]. 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`. 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]$ mkdir modules
[mybase]$ cd modules [mybase]$ cd modules
@ -48,7 +48,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar [mybase]$ java -jar /opt/jetty-dist/start.jar
.... ----
The replacement `logging.mod` performs a number of tasks. 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. 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] [NOTE]
====
`java.util.logging` is configured via the `${jetty.base}/resources/logging.properties` file during a valid startup of Jetty. `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. 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. * 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]. 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. The example below shows how to accomplish this with Jetty and Slf4j, using `Logback` to manage the final writing of logs to disk.
____
[IMPORTANT] [IMPORTANT]
====
This mechanism forces all webapps to use the server's configuration for logging, something that isn't 100% appropriate for all webapps. 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). 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. 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 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. 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 [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 % Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed 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 INFO : Base directory was modified
$ $
.... ----
This replacement `centralized-webapp-logging.mod` performs a number of tasks. 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. This can be done with SLF4J + Logback + Jetty Webapp Logging in the mix.
Find example projects for this feature at github: Find example projects for this feature at github:
.... ----
https://github.com/jetty-project/jetty-and-logback-example https://github.com/jetty-project/jetty-and-logback-example
.... ----
.GitHub Example Project .GitHub Example Project
[cols=",",options="header",] [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. 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]$ mkdir modules
[mybase]$ cd 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 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 [mybase]$ java -jar /opt/jetty-dist/start.jar
.... ----
The replacement `logging.mod` performs a number of tasks. 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. 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. This decision guides the rest of the choices about jar files to place on the server classpath.
____
[CAUTION] [CAUTION]
====
There MUST NOT be multiple underlying logging frameworks on the classpath. There MUST NOT be multiple underlying logging frameworks on the classpath.
If there are, the Slf4j framework fails to load. If there are, the Slf4j framework fails to load.
____ ====
____
[NOTE] [NOTE]
====
Some third party libraries provide their own implementations of common logging APIs; be careful not to accidentally include an underlying logging framework. 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. 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. 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 .Slf4j Logging Grid
[width="100%",cols="25%,25%,25%,25%",options="header",] [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. 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]$ mkdir modules
[mybase]$ cd modules [mybase]$ cd modules
@ -115,7 +113,7 @@ INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar [mybase]$ java -jar /opt/jetty-dist/start.jar
.... ----
The replacement `logging.mod` performs a number of tasks. 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: This is a dump of the OneServletContext embedded example with extra threadpool information:
.... ----
Server@59906517{STARTED}[9.4.32-SNAPSHOT] - STARTED 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 += 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 | += 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$AppClassLoader@2c13da15
+> jdk.internal.loader.ClassLoaders$PlatformClassLoader@7364985f +> jdk.internal.loader.ClassLoaders$PlatformClassLoader@7364985f
key: +- bean, += managed, +~ unmanaged, +? auto, +: iterable, +] array, +@ map, +> undefined 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-admin-guide]]
= Jetty Administration Guide == Jetty Administration Guide
include::startup/chapter.adoc[] include::startup/chapter.adoc[]
include::sessions/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. 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: Starting it is as simple as performing the following:
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
> java -jar jetty-runner.jar simple.war > java -jar jetty-runner.jar simple.war
.... ----
This will start Jetty on port 8080, and deploy the webapp to `/`. 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: 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 > 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: 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 > java -jar jetty-runner.jar simple-context.xml
.... ----
____
[NOTE] [NOTE]
====
When using a context xml file, the application being deployed is not even required to be a fully-fledged webapp. 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]. 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. 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. 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: 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. 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): 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 > 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. 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: 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 > java -jar jetty-runner.jar my-first-context.xml my-second-context.xml my-third-context.xml
.... ----
____
[NOTE] [NOTE]
====
Switched used on the command line override configuration file settings. 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. 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 ===== Changing the Default Port
By default the `jetty-runner` will listen on port 8080. By default the `jetty-runner` will listen on port 8080.
You can easily change this on the command line using the `--port` command. 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: 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 > java -jar jetty-runner.jar --port 9090 simple.war
.... ----
===== Using jetty.xml Files ===== 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. 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: 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 > java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war
.... ----
[[runner-configuration-reference]] [[runner-configuration-reference]]
==== Full Configuration Reference ==== Full Configuration Reference
You can see the fill set of configuration options using the `--help` switch: 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 > java -jar jetty-runner.jar --help
.... ----
Here's what the output will look like: 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 ...] 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 ===== Printing the Version
Print out the version of Jetty and then exit immediately. Print out the version of Jetty and then exit immediately.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
> java -jar jetty-runner.jar --version > java -jar jetty-runner.jar --version
.... ----
===== Configuring a Request Log ===== Configuring a Request Log
Cause Jetty to write a request log with the given name. 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. 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. 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 > java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log my.war
.... ----
===== Configuring the Output Log ===== Configuring the Output Log
Redirect the output of jetty logging to the named file. 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. 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 > java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war
.... ----
===== Configuring the Interface for HTTP ===== Configuring the Interface for HTTP
Like Jetty standalone, the default is for the connectors to listen on all interfaces on a machine. 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: 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 > java -jar jetty-runner.jar --host 192.168.22.19 my.war
.... ----
===== Configuring the Port for HTTP ===== Configuring the Port for HTTP
The default port number is 8080. The default port number is 8080.
To link:#how-to-configure-connectors[configure a https connector], use a Jetty xml config file instead. 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 > java -jar jetty-runner.jar --port 9090 my.war
.... ----
===== Configuring Stop ===== 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. 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. 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`: 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 > 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. 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. 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: 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 > java -jar start.jar -DSTOP.PORT=8181 -DSTOP.KEY=abc123 --stop
.... ----
===== Configuring the Container Classpath ===== 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. 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. You can add 1 or more.
Here's an example of configuring 2 directories: 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 > 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. `--jar` adds a single jar file to the container classpath.
You can add 1 or more. You can add 1 or more.
Here's an example of configuring 3 extra jars: 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 > 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. `--classes` add the location of a directory containing classes to add to the container classpath.
You can add 1 or more. You can add 1 or more.
Here's an example of configuring a single extra classes dir: 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 > java -jar jetty-runner.jar --classes /opt/stuff/classes my.war
.... ----
____
[NOTE] [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`. 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]. 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). 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 ===== Gathering Statistics
If statistics gathering is enabled, then they are viewable by surfing to the context `/stats`. 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. You may optionally protect access to that context with a password.
Here's an example of enabling statistics, with no password protection: 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 > 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. 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: 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 jetty: MD5:164c88b302622e17050af52c89945d44,user
admin: CRYPT:adpexzg3FUZAk,server-administrator,content-administrator,admin admin: CRYPT:adpexzg3FUZAk,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq,user other: OBF:1xmk1w261u9r1w1c1xmq,user
@ -281,18 +276,18 @@ plain: plain,user
user: password,user user: password,user
# This entry is for digest auth. The credential is a MD5 hash of username:realmname:password # This entry is for digest auth. The credential is a MD5 hash of username:realmname:password
digest: MD5:6e120743ad67abfbc385bc2bb754e297,user digest: MD5:6e120743ad67abfbc385bc2bb754e297,user
.... ----
Assuming we've copied it into the local directory, we would apply it like so 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 > 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: 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:
Statistics gathering started 1490627ms ago Statistics gathering started 1490627ms ago
@ -346,4 +341,4 @@ Total messages out: 7
Memory: Memory:
Heap memory usage: 49194840 bytes Heap memory usage: 49194840 bytes
Non-heap memory usage: 12611696 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`. 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: 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[] 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: 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 --> <!-- Get a reference to the GCloudSessionIdManager -->
<Ref id="Server"> <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: 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 --> <!-- Reference the server directly -->
<Get name="server"> <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: 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 --> <!-- Get a reference to the GCloudSessionIdManager -->
<Ref id="Server"> <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: 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 --> <!-- Reference the server directly -->
<Get name="server"> <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: 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 ## Unique identifier for this node in the cluster
jetty.infinispanSession.workerName=node1 jetty.infinispanSession.workerName=node1
.... ----
jetty.infinispanSession.workerName:: jetty.infinispanSession.workerName::
The name that uniquely identifies this node in the cluster. 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. This file configures an instance of the `InfinispanSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this: It looks like this:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
include::{SRCDIR}/jetty-infinispan/src/main/config/etc/jetty-infinispan.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: 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 --> <!-- Expose the jetty infinispan classes for session serialization -->
<Get name="serverClasspathPattern"> <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: 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 --> <!-- Expose the jetty infinispan classes for session serialization -->
<Get name="serverClasspathPattern"> <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`. Then, create the file `${jetty.base}/resources/hotrod-client.properties`.
Add the following line to this file: Add the following line to this file:
.... ----
infinispan.client.hotrod.marshaller=org.eclipse.jetty.session.infinispan.WebAppMarshaller 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: 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 ## Unique identifier for this node in the cluster
jetty.jdbcSession.workerName=node1 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. This file configures an instance of the `JDBCSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this: It looks like this:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
include::{SRCDIR}/jetty-server/src/main/config/etc/jetty-jdbc-sessions.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: 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(); 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. 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: 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); 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. 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. *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); 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: From a context xml file, you reference the Server instance as a Ref:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Ref id="Server"> <Ref id="Server">
<Call id="idMgr" name="getSessionIdManager"/> <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: 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 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: 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 //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: 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 ## Unique identifier for this node in the cluster
jetty.nosqlSession.workerName=node1 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. This file configures an instance of the `MongoSessionIdManager` that will be shared across all webapps deployed on that server.
It looks like this: It looks like this:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
include::{SRCDIR}/jetty-nosql/src/main/config/etc/jetty-nosql.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. 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: 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"> <New id="mongodb" class="com.mongodb.Mongo">
<Arg> <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: 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(); 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: 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"> <Ref name="Server" id="Server">
<Call id="mongoIdMgr" name="getSessionIdManager"/> <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: 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 name="server">
<Get id="mongoIdMgr" name="sessionIdManager"/> <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: 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 //assuming you have already set up the MongoSessionIdManager as shown earlier
//and have a reference to the Server instance: //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: 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"?> <?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: 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"> <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: 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"> <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: 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.SessionCookieConfig;
import javax.servlet.ServletContextEvent; 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: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<web-app <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: 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(); 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`: 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(); javax.servlet.SessionContext.getEffectiveSessionTrackingModes();
---- ----
To change the session tracking modes, call: To change the session tracking modes, call:
[source, java, subs="{sub-order}"] [source, java]
---- ----
javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>); javax.servlet.SessionContext.setSessionTrackingModes(Set<SessionTrackingMode>);
---- ----
You may also set the tracking mode in `web.xml`, e.g.: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<web-app <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. 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: 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"> <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. 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: Here's how the configuration looks in XML:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Set name="sessionHandler"> <Set name="sessionHandler">
<New class="org.eclipse.jetty.server.session.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: 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> <plugin>
<groupId>org.eclipse.jetty</groupId> <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. 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 $ java -jar ../start.jar --create-startd
INFO : Base directory was modified 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. 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] [NOTE]
====
Session data is now only loaded when requested. Session data is now only loaded when requested.
Previous functionality such as `setLazyLoad` has been removed. Previous functionality such as `setLazyLoad` has been removed.
____ ====
==== Configuring File System Session Properties ==== 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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. 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 $ java -jar ../start.jar --create-startd
INFO : Base directory was modified 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. 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. 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 $ 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 : 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. 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] [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. 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 ==== 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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:: jetty.session.gcloud.maxRetries::
Maxmium number of tries to connect to GCloud DataStore to write sessions. Maxmium number of tries to connect to GCloud DataStore to write sessions.
jetty.session.gcloud.backoffMs:: 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. 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 $ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d 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. 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] [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. 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 ==== 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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. 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 ==== Configuring Embedded Hazelcast Clustering
During testing, it can be helpful to run an in-process instance of Hazelcast. 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. 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 $ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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. 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. 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 $ java -jar ../start.jar --create-startd
INFO : Base directory was modified 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. 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] [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. 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 ==== 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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 ==== 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. 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. 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 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. 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. 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] [IMPORTANT]
====
If you are running Jetty with JDK 9 or greater, enable `session-store-infinispan-embedded-910.mod` instead. If you are running Jetty with JDK 9 or greater, enable `session-store-infinispan-embedded-910.mod` instead.
____ ====
[source, screen]
[source, screen, subs="{sub-order}"]
---- ----
java -jar ../start.jar --add-to-start=session-store-infinispan-embedded 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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 ==== 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. 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 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. 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. We have provided a conversion program which will convert any sessions stored in Infinispan to the new format.
____
[IMPORTANT] [IMPORTANT]
====
We recommend that you backup your stored sessions before running the conversion program. We recommend that you backup your stored sessions before running the conversion program.
____ ====
How to use the converter: 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 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. 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: 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 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. 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 $ java -jar ../start.jar --create-startd
INFO : Base directory was modified 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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:: db-connection-type::
Set to either `datasource` or `driver` depending on the type of connection being used. Set to either `datasource` or `driver` depending on the type of connection being used.
jetty.session.jdbc.datasourceName:: 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: 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 --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. 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 $ java -jar ../start.jar --create-startd
INFO : Base directory was modified 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. 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] [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. 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 ==== 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: 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 # 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. 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. 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] [NOTE]
====
Configuring `savePeriod` is useful if your persistence technology is very slow/costly for writes. 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. 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. 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`. 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:: jetty.session.mongo.dbName::
Name of the database in Mongo used to store the Session collection. Name of the database in Mongo used to store the Session collection.
jetty.session.mongo.collectionName:: 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]]`. 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.] 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] [NOTE]
====
You will only use *one* `connection-type` at a time, `address` or `uri`. 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. 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. 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`: 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 --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 * 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 * >= 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] [NOTE]
====
If you are not using a `SessionDataStore` that persists sessions, be aware that evicted sessions will be lost. If you are not using a `SessionDataStore` that persists sessions, be aware that evicted sessions will be lost.
____ ====
jetty.session.saveOnInactiveEvict:: jetty.session.saveOnInactiveEvict::
Boolean, default `false`. Boolean, default `false`.
Controls whether a session will be saved to the `SessionDataStore` just prior to its eviction. 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: 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 ==== 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: 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"> <Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Call id="sh" name="getSessionHandler"> <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.] The example above functions in either a `jetty-web.xml` file or a link:#using-basic-descriptor-files[context xml descriptor file.]
____
[NOTE] [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. 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. 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 INFO : Base directory was modified
---- ----
____
[NOTE] [NOTE]
====
It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down. 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. 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 [mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment: Java Environment:
@ -67,4 +67,4 @@ No classpath entries and/or version information available show.
Jetty Active XMLs: Jetty Active XMLs:
------------------ ------------------
(no xml files specified) (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]$ mkdir mybase
[jetty]$ cd mybase [jetty]$ cd mybase
[mybase]$ ls -la [mybase]$ ls -la
@ -30,4 +30,4 @@ WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs] Usage: java -jar start.jar [options] [properties] [configs]
java -jar start.jar --help # for more information 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 [mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment: Java Environment:
@ -83,4 +83,4 @@ ${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml ${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-deploy.xml ${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.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 [mybase]$ java -jar $JETTY_HOME/start.jar --add-to-start=http,webapp,deploy
INFO : webapp initialized in ${jetty.base}/start.ini INFO : webapp initialized in ${jetty.base}/start.ini
INFO : server transitively enabled, ini template available with --add-to-start=server 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 INFO : deploy initialized in ${jetty.base}/start.ini
MKDIR : ${jetty.base}/webapps MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified 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 [mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=logging,-internal
Available Modules: Available Modules:
@ -91,4 +91,4 @@ Modules for tag 'requestlog':
Depend: server, logback-core, resources Depend: server, logback-core, resources
LIB: lib/logback/logback-access-${logback.version}.jar LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml 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 [mybase]$ java -jar ../start.jar --list-modules
Available Modules: Available Modules:
@ -728,4 +728,4 @@ Modules for tag 'session':
Tags: session Tags: session
Depend: server Depend: server
XML: etc/sessions/id-manager.xml 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. 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 [jetty-distribution-{VERSION}]$ java -jar start.jar
2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-{VERSION} 2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-{VERSION}
... ...
.... ----
Jetty is a highly modularized web server container. 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. 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 * Server XML configuration files
--dry-run:: --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: 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 $ java -jar start.jar --dry-run > jetty.sh
$ . jetty.sh $ . jetty.sh
.... ----
--dry-run=<parts>:: --dry-run=<parts>::
Print specific parts of the command line. The parts are a comma separated list of: 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 * "args" - the arguments passed to the main class
It is possible to decompose the start command: It is possible to decompose the start command:
.... ----
$ OPTS=$(java -jar start.jar --dry-run=opts,path) $ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main) $ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args) $ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg $ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
.... ----
Alternatively to create an args file for java: Alternatively to create an args file for java:
.... ----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args $ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args $ java @/tmp/args
.... ----
--exec:: --exec::
Forces the start to use a forked instance of java to run Jetty. 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. 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. 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: 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 $ 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. Doing this will uncomment the property in the associated .ini file and set it to the value specified.
--update-ini:: --update-ini::
Used to update a specified property or properties that exist in an existing .ini file. 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. 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 $ java -jar ../start.jar --update-ini jetty.http.port=8417
ConfigSource <command-line> ConfigSource <command-line>
ConfigSource ${jetty.base} ConfigSource ${jetty.base}
INFO : http property updated jetty.http.port=8417 INFO : http property updated jetty.http.port=8417
INFO : http updated ${jetty.base}/start.d/http.ini INFO : http updated ${jetty.base}/start.d/http.ini
ConfigSource ${jetty.home} ConfigSource ${jetty.home}
.... ----
+ +
--create-startd:: --create-startd::
Creates a `${jetty.base}/start.d/` directory. 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>:: --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}`. 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 # generate module.dot
$ java -jar start.jar --module=websocket --write-module-graph=modules.dot $ java -jar start.jar --module=websocket --write-module-graph=modules.dot
# post process to a PNG file # post process to a PNG file
$ dot -Tpng -o modules.png modules.dot $ 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. 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. 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. Useful for modules that have downloadable content that is being overridden with alternatives in the `${jetty.base}`` directory.
____
[CAUTION] [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. 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-licenses::
Approve all license questions. Approve all license questions.
Useful for enabling modules from a script that does not require user interaction. 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. 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`: 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 > 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. 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. 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: 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 > java -jar start.jar STOP.PORT=8181 STOP.KEY=abc123 --stop
.... ----
____
[NOTE] [NOTE]
====
To perform a graceful shutdown of Jetty, the `stats` link:#startup-modules[module] *must* be enabled. To perform a graceful shutdown of Jetty, the `stats` link:#startup-modules[module] *must* be enabled.
____ ====
===== Advanced Commands ===== Advanced Commands
--lib=<classpath>:: --lib=<classpath>::
@ -293,34 +291,34 @@ Default is https://repo1.maven.org/maven2/.
==== Shaded Start.jar ==== 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. 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> <dependency>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-start</artifactId> <artifactId>jetty-start</artifactId>
<version>{VERSION}</version> <version>{VERSION}</version>
<classifier>shaded</classifier> <classifier>shaded</classifier>
</dependency> </dependency>
.... ----
==== Start.jar without exec or forking. ==== Start.jar without exec or forking.
Some Jetty modules include the `--exec` option so that java command line options can be set. 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`. 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: 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=$(java -jar start.jar --dry-run)
$ $CMD $ $CMD
.... ----
It is possible to decompose the start command so that it can be modified: It is possible to decompose the start command so that it can be modified:
.... ----
$ OPTS=$(java -jar start.jar --dry-run=opts,path) $ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main) $ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args) $ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg $ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
.... ----
Alternatively to create an args file for java: Alternatively to create an args file for java:
.... ----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args $ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/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. * Also known as the `${jetty.home}` property.
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions. * This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
____
[IMPORTANT] [IMPORTANT]
====
Jetty Home should always be treated as a standard of truth. 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. All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.
____ ====
[[base-vs-home-resolution]] [[base-vs-home-resolution]]
Potential configuration is resolved from these 2 directory locations. 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. 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 [jetty-distribution-{VERSION}]$ ls -la
total 496 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: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! 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. 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 [demo-base]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment: Java Environment:
@ -213,7 +212,7 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-rewrite.xml ${jetty.home}/etc/jetty-rewrite.xml
${jetty.base}/etc/demo-rewrite-rules.xml ${jetty.base}/etc/demo-rewrite-rules.xml
${jetty.base}/etc/test-realm.xml ${jetty.base}/etc/test-realm.xml
.... ----
The `--list-config` command line option displays what the configuration will look like when starting Jetty. 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. 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. 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 [my-base]$ cat start.ini
# Enable security via jaas, and configure it # Enable security via jaas, and configure it
@ -257,7 +256,7 @@ jetty.dump.stop=false
--module=resources --module=resources
--module=client --module=client
--module=annotations --module=annotations
.... ----
In this example, `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty. 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) 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: 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 [jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION} /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.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 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. 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}`. 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 [jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION} /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.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 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 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 `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}`. 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 [jetty-distribution-{VERSION}]$ pwd
/home/user/jetty-distribution-{VERSION} /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.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 2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
... ...
.... ----
____
[IMPORTANT] [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. 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. 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. 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] [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]. 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 ==== 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. 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]) (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 [demo-base]$ java -jar $JETTY_HOME/start.jar --list-classpath
Jetty Server 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 39: {VERSION} | ${jetty.home}/lib/websocket/websocket-common-{VERSION}.jar
40: {VERSION} | ${jetty.home}/lib/websocket/websocket-server-{VERSION}.jar 40: {VERSION} | ${jetty.home}/lib/websocket/websocket-server-{VERSION}.jar
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{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. 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: 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 $ mkdir my-jetty-base
$ cd my-jetty-base $ cd my-jetty-base
$ java -jar $JETTY_HOME/start.jar --add-to-start=http $ 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 : threadpool transitively enabled, ini template available with --add-to-start=threadpool
INFO : Base directory was modified INFO : Base directory was modified
$ java -jar $JETTY_HOME/start.jar --jpms $ 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 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. 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: 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 $ java -jar $JETTY_HOME/start.jar --jpms --dry-run
.... ----
This will give an output looking something like this (broken in sections for clarity): 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 /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:... --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 --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 ... --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. 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. 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]: 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 .mysql.mod
.... ----
[description] [description]
MySQL module MySQL module
[lib] [lib]
lib/mysql/mysql-connector-java-*.jar lib/mysql/mysql-connector-java-*.jar
.... ----
However, when running on the module-path, things are quite different. 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: 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 .mysql.mod
.... ----
[description] [description]
MySQL module MySQL module
@ -122,7 +122,7 @@ lib/mysql/mysql-connector-java-*.jar
[jpms] [jpms]
add-modules: java.sql 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. 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: 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 .mysql.mod
.... ----
[description] [description]
MySQL module MySQL module
@ -141,21 +141,21 @@ lib/mysql/mysql-connector-java-*.jar
[jpms] [jpms]
add-modules: com.mysql.jdbc 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 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: The `[jpms]` section has the following format:
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[jpms] [jpms]
add-modules: <module name>(,<module name>)* add-modules: <module name>(,<module name>)*
patch-module: <module>=<file>(:<file>)* patch-module: <module>=<file>(:<file>)*
add-opens: <module>/<package>=<target-module>(,<target-module>)* add-opens: <module>/<package>=<target-module>(,<target-module>)*
add-exports: <module>/<package>=<target-module>(,<target-module>)* add-exports: <module>/<package>=<target-module>(,<target-module>)*
add-reads: <module>=<target-module>(,<target-module>)* add-reads: <module>=<target-module>(,<target-module>)*
.... ----
[[jpms-module-path-alternative]] [[jpms-module-path-alternative]]
==== Alternative way to start Jetty on the module-path ==== 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`, 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). 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 .jpms.mod
.... ----
[ini] [ini]
--jpms --jpms
[jpms] [jpms]
# Additional JPMS configuration. # Additional JPMS configuration.
.... ----
The `[ini]` section is equivalent to passing the `--jpms` option to the command line. 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]) The `[jpms]` section (see also the link:#jpms-advanced-config[advanced JPMS configuration section])
allows you specify additional JPMS configuration. allows you specify additional JPMS configuration.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
$ mkdir jetty-base-jpms $ mkdir jetty-base-jpms
$ cd jetty-base-jpms $ cd jetty-base-jpms
$ mkdir modules $ mkdir modules
@ -189,4 +189,4 @@ $ cp /tmp/jpms.mod modules/
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,jpms $ java -jar $JETTY_HOME/start.jar --add-to-start=http,jpms
# Jetty will start on the module-path. # Jetty will start on the module-path.
$ java -jar $JETTY_HOME/start.jar $ 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]]
==== Enabling Modules ==== Enabling Modules
____
[TIP] [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. 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. 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. 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. 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. 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. 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]$ mkdir mybase
[jetty.home]$ cd mybase/ [jetty.home]$ cd mybase/
[mybase]$ java -jar ../start.jar --create-startd [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 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 265 Aug 29 15:19 webapp.ini
-rw-r--r-- 1 staff staff 177 Aug 29 15:19 websocket.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. 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. 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. 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. 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 [mybase]$ java -jar ../start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.ini INFO : webapp initialised in ${jetty.base}/start.ini
INFO : server 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 └── start.d
├── ssl.ini ├── ssl.ini
└── start.ini └── start.ini
.... ----
[NOTE] [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 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. 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] [IMPORTANT]
====
It is important that you *do not* modify the module files in the `$JETTY_HOME/modules` directory. 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. $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. 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`. 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. When a module is activated, a number of properties are set by default.
To view these defaults, open up the associated ini file. 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. 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: Below is an example of the `requestlog.ini` file:
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
# --------------------------------------- # ---------------------------------------
# Module: requestlog # Module: requestlog
--module=requestlog --module=requestlog
@ -194,7 +192,7 @@ Below is an example of the `requestlog.ini` file:
## Whether to log LogLatency ## Whether to log LogLatency
# jetty.requestlog.loglatency=false # jetty.requestlog.loglatency=false
.... ----
The first lines name the module file being called (located in `{$jetty.home/modules}`). 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. 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. 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. If there are multiple entries in the `[tags]` section, it sorts by the first tag in the list.
____
[NOTE] [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. 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` If you would like to see *all* modules, use `--list-all-modules`
____ ====
Here's an example of the `--list-modules` command: Here's an example of the `--list-modules` command:
include::screen-list-modules.adoc[] 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: 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} [user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080 [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. 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: 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 [jetty-distribution-{VERSION}]$ cat modules/http.mod
[depend] [depend]
server server
@ -92,15 +92,15 @@ etc/jetty-http.xml
[ini-template] [ini-template]
jetty.http.port=8080 jetty.http.port=8080
http.timeout=30000 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 `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. 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: 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 [jetty-distribution-{VERSION}]$ cat modules/server.mod
[lib] [lib]
lib/servlet-api-3.1.jar lib/servlet-api-3.1.jar
@ -116,15 +116,15 @@ etc/jetty.xml
[ini-template] [ini-template]
threads.min=10 threads.min=10
threads.max=200 threads.max=200
.... ----
The `server` module declares the libraries the server needs and to use `jetty.xml` file. 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. 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: 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 [jetty-distribution-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config
Java Environment: Java Environment:
@ -174,7 +174,7 @@ Jetty Active XMLs:
------------------ ------------------
${jetty.home}/etc/jetty.xml ${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-http.xml ${jetty.home}/etc/jetty-http.xml
.... ----
This represents the entirety of the configuration that is applied to start Jetty. 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. 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} [user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ echo jetty.http.port=8080 > /tmp/jetty.properties [jetty-distribution-{VERSION}]$ echo jetty.http.port=8080 > /tmp/jetty.properties
[jetty-distribution-{VERSION}]$ export JETTY_HOME=`pwd` [jetty-distribution-{VERSION}]$ export JETTY_HOME=`pwd`
@ -203,14 +203,14 @@ org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \ /tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \ $JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.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. 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: 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} [user]$ cd jetty-distribution-{VERSION}
[jetty-distribution-{VERSION}]$ mkdir example-base [jetty-distribution-{VERSION}]$ mkdir example-base
[example-base]$ cd 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 2 user webgroup 4096 Oct 4 11:55 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../ drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini -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: 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 [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: 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]# tar -zxf /home/user/downloads/jetty-distribution-{VERSION}.tar.gz
[/opt/jetty]# cd jetty-distribution-{VERSION}/ [/opt/jetty]# cd jetty-distribution-{VERSION}/
[/opt/jetty/jetty-distribution-{VERSION}]# ls [/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 [/opt/jetty/jetty-distribution-{VERSION}]# service jetty start
Starting Jetty: OK Wed Nov 20 10:26:53 MST 2013 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. 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. Prepare some empty directories to work with.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
# mkdir -p /opt/jetty # mkdir -p /opt/jetty
# mkdir -p /opt/web/mybase # mkdir -p /opt/web/mybase
# mkdir -p /opt/jetty/temp # mkdir -p /opt/jetty/temp
.... ----
The directory purposes are as follows: 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. Jetty 9.3 requires Java 8 (or greater) to run.
Make sure you have it installed. Make sure you have it installed.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
# apt-get install openjdk-8-jdk # apt-get install openjdk-8-jdk
.... ----
Or download Java 8 from: http://www.oracle.com/technetwork/java/javase/downloads/index.html 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
java version "1.6.0_27" java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2) 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" java version "1.7.0_25"
OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1ubuntu0.12.04.2) 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) OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)
.... ----
It is recommended that you create a user to specifically run Jetty. 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. 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 # 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`. 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. 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]# tar -zxf /home/user/Downloads/jetty-distribution-{VERSION}.tar.gz
[/opt/jetty]# ls -F [/opt/jetty]# ls -F
jetty-distribution-{VERSION}/ jetty-distribution-{VERSION}/
[/opt/jetty]# mkdir /opt/jetty/temp [/opt/jetty]# mkdir /opt/jetty/temp
.... ----
It might seem strange or undesirable to unpack the first portion of the jetty-distribution directory name too. 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. 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. 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/ # cd /opt/web/mybase/
[/opt/web/mybase]# ls [/opt/web/mybase]# ls
[/opt/web/mybase]# java -jar /opt/jetty/jetty-distribution-{VERSION}/start.jar \ [/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 INFO : Base directory was modified
[/opt/web/mybase]# ls -F [/opt/web/mybase]# ls -F
start.ini webapps/ start.ini webapps/
.... ----
At this point you have configured your `/opt/web/mybase` to enable the following modules: 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. Copy your war file into place.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
# cp /home/user/projects/mywebsite.war /opt/web/mybase/webapps/ # 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`. 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. 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 # grep jetty.http.port /opt/web/mybase/start.ini
jetty.port=80 jetty.port=80
.... ----
Change the permissions on the Jetty distribution and webapp directories so that the user you created can access it. 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/jetty
# chown --recursive jetty /opt/web/mybase # 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. 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 # 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_HOME=/opt/jetty/jetty-distribution-{VERSION}" > /etc/default/jetty
# echo "JETTY_BASE=/opt/web/mybase" >> /etc/default/jetty # echo "JETTY_BASE=/opt/web/mybase" >> /etc/default/jetty
# echo "JETTY_USER=jetty" >> /etc/default/jetty # echo "JETTY_USER=jetty" >> /etc/default/jetty
# echo "TMPDIR=/opt/jetty/temp" >> /etc/default/jetty # echo "TMPDIR=/opt/jetty/temp" >> /etc/default/jetty
.... ----
Test out the configuration: Test out the configuration:
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
# service jetty status # service jetty status
Checking arguments to Jetty: Checking arguments to Jetty:
START_INI = /opt/web/mybase/start.ini START_INI = /opt/web/mybase/start.ini
@ -254,14 +254,14 @@ RUN_CMD = /usr/bin/java
-jar /opt/jetty/jetty-distribution-{VERSION}/start.jar -jar /opt/jetty/jetty-distribution-{VERSION}/start.jar
console-capture.xml console-capture.xml
jetty-started.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. 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. Test the service to make sure it starts up and runs successfully.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
# service jetty start # service jetty start
Starting Jetty: OK Wed Nov 20 12:35:28 MST 2013 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 [/opt/web/mybase]# ps u 2958
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND 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... jetty 2958 5.3 0.1 11179176 53984 ? Sl 12:46 0:00 /usr/bin/java -Djetty...
.... ----
You should now have your server running. 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. Prepare some empty directories to work with.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
C:\> mkdir opt C:\> mkdir opt
C:\> cd opt C:\> cd opt
C:\opt> mkdir jetty 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> myappbase
11/21/2013 04:06 PM <DIR> temp 11/21/2013 04:06 PM <DIR> temp
0 File(s) 0 bytes 0 File(s) 0 bytes
.... ----
The directory purposes are as follows: 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 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 C:\opt>java -version
java version "1.7.0_45" java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18) Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode) 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] 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: 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 C:\opt\jetty>dir
Volume in drive C has no label. Volume in drive C has no label.
Volume Serial Number is C8CF-820B Volume Serial Number is C8CF-820B
@ -110,7 +110,7 @@ C:\opt\jetty>dir
11/21/2013 12:13 PM <DIR> webapps 11/21/2013 12:13 PM <DIR> webapps
6 File(s) 453,659 bytes 6 File(s) 453,659 bytes
11 Dir(s) 306,711,420,928 bytes free 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. 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: Once you are complete, the contents of `C:\opt` directory should look like this:
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
C:\opt> dir C:\opt> dir
Volume in drive C has no label. Volume in drive C has no label.
Volume Serial Number is DEAD-BEEF 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 104,448 prunmgr.exe
11/21/2013 04:11 PM 80,896 prunsrv.exe 11/21/2013 04:11 PM 80,896 prunsrv.exe
2 File(s) 185,344 bytes 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. 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) 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 C:\opt\myappbase>java -jar ..\jetty\start.jar --add-to-start=deploy,http,console-capture
WARNING: deploy initialised in ${jetty.base}\start.ini (appended) 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 11/21/2013 12:49 PM <DIR> webapps
1 File(s) 1,355 bytes 1 File(s) 1,355 bytes
4 Dir(s) 306,711,064,576 bytes free 4 Dir(s) 306,711,064,576 bytes free
.... ----
At this point you have configured your `C:\opt\myappbase` to enable the following modules: 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. 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\ 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. 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. 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. 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 .JDK 8 Garbage Collection Logging Configuration
[source,screen, subs="{sub-order}"] [source,screen]
.... ----
-Xloggc:/path/to/myjettybase/logs/gc.log -Xloggc:/path/to/myjettybase/logs/gc.log
-XX:+PrintGCDateStamps -XX:+PrintGCDateStamps
-XX:+PrintGCDetails -XX:+PrintGCDetails
@ -40,18 +40,18 @@ They provide good information about the GC activity of your JVM, producing logs
-XX:+PrintReferenceGC -XX:+PrintReferenceGC
-XX:+PrintTenuringDistribution -XX:+PrintTenuringDistribution
-XX:+PrintAdaptiveSizePolicy -XX:+PrintAdaptiveSizePolicy
.... ----
.JDK 9 Garbage Collection Logging Configuration .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 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. 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). 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 -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). 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.rmem_max=16777216
$ sysctl -w net.core.wmem_max=16777216 $ sysctl -w net.core.wmem_max=16777216
$ sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216" $ sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216"
$ sysctl -w net.ipv4.tcp_wmem="4096 16384 16777216" $ sysctl -w net.ipv4.tcp_wmem="4096 16384 16777216"
.... ----
====== Queue Sizes ====== 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. 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. 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 $ 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 `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: 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.core.netdev_max_backlog=16384
$ sysctl -w net.ipv4.tcp_max_syn_backlog=8192 $ sysctl -w net.ipv4.tcp_max_syn_backlog=8192
$ sysctl -w net.ipv4.tcp_syncookies=1 $ sysctl -w net.ipv4.tcp_syncookies=1
.... ----
====== Ports ====== Ports
If many outgoing connections are made (for example, on load generators), the operating system might run low on 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`: 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.ip_local_port_range="1024 65535"
$ sysctl -w net.ipv4.tcp_tw_recycle=1 $ sysctl -w net.ipv4.tcp_tw_recycle=1
.... ----
====== File Descriptors ====== File Descriptors
Busy servers and load generators may run out of file descriptors as the system defaults are normally low. 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`: These can be increased for a specific user in `/etc/security/limits.conf`:
.... ----
theusername hard nofile 40000 theusername hard nofile 40000
theusername soft nofile 40000 theusername soft nofile 40000
.... ----
====== Congestion Control ====== Congestion Control
Linux supports pluggable congestion control algorithms. Linux supports pluggable congestion control algorithms.
To get a list of congestion control algorithms that are available in your kernel run: 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 $ 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. 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: You can try setting the control to cubic with:
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
$ sysctl -w net.ipv4.tcp_congestion_control=cubic $ sysctl -w net.ipv4.tcp_congestion_control=cubic
.... ----
====== Mac OS ====== 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. 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: 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[] 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. 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: 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 [mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=connector
Available Modules: Available Modules:
@ -178,13 +178,13 @@ Modules for tag 'connector':
Depend: unixsocket-http Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml XML: etc/jetty-unixsocket-secure.xml
... ...
.... ----
To enable a connector, simply activate the associated module. 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]: 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 [mybase] java -jar $JETTY_HOME/start.jar --create-startd
MKDIR : ${jetty.base}/start.d MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified INFO : Base directory was modified
@ -204,14 +204,14 @@ INFO : Base directory was modified
└── start.d └── start.d
├── http.ini ├── http.ini
└── https.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`. 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: 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 [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: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 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.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.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 2017-08-31 10:19:59.274:INFO:oejs.Server:main: Started @791ms
.... ----
When modules are enabled, they are loaded with several default options. 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`). 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: 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 # Module: http
# Enables a HTTP connector on the server. # 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 ## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230 # 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. 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: 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 ## Connector port to listen on
jetty.http.port=5231 jetty.http.port=5231
... ...
.... ----
Now when the server is started, HTTP connections will enter on 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 [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: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.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.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 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. 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]. For additional information on the module system, please refer to our documentation on link:#startup-modules[Startup Modules].
____
[NOTE] [NOTE]
====
Editing these module files is the recommended way to edit the configuration of your server. 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. 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. 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 ==== Limiting Connections
Jetty also provides the means by which to limit connections to the server and/or contexts. 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. 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: 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"> <New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg> <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. 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: 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"> <New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg> <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. 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: 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"> <New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="Server" /></Arg> <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: 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"> <New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Set name="secureScheme">https</Set> <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`": This example HttpConfiguration may be used by reference to the ID "`httpConfig`":
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Call name="addConnector"> <Call name="addConnector">
<Arg> <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`": 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"> <New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Arg><Ref refid="httpConfig"/></Arg> <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. 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. 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] [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. 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. 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. Rather the files should be copied into a Jetty base directory and then modified.
____ ====
===== X-Forward-for Configuration ===== X-Forward-for Configuration
The `X-Forwarded-for` header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection. The `X-Forwarded-for` header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection.
These headers can be interpreted by an instance of link:{JDURL}/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`] which can be added to a `HttpConfiguration` as follows: 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"> <New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">
<Set name="outputBufferSize">32768</Set> <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: An example of adding the factory to a HTTP connector is shown below:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Call name="addConnector"> <Call name="addConnector">
<Arg> <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]: For the default SSL support, simply activate the `ssl` link:#startup-modules[module]:
[source, plain, subs="{sub-order}"] [source, plain]
---- ----
$ cd /path/to/mybase $ cd /path/to/mybase
$ java -jar ${JETTY_HOME}/start.jar --add-to-startd=ssl $ 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]: 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} $ cd ${JETTY_HOME}
$ java -jar ../start.jar --add-to-start=ssl,conscrypt $ 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. 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 $ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https $ 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. 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] [NOTE]
====
Once TLS v1.3 is released, there will be no workaround available for TLS v1.0 or v1.1. 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. 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. 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`.] 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: 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.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setExcludeCipherSuites("^.*_(MD5|SHA|SHA1)$"); 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`: 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 $ keytool -keystore keystore -alias jetty -genkey -keyalg RSA
---- ----
____
[NOTE] [NOTE]
====
The DSA key algorithm certificate produces an error after loading several pages. 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." 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. 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. 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. The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt.
For example: For example:
[source, screen, subs="{sub-order}"] [source, screen]
---- ----
$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA $ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA
Enter keystore password: password 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: 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' $ 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`: 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 $ 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`: 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 $ 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 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: 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 $ openssl genrsa -aes128 -out jetty.key
Generating RSA private key, 2048 bit long modulus 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: 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 $ 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`: 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 $ 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. 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] [NOTE]
====
You need both the private key and the certificate in the JSSE keystore. You need both the private key and the certificate in the JSSE keystore.
You should load the certificate into the keystore used to generate the CSR with `keytool`. You should load the certificate into the keystore used to generate the CSR with `keytool`.
If your key pair is not already in a keystore (for example, because it has been generated with OpenSSL), you need to use the PKCS12 format to load both key and certificate (see link:#loading-keys-and-certificates-via-pkcks12[PKCKS12 Keys &Certificates]). 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]]
====== 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. 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: An example PEM file is:
[source, screen, subs="{sub-order}"] [source, screen]
---- ----
jetty.crt jetty.crt
-----BEGIN CERTIFICATE----- -----BEGIN CERTIFICATE-----
@ -302,14 +299,14 @@ Rcz6oCRvCGCe5kDB
The following command loads a PEM encoded certificate in the `jetty.crt` file into a JSSE keystore: 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 $ 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: 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 $ 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: 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 $ 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: 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 $ 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 $ openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12
---- ----
____
[NOTE] [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.] 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__. OpenSSL asks for an __export password__.
A non-empty password is required to make the next step work. A non-empty password is required to make the next step work.
Load the resulting PKCS12 file into a JSSE keystore with `keytool`: 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 $ 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. The `keystore` only contains the server's private key and certificate.
[[img-certificate-chain]] [[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] [literal]
.The structure of KeyStore file: .The structure of KeyStore file:
.... ----
├── PrivateKeyEntry ├── PrivateKeyEntry
│   ├── PrivateKey │   ├── PrivateKey
│   ├── Certificate chain │   ├── Certificate chain
@ -376,13 +372,12 @@ image::images/certificate-chain.png[title="Certificate chain", alt="Certificate
│   └── Intermediary CA certificate │   └── Intermediary CA certificate
└── TrustedCertEntry └── TrustedCertEntry
   └── Root CA certificate    └── Root CA certificate
.... ----
____
[NOTE] [NOTE]
====
Both the `Intermediary CA certificate` and `Root CA certificate` are optional. Both the `Intermediary CA certificate` and `Root CA certificate` are optional.
____ ====
[source%nowrap,plain,linenums] [source%nowrap,plain,linenums]
---- ----
$ cd $JETTY_BASE $ cd $JETTY_BASE
@ -644,21 +639,21 @@ the other is `$JETTY/etc/truststore` which contains intermediary CA and root CA.
[literal] [literal]
.The structure of `$JETTY/etc/keystore` .The structure of `$JETTY/etc/keystore`
.... ----
└── PrivateKeyEntry └── PrivateKeyEntry
   ├── PrivateKey    ├── PrivateKey
   └── Certificate chain    └── Certificate chain
      └── Server certificate (end entity)       └── Server certificate (end entity)
.... ----
[literal] [literal]
.The structure of `$JETTY/etc/truststore` .The structure of `$JETTY/etc/truststore`
.... ----
├── TrustedCertEntry ├── TrustedCertEntry
│   └── Intermediary CA certificate │   └── Intermediary CA certificate
└── TrustedCertEntry └── TrustedCertEntry
   └── Root CA certificate    └── Root CA certificate
.... ----
[[configuring-sslcontextfactory]] [[configuring-sslcontextfactory]]
==== Configuring the Jetty SslContextFactory ==== Configuring the Jetty SslContextFactory
@ -686,11 +681,10 @@ While the `SslContextFactory` can operate without a keystore (this mode is most
setKeyStorePath:: setKeyStorePath::
The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client). The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client).
____
[NOTE] [NOTE]
====
As a keystore is vital security information, it can be desirable to locate the file in a directory with *very* restricted access. As a keystore is vital security information, it can be desirable to locate the file in a directory with *very* restricted access.
____ ====
setKeyStorePassword:: 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. 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:: setTrustStorePath::
@ -704,26 +698,24 @@ setExcludeCipherSuites / setIncludeCipherSuites::
setExcludeProtocols / setIncludeProtocols:: setExcludeProtocols / setIncludeProtocols::
This allows for the customization of the selected Protocols that will be used by SSL/TLS. This allows for the customization of the selected Protocols that will be used by SSL/TLS.
____
[NOTE] [NOTE]
====
When working with Includes / Excludes, it is important to know that *Excludes will always win.* 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. 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). Be aware that each Include / Exclude list has a Set method (replace the list) or Add method (append the list).
____ ====
____
[CAUTION] [CAUTION]
====
The keystore and truststore passwords may also be set using the system properties: `org.eclipse.jetty.ssl.keypassword` `org.eclipse.jetty.ssl.password`. 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. This is _not_ a recommended usage.
____ ====
[[conscrypt]] [[conscrypt]]
==== Conscrypt SSL ==== 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]. 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`: 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()); 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()`. 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. Tools like https://www.ssllabs.com/[ssllabs.com] might report slightly different names which will be ignored.
____
[IMPORTANT] [IMPORTANT]
====
It is important to stay up-to-date with the latest supported cipher suites. 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. 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] [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. 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]. 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/`. 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. 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. 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] [NOTE]
====
Jetty *does* allow users to enable weak/deprecated cipher suites (or even no cipher suites at all). 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. 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-"). 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" <!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
"http://www.eclipse.org/jetty/configure_9_3.dtd"> "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`. 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 $ cd /path/to/mybase
$ ls -l $ ls -l
@ -821,23 +810,21 @@ etc/tweak-ssl.xml
$ $
---- ----
____
[NOTE] [NOTE]
====
The default `SslContextFactory` implementation applies the latest SSL/TLS recommendations surrounding vulnerabilities in SSL/TLS. 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. 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. 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] [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. 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: Additional Include / Exclude examples:
*Example*: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex: *Example*: Include all ciphers which support https://en.wikipedia.org/wiki/Forward_secrecy[Forward Secrecy] using regex:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<!-- Enable Forward Secrecy Ciphers. <!-- Enable Forward Secrecy Ciphers.
Note: this replaces the default Include Cipher list --> 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: *Example*: Exclude all old, insecure or anonymous cipher suites:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<!-- Eliminate Old / Insecure / Anonymous Ciphers --> <!-- Eliminate Old / Insecure / Anonymous Ciphers -->
<Call name="addExcludeCipherSuites"> <Call name="addExcludeCipherSuites">
@ -869,7 +856,7 @@ Additional Include / Exclude examples:
*Example*: Since 2014 SSLv3 is considered insecure and should be disabled. *Example*: Since 2014 SSLv3 is considered insecure and should be disabled.
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<!-- Eliminate Insecure Protocols --> <!-- Eliminate Insecure Protocols -->
<Call name="addExcludeProtocols"> <Call name="addExcludeProtocols">
@ -884,14 +871,13 @@ Additional Include / Exclude examples:
</Call> </Call>
---- ----
____
[NOTE] [NOTE]
====
Note that disabling SSLv3 prevents very old browsers like Internet Explorer 6 on Windows XP from connecting. 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. *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> <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. 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 [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`". 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: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: For `blah` webapp:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: For `other` webapp:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: For foo webapp:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: For bar webapp:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: Error code example:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<error-page> <error-page>
<error-code>404</error-code> <error-code>404</error-code>
@ -43,7 +43,7 @@ Error code example:
Exception example: Exception example:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<error-page> <error-page>
<exception-type>java.io.IOException</exception-type> <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. 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: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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: 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 handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException
void handleErrorPage(HttpServletRequest request, Writer writer, int code, String message) 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. 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: For example:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure class="org.eclipse.jetty.server.handler.ContextHandler"> <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. 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: 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"> <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: * 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"> <Configure id="OtherServer" class="org.eclipse.jetty.server.Server">
---- ----
* For all connectors for the new server change the `refid` in the server argument: * 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> <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: 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[] 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: 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 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. 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: For example:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/test</Set> <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: 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"> <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: 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"> <Configure class="org.eclipse.jetty.server.Server">
<Call name="setAttribute"> <Call name="setAttribute">
@ -56,20 +56,19 @@ Set an attribute in `jetty.xml` on the Server instance for which you want to mod
</Configure> </Configure>
---- ----
____
[IMPORTANT] [IMPORTANT]
====
It is important to remember that you should *not* modify the XML files in your `$JETTY_HOME`. 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. 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. Jetty will always look first to the `$JETTY_BASE` for configuration.
____ ====
==== For All Apps in the JVM ==== For All Apps in the JVM
Use the system property `org.eclipse.jetty.server.Request.maxFormContentSize`. 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.] 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: Using `$JETTY_BASE\start.d\server.ini` as an example:
[source, console, subs="{sub-order}"] [source, console]
---- ----
# --------------------------------------- # ---------------------------------------
# Module: server # 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: 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" "jetty-"+host+"-"+port+"-"+resourceBase+"-_"+context+"-"+virtualhost+"-"+randomdigits+".dir"
.... ----
For example: For example:
.... ----
jetty-0.0.0.0-8080-test.war-_test-any-8900275691885214790.dir 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. 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: 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"> <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: The equivalent in code is:
[source, java, subs="{sub-order}"] [source, java]
---- ----
WebAppContext context = new WebAppContext(); WebAppContext context = new WebAppContext();
context.setContextPath("/test"); 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. 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: 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"> <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: And here is an example of doing it with java code:
[source, java, subs="{sub-order}"] [source, java]
---- ----
WebAppContext context = new WebAppContext(); WebAppContext context = new WebAppContext();
context.setContextPath("/test"); 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. 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: Again, you can do this in XML:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -125,7 +125,7 @@ Again, you can do this in XML:
Or in java: Or in java:
[source, java, subs="{sub-order}"] [source, java]
---- ----
WebAppContext context = new WebAppContext(); WebAppContext context = new WebAppContext();
context.setContextPath("/test"); 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. 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] [NOTE]
====
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments. 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.] 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 ===== 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. 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. 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 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. 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. 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 # Module: jvm
# A noop module that creates an ini template useful for # 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:+PrintCommandLineFlags
# -XX:+DisableExplicitGC # -XX:+DisableExplicitGC
-Djava.io.tmpdir=/path/to/desired/directory -Djava.io.tmpdir=/path/to/desired/directory
.... ----
==== The "work" 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. 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)]. To configure Jetty to keep it, use link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext.setPersistTempDirectory(true)].
____
[NOTE] [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. 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`: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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: 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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. This is useful if the version of an app is frequently changed.
____
[NOTE] [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.] 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]]
==== 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 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. 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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. 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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 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. 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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. 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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]] [[udm-application-providers]]
==== 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]. 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. 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.). 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/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. * 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. 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. 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"> <Call name="addLifeCycleBinding">
<Arg> <Arg>
@ -101,7 +101,7 @@ It supports hot (re)deployment.
The basic operation of the `WebAppProvider` is to periodically scan a directory for deployables. 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. 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"?> <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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: 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"?> <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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]. 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: They will then be applied to each `WebAppContext` deployed by the deployer:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<?xml version="1.0"?> <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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: 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"?> <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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": 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"?> <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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-`: 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"?> <?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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.] 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"?> <?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: 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 $ 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`. In a Maven project you add a dependency on the artifact `jetty-quickstart`.
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<dependency> <dependency>
<groupId>org.eclipse.jetty</groupId> <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. 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 that origin attributes will also be generated if debug log level is enabled.
____
[NOTE] [NOTE]
====
If you are using Spring-Boot you must set `generateOrigin` to true. 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. 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. 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: 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="DefaultsDescriptor(file:///path/to/distro/etc/webdefault.xml):21">
<listener origin="WebDescriptor(file:///path/to/base/webapps/test-spec/WEB-INF/web.xml):22"> <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. 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): 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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: 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 $ 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. 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): 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> <context-param>
<param-name>org.eclipse.jetty.jsp.precompiled</param-name> <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`. 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: 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) $ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
$ eval $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. 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. 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"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"> <!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. 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[] 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: 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> <context-param>
<param-name>org.eclipse.jetty.servlet.jspPackagePrefix</param-name> <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> </context-param>
---- ----
____
[NOTE] [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. 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]] [[compiling-jsps]]
===== Apache JSP Container ===== 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. 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. Set all parameters on the `org.apache.jasper.servlet.JspServlet` instance defined in the link:#webdefault-xml[`webdefault.xml`] file.
____
[NOTE] [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. 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]]
==== 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. 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. The example below shows how to do this when using the Jetty Maven plugin.
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <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: 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"> <Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/foo</Set> <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 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. 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 id="jsp">
<servlet-name>jsp</servlet-name> <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. 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. 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 id="jsp">
<servlet-name>jsp</servlet-name> <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. 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: Below is a snippet from the example:
[source, java, subs="{sub-order}"] [source, java]
---- ----
webapp.setAttribute("org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern",".*/[^/]*taglibs.*\\.jar$"); 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. You should make your JSF jars dependencies of the plugin and _not_ the webapp itself.
For example: For example:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<plugin> <plugin>
<groupId>org.eclipse.jetty</groupId> <groupId>org.eclipse.jetty</groupId>

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

@ -18,7 +18,7 @@
[[jetty-config-guide]] [[jetty-config-guide]]
= Jetty Configuration Guide == Jetty Configuration Guide
include::deploying/chapter.adoc[] include::deploying/chapter.adoc[]
include::contexts/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: 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> <login-config>
<auth-method>BASIC</auth-method> <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: 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> <login-config>
<auth-method>FORM</auth-method> <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. 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]: 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> <HTML>
<H1>FORM Authentication demo</H1> <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). 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]: 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"> <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. 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]: 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"> <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. 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]: 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"> <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: 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> <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. 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"> <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: 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"> <New class="org.eclipse.jetty.security.JDBCLoginService">
<Set name="name">Test JDBC Realm</Set> <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: * Access granted to a set of named roles:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<security-constraint> <security-constraint>
<web-resource-collection> <web-resource-collection>
@ -396,7 +396,7 @@ Until Servlet 3.1, role-based authorization could define:
* Access totally forbidden, regardless of role: * Access totally forbidden, regardless of role:
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<security-constraint> <security-constraint>
<web-resource-collection> <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`. * 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>`: 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> <security-constraint>
<web-resource-collection> <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. * 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>`: 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> <security-constraint>
<web-resource-collection> <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>`. 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>`: 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> <security-constraint>
<web-resource-collection> <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`. 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. 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"> <Configure id="testWebapp" class="org.eclipse.jetty.webapp.WebAppContext">
<Get name="securityHandler"> <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. 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. 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[] 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: Used from command line as such:
[source,shell,subs="{sub-order}"] [source,shell]
---- ----
$ java -Dorg.eclipse.jetty.server.Request.maxFormKeys=200 -jar ... $ 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`) 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_KEYS_KEY, "200");
System.setProperty(ContextHandler.MAX_FORM_CONTENT_SIZE_KEY, "400000"); 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: 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.setMaxFormContentSize(int maxSizeInBytes);
ContextHandler.setMaxFormKeys(int formKeys); 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: 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"> <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: 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> <login-config>
<auth-method>FORM</auth-method> <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": 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"> <New class="org.eclipse.jetty.jaas.JAASLoginService">
<Set name="Name">Test JAAS Realm</Set> <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>>). The `LoginModuleName` must match the name of your LoginModule as declared in your login module configuration file (see <<jaas-step-2,Step 2>>).
____
[CAUTION] [CAUTION]
====
The name of the realm-name that you declare in `web.xml` must match *exactly* the `Name` field of your `JAASLoginService`. 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: 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`. 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: An example:
+ +
[source, xml, subs="{sub-order}"] [source, xml]
---- ----
<Configure id="Server" class="org.eclipse.jetty.server.Server"> <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: 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"> <Configure class="org.eclipse.jetty.webapp.WebAppContext">
@ -134,11 +133,10 @@ xyz {
}; };
---- ----
____
[CAUTION] [CAUTION]
====
It is imperative that the application name on the first line is *exactly* the same as the `LoginModuleName` of your `JAASLoginService`. 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. 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 ===== 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]: 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 java -jar start.jar --add-to-start=jaas
.... ----
____
[NOTE] [NOTE]
====
The top level of the distribution does not have the JAAS module enabled by default. 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. 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: Now you will have a file named `start.d/jaas.ini`, which contains:
[source,ini] [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): 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"> <New class="org.eclipse.jetty.jaas.JAASLoginService">
<Set name="Name">Test JAAS Realm</Set> <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/DataSourceLoginModule.html[`org.eclipse.jetty.jaas.spi.DataSourceLoginModule`]
* link:{JDURL}/org/eclipse/jetty/jaas/spi/LdapLoginModule.html[`org.eclipse.jetty.jaas.ldap.LdapLoginModule`] * link:{JDURL}/org/eclipse/jetty/jaas/spi/LdapLoginModule.html[`org.eclipse.jetty.jaas.ldap.LdapLoginModule`]
____
[NOTE] [NOTE]
====
Passwords can be stored in clear text, obfuscated or checksummed. 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. 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]. See more on this under the Configuration section on link:#configuring-security-secure-passwords[securing passwords].
____ ====
===== JDBCLoginModule ===== JDBCLoginModule
The `JDBCLoginModule` stores user passwords and roles in a database that are accessed via JDBC calls. 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. 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: Here is an example:
[source, java, subs="{sub-order}"] [source, java]
---- ----
public class FooLoginModule extends AbstractLoginModule 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. 1. Create a base directory anywhere.
+ +
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[/home/user]$ mkdir my-base [/home/user]$ mkdir my-base
[/home/user]$ cd my-base [/home/user]$ cd my-base
.... ----
2. Add the modules for SSL, HTTP, and webapp deployment. 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. 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 [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 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 COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
MKDIR : ${jetty.base}/webapps MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified INFO : Base directory was modified
.... ----
3. Look at your directory. 3. Look at your directory.
+ +
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[my-base]$ ls -la [my-base]$ ls -la
total 20 total 20
drwxrwxr-x 4 user group 4096 Oct 8 06:55 ./ 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/ drwxrwxr-x 2 user group 4096 Oct 8 06:55 etc/
-rw-rw-r-- 1 user group 815 Oct 8 06:55 start.ini -rw-rw-r-- 1 user group 815 Oct 8 06:55 start.ini
drwxrwxr-x 2 user group 4096 Oct 8 06:55 webapps/ drwxrwxr-x 2 user group 4096 Oct 8 06:55 webapps/
.... ----
4. Copy your WAR files into webapps. 4. Copy your WAR files into webapps.
+ +
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[my-base]$ ls -la [my-base]$ ls -la
[my-base]$ cp ~/code/project/target/gadget.war webapps/ [my-base]$ cp ~/code/project/target/gadget.war webapps/
.... ----
5. Copy your keystore into place. 5. Copy your keystore into place.
+ +
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[my-base]$ cp ~/code/project/keystore etc/keystore [my-base]$ cp ~/code/project/keystore etc/keystore
.... ----
6. Edit the `start.ini` to configure your SSL settings. 6. Edit the `start.ini` to configure your SSL settings.
+ +
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[my-base]$ cat start.ini [my-base]$ cat start.ini
.... ----
7. Initialize module ssl. 7. Initialize module ssl.
+ +
.... ----
--module=ssl --module=ssl
.... ----
8. Define the port to use for secure redirection. 8. Define the port to use for secure redirection.
+ +
.... ----
jetty.secure.port=8443 jetty.secure.port=8443
.... ----
9. Set up a demonstration keystore and truststore. 9. Set up a demonstration keystore and truststore.
+ +
.... ----
jetty.keystore=etc/keystore jetty.keystore=etc/keystore
jetty.truststore=etc/keystore jetty.truststore=etc/keystore
.... ----
10. Set the demonstration passwords. 10. Set the demonstration passwords.
+ +
.... ----
jetty.keystore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4 jetty.keystore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
jetty.keymanager.password=OBF:1u2u1wml1z7s1z7a1wnl1u2g jetty.keymanager.password=OBF:1u2u1wml1z7s1z7a1wnl1u2g
jetty.truststore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4 jetty.truststore.password=OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
.... ----
11. Initialize the module server. 11. Initialize the module server.
+ +
.... ----
--module=server --module=server
threads.min=10 threads.min=10
threads.max=200 threads.max=200
@ -144,24 +144,24 @@ threads.timeout=60000
#jetty.host=myhost.com #jetty.host=myhost.com
jetty.dump.start=false jetty.dump.start=false
jetty.dump.stop=false jetty.dump.stop=false
.... ----
12. Initialize module http. 12. Initialize module http.
+ +
.... ----
--module=http --module=http
jetty.http.port=8080 jetty.http.port=8080
http.timeout=30000 http.timeout=30000
.... ----
13. Initialize module deploy. 13. Initialize module deploy.
+ +
.... ----
--module=deploy --module=deploy
.... ----
Look at the configuration you have at this point. 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 [my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-config
Java Environment: Java Environment:
@ -229,17 +229,17 @@ Jetty Active XMLs:
${jetty.home}/etc/jetty-http.xml ${jetty.home}/etc/jetty-http.xml
${jetty.home}/etc/jetty-ssl.xml ${jetty.home}/etc/jetty-ssl.xml
${jetty.home}/etc/jetty-deploy.xml ${jetty.home}/etc/jetty-deploy.xml
.... ----
Now start Jetty. Now start Jetty.
[source, screen, subs="{sub-order}"] [source, screen]
.... ----
[my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar [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.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.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} 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-ssl-config]]
==== Reviewing the Configuration ==== 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: 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 [my-base]$ java -jar /home/user/jetty-distribution-{VERSION}/start.jar --list-modules
Jetty All Available Modules: Jetty All Available Modules:
@ -440,7 +440,7 @@ Jetty Active Module Tree:
+ Module: ssl [enabled] + Module: ssl [enabled]
+ Module: webapp [transitive] + Module: webapp [transitive]
+ Module: deploy [enabled] + 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. 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: 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 [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`. This adds the `--module=` lines and associated properties (the parameterized values mentioned above), to your `start.ini`.
____
[IMPORTANT] [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. 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. 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. 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}`. 1. Download and unpack Jetty into `/home/user/jetty-distribution-{VERSION}`.
2. Go to your base directory and just use the distribution, no editing. 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 [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`. * 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. These can be found in the `${jetty.home}/etc/` directory.
* We have parameterized all of the configurable values in those XMLs. * 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: 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 [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. Just because the JARs exist on disk does not mean that they are in use.
The configuration controls what is used. 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. Notice that only a subset of the JARs from the distribution are in use.
The modules you have enabled determine that subset. 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 [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