202 lines
16 KiB
HTML
202 lines
16 KiB
HTML
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Engine Container</title><meta name="author" value="Craig R. McClanahan"><meta name="email" value="craigmcc@apache.org"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="right" alt="
|
||
|
|
The Apache Tomcat Servlet/JSP Container
|
||
|
|
" border="0"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>Apache Tomcat Configuration Reference</h1><h2>The Engine Container</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>The <strong>Engine</strong> element represents the entire request
|
||
|
|
processing machinery associated with a particular Catalina
|
||
|
|
<a href="service.html">Service</a>. It receives and processes
|
||
|
|
<em>all</em> requests from one or more <strong>Connectors</strong>,
|
||
|
|
and returns the completed response to the Connector for ultimate
|
||
|
|
transmission back to the client.</p>
|
||
|
|
|
||
|
|
<p>Exactly one <strong>Engine</strong> element MUST be nested inside
|
||
|
|
a <a href="service.html">Service</a> element, following all of the
|
||
|
|
corresponding Connector elements associated with this Service.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>All implementations of <strong>Engine</strong>
|
||
|
|
support the following attributes:</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>backgroundProcessorDelay</code></td><td align="left" valign="center">
|
||
|
|
<p>This value represents the delay in seconds between the
|
||
|
|
invocation of the backgroundProcess method on this engine and
|
||
|
|
its child containers, including all hosts and contexts.
|
||
|
|
Child containers will not be invoked if their delay value is not
|
||
|
|
negative (which would mean they are using their own processing
|
||
|
|
thread). Setting this to a positive value will cause
|
||
|
|
a thread to be spawn. After waiting the specified amount of time,
|
||
|
|
the thread will invoke the backgroundProcess method on this engine
|
||
|
|
and all its child containers. If not specified, the default value for
|
||
|
|
this attribute is 10, which represent a 10 seconds delay.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
|
||
|
|
<p>Java class name of the implementation to use. This class must
|
||
|
|
implement the <code>org.apache.catalina.Engine</code> interface.
|
||
|
|
If not specified, the standard value (defined below) will be used.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>defaultHost</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>The default host name, which identifies the
|
||
|
|
<a href="host.html">Host</a> that will process requests directed
|
||
|
|
to host names on this server, but which are not configured in
|
||
|
|
this configuration file. This name MUST match the <code>name</code>
|
||
|
|
attributes of one of the <a href="host.html">Host</a> elements
|
||
|
|
nested immediately inside.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><code>jvmRoute</code></td><td align="left" valign="center">
|
||
|
|
<p>Identifier which must be used in load balancing scenarios to enable
|
||
|
|
session affinity. The identifier, which must be unique across all
|
||
|
|
Tomcat 5 servers which participate in the cluster, will be appended to
|
||
|
|
the generated session identifier, therefore allowing the front end
|
||
|
|
proxy to always forward a particular session to the same Tomcat 5
|
||
|
|
instance.</p>
|
||
|
|
</td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
|
||
|
|
<p>Logical name of this Engine, used in log and error messages. <em>When
|
||
|
|
using muliple <a href="service.html">Service</a> elements in the same
|
||
|
|
<a href="server.html">Server</a>, each Engine MUST be assigned a unique
|
||
|
|
name.</em></p>
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>The standard implementation of <strong>Engine</strong> is
|
||
|
|
<strong>org.apache.catalina.core.StandardEngine</strong>.
|
||
|
|
It supports the following additional attributes (in addition to the
|
||
|
|
common attributes listed above):</p>
|
||
|
|
|
||
|
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr></table>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>You can nest one or more <a href="host.html">Host</a> elements inside
|
||
|
|
this <strong>Engine</strong> element, each representing a different virtual
|
||
|
|
host associated with this server. At least one <a href="host.html">Host</a>
|
||
|
|
is required, and one of the nested <a href="host.html">Hosts</a> MUST
|
||
|
|
have a name that matches the name specified for the
|
||
|
|
<code>defaultHost</code> attribute, listed above.</p>
|
||
|
|
|
||
|
|
<p>You can optional nest a <a href="defaultcontext.html">DefaultContext</a>
|
||
|
|
element inside this <strong>Engine</strong> element, to define the default
|
||
|
|
characteristics of web applications that are automatically deployed.</p>
|
||
|
|
|
||
|
|
<p>You can nest at most one instance of the following utility components
|
||
|
|
by nesting a corresponding element inside your <strong>Engine</strong>
|
||
|
|
element:</p>
|
||
|
|
<ul>
|
||
|
|
<li><a href="realm.html"><strong>Realm</strong></a> -
|
||
|
|
Configure a realm that will allow its
|
||
|
|
database of users, and their associated roles, to be shared across all
|
||
|
|
<a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>
|
||
|
|
nested inside this Engine, unless overridden by a
|
||
|
|
<a href="realm.html">Realm</a> configuration at a lower level.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Special Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>An engine is associated with the
|
||
|
|
<code>org.apache.catalina.core.ContainerBase.[enginename]</code>
|
||
|
|
log category. Note that the brackets are actually part of the name,
|
||
|
|
don't omit them.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>When you run a web server, one of the output files normally generated
|
||
|
|
is an <em>access log</em>, which generates one line of information for
|
||
|
|
each request processed by the server, in a standard format. Catalina
|
||
|
|
includes an optional <a href="valve.html">Valve</a> implementation that
|
||
|
|
can create access logs in the same standard format created by web servers,
|
||
|
|
or in any number of custom formats.</p>
|
||
|
|
|
||
|
|
<p>You can ask Catalina to create an access log for all requests
|
||
|
|
processed by an <a href="engine.html">Engine</a>,
|
||
|
|
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
|
||
|
|
by nesting a <a href="valve.html">Valve</a> element like this:</p>
|
||
|
|
|
||
|
|
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Engine name="Standalone" ...>
|
||
|
|
...
|
||
|
|
<Valve className="org.apache.catalina.valves.AccessLogValve"
|
||
|
|
prefix="catalina_access_log." suffix=".txt"
|
||
|
|
pattern="common"/>
|
||
|
|
...
|
||
|
|
</Engine>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
|
||
|
|
for more information on the configuration attributes that are
|
||
|
|
supported.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Lifecycle Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>If you have implemented a Java object that needs to know when this
|
||
|
|
<strong>Engine</strong> is started or stopped, you can declare it by
|
||
|
|
nesting a <strong>Listener</strong> element inside this element. The
|
||
|
|
class name you specify must implement the
|
||
|
|
<code>org.apache.catalina.LifecycleListener</code> interface, and
|
||
|
|
it will be notified about the occurrence of the coresponding
|
||
|
|
lifecycle events. Configuration of such a listener looks like this:</p>
|
||
|
|
|
||
|
|
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Engine name="Standalone" ...>
|
||
|
|
...
|
||
|
|
<Listener className="com.mycompany.mypackage.MyListener" ... >
|
||
|
|
...
|
||
|
|
</Engine>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>Note that a Listener can have any number of additional properties
|
||
|
|
that may be configured from this element. Attribute names are matched
|
||
|
|
to corresponding JavaBean property names using the standard property
|
||
|
|
method naming patterns.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
|
||
|
|
<p>You can ask Catalina to check the IP address, or host name, on every
|
||
|
|
incoming request directed to the surrounding
|
||
|
|
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
|
||
|
|
<a href="context.html">Context</a> element. The remote address or name
|
||
|
|
will be checked against a configured list of "accept" and/or "deny"
|
||
|
|
filters, which are defined using the Regular Expression syntax supported
|
||
|
|
by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a>
|
||
|
|
regular expression library. Requests that come from locations that are
|
||
|
|
not accepted will be rejected with an HTTP "Forbidden" error.
|
||
|
|
Example filter declarations:</p>
|
||
|
|
|
||
|
|
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
|
<Engine name="Standalone" ...>
|
||
|
|
...
|
||
|
|
<Valve className="org.apache.catalina.valves.RemoteHostValve"
|
||
|
|
allow="*.mycompany.com,www.yourcompany.com"/>
|
||
|
|
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
|
||
|
|
deny="192.168.1.*"/>
|
||
|
|
...
|
||
|
|
</Engine>
|
||
|
|
</pre></td><td bgcolor="#023264" width="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
|
|
||
|
|
<p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
|
||
|
|
and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
|
||
|
|
more information about the configuration options that are supported.</p>
|
||
|
|
|
||
|
|
</blockquote></td></tr></table>
|
||
|
|
|
||
|
|
|
||
|
|
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
|
||
|
|
Copyright © 1999-2006, Apache Software Foundation
|
||
|
|
</em></font></div></td></tr></table></body></html>
|