Subversion Repositories Integrator Subversion

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
771 blopes 1 
<!DOCTYPE html SYSTEM "about:legacy-compat">
2 
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="../images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 Configuration Reference (9.0.112) - The Engine Container</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="../images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="../images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9 Configuration Reference</h1><div class="versionInfo">
3 
            Version 9.0.112,
4 
            <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>Top Level Elements</h2><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul></div><div><h2>Executors</h2><ul><li><a href="executor.html">Executor</a></li></ul></div><div><h2>Connectors</h2><ul><li><a href="http.html">HTTP/1.1</a></li><li><a href="http2.html">HTTP/2</a></li><li><a href="ajp.html">AJP</a></li></ul></div><div><h2>Containers</h2><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></div><div><h2>Nested Components</h2><ul><li><a href="cookie-processor.html">CookieProcessor</a></li><li><a href="credentialhandler.html">CredentialHandler</a></li><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="jar-scan-filter.html">JarScanFilter</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="sessionidgenerator.html">SessionIdGenerator</a></li><li><a href="valve.html">Valve</a></li></ul></div><div><h2>Cluster Elements</h2><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></div><div><h2>web.xml</h2><ul><li><a href="filter.html">Filter</a></li></ul></div><div><h2>Other</h2><ul><li><a href="runtime-attributes.html">Runtime attributes</a></li><li><a href="systemprops.html">System properties</a></li><li><a href="jaspic.html">JASPIC</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>The Engine Container</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
5 
<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>
6 
</div><h3 id="Introduction">Introduction</h3><div class="text">
7 
 
8 
  <p>The <strong>Engine</strong> element represents the entire request
9 
  processing machinery associated with a particular Catalina
10 
  <a href="service.html">Service</a>.  It receives and processes
11 
  <em>all</em> requests from one or more <strong>Connectors</strong>,
12 
  and returns the completed response to the Connector for ultimate
13 
  transmission back to the client.</p>
14 
 
15 
  <p>Exactly one <strong>Engine</strong> element MUST be nested inside
16 
  a <a href="service.html">Service</a> element, following all of the
17 
  corresponding Connector elements associated with this Service.</p>
18 
 
19 
</div><h3 id="Attributes">Attributes</h3><div class="text">
20 
 
21 
  <div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
22 
 
23 
    <p>All implementations of <strong>Engine</strong>
24 
    support the following attributes:</p>
25 
 
26 
    <table class="defaultTable"><tr><th style="width: 15%;">
27 
          Attribute
28 
        </th><th style="width: 85%;">
29 
          Description
30 
        </th></tr><tr id="Attributes_Common Attributes_backgroundProcessorDelay"><td><code class="attributeName">backgroundProcessorDelay</code></td><td>
31 
        <p>This value represents the delay in seconds between the
32 
        invocation of the backgroundProcess method on this engine and
33 
        its child containers, including all hosts and contexts.
34 
        Child containers will not be invoked if their delay value is not
35 
        negative (which would mean they are using their own processing
36 
        thread). Setting this to a positive value will cause
37 
        a thread to be spawn. After waiting the specified amount of time,
38 
        the thread will invoke the backgroundProcess method on this engine
39 
        and all its child containers. If not specified, the default value for
40 
        this attribute is 10, which represent a 10 seconds delay.</p>
41 
      </td></tr><tr id="Attributes_Common Attributes_className"><td><code class="attributeName">className</code></td><td>
42 
        <p>Java class name of the implementation to use.  This class must
43 
        implement the <code>org.apache.catalina.Engine</code> interface.
44 
        If not specified, the standard value (defined below) will be used.</p>
45 
      </td></tr><tr id="Attributes_Common Attributes_defaultHost"><td><strong><code class="attributeName">defaultHost</code></strong></td><td>
46 
        <p>The default host name, which identifies the
47 
        <a href="host.html">Host</a> that will process requests directed
48 
        to host names on this server, but which are not configured in
49 
        this configuration file.  This name MUST match the <code>name</code>
50 
        attributes of one of the <a href="host.html">Host</a> elements
51 
        nested immediately inside.</p>
52 
      </td></tr><tr id="Attributes_Common Attributes_jvmRoute"><td><code class="attributeName">jvmRoute</code></td><td>
53 
        <p>Identifier which must be used in load balancing scenarios to enable
54 
        session affinity. The identifier, which must be unique across all
55 
        Tomcat servers which participate in the cluster, will be appended to
56 
        the generated session identifier, therefore allowing the front end
57 
        proxy to always forward a particular session to the same Tomcat
58 
        instance.</p>
59 
        <p>
60 
            Note that the <code>jvmRoute</code> can also be set using the
61 
            deprecated <code>jvmRoute</code> system property. The
62 
            <code>jvmRoute</code> set in an <code>&lt;Engine&gt;</code>
63 
            attribute will override any <code>jvmRoute</code> system property.
64 
        </p>
65 
      </td></tr><tr id="Attributes_Common Attributes_name"><td><strong><code class="attributeName">name</code></strong></td><td>
66 
        <p>Logical name of this Engine, used in log and error messages. <em>When
67 
        using multiple <a href="service.html">Service</a> elements in the same
68 
        <a href="server.html">Server</a>, each Engine MUST be assigned a unique
69 
        name.</em></p>
70 
      </td></tr><tr id="Attributes_Common Attributes_startStopThreads"><td><code class="attributeName">startStopThreads</code></td><td>
71 
        <p>The number of threads this <strong>Engine</strong> will use to start
72 
        child <a href="host.html">Host</a> elements in parallel. The special
73 
        value of 0 will result in the value of
74 
        <code>Runtime.getRuntime().availableProcessors()</code> being used.
75 
        Negative values will result in
76 
        <code>Runtime.getRuntime().availableProcessors() + value</code> being
77 
        used unless this is less than 1 in which case 1 thread will be used. If
78 
        not specified, the default value of 1 will be used. If 1 thread is
79 
        used then, rather than using an <code>ExecutorService</code>, the
80 
        current thread will be used.</p>
81 
      </td></tr></table>
82 
 
83 
  </div></div>
84 
 
85 
 
86 
  <div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
87 
 
88 
    <p>The standard implementation of <strong>Engine</strong> is
89 
    <strong>org.apache.catalina.core.StandardEngine</strong>.
90 
    It supports the following additional attributes (in addition to the
91 
    common attributes listed above):</p>
92 
 
93 
    <table class="defaultTable"><tr><th style="width: 15%;">
94 
          Attribute
95 
        </th><th style="width: 85%;">
96 
          Description
97 
        </th></tr></table>
98 
 
99 
  </div></div>
100 
 
101 
 
102 
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
103 
 
104 
  <p>You can nest one or more <a href="host.html">Host</a> elements inside
105 
  this <strong>Engine</strong> element, each representing a different virtual
106 
  host associated with this server.  At least one <a href="host.html">Host</a>
107 
  is required, and one of the nested <a href="host.html">Hosts</a> MUST
108 
  have a name that matches the name specified for the
109 
  <code>defaultHost</code> attribute, listed above.</p>
110 
 
111 
  <p>You can nest at most one instance of the following utility components
112 
  by nesting a corresponding element inside your <strong>Engine</strong>
113 
  element:</p>
114 
  <ul>
115 
  <li><a href="realm.html"><strong>Realm</strong></a> -
116 
      Configure a realm that will allow its
117 
      database of users, and their associated roles, to be shared across all
118 
      <a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>
119 
      nested inside this Engine, unless overridden by a
120 
      <a href="realm.html">Realm</a> configuration at a lower level.</li>
121 
  </ul>
122 
 
123 
</div><h3 id="Special_Features">Special Features</h3><div class="text">
124 
 
125 
 
126 
  <div class="subsection"><h4 id="Logging">Logging</h4><div class="text">
127 
 
128 
    <p>An engine is associated with the
129 
       <code>org.apache.catalina.core.ContainerBase.[enginename]</code>
130 
       log category.  Note that the brackets are actually part of the name,
131 
       don't omit them.</p>
132 
 
133 
  </div></div>
134 
 
135 
 
136 
  <div class="subsection"><h4 id="Access_Logs">Access Logs</h4><div class="text">
137 
 
138 
    <p>When you run a web server, one of the output files normally generated
139 
    is an <em>access log</em>, which generates one line of information for
140 
    each request processed by the server, in a standard format.  Catalina
141 
    includes an optional <a href="valve.html">Valve</a> implementation that
142 
    can create access logs in the same standard format created by web servers,
143 
    or in any number of custom formats.</p>
144 
 
145 
    <p>You can ask Catalina to create an access log for all requests
146 
    processed by an <a href="engine.html">Engine</a>,
147 
    <a href="host.html">Host</a>, or <a href="context.html">Context</a>
148 
    by nesting a <a href="valve.html">Valve</a> element like this:</p>
149 
 
150 
<div class="codeBox"><pre><code>&lt;Engine name="Standalone" ...&gt;
151 
  ...
152 
  &lt;Valve className="org.apache.catalina.valves.AccessLogValve"
153 
         prefix="catalina_access_log" suffix=".txt"
154 
         pattern="common"/&gt;
155 
  ...
156 
&lt;/Engine&gt;</code></pre></div>
157 
 
158 
    <p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
159 
    for more information on the configuration attributes that are
160 
    supported.</p>
161 
 
162 
  </div></div>
163 
 
164 
 
165 
  <div class="subsection"><h4 id="Lifecycle_Listeners">Lifecycle Listeners</h4><div class="text">
166 
 
167 
    <p>If you have implemented a Java object that needs to know when this
168 
    <strong>Engine</strong> is started or stopped, you can declare it by
169 
    nesting a <strong>Listener</strong> element inside this element.  The
170 
    class name you specify must implement the
171 
    <code>org.apache.catalina.LifecycleListener</code> interface, and
172 
    it will be notified about the occurrence of the corresponding
173 
    lifecycle events.  Configuration of such a listener looks like this:</p>
174 
 
175 
<div class="codeBox"><pre><code>&lt;Engine name="Standalone" ...&gt;
176 
  ...
177 
  &lt;Listener className="com.mycompany.mypackage.MyListener" ... &gt;
178 
  ...
179 
&lt;/Engine&gt;</code></pre></div>
180 
 
181 
    <p>Note that a Listener can have any number of additional properties
182 
    that may be configured from this element.  Attribute names are matched
183 
    to corresponding JavaBean property names using the standard property
184 
    method naming patterns.</p>
185 
 
186 
  </div></div>
187 
 
188 
 
189 
  <div class="subsection"><h4 id="Request_Filters">Request Filters</h4><div class="text">
190 
 
191 
    <p>You can ask Catalina to check the IP address, or host name, on every
192 
    incoming request directed to the surrounding
193 
    <a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
194 
    <a href="context.html">Context</a> element.  The remote address or name
195 
    will be checked against configured "accept" and/or "deny"
196 
    filters, which are defined using <code>java.util.regex</code> Regular
197 
    Expression syntax.  Requests that come from locations that are
198 
    not accepted will be rejected with an HTTP "Forbidden" error.
199 
    Example filter declarations:</p>
200 
 
201 
<div class="codeBox"><pre><code>&lt;Engine name="Standalone" ...&gt;
202 
  ...
203 
  &lt;Valve className="org.apache.catalina.valves.RemoteHostValve"
204 
         allow=".*\.mycompany\.com|www\.yourcompany\.com"/&gt;
205 
  &lt;Valve className="org.apache.catalina.valves.RemoteCIDRValve"
206 
         deny="192.168.1.0/24"/&gt;
207 
  ...
208 
&lt;/Engine&gt;</code></pre></div>
209 
 
210 
  <p>See <a href="valve.html#Remote_Address_Filter">Remote Address Filter</a>
211 
  and <a href="valve.html#Remote_Host_Filter">Remote Host Filter</a> for
212 
  more information about the configuration options that are supported.</p>
213 
 
214 
  </div></div>
215 
 
216 
 
217 
</div></div></div></div></div><footer><div id="footer">
218 
    Copyright &copy; 1999-2025, The Apache Software Foundation
219 
    <br>
220 
    Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo
221 
    are either registered trademarks or trademarks of the Apache Software
222 
    Foundation.
223 
    </div></footer></div></body></html>