Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 67d615191938bb60e9b73af6701f5339749950ca / . / tomcat-cas / webapps / docs / config / engine.html
blob: 075d68eeaab9a08544336a7418c76baf8921f09b [file] [log] [blame]
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference (6.0.41) - The Engine Container</title><meta name="author" content="Craig R. McClanahan"><style type="text/css" media="print">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4 </style></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="
5 The Apache Tomcat Servlet/JSP Container
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]6 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 6.0</font></h1><font face="arial,helvetica,sanserif">Version 6.0.41, May 19 2014</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><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="nowrap" class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>web.xml</strong></p><ul><li><a href="filter.html">Filter</a></li></ul><p><strong>Other</strong></p><ul><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Tomcat Configuration Reference</h1><h2>The Engine Container</h2><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]7<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Standard_Implementation">Standard Implementation</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Logging">Logging</a></li><li><a href="#Access_Logs">Access Logs</a></li><li><a href="#Lifecycle_Listeners">Lifecycle Listeners</a></li><li><a href="#Request_Filters">Request Filters</a></li></ol></li></ul>
8</blockquote></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>
9
10 <p>The <strong>Engine</strong> element represents the entire request
11 processing machinery associated with a particular Catalina
12 <a href="service.html">Service</a>. It receives and processes
13 <em>all</em> requests from one or more <strong>Connectors</strong>,
14 and returns the completed response to the Connector for ultimate
15 transmission back to the client.</p>
16
17 <p>Exactly one <strong>Engine</strong> element MUST be nested inside
18 a <a href="service.html">Service</a> element, following all of the
19 corresponding Connector elements associated with this Service.</p>
20
21</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>
22
23 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>
24
25 <p>All implementations of <strong>Engine</strong>
26 support the following attributes:</p>
27
28 <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">
29 <p>This value represents the delay in seconds between the
30 invocation of the backgroundProcess method on this engine and
31 its child containers, including all hosts and contexts.
32 Child containers will not be invoked if their delay value is not
33 negative (which would mean they are using their own processing
34 thread). Setting this to a positive value will cause
35 a thread to be spawn. After waiting the specified amount of time,
36 the thread will invoke the backgroundProcess method on this engine
37 and all its child containers. If not specified, the default value for
38 this attribute is 10, which represent a 10 seconds delay.</p>
39 </td></tr><tr><td align="left" valign="center"><code>className</code></td><td align="left" valign="center">
40 <p>Java class name of the implementation to use. This class must
41 implement the <code>org.apache.catalina.Engine</code> interface.
42 If not specified, the standard value (defined below) will be used.</p>
43 </td></tr><tr><td align="left" valign="center"><strong><code>defaultHost</code></strong></td><td align="left" valign="center">
44 <p>The default host name, which identifies the
45 <a href="host.html">Host</a> that will process requests directed
46 to host names on this server, but which are not configured in
47 this configuration file. This name MUST match the <code>name</code>
48 attributes of one of the <a href="host.html">Host</a> elements
49 nested immediately inside.</p>
50 </td></tr><tr><td align="left" valign="center"><code>jvmRoute</code></td><td align="left" valign="center">
51 <p>Identifier which must be used in load balancing scenarios to enable
52 session affinity. The identifier, which must be unique across all
53 Tomcat 6 servers which participate in the cluster, will be appended to
54 the generated session identifier, therefore allowing the front end
55 proxy to always forward a particular session to the same Tomcat 6
56 instance.</p>
57 </td></tr><tr><td align="left" valign="center"><strong><code>name</code></strong></td><td align="left" valign="center">
58 <p>Logical name of this Engine, used in log and error messages. <em>When
59 using multiple <a href="service.html">Service</a> elements in the same
60 <a href="server.html">Server</a>, each Engine MUST be assigned a unique
61 name.</em></p>
62 </td></tr></table>
63
64 </blockquote></td></tr></table>
65
66
67 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementation"><!--()--></a><a name="Standard_Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote>
68
69 <p>The standard implementation of <strong>Engine</strong> is
70 <strong>org.apache.catalina.core.StandardEngine</strong>.
71 It supports the following additional attributes (in addition to the
72 common attributes listed above):</p>
73
74 <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>
75
76 </blockquote></td></tr></table>
77
78
79</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"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>
80
81 <p>You can nest one or more <a href="host.html">Host</a> elements inside
82 this <strong>Engine</strong> element, each representing a different virtual
83 host associated with this server. At least one <a href="host.html">Host</a>
84 is required, and one of the nested <a href="host.html">Hosts</a> MUST
85 have a name that matches the name specified for the
86 <code>defaultHost</code> attribute, listed above.</p>
87
88 <p>You can nest at most one instance of the following utility components
89 by nesting a corresponding element inside your <strong>Engine</strong>
90 element:</p>
91 <ul>
92 <li><a href="realm.html"><strong>Realm</strong></a> -
93 Configure a realm that will allow its
94 database of users, and their associated roles, to be shared across all
95 <a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>
96 nested inside this Engine, unless overridden by a
97 <a href="realm.html">Realm</a> configuration at a lower level.</li>
98 </ul>
99
100</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"><!--()--></a><a name="Special_Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote>
101
102
103 <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>
104
105 <p>An engine is associated with the
106 <code>org.apache.catalina.core.ContainerBase.[enginename]</code>
107 log category. Note that the brackets are actually part of the name,
108 don't omit them.</p>
109
110 </blockquote></td></tr></table>
111
112
113 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Access Logs"><!--()--></a><a name="Access_Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote>
114
115 <p>When you run a web server, one of the output files normally generated
116 is an <em>access log</em>, which generates one line of information for
117 each request processed by the server, in a standard format. Catalina
118 includes an optional <a href="valve.html">Valve</a> implementation that
119 can create access logs in the same standard format created by web servers,
120 or in any number of custom formats.</p>
121
122 <p>You can ask Catalina to create an access log for all requests
123 processed by an <a href="engine.html">Engine</a>,
124 <a href="host.html">Host</a>, or <a href="context.html">Context</a>
125 by nesting a <a href="valve.html">Valve</a> element like this:</p>
126
127<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
128&lt;Engine name="Standalone" ...&gt;
129 ...
130 &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
131 prefix="catalina_access_log." suffix=".txt"
132 pattern="common"/&gt;
133 ...
134&lt;/Engine&gt;
135</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" 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" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
136
137 <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a>
138 for more information on the configuration attributes that are
139 supported.</p>
140
141 </blockquote></td></tr></table>
142
143
144 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Lifecycle Listeners"><!--()--></a><a name="Lifecycle_Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote>
145
146 <p>If you have implemented a Java object that needs to know when this
147 <strong>Engine</strong> is started or stopped, you can declare it by
148 nesting a <strong>Listener</strong> element inside this element. The
149 class name you specify must implement the
150 <code>org.apache.catalina.LifecycleListener</code> interface, and
151 it will be notified about the occurrence of the corresponding
152 lifecycle events. Configuration of such a listener looks like this:</p>
153
154<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
155&lt;Engine name="Standalone" ...&gt;
156 ...
157 &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
158 ...
159&lt;/Engine&gt;
160</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" 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" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
161
162 <p>Note that a Listener can have any number of additional properties
163 that may be configured from this element. Attribute names are matched
164 to corresponding JavaBean property names using the standard property
165 method naming patterns.</p>
166
167 </blockquote></td></tr></table>
168
169
170 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Filters"><!--()--></a><a name="Request_Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote>
171
172 <p>You can ask Catalina to check the IP address, or host name, on every
173 incoming request directed to the surrounding
174 <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
175 <a href="context.html">Context</a> element. The remote address or name
176 will be checked against a configured list of "accept" and/or "deny"
177 filters, which are defined using <code>java.util.regex</code> Regular
178 Expression syntax. Requests that come from locations that are
179 not accepted will be rejected with an HTTP "Forbidden" error.
180 Example filter declarations:</p>
181
182<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
183&lt;Engine name="Standalone" ...&gt;
184 ...
185 &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
186 allow=".*\.mycompany\.com|www\.yourcompany\.com"/&gt;
187 &lt;Valve className="org.apache.catalina.valves.RemoteAddrValve"
188 deny="192\.168\.1\.\d+"/&gt;
189 ...
190&lt;/Engine&gt;
191</pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" 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" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
192
193 <p>See <a href="valve.html#Remote Address Filter">Remote Address Filter</a>
194 and <a href="valve.html#Remote Host Filter">Remote Host Filter</a> for
195 more information about the configuration options that are supported.</p>
196
197 </blockquote></td></tr></table>
198
199
200</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>
201 Copyright &copy; 1999-2014, Apache Software Foundation
202 </em></font></div></td></tr></table></body></html>