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

Improvements to the Jetty documentation. 

Documented the Jetty start mechanism.

Reorganized the documentation to look better on the TOC.

Improved JettyIncludeExtension to support replacements, deletions and callouts.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2021-02-10 11:27:30 +01:00
parent 68790d861c
commit 29d48b0de5
37 changed files with 1339 additions and 1715 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
documentation/jetty-asciidoctor-extensions/src/main/java/org/eclipse/jetty/docs/JettyIncludeExtension.java
View File

@ -13,12 +13,16 @@
package org.eclipse.jetty.docs; package org.eclipse.jetty.docs;
import java.nio.file.Files;
import java.nio.file.Path; import java.nio.file.Path;
import java.util.List;
import java.util.Map; import java.util.Map;
import java.util.concurrent.TimeUnit; import java.util.concurrent.TimeUnit;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.regex.Matcher; import java.util.regex.Matcher;
import java.util.regex.Pattern; import java.util.regex.Pattern;
import java.util.stream.Collectors; import java.util.stream.Collectors;
import java.util.stream.Stream;
import org.asciidoctor.Asciidoctor; import org.asciidoctor.Asciidoctor;
import org.asciidoctor.ast.Document; import org.asciidoctor.ast.Document;
@ -36,6 +40,8 @@ import org.eclipse.jetty.tests.distribution.JettyHomeTester;
* </pre> * </pre>
* <p>Available configuration parameters are:</p> * <p>Available configuration parameters are:</p>
* <dl> * <dl>
* <dt>setupModules</dt>
* <dd>Optional, specifies a comma-separated list of files to copy to {@code $JETTY_BASE/modules}.</dd>
* <dt>setupArgs</dt> * <dt>setupArgs</dt>
* <dd>Optional, specifies the arguments to use in a Jetty server <em>setup</em> run. * <dd>Optional, specifies the arguments to use in a Jetty server <em>setup</em> run.
* If missing, no Jetty server <em>setup</em> run will be executed. * If missing, no Jetty server <em>setup</em> run will be executed.
@ -44,12 +50,21 @@ import org.eclipse.jetty.tests.distribution.JettyHomeTester;
* <dd>Optional, specifies the arguments to use in a Jetty server run. * <dd>Optional, specifies the arguments to use in a Jetty server run.
* If missing, a Jetty server run will be executed with no arguments. * If missing, a Jetty server run will be executed with no arguments.
* The output produced by this run is included in the Asciidoc document.</dd> * The output produced by this run is included in the Asciidoc document.</dd>
* <dt>replace</dt>
* <dd>Optional, specifies a comma-separated pair where the first element is a regular
* expression and the second is the string replacement.</dd>
* <dt>delete</dt>
* <dd>Optional, specifies a regular expression that when matched deletes the line</dd>
* <dt>highlight</dt> * <dt>highlight</dt>
* <dd>Optional, specifies a regular expression that matches lines that should be highlighted. * <dd>Optional, specifies a regular expression that matches lines that should be highlighted.
* If missing, no line will be highlighted. * If missing, no line will be highlighted.
* If the regular expression contains capturing groups, only the text matching * If the regular expression contains capturing groups, only the text matching
* the groups is highlighted, not the whole line. * the groups is highlighted, not the whole line.
* </dd> * </dd>
* <dt>callouts</dt>
* <dd>Optional, specifies a comma-separated pair where the first element is a callout
* pattern, and the second element is a comma-separated list of regular expressions,
* each matching a single line, that get a callout added at the end of the line.</dd>
* </dl> * </dl>
* *
* @see JettyHomeTester * @see JettyHomeTester
@ -74,14 +89,27 @@ public class JettyIncludeExtension implements ExtensionRegistry
{ {
try try
{ {
Path projectPath = Path.of((String)document.getAttribute("projectdir")); Path jettyDocsPath = Path.of((String)document.getAttribute("project.basedir"));
Path jettyHome = projectPath.resolve("jetty-home/target/jetty-home").normalize(); Path jettyHome = jettyDocsPath.resolve("../../jetty-home/target/jetty-home").normalize();
JettyHomeTester jetty = JettyHomeTester.Builder.newInstance() JettyHomeTester jetty = JettyHomeTester.Builder.newInstance()
.jettyHome(jettyHome) .jettyHome(jettyHome)
.mavenLocalRepository((String)document.getAttribute("mavenrepository")) .mavenLocalRepository((String)document.getAttribute("maven.local.repo"))
.build(); .build();
String setupModules = (String)attributes.get("setupModules");
if (setupModules != null)
{
Path jettyBaseModules = jetty.getJettyBase().resolve("modules");
Files.createDirectories(jettyBaseModules);
String[] modules = setupModules.split(",");
for (String module : modules)
{
Path sourcePath = jettyDocsPath.resolve(module.trim());
Files.copy(sourcePath, jettyBaseModules.resolve(sourcePath.getFileName()));
}
}
String setupArgs = (String)attributes.get("setupArgs"); String setupArgs = (String)attributes.get("setupArgs");
if (setupArgs != null) if (setupArgs != null)
{ {
@ -97,7 +125,7 @@ public class JettyIncludeExtension implements ExtensionRegistry
try (JettyHomeTester.Run run = jetty.start(args.split(" "))) try (JettyHomeTester.Run run = jetty.start(args.split(" ")))
{ {
run.awaitFor(15, TimeUnit.SECONDS); run.awaitFor(15, TimeUnit.SECONDS);
String output = captureOutput(attributes, jetty, run); String output = captureOutput(attributes, run);
reader.push_include(output, "jettyHome_run", target, 1, attributes); reader.push_include(output, "jettyHome_run", target, 1, attributes);
} }
} }
@ -108,62 +136,123 @@ public class JettyIncludeExtension implements ExtensionRegistry
} }
} }
private String captureOutput(Map<String, Object> attributes, JettyHomeTester jetty, JettyHomeTester.Run run) private String captureOutput(Map<String, Object> attributes, JettyHomeTester.Run run)
{ {
String highlight = (String)attributes.get("highlight"); Stream<String> lines = run.getLogs().stream()
return run.getLogs().stream() .map(line -> redactPath(line, System.getProperty("java.home"), "/path/to/java.home"))
.map(line -> redactPath(line, jetty.getJettyHome(), "/path/to/jetty.home")) .map(line -> redactPath(line, run.getConfig().getMavenLocalRepository(), "/path/to/maven.repository"))
.map(line -> redactPath(line, jetty.getJettyBase(), "/path/to/jetty.base")) .map(line -> redactPath(line, run.getConfig().getJettyHome().toString(), "/path/to/jetty.home"))
.map(this::denoteLineStart) .map(line -> redactPath(line, run.getConfig().getJettyBase().toString(), "/path/to/jetty.base"));
.map(line -> highlight(line, highlight)) lines = replace(lines, (String)attributes.get("replace"));
.collect(Collectors.joining(System.lineSeparator())); lines = delete(lines, (String)attributes.get("delete"));
lines = denoteLineStart(lines);
lines = highlight(lines, (String)attributes.get("highlight"));
lines = callouts(lines, (String)attributes.get("callouts"));
return lines.collect(Collectors.joining(System.lineSeparator()));
} }
private String redactPath(String line, Path path, String replacement) private String redactPath(String line, String target, String replacement)
{ {
return line.replaceAll(path.toString(), replacement); return line.replace(target, replacement);
} }
private String denoteLineStart(String line) private Stream<String> replace(Stream<String> lines, String replace)
{
if (replace == null)
return lines;
// Format is: (regexp,replacement).
String[] parts = replace.split(",");
String regExp = parts[0];
String replacement = parts[1].replace("\\n", "\n");
return lines.flatMap(line -> Stream.of(line.replaceAll(regExp, replacement).split("\n")));
}
private Stream<String> delete(Stream<String> lines, String delete)
{
if (delete == null)
return lines;
Pattern regExp = Pattern.compile(delete);
return lines.filter(line -> !regExp.matcher(line).find())
.filter(line -> !line.contains("jetty-halt.xml"));
}
private Stream<String> denoteLineStart(Stream<String> lines)
{ {
// Matches lines that start with a date such as "2020-01-01 00:00:00.000:". // Matches lines that start with a date such as "2020-01-01 00:00:00.000:".
Pattern lineStart = Pattern.compile("(^[^:]+:[^:]+:[^:]+:)"); Pattern regExp = Pattern.compile("(^\\d{4}[^:]+:[^:]+:[^:]+:)");
Matcher matcher = lineStart.matcher(line); return lines.map(line ->
if (!matcher.find()) {
return line; Matcher matcher = regExp.matcher(line);
return "**" + matcher.group(1) + "**" + line.substring(matcher.end(1)); if (!matcher.find())
return line;
return "**" + matcher.group(1) + "**" + line.substring(matcher.end(1));
});
} }
private String highlight(String line, String regExp) private Stream<String> highlight(Stream<String> lines, String highlight)
{ {
if (regExp == null) if (highlight == null)
return line; return lines;
Matcher matcher = Pattern.compile(regExp).matcher(line); Pattern regExp = Pattern.compile(highlight);
if (!matcher.find()) return lines.map(line ->
return line;
int groupCount = matcher.groupCount();
// No capturing groups, highlight the whole line.
if (groupCount == 0)
return "##" + line + "##";
// Highlight the capturing groups.
StringBuilder result = new StringBuilder(line.length() + 4 * groupCount);
int start = 0;
for (int groupIndex = 1; groupIndex <= groupCount; ++groupIndex)
{ {
int matchBegin = matcher.start(groupIndex); Matcher matcher = regExp.matcher(line);
result.append(line, start, matchBegin); if (!matcher.find())
result.append("##"); return line;
int matchEnd = matcher.end(groupIndex);
result.append(line, matchBegin, matchEnd); int groupCount = matcher.groupCount();
result.append("##");
start = matchEnd; // No capturing groups, highlight the whole line.
} if (groupCount == 0)
result.append(line, start, line.length()); return "##" + line + "##";
return result.toString();
// Highlight the capturing groups.
StringBuilder result = new StringBuilder(line.length() + 4 * groupCount);
int start = 0;
for (int groupIndex = 1; groupIndex <= groupCount; ++groupIndex)
{
int matchBegin = matcher.start(groupIndex);
result.append(line, start, matchBegin);
result.append("##");
int matchEnd = matcher.end(groupIndex);
result.append(line, matchBegin, matchEnd);
result.append("##");
start = matchEnd;
}
result.append(line, start, line.length());
return result.toString();
});
}
private Stream<String> callouts(Stream<String> lines, String callouts)
{
if (callouts == null)
return lines;
// Format is (prefix$Nsuffix,regExp...).
String[] parts = callouts.split(",");
String calloutPattern = parts[0];
List<Pattern> regExps = Stream.of(parts)
.skip(1)
.map(Pattern::compile)
.collect(Collectors.toList());
AtomicInteger index = new AtomicInteger();
return lines.map(line ->
{
int regExpIndex = index.get();
if (regExpIndex == regExps.size())
return line;
Pattern regExp = regExps.get(regExpIndex);
if (!regExp.matcher(line).find())
return line;
int calloutIndex = index.incrementAndGet();
return line + calloutPattern.replace("$N", String.valueOf(calloutIndex));
});
} }
} }
} }

4
documentation/jetty-documentation/pom.xml
View File

@ -44,8 +44,8 @@
<require>asciidoctor-diagram</require> <require>asciidoctor-diagram</require>
</requires> </requires>
<attributes> <attributes>
<MAVENREPOSITORY>${settings.localRepository}</MAVENREPOSITORY> <project.basedir>${project.basedir}</project.basedir>
<PROJECTDIR>${project.basedir}/../..</PROJECTDIR> <maven.local.repo>${settings.localRepository}</maven.local.repo>
<JDURL>http://www.eclipse.org/jetty/javadoc/${project.version}</JDURL> <JDURL>http://www.eclipse.org/jetty/javadoc/${project.version}</JDURL>
<JXURL>http://download.eclipse.org/jetty/stable-9/xref</JXURL> <JXURL>http://download.eclipse.org/jetty/stable-9/xref</JXURL>
<SRCDIR>${basedir}/..</SRCDIR> <SRCDIR>${basedir}/..</SRCDIR>

5
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/chapter.adoc
View File

@ -14,13 +14,8 @@
[[startup]] [[startup]]
== Starting Jetty == Starting Jetty
include::startup-overview.adoc[]
include::start-jar.adoc[]
include::startup-base-vs-home.adoc[]
include::startup-classpath.adoc[]
include::startup-modules.adoc[] include::startup-modules.adoc[]
include::custom-modules.adoc[] include::custom-modules.adoc[]
include::startup-xml-config.adoc[] include::startup-xml-config.adoc[]
include::startup-unix-service.adoc[] include::startup-unix-service.adoc[]
include::startup-windows-service.adoc[] include::startup-windows-service.adoc[]
include::startup-jpms.adoc[]

323
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-base-vs-home.adoc
View File

@ -1,323 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[startup-base-and-home]]
=== Managing Jetty Base and Jetty Home
Instead of managing multiple Jetty implementations out of several different distribution locations, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment(s) (known as `${jetty.base}`).
In addition to easy management of multiple server instances, is allows for quick, drop-in upgrades of Jetty.
There should always only be *one* Jetty Home (per version of Jetty), but there can be multiple Jetty Base directories that reference it.
Jetty Base::
* Also known as the `${jetty.base}` property.
* This is the location for your configurations and customizations to the Jetty distribution.
Jetty Home::
* Also known as the `${jetty.home}` property.
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
____
[IMPORTANT]
Jetty Home should always be treated as a standard of truth.
All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.
____
[[base-vs-home-resolution]]
Potential configuration is resolved from these 2 directory locations.
When Jetty starts up in processes configuration from them as follows:
Check Jetty Base First::
If the referenced configuration exists, relative to the defined Jetty base, it is used.
Check Jetty Home Second::
If the referenced configuration exists, relative to the defined Jetty home, it is used.
Use java.io.File(String pathname) Logic::
Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor.In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).
For more details on how startup with start.jar works, see link:#executing-startjar[Using start.jar: Executing]
[[demo-base]]
==== Demo-Base in the Jetty Distribution
The Jetty Distribution comes with an example `${jetty.base}` which enables the various demonstration webapps and server configurations.
[source, screen, subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ ls -la
total 496
drwxrwxr-x 11 user group 4096 Oct 8 15:23 ./
drwxr-xr-x 14 user group 4096 Oct 8 13:04 ../
drwxrwxr-x 2 user group 4096 Oct 8 06:54 bin/
drwxrwxr-x 6 user group 4096 Oct 8 06:54 demo-base/
drwxrwxr-x 2 user group 4096 Oct 11 15:14 etc/
drwxrwxr-x 11 user group 4096 Oct 8 06:54 lib/
-rw-rw-r-- 1 user group 30012 Sep 30 19:55 license-eplv10-aslv20.html
drwxrwxr-x 2 user group 4096 Oct 8 06:54 logs/
drwxrwxr-x 2 user group 4096 Oct 8 06:54 modules/
-rw-rw-r-- 1 user group 6262 Sep 30 19:55 notice.html
-rw-rw-r-- 1 user group 1249 Sep 30 19:55 README.TXT
drwxrwxr-x 2 user group 4096 Oct 8 06:54 resources/
drwxrwxr-x 2 user group 4096 Oct 8 06:54 start.d/
-rw-rw-r-- 1 user group 1780 Sep 30 19:55 start.ini
-rw-rw-r-- 1 user group 71921 Sep 30 19:55 start.jar
-rw-rw-r-- 1 user group 336468 Sep 30 19:55 VERSION.txt
drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
[jetty-home-{VERSION}]$ cd demo-base
[my-base]$ java -jar /path/to/jetty-home/start.jar
2013-10-16 09:08:47.800:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
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/jetty-home-{VERSION}/demo-base/webapps/] at interval 1
2013-10-16 09:08:48.072:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
...
....
If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration by using the `--list-config` command.
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-config
Java Environment:
-----------------
java.home=/usr/lib/jvm/jdk-7u21-x64/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.92-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
user.dir = /home/user/jetty-home-{VERSION}
user.language = en
user.country = US
Jetty Environment:
-----------------
jetty.home=/home/user/jetty-home-{VERSION}
jetty.tag.version = master
jetty.base=/home/user/jetty-home-{VERSION}/demo-base
jetty.version={VERSION}
Config Search Order:
--------------------
<command-line>
${jetty.base} -> /home/user/jetty-home-{VERSION}/demo-base
${jetty.home} -> /home/user/Desktop/jetty-home-{VERSION}
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
jetty.base = /home/user/jetty-home-{VERSION}/demo-base
jetty.home = /home/user/jetty-home-{VERSION}
Properties:
-----------
demo.realm = etc/realm.properties
https.port = 8443
https.timeout = 30000
jaas.login.conf = etc/login.conf
jetty.dump.start = false
jetty.dump.stop = false
jetty.keymanager.password = OBF:1u2u1wml1z7s1z7a1wnl1u2g
jetty.keystore = etc/keystore
jetty.keystore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
jetty.http.port = 8080
jetty.secure.port = 8443
jetty.truststore = etc/keystore
jetty.truststore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
org.eclipse.jetty.websocket.javax = false
threads.max = 200
threads.min = 10
threads.timeout = 60000
Jetty Server Classpath:
-----------------------
Version Information on 42 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: {VERSION} | ${jetty.home}/lib/jetty-client-{VERSION}.jar
1: 1.4.1.v201005082020 | ${jetty.base}/lib/ext/javax.mail.glassfish-1.4.1.v201005082020.jar
2: {VERSION} | ${jetty.base}/lib/ext/test-mock-resources-{VERSION}.jar
3: (dir) | ${jetty.home}/resources
4: 3.1.0 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
6: {VERSION} | ${jetty.home}/lib/jetty-http-{VERSION}.jar
7: {VERSION} | ${jetty.home}/lib/jetty-continuation-{VERSION}.jar
8: {VERSION} | ${jetty.home}/lib/jetty-server-{VERSION}.jar
9: {VERSION} | ${jetty.home}/lib/jetty-xml-{VERSION}.jar
10: {VERSION} | ${jetty.home}/lib/jetty-util-{VERSION}.jar
11: {VERSION} | ${jetty.home}/lib/jetty-io-{VERSION}.jar
12: {VERSION} | ${jetty.home}/lib/jetty-jaas-{VERSION}.jar
13: {VERSION} | ${jetty.home}/lib/jetty-jndi-{VERSION}.jar
14: 1.1.0.v201105071233 | ${jetty.home}/lib/jndi/javax.activation-1.1.0.v201105071233.jar
15: 1.4.1.v201005082020 | ${jetty.home}/lib/jndi/javax.mail.glassfish-1.4.1.v201005082020.jar
16: 1.3 | ${jetty.home}/lib/jndi/javax.transaction-api-1.3.jar
17: {VERSION} | ${jetty.home}/lib/jetty-rewrite-{VERSION}.jar
18: {VERSION} | ${jetty.home}/lib/jetty-security-{VERSION}.jar
19: {VERSION} | ${jetty.home}/lib/jetty-servlet-{VERSION}.jar
20: 3.0.0 | ${jetty.home}/lib/jsp/javax.el-3.0.0.jar
21: 1.2.0.v201105211821 | ${jetty.home}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
22: 2.3.2 | ${jetty.home}/lib/jsp/javax.servlet.jsp-2.3.2.jar
23: 2.3.1 | ${jetty.home}/lib/jsp/javax.servlet.jsp-api-2.3.1.jar
24: 2.3.3 | ${jetty.home}/lib/jsp/jetty-jsp-jdt-2.3.3.jar
25: 1.2.0.v201112081803 | ${jetty.home}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
26: 3.8.2.v20130121-145325 | ${jetty.home}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
27: {VERSION} | ${jetty.home}/lib/jetty-plus-{VERSION}.jar
28: {VERSION} | ${jetty.home}/lib/jetty-webapp-{VERSION}.jar
29: {VERSION} | ${jetty.home}/lib/jetty-annotations-{VERSION}.jar
30: 4.1 | ${jetty.home}/lib/annotations/asm-4.1.jar
31: 4.1 | ${jetty.home}/lib/annotations/asm-commons-4.1.jar
32: 1.2 | ${jetty.home}/lib/annotations/javax.annotation-api-1.2.jar
33: {VERSION} | ${jetty.home}/lib/jetty-deploy-{VERSION}.jar
34: 1.0 | ${jetty.home}/lib/websocket/javax.websocket-api-1.0.jar
35: {VERSION} | ${jetty.home}/lib/websocket/websocket-javax-client-{VERSION}.jar
36: {VERSION} | ${jetty.home}/lib/websocket/websocket-javax-server-{VERSION}.jar
37: {VERSION} | ${jetty.home}/lib/websocket/websocket-api-{VERSION}.jar
38: {VERSION} | ${jetty.home}/lib/websocket/websocket-client-{VERSION}.jar
39: {VERSION} | ${jetty.home}/lib/websocket/websocket-common-{VERSION}.jar
40: {VERSION} | ${jetty.home}/lib/websocket/websocket-server-{VERSION}.jar
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-plus.xml
${jetty.home}/etc/jetty-annotations.xml
${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.xml
${jetty.home}/etc/jetty-ssl.xml
${jetty.home}/etc/jetty-ssl-context.xml
${jetty.home}/etc/jetty-https.xml
${jetty.home}/etc/jetty-jaas.xml
${jetty.home}/etc/jetty-rewrite.xml
${jetty.base}/etc/demo-rewrite-rules.xml
${jetty.base}/etc/test-realm.xml
....
The `--list-config` command line option displays what the configuration will look like when starting Jetty.
This includes information on the Java environment to the system properties, the classpath and the Active Jetty IoC XML used to build up the Jetty server configuration.
Of note, is that the output will make it known where the configuration elements came from, be it in either in `${jetty.home}` or `${jetty.base}`.
If you look at the `${jetty.base}/start.ini` you will see a layout similar to below.
[source, screen, subs="{sub-order}"]
....
[my-base]$ cat start.ini
# Enable security via jaas, and configure it
--module=jaas
jaas.login.conf=etc/login.conf
# Enable rewrite examples
--module=rewrite
etc/demo-rewrite-rules.xml
# Websocket chat examples needs websocket enabled
# Don't start for all contexts (set to true in test.xml context)
org.eclipse.jetty.websocket.javax=false
--module=websocket
# Create and configure the test realm
etc/test-realm.xml
demo.realm=etc/realm.properties
# Initialize module server
--module=server
threads.min=10
threads.max=200
threads.timeout=60000
jetty.dump.start=false
jetty.dump.stop=false
--module=deploy
--module=jsp
--module=ext
--module=resources
--module=client
--module=annotations
....
In this example, `${jetty.base}/start.ini` is the main startup configuration entry point for Jetty.
You will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the `etc/demo-rewrite-rules.xml` and `etc/test-realm.xml` files)
When Jetty's `start.jar` resolves the entries in the `start.ini`, it will follow the link:#base-vs-home-resolution[resolution rules above].
For example, the reference to `etc/demo-rewrite-rules.xml` was found in `${jetty.base}/etc/demo-rewrite-rules.xml`.
==== Declaring Jetty Base
The Jetty distribution's `start.jar` is the component that manages the behavior of this separation.
The Jetty `start.jar` and XML files always assume that both `${jetty.home}` and `${jetty.base}` are defined when starting Jetty.
You can opt to manually define the `${jetty.home}` and `${jetty.base}` directories, such as this:
[source, screen, subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ pwd
/home/user/jetty-home-{VERSION}
[jetty-home-{VERSION}]$ java -jar start.jar \
jetty.home=/home/user/jetty-home-{VERSION} \
jetty.base=/home/user/my-base
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
Alternately, you can declare one directory and let the other one be discovered.
The following example uses default discovery of `${jetty.home}` by using the parent directory of wherever `start.jar` itself is, and a manual declaration of `${jetty.base}`.
[source, screen, subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ pwd
/home/user/jetty-home-{VERSION}
[jetty-home-{VERSION}]$ java -jar start.jar jetty.base=/home/user/my-base
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
But Jetty recommends that you always start Jetty from the directory that is your `${jetty.base}` and starting Jetty by referencing
the `start.jar` in your `{$jetty.home}` remotely.
The following demonstrates this by allowing default discovery of `${jetty.home}` via locating the `start.jar`, and using the `user.dir` System Property for `${jetty.base}`.
[source,screen,subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ pwd
/home/user/jetty-home-{VERSION}
[jetty-home-{VERSION}]$ cd /home/user/my-base
[my-base]$ java -jar /path/to/jetty-home/start.jar
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-{VERSION}
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...
....
____
[IMPORTANT]
Be aware of the `user.dir` system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property.
It is strongly recommended that you sit in the directory that is your desired `${jetty.base}` when starting Jetty to have consistent behavior and use of the `user.dir` system property.
____

105
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-classpath.adoc
View File

@ -1,105 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[startup-classpath]]
=== Managing Server Classpath
Jetty Server Classpath is determined by a combination of factors.
The java.class.path System Property::
If you start Jetty with a JVM specified classpath, then Jetty will use the java.class.path System Property to populate the initial classpath.
Module specified Libraries::
The module system declares various libraries that are required for that module to operate.
These module defined libraries are added to the Jetty Server classpath when any module is activated with library declarations.
Command Line Libraries::
The command line option `--lib=<path>` can be used as a final means to add arbitrary entries to the Jetty Server classpath.
Of special note, there are 2 structural modules defined to ease some of this for you.
--module=ext::
The `ext` module will enable the `lib/ext/*.jar` logic.
+
If this module is activated, then all jar files found in the lib/ext/ paths will be automatically added to the Jetty Server Classpath.
--module=resources::
The `resources` module will add the `resources/` directory the classpath.
+
If you have 3rd party libraries that lookup resources from the classpath, put your files in here.
+
Logging libraries often have classpath lookup of their configuration files (eg: `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so this would be the ideal setup for this sort of configuration demand.
____
[NOTE]
Both the `ext` and `resources` modules declare relative paths that follow link:#base-vs-home-resolution[Jetty Base and Jetty Home path resolution rules].
____
==== Interrogating the Server Classpath
The Jetty `start.jar` has the ability to resolve the classpath from the command line, modules and configuration, and to list the classpath entries it will use to start jetty.
The `--list-classpath` command line option is used as such.
(Demonstrated with the link:#demo-base[demo-base from the Jetty Distribution])
[source,screen,subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar --list-classpath
Jetty Server Classpath:
-----------------------
Version Information on 42 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: {VERSION} | ${jetty.home}/lib/jetty-client-{VERSION}.jar
1: 1.4.1.v201005082020 | ${jetty.base}/lib/ext/javax.mail.glassfish-1.4.1.v201005082020.jar
2: {VERSION} | ${jetty.base}/lib/ext/test-mock-resources-{VERSION}.jar
3: (dir) | ${jetty.home}/resources
4: 4.0.2 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
6: {VERSION} | ${jetty.home}/lib/jetty-http-{VERSION}.jar
7: {VERSION} | ${jetty.home}/lib/jetty-continuation-{VERSION}.jar
8: {VERSION} | ${jetty.home}/lib/jetty-server-{VERSION}.jar
9: {VERSION} | ${jetty.home}/lib/jetty-xml-{VERSION}.jar
10: {VERSION} | ${jetty.home}/lib/jetty-util-{VERSION}.jar
11: {VERSION} | ${jetty.home}/lib/jetty-io-{VERSION}.jar
12: {VERSION} | ${jetty.home}/lib/jetty-jaas-{VERSION}.jar
13: {VERSION} | ${jetty.home}/lib/jetty-jndi-{VERSION}.jar
14: 1.1.0.v201105071233 | ${jetty.home}/lib/jndi/javax.activation-1.1.0.v201105071233.jar
15: 1.4.1.v201005082020 | ${jetty.home}/lib/jndi/javax.mail.glassfish-1.4.1.v201005082020.jar
16: 1.3 | ${jetty.home}/lib/jndi/javax.transaction-api-1.3.jar
17: {VERSION} | ${jetty.home}/lib/jetty-rewrite-{VERSION}.jar
18: {VERSION} | ${jetty.home}/lib/jetty-security-{VERSION}.jar
19: {VERSION} | ${jetty.home}/lib/jetty-servlet-{VERSION}.jar
20: 3.0.0 | ${jetty.home}/lib/jsp/javax.el-3.0.0.jar
21: 1.2.0.v201105211821 | ${jetty.home}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
22: 2.3.2 | ${jetty.home}/lib/jsp/javax.servlet.jsp-2.3.2.jar
23: 2.3.1 | ${jetty.home}/lib/jsp/javax.servlet.jsp-api-2.3.1.jar
24: 2.3.3 | ${jetty.home}/lib/jsp/jetty-jsp-jdt-2.3.3.jar
25: 1.2.0.v201112081803 | ${jetty.home}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
26: 3.8.2.v20130121-145325 | ${jetty.home}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
27: {VERSION} | ${jetty.home}/lib/jetty-plus-{VERSION}.jar
28: {VERSION} | ${jetty.home}/lib/jetty-webapp-{VERSION}.jar
29: {VERSION} | ${jetty.home}/lib/jetty-annotations-{VERSION}.jar
30: 4.1 | ${jetty.home}/lib/annotations/asm-4.1.jar
31: 4.1 | ${jetty.home}/lib/annotations/asm-commons-4.1.jar
32: 1.2 | ${jetty.home}/lib/annotations/javax.annotation-api-1.2.jar
33: {VERSION} | ${jetty.home}/lib/jetty-deploy-{VERSION}.jar
34: 1.0 | ${jetty.home}/lib/websocket/javax.websocket-api-1.0.jar
35: {VERSION} | ${jetty.home}/lib/websocket/websocket-javax-client-{VERSION}.jar
36: {VERSION} | ${jetty.home}/lib/websocket/websocket-javax-server-{VERSION}.jar
37: {VERSION} | ${jetty.home}/lib/websocket/websocket-api-{VERSION}.jar
38: {VERSION} | ${jetty.home}/lib/websocket/websocket-client-{VERSION}.jar
39: {VERSION} | ${jetty.home}/lib/websocket/websocket-common-{VERSION}.jar
40: {VERSION} | ${jetty.home}/lib/websocket/websocket-server-{VERSION}.jar
41: {VERSION} | ${jetty.home}/lib/websocket/websocket-servlet-{VERSION}.jar
....
Of note is that an attempt is made to list the internally declared version of each artifact on the Server Classpath, which can potentially help when diagnosing classpath issues.

184
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-jpms.adoc
View File

@ -1,184 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[startup-jpms]]
=== Startup using the Java Platform Module System (JPMS)
Jetty modules also act as automatic https://en.wikipedia.org/wiki/Java_Platform_Module_System[JPMS] modules via the `Automatic-Module-Name` attribute in the jar's `MANIFEST.MF` file.
This makes possible to run Jetty from the module-path, rather than the class-path.
We recommend using JDK 11 or greater due to the fact that JDK 11 removed all the "enterprise" modules from the JDK,
and therefore it guarantees a more stable platform to base your application's dependencies on.
The classes in these "enterprise" modules were bundled with JDK 8, and present in "enterprise" modules in JDK 9 and JDK 10.
With JDK 11, these "enterprise" classes are either not available in the JDK (because their corresponding module was removed), or they are present in a different module.
Because some of these "enterprise" classes are required by Jetty or by applications running in Jetty, it is better to use a stable source for those classes - in this case by using JDK 11
or greater, and explicitly referencing the "enterprise" classes as dependencies, rather than assuming they are bundled with the JDK.
[[jpms-module-path]]
==== Starting Jetty on the module-path
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}"]
....
$ mkdir my-jetty-base
$ cd my-jetty-base
$ java -jar $JETTY_HOME/start.jar --add-to-start=http
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : http initialized in ${jetty.base}/start.ini
INFO : threadpool transitively enabled, ini template available with --add-to-start=threadpool
INFO : Base directory was modified
$ java -jar $JETTY_HOME/start.jar --jpms
....
The example above creates a link:#startup-base-and-home[Jetty base directory] and enables the `http` module using the `--add-to-start` command.
The server then starts Jetty on the module-path using the `--jpms` option.
----
[NOTE]
When running on the module-path using the `--jpms` option, the Jetty start mechanism will fork a second JVM passing it the right JVM options to run on the module-path.
You will have two JVMs running: one that runs `start.jar` and one that runs Jetty on the module-path.
----
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}"]
....
$ java -jar $JETTY_HOME/start.jar --jpms --dry-run
....
This will give an output looking something like this (broken in sections for clarity):
[source, screen, subs="{sub-order}"]
....
/opt/openjdk-11+28/bin/java
--module-path /opt/jetty/lib/jetty-servlet-api-4.0.2.jar:/opt/jetty/lib/jetty-http-{VERSION}.jar:...
--module org.eclipse.jetty.xml/org.eclipse.jetty.xml.XmlConfiguration /opt/jetty/etc/jetty-threadpool.xml /opt/jetty/etc/jetty.xml ...
....
The `--module-path` option specifies the list of Jetty jars.
This list depends on the Jetty modules that have been enabled via the link:#startup-modules[`--add-to-start`] command.
The `--module` option tells the JVM to run main class `XmlConfiguration` from the `org.eclipse.jetty.xml` module, with the given XML files as program arguments.
When the JVM starts, module `org.eclipse.jetty.xml` is added to the set of JPMS _root modules_; all other Jetty modules, being automatic, will be resolved and added to the module graph.
JAR files that are not modules, such as `jetty-servlet-api-4.0.2.jar`, are on the module-path and therefore will be made automatic modules by the JVM (hence the derived module name `servlet.api` for this jar, referenced by the `--patch-module` command line option above).
[[jpms-advanced-config]]
==== Advanced JPMS Configuration
Web applications may need additional services from the Servlet Container, such as JDBC `DataSource` references or JTA `UserTransaction` references.
For example, for JDBC it is typical to store, in JNDI, a reference to the connection pool's `DataSource` (such as `com.zaxxer.hikari.HikariDataSource`) or a reference directly to the JDBC driver's `DataSource` (`com.mysql.jdbc.jdbc2.optional.MysqlDataSource`).
Jetty needs to be able to instantiate those classes and therefore needs to be able to load those classes and all their super-classes, among which includes `javax.sql.DataSource`.
When Jetty runs on the class-path, this is easily achieved by using a link:#custom-modules[custom module]:
[source, screen, subs="{sub-order}"]
.mysql.mod
....
[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
....
However, when running on the module-path, things are quite different.
Class `javax.sql.DataSource` is in a JDK bundled module named `java.sql`, which is not automatic (it's a proper JPMS module) and it is not in the _root modules_ set.
Because it is not an automatic module, it is not added to the module graph, and therefore needs to be added explicitly using the JVM command line `--add-modules`.
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}"]
.mysql.mod
....
[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: java.sql
....
The new `[jpms]` section is only used when Jetty is started on the module-path via the `--jpms` command line option.
Assuming that `mysql-connector-java-*.jar` is a non JPMS modular jar, or an automatic JPMS modular jar, the Jetty start mechanism will add `mysql-connector-java-*.jar` to the module-path, and will add the JVM command line option `--add-modules java.sql`.
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}"]
.mysql.mod
....
[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: com.mysql.jdbc
....
The JPMS module `java.sql` does not need to be explicitly added because it would be a dependency of the `com.mysql.jdbc` module and therefore automatically added to the module graph.
The `[jpms]` section has the following format:
[source, screen, subs="{sub-order}"]
....
[jpms]
add-modules: <module name>(,<module name>)*
patch-module: <module>=<file>(:<file>)*
add-opens: <module>/<package>=<target-module>(,<target-module>)*
add-exports: <module>/<package>=<target-module>(,<target-module>)*
add-reads: <module>=<target-module>(,<target-module>)*
....
[[jpms-module-path-alternative]]
==== Alternative way to start Jetty on the module-path
The section above uses the `--jpms` command line option to start Jetty on the module-path.
An alternative way of achieving the same result is to use a Jetty module, `$JETTY_BASE/modules/jpms.mod`,
that specifies that you want to run using JPMS (and possibly add some JPMS specific configuration).
[source, screen, subs="{sub-order}"]
.jpms.mod
....
[ini]
--jpms
[jpms]
# Additional JPMS configuration.
....
The `[ini]` section is equivalent to passing the `--jpms` option to the command line.
The `[jpms]` section (see also the link:#jpms-advanced-config[advanced JPMS configuration section])
allows you specify additional JPMS configuration.
[source, screen, subs="{sub-order}"]
....
$ mkdir jetty-base-jpms
$ cd jetty-base-jpms
$ mkdir modules
# Copy the jpms.mod file above into the $JETTY_BASE/modules/ directory.
$ cp /tmp/jpms.mod modules/
# Add both the http and the jpms modules.
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,jpms
# Jetty will start on the module-path.
$ java -jar $JETTY_HOME/start.jar
....

234
documentation/jetty-documentation/src/main/asciidoc/old_docs/startup/startup-overview.adoc
View File

@ -1,234 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[startup-overview]]
=== Startup Overview
The `start.jar` bootstrap manages the startup of standalone Jetty.
It is responsible for:
Building the classpath::
The `start.jar` bootstrap builds a classpath for all the required Jetty features and their dependencies.
It builds the classpath using either the `--lib` option to `start.jar` to add an individual classpath entry, or with the `--module` option that includes all the libs and their dependencies for a module (a named Jetty feature).
Instantiating the Server Components::
The server and its components are instantiated using either Jetty IoC XML or Spring.
The Jetty server is a collection of POJOs for the server, connectors, session managers and others.
These are instantiated, injected, and wired up together in XML files, commonly one per module/feature, that are passed as arguments to `start.jar`.
Resolving Server Filesystem Locations::
The `start.jar` mechanism resolves canonical locations for the `${jetty.home}` and the `${jetty.base}` directories.
The `${jetty.home}` directory is the location of the standard distribution of Jetty.
The `${jetty.base}` directory is the location of the local server customization and configurations.
+
If you want to modify the Jetty distribution, base and home can be the same directory.
Separating the base and home directories allows the distribution to remain unmodified, with all customizations in the base directory, and thus simplifies subsequent server version upgrades.
Parameterizing the Server Configuration::
XML files primarily determine the server configuration.
Many of these files are parameterized to allow simple injection of host names, ports, passwords and more.
The `start.jar` mechanism allows you to set parameters on the command line or in properties files.
To achieve these start up mechanisms, the `start.jar` uses:
Command line arguments::
You can configure the entire server with command line arguments that specify libraries, properties and XML files.
However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.
INI files::
The `start.jar` mechanism uses the contents of the `${jetty.base}/start.ini` and `${jetty.base}/start.d/*.ini` files with each line equivalent to a `start.jar` command line argument.
This means that either a global `start.ini` file or multiple `start.d/feature.ini` files control the configuration of the server.
[NOTE]
--
It is important to chose *either* `${jetty.base}/start.ini` or `${jetty.base}/start.d/*.ini` to manage configuration.
Using both is not recommended and can lead to issues with your server.
--
Modules::
Instead of explicitly listing all the libraries, properties and XML files for a feature, the `start.jar` mechanism allows you to create modules.
A module is defined in a `modules/*.mod` file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
Thus you can use a single `--module=name` command line option as the equivalent of specifying `--lib=location`, `feature.xml` or `name=value` arguments for a feature and all its dependencies.
Modules also use their dependencies to control the ordering of libraries and XML files.
There are several module files included with the Jetty distribution that cover the most common server features, such as HTTP, HTTPS, SSL, Logging, Annotations...etc.
These module files should *only* be edited if you are making structural changes to the way the feature will perform.
For more information, refer to the section on link:#startup-modules[managing startup modules] later in this chapter.
XML Files::
XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server.
This includes all major components such as connectors, keystores, session managers, and data sources.
Typically there are one or more XML files per module, and these are defined and activated in the corresponding module.
==== Startup Example
The simplest way to start Jetty is via the `start.jar` mechanism using the following Java command line:
[source, screen, subs="{sub-order}"]
....
[user]$ cd jetty-home-{VERSION}
[jetty-home-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=8080
....
This command uses the `start.jar` mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the `http` module.
Specifically the `http` module is defined in the `${jetty.home}/modules/http.mod` file, and includes the following:
[source, screen, subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ cat modules/http.mod
[depend]
server
[xml]
etc/jetty-http.xml
[ini-template]
jetty.http.port=8080
http.timeout=30000
....
The `http` module declares that `http` depends on the server module, uses the `jetty-http.xml` file, and can be parameterized with `jetty.http.port` and `http.timeout` parameters.
The INI-template section is not actually used by the command above, so the `jetty.http.port` must still be defined on the command line.
Following the server dependency, the `${jetty.home}/modules/server.mod` file includes:
[source, screen, subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ cat modules/server.mod
[lib]
lib/jetty-servlet-api-4.0.2.jar
lib/jetty-http-${jetty.version}.jar
lib/jetty-server-${jetty.version}.jar
lib/jetty-xml-${jetty.version}.jar
lib/jetty-util-${jetty.version}.jar
lib/jetty-io-${jetty.version}.jar
[xml]
etc/jetty.xml
[ini-template]
threads.min=10
threads.max=200
....
The `server` module declares the libraries the server needs and to use `jetty.xml` file.
The combined metadata of the `http` and `server` modules results in `start.jar` generating the effective Java command line required to start Jetty.
Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:
[source, screen, subs="{sub-order}"]
....
[jetty-home-{VERSION}]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config
Java Environment:
-----------------
java.home=/user/lib/jvm/jdk-7u21-x64/jre
java.vm.vendor=Oracle Corporation
java.vm.version=23.25-b01
java.vm.name=Java HotSpot(TM) 64-Bit Server VM
java.vm.info=mixed mode
java.runtime.name=Java(TM) SE Runtime Environment
java.runtime.version=1.7.0_25-b15
java.io.tmpdir=/tmp
Jetty Environment:
-----------------
jetty.home=/opt/jetty/jetty-home-{VERSION}
jetty.base=/opt/jetty/jetty-home-{VERSION}
jetty.version={VERSION}
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
jetty.home = /opt/jetty/jetty-home-{VERSION}
jetty.base = /opt/jetty/jetty-home-{VERSION}
Properties:
-----------
jetty.http.port = 9099
Jetty Server Classpath:
-----------------------
Version Information on 7 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: 3.1.0 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
2: {VERSION} | ${jetty.home}/lib/jetty-http-{VERSION}.jar
3: {VERSION} | ${jetty.home}/lib/jetty-server-{VERSION}.jar
4: {VERSION} | ${jetty.home}/lib/jetty-xml-{VERSION}.jar
5: {VERSION} | ${jetty.home}/lib/jetty-util-{VERSION}.jar
6: {VERSION} | ${jetty.home}/lib/jetty-io-{VERSION}.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-http.xml
....
This represents the entirety of the configuration that is applied to start Jetty.
If you don't want to use the `start.jar` bootstrap, you can start Jetty using a traditional Java command line.
The following is the equivalent Java command line for what the `start.jar` bootstrap above performs.
[source, screen, subs="{sub-order}"]
....
[user]$ cd jetty-home-{VERSION}
[jetty-home-{VERSION}]$ echo jetty.http.port=8080 > /tmp/jetty.properties
[jetty-home-{VERSION}]$ export JETTY_HOME=`pwd`
[jetty-home-{VERSION}]$ export JETTY_BASE=`pwd`
[jetty-home-{VERSION}]$ export JETTY_VERSION="${project.version}"
[jetty-home-{VERSION}]$ java -Djetty.home=$JETTY_HOME \
-Djetty.base=$JETTY_BASE \
-cp \
$JETTY_HOME/lib/jetty-servlet-api-4.0.2.jar\
:$JETTY_HOME/lib/jetty-http-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-server-$JETTY_VERSION.jar \
:$JETTY_HOME/lib/jetty-xml-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-util-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-io-$JETTY_VERSION.jar\
org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml
....
The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the `jetty.properties` file.
You can further simplify the startup of this server by using the INI template defined by the modules to create a `start.ini` file with the command:
[source,screen,subs="{sub-order}"]
....
[user]$ cd jetty-home-{VERSION}
[jetty-home-{VERSION}]$ mkdir example-base
[example-base]$ cd example-base
[example-base]$ ls -la
total 8
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
[my-base]$ java -jar /path/to/jetty-home/start.jar --add-to-start=http
WARNING: http initialised in ${jetty.base}/start.ini (appended)
WARNING: http enabled in ${jetty.base}/start.ini
WARNING: server initialised in ${jetty.base}/start.ini (appended)
WARNING: server enabled in ${jetty.base}/start.ini
[example-base]$ ls -la
total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini
....
Once complete, you can edit the `start.ini` file to modify any parameters and you can run the server with the simple command:
[source, screen, subs="{sub-order}"]
....
[my-base]$ java -jar /path/to/jetty-home/start.jar
....

1
documentation/jetty-documentation/src/main/asciidoc/operations-guide/.asciidoctorconfig
View File

@ -1,3 +1,4 @@
// Asciidoctor IDE configuration file. // Asciidoctor IDE configuration file.
// See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-project-specific-configurations // See https://github.com/asciidoctor/asciidoctor-intellij-plugin/wiki/Support-project-specific-configurations
:experimental:
:JETTY_HOME: ../../../../../../../jetty-home/target/jetty-home :JETTY_HOME: ../../../../../../../jetty-home/target/jetty-home

127
documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/architecture.adoc Normal file
View File

@ -0,0 +1,127 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-arch]]
=== Architecture Overview
There are three main concepts on which the Jetty standalone server is based:
* The xref:og-arch-modules[Jetty _module_ system], where Jetty modules provides Jetty features.
* The xref:og-arch-jetty-base[`$JETTY_BASE` directory], that provides a place where you configure which Jetty modules you want to enable, configure the properties of each enabled module, and therefore configure the features you need for your web applications.
* The xref:og-arch-start[Jetty start mechanism], that starts a JVM that runs Jetty with the configuration you specified.
After installing Jetty, you will want to set up a xref:og-arch-jetty-base[`$JETTY_BASE` directory] where you configure xref:og-arch-modules[Jetty modules].
[[og-arch-modules]]
==== Jetty Modules
The Jetty standalone server is made of Java components that are assembled together, configured and started to provide different features.
A Jetty _module_ provides one or more components that work together to provide typically one feature, although they may provide more than one feature.
A Jetty module is nothing more than Jetty components assembled together like you would do using Java APIs, just done in a declarative way using configuration files.
What you can do in Java code to assemble Jetty components can be done using Jetty modules.
A Jetty module may be dependent on other Jetty modules: for example, the `http` Jetty module depends on the `server` Jetty module which in turn depends on the `threadpool` and `logging` Jetty modules.
Every feature in a Jetty server is enabled by enabling the corresponding Jetty module(s).
For example, if you enable only the `http` Jetty module, then your Jetty standalone server will only be able to listen to a network port for clear-text HTTP requests.
It will not be able to process secure HTTP (i.e. `https`) requests, it will not be able to process WebSocket, or HTTP/2 or any other protocol because the correspondent modules have not been enabled.
You can even start a Jetty server _without_ listening on a network port -- for example because you have enabled a custom module you wrote that provides the features you need.
This allows the Jetty standalone server to be as small as necessary: modules that are not enabled are not loaded, don't waste memory, and you don't risk a client using a module that you did not know was even there.
For more detailed information about the Jetty module system, see xref:og-modules[this section].
[[og-arch-jetty-base]]
==== `$JETTY_HOME` and `$JETTY_BASE`
Instead of managing multiple Jetty distributions out of many locations, it is possible to maintain a separation between the binary installation of the standalone Jetty, known as `$JETTY_HOME`, and the customizations for your specific environment(s), known as `$JETTY_BASE`.
This separation between the binary installation directory and the specific configuration directory allows to manage multiple, different, server configurations, and allows for quick, drop-in upgrades of Jetty.
There should always only be *one* `$JETTY_HOME` (per version of Jetty), but there can be many `$JETTY_BASE` directories that reference it.
This separation between `$JETTY_HOME` and `$JETTY_BASE` allows Jetty upgrades without affecting your web applications.
`$JETTY_HOME` contains the Jetty runtime and libraries and the default configuration, while a `$JETTY_BASE` contains your web applications and any override of the default configuration.
For example, with the `$JETTY_HOME` installation the default value for the network port for clear-text HTTP is `8080`.
However, you may want that port to be `6060`, because xref:og-protocols-proxy[Jetty is behind a load balancer] that is configured to forward to the backend on port `6060`.
In this case, you configure the clear-text HTTP port in `$JETTY_BASE`, not in `$JETTY_HOME`.
When you upgrade Jetty, you will upgrade only the files in `$JETTY_HOME`, and all the configuration in `$JETTY_BASE` will remain unchanged, keeping your clear-text HTTP port at `6060`.
Installing the Jetty runtime and libraries in `$JETTY_HOME` also allows you to leverage file system permissions: `$JETTY_HOME` may be owned by an administrator user (so that only administrators can upgrade it), while `$JETTY_BASE` directories may be owned by a less privileged user.
If you had changed the default configuration in `$JETTY_HOME`, when you upgrade Jetty, say from version `10.0.0` to version `10.0.1`, your changes would be lost.
Maintaining all the changes in `$JETTY_HOME`, and having to reconfigure these with each upgrade results in a massive commitment of time and effort.
To recap:
`$JETTY_HOME`::
This is the location for the Jetty binaries.
`$JETTY_BASE`::
This is the location for your configurations and customizations to the Jetty binaries.
[[og-arch-start]]
==== Start Mechanism
The Jetty start mechanism provides two features:
* The mean to configure your `$JETTY_BASE` by enabling the desired modules, and to display the configuration of your `$JETTY_BASE`.
* The mean to start Jetty itself, by starting a JVM that reads the Jetty configuration in `$JETTY_BASE`, which is then executed to assemble and start the Jetty components.
The Jetty start mechanism is invoked by executing `$JETTY_HOME/start.jar` from within your `$JETTY_BASE`, and you can think of it as the Jetty command line program, similar to many Unix/Windows command line programs.
For example, you can ask for help:
----
$ java -jar $JETTY_HOME/start.jar --help
----
Or you can list all available modules (or only those with a specific tag):
----
# List all the modules.
$ java -jar $JETTY_HOME/start.jar --list-modules=*
# List all the modules tagged as "demo".
$ java -jar $JETTY_HOME/start.jar --list-modules=demo
----
You can enable a module, for example the `http` module:
----
$ java -jar $JETTY_HOME/start.jar --add-module=http
----
Once you have one or more module enabled, you can display the current configuration, to verify that the configuration is correct:
----
$ java -jar $JETTY_HOME/start.jar --list-config
----
You can enable a Jetty demo module, which will deploy a demo web application:
----
$ java -jar $JETTY_HOME/start.jar --add-module=demo-simple
----
Finally, you can start Jetty:
----
$ java -jar $JETTY_HOME/start.jar
----
Read more information at the xref:og-start[Jetty start mechanism section].

8
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-details.adoc → documentation/jetty-documentation/src/main/asciidoc/operations-guide/architecture/chapter.adoc
View File

@ -11,10 +11,4 @@
// ======================================================================== // ========================================================================
// //
[[og-start-details]] include::architecture.adoc[]
=== Starting Eclipse Jetty: Details
// TODO: how start.jar builds a classpath, etc.
// how command line overrides base, that overrides home
// how you can start Jetty on-the-fly without modules or ini files
// etc.

92
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/architecture.adoc
View File

@ -1,92 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-begin-arch]]
==== Eclipse Jetty Architecture Overview
There are two main concepts on which the Eclipse Jetty standalone server is based:
* The xref:og-begin-arch-modules[Jetty _module_ system], that provides the Jetty features
* The xref:og-begin-arch-jetty-base[`$JETTY_BASE` directory], that provides a place where you configure the modules, and therefore the features you need for your web applications
After installing Jetty, you will want to set up a xref:og-begin-arch-jetty-base[`$JETTY_BASE` directory] where you configure xref:og-begin-arch-modules[Jetty modules].
[[og-begin-arch-modules]]
===== Eclipse Jetty Architecture: Modules
The Jetty standalone server is made of components that are assembled together, configured and started to provide different features.
A Jetty _module_ is made of one or more components that work together to provide typically one feature, although they may provide more than one feature.
A Jetty module is nothing more than Jetty components assembled together like you would do using Java APIs, just done in a declarative way using configuration files.
What you can do in Java code to assemble Jetty components can be done using Jetty modules.
A Jetty module may be dependent on other Jetty modules: for example, the `http` Jetty module depends on the `server` Jetty module which in turn depends on the `threadpool` and `logging` Jetty modules.
Every feature in a Jetty server is enabled by enabling the corresponding Jetty module(s).
For example, if you enable only the `http` Jetty module, then your Jetty standalone server will only be able to listen to a network port for clear-text HTTP requests.
It will not be able to process secure HTTP (i.e. `https`) requests, it will not be able to process WebSocket, or HTTP/2 or any other protocol because the correspondent modules have not been enabled.
You can even start a Jetty server _without_ listening on a network port -- for example because you have enabled a custom module you wrote that provides the features you need.
This allows the Jetty standalone server to be as small as necessary: modules that are not enabled are not loaded, don't waste memory, and you don't risk a client using a module that you did not know was even there.
For more detailed information about the Jetty module system, see xref:og-modules[this section].
[[og-begin-arch-jetty-base]]
===== Eclipse Jetty Architecture: `$JETTY_BASE`
Instead of managing multiple Jetty implementations out of several different distribution locations, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as `${jetty.home}`), and the customizations for your specific environment(s) (known as `${jetty.base}`).
In addition to easy management of multiple server instances, is allows for quick, drop-in upgrades of Jetty.
There should always only be *one* Jetty Home (per version of Jetty), but there can be multiple Jetty Base directories that reference it.
This separation between `$JETTY_HOME` and `$JETTY_BASE` allows upgrades without affecting your web applications.
`$JETTY_HOME` contains the Jetty runtime and libraries and the default configuration, while a `$JETTY_BASE` contains your web applications and any override of the default configuration.
For example, with the `$JETTY_HOME` installation the default value for the network port for clear-text HTTP is `8080`.
However, you want that port to be `6060`, because you are behind a load balancer that is configured to forward to the backend on port `6060`.
Instead, you want to configure the clear-text HTTP port in your `$JETTY_BASE`.
When you upgrade Jetty, you will upgrade only files in `$JETTY_HOME`, and all the configuration in `$JETTY_BASE` will remain unchanged.
Installing the Jetty runtime and libraries in `$JETTY_HOME` also allows you to leverage file system permissions: `$JETTY_HOME` may be owned by an administrator user (so that only administrators can upgrade it), while `$JETTY_BASE` directories may be owned by a less privileged user.
If you had changed the default configuration in `$JETTY_HOME`, when you upgrade Jetty, say from version `10.0.0` to version `10.0.1`, your change would be lost.
Maintaining all the changes in `$JETTY_HOME`, and having to reconfigure these with each upgrade results in a massive commitment of time and effort.
To recap:
`$JETTY_BASE`::
* This is the location for your configurations and customizations to the Jetty distribution.
`$JETTY_HOME`::
* This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.
____
[IMPORTANT]
Jetty Home should always be treated as a standard of truth.
All configuration modifications, changes and additions should *always* be made in the appropriate Jetty Base directory.
____
[[base-vs-home-resolution]]
===== Eclipse Jetty Architecture: `$JETTY_HOME` and `$JETTY_BASE` Configuration Resolution
Potential configuration is resolved from these 2 directory locations.
When Jetty starts up in processes configuration from them as follows:
Check Jetty Base First::
If the referenced configuration exists, relative to the defined Jetty base, it is used.
Check Jetty Home Second::
If the referenced configuration exists, relative to the defined Jetty home, it is used.
Use java.io.File(String pathname) Logic::
Lastly, use the reference as a `java.io.File(String pathname)` reference, following the default resolution rules outlined by that constructor.In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).

9
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/chapter.adoc
View File

@ -12,16 +12,17 @@
// //
[[og-begin]] [[og-begin]]
=== Introduction to Eclipse Jetty === Getting Started
This section will get you started with Eclipse Jetty. If you are new to Eclipse Jetty, read on to download, install, start and deploy web applications to Jetty.
include::../../../../../../../jetty-home/src/main/resources/README.adoc[tags=quick] include::../../../../../../../jetty-home/src/main/resources/README.adoc[tags=quick]
The following sections will guide you in details about downloading, installing and starting Jetty, as well as deploying your web applications to Jetty. The following sections will guide you in details about xref:og-begin-download[downloading], xref:og-begin-install[installing] and xref:og-begin-start[starting] Jetty, and xref:og-begin-deploy[deploying] your web applications to Jetty.
Read the xref:og-arch[Jetty architecture section] for more information about Jetty modules, `$JETTY_HOME`, `$JETTY_BASE` and how to customize and start Jetty.
include::download.adoc[] include::download.adoc[]
include::install.adoc[] include::install.adoc[]
include::architecture.adoc[]
include::start.adoc[] include::start.adoc[]
include::deploy.adoc[] include::deploy.adoc[]

9
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc
View File

@ -12,17 +12,17 @@
// //
[[og-begin-deploy]] [[og-begin-deploy]]
==== Deploying Web Applications to Eclipse Jetty ==== Deploying Web Applications
For the purpose of deploying web applications to Jetty, there are two types of resources that can be deployed: For the purpose of deploying web applications to Jetty, there are two types of resources that can be deployed:
* Standard Web Application Archives, in the form of `+*.war+` files or `+*.war+` directories, defined by the Servlet specification. * Standard Web Application Archives, in the form of `+*.war+` files or web application directories, defined by the Servlet specification.
Their deployment is described in xref:og-begin-deploy-war[this section]. Their deployment is described in xref:og-begin-deploy-war[this section].
* Jetty context XML files, that allow you to customize the deployment of standard web applications, and also allow you use Jetty components, and possibly custom components written by you, to assemble your web applications. * Jetty context XML files, that allow you to customize the deployment of standard web applications, and also allow you use Jetty components, and possibly custom components written by you, to assemble your web applications.
Their deployment is described in xref:og-deploy[this section]. Their deployment is described in xref:og-deploy[this section].
[[og-begin-deploy-war]] [[og-begin-deploy-war]]
===== Deploying Standard +*.war+ Web Applications ===== Deploying +*.war+ Files
A standard Servlet web application is packaged in either a `+*.war+` file or in a directory with the structure of a `+*.war+` file. A standard Servlet web application is packaged in either a `+*.war+` file or in a directory with the structure of a `+*.war+` file.
@ -101,4 +101,7 @@ Note the highlighted line that logs the deployment of `demo-simple.war`.
Now you can access the web application by pointing your browser to `+http://localhost:8080/demo-simple+`. Now you can access the web application by pointing your browser to `+http://localhost:8080/demo-simple+`.
[[og-begin-deploy-war-advanced]]
===== Advanced Deployment
If you want to customize the deployment of your web application, for example by specifying a `contextPath` different from the file/directory name, or by specifying JNDI entries, or by specifying virtual hosts, etc. read xref:og-deploy[this section]. If you want to customize the deployment of your web application, for example by specifying a `contextPath` different from the file/directory name, or by specifying JNDI entries, or by specifying virtual hosts, etc. read xref:og-deploy[this section].

2
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/download.adoc
View File

@ -12,7 +12,7 @@
// //
[[og-begin-download]] [[og-begin-download]]
==== Downloading Eclipse Jetty ==== Downloading Jetty
The Eclipse Jetty distribution is available for download from link:https://www.eclipse.org/jetty/download.html[] The Eclipse Jetty distribution is available for download from link:https://www.eclipse.org/jetty/download.html[]

9
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc
View File

@ -12,19 +12,18 @@
// //
[[og-begin-install]] [[og-begin-install]]
==== Installing Eclipse Jetty ==== Installing Jetty
After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version that you downloaded, for example `10.0.0`, so that the directory is called `jetty-home-10.0.0`. After the download, unpacking Eclipse Jetty will extract the files into a directory called `jetty-home-VERSION`, where `VERSION` is the version that you downloaded, for example `{version}`, so that the directory is called `jetty-home-{version}`.
Unpack Eclipse Jetty compressed file in a convenient location, for example under `/opt`. Unpack Eclipse Jetty compressed file in a convenient location, for example under `/opt`.
NOTE: For Windows users, you should unpack Jetty to a path that does not contain spaces. CAUTION: For Windows users, you should unpack Jetty to a path that does not contain spaces.
The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`. The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`, or `${jetty.home}`.
IMPORTANT: It is important that *only* stable release versions are used in production environments. IMPORTANT: It is important that *only* stable release versions are used in production environments.
Versions that have been deprecated or are released as Milestones (M), Alpha, Beta or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets. Versions that have been deprecated or are released as Milestones (M), Alpha, Beta or Release Candidates (RC) are *not* suitable for production as they may contain security flaws or incomplete/non-functioning feature sets.
If you are new to Jetty, you should read the xref:og-begin-arch[Jetty architecture section below] to become familiar with the terms used in this documentation. If you are new to Jetty, you should read the xref:og-arch[Jetty architecture section] to become familiar with the terms used in this documentation.
Otherwise, you can jump to the xref:og-begin-start[section on starting Jetty]. Otherwise, you can jump to the xref:og-begin-start[section on starting Jetty].

20
documentation/jetty-documentation/src/main/asciidoc/operations-guide/begin/start.adoc
View File

@ -12,7 +12,7 @@
// //
[[og-begin-start]] [[og-begin-start]]
==== Starting Eclipse Jetty ==== Starting Jetty
// TODO: Consider: old_docs/startup/*.adoc // TODO: Consider: old_docs/startup/*.adoc
@ -20,13 +20,18 @@
Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line. Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line.
Recall from the xref:og-begin-arch[Eclipse Jetty standalone server architecture section] that Jetty is based on xref:og-modules[modules], that provides features, and on xref:og-begin-arch-jetty-base[`$JETTY_BASE`], the place where you configure which module (and therefore which feature) you want to enable, and where you configure module parameters. Recall from the xref:og-arch[architecture section] that Jetty is based on xref:og-modules[modules], that provides features, and on xref:og-arch-jetty-base[`$JETTY_BASE`], the place where you configure which module (and therefore which feature) you want to enable, and where you configure module parameters.
Jetty is started by executing `$JETTY_HOME/start.jar`, but first we need to create a `$JETTY_BASE`: Jetty is started by executing `$JETTY_HOME/start.jar` from within a `$JETTY_BASE` directory, so first we need to create a `$JETTY_BASE`:
---- ----
$ JETTY_BASE=/path/to/jetty.base $ JETTY_BASE=/path/to/jetty.base
$ cd $JETTY_BASE $ cd $JETTY_BASE
----
If you try to start Jetty from an empty `$JETTY_BASE` you get:
----
$ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar
---- ----
@ -35,18 +40,17 @@ $ java -jar $JETTY_HOME/start.jar
include::jetty[] include::jetty[]
---- ----
The error is normal, since the `$JETTY_BASE` you just created is empty and therefore there is no configuration to use to assemble the Jetty server. Jetty exited complaining that there are no modules enabled, since the `$JETTY_BASE` you just created is empty and therefore there is no configuration to read to assemble the Jetty server.
However, it shows that `start.jar` takes parameters, whose details can be found in xref:og-start-jar[this section]. However, it shows that `start.jar` takes parameters, whose details can be found in xref:og-start[this section].
You can explore what modules are available out of the box via: You can explore what modules are available out of the box via:
---- ----
$ java -jar $JETTY_HOME/start.jar --list-modules=* $ java -jar $JETTY_HOME/start.jar --list-modules=*
---- ----
// TODO: add output of the --list-modules command?
Try to enable the `http` module (see also xref:og-protocols-http[this section] for additional information): Let's try to enable the `http` module (see also xref:og-protocols-http[this section] for additional information):
---- ----
$ java -jar $JETTY_HOME/start.jar --add-module=http $ java -jar $JETTY_HOME/start.jar --add-module=http
@ -131,4 +135,4 @@ NOTE: If you want to enable support for different protocols such as secure HTTP/
The Jetty server is now up and running, but it has no web applications deployed, so it just replies with `404 Not Found` to every request. The Jetty server is now up and running, but it has no web applications deployed, so it just replies with `404 Not Found` to every request.
It is time to xref:og-begin-deploy[deploy your web applications] to Jetty. It is time to xref:og-begin-deploy[deploy your web applications] to Jetty.
For more detailed information about the Jetty start system, you can read the xref:og-start-details[Jetty start system] section. For more detailed information about the Jetty start mechanism, you can read the xref:og-arch-start[Jetty start mechanism] section.

42
documentation/jetty-documentation/src/main/asciidoc/operations-guide/features.adoc Normal file
View File

@ -0,0 +1,42 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-features]]
=== Eclipse Jetty Features
If you know Eclipse Jetty already, jump to a feature:
Protocols::
* xref:og-protocols-http[HTTP/1.1 Support]
* xref:og-protocols-http2[HTTP/2 Support]
* xref:og-protocols-websocket[WebSocket Support]
Technologies::
* xref:og-annotations[Servlet Annotations]
* xref:og-jaas[JAAS]
* xref:og-jndi[JNDI]
* xref:og-jsp[JSP]
* xref:og-jmx[JMX Monitoring & Management]
Clustering::
* xref:og-sessions[HTTP Session Caching and Clustering]
Performance::
* xref:og-quickstart[Faster Web Application Deployment]
TODO
* Jetty Overview
* Jetty Modules
* Rewrite Modules

23
documentation/jetty-documentation/src/main/asciidoc/operations-guide/howtos.adoc Normal file
View File

@ -0,0 +1,23 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-howtos]]
=== Eclipse Jetty How-Tos
* xref:og-protocols-http[Configure Clear-Text HTTP/1.1]
* xref:og-protocols-https[Configure Secure HTTP/1.1 (https)]
* xref:og-protocols-http2c[Configure Clear-Text HTTP/2]
* xref:og-protocols-http2s[Configure Secure HTTP/2]
* xref:og-protocols-proxy[Configure Jetty Behind a Load Balancer or Reverse Proxy]
* xref:og-logging[Configure Jetty Logging]
* xref:og-troubleshooting[Troubleshooting]

5
documentation/jetty-documentation/src/main/asciidoc/operations-guide/index.adoc
View File

@ -21,8 +21,11 @@ include::../config.adoc[]
include::.asciidoctorconfig[] include::.asciidoctorconfig[]
include::introduction.adoc[] include::introduction.adoc[]
include::begin/chapter.adoc[] include::begin/chapter.adoc[]
include::architecture/chapter.adoc[]
include::features.adoc[]
include::howtos.adoc[]
include::start/chapter.adoc[] include::start/chapter.adoc[]
include::deploy/chapter.adoc[] include::deploy/chapter.adoc[]
include::protocols/chapter.adoc[] include::protocols/chapter.adoc[]
include::keystore/chapter.adoc[] include::keystore/chapter.adoc[]

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

@ -15,45 +15,3 @@
== Eclipse Jetty Operations Guide == Eclipse Jetty Operations Guide
The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications. The Eclipse Jetty Operations Guide targets sysops, devops, and developers who want to install Eclipse Jetty as a standalone server to deploy web applications.
=== Getting Started
If you are new to Eclipse Jetty, read xref:og-begin[here] to download, install, start and deploy web applications to Jetty.
=== Eclipse Jetty Features
If you know Eclipse Jetty already, jump to a feature:
Protocols::
* xref:og-protocols-http[HTTP/1.1 Support]
* xref:og-protocols-http2[HTTP/2 Support]
* xref:og-protocols-websocket[WebSocket Support]
Technologies::
* xref:og-annotations[Servlet Annotations]
* xref:og-jaas[JAAS]
* xref:og-jndi[JNDI]
* xref:og-jsp[JSP]
* xref:og-jmx[JMX Monitoring & Management]
Clustering::
* xref:og-sessions[HTTP Session Caching and Clustering]
Performance::
* xref:og-quickstart[Faster Web Application Deployment]
TODO
* Jetty Overview
* Jetty Modules
* Rewrite Modules
=== Eclipse Jetty How-Tos
* xref:og-protocols-http[Configure Clear-Text HTTP/1.1]
* xref:og-protocols-https[Configure Secure HTTP/1.1 (https)]
* xref:og-protocols-http2c[Configure Clear-Text HTTP/2]
* xref:og-protocols-http2s[Configure Secure HTTP/2]
* xref:og-protocols-proxy[Configure Jetty Behind a Load Balancer or Reverse Proxy]
* xref:og-logging[Configure Jetty Logging]
* xref:og-troubleshooting[Troubleshooting]

3
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/module-server.adoc
View File

@ -37,3 +37,6 @@ See also the xref:og-troubleshooting-dump[Jetty Server Dump] section for more in
Whether to perform a `Server.dump()` operation before the `Server` stops. Whether to perform a `Server.dump()` operation before the `Server` stops.
The output of the dump operation is sent to `System.err`. The output of the dump operation is sent to `System.err`.
See also the xref:og-troubleshooting-dump[Jetty Server Dump] section for more information. See also the xref:og-troubleshooting-dump[Jetty Server Dump] section for more information.
`jetty.server.stopAtShutdown`::
Whether to call `Server.stop()` through a JVM shutdown hook when the JVM exits.

17
documentation/jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc
View File

@ -20,3 +20,20 @@ TODO
// * old_docs/startup/startup-modules.adoc // * old_docs/startup/startup-modules.adoc
// * old_docs/startup/custom-modules.adoc // * old_docs/startup/custom-modules.adoc
// //
[[og-modules-custom]]
==== Custom Jetty Modules
TODO
//The `[jpms]` section has the following format:
//
//[source, screen, subs="{sub-order}"]
//....
//[jpms]
//add-modules: <module name>(,<module name>)*
//patch-module: <module>=<file>(:<file>)*
//add-opens: <module>/<package>=<target-module>(,<target-module>)*
//add-exports: <module>/<package>=<target-module>(,<target-module>)*
//add-reads: <module>=<target-module>(,<target-module>)*
//....

56
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/chapter.adoc
View File

@ -11,5 +11,57 @@
// ======================================================================== // ========================================================================
// //
include::start-details.adoc[] [[og-start]]
include::start-jar.adoc[] === Jetty Start Mechanism
NOTE: Make sure you have read the xref:og-arch[Jetty architecture section] if you are not familiar with the terms used in this section.
The Jetty start mechanism is invoked by executing `$JETTY_HOME/start.jar`, from within a `$JETTY_BASE` directory, with zero or more command line options:
----
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar ...
----
The Jetty start mechanism has two main modes of operation:
* The _tool_ mode, detailed in xref:og-start-configure[this section], when it is used as a command line tool to configure the `$JETTY_BASE` directory by enabling modules, creating sub-directories and files, downloading files, etc.
In this mode, the JVM started with `java -jar $JETTY_HOME/start.jar` performs the specified command and then exits.
* The _start_ mode, detailed in xref:og-start-start[this section], when it is used to start the JVM that runs Jetty with the specified configuration.
In this mode, the JVM started with `java -jar $JETTY_HOME/start.jar` starts Jetty and does not exit until stopped, for example by hitting kbd:[Ctrl+C] on the terminal.
Refer to the xref:og-start-reference[Jetty start mechanism reference section] for the complete list of the available command line options.
You want to use the Jetty start mechanism to xref:og-start-configure[configure your $JETTY_BASE] and then to xref:og-start-start[start Jetty].
include::start-configure.adoc[]
include::start-start.adoc[]
include::start-jpms.adoc[]
include::start-stop.adoc[]
==== Logging and Debugging
The steps performed by the Jetty start mechanism are logged by the `StartLog` class, that outputs directly, by default, to `System.err`.
This is necessary to avoid that the Jetty start mechanism depend on logging libraries that may clash with those defined by Jetty logging modules, when Jetty is started in-VM.
You can enable DEBUG level logging with the `--debug` command line option, for both the _tool_ and _start_ modes:
----
$ java -jar $JETTY_HOME/start.jar --debug ...
----
You can send the start log output to a file, by default relative to `$JETTY_BASE`, with the `--start-log-file=<file>` option:
----
$ java -jar $JETTY_HOME/start.jar --debug --start-log-file=start.log ...
----
This is useful for capturing startup issues where the Jetty-specific logger has not yet kicked in due to a possible startup configuration error.
[[og-start-reference]]
==== Usage Reference
----
include::../../../../../../../jetty-start/src/main/resources/org/eclipse/jetty/start/usage.txt[]
----

8
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/jpms.mod Normal file
View File

@ -0,0 +1,8 @@
[description]
JPMS Configuration Module
[ini]
--jpms
[jpms]
# Additional JPMS configuration.

6
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/jvm.mod Normal file
View File

@ -0,0 +1,6 @@
[description]
JVM Options Module
[exec]
-Xmx1g
-Xlog:gc*,gc+stats=off:file=logs/gc.log:time,level,tags

15
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/postgresql.mod Normal file
View File

@ -0,0 +1,15 @@
[description]
Postgres JDBC Driver Module
[lib]
lib/postgresql-${postgresql-version}.jar
[files]
maven://org.postgresql/postgresql/${postgresql-version}|lib/postgresql-${postgresql-version}.jar
[ini]
postgresql-version?=42.2.18
[ini-template]
# Postgres JDBC version
postgresql-version=42.2.18

306
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-configure.adoc Normal file
View File

@ -0,0 +1,306 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-start-configure]]
==== Configuring $JETTY_BASE
Within the Jetty start mechanism, the source of configurations is layered in this order, from higher priority to lower priority:
* The command line options.
* The `$JETTY_BASE` directory, and its files.
* The directory specified with the `--include-jetty-dir` option, and its files.
* The `$JETTY_HOME` directory, and its files.
You can enable Jetty modules with the `--add-modules` command:
----
$ java -jar $JETTY_HOME/start.jar --add-modules=server,http
----
The Jetty start mechanism will look for the specified modules following the order specified above.
In the common case (without a `--include-jetty-dir` directory), it will look in `$JETTY_BASE/modules/` first and then in `$JETTY_HOME/modules/`.
Since the `server` and `http` modules are standard Jetty modules, they are present in `$JETTY_HOME/modules/` and loaded from there.
When you enable a Jetty module, the Jetty start mechanism:
* Creates the correspondent `+$JETTY_BASE/start.d/*.ini+` module configuration file.
The content of these `+*.ini+` files is copied from the `[ini-template]` section of the correspondent `+*.mod+` file.
* Executes the directives specified in `[files]` section (if present) of the `+*.mod+` file.
This may simply create a file or a directory, or download files from the Internet.
This step is performed transitively for all module dependencies.
The fact that there exist a `+$JETTY_BASE/start.d/*.ini+` file means that the module is enabled.
To disable the module, simply delete the `+$JETTY_BASE/start.d/*.ini+` file.
In the example above, enabling the `server` and `http` modules results in the `$JETTY_BASE` directory to have the following structure:
----
$JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
├── http.ini
└── server.ini
----
The `$JETTY_BASE/resources/jetty-logging.properties` is created by the `[files]` directives of the `logging-jetty` module, which is a transitive dependency of the `server` module.
[[og-start-configure-edit-ini]]
===== Editing `+*.ini+` Files
You can now edit the `+$JETTY_BASE/start.d/*.ini+` configuration files, typically by uncommenting properties to change their default value.
The `+$JETTY_BASE/start.d/*.ini+` configuration file may be missing, if the correspondent module is a transitive dependency.
You can easily generate the configuration file by explicitly enabling the module, for example to generate the `$JETTY_BASE/start.d/logging-jetty.ini` configuration file you would issue the following command (the module order does not matter):
----
$ java -jar $JETTY_HOME/start.jar --add-modules=server,http,logging-jetty
----
The `$JETTY_BASE` directory structure is now:
[source,subs=quotes]
----
$JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
├── http.ini
├── ##logging-jetty.ini##
└── server.ini
----
You want to edit the `+$JETTY_BASE/start.d/*.ini+` configuration files so that the configuration is applied every time Jetty is started (or re-started).
For example, `$JETTY_BASE/start.d/http.ini` contains the following property, commented out:
.http.ini
----
# jetty.http.port=8080
----
You can change the clear-text HTTP port Jetty listens to by uncommenting that property and changing its value:
.http.ini
----
jetty.http.port=9876
----
When Jetty is started (or re-started) this configuration is applied and Jetty will listen for clear-text HTTP/1.1 on port `9876`.
[[og-start-configure-custom-module]]
===== Adding Your Own Modules
NOTE: Refer to the xref:og-modules-custom[custom module section] for the details about how to create your own modules.
You can add your own modules by adding a `+$JETTY_BASE/modules/*.mod+` file.
For example, you may want to add a Postgres JDBC driver to the server class-path, to avoid that each deployed web application bring its own version. This allows you to control the exact Postgres JDBC driver version for all web applications.
Create the `$JETTY_BASE/modules/postgresql.mod` file:
.postgresql.mod
----
include::postgresql.mod[]
----
Then enable it:
----
$ java -jar $JETTY_HOME/start.jar --add-modules=postgresql
----
Enabling the `postgresql` module will execute the `[files]` directive (downloading the `+*.jar+` file from Maven Central if not already present) and create the `$JETTY_BASE/start.d/postgresql.ini` with the content of the `[ini-template]` section.
The `[lib]` section ensures that the specified file is in the server class-path when Jetty is started.
You can xref:og-start-configure-display[display the Jetty configuration] to verify that the server class-path is correct.
[[og-start-configure-custom-module-exec]]
===== Custom Module with JVM Options
Using a custom Jetty module, you can customize the JVM startup options.
This is useful if you need to start Jetty and want to specify JVM options such as:
* `+-Xmx+`, to specify the max heap size
* `+-Xlog:gc+`, to specify the GC log file and options
* `+-javaagent+`, to specify Java agents
* `+-XX:+` options, for example to specify the GC implementation
Start by creating `$JETTY_BASE/modules/jvm.mod`:
.jvm.mod
----
include::jvm.mod[]
----
Enable it:
----
$ java -jar $JETTY_HOME/start.jar --add-modules=jvm
----
Since the module defines an `[exec]` section, it will fork _another_ JVM when Jetty is started.
This means that when you start Jetty, there will be _two_ JVMs running: one spawned by you when you run `java -jar $JETTY_HOME/start.jar`, and another spawned by the Jetty start mechanism with the JVM options you specified (that cannot be applied to an already running JVM).
Again, you can xref:og-start-configure-dry-run[display the JVM command line] to verify that it is correct.
[[og-start-configure-display]]
===== Displaying the Configuration
Once you have enabled and configured the `$JETTY_BASE`, you can display the configuration to verify that it is correct.
Using the standard `server` and `http` Jetty modules, and the `postgresql` and `jvm` custom Jetty module defined above, you obtain:
----
$ java -jar $JETTY_HOME/start.jar --list-config
----
[source,options=nowrap]
----
include::jetty[setupModules="src/main/asciidoc/operations-guide/start/jvm.mod,src/main/asciidoc/operations-guide/start/postgresql.mod",setupArgs="--add-modules=server,http,postgresql,jvm",args="--list-config"]
----
Note how the configuration displayed above includes:
* In the list of enabled modules, the `postgresql` and `jvm` modules
* In the list of JVM arguments, those specified by the `jvm` module
* In the server class-path, the `+*.jar+` file specified by the `postgresql` module
[[og-start-configure-dry-run]]
===== Displaying the JVM Command Line
The Jetty start mechanism can display a full JVM command line that will start Jetty with the configuration you specified, with the `--dry-run` option:
----
$ java -jar $JETTY_HOME/start.jar --dry-run
----
The full JVM command line generated by `--dry-run` can be split in various parts that can be used individually, for example in scripts.
Furthermore, Jetty modules may specify the `--exec` option that will fork a second JVM to start Jetty, which may not be desirable.
Some option, such as `--jpms`, imply `--exec`, as it won't be possible to modify the module-path in the already started JVM.
To start Jetty without forking a second JVM, the `--dry-run` option can be used to generate a command line that is then executed so that starting Jetty only spawns one JVM.
The `--dry-run` option is quite flexible and below you can find a few examples of how to use it to generate scripts or to create an arguments file that can be passed to the `java` executable.
To display the `java` executable used to start Jetty:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --dry-run=##java##
----
[source,options=nowrap]
----
include::jetty[setupArgs="--add-modules=http",args="--dry-run=java"]
----
To display the JVM options:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --dry-run=##opts##
----
[source,options=nowrap]
----
include::jetty[setupModules="src/main/asciidoc/operations-guide/start/jvm.mod",setupArgs="--add-modules=http,jvm",args="--dry-run=opts",replace="( ),$1\\\n"]
----
To display the JVM class-path:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --dry-run=##path##
----
[source,options=nowrap]
----
include::jetty[setupModules="src/main/asciidoc/operations-guide/start/postgresql.mod",setupArgs="--add-modules=http,jvm",args="--dry-run=path",replace="( |:),$1\\\n"]
----
To display the JVM class-path and module-path, if you want to xref:og-start-start-jpms[start Jetty using JPMS] with the `--jpms` option:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar ##--jpms## --dry-run=##path##
----
[source,options=nowrap]
----
include::jetty[setupModules="src/main/asciidoc/operations-guide/start/postgresql.mod",setupArgs="--add-modules=http,jvm",args="--jpms --dry-run=path",replace="( |:),$1\\\n"]
----
To display the JVM main class:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --dry-run=##main##
----
[source,options=nowrap]
----
include::jetty[setupArgs="--add-modules=http",args="--dry-run=main"]
----
To display the JVM main class when xref:og-start-start-jpms[starting Jetty using JPMS]:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --jpms --dry-run=##main##
----
[source,options=nowrap]
----
include::jetty[setupArgs="--add-modules=http",args="--jpms --dry-run=main"]
----
The main class is typically Jetty's `XmlConfiguration` class that accepts, as program arguments, a list of properties and a list of Jetty XML files to process.
The Jetty XML files compose together the Jetty components that are then configured with the values from the command line properties.
To display the program arguments passed to the main class:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --dry-run=##args##
----
[source,options=nowrap]
----
include::jetty[setupModules="src/main/asciidoc/operations-guide/start/postgresql.mod",setupArgs="--add-modules=http",args="--dry-run=args",replace="( ),$1\\\n"]
----
Note how the program arguments are a list of properties in the form `<name>=<value>` and a list of Jetty XML files.
The various parts of the full JVM command line can be combined to leverage the arguments file feature (that is, specify the JVM options in a file rather than on the command line) that is built-in in the `java` executable:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar --dry-run=##opts,path,main,args## > /tmp/jvm_cmd_line.txt
$ /some/other/java @/tmp/jvm_cmd_line.txt
----
Alternatively, they can be combined in a shell script:
[source,subs=quotes]
----
$ OPTS=$(java -jar start.jar --dry-run=##opts,path##)
$ MAIN=$(java -jar start.jar --dry-run=##main##)
$ ARGS=$(java -jar start.jar --dry-run=##args##)
$ java $OPTS -Dextra=opt $MAIN $ARGS extraProp=value extra.xml
----

331
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-jar.adoc
View File

@ -1,331 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-start-jar]]
=== Using start.jar
TODO: review in light of Jetty 10
The most basic way of starting the Jetty standalone server is to execute the `start.jar` from a base directory containing
the configuration of jetty:
----
[] mkdir /var/jetty-base
[] cd /var/jetty-base
[] java -jar $JETTY_HOME/start.jar
ERROR : No enabled jetty modules found!
...
----
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. You use start.jar to configure the modules:
----
[] java -jar $JETTY_HOME/start.jar --add-module=http
...
INFO : http initialized in ${jetty.base}/start.d/http.ini
...
[] java -jar $JETTY_HOME/start.jar
2020-12-02 09:31:45.563:INFO :oejs.Server:main: jetty-10.0.0; built: 2020-11-30T14:38:10.953Z; git: cac070fdb134df192252e99653d99d7c3fb91b87; jvm 15.0.1+9
2020-12-02 09:31:45.601:INFO :oejs.AbstractConnector:main: Started ServerConnector@3eb7fc54{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2020-12-02 09:31:45.615:INFO :oejs.Server:main: Started Server@55a561cf{STARTING}[10.0.0,sto=5000] @760ms
----
At its most basic, you configure Jetty from two elements:
1. A set of libraries and directories that make up the server classpath.
2. A set of Jetty XML configuration files (IoC style) that establish how to build the Jetty server and its components.
Instead of editing these directly, Jetty 9.1 introduced more options on how to configure Jetty (these are merely syntactic sugar that eventually resolve into the two basic configuration components).
Jetty Startup Features include:
* A separation of the Jetty distribution binaries in `${jetty.home}` and the environment specific configurations (and binaries) found in `${jetty.base}` (detailed in link:#startup-jetty-base-and-jetty-home[Managing Jetty Base and Jetty Home.])
* You can enable a set of libraries and XML configuration files via the newly introduced link:#startup-modules[module system.]
* All of the pre-built XML configuration files shipped in Jetty are now parameterized with properties that you can specify in your `${jetty.base}/start.ini` (demonstrated in link:#quick-start-configure[Quick Start Configuration]).
These are powerful new features, made to support a variety of styles of configuring Jetty, from a simple property based configuration, to handling multiple installations on a server, to customized stacks of technology on top of Jetty, and even the classic, custom XML configurations of old.
For example, if you use the `${jetty.base}` concepts properly, you can upgrade the Jetty distribution without having to remake your entire tree of modifications to Jetty.
Simply separate out your specific modifications to the `${jetty.base}`, and in the future, just upgrade your `${jetty.home}` directory with a new Jetty distribution.
[[executing-startjar]]
==== Executing start.jar
When executed `start.jar` performs the following actions:
* Loads and parses all INIs found in `${jetty.base}/start.d/*.ini` as command line arguments.
* Loads and parses `${jetty.base}/start.ini` as command line arguments.
** Please see link:#start-vs-startd[Start.ini vs. Start.d] for more information on the difference between these.
* Parses actual command line arguments used to execute `start.jar` itself.
* Resolves any XML configuration files, modules, and libraries using base vs. home resolution steps:
1. Checks whether file exists as relative reference to `${jetty.base}.`
2. Checks whether file exists as relative reference to `${jetty.home}.`
3. Uses default behavior of `java.io.File` (Relative to `System.getProperty` ("user.dir") and then as absolute file system path).
* Loads any dependent modules (merges XXNK, library, and properties results with active command line).
* Builds out server classpath.
* Determines run mode as one of:
** Shows informational command line options and exit.
** Executes Jetty normally, waits for Jetty to stop.
** Executes a forked JVM to run Jetty in, waits for forked JVM to exit.
==== start.jar Command Line Options
===== Command Line Options
--help::
Obtains the current list of command line options and some basic usage help.
--version::
Shows the list of server classpath entries, and prints version information found for each entry.
--list-classpath::
Similar to --version, shows the server classpath.
--list-config::
Lists the resolved configuration that will start Jetty.
* Java environment
* Jetty environment
* JVM arguments
* Properties
* Server classpath
* Server XML configuration files
--dry-run::
Print the command line that the start.jar generates, then exit. This may be used to generate command lines when the start.ini includes -X or -D arguments:
----
$ java -jar start.jar --dry-run > jetty.sh
$ . jetty.sh
----
--dry-run=<parts>::
Print specific parts of the command line. The parts are a comma separated list of:
* "java" - the JVM to run
* "opts" - the JVM options (eg -D and -X flags)
* "path" - the JVM class path or JPMS modules options
* "main" - the main class to run
* "args" - the arguments passed to the main class
It is possible to decompose the start command:
----
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
----
Alternatively to create an args file for java:
----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
----
--exec::
Forces the start to use a forked instance of java to run Jetty.
Some modules include `--exec` in order to set java command line options.
Some start options, such as `--jpms` also imply `--exec`
--exec-properties=<filename>::
Assign a fixed name to the file used to transfer properties to the sub process.
This allows the generated properties file to be saved and reused.
Without this option, a temporary file is used.
--commands=<filename>::
Instructs `start.jar` to use each line of the specified file as arguments on the command line.
===== Debug and Start Logging
--debug::
Enables debugging output of the startup procedure.
+
*Note*: This does not set up debug logging for Jetty itself.
For information on logging, please see the section on link:#configuring-jetty-logging[Configuring Jetty Logging.]]
--start-log-file=<filename>::
Sends all startup output to the filename specified.
Filename is relative to `${jetty.base}`.
This is useful for capturing startup issues where the Jetty-specific logger has not yet kicked in due to a possible startup configuration error.
===== Module Management
--list-modules::
Lists all the modules defined by the system.
Looks for module files using the link:#startup-base-and-home[normal `${jetty.base}` and `${jetty.home}` resolution logic].
Also lists enabled state based on information present on the command line, and all active startup INI files.
--list-modules=<tag>(,<tag>)*::
List modules by link:#startup-modules[tag.]
Use '*' for all tags.
Prefix a tag with '-' to exclude the tag.
The special tag "internal" is always excluded unless it is explicitly included.
--list-all-modules::
List all modules.
--module=<name>,(<name>)*::
Enables one or more modules by name (use `--list-modules` to see the list of available modules).
This enables all transitive (dependent) modules from the module system as well.
If you use this from the shell command line, it is considered a temporary effect, useful for testing out a scenario.
If you want this module to always be enabled, add this command to your `${jetty.base}/start.ini.`
--add-to-start=<name>,(<name>)*::
Enables a module by appending lines to the `${jetty.base}/start.ini` file.
The lines that are added are provided by the module-defined INI templates.
Note: Transitive modules are also appended.
If a module contains an .ini template with properties, you can also edit these properties when activating the module.
To do this, simply list the property and its value after the `-add-to-start` command, such as in the following example:
+
----
$ java -jar start.jar --add-to-start=http jetty.http.port=8379 jetty.http.host=1.2.3.4
----
+
Doing this will uncomment the property in the associated .ini file and set it to the value specified.
--update-ini::
Used to update a specified property or properties that exist in an existing .ini file.
Jetty scans the command line, `${jetty.base}` and `${jetty.home}` for .ini files that have the specified property and update it accordingly.
+
----
[my-base]$ java -jar /path/to/jetty-home/start.jar --update-ini jetty.http.port=8417
ConfigSource <command-line>
ConfigSource ${jetty.base}
INFO : http property updated jetty.http.port=8417
INFO : http updated ${jetty.base}/start.d/http.ini
ConfigSource ${jetty.home}
----
+
--create-startd::
Creates a `${jetty.base}/start.d/` directory.
If a `${jetty.base}/start.ini` file already exists, it is copied to the `${jetty.base}/start.d` directory.
[NOTE]
--
With respect to `start.ini` and `start.d/*.ini` files, only *one* of these methods should be implemented.
Mixing a `start.ini` with module specific ini files in the `{$jetty.base}/start.d` directory can lead to server issues unless great care is taken.
Please see link:#start-vs-startd[Start.ini vs. Start.d] for more information.
--
--write-module-graph=<filename>::
Advanced feature: Creates a graphviz http://graphviz.org/content/dot-language[dot file] of the module graph as it exists for the active `${jetty.base}`.
+
----
# generate module.dot
$ java -jar start.jar --module=websocket --write-module-graph=modules.dot
# post process to a PNG file
$ dot -Tpng -o modules.png modules.dot
----
+
See http://graphviz.org/[graphviz.org] for details on how to post-process this dotty file into the output best suited for your needs.
--create-files::
Create any missing files that are required by initialized modules.
This may download a file from the network if the module provides a URL.
--skip-file-validation=<modulename>(,<modulename)*::
Disable the [files] section validation of content in the `${jetty.base}` directory for a specific module.
Useful for modules that have downloadable content that is being overridden with alternatives in the `${jetty.base}`` directory.
____
[CAUTION]
This advanced option is for administrators that fully understand the configuration of their `${jetty.base}` and are willing to forego some of the safety checks built into the jetty-start mechanism.
____
--approve-all-licenses::
Approve all license questions.
Useful for enabling modules from a script that does not require user interaction.
===== Startup / Shutdown Command Line
--stop::
Sends a stop signal to the running Jetty instance.
+
Note: The server must have been started with various stop properties for this to work.
STOP.PORT=<number>;;
The port to use to stop the running Jetty server.
This is an internal port, opened on localhost, used solely for stopping the running Jetty server.
Choose a port that you do not use to serve web traffic.
+
Required for `--stop` to function.
STOP.KEY=<alphanumeric>;;
The passphrase defined to stop the server.
+
Required for `--stop` to function.
STOP.WAIT=<number>;;
The time (in seconds) to wait for confirmation that the running Jetty server has stopped.
If not specified, the stopper waits indefinitely for the server to stop.
+
If the time specified elapses, without a confirmation of server stop, then the `--stop` command exits with a non-zero return code.
You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the `STOP.PORT` and `STOP.KEY` (or `-DSTOP.PORT=` and `-DSTOP.KEY=`, respectively, which will set these as system parameters) parameters as arguments to the `start.jar`:
----
> java -jar ${JETTY_HOME}/start.jar STOP.PORT=1234 STOP.KEY=secretpassword
----
Then, to stop Jetty from a different terminal, you need to supply this port and key information.
You can either use a copy of the Jetty distribution, the link:#jetty-maven-plugin[jetty-maven-plugin], the link:#jetty-ant[jetty-ant plugin], or a custom class to accomplish this.
Here's how to use the Jetty distribution, leveraging `start.jar`, to perform a stop:
----
> java -jar start.jar STOP.PORT=8181 STOP.KEY=abc123 --stop
----
____
[NOTE]
To perform a graceful shutdown of Jetty, the `stats` link:#startup-modules[module] *must* be enabled.
____
===== Advanced Commands
--lib=<classpath>::
Add arbitrary classpath entries to the the server classpath.
--include-jetty-dir=<path>::
Include an extra Jetty directory to use as a source for configuration details.
This directory behaves similarly to `${jetty.base}` but sits at a layer between `${jetty.base}` and `${jetty.home}`.
This allows for some complex hierarchies of configuration details.
--download=<http-uri>|<location>::
If the file does not exist at the given location, download it from the given http URI.
Note: location is always relative to `${jetty.base}`.
You might need to escape the pipe "\|" to use this on some environments.
maven.repo.uri=[url]::
The url to use to download Maven dependencies.
Default is https://repo1.maven.org/maven2/.
==== Shaded Start.jar
If you have a need for a shaded version of `start.jar` (such as for Gradle), you can achieve this via a Maven dependency.
[source,xml]
----
<dependency>
<groupId>org.eclipse.jetty</groupId>
<artifactId>jetty-start</artifactId>
<version>{VERSION}</version>
<classifier>shaded</classifier>
</dependency>
----
==== Start.jar without exec or forking.
Some Jetty modules include the `--exec` option so that java command line options can be set.
Also some `start.jar` options (eg. `--jpms`) include an implicit `--exec`.
To start jetty without forking a new JVM instance from the start JVM, the `--dry-run` option can be used to generate a command line:
----
$ CMD=$(java -jar start.jar --dry-run)
$ $CMD
----
It is possible to decompose the start command so that it can be modified:
----
$ OPTS=$(java -jar start.jar --dry-run=opts,path)
$ MAIN=$(java -jar start.jar --dry-run=main)
$ ARGS=$(java -jar start.jar --dry-run=args)
$ java $OPTS -Dextra=opt $MAIN $ARGS extra=arg
----
Alternatively to create an args file for java:
----
$ java -jar start.jar --dry-run=opts,path,main,args > /tmp/args
$ java @/tmp/args
----

97
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-jpms.adoc Normal file
View File

@ -0,0 +1,97 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-start-start-jpms]]
==== Starting Jetty using JPMS
Jetty modules are proper https://en.wikipedia.org/wiki/Java_Platform_Module_System[JPMS] modules: each Jetty module has a `module-info.class` file.
This makes possible to run Jetty from the module-path, rather than the class-path.
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:
----
$ java -jar $JETTY_HOME/start.jar --jpms
----
[NOTE]
====
The `--jpms` option implies the `--exec` option.
When running on the module-path using the `--jpms` option, the Jetty start mechanism will fork a second JVM passing it the right JVM options to run on the module-path.
Therefore, you will have two JVMs running: one that runs `start.jar` and one that runs Jetty on the module-path.
====
When Jetty is started in JPMS mode, all JPMS modules in the module-path are added to the set of JPMS _root modules_ through the JVM option `--add-modules ALL_MODULE_PATH`.
For a `+*.jar+` file that is not a JPMS module, but is on the module-path, the JVM will assume internally it is an automatic JPMS module, with a JPMS module name derived from the `+*.jar+` file name.
Rather than adding the `--jpms` option to the command line, you can use a custom Jetty module to centralize your JPMS configuration, where you can specify additional JPMS directives.
Create the `$JETTY_BASE/modules/jpms.mod` file:
.jpms.mod
----
include::jpms.mod[]
----
The `[ini]` section with `--jpms` is equivalent to passing the `--jpms` option to the command line.
The `[jpms]` section allows you to specify additional JPMS configuration, for example additional `--add-modules` options, or `--add-opens` options, etc.
// TODO: add a link to the custom module section and the [jpms] section in there, see old_docs/startup/startup-jpms.adoc.
Then enable it:
----
$ java -jar $JETTY_HOME/start.jar --add-modules=jpms
----
Now you can start Jetty without extra command line options, and it will start in JPMS mode because you have enabled the `jpms` module.
[[og-start-start-jpms-advanced]]
===== Advanced JPMS Configuration
Web applications may need additional services from the Servlet Container, such as JDBC `DataSource` references or JTA `UserTransaction` references.
For example, for JDBC it is typical to store, in JNDI, a reference to the connection pool's `DataSource` or directly a reference to the JDBC driver's `DataSource` (for example, `org.postgresql.ds.PGConnectionPoolDataSource`).
Jetty needs to be able to instantiate those classes and therefore needs to be able to load those classes and all their super-classes, among which includes `javax.sql.DataSource`.
When Jetty runs on the class-path, this is easily achieved by using a xref:og-modules-custom[custom module] as explained in xref:og-start-configure-custom-module[this section].
However, when running on the module-path, things are quite different.
When Jetty tries to load, for example, class `org.postgresql.ds.PGConnectionPoolDataSource`, it must be in a JPMS module that is resolved in the run-time module graph.
Furthermore, any dependency, for example classes from the `java.sql` JPMS module, must also be in a module present in the resolved module graph.
Thanks to the fact that when Jetty starts in JPMS mode the `--add-modules ALL_MODULE_PATH` option is added to the JVM command line, every `+*.jar+` file in the module-path is also present in the module graph.
There are now two cases for the `postgresql-<version>.jar` file: either it is a proper JPMS module, or it is an automatic JPMS module (either an explicit automatic JPMS module with the `Automatic-Module-Name` attribute in the manifest, or an implicit automatic JPMS module whose name is derived from the `+*.jar+` file name).
If the `postgresql-<version>.jar` file is a proper JPMS module, then there is nothing more that you should do: the `postgresql-<version>.jar` file is in the module-path, and all the modules in the module-path are in the module graph, and any dependency declared in the `module-info.class` will be added to the module graph.
Otherwise, `postgresql-<version>.jar` file is an automatic module, and will likely have a dependency on the JDK-bundled `java.sql` JPMS module.
However, the `java.sql` JPMS module is not in the module graph, because automatic modules do not have a way to declare their dependencies.
For this reason, you have to manually add the `java.sql` dependency to the module graph.
Using the `postgresql.mod` introduced in xref:og-start-configure-custom-module[this section] as an example, modify your custom module in the following way:
.postgresql.mod
----
...
[jpms]
add-modules: java.sql
----
The `[jpms]` section is only used when Jetty is started on the module-path.

108
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-start.adoc Normal file
View File

@ -0,0 +1,108 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-start-start]]
==== Starting Jetty
After you have configured the `$JETTY_BASE` directory, as explained in xref:og-start-configure[this section], you can start Jetty as a standalone server.
In the _start_ mode, the Jetty start mechanism computes a JVM command line with JVM options, system properties, class-path, module-path, main class and program arguments, and then executes it, forking a new JVM if necessary.
The Jetty start mechanism performs these steps:
. Loads all the Jetty modules files (that have extension `+*.mod+`) from the `modules/` subdirectory of each configuration source directory (see xref:og-start-configure[this section] for the list of configuration sources).
In this way, a Jetty module graph can be built in memory, where the module dependencies form the edges of the graph and each node contains the metadata information declared by each module (for example, the libraries that it needs, the XML files to process, and so on), in preparation for the next step.
. Reads the Jetty module configuration files (that have extension `+*.ini+`) from the `start.d/` subdirectory of each configuration source directory and from the command line.
This step produces a list of _enabled_ modules; for each enabled module all its dependencies are transitively resolved by navigating the graph built in the previous steps.
. Processes the list of enabled (explicitly and transitively) modules, gathering the list of libraries to add to the class-path, the JPMS directives to add to the command line, the properties and XML files to add as program arguments, etc., so that a full JVM command line can be generated.
. Executes the command line, either in-JVM or by forking a second JVM (if the `--exec` option is present or implied by other options such as `--jpms`), and waits for the JVM, or the forked JVM, to exit.
[[og-start-start-class-path]]
===== Server Class-Path
When the Jetty server is started in-JVM, the server class-path gathered by processing the enabled modules is organized in a `URLClassLoader`, the Jetty Start ClassLoader, that is a child of the System ClassLoader:
[plantuml]
----
skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false
skinparam roundCorner 10
rectangle "Jetty Start JVM" {
rectangle "System ClassLoader" as system
rectangle "Jetty Start ClassLoader" as start
note right of system: start.jar
note right of start: jetty-server.jar\njetty-http.jar\njetty-io.jar\njetty-util.jar\njetty-xml.jar\netc.
system <-- start
}
----
The System ClassLoader only has `$JETTY_HOME/start.jar` in its class-path, since the JVM was started with `java -jar $JETTY_HOME/start.jar`.
The Jetty Start ClassLoader has in its class-path the `+*.jar+` files gathered by processing the enabled modules, typically from `+$JETTY_HOME/lib/jetty-*.jar+`, but possibly also from `+$JETTY_BASE/lib/*.jar+` if custom modules extend the server class-path with their own `+*.jar+` files.
When the Jetty server is started in a forked JVM, there will be two JVMs: one started by you with `java -jar $JETTY_HOME/start.jar` and one forked by the Jetty start mechanism.
In the forked JVM, the System ClassLoader has the server class-path and/or module-path in its class-path, since the forked JVM is started with `+java --class-path $JETTY_HOME/lib/jetty-server-<version>.jar:...+`:
[plantuml]
----
skinparam backgroundColor transparent
skinparam monochrome true
skinparam shadowing false
skinparam roundCorner 10
rectangle "Jetty Start JVM" as startJVM {
rectangle "System ClassLoader" as system1
note right of system1: start.jar
}
rectangle "Forked JVM" as forkedJVM {
rectangle "System ClassLoader" as system2
note right of system2: jetty-server.jar\njetty-http.jar\njetty-io.jar\njetty-util.jar\njetty-xml.jar\netc.
}
startJVM --> forkedJVM: " waits for"
----
It is worth mentioning that there are two standard Jetty modules that allow you to easily add entries to the Jetty server class-path:
* The `resources` module, that adds the `$JETTY_BASE/resources/` directory to the server class-path.
This is useful if you have third party libraries that lookup resources from the class-path: just put those resources in the `$JETTY_BASE/resources/` directory. +
Logging libraries often perform class-path lookup of their configuration files (for example, `log4j.properties`, `log4j.xml`, `logging.properties`, and `logback.xml`), so `$JETTY_BASE/resources/` is the ideal place to add those files. +
* The the `ext` module, that adds all the `+*.jar+` files under the `$JETTY_BASE/lib/ext/` directory, and subdirectories recursively, to the server class-path. +
+
[CAUTION]
====
On one hand, the `ext` module provides a handy place to put third party libraries and their dependencies; on the other hand, the `$JETTY_BASE/lib/ext/` directory may become a confused mixture of many `+*.jar+` files from different third party libraries.
Prefer to group third party libraries and their dependencies into their own directories using xref:og-modules-custom[custom modules], or at least group them into `$JETTY_BASE/lib/ext/` subdirectories such as `$JETTY_BASE/lib/ext/util/` or `$JETTY_BASE/lib/ext/acme/`.
====
[[og-start-start-xml]]
===== Assembling Jetty Components
The Jetty start mechanism eventually invokes, by default, main class `org.eclipse.jetty.xml.XmlConfiguration`, passing properties and xref:og-xml[Jetty XML files] as program arguments.
The Jetty XML files are nothing more than Java code in XML format.
The XML files are processed to instantiate Jetty components such as `org.eclipse.jetty.server.Server` or `org.eclipse.jetty.util.ssl.SslContextFactory`.
The components are then assembled together to provide the configured Jetty features.
The Jetty XML files are parametrized using properties; a property is just a name/value pair.
This parametrization of the XML files allows an XML file that resides in `$JETTY_HOME/etc/` to _declare_ a property such as `jetty.http.port`, and allow this property to be set in a `$JETTY_BASE/start.d/http.ini` file, so that you don't need to change the XML files in `$JETTY_HOME`, but only change files in your `$JETTY_BASE`.
You can write your own xref:og-modules-custom[custom modules] with your own Jetty XML files, and your own properties, to further customize Jetty.

78
documentation/jetty-documentation/src/main/asciidoc/operations-guide/start/start-stop.adoc Normal file
View File

@ -0,0 +1,78 @@
//
// ========================================================================
// Copyright (c) 1995-2021 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License v. 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
// which is available at https://www.apache.org/licenses/LICENSE-2.0.
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-start-stop]]
==== Stopping Jetty
When Jetty is started, the Jetty components that you have configured by enabling Jetty modules are assembled and started.
If you have started Jetty from a terminal, you can exit the Jetty JVM by hitting kbd:[Ctrl+C] on the same terminal.
Similarly, from a different terminal, you can exit the Jetty JVM using `kill -INT <pid>` or `kill -TERM <pid>`.
In the three cases above, the JVM is exited, but by default Jetty components are not stopped.
If you want to stop the Jetty components, to stop Jetty more gracefully, you can start Jetty with this property:
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar ##jetty.server.stopAtShutdown=true##
----
This property can also be set in `$JETTY_BASE/start.d/server.ini` so that it is persistently configured across Jetty restarts (see also xref:og-module-server[the `server` module]).
The `jetty.server.stopAtShutdown` property configures a JVM shutdown hook that is run, stopping the `Server` instance, when the JVM exits.
Obviously, the JVM can also be stopped with `kill -KILL <pid>` that exits the process abruptly without running the JVM shutdown hooks.
[[og-start-stop-remote]]
===== Stopping Jetty from Remote
You can configure a Jetty server so that it can be stopped by remote clients using a command sent through a TCP socket.
You can start Jetty with the following properties:
* `stop.host`, the host name Jetty will bind to listen for stop commands. Defaults to `127.0.0.1` which means that the stop command can be issued only clients that run on the same host as Jetty.
* `stop.port`, the port number Jetty will listen to for stop commands. Defaults to `-1`, which means that Jetty will not listen to any port.
* `stop.key`, the password to verify when a stop command is received. Defaults to a password that is randomly generated and printed when Jetty starts.
[source,subs=quotes]
----
$ java -jar $JETTY_HOME/start.jar ##stop.port=8181##
----
[source,subs=quotes,options=nowrap]
----
include::jetty[setupArgs="--add-modules=http",args="stop.port=8181",highlight="(?i)stop.key"]
----
In the example above, Jetty is started with just the `stop.port` property, and the `stop.key` is printed on the terminal when Jetty starts.
CAUTION: You can choose your own `stop.key`, but make sure it's a strong password.
A remote client can now use the Jetty start mechanism to stop the remote Jetty server:
[source,subs=normal]
----
$ java -jar $JETTY_HOME/start.jar ##--stop## stop.port=8181 stop.key=<stop.key>
----
Note the `--stop` command along with the `stop.port` and `stop.key` properties.
The `stop.key` must be the same as the one of remote Jetty server, either the one you chose, or the one printed on the terminal when Jetty starts.
Remote clients can wait for the remote Jetty server to shut down by specifying the `stop.wait` property with the number of seconds to wait:
----
$ java -jar $JETTY_HOME/start.jar --stop stop.port=8181 stop.key=<stop.key> stop.wait=15
----
If the time specified elapses, without the confirmation that the remote Jetty server stopped, then the `--stop` command exits with a non-zero return code.

54
documentation/jetty-documentation/src/main/asciidoc/operations-guide/troubleshooting/troubleshooting-dump.adoc
View File

@ -73,59 +73,7 @@ Below you can find a simple example of a Jetty Server Dump, with annotations for
[source,subs=verbatim,role=small,options=nowrap] [source,subs=verbatim,role=small,options=nowrap]
---- ----
Server@3ee0fea4{STARTING}[10.0.0,sto=5000] - STARTED <1> include::jetty[setupArgs="--add-modules=http",args="jetty.http.selectors=1 jetty.http.acceptors=1 jetty.threadPool.minThreads=4 jetty.server.dumpAfterStart=true",delete="^[0-9]{4}",callouts=" <$N>,Server@,= QueuedThreadPool,(?i)ACCEPTING,(?i)SELECTING,HandlerList@,= ServerConnector,ManagedSelector@,keys @,startJarLoader@,unmanaged"]
+= QueuedThreadPool[qtp1924582348]@72b6cbcc{STARTED,4<=4<=200,i=2,r=12,q=0}[ReservedThreadExecutor@64cd705f{s=0/12,p=0}] - STARTED <2>
| += ReservedThreadExecutor@64cd705f{s=0/12,p=0} - STARTED
| +> threads size=10
| +> qtp1924582348-14-acceptor-0@65a7a043-ServerConnector@5c909414{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} RUNNABLE tid=14 prio=3 ACCEPTING <3>
| +> qtp1924582348-13 RUNNABLE tid=13 prio=5 SELECTING <4>
| +> qtp1924582348-15 TIMED_WAITING tid=15 prio=5 IDLE
| +> qtp1924582348-16 TIMED_WAITING tid=16 prio=5 IDLE
+- org.eclipse.jetty.io.ArrayByteBufferPool@6a28ffa4
+= ScheduledExecutorScheduler@31f924f5{STARTED} - STARTED
+= HandlerList@48ae9b55{STARTED} - STARTED <5>
| += ContextHandlerCollection@1700915{STARTED} - STARTED
| += DefaultHandler@21de60b4{STARTED} - STARTED
+= ServerConnector@5c909414{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} - STARTED <6>
| +~ QueuedThreadPool[qtp1924582348]@72b6cbcc{STARTED,10<=10<=200,i=8,r=12,q=0}[ReservedThreadExecutor@64cd705f{s=0/12,p=0}] - STARTED
| +~ ScheduledExecutorScheduler@31f924f5{STARTED} - STARTED
| +- org.eclipse.jetty.io.ArrayByteBufferPool@6a28ffa4
| +- org.eclipse.jetty.server.AbstractConnector$1@c267ef4
| += HttpConnectionFactory@29ba4338[HTTP/1.1] - STARTED
| | +- HttpConfiguration@1139b2f3{32768/8192,8192/8192,https://:0,[]}
| += SelectorManager@ServerConnector@5c909414{HTTP/1.1, (http/1.1)}{0.0.0.0:8080} - STARTED
| | += ManagedSelector@636be97c{STARTED} id=0 keys=0 selected=0 updates=0 - STARTED <7>
| | += EatWhatYouKill@50a638b5/SelectorProducer@1817d444/PRODUCING/p=false/QueuedThreadPool[qtp1924582348]@72b6cbcc{STARTED,10<=10<=200,i=8,r=12,q=0}[ReservedThreadExecutor@64cd705f{s=0/12,p=0}][pc=0,pic=0,pec=0,epc=0]@2021-01-11T13:08:00.333168316+01:00 - STARTED
| | | +- SelectorProducer@1817d444
| | | +~ QueuedThreadPool[qtp1924582348]@72b6cbcc{STARTED,10<=10<=200,i=8,r=12,q=0}[ReservedThreadExecutor@64cd705f{s=0/12,p=0}] - STARTED
| | +> updates @ 2021-01-11T13:08:00.331898257+01:00 size=0
| | +> keys @ 2021-01-11T13:08:00.332436637+01:00 size=1 <8>
| | +> SelectionKey@306e0284{i=1}->SocketChannelEndPoint@330eef1{l=/[0:0:0:0:0:0:0:1]:8080,r=/[0:0:0:0:0:0:0:1]:36402,OPEN,fill=FI,flush=-,to=17713/30000}{io=1/1,kio=1,kro=1}->HttpConnection@198220f9[p=HttpParser{s=START,0 of -1},g=HttpGenerator@7f14183e{s=START}]=>HttpChannelOverHttp@61ec57fb{s=HttpChannelState@2ebfced8{s=IDLE rs=BLOCKING os=OPEN is=IDLE awp=false se=false i=true al=0},r=2,c=false/false,a=IDLE,uri=null,age=0}
| +- sun.nio.ch.ServerSocketChannelImpl[/[0:0:0:0:0:0:0:0]:8080]
| +- qtp1924582348-14-acceptor-0@65a7a043-ServerConnector@5c909414{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
+= ErrorHandler@6ca8564a{STARTED} - STARTED
+> startJarLoader@41975e01 <9>
+> URLs size=9
| +> file:/tmp/jetty.base/resources/
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/logging/slf4j-api-2.0.0-alpha1.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/logging/jetty-slf4j-impl-10.0.1-SNAPSHOT.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/jetty-servlet-api-4.0.5.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/jetty-http-10.0.1-SNAPSHOT.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/jetty-server-10.0.1-SNAPSHOT.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/jetty-xml-10.0.1-SNAPSHOT.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/jetty-util-10.0.1-SNAPSHOT.jar
| +> file:/home/simon/opensource/jetty/jetty10.0/jetty-home/target/jetty-home/lib/jetty-io-10.0.1-SNAPSHOT.jar
+> jdk.internal.loader.ClassLoaders$AppClassLoader@5bc2b487
+> packages size=4
| +> package org.eclipse.jetty.start.config
| +> package org.eclipse.jetty.start.builders
| +> package org.eclipse.jetty.start.shaded.util
| +> package org.eclipse.jetty.start
+> jdk.internal.loader.ClassLoaders$PlatformClassLoader@3d51f06e
+> packages size=2
+> package sun.util.resources.provider
+> package sun.util.resources.cldr.provider
key: +- bean, += managed, +~ unmanaged, +? auto, +: iterable, +] array, +@ map, +> undefined <10>
---- ----
<1> The `Server` instance at the root of the tree <1> The `Server` instance at the root of the tree
<2> The thread pool component <2> The thread pool component

10
documentation/jetty-documentation/src/main/asciidoc/toc.js
View File

@ -14,12 +14,20 @@
document.addEventListener('DOMContentLoaded', () => dynamicTOC()); document.addEventListener('DOMContentLoaded', () => dynamicTOC());
function dynamicTOC() { function dynamicTOC() {
// Bind a click listener to all section titles.
const content = document.getElementById('content'); const content = document.getElementById('content');
// Bind a click listener to all section titles.
const sectionTitles = content.querySelectorAll('a.link'); const sectionTitles = content.querySelectorAll('a.link');
for (const sectionTitle of sectionTitles) { for (const sectionTitle of sectionTitles) {
sectionTitle.addEventListener('click', event => collapseThenExpand(event.target.hash)); sectionTitle.addEventListener('click', event => collapseThenExpand(event.target.hash));
} }
// Bind a click listener to all inline links to documentation sections.
const inlineLinks = content.querySelectorAll('p > a');
for (const inlineLink of inlineLinks) {
const hash = inlineLink.hash || '';
if (hash.startsWith('#')) {
inlineLink.addEventListener('click', event => collapseThenExpand(event.target.hash));
}
}
// Bind a click listener to all TOC titles. // Bind a click listener to all TOC titles.
const toc = document.getElementById('toc'); const toc = document.getElementById('toc');

14
jetty-home/src/main/resources/README.adoc
View File

@ -11,13 +11,14 @@ Jetty is available under an open source link:LICENSE.txt[LICENSE], and the full
The Jetty documentation is available at link:https://www.eclipse.org/jetty/documentation[]. The Jetty documentation is available at link:https://www.eclipse.org/jetty/documentation[].
// tag::quick[] // tag::quick[]
==== Quick Jetty Setup ==== Quick Setup
Jetty is distributed in an artifact that expands in a directory called `$JETTY_HOME`, which should not be modified. Jetty is distributed in an artifact that expands in a directory called `$JETTY_HOME`, which should not be modified.
Configuration for Jetty is typically done in one (or more) other directories called `$JETTY_BASE`. Configuration for Jetty is typically done in a directory called `$JETTY_BASE`.
There may be more than one `$JETTY_BASE` directories with different configurations.
The following commands can be used to setup a `$JETTY_BASE` directory that supports deployment of `+*.war+` files and a clear-text HTTP connector: The following commands can be used to set up a `$JETTY_BASE` directory that supports deployment of `+*.war+` files and a clear-text HTTP connector:
---- ----
$ export JETTY_HOME=/path/to/jetty-home $ export JETTY_HOME=/path/to/jetty-home
@ -26,7 +27,7 @@ $ cd /path/to/jetty-base
$ java -jar $JETTY_HOME/start.jar --add-module=server,http,deploy $ java -jar $JETTY_HOME/start.jar --add-module=server,http,deploy
---- ----
This will create a `$JETTY_BASE/start.d/` directory and other directories that contain the configuration of the server, including the `$JETTY_BASE/webapps/` directory, in which standard `+*.war+` files can be deployed. The last command creates a `$JETTY_BASE/start.d/` directory and other directories that contain the configuration of the server, including the `$JETTY_BASE/webapps/` directory, in which standard `+*.war+` files can be deployed.
To deploy Jetty's demo web applications, run this command: To deploy Jetty's demo web applications, run this command:
@ -40,9 +41,9 @@ Now you can start the Jetty server with:
$ java -jar $JETTY_HOME/start.jar $ java -jar $JETTY_HOME/start.jar
---- ----
Point your browser at `+http://localhost:8080+` to see the web applications deployed in Jetty. Point your browser at `+http://localhost:8080+` to see the demo web applications deployed in Jetty.
The Jetty server can be stopped with `ctrl-c` in the terminal window. The Jetty server can be stopped with `ctrl+c` in the terminal window.
// end::quick[] // end::quick[]
For more information about how to start Jetty, run this command (or go to the link:https://www.eclipse.org/jetty/documentation[documentation]): For more information about how to start Jetty, run this command (or go to the link:https://www.eclipse.org/jetty/documentation[documentation]):
@ -50,4 +51,3 @@ For more information about how to start Jetty, run this command (or go to the li
---- ----
$ java -jar $JETTY_HOME/start.jar --help $ java -jar $JETTY_HOME/start.jar --help
---- ----

2
jetty-start/src/main/java/org/eclipse/jetty/start/StartArgs.java
View File

@ -778,7 +778,7 @@ public class StartArgs
} }
else else
{ {
cmd.addRawArg("-cp"); cmd.addRawArg("--class-path");
cmd.addRawArg(classpath.toString()); cmd.addRawArg(classpath.toString());
} }
} }

428
jetty-start/src/main/resources/org/eclipse/jetty/start/usage.txt
View File

@ -1,22 +1,28 @@
Usage: java -jar start.jar [options...] [properties...] [configs...] Usage:
The start.jar builds a classpath and executes a main java class with $ java -jar $JETTY_HOME/start.jar [command] [options...]
a classloader built from that classpath. By default the start.jar
mechanism is configured to start the jetty server, but it can be
configured to start any java main class.
Command Line Options: Commands can be of two types: report commands or configuration commands.
--------------------- Commands execute and then exit the JVM.
Options can be specified with or without commands.
When no command is specified, Jetty is started with the given options.
--help This help / usage information. Report Commands:
----------------
--version Print the version information for Jetty and --help
dependent jars, then exit. Prints this help / usage information.
--list-classpath Print the classpath information that will be used to start --version
Jetty Prints the version information for Jetty and
dependent jars, then exits.
--list-config List the resolved configuration that will be used to --list-classpath
Prints the classpath information that will be used to
start Jetty.
--list-config
Lists the resolved configuration that will be used to
start Jetty. start Jetty.
Output includes: Output includes:
o Enabled jetty modules o Enabled jetty modules
@ -29,248 +35,224 @@ Command Line Options:
o Java Classpath o Java Classpath
o XML Configuration files o XML Configuration files
--dry-run Print the command line that the start.jar generates, --list-modules
then exit. This may be used to generate command lines Lists the modules defined in ${jetty.base}/modules/*.mod
when the start.ini includes -X or -D arguments: and then in ${jetty.home}/modules/*.mod.
java -jar start.jar --dry-run > jetty.sh --list-modules=<tag>(,<tag>)*
. jetty.sh Lists the modules by tag. Use '*' for all tags.
Prefix a tag with '-' to exclude the tag.
The special tag "internal" is always excluded unless it is
explicitly included.
--dry-run=parts Print specific parts of the command line. The parts --list-all-modules
are a comma separated list of Lists all modules.
--show-modules=<module>(,<module>)*
Shows the detail of the listed modules, including
dependencies, tags, libraries and XMLs.
--stop
Sends a stop signal to the running Jetty instance.
The running Jetty instance must have been started with a
stop.port=<port> property and the --stop command must
be executed with the same property.
--dry-run
Prints the command line that start.jar generates,
then exits.
This may be used to generate command lines into scripts:
$ java -jar start.jar --dry-run > jetty.sh
--dry-run=<part>(,<part>)*
Prints specific parts of the command line. The parts are:
o "java" - the JVM to run o "java" - the JVM to run
o "opts" - the JVM options (eg -D and -X flags) o "opts" - the JVM options (e.g. -D, -X and -XX flags)
o "path" - the JVM class path or JPMS modules options o "path" - the JVM class-path and/or the JPMS module-path
o "main" - the main class to run o "main" - the main class to run
o "args" - the arguments passed to the main class o "args" - the arguments passed to the main class
It is possible to decompose the start command: Configure Commands:
-------------------
OPTS=$(java -jar start.jar --dry-run=opts,path) --add-modules=<modulename>(,<modulename>)*
MAIN=$(java -jar start.jar --dry-run=main) Adds the given modules to the list of modules enabled at
ARGS=$(java -jar start.jar --dry-run=args) when Jetty starts.
java $OPTS -Dextra=opt $MAIN $ARGS extra=arg Transitive dependencies are followed and dependent
modules may also explicitly added.
Modules are added by creating an *.ini file in the
${jetty.base}/start.d/ directory.
The *.ini file contains the --module option that enables
the module, and any other option defined in the module's
[ini-template] section.
If the *.ini file specifies properties, these may be
overridden by specifying the same properties on the
command line.
Alternatively to create an args file for java: If a module is transitively enabled, its *.ini file will
not be generated.
To generate the *.ini file, the module must be explicitly
listed in the --add-modules=... command.
java -jar start.jar --dry-run=opts,path,main,args > /tmp/args This option replaces the deprecated --add-to-start and
java @/tmp/args --add-to-startd commands.
--create-start-d
Creates a ${jetty.base}/start.d directory.
If the ${jetty.base}/start.ini file exists, then it is
moved into the ${jetty.base}/start.d/ directory.
Using a ${jetty.base}/start.d/ directory is the default and
this option is only needed to either force the creation of
the ${jetty.base}/start.d/ directory, or to move a
${jetty.base}/start.ini file to ${jetty.base}/start.d/.
--create-start-ini
Creates a ${jetty.base}/start.ini file.
If a ${jetty.base}/start.d/ directory exists, then all
the contained *.ini files are concatenated into the
${jetty.base}/start.ini file.
--update-ini
Scans all the ${jetty.base}/start.d/*.ini files and updates
any property with values specified on the command line.
For example:
$ java -jar ${jetty.host}/start.jar --update-ini jetty.http.port=8888
--create-files
Creates any missing files that are required by enabled
modules, as specified in their [files] section.
This may download a file from the network if a HTTP URI
is specified in the [files] section.
--write-module-graph=<filename>
Creates a graphviz *.dot file of the module graph as it
is configured for the current ${jetty.base}.
See https://graphviz.org/ for details on how to post-process
this file into the output best suited for your needs.
Options:
--------
--module=<modulename>(,<modulename>)*
Enables a module for this execution.
To enable a module for all future executions, use the
--add-modules command.
Note: this option is used in the ${jetty.base}/start.ini
file or in ${jetty.base}/start.d/*.ini files created by
the --add-modules command.
--lib=<classpath>
Adds the specified classpath entries to the the server
classpath.
--download=<http-uri>|<location>
Downloads a file from the given HTTP URI, if it does
not already exist at the given location.
Note: the location is always relative to ${jetty.base}.
You might need to escape the pipe "\|" to use it in
some shell environments.
--exec
Executes the generated command line (see --dry-run) in
a sub process.
This can be used when ${jetty.base}/start.d/*.ini files
contain -D, -X or -XX arguments, but creates an extra
JVM process.
--exec Run the generated command line (see --dry-run) in
a sub process. This can be used when start.ini
contains -X or -D arguments, but creates an extra
JVM instance.
--exec-properties=<filename> --exec-properties=<filename>
Assign a fixed name to the file used to transfer Assigns a fixed name to the file used to transfer
properties to the sub process. This allows the properties to the sub process. This allows the
generated properties file to be saved and reused. generated properties file to be saved and reused.
Without this option, a temporary file is used. Without this option, a temporary file is used.
--commands=<filename> --commands=<filename>
Use each line of the file as arguments on the command Uses each line of the specified file as arguments on the
line. JVM command line.
Debug and Start Logging: --debug
------------------------ Enables debug output of the startup execution.
Note: this does not setup debug logging for Jetty itself,
--debug Enable debug output of the startup procedure. only for the startup execution.
Note: this does not setup debug for Jetty itself. If you want debug logging for Jetty, configure one of the
If you want debug for Jetty, configure your logging. available logging modules using the --add-modules command.
https://www.eclipse.org/jetty/documentation/
--start-log-file=<filename> --start-log-file=<filename>
A filename, relative to ${jetty.base}, where all startup A filename, relative to ${jetty.base}, where all startup
output will be sent. This is useful for capturing startup output will be sent. This is useful for capturing startup
issues where the jetty specific logger has not yet kicked issues when the Jetty logging module has not yet started
in due to startup configuration errors. due to configuration errors.
Jetty Module Management:
------------------------
--list-modules List Jetty modules defined in ${jetty.base}/modules/*.mod and
then ${jetty.home}/modules/*.mod
--list-modules=<tag>(,<tag>)*
List modules by tag. Use '*' for all tags. Prefix a tag
with '-' to exclude the tag. The special tag "internal"
is always excluded unless it is explicitly included.
--list-all-modules
List all modules.
--show-modules=<module>(,<module>)*
Show the detail of the listed modules, including
dependencies, tags, libraries and XMLs
--module=<modulename>(,<modulename>)*
Enable a module for this run. To enable a module for all
future runs, use --add-module
Note: this option is used in the ${jetty.base}/start.ini
or ${jetty.base}/start.d/*.ini files created by --add-module.
--add-module=<modulename>(,<modulename>)*
Add the modules to the list of modules enabled at start.
Transitive dependencies are followed and dependent
modules may also explicitly added.
Modules are added to the start by creating an ini file
that contains the --module argument and any other parameters
defined in the modules ini template.
If the ${jetty.base}/start.ini file exists, configuration is
appended, otherwise the directory ${jetty.base}/start.d
is used to create <modulename>.ini files.
If the ini template contains properties, these may be
amended in the generated file by specifying those
properties on the command line.
If a module is transitively enabled, its ini file will not
be generated. An explicit --add-module is required to generate
an ini file.
This option replaces the deprecated --add-to-start and --add-to-startd.
--update-ini Scan all start.ini and start.d/*.ini files and update
any properties with values specified on the command
line. e.g. --update-ini jetty.http.port=8888
--create-start-d
Create a ${jetty.base}/start.d directory. If a ${jetty.base}/start.ini
files exists, then it is moved into start.d. Using a start.d directory
is the default and this option is only needed to either force the creation of a
${jetty.home}/start.d or to move a start.ini file to start.d
--create-start-ini
Create a ${jetty.base}/start.ini file. If a ${jetty.base}/start.d
directory exists, then all its contained ini files are concatenated into
the start.ini file.
--write-module-graph=<filename>
Create a graphviz *.dot file of the module graph as it
exists for the active ${jetty.base}.
See http://graphviz.org/ for details on how to post-process
this file into the output best suited for your needs.
--create-files Create any missing files that are required by initialized
modules. This may download a file from the network if the
module provides a URL.
--skip-file-validation=<modulename>(,<modulename)*
Disable the [files] section validation of content
in the ${jetty.base} directory for a specific
module. Useful for modules that have downloadable
content that is being overridden with alternatives
in the ${jetty.base} directory.
CAUTION:
This advanced option is for administrators that
fully understand the configuration of their
${jetty.base} and are willing to forego some of the
safety checks built into the jetty-start mechanism.
--approve-all-licenses --approve-all-licenses
Approve all license questions. Useful for enabling Approves all license questions from modules that have
modules from a script that does not require user interaction. particular license requirements.
Useful for enabling modules from a script, so that it
does not require user interaction.
Startup / Shutdown Command Line: --skip-file-validation=<modulename>(,<modulename>)*
-------------------------------- Disables the creation of files as specified by the
[files] section of the specified modules.
--stop Send a stop signal to the running Jetty instance. Useful if a logging module specifies a *.properties
The server must have been started with a STOP.PORT=<port> config file, but you want to use that module with an
property set and the stop command must have the same property. *.xml config file instead.
Advanced Commands:
------------------
--lib=<classpath>
Add arbitrary classpath entries to the the server classpath.
--include-jetty-dir=<path> --include-jetty-dir=<path>
Include an extra jetty directory to use as a source Includes the specified directory as a configuration source.
for configuration details. This directory behaves similarly This directory behaves similarly to ${jetty.base} but sits
to ${jetty.base} but sits at a layer between ${jetty.base} at a layer between ${jetty.home} and ${jetty.base}.
and ${jetty.home}. This allows for some complex hierarchies Useful when you want to apply a common "corporate"
of configuration details. configuration to all specific ${jetty.base} directories
without having to modify ${jetty.home}.
--download=<http-uri>|<location> jetty.home=<directory>
Advanced usage, If the file does not exist at the given Sets the ${jetty.home} directory.
location, download it from the given http URI. By default it is resolved from the start.jar file path.
Notes: location is always relative to ${jetty.base}.
you might need to escape the pipe "\|" to use
this on some environments.
maven.repo.uri=[url]
The url to use to download Maven dependencies.
Default is https://repo1.maven.org/maven2/.
jetty.base=<directory>
Sets the ${jetty.base} directory.
By default it is resolved from the current directory path.
Properties: stop.host=<string>
----------- Used with the --stop command.
Properties are used to parameterize: Specifies the host where the Jetty server to stop is
+ XML files using the <Property name="pname"/> element running (defaults to 127.0.0.1).
+ Module files using the ${pname} syntax
Properties and System Properties may be set on the command line, stop.port=<number>
in a ini file or in a [ini] section of a module using the following syntax: Used with the --stop command.
Specifies the port to use to contact the Jetty server
to stop.
name=value stop.key=<alphanumeric>
Set a property that can be expanded in XML files with the <Property> element. Used with the --stop command.
The passphrase required to stop the Jetty server.
name+=value stop.wait=<number>
Append value to an existing property value. Used with the --stop command.
The time, in seconds, to wait for confirmation that the
name+=,value running Jetty server has stopped.
Append value to an existing property value, using a comma separator if needed. If not specified, the stopper will not wait.
name?=value maven.repo.uri=<url>
Set a property only if it is not already set. The base URL to use to download Maven dependencies.
Defaults to: https://repo1.maven.org/maven2/.
If any of the previous formats is preceded by -D, then a system property is set <name>=<value>
as well as a start property. Specifies a property value that overrides the same
property defined in a ${jetty.base}/start.d/*.ini file,
Each module may define its own properties. Start properties defined include: or in the [ini] section of a *.mod file.
jetty.home=[directory] <name>=<value>
Set the home directory of the jetty distribution. Sets the property unconditionally.
<name>+=<value>
Appends the given value to the existing value.
<name>?=<value>
Sets the property only if it is not already set.
jetty.base=[directory] -D<name>=<value>
Set the jetty configuration directory. This is where the etc, webapps and start Specifies a system property, as well as a start property.
files will be looked for. If not found in jetty.base, they are looked for in Note: this is a program argument that is interpreted and
jetty.home. added to the existing JVM system properties.
STOP.HOST=[string] <xml-file>
The host to use to stop the running Jetty server (defaults to 127.0.0.1) Specifies a Jetty XML file relative to ${jetty.base}.
Required along with STOP.PORT if you want to use the --stop option above. This file is in addition to the Jetty XML files resolved
from the [xml] sections of the enabled modules.
STOP.PORT=[number]
The port to use to stop the running Jetty server.
Required along with STOP.KEY if you want to use the --stop option above.
STOP.KEY=[alphanumeric]
The passphrase defined to stop the server.
Required along with STOP.PORT if you want to use the --stop option above.
STOP.WAIT=[number]
The time (in seconds) to wait for confirmation that the running
Jetty server has stopped. If not specified, the stopper will wait
indefinitely. Use in conjunction with the --stop option.
maven.repo.uri=[url] default https://repo1.maven.org/maven2/.
The url to use to download Maven dependencies.
Defaults:
---------
Command line arguments can come from any jetty configuration directory
(except ${jetty.home}), such as ${jetty.base} and any added jetty directories
(see --include-jetty-dir=<path>).
The contents of <path>/start.ini and <path>/start.d/*.ini are all used
to build up your command line arguments.
In case of a conflict, the resolution of who wins, will look like this.
1) <command-line itself>
2) ${jetty.base}/start.ini
3) ${jetty.base}/start.d/*.ini
4) <jetty-dir>/start.ini
5) <jetty-dir>/start.d/*.ini
For more information on startup, see the online documentation at
https://www.eclipse.org/jetty/documentation/

94
tests/test-distribution/src/main/java/org/eclipse/jetty/tests/distribution/JettyHomeTester.java
View File

@ -28,6 +28,7 @@ import java.nio.file.Path;
import java.nio.file.Paths; import java.nio.file.Paths;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Arrays; import java.util.Arrays;
import java.util.Collections;
import java.util.HashMap; import java.util.HashMap;
import java.util.List; import java.util.List;
import java.util.Map; import java.util.Map;
@ -107,7 +108,7 @@ public class JettyHomeTester
{ {
private static final Logger LOGGER = LoggerFactory.getLogger(JettyHomeTester.class); private static final Logger LOGGER = LoggerFactory.getLogger(JettyHomeTester.class);
private Config config; private final Config config;
private JettyHomeTester(Config config) private JettyHomeTester(Config config)
{ {
@ -126,12 +127,12 @@ public class JettyHomeTester
public Path getJettyBase() public Path getJettyBase()
{ {
return config.jettyBase; return config.getJettyBase();
} }
public Path getJettyHome() public Path getJettyHome()
{ {
return config.jettyHome; return config.getJettyHome();
} }
/** /**
@ -141,30 +142,23 @@ public class JettyHomeTester
*/ */
public JettyHomeTester.Run start(List<String> args) throws Exception public JettyHomeTester.Run start(List<String> args) throws Exception
{ {
File jettyBaseDir = config.jettyBase.toFile(); File jettyBaseDir = getJettyBase().toFile();
Path workDir = Files.createDirectories(jettyBaseDir.toPath().resolve("work")); Path workDir = Files.createDirectories(jettyBaseDir.toPath().resolve("work"));
List<String> commands = new ArrayList<>(); List<String> commands = new ArrayList<>();
commands.add(getJavaExecutable()); commands.add(getJavaExecutable());
if (!config.jvmArgs.isEmpty()) commands.addAll(config.getJVMArgs());
{
commands.addAll(config.jvmArgs);
}
commands.add("-Djava.io.tmpdir=" + workDir.toAbsolutePath().toString()); commands.add("-Djava.io.tmpdir=" + workDir.toAbsolutePath().toString());
commands.add("-jar"); commands.add("-jar");
commands.add(config.jettyHome.toAbsolutePath() + "/start.jar"); commands.add(config.jettyHome.toAbsolutePath() + "/start.jar");
args = new ArrayList<>(args); args = new ArrayList<>(args);
if (StringUtil.isNotBlank(config.mavenLocalRepository)) String mavenLocalRepository = config.getMavenLocalRepository();
{ if (StringUtil.isNotBlank(mavenLocalRepository))
args.add("maven.local.repo=" + config.mavenLocalRepository); mavenLocalRepository = System.getProperty("mavenRepoPath");
} if (StringUtil.isNotBlank(mavenLocalRepository))
else if (StringUtil.isNotBlank(System.getProperty("mavenRepoPath"))) args.add("maven.local.repo=" + mavenLocalRepository);
{
// we get artifacts from local repo first
args.add("maven.local.repo=" + System.getProperty("mavenRepoPath"));
}
// if this JVM has `maven.repo.uri` defined, make sure to propagate it to child // if this JVM has `maven.repo.uri` defined, make sure to propagate it to child
String remoteRepoUri = System.getProperty("maven.repo.uri"); String remoteRepoUri = System.getProperty("maven.repo.uri");
@ -172,7 +166,7 @@ public class JettyHomeTester
{ {
args.add("maven.repo.uri=" + remoteRepoUri); args.add("maven.repo.uri=" + remoteRepoUri);
} }
commands.addAll(args); commands.addAll(args);
LOGGER.info("Executing: {}", commands); LOGGER.info("Executing: {}", commands);
@ -182,7 +176,7 @@ public class JettyHomeTester
pbCmd.directory(jettyBaseDir); pbCmd.directory(jettyBaseDir);
Process process = pbCmd.start(); Process process = pbCmd.start();
return new Run(process); return new Run(config, process);
} }
/** /**
@ -259,7 +253,7 @@ public class JettyHomeTester
private void init() throws Exception private void init() throws Exception
{ {
if (config.jettyHome == null) if (config.jettyHome == null)
config.jettyHome = resolveHomeArtifact(config.jettyVersion); config.jettyHome = resolveHomeArtifact(config.getJettyVersion());
if (config.jettyBase == null) if (config.jettyBase == null)
{ {
@ -385,15 +379,40 @@ public class JettyHomeTester
return session; return session;
} }
private static class Config public static class Config
{ {
private final Map<String, String> mavenRemoteRepositories = new HashMap<>();
private Path jettyBase; private Path jettyBase;
private Path jettyHome; private Path jettyHome;
private String jettyVersion; private String jettyVersion;
private String mavenLocalRepository = System.getProperty("user.home") + "/.m2/repository"; private String mavenLocalRepository = System.getProperty("mavenRepoPath", System.getProperty("user.home") + "/.m2/repository");
private Map<String, String> mavenRemoteRepositories = new HashMap<>();
private List<String> jvmArgs = new ArrayList<>(); private List<String> jvmArgs = new ArrayList<>();
public Path getJettyBase()
{
return jettyBase;
}
public Path getJettyHome()
{
return jettyHome;
}
public String getJettyVersion()
{
return jettyVersion;
}
public String getMavenLocalRepository()
{
return mavenLocalRepository;
}
public List<String> getJVMArgs()
{
return Collections.unmodifiableList(jvmArgs);
}
@Override @Override
public String toString() public String toString()
{ {
@ -433,17 +452,24 @@ public class JettyHomeTester
*/ */
public static class Run implements Closeable public static class Run implements Closeable
{ {
private final Config config;
private final Process process; private final Process process;
private final List<ConsoleStreamer> consoleStreamers = new ArrayList<>(); private final List<ConsoleStreamer> consoleStreamers = new ArrayList<>();
private final Queue<String> logs = new ConcurrentLinkedQueue<>(); private final Queue<String> logs = new ConcurrentLinkedQueue<>();
private Run(Process process) private Run(Config config, Process process)
{ {
this.config = config;
this.process = process; this.process = process;
consoleStreamers.add(startPump("STDOUT", process.getInputStream())); consoleStreamers.add(startPump("STDOUT", process.getInputStream()));
consoleStreamers.add(startPump("STDERR", process.getErrorStream())); consoleStreamers.add(startPump("STDERR", process.getErrorStream()));
} }
public Config getConfig()
{
return config;
}
private ConsoleStreamer startPump(String mode, InputStream stream) private ConsoleStreamer startPump(String mode, InputStream stream)
{ {
ConsoleStreamer pump = new ConsoleStreamer(stream); ConsoleStreamer pump = new ConsoleStreamer(stream);
@ -551,7 +577,8 @@ public class JettyHomeTester
while (System.nanoTime() < end) while (System.nanoTime() < end)
{ {
boolean result = logs.stream().anyMatch(s -> s.contains(txt)); boolean result = logs.stream().anyMatch(s -> s.contains(txt));
if (result) return true; if (result)
return true;
Thread.sleep(250); Thread.sleep(250);
} }
return false; return false;
@ -658,7 +685,7 @@ public class JettyHomeTester
public static class Builder public static class Builder
{ {
private Config config = new Config(); private final Config config = new Config();
private Builder() private Builder()
{ {
@ -667,7 +694,7 @@ public class JettyHomeTester
/** /**
* @param jettyVersion the version to use (format: 9.4.14.v20181114 9.4.15-SNAPSHOT). * @param jettyVersion the version to use (format: 9.4.14.v20181114 9.4.15-SNAPSHOT).
* The distribution will be downloaded from local repository or remote * The distribution will be downloaded from local repository or remote
* @return the {@link Builder} * @return this Builder
*/ */
public Builder jettyVersion(String jettyVersion) public Builder jettyVersion(String jettyVersion)
{ {
@ -678,7 +705,7 @@ public class JettyHomeTester
/** /**
* @param jettyHome Path to the local exploded jetty distribution * @param jettyHome Path to the local exploded jetty distribution
* if configured the jettyVersion parameter will not be used * if configured the jettyVersion parameter will not be used
* @return the {@link Builder} * @return this Builder
*/ */
public Builder jettyHome(Path jettyHome) public Builder jettyHome(Path jettyHome)
{ {
@ -691,7 +718,7 @@ public class JettyHomeTester
* <p>If the path is relative, it will be resolved against the Jetty Home directory.</p> * <p>If the path is relative, it will be resolved against the Jetty Home directory.</p>
* *
* @param jettyBase Path to the local Jetty Base directory * @param jettyBase Path to the local Jetty Base directory
* @return the {@link Builder} * @return this Builder
*/ */
public Builder jettyBase(Path jettyBase) public Builder jettyBase(Path jettyBase)
{ {
@ -701,7 +728,7 @@ public class JettyHomeTester
/** /**
* @param mavenLocalRepository Path to the local maven repository * @param mavenLocalRepository Path to the local maven repository
* @return the {@link Builder} * @return this Builder
*/ */
public Builder mavenLocalRepository(String mavenLocalRepository) public Builder mavenLocalRepository(String mavenLocalRepository)
{ {
@ -714,7 +741,7 @@ public class JettyHomeTester
* *
* @param id the id * @param id the id
* @param url the Maven remote repository url * @param url the Maven remote repository url
* @return the {@link Builder} * @return this Builder
*/ */
public Builder addRemoteRepository(String id, String url) public Builder addRemoteRepository(String id, String url)
{ {
@ -723,9 +750,8 @@ public class JettyHomeTester
} }
/** /**
*
* @param jvmArgs the jvm args to add * @param jvmArgs the jvm args to add
* @return the {@link Builder} * @return this Builder
*/ */
public Builder jvmArgs(List<String> jvmArgs) public Builder jvmArgs(List<String> jvmArgs)
{ {
@ -734,7 +760,7 @@ public class JettyHomeTester
} }
/** /**
* @return an empty instance of {@link Builder} * @return an empty instance of Builder
*/ */
public static Builder newInstance() public static Builder newInstance()
{ {