Google Git
Sign in
eclipse/gerrit/www.eclipse.org/jetty/refs/heads/php-test/./distribution-guide/index.html
blob: dcf09594e53766a97cd398331a905079889104ff [file]
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]--><meta name="viewport" content="width=device-width, initial-scale=1"><meta name="generator" content="Asciidoctor 1.5.7.1"><title>Eclipse Jetty: Distribution Guide</title><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1"><!--Google Tag Manager--><script>(function(w,d,s,l,i){
w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});
var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';
j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5WLCZXC');</script><!--End Google Tag Manager--><link rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/quicksilver.min.css?v1.3"><meta name="description" content="The Eclipse Foundation - home to a global community, the Eclipse IDE, Jakarta EE and over 350 open source projects, including runtimes, tools and frameworks."><meta property="og:description" content="The Eclipse Foundation - home to a global community, the Eclipse IDE, Jakarta EE and over 350 open source projects, including runtimes, tools and frameworks."><meta property="og:image" content="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/images/logo/eclipse-foundation-200x200.png"><meta property="og:title" content="Eclipse Jetty"><meta property="og:image:width" content="200"><meta property="og:image:height" content="200"><meta itemprop="name" content="Eclipse Jetty"><meta itemprop="description" content="The Eclipse Foundation - home to a global community, the Eclipse IDE, Jakarta EE and over 350 open source projects, including runtimes, tools and frameworks."><meta itemprop="image" content="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/images/logo/eclipse-foundation-400x400.png"><meta name="twitter:site" content="@EclipseFdn"><meta name="twitter:card" content="summary"><meta name="twitter:title" content="Eclipse Jetty"><meta name="twitter:url" content="https://www.eclipse.org/eclipse.org-common/themes/solstice/html_template/index.php?theme=default&layout=thin"><meta name="twitter:description" content="The Eclipse Foundation - home to a global community, the Eclipse IDE, Jakarta EE and over 350 open source projects, including runtimes, tools and frameworks."><meta name="twitter:image" content="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/images/logo/eclipse-foundation-400x400.png"><link href="https://fonts.googleapis.com/css?family=Libre+Franklin:400,700,300,600,100" rel="stylesheet" type="text/css"><script>var eclipse_org_common = {"settings":{"cookies_class":{"name":"eclipse_settings","enabled":1}}}</script><link rel="stylesheet" href="../common/css/jetty.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.5.0/css/font-awesome.min.css"></head><body id="body_solstice"><!--Google Tag Manager (noscript)--><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5WLCZXC" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><!--End Google Tag Manager (noscript)--><a class="sr-only" href="#content">Skip to main content</a><header class="header-wrapper" id="header-wrapper"><div class="clearfix toolbar-container-wrapper"><div class="container"><div class="text-right toolbar-row row hidden-print"><div class="col-md-24 row-toolbar-col"></div></div></div></div><div class="container"><div class="row" id="header-row"><div class="col-sm-5 col-md-4" id="header-left"><div class="wrapper-logo-default"><a href="https://www.eclipse.org/"><img class="logo-eclipse-default hidden-xs" alt="logo" width="160" src="https://www.eclipse.org/eclipse.org-common/themes/solstice/public/images/logo/eclipse-foundation-white-orange.svg"></a></div></div></div></div></header><section class="default-breadcrumbs hidden-print breadcrumbs-default-margin" id="breadcrumb-thin"><div class="container"><h3 class="sr-only">Breadcrumbs</h3><div class="row"><div class="col-sm-24"><ol class="breadcrumb"><li><a href="../index.html ">Home</a></li><li><a href="./index.html"> Distribution Guide</a></li></ol></div></div></div></section><main id="main-wrapper"><div id="toc" class="toc2"><div id="toctitle">Distribution Guide</div><ul class="sectlevel1"><li><!--startup--><a href="#startup">Starting Jetty</a><ul class="sectlevel2"><li><!--startup-overview--><a href="#startup-overview">Startup Overview</a></li><li><!--start-jar--><a href="#start-jar">Using start.jar</a></li><li><!--startup-base-and-home--><a href="#startup-base-and-home">Managing Jetty Base and Jetty Home</a></li><li><!--startup-classpath--><a href="#startup-classpath">Managing Server Classpath</a></li><li><!--startup-modules--><a href="#startup-modules">Managing Startup Modules</a></li><li><!--custom-modules--><a href="#custom-modules">Custom Modules</a></li><li><!--startup-xml-config--><a href="#startup-xml-config">Managing XML Based Startup Configuration</a></li><li><!--startup-unix-service--><a href="#startup-unix-service">Startup a Unix Service using jetty.sh</a></li><li><!--startup-windows-service--><a href="#startup-windows-service">Startup via Windows Service</a></li><li><!--startup-jpms--><a href="#startup-jpms">Startup using the Java Platform Module System (JPMS)</a></li></ul></li><li><!--configuring-contexts--><a href="#configuring-contexts">Configuring Contexts</a><ul class="sectlevel2"><li><!--setting-context-path--><a href="#setting-context-path">Setting a Context Path</a></li><li><!--configuring-virtual-hosts--><a href="#configuring-virtual-hosts">Configuring Virtual Hosts</a></li><li><!--ref-temporary-directories--><a href="#ref-temporary-directories">Temporary Directories</a></li><li><!--serving-webapp-from-particular-port--><a href="#serving-webapp-from-particular-port">Serving a WebApp from a Particular Port/Connector</a></li><li><!--custom-error-pages--><a href="#custom-error-pages">Creating Custom Error Pages</a></li><li><!--setting-form-size--><a href="#setting-form-size">Setting Max Form Size</a></li></ul></li><li><!--configuring-deployment--><a href="#configuring-deployment">Deploying to Jetty</a><ul class="sectlevel2"><li><!--anatomy-of-a-webapp--><a href="#anatomy-of-a-webapp">Anatomy of a Web Application</a></li><li><!--automatic-webapp-deployment--><a href="#automatic-webapp-deployment">Automatic Web Application Deployment</a></li><li><!--configuring-specific-webapp-deployment--><a href="#configuring-specific-webapp-deployment">Configuring a Specific Web Application Deployment</a></li><li><!--configuring-webapps--><a href="#configuring-webapps">Deployment Processing of WebAppContexts</a></li><li><!--static-content-deployment--><a href="#static-content-deployment">Configuring Static Content Deployment</a></li><li><!--hot-deployment--><a href="#hot-deployment">Hot Deployment</a></li><li><!--deployment-architecture--><a href="#deployment-architecture">Deployment Architecture</a></li><li><!--quickstart-webapp--><a href="#quickstart-webapp">Quickstart Webapps</a></li></ul></li><li><!--configuring-connectors--><a href="#configuring-connectors">Configuring Jetty Connectors</a><ul class="sectlevel2"><li><!--jetty-connectors--><a href="#jetty-connectors">Connector Configuration Overview</a></li><li><!--configuring-ssl--><a href="#configuring-ssl">Configuring SSL/TLS</a></li><li><!--jetty-ssl-distribution--><a href="#jetty-ssl-distribution">SSL in the Jetty Distribution</a></li></ul></li><li><!--http2--><a href="#http2">HTTP/2</a><ul class="sectlevel2"><li><!--http2-introduction--><a href="#http2-introduction">Introducing HTTP/2</a></li><li><!--http2-enabling--><a href="#http2-enabling">Enabling HTTP/2</a></li><li><!--http2-configuring--><a href="#http2-configuring">Configuring HTTP/2</a></li><li><!--http2-configuring-push--><a href="#http2-configuring-push">Configuring HTTP/2 Push</a></li><li><!--http2-configuring-haproxy--><a href="#http2-configuring-haproxy">Configuring HAProxy and Jetty</a></li></ul></li><li><!--configuring-logging--><a href="#configuring-logging">Jetty Logging</a><ul class="sectlevel2"><li><!--configuring-jetty-logging--><a href="#configuring-jetty-logging">Configuring Jetty Logging</a></li><li><!--default-logging-with-stderrlog--><a href="#default-logging-with-stderrlog">Default Logging with Jetty&#8217;s StdErrLog</a></li><li><!--configuring-jetty-request-logs--><a href="#configuring-jetty-request-logs">Configuring Jetty Request Logs</a></li><li><!--configuring-logging-modules--><a href="#configuring-logging-modules">Jetty Logging Integrations (SLF4J, Log4j, Logback, JCL, JUL)</a></li><li><!--example-logging-logback-centralized--><a href="#example-logging-logback-centralized">Centralized Logging using Logback</a></li><li><!--jetty-dump-tool--><a href="#jetty-dump-tool">Jetty Dump Tool</a></li></ul></li><li><!--configuring-security--><a href="#configuring-security">Configuring Security</a><ul class="sectlevel2"><li><!--configuring-security-authentication--><a href="#configuring-security-authentication">Authentication and Authorization</a></li><li><!--configuring-form-size--><a href="#configuring-form-size">Limiting Form Content</a></li><li><!--serving-aliased-files--><a href="#serving-aliased-files">Aliased Files and Symbolic links</a></li><li><!--configuring-security-secure-passwords--><a href="#configuring-security-secure-passwords">Secure Password Obfuscation</a></li><li><!--setting-port80-access--><a href="#setting-port80-access">Setting Port 80 Access for a Non-Root User</a></li><li><!--jaas-support--><a href="#jaas-support">JAAS Support</a></li><li><!--spnego-support--><a href="#spnego-support">SPNEGO Support</a></li><li><!--openid-support--><a href="#openid-support">OpenID Support</a></li></ul></li><li><!--session-management--><a href="#session-management">Session Management</a><ul class="sectlevel2"><li><!--jetty-sessions-architecture--><a href="#jetty-sessions-architecture">Session Architecture</a></li><li><!--sessions-details--><a href="#sessions-details">Session Components</a></li><li><!--session-configuration-housekeeper--><a href="#session-configuration-housekeeper">The SessionIdManager and the Housekeeper</a></li><li><!--session-configuration-sessioncache--><a href="#session-configuration-sessioncache">The L1 Session Cache</a></li><li><!--configuring-sessions-memory--><a href="#configuring-sessions-memory">Non-Persistent Sessions</a></li><li><!--configuring-sessions-file-system--><a href="#configuring-sessions-file-system">Persistent Sessions: File System</a></li><li><!--configuring-sessions-jdbc--><a href="#configuring-sessions-jdbc">Persistent Sessions: JDBC</a></li><li><!--configuring-sessions-mongo--><a href="#configuring-sessions-mongo">Persistent Sessions: MongoDB</a></li><li><!--configuring-sessions-infinispan--><a href="#configuring-sessions-infinispan">Persistent Sessions: Inifinspan</a></li><li><!--configuring-sessions-hazelcast--><a href="#configuring-sessions-hazelcast">Persistent Sessions: Hazelcast</a></li><li><!--configuring-sessions-gcloud--><a href="#configuring-sessions-gcloud">Persistent Sessions: Google Cloud DataStore</a></li><li><!--session-configuration-memcachedsessiondatastore--><a href="#session-configuration-memcachedsessiondatastore">Persistent Sessions: The L2 Session Data Cache</a></li><li><!--sessions-usecases--><a href="#sessions-usecases">Session Use Cases</a></li></ul></li><li><!--configuring-jsp--><a href="#configuring-jsp">Configuring JSP Support</a><ul class="sectlevel2"><li><!--jsp-support--><a href="#jsp-support">Configuring JSP</a></li></ul></li><li><!--annotations--><a href="#annotations">Annotations</a><ul class="sectlevel2"><li><!--annotations-quick-setup--><a href="#annotations-quick-setup">Quick Setup</a></li><li><!--using-annotations--><a href="#using-annotations">Working with Annotations</a></li><li><!--using-annotations-embedded--><a href="#using-annotations-embedded">Using Annotations with Jetty Embedded</a></li></ul></li><li><!--jmx-chapter--><a href="#jmx-chapter">Java Management Extensions (JMX)</a><ul class="sectlevel2"><li><!--using-jmx--><a href="#using-jmx">Using JMX with Jetty</a></li><li><!--jetty-jmx-annotations--><a href="#jetty-jmx-annotations">Jetty JMX Annotations</a></li><li><!--jetty-jconsole--><a href="#jetty-jconsole">Managing Jetty with JConsole and JMC</a></li></ul></li><li><!--jndi--><a href="#jndi">Configuring JNDI</a><ul class="sectlevel2"><li><!--jndi-quick-setup--><a href="#jndi-quick-setup">Quick Setup</a></li><li><!--using-jetty-jndi--><a href="#using-jetty-jndi">Working with Jetty JNDI</a></li><li><!--jndi-configuration--><a href="#jndi-configuration">Configuring JNDI</a></li><li><!--jndi-embedded--><a href="#jndi-embedded">Using JNDI with Jetty Embedded</a></li><li><!--jndi-datasource-examples--><a href="#jndi-datasource-examples">Datasource Examples</a></li></ul></li><li><!--alpn-chapter--><a href="#alpn-chapter">Application Layer Protocol Negotiation (ALPN)</a><ul class="sectlevel2"><li><!--alpn--><a href="#alpn">Introducing ALPN</a></li></ul></li><li><!--fastcgi--><a href="#fastcgi">FastCGI Support</a><ul class="sectlevel2"><li><!--fastcgi-intro--><a href="#fastcgi-intro">FastCGI Introduction</a></li><li><!--configuring-fastcgi--><a href="#configuring-fastcgi">Configuring Jetty for FastCGI</a></li></ul></li><li><!--advanced-extras--><a href="#advanced-extras">Provided Servlets, Filters, and Handlers</a><ul class="sectlevel2"><li><!--default-servlet--><a href="#default-servlet">Default Servlet</a></li><li><!--proxy-servlet--><a href="#proxy-servlet">Proxy Servlet</a></li><li><!--balancer-servlet--><a href="#balancer-servlet">Balancer Servlet</a></li><li><!--cgi-servlet--><a href="#cgi-servlet">CGI Servlet</a></li><li><!--qos-filter--><a href="#qos-filter">Quality of Service Filter</a></li><li><!--dos-filter--><a href="#dos-filter">Denial of Service Filter</a></li><li><!--header-filter--><a href="#header-filter">Header Filter</a></li><li><!--gzip-filter--><a href="#gzip-filter">Gzip Handler</a></li><li><!--cross-origin-filter--><a href="#cross-origin-filter">Cross Origin Filter</a></li><li><!--resource-handler--><a href="#resource-handler">Resource Handler</a></li><li><!--debug-handler--><a href="#debug-handler">Debug Handler</a></li><li><!--statistics-handler--><a href="#statistics-handler">Statistics Handler</a></li><li><!--inetaccess-handler--><a href="#inetaccess-handler">InetAccess Handler</a></li><li><!--moved-context-handler--><a href="#moved-context-handler">Moved Context Handler</a></li><li><!--shutdown-handler--><a href="#shutdown-handler">Shutdown Handler</a></li><li><!--default-handler--><a href="#default-handler">Default Handler</a></li><li><!--error-handler--><a href="#error-handler">Error Handler</a></li><li><!--rewrite-handler--><a href="#rewrite-handler">Rewrite Handler</a></li></ul></li><li><!--runner--><a href="#runner">Jetty Runner</a><ul class="sectlevel2"><li><!--jetty-runner--><a href="#jetty-runner">Use Jetty Without an Installed Distribution</a></li></ul></li><li><!--optimizing--><a href="#optimizing">Optimizing Jetty</a><ul class="sectlevel2"><li><!--garbage-collection--><a href="#garbage-collection">Garbage Collection</a></li><li><!--high-load--><a href="#high-load">High Load</a></li><li><!--limit-load--><a href="#limit-load">Limiting Load</a></li></ul></li></ul></div><div id="content-container"><div id="header"><h1>Eclipse Jetty: Distribution Guide</h1><div class="details"><span class="author" id="author">Jetty Developers</span><br><span class="email" id="email"><a href="mailto:jetty-dev@eclipse.org">jetty-dev@eclipse.org</a></span><br><span id="revnumber">version 1.0,</span> <span id="revdate">2020-03-18 17:03</span></div></div><div id="content"><div class="sect1">
<h2 id="startup">Starting Jetty</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="startup-overview">Startup Overview</h3>
<div class="paragraph">
<p>The <code>start.jar</code> bootstrap manages the startup of standalone Jetty.
It is responsible for:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Building the classpath</dt>
<dd>
<p>The <code>start.jar</code> bootstrap builds a classpath for all the required Jetty features and their dependencies.
It builds the classpath using either the <code>--lib</code> option to <code>start.jar</code> to add an individual classpath entry, or with the <code>--module</code> option that includes all the libs and their dependencies for a module (a named Jetty feature).</p>
</dd>
<dt class="hdlist1">Instantiating the Server Components</dt>
<dd>
<p>The server and its components are instantiated using either Jetty IoC XML or Spring.
The Jetty server is a collection of POJOs for the server, connectors, session managers and others.
These are instantiated, injected, and wired up together in XML files, commonly one per module/feature, that are passed as arguments to <code>start.jar</code>.</p>
</dd>
<dt class="hdlist1">Resolving Server Filesystem Locations</dt>
<dd>
<p>The <code>start.jar</code> mechanism resolves canonical locations for the <code>${jetty.home}</code> and the <code>${jetty.base}</code> directories.
The <code>${jetty.home}</code> directory is the location of the standard distribution of Jetty.
The <code>${jetty.base}</code> directory is the location of the local server customization and configurations.
+
If you want to modify the Jetty distribution, base and home can be the same directory.
Separating the base and home directories allows the distribution to remain unmodified, with all customizations in the base directory, and thus simplifies subsequent server version upgrades.</p>
</dd>
<dt class="hdlist1">Parameterizing the Server Configuration</dt>
<dd>
<p>XML files primarily determine the server configuration.
Many of these files are parameterized to allow simple injection of host names, ports, passwords and more.
The <code>start.jar</code> mechanism allows you to set parameters on the command line or in properties files.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>To achieve these start up mechanisms, the <code>start.jar</code> uses:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Command line arguments</dt>
<dd>
<p>You can configure the entire server with command line arguments that specify libraries, properties and XML files.
However in practice the INI and modules mechanisms (below) reduce the verbosity of the command line.</p>
</dd>
<dt class="hdlist1">INI files</dt>
<dd>
<p>The <code>start.jar</code> mechanism uses the contents of the <code>${jetty.base}/start.ini</code> and <code>${jetty.base}/start.d/*.ini</code> files with each line equivalent to a <code>start.jar</code> command line argument.
This means that either a global <code>start.ini</code> file or multiple <code>start.d/feature.ini</code> files control the configuration of the server.</p>
</dd>
</dl>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>It is important to chose <strong>either</strong> <code>${jetty.base}/start.ini</code> or <code>${jetty.base}/start.d/*.ini</code> to manage configuration.
Using both is not recommended and can lead to issues with your server.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Modules</dt>
<dd>
<p>Instead of explicitly listing all the libraries, properties and XML files for a feature, the <code>start.jar</code> mechanism allows you to create modules.
A module is defined in a <code>modules/<strong>.mod</code> file, including the libraries, dependencies, XML, and template INI files for a Jetty feature.
Thus you can use a single <code>--module=name</code> command line option as the equivalent of specifying <code>--lib=location</code>, <code>feature.xml</code> or <code>name=value</code> arguments for a feature and all its dependencies.
Modules also use their dependencies to control the ordering of libraries and XML files.
There are several module files included with the Jetty distribution that cover the most common server features, such as HTTP, HTTPS, SSL, Logging, Annotations&#8230;&#8203;etc.
These module files should *only</strong> be edited if you are making structural changes to the way the feature will perform.
For more information, refer to the section on <a href="#startup-modules">managing startup modules</a> later in this chapter.</p>
</dd>
<dt class="hdlist1">XML Files</dt>
<dd>
<p>XML files in either Jetty IoC or Spring format instantiate the actual POJO components of the server.
This includes all major components such as connectors, keystores, session managers, and data sources.
Typically there are one or more XML files per module, and these are defined and activated in the corresponding module.</p>
</dd>
</dl>
</div>
<div class="sect3">
<h4>Startup Example</h4>
<div class="paragraph">
<p>The simplest way to start Jetty is via the <code>start.jar</code> mechanism using the following Java command line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[user]$ cd jetty-distribution-10.0.0-SNAPSHOT
[jetty-distribution-10.0.0-SNAPSHOT]$ java -jar start.jar --module=http jetty.http.port=8080</code></pre>
</div>
</div>
<div class="paragraph">
<p>This command uses the <code>start.jar</code> mechanism to bootstrap the classpath, properties, and XML files with the metadata obtained from the <code>http</code> module.
Specifically the <code>http</code> module is defined in the <code>${jetty.home}/modules/http.mod</code> file, and includes the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ cat modules/http.mod
[depend]
server
[xml]
etc/jetty-http.xml
[ini-template]
jetty.http.port=8080
http.timeout=30000</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>http</code> module declares that <code>http</code> depends on the server module, uses the <code>jetty-http.xml</code> file, and can be parameterized with <code>jetty.http.port</code> and <code>http.timeout</code> parameters.
The INI-template section is not actually used by the command above, so the <code>jetty.http.port</code> must still be defined on the command line.</p>
</div>
<div class="paragraph">
<p>Following the server dependency, the <code>${jetty.home}/modules/server.mod</code> file includes:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ cat modules/server.mod
[lib]
lib/jetty-servlet-api-4.0.2.jar
lib/jetty-http-${jetty.version}.jar
lib/jetty-server-${jetty.version}.jar
lib/jetty-xml-${jetty.version}.jar
lib/jetty-util-${jetty.version}.jar
lib/jetty-io-${jetty.version}.jar
[xml]
etc/jetty.xml
[ini-template]
threads.min=10
threads.max=200</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>server</code> module declares the libraries the server needs and to use <code>jetty.xml</code> file.
The combined metadata of the <code>http</code> and <code>server</code> modules results in <code>start.jar</code> generating the effective Java command line required to start Jetty.</p>
</div>
<div class="paragraph">
<p>Another way to see this is by asking Jetty what its configuration looks like by appending --list-config to the command line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ java -jar start.jar --module=http jetty.http.port=9099 --list-config
Java Environment:
-----------------
java.home=/user/lib/jvm/jdk-7u21-x64/jre
java.vm.vendor=Oracle Corporation
java.vm.version=23.25-b01
java.vm.name=Java HotSpot(TM) 64-Bit Server VM
java.vm.info=mixed mode
java.runtime.name=Java(TM) SE Runtime Environment
java.runtime.version=1.7.0_25-b15
java.io.tmpdir=/tmp
Jetty Environment:
-----------------
jetty.home=/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
jetty.base=/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
jetty.version=10.0.0-SNAPSHOT
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
jetty.home = /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
jetty.base = /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
Properties:
-----------
jetty.http.port = 9099
Jetty Server Classpath:
-----------------------
Version Information on 7 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: 3.1.0 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
2: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-http-10.0.0-SNAPSHOT.jar
3: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-server-10.0.0-SNAPSHOT.jar
4: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-xml-10.0.0-SNAPSHOT.jar
5: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-util-10.0.0-SNAPSHOT.jar
6: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-io-10.0.0-SNAPSHOT.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-http.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>This represents the entirety of the configuration that is applied to start Jetty.</p>
</div>
<div class="paragraph">
<p>If you don&#8217;t want to use the <code>start.jar</code> bootstrap, you can start Jetty using a traditional Java command line.</p>
</div>
<div class="paragraph">
<p>The following is the equivalent Java command line for what the <code>start.jar</code> bootstrap above performs.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[user]$ cd jetty-distribution-10.0.0-SNAPSHOT
[jetty-distribution-10.0.0-SNAPSHOT]$ echo jetty.http.port=8080 &gt; /tmp/jetty.properties
[jetty-distribution-10.0.0-SNAPSHOT]$ export JETTY_HOME=`pwd`
[jetty-distribution-10.0.0-SNAPSHOT]$ export JETTY_BASE=`pwd`
[jetty-distribution-10.0.0-SNAPSHOT]$ export JETTY_VERSION="${project.version}"
[jetty-distribution-10.0.0-SNAPSHOT]$ java -Djetty.home=$JETTY_HOME \
-Djetty.base=$JETTY_BASE \
-cp \
$JETTY_HOME/lib/jetty-servlet-api-4.0.2.jar\
:$JETTY_HOME/lib/jetty-http-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-server-$JETTY_VERSION.jar \
:$JETTY_HOME/lib/jetty-xml-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-util-$JETTY_VERSION.jar\
:$JETTY_HOME/lib/jetty-io-$JETTY_VERSION.jar\
org.eclipse.jetty.xml.XmlConfiguration \
/tmp/jetty.properties \
$JETTY_HOME/etc/jetty.xml \
$JETTY_HOME/etc/jetty-http.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>The Java command line sets up the classpath with the core Jetty jars and the servlet API, executes the XmlConfiguration class and passes it some XML files that define the server and an HTTP connector running on the port defined in the <code>jetty.properties</code> file.</p>
</div>
<div class="paragraph">
<p>You can further simplify the startup of this server by using the INI template defined by the modules to create a <code>start.ini</code> file with the command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[user]$ cd jetty-distribution-10.0.0-SNAPSHOT
[jetty-distribution-10.0.0-SNAPSHOT]$ mkdir example-base
[example-base]$ cd example-base
[example-base]$ ls -la
total 8
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:49 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
[example-base]$ java -jar $JETTY_HOME/start.jar --add-to-start=http
WARNING: http initialised in ${jetty.base}/start.ini (appended)
WARNING: http enabled in ${jetty.base}/start.ini
WARNING: server initialised in ${jetty.base}/start.ini (appended)
WARNING: server enabled in ${jetty.base}/start.ini
[example-base]$ ls -la
total 12
drwxrwxr-x 2 user webgroup 4096 Oct 4 11:55 ./
drwxrwxr-x 12 user webgroup 4096 Oct 4 11:49 ../
-rw-rw-r-- 1 user webgroup 250 Oct 4 11:55 start.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once complete, you can edit the <code>start.ini</code> file to modify any parameters and you can run the server with the simple command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[example-base]$ java -jar $JETTY_HOME/start.jar</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="start-jar">Using start.jar</h3>
<div class="paragraph">
<p>The most basic way of starting the Jetty standalone server is to execute the <code>start.jar</code>, which is a bootstrap for starting Jetty with the configuration you want.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ java -jar start.jar
2013-09-23 11:27:06.654:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Jetty is a highly modularized web server container.
Very little is mandatory and required, and most components are optional; you enable or disable them according to the needs of your environment.</p>
</div>
<div class="paragraph">
<p>At its most basic, you configure Jetty from two elements:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>A set of libraries and directories that make up the server classpath.</p>
</li>
<li>
<p>A set of Jetty XML configuration files (IoC style) that establish how to build the Jetty server and its components.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Instead of editing these directly, Jetty 9.1 introduced more options on how to configure Jetty (these are merely syntactic sugar that eventually resolve into the two basic configuration components).</p>
</div>
<div class="paragraph">
<p>Jetty Startup Features include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A separation of the Jetty distribution binaries in <code>${jetty.home}</code> and the environment specific configurations (and binaries) found in <code>${jetty.base}</code> (detailed in <a href="#startup-jetty-base-and-jetty-home">Managing Jetty Base and Jetty Home.</a>)</p>
</li>
<li>
<p>You can enable a set of libraries and XML configuration files via the newly introduced <a href="#startup-modules">module system.</a></p>
</li>
<li>
<p>All of the pre-built XML configuration files shipped in Jetty are now parameterized with properties that you can specify in your <code>${jetty.base}/start.ini</code> (demonstrated in <a href="#quick-start-configure">Quick Start Configuration</a>).</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>These are powerful new features, made to support a variety of styles of configuring Jetty, from a simple property based configuration, to handling multiple installations on a server, to customized stacks of technology on top of Jetty, and even the classic, custom XML configurations of old.</p>
</div>
<div class="paragraph">
<p>For example, if you use the <code>${jetty.base}</code> concepts properly, you can upgrade the Jetty distribution without having to remake your entire tree of modifications to Jetty.
Simply separate out your specific modifications to the <code>${jetty.base}</code>, and in the future, just upgrade your <code>${jetty.home}</code> directory with a new Jetty distribution.</p>
</div>
<div class="sect3">
<h4 id="executing-startjar">Executing start.jar</h4>
<div class="paragraph">
<p>When executed <code>start.jar</code> performs the following actions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Loads and parses all INIs found in <code>${jetty.base}/start.d/*.ini</code> as command line arguments.</p>
</li>
<li>
<p>Loads and parses <code>${jetty.base}/start.ini</code> as command line arguments.</p>
<div class="ulist">
<ul>
<li>
<p>Please see <a href="#start-vs-startd">Start.ini vs. Start.d</a> for more information on the difference between these.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Parses actual command line arguments used to execute <code>start.jar</code> itself.</p>
</li>
<li>
<p>Resolves any XML configuration files, modules, and libraries using base vs. home resolution steps:</p>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Checks whether file exists as relative reference to <code>${jetty.base}.</code></p>
</li>
<li>
<p>Checks whether file exists as relative reference to <code>${jetty.home}.</code></p>
</li>
<li>
<p>Uses default behavior of <code>java.io.File</code> (Relative to <code>System.getProperty</code> ("user.dir") and then as absolute file system path).</p>
</li>
</ol>
</div>
</li>
<li>
<p>Loads any dependent modules (merges XXNK, library, and properties results with active command line).</p>
</li>
<li>
<p>Builds out server classpath.</p>
</li>
<li>
<p>Determines run mode:</p>
<div class="ulist">
<ul>
<li>
<p>Shows informational command line options and exit.</p>
</li>
<li>
<p>Executes Jetty normally, waits for Jetty to stop.</p>
</li>
<li>
<p>Executes a forked JVM to run Jetty in, waits for forked JVM to exit.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4>start.jar Command Line Options</h4>
<div class="sect4">
<h5>Command Line Options</h5>
<div class="dlist">
<dl>
<dt class="hdlist1">--help</dt>
<dd>
<p>Obtains the current list of command line options and some basic usage help.</p>
</dd>
<dt class="hdlist1">--version</dt>
<dd>
<p>Shows the list of server classpath entries, and prints version information found for each entry.</p>
</dd>
<dt class="hdlist1">--list-classpath</dt>
<dd>
<p>Similar to --version, shows the server classpath.</p>
</dd>
<dt class="hdlist1">--list-config</dt>
<dd>
<p>Lists the resolved configuration that will start Jetty.</p>
<div class="ulist">
<ul>
<li>
<p>Java environment</p>
</li>
<li>
<p>Jetty environment</p>
</li>
<li>
<p>JVM arguments</p>
</li>
<li>
<p>Properties</p>
</li>
<li>
<p>Server classpath</p>
</li>
<li>
<p>Server XML configuration files</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1">--dry-run</dt>
<dd>
<p>Prints the resolved command line that <code>start.jar</code> should use to start a forked instance of Jetty.</p>
</dd>
<dt class="hdlist1">--exec</dt>
<dd>
<p>Starts a forked instance of Jetty.</p>
</dd>
<dt class="hdlist1">--exec-properties=&lt;filename&gt;</dt>
<dd>
<p>Assign a fixed name to the file used to transfer properties to the sub process.
This allows the generated properties file to be saved and reused.
Without this option, a temporary file is used.</p>
</dd>
<dt class="hdlist1">--commands=&lt;filename&gt;</dt>
<dd>
<p>Instructs <code>start.jar</code> to use each line of the specified file as arguments on the command line.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>Debugg and Start Logging</h5>
<div class="dlist">
<dl>
<dt class="hdlist1">--debug</dt>
<dd>
<p>Enables debugging output of the startup procedure.</p>
<div class="paragraph">
<p><strong>Note</strong>: This does not set up debug logging for Jetty itself.
For information on logging, please see the section on <a href="#configuring-jetty-logging">Configuring Jetty Logging.</a>]</p>
</div>
</dd>
<dt class="hdlist1">--start-log-file=&lt;filename&gt;</dt>
<dd>
<p>Sends all startup output to the filename specified.
Filename is relative to <code>${jetty.base}</code>.
This is useful for capturing startup issues where the Jetty-specific logger has not yet kicked in due to a possible startup configuration error.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>Module Management</h5>
<div class="dlist">
<dl>
<dt class="hdlist1">--list-modules</dt>
<dd>
<p>Lists all the modules defined by the system.
Looks for module files using the <a href="#startup-base-and-home">normal <code>${jetty.base}</code> and <code>${jetty.home}</code> resolution logic</a>.
Also lists enabled state based on information present on the command line, and all active startup INI files.</p>
</dd>
<dt class="hdlist1">--list-modules=&lt;tag&gt;(,&lt;tag&gt;)*</dt>
<dd>
<p>List modules by <a href="#startup-modules">tag.</a>
Use '*' for all tags.
Prefix a tag with '-' to exclude the tag.
The special tag "internal" is always excluded unless it is explicitly included.</p>
</dd>
<dt class="hdlist1">--list-all-modules</dt>
<dd>
<p>List all modules.</p>
</dd>
<dt class="hdlist1">--module=&lt;name&gt;,(&lt;name&gt;)*</dt>
<dd>
<p>Enables one or more modules by name (use <code>--list-modules</code> to see the list of available modules).
This enables all transitive (dependent) modules from the module system as well.
If you use this from the shell command line, it is considered a temporary effect, useful for testing out a scenario.
If you want this module to always be enabled, add this command to your <code>${jetty.base}/start.ini.</code></p>
</dd>
<dt class="hdlist1">--add-to-start=&lt;name&gt;,(&lt;name&gt;)*</dt>
<dd>
<p>Enables a module by appending lines to the <code>${jetty.base}/start.ini</code> file.
The lines that are added are provided by the module-defined INI templates.
Note: Transitive modules are also appended.
If a module contains an .ini template with properties, you can also edit these properties when activating the module.
To do this, simply list the property and its value after the <code>-add-to-start</code> command, such as in the following example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar start.jar --add-to-start=http jetty.http.port=8379 jetty.http.host=1.2.3.4</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this will uncomment the property in the associated .ini file and set it to the value specified.</p>
</div>
</dd>
<dt class="hdlist1">--update-ini</dt>
<dd>
<p>Used to update a specified property or properties that exist in an existing .ini file.
Jetty scans the command line, <code>${jetty.base}</code> and <code>${jetty.home}</code> for .ini files that have the specified property and update it accordingly.</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --update-ini jetty.http.port=8417
ConfigSource &lt;command-line&gt;
ConfigSource ${jetty.base}
INFO : http property updated jetty.http.port=8417
INFO : http updated ${jetty.base}/start.d/http.ini
ConfigSource ${jetty.home}</code></pre>
</div>
</div>
</dd>
<dt class="hdlist1">--create-startd</dt>
<dd>
<p>Creates a <code>${jetty.base}/start.d/</code> directory.
If a <code>${jetty.base}/start.ini</code> file already exists, it is copied to the <code>${jetty.base}/start.d</code> directory.</p>
</dd>
</dl>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>With respect to <code>start.ini</code> and <code>start.d/<strong>.ini</code> files, only *one</strong> of these methods should be implemented.
Mixing a <code>start.ini</code> with module specific ini files in the <code>{$jetty.base}/start.d</code> directory can lead to server issues unless great care is taken.
Please see <a href="#start-vs-startd">Start.ini vs. Start.d</a> for more information.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">--write-module-graph=&lt;filename&gt;</dt>
<dd>
<p>Advanced feature: Creates a graphviz <a href="http://graphviz.org/content/dot-language">dot file</a> of the module graph as it exists for the active <code>${jetty.base}</code>.</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># generate module.dot
$ java -jar start.jar --module=websocket --write-module-graph=modules.dot
# post process to a PNG file
$ dot -Tpng -o modules.png modules.dot</code></pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="http://graphviz.org/">graphviz.org</a> for details on <a href="http://graphviz.org/content/command-line-invocation">how to post-process this dotty file</a> into the output best suited for your needs.</p>
</div>
</dd>
<dt class="hdlist1">--create-files</dt>
<dd>
<p>Create any missing files that are required by initialized modules.
This may download a file from the network if the module provides a URL.</p>
</dd>
<dt class="hdlist1">--skip-file-validation=&lt;modulename&gt;(,&lt;modulename)*</dt>
<dd>
<p>Disable the [files] section validation of content in the <code>${jetty.base}</code> directory for a specific module.
Useful for modules that have downloadable content that is being overridden with alternatives in the <code>${jetty.base}`</code> directory.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
This advanced option is for administrators that fully understand the configuration of their <code>${jetty.base}</code> and are willing to forego some of the safety checks built into the jetty-start mechanism.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">--approve-all-licenses</dt>
<dd>
<p>Approve all license questions.
Useful for enabling modules from a script that does not require user interaction.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>Startup / Shutdown Command Line</h5>
<div class="dlist">
<dl>
<dt class="hdlist1">--stop</dt>
<dd>
<p>Sends a stop signal to the running Jetty instance.</p>
<div class="paragraph">
<p>Note: The server must have been started with various stop properties for this to work.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">STOP.PORT=&lt;number&gt;</dt>
<dd>
<p>The port to use to stop the running Jetty server.
This is an internal port, opened on localhost, used solely for stopping the running Jetty server.
Choose a port that you do not use to serve web traffic.</p>
<div class="paragraph">
<p>Required for <code>--stop</code> to function.</p>
</div>
</dd>
<dt class="hdlist1">STOP.KEY=&lt;alphanumeric&gt;</dt>
<dd>
<p>The passphrase defined to stop the server.</p>
<div class="paragraph">
<p>Required for <code>--stop</code> to function.</p>
</div>
</dd>
<dt class="hdlist1">STOP.WAIT=&lt;number&gt;</dt>
<dd>
<p>The time (in seconds) to wait for confirmation that the running Jetty server has stopped.
If not specified, the stopper waits indefinitely for the server to stop.</p>
<div class="paragraph">
<p>If the time specified elapses, without a confirmation of server stop, then the <code>--stop</code> command exits with a non-zero return code.</p>
</div>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the <code>STOP.PORT</code> and <code>STOP.KEY</code> (or <code>-DSTOP.PORT=</code> and <code>-DSTOP.KEY=</code>, respectively, which will set these as system parameters) parameters as arguments to the <code>start.jar</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar ${JETTY_HOME}/start.jar STOP.PORT=1234 STOP.KEY=secretpassword</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then, to stop Jetty from a different terminal, you need to supply this port and key information.
You can either use a copy of the Jetty distribution, the <a href="#jetty-maven-plugin">jetty-maven-plugin</a>, the <a href="#jetty-ant">jetty-ant plugin</a>, or a custom class to accomplish this.
Here&#8217;s how to use the Jetty distribution, leveraging <code>start.jar</code>, to perform a stop:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar start.jar STOP.PORT=8181 STOP.KEY=abc123 --stop</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
To perform a graceful shutdown of Jetty, the <code>stats</code> <a href="#startup-modules">module</a> <strong>must</strong> be enabled.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect4">
<h5>Advanced Commands</h5>
<div class="dlist">
<dl>
<dt class="hdlist1">--lib=&lt;classpath&gt;</dt>
<dd>
<p>Add arbitrary classpath entries to the the server classpath.</p>
</dd>
<dt class="hdlist1">--include-jetty-dir=&lt;path&gt;</dt>
<dd>
<p>Include an extra Jetty directory to use as a source for configuration details.
This directory behaves similarly to <code>${jetty.base}</code> but sits at a layer between <code>${jetty.base}</code> and <code>${jetty.home}</code>.
This allows for some complex hierarchies of configuration details.</p>
</dd>
<dt class="hdlist1">--download=&lt;http-uri&gt;|&lt;location&gt;</dt>
<dd>
<p>If the file does not exist at the given location, download it from the given http URI.
Note: location is always relative to <code>${jetty.base}</code>.
You might need to escape the slash "\|" to use this on some environments.</p>
</dd>
<dt class="hdlist1">maven.repo.uri=[url]</dt>
<dd>
<p>The url to use to download Maven dependencies.
Default is <a href="https://repo1.maven.org/maven2/" class="bare">https://repo1.maven.org/maven2/</a>.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect3">
<h4>Shaded Start.jar</h4>
<div class="paragraph">
<p>If you have a need for a shaded version of <code>start.jar</code> (such as for Gradle), you can achieve this via a Maven dependency.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
&lt;groupId&gt;org.eclipse.jetty&lt;/groupId&gt;
&lt;artifactId&gt;jetty-start&lt;/artifactId&gt;
&lt;version&gt;10.0.0-SNAPSHOT&lt;/version&gt;
&lt;classifier&gt;shaded&lt;/classifier&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="startup-base-and-home">Managing Jetty Base and Jetty Home</h3>
<div class="paragraph">
<p>Instead of managing multiple Jetty implementations out of several different distribution locations, it is possible to maintain a separation between the binary installation of the standalone Jetty (known as <code>${jetty.home}</code>), and the customizations for your specific environment(s) (known as <code>${jetty.base}</code>).
In addition to easy management of multiple server instances, is allows for quick, drop-in upgrades of Jetty.
There should always only be <strong>one</strong> Jetty Home (per version of Jetty), but there can be multiple Jetty Base directories that reference it.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Jetty Base</dt>
<dd>
<div class="ulist">
<ul>
<li>
<p>Also known as the <code>${jetty.base}</code> property.</p>
</li>
<li>
<p>This is the location for your configurations and customizations to the Jetty distribution.</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1">Jetty Home</dt>
<dd>
<div class="ulist">
<ul>
<li>
<p>Also known as the <code>${jetty.home}</code> property.</p>
</li>
<li>
<p>This is the location for the Jetty distribution binaries, default XML IoC configurations, and default module definitions.</p>
</li>
</ul>
</div>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Jetty Home should always be treated as a standard of truth.
All configuration modifications, changes and additions should be made in the appropriate Jetty Base directory.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div id="base-vs-home-resolution" class="paragraph">
<p>Potential configuration is resolved from these 2 directory locations.
When Jetty starts up in processes configuration from them as follows:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Check Jetty Base First</dt>
<dd>
<p>If the referenced configuration exists, relative to the defined Jetty base, it is used.</p>
</dd>
<dt class="hdlist1">Check Jetty Home Second</dt>
<dd>
<p>If the referenced configuration exists, relative to the defined Jetty home, it is used.</p>
</dd>
<dt class="hdlist1">Use java.io.File(String pathname) Logic</dt>
<dd>
<p>Lastly, use the reference as a <code>java.io.File(String pathname)</code> reference, following the default resolution rules outlined by that constructor. In brief, the reference will be used as-is, be it relative (to current working directory, aka $\{user.dir}) or absolute path, or even network reference (such as on Windows and use of UNC paths).</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For more details on how startup with start.jar works, see <a href="#executing-startjar">Using start.jar: Executing</a></p>
</div>
<div class="sect3">
<h4 id="demo-base">Demo-Base in the Jetty Distribution</h4>
<div class="paragraph">
<p>The Jetty Distribution comes with an example <code>${jetty.base}</code> which enables the various demonstration webapps and server configurations.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ ls -la
total 496
drwxrwxr-x 11 user group 4096 Oct 8 15:23 ./
drwxr-xr-x 14 user group 4096 Oct 8 13:04 ../
drwxrwxr-x 2 user group 4096 Oct 8 06:54 bin/
drwxrwxr-x 6 user group 4096 Oct 8 06:54 demo-base/
drwxrwxr-x 2 user group 4096 Oct 11 15:14 etc/
drwxrwxr-x 11 user group 4096 Oct 8 06:54 lib/
-rw-rw-r-- 1 user group 30012 Sep 30 19:55 license-eplv10-aslv20.html
drwxrwxr-x 2 user group 4096 Oct 8 06:54 logs/
drwxrwxr-x 2 user group 4096 Oct 8 06:54 modules/
-rw-rw-r-- 1 user group 6262 Sep 30 19:55 notice.html
-rw-rw-r-- 1 user group 1249 Sep 30 19:55 README.TXT
drwxrwxr-x 2 user group 4096 Oct 8 06:54 resources/
drwxrwxr-x 2 user group 4096 Oct 8 06:54 start.d/
-rw-rw-r-- 1 user group 1780 Sep 30 19:55 start.ini
-rw-rw-r-- 1 user group 71921 Sep 30 19:55 start.jar
-rw-rw-r-- 1 user group 336468 Sep 30 19:55 VERSION.txt
drwxrwxr-x 2 user group 4096 Oct 8 06:54 webapps/
[jetty-distribution-10.0.0-SNAPSHOT]$ cd demo-base
[demo-base]$ java -jar $JETTY_HOME/start.jar
2013-10-16 09:08:47.800:WARN::main: demo test-realm is deployed. DO NOT USE IN PRODUCTION!
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/jetty-distribution-10.0.0-SNAPSHOT/demo-base/webapps/] at interval 1
2013-10-16 09:08:48.072:WARN::main: async-rest webapp is deployed. DO NOT USE IN PRODUCTION!
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you want to see what the Jetty base looks like without executing Jetty, you can simply list the configuration by using the <code>--list-config</code> command.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[demo-base]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
-----------------
java.home=/usr/lib/jvm/jdk-7u21-x64/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.92-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
user.dir = /home/user/jetty-distribution-10.0.0-SNAPSHOT
user.language = en
user.country = US
Jetty Environment:
-----------------
jetty.home=/home/user/jetty-distribution-10.0.0-SNAPSHOT
jetty.tag.version = master
jetty.base=/home/user/jetty-distribution-10.0.0-SNAPSHOT/demo-base
jetty.version=10.0.0-SNAPSHOT
Config Search Order:
--------------------
&lt;command-line&gt;
${jetty.base} -&gt; /home/user/jetty-distribution-10.0.0-SNAPSHOT/demo-base
${jetty.home} -&gt; /home/user/Desktop/jetty-distribution-10.0.0-SNAPSHOT
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
jetty.base = /home/user/jetty-distribution-10.0.0-SNAPSHOT/demo-base
jetty.home = /home/user/jetty-distribution-10.0.0-SNAPSHOT
Properties:
-----------
demo.realm = etc/realm.properties
https.port = 8443
https.timeout = 30000
jaas.login.conf = etc/login.conf
jetty.dump.start = false
jetty.dump.stop = false
jetty.keymanager.password = OBF:1u2u1wml1z7s1z7a1wnl1u2g
jetty.keystore = etc/keystore
jetty.keystore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
jetty.http.port = 8080
jetty.secure.port = 8443
jetty.truststore = etc/keystore
jetty.truststore.password = OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4
org.eclipse.jetty.websocket.javax = false
threads.max = 200
threads.min = 10
threads.timeout = 60000
Jetty Server Classpath:
-----------------------
Version Information on 42 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-client-10.0.0-SNAPSHOT.jar
1: 1.4.1.v201005082020 | ${jetty.base}/lib/ext/javax.mail.glassfish-1.4.1.v201005082020.jar
2: 10.0.0-SNAPSHOT | ${jetty.base}/lib/ext/test-mock-resources-10.0.0-SNAPSHOT.jar
3: (dir) | ${jetty.home}/resources
4: 3.1.0 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
6: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-http-10.0.0-SNAPSHOT.jar
7: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-continuation-10.0.0-SNAPSHOT.jar
8: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-server-10.0.0-SNAPSHOT.jar
9: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-xml-10.0.0-SNAPSHOT.jar
10: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-util-10.0.0-SNAPSHOT.jar
11: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-io-10.0.0-SNAPSHOT.jar
12: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-jaas-10.0.0-SNAPSHOT.jar
13: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-jndi-10.0.0-SNAPSHOT.jar
14: 1.1.0.v201105071233 | ${jetty.home}/lib/jndi/javax.activation-1.1.0.v201105071233.jar
15: 1.4.1.v201005082020 | ${jetty.home}/lib/jndi/javax.mail.glassfish-1.4.1.v201005082020.jar
16: 1.3 | ${jetty.home}/lib/jndi/javax.transaction-api-1.3.jar
17: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-rewrite-10.0.0-SNAPSHOT.jar
18: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-security-10.0.0-SNAPSHOT.jar
19: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-servlet-10.0.0-SNAPSHOT.jar
20: 3.0.0 | ${jetty.home}/lib/jsp/javax.el-3.0.0.jar
21: 1.2.0.v201105211821 | ${jetty.home}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
22: 2.3.2 | ${jetty.home}/lib/jsp/javax.servlet.jsp-2.3.2.jar
23: 2.3.1 | ${jetty.home}/lib/jsp/javax.servlet.jsp-api-2.3.1.jar
24: 2.3.3 | ${jetty.home}/lib/jsp/jetty-jsp-jdt-2.3.3.jar
25: 1.2.0.v201112081803 | ${jetty.home}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
26: 3.8.2.v20130121-145325 | ${jetty.home}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
27: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-plus-10.0.0-SNAPSHOT.jar
28: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-webapp-10.0.0-SNAPSHOT.jar
29: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-annotations-10.0.0-SNAPSHOT.jar
30: 4.1 | ${jetty.home}/lib/annotations/asm-4.1.jar
31: 4.1 | ${jetty.home}/lib/annotations/asm-commons-4.1.jar
32: 1.2 | ${jetty.home}/lib/annotations/javax.annotation-api-1.2.jar
33: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-deploy-10.0.0-SNAPSHOT.jar
34: 1.0 | ${jetty.home}/lib/websocket/javax.websocket-api-1.0.jar
35: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-javax-client-10.0.0-SNAPSHOT.jar
36: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-javax-server-10.0.0-SNAPSHOT.jar
37: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-api-10.0.0-SNAPSHOT.jar
38: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-client-10.0.0-SNAPSHOT.jar
39: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-common-10.0.0-SNAPSHOT.jar
40: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-server-10.0.0-SNAPSHOT.jar
41: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-servlet-10.0.0-SNAPSHOT.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-plus.xml
${jetty.home}/etc/jetty-annotations.xml
${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.xml
${jetty.home}/etc/jetty-ssl.xml
${jetty.home}/etc/jetty-ssl-context.xml
${jetty.home}/etc/jetty-https.xml
${jetty.home}/etc/jetty-jaas.xml
${jetty.home}/etc/jetty-rewrite.xml
${jetty.base}/etc/demo-rewrite-rules.xml
${jetty.base}/etc/test-realm.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>--list-config</code> command line option displays what the configuration will look like when starting Jetty.
This includes information on the Java environment to the system properties, the classpath and the Active Jetty IoC XML used to build up the Jetty server configuration.</p>
</div>
<div class="paragraph">
<p>Of note, is that the output will make it known where the configuration elements came from, be it in either in <code>${jetty.home}</code> or <code>${jetty.base}</code>.</p>
</div>
<div class="paragraph">
<p>If you look at the <code>${jetty.base}/start.ini</code> you will see a layout similar to below.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ cat start.ini
# Enable security via jaas, and configure it
--module=jaas
jaas.login.conf=etc/login.conf
# Enable rewrite examples
--module=rewrite
etc/demo-rewrite-rules.xml
# Websocket chat examples needs websocket enabled
# Don't start for all contexts (set to true in test.xml context)
org.eclipse.jetty.websocket.javax=false
--module=websocket
# Create and configure the test realm
etc/test-realm.xml
demo.realm=etc/realm.properties
# Initialize module server
--module=server
threads.min=10
threads.max=200
threads.timeout=60000
jetty.dump.start=false
jetty.dump.stop=false
--module=deploy
--module=jsp
--module=ext
--module=resources
--module=client
--module=annotations</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this example, <code>${jetty.base}/start.ini</code> is the main startup configuration entry point for Jetty.
You will see that we are enabling a few modules for Jetty, specifying some properties, and also referencing some Jetty IoC XML files (namely the <code>etc/demo-rewrite-rules.xml</code> and <code>etc/test-realm.xml</code> files)</p>
</div>
<div class="paragraph">
<p>When Jetty&#8217;s <code>start.jar</code> resolves the entries in the <code>start.ini</code>, it will follow the <a href="#base-vs-home-resolution">resolution rules above</a>.</p>
</div>
<div class="paragraph">
<p>For example, the reference to <code>etc/demo-rewrite-rules.xml</code> was found in <code>${jetty.base}/etc/demo-rewrite-rules.xml</code>.</p>
</div>
</div>
<div class="sect3">
<h4>Declaring Jetty Base</h4>
<div class="paragraph">
<p>The Jetty distribution&#8217;s <code>start.jar</code> is the component that manages the behavior of this separation.</p>
</div>
<div class="paragraph">
<p>The Jetty <code>start.jar</code> and XML files always assume that both <code>${jetty.home}</code> and <code>${jetty.base}</code> are defined when starting Jetty.</p>
</div>
<div class="paragraph">
<p>You can opt to manually define the <code>${jetty.home}</code> and <code>${jetty.base}</code> directories, such as this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ pwd
/home/user/jetty-distribution-10.0.0-SNAPSHOT
[jetty-distribution-10.0.0-SNAPSHOT]$ java -jar start.jar \
jetty.home=/home/user/jetty-distribution-10.0.0-SNAPSHOT \
jetty.base=/home/user/my-base
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternately, you can declare one directory and let the other one be discovered.</p>
</div>
<div class="paragraph">
<p>The following example uses default discovery of <code>${jetty.home}</code> by using the parent directory of wherever <code>start.jar</code> itself is, and a manual declaration of <code>${jetty.base}</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ pwd
/home/user/jetty-distribution-10.0.0-SNAPSHOT
[jetty-distribution-10.0.0-SNAPSHOT]$ java -jar start.jar jetty.base=/home/user/my-base
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>But Jetty recommends that you always start Jetty from the directory that is your <code>${jetty.base}</code> and starting Jetty by referencing
the <code>start.jar</code> in your <code>{$jetty.home}</code> remotely.</p>
</div>
<div class="paragraph">
<p>The following demonstrates this by allowing default discovery of <code>${jetty.home}</code> via locating the <code>start.jar</code>, and using the <code>user.dir</code> System Property for <code>${jetty.base}</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty-distribution-10.0.0-SNAPSHOT]$ pwd
/home/user/jetty-distribution-10.0.0-SNAPSHOT
[jetty-distribution-10.0.0-SNAPSHOT]$ cd /home/user/my-base
[my-base]$ java -jar /home/user/jetty-distribution-10.0.0-SNAPSHOT/start.jar
2013-10-16 09:08:47.802:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2013-10-16 09:08:47.817:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:/home/user/my-base/webapps/] at interval 1
...</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Be aware of the <code>user.dir</code> system property, as it can only be safely set when the JVM starts and many 3rd party libraries (especially logging) use this system property.
It is strongly recommended that you sit in the directory that is your desired <code>${jetty.base}</code> when starting Jetty to have consistent behavior and use of the <code>user.dir</code> system property.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
</div>
<div class="sect2">
<h3 id="startup-classpath">Managing Server Classpath</h3>
<div class="paragraph">
<p>Jetty Server Classpath is determined by a combination of factors.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">The java.class.path System Property</dt>
<dd>
<p>If you start Jetty with a JVM specified classpath, then Jetty will use the java.class.path System Property to populate the initial classpath.</p>
</dd>
<dt class="hdlist1">Module specified Libraries</dt>
<dd>
<p>The module system declares various libraries that are required for that module to operate.
These module defined libraries are added to the Jetty Server classpath when any module is activated with library declarations.</p>
</dd>
<dt class="hdlist1">Command Line Libraries</dt>
<dd>
<p>The command line option <code>--lib=&lt;path&gt;</code> can be used as a final means to add arbitrary entries to the Jetty Server classpath.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Of special note, there are 2 structural modules defined to ease some of this for you.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">--module=ext</dt>
<dd>
<p>The <code>ext</code> module will enable the <code>lib/ext/*.jar</code> logic.
+
If this module is activated, then all jar files found in the lib/ext/ paths will be automatically added to the Jetty Server Classpath.</p>
</dd>
<dt class="hdlist1">--module=resources</dt>
<dd>
<p>The <code>resources</code> module will add the <code>resources/</code> directory the classpath.
+
If you have 3rd party libraries that lookup resources from the classpath, put your files in here.
+
Logging libraries often have classpath lookup of their configuration files (eg: <code>log4j.properties</code>, <code>log4j.xml</code>, <code>logging.properties</code>, and <code>logback.xml</code>), so this would be the ideal setup for this sort of configuration demand.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Both the <code>ext</code> and <code>resources</code> modules declare relative paths that follow <a href="#base-vs-home-resolution">Jetty Base and Jetty Home path resolution rules</a>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect3">
<h4>Interrogating the Server Classpath</h4>
<div class="paragraph">
<p>The Jetty <code>start.jar</code> has the ability to resolve the classpath from the command line, modules and configuration, and to list the classpath entries it will use to start jetty.</p>
</div>
<div class="paragraph">
<p>The <code>--list-classpath</code> command line option is used as such.</p>
</div>
<div class="paragraph">
<p>(Demonstrated with the <a href="#demo-base">demo-base from the Jetty Distribution</a>)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[demo-base]$ java -jar $JETTY_HOME/start.jar --list-classpath
Jetty Server Classpath:
-----------------------
Version Information on 42 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-client-10.0.0-SNAPSHOT.jar
1: 1.4.1.v201005082020 | ${jetty.base}/lib/ext/javax.mail.glassfish-1.4.1.v201005082020.jar
2: 10.0.0-SNAPSHOT | ${jetty.base}/lib/ext/test-mock-resources-10.0.0-SNAPSHOT.jar
3: (dir) | ${jetty.home}/resources
4: 4.0.2 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
6: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-http-10.0.0-SNAPSHOT.jar
7: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-continuation-10.0.0-SNAPSHOT.jar
8: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-server-10.0.0-SNAPSHOT.jar
9: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-xml-10.0.0-SNAPSHOT.jar
10: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-util-10.0.0-SNAPSHOT.jar
11: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-io-10.0.0-SNAPSHOT.jar
12: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-jaas-10.0.0-SNAPSHOT.jar
13: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-jndi-10.0.0-SNAPSHOT.jar
14: 1.1.0.v201105071233 | ${jetty.home}/lib/jndi/javax.activation-1.1.0.v201105071233.jar
15: 1.4.1.v201005082020 | ${jetty.home}/lib/jndi/javax.mail.glassfish-1.4.1.v201005082020.jar
16: 1.3 | ${jetty.home}/lib/jndi/javax.transaction-api-1.3.jar
17: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-rewrite-10.0.0-SNAPSHOT.jar
18: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-security-10.0.0-SNAPSHOT.jar
19: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-servlet-10.0.0-SNAPSHOT.jar
20: 3.0.0 | ${jetty.home}/lib/jsp/javax.el-3.0.0.jar
21: 1.2.0.v201105211821 | ${jetty.home}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
22: 2.3.2 | ${jetty.home}/lib/jsp/javax.servlet.jsp-2.3.2.jar
23: 2.3.1 | ${jetty.home}/lib/jsp/javax.servlet.jsp-api-2.3.1.jar
24: 2.3.3 | ${jetty.home}/lib/jsp/jetty-jsp-jdt-2.3.3.jar
25: 1.2.0.v201112081803 | ${jetty.home}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
26: 3.8.2.v20130121-145325 | ${jetty.home}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
27: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-plus-10.0.0-SNAPSHOT.jar
28: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-webapp-10.0.0-SNAPSHOT.jar
29: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-annotations-10.0.0-SNAPSHOT.jar
30: 4.1 | ${jetty.home}/lib/annotations/asm-4.1.jar
31: 4.1 | ${jetty.home}/lib/annotations/asm-commons-4.1.jar
32: 1.2 | ${jetty.home}/lib/annotations/javax.annotation-api-1.2.jar
33: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-deploy-10.0.0-SNAPSHOT.jar
34: 1.0 | ${jetty.home}/lib/websocket/javax.websocket-api-1.0.jar
35: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-javax-client-10.0.0-SNAPSHOT.jar
36: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-javax-server-10.0.0-SNAPSHOT.jar
37: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-api-10.0.0-SNAPSHOT.jar
38: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-client-10.0.0-SNAPSHOT.jar
39: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-common-10.0.0-SNAPSHOT.jar
40: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-server-10.0.0-SNAPSHOT.jar
41: 10.0.0-SNAPSHOT | ${jetty.home}/lib/websocket/websocket-servlet-10.0.0-SNAPSHOT.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>Of note is that an attempt is made to list the internally declared version of each artifact on the Server Classpath, which can potentially help when diagnosing classpath issues.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="startup-modules">Managing Startup Modules</h3>
<div class="paragraph">
<p>The standard Jetty Distribution ships with several modules defined in <code>${jetty.home}/modules/</code>.
Modules interact with Jetty XML files to configure options and parameters for the server and are the primary configuration method for Jetty distributions.
Modules allow flexibility for implementations and their plug-and-play nature makes adding or removing server functionality virtually painless.</p>
</div>
<div class="sect3">
<h4 id="enabling-modules">Enabling Modules</h4>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The default distribution has a co-mingled <code>${jetty.home}</code> and <code>${jetty.base}</code> where the directories for <code>${jetty.home}</code> and <code>${jetty.base}</code> point to the same location.
It is highly encouraged that you learn about the differences in <a href="#startup-base-and-home">Jetty Base vs Jetty Home</a> and take full advantage of this setup.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Enabling a module is a simple process: simply add the <code>--add-to-start=&lt;module-name1&gt;,&lt;module-name2&gt;,&#8230;&#8203;etc.</code> syntax on the command line.
Doing this will enable the specified module and any dependent modules.</p>
</div>
<div class="paragraph">
<p>An example of this with a new, empty, base directory:</p>
</div>
<div class="paragraph">
<p>If we try to start the Jetty server with no configuration or modules enabled, it will promptly exit:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty]$ mkdir mybase
[jetty]$ cd mybase
[mybase]$ ls -la
total 0
drwxr-xr-x 2 staff staff 68 Jul 12 17:29 .
drwxr-xr-x 20 staff staff 680 Jul 12 17:29 ..
[mybase]$ java -jar $JETTY_HOME/start.jar
WARNING: Nothing to start, exiting ...
Usage: java -jar start.jar [options] [properties] [configs]
java -jar start.jar --help # for more information</code></pre>
</div>
</div>
<div class="paragraph">
<p>By using the <code>--list-config</code> parameter to our startup command, we can see that there are no modules enabled and no Jetty XML files are active:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
-----------------
java.home = /Library/Java/JavaVirtualMachines/jdk1.8.0_92.jdk/Contents/Home/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.92-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
user.dir = /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase
user.language = en
user.country = US
Jetty Environment:
-----------------
jetty.version = 10.0.0-SNAPSHOT
jetty.tag.version = master
jetty.home = /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT
jetty.base = /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase
Config Search Order:
--------------------
&lt;command-line&gt;
${jetty.base} -&gt; /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase
${jetty.home} -&gt; /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
(no system properties specified)
Properties:
-----------
java.version = 1.8.0_92
Jetty Server Classpath:
-----------------------
No classpath entries and/or version information available show.
Jetty Active XMLs:
------------------
(no xml files specified)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Let&#8217;s try adding some basic support for webapps, with automatic deploy (hot deploy), and a single basic HTTP/1.1 connector.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar $JETTY_HOME/start.jar --add-to-start=http,webapp,deploy
INFO : webapp initialized in ${jetty.base}/start.ini
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : security transitively enabled
INFO : servlet transitively enabled
INFO : http initialized in ${jetty.base}/start.ini
INFO : deploy initialized in ${jetty.base}/start.ini
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>This creates the webapps directory in our <code>mybase</code> directory and appended the <code>start.ini</code> file with the ini template arguments from the associated module files.
Additionally, where needed, Jetty enabled any module dependencies.</p>
</div>
<div class="paragraph">
<p>Now that we have added some modules to our server, let&#8217;s run <code>--list-config</code> again to review our new configuration.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar $JETTY_HOME/start.jar --list-config
Java Environment:
-----------------
java.home = /Library/Java/JavaVirtualMachines/jdk1.8.0_92.jdk/Contents/Home/jre
java.vm.vendor = Oracle Corporation
java.vm.version = 25.92-b14
java.vm.name = Java HotSpot(TM) 64-Bit Server VM
java.vm.info = mixed mode
java.runtime.name = Java(TM) SE Runtime Environment
java.runtime.version = 1.8.0_92-b14
java.io.tmpdir = /var/folders/h6/yb_lbnnn11g0y1jjlvqg631h0000gn/T/
user.dir = /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase
user.language = en
user.country = US
Jetty Environment:
-----------------
jetty.version = 10.0.0-SNAPSHOT
jetty.tag.version = master
jetty.home = /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT
jetty.base = /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase
Config Search Order:
--------------------
&lt;command-line&gt;
${jetty.base} -&gt; /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase
${jetty.home} -&gt; /Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT
JVM Arguments:
--------------
(no jvm args specified)
System Properties:
------------------
(no system properties specified)
Properties:
-----------
java.version = 1.8.0_92
Jetty Server Classpath:
-----------------------
Version Information on 11 entries in the classpath.
Note: order presented here is how they would appear on the classpath.
changes to the --module=name command line options will be reflected here.
0: 3.1.0 | ${jetty.home}/lib/jetty-servlet-api-4.0.2.jar
2: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-http-10.0.0-SNAPSHOT.jar
3: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-server-10.0.0-SNAPSHOT.jar
4: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-xml-10.0.0-SNAPSHOT.jar
5: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-util-10.0.0-SNAPSHOT.jar
6: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-io-10.0.0-SNAPSHOT.jar
7: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-security-10.0.0-SNAPSHOT.jar
8: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-servlet-10.0.0-SNAPSHOT.jar
9: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-webapp-10.0.0-SNAPSHOT.jar
10: 10.0.0-SNAPSHOT | ${jetty.home}/lib/jetty-deploy-10.0.0-SNAPSHOT.jar
Jetty Active XMLs:
------------------
${jetty.home}/etc/jetty.xml
${jetty.home}/etc/jetty-webapp.xml
${jetty.home}/etc/jetty-deploy.xml
${jetty.home}/etc/jetty-http.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>You now have a configured and functional server, albeit with no webapps deployed.
At this point you can place a webapp (war file) in the <code>mybase/webapps/</code> directory and and start Jetty.</p>
</div>
</div>
<div class="sect3">
<h4 id="start-vs-startd">Start.ini vs. Start.d</h4>
<div class="paragraph">
<p>In the above example, when a module is activated the contents of that module file are added in <code>${jetty.base}/start.ini</code>.
As additional modules are added, their contents are appended to this file.
This can be beneficial if you want all of your module configurations in a single file, but for large server instances with lots of modules it can pose a challenge to quickly find and make changes or to remove a module.</p>
</div>
<div class="paragraph">
<p>As an alternative to a single <code>start.ini</code> file you can opt to house modules in a <code>${jetty.base}/start.d</code> directory.
Modules activated when a <code>start.d</code> directory exists will be stored as a single file per module.
Below is an example of a fresh <code>${jetty.base}</code> that will create a <code>start.d</code> directory and activate several modules.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jetty.home]$ mkdir mybase
[jetty.home]$ cd mybase/
[mybase]$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
[mybase]$ ls -all
total 0
drwxr-xr-x 3 staff staff 102 Aug 29 15:16 .
drwxr-xr-x@ 26 staff staff 884 Aug 29 15:16 ..
drwxr-xr-x 6 staff staff 204 Aug 29 15:19 start.d
[mybase]$ java -jar ../start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.d/webapp.ini
INFO : server initialised in ${jetty.base}/start.d/server.ini
INFO : websocket initialised in ${jetty.base}/start.d/websocket.ini
INFO : client initialised in ${jetty.base}/start.d/client.ini
INFO : Base directory was modified
[mybase]$ cd start.d/
[mybase]$ ls -all
total 32
drwxr-xr-x 6 staff staff 204 Aug 29 15:19 .
drwxr-xr-x 3 staff staff 102 Aug 29 15:16 ..
-rw-r--r-- 1 staff staff 175 Aug 29 15:19 client.ini
-rw-r--r-- 1 staff staff 2250 Aug 29 15:19 server.ini
-rw-r--r-- 1 staff staff 265 Aug 29 15:19 webapp.ini
-rw-r--r-- 1 staff staff 177 Aug 29 15:19 websocket.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the example, we first create a new <code>${jetty.base}</code> and then create the <code>start.d</code> directory with the <code>--create-startd</code> command.
Next, we use the <code>--add-to-start</code> command which activates the modules and creates their respective ini files in the <code>start.d</code> directory.</p>
</div>
<div class="paragraph">
<p>If you have an existing <code>start.ini</code> file but would like to use the <code>start.d</code> structure for additional modules, you can use the <code>--create-startd</code> command as well.
Doing this will create the <code>start.d</code> directory and copy your existing <code>start.ini</code> file in to it.
Any new modules added to the server will have their own <code>&lt;module name&gt;.ini</code> file created in the <code>start.d</code> directory.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar ../start.jar --add-to-start=server,client,webapp,websocket
INFO : webapp initialised in ${jetty.base}/start.ini
INFO : server initialised in ${jetty.base}/start.ini
INFO : websocket initialised in ${jetty.base}/start.ini
INFO : client initialised in ${jetty.base}/start.ini
INFO : Base directory was modified
[mybase]$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
[mybase]$ tree
.
└── start.d
└── start.ini
[mybase]$ java -jar ../start.jar --add-to-start=ssl
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini
INFO : Base directory was modified
[mybase]$ tree
.
├── etc
│   └── keystore
└── start.d
├── ssl.ini
└── start.ini</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>It is <strong>not</strong> recommended to use both a <code>${jetty.base}/start.ini</code> file and a <code>${jetty.base}/start.d</code> directory at the same time and doing so can cause issues.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="startup-configuring-modules">Configuring Modules</h4>
<div class="paragraph">
<p>Once a module has been enabled for the server, it can be further configured to meet your needs.
This is done by editing the associated ini file for the module.
If your server setup is using a centralized ini configuration, you will edit the <code>${jetty.base}/server.ini</code> file.
If you have elected to manage each module within it&#8217;s own ini file, you can find these files in the <code>${jetty.base}/start.d</code> directory.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
It is important that you <strong>do not</strong> modify the module files in the <code>$JETTY_HOME/modules</code> directory.
$JETTY_HOME should always remain a standard of truth.
If you want to make a change to an actual module file (not the values in its <code>ini-template</code>), either edit its associated <code>ini</code> file in the <code>$JETTY_BASE/start.d</code> directory or make a copy of the desired module file and copy it to the <code>$JETTY_BASE</code> directory and edit it there.
The start.jar reads local <code>$JETTY_BASE/modules</code> files (if they exist) before scanning <code>$JETTY_HOME</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>When a module is activated, a number of properties are set by default.
To view these defaults, open up the associated ini file.
Listed in the ini file is the associated module file and any properties that can be set.</p>
</div>
<div class="paragraph">
<p>Below is an example of the <code>requestlog.ini</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: requestlog
--module=requestlog
## Logging directory (relative to $jetty.base)
# jetty.requestlog.dir=logs
## File path
# jetty.requestlog.filePath=${jetty.requestlog.dir}/yyyy_mm_dd.request.log
## Date format for rollovered files (uses SimpleDateFormat syntax)
# jetty.requestlog.filenameDateFormat=yyyy_MM_dd
## How many days to retain old log files
# jetty.requestlog.retainDays=90
## Whether to append to existing file
# jetty.requestlog.append=true
## Whether to use the extended log output
# jetty.requestlog.extended=true
## Whether to log http cookie information
# jetty.requestlog.cookies=true
## Timezone of the log entries
# jetty.requestlog.timezone=GMT
## Whether to log LogLatency
# jetty.requestlog.loglatency=false</code></pre>
</div>
</div>
<div class="paragraph">
<p>The first lines name the module file being called (located in <code>{$jetty.home/modules}</code>).
Subsequent lines list properties that can be changed as well as a description for each property.
To edit a property, first un-comment the line by deleting the <code>#</code> at the start of the line, then make the change after <code>=</code> sign (such as changing a <code>true</code> value to <code>false</code>).</p>
</div>
</div>
<div class="sect3">
<h4 id="startup-disable-module">Disabling Modules</h4>
<div class="paragraph">
<p>Disabling a module is an easy process.
To disable a module, comment out the <code>--module=</code> line in the associated ini file.
Deleting the ini file associated with module is another option, but may not be practical in all situations.</p>
</div>
</div>
<div class="sect3">
<h4 id="startup-listing-modules">Listing Available and Active Modules</h4>
<div class="paragraph">
<p>To see which modules are <em>available</em>, use the <code>--list-modules</code> command line argument.
This command will also show you which modules are <em>enabled</em>.
Modules are sorted by the value in the <code>[tags]</code> section of the associated <code>.mod</code> file.
If there are multiple entries in the <code>[tags]</code> section, it sorts by the first tag in the list.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
By default, the <code>--list-modules</code> command line argument shows all modules that do not include <code>internal</code> in the <code>[tags]</code> section of the associated <code>.mod</code> file.
If you would like to see <strong>all</strong> modules, use <code>--list-all-modules</code>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Here&#8217;s an example of the <code>--list-modules</code> command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar ../start.jar --list-modules
Available Modules:
==================
tags: [-internal]
Modules for tag '*':
--------------------
Module: alpn
: Enables the ALPN (Application Layer Protocol Negotiation) TLS extension.
Depend: ssl, alpn-impl
LIB: lib/jetty-alpn-client-${jetty.version}.jar
LIB: lib/jetty-alpn-server-${jetty.version}.jar
XML: etc/jetty-alpn.xml
Module: alpn-impl
: Selects an ALPN (Application Layer Protocol Negotiation) implementation by java version.
Depend: alpn-impl/alpn-${java.version.platform}
Module: annotations
: Enables Annotation scanning for deployed webapplications.
Depend: plus
LIB: lib/jetty-annotations-${jetty.version}.jar
LIB: lib/annotations/*.jar
XML: etc/jetty-annotations.xml
Enabled: ${jetty.base}\start.d\annotations.ini
Module: apache-jsp
: Enables use of the apache implementation of JSP
LIB: lib/apache-jsp/*.jar
Enabled: transitive provider of apache-jsp for jsp
Module: apache-jstl
: Enables the apache version of JSTL
LIB: lib/apache-jstl/*.jar
Enabled: transitive provider of apache-jstl for jstl
Module: cdi2
: Jetty setup to support Weld/CDI2 with WELD inside the webapp
Depend: deploy
XML: etc/cdi2/jetty-cdi2.xml
Module: client
: Adds the Jetty HTTP client to the server classpath.
LIB: lib/jetty-client-${jetty.version}.jar
Enabled: ${jetty.base}\start.d\client.ini
Module: continuation
: Enables support for Continuation style asynchronous
: Servlets. Now deprecated in favour of Servlet 3.1
: API
LIB: lib/jetty-continuation-${jetty.version}.jar
Enabled: ${jetty.base}\start.d\continuation.ini
Module: deploy
: Enables webapplication deployment from the webapps directory.
Depend: webapp
LIB: lib/jetty-deploy-${jetty.version}.jar
XML: etc/jetty-deploy.xml
Enabled: ${jetty.base}\start.d\deploy.ini
Module: fcgi
: Adds the FastCGI implementation to the classpath.
Depend: servlet, client
LIB: lib/jetty-proxy-${jetty.version}.jar
LIB: lib/fcgi/*.jar
Module: flight-recorder
Depend: server
JVM: -XX:+UnlockCommercialFeatures
JVM: -XX:+FlightRecorder
Module: global-webapp-common
: Enables Deployer to apply common configuration to all webapp deployments
Depend: deploy
XML: etc/global-webapp-common.xml
Module: hazelcast-embedded-sessions
Depend: annotations, webapp
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/default.xml
Module: hazelcast-remote-sessions
Depend: annotations, webapp
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/remote.xml
Module: home-base-warning
: Generates a warning that server has been run from $JETTY_HOME
: rather than from a $JETTY_BASE.
XML: etc/home-base-warning.xml
Module: jaas
: Enable JAAS for deployed webapplications.
Depend: server
LIB: lib/jetty-jaas-${jetty.version}.jar
XML: etc/jetty-jaas.xml
Enabled: ${jetty.base}\start.d\demo.ini
Module: jaspi
: Enable JASPI authentication for deployed webapplications.
Depend: security
LIB: lib/jetty-jaspi-${jetty.version}.jar
LIB: lib/jaspi/*.jar
Module: jmx
: Enables JMX instrumentation for server beans and
: enables JMX agent.
Depend: server
LIB: lib/jetty-jmx-${jetty.version}.jar
XML: etc/jetty-jmx.xml
Module: jmx-remote
: Enables remote RMI access to JMX
Depend: jmx
XML: etc/jetty-jmx-remote.xml
Module: jndi
: Adds the Jetty JNDI implementation to the classpath.
Depend: server, mail
LIB: lib/jetty-jndi-${jetty.version}.jar
LIB: lib/jndi/*.jar
Enabled: ${jetty.base}\start.d\jndi.ini
Module: jsp
: Enables JSP for all webapplications deployed on the server.
Depend: servlet, annotations, apache-jsp
Enabled: ${jetty.base}\start.d\jsp.ini
Module: jstl
: Enables JSTL for all webapplications deployed on the server
Depend: jsp, apache-jstl
Enabled: ${jetty.base}\start.d\jstl.ini
Module: jvm
: A noop module that creates an ini template useful for
: setting JVM arguments (eg -Xmx )
Module: lowresources
: Enables a low resource monitor on the server
: that can take actions if threads and/or connections
: cross configured threshholds.
Depend: server
XML: etc/jetty-lowresources.xml
Module: mail
: Adds the javax.mail implementation to the classpath.
LIB: lib/mail/*.jar
Enabled: transitive provider of mail for jndi
Module: plus
: Enables JNDI and resource injection for webapplications
: and other servlet 3.x features not supported in the core
: jetty webapps module.
Depend: server, security, jndi, webapp, transactions
LIB: lib/jetty-plus-${jetty.version}.jar
XML: etc/jetty-plus.xml
Enabled: transitive provider of plus for annotations
Module: proxy
: Enable the Jetty Proxy, that allows the server to act
: as a non-transparent proxy for browsers.
Depend: servlet, client
LIB: lib/jetty-proxy-${jetty.version}.jar
XML: etc/jetty-proxy.xml
Module: proxy-protocol
: Enables the Proxy Protocol on the HTTP Connector.
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows a proxy operating in TCP mode to
: transport details of the proxied connection to
: the server.
: Both V1 and V2 versions of the protocol are supported.
Depend: http
XML: etc/jetty-proxy-protocol.xml
Module: quickstart
: Enables the Jetty Quickstart module for rapid
: deployment of preconfigured webapplications.
Depend: server, plus, annotations
LIB: lib/jetty-quickstart-${jetty.version}.jar
Module: rewrite
: Enables the jetty-rewrite handler. Specific rewrite
: rules must be added to either to etc/jetty-rewrite.xml or a custom xml/module
Depend: server
LIB: lib/jetty-rewrite-${jetty.version}.jar
XML: etc/jetty-rewrite.xml
Enabled: ${jetty.base}\start.d\demo.ini
Module: rewrite-compactpath
: Add a rule to the rewrite module to compact paths so that double slashes
: in the path are treated as a single slash.
Depend: rewrite
XML: etc/rewrite-compactpath.xml
Module: rewrite-customizer [rewrite]
: Enables a rewrite Rules container as a request customizer on
: the servers default HttpConfiguration instance
Depend: server
LIB: lib/jetty-rewrite-${jetty.version}.jar
XML: etc/jetty-rewrite-customizer.xml
Module: security
: Adds servlet standard security handling to the classpath.
Depend: server
LIB: lib/jetty-security-${jetty.version}.jar
Enabled: transitive provider of security for webapp
Enabled: transitive provider of security for plus
Module: server
: Enables the core Jetty server on the classpath.
Depend: threadpool
Optional: jvm, ext, resources, logging
LIB: lib/jetty-servlet-api-4.0.2.jar
LIB: lib/jetty-http-${jetty.version}.jar
LIB: lib/jetty-server-${jetty.version}.jar
LIB: lib/jetty-xml-${jetty.version}.jar
LIB: lib/jetty-util-${jetty.version}.jar
LIB: lib/jetty-io-${jetty.version}.jar
XML: etc/jetty.xml
Enabled: ${jetty.base}\start.d\server.ini
Module: servlet
: Enables standard Servlet handling.
Depend: server
LIB: lib/jetty-servlet-${jetty.version}.jar
Enabled: transitive provider of servlet for webapp
Enabled: transitive provider of servlet for servlets
Enabled: transitive provider of servlet for jsp
Module: servlets
: Puts a collection of jetty utility servlets and filters
: on the server classpath (CGI, CrossOriginFilter, DosFilter,
: MultiPartFilter, PushCacheFilter, QoSFilter, etc.) for
: use by all webapplications.
Depend: servlet
LIB: lib/jetty-servlets-${jetty.version}.jar
Enabled: ${jetty.base}\start.d\servlets.ini
Module: setuid
: Enables the unix setUID configuration so that the server
: may be started as root to open privileged ports/files before
: changing to a restricted user (eg jetty).
Depend: server
LIB: lib/setuid/jetty-setuid-java-1.0.3.jar
XML: etc/jetty-setuid.xml
Module: spring
: Enable spring configuration processing so all jetty style
: xml files can optionally be written as spring beans
Depend: server
LIB: lib/spring/*.jar
Module: stop
: This module causes jetty to stop immediately after starting. This is good for testing configuration and/or precompiling quickstart webapps
XML: etc/jetty-stop.xml
Module: threadpool
: Enables the Server thread pool.
XML: etc/jetty-threadpool.xml
Enabled: ${jetty.base}\start.d\threadpool.ini
Module: transactions
: Puts javax.transaction api on the classpath
LIB: lib/transactions/*.jar
Enabled: transitive provider of transactions for plus
Module: webapp
: Adds support for servlet specification webapplication to the server
: classpath. Without this, only Jetty specific handlers may be deployed.
Depend: servlet, security
LIB: lib/jetty-webapp-${jetty.version}.jar
XML: etc/jetty-webapp.xml
Enabled: transitive provider of webapp for plus
Enabled: transitive provider of webapp for deploy
Module: websocket
: Enable websockets for deployed web applications
Depend: client, annotations
LIB: lib/websocket/*.jar
Enabled: ${jetty.base}\start.d\demo.ini
Modules for tag '3rdparty':
---------------------------
Module: conscrypt [alpn-impl]
: Installs the Conscrypt JSSE provider
Tags: 3rdparty
Depend: ssl
LIB: lib/conscrypt/**.jar
LIB: lib/jetty-alpn-conscrypt-server-${jetty.version}.jar
XML: etc/conscrypt.xml
Module: gcloud
: Control GCloud API classpath
Tags: 3rdparty, gcloud
LIB: lib/gcloud/*.jar
Module: gcloud-datastore
: Enables GCloud Datastore API and implementation
Tags: 3rdparty, gcloud
Depend: gcloud, jcl-slf4j, jul-impl
Module: hawtio
: Deploys the Hawtio console as a webapplication.
Tags: 3rdparty
Depend: stats, deploy, jmx
XML: etc/hawtio.xml
Module: jamon
: Deploys the JAMon webapplication
Tags: 3rdparty
Depend: stats, deploy, jmx, jsp
LIB: lib/jamon/**.jar
XML: etc/jamon.xml
Module: jminix
: Deploys the Jminix JMX Console within the server
Tags: 3rdparty
Depend: stats, jmx, jcl-api, jcl-impl
LIB: lib/jminix/**.jar
XML: etc/jminix.xml
Module: jolokia
: Deploys the Jolokia console as a web application.
Tags: 3rdparty
Depend: stats, deploy, jmx
XML: etc/jolokia.xml
Modules for tag 'classpath':
----------------------------
Module: ext
: Adds all jar files discovered in $JETTY_HOME/lib/ext
: and $JETTY_BASE/lib/ext to the servers classpath.
Tags: classpath
LIB: lib/ext/**.jar
Enabled: ${jetty.base}\start.d\ext.ini
Module: resources
: Adds the $JETTY_HOME/resources and/or $JETTY_BASE/resources
: directory to the server classpath. Useful for configuration
: property files (eg jetty-logging.properties)
Tags: classpath
LIB: resources/
Enabled: ${jetty.base}\start.d\resources.ini
Modules for tag 'connector':
----------------------------
Module: acceptratelimit
: Enable a server wide accept rate limit
Tags: connector
Depend: server
XML: etc/jetty-acceptratelimit.xml
Module: connectionlimit
: Enable a server wide connection limit
Tags: connector
Depend: server
XML: etc/jetty-connectionlimit.xml
Module: http
: Enables a HTTP connector on the server.
: By default HTTP/1 is support, but HTTP2C can
: be added to the connector with the http2c module.
Tags: connector, http
Depend: server
XML: etc/jetty-http.xml
Enabled: ${jetty.base}\start.d\http.ini
Module: http-forwarded
: Adds a forwarded request customizer to the HTTP Connector
: to process forwarded-for style headers from a proxy.
Tags: connector
Depend: http
XML: etc/jetty-http-forwarded.xml
Module: http2
: Enables HTTP2 protocol support on the TLS(SSL) Connector,
: using the ALPN extension to select which protocol to use.
Tags: connector, http2, http, ssl
Depend: ssl, alpn
LIB: lib/http2/*.jar
XML: etc/jetty-http2.xml
Module: http2c
: Enables the HTTP2C protocol on the HTTP Connector
: The connector will accept both HTTP/1 and HTTP/2 connections.
Tags: connector, http2, http
Depend: http
LIB: lib/http2/*.jar
XML: etc/jetty-http2c.xml
Module: https
: Adds HTTPS protocol support to the TLS(SSL) Connector
Tags: connector, https, http, ssl
Depend: ssl
Optional: http-forwarded, http2
XML: etc/jetty-https.xml
Enabled: ${jetty.base}\start.d\https.ini
Module: proxy-protocol-ssl
: Enables the Proxy Protocol on the TLS(SSL) Connector.
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows a Proxy operating in TCP mode to transport
: details of the proxied connection to the server.
: Both V1 and V2 versions of the protocol are supported.
Tags: connector, ssl
Depend: ssl
XML: etc/jetty-proxy-protocol-ssl.xml
Module: ssl
: Enables a TLS(SSL) Connector on the server.
: This may be used for HTTPS and/or HTTP2 by enabling
: the associated support modules.
Tags: connector, ssl
Depend: server
XML: etc/jetty-ssl.xml
XML: etc/jetty-ssl-context.xml
Enabled: transitive provider of ssl for https
Module: unixsocket
: Enables a Unix Domain Socket Connector that can receive
: requests from a local proxy and/or SSL offloader (eg haproxy) in either
: HTTP or TCP mode. Unix Domain Sockets are more efficient than
: localhost TCP/IP connections as they reduce data copies, avoid
: needless fragmentation and have better dispatch behaviours.
: When enabled with corresponding support modules, the connector can
: accept HTTP, HTTPS or HTTP2C traffic.
Tags: connector
Depend: server
LIB: lib/jetty-unixsocket-${jetty.version}.jar
LIB: lib/jnr/*.jar
XML: etc/jetty-unixsocket.xml
Module: unixsocket-forwarded
: Adds a forwarded request customizer to the HTTP configuration used
: by the Unix Domain Socket connector, for use when behind a proxy operating
: in HTTP mode that adds forwarded-for style HTTP headers. Typically this
: is an alternate to the Proxy Protocol used mostly for TCP mode.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-forwarded.xml
Module: unixsocket-http
: Adds a HTTP protocol support to the Unix Domain Socket connector.
: It should be used when a proxy is forwarding either HTTP or decrypted
: HTTPS traffic to the connector and may be used with the
: unix-socket-http2c modules to upgrade to HTTP/2.
Tags: connector, http
Depend: unixsocket
XML: etc/jetty-unixsocket-http.xml
Module: unixsocket-http2c
: Adds a HTTP2C connetion factory to the Unix Domain Socket Connector
: It can be used when either the proxy forwards direct
: HTTP/2C (unecrypted) or decrypted HTTP/2 traffic.
Tags: connector, http2
Depend: unixsocket-http
LIB: lib/http2/*.jar
XML: etc/jetty-unixsocket-http2c.xml
Module: unixsocket-proxy-protocol
: Enables the proxy protocol on the Unix Domain Socket Connector
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows information about the proxied connection to be
: efficiently forwarded as the connection is accepted.
: Both V1 and V2 versions of the protocol are supported and any
: SSL properties may be interpreted by the unixsocket-secure
: module to indicate secure HTTPS traffic. Typically this
: is an alternate to the forwarded module.
Tags: connector
Depend: unixsocket
XML: etc/jetty-unixsocket-proxy-protocol.xml
Module: unixsocket-secure
: Enable a secure request customizer on the HTTP Configuration
: used by the Unix Domain Socket Connector.
: This looks for a secure scheme transported either by the
: unixsocket-forwarded, unixsocket-proxy-protocol or in a
: HTTP2 request.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml
Modules for tag 'debug':
------------------------
Module: debug
: Enables the DebugListener to generate additional
: logging regarding detailed request handling events.
: Renames threads to include request URI.
Tags: debug
Depend: deploy
XML: etc/jetty-debug.xml
Module: debuglog
: Deprecated Debug Log using the DebugHandle.
: Replaced with the debug module.
Tags: debug
Depend: server
XML: etc/jetty-debuglog.xml
Modules for tag 'handler':
--------------------------
Module: gzip
: Enable GzipHandler for dynamic gzip compression
: for the entire server.
Tags: handler
Depend: server
XML: etc/jetty-gzip.xml
Module: ipaccess
: Enable the ipaccess handler to apply a white/black list
: control of the remote IP of requests.
Tags: handler
Depend: server
XML: etc/jetty-ipaccess.xml
Module: stats
: Enable detailed statistics collection for the server,
: available via JMX.
Tags: handler
Depend: server
XML: etc/jetty-stats.xml
Module: threadlimit
Tags: handler
Depend: server
XML: etc/jetty-threadlimit.xml
Modules for tag 'logging':
--------------------------
Module: console-capture
: Redirects JVMs console stderr and stdout to a log file,
: including output from Jetty's default StdErrLog logging.
Tags: logging
LIB: resources/
XML: etc/console-capture.xml
Module: logging-jetty [logging]
: Configure jetty logging mechanism.
: Provides a ${jetty.base}/resources/jetty-logging.properties.
Tags: logging
Depend: resources
Module: logging-jul [logging]
: Configure jetty logging to use Java Util Logging (jul)
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-jul, jul-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j [logging]
: Configure jetty logging to use Log4j Logging
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-log4j, log4j-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j2 [logging]
: Configure jetty logging to use log4j version 2
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-log4j2, log4j2-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-logback [logging]
: Configure jetty logging to use Logback Logging.
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-logback, logback-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-slf4j [logging]
: Configure jetty logging to use slf4j.
: Any slf4j-impl implementation is used
Tags: logging
Depend: slf4j-api, slf4j-impl
JVM: -Dorg.eclipse.jetty.util.log.class?=org.eclipse.jetty.util.log.Slf4jLog
Modules for tag 'requestlog':
-----------------------------
Module: logback-access [requestlog]
: Enables logback request log.
Tags: requestlog, logging, logback
Depend: server, logback-impl, resources
LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml
Module: requestlog
: Enables a NCSA style request log.
Tags: requestlog
Depend: server
XML: etc/jetty-requestlog.xml
Modules for tag 'session':
--------------------------
Module: session-cache-hash [session-cache]
: Enable first level session cache in ConcurrentHashMap.
: If not enabled, sessions will use a HashSessionCache by default, so enabling
: via this module is only needed if the configuration properties need to be
: changed.
Tags: session
Depend: sessions
XML: etc/sessions/session-cache-hash.xml
Module: session-cache-null [session-cache]
: A trivial SessionCache that does not actually cache sessions.
Tags: session
Depend: sessions
XML: etc/sessions/session-cache-null.xml
Module: session-store-cache
: Enables caching of SessionData in front of a SessionDataStore.
Tags: session
Depend: session-store, sessions/session-data-cache/${session-data-cache}
XML: etc/sessions/session-data-cache/session-caching-store.xml
Module: session-store-file [session-store]
: Enables session persistent storage in files.
Tags: session
Depend: sessions
XML: etc/sessions/file/session-store.xml
Module: session-store-gcloud [session-store]
: Enables GCloudDatastore session management.
Tags: session, gcloud
Depend: gcloud-datastore, annotations, webapp, sessions
LIB: lib/jetty-gcloud-session-manager-${jetty.version}.jar
XML: etc/sessions/gcloud/session-store.xml
Module: session-store-hazelcast-embedded [session-store]
: Enables session data store in an embedded Hazelcast Map
Tags: session
Depend: sessions
LIB: lib/jetty-hazelcast-${jetty.version}.jar
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/default.xml
Module: session-store-hazelcast-remote [session-store]
: Enables session data store in a remote Hazelcast Map
Tags: session
Depend: sessions
LIB: lib/jetty-hazelcast-${jetty.version}.jar
LIB: lib/hazelcast/*.jar
XML: etc/sessions/hazelcast/remote.xml
Module: session-store-infinispan-embedded [session-store-infnispan-embedded, session-store]
: Enables session data store in a local Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/default.xml
Module: session-store-infinispan-embedded-910 [session-store-infinispan-embedded, session-store]
: Enables session data store in a local Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/default.xml
Module: session-store-infinispan-remote [session-store]
: Enables session data store in a remote Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/remote.xml
Module: session-store-infinispan-remote-910 [session-store-infinispan-remote, session-store]
: Enables session data store in a remote Infinispan cache
Tags: session
Depend: sessions
LIB: lib/jetty-infinispan-${jetty.version}.jar
LIB: lib/infinispan/*.jar
XML: etc/sessions/infinispan/remote.xml
Module: session-store-jdbc [session-store]
: Enables JDBC persistent/distributed session storage.
Tags: session
Depend: sessions, sessions/jdbc/${db-connection-type}
XML: etc/sessions/jdbc/session-store.xml
Module: session-store-mongo [session-store]
: Enables NoSql session management with a MongoDB driver.
Tags: session
Depend: sessions, sessions/mongo/${connection-type}
LIB: lib/jetty-nosql-${jetty.version}.jar
LIB: lib/nosql/*.jar
Module: sessions
: The session management. By enabling this module, it allows
: session management to be configured via the ini templates
: created or by enabling other session-cache or session-store
: modules. Without this module enabled, the server may still
: use sessions, but their management cannot be configured.
Tags: session
Depend: server
XML: etc/sessions/id-manager.xml</code></pre>
</div>
</div>
<div class="sect4">
<h5>Searching Modules</h5>
<div class="paragraph">
<p>Since the introduction of the module system, many new modules have been added.
As a result, looking at the module list as a whole can be somewhat overwhelming.
To narrow down which modules you would like to choose from, you can search by values listed under the <code>[tags]</code> section.
Note that when you search this way, all modules that include your criteria in it&#8217;s <code>[tags]</code> section, including internal modules, will be shown.
To filter out internal modules when searching a specific module tag, simply add <code>-internal</code> to the command line.
For example, if you wanted to look at only the logging modules (excluding the internal implementation modules), you would use <code>--list-modules=logging,-internal</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=logging,-internal
Available Modules:
==================
tags: [logging, -internal]
Modules for tag 'logging':
--------------------------
Module: console-capture
: Redirects JVMs console stderr and stdout to a log file,
: including output from Jetty's default StdErrLog logging.
Tags: logging
LIB: resources/
XML: etc/console-capture.xml
Module: logging-jcl [logging]
: Configure jetty logging to use Java Commons Logging (jcl)
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: jcl-impl, slf4j-jcl
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-jetty [logging]
: Configure jetty logging mechanism.
: Provides a ${jetty.base}/resources/jetty-logging.properties.
Tags: logging
Depend: console-capture, resources
Module: logging-jul [logging]
: Configure jetty logging to use Java Util Logging (jul)
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: jul-impl, slf4j-jul
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j [logging]
: Configure jetty logging to use Log4j Logging
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: log4j-impl, slf4j-log4j
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-log4j2 [logging]
: Configure jetty logging to use log4j version 2
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: slf4j-log4j2, log4j2-impl
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-logback [logging]
: Configure jetty logging to use Logback Logging.
: SLF4J is used as the core logging mechanism.
Tags: logging
Depend: logback-impl, slf4j-logback
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Module: logging-slf4j [logging]
: Configure jetty logging to use slf4j.
: Any slf4j-impl implementation is used
Tags: logging
Depend: slf4j-api, slf4j-impl
JVM: -Dorg.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.Slf4jLog
Modules for tag 'requestlog':
-----------------------------
Module: logback-access [requestlog]
: Enables logback request log.
Tags: requestlog, logging, logback
Depend: server, logback-core, resources
LIB: lib/logback/logback-access-${logback.version}.jar
XML: etc/jetty-logback-access.xml</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="custom-modules">Custom Modules</h3>
<div class="paragraph">
<p>In addition to the modules that come packaged with the Jetty distribution, users are able to create and define their own custom modules for use with their Jetty implementation.
Custom modules can be used for a number of reasons - they can extend features in Jetty, add new features, manage additional libraries available to the server&#8230;&#8203;etc.</p>
</div>
<div class="paragraph">
<p>At the heart of a Jetty module is the <code>{name}.mod</code> file itself.
A jetty <code>.mod</code> file defines the following:</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>It is important to note that when creating your own module, none of these sections are required - simply use those which are applicable to your implementation.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Module Description - <code>[description]</code></dt>
<dd>
<p>The description of the module.
This will be showing when viewing the <code>.mod</code> file itself or using the <code>--list-modules</code> command.</p>
</dd>
<dt class="hdlist1">List of Dependent Modules - <code>[depend]</code></dt>
<dd>
<p>All modules can declare that they depend on other modules with the <code>[depend]</code> section.
The list of dependencies is used to transitively resolve other modules that are deemed to be required based on the modules that you activate.
The order of modules defined in the graph of active modules is used to determine various execution order for configuration, such as Jetty IoC XML configurations, and to resolve conflicting property declarations.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">Optional Modules - <code>[optional]</code></dt>
<dd>
<p>Of note: there is a special section <code>[optional]</code> used to describe structurally dependent modules that are not technically required, but might be of use to your specific configuration.</p>
</dd>
</dl>
</div>
</dd>
<dt class="hdlist1">List of Libraries - <code>[lib]</code></dt>
<dd>
<p>Modules can optionally declare that they have libraries that they need to function properly.
The <code>[lib]</code> section declares a set of pathnames that follow the <a href="#base-vs-home-resolution">Jetty Base and Jetty Home path resolution rules</a>.</p>
</dd>
<dt class="hdlist1">List of Jetty IoC XML Configurations - <code>[xml]</code></dt>
<dd>
<p>A Module can optionally declare a list of Jetty IoC XML configurations used to wire up the functionality that this module defines.
The <code>[xml]</code> section declares a set of pathnames that follow the <a href="#base-vs-home-resolution">Jetty Base and Jetty Home path resolution rules</a>.
Ideally, all XML files are parameterized to accept properties to configure the various elements of the standard configuration.
Allowing for a simplified configuration of Jetty for the vast majority of deployments.
The execution order of the Jetty IoC XML configurations is determined by the graph of active module dependencies resolved via the <code>[depend]</code> sections.
If the default XML is not sufficient to satisfy your needs, you can override this XML by making your own in the <code>${jetty.base}/etc/</code> directory, with the same name.
The resolution steps for Jetty Base and Jetty Home will ensure that your copy from <code>${jetty.base}</code> will be picked up over the default one in <code>${jetty.home}</code>.</p>
</dd>
<dt class="hdlist1">List of Module Tags - <code>[tags]</code></dt>
<dd>
<p>For ease of sorting, modules can be assigned tags.
When using the <code>--list-modules</code> command, modules will be groups by the first tag that exists in this section.
Modules can also be listed specifically by these tags using <code>--list-modules=&lt;tag name&gt;</code> on the command line.</p>
</dd>
<dt class="hdlist1">Ini Variables - <code>[ini]</code></dt>
<dd>
<p>The <code>[ini]</code> section is used to add or change server parameters at startup.
The <code>[ini]</code> section can also include a the path of a file or several files which should be made available to the server only.
This is helpful when you want to control what jars are available to deployed webapps.</p>
</dd>
<dt class="hdlist1">Jetty INI Template - <code>[ini-template]</code></dt>
<dd>
<p>Each module can optionally declare a startup ini template that is used to insert/append/inject sample configuration elements into the <code>start.ini</code> or <code>start.d/*.ini</code> files when using the <code>--add-to-start=&lt;name&gt;</code> command line argument in <code>start.jar</code>.
Commonly used to present some of the parameterized property options from the Jetty IoC XML configuration files also referenced in the same module.</p>
</dd>
<dt class="hdlist1">Required Files and Directories - <code>[files]</code></dt>
<dd>
<p>If the activation of a module requires some paths to exist, the <code>[files]</code> section defines them.
There are 2 modes of operation of the entries in this section.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">Ensure Directory Exists</dt>
<dd>
<p>If you add a pathname that ends in <code>"/"</code> (slash), such as <code>"webapps/"</code>, then that directory will be created if it does not yet exist in <code>${jetty.base}/&lt;pathname&gt;</code> (eg: <code>"webapps/"</code> will result in <code>${jetty.base}/webapps/</code> being created).</p>
</dd>
<dt class="hdlist1">Download File</dt>
<dd>
<p>There is a special syntax to allow you to download a file into a specific location if it doesn&#8217;t exist yet: <code>&lt;url&gt;:&lt;pathname&gt;</code>.
Currently, the <code>&lt;url&gt;</code> must be a <code>http://</code> scheme URL (please <a href="#bugs">let us know</a> if you need more schemes supported).
The <code>&lt;pathname&gt;</code> portion follows the <a href="#base-vs-home-resolution">Jetty Base and Jetty Home path resolution rules</a>.
Example: <code><a href="http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar" class="bare">http://repo.corp.com/maven/corp-security-policy-1.0.jar:lib/corp-security-policy.jar</a></code>
This will check for the existence of <code>lib/corp-security-policy.jar</code>, and if it doesn&#8217;t exist, it will download the jar file from <code><a href="http://repo.corp.com/maven/corp-security-policy-1.0.jar" class="bare">http://repo.corp.com/maven/corp-security-policy-1.0.jar</a></code></p>
</dd>
</dl>
</div>
</dd>
<dt class="hdlist1">Licenses - <code>[license]</code></dt>
<dd>
<p>If you are implementing a software/technology that has a license, it&#8217;s text can be placed here.
When a user attempts to activate the module they will be asked if they accept the license agreement.
If a user does not accept the license agreement, the module will not be activated.</p>
</dd>
<dt class="hdlist1">Additional Startup Commands - <code>[exec]</code></dt>
<dd>
<p>The <code>[exec]</code> section is used to define additional parameters specific to the module.
These commands are added to the server startup.</p>
</dd>
<dt class="hdlist1">JPMS Module-Path Definitions - <code>[jpms]</code></dt>
<dd>
<p>The <code>[jpms]</code> section is used to add <a href="#startup-jpms">JPMS modules</a> to the module-path for startup when using the <code>--jpms</code> command.</p>
</dd>
</dl>
</div>
<div class="sect3">
<h4 id="custom-module-properties">Module Properties</h4>
<div class="paragraph">
<p>Properties are used to parameterize:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>XML files using the <code>&lt;Property name="pname"/&gt;</code> element</p>
</li>
<li>
<p>Module files using the <code>${pname}</code> syntax</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Properties and System Properties may be set on the command line, in a ini file or in a <code>[ini]</code> section of a module using the following syntax.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>name=value</code></dt>
<dd>
<p>Set a property that can be expanded in XML files with the &lt;Property&gt; element.</p>
</dd>
<dt class="hdlist1"><code>name+=value</code></dt>
<dd>
<p>Append value to an existing property value.</p>
</dd>
<dt class="hdlist1"><code>name+=,value</code></dt>
<dd>
<p>Append value to an existing property value, using a comma separator if needed.</p>
</dd>
<dt class="hdlist1"><code>name?=value</code></dt>
<dd>
<p>Set a property only if it is not already set.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>If any of the previous formats is preceded by <code>-D</code>, then a system property is set as well as a start property.</p>
</div>
</div>
<div class="sect3">
<h4 id="custom-module-location">Location of Modules</h4>
<div class="paragraph">
<p>Jetty comes with dozens of modules as part of the distribution package.
By default these are located in the <code>${JETTY_HOME}/modules</code> directory.
These modules should not be modified.
In the unlikely circumstance you need to make changes to a stock module, copy it to your <code>${JETTY_BASE}</code> in a <code>modules</code> directory.</p>
</div>
<div class="paragraph">
<p>Custom modules should also be maintained separately as part of the <code>${JETTY_BASE}/modules</code> directory, though you can optionally place them in <code>${JETTY_HOME}/modules</code> for convenience if you have several <code>{$JETTY_BASE}</code> locations in your implementation.</p>
</div>
</div>
<div class="sect3">
<h4 id="custom-module-examples">Creating Custom Modules</h4>
<div class="paragraph">
<p>As shown above, there are several options that can be utilized when creating custom module files.
This may seem daunting, but the good news is that creating custom modules is actually quite easy.</p>
</div>
<div class="paragraph">
<p>For example, here is a look at the <code>http.mod</code> file which defines parameters for enabling HTTP features for the server:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
[description]
Enables an HTTP connector on the server.
By default HTTP/1 is support, but HTTP2C can
be added to the connector with the http2c module.
[tags]
connector
http
[depend]
server
[xml]
etc/jetty-http.xml
[ini-template]
### HTTP Connector Configuration
## Connector host/address to bind to
# jetty.http.host=0.0.0.0
## Connector port to listen on
# jetty.http.port=8080
## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000
## Number of acceptors (-1 picks default based on number of cores)
# jetty.http.acceptors=-1
## Number of selectors (-1 picks default based on number of cores)
# jetty.http.selectors=-1
## ServerSocketChannel backlog (0 picks platform default)
# jetty.http.acceptorQueueSize=0
## Thread priority delta to give to acceptor threads
# jetty.http.acceptorPriorityDelta=0
## Connect Timeout in milliseconds
# jetty.http.connectTimeout=15000</code></pre>
</div>
</div>
<div class="paragraph">
<p>You&#8217;ll notice that the <code>http.mod</code> file only includes a handful of the possible sections available - <code>[description]</code>, <code>[tags]</code>, <code>[depend]</code>, <code>[xml]</code>, and <code>[ini-template]</code>.
When configuring your own modules, you are free to pick and choose what you include.</p>
</div>
<div class="paragraph">
<p>As an example, below is a module file that defines a custom XML and lib, and activates a number of additional modules.
A module like this could be used to enable a set of standard modules and resources for a new JETTY_BASE without having to define them all manually.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[description]
Enables the standard set of modules and resources for ACME Corp servers.
[tags]
core
[depend]
server
client
http
http2
jsp
console-capture
requestlog
stats
gzip
deploy
jmx
[files]
basehome:modules/acme/acme.xml|etc/acme.xml
[lib]
lib/acme/ACMECustom.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>Activating this module will activate all the dependent modules, create any required directories and copy in any required files:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar ../start.jar --add-to-start=acme
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: alpn-impl/alpn-8
+ ALPN is a hosted at github under the GPL v2 with ClassPath Exception.
+ ALPN replaces/modifies OpenJDK classes in the sun.security.ssl package.
+ http://github.com/jetty-project/jetty-alpn
+ http://openjdk.java.net/legal/gplv2+ce.html
Proceed (y/N)? y
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : requestlog transitively enabled, ini template available with --add-to-start=requestlog
INFO : alpn transitively enabled, ini template available with --add-to-start=alpn
INFO : jsp transitively enabled
INFO : servlet transitively enabled
INFO : alpn-impl/alpn-8 dynamic dependency of alpn
INFO : annotations transitively enabled
INFO : gzip transitively enabled, ini template available with --add-to-start=gzip
INFO : ssl transitively enabled, ini template available with --add-to-start=ssl
INFO : plus transitively enabled
INFO : deploy transitively enabled, ini template available with --add-to-start=deploy
INFO : alpn-impl/alpn-1.8.0_92 dynamic dependency of alpn-impl/alpn-8
INFO : security transitively enabled
INFO : jmx transitively enabled
INFO : apache-jsp transitively enabled
INFO : stats transitively enabled, ini template available with --add-to-start=stats
INFO : acme initialized in ${jetty.base}/start.d/acme.ini
INFO : jndi transitively enabled
INFO : console-capture transitively enabled, ini template available with --add-to-start=console-capture
INFO : client transitively enabled
INFO : http transitively enabled, ini template available with --add-to-start=http
INFO : http2 transitively enabled, ini template available with --add-to-start=http2
MKDIR : ${jetty.base}/logs
MKDIR : ${jetty.base}/lib
MKDIR : ${jetty.base}/lib/alpn
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
MKDIR : ${jetty.base}/webapps
DOWNLD: https://repo1.maven.org/maven2/org/mortbay/jetty/alpn/alpn-boot/8.1.8.v20160420/alpn-boot-8.1.8.v20160420.jar to ${jetty.base}/lib/alpn/alpn-boot-8.1.8.v20160420.jar
COPY : ${jetty.home}/modules/acme/acme.xml to ${jetty.base}/etc/acme.xml
INFO : Base directory was modified</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>Dependencies</h4>
<div class="paragraph">
<p>When dependent modules are enabled, they are done so transitively by default.
This means that any <code>ini</code> files for dependent modules are not created in the <code>${JETTY_BASE}/start.d</code> directory (or added to <code>${JETTY_BASE}/start.ini</code>) and are as such not configurable.</p>
</div>
<div class="paragraph">
<p>For Jetty to create/add the <code>ini-template</code> parameters to <code>start.d</code> or <code>start.ini</code> the associated module must be enabled explicitly.</p>
</div>
<div class="paragraph">
<p>For example, if I activate the <code>http</code> module, it will be enabled, and the <code>server</code> module will be enabled transitively:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --add-to-start=http
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : http initialized in ${jetty.base}/start.d/http.ini
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>You&#8217;ll notice that Jetty informs you of what modules were enabled, and where there associated ini files are located (when applicable).
It also tells the user what command they would need to run to enable any missing or desired ini files for the selected modules, in this case <code>--add-to-start=server</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --add-to-start=server
INFO : server initialized in ${jetty.base}/start.d/server.ini
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
It is important to keep in mind that when activating a dependency, Jetty does not just go one layer down.
If a dependent module also has dependencies they too will be enabled.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
</div>
<div class="sect2">
<h3 id="startup-xml-config">Managing XML Based Startup Configuration</h3>
<div class="paragraph">
<p>When you see XML files on the command line for startup of Jetty, they are always part of the Jetty IoC Configuration mechanism.</p>
</div>
<div class="paragraph">
<p>Internally, Jetty uses these XML files to build up Jetty with the features that you wan to use.</p>
</div>
<div class="paragraph">
<p>The module mechanism present in Jetty determines the load order of the XML files.
The Jetty Base and Jetty Home resolution logic also applies, which allows you to override a XML file declared by a module with your XML by simply having the same named XML in your <code>${jetty.base}/etc</code> directory location.</p>
</div>
</div>
<div class="sect2">
<h3 id="startup-unix-service">Startup a Unix Service using jetty.sh</h3>
<div class="paragraph">
<p>The standalone Jetty distribution ships with a <code>bin/jetty.sh</code> script that can be used by various Unix distros (including OSX) to manage Jetty as a startup service.</p>
</div>
<div class="paragraph">
<p>This script is suitable for setting up Jetty as a service in Unix.</p>
</div>
<div class="sect3">
<h4>Quick-Start a Jetty Service</h4>
<div class="paragraph">
<p>The minimum steps to get Jetty to run as a Service include:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[/opt/jetty]# tar -zxf /home/user/downloads/jetty-distribution-10.0.0-SNAPSHOT.tar.gz
[/opt/jetty]# cd jetty-distribution-10.0.0-SNAPSHOT/
[/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT]# ls
bin lib modules resources start.jar
demo-base license-eplv10-aslv20.html notice.html start.d VERSION.txt
etc logs README.TXT start.ini webapps
[/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT]# cp bin/jetty.sh /etc/init.d/jetty
[/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT]# echo JETTY_HOME=`pwd` &gt; /etc/default/jetty
[/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT]# cat /etc/default/jetty
JETTY_HOME=/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
[/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT]# service jetty start
Starting Jetty: OK Wed Nov 20 10:26:53 MST 2013</code></pre>
</div>
</div>
<div class="paragraph">
<p>From this demonstration we can see that Jetty started successfully as a Unix Service from the <code>/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT</code> directory.</p>
</div>
<div class="paragraph">
<p>This configuration works well but it is running Jetty as the root user.</p>
</div>
</div>
<div class="sect3">
<h4>Practical Setup of a Jetty Service</h4>
<div class="paragraph">
<p>There are various ways this can be accomplished, mostly depending on your Unix environment (and possibly corporate policies).</p>
</div>
<div class="paragraph">
<p>The techniques outlined here assume an installation on Linux (demonstrated on Ubuntu 12.04.3 LTS).</p>
</div>
<div class="paragraph">
<p>Prepare some empty directories to work with.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># mkdir -p /opt/jetty
# mkdir -p /opt/web/mybase
# mkdir -p /opt/jetty/temp</code></pre>
</div>
</div>
<div class="paragraph">
<p>The directory purposes are as follows:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">/opt/jetty</dt>
<dd>
<p>Where the Jetty Distribution will be unpacked into</p>
</dd>
<dt class="hdlist1">/opt/web/mybase</dt>
<dd>
<p>Where your specific set of webapps will be located, including all of the configuration required of the server to make them operational.</p>
</dd>
<dt class="hdlist1">/opt/jetty/temp</dt>
<dd>
<p>This is the temporary directory assigned to Java by the Service Layer (this is what Java sees as the <code>java.io.tmpdir</code> System Property).</p>
<div class="paragraph">
<p>This is intentionally kept separate from the standard temp directory of <code>/tmp</code>, as this location doubles as the Servlet Spec work directory.
It is our experience that the standard temp directory is often managed by various cleanup scripts that wreak havoc on a long running Jetty server.</p>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Jetty 9.3 requires Java 8 (or greater) to run.
Make sure you have it installed.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># apt-get install openjdk-8-jdk</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or download Java 8 from: <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" class="bare">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># java -version
java version "1.6.0_27"
OpenJDK Runtime Environment (IcedTea6 1.12.6) (6b27-1.12.6-1ubuntu0.12.04.2)
OpenJDK 64-Bit Server VM (build 20.0-b12, mixed mode)
# update-alternatives --list java
/usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java
/usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java
# update-alternatives --config java
There are 2 choices for the alternative java (providing /usr/bin/java).
Selection Path Priority Status
------------------------------------------------------------
* 0 /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java 1061 auto mode
1 /usr/lib/jvm/java-6-openjdk-amd64/jre/bin/java 1061 manual mode
2 /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java 1051 manual mode
Press enter to keep the current choice[*], or type selection number: 2
update-alternatives: using /usr/lib/jvm/java-7-openjdk-amd64/jre/bin/java to provide /usr/bin/java (java) in manual mode.
# java -version
java version "1.7.0_25"
OpenJDK Runtime Environment (IcedTea 2.3.10) (7u25-2.3.10-1ubuntu0.12.04.2)
OpenJDK 64-Bit Server VM (build 23.7-b01, mixed mode)</code></pre>
</div>
</div>
<div class="paragraph">
<p>It is recommended that you create a user to specifically run Jetty.
This user should have the minimum set of privileges needed to run Jetty.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># useradd --user-group --shell /bin/false --home-dir /opt/jetty/temp jetty</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will create a user called <code>jetty</code>, belonging to the group called <code>jetty</code>, with no shell access (aka <code>/bin/false</code>), and home directory at <code>/opt/jetty/temp</code>.</p>
</div>
<div class="paragraph">
<p>Download a copy of the Jetty distribution from the <a href="#jetty-downloading">Official Eclipse Download Site</a></p>
</div>
<div class="paragraph">
<p>Unpack it into place.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[/opt/jetty]# tar -zxf /home/user/Downloads/jetty-distribution-10.0.0-SNAPSHOT.tar.gz
[/opt/jetty]# ls -F
jetty-distribution-10.0.0-SNAPSHOT/
[/opt/jetty]# mkdir /opt/jetty/temp</code></pre>
</div>
</div>
<div class="paragraph">
<p>It might seem strange or undesirable to unpack the first portion of the jetty-distribution directory name too.
But starting with Jetty 9 the split between <code>${jetty.home}</code> and <code>${jetty.base}</code> allows for easier upgrades of Jetty itself while isolating your webapp specific configuration.
For more information on the Jetty home and base concepts see the section on managing a Jetty installation <a href="#startup-base-and-home">earlier in this Chapter.</a></p>
</div>
<div class="paragraph">
<p>The <code>/opt/jetty/temp</code> directory is created as a durable place for Jetty to use for temp and working directories.
Many Unix systems will periodically clean out the /tmp directory, this behavior is undesired in a Servlet container and has been known to cause problems.
This durable directory at <code>/opt/jetty/temp</code> solves for that behavior.</p>
</div>
<div class="paragraph">
<p>The directory at <code>/opt/web/mybase</code> is going to be a <code>${jetty.base}</code>, so lets configure it to hold your webapp and its configuration.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>In past versions of Jetty, you would configure / modify / add to the <code>jetty-distribution</code> directory directly.
While this is still supported, we encourage you to setup a proper <code>${jetty.base}</code> directory, as it will benefit you with easier <code>jetty-distribution</code> upgrades in the future.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># cd /opt/web/mybase/
[/opt/web/mybase]# ls
[/opt/web/mybase]# java -jar /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT/start.jar \
--add-to-start=deploy,http,console-capture
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : security transitively enabled
INFO : servlet transitively enabled
INFO : console-capture initialized in ${jetty.base}/start.ini
INFO : http initialized in ${jetty.base}/start.ini
INFO : deploy initialized in ${jetty.base}/start.ini
MKDIR : ${jetty.base}/logs
MKDIR : ${jetty.base}/webapps
INFO : Base directory was modified
[/opt/web/mybase]# ls -F
start.ini webapps/</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point you have configured your <code>/opt/web/mybase</code> to enable the following modules:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">deploy</dt>
<dd>
<p>This is the module that will perform deployment of web applications (WAR files or exploded directories), or Jetty IoC XML context deployables, from the <code>/opt/web/mybase/webapps</code> directory.</p>
</dd>
<dt class="hdlist1">http</dt>
<dd>
<p>This sets up a single Connector that listens for basic HTTP requests.</p>
<div class="paragraph">
<p>See the created <code>start.ini</code> for configuring this connector.</p>
</div>
</dd>
<dt class="hdlist1">console-capture</dt>
<dd>
<p>When running Jetty as a service it is very important to have logging enabled.
This module will enable the basic STDOUT and STDERR capture logging to the <code>/opt/web/mybase/logs/</code> directory.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Additionally, the <code>webapp</code>, <code>server</code>, <code>security</code> and <code>servlet</code> modules were enabled as they are dependencies for other modules.</p>
</div>
<div class="paragraph">
<p>See <a href="#start-jar">Using start.jar</a> for more details and options on setting up and configuring a <code>${jetty.base}</code> directory.</p>
</div>
<div class="paragraph">
<p>Copy your war file into place.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># cp /home/user/projects/mywebsite.war /opt/web/mybase/webapps/</code></pre>
</div>
</div>
<div class="paragraph">
<p>Most service installations will want Jetty to run on port 80, now is the opportunity to change this from the default value of <code>8080</code> to <code>80</code>.</p>
</div>
<div class="paragraph">
<p>Edit the <code>/opt/web/mybase/start.ini</code> and change the <code>jetty.http.port</code> value.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># grep jetty.http.port /opt/web/mybase/start.ini
jetty.port=80</code></pre>
</div>
</div>
<div class="paragraph">
<p>Change the permissions on the Jetty distribution and webapp directories so that the user you created can access it.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># chown --recursive jetty /opt/jetty
# chown --recursive jetty /opt/web/mybase</code></pre>
</div>
</div>
<div class="paragraph">
<p>Next we need to make the Unix System aware that we have a new Jetty Service that can be managed by the standard <code>service</code> calls.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># cp /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT/bin/jetty.sh /etc/init.d/jetty
# echo "JETTY_HOME=/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT" &gt; /etc/default/jetty
# echo "JETTY_BASE=/opt/web/mybase" &gt;&gt; /etc/default/jetty
# echo "TMPDIR=/opt/jetty/temp" &gt;&gt; /etc/default/jetty</code></pre>
</div>
</div>
<div class="paragraph">
<p>Test out the configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># service jetty status
Checking arguments to Jetty:
START_INI = /opt/web/mybase/start.ini
JETTY_HOME = /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
JETTY_BASE = /opt/web/mybase
JETTY_CONF = /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT/etc/jetty.conf
JETTY_PID = /var/run/jetty.pid
JETTY_START = /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT/start.jar
CLASSPATH =
JAVA = /usr/bin/java
JAVA_OPTIONS = -Djetty.state=/opt/web/mybase/jetty.state
-Djetty.logs=/opt/web/mybase/logs
-Djetty.home=/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
-Djetty.base=/opt/web/mybase
-Djava.io.tmpdir=/opt/jetty/temp
JETTY_ARGS = console-capture.xml jetty-started.xml
RUN_CMD = /usr/bin/java
-Djetty.state=/opt/web/mybase/jetty.state
-Djetty.logs=/opt/web/mybase/logs
-Djetty.home=/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT
-Djetty.base=/opt/web/mybase
-Djava.io.tmpdir=/opt/jetty/temp
-jar /opt/jetty/jetty-distribution-10.0.0-SNAPSHOT/start.jar
console-capture.xml
jetty-started.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>You now have a configured <code>${jetty.base}</code> in <code>/opt/web/mybase</code> and a <code>${jetty.home}</code> in <code>/opt/jetty/jetty-distribution-10.0.0-SNAPSHOT</code>, along with the service level files necessary to start the service.</p>
</div>
<div class="paragraph">
<p>Test the service to make sure it starts up and runs successfully.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># service jetty start
Starting Jetty: OK Wed Nov 20 12:35:28 MST 2013
# service jetty check
..(snip)..
Jetty running pid=2958
[/opt/web/mybase]# ps u 2958
USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND
jetty 2958 5.3 0.1 11179176 53984 ? Sl 12:46 0:00 /usr/bin/java -Djetty...</code></pre>
</div>
</div>
<div class="paragraph">
<p>You should now have your server running.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="startup-windows-service">Startup via Windows Service</h3>
<div class="paragraph">
<p>There are no components that ship with the Jetty Distribution to make it a formal Windows Service.</p>
</div>
<div class="paragraph">
<p>However, we recommend the use of <a href="https://commons.apache.org/proper/commons-daemon/procrun.html">Apache ProcRun&#8217;s Daemon</a>.</p>
</div>
<div class="paragraph">
<p>The techniques outlined here are based on Windows 7 (64-bit), using JDK 8 (64-bit), running on an Intel i7 architecture machine.</p>
</div>
<div class="paragraph">
<p>Prepare some empty directories to work with.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">C:\&gt; mkdir opt
C:\&gt; cd opt
C:\opt&gt; mkdir jetty
C:\opt&gt; mkdir logs
C:\opt&gt; mkdir myappbase
C:\opt&gt; mkdir temp
C:\opt&gt; dir
Volume in drive C has no label.
Volume Serial Number is DEAD-BEEF
Directory of C:\opt
11/21/2013 04:06 PM &lt;DIR&gt; .
11/21/2013 04:06 PM &lt;DIR&gt; ..
11/21/2013 04:06 PM &lt;DIR&gt; jetty
11/21/2013 04:06 PM &lt;DIR&gt; logs
11/21/2013 04:06 PM &lt;DIR&gt; myappbase
11/21/2013 04:06 PM &lt;DIR&gt; temp
0 File(s) 0 bytes</code></pre>
</div>
</div>
<div class="paragraph">
<p>The directory purposes are as follows:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">C:\opt</dt>
<dd>
<p>Where the service layer utilities, scripts, and binaries will eventually be.</p>
</dd>
<dt class="hdlist1">C:\opt\logs</dt>
<dd>
<p>Where the logs for the service layer will put its own logs.</p>
<div class="paragraph">
<p>Typically you will see the audit logs (install/update/delete), StdOutput, and StdError logs here.</p>
</div>
</dd>
<dt class="hdlist1">C:\opt\jetty</dt>
<dd>
<p>Where the Jetty Distribution will be unpacked into.</p>
</dd>
<dt class="hdlist1">C:\opt\myappbase</dt>
<dd>
<p>Where your specific set of webapps will be located, including all of the configuration required of the server to make them operational.</p>
</dd>
<dt class="hdlist1">C:\opt\temp</dt>
<dd>
<p>This is the temporary directory assigned to Java by the Service Layer (this is what Java sees as the <code>java.io.tmpdir</code> System Property).</p>
<div class="paragraph">
<p>This is intentionally kept separate from the standard temp directories of Windows, as this location doubles as the Servlet Spec work directory.</p>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Or download Java 8 from: <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" class="bare">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">C:\opt&gt;java -version
java version "1.7.0_45"
Java(TM) SE Runtime Environment (build 1.7.0_45-b18)
Java HotSpot(TM) 64-Bit Server VM (build 24.45-b08, mixed mode)</code></pre>
</div>
</div>
<div class="paragraph">
<p>Download a copy of the ZIP distribution from the <a href="#jetty-downloading">Official Eclipse Download Site</a></p>
</div>
<div class="paragraph">
<p>Extract the contents of the <code>jetty-distribution-10.0.0-SNAPSHOT</code> directory to <code>C:\opt\jetty</code></p>
</div>
<div class="paragraph">
<p>Once complete, the contents of the <code>C:\opt\jetty</code> directory should look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">C:\opt\jetty&gt;dir
Volume in drive C has no label.
Volume Serial Number is C8CF-820B
Directory of C:\opt\jetty
11/21/2013 12:13 PM &lt;DIR&gt; .
11/21/2013 12:13 PM &lt;DIR&gt; ..
11/21/2013 12:13 PM &lt;DIR&gt; bin
11/21/2013 12:13 PM &lt;DIR&gt; demo-base
11/21/2013 12:13 PM &lt;DIR&gt; etc
11/21/2013 12:13 PM &lt;DIR&gt; lib
11/21/2013 12:13 PM 30,012 license-eplv10-aslv20.html
11/21/2013 12:13 PM &lt;DIR&gt; logs
11/21/2013 12:13 PM &lt;DIR&gt; modules
11/21/2013 12:13 PM 6,262 notice.html
11/21/2013 12:13 PM 1,249 README.TXT
11/21/2013 12:13 PM &lt;DIR&gt; resources
11/21/2013 12:13 PM &lt;DIR&gt; start.d
11/21/2013 12:13 PM 2,126 start.ini
11/21/2013 12:13 PM 72,226 start.jar
11/21/2013 12:13 PM 341,784 VERSION.txt
11/21/2013 12:13 PM &lt;DIR&gt; webapps
6 File(s) 453,659 bytes
11 Dir(s) 306,711,420,928 bytes free</code></pre>
</div>
</div>
<div class="paragraph">
<p>Download a copy of the <a href="https://commons.apache.org/proper/commons-daemon/binaries.html">Apache ProcRun</a> native binaries.</p>
</div>
<div class="paragraph">
<p>You should have downloaded a file named <code>commons-daemon-1.0.15-bin-windows.zip</code> (the version might be different).
Open the ZIP file and extract the <code>prunmgr.exe</code> and <code>prunsrv.exe</code> files into the <code>C:\opt</code> directory.</p>
</div>
<div class="paragraph">
<p>Make sure to get the right version of <code>prunsrv.exe</code> for your environment.
The ZIP file has both 32 bit and 64 bit versions of this file.</p>
</div>
<div class="paragraph">
<p>Once you are complete, the contents of <code>C:\opt</code> directory should look like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">C:\opt&gt; dir
Volume in drive C has no label.
Volume Serial Number is DEAD-BEEF
Directory of C:\opt
11/21/2013 04:06 PM &lt;DIR&gt; .
11/21/2013 04:06 PM &lt;DIR&gt; ..
11/21/2013 04:06 PM &lt;DIR&gt; jetty
11/21/2013 04:06 PM &lt;DIR&gt; logs
11/21/2013 04:06 PM &lt;DIR&gt; myappbase
11/21/2013 04:06 PM &lt;DIR&gt; temp
11/21/2013 04:11 PM 104,448 prunmgr.exe
11/21/2013 04:11 PM 80,896 prunsrv.exe
2 File(s) 185,344 bytes</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now it&#8217;s time to setup your new <code>${jetty.base}</code> directory to have all of your WebApps and the configurations that they need.</p>
</div>
<div class="paragraph">
<p>We&#8217;ll start by specifying which modules we want to use (this will create a start.ini file and also create a few empty directories for you)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">C:\opt\myappbase&gt;java -jar ..\jetty\start.jar --add-to-start=deploy,http,console-capture
WARNING: deploy initialised in ${jetty.base}\start.ini (appended)
WARNING: deploy enabled in ${jetty.base}\start.ini
MKDIR: ${jetty.base}\webapps
WARNING: server initialised in ${jetty.base}\start.ini (appended)
WARNING: server enabled in ${jetty.base}\start.ini
WARNING: http initialised in ${jetty.base}\start.ini (appended)
WARNING: http enabled in ${jetty.base}\start.ini
WARNING: server enabled in ${jetty.base}\start.ini
WARNING: logging initialised in ${jetty.base}\start.ini (appended)
WARNING: logging enabled in ${jetty.base}\start.ini
MKDIR: ${jetty.base}\logs
C:\opt\myappbase&gt;dir
Volume in drive C has no label.
Volume Serial Number is C8CF-820B
Directory of C:\opt\myappbase
11/21/2013 12:49 PM &lt;DIR&gt; .
11/21/2013 12:49 PM &lt;DIR&gt; ..
11/21/2013 12:49 PM &lt;DIR&gt; logs
11/21/2013 12:49 PM 1,355 start.ini
11/21/2013 12:49 PM &lt;DIR&gt; webapps
1 File(s) 1,355 bytes
4 Dir(s) 306,711,064,576 bytes free</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point you have configured your <code>C:\opt\myappbase</code> to enable the following modules:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">deploy</dt>
<dd>
<p>This is the module that will perform deployment of web applications (WAR files or exploded directories), or Jetty IoC XML context deployables, from the <code>C:\opt\myappbase\webapps</code> directory.</p>
</dd>
<dt class="hdlist1">http</dt>
<dd>
<p>This sets up a single Connector that listens for basic HTTP requests.</p>
<div class="paragraph">
<p>See the created <code>start.ini</code> for configuring this connector.</p>
</div>
</dd>
<dt class="hdlist1">logging</dt>
<dd>
<p>When running Jetty as a service it is very important to have logging enabled.
This module will enable the basic STDOUT and STDERR capture logging to the <code>C:\opt\myappbase\logs</code> directory.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>See the section on <a href="#start-jar">Using start.jar</a> for more details and options on setting up and configuring a <code>${jetty.base}</code> directory.</p>
</div>
<div class="paragraph">
<p>At this point you merely have to copy your WAR files into the <code>{$jetty.base}/webapps</code> directory.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">C:\opt\myappbase&gt; copy C:\projects\mywebsite.war webapps\</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point you should have your directories, Java, the Jetty distribution, and your webapp specifics setup and ready for operation.</p>
</div>
<div class="paragraph">
<p>We will use the <a href="https://commons.apache.org/proper/commons-daemon/binaries.html">Apache ProcRun&#8217;s prunsrv.exe</a> to install a Jetty Service.</p>
</div>
<div class="paragraph">
<p>The basic command line syntax is outlined in the link above.</p>
</div>
<div class="paragraph">
<p>A example <code>install-jetty-service.bat</code> is provided here as an example, based on the above directories.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-bat" data-lang="bat">@echo off
set SERVICE_NAME=JettyService
set JETTY_HOME=C:\opt\jetty
set JETTY_BASE=C:\opt\myappbase
set STOPKEY=secret
set STOPPORT=50001
set PR_INSTALL=C:\opt\prunsrv.exe
@REM Service Log Configuration
set PR_LOGPREFIX=%SERVICE_NAME%
set PR_LOGPATH=C:\opt\logs
set PR_STDOUTPUT=auto
set PR_STDERROR=auto
set PR_LOGLEVEL=Debug
@REM Path to Java Installation
set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_45
set PR_JVM=%JAVA_HOME%\jre\bin\server\jvm.dll
set PR_CLASSPATH=%JETTY_HOME%\start.jar;%JAVA_HOME%\lib\tools.jar
@REM JVM Configuration
set PR_JVMMS=128
set PR_JVMMX=512
set PR_JVMSS=4000
set PR_JVMOPTIONS=-Duser.dir="%JETTY_BASE%";-Djava.io.tmpdir="C:\opt\temp";-Djetty.home="%JETTY_HOME%";-Djetty.base="%JETTY_BASE%"
@REM Startup Configuration
set JETTY_START_CLASS=org.eclipse.jetty.start.Main
set PR_STARTUP=auto
set PR_STARTMODE=java
set PR_STARTCLASS=%JETTY_START_CLASS%
set PR_STARTPARAMS=STOP.KEY="%STOPKEY%";STOP.PORT=%STOPPORT%
@REM Shutdown Configuration
set PR_STOPMODE=java
set PR_STOPCLASS=%JETTY_START_CLASS%
set PR_STOPPARAMS=--stop;STOP.KEY="%STOPKEY%";STOP.PORT=%STOPPORT%;STOP.WAIT=10
"%PR_INSTALL%" //IS/%SERVICE_NAME% ^
--DisplayName="%SERVICE_NAME%" ^
--Install="%PR_INSTALL%" ^
--Startup="%PR_STARTUP%" ^
--LogPath="%PR_LOGPATH%" ^
--LogPrefix="%PR_LOGPREFIX%" ^
--LogLevel="%PR_LOGLEVEL%" ^
--StdOutput="%PR_STDOUTPUT%" ^
--StdError="%PR_STDERROR%" ^
--JavaHome="%JAVA_HOME%" ^
--Jvm="%PR_JVM%" ^
--JvmMs="%PR_JVMMS%" ^
--JvmMx="%PR_JVMMX%" ^
--JvmSs="%PR_JVMSS%" ^
--JvmOptions=%PR_JVMOPTIONS% ^
--Classpath="%PR_CLASSPATH%" ^
--StartMode="%PR_STARTMODE%" ^
--StartClass="%JETTY_START_CLASS%" ^
--StartParams="%PR_STARTPARAMS%" ^
--StopMode="%PR_STOPMODE%" ^
--StopClass="%PR_STOPCLASS%" ^
--StopParams="%PR_STOPPARAMS%"
if not errorlevel 1 goto installed
echo Failed to install "%SERVICE_NAME%" service. Refer to log in %PR_LOGPATH%
goto end
:installed
echo The Service "%SERVICE_NAME%" has been installed
:end</code></pre>
</div>
</div>
<div class="paragraph">
<p>Configuration&#8217;s of note in this batch file:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">SERVICE_NAME</dt>
<dd>
<p>This is the name of the service that Windows sees.
The name in the Services window will show this name.</p>
</dd>
<dt class="hdlist1">STOPKEY</dt>
<dd>
<p>This is the secret key (password) for the ShutdownMonitor, used to issue a formal command to stop the server.</p>
</dd>
<dt class="hdlist1">STOPPORT</dt>
<dd>
<p>The port that the Shutdown Monitor listens on for the stop command.</p>
<div class="paragraph">
<p>If you have multiple Jetty servers on the same machine, this port will need to be different for each Service.</p>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Once you have run <code>prunsrv.exe //IS/&lt;service-name&gt;</code> (done for you in the above batch file) to install the service, you can use the standard Windows utilities to manage (start/stop/restart) the Jetty service.</p>
</div>
<div class="paragraph">
<p>Open the Service View and start your service.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/windows-service-jetty.png" alt="image" width="576"></span></p>
</div>
</div>
<div class="sect2">
<h3 id="startup-jpms">Startup using the Java Platform Module System (JPMS)</h3>
<div class="paragraph">
<p>Jetty modules also act as automatic <a href="https://en.wikipedia.org/wiki/Java_Platform_Module_System">JPMS</a> modules via the <code>Automatic-Module-Name</code> attribute in the jar&#8217;s <code>MANIFEST.MF</code> file.</p>
</div>
<div class="paragraph">
<p>This makes possible to run Jetty from the module-path, rather than the class-path.</p>
</div>
<div class="paragraph">
<p>We recommend using JDK 11 or greater due to the fact that JDK 11 removed all the "enterprise" modules from the JDK,
and therefore it guarantees a more stable platform to base your application&#8217;s dependencies on.
The classes in these "enterprise" modules were bundled with JDK 8, and present in "enterprise" modules in JDK 9 and JDK 10.
With JDK 11, these "enterprise" classes are either not available in the JDK (because their corresponding module was removed), or they are present in a different module.</p>
</div>
<div class="paragraph">
<p>Because some of these "enterprise" classes are required by Jetty or by applications running in Jetty, it is better to use a stable source for those classes - in this case by using JDK 11
or greater, and explicitly referencing the "enterprise" classes as dependencies, rather than assuming they are bundled with the JDK.</p>
</div>
<div class="sect3">
<h4 id="jpms-module-path">Starting Jetty on the module-path</h4>
<div class="paragraph">
<p>To start Jetty on the module-path rather than the class-path, it is enough to add the <code>--jpms</code> option to the command line, for example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ mkdir my-jetty-base
$ cd my-jetty-base
$ java -jar $JETTY_HOME/start.jar --add-to-start=http
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : http initialized in ${jetty.base}/start.ini
INFO : threadpool transitively enabled, ini template available with --add-to-start=threadpool
INFO : Base directory was modified
$ java -jar $JETTY_HOME/start.jar --jpms</code></pre>
</div>
</div>
<div class="paragraph">
<p>The example above creates a <a href="#startup-base-and-home">Jetty base directory</a> and enables the <code>http</code> module using the <code>--add-to-start</code> command.
The server then starts Jetty on the module-path using the <code>--jpms</code> option.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>[NOTE]
When running on the module-path using the `--jpms` option, the Jetty start mechanism will fork a second JVM passing it the right JVM options to run on the module-path.
You will have two JVMs running: one that runs `start.jar` and one that runs Jetty on the module-path.</pre>
</div>
</div>
<div class="paragraph">
<p>If you are interested in the details of how the command line to run Jetty on the module-path looks like, you can add the <code>--dry-run</code> option:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar $JETTY_HOME/start.jar --jpms --dry-run</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will give an output looking something like this (broken in sections for clarity):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">/opt/openjdk-11+28/bin/java
--module-path /opt/jetty/lib/jetty-servlet-api-4.0.2.jar:/opt/jetty/lib/jetty-http-10.0.0-SNAPSHOT.jar:...
--module org.eclipse.jetty.xml/org.eclipse.jetty.xml.XmlConfiguration /opt/jetty/etc/jetty-threadpool.xml /opt/jetty/etc/jetty.xml ...</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>--module-path</code> option specifies the list of Jetty jars.
This list depends on the Jetty modules that have been enabled via the <a href="#startup-modules"><code>--add-to-start</code></a> command.</p>
</div>
<div class="paragraph">
<p>The <code>--module</code> option tells the JVM to run main class <code>XmlConfiguration</code> from the <code>org.eclipse.jetty.xml</code> module, with the given XML files as program arguments.</p>
</div>
<div class="paragraph">
<p>When the JVM starts, module <code>org.eclipse.jetty.xml</code> is added to the set of JPMS <em>root modules</em>; all other Jetty modules, being automatic, will be resolved and added to the module graph.
JAR files that are not modules, such as <code>jetty-servlet-api-4.0.2.jar</code>, are on the module-path and therefore will be made automatic modules by the JVM (hence the derived module name <code>servlet.api</code> for this jar, referenced by the <code>--patch-module</code> command line option above).</p>
</div>
</div>
<div class="sect3">
<h4 id="jpms-advanced-config">Advanced JPMS Configuration</h4>
<div class="paragraph">
<p>Web applications may need additional services from the Servlet Container, such as JDBC <code>DataSource</code> references or JTA <code>UserTransaction</code> references.</p>
</div>
<div class="paragraph">
<p>For example, for JDBC it is typical to store, in JNDI, a reference to the connection pool&#8217;s <code>DataSource</code> (such as <code>com.zaxxer.hikari.HikariDataSource</code>) or a reference directly to the JDBC driver&#8217;s <code>DataSource</code> (<code>com.mysql.jdbc.jdbc2.optional.MysqlDataSource</code>).
Jetty needs to be able to instantiate those classes and therefore needs to be able to load those classes and all their super-classes, among which includes <code>javax.sql.DataSource</code>.</p>
</div>
<div class="paragraph">
<p>When Jetty runs on the class-path, this is easily achieved by using a <a href="#custom-modules">custom module</a>:</p>
</div>
<div class="listingblock">
<div class="title">mysql.mod</div>
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>However, when running on the module-path, things are quite different.</p>
</div>
<div class="paragraph">
<p>Class <code>javax.sql.DataSource</code> is in a JDK bundled module named <code>java.sql</code>, which is not automatic (it&#8217;s a proper JPMS module) and it is not in the <em>root modules</em> set.
Because it is not an automatic module, it is not added to the module graph, and therefore needs to be added explicitly using the JVM command line <code>--add-modules</code>.</p>
</div>
<div class="paragraph">
<p>To add the JPMS module <code>java.sql</code> to the module graph, you need to modify your custom module in the following way, using our <code>mysql.mod</code> as an example:</p>
</div>
<div class="listingblock">
<div class="title">mysql.mod</div>
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: java.sql</code></pre>
</div>
</div>
<div class="paragraph">
<p>The new <code>[jpms]</code> section is only used when Jetty is started on the module-path via the <code>--jpms</code> command line option.</p>
</div>
<div class="paragraph">
<p>Assuming that <code>mysql-connector-java-<strong>.jar</code> is a non JPMS modular jar, or an automatic JPMS modular jar, the Jetty start mechanism will add <code>mysql-connector-java-</strong>.jar</code> to the module-path, and will add the JVM command line option <code>--add-modules java.sql</code>.</p>
</div>
<div class="paragraph">
<p>If <code>mysql-connector-java-*.jar</code> were a proper JPMS modular jar with name (for example) <code>com.mysql.jdbc</code>, then it would need to be explicitly added to the module graph, in this way:</p>
</div>
<div class="listingblock">
<div class="title">mysql.mod</div>
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[description]
MySQL module
[lib]
lib/mysql/mysql-connector-java-*.jar
[jpms]
add-modules: com.mysql.jdbc</code></pre>
</div>
</div>
<div class="paragraph">
<p>The JPMS module <code>java.sql</code> does not need to be explicitly added because it would be a dependency of the <code>com.mysql.jdbc</code> module and therefore automatically added to the module graph.</p>
</div>
<div class="paragraph">
<p>The <code>[jpms]</code> section has the following format:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[jpms]
add-modules: &lt;module name&gt;(,&lt;module name&gt;)*
patch-module: &lt;module&gt;=&lt;file&gt;(:&lt;file&gt;)*
add-opens: &lt;module&gt;/&lt;package&gt;=&lt;target-module&gt;(,&lt;target-module&gt;)*
add-exports: &lt;module&gt;/&lt;package&gt;=&lt;target-module&gt;(,&lt;target-module&gt;)*
add-reads: &lt;module&gt;=&lt;target-module&gt;(,&lt;target-module&gt;)*</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="jpms-module-path-alternative">Alternative way to start Jetty on the module-path</h4>
<div class="paragraph">
<p>The section above uses the <code>--jpms</code> command line option to start Jetty on the module-path.
An alternative way of achieving the same result is to use a Jetty module, <code>$JETTY_BASE/modules/jpms.mod</code>,
that specifies that you want to run using JPMS (and possibly add some JPMS specific configuration).</p>
</div>
<div class="listingblock">
<div class="title">jpms.mod</div>
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[ini]
--jpms
[jpms]
# Additional JPMS configuration.</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>[ini]</code> section is equivalent to passing the <code>--jpms</code> option to the command line.
The <code>[jpms]</code> section (see also the <a href="#jpms-advanced-config">advanced JPMS configuration section</a>)
allows you specify additional JPMS configuration.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ mkdir jetty-base-jpms
$ cd jetty-base-jpms
$ mkdir modules
# Copy the jpms.mod file above into the $JETTY_BASE/modules/ directory.
$ cp /tmp/jpms.mod modules/
# Add both the http and the jpms modules.
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,jpms
# Jetty will start on the module-path.
$ java -jar $JETTY_HOME/start.jar</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-contexts">Configuring Contexts</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter discusses various options for configuring Jetty contexts.</p>
</div>
<div class="sect2">
<h3 id="setting-context-path">Setting a Context Path</h3>
<div class="paragraph">
<p>The context path is the prefix of a URL path that is used to select the context(s) to which an incoming request is passed. Typically a URL in a Java servlet server is of the format <code><a href="http://hostname.com/contextPath/servletPath/pathInfo" class="bare">http://hostname.com/contextPath/servletPath/pathInfo</a></code>, where each of the path elements can be zero or more / separated elements.
If there is no context path, the context is referred to as the <em>root</em> context.
The root context must be configured as <code>/</code> but is reported as the empty string by the servlet API <code>getContextPath()</code> method.</p>
</div>
<div class="paragraph">
<p>How you set the context path depends on how you deploy the web application (or <code>ContextHandler</code>).</p>
</div>
<div class="sect3">
<h4 id="using-embedded-deployment">Using Embedded Deployment</h4>
<div class="paragraph">
<p>If you run Jetty from code as an embedded server (see <a href="#advanced-embedding">Embedding</a>), setting the context path is a matter of calling the <code>setContextPath</code> method on the <code>ContextHandler</code> instance (or <code>WebAppContext</code> instance).</p>
</div>
</div>
<div class="sect3">
<h4 id="usng-the-context-provider">By naming convention</h4>
<div class="paragraph">
<p>If a web application is deployed using the WebAppProvider of the DeploymentManager without an XML IoC file, then the name of the WAR file is used to set the context path:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If the WAR file is named myapp.war, then the context will be deployed with a context path of <code>/myapp</code></p>
</li>
<li>
<p>If the WAR file is named ROOT.WAR (or any case insensitive variation), then the context will be deployed with a context path of <code>/</code></p>
</li>
<li>
<p>If the WAR file is named ROOT-foobar.war ( or any case insensitive variation), then the context will be deployed with a context path of <code>/</code> and a virtual host of "foobar"</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="using-the-webapp-provider">By Deployer configuration</h4>
<div class="paragraph">
<p>If a web application is deployed using the <code>WebAppProvider</code> of the <code>DeploymentManager</code> with an XML IoC file to configure the context, then the <code>setContextPath</code> method can be called within that file.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
...
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="embedding-web-inf-jetty-web.xml-file">Embedding a WEB-INF/jetty-web.xml File</h4>
<div class="paragraph">
<p>You can also set the context path for webapps by embedding a <code>WEB-INF/jetty-web.xml</code> file in the WAR, which uses the same XML IoC format as the deployer example above.
However this is not the preferred method as it requires the web application to be modified.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-virtual-hosts">Configuring Virtual Hosts</h3>
<div class="paragraph">
<p>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 <a href="#different-virtual-hosts-different-contexts">different</a>, then a virtual host needs to be configured for each deployed <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html">context</a> to indicate which names a context will respond to.</p>
</div>
<div class="paragraph">
<p>Virtual hosts are set on a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html">context</a> by calling the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-"><code>setVirtualHosts</code></a> or <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html#addVirtualHosts-java.lang.String:A-"><code>addVirtualHost</code></a> method which can be done in several ways:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Using a <a href="#deployable-descriptor-file">context XML</a> file in the webapps directory (see the example in <a href="https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jetty-webapp/src/main/config/demo-base/webapps/test.xml">test.xml</a> in the Jetty distribution).</p>
</li>
<li>
<p>Creating a <a href="#deployment-architecture">custom deployer</a> with a binding to configure virtual hosts for all contexts found in the same <code>webapps</code> directory.</p>
</li>
<li>
<p>Calling the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html#setVirtualHosts-java.lang.String:A-">API</a> directly on an <a href="#advanced-embedding">embedded</a> usage.</p>
</li>
<li>
<p>Using a <code>WEB-INF/jetty-web.xml</code> file (now deprecated).</p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="configuring-a-virtual-host">Virtual Host Names</h4>
<div class="paragraph">
<p>Jetty supports the following styles of virtual host name:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">www.hostname.com</dt>
<dd>
<p>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</p>
</dd>
<dt class="hdlist1">*.hostname.com</dt>
<dd>
<p>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</p>
</dd>
<dt class="hdlist1">10.0.0.2</dt>
<dd>
<p>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).</p>
</dd>
<dt class="hdlist1">@ConnectorName</dt>
<dd>
<p>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 <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/AbstractConnector.html#setName(java.lang.String)">Connector.setName(String)</a>.</p>
</dd>
<dt class="hdlist1">www.√integral.com</dt>
<dd>
<p>Non-ASCII and <a href="http://en.wikipedia.org/wiki/Internationalized_domain_name">IDN</a> domain names can be set as virtual hosts using <a href="http://en.wikipedia.org/wiki/Punycode">Puny Code</a> equivalents that may be obtained from a <a href="http://network-tools.com/idn-convert.asp">Punycode/IDN converters</a>.
For example if the non-ASCII domain name <code>www.√integral.com</code> is given to a browser, then it will make a request that uses the domain name <code>www.xn&#8212;&#8203;integral-7g7d.com</code>, which is the name that should be added as the virtual host name.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4>Example Virtual Host Configuration</h4>
<div class="paragraph">
<p>Virtual hosts can be used with any context that is a subclass of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html">ContextHandler</a>.
Lets look at an example where we configure a web application - represented by the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html">WebAppContext</a> class - with virtual hosts.
You supply a list of IP addresses and names at which the web application is reachable, such as the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>333.444.555.666</code></p>
</li>
<li>
<p><code>127.0.0.1</code></p>
</li>
<li>
<p><code>www.blah.com</code></p>
</li>
<li>
<p><code>www.blah.net</code></p>
</li>
<li>
<p><code>www.blah.org</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Suppose you have a webapp called <code>blah.war</code>, that you want all of the above names and addresses to be served at path &#8220;/blah&#8221;.
Here&#8217;s how you would configure the virtual hosts with a <a href="#deployable-descriptor-file">context XML</a> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/blah&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;Property name="jetty.webapps"/&gt;blah.war&lt;/Set&gt;
&lt;Set name="virtualHosts"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;333.444.555.666&lt;/Item&gt;
&lt;Item&gt;127.0.0.1&lt;/Item&gt;
&lt;Item&gt;www.blah.com&lt;/Item&gt;
&lt;Item&gt;www.blah.net&lt;/Item&gt;
&lt;Item&gt;www.blah.org&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="different-virtual-hosts-different-contexts">Using Different Sets of Virtual Hosts to Select Different Contexts</h4>
<div class="paragraph">
<p>You can configure different contexts to respond on different virtual hosts by supplying a specific list of virtual hosts for each one.</p>
</div>
<div class="paragraph">
<p>For example, suppose your imaginary machine has these DNS names:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>www.blah.com</code></p>
</li>
<li>
<p><code>www.blah.net</code></p>
</li>
<li>
<p><code>www.blah.org</code></p>
</li>
<li>
<p><code>www.other.com</code></p>
</li>
<li>
<p><code>www.other.net</code></p>
</li>
<li>
<p><code>www.other.org</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Suppose also you have 2 webapps, one called <code>blah.war</code> that you would like served from the <code><strong>.blah.</strong></code> names, and one called <code>other.war</code> that you want served only from the <code><strong>.other.</strong></code> names.</p>
</div>
<div class="paragraph">
<p>Using the method of preparing <a href="#deployable-descriptor-file">contextXML</a> files, one for each webapp yields the following:</p>
</div>
<div class="paragraph">
<p>For <code>blah</code> webapp:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/blah&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;Property name="jetty.webapps"/&gt;/blah.war&lt;/Set&gt;
&lt;Set name="virtualHosts"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;www.blah.com&lt;/Item&gt;
&lt;Item&gt;www.blah.net&lt;/Item&gt;
&lt;Item&gt;www.blah.org&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>These URLs now resolve to the blah context (ie <code>blah.war</code>):</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code><a href="http://www.blah.com/blah" class="bare">http://www.blah.com/blah</a></code></p>
</li>
<li>
<p><code><a href="http://www.blah.net/blah" class="bare">http://www.blah.net/blah</a></code></p>
</li>
<li>
<p><code><a href="http://www.blah.org/blah" class="bare">http://www.blah.org/blah</a></code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For <code>other</code> webapp:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/other&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;Property name="jetty.webapps"/&gt;/other.war&lt;/Set&gt;
&lt;Set name="virtualHosts"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;www.other.com&lt;/Item&gt;
&lt;Item&gt;www.other.net&lt;/Item&gt;
&lt;Item&gt;www.other.org&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>These URLs now resolve to the other context (i.e. <code>other.war</code>):</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code><a href="http://www.other.com/other" class="bare">http://www.other.com/other</a></code></p>
</li>
<li>
<p><code><a href="http://www.other.net/other" class="bare">http://www.other.net/other</a></code></p>
</li>
<li>
<p><code><a href="http://www.other.org/other" class="bare">http://www.other.org/other</a></code></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="different-virtual-hosts-different-context-same-path">Using Different Sets of Virtual Hosts to Select Different Contexts at the Same Context Path</h4>
<div class="paragraph">
<p>In the previous section we setup 2 different contexts to be served from different virtual hosts at <em>different</em> 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.</p>
</div>
<div class="paragraph">
<p>Consider an example where we have the same set of DNS names as before, and the same webapps <code>blah.war</code> and <code>other.war</code>. We still want <code>blah.war</code> to be served in response to hostnames of <code><strong>.blah.</strong></code>, and we still want <code>other.war</code> to be served in response to <code><strong>.other.</strong></code> names.
However, we would like<em>all</em> of our clients to use the <code>"/"</code> context path, no matter which context is being targeted.</p>
</div>
<div class="paragraph">
<p>In other words, we want all of the following URLs to map to <code>blah.war</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code><a href="http://www.blah.com/" class="bare">http://www.blah.com/</a></code></p>
</li>
<li>
<p><code><a href="http://www.blah.net/" class="bare">http://www.blah.net/</a></code></p>
</li>
<li>
<p><code><a href="http://www.blah.org/" class="bare">http://www.blah.org/</a></code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Similarly, we want the following URLs to map to <code>other.war</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code><a href="http://www.other.com/" class="bare">http://www.other.com/</a></code></p>
</li>
<li>
<p><code><a href="http://www.other.net/" class="bare">http://www.other.net/</a></code></p>
</li>
<li>
<p><code><a href="http://www.other.org/" class="bare">http://www.other.org/</a></code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To achieve this, we simply use the same context path of <code>/</code> for each of our webapps, while still applying our different set of virtual host names.</p>
</div>
<div class="paragraph">
<p>For foo webapp:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;Property name="jetty.webapps"/&gt;/foo.war&lt;/Set&gt;
&lt;Set name="virtualHosts"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;www.blah.com&lt;/Item&gt;
&lt;Item&gt;www.blah.net&lt;/Item&gt;
&lt;Item&gt;www.blah.org&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>For bar webapp:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;Property name="jetty.webapps"/&gt;/bar.war&lt;/Set&gt;
&lt;Set name="virtualHosts"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;www.other.com&lt;/Item&gt;
&lt;Item&gt;www.other.net&lt;/Item&gt;
&lt;Item&gt;www.other.org&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="ref-temporary-directories">Temporary Directories</h3>
<div class="paragraph">
<p>Jetty itself has no temporary directories, but you can assign a directory for each web application, into which the WAR is unpacked, JSPs compiled on-the-fly, etc.
If you do not assign a specific temporary directory, Jetty will create one as needed when your web application starts.
Whether you set the location of the temporary directory - or you let Jetty create one for you - you also have a choice to either keep or delete the temporary directory when the web application stops.</p>
</div>
<div class="sect3">
<h4>The Default Temp Directory</h4>
<div class="paragraph">
<p>By default, Jetty will create a temporary directory for each web application. The name of the directory will be of the form:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>"jetty-"+host+"-"+port+"-"+resourceBase+"-_"+context+"-"+virtualhost+"-"+randomdigits+".dir"</pre>
</div>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>jetty-0.0.0.0-8080-test.war-_test-any-8900275691885214790.dir</pre>
</div>
</div>
<div class="paragraph">
<p>Where <code>0.0.0.0</code> is the host address, <code>8080</code> is the port, <code>test.war</code> is the resourceBase, <code>test</code> is the context path (with / converted to _), <code>any</code> is the virtual host, and <code>randomdigits</code> are a string of digits guaranteed to be unique.</p>
</div>
<div class="paragraph">
<p>Once the temp directory is created, it is retrievable as the value (as a File) of the context attribute <code>javax.servlet.context.tempdir.</code></p>
</div>
<div class="sect4">
<h5>The location of the temp directory</h5>
<div class="paragraph">
<p>By default, Jetty will create this directory inside the directory named by the <code>java.io.tmpdir</code> System property.
You can instruct Jetty to use a different parent directory by setting the context attribute <code>org.eclipse.jetty.webapp.basetempdir</code> to the name of the desired parent directory.
The directory named by this attribute <em>must</em> exist and be <em>writeable</em>.</p>
</div>
<div class="paragraph">
<p>As usual with Jetty, you can either set this attribute in a context xml file, or you can do it in code.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example of setting it in an xml file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
&lt;Set name="war"&gt;foo.war&lt;/Set&gt;
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;org.eclipse.jetty.webapp.basetempdir&lt;/Arg&gt;
&lt;Arg&gt;/home/my/foo&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The equivalent in code is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setAttribute("org.eclipse.jetty.webapp.basetempdir", "/tmp/foo");</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Setting a Specific Temp Directory</h4>
<div class="paragraph">
<p>There are several ways to use a particular directory as the temporary directory:</p>
</div>
<div class="sect4">
<h5>Call WebAppContext.setTempDirectory(String dir)</h5>
<div class="paragraph">
<p>As before this can be accomplished with an XML file or directly in code.
Here is an example of setting the temp directory in XML:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
&lt;Set name="war"&gt;foo.war&lt;/Set&gt;
&lt;Set name="tempDirectory"&gt;/some/dir/foo&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>And here is an example of doing it with java code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setTempDirectory(new File("/some/dir/foo"));</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Setting the javax.servlet.context.tempdir Context Attribute</h5>
<div class="paragraph">
<p>You should set this context attribute with the name of directory you want to use as the temp directory.
Again, you can do this in XML:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
&lt;Set name="war"&gt;foo.war&lt;/Set&gt;
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;javax.servlet.context.tempdir&lt;/Arg&gt;
&lt;Arg&gt;/some/dir/foo&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Or in java:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">WebAppContext context = new WebAppContext();
context.setContextPath("/test");
context.setWar("foo.war");
context.setAttribute("javax.servlet.context.tempdir", "/some/dir/foo");</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once a temporary directory has been created by either of these methods, a file instance for it is set as the value of the <code>javax.servlet.context.tempdir</code> attribute of the web application.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Be wary of setting an explicit temp directory if you are likely to change the jars in WEB-INF/lib between redeployments.
There is a JVM bug concerning <a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4774421">caching of jar contents.</a>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect4">
<h5>Setting the Temp Directory on the Command Line</h5>
<div class="paragraph">
<p>You can set the location of the temp directory on the command line when Jetty starts up in two ways.
First is the most straightforward, simply add it to your command line when starting Jetty.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar ../start.jar -Djava.io.tmpdir=/path/to/desired/directory</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternately, this can be defined in a <a href="#startup-modules">module.</a>
The <code>jvm</code> module packaged with Jetty is set up to add additional JVM options.
After enabling the module (using the <code>--add-to-start=jvm</code> command), edit the <code>jvm.ini</code> file and add the location to the temporary directory.
You will also need verify the line including the <code>--exec</code> command is not commented out, as this is required for Jetty to start a new, forked JVM.
Below is an example of the standard <code>jvm.ini</code> file altered to include a reference to a temp directory.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: jvm
# A noop module that creates an ini template useful for
# setting JVM arguments (eg -Xmx )
# ---------------------------------------
--module=jvm
## JVM Configuration
## If JVM args are include in an ini file then --exec is needed
## to start a new JVM from start.jar with the extra args.
##
## If you wish to avoid an extra JVM running, place JVM args
## on the normal command line and do not use --exec
--exec
# -Xmx2000m
# -Xmn512m
# -XX:+UseConcMarkSweepGC
# -XX:ParallelCMSThreads=2
# -XX:+CMSClassUnloadingEnabled
# -XX:+UseCMSCompactAtFullCollection
# -XX:CMSInitiatingOccupancyFraction=80
# -internal:gc
# -XX:+PrintGCDateStamps
# -XX:+PrintGCTimeStamps
# -XX:+PrintGCDetails
# -XX:+PrintTenuringDistribution
# -XX:+PrintCommandLineFlags
# -XX:+DisableExplicitGC
-Djava.io.tmpdir=/path/to/desired/directory</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>The "work" Directory</h4>
<div class="paragraph">
<p>It is possible to create a directory named <code>work</code> in the <code>$\{jetty.base}</code> directory.
If such a directory is found, it is assumed you want to use it as the parent directory for all of the temporary directories of the webapps in <code>$\{jetty.base}</code>.
Moreover, as has historically been the case, these temp directories inside the work directory are not cleaned up when Jetty exits (or more correctly speaking, the <code>temp</code> directory corresponding to a context is not cleaned up when that context stops).</p>
</div>
<div class="paragraph">
<p>When a <code>work</code> directory is used, the algorithm for generating the name of the context-specific temp directories omits the random digit string.
This ensures the name of the directory remains consistent across context restarts.</p>
</div>
</div>
<div class="sect3">
<h4>Persisting the temp directory</h4>
<div class="paragraph">
<p>Sometimes it is useful to keep the contents of the temporary directory between restarts of the web application.
By default, Jetty will <strong>not</strong> persist the temp directory.
To configure Jetty to keep it, use <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html">WebAppContext.setPersistTempDirectory(true)</a>.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Be aware that if you call <code>setPersistTempDirectory(true)</code>, but let Jetty create a new temp directory each time (i.e. you do NOT set an explicit temp directory), then you will accumulate temp directories in your chosen temp directory location.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
</div>
<div class="sect2">
<h3 id="serving-webapp-from-particular-port">Serving a WebApp from a Particular Port/Connector</h3>
<div class="paragraph">
<p>Sometimes it is required to serve different web applications from different ports/connectors.
The simplest way to do this is to create multiple <code>Server</code> 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.</p>
</div>
<div class="sect3">
<h4 id="creating-server-instances">Creating Multiple Server Instances</h4>
<div class="paragraph">
<p>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 <code>id</code> field in the Configure element of <code>jetty.xml</code> files is used to identify the instance that the configuration applies to, so to run two instances of the Server, you can copy the <code>jetty.xml</code>, 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 <code>jetty.xml</code> files or the multiple XML files may be combined to a single file.</p>
</div>
<div class="paragraph">
<p>When creating new configurations for alternative server:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Change all <code>id="Server"</code> to the new server name:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="OtherServer" class="org.eclipse.jetty.server.Server"&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>For all connectors for the new server change the <code>refid</code> in the server argument:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Arg name="server"&gt;&lt;Ref refid="OtherServer" /&gt;&lt;/Arg&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Make sure that any references to properties like <code>jetty.http.port</code> are either renamed or replaced with absolute values.</p>
</li>
<li>
<p>Make sure that any deployers <code>AppProviders</code> refer to a different "webapps" directory so that a different set of applications are deployed.</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="jetty-otherserver.xml">Example Other Server XML</h5>
<div class="paragraph">
<p>The following example creates another server instance and configures it with a connector and deployer:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure id="OtherServer" class="org.eclipse.jetty.server.Server"&gt;
&lt;Set name="handler"&gt;
&lt;New id="Handlers" class="org.eclipse.jetty.server.handler.HandlerCollection"&gt;
&lt;Set name="handlers"&gt;
&lt;Array type="org.eclipse.jetty.server.Handler"&gt;
&lt;Item&gt;
&lt;New id="OtherContexts" class="org.eclipse.jetty.server.handler.ContextHandlerCollection"/&gt;
&lt;/Item&gt;
&lt;Item&gt;
&lt;New class="org.eclipse.jetty.server.handler.DefaultHandler"/&gt;
&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;Call name="addConnector"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="OtherServer" /&gt;&lt;/Arg&gt;
&lt;Set name="port"&gt;8888&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager"&gt;
&lt;Set name="contexts"&gt;
&lt;Ref refid="OtherContexts" /&gt;
&lt;/Set&gt;
&lt;Call id="webappprovider" name="addAppProvider"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.deploy.providers.WebAppProvider"&gt;
&lt;Set name="monitoredDirName"&gt;&lt;Property name="jetty.base" default="." /&gt;/other-webapps&lt;/Set&gt;
&lt;Set name="defaultsDescriptor"&gt;&lt;Property name="jetty.home" default="." /&gt;/etc/webdefault.xml&lt;/Set&gt;
&lt;Set name="extractWars"&gt;true&lt;/Set&gt;
&lt;Set name="configurationManager"&gt;
&lt;New class="org.eclipse.jetty.deploy.PropertiesConfigurationManager"/&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>To run the other server, add the extra configuration file(s) to the command line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar start.jar jetty-otherserver.xml</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="alternative">Named Connectors</h4>
<div class="paragraph">
<p>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 <code>setName</code> method, then this can be referenced with the special virtual host name "@MyConnector".</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="custom-error-pages">Creating Custom Error Pages</h3>
<div class="paragraph">
<p>The following sections describe several ways to create custom error pages in Jetty.</p>
</div>
<div class="sect3">
<h4>Defining error pages in web.xml</h4>
<div class="paragraph">
<p>You can use the standard webapp configuration file located in <code>webapp/WEB-INF/web.xml</code> to map errors to specific URLs with the <code>error-page</code> element.
This element creates a mapping between the error-code or exception-type to the location of a resource in the web application.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>error-code</code> - an integer value</p>
</li>
<li>
<p><code>exception-type</code> - a fully qualified class name of a Java Exception type</p>
</li>
<li>
<p><code>location</code> - location of the resource in the webapp relative to the root of the web application. Value should start with <code>/</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Error code example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;error-page&gt;
&lt;error-code&gt;404&lt;/error-code&gt;
&lt;location&gt;/jspsnoop/ERROR/404&lt;/location&gt;
&lt;/error-page&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Exception example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;error-page&gt;
&lt;exception-type&gt;java.io.IOException&lt;/exception-type&gt;
&lt;location&gt;/jspsnoop/IOException&lt;/location&gt;
&lt;/error-page&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The error page mappings created with the error-page element will redirect to a normal URL within the web application and will be handled as a normal request to that location and thus may be static content, a JSP or a filter and/or servlet.
When handling a request generated by an error redirection, the following request attributes are set and are available to generate dynamic content:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">javax.servlet.error.exception</dt>
<dd>
<p>The exception instance that caused the error (or null).</p>
</dd>
<dt class="hdlist1">javax.servlet.error.exception_type</dt>
<dd>
<p>The class name of the exception instance that caused the error (or null).</p>
</dd>
<dt class="hdlist1">javax.servlet.error.message</dt>
<dd>
<p>The error message.</p>
</dd>
<dt class="hdlist1">javax.servlet.error.request_uri</dt>
<dd>
<p>The URI of the request with an error.</p>
</dd>
<dt class="hdlist1">javax.servlet.error.servlet_name</dt>
<dd>
<p>The Servlet name of the servlet that the request was
dispatched to.</p>
</dd>
<dt class="hdlist1">javax.servlet.error.status_code</dt>
<dd>
<p>The status code of the error (e.g. 404, 500 etc.).</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4>Configuring error pages context files</h4>
<div class="paragraph">
<p>You can use context IoC XML files to configure the default error page mappings with more flexibility than is available with <code>web.xml</code>, specifically with the support of error code ranges.
Context files are normally located in <code>${jetty.base}/webapps/</code> (see <code>DeployerManager</code> for more details) and an example of more flexible error page mapping is below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
&lt;Set name="war"&gt;
&lt;SystemProperty name="jetty.base" default="."/&gt;/webapps/test
&lt;/Set&gt;
&lt;!-- by Code --&gt;
&lt;Get name="errorHandler"&gt;
&lt;Call name="addErrorPage"&gt;
&lt;Arg type="int"&gt;404&lt;/Arg&gt;
&lt;Arg type="String"&gt;/jspsnoop/ERROR/404&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Get&gt;
&lt;!-- by Exception --&gt;
&lt;Get name="errorHandler"&gt;
&lt;Call name="addErrorPage"&gt;
&lt;Arg&gt;
&lt;Call class="java.lang.Class" name="forName"&gt;
&lt;Arg type="String"&gt;java.io.IOException&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Arg&gt;
&lt;Arg type="String"&gt;/jspsnoop/IOException&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Get&gt;
&lt;!-- by Code Range --&gt;
&lt;Get name="errorHandler"&gt;
&lt;Call name="addErrorPage"&gt;
&lt;Arg type="int"&gt;500&lt;/Arg&gt;
&lt;Arg type="int"&gt;599&lt;/Arg&gt;
&lt;Arg type="String"&gt;/dump/errorCodeRangeMapping&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Get&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>Custom ErrorHandler class</h4>
<div class="paragraph">
<p>If no error page mapping is defined, or if the error page resource itself has an error, then the error page will be generated by an instance of <code>ErrorHandler</code> configured either the Context or the Server.
An <code>ErrorHandler</code> may extend the <code>ErrorHandler</code> class and may totally replace the handle method to generate an error page, or it can implement some or all of the following methods to partially modify the error pages:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response) throws IOException
void handleErrorPage(HttpServletRequest request, Writer writer, int code, String message) throws IOException
void writeErrorPage(HttpServletRequest request, Writer writer, int code, String message, boolean showStacks) throws IOException
void writeErrorPageHead(HttpServletRequest request, Writer writer, int code, String message) throws IOException
void writeErrorPageBody(HttpServletRequest request, Writer writer, int code, String message, boolean showStacks) throws IOException
void writeErrorPageMessage(HttpServletRequest request, Writer writer, int code, String message, String uri) throws IOException
void writeErrorPageStacks(HttpServletRequest request, Writer writer) throws IOException</code></pre>
</div>
</div>
<div class="paragraph">
<p>An <code>ErrorHandler</code> instance may be set on a Context by calling the <code>ContextHandler.setErrorHandler</code> method. This can be done by embedded code or via context IoC XML.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.server.handler.ContextHandler"&gt;
...
&lt;Set name="errorHandler"&gt;
&lt;New class="com.acme.handler.MyErrorHandler"/&gt;
&lt;/Set&gt;
...
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>An <code>ErrorHandler</code> instance may be set on the entire server by setting it as a dependent bean on the Server instance.
This can be done by calling <code>Server.addBean(Object)</code> via embedded code or in <code>jetty.xml</code> IoC XML:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
...
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New class="com.acme.handler.MyErrorHandler"/&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
...
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>Server level 404 error</h4>
<div class="paragraph">
<p>It is possible to get a 'page not found' when a request is made to the server for a resource that is outside of any registered contexts.
As an example, you have a domain name pointing to your public server IP, yet no context is registered with Jetty to serve pages for that domain.
As a consequence, the server, by default, gives a listing of all contexts running on the server.</p>
</div>
<div class="paragraph">
<p>One of the quickest ways to avoid this behavior is to create a catch all context.
Create a "root" web app mapped to the "/" URI, and use the <code>index.html</code> redirect to whatever place with a header directive.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="setting-form-size">Setting Max Form Size</h3>
<div class="paragraph">
<p>Jetty limits the amount of data that can post back from a browser or other client to the server.
This helps protect the server against denial of service attacks by malicious clients sending huge amounts of data.
The default maximum size Jetty permits is 200000 bytes.
You can change this default for a particular webapp, for all webapps on a particular Server instance, or all webapps within the same JVM.</p>
</div>
<div class="sect3">
<h4>For a Single Webapp</h4>
<div class="paragraph">
<p>The method to invoke is: <code>ContextHandler.setMaxFormContentSize(int maxSize);</code></p>
</div>
<div class="paragraph">
<p>This can be done either in a context XML deployment descriptor external to the webapp, or in a <code>jetty-web.xml</code> file in the webapp&#8217;s <code>WEB-INF</code> directory.</p>
</div>
<div class="paragraph">
<p>In either case the syntax of the XML file is the same:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --&gt;
&lt;!-- Max Form Size --&gt;
&lt;!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --&gt;
&lt;Set name="maxFormContentSize"&gt;200000&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>For All Apps on a Server</h4>
<div class="paragraph">
<p>Set an attribute in <code>jetty.xml</code> on the Server instance for which you want to modify the maximum form content size:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.server.Server"&gt;
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;org.eclipse.jetty.server.Request.maxFormContentSize&lt;/Arg&gt;
&lt;Arg&gt;200000&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
It is important to remember that you should <strong>not</strong> modify the XML files in your <code>$JETTY_HOME</code>.
If you do for some reason feel you want to change the way an XML file operates, it is best to make a copy of it in your <code>$JETTY_BASE</code> in an <code>/etc</code> directory.
Jetty will always look first to the <code>$JETTY_BASE</code> for configuration.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>For All Apps in the JVM</h4>
<div class="paragraph">
<p>Use the system property <code>org.eclipse.jetty.server.Request.maxFormContentSize</code>.
This can be set on the command line or in the <code>$JETTY_BASE\start.ini</code> or any <code>$JETTY_BASE\start.d\*.ini</code> <a href="#startup-modules">module ini file.</a>
Using <code>$JETTY_BASE\start.d\server.ini</code> as an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-console" data-lang="console"># ---------------------------------------
# Module: server
# Enables the core Jetty server on the classpath.
# ---------------------------------------
--module=server
### Common HTTP configuration
## Scheme to use to build URIs for secure redirects
# jetty.httpConfig.secureScheme=https
...
-Dorg.eclipse.jetty.server.Request.maxFormContentSize=200000</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-deployment">Deploying to Jetty</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter discusses various ways to deploy applications with Jetty.
Topics range from deployment bindings to deploying third party products.
It also includes information about the Deployment Manager and WebApp Provider.</p>
</div>
<div class="sect2">
<h3 id="anatomy-of-a-webapp">Anatomy of a Web Application</h3>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>Web Applications can be bundled into a single Web Archive (WAR file) or as a directory tree.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>/WEB-INF/</code></dt>
<dd>
<p>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.</p>
</dd>
<dt class="hdlist1"><code>/WEB-INF/web.xml</code></dt>
<dd>
<p><strong>Required</strong> deployment descriptor defining various behavior of the Web Application.</p>
</dd>
<dt class="hdlist1"><code>/WEB-INF/classes/</code></dt>
<dd>
<p>Location for Web Application specific compiled java classes</p>
</dd>
<dt class="hdlist1"><code>/WEB-INF/lib/</code></dt>
<dd>
<p>Directory for JAR files (libraries)</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The Jetty internal <code>WebAppClassloader</code> will load classes from <code>/WEB-INF/classes/</code> first, then from jar files found in <code>/WEB-INF/lib/</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="automatic-webapp-deployment">Automatic Web Application Deployment</h3>
<div class="paragraph">
<p>The most basic technique for deploying Web Applications is to put a WAR file or Exploded WAR directory into the <code>${jetty.base}/webapps/</code> directory and let Jetty&#8217;s deployment scanner find it and deploy it under a Context path of the same name.</p>
</div>
<div class="paragraph">
<p>Only Web Applications that follow the Web Application Layout will be detected by Jetty and deployed this way.</p>
</div>
<div class="paragraph">
<p>The Context Path assigned to this automatic deployment is based the filename (or directory name) of the WAR.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">File or Directory Name</th>
<th class="tableblock halign-left valign-top">Assigned Context Path</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/webapps/footrope.war</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://host/footrope/" class="bare">http://host/footrope/</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/webapps/baggywrinkle-1.0.war</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://host/baggywrinkle-1.0/" class="bare">http://host/baggywrinkle-1.0/</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/webapps/lazaret-2.1.3-SNAPSHOT.war</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://host/lazaret-2.1.3-SNAPSHOT/" class="bare">http://host/lazaret-2.1.3-SNAPSHOT/</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/webapps/belaying-pins/WEB-INF/web.xml</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://host/belaying-pins/" class="bare">http://host/belaying-pins/</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/webapps/root.war</code> <em>(reserved name)</em></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://host/" class="bare">http://host/</a></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>/webapps/root/WEB-INF/web.xml</code> <em>(reserved name)</em></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://host/" class="bare">http://host/</a></p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="configuring-specific-webapp-deployment">Configuring a Specific Web Application Deployment</h3>
<div class="paragraph">
<p>Using the Automatic Web Application Deployment model is quick and easy, but sometimes you might need to tune certain deployment properties (for example, you want to deploy with a context path that is not based on the file name, or you want to define a special database connection pool just for this web application).
You can use a <a href="#deployable-descriptor-file">Jetty Deployable Descriptor XML File</a> to accomplish such tuning.</p>
</div>
<div class="sect3">
<h4 id="deployable-descriptor-file">Jetty Deployable Descriptor XML File</h4>
<div class="paragraph">
<p>Jetty supports deploying Web Applications via XML files which will build an instance of a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html">ContextHandler</a> that Jetty can then deploy.</p>
</div>
</div>
<div class="sect3">
<h4 id="using-basic-descriptor-files">Using Basic Descriptor Files</h4>
<div class="paragraph">
<p>In a default Jetty installation, Jetty scans its <code>$JETTY_HOME/webapps</code> directory for context deployment descriptor files.
To deploy a web application using such a file, simply place the file in that directory.</p>
</div>
<div class="paragraph">
<p>The deployment descriptor file itself is an xml file that configures a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html"><code>WebAppContext</code></a> class.
For a basic installation only two properties need configured:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">war</dt>
<dd>
<p>The filesystem path to the web application file (or directory)</p>
</dd>
<dt class="hdlist1">contextPath</dt>
<dd>
<p>The context path to use for the web application</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For example, here is a descriptor file that deploys the file <code>/opt/myapp/myapp.war</code> to the context path <code>/wiki</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
&lt;Set name="war"&gt;/opt/myapp/myapp.war&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Both <code>SystemProperty</code> and <code>Property</code> elements can be used in the descriptor file.
For example, if the system property is set to <code>myapp.home=/opt/myapp</code>, the previous example can be rewritten as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the home path for an application needs altered, only the system property needs changed.
This is useful if the version of an app is frequently changed.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
To ensure your <code>web.xml</code> files are validated, you will need to set the <code>validateXml</code> attribute to true as described <a href="#jetty-xml-dtd">here.</a>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="configuring-advanced-descriptor-files">Configuring Advanced Descriptor Files</h4>
<div class="paragraph">
<p>Official documentation for the for the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html"><code>WebAppContext</code></a> class lists all the properties that can be set.
Here are some examples that configure advanced options in the descriptor file.</p>
</div>
<div class="paragraph">
<p>This first example tells Jetty not to expand the WAR file when deploying it.
This can help make it clear that users should not make changes to the temporary unpacked WAR because such changes do not persist, and therefore do not apply the next time the web application deploys.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
&lt;Set name="extractWAR"&gt;false&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The next example retrieves the JavaEE Servlet context and sets an initialization parameter on it.
The <code>setAttribute</code> method can also be used to set a Servlet context attribute.
However, since the <code>web.xml</code> for the web application is processed after the deployment descriptor, the <code>web.xml</code> values overwrite identically named attributes from the deployment descriptor.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
&lt;Get name="ServletContext"&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;myapp.config&lt;/Arg&gt;
&lt;Arg&gt;&lt;SystemProperty name="myapp.home"&gt;/config/app-config.xml&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Get&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following example sets a special <code>web.xml</code> override descriptor.
This descriptor is processed after the web application&#8217;s <code>web.xml</code>, so it may override identically named attributes.
This feature is useful when adding parameters or additional Servlet mappings without breaking open a packed WAR file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
&lt;Set name="overrideDescriptor"&gt;/opt/myapp/overlay-web.xml&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The next example configures not only the web application context, but also a database connection pool (see <a href="#jndi-datasource-examples">Datasource Examples</a>) that the application can then use.
If the <code>web.xml</code> does not include a reference to this data source, an override descriptor mechanism (as shown in the previous example) can be used to include it.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/wiki&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="myapp.home"/&gt;/myapp.war&lt;/Set&gt;
&lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.commons.dbcp.BasicDataSource"&gt;
&lt;Set name="driverClassName"&gt;org.some.Driver&lt;/Set&gt;
&lt;Set name="url"&gt;jdbc.url&lt;/Set&gt;
&lt;Set name="username"&gt;jdbc.user&lt;/Set&gt;
&lt;Set name="password"&gt;jdbc.pass&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are many other settings that can be changed in a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html"><code>WebAppContext</code></a>.
The <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html">javadoc</a> for <code>WebAppContext</code> is a good source of information.
Also see the documentation on <a href="#troubleshooting-zip-exceptions">avoiding zip file exceptions</a> for a description of <code>WebAppContext</code> settings that determine such things as whether or not the war is automatically unpacked during deployment, or whether certain sections of a webapp are copied to a temporary location.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-webapps">Deployment Processing of WebAppContexts</h3>
<div class="paragraph">
<p>Web applications require a certain amount of processing before they can go into service: they may need to be unpacked, a special classloader created for their jar files, <code>web.xml</code> and <code>web-fragment.xml</code> descriptors processed, and classes scanned for annotations amongst other things.
As web applications have become more complex, Jetty has added ways to assist with customization by either broadening or lessening the amount of processing that is done at deployment time.
This section will examine this processing and it can be tailored to fit individual needs.</p>
</div>
<div class="paragraph">
<p>If instead you&#8217;re looking for information on how to configure a specific <code>WebAppContext</code> - such as its context path, whether it should be unpacked or not - then you can find that in the section entitled <a href="#configuring-specific-webapp-deployment">Configuring a Specific WebApp Deployment</a>.</p>
</div>
<div class="sect3">
<h4 id="webapp-configurations">Configuration Classes</h4>
<div class="paragraph">
<p>As a webapp is being deployed, a series of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/Configuration.html">org.eclipse.jetty.webapp.Configuration</a> classes are applied to it, each one performing a specific function.
The ordering of these Configurations is significant as subsequent Configurations tend to build on information extracted or setup in foregoing Configurations.
These are the default list, in order, of Configurations that are applied to each <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html">org.eclipse.jetty.webapp.WebAppContex</a>t:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 1. Default Configuration classes</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebInfConfiguration.html">org.eclipse.jetty.webapp.WebInfConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Extracts war, orders jars and defines classpath</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebXmlConfiguration.html">org.eclipse.jetty.webapp.WebXmlConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Processes a WEB-INF/web.xml file</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/MetaInfConfiguration.html">org.eclipse.jetty.webapp.MetaInfConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Looks in container and webapp jars for META-INF/resources and
META-INF/web-fragment.xml</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/FragmentConfiguration.html">org.eclipse.jetty.webapp.FragmentConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Processes all discovered META-INF/web-fragment.xml files</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html">org.eclipse.jetty.webapp.JettyWebXmlConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Processes a WEB-INF/jetty-web.xml file</p></td>
</tr>
</tbody>
</table>
<div class="sect4">
<h5>Anatomy of a Configuration Class</h5>
<div class="paragraph">
<p>A Configuration class is called 5 times in different phases of the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html"><code>WebAppContext&#8217;s</code></a> lifecycle:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">preConfigure</dt>
<dd>
<p>As the <code>WebAppContext</code> is starting up this phase is executed.
The <code>Configuration</code> should discover any of the resources it will need during the subsequent phases.</p>
</dd>
<dt class="hdlist1">configure</dt>
<dd>
<p>This phase is where the work of the class is done, usually using the resources discovered during the <code>preConfigure</code> phase.</p>
</dd>
<dt class="hdlist1">postConfigure</dt>
<dd>
<p>This phase allows the <code>Configuration</code> to clear down any resources that may have been created during the previous 2 phases that are not needed for the lifetime of the <code>WebAppContext</code>.</p>
</dd>
<dt class="hdlist1">deconfigure</dt>
<dd>
<p>This phase occurs whenever a <code>WebAppContext</code> is being stopped and allows the Configuration to undo any resources/metadata that it created.
A <code>WebAppContext</code> should be able to be cleanly start/stopped multiple times without resources being held.</p>
</dd>
<dt class="hdlist1">destroy</dt>
<dd>
<p>This phase is called when a <code>WebAppContext</code> is actually removed from service.
For example, the war file associated with it is deleted from the $JETTY_HOME/webapps directory.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Each phase is called on each <code>Configuration</code> class in the order in which the <code>Configuration</code> class is listed.
Using the default <code>Configuration</code> classes as an example, <code>preConfigure()</code> will be called on <code>WebInfConfiguration</code>, <code>WebXmlConfiguration</code>, <code>MetaInfConfiguration</code>, <code>FragmentConfiguration</code> and then <code>JettyWebXmlConfiguration</code>.
The cycle begins again for the <code>configure()</code> phase and again for the <code>postConfigure()</code> phases.
The cycle is repeated <em>in reverse order</em> for the <code>deconfigure()</code> and eventually the <code>destroy()</code> phases.</p>
</div>
</div>
<div class="sect4">
<h5>Extending Container Support by Creating Extra Configurations</h5>
<div class="paragraph">
<p>As shown, there is a default set of Configurations that support basic deployment of a webapp.
JavaEE features such as JNDI and advanced servlet spec features such as annotations have not been mentioned.
Jetty&#8217;s philosophy is to allow the user to tailor the container exactly to their needs.
If these features are not needed, then Jetty does not pay the price for them - an important consideration because features such as annotations require extensive and time-consuming scanning of <code>WEB-INF/lib</code> jars.
As modern webapps may have scores of these jars, it can be a source of significant deployment delay.
We will see in the section <a href="#webapp-context-attributes">Other Configuration</a> another helpful webapp facility that Jetty provides for cutting down the time spent analyzing jars.</p>
</div>
<div class="paragraph">
<p>Jetty makes use of the flexibility of Configurations to make JNDI and annotation support pluggable.</p>
</div>
<div class="paragraph">
<p>Firstly, lets look at how Configurations help enable JNDI.</p>
</div>
<div class="sect5">
<h6 id="jndi-configuration-classes">Example: JNDI Configurations</h6>
<div class="paragraph">
<p>JNDI lookups within web applications require the container to hookup resources defined in the container&#8217;s environment to that of the web application.
To achieve that, we use 2 extra Configurations:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 2. JNDI Configuration classes</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/plus/webapp/EnvConfiguration.html">org.eclipse.jetty.plus.webapp.EnvConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Creates <code>java:comp/env</code> for the webapp, applies a <code>WEB-INF/jetty-env.xml</code> file</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/plus/webapp/PlusConfiguration.html">org.eclipse.jetty.plus.webapp.PlusConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Processes JNDI related aspects of <code>WEB-INF/web.xml</code> and hooks up naming entries</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>These configurations must be added in <em>exactly</em> the order shown above and should be inserted <em>immediately before</em> the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html">org.eclipse.jetty.webapp.JettyWebXmlConfiguration</a> class in the list of configurations.
To fully support JNDI additional configuration is required, full details of which can be found <a href="#jndi">here</a>.</p>
</div>
</div>
<div class="sect5">
<h6>Example: Annotation Configurations</h6>
<div class="paragraph">
<p>We need just one extra Configuration class to help provide servlet annotation scanning:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 3. Annotation Configuration classes</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/annotations.AnnotationConfiguration.html">org.eclipse.jetty.annotations.AnnotationConfiguration</a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Scan container and web app jars looking for @WebServlet, @WebFilter,
@WebListener etc</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>The above configuration class must be <em>inserted immediately before</em> the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/JettyWebXmlConfiguration.html">org.eclipse.jetty.webapp.JettyWebXmlConfiguration</a> class in the list of configurations.
To fully support annotations additional configuration is require, details of which can be found <a href="#webapp-context-attributes">below.</a></p>
</div>
</div>
</div>
<div class="sect4">
<h5>How to Set the List of Configurations</h5>
<div class="paragraph">
<p>You have a number of options for how to make Jetty use a different list of Configurations.</p>
</div>
<div class="sect5">
<h6>Setting the list directly on the WebAppContext</h6>
<div class="paragraph">
<p>If you have only one webapp that you wish to affect, this may be the easiest option.
You will, however, either need to have a context xml file that represents your web app, or you need to call the equivalent in code.
Let&#8217;s see an example of how we would add in the Configurations for both JNDI <em>and</em> annotations:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="jetty.base" default="."/&gt;/webapps/my-cool-webapp&lt;/Set&gt;
&lt;Set name="configurationClasses"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.WebInfConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.WebXmlConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.MetaInfConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.FragmentConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.plus.webapp.EnvConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.plus.webapp.PlusConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.annotations.AnnotationConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.JettyWebXmlConfiguration&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Of course, you can also use this method to reduce the Configurations applied to a specific <code>WebAppContext</code>.</p>
</div>
</div>
<div class="sect5">
<h6>Setting the list for all webapps via the Deployer</h6>
<div class="paragraph">
<p>If you use the <a href="#deployment-architecture">deployer</a>, you can set up the list of Configuration classes on the <a href="#default-web-app-provider">WebAppProvider</a>.
They will then be applied to each <code>WebAppContext</code> deployed by the deployer:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager"&gt;
&lt;Set name="contexts"&gt;
&lt;Ref refid="Contexts" /&gt;
&lt;/Set&gt;
&lt;Call id="webappprovider" name="addAppProvider"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.deploy.providers.WebAppProvider"&gt;
&lt;Set name="monitoredDirName"&gt;&lt;Property name="jetty.base" default="." /&gt;/webapps&lt;/Set&gt;
&lt;Set name="configurationClasses"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.WebInfConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.WebXmlConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.MetaInfConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.FragmentConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.plus.webapp.EnvConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.plus.webapp.PlusConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.annotations.AnnotationConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.webapp.JettyWebXmlConfiguration&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Adding or inserting to an existing list</h6>
<div class="paragraph">
<p>Instead of having to enumerate the list in its entirety, you can simply nominate classes that you want to add, and indicate whereabouts in the list you want them inserted.
Let&#8217;s look at an example of using this method to add in Configuration support for JNDI - as usual you can either do this in an xml file, or via equivalent code.
This example uses an xml file, in fact it is the <code>$JETTY_HOME/etc/jetty-plus.xml</code> file from the Jetty distribution:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;!-- =========================================================== --&gt;
&lt;!-- Add plus Configuring classes to all webapps for this Server --&gt;
&lt;!-- =========================================================== --&gt;
&lt;Call class="org.eclipse.jetty.webapp.Configuration$ClassList" name="setServerDefault"&gt;
&lt;Arg&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Call name="addAfter"&gt;
&lt;Arg name="afterClass"&gt;org.eclipse.jetty.webapp.FragmentConfiguration&lt;/Arg&gt;
&lt;Arg&gt;
&lt;Array type="String"&gt;
&lt;Item&gt;org.eclipse.jetty.plus.webapp.EnvConfiguration&lt;/Item&gt;
&lt;Item&gt;org.eclipse.jetty.plus.webapp.PlusConfiguration&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/Configuration.html">org.eclipse.jetty.webapp.Configuration.ClassList</a> class provides these methods for insertion:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">addAfter</dt>
<dd>
<p>Inserts the supplied list of <code>Configuration</code> class names after the given Configuration class name.</p>
</dd>
<dt class="hdlist1">addBefore</dt>
<dd>
<p>Inserts the supplied list of <code>Configuration</code> class names before the given Configuration class name.</p>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="webapp-context-attributes">Other Configuration</h4>
<div class="sect4">
<h5 id="container-include-jar-pattern">org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</h5>
<div class="paragraph">
<p>This is a <a href="#context_attributes">context attribute</a> that can be set on <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html">an org.eclipse.jetty.webapp.WebAppContext</a> to control which parts of the <em>container&#8217;s</em> classpath should be processed for things like annotations, <code>META-INF/resources</code>, <code>META-INF/web-fragment.xml</code> and <code>tlds</code> inside <code>META-INF</code>.</p>
</div>
<div class="paragraph">
<p>Normally, nothing from the container classpath will be included for processing.
However, sometimes you will need to include some.
For example, you may have some libraries that are shared amongst your webapps and thus you have put them into a <code>$JETTY_HOME/lib</code> directory.
The libraries contain annotations and therefore must be scanned.</p>
</div>
<div class="paragraph">
<p>The value of this attribute is a regexp that defines which <em>jars</em> and <em>class directories</em> from the container&#8217;s classpath should be examined.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example from a context xml file (although as always, you could have accomplished the same in code), which would match any jar whose name starts with "foo-" or "bar-", or a directory named "classes":</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern&lt;/Arg&gt;
&lt;Arg&gt;.*/foo-[^/]*\.jar$|.*/bar-[^/]*\.jar$|.*/classes/.*&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that the order of the patterns defines the ordering of the scanning of the jars or class directories.</p>
</div>
</div>
<div class="sect4">
<h5 id="web-inf-include-jar-pattern">org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern</h5>
<div class="paragraph">
<p>Similarly to the previous <a href="#context_attributes">context attribute</a>, this attribute controls which jars are processed for things like annotations, <code>META-INF/resources</code>, <code>META-INF/web-fragment.xml</code> and <code>tlds</code> in <code>META-INF</code>.
However, this attribute controls which jars from the <em>webapp&#8217;s</em> classpath (usually <code>WEB-INF/lib</code>) are processed.
This can be particularly useful when you have dozens of jars in <code>WEB-INF/lib</code>, but you know that only a few need to be scanned.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example in a xml file of a pattern that matches any jar that starts with <code>spring-</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern&lt;/Arg&gt;
&lt;Arg&gt;.*/spring-[^/]*\.jar$&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that the order of the patterns defines the ordering of the scanning of jar files.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="static-content-deployment">Configuring Static Content Deployment</h3>
<div class="paragraph">
<p>To serve purely static content, the Jetty Deployment Descriptor XML concepts and the internal <code>ResourceHandler</code> can be used.
Create a file called <code>scratch.xml</code> in the <code>${jetty.base}/webapps</code> directory and paste the following file contents in it.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.server.handler.ContextHandler"&gt;
&lt;Set name="contextPath"&gt;/scratch&lt;/Set&gt;
&lt;Set name="handler"&gt;
&lt;New class="org.eclipse.jetty.server.handler.ResourceHandler"&gt;
   &lt;Set name="resourceBase"&gt;/home/scratch&lt;/Set&gt;
&lt;Set name="directoriesListed"&gt;true&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is a very basic setup for serving static files.
For advanced static file serving, use the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlet/DefaultServlet.html">DefaultServlet</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="hot-deployment">Hot Deployment</h3>
<div class="paragraph">
<p>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&#8217;s <code>DeploymentManager</code> (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.</p>
</div>
<div class="paragraph">
<p>This behavior can be controlled by configuring <code>WebAppProvider</code> properties.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">monitoredDirName</dt>
<dd>
<p>The directory to scan for possible deployable Web Applications (or Deployment Descriptor XML files).</p>
</dd>
<dt class="hdlist1">scanInterval</dt>
<dd>
<p>Number of seconds between scans of the provided <code>monitoredDirName</code>.
A value of <code>0</code> disables the continuous hot deployment scan, Web Applications will be deployed on startup only.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The default location for this configuration is in the <code>${jetty.home}/etc/jetty-deploy.xml</code> file.
To modify it as part of the Jetty distribution, first enable the <code>deploy</code> module.
Once it is enabled, you can edit these properties in either the <code>$JETTY_BASE/start.d/deploy.ini</code> or <code>$JETTY_BASE/start.ini</code> file, depending on <a href="#start-vs-startd">how your implementation is configured.</a></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&lt;?xml version="1.0"?&gt;
# ---------------------------------------
# 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</code></pre>
</div>
</div>
<div class="paragraph">
<p>See <a href="#default-web-app-provider">Understanding the Default WebAppProvider</a> for more configuration details.</p>
</div>
<div class="paragraph">
<p>See also <a href="#deployment-architecture">Deployment Architecture</a> for detailed conceptual information.</p>
</div>
</div>
<div class="sect2">
<h3 id="deployment-architecture">Deployment Architecture</h3>
<div class="paragraph">
<p>Jetty is built around an extensible Deployment Manager architecture complete with formal LifeCycle for Web Applications going through it.</p>
</div>
<div class="paragraph">
<p>For Jetty to serve content (static or dynamic), a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html">ContextHandler</a> needs to be configured and added to Jetty in the appropriate location.
A pluggable <code>DeploymentManager</code> exists to make this process easier.
The Jetty distribution contains example <code>DeploymentManager</code> configurations to deploy WAR files found in a directory to Jetty, and to deploy Jetty context xml files into Jetty as well.</p>
</div>
<div class="paragraph">
<p>The <code>DeploymentManager</code> is the heart of the typical webapp deployment mechanism; it operates as a combination of an Application LifeCycle Graph, Application Providers that find and provide Applications into the Application LifeCycle Graph, and a set of bindings in the graph that control the deployment process.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/Jetty_DeployManager_DeploymentManager_Roles.png" alt="image" width="195"></span></p>
</div>
<div class="sect3">
<h4 id="udm-application-providers">Application Providers</h4>
<div class="paragraph">
<p>Before Jetty deploys an application, an <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/AppProvider.html"><code>AppProvider</code></a> identifies the App and then provides it to the <code>DeploymentManager</code>.
The main <code>AppProvider</code> with the Jetty distribution is the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/providers/WebAppProvider.html"><code>WebAppProvider</code>.</a></p>
</div>
</div>
<div class="sect3">
<h4 id="udm-application-lifecycle-graph">Application LifeCycle Graph</h4>
<div class="paragraph">
<p>The core feature of the <code>DeploymentManager</code> is the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/AppLifeCycle.html">Application LifeCycle Graph</a>.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/Jetty_DeployManager_AppLifeCycle-1.png" alt="image" width="340"></span></p>
</div>
<div class="paragraph">
<p>The nodes and edges of this graph are pre-defined in Jetty along the most common actions and states found.
These nodes and edges are not hardcoded; they can be adjusted and added to depending on need (for example, any complex requirements for added workflow, approvals, staging, distribution, coordinated deploys for a cluster or cloud, etc.).</p>
</div>
<div class="paragraph">
<p>New applications enter this graph at the Undeployed node, and the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/DeploymentManager.html#requestAppGoal(org.eclipse.jetty.deploy.App"><code>java.lang.String DeploymentManager.requestAppGoal(App,String)</code></a> method pushes them through the graph.</p>
</div>
</div>
<div class="sect3">
<h4 id="udm-lifecycle-bindings">LifeCycle Bindings</h4>
<div class="paragraph">
<p>A set of default <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/AppLifeCycle.Binding.html"><code>AppLifeCycle.Bindings</code></a> defines standard behavior, and handles deploying, starting, stopping, and undeploying applications.
If desired, custom <code>AppLifeCycle.Bindings</code> can be written and assigned anywhere on the Application LifeCycle graph.</p>
</div>
<div class="paragraph">
<p>Examples of new <code>AppLifeCycle.Binding</code> implementations that can be developed include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Validating the incoming application.</p>
</li>
<li>
<p>Preventing the deployment of known forbidden applications.</p>
</li>
<li>
<p>Submitting the installation to an application auditing service in a corporate environment.</p>
</li>
<li>
<p>Distributing the application to other nodes in the cluster or cloud.</p>
</li>
<li>
<p>Emailing owner/admin of change of state of the application.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>There are four default bindings:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/bindings/StandardDeployer.html"><code>StandardDeployer</code></a> — Deploys the ContextHandler into Jetty in the appropriate place.</p>
</li>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/bindings/StandardStarter.html"><code>StandardStarter</code></a> — Sets the ContextHandler to started and start accepting incoming requests.</p>
</li>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/bindings/StandardStopper.html"><code>StandardStopper</code></a> — Stops the ContextHandler and stops accepting incoming requests.</p>
</li>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/bindings/StandardUndeployer.html"><code>StandardUndeployer</code></a> — Removes the ContextHandler from Jetty.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/Jetty_DeployManager_DefaultAppLifeCycleBindings.png" alt="image" width="851"></span></p>
</div>
<div class="paragraph">
<p>A fifth, non-standard binding, called <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/bindings/DebugBinding.html">DebugBinding</a>, is also available for debugging reasons; it logs the various transitions through the Application LifeCycle.</p>
</div>
<div class="sect4">
<h5>Using GlobalWebappConfigBinding</h5>
<div class="paragraph">
<p>In addition to the LifeCycle bindings discussed above, there is also the <a href="https://www.eclipse.org/jetty/javadoc/current/org/eclipse/jetty/deploy/bindings/GlobalWebappConfigBinding.html"><code>GlobalWebappConfigBinding</code></a> which, when added to the <code>DeploymentManager</code> will apply an additional configuration XML file to each webapp that it deploys.
This can useful when setting server or system classes, or when defining <a href="#override-web-xml">override descriptors.</a>
This configuration XML file will be <em>in addition to</em> any context XML file that exists for the webapp; it will be applied <em>after</em> any context XML files but <em>before</em> the webapp is started.
The format for the XML file is the same as any context XML file and can be used to same parameters for a webapp.</p>
</div>
<div class="paragraph">
<p>To use this binding, you can either modify the existing <code>jetty-deploy.xml</code> which comes with the Jetty distribution (be sure to <a href="#startup-base-and-home">copy it to your $JETTY_BASE/etc directory first</a>), or by <a href="#custom-modules">creating a new module</a> file which calls to an additional XML file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;Call name="addLifeCycleBinding"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.deploy.bindings.GlobalWebappConfigBinding" &gt;
&lt;Set name="jettyXml"&gt;&lt;Property name="jetty.home" default="." /&gt;/etc/global-webapp-config.xml&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="default-web-app-provider">Understanding the Default WebAppProvider</h4>
<div class="paragraph">
<p>The <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/providers/WebAppProvider.html">WebAppProvider</a> is used for the deployment of Web Applications packaged as WAR files, expanded as a directory, or declared in a <a href="#deployable-descriptor-file">Jetty Deployable Descriptor XML File</a>.
It supports hot (re)deployment.</p>
</div>
<div class="paragraph">
<p>The basic operation of the <code>WebAppProvider</code> is to periodically scan a directory for deployables.
In the standard Jetty Distribution, this is configured in the <code>${jetty.home}/etc/jetty-deploy.xml</code> file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager"&gt;
&lt;Set name="contexts"&gt;
&lt;Ref refid="Contexts" /&gt;
&lt;/Set&gt;
&lt;Call id="webappprovider" name="addAppProvider"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.deploy.providers.WebAppProvider"&gt;
&lt;Set name="monitoredDirName"&gt;&lt;Property name="jetty.home" default="." /&gt;/webapps&lt;/Set&gt;
&lt;Set name="defaultsDescriptor"&gt;&lt;Property name="jetty.home" default="." /&gt;/etc/webdefault.xml&lt;/Set&gt;
&lt;Set name="scanInterval"&gt;1&lt;/Set&gt;
&lt;Set name="extractWars"&gt;true&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above configuration will create a <code>DeploymentManager</code> tracked as a Server LifeCycle Bean, with the following configuration.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">contexts</dt>
<dd>
<p>A passed in reference to the HandlerContainer into which the discovered webapps are deployed.
This is normally a reference that points to the <code>id="Contexts"</code> found in the <code>${jetty.home}/etc/jetty.xml</code> file, which itself is an instance of <code>ContextHandlerCollection</code>.</p>
</dd>
<dt class="hdlist1">monitoredDirName</dt>
<dd>
<p>The file path or URL to the directory to scan for web applications.</p>
<div class="literalblock">
<div class="content">
<pre>Scanning follows these rules:</pre>
</div>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>A base directory must exist.</p>
</li>
<li>
<p>Hidden Files (starting with <code>"."</code>) are ignored.</p>
</li>
<li>
<p>Directories with names ending in <code>".d"</code> are ignored.</p>
</li>
<li>
<p>Common CVS directories <code>"CVS"</code> and <code>"CVSROOT"</code> are ignored.</p>
</li>
<li>
<p>Any <code>*.war</code> files are considered <a href="#automatic-webapp-deployment">automatic deployables</a>.</p>
</li>
<li>
<p>Any <code>*.xml</code> files are considered <a href="#deployable-descriptor-file">context descriptor deployables</a>.</p>
</li>
<li>
<p>In the special case where both a WAR file and XML file exists for same base name, the XML file is assumed to configure and reference the WAR file (see <a href="#configuring-specific-webapp-deployment">Configuring a Specific Web Application Deployment</a>).
Since jetty-9.2.7, if either the WAR file or its corresponding XML file changes, the webapp will be redeployed.</p>
</li>
<li>
<p>A directory is considered to be deployable.</p>
</li>
<li>
<p>In the special case where both a Directory and WAR file of the same name exists, the WAR file is assumed to be an automatic deployable.</p>
</li>
<li>
<p>In the special case where both a Directory and XML file of the same name exists, the XML file is assumed to configure and reference the Directory.</p>
</li>
<li>
<p>All other directories are subject to automatic deployment.</p>
</li>
<li>
<p>If automatic deployment is used, and the special filename <code>root.war/ROOT.war</code> or directory name <code>root/ROOT</code> will result in a deployment to the <code>"/"</code> context path.</p>
</li>
</ol>
</div>
</dd>
<dt class="hdlist1">defaultsDescriptor</dt>
<dd>
<p>Specifies the default Servlet web descriptor to use for all Web Applications.
The intent of this descriptor is to include common configuration for the Web Application before the Web Application&#8217;s own <code>/WEB-INF/web.xml</code> is applied.
The <code>${jetty.home}/etc/webdefault.xml</code> that comes with the Jetty distribution controls the configuration of the JSP and Default servlets, along with MIME-types and other basic metadata.</p>
</dd>
<dt class="hdlist1">scanInterval</dt>
<dd>
<p>The period in seconds between sweeps of the <code>monitoredDirName</code> for changes: new contexts to deploy, changed contexts to redeploy, or removed contexts to undeploy.</p>
</dd>
<dt class="hdlist1">extractWars</dt>
<dd>
<p>If parameter is true, any packed WAR or zip files are first extracted to a temporary directory before being deployed.
This is advisable if there are uncompiled JSPs in the web apps.</p>
</dd>
<dt class="hdlist1">parentLoaderPriority</dt>
<dd>
<p>Parameter is a boolean that selects whether the standard Java <a href="#jetty-classloading">parent first delegation</a> is used or the <a href="#jetty-classloading">servlet specification webapp classloading priority</a>.
The latter is the default.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="quickstart-webapp">Quickstart Webapps</h3>
<div class="paragraph">
<p>The auto discovery features of the Servlet specification can make deployments slow and uncertain.
Auto discovery of Web Application configuration can be useful during the development of a webapp as it allows new features and frameworks to be enabled simply by dropping in a jar file.
However, for deployment, the need to scan the contents of many jars can have a significant impact of the start time of a webapp.</p>
</div>
<div class="paragraph">
<p>With the release of Jetty 9.2, a quickstart module was included which allows a webapp to be pre-scanned and preconfigured.
This means that all the scanning is done prior to deployment and all configuration is encoded into an effective <code>web.xml</code>, called <code>WEB-INF/quickstart-web.xml</code>, which can be inspected to understand what will be deployed before deploying.
Not only does the <code>quickstart-web.xml</code> contain all the discovered Servlets, Filters and Constraints, but it also encodes as context parameters all discovered:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>ServletContainerInitializers</p>
</li>
<li>
<p>HandlesTypes classes</p>
</li>
<li>
<p>Taglib Descriptors</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>With the quickstart mechanism, Jetty is able to entirely bypass all scanning and discovery modes and start a webapp in a predictable and fast way.
Tests have shown that webapps that took many seconds to scan and deploy can now be deployed in a few hundred milliseconds.</p>
</div>
<div class="sect3">
<h4>Setting up Quickstart</h4>
<div class="sect4">
<h5>Prerequisites</h5>
<div class="sect5">
<h6>Jetty Distribution</h6>
<div class="paragraph">
<p>In a standard Jetty distribution the quickstart module can be configured with the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar $JETTY_HOME/start.jar --add-to-start=quickstart</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Embedded</h6>
<div class="paragraph">
<p>In a Maven project you add a dependency on the artifact <code>jetty-quickstart</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;dependency&gt;
&lt;groupId&gt;org.eclipse.jetty&lt;/groupId&gt;
&lt;artifactId&gt;jetty-quickstart&lt;/artifactId&gt;
&lt;version&gt;10.0.0-SNAPSHOT&lt;/version&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuration</h5>
<div class="paragraph">
<p>Webapps need to be instances of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/quickstart/QuickStartWebApp.html"><code>org.eclipse.jetty.quickstart.QuickStartWebApp</code></a> rather than the normal <code>org.eclipse.jetty.webapp.WebAppContext</code>.</p>
</div>
<div class="paragraph">
<p><code>org.eclipse.jetty.quickstart.QuickStartWebApp</code> instances offer the same setters as the familiar <code>org.eclipse.jetty.webapp.WebAppContext</code>, with the addition of:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">autoPreconfigure</dt>
<dd>
<p>(true/false).
If true, the first time the webapp is run, the WEB-INF/quickstart-web.xml is generated BEFORE the webapp is deployed.
Subsequent runs use the previously generated quickstart file.</p>
</dd>
<dt class="hdlist1">originAttribute</dt>
<dd>
<p>The name of an attribute to insert into the generated elements in quickstart-web.xml that gives the origin of the element.
By default it is <code>origin</code>.</p>
</dd>
<dt class="hdlist1">generateOrigin</dt>
<dd>
<p>(true/false).
By default it is <code>false</code>.
If true, the origin attribute will be inserted into each element in quickstart-web.xml.
Note that origin attributes will also be generated if debug log level is enabled.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you are using Spring-Boot you must set <code>generateOrigin</code> to true.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>The origin is either a descriptor eg web.xml,web-fragment.xml,override-web.xml file, or an annotation eg @WebServlet.
For xml validation each attribute must be unique, and therefore an integer counter is appended to each value.
Some examples of elements with origin attribute information are:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;listener origin="DefaultsDescriptor(file:///path/to/distro/etc/webdefault.xml):21"&gt;
&lt;listener origin="WebDescriptor(file:///path/to/base/webapps/test-spec/WEB-INF/web.xml):22"&gt;
&lt;servlet-class origin="FragmentDescriptor(jar:file:///path/to/base/webapps/test-spec/WEB-INF/lib/test-web-fragment.jar!/META-INF/web-fragment.xml):23"&gt;
&lt;servlet-class origin="@WebServlet(com.acme.test.TestServlet):24"&gt;</code></pre>
</div>
</div>
<div class="sect5">
<h6>In XML</h6>
<div class="paragraph">
<p>If a web application already has a context xml file, eg <code>webapps/myapp.xml</code> file, simply change the class in the <code>Configure</code> element.
Otherwise, create a context xml file with the following information (in addition to the usual setting of contextPath, war etc):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.quickstart.QuickStartWebApp"&gt;
&lt;Set name="autoPreconfigure"&gt;true&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>In Code</h6>
<div class="paragraph">
<p>Create an instance of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/quickstart/QuickStartWebApp.html"><code>org.eclipse.jetty.quickstart.QuickStartWebApp</code></a> rather than the normal <code>org.eclipse.jetty.webapp.WebAppContext</code>. You then use the QuickStartWebApp instance in exactly the same way that you would a WebAppContext.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s a snippet:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java"> QuickStartWebApp webapp = new QuickStartWebApp();
webapp.setAutoPreconfigure(true);</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Pre-generating the quickstart-web.xml file</h6>
<div class="paragraph">
<p>Rather than use the <code>autoPreconfigure</code> feature of the QuickStartWebApp - which lazily generates the <code>quickstart-web.xml</code> file - you can eagerly pre-generate it for an existing war by invoking as a main class <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/quickstart/PreconfigureQuickStartWar.html"><code>org.eclipse.jetty.quickstart.PreconfigureQuickStartWar</code></a>.
Note that you will need to provide all necessary jetty jars on the command line classpath.
This will unpack the war if necessary, and create the <code>quickstart-web.xml</code> before the first deployment:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -cp [jetty classpath] org.eclipse.jetty.quickstart.PreconfigureQuickStartWar myapp.war</code></pre>
</div>
</div>
<div class="paragraph">
<p>Run the class with no arguments to see other runtime options.</p>
</div>
<div class="paragraph">
<p>Alternatively, you could use the <a href="#get-up-and-running">Jetty Maven Plugin</a> goal <a href="#jetty-effective-web-xml"><code>jetty:effective-web-xml</code></a>: this will generate quickstart information, but print it to stderr.
The goal provides a configuration option to save the output to a file, which you can then copy into your webapp&#8217;s WEB-INF dir.
Note that as the Jetty Maven Plugin is a general tool for running webapps, it may have more jars on its classpath than are needed by your application, and thus may generate extra quickstart information: we recommend that you use this goal only as a quick guide to the type of information that quickstart generates.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Avoiding TLD Scans with precompiled JSPs</h4>
<div class="paragraph">
<p>Of course precompiling JSPs is an excellent way to improve the start time of a web application.
As of Jetty 9.2 the Apache Jasper JSP implementation has been used and has been augmented to allow the TLD scan to be skipped.
This can be done by adding a <code>context-param</code> to the <code>web.xml</code> file (this is done automatically by the Jetty Maven JSPC plugin):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;context-param&gt;
&lt;param-name&gt;org.eclipse.jetty.jsp.precompiled&lt;/param-name&gt;
&lt;param-value&gt;true&lt;/param-value&gt;
&lt;/context-param&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>Bypassing start.jar</h4>
<div class="paragraph">
<p>The Jetty <code>start.jar</code> mechanism is a very powerful and flexible mechanism for constructing a <code>classpath</code> and executing a configuration encoded in Jetty XML format.
However, this mechanism does take some time to build the <code>classpath</code>.
The start.jar mechanism can be bypassed by using the <code>–dry-run</code> option to generate and reuse a complete command line to start Jetty at a later time:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ RUN=$(java -jar $JETTY_HOME/start.jar --dry-run)
$ eval $RUN</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that <code>--dry-run</code> may create a properties file in the temp directory and include it on the generated command line.
If so, then a copy of the temporary properties file should be taken and the command line updated with it&#8217;s new persistent location.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-connectors">Configuring Jetty Connectors</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter discusses various options for configuring Jetty connectors.</p>
</div>
<div class="sect2">
<h3 id="jetty-connectors">Connector Configuration Overview</h3>
<div class="paragraph">
<p>Connectors are the mechanism through which Jetty accepts network connections for various protocols.
Configuring a connector is a combination of configuring the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Network parameters on the connector itself (for example: the listening port).</p>
</li>
<li>
<p>Services the connector uses (for example: executors, schedulers).</p>
</li>
<li>
<p>Connection factories that instantiate and configure the protocol for an accepted connection.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Typically connectors require very little configuration aside from setting the listening port, and enabling <code>X-Forwarded-For</code> customization when applicable.
Additional settings, including construction your own constructor Jetty XML files, are for expert configuration only.</p>
</div>
<div class="sect3">
<h4>Enabling Connectors</h4>
<div class="paragraph">
<p>Out of the box, Jetty provides several <a href="#startup-modules">modules</a> for enabling different types of connectors, from HTTP to HTTPS, HTTP/2, and others.
If you startup Jetty with the <code>--list-modules=connector</code> command, you can see a list of all available connector modules:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java -jar $JETTY_HOME/start.jar --list-modules=connector
Available Modules:
==================
tags: [connector]
Modules for tag 'connector':
----------------------------
Module: acceptratelimit
: Enable a server wide accept rate limit
Tags: connector
Depend: server
XML: etc/jetty-acceptratelimit.xml
Module: connectionlimit
: Enable a server wide connection limit
Tags: connector
Depend: server
XML: etc/jetty-connectionlimit.xml
Module: http
: Enables a HTTP connector on the server.
: By default HTTP/1 is support, but HTTP2C can
: be added to the connector with the http2c module.
Tags: connector, http
Depend: server
XML: etc/jetty-http.xml
Module: http-forwarded
: Adds a forwarded request customizer to the HTTP Connector
: to process forwarded-for style headers from a proxy.
Tags: connector
Depend: http
XML: etc/jetty-http-forwarded.xml
Module: http2
: Enables HTTP2 protocol support on the TLS(SSL) Connector,
: using the ALPN extension to select which protocol to use.
Tags: connector, http2, http, ssl
Depend: ssl, alpn
LIB: lib/http2/*.jar
XML: etc/jetty-http2.xml
Module: http2c
: Enables the HTTP2C protocol on the HTTP Connector
: The connector will accept both HTTP/1 and HTTP/2 connections.
Tags: connector, http2, http
Depend: http
LIB: lib/http2/*.jar
XML: etc/jetty-http2c.xml
Module: https
: Adds HTTPS protocol support to the TLS(SSL) Connector
Tags: connector, https, http, ssl
Depend: ssl
Optional: http-forwarded, http2
XML: etc/jetty-https.xml
Module: proxy-protocol-ssl
: Enables the Proxy Protocol on the TLS(SSL) Connector.
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows a Proxy operating in TCP mode to transport
: details of the proxied connection to the server.
: Both V1 and V2 versions of the protocol are supported.
Tags: connector, ssl
Depend: ssl
XML: etc/jetty-proxy-protocol-ssl.xml
Module: ssl
: Enables a TLS(SSL) Connector on the server.
: This may be used for HTTPS and/or HTTP2 by enabling
: the associated support modules.
Tags: connector, ssl
Depend: server
XML: etc/jetty-ssl.xml
XML: etc/jetty-ssl-context.xml
Module: unixsocket
: Enables a Unix Domain Socket Connector that can receive
: requests from a local proxy and/or SSL offloader (eg haproxy) in either
: HTTP or TCP mode. Unix Domain Sockets are more efficient than
: localhost TCP/IP connections as they reduce data copies, avoid
: needless fragmentation and have better dispatch behaviours.
: When enabled with corresponding support modules, the connector can
: accept HTTP, HTTPS or HTTP2C traffic.
Tags: connector
Depend: server
LIB: lib/jetty-unixsocket-${jetty.version}.jar
LIB: lib/jnr/*.jar
XML: etc/jetty-unixsocket.xml
Module: unixsocket-forwarded
: Adds a forwarded request customizer to the HTTP configuration used
: by the Unix Domain Socket connector, for use when behind a proxy operating
: in HTTP mode that adds forwarded-for style HTTP headers. Typically this
: is an alternate to the Proxy Protocol used mostly for TCP mode.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-forwarded.xml
Module: unixsocket-http
: Adds a HTTP protocol support to the Unix Domain Socket connector.
: It should be used when a proxy is forwarding either HTTP or decrypted
: HTTPS traffic to the connector and may be used with the
: unix-socket-http2c modules to upgrade to HTTP/2.
Tags: connector, http
Depend: unixsocket
XML: etc/jetty-unixsocket-http.xml
Module: unixsocket-http2c
: Adds a HTTP2C connetion factory to the Unix Domain Socket Connector
: It can be used when either the proxy forwards direct
: HTTP/2C (unecrypted) or decrypted HTTP/2 traffic.
Tags: connector, http2
Depend: unixsocket-http
LIB: lib/http2/*.jar
XML: etc/jetty-unixsocket-http2c.xml
Module: unixsocket-proxy-protocol
: Enables the proxy protocol on the Unix Domain Socket Connector
: http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt
: This allows information about the proxied connection to be
: efficiently forwarded as the connection is accepted.
: Both V1 and V2 versions of the protocol are supported and any
: SSL properties may be interpreted by the unixsocket-secure
: module to indicate secure HTTPS traffic. Typically this
: is an alternate to the forwarded module.
Tags: connector
Depend: unixsocket
XML: etc/jetty-unixsocket-proxy-protocol.xml
Module: unixsocket-secure
: Enable a secure request customizer on the HTTP Configuration
: used by the Unix Domain Socket Connector.
: This looks for a secure scheme transported either by the
: unixsocket-forwarded, unixsocket-proxy-protocol or in a
: HTTP2 request.
Tags: connector
Depend: unixsocket-http
XML: etc/jetty-unixsocket-secure.xml
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>To enable a connector, simply activate the associated module.
Below is an example of activating both the <code>http</code> and <code>https</code> modules in a fresh <a href="#startup-base-and-home">Jetty base</a> using the <a href="#start-vs-startd">start.d directory</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase] java -jar $JETTY_HOME/start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
[mybase] java -jar $JETTY_HOME/start.jar --add-to-start=http,https
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : http initialized in ${jetty.base}/start.d/http.ini
INFO : https initialized in ${jetty.base}/start.d/https.ini
INFO : ssl transitively enabled, ini template available with --add-to-start=ssl
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
INFO : Base directory was modified
[mybase] tree
.
├── etc
│   └── keystore
└── start.d
├── http.ini
└── https.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the <code>http</code> and <code>https</code> modules were activated, so too were any modules they were dependent on, in this case <code>server</code> and <code>ssl</code>, as well as any dependencies for those modules, such as the <code>etc</code> and <code>ketystore</code> directories for <code>ssl</code>.</p>
</div>
<div class="paragraph">
<p>At this point the server has been configured with connectors for both HTTP and HTTPS and can be started:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase] java -jar $JETTY_HOME/start.jar
2017-08-31 10:19:58.855:INFO::main: Logging initialized @372ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:19:59.076:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2017-08-31 10:19:59.125:INFO:oejs.AbstractConnector:main: Started ServerConnector@421e98e0{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2017-08-31 10:19:59.150:INFO:oejus.SslContextFactory:main: x509=X509@5315b42e(jetty,h=[jetty.eclipse.org],w=[]) for SslContextFactory@2ef9b8bc(file:///Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase/etc/keystore,file:///Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase/etc/keystore)
2017-08-31 10:19:59.151:INFO:oejus.SslContextFactory:main: x509=X509@5d624da6(mykey,h=[],w=[]) for SslContextFactory@2ef9b8bc(file:///Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase/etc/keystore,file:///Users/staff/installs/repository/jetty-distribution-10.0.0-SNAPSHOT/mybase/etc/keystore)
2017-08-31 10:19:59.273:INFO:oejs.AbstractConnector:main: Started ServerConnector@2b98378d{SSL,[ssl, http/1.1]}{0.0.0.0:8443}
2017-08-31 10:19:59.274:INFO:oejs.Server:main: Started @791ms</code></pre>
</div>
</div>
<div class="paragraph">
<p>When modules are enabled, they are loaded with several default options.
These can be changed by editing the associated module ini file in the <code>start.d</code> directory (or the associated lines in <code>server.ini</code> if your implementation does not use <code>start.d</code>).
For example, if we examine the <code>http.ini</code> file in our <code>start.d</code> directory created above, we will see the following settings:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: http
# Enables a HTTP connector on the server.
# By default HTTP/1 is support, but HTTP2C can
# be added to the connector with the http2c module.
# ---------------------------------------
--module=http
### HTTP Connector Configuration
## Connector host/address to bind to
# jetty.http.host=0.0.0.0
## Connector port to listen on
# jetty.http.port=8080
## Connector idle timeout in milliseconds
# jetty.http.idleTimeout=30000
## Number of acceptors (-1 picks default based on number of cores)
# jetty.http.acceptors=-1
## Number of selectors (-1 picks default based on number of cores)
# jetty.http.selectors=-1
## ServerSocketChannel backlog (0 picks platform default)
# jetty.http.acceptorQueueSize=0
## Thread priority delta to give to acceptor threads
# jetty.http.acceptorPriorityDelta=0
## HTTP Compliance: RFC7230, RFC2616, LEGACY
# jetty.http.compliance=RFC7230</code></pre>
</div>
</div>
<div class="paragraph">
<p>To make a change to these settings, uncomment the line (by removing the #) and change the property to the desired value.
For example, if you wanted to change the HTTP port to 5231, you would edit the line as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">...
## Connector port to listen on
jetty.http.port=5231
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now when the server is started, HTTP connections will enter on port 5231:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase] java -jar ../start.jar
2017-08-31 10:31:32.955:INFO::main: Logging initialized @366ms to org.eclipse.jetty.util.log.StdErrLog
2017-08-31 10:31:33.109:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2017-08-31 10:31:33.146:INFO:oejs.AbstractConnector:main: Started ServerConnector@2ef9b8bc{HTTP/1.1,[http/1.1]}{0.0.0.0:5231}
...
2017-08-31 10:31:33.263:INFO:oejs.Server:main: Started @675ms</code></pre>
</div>
</div>
<div class="paragraph">
<p>Every module has their own set of configuration options, and reviewing them all is recommended.
For additional information on the module system, please refer to our documentation on <a href="#startup-modules">Startup Modules</a>.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Editing these module files is the recommended way to edit the configuration of your server.
Making changes to the associated Jetty XML file for connectors is <strong>not</strong> recommended, and is for advanced users only.
If you do wish to edit Jetty XML, please see our section on managing <a href="#">Jetty Home and Jetty Base</a> to ensure your Jetty Home remains a standard of truth for your implementation.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Limiting Connections</h4>
<div class="paragraph">
<p>Jetty also provides the means by which to limit connections to the server and/or contexts.
This is provided by two different modules in the distribution.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>connectionlimit</code></dt>
<dd>
<p>Applies a limit to the number of connections.
If this limit is exceeded, new connections are suspended for the time specified (in milliseconds).</p>
</dd>
<dt class="hdlist1"><code>acceptratelimit</code></dt>
<dd>
<p>Limits the rate at which new connections are accepted.
If this limit is exceeded, new connections are suspended for the time specified (in milliseconds).</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>As with the modules listed above, these can be enabled by adding <code>--add-to-start=&lt;module-name&gt;</code> to the command line.</p>
</div>
</div>
<div class="sect3">
<h4>Advanced Configuration</h4>
<div class="paragraph">
<p>Jetty primarily uses a single connector type called <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html">ServerConnector</a>.</p>
</div>
<div class="paragraph">
<p>Prior to Jetty 9, the type of the connector specified both the protocol and the implementation used; for example, selector-based non blocking I/O vs blocking I/O, or SSL connector vs non-SSL connector.
Jetty 9 has a single selector-based non-blocking I/O connector, and a collection of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ConnectionFactory.html"><code>ConnectionFactories</code></a> now configure the protocol on the connector.</p>
</div>
<div class="paragraph">
<p>The standard Jetty distribution comes with the following Jetty XML files that create and configure connectors; you should examine them as you read this section:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-http.xml"><code>jetty-http.xml</code></a></dt>
<dd>
<p>Instantiates a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> that accepts HTTP connections (that may be upgraded to WebSocket connections).</p>
</dd>
<dt class="hdlist1"><a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-ssl.xml"><code>jetty-ssl.xml</code></a></dt>
<dd>
<p>Instantiates a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> that accepts SSL/TLS connections.
On it&#8217;s own, this connector is not functional and requires one or more of the following files to also be configured to add <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ConnectionFactory.html"><code>ConnectionFactories</code></a> to make the connector functional.</p>
</dd>
<dt class="hdlist1"><a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-https.xml"><code>jetty-https.xml</code></a></dt>
<dd>
<p>Adds a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/HttpConnectionFactory.html"><code>HttpConnectionFactory</code></a> to the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> configured by <code>jetty-ssl.xml</code> which combine to provide support for HTTPS.</p>
</dd>
<dt class="hdlist1"><a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-http-forwarded.xml"><code>jetty-http-forwarded.xml</code></a></dt>
<dd>
<p>Adds a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ForwardedRequestCustomizer.html"><code>ForwardedRequestCustomizer</code></a>to the HTTP Connector to process forwarded-for style headers from a proxy.</p>
</dd>
<dt class="hdlist1"><a href="https://github.com/eclipse/jetty.project/tree/master/jetty-http2/http2-server/src/main/config/etc/jetty-http2.xml"><code>jetty-http2.xml</code></a></dt>
<dd>
<p>Adds a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/http2/server/HTTP2ServerConnectionFactory.html"><code>Http2ServerConnectionFactory</code></a> to the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> configured by <code>jetty-ssl.xml</code> to support the http2 protocol.</p>
</dd>
<dt class="hdlist1"><a href="https://github.com/eclipse/jetty.project/tree/master/jetty-alpn/jetty-alpn-server/src/main/config/etc/jetty-alpn.xml"><code>jetty-alpn.xml</code></a></dt>
<dd>
<p>Adds an <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/alpn/server/ALPNServerConnectionFactory.html"><code>ALPNServerConnectionFactory</code></a> to the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> configured by <code>jetty-ssl.xml</code> which allows the one SSL connector to support multiple protocols with the ALPN extension used to select the protocol to be used for each connection.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4>Constructing a ServerConnector</h4>
<div class="paragraph">
<p>The services a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> instance uses are set by constructor injection and once instantiated cannot be changed.
Many of the services may be defaulted with null or 0 values so that a reasonable default is used, thus for most purposes only the Server and the connection factories need to be passed to the connector constructor. In Jetty XML (that is, in <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-http.xml"><code>jetty-http.xml</code></a>) you can do this by:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Arg name="factories"&gt;
&lt;Array type="org.eclipse.jetty.server.ConnectionFactory"&gt;
&lt;!-- insert one or more factories here --&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;!-- set connector fields here --&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can see the other arguments that can be passed when constructing a <code>ServerConnector</code> in the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html#ServerConnector%28org.eclipse.jetty.server.Server,%20java.util.concurrent.Executor,%20org.eclipse.jetty.util.thread.Scheduler,%20org.eclipse.jetty.io.ByteBufferPool,%20int,%20int,%20org.eclipse.jetty.server.ConnectionFactory&#8230;&#8203;%29">Javadoc</a>.
Typically the defaults are sufficient for almost all deployments.</p>
</div>
</div>
<div class="sect3">
<h4 id="jetty-connectors-network-settings">Network Settings</h4>
<div class="paragraph">
<p>You can configure connector network settings by calling setters on the connector before it is started.
For example, you can set the port with the Jetty XML:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Arg name="factories"&gt;&lt;!-- insert one or more factories here --&gt;&lt;/Arg&gt;
&lt;Set name="port"&gt;8080&lt;/Set&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Values in Jetty XML can also be parameterized so that they may be passed from property files or set on the command line.
Thus typically the port is set within Jetty XML, but uses the <code>Property</code> element to be customizable:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Arg name="factories"&gt;&lt;!-- insert one or more factories here --&gt;&lt;/Arg&gt;
&lt;Set name="port"&gt;&lt;Property name="jetty.http.port" default="8080"/&gt;&lt;/Set&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The network settings available for configuration on the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> include:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 4. Connector Configuration</caption>
<colgroup>
<col style="width: 22%;">
<col style="width: 78%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">host</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The network interface this connector binds to as an IP address or a hostname.
If null or 0.0.0.0, bind to all interfaces.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">port</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The configured port for the connector or 0 a random available port may be used (selected port available via <code>getLocalPort()</code>).</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">idleTimeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The time in milliseconds that the connection can be idle before it is closed.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">defaultProtocol</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The name of the default protocol used to select a <code>ConnectionFactory</code> instance. This defaults to the first <code>ConnectionFactory</code> added to the connector.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stopTimeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The time in milliseconds to wait before gently stopping a connector.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">acceptQueueSize</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The size of the pending connection backlog.
The exact interpretation is JVM and operating system specific and you can ignore it.
Higher values allow more connections to wait pending an acceptor thread.
Because the exact interpretation is deployment dependent, it is best to keep this value as the default unless there is a specific connection issue for a specific OS that you need to address.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">reuseAddress</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allow the server socket to be rebound even if in <a href="http://www.ssfnet.org/Exchange/tcp/tcpTutorialNotes.html">TIME_WAIT</a>.
For servers it is typically OK to leave this as the default true.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="jetty-connectors-http-configuration">HTTP Configuration</h4>
<div class="paragraph">
<p>The <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/HttpConfiguration.html"><code>HttpConfiguration</code></a> class holds the configuration for <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/HttpChannel.html"><code>HttpChannel</code></a>s, which you can create 1:1 with each HTTP connection or 1:n on a multiplexed HTTP/2 connection.
Thus a <code>HttpConfiguration</code> object is injected into both the HTTP and HTTP/2 connection factories.
To avoid duplicate configuration, the standard Jetty distribution creates the common <code>HttpConfiguration</code> instance in <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty.xml"><code>jetty.xml</code></a>, which is a <code>Ref</code> element then used in <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-http.xml"><code>jetty-http.xml</code></a>, <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-https.xml"><code>jetty-https.xml</code></a> and in <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-http2/http2-server/src/main/config/etc/jetty-http2.xml"><code>jetty-http2.xml</code></a>.</p>
</div>
<div class="paragraph">
<p>A typical configuration of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/HttpConfiguration.html">HttpConfiguration</a> is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration"&gt;
&lt;Set name="secureScheme"&gt;https&lt;/Set&gt;
&lt;Set name="securePort"&gt;&lt;Property name="jetty.ssl.port" default="8443" /&gt;&lt;/Set&gt;
&lt;Set name="outputBufferSize"&gt;32768&lt;/Set&gt;
&lt;Set name="requestHeaderSize"&gt;8192&lt;/Set&gt;
&lt;Set name="responseHeaderSize"&gt;8192&lt;/Set&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This example HttpConfiguration may be used by reference to the ID &#8220;httpConfig&#8221;:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Call name="addConnector"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Arg name="factories"&gt;
&lt;Array type="org.eclipse.jetty.server.ConnectionFactory"&gt;
&lt;Item&gt;
&lt;New class="org.eclipse.jetty.server.HttpConnectionFactory"&gt;
&lt;Arg name="config"&gt;&lt;Ref refid="httpConfig" /&gt;&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;!-- ... --&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This same <code>httpConfig</code> is referenced by the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/SecuredRedirectHandler.html"><code>SecuredRedirectHandler</code></a> when redirecting secure requests.
Please note that if your <code>httpConfig</code> does not include a <code>secureScheme</code> or <code>securePort</code> or there is no <code>HttpConfiguration</code> present these types of secured requests will be returned a <code>403</code> error.</p>
</div>
<div class="paragraph">
<p>For SSL-based connectors (in <code>jetty-https.xml</code> and <code>jetty-http2.xml</code>), the common &#8220;httpConfig&#8221; instance is used as the basis to create an SSL specific configuration with ID &#8220;sslHttpConfig&#8221;:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="sslHttpConfig" class="org.eclipse.jetty.server.HttpConfiguration"&gt;
&lt;Arg&gt;&lt;Ref refid="httpConfig"/&gt;&lt;/Arg&gt;
&lt;Call name="addCustomizer"&gt;
&lt;Arg&gt;&lt;New class="org.eclipse.jetty.server.SecureRequestCustomizer"/&gt;&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This adds a <code>SecureRequestCustomizer</code> which adds SSL Session IDs and certificate information as request attributes.</p>
</div>
</div>
<div class="sect3">
<h4>SSL Context Configuration</h4>
<div class="paragraph">
<p>The SSL/TLS connectors for HTTPS and HTTP/2 require a certificate to establish a secure connection.
Jetty holds certificates in standard JVM keystores and are configured as keystore and truststores on a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/ssl/SslContextFactory.Server.html"><code>SslContextFactory.Server</code></a> instance that is injected into an <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/SslConnectionFactory.html"><code>SslConnectionFactory</code></a> instance.
An example using the keystore distributed with Jetty (containing a self signed test certificate) is in <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-server/src/main/config/etc/jetty-https.xml"><code>jetty-https.xml</code></a>.
Read more about SSL keystores in <a href="#configuring-ssl">Configuring SSL</a>.</p>
</div>
</div>
<div class="sect3">
<h4>Proxy / Load Balancer Connection Configuration</h4>
<div class="paragraph">
<p>Often a Connector needs to be configured to accept connections from an intermediary such as a Reverse Proxy and/or Load Balancer deployed in front of the server.
In such environments, the TCP/IP connection terminating on the server does not originate from the client, but from the intermediary, so that the Remote IP and port number can be reported incorrectly in logs and in some circumstances the incorrect server address and port may be used.</p>
</div>
<div class="paragraph">
<p>Thus Intermediaries typically implement one of several de facto standards to communicate to the server information about the original client connection terminating on the intermediary.
Jetty supports the <code>X-Forwarded-For</code> header and the <a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">Proxy Protocol</a> mechanisms as described below.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The XML files in the Jetty distribution contain commented out examples of both the <code>X-Forwarded-For</code> and <a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">Proxy Protocol</a> mechanisms.
When using those examples, it is recommended that the XML in the Jetty distribution is not edited.
Rather the files should be copied into a Jetty base directory and then modified.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect4">
<h5>X-Forward-for Configuration</h5>
<div class="paragraph">
<p>The <code>X-Forwarded-for</code> header and associated headers are a de facto standard where intermediaries add HTTP headers to each request they forward to describe the originating connection.
These headers can be interpreted by an instance of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ForwardedRequestCustomizer.html"><code>ForwardedRequestCustomizer</code></a> which can be added to a <code>HttpConfiguration</code> as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration"&gt;
&lt;Set name="outputBufferSize"&gt;32768&lt;/Set&gt;
&lt;Set name="requestHeaderSize"&gt;8192&lt;/Set&gt;
&lt;Set name="responseHeaderSize"&gt;8192&lt;/Set&gt;
&lt;Call name="addCustomizer"&gt;
&lt;Arg&gt;&lt;New class="org.eclipse.jetty.server.ForwardedRequestCustomizer"/&gt;&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Proxy Protocol</h5>
<div class="paragraph">
<p>The <a href="http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt">Proxy Protocol</a> is the <em>de facto</em> standard created by HAProxy and used by environments such as Amazon Elastic Cloud.
This mechanism is independent of any protocol, so it can be used for HTTP2, TLS etc.
The information about the client connection is sent as a small data frame on each newly established connection.
In Jetty, this protocol can be handled by the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ProxyConnectionFactory.html"><code>ProxyConnectionFactory</code></a> which parses the data frame and then instantiates the next <code>ConnectionFactory</code> on the connection with an end point that has been customized with the data obtained about the original client connection.
The connection factory can be added to any <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ServerConnector.html"><code>ServerConnector</code></a> and should be the first <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/ConnectionFactory.html"><code>ConnectionFactory</code></a>.</p>
</div>
<div class="paragraph">
<p>An example of adding the factory to a HTTP connector is shown below:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Call name="addConnector"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Arg name="factories"&gt;
&lt;Array type="org.eclipse.jetty.server.ConnectionFactory"&gt;
&lt;Item&gt;
&lt;New class="org.eclipse.jetty.server.ProxyConnectionFactory"/&gt;
&lt;/Item&gt;
&lt;Item&gt;
&lt;New class="org.eclipse.jetty.server.HttpConnectionFactory"&gt;
&lt;Arg name="config"&gt;&lt;Ref refid="httpConfig" /&gt;&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;Set name="host"&gt;&lt;Property name="jetty.host" /&gt;&lt;/Set&gt;
&lt;Set name="port"&gt;&lt;Property name="jetty.http.port" default="80" /&gt;&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-ssl">Configuring SSL/TLS</h3>
<div class="paragraph">
<p>This document provides an overview of how to configure SSL and TLS for Jetty.</p>
</div>
<div class="sect3">
<h4 id="configuring-jetty-for-ssl">Configuring Jetty for SSL</h4>
<div class="paragraph">
<p>To configure Jetty for SSL, complete the tasks in the following sections:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#generating-key-pairs-and-certificates">Generating Key Pairs and Certificates</a></p>
</li>
<li>
<p><a href="#requesting-trusted-certificate">Requesting a Trusted Certificate</a></p>
</li>
<li>
<p><a href="#loading-keys-and-certificates">Loading Keys and Certificates</a></p>
</li>
<li>
<p><a href="#configuring-sslcontextfactory">Configuring the Jetty SslContextFactory</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="tls-and-ssl-versions">TLS and SSL versions</h4>
<div class="paragraph">
<p>Which browser/OS supports which protocols can be <a href="https://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers">found on Wikipedia</a>.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>TLS v1.2: The protocol which should be used wherever possible.
All CBC based ciphers are supported since Java 7, the new GCM modes are supported since Java 8.</p>
</li>
</ul>
</div>
<div class="sect4">
<h5>Older Protocols</h5>
<div class="paragraph">
<p>TLS v1.0, v1.1 and SSL v3 are no longer supported by default. If your Jetty implementation requires these protocols for legacy support, they can be enabled manually.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Once TLS v1.3 is released, there will be no workaround available for TLS v1.0 or v1.1.
Plans for TLS v1.3 include banning ciphers with known vulnerabilities from being present at any level.
It is recommended to upgrade any clients using these ciphers as soon as possible or face being locked into a outdated version of Jetty, Java or even OS.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>By default, Jetty excludes these ciphers in the <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-util/src/main/java/org/eclipse/jetty/util/ssl/SslContextFactory.java#L249-L256"><code>SslContextFactory</code>.</a>
You can re-enable these by re-declaring the ciphers you want excluded in code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setExcludeCipherSuites("^.*_(MD5|SHA|SHA1)$");</code></pre>
</div>
</div>
<div class="paragraph">
<p>If, after making these changes, you still have issues using these ciphers they are likely being blocked at the JVM level.
Locate the <code>$JAVA_HOME/jre/lib/security/</code> directory for the <code>java.security</code> file and examine it for any configuration that is excluding <em>ciphers</em> or <em>algorithms</em> (depending on the version of the JVM you are using the nomenclature may be different).</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="understanding-certificates-and-keys">Understanding Certificates and Keys</h4>
<div class="paragraph">
<p>Configuring SSL can be a confusing experience of keys, certificates, protocols and formats, thus it helps to have a reasonable understanding of the basics.
The following links provide some good starting points:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Certificates:</p>
<div class="ulist">
<ul>
<li>
<p><a href="http://en.tldp.org/HOWTO/SSL-Certificates-HOWTO/index.html">SSL Certificates HOWTO</a></p>
</li>
<li>
<p><a href="http://mindprod.com/jgloss/certificate.html">Mindprod Java Glossary: Certificates</a></p>
</li>
</ul>
</div>
</li>
<li>
<p>Keytool:</p>
<div class="ulist">
<ul>
<li>
<p><a href="http://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html">Keytool for Unix</a></p>
</li>
<li>
<p><a href="http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html">Keytool for Windows</a></p>
</li>
</ul>
</div>
</li>
<li>
<p>Other tools:</p>
<div class="ulist">
<ul>
<li>
<p><a href="https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=6fb00498-f6ea-4f65-bf0c-adc5bd0c5fcc">IBM Keyman</a></p>
</li>
</ul>
</div>
</li>
<li>
<p>OpenSSL:</p>
<div class="ulist">
<ul>
<li>
<p><a href="http://www.openssl.org/support/faq.html">OpenSSL FAQ</a></p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="openssl-vs-keytool">OpenSSL vs. Keytool</h5>
<div class="paragraph">
<p>For testing, the <code>keytool</code> utility bundled with the JDK provides the simplest way to generate the key and certificate you need.</p>
</div>
<div class="paragraph">
<p>You can also use the OpenSSL tools to generate keys and certificates, or to convert those that you have used with Apache or other servers.
Since Apache and other servers commonly use the OpenSSL tool suite to generate and manipulate keys and certificates, you might already have some keys and certificates created by OpenSSL, or you might also prefer the formats OpenSSL produces.</p>
</div>
<div class="paragraph">
<p>If you want the option of using the same certificate with Jetty or a web server such as Apache not written in Java, you might prefer to generate your private key and certificate with OpenSSL.</p>
</div>
</div>
<div class="sect4">
<h5 id="generating-key-pairs-and-certificates">Generating Key Pairs and Certificates</h5>
<div class="paragraph">
<p>The simplest way to generate keys and certificates is to use the <code>keytool</code> application that comes with the JDK, as it generates keys and certificates directly into the keystore.
See <a href="#generating-key-pairs-and-certificates-JDK-keytool">Generating Keys and Certificates with JDK&#8217;s keytool</a>.</p>
</div>
<div class="paragraph">
<p>If you already have keys and certificates, see <a href="#loading-keys-and-certificates">Loading Keys and Certificates</a> to load them into a JSSE keystore.
This section also applies if you have a renewal certificate to replace one that is expiring.</p>
</div>
<div class="paragraph">
<p>The examples below generate only basic keys and certificates.
You should read the full manuals of the tools you are using if you want to specify:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The key size</p>
</li>
<li>
<p>The certificate expiration date</p>
</li>
<li>
<p>Alternate security providers</p>
</li>
</ul>
</div>
<div class="sect5">
<h6 id="generating-key-pairs-and-certificates-JDK-keytool">Generating Keys and Certificates with JDK&#8217;s keytool</h6>
<div class="paragraph">
<p>The following command generates a key pair and certificate directly into file <code>keystore</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The DSA key algorithm certificate produces an error after loading several pages.
In a browser, it displays a message "Could not establish an encrypted connection because certificate presented by localhost as an invalid signature."
The solution is to use RSA for the key algorithm.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA
Enter keystore password: password
What is your first and last name?
[Unknown]: jetty.eclipse.org
What is the name of your organizational unit?
[Unknown]: Jetty
What is the name of your organization?
[Unknown]: Mort Bay Consulting Pty. Ltd.
What is the name of your City or Locality?
[Unknown]:
What is the name of your State or Province?
[Unknown]:
What is the two-letter country code for this unit?
[Unknown]:
Is CN=jetty.eclipse.org, OU=Jetty, O=Mort Bay Consulting Pty. Ltd.,
L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes
Enter key password for &lt;jetty&gt;
(RETURN if same as keystore password):
$</code></pre>
</div>
</div>
<div class="paragraph">
<p>You now have the minimal requirements to run an SSL connection and could proceed directly to <a href="#configuring-sslcontextfactory">configure an SSL connector</a>.
However, the browser <em>will not</em> trust the certificate you have generated, and prompts the user to this effect.
While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section <a href="#generating-csr-from-keytool">generating a CSR with keytool</a>.</p>
</div>
<div class="paragraph">
<p>If you want to use only a self signed certificate for some kind of internal admin panel add -validity &lt;days&gt; to the keytool call above, otherwise your certificate is only valid for one month.</p>
</div>
<div class="paragraph">
<p>If you are using Java 8 or later, then you may also use the SAN extension to set one or more names that the certificate applies to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA -ext 'SAN=dns:jetty.eclipse.org,dns:*.jetty.org'
...</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="generating-keys-and-certificates-openssl">Generating Keys and Certificates with OpenSSL</h6>
<div class="paragraph">
<p>The following command generates a key pair in the file <code>jetty.key</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl genrsa -aes128 -out jetty.key</code></pre>
</div>
</div>
<div class="paragraph">
<p>You might also want to use the <code>-rand</code> file argument to provide an arbitrary file that helps seed the random number generator.</p>
</div>
<div class="paragraph">
<p>The following command generates a certificate for the key into the file <code>jetty.crt</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt</code></pre>
</div>
</div>
<div class="paragraph">
<p>Adding -sha256 ensures to get a certificate with the now recommended SHA-256 signature algorithm.
For the those with heightened security in mind, add -b4096 to get a 4069 bit key.</p>
</div>
<div class="paragraph">
<p>The next command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it.
The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl genrsa -aes128 -out jetty.key
Generating RSA private key, 2048 bit long modulus
..............+++
......................................................................+++
e is 65537 (0x10001)
Enter pass phrase for jetty.key:
Verifying - Enter pass phrase for jetty.key:
$ openssl req -new -x509 -newkey rsa:2048 -sha256 -key jetty.key -out jetty.crt
Enter pass phrase for jetty.key:
You are about to be asked to enter information that will be incorporated into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank.
For some fields there will be a default value.
If you enter '.', the field will be left blank.
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Mort Bay Consulting Pty. Ltd.
Organizational Unit Name (eg, section) []:Jetty
Common Name (e.g. server FQDN or YOUR name) []:jetty.eclipse.org
Email Address []:
$</code></pre>
</div>
</div>
<div class="paragraph">
<p>You now have the minimal requirements to run an SSL connection and could proceed directly to <a href="#loading-keys-and-certificates">Loading Keys and Certificates</a> to load these keys and certificates into a JSSE keystore.
However the browser <em>will not</em> trust the certificate you have generated, and prompts the user to this effect.
While what you have at this point is often sufficient for testing, most public sites need a trusted certificate, which is demonstrated in the section, <a href="#generating-csr-from-openssl">Generating a CSR from OpenSSL</a> to obtain a certificate.</p>
</div>
</div>
<div class="sect5">
<h6 id="using-keys-and-certificates-from-other-sources">Using Keys and Certificates from Other Sources</h6>
<div class="paragraph">
<p>If you have keys and certificates from other sources, you can proceed directly to <a href="#loading-keys-and-certificates">Loading Keys and Certificates</a>.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="requesting-trusted-certificate">Requesting a Trusted Certificate</h5>
<div class="paragraph">
<p>The keys and certificates generated with JDK&#8217;s <code>keytool</code> and OpenSSL are sufficient to run an SSL connector.
However the browser will not trust the certificate you have generated, and it will prompt the user to this effect.</p>
</div>
<div class="paragraph">
<p>To obtain a certificate that most common browsers will trust, you need to request a well-known certificate authority (CA) to sign your key/certificate.
Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, and beTRUSTed, among others.
Each CA has its own instructions (look for JSSE or OpenSSL sections), but all involve a step that generates a certificate signing request (CSR).</p>
</div>
<div class="sect5">
<h6 id="generating-csr-from-keytool">Generating a CSR with keytool</h6>
<div class="paragraph">
<p>The following command generates the file <code>jetty.csr</code> using <code>keytool</code> for a key/cert already in the keystore:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -certreq -alias jetty -keystore keystore -file jetty.csr</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="generating-csr-from-openssl">Generating a CSR from OpenSSL</h6>
<div class="paragraph">
<p>The following command generates the file <code>jetty.csr</code> using OpenSSL for a key in the file <code>jetty.key</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl req -new -key jetty.key -out jetty.csr</code></pre>
</div>
</div>
<div class="paragraph">
<p>Notice that this command uses only the existing key from <code>jetty.key</code> file, and not a certificate in <code>jetty.crt</code> as generated with OpenSSL.
You need to enter the details for the certificate again.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="loading-keys-and-certificates">Loading Keys and Certificates</h5>
<div class="paragraph">
<p>Once a CA has sent you a certificate, or if you generated your own certificate without <code>keytool</code>, you need to load it into a JSSE keystore.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
You need both the private key and the certificate in the JSSE keystore.
You should load the certificate into the keystore used to generate the CSR with <code>keytool</code>.
If your key pair is not already in a keystore (for example, because it has been generated with OpenSSL), you need to use the PKCS12 format to load both key and certificate (see <a href="#loading-keys-and-certificates-via-pkcks12">PKCKS12 Keys &amp;Certificates</a>).
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect5">
<h6 id="loading-certificates-with-keytool">Loading Certificates with keytool</h6>
<div class="paragraph">
<p>You can use <code>keytool</code> to load a certificate in PEM form directly into a keystore.
The PEM format is a text encoding of certificates; it is produced by OpenSSL, and is returned by some CAs.
An example PEM file is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">jetty.crt
-----BEGIN CERTIFICATE-----
MIICSDCCAfKgAwIBAgIBADANBgkqhkiG9w0BAQQFADBUMSYwJAYDVQQKEx1Nb3J0
IEJheSBDb25zdWx0aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNV
BAMTEWpldHR5Lm1vcnRiYXkub3JnMB4XDTAzMDQwNjEzMTk1MFoXDTAzMDUwNjEz
MTk1MFowVDEmMCQGA1UEChMdTW9ydCBCYXkgQ29uc3VsdGluZyBQdHkuIEx0ZC4x
DjAMBgNVBAsTBUpldHR5MRowGAYDVQQDExFqZXR0eS5tb3J0YmF5Lm9yZzBcMA0G
CSqGSIb3DQEBAQUAA0sAMEgCQQC5V4oZeVdhdhHqa9L2/ZnKySPWUqqy81riNfAJ
7uALW0kEv/LtlG34dOOcVVt/PK8/bU4dlolnJx1SpiMZbKsFAgMBAAGjga4wgasw
HQYDVR0OBBYEFFV1gbB1XRvUx1UofmifQJS/MCYwMHwGA1UdIwR1MHOAFFV1gbB1
XRvUx1UofmifQJS/MCYwoVikVjBUMSYwJAYDVQQKEx1Nb3J0IEJheSBDb25zdWx0
aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNVBAMTEWpldHR5Lm1v
cnRiYXkub3JnggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADQQA6NkaV
OtXzP4ayzBcgK/qSCmF44jdcARmrXhiXUcXzjxsLjSJeYPJojhUdC2LQKy+p4ki8
Rcz6oCRvCGCe5kDB
-----END CERTIFICATE-----</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following command loads a PEM encoded certificate in the <code>jetty.crt</code> file into a JSSE keystore:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the certificate you receive from the CA is not in a format that <code>keytool</code> understands, you can use the <code>openssl</code> command to convert formats:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6 id="loading-keys-and-certificates-via-pkcks12">Loading Keys and Certificates via PKCS12</h6>
<div class="paragraph">
<p>If you have a key and certificate in separate files, you need to combine them into a PKCS12 format file to load into a new keystore.
The certificate can be one you generated yourself or one returned from a CA in response to your CSR.</p>
</div>
<div class="paragraph">
<p>The following OpenSSL command combines the keys in <code>jetty.key</code> and the certificate in the <code>jetty.crt</code> file into the <code>jetty.pkcs12</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you have a chain of certificates, because your CA is an intermediary, build the PKCS12 file as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt &gt; cert-chain.txt
$ openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The order of certificates must be from server to rootCA, as per <a href="https://www.ietf.org/rfc/rfc2246.txt">RFC2246 section 7.4.2.</a>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>OpenSSL asks for an <em>export password</em>.
A non-empty password is required to make the next step work.
Load the resulting PKCS12 file into a JSSE keystore with <code>keytool</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="renewing-certificates">Renewing Certificates</h5>
<div class="paragraph">
<p>If you are updating your configuration to use a newer certificate, as when the old one is expiring, just load the newer certificate as described in the section, <a href="#loading-keys-and-certificates">Loading Keys and Certificates</a>.
If you imported the key and certificate originally using the PKCS12 method, use an alias of "1" rather than "jetty", because that is the alias the PKCS12 process enters into the keystore.</p>
</div>
</div>
<div class="sect4">
<h5 id="layout-of-keystore-and-truststore">Layout of keystore and truststore</h5>
<div class="paragraph">
<p>The <code>keystore</code> only contains the server&#8217;s private key and certificate.</p>
</div>
<div id="img-certificate-chain" class="imageblock">
<div class="content">
<img src="images/certificate-chain.png" alt="Certificate chain">
</div>
<div class="title">Figure 1. Certificate chain</div>
</div>
<div class="literalblock">
<div class="title">The structure of KeyStore file:</div>
<div class="content">
<pre>├── PrivateKeyEntry
│   ├── PrivateKey
│   ├── Certificate chain
│   │   ├── Server certificate (end entity)
│   │   ├── Intermediary CA certificate
│   │   └── Root CA certificate
├── TrustedCertEntry
│   └── Intermediary CA certificate
└── TrustedCertEntry
   └── Root CA certificate</pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Both the <code>Intermediary CA certificate</code> and <code>Root CA certificate</code> are optional.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight nowrap"><code class="language-plain" data-lang="plain">$ cd $JETTY_BASE
$ keytool -v -list -keystore etc/keystore
Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 3 entries
Alias name: *.example.com
Creation date: Sep 20, 2016
Entry type: PrivateKeyEntry
Certificate chain length: 3
Certificate[1]:
Owner: CN=*.example.com, OU=Web Servers, O="Example.com Co.,Ltd.", C=CN
Issuer: CN="Example.com Co.,Ltd. ETP CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Serial number: b63af619ff0b4c368735113ba5db8997
Valid from: Mon Sep 12 15:09:49 CST 2016 until: Wed Sep 12 15:09:49 CST 2018
Certificate fingerprints:
MD5: D9:26:CC:27:77:9D:26:FE:67:4C:BE:FF:E3:95:1E:97
SHA1: AF:DC:D2:65:6A:33:42:E3:81:9E:4D:19:0D:22:20:C7:6F:2F:11:D0
SHA256: 43:E8:21:5D:C6:FB:A0:7D:5D:7B:9C:8B:8D:E9:4B:52:BF:50:0D:90:4F:61:C2:18:9E:89:AA:4C:C2:93:BD:32
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: 44 9B AD 31 E7 FE CA D5 5A 8E 17 55 F9 F0 1D 6B D..1....Z..U...k
0010: F5 A5 8F C1 ....
]
]
#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:false
PathLen: undefined
]
#3: ObjectId: 2.5.29.37 Criticality=true
ExtendedKeyUsages [
serverAuth
clientAuth
]
#4: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
DigitalSignature
Key_Encipherment
Data_Encipherment
]
#5: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 7D 26 36 73 61 5E 08 94 AD 25 13 46 DB DB 95 25 .&amp;6sa^...%.F...%
0010: BF 82 5A CA ..Z.
]
]
Certificate[2]:
Owner: CN="Example.com Co.,Ltd. ETP CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Serial number: f6e7b86f6fdb467f9498fb599310198f
Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2035
Certificate fingerprints:
MD5: ED:A3:91:57:D8:B8:6E:B1:01:58:55:5C:33:14:F5:99
SHA1: D9:A4:93:9D:A6:F8:A3:F9:FD:85:51:E2:C5:2E:0B:EE:80:E7:D0:22
SHA256: BF:54:7A:F6:CA:0C:FA:EF:93:B6:6B:6E:2E:D7:44:A8:40:00:EC:69:3A:2C:CC:9A:F7:FE:8E:6F:C0:FA:22:38
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;..
0010: E6 E6 04 46 ...F
]
]
#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
Key_CertSign
Crl_Sign
]
#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 44 9B AD 31 E7 FE CA D5 5A 8E 17 55 F9 F0 1D 6B D..1....Z..U...k
0010: F5 A5 8F C1 ....
]
]
Certificate[3]:
Owner: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Serial number: f0a45bc9972c458cbeae3f723055f1ac
Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2114
Certificate fingerprints:
MD5: 50:61:62:22:71:60:F7:69:2E:27:42:6B:62:31:82:79
SHA1: 7A:6D:A6:48:B1:43:03:3B:EA:A0:29:2F:19:65:9C:9B:0E:B1:03:1A
SHA256: 05:3B:9C:5B:8E:18:61:61:D1:9C:AA:0E:8C:B1:EA:44:C2:6E:67:5D:96:30:EC:8C:F6:6F:E1:EC:AD:00:60:F1
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;..
0010: E6 E6 04 46 ...F
]
]
#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
Key_CertSign
Crl_Sign
]
#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;..
0010: E6 E6 04 46 ...F
]
]
*******************************************
*******************************************
Alias name: example.com co.,ltd. etp ca
Creation date: Sep 20, 2016
Entry type: trustedCertEntry
Owner: CN="Example.com Co.,Ltd. ETP CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Serial number: f6e7b86f6fdb467f9498fb599310198f
Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2035
Certificate fingerprints:
MD5: ED:A3:91:57:D8:B8:6E:B1:01:58:55:5C:33:14:F5:99
SHA1: D9:A4:93:9D:A6:F8:A3:F9:FD:85:51:E2:C5:2E:0B:EE:80:E7:D0:22
SHA256: BF:54:7A:F6:CA:0C:FA:EF:93:B6:6B:6E:2E:D7:44:A8:40:00:EC:69:3A:2C:CC:9A:F7:FE:8E:6F:C0:FA:22:38
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;..
0010: E6 E6 04 46 ...F
]
]
#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
Key_CertSign
Crl_Sign
]
#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 44 9B AD 31 E7 FE CA D5 5A 8E 17 55 F9 F0 1D 6B D..1....Z..U...k
0010: F5 A5 8F C1 ....
]
]
*******************************************
*******************************************
Alias name: example.com co.,ltd. root ca
Creation date: Sep 20, 2016
Entry type: trustedCertEntry
Owner: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Issuer: CN="Example.com Co.,Ltd. Root CA", OU=CA Center, O="Example.com Co.,Ltd.", C=CN
Serial number: f0a45bc9972c458cbeae3f723055f1ac
Valid from: Wed Nov 18 00:00:00 CST 2015 until: Sun Nov 18 00:00:00 CST 2114
Certificate fingerprints:
MD5: 50:61:62:22:71:60:F7:69:2E:27:42:6B:62:31:82:79
SHA1: 7A:6D:A6:48:B1:43:03:3B:EA:A0:29:2F:19:65:9C:9B:0E:B1:03:1A
SHA256: 05:3B:9C:5B:8E:18:61:61:D1:9C:AA:0E:8C:B1:EA:44:C2:6E:67:5D:96:30:EC:8C:F6:6F:E1:EC:AD:00:60:F1
Signature algorithm name: SHA256withRSA
Version: 3
Extensions:
#1: ObjectId: 2.5.29.35 Criticality=false
AuthorityKeyIdentifier [
KeyIdentifier [
0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;..
0010: E6 E6 04 46 ...F
]
]
#2: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.15 Criticality=true
KeyUsage [
Key_CertSign
Crl_Sign
]
#4: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: A6 BD 5F B3 E8 7D 74 3D 20 44 66 1A 16 3B 1B DF .._...t= Df..;..
0010: E6 E6 04 46 ...F
]
]
*******************************************
*******************************************</code></pre>
</div>
</div>
<div class="paragraph">
<p>In addition, you can split <code>$JETTY/etc/keystore</code> as two files.
One is <code>$JETTY/etc/keystore</code> which only contains the server’s private key and certificate,
the other is <code>$JETTY/etc/truststore</code> which contains intermediary CA and root CA.</p>
</div>
<div class="literalblock">
<div class="title">The structure of <code>$JETTY/etc/keystore</code></div>
<div class="content">
<pre>└── PrivateKeyEntry
   ├── PrivateKey
   └── Certificate chain
      └── Server certificate (end entity)</pre>
</div>
</div>
<div class="literalblock">
<div class="title">The structure of <code>$JETTY/etc/truststore</code></div>
<div class="content">
<pre>├── TrustedCertEntry
│   └── Intermediary CA certificate
└── TrustedCertEntry
   └── Root CA certificate</pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuring-sslcontextfactory">Configuring the Jetty SslContextFactory</h4>
<div class="paragraph">
<p>The generated SSL certificates from above are held in the key store are configured in an instance of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/ssl/SslContextFactory.Server.html">SslContextFactory.Server</a> object.</p>
</div>
<div class="paragraph">
<p>The <code>SslContextFactory</code> is responsible for:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Creating the Java <code>SslEngine</code> used by Jetty&#8217;s Connectors and Jetty&#8217;s Clients (HTTP/1, HTTP/2, and WebSocket).</p>
</li>
<li>
<p>Managing Keystore Access</p>
</li>
<li>
<p>Managing Truststore Access</p>
</li>
<li>
<p>Managing Protocol selection via Excludes / Includes list</p>
</li>
<li>
<p>Managing Cipher Suite selection via Excludes / Includes list</p>
</li>
<li>
<p>Managing order of Ciphers offered (important for TLS/1.2 and HTTP/2 support)</p>
</li>
<li>
<p>SSL Session Caching options</p>
</li>
<li>
<p>Certificate <a href="https://en.wikipedia.org/wiki/Revocation_list">Revocation Lists</a> and Distribution Points (CRLDP)</p>
</li>
<li>
<p><a href="https://en.wikipedia.org/wiki/Online_Certificate_Status_Protocol">OCSP</a> Support</p>
</li>
<li>
<p>Client Authentication Support</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For Jetty Connectors, the configured <code>SslContextFactory.Server</code> is injected into a specific ServerConnector <code>SslConnectionFactory</code>.</p>
</div>
<div class="paragraph">
<p>For Jetty Clients, the various constructors support using a configured <code>SslContextFactory.Client</code>.</p>
</div>
<div class="paragraph">
<p>While the <code>SslContextFactory</code> can operate without a keystore (this mode is most suitable for the various Jetty Clients) it is best practice to at least configure the keystore being used.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">setKeyStorePath</dt>
<dd>
<p>The configured keystore to use for all SSL/TLS in configured Jetty Connector (or Client).</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
As a keystore is vital security information, it can be desirable to locate the file in a directory with <strong>very</strong> restricted access.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">setKeyStorePassword</dt>
<dd>
<p>The keystore password may be set here in plain text, or as some measure of protection from casual observation, it may be obfuscated using the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/security/Password.html">Password</a> class.</p>
</dd>
<dt class="hdlist1">setTrustStorePath</dt>
<dd>
<p>This is used if validating client certificates and is typically set to the same path as the keystore.</p>
</dd>
<dt class="hdlist1">setKeyManagerPassword</dt>
<dd>
<p>The password that is passed to the <code>KeyManagerFactory.init(&#8230;&#8203;)</code>.
If there is no <code>keymanagerpassword</code>, then the <code>keystorepassword</code> is used instead.
If there is no <code>trustmanager</code> set, then the keystore is used as the trust store and the <code>keystorepassword</code> is used as the truststore password.</p>
</dd>
<dt class="hdlist1">setExcludeCipherSuites / setIncludeCipherSuites</dt>
<dd>
<p>This allows for the customization of the selected Cipher Suites that will be used by SSL/TLS.</p>
</dd>
<dt class="hdlist1">setExcludeProtocols / setIncludeProtocols</dt>
<dd>
<p>This allows for the customization of the selected Protocols that will be used by SSL/TLS.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
When working with Includes / Excludes, it is important to know that <strong>Excludes will always win.</strong>
The selection process is to process the JVM list of available Cipher Suites or Protocols against the include list, then remove the excluded ones.
Be aware that each Include / Exclude list has a Set method (replace the list) or Add method (append the list).
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
The keystore and truststore passwords may also be set using the system properties: <code>org.eclipse.jetty.ssl.keypassword</code> <code>org.eclipse.jetty.ssl.password</code>.
This is <em>not</em> a recommended usage.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="conscrypt">Conscrypt SSL</h4>
<div class="paragraph">
<p>Jetty includes support for Google&#8217;s <a href="https://github.com/google/conscrypt/">Conscrypt SSL</a>, which is built on their fork of <a href="https://www.openssl.org/">OpenSSL</a>, <a href="https://boringssl.googlesource.com/boringssl/">BoringSSL</a>.
Implementing Conscrypt for the <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-alpn/jetty-alpn-conscrypt-server/src/test/java/org/eclipse/jetty/alpn/conscrypt/server/ConscryptHTTP2Server.java">server</a> or <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-alpn/jetty-alpn-conscrypt-client/src/test/java/org/eclipse/jetty/alpn/java/client/ConscryptHTTP2Client.java">client</a> is very straightforward process - simply instantiate an instance of Conscrypt&#8217;s <code>OpenSSLProvider</code> and set <code>Conscrypt</code> as a provider for Jetty&#8217;s <code>SslContextFactory</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">...
Security.addProvider(new OpenSSLProvider());
...
SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setKeyStorePath("path/to/keystore");
sslContextFactory.setKeyStorePassword("CleverKeyStorePassword");
sslContextFactory.setKeyManagerPassword("OBF:VerySecretManagerPassword");
sslContextFactory.setProvider("Conscrypt");
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you are using the Jetty Distribution, please see the section on enabling the <a href="#jetty-conscrypt-distribution">Conscrypt SSL module.</a></p>
</div>
<div class="paragraph">
<p>If you are using Conscrypt with Java 8, you must exclude <code>TLSv1.3</code> protocol as it is now enabled per default with Conscrypt 2.0.0 but not supported by Java 8.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring SNI</h4>
<div class="paragraph">
<p>From Java 8, the JVM contains support for the <a href="http://en.wikipedia.org/wiki/Server_Name_Indication">Server Name Indicator (SNI)</a> extension, which allows a SSL connection handshake to indicate one or more DNS names that it applies to.</p>
</div>
<div class="paragraph">
<p>To support this, the <code>SslContextFactory</code> is used.
The <code>SslContextFactory</code> will look for multiple X509 certificates within the keystore, each of which may have multiple DNS names (including wildcards) associated with the <a href="http://en.wikipedia.org/wiki/SubjectAltName">Subject Alternate Name</a> extension.
When using the <code>SslContextFactory</code>, the correct certificate is automatically selected if the SNI extension is present in the handshake.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-sslcontextfactory-cipherSuites">Disabling/Enabling Specific Cipher Suites</h4>
<div class="paragraph">
<p>New cipher suites are always being developed to stay ahead of attacks.
It&#8217;s only a matter of time before the best of suites is exploited though, and making sure your server is up-to-date in this regard is paramount for any implementation.
As an example, to avoid the BEAST attack it is necessary to configure a specific set of cipher suites. This can either be done via <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/ssl/SslContextFactory.html#setIncludeCipherSuites(java.lang.String&#8230;&#8203;)">SslContext.setIncludeCipherSuites(java.lang.String&#8230;&#8203;)</a> or via<a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/ssl/SslContextFactory.html#setExcludeCipherSuites(java.lang.String&#8230;&#8203;)">SslContext.setExcludeCipherSuites(java.lang.String&#8230;&#8203;)</a>.</p>
</div>
<div class="paragraph">
<p>It&#8217;s crucial that you use the <em>exact</em> names of the cipher suites as used/known by the JDK.
You can get them by obtaining an instance of SSLEngine and call <code>getSupportedCipherSuites()</code>.
Tools like <a href="https://www.ssllabs.com/">ssllabs.com</a> might report slightly different names which will be ignored.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
It is important to stay up-to-date with the latest supported cipher suites.
Be sure to consult Oracle&#8217;s <a href="https://java.com/en/jre-jdk-cryptoroadmap.html">JRE and JDK Cryptographic Roadmap</a> frequently for recent and upcoming changes to supported ciphers.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
It&#8217;s recommended to install the Java Cryptography Extension (JCE) Unlimited Strength policy files in your JRE to get full strength ciphers such as AES-256.
The files can be found on the <a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">Java download page</a>.
Just overwrite the two present JAR files in <code>&lt;JRE_HOME&gt;/lib/security/</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Both <code>setIncludeCipherSuites</code> and <code>setExcludeCipherSuites</code> can be fed by the exact cipher suite name used in the JDK or by using regular expressions.
If you have a need to adjust the Includes or Excludes, then this is best done with a custom XML that configures the <code>SslContextFactory</code> to suit your needs.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Jetty <strong>does</strong> allow users to enable weak/deprecated cipher suites (or even no cipher suites at all).
By default, if you have these suites enabled warning messages will appear in the server logs.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>To do this, first create a new <code>${jetty.base}/etc/tweak-ssl.xml</code> file (this can be any name, just avoid prefixing it with "jetty-").</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN"
"https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;!-- Tweak SsslContextFactory Includes / Excludes --&gt;
&lt;Configure id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory$Server"&gt;
&lt;!-- Mitigate SLOTH Attack --&gt;
&lt;Call name="addExcludeCipherSuites"&gt;
&lt;Arg&gt;
&lt;Array type="String"&gt;
&lt;Item&gt;.*_RSA_.*SHA1$&lt;/Item&gt;
&lt;Item&gt;.*_RSA_.*SHA$&lt;/Item&gt;
&lt;Item&gt;.*_RSA_.*MD5$&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This new XML will configure the id <code>sslContextFactory</code> further (this id is first created by the <code>ssl</code> module and its associated <code>${jetty.home}/etc/jetty-ssl-context.xml</code>).
You can do anything you want with the <code>SslContextFactory</code> in use by the Jetty Distribution from this tweaked XML.</p>
</div>
<div class="paragraph">
<p>To make sure that your <code>${jetty.base}</code> uses this new XML, add it to the end of your <code>${jetty.base}/start.ini</code> or <code>${jetty.base}/start.d/server.ini</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">$ cd /path/to/mybase
$ ls -l
drwxrwxr-x. 2 user group 4096 Feb 2 11:47 etc/
-rw-rw-r--. 1 user group 4259 Feb 2 11:47 start.ini
$ tail start.ini
# Module: https
--module=https
etc/tweak-ssl.xml
$</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The default <code>SslContextFactory</code> implementation applies the latest SSL/TLS recommendations surrounding vulnerabilities in SSL/TLS.
Check the release notes (the <code>VERSION.txt</code> found in the root of the Jetty Distribution, or the <a href="http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.eclipse.jetty%22%20AND%20a%3A%22jetty-project%22">alternate (classified 'version') artifacts for the <code>jetty-project</code> component</a> on Maven Central) for updates.
The Java JVM also applies exclusions at the JVM level and, as such, if you have a need to enable something that is generally accepted by the industry as being insecure or vulnerable you will likely have to enable it in <strong>both</strong> the Java JVM and your Jetty configuration.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You can enable the <code>org.eclipse.jetty.util.ssl</code> named logger at <code>DEBUG</code> level to see what the list of selected Protocols and Cipher suites are at startup of Jetty.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Additional Include / Exclude examples:</p>
</div>
<div class="paragraph">
<p><strong>Example</strong>: Include all ciphers which support <a href="https://en.wikipedia.org/wiki/Forward_secrecy">Forward Secrecy</a> using regex:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;!-- Enable Forward Secrecy Ciphers.
Note: this replaces the default Include Cipher list --&gt;
&lt;Set name="IncludeCipherSuites"&gt;
&lt;Array type="String"&gt;
&lt;Item&gt;TLS_DHE_RSA.*&lt;/Item&gt;
&lt;Item&gt;TLS_ECDHE.*&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Example</strong>: Exclude all old, insecure or anonymous cipher suites:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;!-- Eliminate Old / Insecure / Anonymous Ciphers --&gt;
&lt;Call name="addExcludeCipherSuites"&gt;
&lt;Arg&gt;
&lt;Array type="String"&gt;
&lt;Item&gt;.*NULL.*&lt;/Item&gt;
&lt;Item&gt;.*RC4.*&lt;/Item&gt;
&lt;Item&gt;.*MD5.*&lt;/Item&gt;
&lt;Item&gt;.*DES.*&lt;/Item&gt;
&lt;Item&gt;.*DSS.*&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p><strong>Example</strong>: Since 2014 SSLv3 is considered insecure and should be disabled.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;!-- Eliminate Insecure Protocols --&gt;
&lt;Call name="addExcludeProtocols"&gt;
&lt;Arg&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;SSL&lt;/Item&gt;
&lt;Item&gt;SSLv2&lt;/Item&gt;
&lt;Item&gt;SSLv2Hello&lt;/Item&gt;
&lt;Item&gt;SSLv3&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Note that disabling SSLv3 prevents very old browsers like Internet Explorer 6 on Windows XP from connecting.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p><strong>Example</strong>: TLS renegotiation could be disabled too to prevent an attack based on this feature.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;Set name="renegotiationAllowed"&gt;FALSE&lt;/Set&gt;</code></pre>
</div>
</div>
<div id="ssl-dump-ciphers" class="paragraph">
<p>You can view what cipher suites are enabled and disabled by performing a server dump.</p>
</div>
<div class="paragraph">
<p>To perform a server dump upon server startup, add <code>jetty.server.dumpAfterStart=true</code> to the command line when starting the server.
You can also dump the server when shutting down the server instance by adding <code>jetty.server.dumpBeforeStop</code>.</p>
</div>
<div class="paragraph">
<p>Specifically, you will want to look for the <code>SslConnectionFactory</code> portion of the dump.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ${JETTY_HOME}/start.jar jetty.server.dumpAfterStart=true
...
| += SslConnectionFactory@18be83e4{SSL-&gt;http/1.1} - STARTED
| | += SslContextFactory@42530531(null,null) trustAll=false
| | +- Protocol Selections
| | | +- Enabled (size=3)
| | | | +- TLSv1
| | | | +- TLSv1.1
| | | | +- TLSv1.2
| | | +- Disabled (size=2)
| | | +- SSLv2Hello - ConfigExcluded:'SSLv2Hello'
| | | +- SSLv3 - JreDisabled:java.security, ConfigExcluded:'SSLv3'
| | +- Cipher Suite Selections
| | +- Enabled (size=15)
| | | +- TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
| | | +- TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
| | | +- TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
| | | +- TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
| | | +- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
| | | +- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
| | | +- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
| | | +- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
| | | +- TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
| | | +- TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
| | | +- TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
| | | +- TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
| | | +- TLS_EMPTY_RENEGOTIATION_INFO_SCSV
| | | +- TLS_RSA_WITH_AES_128_CBC_SHA256
| | | +- TLS_RSA_WITH_AES_128_GCM_SHA256
| | +- Disabled (size=42)
| | +- SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DHE_DSS_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DHE_RSA_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DH_anon_WITH_3DES_EDE_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_DH_anon_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_RSA_EXPORT_WITH_DES40_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_RSA_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_RSA_WITH_NULL_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- SSL_RSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_DHE_DSS_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_DHE_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_DH_anon_WITH_AES_128_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_DH_anon_WITH_AES_128_CBC_SHA256 - JreDisabled:java.security
| | +- TLS_DH_anon_WITH_AES_128_GCM_SHA256 - JreDisabled:java.security
| | +- TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDHE_ECDSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDHE_RSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_ECDSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_RSA_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_anon_WITH_AES_128_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_ECDH_anon_WITH_NULL_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_KRB5_EXPORT_WITH_DES_CBC_40_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_KRB5_EXPORT_WITH_DES_CBC_40_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_KRB5_WITH_3DES_EDE_CBC_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_KRB5_WITH_3DES_EDE_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_KRB5_WITH_DES_CBC_MD5 - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_KRB5_WITH_DES_CBC_SHA - JreDisabled:java.security, ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_RSA_WITH_AES_128_CBC_SHA - ConfigExcluded:'^.*_(MD5|SHA|SHA1)$'
| | +- TLS_RSA_WITH_NULL_SHA256 - JreDisabled:java.security
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the example above you can see both the enabled/disabled protocols and included/excluded cipher suites.
For disabled or excluded protocols and ciphers, the reason they are disabled is given - either due to JVM restrictions, configuration or both.
As a reminder, when configuring your includes/excludes, <strong>excludes always win</strong>.</p>
</div>
<div class="paragraph">
<p>Dumps can be configured as part of the <code>jetty.xml</code> configuration for your server.
Please see the documentation on the <a href="#jetty-dump-tool">Jetty Dump Tool</a> for more information.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jetty-ssl-distribution">SSL in the Jetty Distribution</h3>
<div class="paragraph">
<p>When making use of the Jetty Distribution, enabling SSL support is as easy as activating the appropriate module.
Jetty supports both the default <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html">JSSE</a>
provider and the <a href="https://github.com/google/conscrypt/">Conscrypt</a> provider as SSL implementations.</p>
</div>
<div class="sect3">
<h4>Default JSSE SSL Configuration</h4>
<div class="paragraph">
<p>For the default SSL support, simply activate the <code>ssl</code> <a href="#startup-modules">module</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">$ cd /path/to/mybase
$ java -jar ${JETTY_HOME}/start.jar --add-to-startd=ssl
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
INFO : ssl initialised in ${jetty.base}/start.d/ssl.ini
INFO : Base directory was modified
$ tree
.
├── etc
│   └── keystore
└── start.d
├── server.ini
└── ssl.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>When you open <code>start.d/ssl.ini</code>, you will see several commented properties ready for use when configuring <code>SslContextFactory</code> basics.</p>
</div>
<div class="paragraph">
<p>To highlight some of the more commonly used properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.ssl.host</dt>
<dd>
<p>Configures which interfaces the SSL/TLS Connector should listen on.</p>
</dd>
<dt class="hdlist1">jetty.ssl.port</dt>
<dd>
<p>Configures which port the SSL/TLS Connector should listen on.</p>
</dd>
<dt class="hdlist1">jetty.httpConfig.securePort</dt>
<dd>
<p>If a webapp needs to redirect to a secure version of the same resource, then this is the port reported back on the response <code>location</code> line (having this be separate is useful if you have something sitting in front of Jetty, such as a Load Balancer or proxy).</p>
</dd>
<dt class="hdlist1">jetty.sslContext.keyStorePath</dt>
<dd>
<p>Sets the location of the <code>keystore</code> that you configured with your certificates.</p>
</dd>
<dt class="hdlist1">jetty.sslContext.keyStorePassword</dt>
<dd>
<p>Sets the Password for the <code>keystore</code>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="jetty-conscrypt-distribution">Conscrypt SSL Configuration</h4>
<div class="paragraph">
<p>Enabling Conscrypt SSL is just as easy as default SSL - enable both the <code>conscrypt</code> and <code>ssl</code> <a href="#startup-modules">modules</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">$ cd ${JETTY_HOME}
$ java -jar ../start.jar --add-to-start=ssl,conscrypt
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: conscrypt
+ Conscrypt is distributed under the Apache Licence 2.0
+ https://github.com/google/conscrypt/blob/master/LICENSE
Proceed (y/N)? y
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : conscrypt initialized in ${jetty.base}/start.d/conscrypt.ini
INFO : ssl initialized in ${jetty.base}/start.d/ssl.ini
MKDIR : ${jetty.base}/lib/conscrypt
DOWNLD: https://repo1.maven.org/maven2/org/conscrypt/conscrypt-openjdk-uber/1.0.0.RC11/conscrypt-openjdk-uber-1.0.0.RC11.jar to ${jetty.base}/lib/conscrypt/conscrypt-uber-1.0.0.RC11.jar
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/conscrypt/conscrypt.xml to ${jetty.base}/etc/conscrypt.xml
COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>No additional Conscrypt configuration is needed.
SSL-specific parameters, like <code>keyStorePath</code> and <code>keyStorePassword</code> can still configured as in the example above, making use of the <code>${JETTY_BASE}/start.d/ssl.ini</code> file.</p>
</div>
</div>
<div class="sect3">
<h4 id="client-certificate-authentication">Client Certificate Authentication</h4>
<div class="paragraph">
<p>To enable client certificate authentication in the Jetty Distribution, you need to enable the both the <code>ssl</code> and <code>https</code> modules.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">$ cd /path/to/mybase
$ java -jar /path/to/jetty-dist/start.jar --add-to-startd=ssl,https</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">$JETTY_BASE/start.d/ssl.ini</div>
<div class="content">
<pre class="highlight nowrap"><code class="language-ini" data-lang="ini"># Module: ssl
--module=ssl
jetty.ssl.host=0.0.0.0
jetty.ssl.port=8583
jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.trustStorePath=etc/truststore
jetty.sslContext.keyStorePassword=OBF:
jetty.sslContext.keyManagerPassword=OBF:
jetty.sslContext.trustStorePassword=OBF:
# Enable client certificate authentication.
jetty.sslContext.needClientAuth=true</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">$JETTY_BASE/start.d/https.ini</div>
<div class="content">
<pre class="highlight nowrap"><code class="language-ini" data-lang="ini"># Module: https
--module=https</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="http2">HTTP/2</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="http2-introduction">Introducing HTTP/2</h3>
<div class="paragraph">
<p>Jetty supports both a client and a server implementation for the HTTP/2 protocol as defined by <a href="http://tools.ietf.org/html/rfc7540">RFC 7540</a>.</p>
</div>
<div class="paragraph">
<p>The requirements for running HTTP/2 are JDK 8 or greater, and typically also ALPN support (see <a href="#alpn-chapter">Application Layer Protocol Negotiation (ALPN)</a>).</p>
</div>
<div class="paragraph">
<p>A server deployed over TLS (SSL) normally advertises the HTTP/2 protocol via the TLS extension Application Layer Protocol Negotiation <a href="#alpn">(ALPN)</a>.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
To use HTTP/2 in Jetty via a TLS connector you need to add the <a href="#alpn-starting">ALPN boot jar</a> in the boot classpath.
This is done automatically when using the Jetty distribution&#8217;s start.jar <a href="#startup-modules">module system</a>, but must be configured directly otherwise.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect3">
<h4 id="http2-security-update">Jetty HTTP/2 Security Update</h4>
<div class="paragraph">
<p>In mid-2019, there were a <a href="#security-reports">number of CVEs</a> were issued warning against vulnerable HTTP/2 implementations. These CVEs (CVE-2019-9511 thru CVE-2019-9518) generally centered around attackers manipulating and flooding HTTP/2 servers and creating a denial of service (DOS). These vulnerabilities were patched with Jetty 9.4.21.</p>
</div>
<div class="paragraph">
<p>As a result of these CVEs, Jetty introduced a new, configurable denial of service (DOS) protection feature in Jetty 9.4.22.</p>
</div>
<div class="paragraph">
<p>Jetty’s HTTP/2 implementation now features a new Rate Control parameter, <code>jetty.http2.rateControl.maxEventsPerSecond</code>, that defaults to 20 events per second, per connection for all pings, bad frames, settings frames, priority changes etc.</p>
</div>
</div>
<div class="sect3">
<h4 id="http2-modules">Jetty HTTP/2 Sub Projects</h4>
<div class="paragraph">
<p>The Jetty HTTP/2 implementation consists of the following sub-projects (each producing a jar file):</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><code>http2-common</code>: Contains the HTTP/2 API and a partial implementation shared across other modules.</p>
</li>
<li>
<p><code>http2-hpack</code>: Contains the HTTP/2 HPACK implementation for HTTP header compression.</p>
</li>
<li>
<p><code>http2-server</code>: Provides the server-side implementation of HTTP/2.</p>
</li>
<li>
<p><code>http2-client</code>: Provides the implementation of HTTP/2 client with a low level HTTP/2 API, dealing with HTTP/2 streams, frames, etc.</p>
</li>
<li>
<p><code>http2-http-client-transport</code>: Provides the implementation of the HTTP/2 transport for <code>HttpClient</code> (see <a href="#http-client">[http-client]</a>).
Applications can use the higher level API provided by <code>HttpClient</code> to send HTTP requests and receive HTTP responses, and the HTTP/2 transport will take care of converting them in HTTP/2 format (see also <a href="https://webtide.com/http2-support-for-httpclient/">this blog entry</a>).</p>
</li>
</ol>
</div>
</div>
</div>
<div class="sect2">
<h3 id="http2-enabling">Enabling HTTP/2</h3>
<div class="paragraph">
<p>This section is written assuming that a <a href="#startup-base-and-home">Jetty base directory</a> is being used.
A demo Jetty base that supports HTTP/1, HTTPS/1 and deployment from a webapps directory can be created with the commands:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ JETTY_BASE=http2-demo
$ mkdir $JETTY_BASE
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http,https,deploy,test-keystore</code></pre>
</div>
</div>
<div class="paragraph">
<p>The commands above create a <code>$JETTY_BASE</code> directory called <code>http2-demo</code>, and initializes the <code>http,</code> <code>https</code> and <code>deploy</code> modules (and their dependencies) to run a typical Jetty Server on port 8080 (for HTTP/1) and 8443 (for HTTPS/1).
Note that the <code>test-keystore</code> module downloads a demo keystore file with a self signed certificate, which needs to be replaced by a Certificate Authority issued certificate for real deployment.
A keystore can also be added by enabling and configuring the <code>ssl</code> module.</p>
</div>
<div class="paragraph">
<p>To add HTTP/2 to this demo base, it is just a matter of enabling the <code>http2</code> module with the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar $JETTY_HOME/start.jar --add-to-start=http2</code></pre>
</div>
</div>
<div class="paragraph">
<p>This command does not create a new connector, but instead simply adds the HTTP/2 protocol to the existing HTTPS/1 connector, so that it now supports both protocols on port 8443.
To do this, it also transitively enables the ALPN module for protocol negotiation.
The support for each protocol can be seen in the info logging when the server is started:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar $JETTY_HOME/start.jar
...
2015-06-17 14:16:12.549:INFO:oejs.ServerConnector:main: Started ServerConnector@34c9c77f{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2015-06-17 14:16:12.782:INFO:oejs.ServerConnector:main: Started ServerConnector@711f39f9{SSL,[ssl, alpn, h2, h2-17, http/1.1]}{0.0.0.0:8443}
...</code></pre>
</div>
</div>
<div class="paragraph">
<p>This log shows that port 8080 supports only HTTP/1.1 (which by specification includes HTTP/1.0 support), while port 8443 supports the SSL protocol, with ALPN negotiation to select between several versions of HTTP/2 (h2 &amp; the draft h2-17) and HTTP/1.1.
What is not shown is that HTTP/1.1 is the default ALPN protocol, so that if a client connects that does not speak ALPN, then HTTP/1.1 will be assumed.</p>
</div>
<div class="paragraph">
<p>A browser can now be pointed at <code><a href="https://localhost:8443/" class="bare">https://localhost:8443/</a></code> and if it supports HTTP/2 then it will be used (often indicated by a lightening bolt icon in the address bar).
Note that a browser pointed at this server with URL starting with <code><a href="http://localhost:8080/" class="bare">http://localhost:8080/</a></code> will still talk HTTP/1.1, as HTTP/2 has not been enabled on the plain text connector.</p>
</div>
<div class="paragraph">
<p>HTTP/2 can be enabled on the plain text connector and the server restarted with the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c
$ java -jar $JETTY_HOME/start.jar
..
2015-06-17 14:16:12.549:INFO:oejs.ServerConnector:main: Started ServerConnector@6f32cd1e{HTTP/1.1,[http/1.1, h2c, h2c-17]}{0.0.0.0:8080}
2015-06-17 14:16:12.782:INFO:oejs.ServerConnector:main: Started ServerConnector@711f39f9{SSL,[ssl, alpn, h2, h2-17, http/1.1]}{0.0.0.0:8443}
..</code></pre>
</div>
</div>
<div class="paragraph">
<p>No major browser currently supports plain text HTTP/2, so the 8080 port will only be able to use HTTP/2 with specific clients (eg <code>curl</code>) that use the upgrade mechanism or assume HTTP/2.</p>
</div>
</div>
<div class="sect2">
<h3 id="http2-configuring">Configuring HTTP/2</h3>
<div class="paragraph">
<p>Enabling the HTTP/2 module in the Jetty server does not create a HTTP/2 specific connector, but rather it adds a HTTP/2 Connection factory to an
existing connector.
Thus configuring HTTP/2 is a combination of configuring common properties on the connector and HTTP/2 specific properties on the connection factory.
The modules and XML files involved can be seen with the following commands:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar $JETTY_HOME/start.jar --list-modules
...
1) alpn-impl &lt;transitive&gt;
...
2) http ${jetty.base}/start.d/http.ini
2) ssl ${jetty.base}/start.d/ssl.ini
3) alpn ${jetty.base}/start.d/alpn.ini
3) http2c ${jetty.base}/start.d/http2c.ini
...
4) http2 ${jetty.base}/start.d/http2.ini
5) https ${jetty.base}/start.d/https.ini
$ java -jar $JETTY_HOME/start.jar --list-config
...
${jetty.home}/etc/jetty-ssl.xml
${jetty.home}/etc/jetty-ssl-context.xml
${jetty.home}/etc/jetty-alpn.xml
${jetty.home}/etc/jetty-http2c.xml
${jetty.home}/etc/jetty-http.xml
...
${jetty.home}/etc/jetty-http2.xml
${jetty.home}/etc/jetty-https.xml</code></pre>
</div>
</div>
<div class="paragraph">
<p>The common properties associated with connectors (host,port, timeouts, etc.) can be set in the module ini files (or <code>start.ini</code> if <code>--add-to-start</code> was used): <code>${jetty.base}/start.d/http.ini</code> and <code>${jetty.base}/start.d/ssl.ini</code>.
These properties are instantiated in the associated XML files: <code>${jetty.home}/etc/jetty-http.xml</code>; <code>${jetty.home}/etc/jetty-ssl.xml</code>, plus the SSL keystore is instantiated in <code>${jetty.home}/etc/jetty-ssl-context.xml</code>.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you are planning to edit XML files, make sure to copy them to your <code>{$jetty.base}/etc/</code> directory before doing so.
The XML files that come with the Jetty distribution should <strong>not</strong> be modified directly.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>HTTP/2 specific properties can be set in the module ini files: <code>${jetty.base}/start.d/http2.ini</code> and <code>${jetty.base}/start.d/http2c.ini</code>, which are instantiated in the associated XML files: <code>${jetty.home}/etc/jetty-http2.xml</code>; <code>${jetty.home}/etc/jetty-http2c.xml</code>, respectively.
Currently there are very few HTTP/2 configuration properties and the default values are reasonable:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 5. HTTP/2 Configuration Properties</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jetty.http2.maxConcurrentStreams</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of concurrently open streams allowed on a single HTTP/2 connection (default 128). Larger values increase parallelism but cost a memory commitment.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jetty.http2.initialSessionRecvWindow</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The initial receive flow control window size for a new session (default 1048576). Larger values may allow greater throughput but also risk head of line blocking if TCP/IP flow control is triggered.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jetty.http2.initialStreamRecvWindow</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The initial receive flow control window size for a new stream (default 524288). Larger values may allow greater throughput but also risk head of line blocking if TCP/IP flow control is triggered.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="http2-configuring-push">Configuring HTTP/2 Push</h3>
<div class="paragraph">
<p>HTTP/2 Push is a mechanism that allows the server to send multiple resources to the client for a single client request.
This will reduce the amount of round-trips necessary to retrieve all the resources that make up a web page and can significantly improve the page load time.</p>
</div>
<div class="paragraph">
<p>HTTP/2 Push can be automated in your application by configuring a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/PushCacheFilter.html"><code>PushCacheFilter</code></a> in the <code>web.xml</code>, in this way:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;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_3_1.xsd"
metadata-complete="true"
version="3.1"&gt;
...
&lt;filter&gt;
&lt;filter-name&gt;PushFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.eclipse.jetty.servlets.PushCacheFilter&lt;/filter-class&gt;
&lt;async-supported&gt;true&lt;/async-supported&gt;
&lt;/filter&gt;
&lt;filter-mapping&gt;
&lt;filter-name&gt;PushFilter&lt;/filter-name&gt;
&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
...
&lt;/web-app&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p><code>PushCacheFilter</code> analyzes the HTTP requests for resources that arrive to your web application.
Some of these requests contain the HTTP <code>Referer</code> header that points to a resource that has been requested previously.</p>
</div>
<div class="paragraph">
<p>This allows the <code>PushCacheFilter</code> to organize resources in a tree, for example a root <code>index.html</code> resource having two children resources, <code>styles.css</code> and <code>application.js</code>, and <code>styles.css</code> having a child resource, <code>background.png</code>.
The root resource is called the <em>primary</em> resource, while descendant resources are called <em>secondary</em> resources.</p>
</div>
<div class="paragraph">
<p>The resource tree is built using a time window so that when a root resource is requested, only subsequent requests that are made within the time window will be added to the resource tree.
The resource tree can also be limited in size so that the number of secondary resources associated to a primary resource is limited.</p>
</div>
<div class="paragraph">
<p>By default, only the resource <em>path</em> (without the <em>query</em> string) is used to associate secondary resources to the primary resource, but you can configure <code>PushCacheFilter</code> to take the query string into account.</p>
</div>
<div class="paragraph">
<p><code>PushCacheFilter</code> can be configured with the following <code>init-params</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>associatePeriod</code>: the time window, in milliseconds, within which a request for a secondary resource will be associated to a primary resource; defaults to 4000 ms</p>
</li>
<li>
<p><code>maxAssociations</code>: the max number of secondary resources that may be associated to a primary resource; defaults to 16</p>
</li>
<li>
<p><code>hosts</code>: a comma separated list of hosts that are allowed in the <code>Referer</code> header; defaults to the host in the <code>Host</code> header</p>
</li>
<li>
<p><code>ports</code>: a comma separated list of ports that are allowed in the <code>Referer</code> header; defaults to the port in the <code>Host</code> header</p>
</li>
<li>
<p><code>useQueryInKey</code>: a boolean indicating whether the query string of the request should be considered when associating secondary resources to primary resources; defaults to <code>false</code></p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="http2-configuring-haproxy">Configuring HAProxy and Jetty</h3>
<div class="paragraph">
<p>Typical website deployments have Apache (or Nginx) configured as reverse proxy to talk to one or more backend Jetty instances.
This configuration cannot be used for HTTP/2 because Apache does not yet support HTTP/2 (nor does Nginx).</p>
</div>
<div class="paragraph">
<p><a href="http://haproxy.org">HAProxy</a> is an open source solution that offers load balancing and proxying for TCP and HTTP based application, and can be used as a replacement for Apache or Nginx when these are used as reverse proxies and has the major benefit that supports HTTP/2.
It also offers load balancing and several other features which can position it as a complete replacement for Apache or Nginx.</p>
</div>
<div class="paragraph">
<p>The deployment proposed here will have HAProxy play the role that Apache and Nginx usually do: to perform the TLS offloading (that is, decrypt and encrypt TLS) and then forwarding the now clear-text traffic to a backend Jetty server, speaking either HTTP/1.1 or HTTP/2.</p>
</div>
<div class="paragraph">
<p>The instructions that follow are for Linux.</p>
</div>
<div class="sect3">
<h4 id="http2-haproxy-install">Installing HAProxy</h4>
<div class="paragraph">
<p>You will need HAProxy 1.5 or later, because it provides support for SSL and ALPN, both required by HTTP/2. Most Linux distributions have the HAProxy package available to be installed out of the box. For example on Ubuntu 15.04:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ sudo apt-get install haproxy</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively you can download the HAProxy source code and build it on your environment by following the README bundled with the HAProxy source code tarball.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
HAProxy supports ALPN only if built with OpenSSL 1.0.2 or greater.
Use <code>haproxy -vv</code> to know with which OpenSSL version HAProxy has been built.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="http2-haproxy-ssl">Setup SSL for HAProxy</h4>
<div class="paragraph">
<p>HAProxy will perform the TLS decryption and encryption much more efficiently than a Java implementation.</p>
</div>
<div class="paragraph">
<p>HAProxy will need a single file containing the X509 certificates and the private key, all in <a href="https://en.wikipedia.org/wiki/X.509">PEM format</a>, with the following order:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>The site certificate; this certificate&#8217;s Common Name refers to the site domain (for example: CN=*.webtide.com) and is signed by Certificate Authority #1.</p>
</li>
<li>
<p>The Certificate Authority #1 certificate; this certificate may be signed by Certificate Authority #2.</p>
</li>
<li>
<p>The Certificate Authority #2 certificate; this certificate may be signed by Certificate Authority #3; and so on until the Root Certificate Authority.</p>
</li>
<li>
<p>The Root Certificate Authority certificate.</p>
</li>
<li>
<p>The private key corresponding to the site certificate.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Let&#8217;s use <code>keytool</code> to generate a self signed certificate:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -genkeypair -keyalg RSA -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -ext SAN=DNS:domain.com
What is your first and last name?
[Unknown]: *.domain.com
What is the name of your organizational unit?
[Unknown]: Unit
What is the name of your organization?
[Unknown]: Domain
What is the name of your City or Locality?
[Unknown]: Torino
What is the name of your State or Province?
[Unknown]: TO
What is the two-letter country code for this unit?
[Unknown]: IT
Is CN=*.domain.com, OU=Unit, O=Domain, L=Torino, ST=TO, C=IT correct?
[no]: yes</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above command will generate a self signed certificate and private key for <code>domain.com</code> and subdomains, stored in the <code>keystore.p12</code> file in PKCS#12 format.
We need to extract the certificate and the private key in PEM format.</p>
</div>
<div class="paragraph">
<p>To extract the certificate into <code>certificate.pem</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ keytool -exportcert -keystore keystore.p12 -storetype pkcs12 -storepass storepwd -rfc -file certificate.pem</code></pre>
</div>
</div>
<div class="paragraph">
<p>To export the private key into <code>private_key.pem</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ openssl pkcs12 -in keystore.p12 -nodes -nocerts -out private_key.pem -passin pass:storepwd</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point you just need to concatenate the two files into one, in the correct order:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cat certificate.pem private_key.pem &gt; domain.pem</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>domain.pem</code> file will be used later by HAProxy.</p>
</div>
</div>
<div class="sect3">
<h4 id="http2-haproxy-cfg">HAProxy Configuration File</h4>
<div class="paragraph">
<p>Now we can setup <code>haproxy.cfg</code> to configure HAProxy.
This is a minimal configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>global
tune.ssl.default-dh-param 1024
defaults
timeout connect 10000ms
timeout client 60000ms
timeout server 60000ms
frontend fe_http
mode http
bind *:80
# Redirect to https
redirect scheme https code 301
frontend fe_https
mode tcp
bind *:443 ssl no-sslv3 crt domain.pem ciphers TLSv1.2 alpn h2,http/1.1
default_backend be_http
backend be_http
mode tcp
server domain 127.0.0.1:8282</code></pre>
</div>
</div>
<div class="paragraph">
<p>The HAProxy configuration file works in the following way.
The <code>fe_http</code> front-end accepts connections on port 80 and redirects them to use the <code>https</code> scheme.</p>
</div>
<div class="paragraph">
<p>The <code>fe_https</code> front-end accepts connections on port 443 and it is where the TLS decryption/encryption happens.
You must specify the path to the PEM file containing the TLS key material (the <code>crt domain.pem</code> part), the ciphers that are suitable for HTTP/2 (the <code>ciphers TLSv1.2</code>), and the ALPN protocols supported (the <code>alpn h2,http/1.1</code> ).
This front-end then forwards the now decrypted bytes to the back-end in <code>mode tcp</code>. The <code>mode tcp</code> says that HAProxy will not try to interpret the bytes as HTTP/1.1 but instead opaquely forward them to the back-end.</p>
</div>
<div class="paragraph">
<p>The <code>be_http</code> back-end will forward (again in <code>mode tcp</code>) the clear-text bytes to a Jetty connector that talks clear-text HTTP/2 and HTTP/1.1 on port 8282.</p>
</div>
</div>
<div class="sect3">
<h4 id="http2-haproxy-jetty">Setup Jetty for HTTP/2 and HTTP/1.1</h4>
<div class="paragraph">
<p>The Jetty setup follows the steps of having Jetty installed in the <code>JETTY_HOME</code> directory, creating a <code>JETTY_BASE</code> directory and initializing it using Jetty&#8217;s command line tools.
You must enable the <code>http2c</code> module, that is the module that speaks clear-text HTTP/2.
Since the <code>http2c</code> module depends on the <code>http</code> module, the <code>http</code> module will be enabled transitively, and the final setup will therefore support both HTTP/2 and HTTP/1.1 in clear text.</p>
</div>
<div class="paragraph">
<p>Additionally, you will also enable the <code>deploy</code> module to be able to deploy a sample web application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ JETTY_BASE=haproxy-jetty-http2
$ mkdir $JETTY_BASE
$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2c,deploy</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now let&#8217;s deploy a demo web application and start Jetty:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cd $JETTY_BASE
$ cp $JETTY_HOME/demo-base/webapps/async-rest.war $JETTY_BASE/webapps/
$ java -jar $JETTY_HOME/start.jar jetty.http.host=127.0.0.1 jetty.http.port=8282</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now you can browse <a href="https://domain.com/async-rest" class="bare">https://domain.com/async-rest</a> (replace <code>domain.com</code> with your own domain, or with <code>localhost</code>, to make this example work).</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
You want the Jetty connector that listens on port 8282 to be available only to HAProxy, and not to remote clients.
For this reason, you want to specify the <code>jetty.http.host</code> property on the command line (or in <code>start.ini</code>/ <code>start.d/http.ini</code> to make this setting persistent) to bind the Jetty connector only on the loopback interface (127.0.0.1), making it available to HAProxy but not to remote clients.
If your Jetty instance runs on a different machine and/or on a different (sub)network, you may want to adjust both the back-end section of the HAProxy configuration file and the <code>jetty.http.host</code> property to match accordingly.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Browsers supporting HTTP/2 will connect to HAProxy, which will decrypt the traffic and send it to Jetty.
Likewise, HTTP/1.1 clients will connect to HAProxy, which will decrypt the traffic and send it to Jetty.</p>
</div>
<div class="paragraph">
<p>The Jetty connector, configured with the <code>http2c</code> module (and therefore transitively with the <code>http</code> module) is able to distinguish whether the incoming bytes are HTTP/2 or HTTP/1.1 and will handle the request accordingly.</p>
</div>
<div class="paragraph">
<p>The response is relayed back to HAProxy, which will encrypt it and send it back to the remote client.</p>
</div>
<div class="paragraph">
<p>This configuration offers you efficient TLS offloading, HTTP/2 support and transparent fallback to HTTP/1.1 for clients that don&#8217;t support HTTP/1.1.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-logging">Jetty Logging</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter discusses various options for configuring logging.</p>
</div>
<div class="sect2">
<h3 id="configuring-jetty-logging">Configuring Jetty Logging</h3>
<div class="paragraph">
<p>Jetty provides logging via its own <code>org.eclipse.jetty.util.log.Logger</code> layer, and does not natively use any existing Java logging framework.
All logging events, produced via the Jetty logging layer, have a name, a level, and a message.
The name is a FQCN (fully qualified class name) similar to how all existing Java logging frameworks operate.</p>
</div>
<div class="paragraph">
<p>Jetty logging, however, has a slightly different set of levels that it uses internally:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">WARN</dt>
<dd>
<p>For events serious enough to inform and log, but not fatal.</p>
</dd>
<dt class="hdlist1">INFO</dt>
<dd>
<p>Informational events.</p>
</dd>
<dt class="hdlist1">DEBUG</dt>
<dd>
<p>Debugging events (very noisy).</p>
</dd>
<dt class="hdlist1">IGNORE</dt>
<dd>
<p>Exception events that you can safely ignore, but useful for some people.
You might see this level as DEBUG under some Java logging framework configurations, where it retains the <em>ignore</em> phrase somewhere in the logging.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Jetty logging produces no FATAL or SEVERE events.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect3">
<h4 id="selecting-log-framework">Selecting the Log Framework</h4>
<div class="paragraph">
<p>Configure the Jetty logging layer via the <code>org.eclipse.jetty.util.log.Log</code> class, following <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-util/src/main/java/org/eclipse/jetty/util/log/Log.java">these rules</a>.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Load Properties</p>
<div class="ulist">
<ul>
<li>
<p>First from a Classpath Resource called <code>jetty-logging.properties</code> (if found).</p>
</li>
<li>
<p>Then from the <code>System.getProperties()</code>.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Determine the log implementation.</p>
<div class="ulist">
<ul>
<li>
<p>If property <code>org.eclipse.jetty.util.log.class</code> is defined, load the class it defines as the logger implementation from the server <code>classpath</code>.</p>
</li>
<li>
<p>If the class <code>org.slf4j.Logger</code> exists in server classpath, the Jetty implementation becomes <code>org.eclipse.jetty.util.log.Slf4jLog</code>.</p>
</li>
<li>
<p>If no logger implementation is specified, default to <code>org.eclipse.jetty.util.log.StdErrLog</code>.</p>
</li>
</ul>
</div>
</li>
</ol>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
You can create your own custom logging by providing an implementation of the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOTorg/eclipse/jetty/util/log/Logger.html">Jetty Logger API</a>.
For an example of a custom logger, see <a href="https://github.com/eclipse/jetty.project/tree/master/jetty-util/src/main/java/org/eclipse/jetty/util/log/JavaUtilLog.java">JavaUtilLog.java</a>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="configuring-jetty-stderrlog">The jetty-logging.properties file</h4>
<div class="paragraph">
<p>By default, the internal Jetty Logging discovery mechanism will load logging specific properties from a classpath resource called <code>jetty-logging.properties</code> and then initialize the Logging from a combination of properties found in that file, along with any System Properties.
A typical jetty-logging.properties file will include at least the declaration of which logging implementation you want to use by defining a value for the <code>org.eclipse.jetty.util.log.class</code> property.</p>
</div>
<div class="paragraph">
<p>Examples for various logging frameworks can be found later in this documentation.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Default Logging with <a href="#default-logging-with-stderrlog">Jetty&#8217;s StdErrLog</a></p>
</li>
<li>
<p>Using <a href="#example-logging-log4j">Log4j or Log4j2 via SLF4J</a></p>
</li>
<li>
<p>Using <a href="#example-logging-logback">Logback via SLF4J</a></p>
</li>
<li>
<p>Using <a href="#example-logging-java-util-logging">Java Util Logging via SLF4J</a></p>
</li>
<li>
<p>Using <a href="#example-logging-java-commons-logging">Java Commons Logging via SLF4J</a></p>
</li>
<li>
<p><a href="#example-logging-logback-centralized">Centralized Logging with Logback and Sfl4jLog</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="default-logging-with-stderrlog">Default Logging with Jetty&#8217;s StdErrLog</h3>
<div class="sect3">
<h4 id="stderrlog-configuration">StdErrLog Configuration</h4>
<div class="paragraph">
<p>If you do nothing to configure a separate logging framework, Jetty will default to using an internal <code>org.eclipse.jetty.util.log.StdErrLog</code> implementation.
This will output all logging events to STDERR (aka <code>System.err</code>).</p>
</div>
<div class="paragraph">
<p>Simply use Jetty and <code>StdErrLog</code>-based logging is output to the console.</p>
</div>
<div class="paragraph">
<p>Included in the Jetty distribution is a logging module named <code>console-capture</code> that is capable of performing simple capturing of all STDOUT (<code>System.out</code>) and STDERR (<code>System.err</code>) output to a file that is rotated daily.</p>
</div>
<div class="paragraph">
<p>To enable this feature, simply activate the <code>console-capture</code> module on the command line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs
INFO : Base directory was modified
[my-base]$ tree
.
├── logs
└── start.d
└── console-capture.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default configuration for logging output will create a file <code>${jetty.base}/logs/yyyy_mm_dd.stderrout.log</code> which allows configuration of the output directory by setting the <code>jetty.logs</code> property.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
By default, logs are not set to be appended, meaning a the log file is wiped clean upon sever restart.
You can change this setting by editing the <code>console-capture.ini</code> and un-commenting the line that reads <code>jetty.console-capture.append=true</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Just enabling the <code>console-capture</code> will simply output the values of STDERR and STDOUT to a log file.
To customize the log further, a module named <code>logging-jetty</code> is available to provides a default properties file to configure.
As with <code>console-capture</code>, you activate the <code>logging-jetty</code> on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/logging-jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified
[my-base]$ tree
.
├── logs
├── resources
│   └── jetty-logging.properties
└── start.d
├── console-capture.ini
└── logging-jetty.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once activated, you can find the properties file at <code>${jetty.base}/resources/jetty-logging.properties</code>.
By default, the following parameters are defined.
To change them, un-comment the line and substitute your naming scheme and configuration choices.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">## Force jetty logging implementation
#org.eclipse.jetty.util.log.class=org.eclipse.jetty.util.log.StdErrLog
## Set logging levels from: ALL, DEBUG, INFO, WARN, OFF
#org.eclipse.jetty.LEVEL=INFO
#com.example.LEVEL=INFO
## Hide stacks traces in logs?
#com.example.STACKS=false
## Show the source file of a log location?
#com.example.SOURCE=false</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are a number of properties that can be defined in the configuration that will affect the behavior of StdErr logging with <code>console-capture</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>&lt;name&gt;.LEVEL=&lt;level&gt;</code></dt>
<dd>
<p>Sets the logging level for all loggers within the <code>name</code> specified to the level, which can be (in increasing order of restriction) <code>ALL</code>, <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code>, <code>OFF</code>.
The name (or hierarchy) can be a specific fully qualified class or a package namespace.
For example, <code>org.eclipse.jetty.http.LEVEL=DEBUG</code> is a package namespace approach to turn all loggers in the Jetty HTTP package to DEBUG level, and <code>org.eclipse.jetty.io.ChanelEndPoint.LEVEL=ALL</code> turns on all logging events for the specific class, including <code>DEBUG</code>, <code>INFO</code>, <code>WARN</code> (and even special internally ignored exception classes).
If more than one system property specifies a logging level, the most specific one applies.</p>
</dd>
<dt class="hdlist1"><code>&lt;name&gt;.SOURCE=&lt;boolean&gt;</code></dt>
<dd>
<p>Named Logger specific, attempts to print the Java source file name and line number from where the logging event originated.
Name must be a fully qualified class name (this configurable does not support package name hierarchy).
Default is false.
Be aware that this is a slow operation and has an impact on performance.</p>
</dd>
<dt class="hdlist1"><code>&lt;name&gt;.STACKS=&lt;boolean&gt;</code></dt>
<dd>
<p>Named Logger specific, controls the display of stacktraces.
Name must be a fully qualified class name (this configurable does not support package name hierarchy).
Default is true.</p>
</dd>
<dt class="hdlist1"><code>org.eclipse.jetty.util.log.stderr.SOURCE=&lt;boolean&gt;</code></dt>
<dd>
<p>Special Global Configuration.
Attempts to print the Java source file name and line number from where the logging event originated.
Default is false.</p>
</dd>
<dt class="hdlist1"><code>org.eclipse.jetty.util.log.stderr.LONG=&lt;boolean&gt;</code></dt>
<dd>
<p>Special Global Configuration.
When true, outputs logging events to <code>STDERR</code> using long form, fully qualified class names.
When false, uses abbreviated package names.
Default is false.</p>
<div class="ulist">
<ul>
<li>
<p>Example when set to false:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">2016-10-21 15:31:01.248:INFO::main: Logging initialized @332ms to org.eclipse.jetty.util.log.StdErrLog
2016-10-21 15:31:01.370:INFO:oejs.Server:main: jetty-10.0.0-SNAPSHOT
2016-10-21 15:31:01.400:INFO:oejs.AbstractConnector:main: Started ServerConnector@2c330fbc{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-10-21 15:31:01.400:INFO:oejs.Server:main: Started @485ms</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Example when set to true:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">2016-10-21 15:31:35.020:INFO::main: Logging initialized @340ms to org.eclipse.jetty.util.log.StdErrLog
2016-10-21 15:31:35.144:INFO:org.eclipse.jetty.server.Server:main: jetty-10.0.0-SNAPSHOT
2016-10-21 15:31:35.174:INFO:org.eclipse.jetty.server.AbstractConnector:main: Started ServerConnector@edf4efb{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
2016-10-21 15:31:35.175:INFO:org.eclipse.jetty.server.Server:main: Started @495ms</code></pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="deprecated-parameters">Deprecated Parameters</h4>
<div class="paragraph">
<p>These parameters existed in prior versions of Jetty, and are no longer supported.
They are included here for historical (and search engine) reasons.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>org.eclipse.jetty.util.log.DEBUG</code></dt>
<dd>
<p>Formerly used to enable DEBUG level logging on any logger used within Jetty (not just Jetty&#8217;s own logger).</p>
<div class="ulist">
<ul>
<li>
<p>Replaced with using the logger implementation specific configuration and level filtering.</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1"><code>org.eclipse.jetty.util.log.stderr.DEBUG</code></dt>
<dd>
<p>Formerly used to enable DEBUG level logging on the internal Jetty <code>StdErrLog</code> implementation.</p>
<div class="ulist">
<ul>
<li>
<p>Replaced with level specific equivalent.
Example: <code>org.eclipse.jetty.LEVEL=DEBUG</code></p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1"><code>DEBUG</code></dt>
<dd>
<p>Ancient debugging flag that turned on all debugging, even non-logging debugging.</p>
<div class="ulist">
<ul>
<li>
<p>Jetty no longer uses because many third party libraries employ this overly simple property name, which would generate far too much console output.</p>
</li>
</ul>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-jetty-request-logs">Configuring Jetty Request Logs</h3>
<div class="paragraph">
<p>Request logs are a record of the requests that the server has processed.
There is one entry per request received, and commonly in the standard NCSA format, so you can use tools like <a href="http://en.wikipedia.org/wiki/Webalizer">Webalizer</a> to analyze them conveniently.</p>
</div>
<div class="sect3">
<h4 id="constructing-request-log-entry">Constructing a Request Log Entry</h4>
<div class="paragraph">
<p>A standard request log entry includes the client IP address, date, method, URL, result, size, referrer, user agent and latency.
For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>123.4.5.6 - - [20/Jul/2016:10:16:17 +0000]
"GET /jetty/tut/XmlConfiguration.html HTTP/1.1"
200 76793 "http://localhost:8080/jetty/tut/logging.html"
"Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.6) Gecko/20040614 Firefox/0.8" 342</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="implementing-request-log">Implementing a Request Log</h4>
<div class="paragraph">
<p>Jetty provides an implementation called <code>NCSARequestLog</code> which supports the NCSA format in files that will roll over on a daily basis.</p>
</div>
<div class="paragraph">
<p>The <a href="http://logback.qos.ch/">Logback Project</a> offers <a href="http://logback.qos.ch/access.html">another implementation</a> of a <code>RequestLog</code> interface, providing rich and powerful HTTP-access log functionality.</p>
</div>
<div class="paragraph">
<p>If neither of these options meets your needs, you can implement a custom request logger by implementing Jetty&#8217;s <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/RequestLog.html"><code>RequestLog.java</code></a> interface and plugging it in similar to the <code>NCSARequestLog</code>, as shown below.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-request-log">Configuring the Request Log module</h4>
<div class="paragraph">
<p>To enable the Request Log module for the entire server via the Jetty distribution, it first needs to be enabled on the command line:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --add-to-start=requestlog
INFO: requestlog initialised in ${jetty.base}/start.d/requestlog.ini
MKDIR: ${jetty.base}/logs
INFO: Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>The above command will add a new <code>requestlog.ini</code> file to your <a href="#start-vs-startd"><code>{$jetty.base}/start.d</code> directory</a>.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
By default, request logs are not set to be appended, meaning a the log file is wiped clean upon sever restart.
You can change this setting by editing the <code>requestlog.ini</code> and un-commenting the line that reads <code>jetty.requestlog.append=true</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>The equivalent code for embedded usages of Jetty is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">NCSARequestLog requestLog = new NCSARequestLog("/var/logs/jetty/jetty-yyyy_mm_dd.request.log");
requestLog.setAppend(true);
requestLog.setExtended(false);
requestLog.setLogTimeZone("GMT");
requestLog.setLogLatency(true);
requestLog.setRetainDays("90");
server.setRequestLog(requestLog);</code></pre>
</div>
</div>
<div class="paragraph">
<p>This configures a request log in <code>{$jetty.home}/logs</code> with filenames including the date.
Existing log files are appended to and the extended NCSA format is used in the GMT time zone.</p>
</div>
<div class="paragraph">
<p>The above configuration enables Log Latency, which is the amount of time it took the server to handle the request.
This value is measured in milliseconds and is appended to the the log file for each request.</p>
</div>
<div class="paragraph">
<p>You can also customize the number of days you wish to keep request logs.
By default, log files are kept for 90 days before being deleted.
The value for <code>retainDays</code> (xml) or <code>setRetainDays</code> (Java) should be configured as <em>1 + n</em> days.
For example, if you wanted to keep the logs for the current day and the day prior you would set the <code>retainDays</code> (or <code>setRetainDays</code>) value to 2.</p>
</div>
</div>
<div class="sect3">
<h4 id="request-log-custom-writer">Introducing RequestLog.Writer</h4>
<div class="paragraph">
<p>The concept of a <code>RequestLog.Writer</code>, introduced in Jetty 9.4.15, manages the writing to a log the string generated by the <code>RequestLog</code>.
This allows the <code>CustomRequestLog</code> to match the functionality of other <code>RequestLogger</code> implementations by plugging in any <code>RequestLog.Writer</code> and a custom format string.
Jetty currently has implementations of <code>RequestLog.Writer</code>, <code>RequestLogWriter</code>, <code>AsyncRequestLogWriter</code>, and <code>Slf4jRequestLogWriter</code>.</p>
</div>
<div class="paragraph">
<p>So, the way to create an asynchronous <code>RequestLog</code> using the extended NCSA format has been changed from:</p>
</div>
<div class="paragraph">
<p><code>new AsyncNcsaRequestLog(filename)</code></p>
</div>
<div class="paragraph">
<p>to:</p>
</div>
<div class="paragraph">
<p><code>new CustomRequestLog(new AsyncRequestLogWriter(filename), CustomRequestLog.EXTENDED_NCSA_FORMAT)</code></p>
</div>
<div class="paragraph">
<p>Additionally, there are now two settings for the log timezone to be configured.
There is the configuration for logging the request time, which is set in the <code>timeZone</code> parameter in the <code>%t</code> format code of the string, given in the format <code>%{format|timeZone|locale}t</code>.</p>
</div>
<div class="paragraph">
<p>The other <code>timeZone</code> parameter relates to the generation of the log file name (both at creation and roll over).
This is configured in the <code>requestlog</code> module file, or can be used as a setter on <code>RequestLogWriter</code> via XML.</p>
</div>
<div class="paragraph">
<p>Both timezones are set to GMT by default.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-separate-request-log-for-web-application">Configuring a Separate Request Log For a Web Application</h4>
<div class="paragraph">
<p>To configure a separate request log for specific a web application, add the following to the context XML file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
...
&lt;Call name="insertHandler"&gt;
&lt;Arg&gt;
&lt;New id="RequestLog" class="org.eclipse.jetty.server.handler.RequestLogHandler"&gt;
&lt;Set name="requestLog"&gt;
&lt;New id="RequestLogImpl" class="org.eclipse.jetty.server.NCSARequestLog"&gt;
&lt;Set name="filename"&gt;&lt;Property name="jetty.logs" default="./logs"/&gt;/test-yyyy_mm_dd.request.log&lt;/Set&gt;
&lt;Set name="filenameDateFormat"&gt;yyyy_MM_dd&lt;/Set&gt;
&lt;Set name="LogTimeZone"&gt;GMT&lt;/Set&gt;
&lt;Set name="retainDays"&gt;90&lt;/Set&gt;
&lt;Set name="append"&gt;true&lt;/Set&gt;
&lt;Set name="LogLatency"&gt;true&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
...
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-logging-modules">Jetty Logging Integrations (SLF4J, Log4j, Logback, JCL, JUL)</h3>
<div class="paragraph">
<p>Jetty provides support for several logging frameworks including SLF4J, Java Commons Logging (JCL), Java Util Logging (JUL), Log4j (including version 2), and Logback.
This page includes examples of how to enable the associated modules for these different frameworks.
These modules are designed to capture container/server logs; <a href="#configuring-jetty-request-logs">request logs</a> and application logs need to be configured separately.
Please note that enabling these modules provides typical and basic functionality for each framework; advanced implementations may require their <a href="#startup-modules">own modules</a> or additional configuration.</p>
</div>
<div class="paragraph">
<p>Enabling these frameworks in the Jetty distribution is as easy as activating any other module, by adding <code>--add-to-start=&lt;module name&gt;</code> to the start command for your server, such as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-jetty
INFO : logging-jetty initialized in ${jetty.base}/start.d/logging-jetty.ini
INFO : resources transitively enabled
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/logging-jetty/resources/jetty-logging.properties to ${jetty.base}/resources/jetty-logging.properties
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>As noted above, Jetty supports a wide array of logging technologies.
If a particular logging framework requires additional jar files, Jetty will automatically download these as part of enabling the associated module and any dependent modules will be transitively enabled.</p>
</div>
<div class="paragraph">
<p>A list of the base Jetty logging modules by running <code>java -jar &lt;path-to-jetty.home&gt;/start.jar --list-modules=logging,-internal</code>.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">logging-jcl</dt>
<dd>
<p>Configures Jetty logging to use Java Commons Logging (JCL), using SLF4J as a binding.</p>
</dd>
<dt class="hdlist1">logging-jetty</dt>
<dd>
<p>Standard Jetty logging that captures <code>System.err</code> and <code>System.out</code> output.</p>
</dd>
<dt class="hdlist1">logging-jul</dt>
<dd>
<p>Configures Jetty logging to use Java Util Logging (JUL), using SLF4J as a binding.</p>
</dd>
<dt class="hdlist1">logging-log4j</dt>
<dd>
<p>Configures Jetty logging to use Log4j as the logging implementation, using SLF4J as a binding.</p>
</dd>
<dt class="hdlist1">logging-log4j2</dt>
<dd>
<p>Configures Jetty logging to use Log4j2 as the logging implementation, using SLF4J as a binding.</p>
</dd>
<dt class="hdlist1">logging-logback</dt>
<dd>
<p>Configures Jetty logging to use Logback as the logging implementation, using SLF4J as a binding.</p>
</dd>
<dt class="hdlist1">logging-slf4j</dt>
<dd>
<p>Configures Jetty logging to use SLF4J and provides a <code>slf4j-impl</code> which can be used by other logging frameworks.
If no other logging is configured, <code>slf4j-simple</code> is used.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>You can view a list of <strong>all</strong> the Jetty logging modules by running <code>java -jar &lt;path-to-jetty.home&gt;/start.jar --list-modules=logging</code>.
This will display all logging modules, including implementation and binding modules.</p>
</div>
<div class="paragraph">
<p>All these modules (with the exception of <code>logging-jetty</code>) arrange for the Jetty private logging API to be routed to the named technology to actually be logged.
For example, enabling the <code>logging-log4j</code> module will do several things:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>it enables an internal Log4j API module so that any container code that uses Log4j will find the API.</p>
</li>
<li>
<p>it enables an internal Log4j Implementation so that any container code that uses the Log4j API will also use a Log4j implementation to handle the logs (and all the normal Log4j configuration mechanisms etc.)</p>
</li>
<li>
<p>it enables the internal <code>slf4j-log4j</code> logging binding so that any container code that uses the SLF4j API to also use the Log4j implementation via the Log4j API.</p>
</li>
<li>
<p>it configures the Jetty logging API to use the SLF4J API, which is then bound to Log4j.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>So, after enabling <code>logging-log4j</code>, within the server container there are 3 logging APIs available: Jetty, SLF4J and Log4J.
But there is only a single logging <strong>implementation</strong> - Log4j; the 3 APIs act only as facades over the Log4j implementation.</p>
</div>
<div class="paragraph">
<p>Note that you can add additional APIs to this configuration.
For example, enabling the internal module <code>jcl-slf4j</code> would add in a Java Commons Logging facade that also would use the Log4j implementation via the SLF4J binding.</p>
</div>
<div class="paragraph">
<p>Most other top level logging modules work in the same way: <code>logging-jcl</code>, <code>logging-jul</code>, <code>logging-slf4j</code>, <code>logging-log4j2</code> and <code>logging-logback</code> all bind their implementation via SLF4J.</p>
</div>
<div class="sect3">
<h4 id="example-logging-slf4j">Logging with SLF4J</h4>
<div class="paragraph">
<p>Jetty uses the SLF4J api as a binding to provide logging information to additional frameworks such as Log4j or Logback.
It can also be used on it&#8217;s own to provide simple server logging.
To enable the SLF4J framework, you need to activate the <code>logging-slf4j</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-slf4j
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: slf4j-api
+ SLF4J is distributed under the MIT License.
+ Copyright (c) 2004-2013 QOS.ch
+ All rights reserved.
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Proceed (y/N)? y
INFO : slf4j-api transitively enabled
INFO : logging-slf4j initialized in ${jetty.base}/start.d/logging-slf4j.ini
MKDIR : ${jetty.base}/lib/slf4j
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar
INFO : Base directory was modified
ERROR : Module logging-slf4j requires a module providing slf4j-impl from one of [slf4j-simple-impl, slf4j-logback, slf4j-jul, slf4j-log4j2, slf4j-log4j]
ERROR : Unsatisfied module dependencies: logging-slf4j
Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
java -jar $JETTY_HOME/start.jar --help # for more information</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you probably noticed, the system gives an <code>ERROR</code> when trying to enable the <code>logging-slf4j</code> on it&#8217;s own.
The <code>logging-slf4j</code> module itself provides the SLF4J api, but as SLF4J is often used as a binding for other logging frameworks does not by default provide an implementation.
To enable the simple SLF4J implementation, we will also need to activate the <code>slf4j-simple-impl</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=slf4j-simple-impl
INFO : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
INFO : resources transitively enabled
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-simple/1.7.21/slf4j-simple-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-simple-1.7.21.jar
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/slf4j-simple-impl/resources/simplelogger.properties to ${jetty.base}/resources/simplelogger.properties
INFO : Base directory was modified
[my-base]$ tree
.
├── lib
│   └── slf4j
│   ├── slf4j-api-1.7.21.jar
│   └── slf4j-simple-1.7.21.jar
├── resources
│   └── simplelogger.properties
└── start.d
├── logging-slf4j.ini
└── slf4j-simple-impl.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>Jetty is now configured to log using the SLF4J framework.
A standard SLF4J properties file is located in <code>${jetty.base}/resources/simplelogger.properties</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="example-logging-log4j">Logging with Log4j and Log4j2</h4>
<div class="paragraph">
<p>It is possible to have the Jetty Server logging configured so that Log4j or Log4j2 controls the output of logging events produced by Jetty.
This is accomplished by configuring Jetty for logging to <a href="http://logging.apache.org/log4j/">Apache Log4j</a> via <a href="http://slf4j.org/manual.html">Slf4j</a> and the <a href="http://slf4j.org/manual.html#swapping">Slf4j binding layer for Log4j</a>.
Implementation of Log4j can be done by enabling the <code>logging-log4j</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-log4j
ALERT: There are enabled module(s) with licenses.
The following 2 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: log4j-impl
+ Log4j is released under the Apache 2.0 license.
+ http://www.apache.org/licenses/LICENSE-2.0.html
Module: slf4j-api
+ SLF4J is distributed under the MIT License.
+ Copyright (c) 2004-2013 QOS.ch
+ All rights reserved.
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Proceed (y/N)? y
INFO : slf4j-api transitively enabled
INFO : log4j-impl transitively enabled
INFO : resources transitively enabled
INFO : slf4j-log4j transitively enabled
INFO : logging-log4j initialized in ${jetty.base}/start.d/logging-log4j.ini
MKDIR : ${jetty.base}/lib/slf4j
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar
MKDIR : ${jetty.base}/lib/log4j
COPY : /Users/admin/.m2/repository/log4j/log4j/1.2.17/log4j-1.2.17.jar to ${jetty.base}/lib/log4j/log4j-1.2.17.jar
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/log4j-impl/resources/log4j.xml to ${jetty.base}/resources/log4j.xml
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-log4j12/1.7.21/slf4j-log4j12-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-log4j12-1.7.21.jar
INFO : Base directory was modified
[my-base]$ tree
.
├── lib
│   ├── log4j
│   │   └── log4j-1.2.17.jar
│   └── slf4j
│   ├── slf4j-api-1.7.21.jar
│   └── slf4j-log4j12-1.7.21.jar
├── resources
│   └── log4j.xml
└── start.d
└── logging-log4j.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>Jetty is now configured to log using the Log4j framework.
A standard Log4j configuration file is located in <code>${jetty.base}/resources/log4j.xml</code>.</p>
</div>
<div class="paragraph">
<p>Or, to set up Log4j2, enable the <code>logging-log4j2</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-log4j2
ALERT: There are enabled module(s) with licenses.
The following 2 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: log4j2-api
+ Log4j is released under the Apache 2.0 license.
+ http://www.apache.org/licenses/LICENSE-2.0.html
Module: slf4j-api
+ SLF4J is distributed under the MIT License.
+ Copyright (c) 2004-2013 QOS.ch
+ All rights reserved.
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Proceed (y/N)? y
INFO : slf4j-api transitively enabled
INFO : logging-log4j2 initialized in ${jetty.base}/start.d/logging-log4j2.ini
INFO : log4j2-api transitively enabled
INFO : resources transitively enabled
INFO : slf4j-log4j2 transitively enabled
INFO : log4j2-impl transitively enabled
MKDIR : ${jetty.base}/lib/slf4j
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar
MKDIR : ${jetty.base}/lib/log4j2
DOWNLD: https://repo1.maven.org/maven2/org/apache/logging/log4j/log4j-api/2.6.1/log4j-api-2.6.1.jar to ${jetty.base}/lib/log4j2/log4j-api-2.6.1.jar
MKDIR : ${jetty.base}/resources
DOWNLD: https://repo1.maven.org/maven2/org/apache/logging/log4j/log4j-slf4j-impl/2.6.1/log4j-slf4j-impl-2.6.1.jar to ${jetty.base}/lib/log4j2/log4j-slf4j-impl-2.6.1.jar
DOWNLD: https://repo1.maven.org/maven2/org/apache/logging/log4j/log4j-core/2.6.1/log4j-core-2.6.1.jar to ${jetty.base}/lib/log4j2/log4j-core-2.6.1.jar
COPY : ${jetty.home}/modules/log4j2-impl/resources/log4j2.xml to ${jetty.base}/resources/log4j2.xml
INFO : Base directory was modified
[my-base]$ tree
.
├── lib
│   ├── log4j2
│   │   ├── log4j-api-2.6.1.jar
│   │   ├── log4j-core-2.6.1.jar
│   │   └── log4j-slf4j-impl-2.6.1.jar
│   └── slf4j
│   └── slf4j-api-1.7.21.jar
├── resources
│   └── log4j2.xml
└── start.d
└── logging-log4j2.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point Jetty is configured so that the Jetty server itself will log using Log4j2, using the Log4j2 configuration found in <code>{$jetty.base}/resources/log4j2.xml</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="example-logging-logback">Logging with Logback</h4>
<div class="paragraph">
<p>It is possible to have the Jetty Server logging configured so that Logback controls the output of logging events produced by Jetty.
This is accomplished by configuring Jetty for logging to <code>Logback</code>, which uses <a href="http://slf4j.org/manual.html">Slf4j</a> and the <a href="http://logback.qos.ch/">Logback Implementation for Slf4j</a>.</p>
</div>
<div class="paragraph">
<p>To set up Jetty logging via Logback, enable the <code>logging-logback</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-logback
ALERT: There are enabled module(s) with licenses.
The following 2 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: logback-impl
+ Logback: the reliable, generic, fast and flexible logging framework.
+ Copyright (C) 1999-2012, QOS.ch. All rights reserved.
+ This program and the accompanying materials are dual-licensed under
+ either:
+ the terms of the Eclipse Public License v1.0
+ as published by the Eclipse Foundation:
+ http://www.eclipse.org/legal/epl-v10.html
+ or (per the licensee's choosing) under
+ the terms of the GNU Lesser General Public License version 2.1
+ as published by the Free Software Foundation:
+ http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html
Module: slf4j-api
+ SLF4J is distributed under the MIT License.
+ Copyright (c) 2004-2013 QOS.ch
+ All rights reserved.
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Proceed (y/N)? y
INFO : slf4j-api transitively enabled
INFO : logback-impl transitively enabled
INFO : slf4j-logback transitively enabled
INFO : logging-logback initialized in ${jetty.base}/start.d/logging-logback.ini
INFO : resources transitively enabled
MKDIR : ${jetty.base}/lib/slf4j
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar
MKDIR : ${jetty.base}/lib/logback
DOWNLD: https://repo1.maven.org/maven2/ch/qos/logback/logback-core/1.1.7/logback-core-1.1.7.jar to ${jetty.base}/lib/logback/logback-core-1.1.7.jar
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/logback-impl/resources/logback.xml to ${jetty.base}/resources/logback.xml
DOWNLD: https://repo1.maven.org/maven2/ch/qos/logback/logback-classic/1.1.7/logback-classic-1.1.7.jar to ${jetty.base}/lib/logback/logback-classic-1.1.7.jar
INFO : Base directory was modified
[my-base]$ tree
.
├── lib
│   ├── logback
│   │   ├── logback-classic-1.1.7.jar
│   │   └── logback-core-1.1.7.jar
│   └── slf4j
│   └── slf4j-api-1.7.21.jar
├── resources
│   └── logback.xml
└── start.d
└── logging-logback.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>At this point Jetty is configured so that the Jetty server itself will log using Logback, using the Logback configuration found in <code>{$jetty.base}/resources/logback.xml</code>.</p>
</div>
</div>
<div class="sect3">
<h4>Logging with Java Util Logging</h4>
<div class="sect4">
<h5 id="example-logging-java-util-logging">Java Util Logging with SLF4J</h5>
<div class="paragraph">
<p>It is possible to have the Jetty Server logging configured so that <code>java.util.logging</code> controls the output of logging events produced by Jetty.</p>
</div>
<div class="paragraph">
<p>This example demonstrates how to configuring Jetty for logging to <code>java.util.logging</code> via <a href="http://slf4j.org/manual.html">SLF4J</a> as a binding layer.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=logging-jul
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: slf4j-api
+ SLF4J is distributed under the MIT License.
+ Copyright (c) 2004-2013 QOS.ch
+ All rights reserved.
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Proceed (y/N)? y
INFO : jul-impl transitively enabled
INFO : slf4j-api transitively enabled
INFO : slf4j-jul transitively enabled
INFO : logging-jul initialized in ${jetty.base}/start.d/logging-jul.ini
INFO : resources transitively enabled
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/jul-impl/etc/java-util-logging.properties to ${jetty.base}/etc/java-util-logging.properties
MKDIR : ${jetty.base}/lib/slf4j
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-jdk14/1.7.21/slf4j-jdk14-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-jdk14-1.7.21.jar
INFO : Base directory was modified
[my-base]$ tree
.
├── etc
│   └── java-util-logging.properties
├── lib
│   └── slf4j
│   ├── slf4j-api-1.7.21.jar
│   └── slf4j-jdk14-1.7.21.jar
└── start.d
└── logging-jul.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>Jetty is now configured to log using the JUL framework.
A standard JUL properties file is located in <code>${jetty.base}/etc/java-util-logging.properties</code>.</p>
</div>
</div>
</div>
<div class="sect3">
<h4>Capturing Console Output</h4>
<div class="paragraph">
<p>By default, enabling the above modules will output log information to the console.
Included in the distribution is the <code>console-capture</code> module, which can be used in lieu of additional configuration to the selected logging module to capture this output to a <code>logs</code> directory in your <code>${jetty.base}</code>.
To enable this functionality, activate the <code>console-capture</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar --add-to-start=console-capture
INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini
MKDIR : ${jetty.base}/logs
INFO : Base directory was modified
[my-base]$ tree
.
├── logs
└── start.d
└── console-capture.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>As an example, here is the output from Logback before using the <code>console-capture</code> module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar
419 [main] INFO org.eclipse.jetty.util.log - Logging initialized @508ms to org.eclipse.jetty.util.log.Slf4jLog
540 [main] INFO org.eclipse.jetty.server.Server - jetty-10.0.0-SNAPSHOT
575 [main] INFO o.e.jetty.server.AbstractConnector - Started ServerConnector@3c0ecd4b{HTTP/1.1,[http/1.1]}{0.0.0.0:8080}
575 [main] INFO org.eclipse.jetty.server.Server - Started @668ms</code></pre>
</div>
</div>
<div class="paragraph">
<p>After enabling <code>console-capture</code>, the output is as follows, which displays the location the log is being saved to:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[my-base]$ java -jar ../start.jar
151 [main] INFO org.eclipse.jetty.util.log - Logging initialized @238ms to org.eclipse.jetty.util.log.Slf4jLog
196 [main] INFO org.eclipse.jetty.util.log - Console stderr/stdout captured to /installs/jetty-distribution/mybase/logs/2016_10_21.jetty.log</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="example-logging-logback-centralized">Centralized Logging using Logback</h3>
<div class="paragraph">
<p>The term <em>Centralized Logging</em> refers to a forced logging configuration for the Jetty Server and all web applications that are deployed on the server.
It routes all logging events from the web applications to a single configuration on the Server side.</p>
</div>
<div class="paragraph">
<p>The example below shows how to accomplish this with Jetty and Slf4j, using <code>Logback</code> to manage the final writing of logs to disk.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This mechanism forces all webapps to use the server&#8217;s configuration for logging, something that isn&#8217;t 100% appropriate for all webapps.
An example would be having Jenkins-CI deployed as an webapp, if you force its logging configuration to the server side, you lose the ability on <a href="http://jenkins-ci.org/">Jenkins-CI</a> to see the logs from the various builds (as now those logs are actually going to the main server log).
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>This configuration is essentially the multiple logger configuration with added configuration to the deployers to force a <code>WebAppClassLoader</code> change to use the server classpath over the webapps classpath for the logger specific classes.</p>
</div>
<div class="paragraph">
<p>The technique used by this configuration is to provide an <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOTorg/eclipse/jetty/deploy/AppLifeCycle.Binding.html">AppLifeCycle.Binding</a> against the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/deploy/AppLifeCycle.html">`"deploying"`node</a> that modifies the
<a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html#getSystemClasspathPattern()">WebAppContext.getSystemClasspathPattern().add(String)</a> for the common logging classes.
See <a href="https://github.com/jetty-project/jetty-webapp-logging/blob/master/src/main/java/org/eclipse/jetty/webapp/logging/CentralizedWebAppLoggingBinding.java">org.eclipse.jetty.logging.CentralizedWebAppLoggingBinding</a> for actual implementation.</p>
</div>
<div class="paragraph">
<p>A convenient replacement <code>logging</code> module has been created to bootstrap your <code>${jetty.base}</code> directory for capturing all Jetty server logging from multiple logging frameworks into a single logging output file managed by Logback.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ mkdir modules
[mybase]$ cd modules
[modules]$ curl -O https://raw.githubusercontent.com/jetty-project/logging-modules/master/capture-all/logging.mod
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 1416 100 1416 0 0 4241 0 --:--:-- --:--:-- --:--:-- 4252
[master]$ curl -O https://raw.githubusercontent.com/jetty-project/logging-modules/master/centralized/webapp-logging.mod
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 660 100 660 0 0 2032 0 --:--:-- --:--:-- --:--:-- 2037
[modules]$ cd ..
[mybase]$ java -jar /opt/jetty-dist/start.jar --add-to-start=logging,webapp-logging
INFO: logging initialised in ${jetty.base}/start.ini (appended)
MKDIR: ${jetty.base}/logs
DOWNLOAD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.6.6/slf4j-api-1.6.6.jar to lib/logging/slf4j-api-1.6.6.jar
DOWNLOAD: https://repo1.maven.org/maven2/org/slf4j/log4j-over-slf4j/1.6.6/log4j-over-slf4j-1.6.6.jar to lib/logging/log4j-over-slf4j-1.6.6.jar
DOWNLOAD: https://repo1.maven.org/maven2/org/slf4j/jul-to-slf4j/1.6.6/jul-to-slf4j-1.6.6.jar to lib/logging/jul-to-slf4j-1.6.6.jar
DOWNLOAD: https://repo1.maven.org/maven2/org/slf4j/jcl-over-slf4j/1.6.6/jcl-over-slf4j-1.6.6.jar to lib/logging/jcl-over-slf4j-1.6.6.jar
DOWNLOAD: https://repo1.maven.org/maven2/ch/qos/logback/logback-core/1.0.7/logback-core-1.0.7.jar to lib/logging/logback-core-1.0.7.jar
DOWNLOAD: https://repo1.maven.org/maven2/ch/qos/logback/logback-classic/1.0.7/logback-classic-1.0.7.jar to lib/logging/logback-classic-1.0.7.jar
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/capture-all/logback.xml to resources/logback.xml
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/capture-all/jetty-logging.properties to resources/jetty-logging.properties
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/logging-modules/master/capture-all/jetty-logging.xml to etc/jetty-logging.xml
INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
INFO: webapp-logging initialised in ${jetty.base}/start.ini (appended)
DOWNLOAD: https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-webapp-logging/9.0.0/jetty-webapp-logging-9.0.0.jar to lib/webapp-logging/jetty-webapp-logging-9.0.0.jar
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/jetty-webapp-logging/master/src/main/config/etc/jetty-webapp-logging.xml to etc/jetty-webapp-logging.xml
DOWNLOAD: https://raw.githubusercontent.com/jetty-project/jetty-webapp-logging/master/src/main/config/etc/jetty-mdc-handler.xml to etc/jetty-mdc-handler.xml
INFO: deploy initialised transitively
INFO: deploy enabled in ${jetty.base}/start.ini
INFO: logging initialised transitively
INFO: resources initialised transitively
INFO: resources enabled in ${jetty.base}/start.ini
[mybase]$ java -jar /opt/jetty-dist/start.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>The replacement <code>logging.mod</code> performs a number of tasks.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><code>mybase</code> is a <code>${jetty.base}</code> directory.</p>
</li>
<li>
<p>The jetty-distribution is unpacked (and untouched) into <code>/opt/jetty-dist/</code> and becomes the <code>${jetty.home}</code> directory for this demonstration.</p>
</li>
<li>
<p>The <code>curl</code> command downloads the replacement <code>logging.mod</code> and puts it into the <code>${jetty.base}/modules/</code> directory for use by mybase only.</p>
</li>
<li>
<p>The <code>start.jar --add-to-start=logging,webapp-logging</code> command performs a number of steps to make the logging module available to the <code>${jetty.base}</code> configuration.</p>
<div class="olist loweralpha">
<ol class="loweralpha" type="a">
<li>
<p>Several entries are added to the <code>${jetty.base}/start.ini</code> configuration.</p>
<div class="ulist">
<ul>
<li>
<p><code>--module=logging</code> is added to enable the logging module.</p>
</li>
<li>
<p><code>--module=webapp-logging</code> is added to enable the webapp-logging module.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Required <code>${jetty.base}</code> directories are created: <code>${jetty.base}/logs</code> and <code>${jetty.base}/resources</code>.</p>
</li>
<li>
<p>Required logging libraries are downloaded (if not present already) to the <code>${jetty.base}/lib/logging/</code> directory:</p>
<div class="ulist">
<ul>
<li>
<p><code>slf4j-api.jar</code> - API jar for Slf4j (used by most of the rest of the jars)</p>
</li>
<li>
<p><code>log4j-over-slf4j.jar</code> - Slf4j jar that captures all log4j emitted logging events</p>
</li>
<li>
<p><code>jul-to-slf4j.jar</code> - Slf4j jar that captures all java.util.logging events</p>
</li>
<li>
<p><code>jcl-over-slf4j.jar</code> - Slf4j jar that captures all commons-logging events</p>
</li>
<li>
<p><code>logback-classic.jar</code> - the Slf4j adapter jar that routes all of the captured logging events to logback itself.</p>
</li>
<li>
<p><code>logback-core.jar</code> - the logback implementation jar, that handles all of the filtering and output of the logging events.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Required webapp-logging library is downloaded (if not present already) to the <code>${jetty.base}/lib/webapp-logging/</code> directory:</p>
<div class="ulist">
<ul>
<li>
<p><code>jetty-webapp-logging.jar</code> - the Jetty side deployment manger app-lifecycle bindings for modifying the <code>WebAppClassloaders</code> of deployed webapps.</p>
</li>
</ul>
</div>
</li>
<li>
<p>Required configuration files are downloaded (if not present already) to the <code>${jetty.base}/resources/</code> directory: <code>jetty-logging.properties</code>, and <code>logback.xml</code>.</p>
</li>
<li>
<p>Required initialization commands are downloaded (if not present already) to the <code>${jetty.base}/etc/</code> directory: <code>jetty-logging.xml</code>, <code>jetty-webapp-logging.xml</code>, and <code>jetty-mdc-handler.xml</code>.</p>
</li>
</ol>
</div>
</li>
</ol>
</div>
<div class="paragraph">
<p>At this point the Jetty <code>mybase</code> is configured so that the jetty server itself will log using slf4j, and all other logging events from other Jetty Server components (such as database drivers, security layers, jsp, mail, and other 3rd party server components) are routed to logback for filtering and output.</p>
</div>
<div class="paragraph">
<p>All webapps deployed via the <code>DeploymentManager</code> have their <code>WebAppClassLoader</code> modified to use server side classes and configuration for all logging implementations.</p>
</div>
<div class="paragraph">
<p>The server classpath can be verified by using the <code>start.jar --list-config</code> command.</p>
</div>
<div class="paragraph">
<p>In essence, Jetty is now configured to emit its own logging events to slf4j, and various slf4j bridge jars are acting on behalf of log4j, <code>java.util.logging</code>, and <code>commons-logging</code>, routing all of the logging events to logback (a slf4j adapter) for routing (to console, file, etc&#8230;&#8203;).</p>
</div>
</div>
<div class="sect2">
<h3 id="jetty-dump-tool">Jetty Dump Tool</h3>
<div class="paragraph">
<p>The dump feature in Jetty provides a good snapshot of the status of the threadpool, select sets, classloaders, and so forth.
To get maximum detail from the dump, you need to <code>setDetailDump(true)</code> on any <code>QueuedThreadPools</code> you are using.
You can do this by a direct call if you are embedding Jetty, or in <code>jetty.xml</code>.</p>
</div>
<div class="sect3">
<h4 id="configuring-dump-feature">Configuring the Dump Feature in jetty.xml</h4>
<div class="paragraph">
<p>You can request that Jetty do a dump immediately after starting and just before stopping by calling the appropriate setters on the <code>Server</code> instance.
This can be accomplished in <code>jetty.xml</code> with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Set name="dumpAfterStart"&gt;true&lt;/Set&gt;
&lt;Set name="dumpBeforeStop"&gt;true&lt;/Set&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="extra-threadpool-info">Extra ThreadPool Information</h4>
<div class="paragraph">
<p>You can get additional detail from the <code>QueuedThreadPool</code> if <code>setDetailedDump(true)</code> is called on the thread pool instance.
Do this in <code>jetty.xml</code> as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;!-- ==================================== --&gt;
&lt;!-- Server Thread Pool --&gt;
&lt;!-- ==================================== --&gt;
&lt;Set name="ThreadPool"&gt;
&lt;!-- Default queued blocking threadpool --&gt;
&lt;New class="org.eclipse.jetty.util.thread.QueuedThreadPool"&gt;
&lt;Set name="minThreads"&gt;10&lt;/Set&gt;
&lt;Set name="maxThreads"&gt;200&lt;/Set&gt;
&lt;Set name="detailedDump"&gt;true&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="dump-tool-via-jmx">Using the Dump Feature via JMX</h4>
<div class="paragraph">
<p>The <code>dump</code> method is on the Server instance and many of its nested components (Handlers, Connectors, and so forth).
Dumps may be obtained by calling these methods either in code or via JMX (see <a href="#using-jmx">Using JMX with Jetty</a>).</p>
</div>
<div class="paragraph">
<p>The Server MBean has a <code>dump()</code> method, which dumps everything, plus a <code>dumpStdErr()</code> operation that dumps to StdErr rather than replying to JConsole.</p>
</div>
</div>
<div class="sect3">
<h4 id="examing-jetty-distro-dump">Examining a Jetty Distribution Dump</h4>
<div class="paragraph">
<p>This is a dump of the stock jetty-distribution with extra threadpool information:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>org.eclipse.jetty.server.Server@76f08fe1 - STARTING
+= qtp1062680061{STARTED,10&lt;=13&lt;=200,i=1,q=0} - STARTED
| +- 12 qtp1062680061-12-selector-0 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 13 qtp1062680061-13-selector-6 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 14 qtp1062680061-14-selector-5 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 15 qtp1062680061-15-acceptor-0-ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090} BLOCKED
| | +- sun.nio.ch.ServerSocketChannelImpl.accept(ServerSocketChannelImpl.java:210)
| | +- org.eclipse.jetty.server.ServerConnector.accept(ServerConnector.java:284)
| | +- org.eclipse.jetty.server.AbstractConnector$Acceptor.run(AbstractConnector.java:460)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 16 qtp1062680061-16-selector-1 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 17 qtp1062680061-17-selector-2 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 18 qtp1062680061-18-selector-3 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 19 qtp1062680061-19-selector-4 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 20 qtp1062680061-20-selector-7 RUNNABLE
| | +- sun.nio.ch.KQueueArrayWrapper.kevent0(Native Method)
| | +- sun.nio.ch.KQueueArrayWrapper.poll(KQueueArrayWrapper.java:159)
| | +- sun.nio.ch.KQueueSelectorImpl.doSelect(KQueueSelectorImpl.java:103)
| | +- sun.nio.ch.SelectorImpl.lockAndDoSelect(SelectorImpl.java:87)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:98)
| | +- sun.nio.ch.SelectorImpl.select(SelectorImpl.java:102)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.run(SelectorManager.java:435)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 21 qtp1062680061-21-acceptor-1-ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090} RUNNABLE
| | +- sun.nio.ch.ServerSocketChannelImpl.accept0(Native Method)
| | +- sun.nio.ch.ServerSocketChannelImpl.accept(ServerSocketChannelImpl.java:226)
| | +- org.eclipse.jetty.server.ServerConnector.accept(ServerConnector.java:284)
| | +- org.eclipse.jetty.server.AbstractConnector$Acceptor.run(AbstractConnector.java:460)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 49 qtp1062680061-49-acceptor-2-ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090} BLOCKED
| | +- sun.nio.ch.ServerSocketChannelImpl.accept(ServerSocketChannelImpl.java:210)
| | +- org.eclipse.jetty.server.ServerConnector.accept(ServerConnector.java:284)
| | +- org.eclipse.jetty.server.AbstractConnector$Acceptor.run(AbstractConnector.java:460)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 50 qtp1062680061-50-acceptor-3-ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090} BLOCKED
| | +- sun.nio.ch.ServerSocketChannelImpl.accept(ServerSocketChannelImpl.java:210)
| | +- org.eclipse.jetty.server.ServerConnector.accept(ServerConnector.java:284)
| | +- org.eclipse.jetty.server.AbstractConnector$Acceptor.run(AbstractConnector.java:460)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool.runJob(QueuedThreadPool.java:596)
| | +- org.eclipse.jetty.util.thread.QueuedThreadPool$3.run(QueuedThreadPool.java:527)
| | +- java.lang.Thread.run(Thread.java:722)
| +- 52 qtp1062680061-52 TIMED_WAITING IDLE
+= org.eclipse.jetty.util.thread.ScheduledExecutorScheduler@725f5 - STARTED
+= org.eclipse.jetty.server.handler.HandlerCollection@58b37561 - STARTED
| += org.eclipse.jetty.server.handler.ContextHandlerCollection@64c6e290 - STARTED
| | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | += o.e.j.w.WebAppContext@7ea88b1c{/async-rest,[file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/, jar:file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/example-async-rest-jar-9.0.2.v20130417.jar!/META-INF/resources/],AVAILABLE}{/async-rest.war} - STARTED
| | | += org.eclipse.jetty.server.session.SessionHandler@6dfb8d2e - STARTED
| | | | += org.eclipse.jetty.server.session.HashSessionManager@6cb83869 - STARTED
| | | | += org.eclipse.jetty.security.ConstraintSecurityHandler@2848c90e - STARTED
| | | | | +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@52b12fef
| | | | | += org.eclipse.jetty.servlet.ServletHandler@46bac287 - STARTED
| | | | | | += default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true - STARTED
| | | | | | | +- maxCacheSize=256000000
| | | | | | | +- etags=true
| | | | | | | +- dirAllowed=true
| | | | | | | +- gzip=true
| | | | | | | +- maxCachedFileSize=200000000
| | | | | | | +- redirectWelcome=false
| | | | | | | +- acceptRanges=true
| | | | | | | +- welcomeServlets=false
| | | | | | | +- aliases=false
| | | | | | | +- useFileMappedBuffer=true
| | | | | | | +- maxCachedFiles=2048
| | | | | | +- [/]=&gt;default
| | | | | | += jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true - STARTED
| | | | | | | +- logVerbosityLevel=DEBUG
| | | | | | | +- fork=false
| | | | | | | +- com.sun.appserv.jsp.classpath=/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar:/home/user/jetty-distribution-{VERSION}/resources:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/start.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/dnsns.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/localedata.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunec.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunjce_provider.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunpkcs11.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/zipfs.jar:/opt/local/lib/libsvnjavahl-1.0.dylib:/System/Library/Java/Extensions/AppleScriptEngine.jar:/System/Library/Java/Extensions/dns_sd.jar:/System/Library/Java/Extensions/j3daudio.jar:/System/Library/Java/Extensions/j3dcore.jar:/System/Library/Java/Extensions/j3dutils.jar:/System/Library/Java/Extensions/jai_codec.jar:/System/Library/Java/Extensions/jai_core.jar:/System/Library/Java/Extensions/libAppleScriptEngine.jnilib:/System/Library/Java/Extensions/libJ3D.jnilib:/System/Library/Java/Extensions/libJ3DAudio.jnilib:/System/Library/Java/Extensions/libJ3DUtils.jnilib:/System/Library/Java/Extensions/libmlib_jai.jnilib:/System/Library/Java/Extensions/libQTJNative.jnilib:/System/Library/Java/Extensions/mlibwrapper_jai.jar:/System/Library/Java/Extensions/MRJToolkit.jar:/System/Library/Java/Extensions/QTJava.zip:/System/Library/Java/Extensions/vecmath.jar:/usr/lib/java/libjdns_sd.jnilib
| | | | | | | +- scratchdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/jsp
| | | | | | | +- xpoweredBy=false
| | | | | | +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp
| | | | | | += SerialRestServlet@461411d==org.eclipse.jetty.example.asyncrest.SerialRestServlet,-1,false - STARTED
| | | | | | +- [/testSerial]=&gt;SerialRestServlet
| | | | | | += AsyncRestServlet@73eb9bd5==org.eclipse.jetty.example.asyncrest.AsyncRestServlet,-1,false - STARTED
| | | | | | +- [/testAsync]=&gt;AsyncRestServlet
| | | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | | += HashLoginService[Test Realm] - STARTED
| | | | | +- org.eclipse.jetty.security.DefaultIdentityService@d2539a6
| | | | | +- org.eclipse.jetty.security.authentication.BasicAuthenticator@7b239469
| | | | | |
| | | | | +&gt; HashLoginService[Test Realm] - STARTED
| | | | | +&gt; org.eclipse.jetty.security.DefaultIdentityService@d2539a6
| | | | | +&gt; org.eclipse.jetty.security.authentication.BasicAuthenticator@7b239469
| | | | | +&gt; []
| | | | | +&gt; /={TRACE={RoleInfo,F,C[]}}
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | += org.eclipse.jetty.servlet.ErrorPageErrorHandler@3c121009 - STARTED
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | |
| | | +&gt; WebAppClassLoader=Async REST Webservice Example@52934ea0
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/classes/
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/example-async-rest-jar-9.0.2.v20130417.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-client-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-http-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-io-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-util-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-util-ajax-{VERSION}.jar
| | | | +- startJarLoader@7194b34a
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/resources/
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar
| | | | +- sun.misc.Launcher$AppClassLoader@19d1b44b
| | | | +- file:/home/user/jetty-distribution-{VERSION}/start.jar
| | | | +- sun.misc.Launcher$ExtClassLoader@1693b52b
| | | +&gt; javax.servlet.context.tempdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-
| | | +&gt; org.apache.catalina.jsp_classpath=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/classes:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/example-async-rest-jar-9.0.2.v20130417.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-client-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-http-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-io-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-util-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/jetty-util-ajax-{VERSION}.jar
| | | +&gt; org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern=.*/jetty-servlet-api-[^/]*\.jar$
| | | +&gt; com.sun.jsp.taglibraryCache={}
| | | +&gt; com.sun.jsp.tagFileJarUrlsCache={}
| | += o.e.j.s.h.MovedContextHandler@5e0c8d24{/oldContextPath,null,AVAILABLE} - STARTED
| | | += org.eclipse.jetty.server.handler.MovedContextHandler$Redirector@2a4200d3 - STARTED
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | |
| | | +&gt; No ClassLoader
| | | +&gt; org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern=.*/jetty-servlet-api-[^/]*\.jar$
| | += o.e.j.w.WebAppContext@6f01ba6f{/,file:/home/user/jetty-distribution-{VERSION}/webapps/ROOT/,AVAILABLE}{/ROOT} - STARTED
| | | += org.eclipse.jetty.server.session.SessionHandler@5a770658 - STARTED
| | | | += org.eclipse.jetty.server.session.HashSessionManager@746a95ae - STARTED
| | | | += org.eclipse.jetty.security.ConstraintSecurityHandler@1890e38 - STARTED
| | | | | +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@6242c657
| | | | | += org.eclipse.jetty.servlet.ServletHandler@debac27 - STARTED
| | | | | | += default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true - STARTED
| | | | | | | +- maxCacheSize=256000000
| | | | | | | +- etags=true
| | | | | | | +- dirAllowed=true
| | | | | | | +- gzip=true
| | | | | | | +- maxCachedFileSize=200000000
| | | | | | | +- redirectWelcome=false
| | | | | | | +- acceptRanges=true
| | | | | | | +- welcomeServlets=false
| | | | | | | +- aliases=false
| | | | | | | +- useFileMappedBuffer=true
| | | | | | | +- maxCachedFiles=2048
| | | | | | +- [/]=&gt;default
| | | | | | += jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true - STARTED
| | | | | | | +- logVerbosityLevel=DEBUG
| | | | | | | +- fork=false
| | | | | | | +- com.sun.appserv.jsp.classpath=/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar:/home/user/jetty-distribution-{VERSION}/resources:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/start.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/dnsns.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/localedata.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunec.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunjce_provider.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunpkcs11.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/zipfs.jar:/opt/local/lib/libsvnjavahl-1.0.dylib:/System/Library/Java/Extensions/AppleScriptEngine.jar:/System/Library/Java/Extensions/dns_sd.jar:/System/Library/Java/Extensions/j3daudio.jar:/System/Library/Java/Extensions/j3dcore.jar:/System/Library/Java/Extensions/j3dutils.jar:/System/Library/Java/Extensions/jai_codec.jar:/System/Library/Java/Extensions/jai_core.jar:/System/Library/Java/Extensions/libAppleScriptEngine.jnilib:/System/Library/Java/Extensions/libJ3D.jnilib:/System/Library/Java/Extensions/libJ3DAudio.jnilib:/System/Library/Java/Extensions/libJ3DUtils.jnilib:/System/Library/Java/Extensions/libmlib_jai.jnilib:/System/Library/Java/Extensions/libQTJNative.jnilib:/System/Library/Java/Extensions/mlibwrapper_jai.jar:/System/Library/Java/Extensions/MRJToolkit.jar:/System/Library/Java/Extensions/QTJava.zip:/System/Library/Java/Extensions/vecmath.jar:/usr/lib/java/libjdns_sd.jnilib
| | | | | | | +- scratchdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-ROOT-_-any-/jsp
| | | | | | | +- xpoweredBy=false
| | | | | | +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp
| | | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | | +~ HashLoginService[Test Realm] - STARTED
| | | | | +- org.eclipse.jetty.security.DefaultIdentityService@d2539a6
| | | | | +- org.eclipse.jetty.security.authentication.BasicAuthenticator@6b733b94
| | | | | |
| | | | | +&gt; HashLoginService[Test Realm] - STARTED
| | | | | +&gt; org.eclipse.jetty.security.DefaultIdentityService@d2539a6
| | | | | +&gt; org.eclipse.jetty.security.authentication.BasicAuthenticator@6b733b94
| | | | | +&gt; []
| | | | | +&gt; /={TRACE={RoleInfo,F,C[]}}
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | += org.eclipse.jetty.servlet.ErrorPageErrorHandler@3c41a9ce - STARTED
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | |
| | | +&gt; WebAppClassLoader=ROOT@7af33249
| | | | +- startJarLoader@7194b34a
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/resources/
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar
| | | | +- sun.misc.Launcher$AppClassLoader@19d1b44b
| | | | +- file:/home/user/jetty-distribution-{VERSION}/start.jar
| | | | +- sun.misc.Launcher$ExtClassLoader@1693b52b
| | | +&gt; javax.servlet.context.tempdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-ROOT-_-any-
| | | +&gt; org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern=.*/jetty-servlet-api-[^/]*\.jar$
| | | +&gt; com.sun.jsp.taglibraryCache={}
| | | +&gt; com.sun.jsp.tagFileJarUrlsCache={}
| | += o.e.j.s.h.ContextHandler@7b2dffdf{/javadoc,file:/home/user/jetty-distribution-{VERSION}/javadoc,AVAILABLE} - STARTED
| | | += org.eclipse.jetty.server.handler.ResourceHandler@8f9c8a7 - STARTED
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | |
| | | +&gt; No ClassLoader
| | | +&gt; org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern=.*/jetty-servlet-api-[^/]*\.jar$
| | += o.e.j.w.WebAppContext@716d9094{/test,file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/,AVAILABLE}{/test.war} - STARTED
| | | += org.eclipse.jetty.server.session.SessionHandler@336abd81 - STARTED
| | | | += org.eclipse.jetty.server.session.HashSessionManager@1246f8d0 - STARTED
| | | | += org.eclipse.jetty.security.ConstraintSecurityHandler@7179290f - STARTED
| | | | | +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@17d41d12
| | | | | += org.eclipse.jetty.servlet.ServletHandler@5034037e - STARTED
| | | | | | += default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true - STARTED
| | | | | | | +- maxCacheSize=256000000
| | | | | | | +- etags=true
| | | | | | | +- dirAllowed=true
| | | | | | | +- gzip=true
| | | | | | | +- maxCachedFileSize=200000000
| | | | | | | +- redirectWelcome=false
| | | | | | | +- acceptRanges=true
| | | | | | | +- welcomeServlets=false
| | | | | | | +- aliases=false
| | | | | | | +- useFileMappedBuffer=true
| | | | | | | +- maxCachedFiles=2048
| | | | | | +- [/]=&gt;default
| | | | | | += jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true - STARTED
| | | | | | | +- logVerbosityLevel=DEBUG
| | | | | | | +- fork=false
| | | | | | | +- com.sun.appserv.jsp.classpath=/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar:/home/user/jetty-distribution-{VERSION}/resources:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/start.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/dnsns.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/localedata.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunec.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunjce_provider.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunpkcs11.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/zipfs.jar:/opt/local/lib/libsvnjavahl-1.0.dylib:/System/Library/Java/Extensions/AppleScriptEngine.jar:/System/Library/Java/Extensions/dns_sd.jar:/System/Library/Java/Extensions/j3daudio.jar:/System/Library/Java/Extensions/j3dcore.jar:/System/Library/Java/Extensions/j3dutils.jar:/System/Library/Java/Extensions/jai_codec.jar:/System/Library/Java/Extensions/jai_core.jar:/System/Library/Java/Extensions/libAppleScriptEngine.jnilib:/System/Library/Java/Extensions/libJ3D.jnilib:/System/Library/Java/Extensions/libJ3DAudio.jnilib:/System/Library/Java/Extensions/libJ3DUtils.jnilib:/System/Library/Java/Extensions/libmlib_jai.jnilib:/System/Library/Java/Extensions/libQTJNative.jnilib:/System/Library/Java/Extensions/mlibwrapper_jai.jar:/System/Library/Java/Extensions/MRJToolkit.jar:/System/Library/Java/Extensions/QTJava.zip:/System/Library/Java/Extensions/vecmath.jar:/usr/lib/java/libjdns_sd.jnilib
| | | | | | | +- scratchdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/jsp
| | | | | | | +- xpoweredBy=false
| | | | | | +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp
| | | | | | += QoSFilter - STARTED
| | | | | | | +- managedAttr=true
| | | | | | | +- maxRequests=10000
| | | | | | +- [/*]/[]==0=&gt;QoSFilter
| | | | | | += MultiPart - STARTED
| | | | | | | +- deleteFiles=true
| | | | | | +- [/dump/*]/[]==0=&gt;MultiPart
| | | | | | += GzipFilter - STARTED
| | | | | | | +- bufferSize=8192
| | | | | | | +- excludedAgents=MSIE 6.0
| | | | | | | +- userAgent=(?:Mozilla[^\(]*\(compatible;\s*+([^;]*);.*)|(?:.*?([^\s]+/[^\s]+).*)
| | | | | | | +- mimeTypes=text/plain,application/xml
| | | | | | | +- uncheckedPrintWriter=true
| | | | | | | +- cacheSize=1024
| | | | | | | +- minGzipSize=2048
| | | | | | +- [/dump/gzip/*, *.txt]/[]==0=&gt;GzipFilter
| | | | | | += Login@462ff49==com.acme.LoginServlet,1,true - STARTED
| | | | | | +- [/login/*]=&gt;Login
| | | | | | += Hello@42628b2==com.acme.HelloWorld,1,true - STARTED
| | | | | | +- [/hello/*]=&gt;Hello
| | | | | | += Dump@20ae14==com.acme.Dump,1,true - STARTED
| | | | | | | +- servlet-override-example=a servlet value
| | | | | | +- [/dump/*, *.dump]=&gt;Dump
| | | | | | += Session@d9891a76==com.acme.SessionDump,5,true - STARTED
| | | | | | +- [/session/*]=&gt;Session
| | | | | | += Cookie@78a4f684==com.acme.CookieDump,1,true - STARTED
| | | | | | +- [/cookie/*]=&gt;Cookie
| | | | | | += Dispatch@14d3a89a==com.acme.DispatchServlet,1,true - STARTED
| | | | | | +- [/dispatch/*]=&gt;Dispatch
| | | | | | += CGI@10465==org.eclipse.jetty.servlets.CGI,1,true - STARTED
| | | | | | +- [/cgi-bin/*]=&gt;CGI
| | | | | | += Chat@200778==com.acme.ChatServlet,1,true - STARTED
| | | | | | +- [/chat/*]=&gt;Chat
| | | | | | += WSChat@99274454==com.acme.WebSocketChatServlet,1,true - STARTED
| | | | | | +- [/ws/*]=&gt;WSChat
| | | | | | += Rewrite@a4dac96c==com.acme.RewriteServlet,-1,false - STARTED
| | | | | | +- [/rewritten/*, /redirected/*]=&gt;Rewrite
| | | | | | += SecureMode@d45951da==com.acme.SecureModeServlet,1,true - STARTED
| | | | | | +- [/secureMode/*]=&gt;SecureMode
| | | | | | += foo.jsp@d7583f1f==org.apache.jasper.servlet.JspServlet,-1,false - STARTED
| | | | | | +- [/jsp/foo/]=&gt;foo.jsp
| | | | | | +- [*.more]=&gt;Dump
| | | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | | | += RegoTest@dafcd1ad==com.acme.RegTest,-1,false - STARTED
| | | | | | +- [/rego/*]=&gt;RegoTest
| | | | | | += RegoTest2@849d6425==com.acme.RegTest,-1,false - STARTED
| | | | | | +- [/rego2/*]=&gt;RegoTest2
| | | | | | += TestFilter - STARTED
| | | | | | | +- remote=false
| | | | | | +- [/*]/[]==31=&gt;TestFilter
| | | | | += HashLoginService[Test Realm] - STARTED
| | | | | +- org.eclipse.jetty.security.authentication.FormAuthenticator@1fa291f2
| | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | | +- org.eclipse.jetty.security.DefaultIdentityService@41917d6d
| | | | | |
| | | | | +&gt; HashLoginService[Test Realm] - STARTED
| | | | | +&gt; org.eclipse.jetty.security.DefaultIdentityService@41917d6d
| | | | | +&gt; org.eclipse.jetty.security.authentication.FormAuthenticator@1fa291f2
| | | | | +&gt; [server-administrator, *, admin, user]
| | | | | +&gt; /rego2/*={*={RoleInfo,C[server-administrator]}}
| | | | | +&gt; *.htm={*={RoleInfo,C[server-administrator, *, admin, user]}}
| | | | | +&gt; /dump/auth/ssl/*={*={RoleInfo[]}}
| | | | | +&gt; /dump/auth/noaccess/*={*={RoleInfo,F,C[]}}
| | | | | +&gt; /auth/*={*={RoleInfo,F,C[]}}
| | | | | +&gt; /dump/auth/admin/*={*={RoleInfo,C[admin]}}
| | | | | +&gt; /dump/auth/relax/*={GET={RoleInfo[]}, HEAD={RoleInfo[]}}
| | | | | +&gt; /rego/*={*={RoleInfo,C[admin]}}
| | | | | +&gt; /dump/auth/*={*={RoleInfo,C[server-administrator, *, admin, user]}}
| | | | | +&gt; /={TRACE={RoleInfo,F,C[]}}
| | | | | +&gt; /auth/relax.txt={GET={RoleInfo[]}, HEAD={RoleInfo[]}}
| | | | | +&gt; /auth2/*={*={RoleInfo,C[server-administrator, *, admin, user]}}
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | += org.eclipse.jetty.servlet.ErrorPageErrorHandler@24bf7a86 - STARTED
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | +- org.eclipse.jetty.servlets.QoSFilter@6df3d1f5
| | | |
| | | +&gt; WebAppClassLoader=Test WebApp@3e2f3adb
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/classes/
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-continuation-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-http-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-io-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-servlets-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-util-{VERSION}.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/websocket-api-9.0.2.v20130417.jar
| | | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/websocket-servlet-9.0.2.v20130417.jar
| | | | +- startJarLoader@7194b34a
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/resources/
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar
| | | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar
| | | | +- sun.misc.Launcher$AppClassLoader@19d1b44b
| | | | +- file:/home/user/jetty-distribution-{VERSION}/start.jar
| | | | +- sun.misc.Launcher$ExtClassLoader@1693b52b
| | | +&gt; org.eclipse.jetty.server.context.ManagedAttributes=QoSFilter,TransparentProxy.ThreadPool,TransparentProxy.HttpClient
| | | +&gt; context-override-example=a context value
| | | +&gt; javax.servlet.context.tempdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-
| | | +&gt; org.apache.catalina.jsp_classpath=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/classes:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-continuation-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-http-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-io-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-servlets-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/jetty-util-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/websocket-api-9.0.2.v20130417.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/WEB-INF/lib/websocket-servlet-9.0.2.v20130417.jar
| | | +&gt; org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern=.*/jetty-servlet-api-[^/]*\.jar$
| | | +&gt; QoSFilter=org.eclipse.jetty.servlets.QoSFilter@6df3d1f5
| | | +&gt; com.sun.jsp.taglibraryCache={}
| | | +&gt; com.sun.jsp.tagFileJarUrlsCache={}
| | += o.e.j.w.WebAppContext@4ac92718{/proxy,file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/,AVAILABLE}{/xref-proxy.war} - STARTED
| | += org.eclipse.jetty.server.session.SessionHandler@5c25bf03 - STARTED
| | | += org.eclipse.jetty.server.session.HashSessionManager@33053093 - STARTED
| | | += org.eclipse.jetty.security.ConstraintSecurityHandler@3bab0b5a - STARTED
| | | | +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@11ad5296
| | | | += org.eclipse.jetty.servlet.ServletHandler@a08feeb - STARTED
| | | | | += default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true - STARTED
| | | | | | +- maxCacheSize=256000000
| | | | | | +- etags=true
| | | | | | +- dirAllowed=true
| | | | | | +- gzip=true
| | | | | | +- maxCachedFileSize=200000000
| | | | | | +- redirectWelcome=false
| | | | | | +- acceptRanges=true
| | | | | | +- welcomeServlets=false
| | | | | | +- aliases=false
| | | | | | +- useFileMappedBuffer=true
| | | | | | +- maxCachedFiles=2048
| | | | | +- [/]=&gt;default
| | | | | += jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true - STARTED
| | | | | | +- logVerbosityLevel=DEBUG
| | | | | | +- fork=false
| | | | | | +- com.sun.appserv.jsp.classpath=/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar:/home/user/jetty-distribution-{VERSION}/resources:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar:/home/user/jetty-distribution-{VERSION}/start.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/dnsns.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/localedata.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunec.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunjce_provider.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/sunpkcs11.jar:/Library/Java/JavaVirtualMachines/jdk1.7.0_17.jdk/Contents/Home/jre/lib/ext/zipfs.jar:/opt/local/lib/libsvnjavahl-1.0.dylib:/System/Library/Java/Extensions/AppleScriptEngine.jar:/System/Library/Java/Extensions/dns_sd.jar:/System/Library/Java/Extensions/j3daudio.jar:/System/Library/Java/Extensions/j3dcore.jar:/System/Library/Java/Extensions/j3dutils.jar:/System/Library/Java/Extensions/jai_codec.jar:/System/Library/Java/Extensions/jai_core.jar:/System/Library/Java/Extensions/libAppleScriptEngine.jnilib:/System/Library/Java/Extensions/libJ3D.jnilib:/System/Library/Java/Extensions/libJ3DAudio.jnilib:/System/Library/Java/Extensions/libJ3DUtils.jnilib:/System/Library/Java/Extensions/libmlib_jai.jnilib:/System/Library/Java/Extensions/libQTJNative.jnilib:/System/Library/Java/Extensions/mlibwrapper_jai.jar:/System/Library/Java/Extensions/MRJToolkit.jar:/System/Library/Java/Extensions/QTJava.zip:/System/Library/Java/Extensions/vecmath.jar:/usr/lib/java/libjdns_sd.jnilib
| | | | | | +- scratchdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/jsp
| | | | | | +- xpoweredBy=false
| | | | | +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp
| | | | | += XrefTransparentProxy@b0222797==org.eclipse.jetty.proxy.ProxyServlet$Transparent,1,true - STARTED
| | | | | | +- proxyTo=http://download.eclipse.org/jetty/stable-9
| | | | | | +- hostHeader=download.eclipse.org
| | | | | +- [/xref/*]=&gt;XrefTransparentProxy
| | | | | += JavadocTransparentProxy@8ab9c012==org.eclipse.jetty.proxy.ProxyServlet$Transparent,1,true - STARTED
| | | | | | +- proxyTo=http://download.eclipse.org/jetty/stable-9
| | | | | | +- hostHeader=download.eclipse.org
| | | | | +- [/apidocs/*]=&gt;JavadocTransparentProxy
| | | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | | | +~ HashLoginService[Test Realm] - STARTED
| | | | +- org.eclipse.jetty.security.DefaultIdentityService@d2539a6
| | | | +- org.eclipse.jetty.security.authentication.BasicAuthenticator@5497fb72
| | | | |
| | | | +&gt; HashLoginService[Test Realm] - STARTED
| | | | +&gt; org.eclipse.jetty.security.DefaultIdentityService@d2539a6
| | | | +&gt; org.eclipse.jetty.security.authentication.BasicAuthenticator@5497fb72
| | | | +&gt; []
| | | | +&gt; /={TRACE={RoleInfo,F,C[]}}
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | += org.eclipse.jetty.servlet.ErrorPageErrorHandler@321f8d38 - STARTED
| | | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| | |
| | +&gt; WebAppClassLoader=Transparent Proxy WebApp@3570713d
| | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/classes/
| | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-client-{VERSION}.jar
| | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-http-{VERSION}.jar
| | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-io-{VERSION}.jar
| | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-proxy-{VERSION}.jar
| | | +- file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-util-{VERSION}.jar
| | | +- startJarLoader@7194b34a
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/resources/
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar
| | | +- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar
| | | +- sun.misc.Launcher$AppClassLoader@19d1b44b
| | | +- file:/home/user/jetty-distribution-{VERSION}/start.jar
| | | +- sun.misc.Launcher$ExtClassLoader@1693b52b
| | +&gt; javax.servlet.context.tempdir=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-
| | +&gt; org.apache.catalina.jsp_classpath=/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/classes:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-client-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-http-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-io-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-proxy-{VERSION}.jar:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/WEB-INF/lib/jetty-util-{VERSION}.jar
| | +&gt; org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern=.*/jetty-servlet-api-[^/]*\.jar$
| | +&gt; JavadocTransparentProxy.HttpClient=org.eclipse.jetty.client.HttpClient@580f016d
| | +&gt; XrefTransparentProxy.HttpClient=org.eclipse.jetty.client.HttpClient@70c7e52b
| | +&gt; com.sun.jsp.taglibraryCache={}
| | +&gt; com.sun.jsp.tagFileJarUrlsCache={}
| += org.eclipse.jetty.server.handler.DefaultHandler@4de4926a - STARTED
| | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| += org.eclipse.jetty.server.handler.RequestLogHandler@3dc087a2 - STARTED
| | += org.eclipse.jetty.server.AsyncNCSARequestLog@108a1cf6 - STARTED
| | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
+- org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| +- [/rego/*]=&gt;RegoTest=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=RegoTest,id=0
| +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@17d41d12=org.eclipse.jetty.security:context=test,type=defaultauthenticatorfactory,id=0
| +- org.eclipse.jetty.server.session.HashSessionManager@1246f8d0=org.eclipse.jetty.server.session:context=test,type=hashsessionmanager,id=0
| +- org.eclipse.jetty.security.ConstraintSecurityHandler@1890e38=org.eclipse.jetty.security:context=ROOT,type=constraintsecurityhandler,id=0
| +- WSChat@99274454==com.acme.WebSocketChatServlet,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=WSChat,id=0
| +- org.eclipse.jetty.deploy.DeploymentManager@c8e4be2=org.eclipse.jetty.deploy:type=deploymentmanager,id=0
| +- org.eclipse.jetty.jmx.MBeanContainer@644a5ddd=org.eclipse.jetty.jmx:type=mbeancontainer,id=0
| +- [/dump/gzip/*, *.txt]/[]==0=&gt;GzipFilter=org.eclipse.jetty.servlet:context=test,type=filtermapping,name=GzipFilter,id=0
| +- Hello@42628b2==com.acme.HelloWorld,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Hello,id=0
| +- [/]=&gt;default=org.eclipse.jetty.servlet:context=xref-proxy,type=servletmapping,name=default,id=0
| +- [/login/*]=&gt;Login=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Login,id=0
| +- org.eclipse.jetty.server.handler.DefaultHandler@4de4926a=org.eclipse.jetty.server.handler:type=defaulthandler,id=0
| +- org.eclipse.jetty.server.session.SessionHandler@5c25bf03=org.eclipse.jetty.server.session:context=xref-proxy,type=sessionhandler,id=0
| +- [/ws/*]=&gt;WSChat=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=WSChat,id=0
| +- o.e.j.w.WebAppContext@6f01ba6f{/,file:/home/user/jetty-distribution-{VERSION}/webapps/ROOT/,AVAILABLE}{/ROOT}=org.eclipse.jetty.webapp:context=ROOT,type=webappcontext,id=0
| +- o.e.j.w.WebAppContext@7ea88b1c{/async-rest,[file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/, jar:file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/example-async-rest-jar-9.0.2.v20130417.jar!/META-INF/resources/],AVAILABLE}{/async-rest.war}=org.eclipse.jetty.webapp:context=async-rest,type=webappcontext,id=0
| +- ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090}=org.eclipse.jetty.server:context=HTTP/1.1@3d0f282,type=serverconnector,id=0
| +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@6242c657=org.eclipse.jetty.security:context=ROOT,type=defaultauthenticatorfactory,id=0
| +- JavadocTransparentProxy@8ab9c012==org.eclipse.jetty.proxy.ProxyServlet$Transparent,1,true=org.eclipse.jetty.servlet:context=xref-proxy,type=servletholder,name=JavadocTransparentProxy,id=0
| +- [/dump/*, *.dump]=&gt;Dump=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Dump,id=0
| +- [/jsp/foo/]=&gt;foo.jsp=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=foo.jsp,id=0
| +- org.eclipse.jetty.servlet.ServletHandler@46bac287=org.eclipse.jetty.servlet:context=async-rest,type=servlethandler,id=0
| +- GzipFilter=org.eclipse.jetty.servlet:context=test,type=filterholder,name=GzipFilter,id=0
| +- o.e.j.w.WebAppContext@4ac92718{/proxy,file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/,AVAILABLE}{/xref-proxy.war}=org.eclipse.jetty.webapp:context=xref-proxy,type=webappcontext,id=0
| +- qtp1062680061{STARTED,10&lt;=13&lt;=200,i=1,q=0}=org.eclipse.jetty.util.thread:type=queuedthreadpool,id=0
| +- org.eclipse.jetty.server.session.HashSessionManager@33053093=org.eclipse.jetty.server.session:context=xref-proxy,type=hashsessionmanager,id=0
| +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@52b12fef=org.eclipse.jetty.security:context=async-rest,type=defaultauthenticatorfactory,id=0
| +- Login@462ff49==com.acme.LoginServlet,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Login,id=0
| +- org.eclipse.jetty.security.authentication.BasicAuthenticator@7b239469=org.eclipse.jetty.security.authentication:context=async-rest,type=basicauthenticator,id=0
| +- MultiPart=org.eclipse.jetty.servlet:context=test,type=filterholder,name=MultiPart,id=0
| +- default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true=org.eclipse.jetty.servlet:context=xref-proxy,type=servletholder,name=default,id=0
| +- default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true=org.eclipse.jetty.servlet:context=ROOT,type=servletholder,name=default,id=0
| +- default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true=org.eclipse.jetty.servlet:context=async-rest,type=servletholder,name=default,id=0
| +- default@5c13d641==org.eclipse.jetty.servlet.DefaultServlet,0,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=default,id=0
| +- org.eclipse.jetty.server.session.HashSessionManager@746a95ae=org.eclipse.jetty.server.session:context=ROOT,type=hashsessionmanager,id=0
| +- RegoTest2@849d6425==com.acme.RegTest,-1,false=org.eclipse.jetty.servlet:context=test,type=servletholder,name=RegoTest2,id=0
| +- org.eclipse.jetty.server.ServerConnector$ServerConnectorManager@6f0ac4be=org.eclipse.jetty.server:context=HTTP/1.1@3d0f282,type=serverconnector$serverconnectormanager,id=0
| +- [/]=&gt;default=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=default,id=0
| +- SecureMode@d45951da==com.acme.SecureModeServlet,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=SecureMode,id=0
| +- org.eclipse.jetty.security.authentication.BasicAuthenticator@6b733b94=org.eclipse.jetty.security.authentication:context=ROOT,type=basicauthenticator,id=0
| +- org.eclipse.jetty.server.session.SessionHandler@6dfb8d2e=org.eclipse.jetty.server.session:context=async-rest,type=sessionhandler,id=0
| +- org.eclipse.jetty.security.DefaultIdentityService@41917d6d=org.eclipse.jetty.security:context=test,type=defaultidentityservice,id=0
| +- jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true=org.eclipse.jetty.servlet:context=xref-proxy,type=servletholder,name=jsp,id=0
| +- jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true=org.eclipse.jetty.servlet:context=ROOT,type=servletholder,name=jsp,id=0
| +- jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true=org.eclipse.jetty.servlet:context=async-rest,type=servletholder,name=jsp,id=0
| +- jsp@19c47==org.apache.jasper.servlet.JspServlet,0,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=jsp,id=0
| +- [/*]/[]==31=&gt;TestFilter=org.eclipse.jetty.servlet:context=test,type=filtermapping,name=TestFilter,id=0
| +- org.eclipse.jetty.server.session.HashSessionManager@6cb83869=org.eclipse.jetty.server.session:context=async-rest,type=hashsessionmanager,id=0
| +- org.eclipse.jetty.io.ArrayByteBufferPool@30ad8942=org.eclipse.jetty.io:context=HTTP/1.1@3d0f282,type=arraybytebufferpool,id=0
| +- [/cgi-bin/*]=&gt;CGI=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=CGI,id=0
| +- org.eclipse.jetty.server.handler.HandlerCollection@58b37561=org.eclipse.jetty.server.handler:type=handlercollection,id=0
| +- Session@d9891a76==com.acme.SessionDump,5,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Session,id=0
| +- org.eclipse.jetty.servlet.ServletHandler@a08feeb=org.eclipse.jetty.servlet:context=xref-proxy,type=servlethandler,id=0
| +- org.eclipse.jetty.util.thread.ScheduledExecutorScheduler@725f5=org.eclipse.jetty.util.thread:type=scheduledexecutorscheduler,id=0
| +- [/*]/[]==0=&gt;QoSFilter=org.eclipse.jetty.servlet:context=test,type=filtermapping,name=QoSFilter,id=0
| +- org.eclipse.jetty.server.session.SessionHandler@5a770658=org.eclipse.jetty.server.session:context=ROOT,type=sessionhandler,id=0
| +- org.eclipse.jetty.server.session.SessionHandler@336abd81=org.eclipse.jetty.server.session:context=test,type=sessionhandler,id=0
| +- o.e.j.s.h.ContextHandler@7b2dffdf{/javadoc,file:/home/user/jetty-distribution-{VERSION}/javadoc,AVAILABLE}=org.eclipse.jetty.server.handler:context=javadoc,type=contexthandler,id=0
| +- org.eclipse.jetty.servlets.QoSFilter@6df3d1f5=org.eclipse.jetty.servlets:context=test,type=qosfilter,id=0
| +- [*.more]=&gt;Dump=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Dump,id=1
| +- Dump@20ae14==com.acme.Dump,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Dump,id=0
| +- HttpConnectionFactory@5e47b1b9{HTTP/1.1}=org.eclipse.jetty.server:context=HTTP/1.1@3d0f282,type=httpconnectionfactory,id=0
| +- org.eclipse.jetty.servlet.ServletHandler@debac27=org.eclipse.jetty.servlet:context=ROOT,type=servlethandler,id=0
| +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp=org.eclipse.jetty.servlet:context=xref-proxy,type=servletmapping,name=jsp,id=0
| +- org.eclipse.jetty.server.handler.MovedContextHandler$Redirector@2a4200d3=org.eclipse.jetty.server.handler:context=oldContextPath,type=movedcontexthandler$redirector,id=0
| +- TestFilter=org.eclipse.jetty.servlet:context=test,type=filterholder,name=TestFilter,id=0
| +- Rewrite@a4dac96c==com.acme.RewriteServlet,-1,false=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Rewrite,id=0
| +- [/dispatch/*]=&gt;Dispatch=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Dispatch,id=0
| +- [/testSerial]=&gt;SerialRestServlet=org.eclipse.jetty.servlet:context=async-rest,type=servletmapping,name=SerialRestServlet,id=0
| +- org.eclipse.jetty.servlet.ErrorPageErrorHandler@24bf7a86=org.eclipse.jetty.servlet:context=test,type=errorpageerrorhandler,id=0
| +- [/secureMode/*]=&gt;SecureMode=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=SecureMode,id=0
| +- [/]=&gt;default=org.eclipse.jetty.servlet:context=async-rest,type=servletmapping,name=default,id=0
| +- Dispatch@14d3a89a==com.acme.DispatchServlet,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Dispatch,id=0
| +- org.eclipse.jetty.server.handler.ContextHandlerCollection@64c6e290=org.eclipse.jetty.server.handler:type=contexthandlercollection,id=0
| +- org.eclipse.jetty.security.ConstraintSecurityHandler@2848c90e=org.eclipse.jetty.security:context=async-rest,type=constraintsecurityhandler,id=0
| +- [/rego2/*]=&gt;RegoTest2=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=RegoTest2,id=0
| +- [/rewritten/*, /redirected/*]=&gt;Rewrite=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Rewrite,id=0
| +- org.eclipse.jetty.servlet.ServletHandler@5034037e=org.eclipse.jetty.servlet:context=test,type=servlethandler,id=0
| +- org.eclipse.jetty.servlet.ErrorPageErrorHandler@3c121009=org.eclipse.jetty.servlet:context=async-rest,type=errorpageerrorhandler,id=0
| +- sun.nio.ch.ServerSocketChannelImpl[/0:0:0:0:0:0:0:0:9090]=sun.nio.ch:context=HTTP/1.1@3d0f282,type=serversocketchannelimpl,id=0
| +- org.eclipse.jetty.security.ConstraintSecurityHandler@7179290f=org.eclipse.jetty.security:context=test,type=constraintsecurityhandler,id=0
| +- org.eclipse.jetty.server.session.HashSessionIdManager@289eb857=org.eclipse.jetty.server.session:type=hashsessionidmanager,id=0
| +- org.eclipse.jetty.security.authentication.BasicAuthenticator@5497fb72=org.eclipse.jetty.security.authentication:context=xref-proxy,type=basicauthenticator,id=0
| +- org.eclipse.jetty.security.DefaultAuthenticatorFactory@11ad5296=org.eclipse.jetty.security:context=xref-proxy,type=defaultauthenticatorfactory,id=0
| +- [/dump/*]/[]==0=&gt;MultiPart=org.eclipse.jetty.servlet:context=test,type=filtermapping,name=MultiPart,id=0
| +- o.e.j.s.h.MovedContextHandler@5e0c8d24{/oldContextPath,null,AVAILABLE}=org.eclipse.jetty.server.handler:context=oldContextPath,type=movedcontexthandler,id=0
| +- QoSFilter=org.eclipse.jetty.servlet:context=test,type=filterholder,name=QoSFilter,id=0
| +- org.eclipse.jetty.security.authentication.FormAuthenticator@1fa291f2=org.eclipse.jetty.security.authentication:context=test,type=formauthenticator,id=0
| +- o.e.j.w.WebAppContext@716d9094{/test,file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/,AVAILABLE}{/test.war}=org.eclipse.jetty.webapp:context=test,type=webappcontext,id=0
| +- [/]=&gt;default=org.eclipse.jetty.servlet:context=ROOT,type=servletmapping,name=default,id=0
| +- [/hello/*]=&gt;Hello=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Hello,id=0
| +- [/chat/*]=&gt;Chat=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Chat,id=0
| +- [/testAsync]=&gt;AsyncRestServlet=org.eclipse.jetty.servlet:context=async-rest,type=servletmapping,name=AsyncRestServlet,id=0
| +- org.eclipse.jetty.security.DefaultIdentityService@d2539a6=org.eclipse.jetty.security:context=async-rest,type=defaultidentityservice,id=0
| +- org.eclipse.jetty.server.handler.RequestLogHandler@3dc087a2=org.eclipse.jetty.server.handler:type=requestloghandler,id=0
| +- org.eclipse.jetty.servlet.ErrorPageErrorHandler@321f8d38=org.eclipse.jetty.servlet:context=xref-proxy,type=errorpageerrorhandler,id=0
| +- org.eclipse.jetty.server.handler.ResourceHandler@8f9c8a7=org.eclipse.jetty.server.handler:context=javadoc,type=resourcehandler,id=0
| +- CGI@10465==org.eclipse.jetty.servlets.CGI,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=CGI,id=0
| +- SerialRestServlet@461411d==org.eclipse.jetty.example.asyncrest.SerialRestServlet,-1,false=org.eclipse.jetty.servlet:context=async-rest,type=servletholder,name=SerialRestServlet,id=0
| +- HashLoginService[Test Realm]=org.eclipse.jetty.security:type=hashloginservice,id=0
| +- AsyncRestServlet@73eb9bd5==org.eclipse.jetty.example.asyncrest.AsyncRestServlet,-1,false=org.eclipse.jetty.servlet:context=async-rest,type=servletholder,name=AsyncRestServlet,id=0
| +- org.eclipse.jetty.server.Server@76f08fe1=org.eclipse.jetty.server:type=server,id=0
| +- org.eclipse.jetty.servlet.ErrorPageErrorHandler@3c41a9ce=org.eclipse.jetty.servlet:context=ROOT,type=errorpageerrorhandler,id=0
| +- [/apidocs/*]=&gt;JavadocTransparentProxy=org.eclipse.jetty.servlet:context=xref-proxy,type=servletmapping,name=JavadocTransparentProxy,id=0
| +- Chat@200778==com.acme.ChatServlet,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Chat,id=0
| +- [/cookie/*]=&gt;Cookie=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Cookie,id=0
| +- [/session/*]=&gt;Session=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=Session,id=0
| +- org.eclipse.jetty.deploy.providers.WebAppProvider@7b26b7df=org.eclipse.jetty.deploy.providers:type=webappprovider,id=0
| +- org.eclipse.jetty.server.AsyncNCSARequestLog@108a1cf6=org.eclipse.jetty.server:type=asyncncsarequestlog,id=0
| +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp=org.eclipse.jetty.servlet:context=test,type=servletmapping,name=jsp,id=0
| +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp=org.eclipse.jetty.servlet:context=ROOT,type=servletmapping,name=jsp,id=0
| +- HashLoginService[Test Realm]=org.eclipse.jetty.security:context=test,type=hashloginservice,id=0
| +- [*.jsp, *.jspf, *.jspx, *.xsp, *.JSP, *.JSPF, *.JSPX, *.XSP]=&gt;jsp=org.eclipse.jetty.servlet:context=async-rest,type=servletmapping,name=jsp,id=0
| +- foo.jsp@d7583f1f==org.apache.jasper.servlet.JspServlet,-1,false=org.eclipse.jetty.servlet:context=test,type=servletholder,name=foo.jsp,id=0
| +- RegoTest@dafcd1ad==com.acme.RegTest,-1,false=org.eclipse.jetty.servlet:context=test,type=servletholder,name=RegoTest,id=0
| +- [/xref/*]=&gt;XrefTransparentProxy=org.eclipse.jetty.servlet:context=xref-proxy,type=servletmapping,name=XrefTransparentProxy,id=0
| +- org.eclipse.jetty.security.ConstraintSecurityHandler@3bab0b5a=org.eclipse.jetty.security:context=xref-proxy,type=constraintsecurityhandler,id=0
| +- HttpConfiguration@703b16bb{32768,8192/8192,https://:8443,[]}=org.eclipse.jetty.server:context=HTTP/1.1@3d0f282,type=httpconfiguration,id=0
| +- org.eclipse.jetty.util.log.Log@dda4f7b=org.eclipse.jetty.util.log:type=log,id=0
| +- Cookie@78a4f684==com.acme.CookieDump,1,true=org.eclipse.jetty.servlet:context=test,type=servletholder,name=Cookie,id=0
| +- XrefTransparentProxy@b0222797==org.eclipse.jetty.proxy.ProxyServlet$Transparent,1,true=org.eclipse.jetty.servlet:context=xref-proxy,type=servletholder,name=XrefTransparentProxy,id=0
+- org.eclipse.jetty.util.log.Log@dda4f7b
+= ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090} - STARTED
| +~ org.eclipse.jetty.server.Server@76f08fe1 - STARTING
| +~ qtp1062680061{STARTED,10&lt;=13&lt;=200,i=1,q=0} - STARTED
| +~ org.eclipse.jetty.util.thread.ScheduledExecutorScheduler@725f5 - STARTED
| +- org.eclipse.jetty.io.ArrayByteBufferPool@30ad8942
| += HttpConnectionFactory@5e47b1b9{HTTP/1.1} - STARTED
| | +- HttpConfiguration@703b16bb{32768,8192/8192,https://:8443,[]}
| | +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| += org.eclipse.jetty.server.ServerConnector$ServerConnectorManager@6f0ac4be - STARTED
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@61454787 keys=0 selected=0 id=0
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@a0c508b keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@2e7bdad4 keys=0 selected=0 id=1
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@5825168 keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@2eae85ab keys=0 selected=0 id=2
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@6faa85f6 keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@244112c0 keys=0 selected=0 id=3
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@10c6f695 keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@7666b8cd keys=0 selected=0 id=4
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@17836c59 keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@353e531e keys=0 selected=0 id=5
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@2095f259 keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@5459c1c5 keys=0 selected=0 id=6
| | | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | | +- sun.nio.ch.KQueueSelectorImpl@142c7195 keys=0
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector@71d4f78b keys=0 selected=0 id=7
| | +- org.eclipse.jetty.io.SelectorManager$ManagedSelector.select(SelectorManager.java:459)
| | +- sun.nio.ch.KQueueSelectorImpl@16bdab45 keys=0
| +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
| +- sun.nio.ch.ServerSocketChannelImpl[/0:0:0:0:0:0:0:0:9090]
+= org.eclipse.jetty.deploy.DeploymentManager@c8e4be2 - STARTED
| +~ org.eclipse.jetty.deploy.providers.WebAppProvider@7b26b7df - STARTED
| +~ org.eclipse.jetty.jmx.MBeanContainer@644a5ddd
+~ HashLoginService[Test Realm] - STARTED
+= org.eclipse.jetty.server.session.HashSessionIdManager@289eb857 - STARTED
|
+&gt; startJarLoader@7194b34a
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-xml-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-api-4.0.2.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-http-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-continuation-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-server-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-security-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-servlet-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-webapp-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-deploy-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-client-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-jmx-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/com.sun.el-2.2.0.v201303151357.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.el-2.2.0.v201303151357.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp.jstl-1.2.0.v201105211821.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/javax.servlet.jsp-2.2.0.v201112011158.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.jasper.glassfish-2.2.2.v201112011158.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.apache.taglibs.standard.glassfish-1.2.0.v201112081803.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jsp/org.eclipse.jdt.core-3.8.2.v20130121.jar
+- file:/home/user/jetty-distribution-{VERSION}/resources/
+- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-api-9.0.2.v20130417.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-common-9.0.2.v20130417.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-server-9.0.2.v20130417.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/websocket/websocket-servlet-9.0.2.v20130417.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-util-{VERSION}.jar
+- file:/home/user/jetty-distribution-{VERSION}/lib/jetty-io-{VERSION}.jar
+- sun.misc.Launcher$AppClassLoader@19d1b44b
+- file:/home/user/jetty-distribution-{VERSION}/start.jar
+- sun.misc.Launcher$ExtClassLoader@1693b52b
2013-04-29 14:38:39.422:INFO:oejs.Server:Thread-2: Graceful shutdown org.eclipse.jetty.server.Server@76f08fe1 by Mon Apr 29 14:38:44 CDT 2013
2013-04-29 14:38:39.429:INFO:oejs.ServerConnector:Thread-2: Stopped ServerConnector@3d0f282{HTTP/1.1}{0.0.0.0:9090}
2013-04-29 14:38:39.444:INFO:oejsl.ELContextCleaner:Thread-2: javax.el.BeanELResolver purged
2013-04-29 14:38:39.444:INFO:oejsh.ContextHandler:Thread-2: stopped o.e.j.w.WebAppContext@4ac92718{/proxy,file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-xref-proxy.war-_xref-proxy-any-/webapp/,UNAVAILABLE}{/xref-proxy.war}
2013-04-29 14:38:39.447:INFO:oejsl.ELContextCleaner:Thread-2: javax.el.BeanELResolver purged
2013-04-29 14:38:39.447:INFO:oejsh.ContextHandler:Thread-2: stopped o.e.j.w.WebAppContext@716d9094{/test,file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-test.war-_test-any-/webapp/,UNAVAILABLE}{/test.war}
2013-04-29 14:38:39.455:INFO:oejsh.ContextHandler:Thread-2: stopped o.e.j.s.h.ContextHandler@7b2dffdf{/javadoc,file:/home/user/jetty-distribution-{VERSION}/javadoc,UNAVAILABLE}
2013-04-29 14:38:39.456:INFO:oejsl.ELContextCleaner:Thread-2: javax.el.BeanELResolver purged
2013-04-29 14:38:39.456:INFO:oejsh.ContextHandler:Thread-2: stopped o.e.j.w.WebAppContext@6f01ba6f{/,file:/home/user/jetty-distribution-{VERSION}/webapps/ROOT/,UNAVAILABLE}{/ROOT}
2013-04-29 14:38:39.456:INFO:oejsh.ContextHandler:Thread-2: stopped o.e.j.s.h.MovedContextHandler@5e0c8d24{/oldContextPath,null,UNAVAILABLE}
2013-04-29 14:38:39.457:INFO:oejsl.ELContextCleaner:Thread-2: javax.el.BeanELResolver purged
2013-04-29 14:38:39.457:INFO:oejsh.ContextHandler:Thread-2: stopped o.e.j.w.WebAppContext@7ea88b1c{/async-rest,[file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/, jar:file:/private/var/folders/br/kbs2g3753c54wmv4j31pnw5r0000gn/T/jetty-0.0.0.0-9090-async-rest.war-_async-rest-any-/webapp/WEB-INF/lib/example-async-rest-jar-9.0.2.v20130417.jar!/META-INF/resources/],UNAVAILABLE}{/async-rest.war}</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-security">Configuring Security</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="configuring-security-authentication">Authentication and Authorization</h3>
<div class="paragraph">
<p>There are two aspects to securing a web application(or context) within the Jetty server:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Authentication</dt>
<dd>
<p>The web application can be configured with a mechanism to determine the identity of the user.
This is configured by a mix of standard declarations and jetty specific mechanisms and is covered in this section.</p>
</dd>
<dt class="hdlist1">Authorization</dt>
<dd>
<p>Once the identify of the user is known (or not known), the web application can be configured via standard descriptors with security constraints that declare what resources that user may access.</p>
</dd>
</dl>
</div>
<div class="sect3">
<h4>Configuring an Authentication mechanism</h4>
<div class="paragraph">
<p>Jetty server supports several standard authentication mechanisms: <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">BASIC</a>; <a href="http://en.wikipedia.org/wiki/Digest_authentication">DIGEST</a>; <a href="http://en.wikipedia.org/wiki/Form-based_authentication">FORM</a>; CLIENT-CERT; and other mechanisms can be plugged in using the extensible <a href="http://docs.oracle.com/cd/E19462-01/819-6717/gcszc/index.html">JASPI</a> or <a href="http://en.wikipedia.org/wiki/SPNEGO">SPNEGO</a> mechanisms.</p>
</div>
<div class="paragraph">
<p>Internally, configuring an authentication mechanism is done by setting an instance of a the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/Authenticator.html">Authenticator</a> interface onto the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/SecurityHandler.html">SecurityHandler</a> of the context, but in most cases it is done by declaring a <code>&lt;login-config&gt;</code> element in the standard web.xml descriptor or via annotations.</p>
</div>
<div class="paragraph">
<p>Below is an example taken from the <a href="https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB-INF/web.xml?h=release-9">jetty-test-webapp web.xml</a> that configures BASIC authentication:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;login-config&gt;
&lt;auth-method&gt;BASIC&lt;/auth-method&gt;
&lt;realm-name&gt;Test Realm&lt;/realm-name&gt;
&lt;/login-config&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <a href="https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jetty-webapp/src/main/webapp/WEB-INF/web.xml?h=release-9">jetty-test-webapp web.xml</a> also includes commented out examples of other DIGEST and FORM configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;login-config&gt;
&lt;auth-method&gt;FORM&lt;/auth-method&gt;
&lt;realm-name&gt;Test Realm&lt;/realm-name&gt;
&lt;form-login-config&gt;
&lt;form-login-page&gt;/logon.html?param=test&lt;/form-login-page&gt;
&lt;form-error-page&gt;/logonError.html?param=test&lt;/form-error-page&gt;
&lt;/form-login-config&gt;
&lt;/login-config&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>With FORM Authentication, you must also configure URLs of pages to generate a login form and handle errors.
Below is a simple HTML form from the <a href="https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jetty-webapp/src/main/webapp/logon.html?h=release-9">test webapp logon.html</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;HTML&gt;
&lt;H1&gt;FORM Authentication demo&lt;/H1&gt;
&lt;form method="POST" action="j_security_check"&gt;
&lt;table border="0" cellspacing="2" cellpadding="1"&gt;
&lt;tr&gt;
&lt;td&gt;Username:&lt;/td&gt;
&lt;td&gt;&lt;input size="12" value="" name="j_username" maxlength="25" type="text"&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Password:&lt;/td&gt;
&lt;td&gt;&lt;input size="12" value="" name="j_password" maxlength="25" type="password"&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td colspan="2" align="center"&gt;
&lt;input name="submit" type="submit" value="Login"&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/form&gt;
&lt;/HTML&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The Authentication mechanism declared for a context / web application defines how the server obtain authentication credentials from the
client, but it does not define how the server checks if those credentials are valid.
To check credentials, the server and/or context also need to be configured with a <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/LoginService.html">LoginService</a> instance, which may be matched by the declared realm-name.</p>
</div>
</div>
<div class="sect3">
<h4 id="security-realms">Security Realms</h4>
<div class="paragraph">
<p>Security realms allow you to secure your web applications against unauthorized access.
Protection is based on authentication that identifies who is requesting access to the webapp and access control that restricts what can be accessed and how it is accessed within the webapp.</p>
</div>
<div class="paragraph">
<p>A webapp statically declares its security requirements in its web.xml file.
Authentication is controlled by the <code>&lt;login-config&gt;</code> element.
Access controls are specified by <code>&lt;security-constraint&gt;</code> and <code>&lt;security-role-ref&gt;</code> elements.
When a request is received for a protected resource, the web container checks if the user performing the request is authenticated, and if the user has a role assignment that permits access to the requested resource.</p>
</div>
<div class="paragraph">
<p>The Servlet Specification does not address how the static security information in the <code>WEB-INF/web.xml</code> file is mapped to the runtime environment of the container.
For Jetty, the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/LoginService.html">LoginService</a> performs this function.</p>
</div>
<div class="paragraph">
<p>A <code>LoginService</code> has a unique name, and gives access to information about a set of users.
Each user has authentication information (e.g. a password) and a set of roles associated with him/herself.</p>
</div>
<div class="paragraph">
<p>You may configure one or many different LoginServices depending on your needs.
A single realm would indicate that you wish to share common security information across all of your web applications.
Distinct realms allow you to partition your security information webapp by webapp.</p>
</div>
<div class="paragraph">
<p>When a request to a web application requires authentication or authorization, Jetty will use the <code>&lt;realm-name&gt;</code> sub-element inside <code>&lt;login-config&gt;</code> element in the web.xml file to perform an <em>exact match</em> to a LoginService.</p>
</div>
</div>
<div class="sect3">
<h4>Scoping Security Realms</h4>
<div class="paragraph">
<p>A <code>LoginService</code> has a unique name, and is composed of a set of users.
Each user has authentication information (for example, a password) and a set of roles associated with him/herself.
You can configure one or many different realms depending on your needs.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Configure a single LoginService to share common security information across all of your web applications.</p>
</li>
<li>
<p>Configure distinct LoginServices to partition your security information webapp by webapp.</p>
</li>
</ul>
</div>
<div class="sect4">
<h5>Globally Scoped</h5>
<div class="paragraph">
<p>A LoginService is available to all web applications on a Server instance if you add it as a bean to the Server.
Such a definition would go into an xml file in your <code>${jetty.base}/etc</code> directory, e.g. <code>${jetty.base}/etc/my-realm.xml</code> and you would add this xml file to the execution path via <code>start.ini</code> or <code>start.d</code> (you may want to review the material in the <a href="#startup">Starting Jetty</a> chapter).
Here&#8217;s an example of an xml file that defines an in-memory type of LoginService called the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/HashLoginService.html">HashLoginService</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.security.HashLoginService"&gt;
&lt;Set name="name"&gt;Test Realm&lt;/Set&gt;
&lt;Set name="config"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/etc/realm.properties&lt;/Set&gt;
&lt;Set name="hotReload"&gt;true&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you define more than one <code>LoginService</code> on a Server, you will need to specify which one you want used for each context.
You can do that by telling the context the name of the <code>LoginService</code>, or passing it the <code>LoginService</code> instance.
Here&#8217;s an example of doing both of these, using a <a href="#deployable-descriptor-file">context xml file</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Get name="securityHandler"&gt;
&lt;!-- Either: --&gt;
&lt;Set name="loginService"&gt;
&lt;New class="org.eclipse.jetty.security.HashLoginService"&gt;
&lt;Set name="name"&gt;Test Realm&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;!-- or if you defined a LoginService called "Test Realm" in jetty.xml : --&gt;
&lt;Set name="realmName"&gt;Test Realm&lt;/Set&gt;
&lt;/Get&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Per-Webapp Scoped</h5>
<div class="paragraph">
<p>Alternatively, you can define a <code>LoginService</code> for just a single web application.
Here&#8217;s how to define the same HashLoginService, but inside a <a href="#deployable-descriptor-file">context xml file</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
&lt;Set name="war"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/webapps/test&lt;/Set&gt;
&lt;Get name="securityHandler"&gt;
&lt;Set name="loginService"&gt;
&lt;New class="org.eclipse.jetty.security.HashLoginService"&gt;
&lt;Set name="name"&gt;Test Realm&lt;/Set&gt;
&lt;Set name="config"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/etc/realm.properties&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Get&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Jetty provides a number of different <code>LoginService</code> types which can be seen in the next section.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuring-login-service">Configuring a LoginService</h4>
<div class="paragraph">
<p>A <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/LoginService.html"><code>LoginService</code></a> instance is required by each context/webapp that has a authentication mechanism, which is used to check the validity of the username and credentials collected by the authentication mechanism. Jetty provides the following implementations of <code>LoginService</code>:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/HashLoginService.html">HashLoginService</a></dt>
<dd>
<p>A user realm that is backed by a hash map that is filled either programatically or from a Java properties file.</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/JDBCLoginService.html">JDBCLoginService</a></dt>
<dd>
<p>Uses a JDBC connection to an SQL database for authentication</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/plus/security/DataSourceLoginService.html">DataSourceLoginService</a></dt>
<dd>
<p>Uses a JNDI defined <a href="http://docs.oracle.com/javase/7/docs/api/javax/sql/DataSource.html">DataSource</a> for authentication</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/jaas/JAASLoginService.html">JAASLoginService</a></dt>
<dd>
<p>Uses a <a href="http://en.wikipedia.org/wiki/Java_Authentication_and_Authorization_Service">JAAS</a> provider for authentication; see the section on
<a href="#jaas-support">JAAS support</a> for more information</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/security/SpnegoLoginService.html">SpnegoLoginService</a></dt>
<dd>
<p><a href="http://en.wikipedia.org/wiki/SPNEGO">SPNEGO</a> Authentication; see the section on <a href="#spnego-support">SPNEGO support</a> for more information.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>An instance of a <code>LoginService</code> can be matched to a context/webapp by:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A <code>LoginService</code> instance may be set directly on the <code>SecurityHandler</code> instance via embedded code or IoC XML</p>
</li>
<li>
<p>Matching the realm-name defined in web.xml with the name of a <code>LoginService</code> instance that has been added to the Server instance as a dependent bean</p>
</li>
<li>
<p>If only a single <code>LoginService</code> instance has been set on the Server then it is used as the login service for the context</p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="hash-login-service">HashLoginService</h5>
<div class="paragraph">
<p>The <code>HashLoginService</code> is a simple and efficient login service that loads usernames, credentials and roles from a Java properties file in the format:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">username: password[,rolename ...]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Where:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">username</dt>
<dd>
<p>is the user&#8217;s unique identity</p>
</dd>
<dt class="hdlist1">password</dt>
<dd>
<p>is the user&#8217;s (possibly obfuscated or MD5 encrypted) password;</p>
</dd>
<dt class="hdlist1">rolename</dt>
<dd>
<p>is a role of the user</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">admin: CRYPT:ad1ks..kc.1Ug,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq
guest: guest,read-only</code></pre>
</div>
</div>
<div class="paragraph">
<p>You configure the <code>HashLoginService</code> with a name and a reference to the location of the properties file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Item&gt;
&lt;New class="org.eclipse.jetty.security.HashLoginService"&gt;
&lt;Set name="name"&gt;Test Realm&lt;/Set&gt;
&lt;Set name="config"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/etc/realm.properties&lt;/Set&gt;
&lt;/New&gt;
&lt;/Item&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can also configure it to reload the configuration file when changes to it are detected.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.security.HashLoginService"&gt;
&lt;Set name="name"&gt;Test Realm&lt;/Set&gt;
&lt;Set name="config"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/etc/realm.properties&lt;/Set&gt;
&lt;Set name="hotReload"&gt;true&lt;/Set&gt;
&lt;Call name="start"&gt;&lt;/Call&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="jdbc-login-service">JDBCLoginService</h5>
<div class="paragraph">
<p>In this implementation, authentication and role information is stored in a database accessed via JDBC.
A properties file defines the JDBC connection and database table information.
Here is an example of a properties file for this realm implementation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-properties" data-lang="properties">jdbcdriver = org.gjt.mm.mysql.Driver
url = jdbc:mysql://localhost/jetty
username = jetty
password = jetty
usertable = users
usertablekey = id
usertableuserfield = username
usertablepasswordfield = pwd
roletable = roles
roletablekey = id
roletablerolefield = role
userroletable = user_roles
userroletableuserkey = user_id
userroletablerolekey = role_id
cachetime = 300</code></pre>
</div>
</div>
<div class="paragraph">
<p>The format of the database tables is (pseudo-sql):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-sql" data-lang="sql">users
(
id integer PRIMARY KEY,
username varchar(100) NOT NULL UNIQUE KEY,
pwd varchar(50) NOT NULL
);
user_roles
(
user_id integer NOT NULL,
role_id integer NOT NULL,
UNIQUE KEY (user_id, role_id),
INDEX(user_id)
);
roles
(
id integer PRIMARY KEY,
role varchar(100) NOT NULL UNIQUE KEY
);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Where:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>users</strong> is a table containing one entry for every user consisting of:</p>
<div class="dlist">
<dl>
<dt class="hdlist1">id</dt>
<dd>
<p>the unique identity of a user</p>
</dd>
<dt class="hdlist1">user</dt>
<dd>
<p>the name of the user</p>
</dd>
<dt class="hdlist1">pwd</dt>
<dd>
<p>the user&#8217;s password (possibly obfuscated or MD5 encrypted)</p>
</dd>
</dl>
</div>
</li>
<li>
<p><strong>user-roles</strong> is a table containing one row for every role granted to a
user:</p>
<div class="dlist">
<dl>
<dt class="hdlist1">user_id</dt>
<dd>
<p>the unique identity of the user</p>
</dd>
<dt class="hdlist1">role_id</dt>
<dd>
<p>the role for a user</p>
</dd>
</dl>
</div>
</li>
<li>
<p><strong>roles</strong> is a a table containing one role for every role in the system:</p>
<div class="dlist">
<dl>
<dt class="hdlist1">id</dt>
<dd>
<p>the unique identifier of a role</p>
</dd>
<dt class="hdlist1">role</dt>
<dd>
<p>a human-readable name for a role</p>
</dd>
</dl>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>If you want to use obfuscated, MD5 hashed or encrypted passwords the <code>pwd</code> column of the <code>users</code> table must be large enough to hold the obfuscated, hashed or encrypted password text plus the appropriate prefix.</p>
</div>
<div class="paragraph">
<p>You define a <code>JDBCLoginService</code> with the name of the realm and the location of the properties file describing the database:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.security.JDBCLoginService"&gt;
&lt;Set name="name"&gt;Test JDBC Realm&lt;/Set&gt;
&lt;Set name="config"&gt;etc/jdbcRealm.properties&lt;/Set&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Authorization</h4>
<div class="paragraph">
<p>As far as the <a href="https://jcp.org/en/jsr/detail?id=340">Servlet Specification</a> is concerned, authorization is based on roles.
As we have seen, a <code>LoginService</code> associates a user with a set of roles.
When a user requests a resource that is access protected, the <code>LoginService</code> will be asked to authenticate the user if they are not already, and then asked to confirm if that user possesses one of the roles permitted access to the resource.</p>
</div>
<div class="paragraph">
<p>Until Servlet 3.1, role-based authorization could define:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Access granted to a set of named roles:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;security-constraint&gt;
&lt;web-resource-collection&gt;
&lt;web-resource-name&gt;Foo Admin Data&lt;/web-resource-name&gt;
&lt;url-pattern&gt;/foo/admin/*&lt;/url-pattern&gt;
&lt;/web-resource-collection&gt;
&lt;auth-constraint&gt;
&lt;role-name&gt;admin&lt;/role-name&gt;
&lt;role-name&gt;manager&lt;/role-name&gt;
&lt;/auth-constraint&gt;
&lt;/security-constraint&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Access totally forbidden, regardless of role:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;security-constraint&gt;
&lt;web-resource-collection&gt;
&lt;web-resource-name&gt;Foo Protected Data&lt;/web-resource-name&gt;
&lt;url-pattern&gt;/foo/protected/*&lt;/url-pattern&gt;
&lt;/web-resource-collection&gt;
&lt;auth-constraint&gt;
&lt;/auth-constraint&gt;
&lt;/security-constraint&gt;</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p>Access granted to a user in any of the roles defined in the effective <code>web.xml</code>.
This is indicated by the special value of <code>*</code> for the <code>&lt;role-name&gt;</code> of a <code>&lt;auth-constraint&gt;</code> in the <code>&lt;security-constraint&gt;</code>:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;security-constraint&gt;
&lt;web-resource-collection&gt;
&lt;web-resource-name&gt;Foo Role Data&lt;/web-resource-name&gt;
&lt;url-pattern&gt;/foo/role/*&lt;/url-pattern&gt;
&lt;/web-resource-collection&gt;
&lt;auth-constraint&gt;
&lt;role-name&gt;*&lt;/role-name&gt;
&lt;/auth-constraint&gt;
&lt;/security-constraint&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Servlet 3.1 introduced an additional authorization:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Access granted to any user who is authenticated, regardless of roles.
This is indicated by the special value of <code>**</code> for the <code>&lt;role-name&gt;</code> of a <code>&lt;auth-constraint&gt;</code> in the <code>&lt;security-constraint&gt;</code>:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;security-constraint&gt;
&lt;web-resource-collection&gt;
&lt;web-resource-name&gt;Foo Authenticated Data&lt;/web-resource-name&gt;
&lt;url-pattern&gt;/foo/authenticated/*&lt;/url-pattern&gt;
&lt;/web-resource-collection&gt;
&lt;auth-constraint&gt;
&lt;role-name&gt;**&lt;/role-name&gt;
&lt;/auth-constraint&gt;
&lt;/security-constraint&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Additionally, when configuring your security constraints you can protect various HTTP methods as well, such as <code>PUT</code>, <code>GET</code>, <code>POST</code>, <code>HEAD</code> or <code>DELETE</code>.
This is done by adding the method you want to protect as a <code>&lt;http-method&gt;</code> in the <code>&lt;web-resource-collection&gt;</code>.
You can then define roles that should be able to perform these protected methods in an <code>&lt;auth-constraint&gt;</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;security-constraint&gt;
&lt;web-resource-collection&gt;
&lt;web-resource-name&gt;Foo Authenticated Data&lt;/web-resource-name&gt;
&lt;url-pattern&gt;/foo/authenticated/*&lt;/url-pattern&gt;
&lt;http-method&gt;DELETE&lt;/http-method&gt;
&lt;http-method&gt;POST&lt;/http-method&gt;
&lt;/web-resource-collection&gt;
&lt;auth-constraint&gt;
&lt;role-name&gt;admin&lt;/role-name&gt;
&lt;/auth-constraint&gt;
&lt;/security-constraint&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the above example, only users with an <code>admin</code> role will be able to perform <code>DELETE</code> or <code>POST</code> methods.</p>
</div>
<div class="sect4">
<h5>Configuring Authorization with Context XML Files</h5>
<div class="paragraph">
<p>While the examples above show configuration of Authorization in a <code>web.xml</code> file, they can also be configured as part of the link#<a href="#deployable-descriptor-file">context xml file</a> for a web application.
This is especially helpful if authorization needs change over time and need updated without re-packaging the whole web app.</p>
</div>
<div class="paragraph">
<p>To do this, we add a section for security constraints into the context xml file for our web app as part of the <code>securityHandler</code>.
In the example below, a <code>HashLoginService</code> is defined with authorization being granted too <code>foo/*</code> paths to users with the <code>admin</code> and <code>manager</code> roles.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="testWebapp" class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Get name="securityHandler"&gt;
&lt;Set name="realmName"&gt;Test Realm&lt;/Set&gt;
&lt;Set name="authMethod"&gt;BASIC&lt;/Set&gt;
&lt;Call name="addConstraintMapping"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.security.ConstraintMapping"&gt;
&lt;Set name="pathSpec"&gt;/foo/*&lt;/Set&gt;
&lt;Set name="constraint"&gt;
&lt;New class="org.eclipse.jetty.util.security.Constraint"&gt;
&lt;Set name="name"&gt;Foo Auth&lt;/Set&gt;
&lt;Set name="authenticate"&gt;true&lt;/Set&gt;
&lt;Set name="roles"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;admin&lt;/Item&gt;
&lt;Item&gt;manager&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Set name="loginService"&gt;
&lt;New class="org.eclipse.jetty.security.HashLoginService"&gt;
&lt;Set name="name"&gt;Test Realm&lt;/Set&gt;
&lt;Set name="config"&gt;/src/tmp/small-security-test/realm.properties&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Get&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If roles changed in the future, administrators could easily change this context xml file without having to edit the contents of the web app at all.</p>
</div>
</div>
</div>
<div class="sect3">
<h4>Authentication and Authorization with Embedded Jetty</h4>
<div class="paragraph">
<p>In addition to the distribution, security can be defined as part of an embedded implementation as well.
Below is an example which, like the one above, sets up a server with a <code>HashLoginService</code> and adds security constraints to restrict access based on roles.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">//
// ========================================================================
// 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
// ========================================================================
//
package org.eclipse.jetty.embedded;
import java.io.FileNotFoundException;
import java.net.URL;
import java.util.Collections;
import org.eclipse.jetty.security.ConstraintMapping;
import org.eclipse.jetty.security.ConstraintSecurityHandler;
import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.security.LoginService;
import org.eclipse.jetty.security.authentication.BasicAuthenticator;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.util.security.Constraint;
public class SecuredHelloHandler
{
public static Server createServer(int port) throws FileNotFoundException
{
// Create a basic jetty server object that will listen on port 8080.
// Note that if you set this to port 0 then a randomly available port
// will be assigned that you can either look in the logs for the port,
// or programmatically obtain it for use in test cases.
Server server = new Server(port);
// Since this example is for our test webapp, we need to setup a
// LoginService so this shows how to create a very simple hashmap based
// one. The name of the LoginService needs to correspond to what is
// configured a webapp's web.xml and since it has a lifecycle of its own
// we register it as a bean with the Jetty server object so it can be
// started and stopped according to the lifecycle of the server itself.
// In this example the name can be whatever you like since we are not
// dealing with webapp realms.
String realmResourceName = "etc/realm.properties";
ClassLoader classLoader = SecuredHelloHandler.class.getClassLoader();
URL realmProps = classLoader.getResource(realmResourceName);
if (realmProps == null)
throw new FileNotFoundException("Unable to find " + realmResourceName);
LoginService loginService = new HashLoginService("MyRealm",
realmProps.toExternalForm());
server.addBean(loginService);
// A security handler is a jetty handler that secures content behind a
// particular portion of a url space. The ConstraintSecurityHandler is a
// more specialized handler that allows matching of urls to different
// constraints. The server sets this as the first handler in the chain,
// effectively applying these constraints to all subsequent handlers in
// the chain.
ConstraintSecurityHandler security = new ConstraintSecurityHandler();
server.setHandler(security);
// This constraint requires authentication and in addition that an
// authenticated user be a member of a given set of roles for
// authorization purposes.
Constraint constraint = new Constraint();
constraint.setName("auth");
constraint.setAuthenticate(true);
constraint.setRoles(new String[]{"user", "admin"});
// Binds a url pattern with the previously created constraint. The roles
// for this constraint mapping are mined from the Constraint itself
// although methods exist to declare and bind roles separately as well.
ConstraintMapping mapping = new ConstraintMapping();
mapping.setPathSpec("/*");
mapping.setConstraint(constraint);
// First you see the constraint mapping being applied to the handler as
// a singleton list, however you can passing in as many security
// constraint mappings as you like so long as they follow the mapping
// requirements of the servlet api. Next we set a BasicAuthenticator
// instance which is the object that actually checks the credentials
// followed by the LoginService which is the store of known users, etc.
security.setConstraintMappings(Collections.singletonList(mapping));
security.setAuthenticator(new BasicAuthenticator());
security.setLoginService(loginService);
// The Hello Handler is the handler we are securing so we create one,
// and then set it as the handler on the
// security handler to complain the simple handler chain.
HelloHandler hh = new HelloHandler();
// chain the hello handler into the security handler
security.setHandler(hh);
return server;
}
public static void main(String[] args) throws Exception
{
int port = ExampleUtil.getPort(args, "jetty.http.port", 8080);
Server server = createServer(port);
// Start things up!
server.start();
// The use of server.join() the will make the current thread join and
// wait until the server is done executing.
server.join();
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-form-size">Limiting Form Content</h3>
<div class="paragraph">
<p>Form content sent to the server is processed by Jetty into a map of parameters to be used by the web application.
This can be vulnerable to denial of service (DOS) attacks since significant memory and CPU can be consumed if a malicious clients sends very large form content or large number of form keys.
Thus Jetty limits the amount of data and keys that can be in a form posted to Jetty.</p>
</div>
<div class="paragraph">
<p>The default maximum size Jetty permits is 200000 bytes and 1000 keys.
You can change this default for a particular webapp or for all webapps on a particular Server instance.</p>
</div>
<div class="sect3">
<h4>Configuring Form Limits for a Webapp</h4>
<div class="paragraph">
<p>To configure the form limits for a single web application, the context handler (or webappContext) instance must be configured using the following methods:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">ContextHandler.setMaxFormContentSize(int maxSizeInBytes);
ContextHandler.setMaxFormKeys(int formKeys);</code></pre>
</div>
</div>
<div class="paragraph">
<p>These methods may be called directly when embedding Jetty, but more commonly are configured from a context XML file or WEB-INF/jetty-web.xml file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
...
&lt;Set name="maxFormContentSize"&gt;200000&lt;/Set&gt;
&lt;Set name="maxFormKeys"&gt;200&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>Configuring Form Limits for the Server</h4>
<div class="paragraph">
<p>If a context does not have specific form limits configured, then the server attributes are inspected to see if a server wide limit has been set on the size or keys.
The following XML shows how these attributes can be set in <code>jetty.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;configure class="org.eclipse.jetty.server.Server"&gt;
...
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;org.eclipse.jetty.server.Request.maxFormContentSize&lt;/Arg&gt;
&lt;Arg&gt;100000&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="setAttribute"&gt;
&lt;Arg&gt;org.eclipse.jetty.server.Request.maxFormKeys&lt;/Arg&gt;
&lt;Arg&gt;2000&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/configure&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="serving-aliased-files">Aliased Files and Symbolic links</h3>
<div class="paragraph">
<p>Web applications will often serve static content from the file system provided by the operating system running underneath the JVM.
However, because file systems often implement multiple aliased names for the same file, then security constraints and other servlet URI space mappings may inadvertently be bypassed by aliases.</p>
</div>
<div class="paragraph">
<p>A key example of this is case insensitivity and 8.3 filenames implemented by the Windows file system.
If a file within a web application called <code>/mysecretfile.txt</code> is protected by a security constraint on the URI <code>/mysecretfile.txt</code>, then a request to <code>/MySecretFile.TXT</code> will not match the URI constraint because URIs are case sensitive, but the Windows file system will report that a file does exist at that name and it will be served despite the security constraint.
Less well known than case insensitivity is that Windows files systems also support <a href="http://en.wikipedia.org/wiki/8.3_filename">8.3 filenames</a> for compatibility with legacy programs.
Thus a request to a URI like <code>/MYSECR~1.TXT</code> will again not match the security constraint, but will be reported as an existing file by the file system and served.</p>
</div>
<div class="paragraph">
<p>There are many examples of aliases, not just on Windows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>NTFS Alternate stream names like <code>c:\test\file.txt::$DATA:name</code></p>
</li>
<li>
<p>OpenVMS support file versionig so that <code>/mysecret.txt;N</code> refers to version N of <code>/mysecret.txt</code> and is essentially an alias.</p>
</li>
<li>
<p>The clearcase software configuration management system provides a file system where <code>@@</code> in a file name is an alias to a specific version.</p>
</li>
<li>
<p>The Unix files system supports <code>/./foo.txt</code> as and alias for <code>/foo.txt</code></p>
</li>
<li>
<p>Many JVM implementations incorrectly assume the null character is a string terminator, so that a file name resulting from <code>/foobar.txt%00</code> is an alias for <code>/foobar.txt</code></p>
</li>
<li>
<p>Unix symbolic links and hard links are a form of aliases that allow the same file or directory to have multiple names.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In addition, it is not just URI security constraints that can be bypassed. For example the mapping of the URI pattern <code>*.jsp</code> to the JSP
Servlet may be bypassed by an a request to an alias like <code>/foobar.jsp%00</code>, thus rather than execute the JSP, the source code of the JSP is returned by the file system.</p>
</div>
<div class="sect3">
<h4>Good Security Practise</h4>
<div class="paragraph">
<p>Part of the problem with aliases is that the standard web application security model is to allow all requests except the ones that are specifically denied by security constraints.
A best practice for security is to deny all requests and to permit only those that are specifically identified as allowable.
While it is possible to design web application security constraints in this style, it can be difficult in all circumstances and it is not the default. T
hus it is important for Jetty to be able to detect and deny requests to aliased static content.</p>
</div>
</div>
<div class="sect3">
<h4 id="file-alias-detection">Alias detection</h4>
<div class="paragraph">
<p>It is impossible for Jetty to know of all the aliases that may be implemented by the file system running beneath it, thus it does not attempt to make any specific checks for any know aliases.
Instead Jetty detects aliases by using the canonical path of a file.
If a file resource handled by jetty has a canonical name that differs from the name used to request the resource, then Jetty determines that the resource is an aliased request and it will not be returned by the <code>ServletContext.getResource(String)</code> method (or similar) and thus will not be served as static content nor used as the basis of a JSP.</p>
</div>
<div class="paragraph">
<p>This if Jetty is running on a Windows operating system, then a file called <code>/MySecret.TXT</code> will have a canonical name that exactly matches that case.
So while a request to <code>/mysecret.txt</code> or <code>/MYSECR~1.TXT</code> will result in a File Resource that matches the file, the different canonical name will indicate that those requests are aliases and they will not be served as static content and instead a 404 response returned.</p>
</div>
<div class="paragraph">
<p>Unfortunately this approach denies all aliases, including symbolic links, which can be useful in assembling complex web applications.</p>
</div>
</div>
<div class="sect3">
<h4 id="file-alias-serving">Serving Aliases and Symbolic Links</h4>
<div class="paragraph">
<p>Not all aliases are bad nor should be seen as attempts to subvert security constraints.
Specifically, symbolic links can be very useful when assembling complex web applications.
As such, Jetty contexts support an extensible <code>AliasCheck</code> mechanism to allow aliases resources to be inspected and conditionally served.
In this way, "good" aliases can be detected and served.
Jetty provides several utility implementations of the <code>AliasCheck</code> interface as nested classes with <code>ContextHandler</code>:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">ApproveAliases</dt>
<dd>
<p>Approve all aliases (<strong>Use with caution!</strong>).</p>
</dd>
<dt class="hdlist1">AllowSymLinkAliasChecker</dt>
<dd>
<p>Approve Aliases using the java-7 <code>Files.readSymbolicLink(path)</code> and <code>Path.toRealPath(&#8230;&#8203;)</code> APIs to check that aliases are valid symbolic links.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
By default, Jetty serves aliased files for implementations running on UNIX as Contexts are created with both the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/AllowSymLinkAliasChecker.html"><code>AllowSymLinkAliasChecker</code></a> and <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.ApproveNonExistentDirectoryAliases.html"><code>ApproveNonExistentDirectoryAliases</code></a> alias checkers.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>An application is free to implement its own Alias checking.
Alias Checkers can be installed in a context via the following XML used in a context deployer file or <code>WEB-INF/jetty-web.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;!-- Allow symbolic links --&gt;
&lt;Call name="addAliasCheck"&gt;
&lt;Arg&gt;&lt;New class="org.eclipse.jetty.server.handler.AllowSymLinkAliasChecker"/&gt;&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-security-secure-passwords">Secure Password Obfuscation</h3>
<div class="paragraph">
<p>There are many places where you might want to use and store a password, for example for the SSL connectors and user passwords in realms.</p>
</div>
<div class="paragraph">
<p>Passwords can be stored in clear text, obfuscated, checksummed or encrypted in order of increasing security.
The choice of method to secure a password depends on where you are using the password.
In some cases, such as keystore passwords and <code>DIGEST</code> authentication, the system must retrieve the original password, which requires the obfuscation method.
The drawback of the obfuscation algorithm is that it protects passwords <strong>from casual viewing only.</strong></p>
</div>
<div class="paragraph">
<p>When the stored password is compared to one a user enters, the handling code can apply the same algorithm that secures the stored password to the user input and compare results, making password authentication more secure.</p>
</div>
<div class="paragraph">
<p>The class <code>org.eclipse.jetty.util.security.Password</code> can be used to generate all varieties of passwords.</p>
</div>
<div class="paragraph">
<p>Run it without arguments to see usage instructions:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -cp lib/jetty-util-10.0.0-SNAPSHOT.jar org.eclipse.jetty.util.security.Password
Usage - java org.eclipse.jetty.util.security.Password [&lt;user&gt;] &lt;password&gt;
If the password is ?, the user will be prompted for the password</code></pre>
</div>
</div>
<div class="paragraph">
<p>For example, to generate a secured version of the password <code>password</code> for the user <code>username</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -cp ../lib/jetty-util-10.0.0-SNAPSHOT.jar org.eclipse.jetty.util.security.Password username password
2017-12-13 11:19:27.928:INFO::main: Logging initialized @95ms to org.eclipse.jetty.util.log.StdErrLog
password
OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v
MD5:5f4dcc3b5aa765d61d8327deb882cf99
CRYPT:usjRS48E8ZADM</code></pre>
</div>
</div>
<div class="paragraph">
<p>If using a external tool to create/verify the MD5 hash (such as <code>md5sum</code> or <code>md5</code>), be sure to verify a carriage return (CR) or new line is not added.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">//With a CR included
$ echo password | md5sum
286755fad04869ca523320acce0dc6a4 *-
//Using the `-n` option to exclude a new line from being added.
$ echo -n password | md5sum
5f4dcc3b5aa765d61d8327deb882cf99 *-</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
When using the <code>DIGEST</code> method in tandem with an MD5 hash, you must hash the entire <code>user:realm:password</code> string or you will encounter issues with authenticating.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -cp ../lib/jetty-util-10.0.0-SNAPSHOT.jar org.eclipse.jetty.util.security.Password username username:realm:password
2017-12-13 11:34:33.263:INFO::main: Logging initialized @97ms to org.eclipse.jetty.util.log.StdErrLog
username:realm:password
OBF:1w281yf41v1x1z7e1xmi1v1p1tvv1v901c3j1x8k1ugo1ri71uh21x8a1c3j1v9m1tv71v2p1xms1z7o1v2h1yf21w1a
MD5:66999343281b2624585fd58cc9d36dfc
CRYPT:usulxZfApLefk
$ echo -n username:realm:password | md5sum
66999343281b2624585fd58cc9d36dfc *-</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can now cut and paste whichever secure version you choose into your configuration file or Java code.</p>
</div>
<div class="paragraph">
<p>For example, the last line below shows how you would implement the encrypted password generated above into the properties file for a <code>LoginService</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-bash" data-lang="bash">admin: CRYPT:ad1ks..kc.1Ug,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq
guest: guest,read-only
me:CRYPT:me/ks90E221EY</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Don&#8217;t forget to also copy the OBF:, MD5: or CRYPT: prefix on the generated password. It will not be usable by Jetty without it.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>You can also use obfuscated passwords in Jetty xml files where a plain text password is required.
Here&#8217;s an example setting the password for a JDBC Datasource with obfuscation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.jolbox.bonecp.BoneCPDataSource"&gt;
&lt;Set name="driverClass"&gt;com.mysql.jdbc.Driver&lt;/Set&gt;
&lt;Set name="jdbcUrl"&gt;jdbc:mysql://localhost:3306/foo&lt;/Set&gt;
&lt;Set name="username"&gt;dbuser&lt;/Set&gt;
&lt;Set name="password"&gt;
&lt;Call class="org.eclipse.jetty.util.security.Password" name="deobfuscate"&gt;
&lt;Arg&gt;OBF:1ri71v1r1v2n1ri71shq1ri71shs1ri71v1r1v2n1ri7&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Set&gt;
&lt;Set name="minConnectionsPerPartition"&gt;5&lt;/Set&gt;
&lt;Set name="maxConnectionsPerPartition"&gt;50&lt;/Set&gt;
&lt;Set name="acquireIncrement"&gt;5&lt;/Set&gt;
&lt;Set name="idleConnectionTestPeriod"&gt;30&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="setting-port80-access">Setting Port 80 Access for a Non-Root User</h3>
<div class="paragraph">
<p>On Unix-based systems, port 80 is protected; typically only the superuser <code>root</code> can open it. For security reasons, it is not desirable to run the server as <code>root</code>.
This page presents several options to access port 80 as a non-root user, including using <code>ipchains</code>, <code>iptables</code>, Jetty&#8217;s SetUID feature, <code>xinetd</code>, and the Solaris 10 User Rights Management Framework.</p>
</div>
<div class="sect3">
<h4 id="using-ipchains">Using ipchains</h4>
<div class="paragraph">
<p>On some Linux systems you can use the <em>ipchains REDIRECT</em> mechanism to redirect from one port to another inside the kernel (if <code>ipchains</code> is not available, then <code>iptables</code> usually is):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># /sbin/ipchains -I input --proto TCP --dport 80 -j REDIRECT 8080</code></pre>
</div>
</div>
<div class="paragraph">
<p>This command instructs the system as follows: "Insert into the kernel&#8217;s packet filtering the following as the first rule to check on incoming packets: if the protocol is TCP and the destination port is 80, redirect the packet to port 8080".
Be aware that your kernel must be compiled with support for <code>ipchains</code> (virtually all stock kernels are).
You must also have the <code>ipchains</code> command-line utility installed.
You can run this command at any time, preferably just once, since it inserts another copy of the rule every time you run it.</p>
</div>
</div>
<div class="sect3">
<h4 id="using-iptables">Using iptables</h4>
<div class="paragraph">
<p>On many Linux systems you can use the <code>iptables</code> REDIRECT mechanism to redirect from one port to another inside the kernel (if <code>iptables</code> is not available, then usually <code>ipchains</code> is).</p>
</div>
<div class="paragraph">
<p>You need to add something like the following to the startup scripts or your firewall rules:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># /sbin/iptables -t nat -I PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 8080</code></pre>
</div>
</div>
<div class="paragraph">
<p>The underlying model of <code>iptables</code> is different from <code>ipchains</code>, so the forwarding normally happens only to packets originating outside of the server itself.
You also need to allow incoming packets to port 8080 if you use <code>iptables</code> as a local firewall.</p>
</div>
<div class="paragraph">
<p>Be careful to place rules like this one early in your <em>input</em> chain.
Such rules must precede any rule that accepts the packet, otherwise the redirection won&#8217;t occur.
You can insert as many rules as required if your server needs to listen on multiple ports, as for HTTPS.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-jetty-setuid-feature">Configuring Jetty&#8217;s SetUID Feature</h4>
<div class="paragraph">
<p><a href="http://en.wikipedia.org/wiki/Setuid">SetUID</a> is a technique that uses Unix-like file system access rights to allow users to run an executable that would otherwise require higher privileges.</p>
</div>
<div class="paragraph">
<p>Jetty&#8217;s <code>SetUID</code> module allows you to run Jetty as a normal user even when you need to run Jetty on port 80 or 443.</p>
</div>
<div class="paragraph">
<p>To use it with the Jetty distribution:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Ensure that you have the <code>http.mod</code> (and <a href="#quickstart-starting-https">https.mod</a> if you are using SSL) <a href="#startup-modules">modules enabled</a> for the <a href="#creating-jetty-base">base</a> you are using.
The <code>http.mod</code> is enabled by default in the distribution, while the <a href="#quickstart-starting-https">https.mod</a> is only enabled in the <a href="#demo-webapps-base">demo-base</a> directory.</p>
</li>
<li>
<p>Ensure that you have <a href="#quickstart-changing-jetty-port">changed the http port</a> to 80 (and <a href="#quickstart-changing-https-port">changed the https port</a> to 443 if you are using SSL).</p>
</li>
<li>
<p>Enable the <code>setuid.mod</code> module:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># java -jar start.jar --add-to-start=setuid</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The --add-to-start command will enable the setuid module for this and all subsequent executions of jetty.
There are other ways to enable the module, such as for a single execution.
For more information on the alternatives see the section on <a href="#startup-modules">Managing Startup Modules</a>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</li>
<li>
<p>Edit the configuration for the <code>setuid</code> module to substitute the <code>userid</code> and <code>groupid</code> of the user to switch to after starting.
If your server instance has a <code>${jetty.base/start.d}</code> directory, this configuration is in the <code>start.d/setuid.ini</code> file instead.
Otherwise. this configuration is in the <code>${jetty.base}start.ini</code> file.</p>
<div class="literalblock">
<div class="content">
<pre>Below are the lines to configure:</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-text" data-lang="text">jetty.startServerAsPrivileged=false
jetty.username=foo
jetty.groupname=bar
jetty.umask=002</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
As well as opening the connectors as <code>root</code>, you can also have Jetty start the Server as <code>root</code> before changing to the non-<code>root</code> user.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</li>
<li>
<p>A native code library is required to perform user switching.
This code is hosted as part of the Jetty ToolChain project and is released independently from Jetty itself.
You can find the source code <a href="https://github.com/eclipsejetty.toolchain">here</a> in the <a href="https://github.com/eclipse/jetty.toolchain/jetty-setuid">jetty-setuid</a> project.
Build it locally, which will produce a native library appropriate for the operating system:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># mvn clean install</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you built on a linux machine you will find the native library in <code>jetty-setuid/libsetuid-linux/target/libsetuid-linux.so</code>.
If you built on a different operating system you will find the library in a different subdirectory, with the name containing the name of the operating system.
You may want copy this file into your Jetty distribution&#8217;s lib directory.</p>
</div>
</li>
<li>
<p>Start Jetty as the <code>root</code> user in your base directory, providing the location of the native library to Java.
Below is an example of how to do it from the command line, assuming you are in the <a href="#demo-webapps-base">demo-base</a> directory:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># sudo java -Djava.library.path=libsetuid-linux -jar $JETTY_HOME/start.jar</code></pre>
</div>
</div>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4 id="using-solaris10-user-rights-management-framework">Using the Solaris 10 User Rights Management Framework</h4>
<div class="paragraph">
<p>Solaris 10 provides a User Rights Management framework that can permit users and processes superuser-like abilities:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">usermod -K defaultpriv=basic,net_privaddr myself</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now the <code>myself</code> user can bind to port 80.</p>
</div>
<div class="paragraph">
<p>Refer to the <a href="http://docs.oracle.com/cd/E23823_01/html/816-4557/prbactm-1.html#scrolltoc">Solaris 10</a> and <a href="http://docs.oracle.com/cd/E23824_01/html/821-1456/prbactm-1.html#scrolltoc">Solaris 11 Security Services documentation</a> for more information.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jaas-support">JAAS Support</h3>
<div class="paragraph">
<p>JAAS implements a Java version of the standard Pluggable Authentication Module (PAM) framework.</p>
</div>
<div class="paragraph">
<p>JAAS can be used for two purposes:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>for authentication of users, to reliably and securely determine who is currently executing Java code, regardless of whether the code is running as an application, an applet, a bean, or a servlet</p>
</li>
<li>
<p>for authorization of users to ensure they have the access control rights (permissions) required to do the actions performed</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>JAAS authentication is performed in a pluggable fashion.
This permits applications to remain independent from underlying authentication technologies.
New or updated authentication technologies can be plugged under an application without requiring modifications to the application itself.
Applications enable the authentication process by instantiating a <code>LoginContext</code> object, which in turn references a configuration to determine the authentication technology(ies), or <code>LoginModule</code>(s), to be used in performing the authentication.
Typical <code>LoginModules</code> may prompt for and verify a username and password.
Others may read and verify a voice or fingerprint sample.</p>
</div>
<div class="paragraph">
<p>See Java Authentication and Authorization Service (JAAS) <a href="http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASRefGuide.html">Reference Guide</a> for more information about JAAS.</p>
</div>
<div class="sect3">
<h4 id="jetty-jaas">Jetty and JAAS</h4>
<div class="paragraph">
<p>Many application servers support JAAS as a means of bringing greater flexibility to the declarative security models of the J2EE (now known as the JavaEE) <a href="http://java.sun.com/javaee/index.jsp">specification</a>.
Jetty support for JAAS provides greater alternatives for servlet security, and increases the portability of web applications.</p>
</div>
<div class="paragraph">
<p>The JAAS support aims to dictate as little as possible whilst providing a sufficiently flexible infrastructure to allow users to drop in their
own custom <a href="http://java.sun.com/j2se/1.4.2/docs/guide/security/jaas/JAASLMDevGuide.html">LoginModules</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="jaas-configuration">Configuration</h4>
<div class="paragraph">
<p>Using JAAS with Jetty is very simply a matter of declaring a <code>org.eclipse.jetty.jaas.JAASLoginService</code>, creating a JAAS login module configuration file and specifying it on the Jetty run line.
Let&#8217;s look at an example.</p>
</div>
<div class="sect4">
<h5>Step 1</h5>
<div class="paragraph">
<p>Configure a Jetty <code>org.eclipse.jetty.jaas.JAASLoginService</code> to match the <code>&lt;realm-name&gt;</code> in your <code>web.xml</code> file. For example, if the <code>web.xml</code> contains a realm called "Test JAAS Realm" like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;login-config&gt;
&lt;auth-method&gt;FORM&lt;/auth-method&gt;
&lt;realm-name&gt;Test JAAS Realm&lt;/realm-name&gt;
&lt;form-login-config&gt;
&lt;form-login-page&gt;/login/login&lt;/form-login-page&gt;
&lt;form-error-page&gt;/login/error&lt;/form-error-page&gt;
&lt;/form-login-config&gt;
&lt;/login-config&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>then you need to create a <code>JAASLoginService</code> with the matching realm name of "Test JAAS Realm":</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.jaas.JAASLoginService"&gt;
&lt;Set name="Name"&gt;Test JAAS Realm&lt;/Set&gt;
&lt;Set name="LoginModuleName"&gt;xyz&lt;/Set&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>LoginModuleName</code> must match the name of your LoginModule as declared in your login module configuration file (see <a href="#jaas-step-2">Step 2</a>).</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
The name of the realm-name that you declare in <code>web.xml</code> must match <strong>exactly</strong> the <code>Name</code> field of your <code>JAASLoginService</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>You can declare your <code>JAASLoginService</code> in a couple of different ways:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>If you have more than one webapp that you would like to use the same security infrastructure, then you can declare your <code>JAASLoginService</code> in a top-level Jetty xml file as a bean that is added to the <code>org.eclipse.jetty.server.Server</code>.
An example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.jaas.JAASLoginService"&gt;
&lt;Set name="name"&gt;Test JAAS Realm&lt;/Set&gt;
&lt;Set name="LoginModuleName"&gt;xyz&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</li>
<li>
<p>Alternatively, you can use a <code>JAASLoginService</code> with just a specific webapp by creating a <a href="#deployable-descriptor-file">context xml</a> file for the webapp, and specifying the <code>JAASLoginService</code> in it:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="securityHandler"&gt;
&lt;New class="org.eclipse.jetty.security.ConstraintSecurityHandler"&gt;
&lt;Set name="loginService"&gt;
&lt;New class="org.eclipse.jetty.jaas.JAASLoginService"&gt;
&lt;Set name="name"&gt;Test JAAS Realm&lt;/Set&gt;
&lt;Set name="loginModuleName"&gt;xyz&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</li>
</ol>
</div>
</div>
<div class="sect4">
<h5 id="jaas-step-2">Step 2</h5>
<div class="paragraph">
<p>Set up your <code>LoginModule</code> in a configuration file, following the <a href="https://docs.oracle.com/javase/7/docs/api/javax/security/auth/login/Configuration.html">syntax rules</a> :</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">xyz {
com.acme.SomeLoginModule required debug=true;
};</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock caution">
<table>
<tr>
<td class="icon">
<i class="fa icon-caution" title="Caution"></i>
</td>
<td class="content">
It is imperative that the application name on the first line is <strong>exactly</strong> the same as the <code>LoginModuleName</code> of your <code>JAASLoginService</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>You may find it convenient to name this configuration file as <code>etc/login.conf</code> because, as we will see below, some of the wiring up for JAAS has been done for you.</p>
</div>
</div>
<div class="sect4">
<h5>Step 3</h5>
<div class="paragraph">
<p>You now need to invoke Jetty with support for JAAS.
There are 2 aspects to this:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>adding JAAS-related jars to the Jetty container classpath</p>
</li>
<li>
<p>setting the System property <code>java.security.auth.login.config</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To accomplish the above, use the Jetty <a href="#startup-overview">startup</a> <a href="#startup-modules">modules mechanism</a> to add the JAAS <a href="#startup-modules">module</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar start.jar --add-to-start=jaas</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The top level of the distribution does not have the JAAS module enabled by default.
However, there are several <a href="#demo-webapps-base">demo webapps</a> - including a JAAS webapp - available in the <code>demo-base</code> directory of the distribution which has pre-enabled the JAAS module.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Now you will have a file named <code>start.d/jaas.ini</code>, which contains:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">--module=jaas
jaas.login.conf=etc/login.conf</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>jaas.login.conf</code> property refers to the location of your <code>LoginModule</code> configuration file that you established in <a href="#jaas-step-2">Step 2</a>.
If you called it <code>etc/login.conf</code>, then your work is done. Otherwise, change the value of the <code>jaas.login.conf</code> property to be the location of your LoginModule configuration file.
Jetty will automatically use this property to set the value of the System property <code>java.security.auth.login.config.</code></p>
</div>
</div>
</div>
<div class="sect3">
<h4>A Closer Look at JAASLoginService</h4>
<div class="paragraph">
<p>To allow the greatest degree of flexibility in using JAAS with web applications, the <code>JAASLoginService</code> supports a couple of configuration options.
Note that you don&#8217;t ordinarily need to set these explicitly, as Jetty has defaults which will work in 99% of cases.
However, should you need to, you can configure:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>a CallbackHandler (Default: <code>org.eclipse.jetty.jaas.callback.DefaultCallbackHandler</code>)</p>
</li>
<li>
<p>a list of classnames for the Principal implementation that equate to a user role (Default: <code>org.eclipse.jetty.jaas.JAASRole</code>)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Here&#8217;s an example of setting each of these (to their default values):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.jaas.JAASLoginService"&gt;
&lt;Set name="Name"&gt;Test JAAS Realm&lt;/Set&gt;
&lt;Set name="LoginModuleName"&gt;xyz&lt;/Set&gt;
&lt;Set name="CallbackHandlerClass"&gt;
org.eclipse.jetty.jaas.callback.DefaultCallbackHandler
&lt;/Set&gt;
&lt;Set name="roleClassNames"&gt;
&lt;Array type="java.lang.String"&gt;
&lt;Item&gt;org.eclipse.jetty.jaas.JAASRole&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="sect4">
<h5>CallbackHandler</h5>
<div class="paragraph">
<p>A CallbackHandler is responsible for interfacing with the user to obtain usernames and credentials to be authenticated.</p>
</div>
<div class="paragraph">
<p>Jetty ships with the <code>org.eclipse.jetty.jaas.DefaultCallbackHandler</code> which interfaces the information contained in the request to the Callbacks that are requested by <code>LoginModules</code>.
You can replace this default with your own implementation if you have specific requirements not covered by the default.</p>
</div>
</div>
<div class="sect4">
<h5>Role Principal Implementation Class</h5>
<div class="paragraph">
<p>When <code>LoginModules</code> authenticate a user, they usually also gather all of the roles that a user has and place them inside the JAAS Subject.
As <code>LoginModules</code> are free to use their own implementation of the JAAS Principal to put into the Subject, Jetty needs to know which Principals represent the user and which represent his/her roles when performing authorization checks on <code>&lt;security-constraint&gt;</code>. The example <code>LoginModules</code> that ship with Jetty all use the <code>org.eclipse.jetty.jaas.JAASRole</code> class. However, if you have plugged in other <code>LoginModules</code>, you must configure the classnames of their role Principal implementations.</p>
</div>
</div>
<div class="sect4">
<h5>Sample LoginModules</h5>
<div class="ulist">
<ul>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/jaas/spi/JDBCLoginModule.html"><code>org.eclipse.jetty.jaas.spi.JDBCLoginModule</code></a></p>
</li>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/jaas/spi/PropertyFileLoginModule.html"><code>org.eclipse.jetty.jaas.spi.PropertyFileLoginModule</code></a></p>
</li>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/jaas/spi/DataSourceLoginModule.html"><code>org.eclipse.jetty.jaas.spi.DataSourceLoginModule</code></a></p>
</li>
<li>
<p><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/jaas/spi/LdapLoginModule.html"><code>org.eclipse.jetty.jaas.ldap.LdapLoginModule</code></a></p>
</li>
</ul>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Passwords can be stored in clear text, obfuscated or checksummed.
The class <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/security/Password.html"><code>org.eclipse.jetty.util.security.Password</code></a> should be used to generate all varieties of passwords,the output from which can be put in to property files or entered into database tables.
See more on this under the Configuration section on <a href="#configuring-security-secure-passwords">securing passwords</a>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect4">
<h5>JDBCLoginModule</h5>
<div class="paragraph">
<p>The <code>JDBCLoginModule</code> stores user passwords and roles in a database that are accessed via JDBC calls.
You can configure the JDBC connection information, as well as the names of the table and columns storing the username and credential, and the names of the table and columns storing the roles.</p>
</div>
<div class="paragraph">
<p>Here is an example login module configuration file entry for it using an HSQLDB driver:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">jdbc {
org.eclipse.jetty.jaas.spi.JDBCLoginModule required
debug="true"
dbUrl="jdbc:hsqldb:."
dbUserName="sa"
dbDriver="org.hsqldb.jdbcDriver"
userTable="myusers"
userField="myuser"
credentialField="mypassword"
userRoleTable="myuserroles"
userRoleUserField="myuser"
userRoleRoleField="myrole";
};</code></pre>
</div>
</div>
<div class="paragraph">
<p>There is no particular schema required for the database tables storing the authentication and role information.
The properties <code>userTable</code>, <code>userField</code>, <code>credentialField</code>, <code>userRoleTable</code>, <code>userRoleUserField</code>, <code>userRoleRoleField</code> configure the names of the tables and the columns within them that are used to format the following queries:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-sql" data-lang="sql"> select &lt;credentialField&gt; from &lt;userTable&gt;
where &lt;userField&gt; =?
select &lt;userRoleRoleField&gt; from &lt;userRoleTable&gt;
where &lt;userRoleUserField&gt; =?</code></pre>
</div>
</div>
<div class="paragraph">
<p>Credential and role information is lazily read from the database when a previously unauthenticated user requests authentication.
Note that this information is <em>only</em> cached for the length of the authenticated session.
When the user logs out or the session expires, the information is flushed from memory.</p>
</div>
<div class="paragraph">
<p>Note that passwords can be stored in the database in plain text or encoded formats - see the note on "Passwords/Credentials" above.</p>
</div>
</div>
<div class="sect4">
<h5>DataSourceLoginModule</h5>
<div class="paragraph">
<p>Similar to the <code>JDBCLoginModule</code>, but this <code>LoginModule</code> uses a <code>DataSource</code> to connect to the database instead of a JDBC driver. The <code>DataSource</code> is obtained by performing a JNDI lookup on <code>java:comp/env/${dnJNDIName}</code>.</p>
</div>
<div class="paragraph">
<p>A sample login module configuration using this method:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">ds {
org.eclipse.jetty.jaas.spi.DataSourceLoginModule required
debug="true"
dbJNDIName="ds"
userTable="myusers"
userField="myuser"
credentialField="mypassword"
userRoleTable="myuserroles"
userRoleUserField="myuser"
userRoleRoleField="myrole";
};</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>PropertyFileLoginModule</h5>
<div class="paragraph">
<p>With this login module implementation, the authentication and role information is read from a property file.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">props {
org.eclipse.jetty.jaas.spi.PropertyFileLoginModule required
debug="true"
file="/somewhere/somefile.props";
};</code></pre>
</div>
</div>
<div class="paragraph">
<p>The file parameter is the location of a properties file of the same format as the <code>etc/realm.properties</code> example file.
The format is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-text" data-lang="text">&lt;username&gt;: &lt;password&gt;[,&lt;rolename&gt; ...]</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">fred: OBF:1xmk1w261u9r1w1c1xmq,user,admin
harry: changeme,user,developer
tom: MD5:164c88b302622e17050af52c89945d44,user
dick: CRYPT:adpexzg3FUZAk,admin</code></pre>
</div>
</div>
<div class="paragraph">
<p>The contents of the file are fully read in and cached in memory the first time a user requests authentication.</p>
</div>
</div>
<div class="sect4">
<h5>LdapLoginModule</h5>
<div class="paragraph">
<p>Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">ldaploginmodule {
org.eclipse.jetty.jaas.spi.LdapLoginModule required
debug="true"
contextFactory="com.sun.jndi.ldap.LdapCtxFactory"
hostname="ldap.example.com"
port="389"
bindDn="cn=Directory Manager"
bindPassword="directory"
authenticationMethod="simple"
forceBindingLogin="false"
userBaseDn="ou=people,dc=alcatel"
userRdnAttribute="uid"
userIdAttribute="uid"
userPasswordAttribute="userPassword"
userObjectClass="inetOrgPerson"
roleBaseDn="ou=groups,dc=example,dc=com"
roleNameAttribute="cn"
roleMemberAttribute="uniqueMember"
roleObjectClass="groupOfUniqueNames";
};</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Writing your Own LoginModule</h4>
<div class="paragraph">
<p>If you want to implement your own custom <code>LoginModule</code>, there are two classes to be familiar with: <code>org.eclipse.jetty.jaas.spi.AbstractLoginModule</code> and <code>org.eclipse.jetty.jaas.spi.UserInfo</code>.</p>
</div>
<div class="paragraph">
<p>The <code>org.eclipse.jetty.jaas.spi.AbstractLoginModule</code> implements all of the <code>javax.security.auth.spi.LoginModule</code> methods.
All you need to do is to implement the <code>getUserInfo</code> method to return a <code>org.eclipse.jetty.jaas.UserInfo</code> instance which encapsulates the username, password and role names (note: as <code>java.lang.Strings</code>) for a user.</p>
</div>
<div class="paragraph">
<p>The <code>AbstractLoginModule</code> does not support any caching, so if you want to cache UserInfo (eg as does the <code>org.eclipse.jetty.jaas.spi.PropertyFileLoginModule</code>) then you must provide this yourself.</p>
</div>
</div>
<div class="sect3">
<h4>Other Goodies</h4>
<div class="sect4">
<h5>ServletRequestCallback</h5>
<div class="paragraph">
<p>This callback gives you access to the ServletRequest that is involved in the authentication, and thus to other features like the current Session. This callback can be configured in your custom LoginModule implementation. Note that none of the LoginModule implementations provided with Jetty currently use this callback.</p>
</div>
</div>
<div class="sect4">
<h5>RequestParameterCallback</h5>
<div class="paragraph">
<p>As all servlet containers intercept and process a form submission with action <code>j_security_check</code>, it is usually not possible to insert any extra input fields onto a login form with which to perform authentication: you may only pass <code>j_username</code> and <code>j_password</code>.
For those rare occasions when this is not good enough, and you require more information from the user in order to authenticate them, you can use the JAAS callback handler <code>org.eclipse.jetty.jaas.callback.RequestParameterCallback</code>.
This callback gives you access to all parameters that were passed in the form submission.
To use it, in the <code>login()</code> method of your custom login module, add the <code>RequestParameterCallback</code> to the list of callback handlers the login module uses, tell it which params you are interested in, and then get the value of the parameter back.
Here is an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class FooLoginModule extends AbstractLoginModule
{
public boolean login()
throws LoginException
{
Callback[] callbacks = new Callback[3];
callbacks[0] = new NameCallback();
callbacks[1] = new ObjectCallback();
//as an example, look for a param named "extrainfo" in the request
//use one RequestParameterCallback() instance for each param you want to access
callbacks[2] = new RequestParameterCallback ();
((RequestParameterCallback)callbacks[2]).setParameterName ("extrainfo");
callbackHandler.handle(callbacks);
String userName = ((NameCallback)callbacks[0]).getName();
Object pwd = ((ObjectCallback)callbacks[1]).getObject();
List paramValues = ((RequestParameterCallback)callbacks[2]).getParameterValues();
//use the userName, pwd and the value(s) of the parameter named "extrainfo" to
//authenticate the user
}
}</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Example JAAS WebApp</h5>
<div class="paragraph">
<p>An example webapp using JAAS can be found in the Jetty GitHub repository:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jaas-webapp">https://github.com/eclipse/jetty.project/tree/master/tests/test-webapps/test-jaas-webapp</a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="spnego-support">SPNEGO Support</h3>
<div class="paragraph">
<p>Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) is a way for users
to be seamlessly authenticated when running on systems that rely on Kerberos
for authentication, such as Windows Active Directory based networks.</p>
</div>
<div class="paragraph">
<p>Jetty supports this type of authentication and authorization through the JDK
(which has been enabled since the later versions of Java 6 and 7).</p>
</div>
<div class="sect3">
<h4>Configuring Jetty and SPNEGO</h4>
<div class="paragraph">
<p>To run with SPNEGO enabled the following command line options are required:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">-Djava.security.krb5.conf=/path/to/krb5.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>For debugging the SPNEGO authentication the following options are helpful:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">-Dorg.eclipse.jetty.LEVEL=debug
-Dsun.security.spnego.debug=true
-Dsun.security.jgss.debug=true
-Dsun.security.krb5.debug=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>SPNEGO authentication must be enabled in the webapp in the following way.
The name of the role will be different for your network.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;security-constraint&gt;
&lt;web-resource-collection&gt;
&lt;web-resource-name&gt;Secure Area&lt;/web-resource-name&gt;
&lt;url-pattern&gt;/secure/me/*&lt;/url-pattern&gt;
&lt;/web-resource-collection&gt;
&lt;auth-constraint&gt;
&lt;!-- this is the domain that the user is a member of --&gt;
&lt;role-name&gt;MORTBAY.ORG&lt;/role-name&gt;
&lt;/auth-constraint&gt;
&lt;/security-constraint&gt;
&lt;login-config&gt;
&lt;auth-method&gt;SPNEGO&lt;/auth-method&gt;
&lt;realm-name&gt;Test Realm&lt;/realm-name&gt;
&lt;!-- optionally to add custom error page --&gt;
&lt;spnego-login-config&gt;
&lt;spnego-error-page&gt;/loginError.html?param=foo&lt;/spnego-error-page&gt;
&lt;/spnego-login-config&gt;
&lt;/login-config&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>A corresponding <code>UserRealm</code> needs to be created either programmatically if
embedded, via the <code>jetty.xml</code> or in a context file for the webapp.</p>
</div>
<div class="paragraph">
<p>This is what the configuration within a context XML file would look like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Get name="securityHandler"&gt;
&lt;Set name="loginService"&gt;
&lt;New class="org.eclipse.jetty.security.ConfigurableSpnegoLoginService"&gt;
&lt;Arg&gt;Test Realm&lt;/Arg&gt;
&lt;Arg&gt;&lt;Ref refid="authorizationService" /&gt;&lt;/Arg&gt;
&lt;Set name="keyTabPath"&gt;&lt;Ref refid="keyTabPath" /&gt;&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Get&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>On the Windows Active Domain Controller run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ setspn -A HTTP/linux.mortbay.org ADUser</code></pre>
</div>
</div>
<div class="paragraph">
<p>To create the keyTab file use the following process:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ ktpass -out c:\dir\krb5.keytab -princ HTTP/linux.mortbay.org@MORTBAY.ORG -mapUser ADUser -mapOp set -pass ADUserPWD -crypto RC4-HMAC-NT -pType KRB5_NT_PRINCIPAL</code></pre>
</div>
</div>
<div class="paragraph">
<p>This step will give you the keyTab file which should then be copied to the
machine running the http server and referenced from the configuration files.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring Firefox</h4>
<div class="paragraph">
<p>The follows steps have been required to inform Firefox that it should use a negotiation dialog to authenticate.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Browse to about:config and agree to the warnings</p>
</li>
<li>
<p>Search through to find the 'network' settings</p>
</li>
<li>
<p>Set <code>network.negotiate-auth.delegation-uris</code> to <a href="http://,https://" class="bare">http://,https://</a></p>
</li>
<li>
<p>Set <code>network.negotiate-auth.trusted-uris</code> to <a href="http://,https://" class="bare">http://,https://</a></p>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4>Configuring Internet Explorer</h4>
<div class="paragraph">
<p>The follows steps have been required to inform Internet Explorer that it should use a negotiation dialog to authenticate.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Tools &#8594; Options &#8594; Security &#8594; Local Intranet &#8594; Sites (everything should be checked here)</p>
</li>
<li>
<p>Tools &#8594; Options &#8594; Security &#8594; Local Intranet &#8594; Sites &#8594; Advanced (add url to server (<code>http://</code> and/or <code>https://</code>&#8201;&#8212;&#8201;use the hostname, not the IP)</p>
</li>
<li>
<p>Tools &#8594; Options &#8594; Security &#8594; Local Intranet &#8594; Sites &#8594; Advanced &#8594; Close</p>
</li>
<li>
<p>Tools &#8594; Options &#8594; Security &#8594; Local Intranet &#8594; Sites &#8594; Ok</p>
</li>
<li>
<p>Tools &#8594; Options &#8594; Advanced &#8594; Security (in the checkbox list)</p>
</li>
<li>
<p>Locate and select <code>Enable Integrated Windows Authentication</code></p>
</li>
<li>
<p>Tools &#8594; Options &#8594; Advanced &#8594; Security &#8594; Ok</p>
</li>
<li>
<p>Close IE then reopen and browse to your SPNEGO protected resource</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>You <strong>must</strong> use hostname and not the IP.
If you use the IP it will default to NTLM authentication.
The following conditions must be true for SPNEGO authentication to work:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>You must be within the Intranet Zone of the network</p>
</li>
<li>
<p>Access the server using a Hostname rather than IP</p>
</li>
<li>
<p>Integrated Windows Authentication in IE is enabled and/or the host is trusted in Firefox</p>
</li>
<li>
<p>The server is not local to the browser; it can&#8217;t be running on localhost</p>
</li>
<li>
<p>The client&#8217;s Kerberos system is authenticated to a domain controller</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="openid-support">OpenID Support</h3>
<div class="sect3">
<h4>External Setup</h4>
<div class="sect4">
<h5>Registering an App with OpenID Provider</h5>
<div class="paragraph">
<p>You must register the app with an OpenID Provider such as <a href="https://developers.google.com/identity/protocols/OpenIDConnect#authenticatingtheuser">Google</a> or <a href="https://images-na.ssl-images-amazon.com/images/G/01/lwa/dev/docs/website-developer-guide.<em>TTH</em>.pdf">Amazon.</a>
This will give you a Client ID and Client Secret.
Once set up you must also register all the possible URI&#8217;s for your webapp with the path <code>/j_security_check</code> so that the OpenId Provider will allow redirection back to the webapp.</p>
</div>
<div class="paragraph">
<p>These may look like</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code><a href="http://localhost:8080/openid-webapp/j_security_check" class="bare">http://localhost:8080/openid-webapp/j_security_check</a></code></p>
</li>
<li>
<p><code><a href="https://example.com/j_security_check" class="bare">https://example.com/j_security_check</a></code></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4>Distribution Configuration</h4>
<div class="sect4">
<h5>OpenID Provider Configuration</h5>
<div class="paragraph">
<p>To enable OpenID support, you first need to activate the <code>openid</code> module in your implementation.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar {JETTY_HOME}/start.jar --add-to-start=openid</code></pre>
</div>
</div>
<div class="paragraph">
<p>To configure OpenID Authentication with Jetty you will need to specify the OpenID Provider&#8217;s issuer identifier (case sensitive URL using the <code>https</code> scheme) and the OAuth 2.0 Client ID and Client Secret.
If the OpenID Provider does not allow metadata discovery you will also need to specify the token endpoint and authorization endpoint of the OpenID Provider.
These can be set as properties in the <code>start.ini</code> or <code>start.d/openid.ini</code> files.</p>
</div>
</div>
<div class="sect4">
<h5>WebApp Specific Configuration in web.xml</h5>
<div class="paragraph">
<p>The <code>web.xml</code> file needs some specific configuration to use OpenID.
There must be a <code>login-config</code> element with an <code>auth-method</code> value of <code>OPENID</code>, and a <code>realm-name</code> value of the exact URL string used to set the OpenID Provider.</p>
</div>
<div class="paragraph">
<p>To set the error page, an init param is set at <code>"org.eclipse.jetty.security.openid.error_page"</code>, its value should be a path relative to the webapp where authentication errors should be redirected.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;login-config&gt;
&lt;auth-method&gt;OPENID&lt;/auth-method&gt;
&lt;realm-name&gt;https://accounts.google.com&lt;/realm-name&gt;
&lt;/login-config&gt;
&lt;context-param&gt;
&lt;param-name&gt;org.eclipse.jetty.security.openid.error_page&lt;/param-name&gt;
&lt;param-value&gt;/error&lt;/param-value&gt;
&lt;/context-param&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Embedded Configuration</h4>
<div class="sect4">
<h5>Define the <code>OpenIdConfiguration</code> for a specific OpenID Provider.</h5>
<div class="paragraph">
<p>If the OpenID Provider allows metadata discovery then you can use.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, CLIENT_ID, CLIENT_SECRET);</code></pre>
</div>
</div>
<div class="paragraph">
<p>Otherwise you can manually enter the necessary information:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">OpenIdConfiguration openIdConfig = new OpenIdConfiguration(ISSUER, TOKEN_ENDPOINT, AUTH_ENDPOINT, CLIENT_ID, CLIENT_SECRET);</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring an <code>OpenIdLoginService</code></h5>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">LoginService loginService = new OpenIdLoginService(openIdConfig);
securityHandler.setLoginService(loginService);</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring an <code>OpenIdAuthenticator</code> with <code>OpenIdConfiguration</code> and Error Page Redirect</h5>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">Authenticator authenticator = new OpenIdAuthenticator(openIdConfig, "/error");
securityHandler.setAuthenticator(authenticator);
servletContextHandler.setSecurityHandler(securityHandler);</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Usage</h5>
<div class="sect5">
<h6>Claims and Access Token</h6>
<div class="paragraph">
<p>Claims about the user can be found using attributes on the session attribute <code>"org.eclipse.jetty.security.openid.claims"</code>, and the full response containing the OAuth 2.0 Access Token can be found with the session attribute <code>"org.eclipse.jetty.security.openid.response"</code>.</p>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">Map&lt;String, Object&gt; claims = (Map)request.getSession().getAttribute("org.eclipse.jetty.security.openid.claims");
String userId = claims.get("sub");
Map&lt;String, Object&gt; response = (Map)request.getSession().getAttribute("org.eclipse.jetty.security.openid.response");
String accessToken = response.get("access_token");</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Scopes</h4>
<div class="paragraph">
<p>The OpenID scope is always used but additional scopes can be requested which can give you additional resources or privileges.
For the Google OpenID Provider it can be useful to request the scopes <code>profile</code> and <code>email</code> which will give you additional user claims.</p>
</div>
<div class="paragraph">
<p>Additional scopes can be requested through the <code>start.ini</code> or <code>start.d/openid.ini</code> files, or with <code>OpenIdConfiguration.addScopes(&#8230;&#8203;);</code> in embedded code.</p>
</div>
</div>
<div class="sect3">
<h4>Roles</h4>
<div class="paragraph">
<p>If security roles are required they can be configured through a wrapped <code>LoginService</code> which is deferred to for role information by the <code>OpenIdLoginService</code>.</p>
</div>
<div class="paragraph">
<p>This can be configured in XML through <code>etc/openid-baseloginservice.xml</code> in the Distribution, or in embedded code using the constructor for the <code>OpenIdLoginService</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">LoginService wrappedLoginService = ...; // Optional LoginService for Roles
LoginService loginService = new OpenIdLoginService(openIdConfig, wrappedLoginService);</code></pre>
</div>
</div>
<div class="paragraph">
<p>When using authorization roles, the setting <code>authenticateNewUsers</code> becomes significant.
If set to <code>true</code> users not found by the wrapped <code>LoginService</code> will still be authenticated but will have no roles.
If set to <code>false</code> those users will be not be allowed to authenticate and are redirected to the error page.
This setting is configured through the property <code>jetty.openid.authenticateNewUsers</code> in the <code>start.ini</code> or <code>start.d/openid.ini</code> file, or with <code>OpenIdLoginService.setAuthenticateNewUsers(&#8230;&#8203;);</code> in embedded code.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="session-management">Session Management</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Sessions are a concept within the Servlet api which allow requests to store and retrieve information across the time a user spends in an application.
Choosing the correct session manager implementation is an important consideration for every application as each can fit and perform optimally in different situations.
If you need a simple in-memory session manager that can persist to disk then session management using the local file system can be a good place to start.
If you need a session manager that can work in a clustered scenario with multiple instances of Jetty, then the JDBC session manager can be an excellent option.
Jetty also offers more niche session managers that leverage backends such as MongoDB, Inifinispan, or even Google&#8217;s Cloud Data Store.</p>
</div>
<div class="sect2">
<h3 id="jetty-sessions-architecture">Session Architecture</h3>
<div class="sect3">
<h4>Session Architecture Hierarchy</h4>
<div class="paragraph">
<p>Each Jetty instance has a singular <code>SessionIdManager</code> to handle all session requests, regardless of clustering technology.
For each context on the server there is one (1) <code>SessionCache</code> which contains all of the Session objects for the given context.
The benefit of the <code>SessionCache</code> is to ensure that simultaneous requests accessing the same Session Id in the same context always operate on the same Session object.
The SessionCache implementation supplied with the Jetty distribution does just that: keeps Session objects in memory so that they can be shared between simultaneous requests.
However, it is possible to provide your own implementation that never shares Session objects should you require it.</p>
</div>
<div class="paragraph">
<p>Where the <code>SessionCache</code> handles Session information, Session data is stored in a <code>SessionDataStore</code> that is specific to the clustering technology being implemented.
There is only one (1) <code>SessionDataStore</code> per <code>SessionCache</code>.</p>
</div>
<div class="paragraph">
<p>Visually the session architecture can be represented like this:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/SessionsHierarchy.png" alt="SessionsHierarchy">
</div>
</div>
</div>
<div class="sect3">
<h4>Configuring Sessions in the Jetty Distribution</h4>
<div class="paragraph">
<p>Configuring session management involves selecting a <a href="#startup-modules">module</a> for the desired type of <a href="#session-configuration-sessioncache">session caching</a> behavior, and a module for the type of session persistence.</p>
</div>
<div class="paragraph">
<p>Jetty provides two different session caches: the <code>DefaultSessionCache</code> which holds sessions in memory, and the <code>NullSessionCache</code> which does not.
There is more information on both of these types of session caching and the circumstances which would lead you to select one or the other in the <a href="#sessions-details">Session Components</a> section, and more information on the configuration options of each in <a href="#session-configuration-sessioncache">the L1 Session Cache</a> section.</p>
</div>
<div class="paragraph">
<p>For session persistence, Jetty provides a number of different implementations from which to choose including <a href="#configuring-sessions-memory">non-persistence</a>, <a href="#configuring-sessions-file-system">local file storage</a>, clustered technologies such as <a href="#configuring-sessions-jdbc">JDBC</a>, <a href="#configuring-sessions-mongo">MongoDB</a>, <a href="#configuring-sessions-infinispan">Inifinispan</a>, <a href="#configuring-sessions-gcloud">Google Cloud Datastore</a>, and <a href="#configuring-sessions-hazelcast">Hazelcast</a>.</p>
</div>
<div class="paragraph">
<p>Depending on your persistence technology, to enhance performance, you may want to use an L2 cache for session data, in which case Jetty provides the <a href="#session-configuration-memcachedsessiondatastore">memcached L2 session data cache</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="sessions-details">Session Components</h3>
<div class="sect3">
<h4>SessionIdManager</h4>
<div class="paragraph">
<p>There is a maximum of one (1) <code>SessionIdManager</code> per Jetty Server instance.
Its purpose is to generate fresh, unique session ids and to coordinate the re-use of session ids amongst co-operating contexts.</p>
</div>
<div class="paragraph">
<p>Unlike in previous versions of Jetty, the <code>SessionIdManager</code> is agnostic with respect to the type of clustering technology chosen.</p>
</div>
<div class="paragraph">
<p>Jetty provides a default implementation - the <code>DefaultSessionIdManager</code> - which should meet the needs of most users.
If you do not explicitly enable one of the session modules or otherwise configure a <code>SessionIdManager</code>, the <code>DefaultSessionIdManager</code> will be used.</p>
</div>
<div class="paragraph">
<p>If the <code>DefaultSessionIdManager</code> does not meet your needs, you can extend the <code>org.eclipse.jetty.server.session.AbstractSessionIdManager</code> or do a fresh implementation of the <code>org.eclipse.jetty.server.session.SessionIdManager</code> interface.</p>
</div>
<div class="paragraph">
<p>See <a href="#session-configuration-housekeeper">Configuring the SessionIdManager and HouseKeeper</a> for details on configuration.</p>
</div>
</div>
<div class="sect3">
<h4>HouseKeeper</h4>
<div class="paragraph">
<p>There is a maximum of one (1) <code>HouseKeeper</code> per <code>SessionIdManager</code>.
Its purpose is to periodically poll the <code>SessionHandlers</code> to clean out expired sessions.</p>
</div>
<div class="paragraph">
<p>By default the <code>HouseKeeper</code> will poll the <code>SessionHandlers</code> every 10 mins to find and delete expired sessions, although this interval is configurable.</p>
</div>
<div class="paragraph">
<p>See <a href="#session-configuration-housekeeper">Configuring the SessionIdManager and HouseKeeper</a> for details on configuration.</p>
</div>
</div>
<div class="sect3">
<h4>SessionCache</h4>
<div class="paragraph">
<p>There is one (1) <code>SessionCache</code> <strong>per context.</strong>
Its purpose is to provide an L1 cache of Session objects.
Having a working set of Session objects in memory allows multiple simultaneous requests for the same session to share the same Session object.</p>
</div>
<div class="paragraph">
<p>Jetty provides two (2) <code>SessionCache</code> implementations: the <code>DefaultSessionCache</code> and the <code>NullSessionCache</code>.
The <code>DefaultSessionCache</code> retains Session objects in memory in a cache and has a number of <a href="#session-configuration-sessioncache">configuration options</a> to control cache behavior.
It is the default that is used if no other <code>SessionCache</code> has been configured.
It is suitable for non-clustered and clustered deployments with a sticky load balancer, as well as clustered deployments with a non-sticky load balancer, with some caveats.</p>
</div>
<div class="paragraph">
<p>The <code>NullSessionCache</code> does not actually cache any objects: each request uses a fresh Session object.
It is suitable for clustered deployments without a sticky load balancer and non-clustered deployments when purely minimal support for sessions is needed.</p>
</div>
<div class="paragraph">
<p><code>SessionCaches</code> always write out a Session to the <code>SessionDataStore</code> whenever the last request for the Session exits.</p>
</div>
<div class="paragraph">
<p>They can also be configured to do an immediate, eager write of a freshly created session.
This can be useful if you are likely to experience multiple, near simultaneous requests referencing the same session, e.g. with HTTP/2 and you don&#8217;t have a sticky load balancer.
Alternatively, if the eager write is not done, application paths which create and then invalidate a session within a single request never incur the cost of writing to persistent storage.</p>
</div>
<div class="paragraph">
<p>Additionally, if the <code>EVICT_ON_INACTIVITY</code> eviction policy is in use, you can <a href="#session-configuration-sessioncache">configure</a> the <code>DefaultSessionCache</code> to force a write of the Session to the <code>SessionDataStore</code> just before the Session is evicted.</p>
</div>
<div class="paragraph">
<p>See <a href="#session-configuration-sessioncache">the L1 Session Cache</a> for more information.</p>
</div>
</div>
<div class="sect3">
<h4>SessionDataStore</h4>
<div class="paragraph">
<p>There is one (1) <code>SessionDataStore</code> per context.
Its purpose is to handle all persistence related operations on sessions.</p>
</div>
<div class="paragraph">
<p>The common characteristics for all <code>SessionDataStores</code> are whether or not they support passivation, and the length of the grace period.</p>
</div>
<div class="paragraph">
<p>Supporting passivation means that session data is serialized.
Some persistence mechanisms serialize, such as JDBC, GCloud Datastore etc, whereas others may store an object in shared memory, e.g. Infinispan, when configured with a local cache.</p>
</div>
<div class="paragraph">
<p>Whether or not a clustering technology entails passivation controls whether or not the session passivation/activation listeners will be called.</p>
</div>
<div class="paragraph">
<p>The grace period is an interval, configured in seconds, that attempts to deal with the non-transactional nature of sessions with regard to finding sessions that have expired.
Due to the lack of transactionality, in a clustered configuration, even with a sticky load balancer, it is always possible that a Session is live on a node but has not yet been updated in the persistent store.
When <code>SessionDataStores</code> search their persistent store to find sessions that have expired, they typically perform a few sequential searches:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The first verifies the expiration of a list of candidate session ids suggested by the SessionCache</p>
</li>
<li>
<p>The second finds sessions in the store that have expired which were last live on the current node</p>
</li>
<li>
<p>The third finds sessions that expired a "while" ago, irrespective of on which node they were last used: the definition of "a while" is based on the grace period.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Jetty instantiates the trivial <code>NullSessionDataStore</code> - which does not persist sessions - as the default.</p>
</div>
<div class="paragraph">
<p>The distribution provides a number of alternative <code>SessionDataStore</code> implementations such as <a href="#configuring-sessions-file-system">FileSessionDataStore</a>, <a href="#configuring-sessions-gcloud">GCloudSessionDataStore</a>, <a href="#configuring-sessions-jdbc">JDBCSessionDataStore</a>, <a href="#configuring-sessions-mongodb">MongoSessionDataStore</a>, <a href="#configuring-sessions-infinispan">InfinispanSessionDataStore</a>, <a href="#configuring-sessions-hazelcast">HazelcastSessionDataStore</a>.</p>
</div>
</div>
<div class="sect3">
<h4>CachingSessionDataStore</h4>
<div class="paragraph">
<p>The <code>CachingSessionDataStore</code> is a special type of <code>SessionDataStore</code> that inserts an L2 cache of Session data - the <code>SessionDataMap</code> - in front of a delegate <code>SessionDataStore</code>.
The <code>SessionDataMap</code> is preferentially consulted before the actual SessionDataStore on reads.
This can improve the performance of slow stores.</p>
</div>
<div class="paragraph">
<p>Jetty provides one implementation of the this L2 cache based on <code>Memcached</code>, the <code>MemcachedSessionDataMap</code>.</p>
</div>
<div class="paragraph">
<p>See <a href="#session-configuration-memcachedsessiondatastore">the L2 SessionData Cache</a>for additional information.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="session-configuration-housekeeper">The SessionIdManager and the Housekeeper</h3>
<div class="sect3">
<h4>Default Settings</h4>
<div class="paragraph">
<p>By default, Jetty will instantiate a single instance of the <code>DefaultSessionIdManager</code> and <code>HouseKeeper</code> at startup with default settings.</p>
</div>
<div class="paragraph">
<p>The default settings are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">DefaultSessionIdManager: worker name</dt>
<dd>
<p>This uniquely identifies the jetty server instance within a cluster.
It is set from the value of the <code>JETTY_WORKER_INSTANCE</code> environment variable, or <code>node0</code> if the environment value is not set.
If you have more than one Jetty instance, it is <strong>crucial</strong> that you explicitly configure the worker name on each Jetty instance (see <a href="#session-idmanager-housekeeper-config">below</a> for how to configure).</p>
</dd>
<dt class="hdlist1">HouseKeeper: scavenge interval</dt>
<dd>
<p>This is the period in seconds between runs of the session scavenger, and by default is set to the equivalent of 10 minutes.
As a rule of thumb, you should ensure that the scavenge interval is shorter than the <code>maxInactiveInterval</code> of your sessions to ensure that they are promptly scavenged.
See below for instructions on how to configure this.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="session-idmanager-housekeeper-config">Configuration</h4>
<div class="paragraph">
<p>To change the default values, use the <a href="#startup-modules">module system</a> to <a href="#startup-modules">enable</a> the <code>sessions</code> module.</p>
</div>
<div class="paragraph">
<p>This will enable the <code>$jetty.home/etc/sessions/id-manager.xml</code> file and generate a <code>$jetty.base/start.d/sessions.ini</code> file.</p>
</div>
<div class="paragraph">
<p>The <code>id-manager.xml</code> file instantiates a single <code>DefaultSessionIdManager</code> and <code>HouseKeeper</code> and configures them using the properties from the <code>sessions.ini</code> file.</p>
</div>
<div class="paragraph">
<p>Edit the ini file to change the properties to easily customize the <code>DefaultSessionIdManager</code> and <code>HouseKeeper</code>:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.sessionIdManager.workerName</dt>
<dd>
<p>By default it is <code>node1</code>.
This uniquely identifies the Jetty server instance within a cluster.
If you have more than one Jetty instance, it is crucial that you configure the worker name differently on each jetty instance.</p>
</dd>
<dt class="hdlist1">jetty.sessionScavengeInterval.seconds</dt>
<dd>
<p>This is the period in seconds between runs of the session scavenger.
By default it will run every 600 secs (ie 10 mins).
As a rule of thumb, you should ensure that the scavenge interval is shorter than the maxInactiveInterval of your sessions to ensure that they are promptly scavenged.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="session-configuration-sessioncache">The L1 Session Cache</h3>
<div class="sect3">
<h4>The DefaultSessionCache</h4>
<div class="paragraph">
<p>In the absence of any explicit configuration, Jetty will instantiate an instance of the <code>DefaultSessionCache</code> per context.
If you wish to change any of the default values, you need to enable the <code>session-cache-hash</code> <a href="#startup-modules">module</a>.</p>
</div>
<div class="paragraph">
<p>Once the <code>session-cache-hash</code> module has been enabled, you can view a list of all the configurable values by opening <code>start.d/session-cache-hash.ini</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">--module=session-cache-hash
#jetty.session.evictionPolicy=-1
#jetty.session.saveOnInactiveEvict=false
#jetty.session.saveOnCreate=false
#jetty.session.removeUnloadableSessions=false
#jetty.session.flushOnResponseCommit=false</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.evictionPolicy</dt>
<dd>
<p>Integer.
Controls whether session objects that are held in memory are subject to eviction from the memory cache.
Evicting sessions can reduce the memory footprint of the cache.
Eviction is usually used in conjunction with a <code>SessionDataStore</code> that persists sessions.
Values are:</p>
<div class="ulist">
<ul>
<li>
<p>-1 : sessions are never evicted from the cache</p>
</li>
<li>
<p>0 : sessions are evicted from the cache as soon as the last active request for it finishes</p>
</li>
<li>
<p>&gt;= 1 : any positive number is the time in seconds after which a session that is in the cache but has not experienced any activity will be evicted</p>
</li>
</ul>
</div>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you are not using a <code>SessionDataStore</code> that persists sessions, be aware that evicted sessions will be lost.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.saveOnInactiveEvict</dt>
<dd>
<p>Boolean, default <code>false</code>.
Controls whether a session will be saved to the <code>SessionDataStore</code> just prior to its eviction.</p>
</dd>
<dt class="hdlist1">jetty.session.saveOnCreate</dt>
<dd>
<p>Boolean, default <code>false</code>.
Controls whether a session that is newly created will be immediately saved to the <code>SessionDataStore</code> or lazily saved as the last request for the session exits.</p>
</dd>
<dt class="hdlist1">jetty.session.removeUnloadableSessions</dt>
<dd>
<p>Boolean, default <code>false</code>.
Controls whether a session that cannot be restored - for example because it is corrupted - from the <code>SessionDataStore</code> is deleted by the <code>SessionDataStore</code>.</p>
</dd>
<dt class="hdlist1">jetty.session.flushOnResponseCommit</dt>
<dd>
<p>Boolean, default <code>false</code>.
If true, if a session is "dirty" - ie its attributes have changed - it will be written to the backing store as the response is about to commit.
This ensures that all subsequent requests whether to the same or different node will see the updated session data.
If false, a dirty session will only be written to the backing store when the last simultaneous request for it leaves the session.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For more general information on the uses of these configuration properties, see <a href="#sessions-details">Session Components</a>.</p>
</div>
</div>
<div class="sect3">
<h4>The NullSessionCache</h4>
<div class="paragraph">
<p>The <code>NullSessionCache</code> is a trivial implementation of the <code>SessionCache</code> that does not cache any session information.
You may need to use it if your clustering setup does not have a sticky load balancer, or if you want absolutely minimal support for sessions.
If you use this in conjunction with the <code>NullSessionDataStore</code>, then sessions will neither be retained in memory nor persisted.</p>
</div>
<div class="paragraph">
<p>To enable the <code>NullSessionCache</code>, enable the <code>sesssion-cache-null</code> <a href="#startup-modules">module</a>.
Configuration options are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.saveOnCreate</dt>
<dd>
<p>Boolean, default <code>false</code>.
Controls whether a session that is newly created will be immediately saved to the <code>SessionDataStore</code> or lazily saved as the last request for the session exits.</p>
</dd>
<dt class="hdlist1">jetty.session.removeUnloadableSessions</dt>
<dd>
<p>Boolean, default <code>false</code>.
Controls whether a session that cannot be restored - for example because it is corrupted - from the <code>SessionDataStore</code> is deleted by the <code>SessionDataStore</code>.</p>
</dd>
<dt class="hdlist1">jetty.session.flushOnResponseCommit</dt>
<dd>
<p>Boolean, default <code>false</code>.
If true, if a session is "dirty" - ie its attributes have changed - it will be written to the backing store as the response is about to commit.
This ensures that all subsequent requests whether to the same or different node will see the updated session data.
If false, a dirty session will only be written to the backing store when the last simultaneous request for it leaves the session.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For more general information on the uses of these configuration properties, see <a href="#sessions-details">Session Components</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-memory">Non-Persistent Sessions</h3>
<div class="paragraph">
<p>Non-clustered, non-persistent, in-memory-only is the default style of session management.
In previous versions of Jetty this was referred to as "hash" sessions, as they were stored in a <code>HashMap</code> in memory.</p>
</div>
<div class="paragraph">
<p>This is delivered by a combination of the <code>DefaultSessionCache</code> (to keep sessions in memory) and a <code>NullSessionDataStore</code> (to avoid session persistence).</p>
</div>
<div class="paragraph">
<p>If you do nothing, Jetty will instantiate one of each of these objects for each context at startup time using hard-coded defaults.</p>
</div>
<div class="paragraph">
<p>To explicitly set up non-persisted sessions using modules, use both the <code>session-cache-hash</code> and the <code>session-store-null</code> modules.</p>
</div>
<div class="paragraph">
<p>Enabling the modules allows you to configure behavior - see <a href="#session-configuration-sessioncache">the L1 Session Cache</a> for detailed information on configuration options for the <code>DefaultSessionCache</code>.
The <code>NullSessionDataStore</code> has no customizable options.</p>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-file-system">Persistent Sessions: File System</h3>
<div class="paragraph">
<p>Note: Persisting sessions to the local file system should <strong>not</strong> be used in a clustered environment.</p>
</div>
<div class="sect3">
<h4>Enabling File System Sessions</h4>
<div class="paragraph">
<p>When using the Jetty distribution, you will first need to enable the <code>session-store-file</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-file
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-file initialized in ${jetty.base}/start.d/session-store-file.ini
MKDIR : ${jetty.base}/sessions
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the File System Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.</p>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-file</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for the File System session management to operate.
Additionally a <code>${jetty.base}/sessions</code> directory was created.
By default Session files will be saved to this directory.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server, several ini configuration files were added to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Session data is now only loaded when requested.
Previous functionality such as <code>setLazyLoad</code> has been removed.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Configuring File System Session Properties</h4>
<div class="paragraph">
<p>Opening <code>start.d/session-store-file.ini</code> will show a list of all the configurable options for the file system session module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-file
# Enables session persistent storage in files.
# ---------------------------------------
--module=session-store-file
jetty.session.file.storeDir=${jetty.base}/sessions
#jetty.session.file.deleteUnrestorableFiles=false
#jetty.session.savePeriod.seconds=0</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.storeDir</dt>
<dd>
<p>This defines the location for storage of Session files.</p>
</dd>
<dt class="hdlist1">jetty.session.file.deleteUnrestorableFiles</dt>
<dd>
<p>Boolean.
If set to true, unreadable files will be deleted: this is useful to prevent repeated logging of the same error when the scavenger periodically (re-) attempts to load the corrupted information for a session in order to expire it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-jdbc">Persistent Sessions: JDBC</h3>
<div class="sect3">
<h4>Enabling JDBC Sessions</h4>
<div class="paragraph">
<p>When using the Jetty distribution, you will first need to enable the <code>session-store-jdbc</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-jdbc
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : sessions/jdbc/datasource dynamic dependency of session-store-jdbc
INFO : session-store-jdbc initialized in ${jetty.base}/start.d/session-store-jdbc.ini
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the JDBC Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.</p>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-jdbc</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for JDBC session management to operate.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server, several ini configuration files were added to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring JDBC Session Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/session-store-jdbc.ini</code> will show a list of all the configurable options for the JDBC module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-jdbc
# Enables JDBC persistent/distributed session storage.
# ---------------------------------------
--module=session-store-jdbc
##
##JDBC Session properties
##
#jetty.session.gracePeriod.seconds=3600
## Connection type:Datasource
db-connection-type=datasource
#jetty.session.jdbc.datasourceName=/jdbc/sessions
## Connection type:driver
#db-connection-type=driver
#jetty.session.jdbc.driverClass=
#jetty.session.jdbc.driverUrl=
## Session table schema
#jetty.session.jdbc.schema.accessTimeColumn=accessTime
#jetty.session.jdbc.schema.contextPathColumn=contextPath
#jetty.session.jdbc.schema.cookieTimeColumn=cookieTime
#jetty.session.jdbc.schema.createTimeColumn=createTime
#jetty.session.jdbc.schema.expiryTimeColumn=expiryTime
#jetty.session.jdbc.schema.lastAccessTimeColumn=lastAccessTime
#jetty.session.jdbc.schema.lastSavedTimeColumn=lastSavedTime
#jetty.session.jdbc.schema.idColumn=sessionId
#jetty.session.jdbc.schema.lastNodeColumn=lastNode
#jetty.session.jdbc.schema.virtualHostColumn=virtualHost
#jetty.session.jdbc.schema.maxIntervalColumn=maxInterval
#jetty.session.jdbc.schema.mapColumn=map
#jetty.session.jdbc.schema.table=JettySessions</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</dd>
<dt class="hdlist1">db-connection-type</dt>
<dd>
<p>Set to either <code>datasource</code> or <code>driver</code> depending on the type of connection being used.</p>
</dd>
<dt class="hdlist1">jetty.session.jdbc.datasourceName</dt>
<dd>
<p>Name of the remote datasource.</p>
</dd>
<dt class="hdlist1">jetty.session.jdbc.driverClass</dt>
<dd>
<p>Name of the JDBC driver that controls access to the remote database, such as <code>com.mysql.jdbc.Driver</code></p>
</dd>
<dt class="hdlist1">jetty.session.jdbc.driverUrl</dt>
<dd>
<p>Url of the database which includes the driver type, host name and port, service name and any specific attributes unique to the database, such as a username.
As an example, here is a mysql connection with the username appended: <code>jdbc:mysql://127.0.0.1:3306/sessions?user=sessionsadmin</code>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The <code>jetty.sessionTableSchema</code> values represent the names for the columns in the JDBC database and can be changed to suit your environment.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-mongo">Persistent Sessions: MongoDB</h3>
<div class="sect3">
<h4>Enabling MongoDB Sessions</h4>
<div class="paragraph">
<p>When using the Jetty distribution, you will first need to enable the <code>session-store-mongo</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-mongo
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: session-store-mongo
+ The java driver for the MongoDB document-based database system is hosted on GitHub and released under the Apache 2.0 license.
+ http://www.mongodb.org/
+ http://www.apache.org/licenses/LICENSE-2.0.html
Proceed (y/N)? y
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-mongo initialized in ${jetty.base}/start.d/session-store-mongo.ini
INFO : sessions/mongo/address dynamic dependency of session-store-mongo
MKDIR : ${jetty.base}/lib/nosql
DOWNLD: https://repo1.maven.org/maven2/org/mongodb/mongo-java-driver/2.13.2/mongo-java-driver-2.13.2.jar to ${jetty.base}/lib/nosql/mongo-java-driver-2.13.2.jar
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the MongoDB Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.</p>
</div>
<div class="paragraph">
<p>Because MongoDB is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).
When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-mongo</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for MongoDB session management to operate..
It also downloaded the needed Mongo-specific jar file and created a directory named <code>${jetty.base}/lib/nosql/</code> to house it.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server, several ini configuration files were added to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated <code>${jetty.base}/lib/</code> directory and use the <code>--skip-file-validation=&lt;module name&gt;</code> command line option to prevent errors when starting your server.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Configuring MongoDB Session Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/session-store-mongo.ini</code> will show a list of all the configurable options for the MongoDB module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-mongo
# Enables NoSql session management with a MongoDB driver.
# ---------------------------------------
--module=session-store-mongo
#jetty.session.mongo.dbName=HttpSessions
#jetty.session.mongo.collectionName=jettySessions
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0
connection-type=address
#jetty.session.mongo.host=localhost
#jetty.session.mongo.port=27017
#connection-type=uri
#jetty.session.mongo.connectionString=mongodb://localhost</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</dd>
<dt class="hdlist1">jetty.session.mongo.dbName</dt>
<dd>
<p>Name of the database in Mongo used to store the Session collection.</p>
</dd>
<dt class="hdlist1">jetty.session.mongo.collectionName</dt>
<dd>
<p>Name of the collection in Mongo used to keep all of the Sessions.</p>
</dd>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">connection-type=address</dt>
<dd>
<p>Used when utilizing a direct connection to the Mongo server.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.mongo.host</dt>
<dd>
<p>Host name or address for the remote Mongo instance.</p>
</dd>
<dt class="hdlist1">jetty.session.mongo.port</dt>
<dd>
<p>Port number for the remote Mongo instance.</p>
</dd>
</dl>
</div>
</dd>
<dt class="hdlist1">connection-type=uri</dt>
<dd>
<p>Used when utilizing MongoURI for secured connections.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.mongo.connectionString</dt>
<dd>
<p>The string defining the MongoURI value, such as <code>mongodb://[username:password@]host1[:port1][,host2[:port2],&#8230;&#8203;[,hostN[:portN]]][/[database][?options]]</code>.
More information on how to format the MongoURI string can be found in the <a href="https://docs.mongodb.com/manual/reference/connection-string/">official documentation for mongo.</a></p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
You will only use <strong>one</strong> <code>connection-type</code> at a time, <code>address</code> or <code>uri</code>.
If both are utilized in your <code>session-store-mongo.ini</code>, only the last <code>connection-type</code> configured in the file will be used.
By default, the <code>connection-type</code> of <code>address</code> is used.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-infinispan">Persistent Sessions: Inifinspan</h3>
<div class="sect3">
<h4>Enabling Infinispan Sessions</h4>
<div class="paragraph">
<p>When using the Jetty distribution, you will first need to enable the <code>session-store-infinispan-remote</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-infinispan-remote
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: session-store-infinispan-remote
+ Infinispan is an open source project hosted on Github and released under the Apache 2.0 license.
+ http://infinispan.org/
+ http://www.apache.org/licenses/LICENSE-2.0.html
Proceed (y/N)? y
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-infinispan-remote initialized in ${jetty.base}/start.d/session-store-infinispan-remote.ini
MKDIR : ${jetty.base}/lib/infinispan
DOWNLD: https://repo1.maven.org/maven2/org/infinispan/infinispan-remote-it/9.4.8.Final/infinispan-remote-it-9.4.8.Final.jar to ${jetty.base}/lib/infinispan/infinispan-remote-it-9.4.8.Final.jar
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/session-store-infinispan-remote/resources/hotrod-client.properties to ${jetty.base}/resources/hotrod-client.properties
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the remote Infinispan Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.
Because Infinispan is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).</p>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-infinispan-remote</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for Infinispan session management to operate.
It also downloaded the needed Infinispan-specific jar files and created a directory named <code>${jetty.base}/lib/infinispan/</code> to house them.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server it also added several ini configuration files to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated <code>${jetty.base}/lib/</code> directory and use the <code>--skip-file-validation=&lt;module name&gt;</code> command line option to prevent errors when starting your server.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Configuring Inifinspan Remote Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/session-store-infinispan-remote.ini</code> will show a list of all the configurable options for the JDBC module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-infinispan-remote
# Enables session data store in a remote Infinispan cache
# ---------------------------------------
--module=session-store-infinispan-remote
#jetty.session.infinispan.remoteCacheName=sessions
#jetty.session.infinispan.idleTimeout.seconds=0
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.infinispan.remoteCacheName</dt>
<dd>
<p>Name of the cache in Infinispan where sessions will be stored.</p>
</dd>
<dt class="hdlist1">jetty.session.infinispan.idleTimeout.seconds</dt>
<dd>
<p>Amount of time, in seconds, that a session entry in infinispan can be idle (ie not read or written) before infinispan will delete its entry.
Usually, you do <strong>not</strong> want to set a value for this, as you want jetty to handle all session expiration (and call any SessionListeners).
However, if there is the possibility that sessions can be left in infinispan but no longer referenced by any jetty node (so called "zombie" or "orphan" sessions), then you might want to use this feature.
You should make sure that the number of seconds you specify is sufficiently large to avoid the situation where a session is still being referenced by jetty, but is rarely accessed and thus deleted by infinispan.
Alternatively, you can enable the <code>infinispan-remote-query</code> module, which will allow jetty to search the infinispan session cache to proactively find and properly (ie calling any SessionListeners) scavenge defunct sessions.</p>
</dd>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
</dd>
</dl>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Configuring the Remote Infinispan Query Module</h4>
<div class="paragraph">
<p>Enabling this module allows jetty to search infinispan for expired sessions that are no longer being referenced by any jetty node.
Note that this is an <strong>additional</strong> module, to be used in conjuction with the <code>session-store-infinispan-remote</code> module.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar ../start.jar --add-to-start=infinispan-remote-query</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are no configuration properties associated with this module.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring Embedded Inifinspan Clustering</h4>
<div class="paragraph">
<p>During testing, it can be helpful to run an in-process instance of Infinispan.
To enable this you will first need to enable the <code>session-store-infinispan-embedded</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you are running Jetty with JDK 9 or greater, enable <code>session-store-infinispan-embedded-910.mod</code> instead.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar ../start.jar --add-to-start=session-store-infinispan-embedded
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: session-store-infinispan-embedded
+ Infinispan is an open source project hosted on Github and released under the Apache 2.0 license.
+ http://infinispan.org/
+ http://www.apache.org/licenses/LICENSE-2.0.html
Proceed (y/N)? y
INFO : server initialised (transitively) in ${jetty.base}/start.d/server.ini
INFO : sessions initialised (transitively) in ${jetty.base}/start.d/sessions.ini
INFO : session-store-infinispan-embedded initialised in ${jetty.base}/start.d/session-store-infinispan-embedded.ini
DOWNLOAD: https://repo1.maven.org/maven2/org/infinispan/infinispan-embedded-it/9.4.8.Final/infinispan-embedded-it-9.4.8.Final.jar to ${jetty.base}/lib/infinispan/infinispan-embedded-it-9.4.8.Final.jar
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the embedded Infinispan Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.
Because Infinispan is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).</p>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-infinispan-embedded</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for Infinispan session management to operate.
It also downloaded the needed Infinispan-specific jar files and created a directory named <code>${jetty.base}/lib/infinispan/</code> to house them.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server it also added several ini configuration files to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring Inifinspan Embedded Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/session-store-infinispan-remote.ini</code> will show a list of all the configurable options for the JDBC module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-infinispan-embedded
# Enables session data store in a local Infinispan cache
# ---------------------------------------
--module=session-store-infinispan-embedded
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4>Configuring Inifinspan Embedded Query</h4>
<div class="paragraph">
<p>Similarly to the <code>session-store-infinispan-remote</code> module, the <code>session-store-infinispan-embedded</code> module has an adjunct module <code>infinispan-embedded-query</code>, which when enabled, will allow jetty to detect and properly scavenge defunct sessions stranded in infinispan.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -jar ../start.jar --add-to-start=infinispan-embedded-query</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are no configuration properties associated with this module.</p>
</div>
</div>
<div class="sect3">
<h4>Converting Session Format for Jetty-9.4.13</h4>
<div class="paragraph">
<p>From Jetty-9.4.13 onwards, we have changed the format of the serialized session when using a remote cache (ie using hotrod).
Prior to release 9.4.13 we used the default Infinispan serialization, however this was not able to store sufficient information to allow jetty to properly deserialize session attributes in all circumstances.
See issue <a href="https://github.com/eclipse/jetty.project/issues/2919" class="bare">https://github.com/eclipse/jetty.project/issues/2919</a> for more background.</p>
</div>
<div class="paragraph">
<p>We have provided a conversion program which will convert any sessions stored in Infinispan to the new format.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
We recommend that you backup your stored sessions before running the conversion program.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>How to use the converter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -cp jetty-servlet-api-4.0.2.jar:jetty-util-10.0.0-SNAPSHOT.jar:jetty-server-10.0.0-SNAPSHOT.jar:infinispan-remote-9.1.0.Final.jar:jetty-infinispan-10.0.0-SNAPSHOT.jar:[other classpath] org.eclipse.jetty.session.infinispan.InfinispanSessionLegacyConverter
Usage: InfinispanSessionLegacyConverter [-Dhost=127.0.0.1] [-Dverbose=true|false] &lt;cache-name&gt; [check]</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">The classpath</dt>
<dd>
<p>Must contain the servlet-api, jetty-util, jetty-server, jetty-infinispan and infinispan-remote jars. If your sessions contain attributes that use application classes, you will also need to also put those classes onto the classpath. If your session has been authenticated, you may also need to include the jetty-security and jetty-http jars on the classpath.</p>
</dd>
<dt class="hdlist1">Parameters</dt>
<dd>
<p>When used with no arguments the usage message is printed. When used with the <code>cache-name</code> parameter the conversion is performed. When used with both <code>cache-name</code> and <code>check</code> parameters, sessions are checked for whether or not they are converted.</p>
<div class="dlist">
<dl>
<dt class="hdlist1">-Dhost</dt>
<dd>
<p>you can optionally provide a system property with the address of your remote Infinispan server. Defaults to the localhost.</p>
</dd>
<dt class="hdlist1">-Dverbose</dt>
<dd>
<p>defaults to false. If true, prints more comprehensive stacktrace information about failures. Useful to diagnose why a session is not converted.</p>
</dd>
<dt class="hdlist1">cache-name</dt>
<dd>
<p>the name of the remote cache containing your sessions. This is mandatory.</p>
</dd>
<dt class="hdlist1">check</dt>
<dd>
<p>the optional check command will verify sessions have been converted. Use it <em>after</em> doing the conversion.</p>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>To perform the conversion, run the InfinispanSessionLegacyConverter with just the <code>cache-name</code>, and optionally the <code>host</code> system property.
The following command will attempt to convert all sessions in the cached named <code>my-remote-cache</code> on the machine <code>myhost</code>, ensuring that application classes in the <code>/my/custom/classes</code> directory are on the classpath:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">java -cp jetty-servlet-api-4.0.2.jar:jetty-util-10.0.0-SNAPSHOT.jar:jetty-server-10.0.0-SNAPSHOT.jar:infinispan-remote-9.1.0.Final.jar:jetty-infinispan-10.0.0-SNAPSHOT.jar:/my/custom/classes org.eclipse.jetty.session.infinispan.InfinispanSessionLegacyConverter -Dhost=myhost my-remote-cache</code></pre>
</div>
</div>
<div class="paragraph">
<p>If the converter fails to convert a session, an error message and stacktrace will be printed and the conversion will abort. The failed session should be untouched, however <em>it is prudent to take a backup of your cache before attempting the conversion</em>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-hazelcast">Persistent Sessions: Hazelcast</h3>
<div class="sect3">
<h4>Enabling Hazelcast Sessions</h4>
<div class="paragraph">
<p>When using the Jetty distribution, you will first need to enable the <code>session-store-hazelcast-remote</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-hazelcast-remote
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: session-store-hazelcast-remote
+ Hazelcast is an open source project hosted on Github and released under the Apache 2.0 license.
+ https://hazelcast.org/
+ http://www.apache.org/licenses/LICENSE-2.0.html
Proceed (y/N)? y
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-hazelcast-remote initialized in ${jetty.base}/start.d/session-store-hazelcast-remote.ini
MKDIR : /Users/admin/mvn-repo/com/hazelcast/hazelcast/3.8.2
DOWNLD: https://repo1.maven.org/maven2/com/hazelcast/hazelcast/3.8.2/hazelcast-3.8.2.jar to /Users/admin/mvn-repo/com/hazelcast/hazelcast/3.8.2/hazelcast-3.8.2.jar
MKDIR : ${jetty.base}/lib/hazelcast
COPY : /Users/admin/mvn-repo/com/hazelcast/hazelcast/3.8.2/hazelcast-3.8.2.jar to ${jetty.base}/lib/hazelcast/hazelcast-3.8.2.jar
COPY : /Users/admin/mvn-repo/com/hazelcast/hazelcast-client/3.8.2/hazelcast-client-3.8.2.jar to ${jetty.base}/lib/hazelcast/hazelcast-client-3.8.2.jar
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the remote Hazelcast Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.
Because Hazelcast is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).</p>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-hazelcast-remote</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for Hazelcast session management to operate.
It also downloaded the needed Hazelcast-specific jar files and created a directory named <code>${jetty.base}/lib/hazelcast/</code> to house them.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server it also added several ini configuration files to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated <code>${jetty.base}/lib/</code> directory and use the <code>--skip-file-validation=&lt;module name&gt;</code> command line option to prevent errors when starting your server.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Configuring Hazelcast Remote Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/session-store-hazelcast-remote.ini</code> will show a list of all the configurable options for the Hazelcast module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-hazelcast-remote
# Enables session data store in a remote Hazelcast Map
# ---------------------------------------
--module=session-store-hazelcast-remote
#jetty.session.hazelcast.mapName=jetty_sessions
#jetty.session.hazelcast.onlyClient=true
#jetty.session.hazelcast.configurationLocation=
jetty.session.hazelcast.scavengeZombies=false
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.hazelcast.mapName</dt>
<dd>
<p>Name of the Map in Hazelcast where sessions will be stored.</p>
</dd>
<dt class="hdlist1">jetty.session.hazelcast.onlyClient</dt>
<dd>
<p>Hazelcast instance will be configured in client mode</p>
</dd>
<dt class="hdlist1">jetty.session.hazelcast.configurationLocation</dt>
<dd>
<p>Path to an an Hazelcast xml configuration file</p>
</dd>
<dt class="hdlist1">jetty.session.hazelcast.scavengeZombies</dt>
<dd>
<p>True/False. <code>False</code> by default. If <code>true</code>, jetty will use hazelcast queries to find sessions that are no longer being used on any jetty node and whose expiry time has passed. If you enable this option, and your session stores attributes that reference classes from inside your webapp, or jetty classes, you will need to ensure that these classes are available on each of your hazelcast instances.</p>
</dd>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Be aware using the <code>scavengeZombies</code> option that if your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances.</p>
</div>
</blockquote>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4>Configuring Embedded Hazelcast Clustering</h4>
<div class="paragraph">
<p>During testing, it can be helpful to run an in-process instance of Hazelcast.
To enable this you will first need to enable the <code>session-store-hazelcast-embedded</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
MKDIR : ${jetty.base}/start.d
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-hazelcast-embedded
ALERT: There are enabled module(s) with licenses.
The following 1 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: session-store-hazelcast-embedded
+ Hazelcast is an open source project hosted on Github and released under the Apache 2.0 license.
+ https://hazelcast.org/
+ http://www.apache.org/licenses/LICENSE-2.0.html
Proceed (y/N)? y
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : session-store-hazelcast-embedded initialized in ${jetty.base}/start.d/session-store-hazelcast-embedded.ini
MKDIR : /Users/admin/mvn-repo/com/hazelcast/hazelcast/3.8.2
DOWNLD: https://repo1.maven.org/maven2/com/hazelcast/hazelcast/3.8.2/hazelcast-3.8.2.jar to /Users/admin/mvn-repo/com/hazelcast/hazelcast/3.8.2/hazelcast-3.8.2.jar
MKDIR : ${jetty.base}/lib/hazelcast
COPY : /Users/admin/mvn-repo/com/hazelcast/hazelcast/3.8.2/hazelcast-3.8.2.jar to ${jetty.base}/lib/hazelcast/hazelcast-3.8.2.jar
COPY : /Users/admin/mvn-repo/com/hazelcast/hazelcast-client/3.8.2/hazelcast-client-3.8.2.jar to ${jetty.base}/lib/hazelcast/hazelcast-client-3.8.2.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the embedded Hazelcast Session module and any dependent modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.
Because Hazelcast is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).</p>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line, it enabled the the <code>session-store-hazelcast-embedded</code> module as well as the <code>sessions</code> and <code>server</code> modules, which are required for Hazelcast session management to operate.
It also downloaded the needed Hazelcast-specific jar files and created a directory named <code>${jetty.base}/lib/hazelcast/</code> to house them.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server it also added several ini configuration files to the <code>${jetty.base}/start.d</code> directory.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring Hazelcast Embedded Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/start.d/session-store-hazelcast-embedded.ini</code> will show a list of all the configurable options for the Hazelcast module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-hazelcast-embedded
# Enables session data store in an embedded Hazelcast Map
# ---------------------------------------
--module=session-store-hazelcast-embedded
#jetty.session.hazelcast.mapName=jetty_sessions
#jetty.session.hazelcast.configurationLocation=
jetty.session.hazelcast.scavengeZombies=false
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.hazelcast.mapName</dt>
<dd>
<p>Name of the Map in Hazelcast where sessions will be stored.</p>
</dd>
<dt class="hdlist1">jetty.session.hazelcast.configurationLocation</dt>
<dd>
<p>Path to an an Hazelcast xml configuration file</p>
</dd>
<dt class="hdlist1">jetty.session.hazelcast.scavengeZombies</dt>
<dd>
<p>True/False. <code>False</code> by default. If <code>true</code>, jetty will use hazelcast queries to find sessions that are no longer being used on any jetty node and whose expiry time has passed. If you enable this option, and your sessions contain attributes that reference classes from inside your webapp (or jetty classes) you will need to ensure that these classes are available on each of your hazelcast instances.</p>
</dd>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Be aware using the <code>scavengeZombies</code> option that if your session attributes contain classes from inside your webapp (or jetty classes) then you will need to put these classes onto the classpath of all of your hazelcast instances. In the cast of embedded hazelcast, as it is started before your webapp, it will NOT have access to your webapp&#8217;s classes - you will need to extract these classes and put them onto the jetty server&#8217;s classpath.</p>
</div>
</blockquote>
</div>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="configuring-sessions-gcloud">Persistent Sessions: Google Cloud DataStore</h3>
<div class="sect3">
<h4>Preparation</h4>
<div class="paragraph">
<p>You will first need to create a project and enable the Google Cloud api: <a href="https://cloud.google.com/docs/authentication#preparation" class="bare">https://cloud.google.com/docs/authentication#preparation</a>.
Take note of the project id that you create in this step as you need to supply it in later steps.</p>
</div>
<div class="sect4">
<h5>Communicating with GCloudDataStore</h5>
<div class="sect5">
<h6>When running Jetty outside of google infrastructure</h6>
<div class="paragraph">
<p>Before running Jetty, you will need to choose one of the following methods to set up the local environment to enable remote GCloud DataStore communications.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Using the GCloud SDK:</p>
<div class="ulist">
<ul>
<li>
<p>Ensure you have the GCloud SDK installed: <a href="https://cloud.google.com/sdk/?hl=en" class="bare">https://cloud.google.com/sdk/?hl=en</a>.</p>
</li>
<li>
<p>Use the GCloud tool to set up the project you created in the preparation step: <code>gcloud config set project PROJECT_ID</code></p>
</li>
<li>
<p>Use the GCloud tool to authenticate a google account associated with the project created in the preparation step: <code>gcloud auth login ACCOUNT</code></p>
</li>
</ul>
</div>
</li>
<li>
<p>Using environment variables</p>
<div class="ulist">
<ul>
<li>
<p>Define the environment variable <code>GCLOUD_PROJECT</code> with the project id you created in the preparation step.</p>
</li>
<li>
<p>Generate a JSON <a href="https://cloud.google.com/storage/docs/authentication?hl=en#service_accounts">service account key</a> and then define the environment variable <code>GOOGLE_APPLICATION_CREDENTIALS=/path/to/my/key.json</code></p>
</li>
</ul>
</div>
</li>
</ol>
</div>
</div>
<div class="sect5">
<h6>When Running Jetty Inside of Google Infrastructure</h6>
<div class="paragraph">
<p>The Google deployment tools will automatically configure the project and authentication information for you.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4>Configuring Indexes for Session Data</h4>
<div class="paragraph">
<p>Using some special, composite indexes can speed up session search operations, although it may make write operations slower.
By default, indexes will not be used.
In order to use them, you will need to manually upload a file that defines the indexes.
This file is named <code>index.yaml</code> and you can find it in your distribution in <code>${jetty.base}/etc/sessions/gcloud/index.yaml</code>.</p>
</div>
<div class="paragraph">
<p>Follow the instructions <a href="https://cloud.google.com/datastore/docs/tools/#the_development_workflow_using_gcloud">here</a> to upload the pre-generated <code>index.yaml</code> file.</p>
</div>
<div class="sect4">
<h5>Communicating with the GCloudDataStore Emulator</h5>
<div class="paragraph">
<p>To enable communication using the GCloud Emulator:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Ensure you have the GCloud SDK installed: <a href="https://cloud.google.com/sdk/?hl=en" class="bare">https://cloud.google.com/sdk/?hl=en</a></p>
</li>
<li>
<p>Follow the instructions <a href="https://cloud.google.com/datastore/docs/tools/datastore-emulator">here</a> on how to start the GCloud datastore emulator, and how to propagate the environment variables that it creates to the terminal in which you run Jetty.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4>Enabling the Google Cloud DataStore Module</h4>
<div class="paragraph">
<p>When using the Jetty distribution, you will first need to enable the <code>session-store-gcloud</code> <a href="#startup-modules">module</a> for your <a href="#startup-base-and-home">Jetty base</a> using the <code>--add-to-start</code> argument on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --create-startd
INFO : Base directory was modified
$ java -jar ../start.jar --add-to-start=session-store-gcloud
ALERT: There are enabled module(s) with licenses.
The following 2 module(s):
+ contains software not provided by the Eclipse Foundation!
+ contains software not covered by the Eclipse Public License!
+ has not been audited for compliance with its license
Module: gcloud
+ GCloudDatastore is an open source project hosted on Github and released under the Apache 2.0 license.
+ https://github.com/GoogleCloudPlatform/gcloud-java
+ http://www.apache.org/licenses/LICENSE-2.0.html
Module: slf4j-api
+ SLF4J is distributed under the MIT License.
+ Copyright (c) 2004-2013 QOS.ch
+ All rights reserved.
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+ The above copyright notice and this permission notice shall be
+ included in all copies or substantial portions of the Software.
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Proceed (y/N)? y
INFO : webapp transitively enabled, ini template available with --add-to-start=webapp
INFO : jul-impl transitively enabled
INFO : server transitively enabled, ini template available with --add-to-start=server
INFO : sessions transitively enabled, ini template available with --add-to-start=sessions
INFO : servlet transitively enabled
INFO : gcloud transitively enabled, ini template available with --add-to-start=gcloud
INFO : annotations transitively enabled
INFO : plus transitively enabled
INFO : slf4j-api transitively enabled
INFO : security transitively enabled
INFO : gcloud-datastore transitively enabled
INFO : jcl-slf4j transitively enabled
INFO : session-store-gcloud initialized in ${jetty.base}/start.d/session-store-gcloud.ini
INFO : jndi transitively enabled
MKDIR : ${jetty.base}/etc
COPY : ${jetty.home}/modules/jul-impl/etc/java-util-logging.properties to ${jetty.base}/etc/java-util-logging.properties
MKDIR : ${jetty.base}/lib/slf4j
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.7.21/slf4j-api-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-api-1.7.21.jar
MKDIR : ${jetty.base}/lib/gcloud
COPY : /Users/admin/.m2/repository/aopalliance/aopalliance/1.0/aopalliance-1.0.jar to ${jetty.base}/lib/gcloud/aopalliance-1.0.jar
COPY : /Users/admin/.m2/repository/com/fasterxml/jackson/core/jackson-core/2.1.3/jackson-core-2.1.3.jar to ${jetty.base}/lib/gcloud/jackson-core-2.1.3.jar
COPY : /Users/admin/.m2/repository/com/google/api-client/google-api-client-appengine/1.21.0/google-api-client-appengine-1.21.0.jar to ${jetty.base}/lib/gcloud/google-api-client-appengine-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/api-client/google-api-client/1.20.0/google-api-client-1.20.0.jar to ${jetty.base}/lib/gcloud/google-api-client-1.20.0.jar
COPY : /Users/admin/.m2/repository/com/google/api-client/google-api-client-servlet/1.21.0/google-api-client-servlet-1.21.0.jar to ${jetty.base}/lib/gcloud/google-api-client-servlet-1.21.0.jar
DOWNLD: https://repo1.maven.org/maven2/com/google/api/gax/0.0.21/gax-0.0.21.jar to ${jetty.base}/lib/gcloud/gax-0.0.21.jar
COPY : /Users/admin/.m2/repository/com/google/api/grpc/grpc-google-common-protos/0.1.0/grpc-google-common-protos-0.1.0.jar to ${jetty.base}/lib/gcloud/grpc-google-common-protos-0.1.0.jar
COPY : /Users/admin/.m2/repository/com/google/api/grpc/grpc-google-iam-v1/0.1.0/grpc-google-iam-v1-0.1.0.jar to ${jetty.base}/lib/gcloud/grpc-google-iam-v1-0.1.0.jar
COPY : /Users/admin/.m2/repository/com/google/auth/google-auth-library-credentials/0.3.1/google-auth-library-credentials-0.3.1.jar to ${jetty.base}/lib/gcloud/google-auth-library-credentials-0.3.1.jar
COPY : /Users/admin/.m2/repository/com/google/auth/google-auth-library-oauth2-http/0.3.1/google-auth-library-oauth2-http-0.3.1.jar to ${jetty.base}/lib/gcloud/google-auth-library-oauth2-http-0.3.1.jar
DOWNLD: https://repo1.maven.org/maven2/com/google/auto/value/auto-value/1.2/auto-value-1.2.jar to ${jetty.base}/lib/gcloud/auto-value-1.2.jar
DOWNLD: https://repo1.maven.org/maven2/com/google/cloud/datastore/datastore-v1-proto-client/1.3.0/datastore-v1-proto-client-1.3.0.jar to ${jetty.base}/lib/gcloud/datastore-v1-proto-client-1.3.0.jar
DOWNLD: https://repo1.maven.org/maven2/com/google/cloud/datastore/datastore-v1-protos/1.3.0/datastore-v1-protos-1.3.0.jar to ${jetty.base}/lib/gcloud/datastore-v1-protos-1.3.0.jar
DOWNLD: https://repo1.maven.org/maven2/com/google/cloud/google-cloud-core/0.5.1/google-cloud-core-0.5.1.jar to ${jetty.base}/lib/gcloud/google-cloud-core-0.5.0.jar
DOWNLD: https://repo1.maven.org/maven2/com/google/cloud/google-cloud-datastore/0.5.1/google-cloud-datastore-0.5.1.jar to ${jetty.base}/lib/gcloud/google-cloud-datastore-0.5.1.jar
COPY : /Users/admin/.m2/repository/com/google/code/findbugs/jsr305/1.3.9/jsr305-1.3.9.jar to ${jetty.base}/lib/gcloud/jsr305-1.3.9.jar
COPY : /Users/admin/.m2/repository/com/google/code/gson/gson/2.3/gson-2.3.jar to ${jetty.base}/lib/gcloud/gson-2.3.jar
COPY : /Users/admin/.m2/repository/com/google/guava/guava/19.0/guava-19.0.jar to ${jetty.base}/lib/gcloud/guava-19.0.jar
COPY : /Users/admin/.m2/repository/com/google/http-client/google-http-client-appengine/1.21.0/google-http-client-appengine-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-appengine-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/http-client/google-http-client-jackson2/1.19.0/google-http-client-jackson2-1.19.0.jar to ${jetty.base}/lib/gcloud/google-http-client-jackson2-1.19.0.jar
COPY : /Users/admin/.m2/repository/com/google/http-client/google-http-client-jackson/1.21.0/google-http-client-jackson-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-jackson-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/http-client/google-http-client/1.21.0/google-http-client-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/http-client/google-http-client-jdo/1.21.0/google-http-client-jdo-1.21.0.jar to ${jetty.base}/lib/gcloud/google-http-client-jdo-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/http-client/google-http-client-protobuf/1.20.0/google-http-client-protobuf-1.20.0.jar to ${jetty.base}/lib/gcloud/google-http-client-protobuf-1.20.0.jar
COPY : /Users/admin/.m2/repository/com/google/inject/guice/4.0/guice-4.0.jar to ${jetty.base}/lib/gcloud/guice-4.0.jar
COPY : /Users/admin/.m2/repository/com/google/oauth-client/google-oauth-client-appengine/1.21.0/google-oauth-client-appengine-1.21.0.jar to ${jetty.base}/lib/gcloud/google-oauth-client-appengine-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/oauth-client/google-oauth-client/1.21.0/google-oauth-client-1.21.0.jar to ${jetty.base}/lib/gcloud/google-oauth-client-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/oauth-client/google-oauth-client-servlet/1.21.0/google-oauth-client-servlet-1.21.0.jar to ${jetty.base}/lib/gcloud/google-oauth-client-servlet-1.21.0.jar
COPY : /Users/admin/.m2/repository/com/google/protobuf/protobuf-java/3.0.0/protobuf-java-3.0.0.jar to ${jetty.base}/lib/gcloud/protobuf-java-3.0.0.jar
COPY : /Users/admin/.m2/repository/com/google/protobuf/protobuf-java-util/3.0.0/protobuf-java-util-3.0.0.jar to ${jetty.base}/lib/gcloud/protobuf-java-util-3.0.0.jar
COPY : /Users/admin/.m2/repository/commons-codec/commons-codec/1.3/commons-codec-1.3.jar to ${jetty.base}/lib/gcloud/commons-codec-1.3.jar
COPY : /Users/admin/.m2/repository/io/grpc/grpc-context/1.0.1/grpc-context-1.0.1.jar to ${jetty.base}/lib/gcloud/grpc-context-1.0.1.jar
COPY : /Users/admin/.m2/repository/io/grpc/grpc-core/1.0.1/grpc-core-1.0.1.jar to ${jetty.base}/lib/gcloud/grpc-core-1.0.1.jar
COPY : /Users/admin/.m2/repository/io/grpc/grpc-protobuf/1.0.1/grpc-protobuf-1.0.1.jar to ${jetty.base}/lib/gcloud/grpc-protobuf-1.0.1.jar
COPY : /Users/admin/.m2/repository/io/grpc/grpc-protobuf-lite/1.0.1/grpc-protobuf-lite-1.0.1.jar to ${jetty.base}/lib/gcloud/grpc-protobuf-lite-1.0.1.jar
COPY : /Users/admin/.m2/repository/javax/inject/javax.inject/1/javax.inject-1.jar to ${jetty.base}/lib/gcloud/javax.inject-1.jar
COPY : /Users/admin/.m2/repository/javax/jdo/jdo2-api/2.3-eb/jdo2-api-2.3-eb.jar to ${jetty.base}/lib/gcloud/jdo2-api-2.3-eb.jar
COPY : /Users/admin/.m2/repository/javax/transaction/transaction-api/1.1/transaction-api-1.1.jar to ${jetty.base}/lib/gcloud/transaction-api-1.1.jar
COPY : /Users/admin/.m2/repository/joda-time/joda-time/2.9.2/joda-time-2.9.2.jar to ${jetty.base}/lib/gcloud/joda-time-2.9.2.jar
COPY : /Users/admin/.m2/repository/org/apache/httpcomponents/httpclient/4.0.1/httpclient-4.0.1.jar to ${jetty.base}/lib/gcloud/httpclient-4.0.1.jar
COPY : /Users/admin/.m2/repository/org/apache/httpcomponents/httpcore/4.0.1/httpcore-4.0.1.jar to ${jetty.base}/lib/gcloud/httpcore-4.0.1.jar
COPY : /Users/admin/.m2/repository/org/codehaus/jackson/jackson-core-asl/1.9.11/jackson-core-asl-1.9.11.jar to ${jetty.base}/lib/gcloud/jackson-core-asl-1.9.11.jar
COPY : /Users/admin/.m2/repository/org/json/json/20151123/json-20151123.jar to ${jetty.base}/lib/gcloud/json-20151123.jar
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/jcl-over-slf4j/1.7.21/jcl-over-slf4j-1.7.21.jar to ${jetty.base}/lib/slf4j/jcl-over-slf4j-1.7.21.jar
COPY : ${jetty.home}/modules/gcloud/index.yaml to ${jetty.base}/etc/index.yaml
INFO : Base directory was modified
ERROR : Module jcl-slf4j requires a module providing slf4j-impl from one of [slf4j-simple-impl, slf4j-logback, slf4j-jul, slf4j-log4j2, slf4j-log4j]
ERROR : Unsatisfied module dependencies: jcl-slf4j
Usage: java -jar $JETTY_HOME/start.jar [options] [properties] [configs]
java -jar $JETTY_HOME/start.jar --help # for more information</code></pre>
</div>
</div>
<div class="paragraph">
<p>Doing this enables the GCloud Session module and any dependent session modules or files needed for it to run on the server.
The example above is using a fresh <code>${jetty.base}</code> with nothing else enabled.
Because the Google Cloud DataStore is not a technology provided by the Eclipse Foundation, users are prompted to assent to the licenses of the external vendor (Apache in this case).</p>
</div>
<div class="paragraph">
<p>You will notice, however, that the above output presented a warning: GCloud requires certain Java Commons Logging features to work correctly.
GCloud has a dependency on Java Commons Logging, and by default Jetty will route this through SLF4J.
Enabling the GCloud Sessions module will also enable the <code>jcl-slf4j</code> module, which sends JCL logging information to SLF4J.
It does <strong>not</strong>, however, configure a SLF4J implementation for the users.</p>
</div>
<div class="paragraph">
<p>As such, you will also need to enable one of the SLF4J implementation modules listed.
In this example, we will enable the <code>slf4j-simple-impl</code> module to provide a SLF4J implementation.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar ../start.jar --add-to-start=slf4j-simple-impl
INFO : slf4j-simple-impl initialized in ${jetty.base}/start.d/slf4j-simple-impl.ini
INFO : resources transitively enabled
DOWNLD: https://repo1.maven.org/maven2/org/slf4j/slf4j-simple/1.7.21/slf4j-simple-1.7.21.jar to ${jetty.base}/lib/slf4j/slf4j-simple-1.7.21.jar
MKDIR : ${jetty.base}/resources
COPY : ${jetty.home}/modules/slf4j-simple-impl/resources/simplelogger.properties to ${jetty.base}/resources/simplelogger.properties
INFO : Base directory was modified</code></pre>
</div>
</div>
<div class="paragraph">
<p>When the <code>--add-to-start</code> argument was added to the command line the first time, it enabled the the <code>session-store-gcloud</code> module as well as several others, such as as <code>server</code>, <code>sessions</code>, <code>webapp</code> and others which are required for GCloud session management to operate; the <code>slf4j-simple-impl</code> and its dependent modules were added when the the command was run the second time.</p>
</div>
<div class="paragraph">
<p>In addition to adding these modules to the classpath of the server it also added the respective configuration files to the <code>${jetty.base}start.d</code> directory.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you have updated versions of the jar files automatically downloaded by Jetty, you can place them in the associated <code>${jetty.base}/lib/</code> directory and use the <code>--skip-file-validation=&lt;module name&gt;</code> command line option to prevent errors when starting your server.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Configuring GCloud Session Properties</h4>
<div class="paragraph">
<p>Opening the <code>start.d/session-store-gcloud.ini</code> will display a list of all the configurable properties for the Google Cloud DataStore module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"># ---------------------------------------
# Module: session-store-gcloud
# Enables GCloudDatastore session management.
# ---------------------------------------
--module=session-store-gcloud
## GCloudDatastore Session config
#jetty.session.gracePeriod.seconds=3600
#jetty.session.savePeriod.seconds=0
#jetty.session.gcloud.maxRetries=5
#jetty.session.gcloud.backoffMs=1000
#jetty.session.gcloud.namespace=
#jetty.session.gcloud.model.kind=GCloudSession
#jetty.session.gcloud.model.id=id
#jetty.session.gcloud.model.contextPath=contextPath
#jetty.session.gcloud.model.vhost=vhost
#jetty.session.gcloud.model.accessed=accessed
#jetty.session.gcloud.model.lastAccessed=lastAccessed
#jetty.session.gcloud.model.createTime=createTime
#jetty.session.gcloud.model.cookieSetTime=cookieSetTime
#jetty.session.gcloud.model.lastNode=lastNode
#jetty.session.gcloud.model.expiry=expiry
#jetty.session.gcloud.model.maxInactive=maxInactive
#jetty.session.gcloud.model.attributes=attributes</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.gracePeriod.seconds</dt>
<dd>
<p>Amount of time, in seconds, to wait for other nodes to be checked to verify an expired session is in fact expired throughout the cluster before closing it.</p>
</dd>
<dt class="hdlist1">jetty.session.savePeriod.seconds=0</dt>
<dd>
<p>By default whenever the last concurrent request leaves a session, that session is always persisted via the <code>SessionDataStore</code>, even if the only thing that changed on the session is its updated last access time.
A non-zero value means that the <code>SessionDataStore</code> will skip persisting the session if only the access time changed, and it has been less than <code>savePeriod</code> seconds since the last time the session was written.</p>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Configuring <code>savePeriod</code> is useful if your persistence technology is very slow/costly for writes.
In a clustered environment, there is a risk of the last access time of the session being out-of-date in the shared store for up to <code>savePeriod</code> seconds.
This allows the possibility that a node may prematurely expire the session, even though it is in use by another node.
Thorough consideration of the <code>maxIdleTime</code> of the session when setting the <code>savePeriod</code> is imperative - there is no point in setting a <code>savePeriod</code> that is larger than the <code>maxIdleTime</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</dd>
<dt class="hdlist1">jetty.session.gcloud.maxRetries</dt>
<dd>
<p>Maxmium number of tries to connect to GCloud DataStore to write sessions.</p>
</dd>
<dt class="hdlist1">jetty.session.gcloud.backoffMs</dt>
<dd>
<p>Amount of time, in milliseconds, between attempts to connect to the GCloud DataStore to write sessions.</p>
</dd>
<dt class="hdlist1">jetty.session.gcloud.namespace</dt>
<dd>
<p>Optional.
Sets the namespace for GCloud Datastore to use.
If set, partitions the visibility of session data between webapps, which is helpful for multi-tenant deployments.
More information can be found <a href="https://cloud.google.com/datastore/docs/concepts/multitenancy">here.</a></p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The other values listed are simply the names of properties that represent stored session data, and can be changed if needed.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="session-configuration-memcachedsessiondatastore">Persistent Sessions: The L2 Session Data Cache</h3>
<div class="paragraph">
<p>If your chosen persistence technology is slow, it can be helpful to locally cache the session data.
The <code>CachingSessionDataStore</code> is a special type of <code>SessionDataStore</code> that locally caches session data, which makes reads faster. It writes-through to your chosen type of <code>SessionDataStore</code> when session data changes.</p>
</div>
<div class="sect3">
<h4>MemcachedSessionDataMap</h4>
<div class="paragraph">
<p>The <code>MemcachedSessionDataMap</code> uses <code>memcached</code> to perform caching.</p>
</div>
<div class="paragraph">
<p>To enable it with the Jetty distribution, enable the <code>session-store-cache</code> <a href="#startup-modules">module</a>, along with your chosen <code>session-store-xxxx</code> module, and optionally the <code>session-cache-hash</code> or <code>session-cache-null</code> modules.</p>
</div>
<div class="paragraph">
<p>After enabling, the <code>$jetty.base/start.d/session-store-cache.ini</code> file will be generated:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">--module=session-store-cache
## Session Data Cache type: xmemcached
session-data-cache=xmemcached
#jetty.session.memcached.host=localhost
#jetty.session.memcached.port=11211
#jetty.session.memcached.expirySec=
#jetty.session.memcached.heartbeats=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>The configuration properties are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">jetty.session.memcached.host</dt>
<dd>
<p>Default value is <code>localhost</code>.
This is the host on which the memcached server resides.</p>
</dd>
<dt class="hdlist1">jetty.session.memcached.port</dt>
<dd>
<p>Default value is <code>11211</code>.
This is the port on which the memcached server is listening.</p>
</dd>
<dt class="hdlist1">jetty.session.memcached.expirySec</dt>
<dd>
<p>Default value <code>0</code>.
This is the length of time in seconds that an item can remain in the memcached cache, where 0 indicates indefinitely.</p>
</dd>
<dt class="hdlist1">jetty.session.memcached.heartbeats</dt>
<dd>
<p>Default value <code>true</code>.
Whether or not the memcached system should generate heartbeats.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="sessions-usecases">Session Use Cases</h3>
<div class="sect3">
<h4>Clustering with a Sticky Load Balancer</h4>
<div class="paragraph">
<p>Preferably, your cluster will utilize a sticky load balancer.
This will route requests for the same Session to the same Jetty instance.
In this case, the <code>DefaultSessionCache</code> can be used to keep in-use Session objects in memory.
You can fine-tune the cache by controlling how long Session objects remain in memory with the eviction policy settings.</p>
</div>
<div class="paragraph">
<p>If you have a large number of Sessions or very large Session objects, then you may want to manage your memory allocation by controlling the amount of time Session objects spend in the cache.
The <code>EVICT_ON_SESSION_EXIT</code> eviction policy will remove a Session object from the cache as soon as the last simultaneous request referencing it exits.
Alternatively, the <code>EVICT_ON_INACTIVITY</code> policy will remove a Session object from the cache after a configurable amount of time has passed without a request referencing it.</p>
</div>
<div class="paragraph">
<p>If your Sessions are very long lived and infrequently referenced, you might use the <code>EVICT_ON_INACTIVITY_POLICY</code> to control the size of the cache.</p>
</div>
<div class="paragraph">
<p>If your Sessions are small, or relatively few or stable in number or they are read-mostly, then you might select the <code>NEVER_EVICT</code> policy.
With this policy, Session objects will remain in the cache until they either expire or are explicitly invalidated.</p>
</div>
<div class="paragraph">
<p>If you have a high likelihood of simultaneous requests for the same session object, then the <code>EVICT_ON_SESSION_EXIT</code> policy will ensure the Session object stays in the cache as long as it is needed.</p>
</div>
</div>
<div class="sect3">
<h4>Clustering Without a Sticky Load Balancer</h4>
<div class="paragraph">
<p>Without a sticky load balancer requests for the same session may arrive on any node in the cluster.
This means it is likely that the copy of the Session object in any <code>SessionCache</code> is likely to be out-of-date, as the Session was probably last accessed on a different node.
In this case, your <code>choices</code> are to use either the <code>NullSessionCache</code> or to de-tune the <code>DefaultSessionCache</code>.
If you use the NullSessionCache all Session object caching is avoided.
This means that every time a request references a session it must be brought in from persistent storage.
It also means that there can be no sharing of Session objects for multiple requests for the same session: each will have their own Session object.
Furthermore, the outcome of session writes are indeterminate because the Servlet Specification does not mandate ACID transactions for sessions.</p>
</div>
<div class="paragraph">
<p>If you use the <code>DefaultSessionCache</code>, there is a risk that the caches on some nodes will contain out-of-date Session information as simultaneous requests for the same session are scattered over the cluster.
To mitigate this somewhat you can use the <code>EVICT_ON_SESSION_EXIT</code> eviction policy: this will ensure that the Session is removed from the cache as soon as the last simultaneous request for it exits.
Again, due to the lack of Session transactionality, the ordering outcome of write operations cannot be guaranteed.
As the Session is cached while at least one request is accessing it, it is possible for multiple simultaneous requests to share the same Session object.</p>
</div>
</div>
<div class="sect3">
<h4>Handling corrupted or unloadable session data</h4>
<div class="paragraph">
<p>For various reasons it might not be possible for the <code>SessionDataStore</code> to re-read a stored session.
One scenario is that the session stores a serialized object in it&#8217;s attributes, and after a redeployment there in an incompatible class change.
Using the setter <code>SessionCache.setRemoveUnloadableSessions(true)</code> will allow the <code>SessionDataStore</code> to delete the unreadable session from persistent storage.
This can be useful from preventing the scavenger from continually generating errors on the same expired, but un-restorable, session.</p>
</div>
</div>
<div class="sect3">
<h4>Configuring Sessions via Jetty XML</h4>
<div class="paragraph">
<p>With the provided session modules, there is no need to configure a context xml or <code>jetty-web.xml</code> file for sessions.
That said, if a user wishes to configure sessions this way, it is possible using <a href="#jetty-xml-syntax">Jetty IoC XML format.</a></p>
</div>
<div class="paragraph">
<p>Below is an example of how you could configure a the <a href="#configuring-sessions-file-system"><code>FileSessionDataStore</code></a>, but the same concept would apply to any of the *SessionDataStores discussed in this chapter:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Call id="sh" name="getSessionHandler"&gt;
&lt;Set name="sessionCache"&gt;
&lt;New class="org.eclipse.jetty.server.session.DefaultSessionCache"&gt;
&lt;Arg&gt;&lt;Ref id="sh"/&gt;&lt;/Arg&gt;
&lt;Set name="sessionDataStore"&gt;
&lt;New class="org.eclipse.jetty.server.session.FileSessionDataStore"&gt;
&lt;Set name="storeDir"&gt;/tmp/sessions&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The example above functions in either a <code>jetty-web.xml</code> file or a <a href="#using-basic-descriptor-files">context xml descriptor file.</a></p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you explicitly configure the <code>SessionCache</code> and <code>SessionDataStore</code> for a <code>SessionHandler</code> in a context xml file or <code>jetty-web.xml</code> file, any session modules you already have enabled are ignored.
So, for example, if you had enabled the <code>session-store-gcloud module</code> for your sever, you could force a particular webapp to use the <code>FileSessionDataStore</code> by explicitly configuring it in either a context xml file or a <code>jetty-web.xml</code> file as shown above.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuring-jsp">Configuring JSP Support</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="jsp-support">Configuring JSP</h3>
<div class="paragraph">
<p>This document provides information about configuring Java Server Pages (JSP) for Jetty.</p>
</div>
<div class="sect3">
<h4 id="which-jsp-implementation">Which JSP Implementation</h4>
<div class="paragraph">
<p>Jetty uses Jasper from <a href="http://tomcat.apache.org/tomcat-8.0-doc/jasper-howto.html">Apache</a> as the default JSP container implementation.</p>
</div>
<div class="paragraph">
<p>By default the Jetty distribution enables the JSP <a href="#startup-modules">module</a>, and by default, this module is set to Apache Jasper.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
[description]
Enables JSP for all webapplications deployed on the server.
[depend]
servlet
annotations
apache-jsp</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that the availability of some JSP features may depend on which JSP container implementation you are using.
Note also that it may not be possible to precompile your JSPs with one container and deploy to the other.</p>
</div>
<div class="sect4">
<h5>Logging</h5>
<div class="paragraph">
<p>The Apache Jasper logging system is bridged to the jetty logging system.
Thus, you can enable logging for jsps in the same way you have setup for your webapp.
For example, assuming you are using Jetty&#8217;s default StdErr logger, you would enable DEBUG level logging for jsps by adding the system property <code>-Dorg.apache.jasper.LEVEL=DEBUG</code> to the command line.</p>
</div>
</div>
<div class="sect4">
<h5>JSPs and Embedding</h5>
<div class="paragraph">
<p>If you have an embedded setup for your webapp and wish to use JSPs, you will need to ensure that a JSP engine is correctly initialized.</p>
</div>
<div class="paragraph">
<p>For Apache, a Servlet Specification 3.1 style <a href="#servlet-container-initializers">ServletContainerInitializer</a> is used to accomplish this.
You will need to ensure that this ServletContainerInitializer is run by jetty. Perhaps the easiest way to do this is to enable annotations processing so that Jetty automatically discovers and runs it.
The <a href="#embedded-examples">Embedded Examples</a> section includes a <a href="#embedded-webapp-jsp">worked code example</a> of how to do this.</p>
</div>
<div class="paragraph">
<p>Alternatively, you can manually wire in the appropriate ServletContainerInitializer as shown in the <a href="https://github.com/jetty-project/embedded-jetty-jsp/blob/master/src/main/java/org/eclipse/jetty/demo/Main.java">embedded-jetty-jsp</a> example on <a href="https://github.com/jetty-project">GitHub</a>, in which case you will not need the jetty-annotations jar on your classpath, nor include the AnnotationConfiguration in the list of <a href="#webapp-configurations">configuration classes</a>.</p>
</div>
</div>
</div>
<div class="sect3">
<h4>Precompiling JSPs</h4>
<div class="paragraph">
<p>You can either follow the instructions on precompilation provided by Apache, or if you are using Maven for your builds, you can use the <a href="#jetty-jspc-maven-plugin">jetty-jspc-maven</a> plugin to do it for you.</p>
</div>
<div class="paragraph">
<p>If you have precompiled your JSPs, and have customized the output package prefix (which is <code>org.apache.jsp</code> by default), you should configure your webapp context to tell Jetty about this custom package name.
You can do this using a servlet context init-param called <code>org.eclipse.jetty.servlet.jspPackagePrefix</code>.</p>
</div>
<div class="paragraph">
<p>For example, suppose you have precompiled your JSPs with the custom package prefix of <code>com.acme</code>, then you would add the following lines to your <code>web.xml</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;context-param&gt;
&lt;param-name&gt;org.eclipse.jetty.servlet.jspPackagePrefix&lt;/param-name&gt;
&lt;param-value&gt;com.acme&lt;/param-value&gt;
&lt;/context-param&gt;</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Both Jetty Maven plugins - <a href="#jetty-jspc-maven-plugin">jetty-jspc-maven-plugin</a> and the <a href="#jetty-maven-plugin">jetty-maven-plugin</a> - will only use Apache Jasper.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect4">
<h5 id="compiling-jsps">Apache JSP Container</h5>
<div class="paragraph">
<p>By default, the Apache JSP container will look for the Eclipse Java Compiler (jdt).
The Jetty distribution ships a copy of this in <code>{$jetty.home}/lib/apache-jsp</code>.
If you wish to use a different compiler, you will need to configure the <code>compilerClassName</code> init-param on the <code>JspServlet</code> with the name of the class.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 6. Understanding Apache JspServlet Parameters</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
<col style="width: 25%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">init param</th>
<th class="tableblock halign-left valign-top">Description</th>
<th class="tableblock halign-left valign-top">Default</th>
<th class="tableblock halign-left valign-top"><code>webdefault.xml</code></th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">checkInterval</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If non-zero and <code>development</code> is <code>false</code>, background jsp recompilation is enabled. This value is the interval in seconds between background recompile checks.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">classpath</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The classpath is dynamically generated if the context has a URL classloader. The <code>org.apache.catalina.jsp_classpath</code>
context attribute is used to add to the classpath, but if this is not set, this <code>classpath</code> configuration item is added to the classpath instead.`</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">classdebuginfo</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Include debugging info in class file.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">compilerClassName</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If not set, defaults to the Eclipse jdt compiler.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">compiler</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Used if the Eclipse jdt compiler cannot be found on the
classpath. It is the classname of a compiler that Ant should invoke.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">compilerTargetVM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Target vm to compile for.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1.8</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1.8</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">compilerSourceVM</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Sets source compliance level for the jdt compiler.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1.8</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">1.8</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">development</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>true</code> recompilation checks occur at the frequency governed by <code>modificationTestInterval</code>.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">displaySourceFragment</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Should a source fragment be included in
exception messages</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">dumpSmap</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Dump SMAP JSR45 info to a file.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">enablePooling</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Determines whether tag handler pooling is enabled.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">engineOptionsClass</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Allows specifying the Options class used to
configure Jasper. If not present, the default EmbeddedServletOptions
will be used.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">errorOnUseBeanInvalidClassAttribute</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Should Jasper issue an error when
the value of the class attribute in an useBean action is not a valid
bean class</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">fork</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Only relevant if you use Ant to compile jsps: by default Jetty will use the Eclipse jdt compiler.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">genStrAsCharArray</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Option for generating Strings as char arrays.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">ieClassId</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The class-id value to be sent to Internet Explorer when
using &lt;jsp:plugin&gt; tags.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">javaEncoding</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Pass through the encoding to use for the compilation.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">UTF8</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">jspIdleTimeout</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The amount of time in seconds a JSP can be idle before
it is unloaded. A value of zero or less indicates never unload.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">keepgenerated</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Do you want to keep the generated Java files around?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">mappedFile</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Support for mapped Files. Generates a servlet that has a
print statement per line of the JSP file </p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">maxLoadedJsps</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The maximum number of JSPs that will be loaded for a web
application. If more than this number of JSPs are loaded, the least
recently used JSPs will be unloaded so that the number of JSPs loaded at
any one time does not exceed this limit. A value of zero or less
indicates no limit.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-1</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">modificationTestInterval</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If <code>development=true</code>, interval between
recompilation checks, triggered by a request.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">4</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">quoteAttributeEL</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">When EL is used in an attribute value on a JSP page, should the rules for quoting of attributes described in JSP.1.6 be applied to the expression</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">recompileOnFail</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If a JSP compilation fails should the
modificationTestInterval be ignored and the next access trigger a
re-compilation attempt? Used in development mode only and is disabled by
default as compilation may be expensive and could lead to excessive
resource usage.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">scratchDir</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Directory where servlets are generated. The default is the value of the context attribute <code>javax.servlet.context.tempdir</code>, or the system property <code>java.io.tmpdir</code> if the context attribute is not set.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">strictQuoteEscaping</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Should the quote escaping required by section JSP.1.6 of the JSP specification be applied to scriplet expression.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">TRUE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">-</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">suppressSmap</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Generation of SMAP info for JSR45 debugging.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">trimSpaces</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Should template text that consists entirely of whitespace be removed from the output (true), replaced with a single space (single) or left unchanged (false)? Note that if a JSP page or tag file specifies a trimDirectiveWhitespaces value of true, that will take precedence over this configuration setting for that page/tag.
trimmed?</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">–</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">xpoweredBy</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Generate an X-Powered-By response header.</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">FALSE</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect4">
<h5 id="configuring-jsp-for-jetty">Configuration</h5>
<div class="paragraph">
<p>The JSP engine has many configuration parameters.
Some parameters affect only precompilation, and some affect runtime recompilation checking.
Parameters also differ among the various versions of the JSP engine.
This page lists the configuration parameters, their meanings, and their default settings.
Set all parameters on the <code>org.eclipse.jetty.jsp.JettyJspServlet</code> instance defined in the <a href="#webdefault-xml"><code>webdefault.xml</code></a> file.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Be careful: for all of these parameters, if the value you set doesn&#8217;t take effect, try using all lower case instead of camel case, or capitalizing only some of the words in the name, as JSP is inconsistent in its parameter naming strategy.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
</div>
<div class="sect3">
<h4 id="modifying-configuration">Modifying Configuration</h4>
<div class="sect4">
<h5 id="overriding-webdefault.xml">Overriding <code>webdefault.xml</code></h5>
<div class="paragraph">
<p>You can make a copy of the <a href="#webdefault-xml">{$jetty.home}/etc/webdefault.xml</a> that ships with Jetty, apply your changes, and use it instead of the shipped version.
The example below shows how to do this when using the Jetty Maven plugin.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;plugin&gt;
&lt;groupId&gt;org.eclipse.jetty&lt;/groupId&gt;
&lt;artifactId&gt;jetty-maven-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;webApp&gt;
&lt;defaultsDescriptor&gt;src/main/resources/webdefault.xml&lt;/defaultsDescriptor&gt;
&lt;/webApp&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you are using the Jetty distribution, and you want to change the JSP settings for just one or a few of your webapps, copy the <code>{$jetty.home}/etc/webdefault.xml</code> file somewhere, modify it, and then use a <a href="#intro-jetty-configuration-contexts">context xml</a> file to set this file as the <code>defaultsDescriptor</code> for your webapp. Here&#8217;s a snippet:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;Configure class=&gt;"org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name=&gt;"contextPath"&gt;/foo&lt;/Set&gt;
&lt;Set name=&gt;"war"&gt;&lt;SystemProperty name=&gt;"jetty.home" &gt;default=&gt;"."/&gt;/webapps/foobar.war&lt;/Set&gt;
&lt;Set name=&gt;"defaultsDescriptor"&gt;/home/smith/dev/webdefault.xml&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you want to change the JSP settings for all webapps, edit the <code>{$jetty.home}/etc/webdefaults.xml</code> file directly instead.</p>
</div>
</div>
<div class="sect4">
<h5 id="configuring-jsp-servlet-in-web.xml">Configuring the JSP Servlet in web.xml</h5>
<div class="paragraph">
<p>Another option is to add an entry for the JSPServlet to the <code>WEB-INF/web.xml</code> file of your webapp and change or add init-params.
You may also add (but not remove) servlet-mappings.
You can use the entry in <a href="#webdefault-xml">{$jetty.home}/etc/webdefault.xml</a> as a starting point.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;servlet id="jsp"&gt;
&lt;servlet-name&gt;jsp&lt;/servlet-name&gt;
&lt;servlet-class&gt;org.eclipse.jetty.jsp.JettyJspServlet&lt;/servlet-class&gt;
&lt;init-param&gt;
&lt;param-name&gt;keepgenerated&lt;/param-name&gt;
&lt;param-value&gt;true&lt;/param-value&gt;
&lt;/init-param&gt;
...
&lt;load-on-startup&gt;0&lt;/load-on-startup&gt;
&lt;/servlet&gt;
&lt;servlet-mapping&gt;
&lt;servlet-name&gt;jsp&lt;/servlet-name&gt;
&lt;url-pattern&gt;*.jsp&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.jspf&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.jspx&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.xsp&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.JSP&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.JSPF&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.JSPX&lt;/url-pattern&gt;
&lt;url-pattern&gt;*.XSP&lt;/url-pattern&gt;
&lt;/servlet-mapping&gt;
&lt;servlet id="my-servlet"&gt;
&lt;servlet-name&gt;myServlet&lt;/servlet-name&gt;
&lt;servlet-class&gt;com.acme.servlet.MyServlet&lt;/servlet-class&gt;
...</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="jsp-async-support">Configuring Async Support</h5>
<div class="paragraph">
<p>By default, Jetty does not enable async support for the JSP servlet.
Configuring the JSP servlet for async is relatively easy - simply define the <code>async-supported</code> parameter as <code>true</code> in either your <code>webdefault.xml</code> or the <code>web.xml</code> for a specific context.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;servlet id="jsp"&gt;
&lt;servlet-name&gt;jsp&lt;/servlet-name&gt;
&lt;async-supported&gt;true&lt;/async-supported&gt;
&lt;/servlet&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="using-jstl-taglibs-for-jetty7-jetty8">Using JSTL Taglibs</h4>
<div class="paragraph">
<p>The JavaServer Pages Standlard Tag Library (JSTL) is part of the Jetty distribution and is automatically put on the classpath when you <a href="#which-jsp-implementation">select your flavour of JSP</a>.
It is also automatically on the classpath for the Jetty Maven plugin, which uses the Apache JSP engine.</p>
</div>
<div class="sect4">
<h5>Embedding</h5>
<div class="paragraph">
<p>If you are using Jetty in an embedded scenario, and you need to use JSTL, then you must ensure that the JSTL jars are included on the <em>container&#8217;s</em> classpath - that is the classpath that is the <em>parent</em> of the webapp&#8217;s classpath.
This is a restriction that arises from the JavaEE specification.</p>
</div>
<div class="sect5">
<h6>Apache JSP</h6>
<div class="paragraph">
<p>You will need to put the jars that are present in the <code>{$jetty.home}/lib/apache-jstl</code> directory onto the <em>container&#8217;s</em> classpath.
The Apache JSP engine will find the JSTL tag definitions inside these jars during startup.</p>
</div>
<div class="paragraph">
<p>As an efficiency enhancement, you can have jetty examine the JSTL jars to find the tags, and pre-feed them into the Apache JSP engine.
This is more efficient, because jetty will only scan the jars you tell it to, whereas the Apache JSP engine will scan every jar, which can be time-consuming in applications with a lot of jars on the container classpath.</p>
</div>
<div class="paragraph">
<p>To take advantage of this efficiency enhancement, set up the <a href="#container-include-jar-pattern">org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</a> to include a <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">pattern</a> that will match the names of the JSTL jars.
The <a href="#embedded-examples">Embedded Examples</a> section includes a <a href="#embedded-webapp-jsp">worked code example</a> of how to do this.
Below is a snippet from the example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java"> webapp.setAttribute("org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern",".*/[^/]*taglibs.*\\.jar$");</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="using-jsf-taglibs">Using JSF Taglibs</h4>
<div class="paragraph">
<p>The following sections provide information about using JSF TagLibs with Jetty Standalone and the Jetty Maven Plugin.</p>
</div>
<div class="sect4">
<h5 id="using-jsf-taglibs-with-jetty-standalone">Using JSF Taglibs with Jetty Distribution</h5>
<div class="paragraph">
<p>If you want to use JSF with your webapp, you need to copy the JSF implementation Jar (whichever Jar contains the <code>META-INF/*.tld</code> files from your chosen JSF implementation) into Jetty&#8217;s shared container lib directory.
You can either put them into the lib directory for Apache <code>{$jetty.home}/lib/apache-jsp</code> or put them into <code>{$jetty.home}/lib/ext</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="using-jsf-taglibs-with-jetty-maven-plugin">Using JSF Taglibs with Jetty Maven Plugin</h5>
<div class="paragraph">
<p>You should make your JSF jars dependencies of the plugin and <em>not</em> the webapp itself.
For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;plugin&gt;
&lt;groupId&gt;org.eclipse.jetty&lt;/groupId&gt;
&lt;artifactId&gt;jetty-maven-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;webApp&gt;
&lt;contextPath&gt;/${artifactId}&lt;/contextPath&gt;
&lt;/webApp&gt;
&lt;scanIntervalSeconds&gt;5&lt;/scanIntervalSeconds&gt;
&lt;/configuration&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.sun.faces&lt;/groupId&gt;
&lt;artifactId&gt;jsf-api&lt;/artifactId&gt;
&lt;version&gt;2.0.8&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.sun.faces&lt;/groupId&gt;
&lt;artifactId&gt;jsf-impl&lt;/artifactId&gt;
&lt;version&gt;2.0.8&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="annotations">Annotations</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Jetty supports the servlet specification annotations.
It is not enable by default, so the following sections show you how to enable it, and how to use them.</p>
</div>
<div class="sect2">
<h3 id="annotations-quick-setup">Quick Setup</h3>
<div class="sect3">
<h4>Jetty Distribution</h4>
<div class="paragraph">
<p>If you are using the jetty distribution, then annotations are enabled by default.
The annotations <a href="#startup-modules">module</a> and its transitive dependencies are responsible for making annotation processing available.</p>
</div>
<div class="paragraph">
<p>Note that annotations that relate to <a href="#jndi">JNDI</a>, such as @Resource and @Resources are enabled via the JNDI module, which is a transitive dependency on the annotations module.</p>
</div>
</div>
<div class="sect3">
<h4>Jetty Maven Plugin</h4>
<div class="paragraph">
<p>Annotations and JNDI are pre-enabled for the Maven plugin.</p>
</div>
</div>
<div class="sect3">
<h4>Embedding</h4>
<div class="paragraph">
<p>To use annotations in an embedded scenario, you will need to include the <code>jetty-annotations</code> jar and all its dependencies onto your classpath.
You will also need to include the <code>org.eclipse.jetty.annotations.AnnotationConfiguration</code> class into the list of <a href="#webapp-configurations">Configuration classes</a> applied to the <code>org.eclipse.jetty.webapp.WebAppContext</code> class representing your webapp.</p>
</div>
<div class="paragraph">
<p>Below is an example application that sets up the standard <code>test-spec.war</code> webapp from the distribution in embedded fashion.
It can also be found in the Jetty GitHub repository on the examples/embedded page as <a href="https://github.com/eclipse/jetty.project/tree/master/examples/embedded/src/main/java/org/eclipse/jetty/embedded"><code>ServerWithAnnotations.java</code>.</a>
Note that the <code>test-spec.war</code> uses not only annotations, but also <a href="#jndi">JNDI</a>, so this example also enables their processing (via the <a href="#jndi-configuration-classes">org.eclipse.jetty.plus.webapp.EnvConfiguration</a>, <a href="#jndi-configuration-classes">org.eclipse.jetty.plus.webapp.PlusConfiguration</a> and their related jars).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">//
// ========================================================================
// 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
// ========================================================================
//
package org.eclipse.jetty.embedded;
import java.io.File;
import java.io.FileNotFoundException;
import java.net.URL;
import javax.naming.NamingException;
import org.eclipse.jetty.annotations.AnnotationConfiguration;
import org.eclipse.jetty.plus.jndi.EnvEntry;
import org.eclipse.jetty.plus.jndi.NamingDump;
import org.eclipse.jetty.plus.jndi.Resource;
import org.eclipse.jetty.plus.jndi.Transaction;
import org.eclipse.jetty.plus.webapp.EnvConfiguration;
import org.eclipse.jetty.plus.webapp.PlusConfiguration;
import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;
/**
* ServerWithAnnotations
*/
public class ServerWithAnnotations
{
public static Server createServer(int port) throws NamingException, FileNotFoundException
{
// Create the server
Server server = new Server(port);
// Create a WebApp
WebAppContext webapp = new WebAppContext();
// Enable parsing of jndi-related parts of web.xml and jetty-env.xml
webapp.addConfiguration(new EnvConfiguration(), new PlusConfiguration(), new AnnotationConfiguration());
webapp.setContextPath("/");
File warFile = JettyDistribution.resolve("demo-base/webapps/test-spec.war").toFile();
webapp.setWar(warFile.getAbsolutePath());
webapp.setAttribute(
"org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern",
".*/jetty-servlet-api-[^/]*\\.jar$");
server.setHandler(webapp);
// Register new transaction manager in JNDI
// At runtime, the webapp accesses this as java:comp/UserTransaction
new Transaction(new com.acme.MockUserTransaction());
// Define an env entry with webapp scope.
// THIS ENTRY IS OVERRIDDEN BY THE ENTRY IN jetty-env.xml
new EnvEntry(webapp, "maxAmount", 100d, true);
// Register a mock DataSource scoped to the webapp
new Resource(server, "jdbc/mydatasource", new com.acme.MockDataSource());
// Add JNDI context to server for dump
server.addBean(new NamingDump());
// Configure a LoginService
String realmResourceName = "etc/realm.properties";
ClassLoader classLoader = ServerWithAnnotations.class.getClassLoader();
URL realmProps = classLoader.getResource(realmResourceName);
if (realmProps == null)
throw new FileNotFoundException("Unable to find " + realmResourceName);
HashLoginService loginService = new HashLoginService();
loginService.setName("Test Realm");
loginService.setConfig(realmProps.toExternalForm());
server.addBean(loginService);
return server;
}
public static void main(String[] args) throws Exception
{
int port = ExampleUtil.getPort(args, "jetty.http.port", 8080);
Server server = createServer(port);
server.start();
server.dumpStdErr();
server.join();
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="using-annotations">Working with Annotations</h3>
<div class="sect3">
<h4>Which Annotations Are Supported</h4>
<div class="paragraph">
<p>Jetty supports interpretation and application of the following annotations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>@Resource</p>
</li>
<li>
<p>@Resources</p>
</li>
<li>
<p>@PostConstruct</p>
</li>
<li>
<p>@PreDestroy</p>
</li>
<li>
<p>@DeclaredRoles</p>
</li>
<li>
<p>@RunAs</p>
</li>
<li>
<p>@MultipartConfig</p>
</li>
<li>
<p>@WebServlet</p>
</li>
<li>
<p>@WebFilter</p>
</li>
<li>
<p>@WebListener</p>
</li>
<li>
<p>@WebInitParam</p>
</li>
<li>
<p>@ServletSecurity, @HttpConstraint, @HttpMethodConstraint</p>
</li>
<li>
<p>@HandlesTypes (on ServletContainerInitializers)</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="discoverable_introspectable_annotations">Discovered vs Introspected Annotations</h4>
<div class="paragraph">
<p>Some types of annotation can be placed on any class, not necessarily just those with which the container interacts directly.
These type of annotations are referred to as "discovered" to indicate that the container must take proactive action to go out and find them.
The other type of annotation is call "introspected", meaning that they occur on classes with which the container interacts during their lifecycle (e.g. <code>javax.servlet.Servlet</code>, <code>javax.servlet.Filter</code>, &#8230;&#8203;etc.), and hence can be found by simple inspection of the class at that point.</p>
</div>
<div class="paragraph">
<p>Some examples of discovered annotations are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>@WebServlet</p>
</li>
<li>
<p>@WebFilter</p>
</li>
<li>
<p>@WebListener</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Some examples of introspected annotations are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>@PostConstruct</p>
</li>
<li>
<p>@PreDestroy</p>
</li>
<li>
<p>@Resource</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="jars-scanned-for-annotations">Which Jar Files Are Scanned For Discovered Annotations</h4>
<div class="paragraph">
<p>The web.xml file can contain the attribute <code>metadata-complete</code>.
If this is set to <code>true</code>, then <em>no</em> scanning of discoverable annotations takes place.
However, scanning of classes may <em>still</em> occur because of <a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html">javax.servlet.ServletContainerInitializer</a>s.
Classes implementing this interface are found by Jetty using the <a href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">javax.util.ServiceLoader</a> mechanism, and if one is present <em>and</em> it includes the @HandlesTypes annotation, then Jetty must scan the class hierarchy of the web application.
This may be very time-consuming if you have many jars in the container&#8217;s path or in the webapp&#8217;s WEB-INF/lib.</p>
</div>
<div class="paragraph">
<p>If scanning is to take place - because either <code>metadata-complete</code> is <code>false</code> or missing, or because there are one or more <a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html">javax.servlet.ServletContainerIntializer</a>s with @HandlesTypes - then Jetty must consider both the container&#8217;s classpath and the webapp&#8217;s classpath.</p>
</div>
<div class="paragraph">
<p>By default, Jetty will <em>not</em> scan any classes that are on the container&#8217;s classpath.
If you need to cause jars and classes that are on the container&#8217;s classpath to be scanned, then you can use the <a href="#container-include-jar-pattern"><code>org.eclipse.jetty.server.webapp.ContainerIncludeJarPattern</code></a> <a href="#context_attributes">context attribute</a> to specify a pattern for jars and directories from the container&#8217;s classpath to scan.</p>
</div>
<div class="paragraph">
<p>By default Jetty will scan <em>all</em>classes from <code>WEB-INF/classes</code> and all jars from <code>WEB-INF/lib</code> according to the order, if any, established by absolute or relative ordering clauses in web.xml.
If your webapp contains many jar files, you can significantly speed up deployment by omitting them from scanning.
To do this, use the <a href="#web-inf-include-jar-pattern">org.eclipse.jetty.server.webapp.WebInfIncludeJarPattern</a> <a href="#context_attributes">context attribute</a> to define the patterns of jars that you specifically want to be scanned.</p>
</div>
<div class="paragraph">
<p>Note that if you have configured an <a href="#using-extra-classpath-method">extraClasspath</a> for the webapp, then it participates in the scanning process too.
Any classes dirs are treated the same for scanning purposes as if they were in WEB-INF/classes and jars are treated as if they were in WEB-INF/lib.</p>
</div>
<div class="paragraph">
<p>See also the next section on <a href="#servlet-container-initializers">ServletContainerInitializers</a> if you need to <a href="#servlet-container-initializers">control the order in which they are applied</a>.</p>
</div>
</div>
<div class="sect3">
<h4>Multi-threaded Annotation Scanning</h4>
<div class="paragraph">
<p><a href="#jars-scanned-for-annotations">If annotation scanning is to be performed</a>, by default Jetty will do it in a multi-threaded manner in order to complete it in the minimum amount of time.</p>
</div>
<div class="paragraph">
<p>If for some reason you don&#8217;t want multi-threaded scanning, you can configure Jetty to revert to single-threaded scanning.
There are several ways to configure this:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Set the <a href="#context_attributes">context attribute</a> <code>org.eclipse.jetty.annotations.multiThreaded</code> to <code>false</code></p>
</li>
<li>
<p>Set the <a href="#server_attributes">Server attribute</a> <code>org.eclipse.jetty.annotations.multiThreaded</code> to <code>false</code></p>
</li>
<li>
<p>Set the System property <code>org.eclipse.jetty.annotations.multiThreaded</code> to <code>false</code></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Method 1 will only affect the current webapp.
Method 2 will affect all webapps deployed to the same Server instance.
Method 3 will affect all webapps deployed in the same JVM.</p>
</div>
<div class="paragraph">
<p>By default, Jetty will wait a maximum of 60 seconds for all of the scanning threads to complete.
You can set this to a higher or lower number of seconds by doing one of the following:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Set the <a href="#context_attributes">context attribute</a> <code>org.eclipse.jetty.annotations.maxWait</code></p>
</li>
<li>
<p>Set the <a href="#server_attributes">Server attribute</a> <code>org.eclipse.jetty.annotations.maxWait</code></p>
</li>
<li>
<p>Set the System property <code>org.eclipse.jetty.annotations.maxWait</code></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Method 1 will only affect the current webapp.
Method 2 will affect all webapps deployed to the same Server instance.
Method 3 will affect all webapps deployed in the same JVM.</p>
</div>
</div>
<div class="sect3">
<h4 id="servlet-container-initializers">ServletContainerInitializers</h4>
<div class="paragraph">
<p>The <a href="http://docs.oracle.com/javaee/6/api/javax/servlet/ServletContainerInitializer.html">javax.servlet.ServletContainerInitializer</a> class can exist in: the container&#8217;s classpath, the webapp&#8217;s <code>WEB-INF/classes</code> directory, the webapp&#8217;s <code>WEB-INF/lib</code> jars, or any external <a href="#using-extra-classpath-method">extraClasspath</a> that you have configured on the webapp.</p>
</div>
<div class="paragraph">
<p>The <a href="http://jcp.org/aboutJava/communityprocess/final/jsr340/">Servlet Specification</a> does not define any order in which a <code>ServletContainerInitializer</code> must be called when the webapp starts.
By default Jetty will call them in the following order:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>ServletContainerInitializers from the container&#8217;s classpath</p>
</li>
<li>
<p>ServletContainerInitializers from WEB-INF/classes</p>
</li>
<li>
<p>ServletContainerInitializers from WEB-INF/lib jars <em>in the order established in web.xml</em>, or in the order that the SCI is returned by the <a href="http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html">javax.util.ServiceLoader</a> if there is <em>no</em> ordering</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>As is the case with annotation scanning, the <a href="#using-extra-classpath-method">extraClasspath</a> is fully considered for <code>ServletContainerInitializer</code> callbacks. <code>ServletContainerInitializer</code> derived from a classes directory on the <code>extraClasspath</code> and jars from an <code>extraClasspath</code> for the webapp are called in step 2 and 3, respectively.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
As of Jetty-9.4.4, unless the <code>web.xml</code> is version 3.0 or greater, only <code>ServletContainerInitializers</code> that are on the container classpath will be discovered.
Users wishing to use <code>ServletContainerInitializers</code> from within the webapp with older versions of <code>web.xml</code> must either upgrade their <code>web.xml</code> version, or call <code>WebAppContext.setConfigurationDiscovered(true)</code> either programmatically or in xml.
Upgrading the <code>web.xml</code> version is preferable.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect4">
<h5>Controlling the order of ServletContainerInitializer invocation</h5>
<div class="paragraph">
<p>If you need <code>ServletContainerInitializer</code> classes called in a specific order that is different from that outlined above, you can use the <a href="#context_attributes">context attribute</a> <code>org.eclipse.jetty.containerInitializerOrder</code>.
Set them to a list of comma separated class names of <code>ServletContainerInitializers</code> in the order that you want them applied.
You may optionally use the wildcard character "<strong>" *once</strong> in the list.
It will match all <code>ServletContainerInitializer</code> classed not explicitly named in the list.</p>
</div>
<div class="paragraph">
<p>Here is an example, setting the context attribute in code (although you can also do the <a href="#intro-jetty-configuration-webapps">same in xml</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerOrder",
"org.eclipse.jetty.websocket.javax.server.JavaxWebSocketServletContainerInitializer, com.acme.Foo.MySCI, *");</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this example, we ensure that the <code>WebSocketServerContainerInitializer</code> is the very first <code>ServletContainerInitializer</code> that is called, followed by MySCI and then any other <code>ServletContainerInitializer</code> instances that were discovered but not yet called.</p>
</div>
</div>
<div class="sect4">
<h5 id="excluding-scis">Excluding ServletContainerInitializers</h5>
<div class="paragraph">
<p>By default, as according to the Servlet Specification, all <code>ServletContainerInitializer</code> that are discovered are invoked (see above for how to control the invocation order).
Sometimes, depending on your requirements, you may need to prevent some being called at all.</p>
</div>
<div class="paragraph">
<p>In this case, you can define the <code>org.eclipse.jetty.containerInitializerExclusionPattern</code> <a href="#context_attributes">context attribute</a>.
This is a regular expression that defines <a href="http://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html">patterns</a> of classnames that you want to exclude.
Here&#8217;s an example, setting the context attribute in code, although you may do exactly the <a href="#intro-jetty-configuration-webapps">same in xml</a>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">WebAppContext context = new WebAppContext();
context.setAttribute("org.eclipse.jetty.containerInitializerExclusionPattern",
"com.acme.*|com.corp.SlowContainerInitializer");</code></pre>
</div>
</div>
<div class="paragraph">
<p>In this example we exclude <strong>all</strong> <code>ServletContainerInitializer</code> instances in the com.acme package, and the <code>SlowContainerInitializer</code>.</p>
</div>
<div class="paragraph">
<p>It is possible to use exclusion and ordering together to control <code>ServletContainerInitializer</code> invocation - the exclusions will be applied before the ordering.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="using-annotations-embedded">Using Annotations with Jetty Embedded</h3>
<div class="sect3">
<h4>Setting up the Classpath</h4>
<div class="paragraph">
<p>You will need to place the following Jetty jar files onto the classpath of your application.
You can obtain them from the <a href="https://www.eclipse.org/jetty/download.html">Jetty distribution</a>, or the <a href="https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-annotations">Maven repository</a>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>jetty-plus.jar
jetty-annotations.jar</pre>
</div>
</div>
<div class="paragraph">
<p>You will also need the <a href="http://asm.ow2.org/">asm</a> jar, which you can obtain from <a href="http://central.maven.org/maven2/org/eclipse/jetty/orbit/org.objectweb.asm/3.3.1.v201105211655/org.objectweb.asm-3.3.1.v201105211655.jar">this link.</a></p>
</div>
</div>
<div class="sect3">
<h4>Example</h4>
<div class="paragraph">
<p>Here&#8217;s an example application that sets up a Jetty server, performs some setup to ensure that annotations are scanned, and then deploys a webapp that uses annotations.
This example also uses the @Resource annotation which involves JNDI, so we would also <a href="#jndi-embedded">add the necessary JNDI jars to the classpath</a>.
The example also adds in the configuration classes that are responsible for JNDI (see line 19).</p>
</div>
<div class="paragraph">
<p>The code is as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">import org.eclipse.jetty.security.HashLoginService;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;
/**
* ServerWithAnnotations
*
*
*/
public class ServerWithAnnotations
{
public static final void main(String args[]) throws Exception
{
//Create the server
Server server = new Server(8080);
//Enable parsing of jndi-related parts of web.xml and jetty-env.xml
org.eclipse.jetty.webapp.Configuration.ClassList classlist = org.eclipse.jetty.webapp.Configuration.ClassList.setServerDefault(server);
classlist.addAfter("org.eclipse.jetty.webapp.FragmentConfiguration", "org.eclipse.jetty.plus.webapp.EnvConfiguration", "org.eclipse.jetty.plus.webapp.PlusConfiguration");
classlist.addBefore("org.eclipse.jetty.webapp.JettyWebXmlConfiguration", "org.eclipse.jetty.annotations.AnnotationConfiguration");
//Create a WebApp
WebAppContext webapp = new WebAppContext();
webapp.setContextPath("/");
webapp.setWar("../../tests/test-webapps/test-servlet-spec/test-spec-webapp/target/test-spec-webapp-9.0.4-SNAPSHOT.war");
server.setHandler(webapp);
//Register new transaction manager in JNDI
//At runtime, the webapp accesses this as java:comp/UserTransaction
org.eclipse.jetty.plus.jndi.Transaction transactionMgr = new org.eclipse.jetty.plus.jndi.Transaction(new com.acme.MockUserTransaction());
//Define an env entry with webapp scope.
org.eclipse.jetty.plus.jndi.EnvEntry maxAmount = new org.eclipse.jetty.plus.jndi.EnvEntry (webapp, "maxAmount", new Double(100), true);
// Register a mock DataSource scoped to the webapp
org.eclipse.jetty.plus.jndi.Resource mydatasource = new org.eclipse.jetty.plus.jndi.Resource(webapp, "jdbc/mydatasource", new com.acme.MockDataSource());
// Configure a LoginService
HashLoginService loginService = new HashLoginService();
loginService.setName("Test Realm");
loginService.setConfig("src/test/resources/realm.properties");
server.addBean(loginService);
server.start();
server.join();
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>On line 19 the configuration classes responsible for setting up JNDI and <code>java:comp/env</code> are added.</p>
</div>
<div class="paragraph">
<p>On line 20 we add in the configuration class that ensures annotations are inspected.</p>
</div>
<div class="paragraph">
<p>On lines 30, 33 and 37 JNDI resources that we will be able to reference with @Resource annotations are configured.</p>
</div>
<div class="paragraph">
<p>With the setup above, a servlet that uses annotations and Jetty will honour the annotations when the webapp is deployed can be created:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">import javax.annotation.security.DeclareRoles;
import javax.annotation.security.RunAs;
import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletOutputStream;
import javax.servlet.annotation.WebInitParam;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
import javax.transaction.UserTransaction;
/**
* AnnotationTest
*
* Use servlet 3.0 annotations from within Jetty.
*
* Also uses servlet 2.5 resource injection and lifecycle callbacks
*/
@RunAs("special")
@WebServlet(urlPatterns = {"/","/test/*"}, name="AnnotationTest", initParams={@WebInitParam(name="fromAnnotation", value="xyz")})
@DeclareRoles({"user","client"})
public class AnnotationTest extends HttpServlet
{
private DataSource myDS;
@Resource(mappedName="UserTransaction")
private UserTransaction myUserTransaction;
@Resource(mappedName="maxAmount")
private Double maxAmount;
@Resource(mappedName="jdbc/mydatasource")
public void setMyDatasource(DataSource ds)
{
myDS=ds;
}
@PostConstruct
private void myPostConstructMethod ()
{
System.err.println("PostConstruct called");
}
@PreDestroy
private void myPreDestroyMethod()
{
System.err.println("PreDestroy called");
}
public void init(ServletConfig config) throws ServletException
{
super.init(config);
}
public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
{
doGet(request, response);
}
public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException
{
try
{
response.setContentType("text/html");
ServletOutputStream out = response.getOutputStream();
out.println("&lt;html&gt;");
out.println("&lt;body&gt;");
out.println("&lt;h1&gt;Results&lt;/h1&gt;");
out.println(myDS.toString());
out.println("&lt;br/&gt;");
out.println(maxAmount.toString());
out.println("&lt;/body&gt;");
out.println("&lt;/html&gt;");
out.flush();
}
catch (Exception e)
{
throw new ServletException(e);
}
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="jmx-chapter">Java Management Extensions (JMX)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <a href="http://java.sun.com/products/JavaManagement/">Java Management Extensions (JMX) API</a> is a standard API for managing and monitoring resources such as applications, devices, services, and the Java virtual machine.</p>
</div>
<div class="paragraph">
<p>Typical uses of the JMX technology include:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Consulting and changing application configuration</p>
</li>
<li>
<p>Accumulating and making available statistics about application behavior</p>
</li>
<li>
<p>Notifying of state changes and erroneous conditions</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The JMX API includes remote access, so a remote management program can interact with a running application for these purposes.</p>
</div>
<div class="sect2">
<h3 id="using-jmx">Using JMX with Jetty</h3>
<div class="paragraph">
<p>Jetty&#8217;s architecture is based on POJO components (see <a href="#basic-architecture">[basic-architecture]</a>).
These components are organized in a tree and each component may have a lifecycle that spans the <code>Server</code> lifetime, or a web application lifetime, or even shorter lifetimes such as that of a TCP connection.</p>
</div>
<div class="paragraph">
<p>Every time a component is added or removed from the component tree, an event is emitted, and <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/component/Container.html"><code>Container.Listener</code></a> implementations can listen to those events and perform additional actions.</p>
</div>
<div class="paragraph">
<p>One such <code>Container.Listener</code> is <code>MBeanContainer</code> that uses <code>ObjectMBean</code> to create an MBean from an arbitrary POJO, and register/unregister the MBean to/from the platform <code>MBeanServer</code>.</p>
</div>
<div class="paragraph">
<p>Jetty components are annotated with <a href="#jetty-jmx-annotations">Jetty JMX Annotations</a> and provide specific JMX details so that <code>ObjectMBean</code> can build a more precise representation of the JMX metadata associated with the component POJO.</p>
</div>
<div class="paragraph">
<p>Therefore, when a component is added to the component tree, <code>MBeanContainer</code> is notified, it creates the MBean from the component POJO and registers it to the <code>MBeanServer</code>.
Similarly, when a component is removed from the tree, <code>MBeanContainer</code> is notified, and unregisters the MBean from the <code>MBeanServer</code>.</p>
</div>
<div class="paragraph">
<p>The Jetty MBeans can be accessed via any JMX console such as Java Mission Control (JMC), VisualVM, JConsole or others.</p>
</div>
<div class="sect3">
<h4 id="configuring-jmx">Configuring JMX</h4>
<div class="paragraph">
<p>This guide describes the various ways to initialize and configure the Jetty JMX integration.
Configuring the Jetty JMX integration only registers the Jetty MBeans into the platform <code>MBeanServer</code>, and therefore the MBeans can only be accessed locally (from the same machine), not from remote machines.</p>
</div>
<div class="paragraph">
<p>This means that this configuration is enough for development, where you have easy access (with graphical user interface) to the machine where Jetty runs, but it is typically not enough when the machine Jetty where runs is remote, or only accessible via SSH or otherwise without graphical user interface support.
In these cases, you have to enable <a href="#jmx-remote-access">JMX Remote Access</a>.</p>
</div>
<div class="sect4">
<h5 id="jmx-standalone-jetty">Standalone Jetty Server</h5>
<div class="paragraph">
<p>JMX is not enabled by default in the Jetty distribution.
To enable JMX in the Jetty distribution run the following, where <code>{$jetty.home}</code> is the directory where you have the Jetty distribution installed, and <code>${jetty.base}</code> is the directory where you have your Jetty configuration (see <a href="#startup-base-and-home">the documentation for Jetty base vs. home examples</a>):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx</code></pre>
</div>
</div>
<div class="paragraph">
<p>Running the above command will append the available configurable elements of the <code>jmx</code> module to the <code>{$jetty.base}/start.ini</code> file, or create the <code>${jetty.base}/start.d/jmx.ini</code> file.</p>
</div>
</div>
<div class="sect4">
<h5 id="jmx-embedded-jetty">Embedded Jetty Server</h5>
<div class="paragraph">
<p>When running Jetty embedded into an application, create and configure an <code>MBeanContainer</code> instance as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">Server server = new Server();
// Setup JMX.
MBeanContainer mbeanContainer = new MBeanContainer(ManagementFactory.getPlatformMBeanServer());
server.addBean(mbeanContainer);
// Export the loggers as MBeans.
server.addBean(Log.getLog());</code></pre>
</div>
</div>
<div class="paragraph">
<p>Because logging is initialized prior to the <code>MBeanContainer</code> (even before the <code>Server</code> itself), it is necessary to register the logger manually via <code>server.addBean()</code> so that the loggers may show up in the JMX tree as MBeans.</p>
</div>
</div>
<div class="sect4">
<h5 id="jmx-jetty-maven-plugin">Using the Jetty Maven Plugin with JMX</h5>
<div class="paragraph">
<p>If you are using the <a href="#jetty-maven-plugin">Jetty Maven plugin</a> you should copy the <code>${jetty.home}/etc/jetty-jmx.xml</code> file into your webapp project somewhere, such as <code>src/main/config/etc/</code>, then add a <code>&lt;jettyXml&gt;</code> element to the <code>&lt;configuration&gt;</code> element of the Jetty Maven Plugin:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;plugin&gt;
&lt;groupid&gt;org.eclipse.jetty&lt;/groupid&gt;
&lt;artifactid&gt;jetty-maven-plugin&lt;/artifactid&gt;
&lt;version&gt;10.0.0-SNAPSHOT&lt;/version&gt;
&lt;configuration&gt;
&lt;scanintervalseconds&gt;10&lt;/scanintervalseconds&gt;
&lt;jettyXml&gt;src/main/config/etc/jetty-jmx.xml&lt;/jettyXml&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="accessing-jetty-mbeans">Using JConsole or Java Mission Control to Access Jetty MBeans</h4>
<div class="paragraph">
<p>The simplest way to access the MBeans that Jetty publishes is to use <a href="#jetty-jconsole">Java Mission Control (JMC) or JConsole.</a></p>
</div>
<div class="paragraph">
<p>Both these tools can connect to local or remote JVMs to display the MBeans.</p>
</div>
<div class="paragraph">
<p>For local access, you just need to start JConsole or JMC and then choose from their user interface the local JVM you want to connect to.</p>
</div>
<div class="paragraph">
<p>For remote access, you need first to enable JMX Remote Access in Jetty.</p>
</div>
</div>
<div class="sect3">
<h4 id="jmx-remote-access">Enabling JMX Remote Access</h4>
<div class="paragraph">
<p>There are two ways of enabling remote connectivity so that JConsole or JMC can connect to the remote JVM to visualize MBeans.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Use the <code>com.sun.management.jmxremote</code> system property on the command line.
Unfortunately, this solution does not work well with firewalls and is not flexible.</p>
</li>
<li>
<p>Use Jetty&#8217;s <code>jmx-remote</code> module or - equivalently - the <code>ConnectorServer</code> class.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><code>ConnectorServer</code> will use by default RMI to allow connection from remote clients,
and it is a wrapper around the standard JDK class <code>JMXConnectorServer</code>, which is the class that provides remote access to JMX clients.</p>
</div>
<div class="paragraph">
<p>Connecting to the remote JVM is a two step process:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>First, the client will connect to the RMI <em>registry</em> to download the RMI stub for the <code>JMXConnectorServer</code>; this RMI stub contains the IP address and port to connect to the RMI server, i.e. the remote <code>JMXConnectorServer</code>.</p>
</li>
<li>
<p>Second, the client uses the RMI stub to connect to the RMI <em>server</em> (i.e. the remote <code>JMXConnectorServer</code>) typically on an address and port that may be different from the RMI registry address and port.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The configuration for the RMI registry and the RMI server is specified by a <code>JMXServiceURL</code>.
The string format of an RMI <code>JMXServiceURL</code> is:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">service:jmx:rmi://&lt;rmi_server_host&gt;:&lt;rmi_server_port&gt;/jndi/rmi://&lt;rmi_registry_host&gt;:&lt;rmi_registry_port&gt;/jmxrmi</code></pre>
</div>
</div>
<div class="paragraph">
<p>Default values are:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">rmi_server_host = localhost
rmi_server_port = 1099
rmi_registry_host = localhost
rmi_registry_port = 1099</code></pre>
</div>
</div>
<div class="paragraph">
<p>With the default configuration, only clients that are local to the server machine can connect to the RMI registry and RMI server - this is done for security reasons.
With this configuration it would still be possible to access the MBeans from remote using a <a href="#jmx-remote-access-ssh-tunnel">SSH tunnel.</a></p>
</div>
<div class="paragraph">
<p>By specifying an appropriate <code>JMXServiceURL</code>, you can fine tune the network interfaces the RMI registry and the RMI server bind to, and the ports that the RMI registry and the RMI server listen to.
The RMI server and RMI registry hosts and ports can be the same (as in the default configuration) because RMI is able to multiplex traffic arriving to a port to multiple RMI objects.</p>
</div>
<div class="paragraph">
<p>If you need to allow JMX remote access through a firewall, you must open both the RMI registry and the RMI server ports.</p>
</div>
<div class="paragraph">
<p>Examples:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">service:jmx:rmi:///jndi/rmi:///jmxrmi
rmi_server_host = local host address
rmi_server_port = randomly chosen
rmi_registry_host = local host address
rmi_registry_port = 1099
service:jmx:rmi://0.0.0.0:1099/jndi/rmi://0.0.0.0:1099/jmxrmi
rmi_server_host = any address
rmi_server_port = 1099
rmi_registry_host = any address
rmi_registry_port = 1099
service:jmx:rmi://localhost:1100/jndi/rmi://localhost:1099/jmxrmi
rmi_server_host = loopback address
rmi_server_port = 1100
rmi_registry_host = loopback address
rmi_registry_port = 1099</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>When <code>ConnectorServer</code> is started, its RMI stub is exported to the RMI registry.
The RMI stub contains the IP address and port to connect to the RMI object, but the IP address is typically the machine host name, not the host specified in the <code>JMXServiceURL</code>.</p>
</div>
<div class="paragraph">
<p>To control the IP address stored in the RMI stub you need to set the system property <code>java.rmi.server.hostname</code> with the desired value.
This is especially important when binding the RMI server host to the loopback address for security reasons. See also <a href="#jmx-remote-access-ssh-tunnel">JMX Remote Access via SSH Tunnel.</a></p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5>Enabling JMX Remote Access in Standalone Jetty Server</h5>
<div class="paragraph">
<p>Similarly to <a href="#jmx-standalone-jetty">enabling JMX in a standalone Jetty server</a>, you enable the <code>jmx-remote</code> module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cd ${jetty.base}
$ java -jar {$jetty.home}/start.jar --add-to-start=jmx-remote</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Enabling JMX Remote Access in Embedded Jetty</h5>
<div class="paragraph">
<p>When running Jetty embedded into an application, create and configure a <code>ConnectorServer</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">Server server = new Server();
// Setup JMX
MBeanContainer mbeanContainer = new MBeanContainer(ManagementFactory.getPlatformMBeanServer());
server.addBean(mbeanContainer);
// Setup ConnectorServer
JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1999, "/jndi/rmi:///jmxrmi");
ConnectorServer jmxServer = new ConnectorServer(jmxURL, "org.eclipse.jetty.jmx:name=rmiconnectorserver");
server.addBean(jmxServer);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>JMXServiceURL</code> above specifies that the RMI server binds to the wildcard address on port 1999, while the RMI registry binds to the wildcard address on port 1099 (the default RMI registry port).</p>
</div>
</div>
<div class="sect4">
<h5 id="jmx-remote-access-authorization">JMX Remote Access Authorization</h5>
<div class="paragraph">
<p>The standard <code>JMXConnectorServer</code> provides several options to authorize access.
For a complete guide to controlling authentication and authorization in JMX, see <a href="https://blogs.oracle.com/lmalventosa/entry/jmx_authentication_authorization">Authentication and Authorization in JMX RMI connectors</a>.</p>
</div>
<div class="paragraph">
<p>To authorize access to the <code>JMXConnectorServer</code> you can use this configuration, where the <code>jmx.password</code> and <code>jmx.access</code> files have the format specified in the blog entry above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer"&gt;
&lt;Arg&gt;
&lt;New class="javax.management.remote.JMXServiceURL"&gt;
&lt;Arg type="java.lang.String"&gt;rmi&lt;/Arg&gt;
&lt;Arg type="java.lang.String" /&gt;
&lt;Arg type="java.lang.Integer"&gt;1099&lt;/Arg&gt;
&lt;Arg type="java.lang.String"&gt;/jndi/rmi:///jmxrmi&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;Arg&gt;
&lt;Map&gt;
&lt;Entry&gt;
&lt;Item&gt;jmx.remote.x.access.file&lt;/Item&gt;
&lt;Item&gt;
&lt;New class="java.lang.String"&gt;&lt;Arg&gt;&lt;Property name="jetty.base" default="." /&gt;/resources/jmx.access&lt;/Arg&gt;&lt;/New&gt;
&lt;/Item&gt;
&lt;/Entry&gt;
&lt;Entry&gt;
&lt;Item&gt;jmx.remote.x.password.file&lt;/Item&gt;
&lt;Item&gt;
&lt;New class="java.lang.String"&gt;&lt;Arg&gt;&lt;Property name="jetty.base" default="." /&gt;/resources/jmx.password&lt;/Arg&gt;&lt;/New&gt;
&lt;/Item&gt;
&lt;/Entry&gt;
&lt;/Map&gt;
&lt;/Arg&gt;
&lt;Arg&gt;org.eclipse.jetty.jmx:name=rmiconnectorserver&lt;/Arg&gt;
&lt;Call name="start" /&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Similarly, in code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi:///jmxrmi");
Map&lt;String, Object&gt; env = new HashMap&lt;&gt;();
env.put("jmx.remote.x.access.file", "resources/jmx.access");
env.put("jmx.remote.x.password.file", "resources/jmx.password");
ConnectorServer jmxServer = new ConnectorServer(jmxURL, env, "org.eclipse.jetty.jmx:name=rmiconnectorserver");
jmxServer.start();</code></pre>
</div>
</div>
<div class="paragraph">
<p>Calling <code>ConnectorServer.start()</code> may be explicit as in the examples above, or can be skipped when adding the <code>ConnectorServer</code> as a bean to the <code>Server</code>, so that starting the <code>Server</code> will also start the <code>ConnectorServer</code>.</p>
</div>
</div>
<div class="sect4">
<h5>Securing JMX Remote Access with TLS</h5>
<div class="paragraph">
<p>The JMX communication via RMI happens by default in clear-text.</p>
</div>
<div class="paragraph">
<p>It is possible to configure the <code>ConnectorServer</code> with a <code>SslContextFactory</code> so that the JMX communication via RMI is encrypted:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="ConnectorServer" class="org.eclipse.jetty.jmx.ConnectorServer"&gt;
&lt;Arg&gt;
&lt;New class="javax.management.remote.JMXServiceURL"&gt;
&lt;Arg type="java.lang.String"&gt;rmi&lt;/Arg&gt;
&lt;Arg type="java.lang.String" /&gt;
&lt;Arg type="java.lang.Integer"&gt;1099&lt;/Arg&gt;
&lt;Arg type="java.lang.String"&gt;/jndi/rmi:///jmxrmi&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;Arg /&gt;
&lt;Arg&gt;org.eclipse.jetty.jmx:name=rmiconnectorserver&lt;/Arg&gt;
&lt;Arg&gt;&lt;Ref refid="sslContextFactory" /&gt;&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Similarly, in code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">SslContextFactory.Server sslContextFactory = new SslContextFactory.Server();
sslContextFactory.setKeyStorePath("/path/to/keystore");
sslContextFactory.setKeyStorePassword("secret");
JMXServiceURL jmxURL = new JMXServiceURL("rmi", null, 1099, "/jndi/rmi:///jmxrmi");
ConnectorServer jmxServer = new ConnectorServer(jmxURL, null, "org.eclipse.jetty.jmx:name=rmiconnectorserver", sslContextFactory);</code></pre>
</div>
</div>
<div class="paragraph">
<p>It is possible to use the same <code>SslContextFactory</code> used to configure the Jetty <code>ServerConnector</code> that supports TLS for the HTTP protocol.
This is used in the XML example above: the <code>SslContextFactory</code> configured for the TLS <code>ServerConnector</code> is registered with an id of <code>sslContextFactory</code> which is referenced in the XML via the <code>Ref</code> element.</p>
</div>
<div class="paragraph">
<p>The keystore must contain a valid certificate signed by a Certification Authority.</p>
</div>
<div class="paragraph">
<p>The RMI mechanic is the usual one: the RMI client (typically a monitoring console) will connect first to the RMI registry (using TLS), download the RMI server stub that contains the address and port of the RMI server to connect to, then connect to the RMI server (using TLS).</p>
</div>
<div class="paragraph">
<p>This also mean that if the RMI registry and the RMI server are on different hosts, the RMI client must have available the cryptographic material to validate both hosts.</p>
</div>
<div class="paragraph">
<p>Having certificates signed by a Certification Authority simplifies by a lot the configuration needed to get the JMX communication over TLS working properly.</p>
</div>
<div class="paragraph">
<p>If that is not the case (for example the certificate is self-signed), then you need to specify the required system properties that allow RMI (especially when acting as an RMI client) to retrieve the cryptographic material necessary to establish the TLS connection.</p>
</div>
<div class="paragraph">
<p>For example, trying to connect using the JDK standard <code>JMXConnector</code> with both the RMI server and the RMI registry to <code>domain.com</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">// System properties necessary for an RMI client to trust a self-signed certificate.
System.setProperty("javax.net.ssl.trustStore", "/path/to/trustStore");
System.setProperty("javax.net.ssl.trustStorePassword", "secret");
JMXServiceURL jmxURL = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://domain.com:1100/jmxrmi")
Map&lt;String, Object&gt; clientEnv = new HashMap&lt;&gt;();
// Required to connect to the RMI registry via TLS.
clientEnv.put(ConnectorServer.RMI_REGISTRY_CLIENT_SOCKET_FACTORY_ATTRIBUTE, new SslRMIClientSocketFactory());
try (JMXConnector client = JMXConnectorFactory.connect(jmxURL, clientEnv))
{
Set&lt;ObjectName&gt; names = client.getMBeanServerConnection().queryNames(null, null);
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Similarly, to launch JMC:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">$ jmc -vmargs -Djavax.net.ssl.trustStore=/path/to/trustStore -Djavax.net.ssl.trustStorePassword=secret</code></pre>
</div>
</div>
<div class="paragraph">
<p>Note that these system properties are required when launching the <code>ConnectorServer</code> too, on the server, because it acts as an RMI client with respect to the RMI registry.</p>
</div>
</div>
<div class="sect4">
<h5 id="jmx-remote-access-ssh-tunnel">JMX Remote Access with Port Forwarding via SSH Tunnel</h5>
<div class="paragraph">
<p>You can access JMX MBeans on a remote machine when the RMI ports are not open, for example because of firewall policies, but you have SSH access to the machine using local port forwarding via a SSH tunnel.</p>
</div>
<div class="paragraph">
<p>In this case you want to configure the <code>ConnectorServer</code> with a <code>JMXServiceURL</code> that binds the RMI server and the RMI registry to the loopback interface only: <code>service:jmx:rmi://localhost:1099/jndi/rmi://localhost:1099/jmxrmi</code>.</p>
</div>
<div class="paragraph">
<p>Then you setup the local port forwarding with the SSH tunnel:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ ssh -L 1099:localhost:1099 &lt;user&gt;@&lt;machine_host&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now you can use JConsole or JMC to connect to <code>localhost:1099</code> on your local computer.
The traffic will be forwarded to <code>machine_host</code> and when there, SSH will forward the traffic to <code>localhost:1099</code>, which is exactly where the <code>ConnectorServer</code> listens.</p>
</div>
<div class="paragraph">
<p>When you configure <code>ConnectorServer</code> in this way, you must set the system property <code>-Djava.rmi.server.hostname=localhost</code>, on the server.</p>
</div>
<div class="paragraph">
<p>This is required because when the RMI server is exported, its address and port are stored in the RMI stub. You want the address in the RMI stub to be <code>localhost</code> so that when the RMI stub is downloaded to the remote client, the RMI communication will go through the SSH tunnel.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jetty-jmx-annotations">Jetty JMX Annotations</h3>
<div class="paragraph">
<p>When the <code>jetty-jmx</code> libraries are present on startup and the wiring is enabled for exposing Jetty MBeans to JMX, there are three annotations that govern when and how MBeans are created and exposed.</p>
</div>
<div class="sect3">
<h4 id="jmx-annotation-introspection">Annotation Introspection</h4>
<div class="paragraph">
<p>When JMX is configured and enabled in Jetty, any time an object is registered with the Server it is introspected as a potential MBean to be exposed.
This introspection proceeds as follows assuming the class is named <code>com.acme.Foo</code>:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>All influences for <code>com.acme.Foo</code> determined.
These include each class in the chain of super classes, and by convention each of these classes following a form of <code>com.acme.jmx.FooMBean</code>.
All super classes and their corresponding MBean representations are then used in the next step.</p>
</li>
<li>
<p>Each potential influencing class is checked for the <code>@ManagedObject</code> annotation.
Should this annotation exist at any point in the chain of influencers then an MBran is created with the description of the version <code>@ManagedObject</code> discovered.</p>
</li>
<li>
<p>Once a MBean has been created for an object then each potential influencing object is introspected for <code>@ManagedAttribute</code> and <code>@ManagedOperation</code> annotations and the corresponding type is exposed to the MBean.</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>The convention of looking for <code>@ManagedObject</code> annotations on <code>.jmx.ClassMBean</code> allows for a normal POJOs to be wrapped in an MBean without itself without requiring it being marked up with annotations.
Since the POJO is passed to these wrapped derived Mbean instances and is an internal variable then the MBean can be used to better expose a set of attributes and operations that may not have been anticipated when the original object was created.</p>
</div>
</div>
<div class="sect3">
<h4 id="jmx-managed-object">@ManagedObject</h4>
<div class="paragraph">
<p>The <code>@ManagedObject</code> annotation is used on a class at the top level to indicate that it should be exposed as an MBean.
It has only one attribute to it which is used as the description of the MBean.
Should multiple <code>@ManagedObject</code> annotations be found in the chain of influence then the first description is used.</p>
</div>
<div class="paragraph">
<p>The list of attributes available are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">value</dt>
<dd>
<p>The description of the Managed Object.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="jmx-managed-attribute">@ManagedAttribute</h4>
<div class="paragraph">
<p>The <code>@ManagedAttribute</code> annotation is used to indicate that a given method exposes a JMX attribute.
This annotation is placed always on the reader method of a given attribute.
Unless it is marked as read-only in the configuration of the annotation a corresponding setter is looked for following normal naming conventions.
For example if this annotation is on a method called <code>getFoo()</code> then a method called <code>setFoo()</code> would be looked for and if found wired automatically into the JMX attribute.</p>
</div>
<div class="paragraph">
<p>The list of attributes available are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">value</dt>
<dd>
<p>The description of the Managed Attribute.</p>
</dd>
<dt class="hdlist1">name</dt>
<dd>
<p>The name of the Managed Attribute.</p>
</dd>
<dt class="hdlist1">proxied</dt>
<dd>
<p>Value is true if the corresponding MBean for this object contains the method of this JMX attribute in question.</p>
</dd>
<dt class="hdlist1">readonly</dt>
<dd>
<p>By default this value is false which means that a corresponding setter will be looked for an wired into the attribute should one be found.
Setting this to true make the JMX attribute read only.</p>
</dd>
<dt class="hdlist1">setter</dt>
<dd>
<p>This attribute can be used when the corresponding setter for a JMX attribute follows a non-standard naming convention and it should still be exposed as the setter for the attribute.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="jmx-managed-operation">@ManagedOperation</h4>
<div class="paragraph">
<p>The <code>@ManagedOperation</code> annotation is used to indicate that a given method should be considered a JMX operation.</p>
</div>
<div class="paragraph">
<p>The list of attributes available are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">value</dt>
<dd>
<p>The description of the Managed Operation.</p>
</dd>
<dt class="hdlist1">impact</dt>
<dd>
<p>The impact of an operation.
By default this value is "UNKNOWN" and acceptable values are "ACTION", "INFO", "ACTION_INFO" and should be used according to their definitions with JMX.</p>
</dd>
<dt class="hdlist1">proxied</dt>
<dd>
<p>Value is true if the corresponding MBean for this object contains the method of this JMX operation in question.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="jmx-name-annotation">@Name</h4>
<div class="paragraph">
<p>A fourth annotation is often used in conjunction with the JMX annotations mentioned above.
This annotation is used to describe variables in method signatures so that when rendered into tools like JConsole it is clear what the parameters are.
For example:</p>
</div>
<div class="paragraph">
<p>The list of attributes available are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">value</dt>
<dd>
<p>The name of the parameter.</p>
</dd>
<dt class="hdlist1">description</dt>
<dd>
<p>The description of the parameter.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="jmx-annotation-example">Example</h4>
<div class="paragraph">
<p>The following is an example of each of the annotations mentioned above in practice.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">package com.acme;
import org.eclipse.jetty.util.annotation.ManagedAttribute;
import org.eclipse.jetty.util.annotation.ManagedObject;
import org.eclipse.jetty.util.annotation.ManagedOperation;
import org.eclipse.jetty.util.annotation.Name;
@ManagedObject("Test MBean Annotations")
public class Derived extends Base implements Signature
{
String fname="Full Name";
@ManagedAttribute(value="The full name of something", name="fname")
public String getFullName()
{
return fname;
}
public void setFullName(String name)
{
fname=name;
}
@ManagedOperation("Doodle something")
public void doodle(@Name(value="doodle", description="A description of the argument") String doodle)
{
System.err.println("doodle "+doodle);
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jetty-jconsole">Managing Jetty with JConsole and JMC</h3>
<div class="paragraph">
<p>JConsole and the Java Mission Control (JMX) are graphical tools; they allow you to remotely manage and monitor your server and web application status using JMX.
When following the instructions given below, please also ensure that you make any necessary changes to any anti-virus software you may be using which may prevent JConsole or JMC from running.</p>
</div>
<div class="sect3">
<h4>Starting Jetty Standalone</h4>
<div class="paragraph">
<p>The simplest way to enable support is to add the JMX-Remote support module to your <code>{$jetty.base}</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">[mybase]$ java /opt/jetty-dist/start.jar --add-to-start=jmx-remote, jmx
INFO: jmx-remote initialised in ${jetty.base}/start.ini
INFO: jmx initialised in ${jetty.base}/start.ini</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then open the <code>{$jetty.base}/start.ini</code> (or <code>{$jetty.base}/start.d/jmx-remote.ini</code>) file and edit the properties to suit your needs:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">#
# Initialize module jmx-remote
#
--module=jmx-remote
## JMX Configuration
## Enable for an open port accessible by remote machines
jetty.jmxrmihost=localhost
jetty.jmxrmiport=1099</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="jetty-jconsole-monitoring">Monitoring Jetty with JConsole</h4>
<div class="paragraph">
<p>To monitor Jetty&#8217;s server status with JConsole, start Jetty and then start JConsole by typing <code>jconsole</code> on the command line.</p>
</div>
<div class="sect4">
<h5>Connecting to your server process</h5>
<div class="paragraph">
<p>After you start Jetty, you will see a dialog box in JConsole with a list of running processes to which you can connect.
It should look something like so:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/jconsole1.jpg" alt="image" width="576"></span></p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you don&#8217;t see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
This forces JConsole to refresh the list, and recognize your newly-started Jetty process.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Select the start.jar entry and click the "Connect" button.
A new JConsole window opens:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/jconsole2.jpg" alt="image" width="576"></span></p>
</div>
<div class="paragraph">
<p>From this window you can monitor memory usage, thread usage, classloading and VM statistics.
You can also perform operations such as a manual garbage collect.
JConsole is an extremely powerful and useful tool.</p>
</div>
</div>
</div>
<div class="sect3">
<h4>Managing Jetty Objects with JConsole</h4>
<div class="paragraph">
<p>The MBean tab of JConsole allows access to managed objects within the Java application, including MBeans the JVM provides.
If you also want to interact with the Jetty JMX implementation via JConsole, you need to start Jetty JMX in a form that JConsole can access.
See <a href="#using-jmx">Using JMX with Jetty</a> for more information.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/jconsole3.png" alt="image" width="576"></span></p>
</div>
</div>
<div class="sect3">
<h4 id="jetty-jmc-monitoring">Monitoring Jetty with JMC</h4>
<div class="paragraph">
<p>To monitor Jetty&#8217;s server status with JMC, start Jetty and then start JMC by typing <code>jmc</code> on the command line.</p>
</div>
<div class="sect4">
<h5>Connecting to your server process</h5>
<div class="paragraph">
<p>After you start Jetty, you will see a dialog box in JMC with a list of running processes to which you can connect.
It should look something like so:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/jmc1.png" alt="image" width="576"></span></p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you don&#8217;t see your Jetty process in the list of processes you can connect to, quickly switch tabs, or close and reopen a new "New Connection" dialog window.
This forces JMC to refresh the list, and recognize your newly-started Jetty process.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>Double-click the start.jar entry or right-click the start.jar entry and select "Start JMX Console".
A new JMC window opens on the right:</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/jmc2.png" alt="image" width="576"></span></p>
</div>
<div class="paragraph">
<p>From this window you can monitor memory usage, thread usage, classloading and VM statistics.
You can also perform operations such as a manual garbage collect.
JMC is an extremely powerful and useful tool.</p>
</div>
</div>
</div>
<div class="sect3">
<h4>Managing Jetty Objects with JConsole</h4>
<div class="paragraph">
<p>The MBean tab of JMC allows access to managed objects within the Java application, including MBeans the JVM provides.
If you also want to interact with the Jetty JMX implementation via JMC, you need to start Jetty JMX in a form that JMC can access.
See <a href="#using-jmx">Using JMX with Jetty</a> for more information.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/jmc3.png" alt="image" width="576"></span></p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="jndi">Configuring JNDI</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Jetty supports <code>java:comp/env</code> lookups in webapps.
This is an optional feature for which some configuration is required.</p>
</div>
<div class="sect2">
<h3 id="jndi-quick-setup">Quick Setup</h3>
<div class="paragraph">
<p>If you are using the standard distribution of Jetty, you must enable the <em>JNDI</em> <a href="#startup-modules">module</a> to obtain Jetty&#8217;s JNDI implementation, and the <strong>plus</strong> <a href="#startup-modules">module</a> which provides classes for interacting with JNDI.
As the <em>plus</em> module depends on the <em>JNDI</em> module, you only need to enable the <em>plus</em> module to enable both.
Assuming you have Jetty installed in <code>/opt/jetty</code>, and you have made a <a href="#startup-base-and-home">jetty base</a> in <code>/opt/jetty/my-base</code>, do:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">cd /opt/jetty
cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=plus</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can now start Jetty and use JNDI within your webapps.
See <a href="#using-jndi">Using JNDI</a> for information on how to add entries to the JNDI environment that Jetty can look up within webapps.</p>
</div>
<div class="paragraph">
<p>If you have extra jars associated with your JNDI resources, for example a database driver jar, and you haven&#8217;t made a custom <a href="#startup-modules">module</a> for it, you can put the jars into your <code>{$jetty base}ext/</code> directory.
You will then need to enable the <em>ext</em> module to ensure the jars in the <code>ext/</code> directory are on the classpath.
Assuming you have Jetty installed in <code>/opt/jetty</code>, and you have made a <a href="#startup-base-and-home">jetty base</a> in <code>/opt/jetty/my-base</code>, do:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">cd /opt/jetty
cd my-base
java -jar $JETTY_HOME/start.jar --add-to-start=ext</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="using-jetty-jndi">Working with Jetty JNDI</h3>
<div class="sect3">
<h4>Defining the web.xml</h4>
<div class="paragraph">
<p>You can configure naming resources to reference in a <code>web.xml</code> file and access from within the <code>java:comp/env</code> naming environment of the webapp during execution.
Specifically, you can configure support for the following <code>web.xml</code> elements:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;env-entry/&gt;
&lt;resource-ref/&gt;
&lt;resource-env-ref/&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p><a href="#configuring-jndi-env-entries">Configuring env-entries</a> shows you how to set up overrides for <code>env-entry</code> elements in <code>web.xml</code>, while <a href="#configuring-resource-refs-and-resource-env-refs">Configuring <code>resource-refs</code> and <code>resource-env-refs</code></a> discusses how to configure support resources such as <code>javax.sql.DataSource</code>.</p>
</div>
<div class="paragraph">
<p>You can also plug a JTA <code>javax.transaction.UserTransaction</code> implementation into Jetty so that webapps can look up <code>java:comp/UserTransaction</code> to obtain a distributed transaction manager: see <a href="#configuring-xa-transactions">Configuring XA Transactions</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="defining-jndi-naming-entries">Declaring Resources</h4>
<div class="paragraph">
<p>You must declare the objects you want bound into the Jetty environment so that you can then hook into your webapp via <code>env-entry</code>, <code>resource-ref</code> and <code>resource-env-refs</code> in <code>web.xml</code>.
You create these bindings by using declarations of the following types:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>org.eclipse.jetty.plus.jndi.EnvEntry</code></dt>
<dd>
<p>For <code>env-entry</code> type of entries</p>
</dd>
<dt class="hdlist1"><code>org.eclipse.jetty.plus.jndi.Resource</code></dt>
<dd>
<p>For all other type of resources</p>
</dd>
<dt class="hdlist1"><code>org.eclipse.jetty.plus.jndi.Transaction</code></dt>
<dd>
<p>For a JTA manager</p>
</dd>
<dt class="hdlist1"><code>org.eclipse.jetty.plus.jndi.Link</code></dt>
<dd>
<p>For the link between a <code>web.xml</code> resource name and a naming entry</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Declarations of each of these types follow the same general pattern:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.plus.jndi.xxxx"&gt;
&lt;Arg&gt;&lt;!-- scope --&gt;&lt;/Arg&gt;
&lt;Arg&gt;&lt;!-- name --&gt;&lt;/Arg&gt;
&lt;Arg&gt;&lt;!-- value --&gt;&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can place these declarations into three different files, depending on your needs and the <a href="#jndi-name-scope">scope</a> of the resources being declared.</p>
</div>
</div>
<div class="sect3">
<h4 id="jndi-where-to-declare">Deciding Where to Declare Resources</h4>
<div class="paragraph">
<p>You can define naming resources in three places:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><em>jetty.xml</em></dt>
<dd>
<p>Naming resources defined in a <code>jetty.xml</code> file are <a href="#jndi-name-scope">scoped</a> at either the JVM level or the Server level.
The classes for the resource must be visible at the Jetty container level.
If the classes for the resource only exist inside your webapp, you must declare it in a <code>WEB-INF/jetty-env.xml</code> file.</p>
</dd>
<dt class="hdlist1">WEB-INF/jetty-env.xml</dt>
<dd>
<p>Naming resources in a <code>WEB-INF/jetty-env.xml</code> file are <a href="#jndi-name-scope">scoped</a> to the web app in which the file resides.
While you can enter JVM or Server scopes if you choose, we do not recommend doing so.
The resources defined here may use classes from inside your webapp.
This is a Jetty-specific mechanism.</p>
</dd>
<dt class="hdlist1">Context xml file</dt>
<dd>
<p>Entries in a context xml file should be <a href="#jndi-name-scope">scoped</a> at the level of the webapp to which they apply, although you can supply a less strict scoping level of Server or JVM if you choose.
As with resources declared in a <code>jetty.xml</code> file, classes associated with the resource must be visible on the container&#8217;s classpath.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="jndi-name-scope">Scope of Resource Names</h4>
<div class="paragraph">
<p>Naming resources within Jetty belong to one of three different scopes, in increasing order of restrictiveness:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">JVM scope</dt>
<dd>
<p>The name is unique across the JVM instance, and is visible to all application code.
You represent this scope by a <code>null</code> first parameter to the resource declaration.
For example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt; &lt;!-- empty arg --&gt;
&lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
&lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</dd>
<dt class="hdlist1">Server scope</dt>
<dd>
<p>The name is unique to a Server instance, and is only visible to code associated with that instance.
You represent this scope by referencing the Server instance as the first parameter to the resource declaration.
For example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id="Server" class="org.eclipse.jetty.Server"&gt;
&lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid="Server"/&gt;&lt;/Arg&gt; &lt;!-- reference to Server instance --&gt;
&lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
&lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</dd>
<dt class="hdlist1">Webapp scope</dt>
<dd>
<p>The name is unique to the WebAppContext instance, and is only visible to code associated with that instance.
You represent this scope by referencing the <code>WebAppContext</code> instance as the first parameter to the resource declaration.
For example:</p>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid='wac'/&gt;&lt;/Arg&gt; &lt;!-- reference to WebAppContext --&gt;
&lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
&lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="binding-objects-into-jetty-jndi">What Can Be Bound as a Resource?</h4>
<div class="paragraph">
<p>You can bind four types of objects into a Jetty JNDI reference:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>An ordinary POJO instance.</p>
</li>
<li>
<p>A <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html">javax.naming.Reference</a> instance.</p>
</li>
<li>
<p>An object instance that implements the <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html">javax.naming.Referenceable</a> interface.</p>
</li>
<li>
<p>A link between a name as referenced in <code>web.xml</code> and as referenced in the Jetty environment.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jndi-configuration">Configuring JNDI</h3>
<div class="sect3">
<h4 id="configuring-jndi-env-entries">Configuring JNDI <em>env-entries</em></h4>
<div class="paragraph">
<p>Sometimes it is useful to pass configuration information to a webapp at runtime that you either cannot or cannot conveniently code into a <code>web.xml</code> env-entry.
In such cases, you can use the <code>org.eclipse.jetty.plus.jndi.EnvEntry</code> class, and even override an entry of the same name in <code>web.xml</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New class="org.eclipse.jetty.plus.jndi.EnvEntry"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;mySpecialValue&lt;/Arg&gt;
&lt;Arg type="java.lang.Integer"&gt;4000&lt;/Arg&gt;
&lt;Arg type="boolean"&gt;true&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This example defines a virtual <code>env-entry</code> called <code>mySpecialValue</code> with value <code>4000</code> that is <a href="#jndi-name-scope">scoped</a> to the JVM.
It is put into JNDI at <code>java:comp/env/mySpecialValue</code> for <em>every</em> web app deployed.
Moreover, the boolean argument indicates that this value overrides an <code>env-entry</code> of the same name in <code>web.xml</code>.
If you don&#8217;t want to override, omit this argument, or set it to <code>false</code>.</p>
</div>
<div class="paragraph">
<p>The Servlet Specification allows binding only the following object types to an <code>env-entry</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>java.lang.String</p>
</li>
<li>
<p>java.lang.Integer</p>
</li>
<li>
<p>java.lang.Float</p>
</li>
<li>
<p>java.lang.Double</p>
</li>
<li>
<p>java.lang.Long</p>
</li>
<li>
<p>java.lang.Short</p>
</li>
<li>
<p>java.lang.Character</p>
</li>
<li>
<p>java.lang.Byte</p>
</li>
<li>
<p>java.lang.Boolean</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>That being said, Jetty is a little more flexible and allows you to also bind custom POJOs, <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Reference.html"><code>javax.naming.References</code></a> and <a href="http://docs.oracle.com/javase/1.5.0/docs/api/javax/naming/Referenceable.html"><code>javax.naming.Referenceables</code></a>.
Be aware that if you take advantage of this feature, your web application is <em>not portable</em>.</p>
</div>
<div class="paragraph">
<p>To use the <code>env-entry</code> configured above, use code in your <code>servlet/filter/etc.</code>, such as:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">import javax.naming.InitialContext;
public class MyClass {
public void myMethod() {
InitialContext ic = new InitialContext();
Integer mySpecialValue = (Integer)ic.lookup("java:comp/env/mySpecialValue");
...
}
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuring-resource-refs-and-resource-env-refs">Configuring <em>resource-refs</em> and <em>resource-env-refs</em></h4>
<div class="paragraph">
<p>You can configure any type of resource that you want to refer to in a <code>web.xml</code> file as a <code>resource-ref</code> or <code>resource-env-ref</code>, using the <code>org.eclipse.jetty.plus.jndi.Resource</code> type of naming entry.
You provide the scope, the name of the object (relative to <code>java:comp/env</code>) and a POJO instance or a <code>javax.naming.Reference</code> instance or <code>javax.naming.Referenceable</code> instance.</p>
</div>
<div class="paragraph">
<p>The <a href="http://jcp.org/aboutJava/communityprocess/pr/jsr244/index.html">J2EE Specification</a> recommends storing DataSources in <code>java:comp/env/jdbc</code>, JMS connection factories under <code>java:comp/env/jms</code>, JavaMail connection factories under <code>java:comp/env/mail</code> and URL connection factories under <code>java:comp/env/url</code>.</p>
</div>
<div class="paragraph">
<p>For example:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 7. DataSource Declaration Conventions</caption>
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Resource Type</th>
<th class="tableblock halign-left valign-top">Name in <code>jetty.xml</code></th>
<th class="tableblock halign-left valign-top">Environment Lookup</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">javax.sql.DataSource</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jdbc/myDB</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">java:comp/env/jdbc/myDB</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">javax.jms.QueueConnectionFactory</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">jms/myQueue</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">java:comp/env/jms/myQueue</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">javax.mail.Session</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">mail/myMailService</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">java:comp/env/mail/myMailService</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="configuring-datasources">Configuring DataSources</h4>
<div class="paragraph">
<p>Here is an example of configuring a <code>javax.sql.DataSource</code>.
Jetty can use any DataSource implementation available on its classpath.
In this example, the DataSource is from the <a href="http://db.apache.org/derby">Derby</a> relational database, but you can use any implementation of a <code>javax.sql.DataSource</code>.
This example configures it as scoped to a web app with the id of <em>wac</em>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;New id="myds" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid="wac"/&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/myds&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.derby.jdbc.EmbeddedDataSource"&gt;
&lt;Set name="DatabaseName"&gt;test&lt;/Set&gt;
&lt;Set name="createDatabase"&gt;create&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The code above creates an instance of <code>org.apache.derby.jdbc.EmbeddedDataSource</code>, calls the two setter methods <code>setDatabaseName("test"),</code> and <code>setCreateDatabase("create"),</code> and binds it into the JNDI scope for the web app.
If you do not have the appropriate <code>resource-ref</code> set up in your <code>web.xml</code>, it is available from application lookups as <code>java:comp/env/jdbc/myds</code>.</p>
</div>
<div class="paragraph">
<p>Here&#8217;s an example <code>web.xml</code> declaration for the datasource above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;resource-ref&gt;
&lt;res-ref-name&gt;jdbc/myds&lt;/res-ref-name&gt;
&lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
&lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>To look up your DataSource in your <code>servlet/filter/etc.</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">import javax.naming.InitialContext;
import javax.sql.DataSource;
public class MyClass {
public void myMethod() {
InitialContext ic = new InitialContext();
DataSource myDS = (DataSource)ic.lookup("java:comp/env/jdbc/myds");
...
}
}</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Careful! When configuring Resources, ensure that the type of object you configure matches the type of object you expect to look up in <code>java:comp/env</code>.
For database connection factories, this means that the object you register as a Resource <em>must</em> implement the <code>javax.sql.DataSource</code> interface.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>For more examples of datasource configurations, see <a href="#jndi-datasource-examples">Datasource Examples</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="configuring-jms-queues-topics-connectionfactories">Configuring JMS Queues, Topics and ConnectionFactories</h4>
<div class="paragraph">
<p>Jetty can bind any implementation of the JMS destinations and connection factories.
You just need to ensure the implementation Jars are available on Jetty&#8217;s classpath.
Here is an example of binding an <a href="http://activemq.apache.org">ActiveMQ</a> in-JVM connection factory:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;New id="cf" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid='wac'/&gt;&lt;/Arg&gt;
&lt;Arg&gt;jms/connectionFactory&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.activemq.ActiveMQConnectionFactory"&gt;
&lt;Arg&gt;vm://localhost?broker.persistent=false&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The entry in <code>web.xml</code> would be:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;resource-ref&gt;
&lt;res-ref-name&gt;jms/connectionFactory&lt;/res-ref-name&gt;
&lt;res-type&gt;javax.jms.ConnectionFactory&lt;/res-type&gt;
&lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuring-mail-with-jndi">Configuring Mail</h4>
<div class="paragraph">
<p>Jetty also provides infrastructure for access to <code>javax.mail.Sessions</code> from within an application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;New id="mail" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid="wac"/&gt;&lt;/Arg&gt;
&lt;Arg&gt;mail/Session&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.jndi.factories.MailSessionReference"&gt;
&lt;Set name="user"&gt;fred&lt;/Set&gt;
&lt;Set name="password"&gt;OBF:1xmk1w261z0f1w1c1xmq&lt;/Set&gt;
&lt;Set name="properties"&gt;
&lt;New class="java.util.Properties"&gt;
&lt;Put name="mail.smtp.host"&gt;XXX&lt;/Put&gt;
&lt;Put name="mail.from"&gt;me@me&lt;/Put&gt;
&lt;Put name="mail.debug"&gt;true&lt;/Put&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This setup creates an instance of the <code>org.eclipse.jetty.jndi.factories.MailSessionReference</code> class, calls it&#8217;s setter methods to set up the authentication for the mail system, and populates a set of Properties, setting them on the <code>MailSessionReference</code> instance.
The result is that an application can look up <code>java:comp/env/mail/Session</code> at runtime and obtain access to a <code>javax.mail.Session</code> that has the necessary configuration to permit it to send email via SMTP.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
As of Jetty 10, the <a href="http://central.maven.org/maven2/org/eclipse/jetty/orbit/javax.mail.glassfish/1.4.1.v201005082020/javax.mail.glassfish-1.4.1.v201005082020.jar"><code>javax.mail</code></a> and <a href="http://central.maven.org/maven2/org/eclipse/jetty/orbit/javax.activation/1.1.0.v201105071233/javax.activation-1.1.0.v201105071233.jar"><code>javax.activation</code></a> jar files are not included in the Jetty Distribution and will need to be downloaded separately from Maven Central.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You can set the password to be plain text, or use Jetty&#8217;s <a href="#configuring-security-secure-passwords">Secure Password Obfuscation</a> (OBF:) mechanism to make the config file a little more secure from prying eyes.
Remember that you cannot use the other Jetty encryption mechanisms of MD5 and Crypt because they do not allow you to recover the original password, which the mail system requires.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="configuring-xa-transactions">Configuring XA Transactions</h4>
<div class="paragraph">
<p>If you want to perform distributed transactions with your resources, you need a <em>transaction manager</em> that supports the JTA interfaces, and that you can look up as <code>java:comp/UserTransaction</code> in your webapp.
Jetty does not ship with one as standard, but you can plug in the one you prefer.
You can configure a transaction manager using the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/plus/jndi/Transaction.html">JNDI Transaction</a> object in a Jetty config file.
The following example configures the <a href="http://www.atomikos.com/">Atomikos</a> transaction manager:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="tx" class="org.eclipse.jetty.plus.jndi.Transaction"&gt;
&lt;Arg&gt;
&lt;New class="com.atomikos.icatch.jta.J2eeUserTransaction"/&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="configuring-links">Configuring Links</h4>
<div class="paragraph">
<p>Generally, the name you set for your <code>Resource</code> should be the same name you use for it in <code>web.xml</code>.
For example:</p>
</div>
<div class="paragraph">
<p>In a context xml file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;New id="myds" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid="wac"/&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/mydatasource&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.derby.jdbc.EmbeddedDataSource"&gt;
&lt;Set name="DatabaseName"&gt;test&lt;/Set&gt;
&lt;Set name="createDatabase"&gt;create&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>In a <code>web.xml</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;resource-ref&gt;
&lt;res-ref-name&gt;jdbc/mydatasource&lt;/res-ref-name&gt;
&lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
&lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;injection-target&gt;
&lt;injection-target-class&gt;com.acme.JNDITest&lt;/injection-target-class&gt;
&lt;injection-target-name&gt;myDatasource&lt;/injection-target-name&gt;
&lt;/injection-target&gt;
&lt;/resource-ref&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>However, you can refer to it in <code>web.xml</code> by a different name, and link it to the name in your <code>org.eclipse.jetty.plus.jndi.Resource</code> by using an <code>org.eclipse.jetty.plus.jndi.Link</code>.
For the example above, you can refer to the <code>jdbc/mydatasource</code> resource as <code>jdbc/mydatasource1</code> as follows:</p>
</div>
<div class="paragraph">
<p>In a context xml file declare <code>jdbc/mydatasource</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;Configure id='wac' class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;New id="myds" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;Ref refid="wac"/&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/mydatasource&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.derby.jdbc.EmbeddedDataSource"&gt;
&lt;Set name="DatabaseName"&gt;test&lt;/Set&gt;
&lt;Set name="createDatabase"&gt;create&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then in a <code>WEB-INF/jetty-env.xml</code> file, link the name <code>jdbc/mydatasource</code> to the name you want to reference it as in
<code>web.xml</code>, which in this case is <code>jdbc/mydatasource1</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;New id="map1" class="org.eclipse.jetty.plus.jndi.Link"&gt;
&lt;Arg&gt;&lt;Ref refid='wac'/&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/mydatasource1&lt;/Arg&gt; &lt;!-- name in web.xml --&gt;
&lt;Arg&gt;jdbc/mydatasource&lt;/Arg&gt; &lt;!-- name in container environment --&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now you can refer to <code>jdbc/mydatasource1</code> in the <code>web.xml</code> like this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;resource-ref&gt;
&lt;res-ref-name&gt;jdbc/mydatasource1&lt;/res-ref-name&gt;
&lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
&lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;injection-target&gt;
&lt;injection-target-class&gt;com.acme.JNDITest&lt;/injection-target-class&gt;
&lt;injection-target-name&gt;myDatasource&lt;/injection-target-name&gt;
&lt;/injection-target&gt;
&lt;/resource-ref&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>This can be useful when you cannot change a JNDI resource directly in the <code>web.xml</code> but need to link it to a specific resource in your deployment environment.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jndi-embedded">Using JNDI with Jetty Embedded</h3>
<div class="sect3">
<h4>Setting up the Classpath</h4>
<div class="paragraph">
<p>In addition to the jars that you require for your application, and the jars needed for core Jetty, you will need to place the following jars onto your classpath:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>jetty-jndi.jar
jetty-plus.jar</pre>
</div>
</div>
<div class="paragraph">
<p>If you are using transactions, you will also need the <code>javax.transaction</code> api.
You can obtain this jar <a href="http://central.maven.org/maven2/org/eclipse/jetty/orbit/javax.transaction/1.1.1.v201105210645/javax.transaction-1.1.1.v201105210645.jar">here.</a></p>
</div>
<div class="paragraph">
<p>If you wish to use mail, you will also need the <code>javax.mail</code> api and implementation which <a href="http://central.maven.org/maven2/org/eclipse/jetty/orbit/javax.mail.glassfish/1.4.1.v201005082020/javax.mail.glassfish-1.4.1.v201005082020.jar">you can download here.</a>
Note that this jar also requires the <code>javax.activation</code> classes, which is available <a href="http://central.maven.org/maven2/org/eclipse/jetty/orbit/javax.activation/1.1.0.v201105071233/javax.activation-1.1.0.v201105071233.jar">at this link.</a></p>
</div>
</div>
<div class="sect3">
<h4>Example Code</h4>
<div class="paragraph">
<p>Here is an example class that sets up some JNDI entries and deploys a webapp that references these JNDI entries in code.
We&#8217;ll use some mocked up classes for the transaction manager and the DataSource in this example for simplicity:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">import java.util.Properties;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.webapp.WebAppContext;
/**
* ServerWithJNDI
*
*
*/
public class ServerWithJNDI
{
public static void main(String[] args) throws Exception
{
//Create the server
Server server = new Server(8080);
//Enable parsing of jndi-related parts of web.xml and jetty-env.xml
org.eclipse.jetty.webapp.Configuration.ClassList classlist = org.eclipse.jetty.webapp.Configuration.ClassList.setServerDefault(server);
classlist.addAfter("org.eclipse.jetty.webapp.FragmentConfiguration", "org.eclipse.jetty.plus.webapp.EnvConfiguration", "org.eclipse.jetty.plus.webapp.PlusConfiguration");
//Create a WebApp
WebAppContext webapp = new WebAppContext();
webapp.setContextPath("/");
webapp.setWar("./my-foo-webapp.war");
server.setHandler(webapp);
//Register new transaction manager in JNDI
//At runtime, the webapp accesses this as java:comp/UserTransaction
org.eclipse.jetty.plus.jndi.Transaction transactionMgr = new org.eclipse.jetty.plus.jndi.Transaction(new com.acme.MockUserTransaction());
//Define an env entry with Server scope.
//At runtime, the webapp accesses this as java:comp/env/woggle
//This is equivalent to putting an env-entry in web.xml:
//&lt;env-entry&gt;
// &lt;env-entry-name&gt;woggle&lt;/env-entry-name&gt;
// &lt;env-entry-type&gt;java.lang.Integer&lt;/env-entry-type&gt;
// &lt;env-entry-value&gt;4000&lt;/env-entry-value&gt;
//&lt;/env-entry&gt;
org.eclipse.jetty.plus.jndi.EnvEntry woggle = new org.eclipse.jetty.plus.jndi.EnvEntry(server, "woggle", new Integer(4000), false);
//Define an env entry with webapp scope.
//At runtime, the webapp accesses this as java:comp/env/wiggle
//This is equivalent to putting a web.xml entry in web.xml:
//&lt;env-entry&gt;
// &lt;env-entry-name&gt;wiggle&lt;/env-entry-name&gt;
// &lt;env-entry-value&gt;100&lt;/env-entry-value&gt;
// &lt;env-entry-type&gt;java.lang.Double&lt;/env-entry-type&gt;
//&lt;/env-entry&gt;
//Note that the last arg of "true" means that this definition for "wiggle" would override an entry of the
//same name in web.xml
org.eclipse.jetty.plus.jndi.EnvEntry wiggle = new org.eclipse.jetty.plus.jndi.EnvEntry(webapp, "wiggle", new Double(100), true);
//Register a reference to a mail service scoped to the webapp.
//This must be linked to the webapp by an entry in web.xml:
// &lt;resource-ref&gt;
// &lt;res-ref-name&gt;mail/Session&lt;/res-ref-name&gt;
// &lt;res-type&gt;javax.mail.Session&lt;/res-type&gt;
// &lt;res-auth&gt;Container&lt;/res-auth&gt;
// &lt;/resource-ref&gt;
//At runtime the webapp accesses this as java:comp/env/mail/Session
org.eclipse.jetty.jndi.factories.MailSessionReference mailref = new org.eclipse.jetty.jndi.factories.MailSessionReference();
mailref.setUser("CHANGE-ME");
mailref.setPassword("CHANGE-ME");
Properties props = new Properties();
props.put("mail.smtp.auth", "false");
props.put("mail.smtp.host","CHANGE-ME");
props.put("mail.from","CHANGE-ME");
props.put("mail.debug", "false");
mailref.setProperties(props);
org.eclipse.jetty.plus.jndi.Resource xxxmail = new org.eclipse.jetty.plus.jndi.Resource(webapp, "mail/Session", mailref);
// Register a mock DataSource scoped to the webapp
//This must be linked to the webapp via an entry in web.xml:
//&lt;resource-ref&gt;
// &lt;res-ref-name&gt;jdbc/mydatasource&lt;/res-ref-name&gt;
// &lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
// &lt;res-auth&gt;Container&lt;/res-auth&gt;
//&lt;/resource-ref&gt;
//At runtime the webapp accesses this as java:comp/env/jdbc/mydatasource
org.eclipse.jetty.plus.jndi.Resource mydatasource = new org.eclipse.jetty.plus.jndi.Resource(webapp, "jdbc/mydatasource",
new com.acme.MockDataSource());
server.start();
server.join();
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="jndi-datasource-examples">Datasource Examples</h3>
<div class="paragraph">
<p>Here are examples of configuring a JNDI datasource for various databases.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Read <a href="#configuring-datasources">Configuring DataSources</a> in <a href="#jndi-configuration">Configuring JNDI</a> for more information about configuring datasources.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>All of these examples correspond to a <code>resource-ref</code> in <code>web.xml</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;resource-ref&gt;
&lt;description&gt;My DataSource Reference&lt;/description&gt;
&lt;res-ref-name&gt;jdbc/DSTest&lt;/res-ref-name&gt;
&lt;res-type&gt;javax.sql.DataSource&lt;/res-type&gt;
&lt;res-auth&gt;Container&lt;/res-auth&gt;
&lt;/resource-ref&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>These examples assume that all of the datasources are declared at the JVM scope, but you can use other scopes if desired.
You can configure all JNDI resources in a <code>jetty.xml</code> file, a <code>WEB-INF/jetty-env.xml</code> file, or a context XML file.
See the section <a href="#jndi-where-to-declare">Deciding Where to Declare Resources</a> for more information.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
You must provide Jetty with the libraries necessary to instantiate the datasource you have configured by putting the corresponding Jar in <code>JETTY_HOME/lib/ext</code>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect3">
<h4 id="pooling-datasources">Pooling DataSources</h4>
<div class="paragraph">
<p>Pooling datasources enables connection pooling, which lets you reuse an existing connection instead of creating a new connection to the database.
This is highly efficient in terms of memory allocation and speed of the request to the database.
We highly recommend this option for production environments.</p>
</div>
<div class="paragraph">
<p>The following is a list of the pooled datasource examples we have worked with in the past:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#hikaricp-datasource">HikariCP</a></p>
</li>
<li>
<p><a href="#bonecp-datasource">BoneCP</a></p>
</li>
<li>
<p><a href="#c3p0-datasource">c3p0</a></p>
</li>
<li>
<p><a href="#dbcp-datasource">DBCP</a></p>
</li>
<li>
<p><a href="#atomikos-datasource">Atomikos 3.3.2+</a></p>
</li>
<li>
<p><a href="#mysql-pooled-datasource">MySQL</a></p>
</li>
<li>
<p><a href="#postgreSQL-pooled-datasource">PostgreSQL</a></p>
</li>
<li>
<p><a href="#DB2-pooled-datasource">DB2</a></p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="hikaricp-datasource">HikariCP</h5>
<div class="paragraph">
<p>Connection pooling, available at <a href="http://search.maven.org/remotecontent?filepath=com/zaxxer/HikariCP/1.4.0/HikariCP-1.4.0.jar">HikariCP Download</a>.
All configuration options for HikariCP are described here: <a href="https://github.com/brettwooldridge/HikariCP">HikariCP documentation</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.zaxxer.hikari.HikariDataSource"&gt;
&lt;Arg&gt;
&lt;New class="com.zaxxer.hikari.HikariConfig"&gt;
&lt;Set name="minimumPoolSize"&gt;5&lt;/Set&gt;
&lt;Set name="maximumPoolSize"&gt;20&lt;/Set&gt;
&lt;Set name="dataSourceClassName"&gt;com.mysql.jdbc.jdbc2.optional.MysqlDataSource&lt;/Set&gt;
&lt;Set name="username"&gt;jdbc.user&lt;/Set&gt;
&lt;Set name="password"&gt;jdbc.pass&lt;/Set&gt;
&lt;Call name="addDataSourceProperty"&gt;
&lt;Arg&gt;url&lt;/Arg&gt;
&lt;Arg&gt;jdbc.url&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="bonecp-datasource">BoneCP</h5>
<div class="paragraph">
<p>Connection pooling, available at <a href="http://jolbox.com/index.html?page=http://jolbox.com/download.html">BoneCP Download</a>.
All configuration options for BoneCP are described here: <a href="http://jolbox.com/bonecp/downloads/site/apidocs/com/jolbox/bonecp/BoneCPDataSource.html">BoneCP API</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.jolbox.bonecp.BoneCPDataSource"&gt;
&lt;Set name="driverClass"&gt;com.mysql.jdbc.Driver&lt;/Set&gt;
&lt;Set name="jdbcUrl"&gt;jdbc.url&lt;/Set&gt;
&lt;Set name="username"&gt;jdbc.user&lt;/Set&gt;
&lt;Set name="password"&gt;jdbc.pass&lt;/Set&gt;
&lt;Set name="minConnectionsPerPartition"&gt;5&lt;/Set&gt;
&lt;Set name="maxConnectionsPerPartition"&gt;50&lt;/Set&gt;
&lt;Set name="acquireIncrement"&gt;5&lt;/Set&gt;
&lt;Set name="idleConnectionTestPeriod"&gt;30&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="c3p0-datasource">c3p0</h5>
<div class="paragraph">
<p>Connection pooling, available at <a href="https://repo1.maven.org/maven2/c3p0/c3p0/0.9.1.2/c3p0-0.9.1.2.jar">c3p0 Jar</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.mchange.v2.c3p0.ComboPooledDataSource"&gt;
&lt;Set name="driverClass"&gt;org.some.Driver&lt;/Set&gt;
&lt;Set name="jdbcUrl"&gt;jdbc.url&lt;/Set&gt;
&lt;Set name="user"&gt;jdbc.user&lt;/Set&gt;
&lt;Set name="password"&gt;jdbc.pass&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="dbcp-datasource">DBCP</h5>
<div class="paragraph">
<p>Connection pooling, available at <a href="https://repo1.maven.org/maven2/commons-dbcp/commons-dbcp/1.2/commons-dbcp-1.2.jar">dbcp Jar</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.apache.commons.dbcp.BasicDataSource"&gt;
&lt;Set name="driverClassName"&gt;org.some.Driver&lt;/Set&gt;
&lt;Set name="url"&gt;jdbc.url&lt;/Set&gt;
&lt;Set name="username"&gt;jdbc.user&lt;/Set&gt;
&lt;Set name="password"&gt;jdbc.pass&lt;/Set&gt;
&lt;/New&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="atomikos-datasource">Atomikos 3.3.2+</h5>
<div class="paragraph">
<p>Connection pooling + XA transactions.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.atomikos.jdbc.AtomikosDataSourceBean"&gt;
&lt;Set name="minPoolSize"&gt;2&lt;/Set&gt;
&lt;Set name="maxPoolSize"&gt;50&lt;/Set&gt;
&lt;Set name="xaDataSourceClassName"&gt;com.mysql.jdbc.jdbc2.optional.MysqlXADataSource&lt;/Set&gt;
&lt;Set name="UniqueResourceName"&gt;DSTest&lt;/Set&gt;
&lt;Get name="xaProperties"&gt;
&lt;Call name="setProperty"&gt;
&lt;Arg&gt;url&lt;/Arg&gt;
&lt;Arg&gt;jdbc:mysql://localhost:3306/databasename&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="setProperty"&gt;
&lt;Arg&gt;user&lt;/Arg&gt;
&lt;Arg&gt;some_username&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="setProperty"&gt;
&lt;Arg&gt;password&lt;/Arg&gt;
&lt;Arg&gt;some_password&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Get&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="mysql-pooled-datasource">MySQL</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.DataSource</code> and <code>javax.sql.ConnectionPoolDataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource"&gt;
&lt;Set name="Url"&gt;jdbc:mysql://localhost:3306/databasename&lt;/Set&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="postgreSQL-pooled-datasource">PostgreSQL</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.ConnectionPoolDataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.postgresql.ds.PGConnectionPoolDataSource"&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;Set name="DatabaseName"&gt;dbname&lt;/Set&gt;
&lt;Set name="ServerName"&gt;localhost&lt;/Set&gt;
&lt;Set name="PortNumber"&gt;5432&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="DB2-pooled-datasource">DB2</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.ConnectionPoolDataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.ibm.db2.jcc.DB2ConnectionPoolDataSource"&gt;
&lt;Set name="DatabaseName"&gt;dbname&lt;/Set&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;Set name="ServerName"&gt;servername&lt;/Set&gt;
&lt;Set name="PortNumber"&gt;50000&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="non-pooling-datasources">Non-pooling DataSources</h4>
<div class="paragraph">
<p>If you are deploying in a production environment, we highly recommend using a Pooling DataSource.
Since that is not always an option we have a handful of examples for non-pooling datasources listed here as well.</p>
</div>
<div class="paragraph">
<p>The following is a list of the non-pooled datasource examples:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#sql-server-2000-datasource">SQL Server 2000</a></p>
</li>
<li>
<p><a href="#oracle-9i10g-datasource">Oracle 9i/10g</a></p>
</li>
<li>
<p><a href="#postgreSQL-datasource">PostgreSQL</a></p>
</li>
<li>
<p><a href="#sybase-datasource">Sybase</a></p>
</li>
<li>
<p><a href="#DB2-datasource">DB2</a></p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="sql-server-2000-datasource">SQL Server 2000</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.DataSource</code> and <code>javax.sql.ConnectionPoolDataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="net.sourceforge.jtds.jdbcx.JtdsDataSource"&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;Set name="DatabaseName"&gt;dbname&lt;/Set&gt;
&lt;Set name="ServerName"&gt;localhost&lt;/Set&gt;
&lt;Set name="PortNumber"&gt;1433&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="oracle-9i10g-datasource">Oracle 9i/10g</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.DataSource</code> and <code>javax.sql.ConnectionPoolDataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="oracle.jdbc.pool.OracleDataSource"&gt;
&lt;Set name="DriverType"&gt;thin&lt;/Set&gt;
&lt;Set name="URL"&gt;jdbc:oracle:thin:@fmsswdb1:10017:otcd&lt;/Set&gt;
&lt;Set name="User"&gt;xxxx&lt;/Set&gt;
&lt;Set name="Password"&gt;xxxx&lt;/Set&gt;
&lt;Set name="connectionCachingEnabled"&gt;true&lt;/Set&gt;
&lt;Set name="connectionCacheProperties"&gt;
&lt;New class="java.util.Properties"&gt;
&lt;Call name="setProperty"&gt;
&lt;Arg&gt;MinLimit&lt;/Arg&gt;
&lt;Arg&gt;5&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- put the other properties in here too --&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>For more information, refer to: <a href="http://docs.oracle.com/cd/B14117_01/java.101/b10979/conncache.htm">Oracle Database JDBC documentation</a>.</p>
</div>
</div>
<div class="sect4">
<h5 id="postgreSQL-datasource">PostgreSQL</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.DataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="org.postgresql.ds.PGSimpleDataSource"&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;Set name="DatabaseName"&gt;dbname&lt;/Set&gt;
&lt;Set name="ServerName"&gt;localhost&lt;/Set&gt;
&lt;Set name="PortNumber"&gt;5432&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="sybase-datasource">Sybase</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.DataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.sybase.jdbc2.jdbc.SybDataSource"&gt;
&lt;Set name="DatabaseName"&gt;dbname&lt;/Set&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;Set name="ServerName"&gt;servername&lt;/Set&gt;
&lt;Set name="PortNumber"&gt;5000&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="DB2-datasource">DB2</h5>
<div class="paragraph">
<p>Implements <code>javax.sql.DataSource</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;New id="DSTest" class="org.eclipse.jetty.plus.jndi.Resource"&gt;
&lt;Arg&gt;&lt;/Arg&gt;
&lt;Arg&gt;jdbc/DSTest&lt;/Arg&gt;
&lt;Arg&gt;
&lt;New class="com.ibm.db2.jcc.DB2SimpleDataSource"&gt;
&lt;Set name="DatabaseName"&gt;dbname&lt;/Set&gt;
&lt;Set name="User"&gt;user&lt;/Set&gt;
&lt;Set name="Password"&gt;pass&lt;/Set&gt;
&lt;Set name="ServerName"&gt;servername&lt;/Set&gt;
&lt;Set name="PortNumber"&gt;50000&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/New&gt;</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="alpn-chapter">Application Layer Protocol Negotiation (ALPN)</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The development of new web protocols such as HTTP/2 raised the need of protocol
negotiation within a Transport Layer Security (TLS) handshake.
A protocol negotiation called ALPN (Application Layer Protocol Negotiation -
<a href="https://tools.ietf.org/html/rfc7301">RFC7301</a>) has been defined to accomplish this.</p>
</div>
<div class="paragraph">
<p>ALPN has now replaced the older (and now fully deprecated) NPN in the general Web
as of 2016.</p>
</div>
<div class="paragraph">
<p>For those browsers that support HTTP/2, they all now support ALPN.
Starting with Jetty 9.3.0, only ALPN is supported by Jetty.</p>
</div>
<div class="sect2">
<h3 id="alpn">Introducing ALPN</h3>
<div class="paragraph">
<p>Application Layer Protocol Negotiation (ALPN) is a TLS extension that allows client and server to negotiate the application protocol that they will use to communicate within the encryption provided by TLS.</p>
</div>
<div class="paragraph">
<p>Any protocol can be negotiated by ALPN within a TLS connection; the protocols that are most commonly negotiated are HTTP/2 and HTTP/1.1.</p>
</div>
<div class="paragraph">
<p>Browsers only support HTTP/2 over TLS by negotiating the HTTP/2 protocol via ALPN.
You need to configure the server to support TLS and ALPN if you want browsers to use
the HTTP/2 protocol, otherwise they will default to HTTP/1.1.</p>
</div>
<div class="paragraph">
<p>In the Jetty project, ALPN is <em>used</em> in two artifacts: <code>jetty-alpn-client</code> and <code>jetty-alpn-server</code>, respectively for the client and for the server.</p>
</div>
<div class="paragraph">
<p>When using Jetty as a standalone server via the Jetty distribution, the <code>jetty-alpn-server</code> artifact is automatically included in the server classpath by the Jetty module system.</p>
</div>
<div class="paragraph">
<p>When using Jetty embedded, the <code>jetty-alpn-client</code> and <code>jetty-alpn-server</code> artifacts must be included in the classpath, respectively for client and server use cases.</p>
</div>
<div class="paragraph">
<p>The ALPN implementation is <em>provided</em> to these two artifacts with the following three options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>For JDK 8 or later, a provider based on the <a href="#conscrypt">Conscrypt security provider</a></p>
<div class="ulist">
<ul>
<li>
<p>Works with JDK 8 or later and provides improved performance</p>
</li>
<li>
<p>Binds to the OpenSSL native library shipped by Conscrypt and is therefore only available on the platforms supported by Conscrypt</p>
</li>
</ul>
</div>
</li>
<li>
<p>For JDK 9 or later, a provider based on the ALPN APIs present in the JDK</p>
<div class="ulist">
<ul>
<li>
<p>Works with JDK 9 or later, pure Java implementation</p>
</li>
<li>
<p>Lower performance than Conscrypt</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>The first, although hosted under the umbrella of the Jetty project, is independent of Jetty (the Servlet Container); you can use it in any other Java network server.</p>
</div>
<div class="paragraph">
<p>Each provider above provides an ALPN <em>service</em> implementation; Jetty uses the <code>ServiceLoader</code> mechanism to load these service implementations.
At least one valid provider must be present in the server classpath.
For example, using JDK 8 with the JDK 9 ALPN provider is an <em>invalid</em> combination.
The absence of valid implementations is an error at startup (see also the <a href="#alpn-troubleshooting">troubleshooting section</a>).</p>
</div>
<div class="paragraph">
<p>There may be multiple ALPN service providers in the server classpath.
When a new connection is created, an <code>SSLEngine</code> instance is associated to it; each <code>SSLEngine</code> is passed all service implementations, until one accepts it.</p>
</div>
<div class="paragraph">
<p>It is therefore possible to have multiple providers active at the same time, for example the JDK 9 provider and the Conscrypt provider, and at runtime the correct one will be chosen by the Jetty runtime.</p>
</div>
<div class="sect3">
<h4 id="alpn-conscrypt">ALPN and Conscrypt</h4>
<div class="paragraph">
<p>When using JDK 8 or later, you can use the <a href="https://conscrypt.org/">Conscrypt</a> security provider to provide the ALPN service implementation.</p>
</div>
<div class="paragraph">
<p>Conscrypt binds natively to BoringSSL (a fork of OpenSSL by Google), so ALPN will be supported via the support provided by BoringSSL (bundled together with Conscrypt).</p>
</div>
<div class="paragraph">
<p>When using Jetty as a standalone server via the Jetty distribution, ALPN is enabled by enabling the <code>conscrypt</code> module.</p>
</div>
<div class="paragraph">
<p>When using Jetty embedded, ALPN is enabled by the <code>jetty-alpn-conscrypt-client</code> and <code>jetty-alpn-conscrypt-server</code> artifacts, respectively for client usage and server usage.
In addition, you also need the Conscrypt artifacts, typically the <code>org.conscrypt:conscrypt-openjdk-uber</code> artifact.
All these artifacts must be added to the classpath.</p>
</div>
</div>
<div class="sect3">
<h4 id="alpn-jdk9">ALPN and JDK 9</h4>
<div class="paragraph">
<p>When using JDK 9 or later and Jetty as a standalone server via the Jetty distribution, ALPN support is automatically enabled when the <code>http2</code> module is enabled.
This enables transitively the <code>alpn-9</code> module which puts the <code>jetty-alpn-java-server</code> artifact in the server classpath, providing the ALPN JDK 9 service implementation.</p>
</div>
<div class="paragraph">
<p>When using JDK 9 or later and Jetty embedded, the ALPN service implementation is provided by the <code>jetty-alpn-java-client</code> and <code>jetty-alpn-java-server</code> artifacts, respectively for client usage and server usage, and must be added to the classpath.</p>
</div>
<div class="sect4">
<h5 id="alpn-osgi">Starting in OSGi</h5>
<div class="paragraph">
<p>To use ALPN in an OSGi environment, in addition to what described above, you will also need to deploy the <code>jetty-osgi-alpn</code> jar.
This jar contains a <code>Fragment-Host</code> directive that ensures the ALPN classes will be available from the system bundle.</p>
</div>
<div class="paragraph">
<p>You can download the <a href="https://repo1.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-alpn/">jetty-osgi-alpn jar</a> from Maven Central.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
OSGi <strong>requires</strong> a <code>ServiceLoader</code> implementation for Jetty to function properly.
OSGi leverages <a href="http://aries.apache.org/modules/spi-fly.html">Apache Aries SPI Fly</a> for this functionality.
You can read more about OSGi and <code>ServiceLoader</code> <a href="http://blog.osgi.org/2013/02/javautilserviceloader-in-osgi.html">here.</a>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
</div>
<div class="sect3">
<h4 id="alpn-troubleshooting">ALPN Troubleshooting</h4>
<div class="paragraph">
<p>When starting the Jetty server, especially when using Jetty embedded, it may be possible that you see an error similar to this:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">IllegalStateException: no ALPN processor</code></pre>
</div>
</div>
<div class="paragraph">
<p>The error means that you don&#8217;t have the ALPN dependencies setup correctly in your classpath.</p>
</div>
<div class="paragraph">
<p>For example, you do not have the <code>jetty-alpn-java-server</code> artifact in the classpath.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="fastcgi">FastCGI Support</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="fastcgi-intro">FastCGI Introduction</h3>
<div class="paragraph">
<p>FastCGI is a network protocol primarily used by a <em>web server</em> to communicate to a <em>FastCGI server</em>.
FastCGI servers are typically used to serve web content generated by dynamic web languages, primarily <a href="http://www.php.net/">PHP</a>, but also Python, Ruby, Perl and others.</p>
</div>
<div class="paragraph">
<p>Web servers that supports FastCGI are, among others, <a href="http://httpd.apache.org/">Apache</a>, <a href="http://nginx.org/">Nginx</a>, and Jetty.
Web servers typically act as proxies, converting HTTP requests that they receive from clients (browsers) to FastCGI requests that are forwarded to the FastCGI server.
The FastCGI server spawns the dynamic web language interpreter, passing it the information contained in the FastCGI request and a dynamic web language script is executed, producing web content, typically HTML.
The web content is then formatted into a FastCGI response that is returned to the web server, which converts it to a HTTP response that is then returned to the client.</p>
</div>
<div class="paragraph">
<p>The most well known FastCGI server is the <a href="http://php-fpm.org/">PHP FastCGI Process Manager</a>, or <code>php-fpm</code>.
In the following we will assume that <code>php-fpm</code> is used as FastCGI server.</p>
</div>
<div class="paragraph">
<p>Jetty can be configured to act as a web server that supports FastCGI, replacing the functionality that is normally provided by Apache or Nginx.
This allows users to leverage Jetty features such as HTTP/2, the unique support that Jetty provides for HTTP/2 Push, Jetty&#8217;s scalability, and of course Jetty&#8217;s native support for Java Web Standards such as Servlets, JSPs, etc.</p>
</div>
<div class="paragraph">
<p>With such configuration, users can not only deploy their Java Web Applications in Jetty, but also serve their <a href="http://wordpress.com/">WordPress</a> site or blog or their <a href="https://drupal.org/">Drupal</a> site without having to install and manage multiple web servers.</p>
</div>
</div>
<div class="sect2">
<h3 id="configuring-fastcgi">Configuring Jetty for FastCGI</h3>
<div class="paragraph">
<p>In this section you will see how to configure Jetty to serve WordPress via FastCGI.</p>
</div>
<div class="paragraph">
<p>The first step is to have WordPress installed on your server machine, for example under <code>/var/www/wordpress</code>.
For more information about how to install WordPress, please refer to the <a href="https://codex.wordpress.org/Installing_WordPress">WordPress Installation Guide</a>.</p>
</div>
<div class="paragraph">
<p>The second step is to install <code>php-fpm</code> and make sure it is configured to listen on a TCP socket; typically it is configured to listen to <code>localhost:9000</code>.</p>
</div>
<div class="paragraph">
<p>The third step is to install Jetty, for example under <code>/opt/jetty</code>, called in the following <code>$JETTY_HOME</code>.
Refer to <a href="#jetty-downloading">[jetty-downloading]</a> for more information about how to install Jetty.</p>
</div>
<div class="paragraph">
<p>The fourth step is to create a Jetty base directory (see <a href="#startup-base-and-home">Managing Jetty Base and Jetty Home</a>), called in the following <code>$JETTY_BASE</code>, where you setup the configuration needed to support FastCGI in Jetty, and configure the <code>fcgi</code>, <code>http</code> and <code>deploy</code> modules, so that Jetty will be able to accept HTTP requests from browsers, convert them in FastCGI, and proxy them to <code>php-fpm</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ mkdir -p /usr/jetty/wordpress
$ cd /usr/jetty/wordpress
$ java -jar $JETTY_HOME/start.jar --add-to-start=fcgi,http,deploy</code></pre>
</div>
</div>
<div class="paragraph">
<p>Therefore <code>$JETTY_BASE=/usr/jetty/wordpress</code>.</p>
</div>
<div class="paragraph">
<p>The fifth step is to deploy the web application that provides the proxying of client requests to the FastCGI server, <code>php-fpm</code>.
Typically this is done by deploying a <code>*.war</code> file in the <code>$JETTY_BASE/webapps</code> directory.
For FastCGI there is no web application that needs developed - all the work has already been done for you by Jetty.
As such you only need to deploy a Jetty context XML file that configures the web application directly.
Copy and paste the following content as <code>$JETTY_BASE/webapps/jetty-wordpress.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.servlet.ServletContextHandler"&gt;
&lt;New id="root" class="java.lang.String"&gt;
&lt;Arg&gt;/var/www/wordpress&lt;/Arg&gt;
&lt;/New&gt;
&lt;Set name="contextPath"&gt;/&lt;/Set&gt;
&lt;Set name="resourceBase"&gt;&lt;Ref refid="root" /&gt;&lt;/Set&gt;
&lt;Set name="welcomeFiles"&gt;
&lt;Array type="string"&gt;&lt;Item&gt;index.php&lt;/Item&gt;&lt;/Array&gt;
&lt;/Set&gt;
&lt;Call name="addFilter"&gt;
&lt;Arg&gt;org.eclipse.jetty.fcgi.server.proxy.TryFilesFilter&lt;/Arg&gt;
&lt;Arg&gt;/*&lt;/Arg&gt;
&lt;Arg&gt;
&lt;Call name="of" class="java.util.EnumSet"&gt;
&lt;Arg&gt;&lt;Get name="REQUEST" class="javax.servlet.DispatcherType" /&gt;&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Arg&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;files&lt;/Arg&gt;
&lt;Arg&gt;$path /index.php?p=$path&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Call&gt;
&lt;Call name="addServlet"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.servlet.ServletHolder"&gt;
&lt;Arg&gt;default&lt;/Arg&gt;
&lt;Arg&gt;
&lt;Call name="forName" class="java.lang.Class"&gt;
&lt;Arg&gt;org.eclipse.jetty.servlet.DefaultServlet&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Arg&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;dirAllowed&lt;/Arg&gt;
&lt;Arg&gt;false&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;Arg&gt;/&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="addServlet"&gt;
&lt;Arg&gt;org.eclipse.jetty.fcgi.server.proxy.FastCGIProxyServlet&lt;/Arg&gt;
&lt;Arg&gt;*.php&lt;/Arg&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;proxyTo&lt;/Arg&gt;
&lt;Arg&gt;http://localhost:9000&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;prefix&lt;/Arg&gt;
&lt;Arg&gt;/&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;scriptRoot&lt;/Arg&gt;
&lt;Arg&gt;&lt;Ref refid="root" /&gt;&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Call name="setInitParameter"&gt;
&lt;Arg&gt;scriptPattern&lt;/Arg&gt;
&lt;Arg&gt;(.+?\\.php)&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>An explanation of the above contents:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Linne 6 specifies the WordPress installation directory, in this example <code>/var/www/wordpress</code> (as defined in the first step).</p>
</li>
<li>
<p>Line 9 it is specified the context path at which WordPress will be served, in this example at the root context path <code>/</code>.</p>
</li>
<li>
<p>Line 10 specifies the resource base of the context, also set to the WordPress installation directory.
This allows Jetty to serve static resources directly from the WordPress installation directory.</p>
</li>
<li>
<p>Line 12 specifies the welcome file as <code>index.php</code>, so that Jetty can perform the proper redirects in case of URIs ending with the <code>/</code> character.</p>
</li>
<li>
<p>Line 15 specifies the <code>TryFilesFilter</code>, a Servlet Filter that has been inspired by the <a href="http://wiki.nginx.org/HttpCoreModule#try_files">try_files</a> functionality offered by Nginx.
This filter tries to serve the resource from the file system first, and if the resource is not found it forwards the request as <code>index.php?p=$path</code>, which will match the proxy servlet defined below.
Refer to the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/fcgi/server/proxy/TryFilesFilter.html">TryFilesFilter</a> documentation for further information.</p>
</li>
<li>
<p>Line 29specifies Jetty&#8217;s <code>DefaultServlet</code> to serve static content such as CSS files, JavaScript files, etc. <code>DefaultServlet</code> will serve these files by looking in the resource base of the context, defined at line 10 (see above).</p>
</li>
<li>
<p>Line 47 specifies the <code>FastCGIProxyServlet</code>, a Servlet that proxies HTTP requests arriving from clients to FastCGI requests to the FastCGI server.</p>
</li>
<li>
<p>Line 52 specifies the TCP address of the FastCGI server (<code>php-fpm</code>), where HTTP requests are forwarded as FastCGI requests.</p>
</li>
<li>
<p>Line 60 specifies once again the WordPress installation directory, so that the <code>FastCGIProxyServlet</code> can pass this information to the FastCGI server.</p>
</li>
<li>
<p>Line 64 specifies a regular expression that matches request URIs performed to this servlet, in addition to the standard URL mapping defined by Servlet at line 49.
Refer to the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/fcgi/server/proxy/FastCGIProxyServlet.html">FastCGIProxyServlet</a> documentation for further information.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The last step is to start Jetty (see <a href="#startup">Starting Jetty</a>) and navigate to <code><a href="http://localhost:8080" class="bare">http://localhost:8080</a></code> with your browser and enjoy WordPress:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cd $JETTY_BASE
$ java -jar /opt/jetty/start.jar</code></pre>
</div>
</div>
<div class="sect3">
<h4 id="configuring-fastcgi-http2">Configuring Jetty to Proxy HTTP/2 to FastCGI</h4>
<div class="paragraph">
<p>In order to configure Jetty to listen for HTTP/2 requests from clients that are HTTP/2 enabled and forward them to the FastCGI server as FastCGI requests, you need to enable the <code>http2</code> module, which in turn will require a TLS connector and consequently a keystore to read the key material required by TLS.</p>
</div>
<div class="paragraph">
<p>Enabling the <code>http2</code> is easy; in additions to the modules you have enabled above, add the <code>http2</code> module:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar --add-to-start=http2</code></pre>
</div>
</div>
<div class="paragraph">
<p>The command above adds the <code>http2</code> module (and its dependencies) to the existing modules and uses the default Jetty keystore to provide the key material required by TLS.
You will want to use your own keystore with your own private key and certificate for your own domain.</p>
</div>
<div class="paragraph">
<p>Remember that by adding the <code>http2</code> module, you will start two JVMs: one that reads the configuration, and one that has the ALPN boot boot jar in the boot classpath, as explained in <a href="#http2-configuring">Configuring HTTP/2</a>.</p>
</div>
<div class="paragraph">
<p>Since now your site will run over TLS, you need to make sure that the WordPress URL is also configured so.
If you have followed the steps of the <a href="#configuring-fastcgi">previous section</a>, your WordPress site is served at <code><a href="http://localhost:8080" class="bare">http://localhost:8080</a></code>.
You will need to change that to be <code><a href="https://localhost:8443" class="bare">https://localhost:8443</a></code> from the WordPress administration web interface, or follow the <a href="http://codex.wordpress.org/Changing_The_Site_URL">WordPress instructions</a> to do so without using the administration web interface.</p>
</div>
<div class="paragraph">
<p>The minimal modules required to run WordPress with Jetty on HTTP/2 are therefore: <code>http2</code>, <code>http</code>, <code>fcgi</code> and <code>deploy</code>.
These will setup a clear text connector on port 8080 for HTTP/1.1 and a TLS connector on port 8443 for HTTP/2 and HTTP/1.1.</p>
</div>
<div class="paragraph">
<p>At this point, you can start Jetty (see <a href="#startup">Starting Jetty</a>), hit <code><a href="http://localhost:8080" class="bare">http://localhost:8080</a></code> with your browser and enjoy WordPress via HTTP/2 using a HTTP/2 enabled browser:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ cd $JETTY_BASE
$ java -jar $JETTY_HOME/start.jar</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you don&#8217;t have a HTTP/2 enabled browser, WordPress will still be available over HTTP/1.1.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="advanced-extras">Provided Servlets, Filters, and Handlers</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Jetty ships with a bundle of servlets that interact with the key classes.
Most are in the org.eclipse.jetty.servlets package.
These servlets and filters are among the principle elements of Jetty as a component-based infrastructure that holds and runs J2EE applications.
As described, they play a major role in running and maintaining the Jetty server.</p>
</div>
<div class="paragraph">
<p>Also included are a number of Jetty specific handlers that allow access to internals of jetty that would not normally be exposed and are very useful testing environments and many production scenarios.</p>
</div>
<div class="sect2">
<h3 id="default-servlet">Default Servlet</h3>
<div class="sect3">
<h4 id="default-servlet-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.servlet.DefaultServlet</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlet</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlet/DefaultServlet.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlet/DefaultServlet.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="default-servlet-usage">Usage</h4>
<div class="paragraph">
<p>The <code>DefaultServlet</code> implements the <code>ResourceFactory</code> interface and extends the <code>HttpServlet</code> abstract class.
It is usually mapped to "/" and provides handling for static content, <code>OPTION</code> and <code>TRACE</code> methods for the context.
The <code>MOVE</code> method is allowed if <code>PUT</code> and <code>DELETE</code> are allowed.
See the <code>DefaultServlet</code> <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlet/DefaultServlet.html">javadoc</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="default-servlet-init">Init Parameters</h4>
<div class="paragraph">
<p>Jetty supports the following <code>initParameters</code>:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">acceptRanges</dt>
<dd>
<p>If <code>true</code>, range requests and responses are supported.</p>
</dd>
<dt class="hdlist1">dirAllowed</dt>
<dd>
<p>If <code>true</code>, directory listings are returned if no welcome file is found.
Otherwise 403 Forbidden displays.</p>
</dd>
<dt class="hdlist1">redirectWelcome</dt>
<dd>
<p>If <code>true</code>, welcome files are redirected rather that forwarded.</p>
</dd>
<dt class="hdlist1">welcomeServlets</dt>
<dd>
<p>If <code>true</code>, attempt to dispatch to welcome files that are servlets, but only after no matching static
resources could be found. If <code>false</code>, then a welcome file must exist on disk. If <code>exact</code>, then exact
servlet matches are supported without an existing file. Default is <code>true</code>. This must be <code>false</code> if you want directory listings,
but have index.jsp in your welcome file list.</p>
</dd>
<dt class="hdlist1">precompressed</dt>
<dd>
<p>If set to a comma separated list of encoding types (that may be listed in a requests Accept-Encoding header) to file extension mappings to look for and serve.
For example: <code>br=.br,gzip=.gz,bzip2=.bz</code>.
If set to a boolean <code>true</code>, then a default set of compressed formats will be used, otherwise no precompressed formats supported.</p>
</dd>
<dt class="hdlist1">gzip</dt>
<dd>
<p>Deprecated. Use <code>precompressed</code> instead. If set to <code>true</code>, then static content is served as gzip content encoded if a matching resource is found ending with ".gz".</p>
</dd>
<dt class="hdlist1">resourceBase</dt>
<dd>
<p>Set to replace the context resource base.</p>
</dd>
<dt class="hdlist1">resourceCache</dt>
<dd>
<p>If set, this is a context attribute name, which the servlet will use to look for a shared ResourceCache instance.</p>
</dd>
<dt class="hdlist1">relativeResourceBase</dt>
<dd>
<p>Set with a pathname relative to the base of the servlet context root. Useful for only serving static content out of only specific subdirectories.</p>
</dd>
<dt class="hdlist1">cacheControl</dt>
<dd>
<p>If set, all static content will have this value set as the cache-control header.</p>
</dd>
<dt class="hdlist1">pathInfoOnly</dt>
<dd>
<p>If <code>true</code>, only the path info will be applied to the resourceBase</p>
</dd>
<dt class="hdlist1">stylesheet</dt>
<dd>
<p>Set with the location of an optional stylesheet that will be used to decorate the directory listing html.</p>
</dd>
<dt class="hdlist1">etags</dt>
<dd>
<p>If <code>true</code>, weak etags will be generated and handled.</p>
</dd>
<dt class="hdlist1">maxCacheSize</dt>
<dd>
<p>Maximum total size of the cache or 0 for no cache.</p>
</dd>
<dt class="hdlist1">maxCachedFileSize</dt>
<dd>
<p>Maximum size of a file to cache.</p>
</dd>
<dt class="hdlist1">maxCachedFiles</dt>
<dd>
<p>Maximum number of files to cache.</p>
</dd>
<dt class="hdlist1">useFileMappedBuffer</dt>
<dd>
<p>If set to <code>true</code>, mapped file buffer serves static content.
Setting this value to <code>false</code> means that a direct buffer is used instead of a mapped file buffer.
By default, this is set to <code>true</code>.</p>
</dd>
<dt class="hdlist1">otherGzipFileExtensions</dt>
<dd>
<p>A comma separated list of other file extensions that signify that a file is gzip compressed.
If you don&#8217;t explicitly set this, it defaults to <code>.svgz</code>.</p>
</dd>
<dt class="hdlist1">encodingHeaderCacheSize</dt>
<dd>
<p>Max entries in a cache of ACCEPT-ENCODING headers</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="proxy-servlet">Proxy Servlet</h3>
<div class="sect3">
<h4 id="proxy-servlet-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.proxy.ProxyServlet</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-proxy</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/proxy/ProxyServlet.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/proxy/ProxyServlet.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="proxy-servlet-usage">Usage</h4>
<div class="paragraph">
<p>An asynchronous servlet that forwards requests to another server either as a standard web reverse proxy (as defined by RFC2616) or as a transparent reverse proxy.
Internally it uses the async jetty-client.</p>
</div>
<div class="paragraph">
<p>To facilitate JMX monitoring, the <code>HttpClient</code> instance is set as context attribute, prefixed with the servlet&#8217;s name and exposed by the mechanism provided by <code>ContextHandler.MANAGED_ATTRIBUTES</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="proxy-servlet-init">Init Parameters</h4>
<div class="paragraph">
<p>The following init parameters may be used to configure the servlet:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">hostHeader</dt>
<dd>
<p>forces the host header to a particular value</p>
</dd>
<dt class="hdlist1">viaHost</dt>
<dd>
<p>the name to use in the Via header: Via: http/1.1 &lt;viaHost&gt;</p>
</dd>
<dt class="hdlist1">whiteList</dt>
<dd>
<p>comma-separated list of allowed proxy hosts</p>
</dd>
<dt class="hdlist1">blackList</dt>
<dd>
<p>comma-separated list of forbidden proxy hosts</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>In addition, there are a number of init parameters that can be used to configure the <code>HttpClient</code> instance used internally for the proxy.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">maxThreads</dt>
<dd>
<p>Default Value: 256
The max number of threads of HttpClient&#8217;s Executor</p>
</dd>
<dt class="hdlist1">maxConnections</dt>
<dd>
<p>Default Value: 32768
The max number of connections per destination.
RFC 2616 suggests that 2 connections should be opened per each destination, but browsers commonly open 6 or more.
If this <code>HttpClient</code> is used for load testing, it is common to have only one destination (the server to load test), and it is recommended to set this value to a high value (at least as much as the threads present in the executor).</p>
</dd>
<dt class="hdlist1">idleTimeout</dt>
<dd>
<p>Default Value: 30000
The idle timeout in milliseconds that a connection can be idle, that is without traffic of bytes in either direction.</p>
</dd>
<dt class="hdlist1">timeout</dt>
<dd>
<p>Default Value: 60000
The total timeout in milliseconds for the request/response conversation.</p>
</dd>
<dt class="hdlist1">requestBufferSize</dt>
<dd>
<p>Default Value: 4096
The size of the request buffer the request is written into.</p>
</dd>
<dt class="hdlist1">responseBufferSize</dt>
<dd>
<p>Default Value: 4096
The size of the response buffer the response is written into.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="balancer-servlet">Balancer Servlet</h3>
<div class="sect3">
<h4 id="balancer-servlet-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.proxy.BalancerServlet</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-proxy</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/proxy/BalancerServlet.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/proxy/BalancerServlet.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="balancer-servlet-usage">Usage</h4>
<div class="paragraph">
<p>The Balancer servlet allows for simple, sticky round robin load balancing leveraging the <code>ProxyServlet</code> that is distributed with Jetty.</p>
</div>
<div class="paragraph">
<p>In addition to the parameters for <code>ProxyServlet</code>, the following are available for the balancer servlet:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">stickySessions</dt>
<dd>
<p>True if sessions should be sticky for subsequent requests</p>
</dd>
<dt class="hdlist1">balancerMember.&lt;name&gt;.proxyTo</dt>
<dd>
<p>One of more of these are required and will be the locations that are used to proxy traffic to.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="cgi-servlet">CGI Servlet</h3>
<div class="sect3">
<h4 id="cgi-servlet-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.servlets.CGI</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlets</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/CGI.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/CGI.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="cgi-servlet-usage">Usage</h4>
<div class="paragraph">
<p>The CGI servlet class extends the abstract HttpServlet class.
When the init parameter is called, the cgi bin directory is set with the <code>cgibinResourceBase</code>.
Otherwise, it defaults to the resource base of the context.</p>
</div>
<div class="paragraph">
<p>The cgi bin uses three parameters:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">commandPrefix</dt>
<dd>
<p>The init parameter obtained when there is a prefix set to all commands directed to the method exec.</p>
</dd>
<dt class="hdlist1">Path</dt>
<dd>
<p>An init parameter passed to the exec environment as a PATH.
This must be run unpacked somewhere in the filesystem.</p>
</dd>
<dt class="hdlist1">ENV_</dt>
<dd>
<p>An init parameter that points to an environment variable with the name stripped of the leading ENV_ and using the init parameter value.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="qos-filter">Quality of Service Filter</h3>
<div class="sect3">
<h4 id="qos-filter-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.servlets.QoSFilter</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlets</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/QoSFilter.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/QoSFilter.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="qos-filter-usage">Usage</h4>
<div class="paragraph">
<p>Jetty supports Continuations, which allow non-blocking handling of HTTP requests, so that threads can be allocated in a managed way to provide application specific Quality of Service (QoS).
The <code>QoSFilter</code> is a utility servlet filter that implements some QoS features.</p>
</div>
</div>
<div class="sect3">
<h4 id="qos-understanding">Understanding the Problem</h4>
<div class="sect4">
<h5>Waiting for Resources</h5>
<div class="paragraph">
<p>Web applications frequently use JDBC Connection pools to limit the simultaneous load on the database.
This protects the database from peak loads, but makes the web application vulnerable to thread starvation.
Consider a thread pool with 20 connections, being used by a web application that that typically receives 200 requests per second and each request holds a JDBC connection for 50ms.
Such a pool can service on average 200*20*1000/50 = 400 requests per second.</p>
</div>
<div class="paragraph">
<p>However, if the request rate rises above 400 per second, or if the database slows down (due to a large query) or becomes momentarily unavailable, the thread pool can very quickly accumulate many waiting requests.
If, for example, the website is "slashdotted" or experiences some other temporary burst of traffic and the request rate rises from 400 to 500 requests per second, then 100 requests per second join those waiting for a JDBC connection.
Typically, a web server&#8217;s thread pool contains only a few hundred threads, so a burst or slow DB need only persist for a few seconds to consume the entire web server&#8217;s thread pool; this is called thread starvation.
The key issue with thread starvation is that it effects the entire web application, and potentially the entire web server.
Even if the requests using the database are only a small proportion of the total requests on the web server, all requests are blocked because all the available threads are waiting on the JDBC connection pool.
This represents non-graceful degradation under load and provides a very poor quality of service.</p>
</div>
</div>
<div class="sect4">
<h5>Prioritizing Resources</h5>
<div class="paragraph">
<p>Consider a web application that is under extreme load.
This load might be due to a popularity spike (slashdot), usage burst (Christmas or close of business), or even a denial of service attack.
During such periods of load, it is often desirable not to treat all requests as equals, and to give priority to high value customers or administrative users.</p>
</div>
<div class="paragraph">
<p>The typical behavior of a web server under extreme load is to use all its threads to service requests and to build up a backlog of unserviced requests.
If the backlog grows deep enough, then requests start to timeout and users experience failures as well as delays.</p>
</div>
<div class="paragraph">
<p>Ideally, the web application should be able to examine the requests in the backlog, and give priority to high value customers and administrative users.
But with the standard blocking servlet API, it is not possible to examine a request without allocating a thread to that request for the duration of its handling.
There is no way to delay the handling of low priority requests, so if the resources are to be reallocated, then the low priority requests must all be failed.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="qos-applying">Applying the QoSFilter</h4>
<div class="paragraph">
<p>The Quality of Service Filter (QoSFilter) uses Continuations to avoid thread starvation, prioritize requests and give graceful degradation under load, to provide a high quality of service.
When you apply the filter to specific URLs within a web application, it limits the number of active requests being handled for those URLs.
Any requests in excess of the limit are suspended. When a request completes handling the limited URL, one of the waiting requests resumes and can be handled.
You can assign priorities to each suspended request, so that high priority requests resume before lower priority requests.</p>
</div>
<div class="sect4">
<h5>Required JARs</h5>
<div class="paragraph">
<p>To use the QoS Filter, these JAR files must be available in <code>WEB-INF/lib</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>$JETTY_HOME/lib/jetty-util.jar</p>
</li>
<li>
<p>$JETTY_HOME/lib/jetty-servlets.jar – contains QoSFilter</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5>Sample Configuration</h5>
<div class="paragraph">
<p>Place the configuration in a webapp&#8217;s <code>web.xml</code> or <code>jetty-web.xml</code>.
The default configuration processes ten requests at a time, servicing more important requests first and queuing up the rest.
This example processes fifty requests at a time:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;filter&gt;
&lt;filter-name&gt;QoSFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.eclipse.jetty.servlets.QoSFilter&lt;/filter-class&gt;
&lt;init-param&gt;
&lt;param-name&gt;maxRequests&lt;/param-name&gt;
&lt;param-value&gt;50&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;/filter&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="qos-filter-init">Configuring QoS Filter Parameters</h5>
<div class="paragraph">
<p>A semaphore polices the <code>maxRequests</code> limit.
The filter waits a short time while attempting to acquire the semaphore.
The <code>waitMs</code> init parameter controls the wait, avoiding the expense of a suspend if the semaphore is shortly available.
If the semaphore cannot be obtained, Jetty suspends the request for the default suspend period of the container or the value set as the <code>suspendMs</code> init parameter.</p>
</div>
<div class="paragraph">
<p>The QoS filter uses the following init parameters:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">maxRequests</dt>
<dd>
<p>The maximum number of requests to be serviced at a time. The default is 10.</p>
</dd>
<dt class="hdlist1">maxPriority</dt>
<dd>
<p>The maximum valid priority that can be assigned to a request.
A request with a high priority value is more important than a request with a low priority value. The default is 10.</p>
</dd>
<dt class="hdlist1">waitMs</dt>
<dd>
<p>The length of time, in milliseconds, to wait while trying to accept a new request.
Used when the maxRequests limit is reached.
Default is 50 ms.</p>
</dd>
<dt class="hdlist1">suspendMs</dt>
<dd>
<p>Length of time, in milliseconds, that the request will be suspended if it is not accepted immediately.
If not set, the container&#8217;s default suspend period applies. Default is -1 ms.</p>
</dd>
<dt class="hdlist1">managedAttr</dt>
<dd>
<p>If set to true, then this servlet is set as a <code>ServletContext</code> attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via <code>ContextHandler.MANAGED_ATTRIBUTES</code>) to manage the configuration of the filter.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>Mapping to URLs</h5>
<div class="paragraph">
<p>You can use the <code>&lt;filter-mapping&gt;</code> syntax to map the QoSFilter to a servlet, either by using the servlet name, or by using a URL pattern.
In this example, a URL pattern applies the QoSFilter to every request within the web application context:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;filter-mapping&gt;
&lt;filter-name&gt;QoSFilter&lt;/filter-name&gt;
&lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Setting the Request Priority</h5>
<div class="paragraph">
<p>Requests with higher values have a higher priority.
The default request priorities assigned by the QoSFilter are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>2&#8201;&#8212;&#8201;For any authenticated request</p>
</li>
<li>
<p>1&#8201;&#8212;&#8201;For any request with a non-new valid session</p>
</li>
<li>
<p>0&#8201;&#8212;&#8201;For all other requests</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To customize the priority, subclass QoSFilter and then override the <code>getPriority(ServletRequest request)</code> method to return an appropriate priority for the request.
You can then use this subclass as your QoS filter.
Here&#8217;s an example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">public class ParsePriorityQoSFilter extends QoSFilter
{
protected int getPriority(ServletRequest request)
{
String p = ((HttpServletRequest)request).getParameter("priority");
if (p!=null)
return Integer.parseInt(p);
return 0;
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="dos-filter">Denial of Service Filter</h3>
<div class="sect3">
<h4 id="dos-filter-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.servlets.DoSFilter</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlets</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/DoSFilter.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/DoSFilter.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="dos-filter-usage">Usage</h4>
<div class="paragraph">
<p>The Denial of Service (DoS) filter limits exposure to request flooding, whether malicious, or as a result of a misconfigured client.
The DoS filter keeps track of the number of requests from a connection per second.
If the requests exceed the limit, Jetty rejects, delays, or throttles the request, and sends a warning message.
The filter works on the assumption that the attacker might be written in simple blocking style, so by suspending requests you are hopefully consuming the attacker&#8217;s resources.</p>
</div>
</div>
<div class="sect3">
<h4 id="dos-filter-using">Using the DoS Filter</h4>
<div class="paragraph">
<p>Jetty places throttled requests in a priority queue, giving priority first to authenticated users and users with an HttpSession, then to connections identified by their IP addresses.
Connections with no way to identify them have lowest priority.
To uniquely identify authenticated users, you should implement the The extractUserId(ServletRequest request) function.</p>
</div>
<div class="sect4">
<h5>Required JARs</h5>
<div class="paragraph">
<p>To use the DoS Filter, these JAR files must be available in WEB-INF/lib:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>$JETTY_HOME/lib/jetty-util.jar</p>
</li>
<li>
<p>$JETTY_HOME/lib/jetty-servlets.jar</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5>Sample Configuration</h5>
<div class="paragraph">
<p>Place the configuration in a webapp&#8217;s <code>web.xml</code> or <code>jetty-web.xml</code>.
The default configuration allows 25 requests per connection at a time, servicing more important requests first, and queuing up the rest.
This example allow 30 requests at a time:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;filter&gt;
&lt;filter-name&gt;DoSFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.eclipse.jetty.servlets.DoSFilter&lt;/filter-class&gt;
&lt;init-param&gt;
&lt;param-name&gt;maxRequestsPerSec&lt;/param-name&gt;
&lt;param-value&gt;30&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;/filter&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="dos-filter-init">Configuring DoS Filter Parameters</h5>
<div class="paragraph">
<p>The following <code>init</code> parameters control the behavior of the filter:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">maxRequestsPerSec</dt>
<dd>
<p>Maximum number of requests from a connection per second.
Requests in excess of this are first delayed, then throttled.
Default is 25.</p>
</dd>
<dt class="hdlist1">delayMs</dt>
<dd>
<p>Delay imposed on all requests over the rate limit, before they are considered at all:</p>
<div class="ulist">
<ul>
<li>
<p>100 (ms) = Default</p>
</li>
<li>
<p>-1 = Reject request</p>
</li>
<li>
<p>0 = No delay</p>
</li>
<li>
<p>any other value = Delay in ms</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1">maxWaitMs</dt>
<dd>
<p>Length of time, in ms, to blocking wait for the throttle semaphore.
Default is 50 ms.</p>
</dd>
<dt class="hdlist1">throttledRequests</dt>
<dd>
<p>Number of requests over the rate limit able to be considered at once.
Default is 5.</p>
</dd>
<dt class="hdlist1">throttleMs</dt>
<dd>
<p>Length of time, in ms, to async wait for semaphore. Default is 30000L.</p>
</dd>
<dt class="hdlist1">maxRequestMs</dt>
<dd>
<p>Length of time, in ms, to allow the request to run. Default is 30000L.</p>
</dd>
<dt class="hdlist1">maxIdleTrackerMs</dt>
<dd>
<p>Length of time, in ms, to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
Default is 30000L.</p>
</dd>
<dt class="hdlist1">insertHeaders</dt>
<dd>
<p>If true, insert the DoSFilter headers into the response.
Defaults to true.</p>
</dd>
<dt class="hdlist1">trackSessions</dt>
<dd>
<p>If true, usage rate is tracked by session if a session exists.
Defaults to true.</p>
</dd>
<dt class="hdlist1">remotePort</dt>
<dd>
<p>If true and session tracking is not used, then rate is tracked by IP and port (effectively connection).
Defaults to false.</p>
</dd>
<dt class="hdlist1">ipWhitelist</dt>
<dd>
<p>A comma-separated list of IP addresses that will not be rate limited.</p>
</dd>
<dt class="hdlist1">managedAttr</dt>
<dd>
<p>If set to true, then this servlet is set as a ServletContext attribute with the filter name as the attribute name.
This allows a context external mechanism (for example, JMX via <code>ContextHandler.MANAGED_ATTRIBUTES</code>) to manage the configuration of the filter.</p>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="header-filter">Header Filter</h3>
<div class="sect3">
<h4 id="header-filter-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.servlets.HeaderFilter</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlets</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/HeaderFilter.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/HeaderFilter.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="header-filter-usage">Usage</h4>
<div class="paragraph">
<p>The header filter sets or adds headers to each response based on an optionally included/excluded list of path specs, mime types, and/or HTTP methods.
This filter processes its configured headers before calling <code>doFilter</code> in the filter chain. Some of the headers configured in this filter may get overwritten by other filters and/or the servlet processing the request.</p>
</div>
<div class="sect4">
<h5>Required JARs</h5>
<div class="paragraph">
<p>To use the Header Filter, these JAR files must be available in WEB-INF/lib:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>$JETTY_HOME/lib/jetty-http.jar</p>
</li>
<li>
<p>$JETTY_HOME/lib/jetty-servlets.jar</p>
</li>
<li>
<p>$JETTY_HOME/lib/jetty-util.jar</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5>Sample Configuration</h5>
<div class="paragraph">
<p>Place the configuration in a webapp&#8217;s <code>web.xml</code> or <code>jetty-web.xml</code>.
This filter will perform the following actions on each response:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Set the X-Frame-Options header to DENY.</p>
</li>
<li>
<p>Add a Cache-Control header containing no-cache, no-store, must-revalidate</p>
</li>
<li>
<p>Set the Expires header to approximately one year in the future.</p>
</li>
<li>
<p>Add a Date header with the current system time.</p>
</li>
</ul>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Each action must be separated by a comma.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;filter&gt;
&lt;filter-name&gt;HeaderFilter&lt;/filter-name&gt;
&lt;filter-class&gt;org.eclipse.jetty.servlets.HeaderFilter&lt;/filter-class&gt;
&lt;init-param&gt;
&lt;param-name&gt;headerConfig&lt;/param-name&gt;
&lt;param-value&gt;
set X-Frame-Options: DENY,
"add Cache-Control: no-cache, no-store, must-revalidate",
setDate Expires: 31540000000,
addDate Date: 0
&lt;/param-value&gt;
&lt;/init-param&gt;
&lt;/filter&gt;</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="header-filter-init">Configuring Header Filter Parameters</h5>
<div class="paragraph">
<p>The following <code>init</code> parameters control the behavior of the filter:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">includedPaths</dt>
<dd>
<p>Optional. Comma separated values of included path specs.</p>
</dd>
<dt class="hdlist1">excludedPaths</dt>
<dd>
<p>Optional. Comma separated values of excluded path specs.</p>
</dd>
<dt class="hdlist1">includedMimeTypes</dt>
<dd>
<p>Optional. Comma separated values of included mime types. The mime type will be guessed from the extension at the end of the request URL if the content type has not been set on the response.</p>
</dd>
<dt class="hdlist1">excludedMimeTypes</dt>
<dd>
<p>Optional. Comma separated values of excluded mime types. The mime type will be guessed from the extension at the end of the request URL if the content type has not been set on the response.</p>
</dd>
<dt class="hdlist1">includedHttpMethods</dt>
<dd>
<p>Optional. Comma separated values of included http methods.</p>
</dd>
<dt class="hdlist1">excludedHttpMethods</dt>
<dd>
<p>Optional. Comma separated values of excluded http methods.</p>
</dd>
<dt class="hdlist1">headerConfig</dt>
<dd>
<p>Comma separated values of actions to perform on headers. The syntax for each action is <code>action headerName: headerValue</code>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Supported header actions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>set</code> - causes set <code>setHeader</code> to be called on the response</p>
</li>
<li>
<p><code>add</code> - causes set <code>addHeader</code> to be called on the response</p>
</li>
<li>
<p><code>setDate</code> - causes <code>setDateHeader</code> to be called on the response.</p>
</li>
<li>
<p><code>addDate</code> - causes <code>addDateHeader</code> to be called on the response.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If <code>setDate</code> or <code>addDate</code> is used, <code>headerValue</code> should be the number of milliseconds to add to the current system time before writing the header value.</p>
</div>
<div class="paragraph">
<p>If a property is both included and excluded by the filter configuration, then it will be considered excluded.</p>
</div>
<div class="paragraph">
<p>Path spec rules:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If the spec starts with <code>^</code>, the spec is assumed to be a regex based path spec and will match with normal Java regex rules.</p>
</li>
<li>
<p>If the spec starts with <code>/</code>, the spec is assumed to be a Servlet url-pattern rules path spec for either an exact match or prefix based match.</p>
</li>
<li>
<p>If the spec starts with <code>*.</code>, the spec is assumed to be a Servlet url-pattern rules path spec for a suffix based match.</p>
</li>
<li>
<p>All other syntaxes are unsupported.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="gzip-filter">Gzip Handler</h3>
<div class="sect3">
<h4 id="gzip-filter-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.gzip.GzipHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlets</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/gzip/GzipHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/gzip/GzipHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="gzip-filter-usage">Usage</h4>
<div class="paragraph">
<p>The Jetty <code>GzipHandler</code> is a compression handler that you can apply to any dynamic resource (servlet).
It fixes many of the bugs in commonly available compression filters: it works with asynchronous servlets; it handles all ways to set content length.
Some user-agents might be excluded from compression to avoid common browser bugs (yes, this means IE!).</p>
</div>
<div class="paragraph">
<p>The <code>GzipHandler</code> can be added to the entire server by enabling the <code>gzip.mod</code> module.
It may also be added to individual contexts in a context xml file.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Jetty 9 only compresses using GZip.
Using deflate HTTP compression is not supported and will not function.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="gzip-filter-rules">Gzip Rules</h4>
<div class="paragraph">
<p><code>GzipHandler</code> will gzip the content of a response if:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>It is mapped to a matching path</p>
</li>
<li>
<p>The request method is configured to support gzip</p>
</li>
<li>
<p>The request is not from an excluded User-Agent</p>
</li>
<li>
<p>accept-encoding header is set to gzip</p>
</li>
<li>
<p>The response status code is &gt;=200 and &lt;300</p>
</li>
<li>
<p>The content length is unknown or more than the minGzipSize initParameter or the minGzipSize is 0(default)</p>
</li>
<li>
<p>The content-type does not match an excluded mime-type</p>
</li>
<li>
<p>No content-encoding is specified by the resource</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Compressing the content can greatly improve the network bandwidth usage, but at the cost of memory and CPU cycles.
The <a href="#default-servlet">DefaultServlet</a> is capable of serving pre-compressed static content, which saves memory and CPU.</p>
</div>
<div class="paragraph">
<p>The <code>GzipHandler</code> installs an output interceptor which passes through to the <code>DefaultServlet</code>.
If the content served by <code>DefaultServlet</code> is already compressed, the <code>GzipHandler</code> does nothing; if it is not compressed, the content is compressed on-the-fly.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Automatic precompression by the <code>DefaultServlet</code> can be configured.
Read more about the <code>DefaultServlet</code> <a href="#default-servlet">here.</a>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="gzip-filter-init">Gzip Configuration</h4>
<div class="dlist">
<dl>
<dt class="hdlist1">minGzipSize</dt>
<dd>
<p>Content will only be compressed if content length is either unknown or greater than <code>minGzipSize</code>.</p>
</dd>
<dt class="hdlist1">checkGzExists (Deprecated)</dt>
<dd>
<p>False by default.
If set to true, the handler will check for pre-compressed content.</p>
</dd>
<dt class="hdlist1">includedMethods</dt>
<dd>
<p>List of HTTP methods to compress.
If not set, only <code>GET</code> requests are compressed.</p>
</dd>
<dt class="hdlist1">includedMimeTypes</dt>
<dd>
<p>List of MIME types to compress.</p>
</dd>
<dt class="hdlist1">excludedMimeTypes</dt>
<dd>
<p>List of MIME types not to compress.</p>
</dd>
<dt class="hdlist1">excludedAgentPatterns</dt>
<dd>
<p>A list of regex patterns for User-Agent names from which requests should not be compressed.</p>
</dd>
<dt class="hdlist1">excludedPaths</dt>
<dd>
<p>List of paths to exclude from compression.
Performs a <code>String.startsWith(String)</code> comparison to check if the path matches.
If it does match then there is no compression.
To match subpaths use excludePathPatterns instead.</p>
</dd>
<dt class="hdlist1">includedPaths</dt>
<dd>
<p>List of paths to consider for compression.</p>
</dd>
<dt class="hdlist1">includePaths</dt>
<dd>
<p>List of paths to definitely consider for compression.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="cross-origin-filter">Cross Origin Filter</h3>
<div class="sect3">
<h4 id="cross-origin-filter-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.servlets.CrossOriginFilter</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-servlets</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/CrossOriginFilter.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/servlets/CrossOriginFilter.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="cross-origin-filter-usage">Usage</h4>
<div class="paragraph">
<p>HTTP requests made from a script are subject to well known restrictions, the most prominent being the same domain policy.</p>
</div>
<div class="paragraph">
<p>Firefox 3.5 introduced support for W3C&#8217;s Access Control for Cross-Site Requests specification, which requires a compliant client (for example, Firefox 3.5) and a compliant server (via this servlet filter).</p>
</div>
<div class="paragraph">
<p>This filter implements the required bits to support the server-side contract of the specification, and will allow a compliant client to perform cross-domain requests via the standard XMLHttpRequest object.
If the client does not issue a compliant cross-domain request, this filter does nothing, and its overhead is the check of the presence of the cross-domain HTTP header.</p>
</div>
<div class="paragraph">
<p>This is extremely useful in CometD web applications where it is now possible to perform cross-domain long polling without using script injection (also known as the JSONP transport), and therefore removing all the downsides that the JSONP transport has (it&#8217;s chattier, does not react quickly to failures, has a message size limit, uses GET instead of POST, etc.).</p>
</div>
</div>
<div class="sect3">
<h4 id="cross-origin-setup">Setup</h4>
<div class="paragraph">
<p>You will need to put the <code>jetty-servlets.jar</code> file onto your classpath.
If you are creating a webapp, ensure that this jar is included in your webapp&#8217;s <code>WEB-INF/lib</code>.
Or, if you are running Jetty embedded you will need to ensure that <code>jetty-servlets.jar</code> is on the execution classpath.
You can download the <code>jetty-servlets.jar</code> from the Maven Central Repository at <a href="https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-servlets/" class="bare">https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-servlets/</a>.
It is also available as part of the Jetty distribution in the <code>$JETTY_HOME/lib</code> directory.</p>
</div>
</div>
<div class="sect3">
<h4 id="cross-origin-config">Configuration</h4>
<div class="paragraph">
<p>This is a regular servlet filter that must be configured in <code>web.xml</code>.</p>
</div>
<div class="paragraph">
<p>It supports the following configuration parameters:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">allowedOrigins</dt>
<dd>
<p>A comma separated list of origins that are allowed to access the resources.
Default value is: * (all origins)</p>
</dd>
<dt class="hdlist1">allowedMethods</dt>
<dd>
<p>A comma separated list of HTTP methods that are allowed to be used when accessing the resources.
Default value is: GET,POST,HEAD</p>
</dd>
<dt class="hdlist1">allowedHeaders</dt>
<dd>
<p>A comma separated list of HTTP headers that are allowed to be specified when accessing the resources.
Default value is: X-Requested-With,Content-Type,Accept,Origin</p>
</dd>
<dt class="hdlist1">allowCredentials</dt>
<dd>
<p>A boolean indicating if the resource allows requests with credentials.
Default value is: true</p>
</dd>
<dt class="hdlist1">preflightMaxAge</dt>
<dd>
<p>The number of seconds that preflight requests can be cached by the client.
Default value is 1800 seconds (30 minutes)</p>
</dd>
<dt class="hdlist1">chainPreflight</dt>
<dd>
<p>If true preflight requests are chained to their target resource for normal handling (as an OPTION request).
Otherwise the filter will response to the preflight.
Default is true.</p>
</dd>
<dt class="hdlist1">exposedHeaders</dt>
<dd>
<p>A comma separated list of HTTP headers that are allowed to be exposed on the client.
Default value is the empty list.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>A typical configuration could be:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;web-app&gt;
&lt;filter&gt;
&lt;filter-name&gt;cross-origin&lt;/filter-name&gt;
&lt;filter-class&gt;org.eclipse.jetty.servlets.CrossOriginFilter&lt;/filter-class&gt;
&lt;/filter&gt;
&lt;filter-mapping&gt;
&lt;filter-name&gt;cross-origin&lt;/filter-name&gt;
&lt;url-pattern&gt;/cometd/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
&lt;/web-app&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="resource-handler">Resource Handler</h3>
<div class="sect3">
<h4 id="resource-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.ResourceHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ResourceHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ResourceHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="resource-handler-usage">Usage</h4>
<div class="paragraph">
<p>This handler will serve static content and handle If-Modified-Since headers and is suitable for simple serving of static content.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
There is no caching done with this handler, so if you are looking for a more fully featured way of serving static content look to the <a href="#default-servlet">Default Servlet</a>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Requests for resources that do not exist are let pass (Eg no 404&#8217;s).
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Improving the Look and Feel</h4>
<div class="paragraph">
<p>The resource handler has a default stylesheet which you can change by calling <code>setStyleSheet(String location)</code> with the location of a file on the system that it can locate through the resource loading system.
The default css is called <code>jetty-dir.css</code> and is located in the <code>jetty-util</code> package, pulled as a classpath resource from the <code>jetty-util</code> jar when requested through the <code>ResourceHandler</code>.</p>
</div>
</div>
<div class="sect3">
<h4>Embedded Example</h4>
<div class="paragraph">
<p>The following is an example of a split fileserver, able to serve static content from multiple directory locations.
Since this handler does not return 404&#8217;s on content you are able to iteratively try multiple resource handlers to resolve content.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">//
// ========================================================================
// 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
// ========================================================================
//
package org.eclipse.jetty.embedded;
import java.nio.file.Paths;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.ServerConnector;
import org.eclipse.jetty.server.handler.ContextHandler;
import org.eclipse.jetty.server.handler.ContextHandlerCollection;
import org.eclipse.jetty.server.handler.ResourceHandler;
import org.eclipse.jetty.util.resource.PathResource;
import org.eclipse.jetty.util.resource.Resource;
/**
* A {@link ContextHandlerCollection} handler may be used to direct a request to
* a specific Context. The URI path prefix and optional virtual host is used to
* select the context.
*/
public class SplitFileServer
{
public static Server createServer(int port, Resource baseResource0, Resource baseResource1)
{
// Create the Server object and a corresponding ServerConnector and then
// set the port for the connector. In this example the server will
// listen on port 8080. If you set this to port 0 then when the server
// has been started you can called connector.getLocalPort() to
// programmatically get the port the server started on.
Server server = new Server();
ServerConnector connector = new ServerConnector(server);
connector.setPort(port);
server.addConnector(connector);
// Create a Context Handler and ResourceHandler. The ContextHandler is
// getting set to "/" path but this could be anything you like for
// building out your url. Note how we are setting the ResourceBase using
// our jetty maven testing utilities to get the proper resource
// directory, you needn't use these, you simply need to supply the paths
// you are looking to serve content from.
ResourceHandler rh0 = new ResourceHandler();
rh0.setDirectoriesListed(false);
ContextHandler context0 = new ContextHandler();
context0.setContextPath("/");
context0.setBaseResource(baseResource0);
context0.setHandler(rh0);
// Rinse and repeat the previous item, only specifying a different
// resource base.
ResourceHandler rh1 = new ResourceHandler();
rh1.setDirectoriesListed(false);
ContextHandler context1 = new ContextHandler();
context1.setContextPath("/");
context1.setBaseResource(baseResource1);
context1.setHandler(rh1);
// Create a ContextHandlerCollection and set the context handlers to it.
// This will let jetty process urls against the declared contexts in
// order to match up content.
ContextHandlerCollection contexts = new ContextHandlerCollection(
context0, context1
);
server.setHandler(contexts);
return server;
}
public static void main(String[] args) throws Exception
{
int port = ExampleUtil.getPort(args, "jetty.http.port", 8080);
Resource resource0 = new PathResource(Paths.get("src/test/resources/dir0"));
Resource resource1 = new PathResource(Paths.get("src/test/resources/dir1"));
Server server = createServer(port, resource0, resource1);
// Dump the server state
server.setDumpAfterStart(true);
// Start things up!
server.start();
// The use of server.join() the will make the current thread join and
// wait until the server is done executing.
server.join();
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="debug-handler">Debug Handler</h3>
<div class="sect3">
<h4 id="debug-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.DebugHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/DebugHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/DebugHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="debug-handler-usage">Usage</h4>
<div class="paragraph">
<p>A simple handler that is useful to debug incoming traffic.
It will log entry and exit points of HTTP requests as well as the response code.</p>
</div>
</div>
<div class="sect3">
<h4>Usage in Standard Distribution</h4>
<div class="paragraph">
<p>The debug handler can be added to Jetty by activating the <code>debug</code> module.</p>
</div>
</div>
<div class="sect3">
<h4>Embedded usage</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">Server server = new Server(8080);
RolloverFileOutputStream outputStream = new RolloverFileOutputStream("MeinLogPfad/yyyy_mm_dd.request.log", true,10);
DebugHandler debugHandler = new DebugHandler();
debugHandler.setOutputStream(outputStream);
debugHandler.setHandler(server.getHandler());
server.setHandler(debugHandler);
server.start();</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4>Example output</h4>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-bash" data-lang="bash">15:14:05.838:qtp551889550-13-selector-0 OPENED HttpConnection@e910ee4{IDLE},g=HttpGenerator{s=START},p=HttpParser{s=START,0 of 0}
15:14:05.846:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/ REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:05.894:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/ RESPONSE 200 null
15:14:05.959:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/jetty.css REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:05.962:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/jetty.css RESPONSE 200 null
15:14:06.052:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/images/jetty-header.jpg REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:06.055:qtp551889550-57:http://0:0:0:0:0:0:0:1:8080/images/jetty-header.jpg RESPONSE 200 null
15:14:07.248:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/favicon.ico REQUEST 0:0:0:0:0:0:0:1 GET __utma=111872281.10102721.1321534299.1369833564.1370447492.35; __utmz=111872281.1321534299.1.1.utmcsr=(direct)|utmccn=(direct)|utmcmd=(none); _opt_vi_RPY720HZ=75E12E63-0CD0-4D6F-8383-C90D5C8397C7; visited=yes; Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0
15:14:07.251:qtp551889550-59:http://0:0:0:0:0:0:0:1:8080/favicon.ico RESPONSE 404 text/html;charset=ISO-8859-1
15:14:09.330:qtp551889550-57 CLOSED HttpConnection@e910ee4{INTERESTED},g=HttpGenerator{s=START},p=HttpParser{s=START,0 of -1}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="statistics-handler">Statistics Handler</h3>
<div class="sect3">
<h4 id="statistics-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.StatisticsHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/StatisticsHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/StatisticsHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="statistics-handler-usage">Usage</h4>
<div class="paragraph">
<p>Jetty currently has two levels of request statistic collection:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Subclasses of <code>AbstractConnector</code> class optionally can collect statistics about connections as well as number of requests.</p>
</li>
<li>
<p>The <code>StatisticsHandler</code> class may be used to collect request statistics.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In addition to these, subclasses of the <code>SessionHandler</code> and <code>DefaultSessionCache</code> classes optionally can collect session statistics.</p>
</div>
<div class="paragraph">
<p><code>AbstractConnector</code>, <code>SessionHandler</code> and <code>DefaultSessionCache</code> statistics are turned off by default and must either be configured manually for each instance or turned on via JMX interface.
The <code>StatisticsHandler</code> is not included in default Jetty configuration, and needs to be configured manually.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
To view statistics, you have to be able to connect to Jetty using either JConsole or some other JMX agent. See <a href="#using-jmx">Using JMX with Jetty</a> for more information.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4 id="connector-statistics">Connector statistics</h4>
<div class="paragraph">
<p>Detailed statistics on connection duration and number of requests are only collated when a connection is closed.
The current and maximum number of connections are the only "live" statistics.</p>
</div>
<div class="paragraph">
<p>The following example shows how to turn on connector statistics in Jetty xml.
This example comes from within <code>jetty-http.xml</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;Call name="addConnector"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.server.ServerConnector"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid="Server" /&gt;&lt;/Arg&gt;
&lt;Arg name="factories"&gt;
&lt;Array type="org.eclipse.jetty.server.ConnectionFactory"&gt;
&lt;Item&gt;
&lt;New class="org.eclipse.jetty.server.HttpConnectionFactory"&gt;
&lt;Arg name="config"&gt;&lt;Ref refid="httpConfig" /&gt;&lt;/Arg&gt;
&lt;/New&gt;
&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Arg&gt;
&lt;Set name="host"&gt;&lt;Property name="jetty.host" /&gt;&lt;/Set&gt;
&lt;Set name="port"&gt;&lt;Property name="jetty.http.port" default="8080" /&gt;&lt;/Set&gt;
&lt;Set name="idleTimeout"&gt;30000&lt;/Set&gt;
&lt;!-- Enable Connection Statistics --&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New id="ConnectionStatistics" class="org.eclipse.jetty.io.ConnectionStatistics"/&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="request-statistics">Request Statistics</h4>
<div class="paragraph">
<p>To collect request statistics a <code>StatisticsHandler</code> must be configured as one of the handlers of the server.
Typically this can be done as the top level handler, but you may choose to configure a statistics handler for just one context by creating a context configuration file.
You can enable the <code>StatisticsHandler</code> by activating the <code>stats</code> modules on the command line.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar {$jetty.home}/start.jar --add-to-start=stats</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternately, if you are making multiple changes to the Jetty configuration, you could include statistics handler configuration into your own Jetty xml configuration.
The following fragment shows how to configure a top level statistics handler:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml"> &lt;Get id="oldhandler" name="handler" /&gt;
&lt;Set name="handler"&gt;
&lt;New id="StatsHandler" class="org.eclipse.jetty.server.handler.StatisticsHandler"&gt;
&lt;Set name="handler"&gt;&lt;Ref refid="oldhandler" /&gt;&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="session-statistics">Session Statistics</h4>
<div class="paragraph">
<p>Session handling is built into Jetty for any servlet or webapp context.
Detailed statistics on session duration are only collated when a session is closed.
The current, minimum, and maximum number of sessions are the only "live" statistics.
The session statistics are enabled by default and do not need to be configured.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="inetaccess-handler">InetAccess Handler</h3>
<div class="sect3">
<h4 id="inetaccess-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.InetAccessHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/InetAccessHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/InetAccessHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="inetaccess-handler-usage">Usage</h4>
<div class="paragraph">
<p>Controls access to the wrapped handler using the real remote IP. Control is provided by and <code>IncludeExcludeSet</code> over a <code>InetAddressSet</code>.
This handler uses the real internet address of the connection, not one reported in the forwarded for headers, as this cannot be as easily forged.</p>
</div>
</div>
<div class="sect3">
<h4>Usage in Standard Distribution</h4>
<div class="paragraph">
<p>The InetAccess handler can be added to Jetty by activating the <code>inetaccess</code> module.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="moved-context-handler">Moved Context Handler</h3>
<div class="sect3">
<h4 id="moved-context-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.MovedContextHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/MovedContextHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/MovedContextHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="moved-context-handler-usage">Usage</h4>
<div class="paragraph">
<p>You can use the <code>MovedContextHandler</code> to relocate or redirect a context that has changed context path and/or virtual hosts.</p>
</div>
<div class="paragraph">
<p>You can configure it to <em>permanently</em> redirect the old URL to the new URL, in which case Jetty sends a Http Status code of 301 to the browser with the new URL.
Alternatively, you can make it non-permanent, in which case Jetty sends a 302 Http Status code along with the new URL.</p>
</div>
<div class="paragraph">
<p>In addition, as with any other context, you can configure a list of virtual hosts, meaning that this context responds only to requests to one of the listed host names.</p>
</div>
<div class="paragraph">
<p>Suppose you have a context deployed at <code>/foo</code>, but that now you want to deploy at the root context <code>/</code> instead.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>First you reconfigure and redeploy the context on Jetty.</p>
</li>
<li>
<p>Next you need a way to redirect all the browsers who have bookmarked <code>/foo</code> to the new path.
You create a new <a href="#configuring-contexts">context xml</a> file in <code>{$jetty/.base}/webapps</code> and configure the <code>MovedContextHandler</code> to do the redirection from <code>/foo</code> to <code>/</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Below is an example.
This is a permanent redirection, which also preserves <code>pathinfo</code> and query strings on the redirect:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.server.handler.MovedContextHandler"&gt;
&lt;Set name="contextPath"&gt;/foo&lt;/Set&gt;
&lt;Set name="newContextURL"&gt;/&lt;/Set&gt;
&lt;Set name="permanent"&gt;true&lt;/Set&gt;
&lt;Set name="discardPathInfo"&gt;false&lt;/Set&gt;
&lt;Set name="discardQuery"&gt;false&lt;/Set&gt;
&lt;Set name="virtualHosts"&gt;
&lt;Array type="String"&gt;
&lt;Item&gt;209.235.245.73&lt;/Item&gt;
&lt;Item&gt;127.0.0.73&lt;/Item&gt;
&lt;Item&gt;acme.org&lt;/Item&gt;
&lt;Item&gt;www.acme.org&lt;/Item&gt;
&lt;Item&gt;server.acme.org&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="shutdown-handler">Shutdown Handler</h3>
<div class="sect3">
<h4 id="shutdown-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.ShutdownHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ShutdownHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ShutdownHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="shutdown-handler-usage">Usage</h4>
<div class="paragraph">
<p>A handler that shuts the server down on a valid request.
This is used to perform "soft" restarts from Java.
If <code>_exitJvm</code> is set to true a hard <code>System.exit()</code> call is being made.</p>
</div>
<div class="paragraph">
<p>This is an example of how you can setup this handler directly with the Server.
It can also be added as a part of handler chain or collection.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java"> Server server = new Server(8080);
HandlerList handlers = new HandlerList();
handlers.setHandlers(new Handler[]
{ someOtherHandler, new ShutdownHandler(server,"secret password") });
server.setHandler(handlers);
server.start();</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is an example that you can use to call the shutdown handler from within java.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java"> public static void attemptShutdown(int port, String shutdownCookie) {
try {
URL url = new URL("http://localhost:" + port + "/shutdown?token=" + shutdownCookie);
HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("POST");
connection.getResponseCode();
logger.info("Shutting down " + url + ": " + connection.getResponseMessage());
} catch (SocketException e) {
logger.debug("Not running");
// Okay - the server is not running
} catch (IOException e) {
throw new RuntimeException(e);
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="default-handler">Default Handler</h3>
<div class="sect3">
<h4 id="default-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.DefaultHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/DefaultHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/DefaultHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="default-handler-usage">Usage</h4>
<div class="paragraph">
<p>A simple handler that is useful to terminate handler chains with a clean fashion.
As in the example below, if a resource to be served is not matched within the resource handler the <code>DefaultHandler</code> will take care of producing a 404 page.
This class is a useful template to either extend and embrace or simply provide a similar implementation for customizing to your needs.
There is also an <a href="#error-handler">Error Handler</a> that services errors related to the servlet api specification, so it is best to not get the two confused.</p>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The <code>DefaultHandler</code> will also handle serving out the <code>flav.ico</code> file should a request make it through all of the other handlers without being resolved.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java"> Server server = new Server(8080);
HandlerList handlers = new HandlerList();
ResourceHandler resourceHandler = new ResourceHandler();
resourceHandler.setBaseResource(Resource.newResource("."));
handlers.setHandlers(new Handler[]
{ resourceHandler, new DefaultHandler() });
server.setHandler(handlers);
server.start();</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="error-handler">Error Handler</h3>
<div class="sect3">
<h4 id="error-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: <code>org.eclipse.jetty.server.handler.ErrorHandler</code></p>
</li>
<li>
<p>Maven Artifact: org.eclipse.jetty:jetty-server</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ErrorHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/handler/ErrorHandler.html</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="error-handler-usage">Usage</h4>
<div class="paragraph">
<p>A handler that is used to report errors from servlet contexts and webapp contexts to report error conditions.
Primarily handles setting the various servlet spec specific response headers for error conditions.
Can be customized by extending; for more information on this see <a href="#custom-error-pages">Creating Custom Error Pages</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="rewrite-handler">Rewrite Handler</h3>
<div class="paragraph">
<p>The <code>RewriteHandler</code> matches a request against a set of rules, and modifies the request accordingly for any rules that match.
The most common use is to rewrite request URIs, but it is capable of much more: rules can also be configured to redirect the response, set a cookie or response code on the response, modify the header, etc.</p>
</div>
<div class="sect3">
<h4 id="rewrite-handler-metadata">Info</h4>
<div class="ulist">
<ul>
<li>
<p>Classname: org.eclipse.jetty.rewrite.handler.RewriteHandler</p>
</li>
<li>
<p>Maven artifact: org.eclipse.jetty:jetty-rewrite</p>
</li>
<li>
<p>Javadoc: <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/RewriteHandler.html" class="bare">http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/RewriteHandler.html</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The standard Jetty distribution bundle contains the <code>jetty-rewrite</code> <a href="#startup-modules">module</a>, so all you need to do is to enable it using one of the <a href="#start-jar">module commands</a>, eg:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ java -jar start.jar --add-to-start=rewrite</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If you are running the standard Jetty distribution with the sample test webapp, there will be a demo of the rewrite module at <a href="http://localhost:8080/test/rewrite/" class="bare">http://localhost:8080/test/rewrite/</a>
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect3">
<h4>Usage</h4>
<div class="paragraph">
<p>The rewrite module enables the following Jetty xml config file on the execution path:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd"&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;!-- =========================================================== --&gt;
&lt;!-- configure rewrite handler --&gt;
&lt;!-- =========================================================== --&gt;
&lt;Call name="insertHandler"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.RewriteHandler"&gt;
&lt;Set name="rewriteRequestURI" property="jetty.rewrite.rewriteRequestURI"/&gt;
&lt;Set name="rewritePathInfo" property="jetty.rewrite.rewritePathInfo"/&gt;
&lt;Set name="originalPathAttribute" property="jetty.rewrite.originalPathAttribute"/&gt;
&lt;!-- Set DispatcherTypes --&gt;
&lt;Set name="dispatcherTypes"&gt;
&lt;Array type="javax.servlet.DispatcherType"&gt;
&lt;Item&gt;&lt;Call class="javax.servlet.DispatcherType" name="valueOf"&gt;&lt;Arg&gt;REQUEST&lt;/Arg&gt;&lt;/Call&gt;&lt;/Item&gt;
&lt;Item&gt;&lt;Call class="javax.servlet.DispatcherType" name="valueOf"&gt;&lt;Arg&gt;ASYNC&lt;/Arg&gt;&lt;/Call&gt;&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;Get id="Rewrite" name="ruleContainer"/&gt;
&lt;!-- see rewrite-rules.xml in $JETTY_BASE for how to add a rule(s) --&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>As the commented out code shows, you configure the <code>RewriteHandler</code> by adding various rules.</p>
</div>
<div class="paragraph">
<p>There is an example of <a href="#rewrite-rules">rules</a> configuration in the standard distribution in the <code>demo-base/etc/demo-rewrite-rules.xml</code> file:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd"&gt;
&lt;!-- =============================================================== --&gt;
&lt;!-- Configure the demos --&gt;
&lt;!-- =============================================================== --&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;!-- ============================================================= --&gt;
&lt;!-- Add rewrite rules --&gt;
&lt;!-- ============================================================= --&gt;
&lt;Ref refid="Rewrite"&gt;
&lt;!-- Add rule to protect against IE ssl bug --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.MsieSslRule"/&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- protect favicon handling --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.HeaderPatternRule"&gt;
&lt;Set name="pattern"&gt;/favicon.ico&lt;/Set&gt;
&lt;Set name="name"&gt;Cache-Control&lt;/Set&gt;
&lt;Set name="value"&gt;Max-Age=3600,public&lt;/Set&gt;
&lt;Set name="terminating"&gt;true&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- redirect from the welcome page to a specific page --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule"&gt;
&lt;Set name="pattern"&gt;/test/rewrite/&lt;/Set&gt;
&lt;Set name="replacement"&gt;/test/rewrite/info.html&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- replace the entire request URI --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule"&gt;
&lt;Set name="pattern"&gt;/test/some/old/context&lt;/Set&gt;
&lt;Set name="replacement"&gt;/test/rewritten/newcontext&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- replace the beginning of the request URI --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.RewritePatternRule"&gt;
&lt;Set name="pattern"&gt;/test/rewrite/for/*&lt;/Set&gt;
&lt;Set name="replacement"&gt;/test/rewritten/&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- reverse the order of the path sections --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.RewriteRegexRule"&gt;
&lt;Set name="regex"&gt;(.*?)/reverse/([^/]*)/(.*)&lt;/Set&gt;
&lt;Set name="replacement"&gt;$1/reverse/$3/$2&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- add a cookie to each path visited --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.CookiePatternRule"&gt;
&lt;Set name="pattern"&gt;/*&lt;/Set&gt;
&lt;Set name="name"&gt;visited&lt;/Set&gt;
&lt;Set name="value"&gt;yes&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- actual redirect, instead of internal rewrite --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.RedirectPatternRule"&gt;
&lt;Set name="pattern"&gt;/test/redirect/*&lt;/Set&gt;
&lt;Set name="location"&gt;/test/redirected&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;!-- add a response rule --&gt;
&lt;Call name="addRule"&gt;
&lt;Arg&gt;
&lt;New class="org.eclipse.jetty.rewrite.handler.ResponsePatternRule"&gt;
&lt;Set name="pattern"&gt;/400Error&lt;/Set&gt;
&lt;Set name="code"&gt;400&lt;/Set&gt;
&lt;Set name="message"&gt;ResponsePatternRule Demo&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Ref&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="sect4">
<h5>Embedded Example</h5>
<div class="paragraph">
<p>This is an example for embedded Jetty, which does something similar to the configuration file example above:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java"> Server server = new Server();
RewriteHandler rewrite = new RewriteHandler();
rewrite.setRewriteRequestURI(true);
rewrite.setRewritePathInfo(false);
rewrite.originalPathAttribute("requestedPath");
RedirectPatternRule redirect = new RedirectPatternRule();
redirect.setPattern("/redirect/*");
redirect.setReplacement("/redirected");
rewrite.addRule(redirect);
RewritePatternRule oldToNew = new RewritePatternRule();
oldToNew.setPattern("/some/old/context");
oldToNew.setReplacement("/some/new/context");
rewrite.addRule(oldToNew);
RewriteRegexRule reverse = new RewriteRegexRule();
reverse.setRegex("/reverse/([^/]*)/(.*)");
reverse.setReplacement("/reverse/$2/$1");
rewrite.addRule(reverse);
server.setHandler(rewrite);</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="rewrite-rules">Rules</h4>
<div class="paragraph">
<p>There are several types of rules that are written extending useful base rule classes.</p>
</div>
<div class="sect4">
<h5>PatternRule</h5>
<div class="paragraph">
<p>Matches against the request URI using the servlet pattern syntax.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/CookiePatternRule.html">CookiePatternRule</a></dt>
<dd>
<p>Adds a cookie to the response.</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/HeaderPatternRule.html">HeaderPatternRule</a></dt>
<dd>
<p>Adds/modifies a header in the response.</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/RedirectPatternRule.html">RedirectPatternRule</a></dt>
<dd>
<p>Redirects the response.</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/ResponsePatternRule.html">ResponsePatternRule</a></dt>
<dd>
<p>Sends the response code (status or error).</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/RewritePatternRule.html">RewritePatternRule</a></dt>
<dd>
<p>Rewrite the URI by replacing the matched request path with a fixed string.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>RegexRule</h5>
<div class="paragraph">
<p>Matches against the request URI using regular expressions.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/RedirectRegexRule.html">RedirectRegexRule</a></dt>
<dd>
<p>Redirect the response.</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/RewriteRegexRule.html">RewriteRegexRule</a></dt>
<dd>
<p>Rewrite the URI by matching with a regular expression.
(The replacement string may use <code>Template:$n</code> to replace the nth capture group.)</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>HeaderRule</h5>
<div class="paragraph">
<p>Match against request headers. Match either on a header name and specific value, or on the presence of a header (with any value).</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/ForwardedSchemeHeaderRule.html">ForwardedSchemaHeaderRule</a></dt>
<dd>
<p>Set the scheme on the request (defaulting to HTTPS).</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>Others</h5>
<div class="paragraph">
<p>Extra rules that defy standard classification.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/MsieSslRule.html">MsieSslRule</a></dt>
<dd>
<p>Disables the keep alive for SSL from IE5 or IE6.</p>
</dd>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/LegacyRule.html">LegacyRule</a></dt>
<dd>
<p>Implements the legacy API of RewriteHandler</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5>RuleContainer</h5>
<div class="paragraph">
<p>Groups rules together.
The contained rules will only be processed if the conditions for the <code>RuleContainer</code> evaluate to true.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/rewrite/handler/VirtualHostRuleContainer.html">VirtualHostRuleContainer</a></dt>
<dd>
<p>Groups rules that apply only to a specific virtual host or a set of virtual hosts</p>
</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="runner">Jetty Runner</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This chapter explains how to use the <code>jetty-runner</code> to run your webapps without needing an installation of Jetty.</p>
</div>
<div class="sect2">
<h3 id="jetty-runner">Use Jetty Without an Installed Distribution</h3>
<div class="paragraph">
<p>The idea of the <code>jetty-runner</code> is extremely simple – run a webapp directly from the command line using a single jar file and as much default configuration as possible.
Of course, if your webapp is not as straightforward, the <code>jetty-runner</code> has command line options which allow you to customize the execution environment.</p>
</div>
<div class="sect3">
<h4 id="jetty-runner-preparation">Preparation</h4>
<div class="paragraph">
<p>You will need the <code>jetty-runner</code> jar:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Download the <code>jetty-runner</code> jar available at <a href="https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-runner/">Maven Central</a>.</p>
</li>
</ol>
</div>
</div>
<div class="sect3">
<h4>Deploying a Simple Context</h4>
<div class="paragraph">
<p>Let&#8217;s assume we have a very simple webapp that does not need any resources from its environment, nor any configuration apart from the defaults.
Starting it is as simple as performing the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar simple.war</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will start Jetty on port 8080, and deploy the webapp to <code>/</code>.</p>
</div>
<div class="paragraph">
<p>Your webapp does not have to be packed into a war, you can deploy a webapp that is a directory instead in the same way:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar simple</code></pre>
</div>
</div>
<div class="paragraph">
<p>In fact, the webapp does not have to be a war or even a directory, it can simply be a Jetty <a href="#using-context-provider">context xml</a> file that describes your webapp:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar simple-context.xml</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
When using a context xml file, the application being deployed is not even required to be a fully-fledged webapp.
It can simply be a Jetty <a href="#what-is-a-context">context</a>.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="paragraph">
<p>By default, <code>jetty-runner</code> implements all Configuration Classes so that users can set up and deploy new instances with as little configuration as possible.
If you wish to only implement certain Configuration Classes, they will need to be defined in the context xml for the webapp/context.
The default Configuration Classes are:</p>
</div>
<div class="paragraph">
<p><code>org.eclipse.jetty.webapp.WebInfConfiguration</code>
<code>org.eclipse.jetty.webapp.WebXmlConfiguration</code>
<code>org.eclipse.jetty.webapp.MetaInfConfiguration</code>
<code>org.eclipse.jetty.webapp.FragmentConfiguration</code>
<code>org.eclipse.jetty.webapp.JettyWebXmlConfiguration</code>
<code>org.eclipse.jetty.plus.webapp.EnvConfiguration</code>
<code>org.eclipse.jetty.plus.webapp.PlusConfiguration</code>
<code>org.eclipse.jetty.annotations.AnnotationConfiguration</code></p>
</div>
<div class="paragraph">
<p>You can learn more about implementing specific Configuration Classes <a href="https://www.eclipse.org/jetty/documentation/current/configuring-webapps.html#webapp-configurations">here.</a></p>
</div>
</div>
<div class="sect3">
<h4>Deploying Multiple Contexts</h4>
<div class="paragraph">
<p>If you have more than one webapp that must be deployed, simply provide them all on the command line.
You can control the context paths for them using the <code>--path</code> parameter.
Here&#8217;s an example of deploying 2 wars (although either or both of them could be unpacked directories instead):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --path /one my1.war --path /two my2.war</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you have context xml files that describe your webapps, you can fully configure your webapps in them and hence you won&#8217;t need to use the command line switches.
Just provide the list of context files like so:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar my-first-context.xml my-second-context.xml my-third-context.xml</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Switched used on the command line override configuration file settings.
So, for example, you could set the context path for the webapp inside the context xml file, and use the <code>--path</code> switch to override it on the command line.
</td>
</tr>
</table>
</div>
</blockquote>
</div>
<div class="sect4">
<h5>Changing the Default Port</h5>
<div class="paragraph">
<p>By default the <code>jetty-runner</code> will listen on port 8080.
You can easily change this on the command line using the <code>--port</code> command.
Here&#8217;s an example that runs our simple.war on port 9090:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --port 9090 simple.war</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Using jetty.xml Files</h5>
<div class="paragraph">
<p>Instead of, or in addition to, using command line switches, you can use one or more <code>jetty.xml</code> files to configure the environment for your webapps.
Here&#8217;s an example where we apply two different <code>jetty.xml</code> files:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --config jetty.xml --config jetty-https.xml simple.war</code></pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="runner-configuration-reference">Full Configuration Reference</h4>
<div class="paragraph">
<p>You can see the fill set of configuration options using the <code>--help</code> switch:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --help</code></pre>
</div>
</div>
<div class="paragraph">
<p>Here&#8217;s what the output will look like:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-plain" data-lang="plain">Usage: java [-Djetty.home=dir] -jar jetty-runner.jar [--help|--version] [ server opts] [[ context opts] context ...]
Server opts:
--version - display version and exit
--log file - request log filename (with optional 'yyyy_mm_dd' wildcard
--out file - info/warn/debug log filename (with optional 'yyyy_mm_dd' wildcard
--host name|ip - interface to listen on (default is all interfaces)
--port n - port to listen on (default 8080)
--stop-port n - port to listen for stop command (or -DSTOP.PORT=n)
--stop-key n - security string for stop command (required if --stop-port is present) (or -DSTOP.KEY=n)
[--jar file]*n - each tuple specifies an extra jar to be added to the classloader
[--lib dir]*n - each tuple specifies an extra directory of jars to be added to the classloader
[--classes dir]*n - each tuple specifies an extra directory of classes to be added to the classloader
--stats [unsecure|realm.properties] - enable stats gathering servlet context
[--config file]*n - each tuple specifies the name of a jetty xml config file to apply (in the order defined)
Context opts:
[[--path /path] context]*n - WAR file, web app dir or context xml file, optionally with a context path</code></pre>
</div>
</div>
<div class="sect4">
<h5>Printing the Version</h5>
<div class="paragraph">
<p>Print out the version of Jetty and then exit immediately.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --version</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring a Request Log</h5>
<div class="paragraph">
<p>Cause Jetty to write a request log with the given name.
If the file is prefixed with <code>yyyy_mm_dd</code> then the file will be automatically rolled over.
Note that for finer grained configuration of the <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/NCSARequestLog.html">request log</a>, you will need to use a Jetty xml file instead.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --log yyyy_mm_dd-requests.log my.war</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring the Output Log</h5>
<div class="paragraph">
<p>Redirect the output of jetty logging to the named file.
If the file is prefixed with <code>yyyy_mm_dd</code> then the file will be automatically rolled over.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --out yyyy_mm_dd-output.log my.war</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring the Interface for HTTP</h5>
<div class="paragraph">
<p>Like Jetty standalone, the default is for the connectors to listen on all interfaces on a machine.
You can control that by specifying the name or ip address of the particular interface you wish to use with the <code>--host</code> argument:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --host 192.168.22.19 my.war</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring the Port for HTTP</h5>
<div class="paragraph">
<p>The default port number is 8080.
To <a href="#how-to-configure-connectors">configure a https connector</a>, use a Jetty xml config file instead.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --port 9090 my.war</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring Stop</h5>
<div class="paragraph">
<p>You can configure a port number for Jetty to listen on for a stop command, so you are able to stop it from a different terminal.
This requires the use of a "secret" key, to prevent malicious or accidental termination.
Use the <code>--stop-port</code> and <code>--stop-key</code> (or <code>-DSTOP.PORT=</code> and <code>-DSTOP.KEY=</code>, respectively) parameters as arguments to the <code>jetty-runner</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --stop-port 8181 --stop-key abc123</code></pre>
</div>
</div>
<div class="paragraph">
<p>Then, to stop Jetty from a different terminal, you need to supply the same port and key information.
For this you&#8217;ll either need a local installation of Jetty, the <a href="#jetty-maven-plugin">jetty-maven-plugin</a>, the <a href="#jetty-ant">jetty-ant plugin</a>, or a custom class.
Here&#8217;s how to use a Jetty installation to perform a stop:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar start.jar -DSTOP.PORT=8181 -DSTOP.KEY=abc123 --stop</code></pre>
</div>
</div>
</div>
<div class="sect4">
<h5>Configuring the Container Classpath</h5>
<div class="paragraph">
<p>With a local installation of Jetty, you add jars and classes to the container&#8217;s classpath by putting them in the <code>{$jetty.base}/lib</code> directory.
With the <code>jetty-runner</code>, you can use the <code>--lib</code>, <code>--jar</code> and <code>--classes</code> arguments instead to achieve the same thing.</p>
</div>
<div class="paragraph">
<p><code>--lib</code> adds the location of a directory which contains jars to add to the container classpath.
You can add 1 or more.
Here&#8217;s an example of configuring 2 directories:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --lib /usr/local/external/lib --lib $HOME/external-other/lib my.war</code></pre>
</div>
</div>
<div class="paragraph">
<p><code>--jar</code> adds a single jar file to the container classpath.
You can add 1 or more.
Here&#8217;s an example of configuring 3 extra jars:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --jar /opt/stuff/jars/jar1.jar --jar $HOME/jars/jar2.jar --jar /usr/local/proj/jars/jar3.jar my.war</code></pre>
</div>
</div>
<div class="paragraph">
<p><code>--classes</code> add the location of a directory containing classes to add to the container classpath.
You can add 1 or more.
Here&#8217;s an example of configuring a single extra classes dir:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --classes /opt/stuff/classes my.war</code></pre>
</div>
</div>
<div class="quoteblock">
<blockquote>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
When using the <code>--jar</code> and/or <code>--lib</code> arguments, by default these will <strong>not</strong> be inspected for <code>META-INF</code> information such as <code>META-INF/resources</code>, <code>META-INF/web-fragment.xml</code>, or <code>META-INF/taglib.tld</code>.
If you require these jar files inspected you will need to define the <a href="https://www.eclipse.org/jetty/documentation/current/configuring-webapps.html#webapp-context-attributes">jar pattern in your context xml file</a>.
Jetty-Runner automatically provides and appends a suitable pattern for jtsl taglibs (this pattern is different than the one in the standard Jetty distribution).
</td>
</tr>
</table>
</div>
</blockquote>
</div>
</div>
<div class="sect4">
<h5>Gathering Statistics</h5>
<div class="paragraph">
<p>If statistics gathering is enabled, then they are viewable by surfing to the context <code>/stats</code>.
You may optionally protect access to that context with a password.
Here&#8217;s an example of enabling statistics, with no password protection:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --stats unsecure my.war</code></pre>
</div>
</div>
<div class="paragraph">
<p>If we wished to protect access to the <code>/stats</code> context, we would provide the location of a Jetty realm configuration file containing authentication and authorization information.
For example, we could use the following example realm file from the Jetty distribution:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">jetty: MD5:164c88b302622e17050af52c89945d44,user
admin: CRYPT:adpexzg3FUZAk,server-administrator,content-administrator,admin
other: OBF:1xmk1w261u9r1w1c1xmq,user
plain: plain,user
user: password,user
# This entry is for digest auth. The credential is a MD5 hash of username:realmname:password
digest: MD5:6e120743ad67abfbc385bc2bb754e297,user</code></pre>
</div>
</div>
<div class="paragraph">
<p>Assuming we&#8217;ve copied it into the local directory, we would apply it like so</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">&gt; java -jar jetty-runner.jar --stats realm.properties my.war</code></pre>
</div>
</div>
<div class="paragraph">
<p>After navigating to <a href="http://localhost:8080/" class="bare">http://localhost:8080/</a> a few times, we can point to the stats servlet on <a href="http://localhost:8080/stats" class="bare">http://localhost:8080/stats</a> to see the output:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Statistics:
Statistics gathering started 1490627ms ago
Requests:
Total requests: 9
Active requests: 1
Max active requests: 1
Total requests time: 63
Mean request time: 7.875
Max request time: 26
Request time standard deviation: 8.349764752888037
Dispatches:
Total dispatched: 9
Active dispatched: 1
Max active dispatched: 1
Total dispatched time: 63
Mean dispatched time: 7.875
Max dispatched time: 26
Dispatched time standard deviation: 8.349764752888037
Total requests suspended: 0
Total requests expired: 0
Total requests resumed: 0
Responses:
1xx responses: 0
2xx responses: 7
3xx responses: 1
4xx responses: 0
5xx responses: 0
Bytes sent total: 1453
Connections:
org.eclipse.jetty.server.ServerConnector@203822411
Protocols:http/1.1
Statistics gathering started 1490606ms ago
Total connections: 7
Current connections open: 1
Max concurrent connections open: 2
Total connections duration: 72883
Mean connection duration: 12147.166666666666
Max connection duration: 65591
Connection duration standard deviation: 23912.40292977684
Total messages in: 7
Total messages out: 7
Memory:
Heap memory usage: 49194840 bytes
Non-heap memory usage: 12611696 bytes</pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="optimizing">Optimizing Jetty</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There are many ways to optimize Jetty which vary depending on the situation.
Are you trying to optimize for number of requests within a given amount of time?
Are you trying to optimize the serving of static content?
Do you have a large bit of hardware that you want to give entirely over to Jetty to use to its heart&#8217;s delight?
This chapter examines a few of the many different ways to optimize Jetty.</p>
</div>
<div class="sect2">
<h3 id="garbage-collection">Garbage Collection</h3>
<div class="paragraph">
<p>Tuning the JVM garbage collection (GC) can greatly improve the performance of the JVM where Jetty and your application are running.
Optimal tuning of the GC depends on the behavior of the application(s) and requires detailed analysis, but there are general recommendations to follow to at least obtain comprehensive GC logs that can be later analyzed.</p>
</div>
<div class="paragraph">
<p>See official <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/vm/gctuning/">Java 8</a> and <a href="https://docs.oracle.com/javase/9/gctuning/introduction-garbage-collection-tuning.htm">Java 9</a> Garbage Collection documentation for further assistance.</p>
</div>
<div class="sect3">
<h4 id="garbage-collection-logging-configuration">Garbage Collection Logging Configuration</h4>
<div class="paragraph">
<p>These options are general to OpenJDK (and therefore also for the Oracle JVM).
They provide good information about the GC activity of your JVM, producing logs that can later be analyzed to perform finer tuning.</p>
</div>
<div class="listingblock">
<div class="title">JDK 8 Garbage Collection Logging Configuration</div>
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">-Xloggc:/path/to/myjettybase/logs/gc.log
-XX:+PrintGCDateStamps
-XX:+PrintGCDetails
-XX:+ParallelRefProcEnabled
-XX:+PrintReferenceGC
-XX:+PrintTenuringDistribution
-XX:+PrintAdaptiveSizePolicy</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">JDK 9 Garbage Collection Logging Configuration</div>
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">Xlog:gc*,ergo*=trace,ref*=debug,age*=trace:file=/path/to/myjettybase/logs/gc.log:time,level,tags</code></pre>
</div>
</div>
<div class="paragraph">
<p>There are not many recommended options for GC that can apply to all users.
However, the most obvious one is to disable explicit GC (this is performed regularly by RMI and can introduce an abnormal amount of GC pauses).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">-XX:+DisableExplicitGC</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="high-load">High Load</h3>
<div class="paragraph">
<p>Configuring Jetty for high load, whether for load testing or for production, requires that the operating system, the JVM, Jetty, the application, the network and the load generation all be tuned.</p>
</div>
<div class="sect3">
<h4>Load Generation for Load Testing</h4>
<div class="paragraph">
<p>Machines handling load generation must have their OS, JVM, etc., tuned just as much as the server machines.</p>
</div>
<div class="paragraph">
<p>The load generation should not be over the local network on the server machine, as this has unrealistic performance and latency as well as different packet sizes and transport characteristics.</p>
</div>
<div class="paragraph">
<p>The load generator should generate a realistic load.
Avoid the following pitfalls:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>A common mistake is that load generators often open relatively few connections that are extremely busy sending as many requests as possible over each connection.
This causes the measured throughput to be limited by request latency (see <a href="http://blogs.webtide.com/gregw/entry/lies_damned_lies_and_benchmarks">Lies, Damned Lies and Benchmarks</a> for an analysis of such an issue).</p>
</li>
<li>
<p>Another common mistake is to use TCP/IP for a single request, and to open many, many short-lived connections.
This often results in accept queues filling and limitations due to file descriptor and/or port starvation.</p>
</li>
<li>
<p>A load generator should model the traffic profile from the normal clients of the server.
For browsers, this is often between two and six connections that are mostly idle and that are used in sporadic bursts with read times in between.
The connections are typically long held HTTP/1.1 connections.</p>
</li>
<li>
<p>Load generators should be written in asynchronously so that a limited number of threads does not restrict the maximum number of users that can be simulated.
If the generator is not asynchronous, a thread pool of 2000 may only be able to simulate 500 or fewer users.
The Jetty <code>HttpClient</code> is an ideal choice for building a load generator as it is asynchronous and can simulate many thousands of connections (see the CometD Load Tester for a good example of a realistic load generator).</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4>Operating System Tuning</h4>
<div class="paragraph">
<p>Both the server machine and any load generating machines need to be tuned to support many TCP/IP connections and high throughput.</p>
</div>
<div class="sect4">
<h5>Linux</h5>
<div class="paragraph">
<p>Linux does a reasonable job of self-configuring TCP/IP, but there are a few limits and defaults that you should increase.
You can configure most of these in <code>/etc/security/limits.conf</code> or via <code>sysctl</code>.</p>
</div>
<div class="sect5">
<h6>TCP Buffer Sizes</h6>
<div class="paragraph">
<p>You should increase TCP buffer sizes to at least 16MB for 10G paths and tune the auto-tuning (keep in mind that you need to consider buffer bloat).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ sysctl -w net.core.rmem_max=16777216
$ sysctl -w net.core.wmem_max=16777216
$ sysctl -w net.ipv4.tcp_rmem="4096 87380 16777216"
$ sysctl -w net.ipv4.tcp_wmem="4096 16384 16777216"</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Queue Sizes</h6>
<div class="paragraph">
<p><code>net.core.somaxconn</code> controls the size of the connection listening queue.
The default value is 128.
If you are running a high-volume server and connections are getting refused at a TCP level, you need to increase this value.
This setting can take a bit of finesse to get correct: if you set it too high, resource problems occur as it tries to notify a server of a large number of connections, and many remain pending, but if you set it too low, refused connections occur.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen"> $ sysctl -w net.core.somaxconn=4096</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>net.core.netdev_max_backlog</code> controls the size of the incoming packet queue for upper-layer (Java) processing.
The default (2048) may be increased and other related parameters adjusted with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ sysctl -w net.core.netdev_max_backlog=16384
$ sysctl -w net.ipv4.tcp_max_syn_backlog=8192
$ sysctl -w net.ipv4.tcp_syncookies=1</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Ports</h6>
<div class="paragraph">
<p>If many outgoing connections are made (for example, on load generators), the operating system might run low on ports.
Thus it is best to increase the port range, and allow reuse of sockets in <code>TIME_WAIT</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ sysctl -w net.ipv4.ip_local_port_range="1024 65535"
$ sysctl -w net.ipv4.tcp_tw_recycle=1</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>File Descriptors</h6>
<div class="paragraph">
<p>Busy servers and load generators may run out of file descriptors as the system defaults are normally low.
These can be increased for a specific user in <code>/etc/security/limits.conf</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>theusername hard nofile 40000
theusername soft nofile 40000</pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Congestion Control</h6>
<div class="paragraph">
<p>Linux supports pluggable congestion control algorithms.
To get a list of congestion control algorithms that are available in your kernel run:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ sysctl net.ipv4.tcp_available_congestion_control</code></pre>
</div>
</div>
<div class="paragraph">
<p>If cubic and/or htcp are not listed, you need to research the control algorithms for your kernel.
You can try setting the control to cubic with:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-screen" data-lang="screen">$ sysctl -w net.ipv4.tcp_congestion_control=cubic</code></pre>
</div>
</div>
</div>
<div class="sect5">
<h6>Mac OS</h6>
<div class="paragraph">
<p>Tips welcome.</p>
</div>
</div>
<div class="sect5">
<h6>Windows</h6>
<div class="paragraph">
<p>Tips welcome.</p>
</div>
</div>
<div class="sect5">
<h6>Network Tuning</h6>
<div class="paragraph">
<p>Intermediaries such as nginx can use a non-persistent HTTP/1.0 connection.
Make sure to use persistent HTTP/1.1 connections.</p>
</div>
</div>
<div class="sect5">
<h6>JVM Tuning</h6>
<div class="ulist">
<ul>
<li>
<p>Tune the <a href="#tuning-examples">Garbage Collection</a></p>
</li>
<li>
<p>Allocate sufficient memory</p>
</li>
<li>
<p>Use the -server option</p>
</li>
<li>
<p>Jetty Tuning</p>
</li>
</ul>
</div>
</div>
<div class="sect5">
<h6>Acceptors</h6>
<div class="paragraph">
<p>The standard rule of thumb for the number of Accepters to configure is one per CPU on a given machine.</p>
</div>
</div>
<div class="sect5">
<h6>Low Resource Limits</h6>
<div class="paragraph">
<p>Must not be configured for less than the number of expected connections.</p>
</div>
</div>
<div class="sect5">
<h6>Thread Pool</h6>
<div class="paragraph">
<p>Configure with goal of limiting memory usage maximum available.
Typically this is &gt;50 and &lt;500</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="limit-load">Limiting Load</h3>
<div class="paragraph">
<p>To achieve optimal fair handling for all users of a server, it can be necessary to limit the resources that each user/connection can utilize so as to maximize throughput for the server or to ensure that the entire server runs within the limitations of it&#8217;s runtime.</p>
</div>
<div class="sect3">
<h4>Low Resources Monitor</h4>
<div class="paragraph">
<p>An instance of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/server/LowResourcesMonitor.html">LowResourcesMonitor</a> may be added to a Jetty server to monitor for low resources situations and to take action to limit the number of idle connections on the server.
To configure the low resources monitor, you can enable the the <code>lowresources.mod</code> on the command line, which has the effect of including the following XML configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-xml" data-lang="xml">&lt;?xml version="1.0"?&gt;
&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "https://www.eclipse.org/jetty/configure_10_0.dtd"&gt;
&lt;!-- =============================================================== --&gt;
&lt;!-- Mixin the Low Resources Monitor --&gt;
&lt;!-- =============================================================== --&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;Call name="addBean"&gt;
&lt;Arg&gt;
&lt;New id="lowResourceMonitor" class="org.eclipse.jetty.server.LowResourceMonitor"&gt;
&lt;Arg name="server"&gt;&lt;Ref refid='Server'/&gt;&lt;/Arg&gt;
&lt;Set name="period" property="jetty.lowresources.period"/&gt;
&lt;Set name="lowResourcesIdleTimeout" property="jetty.lowresources.idleTimeout"/&gt;
&lt;Set name="monitorThreads" property="jetty.lowresources.monitorThreads"/&gt;
&lt;Set name="maxConnections" property="jetty.lowresources.maxConnections"/&gt;
&lt;Set name="maxMemory" property="jetty.lowresources.maxMemory"/&gt;
&lt;Set name="maxLowResourcesTime" property="jetty.lowresources.maxLowResourcesTime"/&gt;
&lt;Set name="acceptingInLowResources" property="jetty.lowresources.accepting"/&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;/Configure&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>The monitor is configured with a period in milliseconds at which it will scan the server looking for a low resources condition, which may be one of:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If <code>monitorThreads</code> is configured as true and a connectors Executor is an instance of <a href="http://www.eclipse.org/jetty/javadoc/10.0.0-SNAPSHOT/org/eclipse/jetty/util/thread/ThreadPool.html">ThreadPool</a>, then its <code>isLowOnThreads()</code> method is used to detect low resources.</p>
</li>
<li>
<p>If <code>maxConnections</code> is configured to a number &gt;0 then if the total number of connections from all monitored connectors exceeds this value, then low resources state is entered.</p>
</li>
<li>
<p>If the <code>maxMemory</code> field is configured to a number of bytes &gt;0 then if the JVMs total memory minus its idle memory exceeds this value, then low resources state is entered.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Once low resources state is detected, then the monitor will iterate over all existing connections and set their <code>IdleTimeout</code> to its configured <code>lowResourcesIdleTimeout</code> in milliseconds.
This allows the idle time of existing connections to be reduced so that the connection is quickly closed if no further request are received.</p>
</div>
<div class="paragraph">
<p>If the low resources state persists longer than the time in milliseconds configured for the <code>maxLowResourcesTime</code> field, the the <code>lowResourcesIdleTimeout</code> is repeatedly applied so that new connections as well as existing connections will be limited.</p>
</div>
</div>
</div>
</div>
</div></div><div id="footer"><div id="footer-text">Version 1.0<br>Last updated 2020-03-18 12:02:44 CDT</div></div></div></main><a href="#" class="scrollup">Back to the top</a></body></html>