| 1 | <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat Configuration Reference - The Engine Container</title><meta value="Craig R. McClanahan" name="author"><meta value="craigmcc@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt=" |
|---|
| 2 | The Apache Tomcat Servlet/JSP Container |
|---|
| 3 | " align="right" src="../../images/tomcat.gif"></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 border="0" alt="Apache Logo" align="right" src="../../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat Configuration Reference</h1><h2>The Engine Container</h2></td><td nowrap="true" valign="top" align="right"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 4 | |
|---|
| 5 | <p>The <strong>Engine</strong> element represents the entire request |
|---|
| 6 | processing machinery associated with a particular Catalina |
|---|
| 7 | <a href="service.html">Service</a>. It receives and processes |
|---|
| 8 | <em>all</em> requests from one or more <strong>Connectors</strong>, |
|---|
| 9 | and returns the completed response to the Connector for ultimate |
|---|
| 10 | transmission back to the client.</p> |
|---|
| 11 | |
|---|
| 12 | <p>Exactly one <strong>Engine</strong> element MUST be nested inside |
|---|
| 13 | a <a href="service.html">Service</a> element, following all of the |
|---|
| 14 | corresponding Connector elements associated with this Service.</p> |
|---|
| 15 | |
|---|
| 16 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 17 | |
|---|
| 18 | <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Common Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 19 | |
|---|
| 20 | <p>All implementations of <strong>Engine</strong> |
|---|
| 21 | support the following attributes:</p> |
|---|
| 22 | |
|---|
| 23 | <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr><tr><td valign="center" align="left"><code>backgroundProcessorDelay</code></td><td valign="center" align="left"> |
|---|
| 24 | <p>This value represents the delay in seconds between the |
|---|
| 25 | invocation of the backgroundProcess method on this engine and |
|---|
| 26 | its child containers, including all hosts and contexts. |
|---|
| 27 | Child containers will not be invoked if their delay value is not |
|---|
| 28 | negative (which would mean they are using their own processing |
|---|
| 29 | thread). Setting this to a positive value will cause |
|---|
| 30 | a thread to be spawn. After waiting the specified amount of time, |
|---|
| 31 | the thread will invoke the backgroundProcess method on this engine |
|---|
| 32 | and all its child containers. If not specified, the default value for |
|---|
| 33 | this attribute is 10, which represent a 10 seconds delay.</p> |
|---|
| 34 | </td></tr><tr><td valign="center" align="left"><code>className</code></td><td valign="center" align="left"> |
|---|
| 35 | <p>Java class name of the implementation to use. This class must |
|---|
| 36 | implement the <code>org.apache.catalina.Engine</code> interface. |
|---|
| 37 | If not specified, the standard value (defined below) will be used.</p> |
|---|
| 38 | </td></tr><tr><td valign="center" align="left"><strong><code>defaultHost</code></strong></td><td valign="center" align="left"> |
|---|
| 39 | <p>The default host name, which identifies the |
|---|
| 40 | <a href="host.html">Host</a> that will process requests directed |
|---|
| 41 | to host names on this server, but which are not configured in |
|---|
| 42 | this configuration file. This name MUST match the <code>name</code> |
|---|
| 43 | attributes of one of the <a href="host.html">Host</a> elements |
|---|
| 44 | nested immediately inside.</p> |
|---|
| 45 | </td></tr><tr><td valign="center" align="left"><code>jvmRoute</code></td><td valign="center" align="left"> |
|---|
| 46 | <p>Identifier which must be used in load balancing scenarios to enable |
|---|
| 47 | session affinity. The identifier, which must be unique across all |
|---|
| 48 | Tomcat 6 servers which participate in the cluster, will be appended to |
|---|
| 49 | the generated session identifier, therefore allowing the front end |
|---|
| 50 | proxy to always forward a particular session to the same Tomcat 6 |
|---|
| 51 | instance.</p> |
|---|
| 52 | </td></tr><tr><td valign="center" align="left"><strong><code>name</code></strong></td><td valign="center" align="left"> |
|---|
| 53 | <p>Logical name of this Engine, used in log and error messages. <em>When |
|---|
| 54 | using muliple <a href="service.html">Service</a> elements in the same |
|---|
| 55 | <a href="server.html">Server</a>, each Engine MUST be assigned a unique |
|---|
| 56 | name.</em></p> |
|---|
| 57 | </td></tr></table> |
|---|
| 58 | |
|---|
| 59 | </blockquote></td></tr></table> |
|---|
| 60 | |
|---|
| 61 | |
|---|
| 62 | <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Standard Implementation"><strong>Standard Implementation</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 63 | |
|---|
| 64 | <p>The standard implementation of <strong>Engine</strong> is |
|---|
| 65 | <strong>org.apache.catalina.core.StandardEngine</strong>. |
|---|
| 66 | It supports the following additional attributes (in addition to the |
|---|
| 67 | common attributes listed above):</p> |
|---|
| 68 | |
|---|
| 69 | <table cellpadding="5" border="1"><tr><th bgcolor="#023264" width="15%"><font color="#ffffff">Attribute</font></th><th bgcolor="#023264" width="85%"><font color="#ffffff">Description</font></th></tr></table> |
|---|
| 70 | |
|---|
| 71 | </blockquote></td></tr></table> |
|---|
| 72 | |
|---|
| 73 | |
|---|
| 74 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Nested Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 75 | |
|---|
| 76 | <p>You can nest one or more <a href="host.html">Host</a> elements inside |
|---|
| 77 | this <strong>Engine</strong> element, each representing a different virtual |
|---|
| 78 | host associated with this server. At least one <a href="host.html">Host</a> |
|---|
| 79 | is required, and one of the nested <a href="host.html">Hosts</a> MUST |
|---|
| 80 | have a name that matches the name specified for the |
|---|
| 81 | <code>defaultHost</code> attribute, listed above.</p> |
|---|
| 82 | |
|---|
| 83 | <p>You can optional nest a <a href="defaultcontext.html">DefaultContext</a> |
|---|
| 84 | element inside this <strong>Engine</strong> element, to define the default |
|---|
| 85 | characteristics of web applications that are automatically deployed.</p> |
|---|
| 86 | |
|---|
| 87 | <p>You can nest at most one instance of the following utility components |
|---|
| 88 | by nesting a corresponding element inside your <strong>Engine</strong> |
|---|
| 89 | element:</p> |
|---|
| 90 | <ul> |
|---|
| 91 | <li><a href="realm.html"><strong>Realm</strong></a> - |
|---|
| 92 | Configure a realm that will allow its |
|---|
| 93 | database of users, and their associated roles, to be shared across all |
|---|
| 94 | <a href="host.html">Hosts</a> and <a href="context.html">Contexts</a> |
|---|
| 95 | nested inside this Engine, unless overridden by a |
|---|
| 96 | <a href="realm.html">Realm</a> configuration at a lower level.</li> |
|---|
| 97 | </ul> |
|---|
| 98 | |
|---|
| 99 | </blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Special Features"><strong>Special Features</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 100 | |
|---|
| 101 | |
|---|
| 102 | <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 103 | |
|---|
| 104 | <p>An engine is associated with the |
|---|
| 105 | <code>org.apache.catalina.core.ContainerBase.[enginename]</code> |
|---|
| 106 | log category. Note that the brackets are actually part of the name, |
|---|
| 107 | don't omit them.</p> |
|---|
| 108 | |
|---|
| 109 | </blockquote></td></tr></table> |
|---|
| 110 | |
|---|
| 111 | |
|---|
| 112 | <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Access Logs"><strong>Access Logs</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 113 | |
|---|
| 114 | <p>When you run a web server, one of the output files normally generated |
|---|
| 115 | is an <em>access log</em>, which generates one line of information for |
|---|
| 116 | each request processed by the server, in a standard format. Catalina |
|---|
| 117 | includes an optional <a href="valve.html">Valve</a> implementation that |
|---|
| 118 | can create access logs in the same standard format created by web servers, |
|---|
| 119 | or in any number of custom formats.</p> |
|---|
| 120 | |
|---|
| 121 | <p>You can ask Catalina to create an access log for all requests |
|---|
| 122 | processed by an <a href="engine.html">Engine</a>, |
|---|
| 123 | <a href="host.html">Host</a>, or <a href="context.html">Context</a> |
|---|
| 124 | by nesting a <a href="valve.html">Valve</a> element like this:</p> |
|---|
| 125 | |
|---|
| 126 | <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> |
|---|
| 127 | <Engine name="Standalone" ...> |
|---|
| 128 | ... |
|---|
| 129 | <Valve className="org.apache.catalina.valves.AccessLogValve" |
|---|
| 130 | prefix="catalina_access_log." suffix=".txt" |
|---|
| 131 | pattern="common"/> |
|---|
| 132 | ... |
|---|
| 133 | </Engine> |
|---|
| 134 | </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr></table></div> |
|---|
| 135 | |
|---|
| 136 | <p>See <a href="valve.html#Access Log Valve">Access Log Valve</a> |
|---|
| 137 | for more information on the configuration attributes that are |
|---|
| 138 | supported.</p> |
|---|
| 139 | |
|---|
| 140 | </blockquote></td></tr></table> |
|---|
| 141 | |
|---|
| 142 | |
|---|
| 143 | <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Lifecycle Listeners"><strong>Lifecycle Listeners</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 144 | |
|---|
| 145 | <p>If you have implemented a Java object that needs to know when this |
|---|
| 146 | <strong>Engine</strong> is started or stopped, you can declare it by |
|---|
| 147 | nesting a <strong>Listener</strong> element inside this element. The |
|---|
| 148 | class name you specify must implement the |
|---|
| 149 | <code>org.apache.catalina.LifecycleListener</code> interface, and |
|---|
| 150 | it will be notified about the occurrence of the coresponding |
|---|
| 151 | lifecycle events. Configuration of such a listener looks like this:</p> |
|---|
| 152 | |
|---|
| 153 | <div align="left"><table border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> |
|---|
| 154 | <Engine name="Standalone" ...> |
|---|
| 155 | ... |
|---|
| 156 | <Listener className="com.mycompany.mypackage.MyListener" ... > |
|---|
| 157 | ... |
|---|
| 158 | </Engine> |
|---|
| 159 | </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr></table></div> |
|---|
| 160 | |
|---|
| 161 | <p>Note that a Listener can have any number of additional properties |
|---|
| 162 | that may be configured from this element. Attribute names are matched |
|---|
| 163 | to corresponding JavaBean property names using the standard property |
|---|
| 164 | method naming patterns.</p> |
|---|
| 165 | |
|---|
| 166 | </blockquote></td></tr></table> |
|---|
| 167 | |
|---|
| 168 | |
|---|
| 169 | <table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Request Filters"><strong>Request Filters</strong></a></font></td></tr><tr><td><blockquote> |
|---|
| 170 | |
|---|
| 171 | <p>You can ask Catalina to check the IP address, or host name, on every |
|---|
| 172 | incoming request directed to the surrounding |
|---|
| 173 | <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or |
|---|
| 174 | <a href="context.html">Context</a> element. The remote address or name |
|---|
| 175 | will be checked against a configured list of "accept" and/or "deny" |
|---|
| 176 | filters, which are defined using the Regular Expression syntax supported |
|---|
| 177 | by the <a href="http://jakarta.apache.org/regexp/">Jakarta Regexp</a> |
|---|
| 178 | regular expression library. 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 border="0" cellpadding="0" cellspacing="4"><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr><tr><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#ffffff"><pre> |
|---|
| 183 | <Engine name="Standalone" ...> |
|---|
| 184 | ... |
|---|
| 185 | <Valve className="org.apache.catalina.valves.RemoteHostValve" |
|---|
| 186 | allow="*.mycompany.com,www.yourcompany.com"/> |
|---|
| 187 | <Valve className="org.apache.catalina.valves.RemoteAddrValve" |
|---|
| 188 | deny="192.168.1.*"/> |
|---|
| 189 | ... |
|---|
| 190 | </Engine> |
|---|
| 191 | </pre></td><td width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td></tr><tr><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></td><td height="1" width="1" bgcolor="#023264"><img border="0" hspace="0" vspace="0" height="1" width="1" src="../../images/void.gif"></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 size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em> |
|---|
| 201 | Copyright © 1999-2008, Apache Software Foundation |
|---|
| 202 | </em></font></div></td></tr></table></body></html> |
|---|
