Google Git
Sign in
eclipse / www.eclipse.org / jetty / f492109d55aa783e4fb41d75d771a794a5a87b42 / . / documentation / 9.4.x / quickstart-config-what.html
blob: fa4828ba7e3bf02d01f192a71ffd1cc227d2a39c [file] [log] [blame]
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>What to Configure in Jetty</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty"><link rel="up" href="quick-start-configure.html" title="Chapter&nbsp;3.&nbsp;An Introduction to Jetty Configuration"><link rel="prev" href="quick-start-configure.html" title="Chapter&nbsp;3.&nbsp;An Introduction to Jetty Configuration"><link rel="next" href="jetty-config-guide.html" title="Part&nbsp;II.&nbsp;Jetty Configuration Guide"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><link rel="stylesheet" href="css/highlighter/foundation.css"><script src="js/highlight.pack.js"></script><script>
hljs.initHighlightingOnLoad();
</script><link type="text/css" rel="stylesheet" href="css/font-awesome/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small">
Version: 9.4.28-SNAPSHOT</span></td><td style="width: 50%"></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">What to Configure in Jetty</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="quick-start-configure.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><th width="60%" align="center">Chapter&nbsp;3.&nbsp;An Introduction to Jetty Configuration<br><a accesskey="p" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></th><td width="20%" align="right">&nbsp;<a accesskey="n" href="jetty-config-guide.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at
<span class="website">www.webtide.com</span></a></h5><p>
private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ...
scalability guidance for your apps and Ajax/Comet projects ... development services for sponsored feature development
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="quickstart-config-what"></a>What to Configure in Jetty</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="quickstart-config-what.html#intro-jetty-configuration-server">Configuring the Server</a></span></dt><dt><span class="section"><a href="quickstart-config-what.html#intro-jetty-configuration-connectors">Configuring Connectors</a></span></dt><dt><span class="section"><a href="quickstart-config-what.html#intro-jetty-configuration-contexts">Configuring Contexts</a></span></dt></dl></div><p>This section gives an overview of the components of Jetty you typically configure using the mechanisms outlined in the previous section.
<a class="xref" href="architecture.html#basic-architecture" title="Jetty Architecture">Jetty Architecture</a> describes the structure of a Jetty server, which is good background reading to understand configuration, and is vital if you want to change the structure of the server as set up by the default configurations in the Jetty distribution.
However, for most purposes, configuration is a matter of identifying the correct configuration file and modifying existing configuration values.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="intro-jetty-configuration-server"></a>Configuring the Server</h3></div></div></div><p>The Server instance is the central coordination object of a Jetty server; it provides services and life cycle management for all other Jetty server components.
In the standard Jetty distribution, the core server configuration is in <code class="literal">etc/jetty.xml</code> file, but you can mix in other server configurations which can include:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">ThreadPool</span></dt><dd>The Server instance provides a ThreadPool instance that is the default Executor service other Jetty server components use.
The prime configuration of the thread pool is the maximum and minimum size and is set in <code class="literal">start.ini</code> or <code class="literal">start.d/server.ini</code>.</dd><dt><span class="term">Handlers</span></dt><dd>A Jetty server can have only a single Handler instance to handle incoming HTTP requests.
However a handler may be a container or wrapper of other handlers forming a tree of handlers that typically
handle a request as a collaboration between the handlers from a branch of the tree from root to leaf.
The default handler tree set up in the <code class="literal">etc/jetty.xml</code> file is a Handler Collection containing a Context Handler Collection and the Default Handler.
The Context Handler Collection selects the next handler by context path and is where deployed Context Handler and Web Application Contexts are added to the handler tree.
The Default Handler handles any requests not already handled and generates the standard 404 page.
Other configuration files may add handlers to this tree (for example, <code class="literal">jetty-rewrite.xml</code>, <code class="literal">jetty-requestlog.xml</code>) or configure components to hot deploy handlers (for example, <code class="literal">jetty-deploy.xml</code>).</dd><dt><span class="term">Server Attributes</span></dt><dd>The server holds a generic attribute map of strings to objects so that other Jetty components can associate named objects with the server, and if the value objects implement the LifeCycle interface, they are started and stopped with the server.
Typically server attributes hold server-wide default values.</dd><dt><span class="term">Server fields</span></dt><dd>The server also has some specific configuration fields that you set in <code class="literal">start.ini</code> or <code class="literal">start.d/server.ini</code> for controlling, among other things, the sending of dates and versions in HTTP responses.</dd><dt><span class="term">Connectors</span></dt><dd>The server holds a collection of connectors that receive connections for HTTP and the other protocols that Jetty supports.
The next section, <a class="xref" href="quickstart-config-what.html#intro-jetty-configuration-connectors" title="Configuring Connectors">Configuring Connectors</a> describes configuration of the connectors themselves.
For the server you can either set the collection of all connectors or add/remove individual connectors.</dd><dt><span class="term">Services</span></dt><dd>The server can hold additional service objects, sometimes as attributes, but often as aggregated LifeCycle beans.
Examples of services are Login Services and DataSources, which you configure at the server level and then inject into the web applications that use them.</dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="intro-jetty-configuration-connectors"></a>Configuring Connectors</h3></div></div></div><p>A Jetty Server Connector is a network end point that accepts connections for one or more protocols which produce requests and/or messages for the Jetty server.
In the standard Jetty server distribution, several provided configuration files add connectors to the server for various protocols and combinations of protocols: <code class="literal">http.ini</code>, <code class="literal">https.ini</code> and <code class="literal">jetty-http2.xml</code>.
The configuration needed for connectors is typically:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Port</span></dt><dd>The TCP/IP port on which the connector listens for connections is set using the the XML Property element which looks up the <code class="literal">jetty.http.port</code> (or <code class="literal">jetty.ssl.port</code>) property, and if not found defaults to 8080 (or 8443 for TLS).</dd><dt><span class="term">Host</span></dt><dd>You can configure a host either as a host name or IP address to identify a specific network interface on which to listen.
If not set, or set to the value of 0.0.0.0, the connector listens on all local interfaces.
The XML Property element is used to look up the host value from the <code class="literal">jetty.host</code> property.</dd><dt><span class="term">Idle Timeout</span></dt><dd>The time in milliseconds that a connection can be idle before the connector takes action to close the connection.</dd><dt><span class="term">HTTP Configuration</span></dt><dd>Connector types that accept HTTP semantics (including HTTP, HTTPS and HTTP2) are configured with a <code class="literal">HttpConfiguration</code> instance that contains common HTTP configuration that is independent of the specific wire protocol used.
Because these values are often common to multiple connector types, the standard Jetty Server distribution creates a single <code class="literal">HttpConfiguration</code> in the <code class="literal">jetty.xml</code> file which is used via the XML Ref element in the specific connector files.</dd><dt><span class="term">SSL Context Factory</span></dt><dd>The TLS connector types (HTTPS and HTTP2) configure an SSL Context Factory with the location of the server keystore and truststore for obtaining server certificates.</dd></dl></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>Virtual hosts are not configured on connectors. You must configure individual contexts with the virtual hosts to which they respond.</p></div></blockquote></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>Prior to Jetty 9, the type of the connector reflected both the protocol supported (HTTP, HTTPS, AJP, SPDY), and the nature of the implementation (NIO or BIO).
From Jetty 9 onwards there is only one prime Connector type (<code class="literal">ServerConnector</code>), which is NIO based and uses Connection Factories to handle one or more protocols.</p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="intro-jetty-configuration-contexts"></a>Configuring Contexts</h3></div></div></div><p>A Jetty context is a handler that groups other handlers under a context path together with associated resources and is roughly equivalent to the standard ServletContext API.
A context may contain either standard Jetty handlers or a custom application handler.</p><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>The servlet specification defines a web application.
In Jetty a standard web application is a specialized context that uses a standard layout and <code class="literal">WEB-INF/web.xml</code> to instantiate and configure classpath, resource base and handlers for sessions, security, and servlets, plus servlets for JSPs and static content.
Standard web applications often need little or no additional configuration, but you can also use the techniques for arbitrary contexts to refine or modify the configuration of standard web applications.</p></div></blockquote></div><p>Configuration values that are common to all contexts are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">contextPath</span></dt><dd><p class="simpara">The contextPath is a URL prefix that identifies which context a HTTP request is destined for.
For example, if a context has a context path <code class="literal">/foo</code>, it handles requests to <code class="literal">/foo</code>, <code class="literal">/foo/index.html</code>,
<code class="literal">/foo/bar/</code>, and <code class="literal">/foo/bar/image.png</code> but it does not handle requests like <code class="literal">/</code>, <code class="literal">/other/</code>, or <code class="literal">/favicon.ico</code>.
A context with a context path of / is called the root context.</p><p class="simpara">The context path can be set by default from the deployer (which uses the filename as the basis for the context path); or in code; or it can be set by a Jetty IoC XML that is either applied by the deployer or found in the <code class="literal">WEB-INF/jetty-web.xml</code> file of a standard web app context.</p></dd><dt><span class="term">virtualHost</span></dt><dd>A context may optionally have one or more virtual hosts set.
Unlike the host set on a connector (which selects the network interface on which to listen), a virtual host does not set any network parameters.
Instead a virtual host represents an alias assigned by a name service to an IP address, which may have many aliases.
To determine which virtual host a request is intended for, the HTTP client (browser) includes in the request the name used to look up the network address.
A context with a virtual host set only handles requests that have a matching virtual host in their request headers.</dd><dt><span class="term">classPath</span></dt><dd>A context may optionally have a classpath, so that any thread that executes a handler within the context has a thread context classloader set with the classpath.
A standard web application has the classpath initialized by the <code class="literal">WEB-INF/lib</code> and <code class="literal">WEB-INF/classes</code> directory and
has additional rules about delegating classloading to the parent classloader.
All contexts may have additional classpath entries added.</dd><dt><span class="term">attributes</span></dt><dd>Attributes are arbitrary named objects that are associated with a context and are frequently used to pass entities between a web application and its container.
For example the attribute <code class="literal">javax.servlet.context.tempdir</code> is used to pass the File instance that represents the assigned temporary directory for a web application.</dd><dt><span class="term">resourceBase</span></dt><dd>The resource base is a directory (or collection of directories or URL) that contains the static resources for the context.
These can be images and HTML files ready to serve or JSP source files ready to be compiled.
In traditional web servers this value is often called the docroot.</dd></dl></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_context_configuration_by_api"></a>Context Configuration by API</h4></div></div></div><p>In an embedded server, you configure contexts by directly calling the <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html" target="_top">ContextHandler</a> API as in the following example:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>//
// ========================================================================
// Copyright (c) 1995-2020 Mort Bay Consulting Pty Ltd and others.
// ------------------------------------------------------------------------
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v1.0
// and Apache License v2.0 which accompanies this distribution.
//
// The Eclipse Public License is available at
// http://www.eclipse.org/legal/epl-v10.html
//
// The Apache License v2.0 is available at
// http://www.opensource.org/licenses/apache2.0.php
//
// You may elect to redistribute this code under either of these licenses.
// ========================================================================
//
package org.eclipse.jetty.embedded;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.handler.ContextHandler;
public class OneContext
{
public static Server createServer(int port)
{
Server server = new Server(port);
// Add a single handler on context "/hello"
ContextHandler context = new ContextHandler();
context.setContextPath("/hello");
context.setHandler(new HelloHandler());
// Can be accessed using http://localhost:8080/hello
server.setHandler(context);
return server;
}
public static void main(String[] args) throws Exception
{
int port = ExampleUtil.getPort(args, "jetty.http.port", 8080);
Server server = createServer(port);
// Start the server
server.start();
server.join();
}
}</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_context_configuration_by_ioc_xml"></a>Context Configuration by IoC XML</h4></div></div></div><p>You can create and configure a context entirely by IoC XML (either Jetty&#8217;s or Spring).
The deployer discovers and hot deploys context IoC descriptors like the following which creates a context to serve the Javadoc from the Jetty distribution:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC
"-//Mort Bay Consulting//DTD Configure//EN"
"http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;!--
Configure a custom context for serving javadoc as static resources
--&gt;
&lt;Configure class="org.eclipse.jetty.server.handler.ContextHandler"&gt;
&lt;Set name="contextPath"&gt;/javadoc&lt;/Set&gt;
&lt;Set name="resourceBase"&gt;&lt;SystemProperty name="jetty.home" default="."/&gt;/javadoc/&lt;/Set&gt;
&lt;Set name="handler"&gt;
&lt;New class="org.eclipse.jetty.server.handler.ResourceHandler"&gt;
&lt;Set name="welcomeFiles"&gt;
&lt;Array type="String"&gt;
&lt;Item&gt;index.html&lt;/Item&gt;
&lt;/Array&gt;
&lt;/Set&gt;
&lt;Set name="cacheControl"&gt;max-age=3600,public&lt;/Set&gt;
&lt;/New&gt;
&lt;/Set&gt;
&lt;/Configure&gt;</code></pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="intro-jetty-configuration-webapps"></a>Configuring Web Applications</h4></div></div></div><p>The servlet specification defines a web application, which when packaged as a zip is called WAR file (Web application ARchive).
Jetty implements both WAR files and unpacked web applications as a specialized context that is configured by means of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">A standard layout which sets the location of the resourceBase (the root of the WAR) and initializes the classpath from jars found in <code class="literal">WEB-INF/lib</code> and classes found in <code class="literal">WEB-INF/classes</code>.</li><li class="listitem">The standard <code class="literal">WEB-INF/web.xml</code> deployment descriptor which is parsed to define and configure init parameters, filters, servlets, listeners, security constraints, welcome files and resources to be injected.</li><li class="listitem">A default <code class="literal">web.xml</code> format deployment descriptor provided either by Jetty or in configuration configures the JSP servlet and the default servlet for handling static content.
The standard <code class="literal">web.xml</code> may override the default <code class="literal">web.xml</code>.</li><li class="listitem">Annotations discovered on classes in Jars contained in <code class="literal">WEB-INF/lib</code> can declare additional filters, servlets and listeners.</li><li class="listitem">Standard deployment descriptor fragments discovered in Jars contained in <code class="literal">WEB-INF/lib</code> can declare additional init parameters, filters, servlets, listeners, security constraints, welcome files and resources to be injected.</li><li class="listitem">An optional <code class="literal">WEB-INF/jetty-web.xml</code> file may contain Jetty IoC configuration to configure the Jetty specific APIs of the context and handlers.</li></ul></div><p>Because these configuration mechanisms are contained within the WAR file (or unpacked web application), typically a web application contains much of its own configuration and deploying a WAR is often just a matter of dropping the WAR file in to the webapps directory that is scanned by the <a class="link" href="quickstart-config-what.html#quickstart-config-deployer" title="Web Application Deployment">Jetty deployer</a>.</p><p>If you need to configure something within a web application, often you do so by unpacking the WAR file and editing the <code class="literal">web.xml</code> and other configuration files.
However, both the servlet standard and some Jetty features allow for other configuration to be applied to a web application externally from the WAR:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Configured data sources and security realms in the server can be injected into a web application either explicitly or by name matching.</li><li class="listitem">Jetty allows one or more override deployment descriptors, in <code class="literal">web.xml</code> format, to be set on a context (via code or IoC XML) to amend the configuration set by the default and standard <code class="literal">web.xml</code>.</li><li class="listitem">The normal Jetty Java API may be called by code or IoC XML to amend the configuration of a web application.</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_setting_the_context_path"></a>Setting the Context Path</h4></div></div></div><p>The web application standard provides no configuration mechanism for a web application or WAR file to set its own <code class="literal">contextPath</code>.
By default the deployer uses conventions to set the context path:
If you deploy a WAR file called <code class="literal">foobar.WAR</code>, the context path is <code class="literal">/foobar</code>; if you deploy a WAR file called <code class="literal">ROOT.WAR</code> the context path is <code class="literal">/</code>.</p><p>However, it is often desirable to explicitly set the context path so that information (for example, version numbers) may be included in the filename of the WAR.
Jetty allows the context Path of a WAR file to be set internally (by the WAR itself) or externally (by the deployer of the WAR).</p><p>To set the contextPath from within the WAR file, you can include a <code class="literal">WEB-INF/jetty-web.xml</code> file which contains IoC XML to set the context path:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC
"-//Mort Bay Consulting//DTD Configure//EN"
"http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure class="org.eclipse.jetty.webapp.WebAppContext"&gt;
&lt;Set name="contextPath"&gt;/contextpath&lt;/Set&gt;
&lt;/Configure&gt;</code></pre><p>Alternately, you can configure the classpath externally without the need to modify the WAR file itself.
Instead of allowing the WAR file to be discovered by the deployer, an IoC XML file may be deployed that both sets the context path and declares the WAR file that it applies to:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE Configure PUBLIC
"-//Mort Bay Consulting//DTD Configure//EN"
"http://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.home" default="."/&gt;/webapps/test.war&lt;/Set&gt;
&lt;Set name="contextPath"&gt;/test&lt;/Set&gt;
&lt;/Configure&gt;</code></pre><p>An example of setting the context path is included with the Jetty distribution in <code class="literal">$JETTY_HOME/webapps/test.xml</code>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="quickstart-config-deployer"></a>Web Application Deployment</h4></div></div></div><p>Jetty is capable of deploying a variety of Web Application formats.
This is accomplished via scans of the <code class="literal">${jetty.base}/webapps</code> directory for contexts to deploy.</p><p>A Context can be any of the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">A standard WAR file. (must in "<code class="literal">.war</code>").</li><li class="listitem">A directory containing an expanded WAR file. (must contain <code class="literal">{dir}/WEB-INF/web.xml</code> file).</li><li class="listitem">A directory containing static content.</li><li class="listitem">A XML descriptor in <a class="xref" href="reference-section.html#jetty-xml-syntax" title="Jetty XML Syntax">Jetty XML Syntax</a> that configures a <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/server/handler/ContextHandler.html" target="_top">ContextHandler</a> instance (Such as a
<a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/webapp/WebAppContext.html" target="_top">WebAppContext</a>).</li></ul></div><p>The new WebAppProvider will attempt to avoid double deployments during the directory scan with the following heuristics:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Hidden files (starting with <code class="literal">"."</code>) are ignored</li><li class="listitem">Directories with names ending in <code class="literal">".d"</code> are ignored</li><li class="listitem">If a directory and matching WAR file exist with the same base name (eg: <code class="literal">foo/</code> and <code class="literal">foo.war</code>), then the directory is assumed to be the unpacked WAR and only the WAR is deployed (which may reuse the unpacked directory)</li><li class="listitem">If a directory and matching XML file exists (eg: <code class="literal">foo/</code> and <code class="literal">foo.xml</code>), then the directory is assumed to be an unpacked WAR and only the XML is deployed (which may use the directory in its own configuration)</li><li class="listitem">If a WAR file and matching XML file exist (eg: <code class="literal">foo.war</code> and <code class="literal">foo.xml</code>), then the WAR is assumed to be configured by the XML and only the XML is deployed.</li></ul></div><div class="blockquote"><blockquote class="blockquote"><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="fa fa-asterisk" aria-hidden="true"></i> Note</h3><p>In prior versions of Jetty there was a separate ContextDeployer that provided XML-based deployment. As of Jetty 9 the ContextDeployer no longer exists and its functionality has been merged with the new <a class="link" href="http://www.eclipse.org/jetty/javadoc/9.4.28-SNAPSHOT/org/eclipse/jetty/deploy/providers/WebAppProvider.html" target="_top">WebAppProvider</a> to avoid double deployment scenarios.</p></div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="_setting_an_authentication_realm"></a>Setting an Authentication Realm</h4></div></div></div><p>The authentication method and realm name for a standard web application may be set in the <code class="literal">web.xml</code> deployment descriptor with elements like:</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>...
&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><p>This example declares that the BASIC authentication mechanism will be used with credentials validated against a realm called "Test Realm."
However the standard does not describe how the realm itself is implemented or configured.
In Jetty, there are several realm implementations (called LoginServices) and the simplest of these is the HashLoginService, which can read usernames and credentials from a Java properties file.</p><p>To configure an instance of HashLoginService that matches the "Test Realm" configured above, the following <code class="literal">$JETTY_BASE/etc/test-realm.xml</code> IoC XML file should be passed on the command line or set in <code class="literal">start.ini</code> or <code class="literal">start.d/server.ini</code>.</p><pre xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><code>&lt;?xml version="1.0"?&gt;&lt;!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd"&gt;
&lt;Configure id="Server" class="org.eclipse.jetty.server.Server"&gt;
&lt;!-- =========================================================== --&gt;
&lt;!-- Configure Authentication Login Service --&gt;
&lt;!-- Realms may be configured for the entire server here, or --&gt;
&lt;!-- they can be configured for a specific web app in a context --&gt;
&lt;!-- configuration (see $(jetty.home)/webapps/test.xml for an --&gt;
&lt;!-- example). --&gt;
&lt;!-- =========================================================== --&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;Property name="jetty.demo.realm" default="etc/realm.properties"/&gt;&lt;/Set&gt;
&lt;Set name="hotReload"&gt;false&lt;/Set&gt;
&lt;/New&gt;
&lt;/Arg&gt;
&lt;/Call&gt;
&lt;Get class="org.eclipse.jetty.util.log.Log" name="rootLogger"&gt;
&lt;Call name="warn"&gt;&lt;Arg&gt;demo test-realm is deployed. DO NOT USE IN PRODUCTION!&lt;/Arg&gt;&lt;/Call&gt;
&lt;/Get&gt;
&lt;/Configure&gt;</code></pre><p>This creates and configures the LoginService as an aggregate bean on the server.
When a web application is deployed that declares a realm called "Test Realm," the server beans are searched for a matching Login Service.</p></div></div></div><script type="text/javascript">
SyntaxHighlighter.all()
</script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="quick-start-configure.html"><i class="fa fa-chevron-left" aria-hidden="true"></i> Previous</a>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="quick-start-configure.html"><i class="fa fa-chevron-up" aria-hidden="true"></i> Top</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="jetty-config-guide.html">Next <i class="fa fa-chevron-right" aria-hidden="true"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter&nbsp;3.&nbsp;An Introduction to Jetty Configuration&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="fa fa-home" aria-hidden="true"></i> Home</a></td><td width="40%" align="right" valign="top">&nbsp;Part&nbsp;II.&nbsp;Jetty Configuration Guide</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout">
See an error or something missing?
<span class="callout"><a href="http://github.com/eclipse/jetty.project">Contribute to this documentation at
<span class="website"><i class="fa fa-github" aria-hidden="true"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2020-03-10)</i></span></div></p></body></html>