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. 

Reworked the start documentation.

Started skeleton of the operations guide.
Removed old_docs/deploying/hot-deployment.adoc and
old_docs/gettingstarted/getting-started/jetty-deployment.adoc,
since its content has been moved to the refactored documentation.

Restructured the skeleton of the operations guide.
Removed old_docs/deploying/anatomy-of-a-webapp.adoc,
since its content has been moved to the refactored documentation.

Removed old_docs/deploying/automatic-webapp-deployment.adoc,
since its content has been moved to the refactored documentation.

Removed old_docs/deploying/configuring-virtual-hosts.adoc,
since its content has been moved to the refactored documentation.

Removed old_docs/contexts/serving-webapps-from-particular-port.adoc
and example-jetty-embedded/src/main/resource/jetty-otherserver.xml,
since its content has been moved to the refactored documentation.

Simplified POMs.
Simplified index.adoc files, refactoring common things into config.adoc.

Expanded the deploy configuration documentation.
Expanded the protocols configuration documentation.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>
This commit is contained in:
Simone Bordet 2020-09-16 10:58:23 +02:00
parent dc6bee5c96
commit 35305b6a5c
55 changed files with 1811 additions and 895 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
examples/embedded/src/main/resources/jetty-otherserver.xml
View File

@ -1,51 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">
<Set name="handler">
<New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerList">
<Set name="handlers">
<Array type="org.eclipse.jetty.server.Handler">
<Item>
<New id="OtherContexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/>
</Item>
<Item>
<New class="org.eclipse.jetty.server.handler.DefaultHandler"/>
</Item>
</Array>
</Set>
</New>
</Set>
<Call name="addConnector">
<Arg>
<New class="org.eclipse.jetty.server.ServerConnector">
<Arg name="server"><Ref refid="OtherServer" /></Arg>
<Set name="port">8888</Set>
</New>
</Arg>
</Call>
<Call name="addBean">
<Arg>
<New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager">
<Set name="contexts">
<Ref refid="OtherContexts" />
</Set>
<Call id="webappprovider" name="addAppProvider">
<Arg>
<New class="org.eclipse.jetty.deploy.providers.WebAppProvider">
<Set name="monitoredDirName"><Property name="jetty.base" default="." />/other-webapps</Set>
<Set name="defaultsDescriptor"><Property name="jetty.home" default="." />/etc/webdefault.xml</Set>
<Set name="extractWars">true</Set>
<Set name="configurationManager">
<New class="org.eclipse.jetty.deploy.PropertiesConfigurationManager"/>
</Set>
</New>
</Arg>
</Call>
</New>
</Arg>
</Call>
</Configure>

4
jetty-deploy/src/main/config/modules/deploy.mod
View File

@ -1,7 +1,5 @@
# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
[description] [description]
Enables webapplication deployment from the webapps directory. Enables web application deployment from the $JETTY_BASE/webapps/ directory.
[depend] [depend]
webapp webapp

195
jetty-documentation/pom.xml
View File

@ -11,23 +11,6 @@
<name>Jetty :: Documentation</name> <name>Jetty :: Documentation</name>
<packaging>jar</packaging> <packaging>jar</packaging>
<properties>
<maven.build.timestamp.format>yyyy-MM-dd HH:mm</maven.build.timestamp.format>
<html.common.directory>${project.build.directory}/html/common</html.common.directory>
<html.image.directory>${project.build.directory}/html/common/images</html.image.directory>
<javadoc.version>${project.version}</javadoc.version>
<asciidoctor.maven.plugin.version>1.5.7.1</asciidoctor.maven.plugin.version>
<asciidoctorj.pdf.version>1.5.0-alpha.16</asciidoctorj.pdf.version>
<asciidoctorj.epub.version>1.5.0-alpha.8.1</asciidoctorj.epub.version>
<asciidoctorj.version>1.5.8.1</asciidoctorj.version>
<jruby.version>1.7.27</jruby.version>
<web.resources.version>1.2</web.resources.version>
<web.resources.directory>${project.build.directory}/web-resources</web.resources.directory>
<!-- old properties -->
<html.directory>${project.build.directory}/current</html.directory>
<javadoc.version>${project.version}</javadoc.version>
</properties>
<dependencies> <dependencies>
<dependency> <dependency>
<groupId>org.eclipse.jetty.toolchain</groupId> <groupId>org.eclipse.jetty.toolchain</groupId>
@ -108,69 +91,23 @@
<build> <build>
<plugins> <plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>unpack-jetty-web-resouces</id>
<phase>generate-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.eclipse.jetty.toolchain</groupId>
<artifactId>jetty-web-resources</artifactId>
<version>${web.resources.version}</version>
<type>jar</type>
<overWrite>true</overWrite>
<outputDirectory>${web.resources.directory}</outputDirectory>
</artifactItem>
</artifactItems>
<excludes>META-INF/**</excludes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-base-html-assets</id>
<phase>generate-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>${web.resources.directory}/html</directory>
<includes>
<include>**</include>
</includes>
</resource>
</resources>
<outputDirectory>${html.common.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
<plugin> <plugin>
<groupId>org.asciidoctor</groupId> <groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.maven.plugin.version}</version>
<dependencies> <dependencies>
<dependency> <dependency>
<groupId>org.asciidoctor</groupId> <groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-diagram</artifactId> <artifactId>asciidoctorj-diagram</artifactId>
<version>2.0.1</version> <version>2.0.2</version>
</dependency> </dependency>
</dependencies> </dependencies>
<configuration> <configuration>
<backend>html5</backend>
<requires>
<require>asciidoctor-diagram</require>
</requires>
<attributes> <attributes>
<JDURL>http://www.eclipse.org/jetty/javadoc/${javadoc.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>
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/master</GITBROWSEURL> <GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/master</GITBROWSEURL>
@ -192,8 +129,6 @@
<goal>process-asciidoc</goal> <goal>process-asciidoc</goal>
</goals> </goals>
<configuration> <configuration>
<backend>html5</backend>
<templateDir>${web.resources.directory}/asciidoc/slim-template</templateDir>
<sourceDirectory>src/main/asciidoc/operations-guide</sourceDirectory> <sourceDirectory>src/main/asciidoc/operations-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName> <sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/operations-guide</outputDirectory> <outputDirectory>${project.build.directory}/html/operations-guide</outputDirectory>
@ -206,12 +141,9 @@
<goal>process-asciidoc</goal> <goal>process-asciidoc</goal>
</goals> </goals>
<configuration> <configuration>
<backend>html5</backend>
<templateDir>${web.resources.directory}/asciidoc/slim-template</templateDir>
<sourceDirectory>${basedir}/src/main/asciidoc/contribution-guide</sourceDirectory> <sourceDirectory>${basedir}/src/main/asciidoc/contribution-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName> <sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/contribution-guide</outputDirectory> <outputDirectory>${project.build.directory}/html/contribution-guide</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
</configuration> </configuration>
</execution> </execution>
<execution> <execution>
@ -221,15 +153,9 @@
<goal>process-asciidoc</goal> <goal>process-asciidoc</goal>
</goals> </goals>
<configuration> <configuration>
<backend>html5</backend>
<templateDir>${web.resources.directory}/asciidoc/slim-template</templateDir>
<sourceDirectory>${basedir}/src/main/asciidoc/programming-guide</sourceDirectory> <sourceDirectory>${basedir}/src/main/asciidoc/programming-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName> <sourceDocumentName>index.adoc</sourceDocumentName>
<outputDirectory>${project.build.directory}/html/programming-guide</outputDirectory> <outputDirectory>${project.build.directory}/html/programming-guide</outputDirectory>
<sourceHighlighter>coderay</sourceHighlighter>
<requires>
<require>asciidoctor-diagram</require>
</requires>
</configuration> </configuration>
</execution> </execution>
</executions> </executions>
@ -254,113 +180,4 @@
</plugin> </plugin>
</plugins> </plugins>
</build> </build>
<profiles>
<profile>
<id>alt-formats</id>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor.maven.plugin.version}</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${asciidoctorj.pdf.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-epub3</artifactId>
<version>${asciidoctorj.epub.version}</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>${jruby.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
</dependencies>
<configuration>
<imagesdir />
<backend>docbook</backend>
<attributes>
<revnumber>${project.version}</revnumber>
<JDURL>http://www.eclipse.org/jetty/javadoc/${javadoc.version}</JDURL>
<JXURL>http://download.eclipse.org/jetty/stable-9/xref</JXURL>
<SRCDIR>${basedir}/..</SRCDIR>
<GITBROWSEURL>https://github.com/eclipse/jetty.project/tree/master</GITBROWSEURL>
<MVNCENTRAL>http://central.maven.org/maven2</MVNCENTRAL>
<VERSION>${project.version}</VERSION>
</attributes>
</configuration>
<executions>
<execution>
<id>contribution-guide-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<icons>font</icons>
<pagenums />
<toc />
<idprefix />
<idseparator>-</idseparator>
</attributes>
<sourceDirectory>${basedir}/src/main/asciidoc/contribution-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputFile>${project.build.directory}/pdf/contribution-guide/contribution-guide.pdf</outputFile>
</configuration>
</execution>
<execution>
<id>quickstart-distribution-guide-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<icons>font</icons>
<pagenums />
<toc />
<idprefix />
<idseparator>-</idseparator>
</attributes>
<sourceDirectory>${basedir}/src/main/asciidoc/quickstart-distribution-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputFile>${project.build.directory}/pdf/quickstart-distribution-guide/quickstart-distribution-guide.pdf</outputFile>
</configuration>
</execution>
<execution>
<id>contribution-guide-epub</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>epub3</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<sourceDirectory>${basedir}/src/main/asciidoc/contribution-guide</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<outputFile>${project.build.directory}/epub/contribution-guide/contribution-guide.epub</outputFile>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project> </project>

41
jetty-documentation/src/main/asciidoc/config.adoc Normal file
View File

@ -0,0 +1,41 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
:author: Jetty Developers
:email: jetty-dev@eclipse.org
:revnumber: {version}
:revdate: {localdate}
:toc: left
:toclevels: 4
:idseparator: -
:sectlinks:
:sectanchors:
// Use fonts for admonitions.
:icons: font
// HTML specific directives
ifdef::backend-html5[]
:safe-mode-unsafe:
:linkcss:
endif::[]
// TODO: remove this attribute once all documentation has been ported.
:sub-order: attributes+

38
jetty-documentation/src/main/asciidoc/contribution-guide/index.adoc
View File

@ -17,45 +17,11 @@
// //
:doctitle: Eclipse Jetty: Contribution Guide :doctitle: Eclipse Jetty: Contribution Guide
:author: Jetty Developers
:email: jetty-dev@eclipse.org
:revnumber: 1.0
:revdate: {TIMESTAMP}
:toc: left
:toc-title: Contribution Guide :toc-title: Contribution Guide
:toc-style:
:header-style: eclipse-thin
:breadcrumb-style: eclipse-thin
:footer-style: default
:breadcrumb: Home:../index.html | Contribution Guide:./index.html :breadcrumb: Home:../index.html | Contribution Guide:./index.html
:idprefix: cg-
// docinfo lets you pull in shared content and/or influence via render type include::../config.adoc[]
//:docinfodir: {DOCINFODIR}/documentation
//:docinfo1:
// html specific directives
ifdef::backend-html5[]
:safe-mode-unsafe:
:stylesdir: ../common/css
:stylesheet: jetty.css
:linkcss:
:scriptsdir: ../common/js
endif::[]
// options for special blocks, code snippets, screen, etc
:sub-order: attributes+
// uncomment to allow include::https:// style content inclusion
//:allow-uri-read: true
// use fonts for admonitions
:icons: font
// suppress automatic id generation
:sectids!:
include::1-introduction.adoc[] include::1-introduction.adoc[]
include::2-community.adoc[] include::2-community.adoc[]
include::3-source.adoc[] include::3-source.adoc[]

3
jetty-documentation/src/main/asciidoc/operations-guide/.asciidoctorconfig Normal file
View File

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

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

@ -0,0 +1,81 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-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 want to setup 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 xref:pg-arch-bean[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 rather than using Java APIs.
What you can do in Java code to assemble Jetty components, it 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, that in turn depends on the `threadpool` and `logging` Jetty modules.
Every feature in a Jetty server is enabled by enabling correspondent Jetty modules.
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 that client use 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`
After installing Jetty in `$JETTY_HOME`, you want to create another directory that will be referred to as `$JETTY_BASE`, likely in a different location in the file system from `$JETTY_HOME`.
The `$JETTY_BASE` directory is where you configure which Jetty modules you want to use and what configuration they have, and it is the base directory where you deploy your web applications.
You do not deploy your web applications in `$JETTY_HOME`, you deploy them in `$JETTY_BASE`.
You can have just one `$JETTY_HOME` but multiple `$JETTY_HOME` directories, each with its own configuration.
This separation between `$JETTY_HOME` and `$JETTY_BASE` allows to upgrade Jetty 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`, for example because you are behind a load balancer that is configured to forward to the backend on port `6060`.
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 will be lost.
You would have to remember all the changes you made to the default configuration, upgrade Jetty (which would overwrite the configuration files with the default values), and made again all the changes, which results in a maintenance nightmare.
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.
[IMPORTANT]
====
Install Jetty and never modify the files under `$JETTY_HOME`, unless you are upgrading Jetty itself.
Do all the rest in `$JETTY_BASE`.
====

28
jetty-documentation/src/main/asciidoc/operations-guide/begin/chapter.adoc Normal file
View File

@ -0,0 +1,28 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-begin]]
=== Introduction to Eclipse Jetty
This section will get you started with Eclipse Jetty.
include::download.adoc[]
include::install.adoc[]
include::architecture.adoc[]
include::start.adoc[]
include::deploy.adoc[]

120
jetty-documentation/src/main/asciidoc/operations-guide/begin/deploy.adoc Normal file
View File

@ -0,0 +1,120 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-begin-deploy]]
==== Deploying Web Applications to Eclipse Jetty
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.
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.
Their deployment is described in xref:og-deploy[this section].
[[og-begin-deploy-war]]
===== Deploying Standard +*.war+ Web Applications
A standard Servlet web application is packaged in either a `+*.war+` file or in a directory with the structure of a `+*.war+` file.
[NOTE]
====
Recall that the structure of a `+*.war+` file is as follows:
[source,subs=verbatim]
----
mywebapp.war
├── index.html <1>
└── WEB-INF <2>
├── classes/ <3>
├── lib/ <4>
└── web.xml <5>
----
<1> Publicly accessible resources such as `+*.html+`, `+*.jsp+`, `+*.css+`, `+*.js+` files, etc. are placed in `+*.war+` or in sub-directories of the `+*.war+`.
<2> `WEB-INF` is a special directory used to store anything related to the web application that must not be publicly accessible, but may be accessed by other resources.
<3> `WEB-INF/classes` stores the web application compiled `+*.class+` files
<4> `WEB-INF/classes` stores the web application `+*.jar+` files
<5> `WEB-INF/web.xml` is the web application deployment descriptor defines the components and the configuration of your web application.
====
To deploy a standard web application, you need to enable the `deploy` module (see the `deploy` module complete definition xref:og-module-deploy[here]).
----
$ java -jar $JETTY_HOME/start.jar --add-module=deploy
----
----
INFO : webapp transitively enabled, ini template available with --add-module=webapp
INFO : security transitively enabled
INFO : servlet transitively enabled
INFO : deploy initialized in ${jetty.base}/start.d/deploy.ini
INFO : mkdir ${jetty.base}/webapps
INFO : Base directory was modified
----
The `deploy` module creates the `$JETTY_BASE/webapps` directory, the directory where `+*.war+` files or `+*.war+` directories should be copied so that Jetty can deploy them.
[NOTE]
====
The `deploy` module only provides the feature of deploying web applications.
Whether these web applications are served via clear-text HTTP/1.1, or secure HTTP/1.1, or secure HTTP/2 (or even all of these protocols) depends on whether the correspondent Jetty modules have been enabled.
Refer to the xref:og-protocols[section about protocols] for further information.
====
Now you need to copy a web application to the `$JETTY_BASE/webapps` directory:
----
curl https://repo1.maven.org/maven2/org/eclipse/jetty/test-jetty-webapp/10.0.0/test-jetty-webapp-10.0.0.war --output $JETTY_BASE/webapps/test.war
----
// TODO: this webapp requires the login module, need something simpler.
// TODO: replace this with a module, so the download is done by the module.
The `$JETTY_BASE` directory is now:
----
$JETTY_BASE
├── resources
│ └── jetty-logging.properties
├── start.d
│ ├── deploy.ini
│ └── http.ini
└── webapps
└── test.war
----
Now start Jetty:
----
$ java -jar $JETTY_HOME/start.jar
----
----
2020-09-16 09:53:38.182:INFO :oejs.Server:main: jetty-10.0.0-SNAPSHOT; built: 2020-09-16T07:47:47.334Z; git: d45455b32d96f516d39e03b53e91502a34b04f37; jvm 15+36-1562
2020-09-16 09:53:38.205:INFO :oejdp.ScanningAppProvider:main: Deployment monitor [file:///tmp/jetty.base/webapps/] at interval 1
2020-09-16 09:53:38.293:WARN :oejshC.test:main: The async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
2020-09-16 09:53:38.298:INFO :oejw.StandardDescriptorProcessor:main: NO JSP Support for /test, did not find org.eclipse.jetty.jsp.JettyJspServlet
2020-09-16 09:53:38.306:INFO :oejss.DefaultSessionIdManager:main: DefaultSessionIdManager workerName=node0
2020-09-16 09:53:38.306:INFO :oejss.DefaultSessionIdManager:main: No SessionScavenger set, using defaults
2020-09-16 09:53:38.307:INFO :oejss.HouseKeeper:main: node0 Scavenging every 660000ms
2020-09-16 09:53:38.331:INFO :oejsh.ContextHandler:main: Started o.e.j.w.WebAppContext@45b4c3a9{Async REST Webservice Example,/test,[file:///tmp/jetty-0_0_0_0-8080-test_war-_test-any-15202033063643714058.dir/webapp/, jar:file:///tmp/jetty-0_0_0_0-8080-test_war-_test-any-15202033063643714058.dir/webapp/WEB-INF/lib/example-async-rest-jar-10.0.0-SNAPSHOT.jar!/META-INF/resources],AVAILABLE}{/tmp/jetty.base/webapps/test.war}
2020-09-16 09:53:38.338:INFO :oejs.AbstractConnector:main: Started ServerConnector@543295b0{HTTP/1.1, (http/1.1)}{0.0.0.0:8080}
2020-09-16 09:53:38.347:INFO :oejs.Server:main: Started Server@5ffead27{STARTING}[10.0.0-SNAPSHOT,sto=5000] @593ms
----
// TODO: highlight the line that says that it deployed a context
Now you can access the web application by pointing your browser to `+http://localhost:8080/test+`.
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].

25
jetty-documentation/src/main/asciidoc/operations-guide/begin/download.adoc Normal file
View File

@ -0,0 +1,25 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-begin-download]]
==== Downloading Eclipse Jetty
The Eclipse Jetty distribution is available for download from link:https://www.eclipse.org/jetty/download.html[]
The Eclipse Jetty distribution is available in both `zip` and `gzip` formats; download the one most appropriate for your system, typically `zip` for Windows and `gzip` for other operative systems.

35
jetty-documentation/src/main/asciidoc/operations-guide/begin/install.adoc Normal file
View File

@ -0,0 +1,35 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-begin-install]]
==== Installing Eclipse Jetty
After the download, unpacking the Eclipse Jetty distribution will extract the files into a directory called `jetty-distribution-VERSION`, where `VERSION` is the version that you downloaded, for example `10.0.0`, so that the directory is called `jetty-distribution-10.0.0`.
Unpack the Eclipse Jetty distribution 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.
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.
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, read the xref:og-begin-arch[Jetty architecture short section] to become familiar with the terms used in this document.
Otherwise, you can jump to the xref:og-begin-start[start Jetty section].

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

@ -0,0 +1,150 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-begin-start]]
==== Starting Eclipse Jetty
// TODO: Consider: old_docs/startup/*.adoc
// So far, what below is the content of old_docs/startup/startup-modules.adoc
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.
Jetty is started by executing `$JETTY_HOME/start.jar`, but first we need to create a `$JETTY_BASE`:
----
$ JETTY_BASE=/path/to/jetty.base
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar
----
----
ERROR : Nothing to start, exiting ...
Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
java -jar $JETTY_HOME/start.jar --help # for more information
----
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.
However, it shows that `start.jar` takes parameters, whose details can be found in xref:og-start-jar[this section].
You can explore what modules are available out of the box via:
----
$ 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):
----
$ java -jar $JETTY_HOME/start.jar --add-module=http
----
----
INFO : mkdir ${jetty.base}/start.d
INFO : server transitively enabled, ini template available with --add-module=server
INFO : logging-jetty transitively enabled
INFO : http initialized in ${jetty.base}/start.d/http.ini
INFO : resources transitively enabled
INFO : threadpool transitively enabled, ini template available with --add-module=threadpool
INFO : logging/slf4j dynamic dependency of logging-jetty
INFO : bytebufferpool transitively enabled, ini template available with --add-module=bytebufferpool
INFO : mkdir ${jetty.base}/resources
INFO : copy ${jetty.home}/modules/logging/jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified
----
Now you can start Jetty:
----
$ java -jar $JETTY_HOME/start.jar
----
[source,subs=quotes]
----
2020-09-11 15:35:17.451:INFO :oejs.Server:main: jetty-10.0.0-SNAPSHOT; built: 2020-09-10T11:01:33.608Z; git: b10a14ebf9b200da388f4f9a2036bd8117ee0b11; jvm 11.0.8+10
2020-09-11 15:35:17.485:INFO :oejs.AbstractConnector:main: Started ServerConnector@2d52216b{HTTP/1.1, #(http/1.1)}{0.0.0.0:8080}#
2020-09-11 15:35:17.496:INFO :oejs.Server:main: Started Server@44821a96{STARTING}[10.0.0-SNAPSHOT,sto=5000] @553ms
----
Note how Jetty is listening on port `8080` for clear-text HTTP/1.1 connections.
After having enabled the `http` module, the `$JETTY_BASE` directory looks like this:
[source,subs=verbatim]
----
JETTY_BASE
├── resources
│ └── jetty-logging.properties <1>
└── start.d <2>
└── http.ini <3>
----
<1> The `resources/jetty-logging.properties` file has been created because the `http` modules depends on the `server` module, which in turn depends on the `logging` module; the `logging` module created this file that can be configured to control the server logging level.
<2> The `start.d/` directory contains the configuration files for the modules.
<3> The `start.d/http.ini` file is the `http` module configuration file, where you can specify values for the `http` module properties.
In the `http.ini` file you can find the following content (among other content):
.http.ini
[source,subs=verbatim]
----
--module=http <1>
# jetty.http.port=8080 <2>
...
----
<1> This line enables the `http` module and should not be modified.
<2> This line is commented out and specifies the default value for the module property `jetty.http.port`, which is the network port that listens for clear-text HTTP connections.
You can change the module property `jetty.http.port` value directly from the command line:
----
$ java -jar $JETTY_HOME/start.jar jetty.http.port=9999
----
To make this change persistent, you can edit the `http.ini` file, uncomment the module property `jetty.http.port` and change its value to `9999`:
.http.ini
----
--module=http
jetty.http.port=9999
...
----
If you restart Jetty, the new value will be used:
----
$ java -jar $JETTY_HOME/start.jar
----
[source,subs=quotes]
----
2020-09-11 15:35:17.451:INFO :oejs.Server:main: jetty-10.0.0-SNAPSHOT; built: 2020-09-10T11:01:33.608Z; git: b10a14ebf9b200da388f4f9a2036bd8117ee0b11; jvm 11.0.8+10
2020-09-11 15:35:17.485:INFO :oejs.AbstractConnector:main: Started ServerConnector@2d52216b{HTTP/1.1, #(http/1.1)}{0.0.0.0:9999}#
2020-09-11 15:35:17.496:INFO :oejs.Server:main: Started Server@44821a96{STARTING}[10.0.0-SNAPSHOT,sto=5000] @553ms
----
Note how Jetty is now listening on port `9999` for clear-text HTTP/1.1 connections.
NOTE: If you want to enable support for different protocols such as secure HTTP/1.1 or HTTP/2, or configured Jetty behind a load balancer, read xref:og-protocols[this section].
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.
For more detailed information about the Jetty start system, you can read the xref:og-start-details[Jetty start system] section.

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

@ -0,0 +1,23 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-contexts]]
=== Configuring Jetty Context XML Files
TODO
// TODO: add here from old_docs/contexts and old_docs/extras

44
jetty-documentation/src/main/asciidoc/operations-guide/deploy/chapter.adoc Normal file
View File

@ -0,0 +1,44 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy]]
=== Customizing Web Application Deployment
Most of the times you want to be able to customize the deployment of your web applications, for example by changing the `contextPath`, or by adding JNDI entries, or by configuring virtual hosts, etc.
The customization is performed by the xref:og-module-deploy[`deploy` module] by processing xref:og-deploy-jetty[Jetty context XML files].
The `deploy` module contains the `DeploymentManager` component that scans the `$JETTY_BASE/webapps` directory for changes, following the deployment rules described in xref:og-deploy-rules[this section].
include::deploy-hot-static.adoc[]
include::deploy-rules.adoc[]
include::deploy-jetty.adoc[]
include::deploy-jndi.adoc[]
include::deploy-virtual-hosts.adoc[]
include::deploy-extract-war.adoc[]
include::deploy-override-webxml.adoc[]
// TODO: move this section to its own file
// TODO: configuring from the Jetty context XML file happens before web.xml
// What about jetty-web.xml? Can this be specified externally, e.g. WebAppContext.setJettyWebXml() ?
[[og-deploy-init-params]]
==== Configuring ``init-param``s
TODO
// TODO: see old_docs/deploying

39
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-extract-war.adoc Normal file
View File

@ -0,0 +1,39 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-extract-war]]
==== Configuring `+*.war+` File Extraction
By default, `+*.war+` files are uncompressed and its content extracted in a temporary directory.
// TODO: reference the `work` module and how it works, perhaps in a section about the `deploy` module?
The web application resources are served by Jetty from the files extracted in the temporary directory, not from the files within the `+*.war+` file, for performance reasons.
If you do not want Jetty to extract the `+*.war+` files, you can disable this feature, for example:
.mywebapp.xml
[source,xml,highlight=8]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/mywebapp</Set>
<Set name="war">/opt/webapps/mywebapp.war</Set>
<Set name="extractWAR">false</Set>
</Configure>
----

43
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-hot-static.adoc Normal file
View File

@ -0,0 +1,43 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-hot-static]]
==== Hot vs Static Deployment
The `DeploymentManager` scans the `$JETTY_BASE/webapps` directory for changes every `N` seconds, where `N` is configured via the `jetty.deploy.scanInterval` property.
By default, the scan interval is `1` second, which means that _hot_ deployment is enabled: if a file is added/changed/removed from the `$JETTY_BASE/webapps` directory, the `DeploymentManager` will notice the change and respectively deploy/redeploy/undeploy the web application.
Setting the scan interval to `0` means that _static_ deployment is enabled, and the `DeploymentManager` will not scan the `$JETTY_BASE/webapps` directory for changes.
This means that to deploy/redeploy/undeploy a web application you will need to stop and restart Jetty.
The following command line disables _hot_ deployment by specifying the `jetty.deploy.scanInterval` property on the command line, and therefore only for this particular run:
----
$ java -jar $JETTY_HOME/start.jar jetty.deploy.scanInterval=0
----
To make _static_ deployment persistent, you need to edit the `deploy` module configuration file, `$JETTY_BASE/start.d/deploy.ini`, uncomment the module property `jetty.deploy.scanInterval` and change its value to `0`:
.deploy.ini
[source,subs=quotes]
----
--module=deploy
#jetty.deploy.scanInterval=0#
...
----

80
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jetty.adoc Normal file
View File

@ -0,0 +1,80 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-jetty]]
==== Deploying Jetty Context XML Files
A Jetty context XML file is a xref:og-xml[Jetty XML file] that allows you to customize the deployment of web applications.
NOTE: Recall that the `DeploymentManager` component of the Jetty `deploy` module xref:og-deploy-rules[gives priority] to Jetty context XML files over `+*.war+` files or directories.
To deploy a web application using a Jetty context XML file, simply place the file in the `$JETTY_BASE/webapps` directory.
A simple Jetty context XML file, for example named `wiki.xml` is the following:
.wiki.xml
[source,xml,subs=verbatim]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext"> <1>
<Set name="contextPath">/wiki</Set> <2>
<Set name="war">/opt/myapps/myapp.war</Set> <3>
</Configure>
----
<1> Configures a link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[`WebAppContext`], which is the Jetty component that represents a standard Servlet web application.
<2> Specifies the web application `contextPath`, which may be different from the `+*.war+` file name.
<3> Specifies the file system path of the `+*.war+` file.
The `$JETTY_BASE` directory would look like this:
----
$JETTY_BASE
├── resources
│ └── jetty-logging.properties
├── start.d
│ ├── deploy.ini
│ └── http.ini
└── webapps
└── wiki.xml
----
TIP: The `+*.war+` file may be placed anywhere in the file system and does not need to be placed in the `$JETTY_BASE/webapps` directory.
IMPORTANT: If you place both the Jetty context XML file _and_ the `+*.war+` file in the `$JETTY_BASE/webapps` directory, remember that they must have the same file name, for example `wiki.xml` and `wiki.war`, so that the `DeploymentManager` deploys the web application only once using the Jetty context XML file (and not the `+*.war+` file).
You can use the features of xref:og-xml[Jetty XML files] to avoid to hard-code file system paths or other configurations in your Jetty context XML files, for example by using system properties:
.wiki.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/wiki</Set>
<Set name="war"><SystemProperty name="myapps.dir"/>/myapp.war</Set>
</Configure>
----
Note how the `+*.war+` file path is now obtained by resolving the system property `myapps.dir` that you can specify on the command line when you start Jetty:
----
$ java -jar $JETTY_HOME/start.jar -Dmyapps.dir=/opt/myapps
----

56
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-jndi.adoc Normal file
View File

@ -0,0 +1,56 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-jndi]]
==== Configuring JNDI Entries
A web application may _reference_ a JNDI entry, such as a JDBC `DataSource` from the web application `web.xml` file.
The JNDI entry must be _defined_ in the Jetty context XML file, for example:
.mywebapp.xml
[source,xml,subs=normal]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/mywebapp</Set>
<Set name="war">/opt/webapps/mywebapp.war</Set>
#&nbsp;&nbsp;<New class="org.eclipse.jetty.plus.jndi.Resource">
<Arg />
<Arg>jdbc/myds</Arg>
<Arg>
<New class="com.mysql.cj.jdbc.MysqlConnectionPoolDataSource">
<Set name="url">jdbc:mysql://localhost:3306/databasename</Set>
<Set name="user">user</Set>
<Set name="password">password</Set>
</New>
</Arg>
</New>#
</Configure>
----
[IMPORTANT]
====
Class `com.mysql.cj.jdbc.MysqlConnectionPoolDataSource` is present in the MySQL JDBC driver file, `mysql-connector-java-<version>.jar`, which must be available to the web application.
File `mysql-connector-java-<version>.jar` must be either present in `WEB-INF/lib`, or in the Jetty server class-path.
====
// TODO: add a link to reference the section about how
// to add a JDBC driver jar to the server classpath.

60
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-override-webxml.adoc Normal file
View File

@ -0,0 +1,60 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-jetty-override-web-xml]]
==== Overriding `web.xml`
You can configure an additional `web.xml` that complements the `web.xml` file that is present in the web application `+*.war+` file.
This additional `web.xml` is processed _after_ the `+*.war+` file `web.xml`.
This allows you to add host specific configuration or server specific configuration without having to extract the web application `web.xml`, modify it, and repackage it in the `+*.war+` file.
.mywebapp.xml
[source,xml,highlight=8]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/mywebapp</Set>
<Set name="war">/opt/webapps/mywebapp.war</Set>
<Set name="overrideDescriptor">/opt/webapps/mywebapp-web.xml</Set>
</Configure>
----
The format of the additional `web.xml` is exactly the same as a standard `web.xml` file, for example:
.mywebapp-web.xml
[source,xml,linenums,highlight=10-11]
----
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
version="4.0">
<servlet>
<servlet-name>my-servlet</servlet-name>
<init-param>
<param-name>host</param-name>
<param-value>192.168.0.13</param-value>
</init-param>
</servlet>
</web-app>
----
In the example above, you configured the `my-servlet` Servlet (defined in the web application `web.xml`), adding a host specific `init-param` with the IP address of the host.

43
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-rules.adoc Normal file
View File

@ -0,0 +1,43 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-rules]]
==== Deployment Rules
_Adding_ a `+*.war+` file, a `+*.war+` directory, a Jetty context XML file or a normal directory to `$JETTY_BASE/webapps` causes the `DeploymentManager` to deploy the new web application.
_Updating_ a `+*.war+` file or a Jetty context XML file causes the `DeploymentManager` to redeploy the web application, which means that the Jetty context component representing the web application is stopped, then reconfigured, and then restarted.
_Removing_ a `+*.war+` file, a `+*.war+` directory, a Jetty context XML file or a normal directory from `$JETTY_BASE/webapps` causes the `DeploymentManager` to undeploy the web application, which means that the Jetty context component representing the web application is stopped and removed from the Jetty server.
When a file or directory is added to `$JETTY_BASE/webapps`, the `DeploymentManager` derives the web application `contextPath` from the file or directory name, with the following rules:
* If the directory name is, for example, `mywebapp/`, it is deployed as a standard web application if it contains a `WEB-INF/` subdirectory, otherwise it is deployed as a web application of static content.
The `contextPath` would be `/mywebapp` (that is, the web application is reachable at `+http://localhost:8080/mywebapp/+`).
* If the directory name is `ROOT`, case insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
* If the directory name ends with `.d`, for example `config.d/`, it is ignored, although it may be referenced to configure other web applications (for example to store common files).
* If the `+*.war+` file name is, for example, `mywebapp.war`, it is deployed as a standard web application with the context path `/mywebapp` (that is, the web application is reachable at `+http://localhost:8080/mywebapp/+`).
* If the file name is `ROOT.war`, case insensitive, the `contextPath` is `/` (that is, the web application is reachable at `+http://localhost:8080/+`).
* If both the `mywebapp.war` file and the `mywebapp/` directory exist, only the file is deployed.
This allows the directory with the same name to be the `+*.war+` file unpack location and avoid that the web application is deployed twice.
* A xref:og-deploy-jetty[Jetty context XML file] named `mywebapp.xml` is deployed as a web application by processing the directives contained in the XML file itself, which must set the `contextPath`.
* If both `mywebapp.xml` and `mywebapp.war` exist, only the XML file is deployed.
This allows the XML file to reference the `+*.war+` file and avoid that the web application is deployed twice.
// TODO: add section about the work directory from
// old_docs/contexts/temporary-directories.adoc

191
jetty-documentation/src/main/asciidoc/operations-guide/deploy/deploy-virtual-hosts.adoc Normal file
View File

@ -0,0 +1,191 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-deploy-virtual-hosts]]
==== Configuring Virtual Hosts
A _virtual host_ is an internet domain name, registered in the Domain Name Server (DNS), for an IP address such that multiple virtual hosts will resolve to the same IP address of a single server instance.
If you have multiple web applications deployed on the same Jetty server, by using virtual hosts you will be able to target a specific web application.
For example, you may have a web application for your business and a web application for your hobbies , both deployed in the same Jetty server.
By using virtual hosts, you will be able to have the first web application available at `+http://domain.biz/+`, and the second web application available at `+http://hobby.net/+`.
Another typical case is when you want to use different subdomains for different web application, for example a project website is at `+http://project.org/+` and the project documentation is at `+http://docs.project.org+`.
Virtual hosts can be used with any context that is a subclass of link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
[[og-deploy-virtual-hosts-names]]
===== Virtual Host Names
Jetty supports the following variants to be specified as virtual host names:
`www.hostname.com`::
A fully qualified domain name. It is important to list all variants as a site may receive traffic for both `www.hostname.com` and `hostname.com`.
`*.hostname.com`::
A wildcard domain name which will match only one level of arbitrary subdomains.
*.foo.com will match www.foo.com and m.foo.com, but not www.other.foo.com.
`10.0.0.2`::
An IP address may be set as a virtual host to indicate that a web application should handle requests received on the network interface with that IP address for protocols that do not indicate a host name such as HTTP/0.9 or HTTP/1.0.
`@ConnectorName`::
A Jetty `ServerConnector` name to indicate that a web application should handle requests received on the `ServerConnector` with that name, and therefore received on a specific IP port.
A `ServerConnector` name can be set via link:{JDURL}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[].
`www.√integral.com`::
Non-ASCII and https://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using https://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a https://www.punycoder.com/[Punycode/IDN converters].
For example if the non-ASCII domain name `www.√integral.com` is given to a browser, then the browser will make a request that uses the domain name `www.xn--integral-7g7d.com`, which is the name that should be added as the virtual host name.
[[og-deploy-virtual-hosts-config]]
===== Virtual Hosts Configuration
If you have a web application `mywebapp.war` you can configure its virtual hosts in this way:
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/mywebapp</Set>
<Set name="war">/opt/webapps/mywebapp.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>mywebapp.com</Item>
<Item>www.mywebapp.com</Item>
<Item>mywebapp.net</Item>
<Item>www.mywebapp.net</Item>
</Array>
</Set>
</Configure>
----
Your web application will be available at:
* `+http://mywebapp.com/mywebapp+`
* `+http://www.mywebapp.com/mywebapp+`
* `+http://mywebapp.net/mywebapp+`
* `+http://www.mywebapp.net/mywebapp+`
[NOTE]
====
You configured the `contextPath` of your web application to `/mywebapp`.
As such, a request to `+http://mywebapp.com/other+` will not match your web application because the `contextPath` does not match.
Likewise, a request to `+http://other.com/mywebapp+` will not match your web application because the virtual host does not match.
====
[[og-deploy-virtual-hosts-same-context]]
===== Same Context Path, Different Virtual Hosts
If you want to deploy different web applications to the same context path, typically the root context path `/`, you must use virtual hosts to differentiate among web applications.
You have `domain.war` that you want to deploy at `+http://domain.biz/+` and `hobby.war` that you want to deploy at `+http://hobby.net+`.
To achieve this, you simply use the same context path of `/` for each of your webapps, while specifying different virtual hosts for each of your webapps:
.domain.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war">/opt/webapps/domain.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>domain.biz</Item>
</Array>
</Set>
</Configure>
----
.hobby.xml
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war">/opt/webapps/hobby.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>hobby.net</Item>
</Array>
</Set>
</Configure>
----
[[og-deploy-virtual-hosts-port]]
===== Different Port, Different Web Application
Sometimes it is required to serve different web applications from different IP ports, and therefore from different ``ServerConnector``s.
For example, you want requests to `+http://localhost:8080/+` to be served by one web application, but requests to `+http://localhost:9090/+` to be served by another web application.
This configuration may be useful when Jetty sits behind a load balancer.
In this case, you want to xref:og-protocols[configure multiple connectors], each with a different name, and then reference the connector name in the web application virtual host configuration:
.domain.xml
[source,xml,highlight=10]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war">/opt/webapps/domain.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>@port8080</Item>
</Array>
</Set>
</Configure>
----
.hobby.xml
[source,xml,highlight=10]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war">/opt/webapps/hobby.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>@port9090</Item>
</Array>
</Set>
</Configure>
----
[NOTE]
====
Web application `domain.war` has a virtual host of `@port8080`, where `port8080` is the name of a Jetty connector.
Likewise, web application `hobby.war` has a virtual host of `@port9090`, where `port9090` is the name of another Jetty connector.
See xref:og-protocols[this section] for further information about how to configure connectors.
====

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

@ -17,48 +17,19 @@
// //
:doctitle: Eclipse Jetty: Operations Guide :doctitle: Eclipse Jetty: Operations Guide
:author: Jetty Developers
:email: jetty-dev@eclipse.org
:revnumber: {version}
:revdate: {TIMESTAMP}
:toc: left
:toc-title: Operations Guide :toc-title: Operations Guide
:toc-style:
:header-style: eclipse-thin
:breadcrumb-style: eclipse-thin
:footer-style: default
:breadcrumb: Home:../index.html | Operations Guide:./index.html :breadcrumb: Home:../index.html | Operations Guide:./index.html
:idprefix: og-
// docinfo lets you pull in shared content and/or influence via render type include::../config.adoc[]
//:docinfodir: {DOCINFODIR}/documentation include::.asciidoctorconfig[]
//:docinfo1:
// html specific directives
ifdef::backend-html5[]
:safe-mode-unsafe:
:stylesdir: ../common/css
:stylesheet: jetty.css
:linkcss:
:scriptsdir: ../common/js
endif::[]
// options for special blocks, code snippets, screen, etc
:sub-order: attributes+
// uncomment to allow include::https:// style content inclusion
//:allow-uri-read: true
// use fonts for admonitions
:icons: font
// suppress automatic id generation
:sectids!:
// download and install
include::introduction.adoc[] include::introduction.adoc[]
// TODO: jetty.home vs jetty.base include::begin/chapter.adoc[]
include::start/chapter.adoc[]
include::deploy/chapter.adoc[]
include::protocols/chapter.adoc[]
include::modules/chapter.adoc[]
// TODO: how jetty standalone work what start.jar does, command line options, modules, etc. // TODO: how jetty standalone work what start.jar does, command line options, modules, etc.
// TODO: this is mostly in old_docs/startup. // TODO: this is mostly in old_docs/startup.

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

@ -16,33 +16,31 @@
// ======================================================================== // ========================================================================
// //
[[og-guide]] [[og-intro]]
== 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.
[[og-download]] === Eclipse Jetty Introduction
=== Downloading Eclipse Jetty
The Eclipse Jetty distribution is available for download from link:https://www.eclipse.org/jetty/download.html[] If you are new to Eclipse Jetty, read xref:og-begin[here] to download, install, start and deploy web applications to Jetty.
The Eclipse Jetty distribution is available in both `zip` and `gzip` formats; download the one most appropriate for your system, typically `zip` for Windows and `gzip` for other operative systems. === Eclipse Jetty Features
[[og-install]] If you know Jetty already, jump to a feature:
=== Installing Eclipse Jetty
After the download, unpacking the Eclipse Jetty distribution will extract the files into a directory called `jetty-distribution-VERSION`, where `VERSION` is the version that you downloaded, for example `10.0.0`, so that the directory is called `jetty-distribution-10.0.0`. TODO
Unpack the Eclipse Jetty distribution compressed file in a convenient location, for example under `/opt`. * Jetty Overview
* Jetty Modules
* Rewrite Modules
The rest of the instructions in this documentation will refer to this location as `$JETTY_HOME`. === Eclipse Jetty How-Tos
IMPORTANT: It is important that *only* stable release versions are used in production environments. * xref:og-protocols-http[Configure Clear-Text HTTP/1.1]
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. * xref:og-protocols-https[Configure Secure HTTP/1.1 (https)]
[[og-running]] TODO
=== Running Eclipse Jetty
Eclipse Jetty as a standalone server has no graphical user interface, so configuring and running the server is done from the command line. * Jetty Behind a Load Balancer
** Forward Header Customizer
TODO: section about general architecture - modules etc.

24
jetty-documentation/src/main/asciidoc/operations-guide/modules/chapter.adoc Normal file
View File

@ -0,0 +1,24 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
include::modules.adoc[]
include::module-bytebufferpool.adoc[]
include::module-deploy.adoc[]
include::module-http.adoc[]
include::module-server.adoc[]
include::module-threadpool.adoc[]

34
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-bytebufferpool.adoc Normal file
View File

@ -0,0 +1,34 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-bytebufferpool]]
==== Module `bytebufferpool`
The `bytebufferpool` module allows you to configure the server-wide `ByteBuffer` pool.
// TODO: expand
The module file is `$JETTY_HOME/modules/bytebufferpool.mod`:
----
include::{JETTY_HOME}/modules/bytebufferpool.mod[]
----
Among the configurable properties, the most relevant are:
TODO

36
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-deploy.adoc Normal file
View File

@ -0,0 +1,36 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-deploy]]
==== Module `deploy`
The `deploy` module provides the deployment feature through a `DeploymentManager` component that watches a directory for changes (see xref:og-deploy[how to deploy web applications] for more information).
Files or directories added in this monitored directory cause the `DeploymentManager` to deploy them as web applications; updating files already existing in this monitored directory cause the `DeploymentManager` to re-deploy the correspondent web application; removing files in this monitored directory cause the `DeploymentManager` to undeploy the correspondent web application (see also xref:og-deploy-rules[here] for more information).
The module file is `$JETTY_HOME/modules/deploy.mod`:
----
include::{JETTY_HOME}/modules/deploy.mod[]
----
Among the configurable properties, the most relevant are:
* `jetty.deploy.monitoredDir`, to change the name of the monitored directory.
* `jetty.deploy.scanInterval`, to change the scan period, that is how frequently the `DeploymentManager` wakes up to scan the monitored directory for changes.
Setting `jetty.deploy.scanInterval=0` disabled _hot_ deployment so that only static deployment will be possible (see also xref:og-deploy-hot-static[here] for more information).

64
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc Normal file
View File

@ -0,0 +1,64 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-http]]
==== Module `http`
The `http` module provides support for the clear-text HTTP/1.1 protocol and depends on the xref:og-module-server[`server` module].
The module file is `$JETTY_HOME/modules/http.mod`:
----
include::{JETTY_HOME}/modules/http.mod[]
----
Among the configurable properties, the most relevant are:
* `jetty.http.port`, default `8080`, is the network port that Jetty listens to for clear-text HTTP/1.1 connections.
* `jetty.http.idleTimeout`, default `30` seconds, is the amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources.
* `jetty.http.acceptors`, default -1 (i.e. an accept heuristic decides the value based on the number of cores), is the number of threads that compete to accept connections.
* `jetty.http.selectors`, default -1 (i.e. a select heuristic decides the value based on the number of cores), is the number of NIO selectors (with an associated thread) that manage connections.
[[og-module-http-acceptors]]
===== Configuration of Acceptors
Accepting connections is a blocking operation, so a thread is blocked in the `accept()` call until a connection is accepted, and other threads are blocked on the lock acquired just before the `accept()` call.
When the accepting thread accepts a connection, it performs a little processing of the just accepted connection, before forwarding it to other components.
During this little processing other connections may be established; if there is only one accepting thread, the newly established connections are waiting for the accepting thread to finish the processing of the previously accepted connection and call again `accept()`.
Servers that manage a very high number of connections that may (naturally) come and go, or that handle inefficient protocols that open and close connections very frequently (such as HTTP/1.0) may benefit of an increased number of acceptor threads.
// TODO: expand on acceptors=0 and non-blocking accepts
[[og-module-http-selectors]]
===== Configuration of Selectors
Performing a NIO `select()` call is a blocking operation, where the selecting thread is blocked in the `select()` call until at least one connection is ready to be processed for an I/O operation.
There are 4 I/O operations: ready to be accepted, ready to be connected, ready to be read and ready to be written.
A single NIO selector can manage thousands of connections, with the assumption that not many of them will be ready at the same time.
For a single NIO selector, the ratio between the average number of selected connections over the total number of connections for every `select()` call depends heavily on the protocol but also on the application.
Multiplexed protocols such as HTTP/2 tend to be busier than duplex protocols such as HTTP/1.1, leading to a higher ratio.
REST applications that exchange many little JSON messages tend to be busier than file server applications, leading to a higher ratio.
The higher the ratio, the higher the number of selectors you want to have, compatibly with the number of cores -- there is no point in having 64 selector threads on a single core hardware.

28
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-https.adoc Normal file
View File

@ -0,0 +1,28 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-https]]
==== Module `https`
The `https` module provides the HTTP/1.1 protocol to the xref:og-module-ssl[`ssl` module].
The module file is `$JETTY_HOME/modules/https.mod`:
----
include::{JETTY_HOME}/modules/https.mod[]
----

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

@ -0,0 +1,36 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-server]]
==== Module `server`
The `server` module provides generic server support, and configures generic HTTP properties that apply to all HTTP protocols, the scheduler properties and the server specific properties.
The `server` module depends on the xref:og-module-threadpool[`threadpool` module], the xref:og-module-bytebufferpool[`bytebufferpool` module] and the xref:og-module-logging[`logging` module].
The module file is `$JETTY_HOME/modules/server.mod`:
----
include::{JETTY_HOME}/modules/server.mod[]
----
Among the configurable properties, the most relevant are:
TODO
// TODO: consider extracting the httpConfig and scheduler properties into separate files.

32
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc Normal file
View File

@ -0,0 +1,32 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-ssl]]
==== Module `ssl`
The `ssl` module provides the secure connector, and allows you to configure the keystore properties and the TLS parameters.
The module file is `$JETTY_HOME/modules/ssl.mod`:
----
include::{JETTY_HOME}/modules/ssl.mod[]
----
Among the configurable properties, the most relevant are:
TODO

31
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-test-keystore.adoc Normal file
View File

@ -0,0 +1,31 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-test-keystore]]
==== Module `test-keystore`
The `test-keystore` module provides a keystore containing a self-signed certificate for domain `localhost`.
The module file is `$JETTY_HOME/modules/test-keystore.mod`:
----
include::{JETTY_HOME}/modules/test-keystore.mod[]
----
Note how properties `jetty.sslContext.keyStorePath` and `jetty.sslContext.keyStorePassword` are configured, only if not already set (via the `?=` operator), directly in the module file, rather than in a `+*.ini+` file.
This is done to avoid that these properties accidentally overwrite a real keystore configuration.

34
jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc Normal file
View File

@ -0,0 +1,34 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-module-threadpool]]
==== Module `threadpool`
The `threadpool` module allows you to configure the server-wide thread pool.
// TODO: thread pool per connector should be documented here?
The module file is `$JETTY_HOME/modules/threadpool.mod`:
----
include::{JETTY_HOME}/modules/threadpool.mod[]
----
Among the configurable properties, the most relevant are:
TODO

27
jetty-documentation/src/main/asciidoc/operations-guide/modules/modules.adoc Normal file
View File

@ -0,0 +1,27 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-modules]]
==== Jetty Modules
TODO
// Consider:
// * old_docs/gettingstarted/configuring/*.adoc
// * old_docs/startup/startup-modules.adoc
// * old_docs/startup/custom-modules.adoc
//

2
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/chapter.adoc
View File

@ -22,8 +22,6 @@
This chapter discusses various options for configuring Jetty contexts. This chapter discusses various options for configuring Jetty contexts.
include::setting-context-path.adoc[] include::setting-context-path.adoc[]
include::configuring-virtual-hosts.adoc[]
include::temporary-directories.adoc[] include::temporary-directories.adoc[]
include::serving-webapp-from-particular-port.adoc[]
include::custom-error-pages.adoc[] include::custom-error-pages.adoc[]
include::setting-form-size.adoc[] include::setting-form-size.adoc[]

216
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/configuring-virtual-hosts.adoc
View File

@ -1,216 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[configuring-virtual-hosts]]
=== Configuring Virtual Hosts
A virtual host is an alternative name, registered in DNS, for an IP address such that multiple domain names will resolve to the same IP of a shared server instance.
If the content to be served to the aliases names is link:#different-virtual-hosts-different-contexts[different], then a virtual host needs to be configured for each deployed link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] to indicate which names a context will respond to.
Virtual hosts are set on a link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[context] by calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[`setVirtualHosts`] or link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#addVirtualHosts-java.lang.String:A-[`addVirtualHost`] method which can be done in several ways:
* Using a link:#deployable-descriptor-file[context XML] file in the webapps directory (see the example in link:{GITBROWSEURL}/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.xml[test.xml] in the Jetty distribution).
* Creating a link:#deployment-architecture[custom deployer] with a binding to configure virtual hosts for all contexts found in the same `webapps` directory.
* Calling the link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-[API] directly on an link:#advanced-embedding[embedded] usage.
* Using a `WEB-INF/jetty-web.xml` file (now deprecated).
[[configuring-a-virtual-host]]
==== Virtual Host Names
Jetty supports the following styles of virtual host name:
www.hostname.com::
A fully qualified host name. It is important to list all variants as a site may receive traffic from both www.hostname.com and just hostname.com
*.hostname.com::
A wildcard qualified host which will match only one level of arbitrary names.
*.foo.com will match www.foo.com and m.foo.com, but not www.other.foo.com
10.0.0.2::
An IP address may be given as a virtual host name to indicate that a context should handle requests received on that server port that do not have a host name specified (HTTP/0.9 or HTTP/1.0).
@ConnectorName::
A connector name, which is not strictly a virtual host, but instead will only match requests that are received on connectors that have a matching name set with link:{JDURL}/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)[Connector.setName(String)].
www.√integral.com::
Non-ASCII and http://en.wikipedia.org/wiki/Internationalized_domain_name[IDN] domain names can be set as virtual hosts using http://en.wikipedia.org/wiki/Punycode[Puny Code] equivalents that may be obtained from a http://network-tools.com/idn-convert.asp[Punycode/IDN converters].
For example if the non-ASCII domain name `www.√integral.com` is given to a browser, then it will make a request that uses the domain name `www.xn--integral-7g7d.com`, which is the name that should be added as the virtual host name.
==== Example Virtual Host Configuration
Virtual hosts can be used with any context that is a subclass of link:{JDURL}/org/eclipse/jetty/server/handler/ContextHandler.html[ContextHandler].
Lets look at an example where we configure a web application - represented by the link:{JDURL}/org/eclipse/jetty/webapp/WebAppContext.html[WebAppContext] class - with virtual hosts.
You supply a list of IP addresses and names at which the web application is reachable, such as the following:
* `333.444.555.666`
* `127.0.0.1`
* `www.blah.com`
* `www.blah.net`
* `www.blah.org`
Suppose you have a webapp called `blah.war`, that you want all of the above names and addresses to be served at path "`/blah`".
Here's how you would configure the virtual hosts with a link:#deployable-descriptor-file[context XML] file:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/blah</Set>
<Set name="war"><Property name="jetty.webapps"/>blah.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>333.444.555.666</Item>
<Item>127.0.0.1</Item>
<Item>www.blah.com</Item>
<Item>www.blah.net</Item>
<Item>www.blah.org</Item>
</Array>
</Set>
</Configure>
----
[[different-virtual-hosts-different-contexts]]
==== Using Different Sets of Virtual Hosts to Select Different Contexts
You can configure different contexts to respond on different virtual hosts by supplying a specific list of virtual hosts for each one.
For example, suppose your imaginary machine has these DNS names:
* `www.blah.com`
* `www.blah.net`
* `www.blah.org`
* `www.other.com`
* `www.other.net`
* `www.other.org`
Suppose also you have 2 webapps, one called `blah.war` that you would like served from the `*.blah.*` names, and one called `other.war` that you want served only from the `*.other.*` names.
Using the method of preparing link:#deployable-descriptor-file[contextXML] files, one for each webapp yields the following:
For `blah` webapp:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/blah</Set>
<Set name="war"><Property name="jetty.webapps"/>/blah.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>www.blah.com</Item>
<Item>www.blah.net</Item>
<Item>www.blah.org</Item>
</Array>
</Set>
</Configure>
----
These URLs now resolve to the blah context (ie `blah.war`):
* `http://www.blah.com/blah`
* `http://www.blah.net/blah`
* `http://www.blah.org/blah`
For `other` webapp:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/other</Set>
<Set name="war"><Property name="jetty.webapps"/>/other.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>www.other.com</Item>
<Item>www.other.net</Item>
<Item>www.other.org</Item>
</Array>
</Set>
</Configure>
----
These URLs now resolve to the other context (i.e. `other.war`):
* `http://www.other.com/other`
* `http://www.other.net/other`
* `http://www.other.org/other`
[[different-virtual-hosts-different-context-same-path]]
==== Using Different Sets of Virtual Hosts to Select Different Contexts at the Same Context Path
In the previous section we setup 2 different contexts to be served from different virtual hosts at _different_ context paths.
However, there is no requirement that the context paths must be distinct: you may use the same context path for multiple contexts, and use virtual hosts to determine which one is served for a given request.
Consider an example where we have the same set of DNS names as before, and the same webapps `blah.war` and `other.war`. We still want `blah.war` to be served in response to hostnames of `*.blah.*`, and we still want `other.war` to be served in response to `*.other.*` names.
However, we would like__all__ of our clients to use the `"/"` context path, no matter which context is being targeted.
In other words, we want all of the following URLs to map to `blah.war`:
* `http://www.blah.com/`
* `http://www.blah.net/`
* `http://www.blah.org/`
Similarly, we want the following URLs to map to `other.war`:
* `http://www.other.com/`
* `http://www.other.net/`
* `http://www.other.org/`
To achieve this, we simply use the same context path of `/` for each of our webapps, while still applying our different set of virtual host names.
For foo webapp:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war"><Property name="jetty.webapps"/>/foo.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>www.blah.com</Item>
<Item>www.blah.net</Item>
<Item>www.blah.org</Item>
</Array>
</Set>
</Configure>
----
For bar webapp:
[source, xml, subs="{sub-order}"]
----
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
<Set name="contextPath">/</Set>
<Set name="war"><Property name="jetty.webapps"/>/bar.war</Set>
<Set name="virtualHosts">
<Array type="java.lang.String">
<Item>www.other.com</Item>
<Item>www.other.net</Item>
<Item>www.other.org</Item>
</Array>
</Set>
</Configure>
----

74
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/contexts/serving-webapp-from-particular-port.adoc
View File

@ -1,74 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[serving-webapp-from-particular-port]]
=== Serving a WebApp from a Particular Port/Connector
Sometimes it is required to serve different web applications from different ports/connectors.
The simplest way to do this is to create multiple `Server` instances.
However, if contexts need to share resources (eg data sources, authentication), or if the mapping of ports to web applications is not cleanly divided, then the named connector mechanism can be used.
[[creating-server-instances]]
==== Creating Multiple Server Instances
Creating multiple server instances is a straight forward process that includes embedding Jetty code by creating multiples instances of the Server class and configuring them as needed.
This is also easy to achieve if you are configuring Jetty servers via XML.
The `id` field in the Configure element of `jetty.xml` files is used to identify the instance that the configuration applies to, so to run two instances of the Server, you can copy the `jetty.xml`, jetty-http.xml and other jetty configuration files used and change the "Server" id to a new name.
This can be done in the same style and layout as the existing `jetty.xml` files or the multiple XML files may be combined to a single file.
When creating new configurations for alternative server:
* Change all `id="Server"` to the new server name:
[source, xml, subs="{sub-order}"]
----
<Configure id="OtherServer" class="org.eclipse.jetty.server.Server">
----
* For all connectors for the new server change the `refid` in the server argument:
[source, xml, subs="{sub-order}"]
----
<Arg name="server"><Ref refid="OtherServer" /></Arg>
----
* Make sure that any references to properties like `jetty.http.port` are either renamed or replaced with absolute values.
* Make sure that any deployers `AppProviders` refer to a different "webapps" directory so that a different set of applications are deployed.
[[jetty-otherserver.xml]]
===== Example Other Server XML
The following example creates another server instance and configures it with a connector and deployer:
[source, xml, subs="{sub-order}"]
----
include::{SRCDIR}/examples/embedded/src/main/resources/jetty-otherserver.xml[]
----
To run the other server, add the extra configuration file(s) to the command line:
[source, screen, subs="{sub-order}"]
----
java -jar start.jar jetty-otherserver.xml
----
[[alternative]]
==== Named Connectors
It is also possible to use an extension to the virtual host mechanism with named to connectors to make some web applications only accessible by specific connectors.
If a connector has a name "MyConnector" set using the `setName` method, then this can be referenced with the special virtual host name "@MyConnector".

42
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/deploying/anatomy-of-a-webapp.adoc
View File

@ -1,42 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[anatomy-of-a-webapp]]
=== Anatomy of a Web Application
The standard Jetty distribution is capable of deploying standard Servlet Spec Web Applications and Jetty internal ContextHandler deployment descriptors, or even a mix of the two.
Web Applications are deployable collections of dynamic (servlets, filters, jsps, etc..) and static content, support libraries, and descriptive metadata that are bound to a specific context path on Jetty.
Ultimately the format and layout are defined by the Servlet Spec, and the official Servlet Spec documentation should be consulted for a more detailed understanding of Web Application layout and structure; however, this will outline basics about how Jetty views these requirements.
Web Applications can be bundled into a single Web Archive (WAR file) or as a directory tree.
`/WEB-INF/`::
Special Servlet API defined directory used to store anything related to the Web Application that are not part of the public access of the Web Application.
If there is content that is accessed by a Web Application internally, but that should also never be accessed directly by a web browser, this is the directory it would placed in.
`/WEB-INF/web.xml`::
*Required* deployment descriptor defining various behavior of the Web Application.
`/WEB-INF/classes/`::
Location for Web Application specific compiled java classes
`/WEB-INF/lib/`::
Directory for JAR files (libraries)
The Jetty internal `WebAppClassloader` will load classes from `/WEB-INF/classes/` first, then from jar files found in `/WEB-INF/lib/`.

42
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/deploying/automatic-webapp-deployment.adoc
View File

@ -1,42 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[automatic-webapp-deployment]]
=== Automatic Web Application Deployment
The most basic technique for deploying Web Applications is to put a WAR file or Exploded WAR directory into the `${jetty.base}/webapps/` directory and let Jetty's deployment scanner find it and deploy it under a Context path of the same name.
Only Web Applications that follow the Web Application Layout will be detected by Jetty and deployed this way.
The Context Path assigned to this automatic deployment is based the filename (or directory name) of the WAR.
[cols=",",options="header",]
|=======================================================================
|File or Directory Name |Assigned Context Path
|`/webapps/footrope.war` |http://host/footrope/
|`/webapps/baggywrinkle-1.0.war` |http://host/baggywrinkle-1.0/
|`/webapps/lazaret-2.1.3-SNAPSHOT.war` |http://host/lazaret-2.1.3-SNAPSHOT/
|`/webapps/belaying-pins/WEB-INF/web.xml` |http://host/belaying-pins/
|`/webapps/root.war` _(reserved name)_ |http://host/
|`/webapps/root/WEB-INF/web.xml` _(reserved name)_ |http://host/
|=======================================================================

3
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/deploying/chapter.adoc
View File

@ -23,12 +23,9 @@ This chapter discusses various ways to deploy applications with Jetty.
Topics range from deployment bindings to deploying third party products. Topics range from deployment bindings to deploying third party products.
It also includes information about the Deployment Manager and WebApp Provider. It also includes information about the Deployment Manager and WebApp Provider.
include::anatomy-of-a-webapp.adoc[]
include::automatic-webapp-deployment.adoc[]
include::configuring-specific-webapp-deployment.adoc[] include::configuring-specific-webapp-deployment.adoc[]
include::deployment-processing-webapps.adoc[] include::deployment-processing-webapps.adoc[]
include::static-content-deployment.adoc[] include::static-content-deployment.adoc[]
include::hot-deployment.adoc[]
include::deployment-architecture.adoc[] include::deployment-architecture.adoc[]
include::quickstart-webapp.adoc[] include::quickstart-webapp.adoc[]
//include::overlay-deployer.adoc[] //include::overlay-deployer.adoc[]

66
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/deploying/hot-deployment.adoc
View File

@ -1,66 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[hot-deployment]]
=== Hot Deployment
Jetty allows for deploying an arbitrary context or web application by monitoring a directory for changes.
If a web application or a context descriptor is added to the directory, Jetty's `DeploymentManager` (DM) deploys a new context.
If a context descriptor is touched or updated, the DM stops, reconfigures, and redeploys its context.
If a context is removed, the DM stops it and removes it from the server.
This behavior can be controlled by configuring `WebAppProvider` properties.
monitoredDirName::
The directory to scan for possible deployable Web Applications (or Deployment Descriptor XML files).
scanInterval::
Number of seconds between scans of the provided `monitoredDirName`.
A value of `0` disables the continuous hot deployment scan, Web Applications will be deployed on startup only.
The default location for this configuration is in the `${jetty.home}/etc/jetty-deploy.xml` file.
To modify it as part of the Jetty distribution, first enable the `deploy` module.
Once it is enabled, you can edit these properties in either the `$JETTY_BASE/start.d/deploy.ini` or `$JETTY_BASE/start.ini` file, depending on link:#start-vs-startd[how your implementation is configured.]
[source, screen, subs="{sub-order}"]
----
<?xml version="1.0"?>
# ---------------------------------------
# Module: deploy
# Enables webapplication deployment from the webapps directory.
# ---------------------------------------
--module=deploy
# Monitored directory name (relative to $jetty.base)
# jetty.deploy.monitoredDir=webapps
# - OR -
# Monitored directory path (fully qualified)
# jetty.deploy.monitoredPath=/var/www/webapps
# Defaults Descriptor for all deployed webapps
# jetty.deploy.defaultsDescriptorPath=${jetty.base}/etc/webdefault.xml
# Monitored directory scan period (seconds)
# jetty.deploy.scanInterval=1
# Whether to extract *.war files
# jetty.deploy.extractWars=true
----
See xref:default-web-app-provider[] for more configuration details.
See also xref:deployment-architecture[] for detailed conceptual information.

1
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/gettingstarted/getting-started/chapter.adoc
View File

@ -25,4 +25,3 @@ This guide covers the latter, a standalone distribution suitable for deploying w
include::jetty-installing.adoc[] include::jetty-installing.adoc[]
include::jetty-running.adoc[] include::jetty-running.adoc[]
include::jetty-common-configuration.adoc[] include::jetty-common-configuration.adoc[]
include::jetty-deploying.adoc[]

72
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/gettingstarted/getting-started/jetty-deploying.adoc
View File

@ -1,72 +0,0 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[quickstart-deploying-webapps]]
=== Deploying Web Applications
Jetty server instances that configure the deploy module will have a web application deployer that link:#hot-deployment[hot deploys] files found in the `webapps` directory.
Standard WAR files and Jetty configuration files that are placed in the `webapps` directory are hot deployed to the server with the following conventions:
* A directory called `example/` is deployed as a standard web application if it contains a `WEB-INF/` subdirectory, otherwise it is deployed as context of static content.
The context path is `/example` (that is, `http://localhost:8080/example/`) unless the base name is ROOT (case insensitive), in which case the context path is /.
If the directory name ends with ".d" it is ignored (but may be used by explicit configuration).
* A file called `example.war` is deployed as a standard web application with the context path `/example` (that is,
`http://localhost:8080/example/`).
If the base name is `ROOT` (case insensitive), the context path is `/`.
If `example.war` and `example/` exist, only the WAR is deployed (which may use the directory as an unpack location).
* An XML file like `example.xml` is deployed as a context whose configuration is defined by the XML.
The configuration itself must set the context path.
If `example.xml` and `example.war` exists, only the XML is deployed (which may use the WAR in its configuration).
If you have a standard web application, you can hot deploy it into Jetty by copying it into the `webapps` directory.
==== Jetty Demonstration Web Applications
The demo-base/webapps directory contains the following deployable and auxiliary files:
`ROOT/`::
A directory of static content that is deployed to the root context / due to it's name.
Contains the Jetty demo welcome page.
`test.d`::
A directory containing additional configuration files used by `test.xml` to inject extra configuration into `test.war`.
`test.xml`::
A context configuration file that configures and deploys `test.war.`
The additional configuration includes the context path as well as setting additional descriptors found in the `test.d` directory.
`test.war`::
The demonstration web application that is configured and deployed by `test.xml`.
`async-rest.war`::
A web application demonstration of asynchronous REST to eBay, automatically deployed to /async-rest based on the file name.
`test-jaas.war`::
A demonstration web application utilizing link:#jaas-support[JAAS] for authentication.
`test-jaas.xml`::
A context configuration file that configures `test-jaas.war`.
Additional configuration includes setting up the link:#configuring-login-service[LoginService] for authentication and authorization.
`test-jndi.war`::
A demonstration web application showing the use of link:#jndi[JNDI].
`test-jndi.xml`::
A context configuration file that configures `test-jndi.war`.
Additional configuration includes defining objects in the naming space that can be referenced from the webapp.
`test-spec.war`::
A demonstration web application that shows the use of annotations, fragments, `ServletContainerInitializers` and other Servlet Specification 3.0/3.1 features.
`test-spec.xml`::
A context configuration file that configures `test-spec.war`.
Additional configuration includes setting up some objects in the naming space that can be referenced by annotations.
`javadoc-proxy.war`::
A demonstration web application that uses a transparent proxy to serve the Jetty source link:{JDURL}/[Javadoc] from the http://www.eclipse.org/jetty[Eclipse Jetty website].
`example-moved.xml`::
A demonstration context configuration file that shows how to use the link:#moved-context-handler[`MovedContextHandler`] to redirect from one path to another.

43
jetty-documentation/src/main/asciidoc/operations-guide/protocols/chapter.adoc Normal file
View File

@ -0,0 +1,43 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-protocols]]
=== Configuring Eclipse Jetty Connectors and Protocols
Connectors are the network components through which Jetty accepts incoming network connections.
Each connector listens on a network port and can be configured with `ConnectionFactory` components that _understand_ one or more network protocols.
Understanding a protocol means that the connector is able to interpret incoming network bytes (for example, the bytes that represent an HTTP/1.1 request) and convert them into more abstract objects (for example an `HttpServletRequest` object) that are then processed by applications.
Conversely, an abstract object (for example an `HttpServletResponse`) is converted into the correspondent outgoing network bytes (the bytes that represent an HTTP/1.1 response).
Like other Jetty components, connectors are enabled and configured by enabling and configuring the correspondent Jetty module.
IMPORTANT: Recall that you must always issue the commands to enable Jetty modules from within the `$JETTY_BASE` directory, and that the Jetty module configuration files are in the `$JETTY_BASE/start.d/` directory.
You can obtain the list of connector-related modules in this way:
----
$ java -jar $JETTY_HOME/start.jar --list-modules=connector
----
include::protocols-http.adoc[]
include::protocols-https.adoc[]
include::protocols-ssl.adoc[]
// TODO: old_docs/connectors/*.adoc

77
jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-http.adoc Normal file
View File

@ -0,0 +1,77 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-protocols-http]]
==== Configuring Clear-Text HTTP/1.1
Clear text HTTP/1.1 is enabled with the `http` Jetty module with the following command (issued from within the `$JETTY_BASE` directory):
----
$ java -jar $JETTY_HOME/start.jar --add-module=http
----
----
INFO : mkdir ${jetty.base}/start.d
INFO : server transitively enabled, ini template available with --add-module=server
INFO : logging-jetty transitively enabled
INFO : http initialized in ${jetty.base}/start.d/http.ini
INFO : resources transitively enabled
INFO : threadpool transitively enabled, ini template available with --add-module=threadpool
INFO : logging/slf4j dynamic dependency of logging-jetty
INFO : bytebufferpool transitively enabled, ini template available with --add-module=bytebufferpool
INFO : mkdir ${jetty.base}/resources
INFO : copy ${jetty.home}/modules/logging/jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified
----
After having enabled the `http` module, the `$JETTY_BASE` directory looks like this:
[source,subs=quotes]
----
JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
└── #http.ini#
----
The `http.ini` file is the file that you want to edit to configure network and protocol parameters -- for more details see xref:og-module-http[this section].
Note that the `http` Jetty module depends on the `server` Jetty module.
Some parameters that you may want to configure are in fact common HTTP parameters that are applied not only for clear-text HTTP/1.1, but also for secure HTTP/1.1 or for clear-text HTTP/2 or for encrypted HTTP/2, and these configuration parameters may be present in the `server` module configuration file.
You can force the creation of the `server.ini` file via:
----
$ java -jar $JETTY_HOME/start.jar --add-module=server
----
Now the `$JETTY_BASE` directory looks like this:
[source,subs=quotes]
----
JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
├── http.ini
└── server.ini
----
Now you can edit the `server.ini` file -- for more details see xref:og-module-server[this section].

102
jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-https.adoc Normal file
View File

@ -0,0 +1,102 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-protocols-https]]
==== Configuring Secure HTTP/1.1
Secure HTTP/1.1 is enabled with both the `ssl` and `https` Jetty modules with the following command (issued from within the `$JETTY_BASE` directory):
----
$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,https
----
----
INFO : mkdir ${jetty.base}/start.d
INFO : server transitively enabled, ini template available with --add-module=server
INFO : logging-jetty transitively enabled
INFO : resources transitively enabled
INFO : https initialized in ${jetty.base}/start.d/https.ini
INFO : ssl initialized in ${jetty.base}/start.d/ssl.ini
INFO : threadpool transitively enabled, ini template available with --add-module=threadpool
INFO : logging/slf4j transitive provider of logging/slf4j for logging-jetty
INFO : logging/slf4j dynamic dependency of logging-jetty
INFO : bytebufferpool transitively enabled, ini template available with --add-module=bytebufferpool
INFO : mkdir ${jetty.base}/resources
INFO : copy ${jetty.home}/modules/logging/jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified
----
The command above enables the `ssl` module, that provides the secure network connector, the keystore configuration and TLS configuration -- for more details see xref:og-protocols-ssl[this section].
Then, the xref:og-module-https[`https` module] adds HTTP/1.1 as the protocol secured by TLS.
The `$JETTY_BASE` directory looks like this:
[source,subs=verbatim]
----
$JETTY_BASE
├── resources
│ └── jetty-logging.properties
└── start.d
├── https.ini
└── ssl.ini
----
Note that the keystore file is missing, because you have to provide one with the cryptographic material you want (read xref:og-ssl[this section] to create your own keystore).
You need to configure these two properties by editing `ssl.ini`:
* `jetty.sslContext.keyStorePath`
* `jetty.sslContext.keyStorePassword`
As a quick example, you can enable the xref:og-module-test-keystore[`test-keystore` module], that provides a keystore containing a self-signed certificate:
----
$ java -jar $JETTY_HOME/start.jar --add-modules=ssl,https
----
----
INFO : test-keystore initialized in ${jetty.base}/start.d/test-keystore.ini
INFO : mkdir ${jetty.base}/etc
INFO : copy ${jetty.home}/modules/test-keystore/test-keystore.p12 to ${jetty.base}/etc/test-keystore.p12
INFO : Base directory was modified
----
The `$JETTY_BASE` directory is now:
----
├── etc
│ └── #test-keystore.p12#
├── resources
│ └── jetty-logging.properties
└── start.d
├── https.ini
├── ssl.ini
└── test-keystore.ini
----
Starting Jetty yields:
----
$ java -jar $JETTY_HOME/start.jar
----
[source,subs=quotes]
----
2020-09-22 08:40:49.482:INFO :oejs.Server:main: jetty-10.0.0-SNAPSHOT; built: 2020-09-21T14:44:05.094Z; git: 5c33f526e5b7426dd9644ece61b10184841bb8fa; jvm 15+36-1562
2020-09-22 08:40:49.709:INFO :oejus.SslContextFactory:main: x509=X509@14cd1699(mykey,h=[localhost],w=[]) for Server@73a1e9a9[provider=null,keyStore=file:///tmp/jetty.base/etc/test-keystore.p12,trustStore=file:///tmp/jetty.base/etc/test-keystore.p12]
2020-09-22 08:40:49.816:INFO :oejs.AbstractConnector:main: Started ServerConnector@2e1d27ba##{SSL, (ssl, http/1.1)}{0.0.0.0:8443}##
2020-09-22 08:40:49.828:INFO :oejs.Server:main: Started Server@2f177a4b{STARTING}[10.0.0-SNAPSHOT,sto=5000] @814ms
----
Note how Jetty is listening on port `8443` for the secure HTTP/1.1 protocol.

48
jetty-documentation/src/main/asciidoc/operations-guide/protocols/protocols-ssl.adoc Normal file
View File

@ -0,0 +1,48 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-protocols-ssl]]
==== Configuring Secure Protocols
Secure protocols are normal protocols such as HTTP/1.1 or WebSocket that are wrapped by the link:https://en.wikipedia.org/wiki/Transport_Layer_Security[TLS protocol].
Any network protocol can be wrapped with TLS.
The `https` scheme used in URIs really means `tls+http/1.1` and similarly the `wss` scheme used in URIs really means `tls+websocket`, etc.
Senders wrap the underlying protocol bytes (e.g. HTTP/1.1 bytes or WebSocket bytes) with the TLS protocol, while receivers first interpret the TLS protocol to obtain the underlying protocol bytes, and then interpret the wrapped bytes.
Secure protocols have a slightly more complicated configuration since they require to configure a _keystore_.
A keystore is a file on the file system that contains a private key and a public certificate, along with the certificate chain of the certificate authorities that issued the certificate.
The private key, the public certificate and the certificate chain, but more generally the items present in a keystore, are typically referred to as "cryptographic material".
Keystores may encode the cryptographic material with different encodings, the most common being link:https://en.wikipedia.org/wiki/PKCS_12[PKCS12], and are typically protected by a password.
After configuring the keystore path and keystore password, you may want to further customize the parameters of the TLS protocol, such as the minimum TLS protocol version, or the TLS algorithms, etc.
The Jetty `ssl` module allows you to configure the keystore and the TLS parameters; if other modules require encryption, they declare a dependency on the `ssl` module.
Since the `ssl` module is only about encryption, it does not configure a connector listening on a network port because it does not know what is the wrapped protocol.
It is the job of other Jetty modules to configure the wrapped protocol.
For example, it is the xref:og-protocols-https[`https` module] that configures the listening network port for secure HTTP/1.1.
The `https` module depends on the `ssl` module to allow the configuration of keystore and TLS, and adds HTTP/1.1 as the protocol wrapped by TLS.
Recall from the xref:og-modules[section about modules], that only modules that are explicitly enabled get their module configuration file (`+*.ini+`) saved in `$JETTY_BASE/start.d/`, and you want `$JETTY_BASE/start.d/ssl.ini` to be present so that you can configure the keystore and TLS properties.
// TODO: section about client authentication with certificates?
// See readme_keystores.txt about the fact that the server keystore needs the CA=true extension.

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

@ -0,0 +1,20 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
include::start-details.adoc[]
include::start-jar.adoc[]

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

@ -0,0 +1,25 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-start-details]]
=== 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.

4
jetty-documentation/src/main/asciidoc/operations-guide/old_docs/startup/start-jar.adoc → jetty-documentation/src/main/asciidoc/operations-guide/start/start-jar.adoc
View File

@ -16,9 +16,11 @@
// ======================================================================== // ========================================================================
// //
[[start-jar]] [[og-start-jar]]
=== Using 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`, which is a bootstrap for starting Jetty with the configuration you want. The most basic way of starting the Jetty standalone server is to execute the `start.jar`, which is a bootstrap for starting Jetty with the configuration you want.
[source, screen, subs="{sub-order}"] [source, screen, subs="{sub-order}"]

19
jetty-documentation/src/main/asciidoc/operations-guide/xml/chapter.adoc Normal file
View File

@ -0,0 +1,19 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
include::xml.adoc[]

24
jetty-documentation/src/main/asciidoc/operations-guide/xml/xml.adoc Normal file
View File

@ -0,0 +1,24 @@
//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
//
// This program and the accompanying materials are made available under
// the terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0
//
// This Source Code may also be made available under the following
// Secondary Licenses when the conditions for such availability set
// forth in the Eclipse Public License, v. 2.0 are satisfied:
// the Apache License v2.0 which is available at
// https://www.apache.org/licenses/LICENSE-2.0
//
// SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
// ========================================================================
//
[[og-xml]]
=== Jetty XML
TODO
// TODO: port the documentation from old_docs/jetty-xml/*.adoc

38
jetty-documentation/src/main/asciidoc/programming-guide/index.adoc
View File

@ -17,45 +17,11 @@
// //
:doctitle: Eclipse Jetty: Programming Guide :doctitle: Eclipse Jetty: Programming Guide
:author: Jetty Developers
:email: jetty-dev@eclipse.org
:revnumber: {version}
:revdate: {TIMESTAMP}
:toc: left
:toc-title: Programming Guide :toc-title: Programming Guide
:toc-style:
:header-style: eclipse-thin
:breadcrumb-style: eclipse-thin
:footer-style: default
:breadcrumb: Home:../index.html | Programming Guide:./index.html :breadcrumb: Home:../index.html | Programming Guide:./index.html
:idprefix: pg-
// docinfo lets you pull in shared content and/or influence via render type include::../config.adoc[]
//:docinfodir: {DOCINFODIR}/documentation
//:docinfo1:
// html specific directives
ifdef::backend-html5[]
:safe-mode-unsafe:
:stylesdir: ../common/css
:stylesheet: jetty.css
:linkcss:
:scriptsdir: ../common/js
endif::[]
// options for special blocks, code snippets, screen, etc
:sub-order: attributes+
// uncomment to allow include::https:// style content inclusion
//:allow-uri-read: true
// use fonts for admonitions
:icons: font
// suppress automatic id generation
:sectids!:
include::.asciidoctorconfig[] include::.asciidoctorconfig[]
include::introduction.adoc[] include::introduction.adoc[]
include::client/client.adoc[] include::client/client.adoc[]

1
jetty-server/src/main/config/modules/https.mod
View File

@ -13,6 +13,7 @@ ssl
ssl ssl
[optional] [optional]
alpn
http2 http2
http-forwarded http-forwarded

10
jetty-server/src/main/config/modules/ssl.mod
View File

@ -59,9 +59,6 @@ etc/jetty-ssl-context.xml
## Connect Timeout in milliseconds ## Connect Timeout in milliseconds
# jetty.ssl.connectTimeout=15000 # jetty.ssl.connectTimeout=15000
## Whether SNI is required for all secure connections. Rejections are in TLS handshakes.
# jetty.sslContext.sniRequired=false
## Whether SNI is required for all secure connections. Rejections are in HTTP 400 response. ## Whether SNI is required for all secure connections. Rejections are in HTTP 400 response.
# jetty.ssl.sniRequired=false # jetty.ssl.sniRequired=false
@ -78,6 +75,9 @@ etc/jetty-ssl-context.xml
## Note that OBF passwords are not secure, just protected from casual observation ## Note that OBF passwords are not secure, just protected from casual observation
## See http://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html ## See http://www.eclipse.org/jetty/documentation/current/configuring-security-secure-passwords.html
## Whether SNI is required for all secure connections. Rejections are in TLS handshakes.
# jetty.sslContext.sniRequired=false
## The Endpoint Identification Algorithm ## The Endpoint Identification Algorithm
## Same as javax.net.ssl.SSLParameters#setEndpointIdentificationAlgorithm(String) ## Same as javax.net.ssl.SSLParameters#setEndpointIdentificationAlgorithm(String)
#jetty.sslContext.endpointIdentificationAlgorithm= #jetty.sslContext.endpointIdentificationAlgorithm=
@ -86,10 +86,10 @@ etc/jetty-ssl-context.xml
# jetty.sslContext.provider= # jetty.sslContext.provider=
## Keystore file path (relative to $jetty.base) ## Keystore file path (relative to $jetty.base)
# jetty.sslContext.keyStorePath=etc/keystore # jetty.sslContext.keyStorePath=etc/keystore.p12
## Truststore file path (relative to $jetty.base) ## Truststore file path (relative to $jetty.base)
# jetty.sslContext.trustStorePath=etc/keystore # jetty.sslContext.trustStorePath=etc/keystore.p12
## Keystore password ## Keystore password
# jetty.sslContext.keyStorePassword= # jetty.sslContext.keyStorePassword=

2
pom.xml
View File

@ -734,7 +734,7 @@
<plugin> <plugin>
<groupId>org.asciidoctor</groupId> <groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId> <artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version> <version>2.1.0</version>
</plugin> </plugin>
<plugin> <plugin>
<groupId>org.codehaus.mojo</groupId> <groupId>org.codehaus.mojo</groupId>