소스 파일 최초 업로드
This commit is contained in:
ByeonJungHun
758
tomcat/webapps.dist/docs/config/ajp.html
Normal file
758
tomcat/webapps.dist/docs/config/ajp.html
Normal file
@@ -0,0 +1,758 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The AJP Connector</title><meta name="author" content="Yoav Shapira"><meta name="author" content="Andrew R. Jaquith"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 AJP Connector</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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_Implementations">Standard Implementations</a></li><li><a href="#Java_TCP_socket_attributes">Java TCP socket attributes</a></li><li><a href="#NIO_specific_configuration">NIO specific configuration</a></li><li><a href="#NIO2_specific_configuration">NIO2 specific configuration</a></li><li><a href="#APR/native_specific_configuration">APR/native specific configuration</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="#Proxy_Support">Proxy Support</a></li><li><a href="#Connector_Comparison">Connector Comparison</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>AJP Connector</strong> element represents a
|
||||
<strong>Connector</strong> component that communicates with a web
|
||||
connector via the <code>AJP</code> protocol. This is used for cases
|
||||
where you wish to invisibly integrate Tomcat into an existing (or new)
|
||||
Apache installation, and you want Apache to handle the static content
|
||||
contained in the web application, and/or utilize Apache's SSL
|
||||
processing.</p>
|
||||
|
||||
<p>Use of the AJP protocol requires additional security considerations because
|
||||
it allows greater direct manipulation of Tomcat's internal data structures
|
||||
than the HTTP connectors. Particular attention should be paid to the values
|
||||
used for the <code>address</code>, <code>secret</code>,
|
||||
<code>secretRequired</code> and <code>allowedRequestAttributesPattern</code>
|
||||
attributes.</p>
|
||||
|
||||
<p>This connector supports load balancing when used in conjunction with
|
||||
the <code>jvmRoute</code> attribute of the
|
||||
<a href="engine.html">Engine</a>.</p>
|
||||
|
||||
<p>The native connectors supported with this Tomcat release are:</p>
|
||||
<ul>
|
||||
<li>JK 1.2.x with any of the supported servers. See
|
||||
<a href="https://tomcat.apache.org/connectors-doc/">the JK docs</a>
|
||||
for details.</li>
|
||||
<li>mod_proxy on Apache httpd 2.x (included by default in Apache HTTP
|
||||
Server 2.2), with AJP enabled: see
|
||||
<a href="https://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html">the
|
||||
httpd docs</a> for details.</li>
|
||||
</ul>
|
||||
|
||||
<p><b>Other native connectors supporting AJP may work, but are no longer
|
||||
supported.</b></p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Connector</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">allowTrace</code></td><td>
|
||||
<p>A boolean value which can be used to enable or disable the TRACE
|
||||
HTTP method. If not specified, this attribute is set to false. As per RFC
|
||||
7231 section 4.3.8, cookie and authorization headers will be excluded from
|
||||
the response to the TRACE request. If you wish to include these, you can
|
||||
implement the <code>doTrace()</code> method for the target Servlet and
|
||||
gain full control over the response.</p>
|
||||
</td></tr><tr><td><code class="attributeName">asyncTimeout</code></td><td>
|
||||
<p>The default timeout for asynchronous requests in milliseconds. If not
|
||||
specified, this attribute is set to the Servlet specification default of
|
||||
30000 (30 seconds).</p>
|
||||
</td></tr><tr><td><code class="attributeName">discardFacades</code></td><td>
|
||||
<p>A boolean value which can be used to enable or disable the recycling
|
||||
of the facade objects that isolate the container internal request
|
||||
processing objects. If set to <code>true</code> the facades will be
|
||||
set for garbage collection after every request, otherwise they will be
|
||||
reused. This setting has no effect when the security manager is enabled.
|
||||
If not specified, this attribute is set to <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">enableLookups</code></td><td>
|
||||
<p>Set to <code>true</code> if you want calls to
|
||||
<code>request.getRemoteHost()</code> to perform DNS lookups in
|
||||
order to return the actual host name of the remote client. Set
|
||||
to <code>false</code> to skip the DNS lookup and return the IP
|
||||
address in String form instead (thereby improving performance).
|
||||
By default, DNS lookups are disabled.</p>
|
||||
</td></tr><tr><td><code class="attributeName">encodedSolidusHandling</code></td><td>
|
||||
<p>When set to <code>reject</code> request paths containing a
|
||||
<code>%2f</code> sequence will be rejected with a 400 response. When set
|
||||
to <code>decode</code> request paths containing a <code>%2f</code>
|
||||
sequence will have that sequence decoded to <code>/</code> at the same
|
||||
time other <code>%nn</code> sequences are decoded. When set to
|
||||
<code>passthrough</code> request paths containing a <code>%2f</code>
|
||||
sequence will be processed with the <code>%2f</code> sequence unchanged.
|
||||
If not specified the default value is <code>reject</code>. This default
|
||||
may be modified if the deprecated <a href="systemprops.html">system
|
||||
property</a>
|
||||
<code>org.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH</code> is
|
||||
set.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxCookieCount</code></td><td>
|
||||
<p>The maximum number of cookies that are permitted for a request. A value
|
||||
of less than zero means no limit. If not specified, a default value of 200
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxParameterCount</code></td><td>
|
||||
<p>The maximum total number of request parameters (including uploaded
|
||||
files) obtained from the query string and, for POST requests, the request
|
||||
body if the content type is
|
||||
<code>application/x-www-form-urlencoded</code> or
|
||||
<code>multipart/form-data</code>. Request parameters beyond this limit
|
||||
will be ignored. A value of less than 0 means no limit. If not specified,
|
||||
a default of 1000 is used. Note that <code>FailedRequestFilter</code>
|
||||
<a href="filter.html">filter</a> can be used to reject requests that
|
||||
exceed the limit.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxPostSize</code></td><td>
|
||||
<p>The maximum size in bytes of the POST which will be handled by
|
||||
the container FORM URL parameter parsing. The limit can be disabled by
|
||||
setting this attribute to a value less than zero. If not specified, this
|
||||
attribute is set to 2097152 (2 megabytes). Note that the
|
||||
<a href="filter.html#Failed_Request_Filter"><code>FailedRequestFilter</code></a>
|
||||
can be used to reject requests that exceed this limit.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxSavePostSize</code></td><td>
|
||||
<p>The maximum size in bytes of the POST which will be saved/buffered by
|
||||
the container during FORM or CLIENT-CERT authentication. For both types
|
||||
of authentication, the POST will be saved/buffered before the user is
|
||||
authenticated. For CLIENT-CERT authentication, the POST is buffered for
|
||||
the duration of the SSL handshake and the buffer emptied when the request
|
||||
is processed. For FORM authentication the POST is saved whilst the user
|
||||
is re-directed to the login form and is retained until the user
|
||||
successfully authenticates or the session associated with the
|
||||
authentication request expires. The limit can be disabled by setting this
|
||||
attribute to -1. Setting the attribute to zero will disable the saving of
|
||||
POST data during authentication. If not specified, this attribute is set
|
||||
to 4096 (4 kilobytes).</p>
|
||||
</td></tr><tr><td><code class="attributeName">parseBodyMethods</code></td><td>
|
||||
<p>A comma-separated list of HTTP methods for which request
|
||||
bodies using <code>application/x-www-form-urlencoded</code> will be parsed
|
||||
for request parameters identically to POST. This is useful in RESTful
|
||||
applications that want to support POST-style semantics for PUT requests.
|
||||
Note that any setting other than <code>POST</code> causes Tomcat
|
||||
to behave in a way that goes against the intent of the servlet
|
||||
specification.
|
||||
The HTTP method TRACE is specifically forbidden here in accordance
|
||||
with the HTTP specification.
|
||||
The default is <code>POST</code></p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">port</code></strong></td><td>
|
||||
<p>The TCP port number on which this <strong>Connector</strong>
|
||||
will create a server socket and await incoming connections. Your
|
||||
operating system will allow only one server application to listen
|
||||
to a particular port number on a particular IP address. If the special
|
||||
value of 0 (zero) is used, then Tomcat will select a free port at random
|
||||
to use for this connector. This is typically only useful in embedded and
|
||||
testing applications.</p>
|
||||
</td></tr><tr><td><code class="attributeName">protocol</code></td><td>
|
||||
<p>Sets the protocol to handle incoming traffic. To configure an AJP
|
||||
connector this must be specified. If no value for protocol is provided,
|
||||
an <a href="http.html">HTTP connector</a> rather than an AJP connector
|
||||
will be configured.<br>
|
||||
The standard protocol value for an AJP connector is <code>AJP/1.3</code>
|
||||
which uses an auto-switching mechanism to select either a Java NIO based
|
||||
connector or an APR/native based connector. If the
|
||||
<code>PATH</code> (Windows) or <code>LD_LIBRARY_PATH</code> (on most unix
|
||||
systems) environment variables contain the Tomcat native library, the
|
||||
native/APR connector will be used. If the native library cannot be
|
||||
found, the Java NIO based connector will be used.<br>
|
||||
To use an explicit protocol rather than rely on the auto-switching
|
||||
mechanism described above, the following values may be used:<br>
|
||||
<code>org.apache.coyote.ajp.AjpNioProtocol</code>
|
||||
- non blocking Java NIO connector.<br>
|
||||
<code>org.apache.coyote.ajp.AjpNio2Protocol</code>
|
||||
- non blocking Java NIO2 connector.<br>
|
||||
<code>org.apache.coyote.ajp.AjpAprProtocol</code>
|
||||
- the APR/native connector.<br>
|
||||
Custom implementations may also be used.<br>
|
||||
Take a look at our <a href="#Connector_Comparison">Connector
|
||||
Comparison</a> chart.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">proxyName</code></td><td>
|
||||
<p>If this <strong>Connector</strong> is being used in a proxy
|
||||
configuration, configure this attribute to specify the server name
|
||||
to be returned for calls to <code>request.getServerName()</code>.
|
||||
See <a href="#Proxy_Support">Proxy Support</a> for more
|
||||
information.</p>
|
||||
</td></tr><tr><td><code class="attributeName">proxyPort</code></td><td>
|
||||
<p>If this <strong>Connector</strong> is being used in a proxy
|
||||
configuration, configure this attribute to specify the server port
|
||||
to be returned for calls to <code>request.getServerPort()</code>.
|
||||
See <a href="#Proxy_Support">Proxy Support</a> for more
|
||||
information.</p>
|
||||
</td></tr><tr><td><code class="attributeName">redirectPort</code></td><td>
|
||||
<p>If this <strong>Connector</strong> is supporting non-SSL
|
||||
requests, and a request is received for which a matching
|
||||
<code><security-constraint></code> requires SSL transport,
|
||||
Catalina will automatically redirect the request to the port
|
||||
number specified here.</p>
|
||||
</td></tr><tr><td><code class="attributeName">scheme</code></td><td>
|
||||
<p>Set this attribute to the name of the protocol you wish to have
|
||||
returned by calls to <code>request.getScheme()</code>. For
|
||||
example, you would set this attribute to "<code>https</code>"
|
||||
for an SSL Connector. The default value is "<code>http</code>".
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">secure</code></td><td>
|
||||
<p>Set this attribute to <code>true</code> if you wish to have
|
||||
calls to <code>request.isSecure()</code> to return <code>true</code>
|
||||
for requests received by this Connector. You would want this on an
|
||||
SSL Connector or a non SSL connector that is receiving data from a
|
||||
SSL accelerator, like a crypto card, an SSL appliance or even a webserver.
|
||||
The default value is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">URIEncoding</code></td><td>
|
||||
<p>This specifies the character encoding used to decode the URI bytes,
|
||||
after %xx decoding the URL. The default value is <code>UTF-8</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">useBodyEncodingForURI</code></td><td>
|
||||
<p>This specifies if the encoding specified in contentType should be used
|
||||
for URI query parameters, instead of using the URIEncoding. This
|
||||
setting is present for compatibility with Tomcat 4.1.x, where the
|
||||
encoding specified in the contentType, or explicitly set using
|
||||
Request.setCharacterEncoding method was also used for the parameters from
|
||||
the URL. The default value is <code>false</code>.
|
||||
</p>
|
||||
<p><em>Notes:</em> See notes on this attribute in
|
||||
<a href="http.html">HTTP Connector</a> documentation.</p>
|
||||
</td></tr><tr><td><code class="attributeName">useIPVHosts</code></td><td>
|
||||
<p>Set this attribute to <code>true</code> to cause Tomcat to use
|
||||
the IP address passed by the native web server to determine the Host
|
||||
to send the request to. The default value is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">xpoweredBy</code></td><td>
|
||||
<p>Set this attribute to <code>true</code> to cause Tomcat to advertise
|
||||
support for the Servlet specification using the header recommended in the
|
||||
specification. The default value is <code>false</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementations">Standard Implementations</h4><div class="text">
|
||||
|
||||
<p>To use AJP, you must specify the protocol attribute (see above).</p>
|
||||
|
||||
<p>The standard AJP connectors (NIO, NIO2 and APR/native) all support the
|
||||
following attributes in addition to the common Connector attributes listed
|
||||
above.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">acceptCount</code></td><td>
|
||||
<p>The maximum length of the operating system provided queue for incoming
|
||||
connection requests when <code>maxConnections</code> has been reached. The
|
||||
operating system may ignore this setting and use a different size for the
|
||||
queue. When this queue is full, the operating system may actively refuse
|
||||
additional connections or those connections may time out. The default
|
||||
value is 100.</p>
|
||||
</td></tr><tr><td><code class="attributeName">acceptorThreadCount</code></td><td>
|
||||
<p>The number of threads to be used to accept connections. Increase this
|
||||
value on a multi CPU machine, although you would never really need more
|
||||
than <code>2</code>. Also, with a lot of non keep alive connections, you
|
||||
might want to increase this value as well. Default value is
|
||||
<code>1</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">acceptorThreadPriority</code></td><td>
|
||||
<p>The priority of the acceptor threads. The threads used to accept
|
||||
new connections. The default value is <code>5</code> (the value of the
|
||||
<code>java.lang.Thread.NORM_PRIORITY</code> constant). See the JavaDoc
|
||||
for the <code>java.lang.Thread</code> class for more details on what
|
||||
this priority means.</p>
|
||||
</td></tr><tr><td><code class="attributeName">address</code></td><td>
|
||||
<p>For servers with more than one IP address, this attribute specifies
|
||||
which address will be used for listening on the specified port. By
|
||||
default, the connector will listen on the loopback address. Unless the JVM
|
||||
is configured otherwise using system properties, the Java based connectors
|
||||
(NIO, NIO2) will listen on both IPv4 and IPv6 addresses when configured
|
||||
with either <code>0.0.0.0</code> or <code>::</code>. The APR/native
|
||||
connector will only listen on IPv4 addresses if configured with
|
||||
<code>0.0.0.0</code> and will listen on IPv6 addresses (and optionally
|
||||
IPv4 addresses depending on the setting of <strong>ipv6v6only</strong>) if
|
||||
configured with <code>::</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">ajpFlush</code></td><td>
|
||||
<p>A boolean value which can be used to enable or disable sending
|
||||
AJP flush messages to the fronting proxy whenever an explicit
|
||||
flush happens. The default value is <code>true</code>.<br>
|
||||
An AJP flush message is a SEND_BODY_CHUNK packet with no body content.
|
||||
Proxy implementations like mod_jk or mod_proxy_ajp will flush the
|
||||
data buffered in the web server to the client when they receive
|
||||
such a packet. Setting this to <code>false</code> can reduce
|
||||
AJP packet traffic but might delay sending packets to the client.
|
||||
At the end of the response, AJP does always flush to the client.</p>
|
||||
</td></tr><tr><td><code class="attributeName">allowedRequestAttributesPattern</code></td><td>
|
||||
<p>The AJP protocol passes some information from the reverse proxy to the
|
||||
AJP connector using request attributes. These attributes are:</p>
|
||||
<ul>
|
||||
<li>javax.servlet.request.cipher_suite</li>
|
||||
<li>javax.servlet.request.key_size</li>
|
||||
<li>javax.servlet.request.ssl_session</li>
|
||||
<li>javax.servlet.request.X509Certificate</li>
|
||||
<li>AJP_LOCAL_ADDR</li>
|
||||
<li>AJP_REMOTE_PORT</li>
|
||||
<li>AJP_SSL_PROTOCOL</li>
|
||||
<li>JK_LB_ACTIVATION</li>
|
||||
<li>CERT_ISSUER (IIS only)</li>
|
||||
<li>CERT_SUBJECT (IIS only)</li>
|
||||
<li>CERT_COOKIE (IIS only)</li>
|
||||
<li>HTTPS_SERVER_SUBJECT (IIS only)</li>
|
||||
<li>CERT_FLAGS (IIS only)</li>
|
||||
<li>HTTPS_SECRETKEYSIZE (IIS only)</li>
|
||||
<li>CERT_SERIALNUMBER (IIS only)</li>
|
||||
<li>HTTPS_SERVER_ISSUER (IIS only)</li>
|
||||
<li>HTTPS_KEYSIZE (IIS only)</li>
|
||||
</ul>
|
||||
<p>The AJP protocol supports the passing of arbitrary request attributes.
|
||||
Requests containing arbitrary request attributes will be rejected with a
|
||||
403 response unless the entire attribute name matches this regular
|
||||
expression. If not specified, the default value is <code>null</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">bindOnInit</code></td><td>
|
||||
<p>Controls when the socket used by the connector is bound. If set to
|
||||
<code>true</code> it is bound when the connector is initiated and unbound
|
||||
when the connector is destroyed. If set to <code>false</code>, the socket
|
||||
will be bound when the connector is started and unbound when it is
|
||||
stopped. If not specified, the default is <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">clientCertProvider</code></td><td>
|
||||
<p>When client certificate information is presented in a form other than
|
||||
instances of <code>java.security.cert.X509Certificate</code> it needs to
|
||||
be converted before it can be used and this property controls which JSSE
|
||||
provider is used to perform the conversion. For example it is used with
|
||||
the AJP connectors, the <a href="http.html">HTTP APR connector</a> and
|
||||
with the <a href="valve.html#SSL_Authenticator_Valve">
|
||||
org.apache.catalina.valves.SSLValve</a>.If not specified, the default
|
||||
provider will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">connectionLinger</code></td><td>
|
||||
<p>The number of seconds during which the sockets used by this
|
||||
<strong>Connector</strong> will linger when they are closed. The default
|
||||
value is <code>-1</code> which disables socket linger.</p>
|
||||
</td></tr><tr><td><code class="attributeName">connectionTimeout</code></td><td>
|
||||
<p>The number of milliseconds this <strong>Connector</strong> will wait,
|
||||
after accepting a connection, for the request URI line to be
|
||||
presented. The default value for AJP protocol connectors
|
||||
is <code>-1</code> (i.e. infinite).</p>
|
||||
</td></tr><tr><td><code class="attributeName">executor</code></td><td>
|
||||
<p>A reference to the name in an <a href="executor.html">Executor</a>
|
||||
element. If this attribute is set, and the named executor exists, the
|
||||
connector will use the executor, and all the other thread attributes will
|
||||
be ignored. Note that if a shared executor is not specified for a
|
||||
connector then the connector will use a private, internal executor to
|
||||
provide the thread pool.</p>
|
||||
</td></tr><tr><td><code class="attributeName">executorTerminationTimeoutMillis</code></td><td>
|
||||
<p>The time that the private internal executor will wait for request
|
||||
processing threads to terminate before continuing with the process of
|
||||
stopping the connector. If not set, the default is <code>5000</code> (5
|
||||
seconds).</p>
|
||||
</td></tr><tr><td><code class="attributeName">keepAliveTimeout</code></td><td>
|
||||
<p>The number of milliseconds this <strong>Connector</strong> will wait for
|
||||
another AJP request before closing the connection.
|
||||
The default value is to use the value that has been set for the
|
||||
connectionTimeout attribute.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxConnections</code></td><td>
|
||||
<p>The maximum number of connections that the server will accept and
|
||||
process at any given time. When this number has been reached, the server
|
||||
will accept, but not process, one further connection. This additional
|
||||
connection be blocked until the number of connections being processed
|
||||
falls below <strong>maxConnections</strong> at which point the server will
|
||||
start accepting and processing new connections again. Note that once the
|
||||
limit has been reached, the operating system may still accept connections
|
||||
based on the <code>acceptCount</code> setting. The default value
|
||||
is <code>8192</code>.</p>
|
||||
<p>For NIO/NIO2 only, setting the value to -1, will disable the
|
||||
maxConnections feature and connections will not be counted.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxHeaderCount</code></td><td>
|
||||
<p>The maximum number of headers in a request that are allowed by the
|
||||
container. A request that contains more headers than the specified limit
|
||||
will be rejected. A value of less than 0 means no limit.
|
||||
If not specified, a default of 100 is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxThreads</code></td><td>
|
||||
<p>The maximum number of request processing threads to be created
|
||||
by this <strong>Connector</strong>, which therefore determines the
|
||||
maximum number of simultaneous requests that can be handled. If
|
||||
not specified, this attribute is set to 200. If an executor is associated
|
||||
with this connector, this attribute is ignored as the connector will
|
||||
execute tasks using the executor rather than an internal thread pool. Note
|
||||
that if an executor is configured any value set for this attribute will be
|
||||
recorded correctly but it will be reported (e.g. via JMX) as
|
||||
<code>-1</code> to make clear that it is not used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">minSpareThreads</code></td><td>
|
||||
<p>The minimum number of threads always kept running. This includes both
|
||||
active and idle threads. If not specified, the default of <code>10</code>
|
||||
is used. If an executor is associated with this connector, this attribute
|
||||
is ignored as the connector will execute tasks using the executor rather
|
||||
than an internal thread pool. Note that if an executor is configured any
|
||||
value set for this attribute will be recorded correctly but it will be
|
||||
reported (e.g. via JMX) as <code>-1</code> to make clear that it is not
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">packetSize</code></td><td>
|
||||
<p>This attribute sets the maximum AJP packet size in Bytes. The maximum
|
||||
value is 65536. It should be the same as the <code>max_packet_size</code>
|
||||
directive configured for mod_jk. Normally it is not necessary to change
|
||||
the maximum packet size. Problems with the default value have been
|
||||
reported when sending certificates or certificate chains. The default
|
||||
value is 8192. If set to less than 8192 then the setting will ignored and
|
||||
the default value of 8192 used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">processorCache</code></td><td>
|
||||
<p>The protocol handler caches Processor objects to speed up performance.
|
||||
This setting dictates how many of these objects get cached.
|
||||
<code>-1</code> means unlimited, default is <code>200</code>. If not using
|
||||
Servlet 3.0 asynchronous processing, a good default is to use the same as
|
||||
the maxThreads setting. If using Servlet 3.0 asynchronous processing, a
|
||||
good default is to use the larger of maxThreads and the maximum number of
|
||||
expected concurrent requests (synchronous and asynchronous).</p>
|
||||
</td></tr><tr><td><code class="attributeName">secret</code></td><td>
|
||||
<p>Only requests from workers with this secret keyword will be accepted.
|
||||
The default value is <code>null</code>. This attribute must be specified
|
||||
with a non-null, non-zero length value unless
|
||||
<strong>secretRequired</strong> is explicitly configured to be
|
||||
<code>false</code>. If this attribute is configured with a non-null,
|
||||
non-zero length value then the workers <strong>must</strong> provide a
|
||||
matching value else the request will be rejected irrespective of the
|
||||
setting of <strong>secretRequired</strong>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">secretRequired</code></td><td>
|
||||
<p>If this attribute is <code>true</code>, the AJP Connector will only
|
||||
start if the <strong>secret</strong> attribute is configured with a
|
||||
non-null, non-zero length value. This attribute only controls whether
|
||||
the <strong>secret</strong> attribute is required to be specified for the
|
||||
AJP Connector to start. It <strong>does not</strong> control whether
|
||||
workers are required to provide the secret. The default value is
|
||||
<code>true</code>. This attribute should only be set to <code>false</code>
|
||||
when the Connector is used on a trusted network.</p>
|
||||
</td></tr><tr><td><code class="attributeName">tcpNoDelay</code></td><td>
|
||||
<p>If set to <code>true</code>, the TCP_NO_DELAY option will be
|
||||
set on the server socket, which improves performance under most
|
||||
circumstances. This is set to <code>true</code> by default.</p>
|
||||
</td></tr><tr><td><code class="attributeName">threadPriority</code></td><td>
|
||||
<p>The priority of the request processing threads within the JVM.
|
||||
The default value is <code>5</code> (the value of the
|
||||
<code>java.lang.Thread.NORM_PRIORITY</code> constant). See the JavaDoc
|
||||
for the <code>java.lang.Thread</code> class for more details on what
|
||||
this priority means.If an executor is associated
|
||||
with this connector, this attribute is ignored as the connector will
|
||||
execute tasks using the executor rather than an internal thread pool. Note
|
||||
that if an executor is configured any value set for this attribute will be
|
||||
recorded correctly but it will be reported (e.g. via JMX) as
|
||||
<code>-1</code> to make clear that it is not used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">throwOnFailure</code></td><td>
|
||||
<p>If the Connector experiences an Exception during a Lifecycle transition
|
||||
should the Exception be rethrown or logged? If not specified, the default
|
||||
of <code>false</code> will be used. Note that the default can be changed
|
||||
by the <code>org.apache.catalina.startup.EXIT_ON_INIT_FAILURE</code>
|
||||
system property.</p>
|
||||
</td></tr><tr><td><code class="attributeName">tomcatAuthentication</code></td><td>
|
||||
<p>If set to <code>true</code>, the authentication will be done in Tomcat.
|
||||
Otherwise, the authenticated principal will be propagated from the native
|
||||
webserver and used for authorization in Tomcat. </p>
|
||||
<p>The web server must send the user principal (username) as a request
|
||||
<i>attribute</i> named <code>REMOTE_USER</code>.</p>
|
||||
<p>Note that this principal will have no roles associated with it.</p>
|
||||
<p>The default value is <code>true</code>. If
|
||||
<code>tomcatAuthorization</code> is set to <code>true</code> this
|
||||
attribute has no effect.</p>
|
||||
</td></tr><tr><td><code class="attributeName">tomcatAuthorization</code></td><td>
|
||||
<p>If set to <code>true</code>, the authenticated principal will be
|
||||
propagated from the native webserver and considered already authenticated
|
||||
in Tomcat. If the web application has one or more security constraints,
|
||||
authorization will then be performed by Tomcat and roles assigned to the
|
||||
authenticated principal. If the appropriate Tomcat Realm for the request
|
||||
does not recognise the provided user name, a Principal will be still be
|
||||
created but it will have no roles. The default value is
|
||||
<code>false</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Java_TCP_socket_attributes">Java TCP socket attributes</h4><div class="text">
|
||||
|
||||
<p>The NIO and NIO2 implementation support the following Java TCP socket
|
||||
attributes in addition to the common Connector and HTTP attributes listed
|
||||
above.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">socket.rxBufSize</code></td><td>
|
||||
<p>(int)The socket receive buffer (SO_RCVBUF) size in bytes. JVM default
|
||||
used if not set.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.txBufSize</code></td><td>
|
||||
<p>(int)The socket send buffer (SO_SNDBUF) size in bytes. JVM default
|
||||
used if not set. Care should be taken if explicitly setting this value.
|
||||
Very poor performance has been observed on some JVMs with values less
|
||||
than ~8k.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.tcpNoDelay</code></td><td>
|
||||
<p>(bool)This is equivalent to standard attribute
|
||||
<strong>tcpNoDelay</strong>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.soKeepAlive</code></td><td>
|
||||
<p>(bool)Boolean value for the socket's keep alive setting
|
||||
(SO_KEEPALIVE). JVM default used if not set.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.ooBInline</code></td><td>
|
||||
<p>(bool)Boolean value for the socket OOBINLINE setting. JVM default
|
||||
used if not set.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.soReuseAddress</code></td><td>
|
||||
<p>(bool)Boolean value for the sockets reuse address option
|
||||
(SO_REUSEADDR). JVM default used if not set.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.soLingerOn</code></td><td>
|
||||
<p>(bool)Boolean value for the sockets so linger option (SO_LINGER).
|
||||
A value for the standard attribute <strong>connectionLinger</strong>
|
||||
that is >=0 is equivalent to setting this to <code>true</code>.
|
||||
A value for the standard attribute <strong>connectionLinger</strong>
|
||||
that is <0 is equivalent to setting this to <code>false</code>.
|
||||
Both this attribute and <code>soLingerTime</code> must be set else the
|
||||
JVM defaults will be used for both.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.soLingerTime</code></td><td>
|
||||
<p>(int)Value in seconds for the sockets so linger option (SO_LINGER).
|
||||
This is equivalent to standard attribute
|
||||
<strong>connectionLinger</strong>.
|
||||
Both this attribute and <code>soLingerOn</code> must be set else the
|
||||
JVM defaults will be used for both.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.soTimeout</code></td><td>
|
||||
<p>This is equivalent to standard attribute
|
||||
<strong>connectionTimeout</strong>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.performanceConnectionTime</code></td><td>
|
||||
<p>(int)The first value for the performance settings. See
|
||||
<a href="http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setPerformancePreferences(int,%20int,%20int)">Socket Performance Options</a>
|
||||
All three performance attributes must be set else the JVM defaults will
|
||||
be used for all three.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.performanceLatency</code></td><td>
|
||||
<p>(int)The second value for the performance settings. See
|
||||
<a href="http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setPerformancePreferences(int,%20int,%20int)">Socket Performance Options</a>
|
||||
All three performance attributes must be set else the JVM defaults will
|
||||
be used for all three.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.performanceBandwidth</code></td><td>
|
||||
<p>(int)The third value for the performance settings. See
|
||||
<a href="http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setPerformancePreferences(int,%20int,%20int)">Socket Performance Options</a>
|
||||
All three performance attributes must be set else the JVM defaults will
|
||||
be used for all three.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.unlockTimeout</code></td><td>
|
||||
<p>(int) The timeout for a socket unlock. When a connector is stopped, it will try to release the acceptor thread by opening a connector to itself.
|
||||
The default value is <code>250</code> and the value is in milliseconds</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="NIO_specific_configuration">NIO specific configuration</h4><div class="text">
|
||||
|
||||
<p>The following attributes are specific to the NIO connector.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">socket.directBuffer</code></td><td>
|
||||
<p>(bool)Boolean value, whether to use direct ByteBuffers or java mapped
|
||||
ByteBuffers. Default is <code>false</code>.<br>
|
||||
When you are using direct buffers, make sure you allocate the
|
||||
appropriate amount of memory for the direct memory space. On Sun's JDK
|
||||
that would be something like <code>-XX:MaxDirectMemorySize=256m</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.appReadBufSize</code></td><td>
|
||||
<p>(int)Each connection that is opened up in Tomcat get associated with
|
||||
a read ByteBuffer. This attribute controls the size of this buffer. By
|
||||
default this read buffer is sized at <code>8192</code> bytes. For lower
|
||||
concurrency, you can increase this to buffer more data. For an extreme
|
||||
amount of keep alive connections, decrease this number or increase your
|
||||
heap size.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.appWriteBufSize</code></td><td>
|
||||
<p>(int)Each connection that is opened up in Tomcat get associated with
|
||||
a write ByteBuffer. This attribute controls the size of this buffer. By
|
||||
default this write buffer is sized at <code>8192</code> bytes. For low
|
||||
concurrency you can increase this to buffer more response data. For an
|
||||
extreme amount of keep alive connections, decrease this number or
|
||||
increase your heap size.<br>
|
||||
The default value here is pretty low, you should up it if you are not
|
||||
dealing with tens of thousands concurrent connections.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.bufferPool</code></td><td>
|
||||
<p>(int)The NIO connector uses a class called NioChannel that holds
|
||||
elements linked to a socket. To reduce garbage collection, the NIO
|
||||
connector caches these channel objects. This value specifies the size of
|
||||
this cache. The default value is <code>500</code>, and represents that
|
||||
the cache will hold 500 NioChannel objects. Other values are
|
||||
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.bufferPoolSize</code></td><td>
|
||||
<p>(int)The NioChannel pool can also be size based, not used object
|
||||
based. The size is calculated as follows:<br>
|
||||
NioChannel
|
||||
<code>buffer size = read buffer size + write buffer size</code><br>
|
||||
SecureNioChannel <code>buffer size = application read buffer size +
|
||||
application write buffer size + network read buffer size +
|
||||
network write buffer size</code><br>
|
||||
The value is in bytes, the default value is <code>1024*1024*100</code>
|
||||
(100MB).</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.processorCache</code></td><td>
|
||||
<p>(int)Tomcat will cache SocketProcessor objects to reduce garbage
|
||||
collection. The integer value specifies how many objects to keep in the
|
||||
cache at most. The default is <code>500</code>. Other values are
|
||||
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.keyCache</code></td><td>
|
||||
<p>(int)Tomcat will cache KeyAttachment objects to reduce garbage
|
||||
collection. The integer value specifies how many objects to keep in the
|
||||
cache at most. The default is <code>500</code>. Other values are
|
||||
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.eventCache</code></td><td>
|
||||
<p>(int)Tomcat will cache PollerEvent objects to reduce garbage
|
||||
collection. The integer value specifies how many objects to keep in the
|
||||
cache at most. The default is <code>500</code>. Other values are
|
||||
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="NIO2_specific_configuration">NIO2 specific configuration</h4><div class="text">
|
||||
|
||||
<p>The following attributes are specific to the NIO2 connector.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">useCaches</code></td><td>
|
||||
<p>(bool)Use this attribute to enable or disable object caching to
|
||||
reduce the amount of GC objects produced.
|
||||
The default value is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.directBuffer</code></td><td>
|
||||
<p>(bool)Boolean value, whether to use direct ByteBuffers or java mapped
|
||||
ByteBuffers. Default is <code>false</code>.<br>
|
||||
When you are using direct buffers, make sure you allocate the
|
||||
appropriate amount of memory for the direct memory space. On Sun's JDK
|
||||
that would be something like <code>-XX:MaxDirectMemorySize=256m</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.appReadBufSize</code></td><td>
|
||||
<p>(int)Each connection that is opened up in Tomcat get associated with
|
||||
a read ByteBuffer. This attribute controls the size of this buffer. By
|
||||
default this read buffer is sized at <code>8192</code> bytes. For lower
|
||||
concurrency, you can increase this to buffer more data. For an extreme
|
||||
amount of keep alive connections, decrease this number or increase your
|
||||
heap size.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.appWriteBufSize</code></td><td>
|
||||
<p>(int)Each connection that is opened up in Tomcat get associated with
|
||||
a write ByteBuffer. This attribute controls the size of this buffer. By
|
||||
default this write buffer is sized at <code>8192</code> bytes. For low
|
||||
concurrency you can increase this to buffer more response data. For an
|
||||
extreme amount of keep alive connections, decrease this number or
|
||||
increase your heap size.<br>
|
||||
The default value here is pretty low, you should up it if you are not
|
||||
dealing with tens of thousands concurrent connections.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.bufferPoolSize</code></td><td>
|
||||
<p>(int)The NIO2 connector uses a class called Nio2Channel that holds
|
||||
elements linked to a socket. To reduce garbage collection, the NIO
|
||||
connector caches these channel objects. This value specifies the size of
|
||||
this cache. The default value is <code>500</code>, and represents that
|
||||
the cache will hold 500 Nio2Channel objects. Other values are
|
||||
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
|
||||
</td></tr><tr><td><code class="attributeName">socket.processorCache</code></td><td>
|
||||
<p>(int)Tomcat will cache SocketProcessor objects to reduce garbage
|
||||
collection. The integer value specifies how many objects to keep in the
|
||||
cache at most. The default is <code>500</code>. Other values are
|
||||
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="APR/native_specific_configuration">APR/native specific configuration</h4><div class="text">
|
||||
|
||||
<p>The APR/native implementation supports the following attributes in
|
||||
addition to the common Connector and AJP attributes listed above.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">ipv6v6only</code></td><td>
|
||||
<p>If listening on an IPv6 address on a dual stack system, should the
|
||||
connector only listen on the IPv6 address? If not specified the default
|
||||
is <code>false</code> and the connector will listen on the IPv6 address
|
||||
and the equivalent IPv4 address if present.</p>
|
||||
</td></tr><tr><td><code class="attributeName">pollTime</code></td><td>
|
||||
<p>Duration of a poll call in microseconds. Lowering this value will
|
||||
slightly decrease latency of connections being kept alive in some cases
|
||||
, but will use more CPU as more poll calls are being made. The default
|
||||
value is 2000 (2ms).
|
||||
</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>None at this time.</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Proxy_Support">Proxy Support</h4><div class="text">
|
||||
|
||||
<p>The <code>proxyName</code> and <code>proxyPort</code> attributes can
|
||||
be used when Tomcat is run behind a proxy server. These attributes
|
||||
modify the values returned to web applications that call the
|
||||
<code>request.getServerName()</code> and <code>request.getServerPort()</code>
|
||||
methods, which are often used to construct absolute URLs for redirects.
|
||||
Without configuring these attributes, the values returned would reflect
|
||||
the server name and port on which the connection from the proxy server
|
||||
was received, rather than the server name and port to whom the client
|
||||
directed the original request.</p>
|
||||
|
||||
<p>For more information, see the
|
||||
<a href="../proxy-howto.html">Proxy Support How-To</a>.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Connector_Comparison">Connector Comparison</h4><div class="text">
|
||||
|
||||
<p>Below is a small chart that shows how the connectors differ.</p>
|
||||
|
||||
<table class="defaultTable" style="text-align: center;">
|
||||
<tr>
|
||||
<th></th>
|
||||
<th style="text-align: center;">Java Nio Connector<br>NIO</th>
|
||||
<th style="text-align: center;">Java Nio2 Connector<br>NIO2</th>
|
||||
<th style="text-align: center;">APR/native Connector<br>APR</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Classname</th>
|
||||
<td><code class="noHighlight">AjpNioProtocol</code></td>
|
||||
<td><code class="noHighlight">AjpNio2Protocol</code></td>
|
||||
<td><code class="noHighlight">AjpAprProtocol</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Tomcat Version</th>
|
||||
<td>7.x onwards</td>
|
||||
<td>8.x onwards</td>
|
||||
<td>5.5.x onwards</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Support Polling</th>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
<td>YES</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Polling Size</th>
|
||||
<td><code class="noHighlight">maxConnections</code></td>
|
||||
<td><code class="noHighlight">maxConnections</code></td>
|
||||
<td><code class="noHighlight">maxConnections</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Read Request Headers</th>
|
||||
<td>Blocking</td>
|
||||
<td>Blocking</td>
|
||||
<td>Blocking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Read Request Body</th>
|
||||
<td>Blocking</td>
|
||||
<td>Blocking</td>
|
||||
<td>Blocking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Write Response Headers and Body</th>
|
||||
<td>Blocking</td>
|
||||
<td>Blocking</td>
|
||||
<td>Blocking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Wait for next Request</th>
|
||||
<td>Non Blocking</td>
|
||||
<td>Non Blocking</td>
|
||||
<td>Non Blocking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>Max Connections</th>
|
||||
<td><code class="noHighlight">maxConnections</code></td>
|
||||
<td><code class="noHighlight">maxConnections</code></td>
|
||||
<td><code class="noHighlight">maxConnections</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
498
tomcat/webapps.dist/docs/config/automatic-deployment.html
Normal file
498
tomcat/webapps.dist/docs/config/automatic-deployment.html
Normal file
@@ -0,0 +1,498 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - Automatic Deployment - Use cases</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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>Automatic Deployment - Use cases</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Key">Key</a></li><li><a href="#New_files">New files</a></li><li><a href="#Deleted_files">Deleted files</a></li><li><a href="#Modified_files">Modified files</a></li><li><a href="#Added_files">Added files</a></li><li><a href="#Notes">Notes</a></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>This page defines the expected behaviour of the automatic deployer in many
|
||||
typical use cases. This is a complex area of Tomcat's functionality.
|
||||
While any difference between this document and Tomcat's behaviour is a
|
||||
bug, the fix may be to change this document, Tomcat's behaviour or
|
||||
both.</p>
|
||||
|
||||
</div><h3 id="Key">Key</h3><div class="text">
|
||||
|
||||
<table class="detail-table">
|
||||
<tr>
|
||||
<th>Term</th><th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>XML</td>
|
||||
<td>An XML configuration file located in the Host's
|
||||
<em>configBase</em>. It must contain a single <Context> element
|
||||
and may contain optional nested elements. It does not define an
|
||||
explicit <em>docBase</em> attribute. It represents a single web
|
||||
application. It is often referred to as a context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>XML+EW</td>
|
||||
<td>An XML configuration file located in the Host's
|
||||
<em>configBase</em>. It must contain a single <Context> element
|
||||
and may contain optional nested elements. It includes an explicit
|
||||
<em>docBase</em> attribute that points to an external WAR. It
|
||||
represents a single web application. It is often referred to as a
|
||||
context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>XML+ED</td>
|
||||
<td>An XML configuration file located in the Host's
|
||||
<em>configBase</em>. It must contain a single <Context> element
|
||||
and may contain optional nested elements. It includes an explicit
|
||||
<em>docBase</em> attribute that points to an external directory. It
|
||||
represents a single web application. It is often referred to as a
|
||||
context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>WAR</td>
|
||||
<td>A WAR file located in the Host's <em>appBase</em>. The WAR does
|
||||
not include an embedded context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>A WAR file located in the Host's <em>appBase</em>. The WAR does
|
||||
include an embedded context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>DIR</td>
|
||||
<td>A directory located in the Host's <em>appBase</em>. The directory
|
||||
does not include an embedded context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>DIR+XML</td>
|
||||
<td>A directory located in the Host's <em>appBase</em>. The directory
|
||||
does include an embedded context.xml file.</td>
|
||||
</tr><tr>
|
||||
<td>redeploy</td>
|
||||
<td>The Context object that represents the web application is destroyed
|
||||
and a new Context object is created. If present and permitted by the
|
||||
configuration, this new Context object is created by parsing the
|
||||
context.xml file. The web.xml file is parsed during the application
|
||||
start process. Any sessions stored in the standard Manager in the
|
||||
default configuration will not be persisted. Any requests to the web
|
||||
application during the redeploy will be handled as if the web
|
||||
application is not deployed.</td>
|
||||
</tr><tr>
|
||||
<td>reload</td>
|
||||
<td>The Context object that represents the web application is stopped and
|
||||
then started. The web.xml file is parsed during the application start
|
||||
process. Any sessions stored in the standard Manager in the default
|
||||
configuration will not be persisted. Any requests to the web
|
||||
application during the reload will be held until the reload completes
|
||||
at which point they will continue using the reloaded web application.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div><h3 id="New_files">New files</h3><div class="text">
|
||||
|
||||
<p>This section describes Tomcat's behaviour when the automatic
|
||||
deployment process discovers a new web application.</p>
|
||||
|
||||
<table class="detail-table">
|
||||
<tr>
|
||||
<th rowspan="2">Starting artifact(s)</th>
|
||||
<th colspan="3">Configuration Settings</th>
|
||||
<th colspan="4">Result</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>deployXML</th><th>copyXML</th><th>unpackWARs</th>
|
||||
<th>XML</th><th>WAR</th><th>DIR</th><th>Notes</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>XML</td>
|
||||
<td>either</td><td>either</td><td>either</td>
|
||||
<td>Y</td><td>N</td><td>N</td><td>1, 2, 3</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>XML+EW</td>
|
||||
<td>either</td><td>either</td><td>false</td>
|
||||
<td>Y</td><td>N</td><td>N</td><td>1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>XML+EW</td>
|
||||
<td>either</td><td>either</td><td>true</td>
|
||||
<td>Y</td><td>N</td><td>Y</td><td>1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>XML+ED</td>
|
||||
<td>either</td><td>either</td><td>either</td>
|
||||
<td>Y</td><td>N</td><td>N</td><td>1, 2</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>false</td><td>either</td><td>false</td>
|
||||
<td>N</td><td>Y</td><td>N</td><td>4</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>false</td><td>either</td><td>true</td>
|
||||
<td>N</td><td>Y</td><td>Y</td><td>4</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>true</td><td>false</td><td>false</td>
|
||||
<td>N</td><td>Y</td><td>N</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>true</td><td>false</td><td>true</td>
|
||||
<td>N</td><td>Y</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>true</td><td>true</td><td>false</td>
|
||||
<td>Y</td><td>Y</td><td>N</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR+XML</td>
|
||||
<td>true</td><td>true</td><td>true</td>
|
||||
<td>Y</td><td>Y</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR</td>
|
||||
<td>either</td><td>either</td><td>false</td>
|
||||
<td>N</td><td>Y</td><td>N</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>WAR</td>
|
||||
<td>either</td><td>either</td><td>true</td>
|
||||
<td>N</td><td>Y</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DIR+XML</td>
|
||||
<td>false</td><td>either</td><td>either</td>
|
||||
<td>N</td><td>N</td><td>Y</td><td>4</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DIR+XML</td>
|
||||
<td>true</td><td>false</td><td>either</td>
|
||||
<td>N</td><td>N</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DIR+XML</td>
|
||||
<td>true</td><td>true</td><td>either</td>
|
||||
<td>Y</td><td>N</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DIR</td>
|
||||
<td>false</td><td>either</td><td>either</td>
|
||||
<td>N</td><td>N</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div><h3 id="Deleted_files">Deleted files</h3><div class="text">
|
||||
|
||||
<p>This section describes Tomcat's behaviour when the automatic
|
||||
deployment process detects that a web application file has been deleted.</p>
|
||||
|
||||
<p>When a file is deleted or modified any redeploy resources that are listed
|
||||
after the modified/deleted resource are themselves deleted (and possibly
|
||||
re-created). The order of redeploy resources is:</p>
|
||||
|
||||
<ol>
|
||||
<li>WAR</li>
|
||||
<li>DIR</li>
|
||||
<li>XML</li>
|
||||
<li>global resources</li>
|
||||
</ol>
|
||||
|
||||
<p>There are some exceptions to the deletion rule above:</p>
|
||||
|
||||
<ul>
|
||||
<li>global resources are never deleted</li>
|
||||
<li>external resources are never deleted</li>
|
||||
<li>if the WAR or DIR has been modified then the XML file is only deleted if
|
||||
<em>copyXML</em> is <code>true</code> and <em>deployXML</em> is
|
||||
<code>true</code></li>
|
||||
</ul>
|
||||
|
||||
<p>In the following table:</p>
|
||||
|
||||
<ul>
|
||||
<li>'-' means "unchanged from not present". i.e. the artifact wasn't present
|
||||
before the change and isn't present after it either. '-' rather than 'N'
|
||||
is used to focus attention on what changes.</li>
|
||||
<li>'R' means that the directory is re-created by expanding the WAR file.
|
||||
This will only happen if <em>unpackWARs</em> is <code>true</code>.</li>
|
||||
<li>'XW' means that the if the WAR contains a META-INF/context.xml file it
|
||||
will be extracted and placed in the Host's <em>configBase</em>.
|
||||
This only happens if <em>copyXML</em> is <code>true</code> and
|
||||
<em>deployXML</em> is <code>true</code>.</li>
|
||||
<li>'XD' means that the if the directory contains a META-INF/context.xml
|
||||
file it will be copied to the Host's <em>configBase</em>. This only
|
||||
happens if <em>copyXML</em> is <code>true</code> and <em>deployXML</em>
|
||||
is <code>true</code>.</li>
|
||||
</ul>
|
||||
|
||||
<table class="detail-table">
|
||||
<tr>
|
||||
<th colspan="3">Artifacts present</th>
|
||||
<th rowspan="2">Artifact removed</th>
|
||||
<th colspan="4">Artifacts remaining</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>XML</th><th>WAR</th><th>DIR</th>
|
||||
<th>XML</th><th>WAR</th><th>DIR</th><th>Notes</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>N</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>-</td><td>-</td><td>N</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>Y</td><td>N</td>
|
||||
<td>WAR</td>
|
||||
<td>-</td><td>N</td><td>-</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>Y</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>-</td><td>Y</td><td>R</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>Y</td><td>Y</td>
|
||||
<td>WAR</td>
|
||||
<td>-</td><td>N</td><td>N</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>N</td>
|
||||
<td>XML</td>
|
||||
<td>N</td><td>-</td><td>-</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>N</td><td>-</td><td>N</td><td>5</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y</td>
|
||||
<td>XML</td>
|
||||
<td>XD</td><td>-</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>N</td>
|
||||
<td>WAR</td>
|
||||
<td>N</td><td>N</td><td>-</td><td>5</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>N</td>
|
||||
<td>XML</td>
|
||||
<td>XW</td><td>Y</td><td>-</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>XW</td><td>Y</td><td>R</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>Y</td>
|
||||
<td>WAR</td>
|
||||
<td>N</td><td>N</td><td>N</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>Y</td>
|
||||
<td>XML</td>
|
||||
<td>XW</td><td>Y</td><td>Y</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y (external)</td><td>N</td>
|
||||
<td>WAR</td>
|
||||
<td>Y</td><td>N</td><td>-</td><td>3</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y (external)</td><td>N</td>
|
||||
<td>XML</td>
|
||||
<td>N</td><td>Y (external)</td><td>-</td><td>6</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y (external)</td>
|
||||
<td>DIR</td>
|
||||
<td>Y</td><td>-</td><td>N</td><td>3</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y (external)</td>
|
||||
<td>XML</td>
|
||||
<td>N</td><td>-</td><td>Y (external)</td><td>6</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y (external)</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>Y</td><td>Y (external)</td><td>R</td><td></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y (external)</td><td>Y</td>
|
||||
<td>WAR</td>
|
||||
<td>Y</td><td>N</td><td>N</td><td>3</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y (external)</td><td>Y</td>
|
||||
<td>XML</td>
|
||||
<td>N</td><td>Y (external)</td><td>N</td><td>6</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div><h3 id="Modified_files">Modified files</h3><div class="text">
|
||||
|
||||
<p>This section describes Tomcat's behaviour when the automatic
|
||||
deployment process detects that a web application file has been modified.</p>
|
||||
|
||||
<p>In the following table:</p>
|
||||
|
||||
<ul>
|
||||
<li>'-' means "unchanged from not present". i.e. the artifact wasn't present
|
||||
before the change and isn't present after it either. '-' rather than 'N'
|
||||
is used to focus attention on what changes.</li>
|
||||
<li>'M' means that the artifact has been modified.</li>
|
||||
<li>'R' means that the directory is deleted and re-created by expanding the
|
||||
WAR file. This will only happen if <em>unpackWARs</em> is
|
||||
<code>true</code>.</li>
|
||||
</ul>
|
||||
|
||||
<table class="detail-table">
|
||||
<tr>
|
||||
<th colspan="3">Artifacts present</th>
|
||||
<th rowspan="2">Artifact modified</th>
|
||||
<th colspan="4">Artifacts remaining</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<th>XML</th><th>WAR</th><th>DIR</th>
|
||||
<th>XML</th><th>WAR</th><th>DIR</th><th>Action</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>N</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>-</td><td>-</td><td>M</td><td>None</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>Y</td><td>N</td>
|
||||
<td>WAR</td>
|
||||
<td>-</td><td>M</td><td>-</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>Y</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>-</td><td>Y</td><td>M</td><td>None</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>N</td><td>Y</td><td>Y</td>
|
||||
<td>WAR</td>
|
||||
<td>-</td><td>M</td><td>R</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>N</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>-</td><td>-</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>Y</td><td>-</td><td>M</td><td>None</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>-</td><td>Y</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>N</td>
|
||||
<td>WAR</td>
|
||||
<td>Y</td><td>M</td><td>-</td><td>Reload</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>N</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>Y</td><td>-</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>Y</td><td>Y</td><td>M</td><td>None</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>Y</td>
|
||||
<td>WAR</td>
|
||||
<td>Y</td><td>M</td><td>R</td><td>Reload</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y</td><td>Y</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>Y</td><td>Y</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y(external)</td><td>N</td>
|
||||
<td>WAR</td>
|
||||
<td>Y</td><td>M(external)</td><td>-</td><td>Reload</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y(external)</td><td>N</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>Y(external)</td><td>-</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y(external)</td>
|
||||
<td>DIR</td>
|
||||
<td>Y</td><td>-</td><td>M(external)</td><td>None</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>N</td><td>Y(external)</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>-</td><td>Y(external)</td><td>Redeploy</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y(external)</td><td>Y</td>
|
||||
<td>DIR</td>
|
||||
<td>Y</td><td>Y(external)</td><td>M</td><td>None</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y(external)</td><td>Y</td>
|
||||
<td>WAR</td>
|
||||
<td>Y</td><td>M(external)</td><td>R</td><td>Reload</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Y</td><td>Y(external)</td><td>Y</td>
|
||||
<td>XML</td>
|
||||
<td>M</td><td>Y(external)</td><td>Y</td><td>Redeploy</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
</div><h3 id="Added_files">Added files</h3><div class="text">
|
||||
|
||||
<p>This is treated as if the added file has been modified with the following
|
||||
additional actions:</p>
|
||||
|
||||
<ul>
|
||||
<li>If a WAR is added, any DIR is removed and may be recreated depending on
|
||||
<em>unpackWARs</em>.</li>
|
||||
<li>If an XML file is added that refers to an external <em>docBase</em> any
|
||||
WAR or DIR in the appBase will be removed. The DIR may be recreated if
|
||||
the external resource is a WAR and <em>unpackWARs</em> is true.</li>
|
||||
<li>If a DIR is added when a WAR already exists and <em>unpackWARs</em> is
|
||||
<code>false</code>, the DIR will be ignored but a warning will be
|
||||
logged when the DIR is first detected. If the WAR is removed, the DIR
|
||||
will be left and may be deployed via automatic deployment.</li>
|
||||
<li>If a WAR is added to the <em>appBase</em> when an external WAR already
|
||||
exists, the WAR in the <em>appBase</em> will be ignored but a warning
|
||||
will be logged when the WAR in the <em>appBase</em> is first detected.
|
||||
If the external WAR is removed, the WAR in the <em>appBase</em> will be
|
||||
left and may be deployed via automatic deployment.</li>
|
||||
<li>If an XML file is added to the META-INF directory of an application
|
||||
deployed from that DIR, the application will always be redeployed. The
|
||||
result will be the same as for a new deployment.</li>
|
||||
</ul>
|
||||
|
||||
</div><h3 id="Notes">Notes</h3><div class="text">
|
||||
|
||||
<ol>
|
||||
<li><em>deployXML</em> and <em>copyXML</em> are ignored since an XML file
|
||||
was discovered in the <em>configBase</em>.</li>
|
||||
<li><em>unpackWARs</em> is ignored since there is no WAR file.</li>
|
||||
<li>The context will fail to start because there is no content in the
|
||||
expected <em>docBase</em>.</li>
|
||||
<li>The web application fails to deploy because it contains an embedded
|
||||
META-INF/context.xml, <em>deployXML</em> is <code>false</code> and an
|
||||
XML has not been provided in the <em>configBase</em>.</li>
|
||||
<li>The XML file is only deleted if <em>copyXML</em> is <code>true</code>
|
||||
and <em>deployXML</em> is <code>true</code>.</li>
|
||||
<li>Although the external resource is still present, the web application is
|
||||
fully undeployed as Tomcat has no knowledge of the external resource.
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
98
tomcat/webapps.dist/docs/config/cluster-channel.html
Normal file
98
tomcat/webapps.dist/docs/config/cluster-channel.html
Normal file
@@ -0,0 +1,98 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster Channel object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster Channel object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.GroupChannel_Attributes">org.apache.catalina.tribes.group.GroupChannel Attributes</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
The cluster channel is the main component of a small framework we've nicknamed Apache Tribes.<br>
|
||||
The channel manages a set of sub components and together they create a group communication framework.<br>
|
||||
This framework is then used internally by the components that need to send messages between different Tomcat instances.
|
||||
<br>
|
||||
A few examples of these components would be the SimpleTcpCluster that does the messaging for the DeltaManager,
|
||||
or the BackupManager that uses a different replication strategy. The ReplicatedContext object does also
|
||||
use the channel object to communicate context attribute changes.
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
<p><b><a href="cluster-membership.html">Channel/Membership</a>:</b> <br>
|
||||
The Membership component is responsible for auto discovering new nodes in the cluster
|
||||
and also to provide for notifications for any nodes that have not responded with a heartbeat.
|
||||
The default implementation uses multicast.<br>
|
||||
In the membership component you configure how your nodes, aka. members, are to be discovered and/or
|
||||
divided up.
|
||||
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
|
||||
</p>
|
||||
<p><b><a href="cluster-sender.html">Channel/Sender</a>:</b> <br>
|
||||
The Sender component manages all outbound connections and data messages that are sent
|
||||
over the network from one node to another.
|
||||
This component allows messages to be sent in parallel.
|
||||
The default implementation uses TCP client sockets, and socket tuning for outgoing messages are
|
||||
configured here.<br>
|
||||
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
|
||||
</p>
|
||||
<p><b><a href="cluster-sender.html#transport">Channel/Sender/Transport</a>:</b> <br>
|
||||
The Transport component is the bottom IO layer for the sender component.
|
||||
The default implementation uses non-blocking TCP client sockets.<br>
|
||||
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
|
||||
</p>
|
||||
<p><b><a href="cluster-receiver.html">Channel/Receiver</a>:</b> <br>
|
||||
The receiver component listens for messages from other nodes.
|
||||
Here you will configure the cluster thread pool, as it will dispatch incoming
|
||||
messages to a thread pool for faster processing.
|
||||
The default implementation uses non-blocking TCP server sockets.<br>
|
||||
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
|
||||
</p>
|
||||
<p><b><a href="cluster-interceptor.html">Channel/Interceptor</a>:</b> <br>
|
||||
The channel will send messages through an interceptor stack. Because of this, you have the ability to
|
||||
customize the way messages are sent and received, and even how membership is handled.<br>
|
||||
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
|
||||
</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
The default value here is <code>org.apache.catalina.tribes.group.GroupChannel</code> and is
|
||||
currently the only implementation available.
|
||||
</td></tr></table>
|
||||
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.GroupChannel_Attributes">org.apache.catalina.tribes.group.GroupChannel Attributes</h4><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">heartbeat</code></td><td>
|
||||
Flag whether the channel manages its own heartbeat.
|
||||
If set to true, the channel start a local thread for the heart beat.
|
||||
If set this flag to false, you must set SimpleTcpCluster#heartbeatBackgroundEnabled
|
||||
to true. default value is true.
|
||||
</td></tr><tr><td><code class="attributeName">heartbeatSleeptime</code></td><td>
|
||||
If heartbeat == true, specifies the interval of heartbeat thread in milliseconds.
|
||||
The default is 5000 (5 seconds).
|
||||
</td></tr><tr><td><code class="attributeName">optionCheck</code></td><td>
|
||||
If set to true, the GroupChannel will check the option flags that each
|
||||
interceptor is using. Reports an error if two interceptor share the same
|
||||
flag. The default is false.
|
||||
</td></tr><tr><td><code class="attributeName">jmxEnabled</code></td><td>
|
||||
Flag whether the channel components register with JMX or not.
|
||||
The default value is true.
|
||||
</td></tr><tr><td><code class="attributeName">jmxDomain</code></td><td>
|
||||
if <code>jmxEnabled</code> set to true, specifies the jmx domain which
|
||||
this channel should be registered. The ClusterChannel is used as the
|
||||
default value.
|
||||
</td></tr><tr><td><code class="attributeName">jmxPrefix</code></td><td>
|
||||
if <code>jmxEnabled</code> set to true, specifies the jmx prefix which
|
||||
will be used with channel ObjectName.
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
69
tomcat/webapps.dist/docs/config/cluster-deployer.html
Normal file
69
tomcat/webapps.dist/docs/config/cluster-deployer.html
Normal file
@@ -0,0 +1,69 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster Deployer object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster Deployer object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#org.apache.catalina.ha.deploy.FarmWarDeployer">org.apache.catalina.ha.deploy.FarmWarDeployer</a><ol><li><a href="#Attributes">Attributes</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>The Farm War Deployer can deploy and undeploy web applications on the other
|
||||
nodes in the cluster.</p>
|
||||
<p><strong>Note:</strong> FarmWarDeployer can be configured at host level
|
||||
cluster only.
|
||||
</p>
|
||||
</div><h3 id="org.apache.catalina.ha.deploy.FarmWarDeployer">org.apache.catalina.ha.deploy.FarmWarDeployer</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Attributes">Attributes</h4><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
The cluster deployer class, currently only one is available,
|
||||
<code>org.apache.catalina.ha.deploy.FarmWarDeployer.</code>
|
||||
</td></tr><tr><td><strong><code class="attributeName">deployDir</code></strong></td><td>
|
||||
Deployment directory. This is the pathname of a directory where deploy
|
||||
the web applications. You may specify an absolute pathname, or a
|
||||
pathname that is relative to the $CATALINA_BASE directory. In the
|
||||
current implementation, this attribute must be the same value as the
|
||||
<strong>Host's appBase</strong>.
|
||||
</td></tr><tr><td><strong><code class="attributeName">tempDir</code></strong></td><td>
|
||||
The temporaryDirectory to store binary data when downloading a war from
|
||||
the cluster. You may specify an absolute pathname, or a pathname that is
|
||||
relative to the $CATALINA_BASE directory.
|
||||
</td></tr><tr><td><code class="attributeName">watchDir</code></td><td>
|
||||
This is the pathname of a directory where watch for changes(add/modify/remove)
|
||||
of web applications. You may specify an absolute pathname, or a pathname
|
||||
that is relative to the $CATALINA_BASE directory.
|
||||
<strong>Note: </strong> if <strong>watchEnabled</strong> is false, this
|
||||
attribute will have no effect.
|
||||
</td></tr><tr><td><code class="attributeName">watchEnabled</code></td><td>
|
||||
Set to true if you want to watch for changes of web applications.
|
||||
Only when this attribute set to true, you can trigger a deploy/undeploy
|
||||
of web applications. The flag's value defaults to false.
|
||||
</td></tr><tr><td><code class="attributeName">processDeployFrequency</code></td><td>
|
||||
Frequency of the Farm watchDir check. Cluster wide deployment will be
|
||||
done once for the specified amount of backgroundProcess calls (ie, the
|
||||
lower the amount, the most often the checks will occur). The minimum
|
||||
value is 1, and the default value is 2.
|
||||
<strong>Note: </strong> if <strong>watchEnabled</strong> is false, this
|
||||
attribute will have no effect.
|
||||
</td></tr><tr><td><code class="attributeName">maxValidTime</code></td><td>
|
||||
FileMessageFactory instances used by the FarmWarDeployer are only
|
||||
retained while they are required. When receiving a WAR file, the
|
||||
associated FileMessageFactory instance is deleted once the WAR file has
|
||||
been fully received. To avoid memory leaks under various error
|
||||
conditions (part of the file never received, very slow message transfer,
|
||||
etc.), this attribute defines the maximum time permitted between
|
||||
receiving valid messages that contain part of the WAR file. If that
|
||||
maximum time is exceeded, the FileMessageFactory will be deleted and the
|
||||
WAR file transfer will fail for that node. If a negative value is
|
||||
specified, the FileMessageFactory will only be removed once the WAR file
|
||||
is fully received. If not specified, the default value of 300 (5
|
||||
minutes) will be used.
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
275
tomcat/webapps.dist/docs/config/cluster-interceptor.html
Normal file
275
tomcat/webapps.dist/docs/config/cluster-interceptor.html
Normal file
@@ -0,0 +1,275 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Channel Interceptor object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Channel Interceptor object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Available_Interceptors">Available Interceptors</a></li><li><a href="#Static_Membership">Static Membership</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes">org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes</a></li><li><a href="#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a><ol><li><a href="#StaticMember_Attributes">StaticMember Attributes</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
Apache Tribes supports an interceptor architecture to intercept both messages and membership notifications.
|
||||
This architecture allows decoupling of logic and opens the way for some very useful feature add-ons.
|
||||
</p>
|
||||
</div><h3 id="Available_Interceptors">Available Interceptors</h3><div class="text">
|
||||
<ul>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.NonBlockingCoordinator</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.OrderInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.SimpleCoordinator</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.TwoPhaseCommitInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.GzipInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor</code></li>
|
||||
<li><code>org.apache.catalina.tribes.group.interceptors.EncryptInterceptor</code></li>
|
||||
</ul>
|
||||
</div><h3 id="Static_Membership">Static Membership</h3><div class="text">
|
||||
<p>
|
||||
In addition to dynamic discovery, Apache Tribes also supports static membership, with membership verification.
|
||||
To achieve this add the <code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code>
|
||||
after the <code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code> interceptor.
|
||||
Inside the <code>StaticMembershipInterceptor</code> you can add the static members you wish to have.
|
||||
The <code>TcpFailureDetector</code> will do a health check on the static members,and also monitor them for crashes
|
||||
so they will have the same level of notification mechanism as the members that are automatically discovered.</p>
|
||||
<div class="codeBox"><pre><code> <Interceptor className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor">
|
||||
<LocalMember className="org.apache.catalina.tribes.membership.StaticMember"
|
||||
domain="staging-cluster"
|
||||
uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/>
|
||||
<Member className="org.apache.catalina.tribes.membership.StaticMember"
|
||||
port="5678"
|
||||
securePort="-1"
|
||||
host="tomcat01.mydomain.com"
|
||||
domain="staging-cluster"
|
||||
uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
|
||||
</Interceptor></code></pre></div>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Required, as there is no default
|
||||
</td></tr><tr><td><code class="attributeName">optionFlag</code></td><td>
|
||||
If you want the interceptor to trigger on certain message depending on the message's option flag,
|
||||
you can setup the interceptors flag here.
|
||||
The default value is <code>0</code>, meaning this interceptor will trigger on all messages.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">domain</code></strong></td><td>
|
||||
The logical cluster domain that this Interceptor accepts.
|
||||
Two different type of values are possible:<br>
|
||||
1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
|
||||
using ISO-8859-1 encoding.<br>
|
||||
2. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><code class="attributeName">logInterval</code></td><td>
|
||||
This value indicates the interval for logging for messages from different domains.
|
||||
The default is 100, which means that to log per 100 messages.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">expire</code></td><td>
|
||||
How long do we keep the fragments in memory and wait for the rest to arrive.
|
||||
The default is 60000 ms.
|
||||
</td></tr><tr><td><code class="attributeName">maxSize</code></td><td>
|
||||
The maximum message size in bytes. If the message size exceeds this value, this interceptor fragments the message and sends them.
|
||||
If it is less than this value, this interceptor does not fragment the message and sent in as one message. The default is 1024*100.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">optionFlag</code></td><td>
|
||||
The default and hard coded value is <code>8 (org.apache.catalina.tribes.Channel.SEND_OPTIONS_ASYNCHRONOUS)</code>.
|
||||
The dispatcher will trigger on this value only, as it is predefined by Tribes.
|
||||
</td></tr><tr><td><code class="attributeName">alwaysSend</code></td><td>
|
||||
What behavior should be executed when the dispatch queue is full. If <code>true</code> (default), then the message is
|
||||
is sent synchronously, if <code>false</code> an error is thrown.
|
||||
</td></tr><tr><td><code class="attributeName">maxQueueSize</code></td><td>
|
||||
Size in bytes of the dispatch queue, the default value is <code> 1024*1024*64 (64MB)</code> sets the maximum queue size for the dispatch queue
|
||||
if the queue fills up, one can trigger the behavior, if <code>alwaysSend</code> is set to true, the message will be sent synchronously
|
||||
if the flag is false, an error is thrown
|
||||
</td></tr><tr><td><code class="attributeName">maxThreads</code></td><td>
|
||||
The maximum number of threads in this pool, default is 10.
|
||||
</td></tr><tr><td><code class="attributeName">maxSpareThreads</code></td><td>
|
||||
The number of threads to keep in the pool, default is 2.
|
||||
</td></tr><tr><td><code class="attributeName">keepAliveTime</code></td><td>
|
||||
Maximum number of milliseconds of until Idle thread terminates. Default value is 5000(5 seconds).
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes">org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">connectTimeout</code></td><td>
|
||||
Specifies the timeout, in milliseconds, to use when attempting a TCP connection
|
||||
to the suspect node. Default is 1000.
|
||||
</td></tr><tr><td><code class="attributeName">performSendTest</code></td><td>
|
||||
If true is set, send a test message to the suspect node. Default is true.
|
||||
</td></tr><tr><td><code class="attributeName">performReadTest</code></td><td>
|
||||
If true is set, read the response of the test message that sent. Default is false.
|
||||
<strong>Note:</strong> if <code>performSendTest</code> is false, this attribute will have no effect.
|
||||
</td></tr><tr><td><code class="attributeName">readTestTimeout</code></td><td>
|
||||
Specifies the timeout, in milliseconds, to use when performing a read test
|
||||
to the suspicious node. Default is 5000.
|
||||
</td></tr><tr><td><code class="attributeName">removeSuspectsTimeout</code></td><td>
|
||||
The maximum time(in seconds) for remove from removeSuspects. Member of
|
||||
removeSuspects will be automatically removed after removeSuspectsTimeout.
|
||||
If a negative value specified, the removeSuspects members never be
|
||||
removed until disappeared really. If the attribute is not provided,
|
||||
a default of 300 seconds (5 minutes) is used.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">interval</code></td><td>
|
||||
If useThread == true, defines the interval of sending a ping message.
|
||||
default is 1000 ms.
|
||||
</td></tr><tr><td><code class="attributeName">useThread</code></td><td>
|
||||
Flag of whether to start a thread for sending a ping message.
|
||||
If set to true, this interceptor will start a local thread for sending a ping message.
|
||||
if set to false, channel heartbeat will send a ping message.
|
||||
default is false.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">interval</code></td><td>
|
||||
Defines the interval in number of messages when we are to report the throughput statistics.
|
||||
The report is logged to the <code>org.apache.juli.logging.LogFactory.getLog(ThroughputInterceptor.class)</code>
|
||||
logger under the <code>INFO</code> level.
|
||||
Default value is to report every <code>10000</code> messages.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes</h4><div class="text">
|
||||
<p>
|
||||
The EncryptInterceptor adds encryption to the channel messages carrying
|
||||
session data between nodes. Added in Tomcat 9.0.13.
|
||||
</p>
|
||||
<p>
|
||||
If using the <code>TcpFailureDetector</code>, the <code>EncryptInterceptor</code>
|
||||
<i>must</i> be inserted into the interceptor chain <i>before</i> the
|
||||
<code>TcpFailureDetector</code>. This is because when validating cluster
|
||||
members, <code>TcpFailureDetector</code> writes channel data directly
|
||||
to the other members without using the remainder of the interceptor chain,
|
||||
but on the receiving side, the message still goes through the chain (in reverse).
|
||||
Because of this asymmetry, the <code>EncryptInterceptor</code> must execute
|
||||
<i>before</i> the <code>TcpFailureDetector</code> on the sender and <i>after</i>
|
||||
it on the receiver, otherwise message corruption will occur.
|
||||
</p>
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">encryptionAlgorithm</code></td><td>
|
||||
The encryption algorithm to be used, including the mode and padding. Please see
|
||||
<a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html">https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html</a>
|
||||
for the standard JCA names that can be used.
|
||||
|
||||
EncryptInterceptor currently supports the following
|
||||
<a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation">block-cipher modes</a>:
|
||||
CBC, OFB, CFB, and GCM.
|
||||
|
||||
The length of the key will specify the flavor of the encryption algorithm
|
||||
to be used, if applicable (e.g. AES-128 versus AES-256).
|
||||
|
||||
The default algorithm is <code>AES/CBC/PKCS5Padding</code>.
|
||||
</td></tr><tr><td><strong><code class="attributeName">encryptionKey</code></strong></td><td>
|
||||
The key to be used with the encryption algorithm.
|
||||
|
||||
The key should be specified as hex-encoded bytes of the appropriate
|
||||
length for the algorithm (e.g. 16 bytes / 32 characters / 128 bits for
|
||||
AES-128, 32 bytes / 64 characters / 256 bits for AES-256, etc.).
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="StaticMember_Attributes">StaticMember Attributes</h4><div class="text">
|
||||
<p><b>LocalMember:</b> <br>
|
||||
Static member that is the local member of the static cluster group.
|
||||
</p>
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
|
||||
</td></tr><tr><td><code class="attributeName">port</code></td><td>
|
||||
There is no need to set.
|
||||
The value of this attribute inherits from the cluster receiver setting.
|
||||
</td></tr><tr><td><code class="attributeName">securePort</code></td><td>
|
||||
There is no need to set.
|
||||
The value of this attribute inherits from the cluster receiver setting.
|
||||
</td></tr><tr><td><code class="attributeName">host</code></td><td>
|
||||
There is no need to set.
|
||||
The value of this attribute inherits from the cluster receiver setting.
|
||||
</td></tr><tr><td><code class="attributeName">domain</code></td><td>
|
||||
The logical cluster domain for that this static member listens for cluster messages.
|
||||
Two different type of values are possible:<br>
|
||||
1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
|
||||
using ISO-8859-1 encoding.
|
||||
2. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><strong><code class="attributeName">uniqueId</code></strong></td><td>
|
||||
A universally uniqueId for this static member.
|
||||
The values must be 16 bytes in the following form:<br>
|
||||
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br>
|
||||
</td></tr></table>
|
||||
|
||||
<p><b>Member:</b> <br>
|
||||
Static member that add to the static cluster group.
|
||||
</p>
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
|
||||
</td></tr><tr><td><strong><code class="attributeName">port</code></strong></td><td>
|
||||
The port that this static member listens to for cluster messages
|
||||
</td></tr><tr><td><code class="attributeName">securePort</code></td><td>
|
||||
The secure port this static member listens to for encrypted cluster messages
|
||||
default value is <code>-1</code>, this value means the member is not listening on a secure port
|
||||
</td></tr><tr><td><strong><code class="attributeName">host</code></strong></td><td>
|
||||
The host (or network interface) that this static member listens for cluster messages.
|
||||
Three different type of values are possible:<br>
|
||||
1. IP address in the form of "216.123.1.23"<br>
|
||||
2. Hostnames like "tomcat01.mydomain.com" or "tomcat01" as long as they resolve correctly<br>
|
||||
3. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><code class="attributeName">domain</code></td><td>
|
||||
The logical cluster domain for that this static member listens for cluster messages.
|
||||
Two different type of values are possible:<br>
|
||||
1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
|
||||
using ISO-8859-1 encoding.<br>
|
||||
2. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><strong><code class="attributeName">uniqueId</code></strong></td><td>
|
||||
A universally uniqueId for this static member.
|
||||
The values must be 16 bytes in the following form:<br>
|
||||
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
30
tomcat/webapps.dist/docs/config/cluster-listener.html
Normal file
30
tomcat/webapps.dist/docs/config/cluster-listener.html
Normal file
@@ -0,0 +1,30 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The ClusterListener object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 ClusterListener object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#org.apache.catalina.ha.session.ClusterSessionListener">org.apache.catalina.ha.session.ClusterSessionListener</a></li><li><a href="#Attributes">Attributes</a></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
The <code>org.apache.catalina.ha.ClusterListener</code> base class
|
||||
lets you listen in on messages that are received by the <code>Cluster</code> component.
|
||||
</p>
|
||||
|
||||
</div><h3 id="org.apache.catalina.ha.session.ClusterSessionListener">org.apache.catalina.ha.session.ClusterSessionListener</h3><div class="text">
|
||||
<p>
|
||||
When using the DeltaManager, the messages are received by the Cluster object and are propagated to the
|
||||
to the manager through this listener.
|
||||
</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Set value to <code>org.apache.catalina.ha.session.ClusterSessionListener</code>
|
||||
</td></tr></table>
|
||||
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
269
tomcat/webapps.dist/docs/config/cluster-manager.html
Normal file
269
tomcat/webapps.dist/docs/config/cluster-manager.html
Normal file
@@ -0,0 +1,269 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The ClusterManager object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 ClusterManager object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#The_<Manager>">The <Manager></a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#org.apache.catalina.ha.session.DeltaManager_Attributes">org.apache.catalina.ha.session.DeltaManager Attributes</a></li><li><a href="#org.apache.catalina.ha.session.BackupManager_Attributes">org.apache.catalina.ha.session.BackupManager Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>A cluster manager is an extension to Tomcat's session manager interface,
|
||||
<code>org.apache.catalina.Manager</code>.
|
||||
A cluster manager must implement the
|
||||
<code>org.apache.catalina.ha.ClusterManager</code> and is solely responsible
|
||||
for how the session is replicated.<br>
|
||||
There are currently two different managers, the
|
||||
<code>org.apache.catalina.ha.session.DeltaManager</code> replicates deltas of
|
||||
session data to all members in the cluster. This implementation is proven and
|
||||
works very well, but has a limitation as it requires the cluster members to be
|
||||
homogeneous, all nodes must deploy the same applications and be exact
|
||||
replicas. The <code>org.apache.catalina.ha.session.BackupManager</code> also
|
||||
replicates deltas but only to one backup node. The location of the backup node
|
||||
is known to all nodes in the cluster. It also supports heterogeneous
|
||||
deployments, so the manager knows at what locations the web application is
|
||||
deployed.</p>
|
||||
</div><h3 id="The_<Manager>">The <Manager></h3><div class="text">
|
||||
<p>The <code><Manager></code> element defined inside the
|
||||
<code><Cluster></code> element is the template defined for all web
|
||||
applications that are marked <code><distributable/></code> in their
|
||||
<code>web.xml</code> file. However, you can still override the manager
|
||||
implementation on a per web application basis, by putting the
|
||||
<code><Manager></code> inside the <code><Context></code> element
|
||||
either in the <code><a href="context.html">context.xml</a></code> file or the
|
||||
<code><a href="index.html">server.xml</a></code> file.</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
</td></tr><tr><td><code class="attributeName">name</code></td><td>
|
||||
<b>The name of this cluster manager, the name is used to identify a
|
||||
session manager on a node. The name might get modified by the
|
||||
<code>Cluster</code> element to make it unique in the container.</b>
|
||||
</td></tr><tr><td><code class="attributeName">notifyListenersOnReplication</code></td><td>
|
||||
Set to <code>true</code> if you wish to have session listeners notified
|
||||
when session attributes are being replicated or removed across Tomcat
|
||||
nodes in the cluster.
|
||||
</td></tr><tr><td><code class="attributeName">processExpiresFrequency</code></td><td>
|
||||
<p>Frequency of the session expiration, and related manager operations.
|
||||
Manager operations will be done once for the specified amount of
|
||||
backgroundProcess calls (i.e., the lower the amount, the more often the
|
||||
checks will occur). The minimum value is 1, and the default value is 6.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomClass</code></td><td>
|
||||
<p>Name of the Java class that extends
|
||||
<code>java.security.SecureRandom</code> to use to generate session IDs.
|
||||
If not specified, the default value is
|
||||
<code>java.security.SecureRandom</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomProvider</code></td><td>
|
||||
<p>Name of the provider to use to create the
|
||||
<code>java.security.SecureRandom</code> instances that generate session
|
||||
IDs. If an invalid algorithm and/or provider is specified, the Manager
|
||||
will use the platform default provider and the default algorithm. If not
|
||||
specified, the platform default provider will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomAlgorithm</code></td><td>
|
||||
<p>Name of the algorithm to use to create the
|
||||
<code>java.security.SecureRandom</code> instances that generate session
|
||||
IDs. If an invalid algorithm and/or provider is specified, the Manager
|
||||
will use the platform default provider and the default algorithm. If not
|
||||
specified, the default algorithm of SHA1PRNG will be used. If the
|
||||
default algorithm is not supported, the platform default will be used.
|
||||
To specify that the platform default should be used, do not set the
|
||||
secureRandomProvider attribute and set this attribute to the empty
|
||||
string.</p>
|
||||
</td></tr><tr><td><code class="attributeName">recordAllActions</code></td><td>
|
||||
<p>Flag whether send all actions for session across Tomcat cluster
|
||||
nodes. If set to false, if already done something to the same attribute,
|
||||
make sure don't send multiple actions across Tomcat cluster nodes.
|
||||
In that case, sends only the actions that have been added at last.
|
||||
Default is <code>false</code>.</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.ha.session.DeltaManager_Attributes">org.apache.catalina.ha.session.DeltaManager Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">expireSessionsOnShutdown</code></td><td>
|
||||
When a web application is being shutdown, Tomcat issues an expire call
|
||||
to each session to notify all the listeners. If you wish for all
|
||||
sessions to expire on all nodes when a shutdown occurs on one node, set
|
||||
this value to <code>true</code>.
|
||||
Default value is <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">maxActiveSessions</code></td><td>
|
||||
The maximum number of active sessions that will be created by this
|
||||
Manager, or -1 (the default) for no limit. For this manager, all
|
||||
sessions are counted as active sessions irrespective if whether or not
|
||||
the current node is the primary node for the session.
|
||||
</td></tr><tr><td><code class="attributeName">notifySessionListenersOnReplication</code></td><td>
|
||||
Set to <code>true</code> if you wish to have session listeners notified
|
||||
when sessions are created and expired across Tomcat nodes in the
|
||||
cluster.
|
||||
</td></tr><tr><td><code class="attributeName">notifyContainerListenersOnReplication</code></td><td>
|
||||
Set to <code>true</code> if you wish to have container listeners notified
|
||||
across Tomcat nodes in the cluster.
|
||||
</td></tr><tr><td><code class="attributeName">persistAuthenticationNotes</code></td><td>
|
||||
<p>Should authentication notes (used during FORM authentication) be
|
||||
included when sessions are replicated? If <code>true</code>, the
|
||||
session's authentication notes (used during FORM authentication) are
|
||||
replicated so that an in progress FORM authentication can continue if
|
||||
failover occurs during FORM authentication. If not specified, the
|
||||
default value of <code>false</code> will be used.</p>
|
||||
|
||||
<p>Please note that all nodes must be upgraded to at least 9.0.66 (the
|
||||
version where this feature was introduced) before this feature is
|
||||
enabled else session replication may fail.</p>
|
||||
|
||||
<p>This attribute has been removed for Tomcat 10.1.x onwards which
|
||||
always replicates FORM authenticaton notes.</p>
|
||||
</td></tr><tr><td><code class="attributeName">stateTransferTimeout</code></td><td>
|
||||
The time in seconds to wait for a session state transfer to complete
|
||||
from another node when a node is starting up.
|
||||
Default value is <code>60</code> seconds.
|
||||
</td></tr><tr><td><code class="attributeName">sendAllSessions</code></td><td>
|
||||
Flag whether send sessions as split blocks.
|
||||
If set to <code>true</code>, send all sessions as one big block.
|
||||
If set to <code>false</code>, send sessions as split blocks.
|
||||
Default value is <code>true</code>.
|
||||
</td></tr><tr><td><code class="attributeName">sendAllSessionsSize</code></td><td>
|
||||
The number of sessions in a session block message. This value is
|
||||
effective only when <code>sendAllSessions</code> is <code>false</code>.
|
||||
Default is <code>1000</code>.
|
||||
</td></tr><tr><td><code class="attributeName">sendAllSessionsWaitTime</code></td><td>
|
||||
Wait time between sending of session block messages. This value is
|
||||
effective only when <code>sendAllSessions</code> is <code>false</code>.
|
||||
Default is <code>2000</code> milliseconds.
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
replicated. An attribute will only be replicated if its name matches
|
||||
this pattern. If the pattern is zero length or <code>null</code>, all
|
||||
attributes are eligible for replication. The pattern is anchored so the
|
||||
session attribute name must fully match the pattern. As an example, the
|
||||
value <code>(userName|sessionHistory)</code> will only replicate the
|
||||
two session attributes named <code>userName</code> and
|
||||
<code>sessionHistory</code>. If not specified, the default value of
|
||||
<code>null</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
replicated. An attribute will only be replicated if the implementation
|
||||
class name of the value matches this pattern. If the pattern is zero
|
||||
length or <code>null</code>, all attributes are eligible for
|
||||
replication. The pattern is anchored so the fully qualified class name
|
||||
must fully match the pattern. If not specified, the default value of
|
||||
<code>null</code> will be used unless a <code>SecurityManager</code> is
|
||||
enabled in which case the default will be
|
||||
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">stateTimestampDrop</code></td><td>
|
||||
When this node sends a <code>GET_ALL_SESSIONS</code> message to other
|
||||
node, all session messages that are received as a response are queued.
|
||||
If this attribute is set to <code>true</code>, the received session
|
||||
messages (except any <code>GET_ALL_SESSIONS</code> sent by other nodes)
|
||||
are filtered by their timestamp. A message is dropped if it is not a
|
||||
<code>GET_ALL_SESSIONS</code> message and its timestamp is earlier than
|
||||
the timestamp of our <code>GET_ALL_SESSIONS</code> message.
|
||||
If set to <code>false</code>, all queued session messages are handled.
|
||||
Default is <code>true</code>.
|
||||
</td></tr><tr><td><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td>
|
||||
<p>If <strong>sessionAttributeNameFilter</strong> or
|
||||
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
|
||||
attribute, should this be logged at <code>WARN</code> level? If
|
||||
<code>WARN</code> level logging is disabled then it will be logged at
|
||||
<code>DEBUG</code>. The default value of this attribute is
|
||||
<code>false</code> unless a <code>SecurityManager</code> is enabled in
|
||||
which case the default will be <code>true</code>.</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="org.apache.catalina.ha.session.BackupManager_Attributes">org.apache.catalina.ha.session.BackupManager Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">mapSendOptions</code></td><td>
|
||||
The backup manager uses a replicated map, this map is sending and
|
||||
receiving messages. You can setup the flag for how this map is sending
|
||||
messages, the default value is <code>6</code>(synchronous).<br>
|
||||
Note that if you use asynchronous messaging it is possible for update
|
||||
messages for a session to be processed by the receiving node in a
|
||||
different order to the order in which they were sent.
|
||||
</td></tr><tr><td><code class="attributeName">maxActiveSessions</code></td><td>
|
||||
The maximum number of active sessions that will be created by this
|
||||
Manager, or -1 (the default) for no limit. For this manager, only
|
||||
sessions where the current node is the primary node for the session are
|
||||
considered active sessions.
|
||||
</td></tr><tr><td><code class="attributeName">persistAuthenticationNotes</code></td><td>
|
||||
<p>Should authentication notes (used during FORM authentication) be
|
||||
included when sessions are replicated? If <code>true</code>, the
|
||||
session's authentication notes (used during FORM authentication) are
|
||||
replicated so that an in progress FORM authentication can continue if
|
||||
failover occurs during FORM authentication. If not specified, the
|
||||
default value of <code>false</code> will be used.</p>
|
||||
|
||||
<p>Please note that all nodes must be upgraded to at least 9.0.66 (the
|
||||
version where this feature was introduced) before this feature is
|
||||
enabled else session replication may fail.</p>
|
||||
|
||||
<p>This attribute has been removed for Tomcat 10.1.x onwards which
|
||||
always replicates FORM authenticaton notes.</p>
|
||||
</td></tr><tr><td><code class="attributeName">rpcTimeout</code></td><td>
|
||||
Timeout for RPC message used for broadcast and transfer state from
|
||||
another map.
|
||||
Default value is <code>15000</code> milliseconds.
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
replicated. An attribute will only be replicated if its name matches
|
||||
this pattern. If the pattern is zero length or <code>null</code>, all
|
||||
attributes are eligible for replication. The pattern is anchored so the
|
||||
session attribute name must fully match the pattern. As an example, the
|
||||
value <code>(userName|sessionHistory)</code> will only replicate the
|
||||
two session attributes named <code>userName</code> and
|
||||
<code>sessionHistory</code>. If not specified, the default value of
|
||||
<code>null</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
replicated. An attribute will only be replicated if the implementation
|
||||
class name of the value matches this pattern. If the pattern is zero
|
||||
length or <code>null</code>, all attributes are eligible for
|
||||
replication. The pattern is anchored so the fully qualified class name
|
||||
must fully match the pattern. If not specified, the default value of
|
||||
<code>null</code> will be used unless a <code>SecurityManager</code> is
|
||||
enabled in which case the default will be
|
||||
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">terminateOnStartFailure</code></td><td>
|
||||
Set to true if you wish to terminate replication map when replication
|
||||
map fails to start. If replication map is terminated, associated context
|
||||
will fail to start. If you set this attribute to false, replication map
|
||||
does not end. It will try to join the map membership in the heartbeat.
|
||||
Default value is <code>false</code> .
|
||||
</td></tr><tr><td><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td>
|
||||
<p>If <strong>sessionAttributeNameFilter</strong> or
|
||||
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
|
||||
attribute, should this be logged at <code>WARN</code> level? If
|
||||
<code>WARN</code> level logging is disabled then it will be logged at
|
||||
<code>DEBUG</code>. The default value of this attribute is
|
||||
<code>false</code> unless a <code>SecurityManager</code> is enabled in
|
||||
which case the default will be <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">accessTimeout</code></td><td>
|
||||
The timeout for a ping message. If a remote map does not respond within
|
||||
this timeout period, its regarded as disappeared.
|
||||
Default value is <code>5000</code> milliseconds.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
<h3>All Manager Implementations</h3>
|
||||
<p>All Manager implementations allow nesting of a
|
||||
<strong><SessionIdGenerator></strong> element. It defines
|
||||
the behavior of session id generation. All implementations
|
||||
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
|
||||
following attributes:
|
||||
</p>
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">sessionIdLength</code></td><td>
|
||||
<p>The length of the session ID may be changed with the
|
||||
<strong>sessionIdLength</strong> attribute.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
276
tomcat/webapps.dist/docs/config/cluster-membership.html
Normal file
276
tomcat/webapps.dist/docs/config/cluster-membership.html
Normal file
@@ -0,0 +1,276 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster Membership object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster Membership object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Default_Implementation">Default Implementation</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#Multicast_Attributes">Multicast Attributes</a></li><li><a href="#Static_Membership_Attributes">Static Membership Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a><ol><li><a href="#StaticMember_Attributes">StaticMember Attributes</a></li><li><a href="#Setting">Setting</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
The membership component in the Apache Tribes <a href="cluster-channel.html">Channel</a> is responsible
|
||||
for dynamic discovery of other members(nodes) in the cluster.
|
||||
There are currently two different membership service, the <code>org.apache.catalina.tribes.membership.McastService</code>
|
||||
and the <code>org.apache.catalina.tribes.membership.StaticMembershipService</code>.
|
||||
The <code>McastService</code> builds a multicast based membership service
|
||||
that sends UDP packets to multicast IP addresses.
|
||||
The <code>StaticMembershipService</code> builds a unicast based membership
|
||||
service that sends TCP packets to predefined member address.
|
||||
</p>
|
||||
</div><h3 id="Default_Implementation">Default Implementation</h3><div class="text">
|
||||
<p>
|
||||
The default implementation of the cluster group notification is built on top of multicast heartbeats
|
||||
sent using UDP packets to a multicast IP address.
|
||||
Cluster members are grouped together by using the same multicast address/port combination.
|
||||
Each member sends out a heartbeat with a given interval (<code>frequency</code>), and this
|
||||
heartbeat is used for dynamic discovery.
|
||||
In a similar fashion, if a heartbeat has not been received in a timeframe specified by <code>dropTime</code>
|
||||
ms. a member is considered suspect and the channel and any membership listener will be notified.
|
||||
</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>
|
||||
The implementation of the membership component.
|
||||
Two implementations available, <code>org.apache.catalina.tribes.membership.McastService</code>
|
||||
and <code>org.apache.catalina.tribes.membership.StaticMembershipService</code>.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="Multicast_Attributes">Multicast Attributes</h4><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>
|
||||
The value is <code>org.apache.catalina.tribes.membership.McastService</code>.
|
||||
This implementation uses multicast heartbeats for member discovery.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">address</code></td><td>
|
||||
<p>
|
||||
The multicast address that the membership will broadcast its presence and listen
|
||||
for other heartbeats on. The default value is <code>228.0.0.4</code>
|
||||
Make sure your network is enabled for multicast traffic.<br>
|
||||
The multicast address, in conjunction with the <code>port</code> is what
|
||||
creates a cluster group. To divide up your farm into several different group, or to
|
||||
split up QA from production, change the <code>port</code> or the <code>address</code>
|
||||
<br>Previously known as mcastAddr.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">port</code></td><td>
|
||||
<p>
|
||||
The multicast port, the default value is <code>45564</code><br>
|
||||
The multicast port, in conjunction with the <code>address</code> is what
|
||||
creates a cluster group. To divide up your farm into several different group, or to
|
||||
split up QA from production, change the <code>port</code> or the <code>address</code>
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">frequency</code></td><td>
|
||||
<p>
|
||||
The frequency in milliseconds in which heartbeats are sent out. The default value is <code>500</code> ms.<br>
|
||||
In most cases the default value is sufficient. Changing this value, simply changes the interval in between heartbeats.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">dropTime</code></td><td>
|
||||
<p>
|
||||
The membership component will time out members and notify the Channel if a member fails to send a heartbeat within
|
||||
a give time. The default value is <code>3000</code> ms. This means, that if a heartbeat is not received from a
|
||||
member in that timeframe, the membership component will notify the cluster of this.<br>
|
||||
On a high latency network you may wish to increase this value, to protect against false positives.<br>
|
||||
Apache Tribes also provides a <a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes"><code>TcpFailureDetector</code></a> that will
|
||||
verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">bind</code></td><td>
|
||||
<p>
|
||||
Use this attribute if you wish to bind your multicast traffic to a specific network interface.
|
||||
By default, or when this attribute is unset, it tries to bind to <code>0.0.0.0</code> and sometimes on multihomed hosts
|
||||
this becomes a problem.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">ttl</code></td><td>
|
||||
<p>
|
||||
The time-to-live setting for the multicast heartbeats.
|
||||
This setting should be a value between 0 and 255. The default value is VM implementation specific.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">domain</code></td><td>
|
||||
<p>
|
||||
Apache Tribes has the ability to logically group members into domains, by using this domain attribute.
|
||||
The <code>org.apache.catalina.tribes.Member.getDomain()</code> method returns the value specified here.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">soTimeout</code></td><td>
|
||||
<p>
|
||||
The sending and receiving of heartbeats is done on a single thread, hence to avoid blocking this thread forever,
|
||||
you can control the <code>SO_TIMEOUT</code> value on this socket.<br>
|
||||
If a value smaller or equal to 0 is presented, the code will default this value to frequency
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">recoveryEnabled</code></td><td>
|
||||
<p>
|
||||
In case of a network failure, Java multicast socket don't transparently fail over, instead the socket will continuously
|
||||
throw IOException upon each receive request. When recoveryEnabled is set to true, this will close the multicast socket
|
||||
and open a new socket with the same properties as defined above.<br>
|
||||
The default is <code>true</code>. <br>
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">recoveryCounter</code></td><td>
|
||||
<p>
|
||||
When <code>recoveryEnabled==true</code> this value indicates how many
|
||||
times an error has to occur before recovery is attempted. The default is
|
||||
<code>10</code>. <br>
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">recoverySleepTime</code></td><td>
|
||||
<p>
|
||||
When <code>recoveryEnabled==true</code> this value indicates how long time (in milliseconds)
|
||||
the system will sleep in between recovery attempts, until it recovers successfully.
|
||||
The default is <code>5000</code> (5 seconds). <br>
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">localLoopbackDisabled</code></td><td>
|
||||
<p>
|
||||
Membership uses multicast, it will call <code>java.net.MulticastSocket.setLoopbackMode(localLoopbackDisabled)</code>.
|
||||
When <code>localLoopbackDisabled==true</code> multicast messages will not reach other nodes on the same local machine.
|
||||
The default is <code>false</code>. <br>
|
||||
</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Static_Membership_Attributes">Static Membership Attributes</h4><div class="text">
|
||||
|
||||
<p>When using the static membership service you must ensure that the
|
||||
<code>channelStartOptions</code> attribute of the <code>Cluster</code>
|
||||
element is set to the default value of <code>15</code>.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>
|
||||
The value is <code>org.apache.catalina.tribes.membership.StaticMembershipService</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">connectTimeout</code></td><td>
|
||||
<p>
|
||||
Timeout for attempting a TCP connection to address of predefined static member.
|
||||
Default is <code>500</code> ms.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">expirationTime</code></td><td>
|
||||
<p>
|
||||
If members have failed to update their alive time within the given time,
|
||||
this membership will notify the memberDisappeared event to cluster.
|
||||
Default is <code>5000</code> ms.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">rpcTimeout</code></td><td>
|
||||
<p>
|
||||
Timeout for messages that used for member notification to/from othee nodes.
|
||||
Default is <code>3000</code> ms.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">useThread</code></td><td>
|
||||
<p>
|
||||
If set to true, this membership service will start a local thread for
|
||||
sending a ping message. if set to <code>false</code>, channel heartbeat
|
||||
will send a ping message. Default is <code>false</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">pingInterval</code></td><td>
|
||||
<p>
|
||||
If <code>useThread</code> == <code>true</code>, defines the interval of
|
||||
sending a ping message. Default is <code>1000</code> ms.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
<p>
|
||||
Static Membership Service allows nesting of a <strong><LocalMember></strong>
|
||||
and <strong><Member></strong> element.
|
||||
</p>
|
||||
<div class="subsection"><h4 id="StaticMember_Attributes">StaticMember Attributes</h4><div class="text">
|
||||
<p><b>LocalMember:</b> <br>
|
||||
Static member that is the local member of the static cluster group.
|
||||
</p>
|
||||
<p><strong>Note:</strong> In Tomcat 9.0.17 and later, The setting of local member is not required.
|
||||
It is possible to set up a list of all cluster members including local member instead of setting this components.
|
||||
</p>
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
|
||||
</td></tr><tr><td><code class="attributeName">port</code></td><td>
|
||||
There is no need to set.
|
||||
The value of this attribute inherits from the cluster receiver setting.
|
||||
</td></tr><tr><td><code class="attributeName">securePort</code></td><td>
|
||||
There is no need to set.
|
||||
The value of this attribute inherits from the cluster receiver setting.
|
||||
</td></tr><tr><td><code class="attributeName">host</code></td><td>
|
||||
There is no need to set.
|
||||
The value of this attribute inherits from the cluster receiver setting.
|
||||
</td></tr><tr><td><code class="attributeName">domain</code></td><td>
|
||||
The logical cluster domain for that this static member listens for cluster messages.
|
||||
Two different type of values are possible:<br>
|
||||
1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
|
||||
using ISO-8859-1 encoding.
|
||||
2. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><strong><code class="attributeName">uniqueId</code></strong></td><td>
|
||||
A universally uniqueId for this static member.
|
||||
The values must be 16 bytes in the following form:<br>
|
||||
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br>
|
||||
</td></tr></table>
|
||||
|
||||
<p><b>Member:</b> <br>
|
||||
Static member that add to the static cluster group.
|
||||
</p>
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
|
||||
</td></tr><tr><td><strong><code class="attributeName">port</code></strong></td><td>
|
||||
The port that this static member listens to for cluster messages
|
||||
</td></tr><tr><td><code class="attributeName">securePort</code></td><td>
|
||||
The secure port this static member listens to for encrypted cluster messages
|
||||
default value is <code>-1</code>, this value means the member is not listening on a secure port
|
||||
</td></tr><tr><td><strong><code class="attributeName">host</code></strong></td><td>
|
||||
The host (or network interface) that this static member listens for cluster messages.
|
||||
Three different type of values are possible:<br>
|
||||
1. IP address in the form of "216.123.1.23"<br>
|
||||
2. Hostnames like "tomcat01.mydomain.com" or "tomcat01" as long as they resolve correctly<br>
|
||||
3. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><code class="attributeName">domain</code></td><td>
|
||||
The logical cluster domain for that this static member listens for cluster messages.
|
||||
Two different type of values are possible:<br>
|
||||
1. Regular string values like "staging-domain" or "tomcat-cluster" will be converted into bytes
|
||||
using ISO-8859-1 encoding.<br>
|
||||
2. byte array in string form, for example {216,123,12,3}<br>
|
||||
</td></tr><tr><td><strong><code class="attributeName">uniqueId</code></strong></td><td>
|
||||
A universally uniqueId for this static member.
|
||||
The values must be 16 bytes in the following form:<br>
|
||||
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Setting">Setting</h4><div class="text">
|
||||
<p><b>Before Tomcat 9.0.16</b> <br>
|
||||
<div class="codeBox"><pre><code> <Membership className="org.apache.catalina.tribes.membership.StaticMembershipService">
|
||||
<LocalMember className="org.apache.catalina.tribes.membership.StaticMember"
|
||||
uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
|
||||
<Member className="org.apache.catalina.tribes.membership.StaticMember"
|
||||
port="4004"
|
||||
host="tomcat02.mydomain.com"
|
||||
uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/>
|
||||
</Membership></code></pre></div>
|
||||
</p>
|
||||
<p><b>Tomcat9.0.17 and later</b> <br>
|
||||
<div class="codeBox"><pre><code> <Membership className="org.apache.catalina.tribes.membership.StaticMembershipService">
|
||||
<Member className="org.apache.catalina.tribes.membership.StaticMember"
|
||||
port="4004"
|
||||
host="tomcat01.mydomain.com"
|
||||
uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
|
||||
<Member className="org.apache.catalina.tribes.membership.StaticMember"
|
||||
port="4004"
|
||||
host="tomcat02.mydomain.com"
|
||||
uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/>
|
||||
</Membership></code></pre></div>
|
||||
</p>
|
||||
</div></div>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
117
tomcat/webapps.dist/docs/config/cluster-receiver.html
Normal file
117
tomcat/webapps.dist/docs/config/cluster-receiver.html
Normal file
@@ -0,0 +1,117 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster Receiver object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster Receiver object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Blocking_vs_Non-Blocking_Receiver">Blocking vs Non-Blocking Receiver</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li><li><a href="#NioReceiver">NioReceiver</a></li><li><a href="#BioReceiver">BioReceiver</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
The receiver component is responsible for receiving cluster messages.
|
||||
As you might notice through the configuration, is that the receiving of messages
|
||||
and sending of messages are two different components, this is different from many other
|
||||
frameworks, but there is a good reason for it, to decouple the logic for how messages are sent from
|
||||
how messages are received.<br>
|
||||
The receiver is very much like the Tomcat Connector, its the base of the thread pool
|
||||
for incoming cluster messages. The receiver is straight forward, but all the socket settings
|
||||
for incoming traffic are managed here.
|
||||
</p>
|
||||
</div><h3 id="Blocking_vs_Non-Blocking_Receiver">Blocking vs Non-Blocking Receiver</h3><div class="text">
|
||||
<p>
|
||||
The receiver supports both a non blocking, <code>org.apache.catalina.tribes.transport.nio.NioReceiver</code>, and a
|
||||
blocking, <code>org.apache.catalina.tribes.transport.bio.BioReceiver</code>. It is preferred to use the non blocking receiver
|
||||
to be able to grow your cluster without running into thread starvation.<br>
|
||||
Using the non blocking receiver allows you to with a very limited thread count to serve a large number of messages.
|
||||
Usually the rule is to use 1 thread per node in the cluster for small clusters, and then depending on your message frequency
|
||||
and your hardware, you'll find an optimal number of threads peak out at a certain number.
|
||||
</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
The implementation of the receiver component. Two implementations available,
|
||||
<code>org.apache.catalina.tribes.transport.nio.NioReceiver</code> and
|
||||
<code>org.apache.catalina.tribes.transport.bio.BioReceiver</code>.<br>
|
||||
The <code>org.apache.catalina.tribes.transport.nio.NioReceiver</code> is the
|
||||
preferred implementation
|
||||
</td></tr><tr><td><code class="attributeName">address</code></td><td>
|
||||
The address (network interface) to listen for incoming traffic.
|
||||
Same as the bind address. The default value is <code>auto</code> and translates to
|
||||
<code>java.net.InetAddress.getLocalHost().getHostAddress()</code>.
|
||||
</td></tr><tr><td><code class="attributeName">direct</code></td><td>
|
||||
Possible values are <code>true</code> or <code>false</code>.
|
||||
Set to true if you want the receiver to use direct bytebuffers when reading data
|
||||
from the sockets.
|
||||
</td></tr><tr><td><code class="attributeName">port</code></td><td>
|
||||
The listen port for incoming data. The default value is <code>4000</code>.
|
||||
To avoid port conflicts the receiver will automatically bind to a free port within the range of
|
||||
<code> port <= bindPort < port+autoBind</code>
|
||||
So for example, if port is 4000, and autoBind is set to 10, then the receiver will open up
|
||||
a server socket on the first available port in the range 4000-4009.
|
||||
</td></tr><tr><td><code class="attributeName">autoBind</code></td><td>
|
||||
Default value is <code>100</code>.
|
||||
Use this value if you wish to automatically avoid port conflicts the cluster receiver will try to open a
|
||||
server socket on the <code>port</code> attribute port, and then work up <code>autoBind</code> number of times.
|
||||
</td></tr><tr><td><code class="attributeName">securePort</code></td><td>
|
||||
The secure listen port. This port is SSL enabled. If this attribute is omitted no SSL port is opened up.
|
||||
There default value is unset, meaning there is no SSL socket available.
|
||||
</td></tr><tr><td><code class="attributeName">udpPort</code></td><td>
|
||||
The UDP listen port. If this attribute is omitted no UDP port is opened up.
|
||||
There default value is unset, meaning there is no UDP listener available.
|
||||
</td></tr><tr><td><code class="attributeName">selectorTimeout</code></td><td>
|
||||
The value in milliseconds for the polling timeout in the <code>NioReceiver</code>. On older versions of the JDK
|
||||
there have been bugs, that should all now be cleared out where the selector never woke up.
|
||||
The default value is a very high <code>5000</code> milliseconds.
|
||||
</td></tr><tr><td><code class="attributeName">maxThreads</code></td><td>
|
||||
The maximum number of threads in the receiver thread pool. The default value is <code>15</code>
|
||||
Adjust this value relative to the number of nodes in the cluster, the number of messages being exchanged and
|
||||
the hardware you are running on. A higher value doesn't mean more efficiency, tune this value according to your
|
||||
own test results.
|
||||
</td></tr><tr><td><code class="attributeName">minThreads</code></td><td>
|
||||
Minimum number of threads to be created when the receiver is started up. Default value is <code>6</code>
|
||||
</td></tr><tr><td><code class="attributeName">maxIdleTime</code></td><td>
|
||||
Maximum number of milliseconds of until Idle thread terminates. Default value is <code>60000</code> milliseconds.
|
||||
</td></tr><tr><td><code class="attributeName">ooBInline</code></td><td>
|
||||
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">rxBufSize</code></td><td>
|
||||
The receiver buffer size on the receiving sockets. Value is in bytes, the default value is <code>65536</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">txBufSize</code></td><td>
|
||||
The sending buffer size on the receiving sockets. Value is in bytes, the default value is <code>25188</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">udpRxBufSize</code></td><td>
|
||||
The receive buffer size on the datagram socket.
|
||||
Default value is <code>25188</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">udpTxBufSize</code></td><td>
|
||||
The send buffer size on the datagram socket.
|
||||
Default value is <code>65536</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">soKeepAlive</code></td><td>
|
||||
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">soLingerOn</code></td><td>
|
||||
Boolean value to determine whether to use the SO_LINGER socket option.
|
||||
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
|
||||
</td></tr><tr><td><code class="attributeName">soLingerTime</code></td><td>
|
||||
Sets the SO_LINGER socket option time value. The value is in seconds.
|
||||
The default value is <code>3</code> seconds.
|
||||
</td></tr><tr><td><code class="attributeName">soReuseAddress</code></td><td>
|
||||
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">tcpNoDelay</code></td><td>
|
||||
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
|
||||
The default value is <code>true</code>
|
||||
</td></tr><tr><td><code class="attributeName">timeout</code></td><td>
|
||||
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
|
||||
milliseconds.
|
||||
</td></tr><tr><td><code class="attributeName">useBufferPool</code></td><td>
|
||||
Boolean value whether to use a shared buffer pool of cached <code>org.apache.catalina.tribes.io.XByteBuffer</code>
|
||||
objects. If set to true, the XByteBuffer that is used to pass a message up the channel, will be recycled at the end
|
||||
of the requests. This means that interceptors in the channel must not maintain a reference to the object
|
||||
after the <code>org.apache.catalina.tribes.ChannelInterceptor#messageReceived</code> method has exited.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="NioReceiver">NioReceiver</h4><div class="text">
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="BioReceiver">BioReceiver</h4><div class="text">
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
133
tomcat/webapps.dist/docs/config/cluster-sender.html
Normal file
133
tomcat/webapps.dist/docs/config/cluster-sender.html
Normal file
@@ -0,0 +1,133 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster Sender object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster Sender object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Concurrent_Parallel_Delivery">Concurrent Parallel Delivery</a></li><li><a href="#Nested_Elements">Nested Elements</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Sender_Attributes">Common Sender Attributes</a></li><li><a href="#Common_Transport_Attributes">Common Transport Attributes</a></li><li><a href="#Common_PooledSender_Attributes">Common PooledSender Attributes</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
The channel sender component is responsible for delivering outgoing cluster messages over the network.
|
||||
In the default implementation, <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>,
|
||||
the sender is a fairly empty shell with not much logic around a fairly complex <code><Transport></code>
|
||||
component the implements the actual delivery mechanism.
|
||||
</p>
|
||||
</div><h3 id="Concurrent_Parallel_Delivery">Concurrent Parallel Delivery</h3><div class="text">
|
||||
<p>
|
||||
In the default <code>transport</code> implementation, <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>,
|
||||
Apache Tribes implements what we like to call "Concurrent Parallel Delivery".
|
||||
This means that we can send a message to more than one destination at the same time(parallel), and
|
||||
deliver two messages to the same destination at the same time(concurrent). Combine these two and we have
|
||||
"Concurrent Parallel Delivery".
|
||||
</p>
|
||||
<p>
|
||||
When is this useful? The simplest example we can think of is when part of your code is sending a 10MB message,
|
||||
like a war file being deployed, and you need to push through a small 10KB message, say a session being replicated,
|
||||
you don't have to wait for the 10MB message to finish, as a separate thread will push in the small message
|
||||
transmission at the same time. Currently there is no interrupt, pause or priority mechanism available, but check back soon.
|
||||
</p>
|
||||
</div><h3 id="Nested_Elements">Nested Elements</h3><div class="text">
|
||||
<p>
|
||||
The nested element <code><Transport></code> is not required, but encouraged, as this is where
|
||||
you would set all the socket options for the outgoing messages. Please see its attributes below.
|
||||
There are two implementations, in a similar manner to the <a href="cluster-receiver.html">receiver</a>, one is non-blocking
|
||||
based and the other is built using blocking IO. <br>
|
||||
<code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code> is the blocking implementation and
|
||||
<code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>.
|
||||
Parallel delivery is not available for the blocking implementation due to the fact that it is blocking a thread on sending data.
|
||||
</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
<div class="subsection"><h4 id="Common_Sender_Attributes">Common Sender Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Required, only available implementation is <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="Common_Transport_Attributes">Common Transport Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Required, an implementation of the <code>org.apache.catalina.tribes.transport.MultiPointSender</code>.<br>
|
||||
Non-blocking implementation is <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code><br>
|
||||
Blocking implementation is <code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code>
|
||||
</td></tr><tr><td><code class="attributeName">rxBufSize</code></td><td>
|
||||
The receive buffer size on the socket.
|
||||
Default value is <code>25188</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">txBufSize</code></td><td>
|
||||
The send buffer size on the socket.
|
||||
Default value is <code>65536</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">udpRxBufSize</code></td><td>
|
||||
The receive buffer size on the datagram socket.
|
||||
Default value is <code>25188</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">udpTxBufSize</code></td><td>
|
||||
The send buffer size on the datagram socket.
|
||||
Default value is <code>65536</code> bytes.
|
||||
</td></tr><tr><td><code class="attributeName">directBuffer</code></td><td>
|
||||
Possible values are <code>true</code> or <code>false</code>.
|
||||
Set to true if you want the receiver to use direct bytebuffers when writing data
|
||||
to the sockets. Default value is <code>false</code>
|
||||
</td></tr><tr><td><code class="attributeName">keepAliveCount</code></td><td>
|
||||
The number of requests that can go through the socket before the socket is closed, and reopened
|
||||
for the next request. The default value is <code>-1</code>, which is unlimited.
|
||||
</td></tr><tr><td><code class="attributeName">keepAliveTime</code></td><td>
|
||||
The number of milliseconds a connection is kept open after its been opened.
|
||||
The default value is <code>-1</code>, which is unlimited.
|
||||
</td></tr><tr><td><code class="attributeName">timeout</code></td><td>
|
||||
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
|
||||
milliseconds.(3 seconds) This timeout starts when a message send attempt is starting, until the transfer has been completed.
|
||||
For the NIO sockets, this will mean, that the caller can guarantee that we will not attempt sending the message
|
||||
longer than this timeout value. For the blocking IO implementation, this translated directly to the soTimeout.<br>
|
||||
A timeout will not spawn a retry attempt, in order to guarantee the return of the application thread.
|
||||
</td></tr><tr><td><code class="attributeName">maxRetryAttempts</code></td><td>
|
||||
How many times do we retry a failed message, that received a IOException at the socket level.
|
||||
The default value is <code>1</code>, meaning we will retry a message that has failed once.
|
||||
In other words, we will attempt a message send no more than twice. One is the original send, and one is the
|
||||
<code>maxRetryAttempts</code>.
|
||||
</td></tr><tr><td><code class="attributeName">ooBInline</code></td><td>
|
||||
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">soKeepAlive</code></td><td>
|
||||
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">soLingerOn</code></td><td>
|
||||
Boolean value to determine whether to use the SO_LINGER socket option.
|
||||
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
|
||||
</td></tr><tr><td><code class="attributeName">soLingerTime</code></td><td>
|
||||
Sets the SO_LINGER socket option time value. The value is in seconds.
|
||||
The default value is <code>3</code> seconds.
|
||||
</td></tr><tr><td><code class="attributeName">soReuseAddress</code></td><td>
|
||||
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
|
||||
</td></tr><tr><td><code class="attributeName">soTrafficClass</code></td><td>
|
||||
Sets the traffic class level for the socket, the value is between 0 and 255.
|
||||
Default value is <code>int soTrafficClass = 0x04 | 0x08 | 0x010;</code>
|
||||
Different values are defined in <a href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html#setTrafficClass(int)">
|
||||
java.net.Socket#setTrafficClass(int)</a>.
|
||||
</td></tr><tr><td><code class="attributeName">tcpNoDelay</code></td><td>
|
||||
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
|
||||
The default value is <code>true</code>
|
||||
</td></tr><tr><td><code class="attributeName">throwOnFailedAck</code></td><td>
|
||||
Boolean value, default value is <code>true</code>.
|
||||
If set to true, the sender will throw a <code>org.apache.catalina.tribes.RemoteProcessException</code>
|
||||
when we receive a negative ack from the remote member.
|
||||
Set to false, and Tribes will treat a positive ack the same way as a negative ack, that the message was received.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
<div class="subsection"><h4 id="Common_PooledSender_Attributes">Common PooledSender Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">poolSize</code></td><td>
|
||||
The maximum number of concurrent connections from A to B.
|
||||
The value is based on a per-destination count.
|
||||
The default value is <code>25</code>
|
||||
</td></tr><tr><td><code class="attributeName">maxWait</code></td><td>
|
||||
The maximum number of milliseconds that the senderPool will wait when
|
||||
there are no available senders. The default value is <code>3000</code>
|
||||
milliseconds.(3 seconds).
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
128
tomcat/webapps.dist/docs/config/cluster-valve.html
Normal file
128
tomcat/webapps.dist/docs/config/cluster-valve.html
Normal file
@@ -0,0 +1,128 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster Valve object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster Valve object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#org.apache.catalina.ha.tcp.ReplicationValve">org.apache.catalina.ha.tcp.ReplicationValve</a><ol><li><a href="#org.apache.catalina.ha.tcp.ReplicationValve/Attributes">Attributes</a></li></ol></li><li><a href="#org.apache.catalina.ha.session.JvmRouteBinderValve">org.apache.catalina.ha.session.JvmRouteBinderValve</a><ol><li><a href="#org.apache.catalina.ha.session.JvmRouteBinderValve/Attributes">Attributes</a></li></ol></li><li><a href="#org.apache.catalina.ha.authenticator.ClusterSingleSignOn">org.apache.catalina.ha.authenticator.ClusterSingleSignOn</a><ol><li><a href="#org.apache.catalina.ha.authenticator.ClusterSingleSignOn/Attributes">Attributes</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
A cluster valve is no different from any other <a href="valve.html">Tomcat <code>Valve</code></a>.
|
||||
The cluster valves are interceptors in the invocation chain for HTTP requests, and the clustering implementation
|
||||
uses these valves to make intelligent decision around data and when data should be replicated.
|
||||
</p>
|
||||
<p>
|
||||
A cluster valve must implement the <code>org.apache.catalina.ha.ClusterValve</code> interface.
|
||||
This is a simple interface that extends the <code>org.apache.catalina.Valve</code> interface.
|
||||
</p>
|
||||
</div><h3 id="org.apache.catalina.ha.tcp.ReplicationValve">org.apache.catalina.ha.tcp.ReplicationValve</h3><div class="text">
|
||||
The <code>ReplicationValve</code> will notify the cluster at the end of an HTTP request
|
||||
so that the cluster can make a decision whether there is data to be replicated or not.
|
||||
<div class="subsection"><h4 id="org.apache.catalina.ha.tcp.ReplicationValve/Attributes">Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
Set value to <code>org.apache.catalina.ha.tcp.ReplicationValve</code>
|
||||
</td></tr><tr><td><code class="attributeName">filter</code></td><td>
|
||||
For known file extensions or urls, you can use this Valve to notify the
|
||||
cluster that the session has not been modified during this request and
|
||||
the cluster doesn't have to probe the session managers for changes. If
|
||||
the request matches this filter pattern, the cluster assumes there has
|
||||
been no session change. An example filter would look like <code>
|
||||
filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"
|
||||
</code>. The filter is a regular expression using
|
||||
<code>java.util.regex</code>. If no filter pattern specified or if the
|
||||
filter pattern is configured to be the empty string, no filtering will
|
||||
take place.
|
||||
</td></tr><tr><td><code class="attributeName">primaryIndicator</code></td><td>
|
||||
Boolean value, so to true, and the replication valve will insert a request attribute with the name
|
||||
defined by the <code>primaryIndicatorName</code> attribute.
|
||||
The value inserted into the request attribute is either <code>Boolean.TRUE</code> or
|
||||
<code>Boolean.FALSE</code>
|
||||
</td></tr><tr><td><code class="attributeName">primaryIndicatorName</code></td><td>
|
||||
Default value is <code>org.apache.catalina.ha.tcp.isPrimarySession</code>
|
||||
The value defined here is the name of the request attribute that contains the boolean value
|
||||
if the session is primary on this server or not.
|
||||
</td></tr><tr><td><code class="attributeName">statistics</code></td><td>
|
||||
Boolean value. Set to <code>true</code> if you want the valve to collect request statistics.
|
||||
Default value is <code>false</code>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div><h3 id="org.apache.catalina.ha.session.JvmRouteBinderValve">org.apache.catalina.ha.session.JvmRouteBinderValve</h3><div class="text">
|
||||
In case of a mod_jk failover, the <code>JvmRouteBinderValve</code> will replace the
|
||||
<code>jvmWorker</code> attribute in the session Id, to make future requests stick to this
|
||||
node. If you want fallback capability, don't enable this valve, but if you want your failover to stick,
|
||||
and for mod_jk not to have to keep probing the node that went down, you use this valve.
|
||||
<div class="subsection"><h4 id="org.apache.catalina.ha.session.JvmRouteBinderValve/Attributes">Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<code>org.apache.catalina.ha.session.JvmRouteBinderValve</code>
|
||||
</td></tr><tr><td><code class="attributeName">enabled</code></td><td>
|
||||
Default value is <code>true</code>
|
||||
Runtime attribute to turn on and off turn over of the session's jvmRoute value.
|
||||
</td></tr><tr><td><code class="attributeName">sessionIdAttribute</code></td><td>
|
||||
Old sessionid before failover is registered in request attributes with this attribute.
|
||||
Default attribute name is <code>org.apache.catalina.ha.session.JvmRouteOriginalSessionID</code>.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div><h3 id="org.apache.catalina.ha.authenticator.ClusterSingleSignOn">org.apache.catalina.ha.authenticator.ClusterSingleSignOn</h3><div class="text">
|
||||
The <code>ClusterSingleSignOn</code> supports feature of single sign on in cluster.
|
||||
By using <code>ClusterSingleSignOn</code>, the security identity authenticated
|
||||
by one web application is recognized by other web applications on the same virtual host,
|
||||
and it is propagated to other nodes in the cluster.
|
||||
|
||||
<p>See the <a href="host.html#Single_Sign_On">Single Sign On</a> special
|
||||
feature on the <strong>Host</strong> element for more information.</p>
|
||||
|
||||
<p><strong>Note:</strong> ClusterSingleSignOn can be configured at host level cluster only.
|
||||
</p>
|
||||
|
||||
<div class="subsection"><h4 id="org.apache.catalina.ha.authenticator.ClusterSingleSignOn/Attributes">Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This MUST be set to
|
||||
<strong>org.apache.catalina.ha.authenticator.ClusterSingleSignOn</strong>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">cookieDomain</code></td><td>
|
||||
<p>Sets the host domain to be used for sso cookies.</p>
|
||||
</td></tr><tr><td><code class="attributeName">mapSendOptions</code></td><td>
|
||||
<p>The Valve uses a replicated map. You can setup the flag for how this
|
||||
map sends messages. The default value is <code>6</code> (synchronous).
|
||||
Note that if you use asynchronous messaging it is possible for update
|
||||
messages to be processed by the receiving node in a different order to
|
||||
the order in which they were sent.</p>
|
||||
</td></tr><tr><td><code class="attributeName">requireReauthentication</code></td><td>
|
||||
<p>Default false. Flag to determine whether each request needs to be
|
||||
reauthenticated to the security <strong>Realm</strong>. If "true", this
|
||||
Valve uses cached security credentials (username and password) to
|
||||
reauthenticate to the <strong>Realm</strong> each request associated
|
||||
with an SSO session. If "false", the Valve can itself authenticate
|
||||
requests based on the presence of a valid SSO cookie, without
|
||||
rechecking with the <strong>Realm</strong>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">rpcTimeout</code></td><td>
|
||||
<p>The Valve uses a replicated map. This is the timeout for messages
|
||||
that transfer state to/from the other nodes in the cluster. If not
|
||||
specified, a default value of <code>15000</code> milliseconds is used.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">terminateOnStartFailure</code></td><td>
|
||||
<p>Set to <code>true</code> if you wish this Valve to fail if the
|
||||
underlying replication fails to start. If the Valve fails, then the
|
||||
associated container will fail to start. If you set this attribute to
|
||||
false, and the underlying replications fails to start, the Valve will
|
||||
start and it will attempt to join the cluster and start replication as
|
||||
part of the heartbeat process. If not specified, the default value of
|
||||
<code>false</code> is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">accessTimeout</code></td><td>
|
||||
The timeout for a ping message. If a remote map does not respond within
|
||||
this timeout period, its regarded as disappeared.
|
||||
Default value is <code>5000</code> milliseconds.
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
174
tomcat/webapps.dist/docs/config/cluster.html
Normal file
174
tomcat/webapps.dist/docs/config/cluster.html
Normal file
@@ -0,0 +1,174 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cluster object</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cluster object</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Security">Security</a></li><li><a href="#Engine_vs_Host_placement">Engine vs Host placement</a></li><li><a href="#Context_Attribute_Replication">Context Attribute Replication</a></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#SimpleTcpCluster_Attributes">SimpleTcpCluster Attributes</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>
|
||||
The tomcat cluster implementation provides session replication, context attribute replication and
|
||||
cluster wide WAR file deployment.
|
||||
While the <code>Cluster</code> configuration is fairly complex, the default configuration will work
|
||||
for most people out of the box. </p><p>
|
||||
The Tomcat Cluster implementation is very extensible, and hence we have exposed a myriad of options,
|
||||
making the configuration seem like a lot, but don't lose faith, instead you have a tremendous control
|
||||
over what is going on.</p>
|
||||
</div><h3 id="Security">Security</h3><div class="text">
|
||||
|
||||
<p>The cluster implementation is written on the basis that a secure, trusted
|
||||
network is used for all of the cluster related network traffic. It is not safe
|
||||
to run a cluster on a insecure, untrusted network.</p>
|
||||
|
||||
<p>There are many options for providing a secure, trusted network for use by a
|
||||
Tomcat cluster. These include:</p>
|
||||
<ul>
|
||||
<li>private LAN</li>
|
||||
<li>a Virtual Private Network (VPN)</li>
|
||||
<li>IPSEC</li>
|
||||
</ul>
|
||||
|
||||
<p>The <a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a>
|
||||
provides confidentiality and integrity protection but it does not protect
|
||||
against all risks associated with running a Tomcat cluster on an untrusted
|
||||
network, particularly DoS attacks.</p>
|
||||
|
||||
</div><h3 id="Engine_vs_Host_placement">Engine vs Host placement</h3><div class="text">
|
||||
<p>
|
||||
You can place the <code><Cluster></code> element inside either the <code><Engine></code>
|
||||
container or the <code><Host></code> container.<br>
|
||||
Placing it in the engine, means that you will support clustering in all virtual hosts of Tomcat,
|
||||
and share the messaging component. When you place the <code><Cluster></code> inside the <code><Engine></code>
|
||||
element, the cluster will append the host name of each session manager to the managers name so that two contexts with
|
||||
the same name but sitting inside two different hosts will be distinguishable.
|
||||
</p>
|
||||
</div><h3 id="Context_Attribute_Replication">Context Attribute Replication</h3><div class="text">
|
||||
<p>To configure context attribute replication, simply do this by swapping out the context implementation
|
||||
used for your application context.</p>
|
||||
<div class="codeBox"><pre><code><Context className="org.apache.catalina.ha.context.ReplicatedContext"/></code></pre></div>
|
||||
<p>
|
||||
This context extends the Tomcat <code><a href="context.html">StandardContext</a></code>
|
||||
so all the options from the <a href="context.html">base implementation</a> are valid.
|
||||
</p>
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
<p><b><a href="cluster-manager.html">Manager</a>:</b> <br>
|
||||
The session manager element identifies what kind of session manager is used in this cluster implementation.
|
||||
This manager configuration is identical to the one you would use in a regular <code><a href="context.html#Nested_Components"><Context></a></code> configuration.
|
||||
<br>The default value is the <code>org.apache.catalina.ha.session.DeltaManager</code> that is closely coupled with
|
||||
the <code>SimpleTcpCluster</code> implementation. Other managers like the <code>org.apache.catalina.ha.session.BackupManager</code>
|
||||
are/could be loosely coupled and don't rely on the <code>SimpleTcpCluster</code> for its data replication.
|
||||
</p>
|
||||
<p><b><a href="cluster-channel.html">Channel</a>:</b> <br>
|
||||
The Channel and its sub components are all part of the IO layer
|
||||
for the cluster group, and is a module in it's own that we have nick named "Tribes"
|
||||
<br>
|
||||
Any configuring and tuning of the network layer, the messaging and the membership logic
|
||||
will be done in the channel and its nested components.
|
||||
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
|
||||
</p>
|
||||
<p><b><a href="cluster-valve.html">Valve</a>:</b> <br>
|
||||
The Tomcat Cluster implementation uses <code>Tomcat <a href="valve.html">Valves</a></code> to
|
||||
track when requests enter and exit the servlet container. It uses these valves to be able to make
|
||||
intelligent decisions on when to replicate data, which is always at the end of a request.
|
||||
</p>
|
||||
<p><b><a href="cluster-deployer.html">Deployer</a>:</b> <br>
|
||||
The Deployer component is the Tomcat Farm Deployer. It allows you to deploy and undeploy applications
|
||||
cluster wide.
|
||||
</p>
|
||||
<p><b><a href="cluster-listener.html">ClusterListener</a>:</b> <br>
|
||||
ClusterListener's are used to track messages sent and received using the <code>SimpleTcpCluster</code>.
|
||||
If you wish to track messages, you can add a listener here, or you can add a valve to the channel object.
|
||||
</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
<div class="subsection"><h4 id="SimpleTcpCluster_Attributes">SimpleTcpCluster Attributes</h4><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>The main cluster class, currently only one is available,
|
||||
<code>org.apache.catalina.ha.tcp.SimpleTcpCluster</code>
|
||||
</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">channelSendOptions</code></strong></td><td>
|
||||
<p>The Tribes channel send options, default is <code>8</code>.<br>
|
||||
This option is used to set the flag that all messages sent through the
|
||||
SimpleTcpCluster uses. The flag decides how the messages are sent, and is a simple logical OR.</p>
|
||||
|
||||
<div class="codeBox"><pre><code>int options = Channel.SEND_OPTIONS_ASYNCHRONOUS |
|
||||
Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
|
||||
Channel.SEND_OPTIONS_USE_ACK;</code></pre></div>
|
||||
<p>Some of the values are:<br>
|
||||
<code>Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004</code><br>
|
||||
<code>Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008</code><br>
|
||||
<code>Channel.SEND_OPTIONS_USE_ACK = 0x0002</code><br>
|
||||
So to use ACK and ASYNC messaging, the flag would be <code>10</code> (8+2)
|
||||
<br>
|
||||
Note that if you use ASYNC messaging it is possible for update messages
|
||||
for a session to be processed by the receiving nodes in a different order
|
||||
to the order in which they were sent.
|
||||
</p>
|
||||
<p>
|
||||
The various <code>channelSendOptions</code> values offer a tradeoff
|
||||
between throughput on the sending node and the reliability of
|
||||
replication should the sending or receiving node(s) fail. Here are
|
||||
some common options. "Message" could be any message sent between nodes,
|
||||
but only session-change messages are considered, here.
|
||||
</p>
|
||||
<p>
|
||||
<code>channelSendOptions="8"</code> / <code>channelSendOptions="async"</code>
|
||||
As far as the sender is concerned, the message is "sent"
|
||||
as soon as it has been placed in the queue on the sender for
|
||||
transmission to the other nodes. The message may not reach any or all
|
||||
of the recipient nodes and may not be successfully processed on any
|
||||
nodes that it does reach. This option offers the highest throughput on
|
||||
the sender but the least reliability, as the triggering request will
|
||||
complete without any knowledge of the success/failure of the session
|
||||
replication.
|
||||
</p>
|
||||
<p>
|
||||
<code>channelSendOptions="2"</code> / <code>channelSendOptions="use_ack"</code>
|
||||
The sender will block the completion of the current request until all
|
||||
of the receiving nodes have acknowledged that they have received the
|
||||
message, but have not necessarily processed that message. This option
|
||||
will result in lower throughput on the sending node, because the message
|
||||
must be transmitted and the acknowledgement received, but the
|
||||
reliability is greater than the asynchronous model.
|
||||
</p>
|
||||
<p>
|
||||
<code>channelSendOptions="6"</code> / <code>channelSendOptions="sync,use_ack"</code>
|
||||
The sender will block the completion of the current request until
|
||||
all of the receiving nodes have acknowledged that they have received
|
||||
<u>and</u> processed the message. This option will have the lowest
|
||||
throughput (of these three) but the greatest reliability.
|
||||
</p>
|
||||
<p>
|
||||
You may also set these options as a comma separated string, e.g. "async, multicast", which
|
||||
will be translated into <code>Channel.SEND_OPTIONS_ASYNCHRONOUS | Channel.SEND_OPTIONS_MULTICAST</code>
|
||||
<br>
|
||||
The valid option names are "asynchronous" (alias "async"), "byte_message" (alias "byte")
|
||||
, "multicast", "secure", "synchronized_ack" (alias "sync"), "udp", "use_ack"
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">channelStartOptions</code></td><td>
|
||||
<p>Sets the start and stop flags for the <Channel> object used by the cluster.
|
||||
The default is <code>Channel.DEFAULT</code> which starts all the channel services, such as
|
||||
sender, receiver, membership sender and membership receiver.
|
||||
The following flags are available today:</p>
|
||||
<div class="codeBox"><pre><code>Channel.DEFAULT = Channel.SND_RX_SEQ (1) |
|
||||
Channel.SND_TX_SEQ (2) |
|
||||
Channel.MBR_RX_SEQ (4) |
|
||||
Channel.MBR_TX_SEQ (8);</code></pre></div>
|
||||
<p>When using the static membership service
|
||||
<code>org.apache.catalina.tribes.membership.StaticMembershipService</code>
|
||||
you must ensure that this attribute is configured to use the default
|
||||
value.</p>
|
||||
</td></tr><tr><td><code class="attributeName">heartbeatBackgroundEnabled</code></td><td>
|
||||
<p>Flag whether invoke channel heartbeat at container background thread. Default value is false.
|
||||
Enable this flag don't forget to disable the channel heartbeat thread.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">notifyLifecycleListenerOnFailure</code></td><td>
|
||||
<p>Flag whether notify LifecycleListeners if all ClusterListener couldn't accept channel message.
|
||||
Default value is false.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
1257
tomcat/webapps.dist/docs/config/context.html
Normal file
1257
tomcat/webapps.dist/docs/config/context.html
Normal file
File diff suppressed because it is too large
Load Diff
166
tomcat/webapps.dist/docs/config/cookie-processor.html
Normal file
166
tomcat/webapps.dist/docs/config/cookie-processor.html
Normal file
@@ -0,0 +1,166 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Cookie Processor Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Cookie Processor Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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><li><a href="#Legacy_Cookie_Processor_-_org.apache.tomcat.util.http.LegacyCookieProcessor">Legacy Cookie Processor - org.apache.tomcat.util.http.LegacyCookieProcessor</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>CookieProcessor</strong> element represents the component that
|
||||
parses received cookie headers into <code>javax.servlet.http.Cookie</code>
|
||||
objects accessible through <code>HttpServletRequest.getCookies()</code> and
|
||||
converts <code>javax.servlet.http.Cookie</code> objects added to the response
|
||||
through <code>HttpServletResponse.addCookie()</code> to the HTTP headers
|
||||
returned to the client.</p>
|
||||
|
||||
<p>A CookieProcessor element MAY be nested inside a
|
||||
<a href="context.html">Context</a> component. If it is not included, a default
|
||||
implementation will be created automatically.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>CookieProcessor</strong> support the
|
||||
following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.tomcat.util.http.CookieProcessor</code>
|
||||
interface. If not specified, the standard value (defined below) will be
|
||||
used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>CookieProcessor</strong> is
|
||||
<code>org.apache.tomcat.util.http.Rfc6265CookieProcessor</code>.</p>
|
||||
|
||||
<p>This cookie processor is based on RFC6265 with the following changes to
|
||||
support better interoperability:</p>
|
||||
|
||||
<ul>
|
||||
<li>Values 0x80 to 0xFF are permitted in cookie-octet to support the use
|
||||
of UTF-8 in cookie values as used by HTML 5.</li>
|
||||
<li>For cookies without a value, the '=' is not required after the name as
|
||||
some browsers do not sent it.</li>
|
||||
</ul>
|
||||
|
||||
<p>The RFC 6265 cookie processor is generally more lenient than the legacy
|
||||
cookie parser. In particular:</p>
|
||||
|
||||
<ul>
|
||||
<li>The '<code>=</code>' and '<code>/</code>' characters are always
|
||||
permitted in a cookie value.</li>
|
||||
<li>Name only cookies are always permitted.</li>
|
||||
<li>The cookie header is always preserved.</li>
|
||||
</ul>
|
||||
|
||||
<p>The <strong>RFC 6265 Cookie Processor</strong> supports the following
|
||||
additional attributes.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">sameSiteCookies</code></td><td>
|
||||
<p>Enables setting same-site cookie attribute.</p>
|
||||
|
||||
<p>If value is <code>unset</code> then the same-site cookie attribute
|
||||
won't be set. This is the default value.</p>
|
||||
|
||||
<p>If value is <code>none</code> then the same-site cookie attribute
|
||||
will be set and the cookie will always be sent in cross-site requests.</p>
|
||||
|
||||
<p>If value is <code>lax</code> then the browser only sends the cookie
|
||||
in same-site requests and cross-site top level GET requests.</p>
|
||||
|
||||
<p>If value is <code>strict</code> then the browser prevents sending the
|
||||
cookie in any cross-site request.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Legacy_Cookie_Processor_-_org.apache.tomcat.util.http.LegacyCookieProcessor">Legacy Cookie Processor - org.apache.tomcat.util.http.LegacyCookieProcessor</h4><div class="text">
|
||||
|
||||
<p>This is the legacy cookie parser based on RFC6265, RFC2109 and RFC2616.
|
||||
It implements a strict interpretation of the cookie specifications. Due to
|
||||
various interoperability issues with browsers not all strict behaviours
|
||||
are enabled by default and additional options are available to further
|
||||
relax the behaviour of this cookie processor if required.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">allowEqualsInValue</code></td><td>
|
||||
<p>If this is <code>true</code> Tomcat will allow '<code>=</code>'
|
||||
characters when parsing unquoted cookie values. If <code>false</code>,
|
||||
cookie values containing '<code>=</code>' will be terminated when the
|
||||
'<code>=</code>' is encountered and the remainder of the cookie value
|
||||
will be dropped.</p>
|
||||
<p>If not set the specification compliant default value of
|
||||
<code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">allowHttpSepsInV0</code></td><td>
|
||||
<p>If this is <code>true</code> Tomcat will allow HTTP separators in
|
||||
cookie names and values.</p>
|
||||
<p>If not specified, the default specification compliant value of
|
||||
<code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">allowNameOnly</code></td><td>
|
||||
<p>If this is <code>true</code> Tomcat will allow name only cookies
|
||||
(with or without trailing '<code>=</code>') when parsing cookie headers.
|
||||
If <code>false</code>, name only cookies will be dropped.</p>
|
||||
<p>If not set the specification compliant default value of
|
||||
<code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">alwaysAddExpires</code></td><td>
|
||||
<p>If this is <code>true</code> Tomcat will always add an expires
|
||||
parameter to a SetCookie header even for cookies with version greater
|
||||
than zero. This is to work around a known IE6 and IE7 bug that causes I
|
||||
to ignore the Max-Age parameter in a SetCookie header.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set
|
||||
to <code>true</code>, the default of this setting will be
|
||||
<code>false</code>, else the default value will be <code>true</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">forwardSlashIsSeparator</code></td><td>
|
||||
<p>If this is <code>true</code> Tomcat will treat the forward slash
|
||||
character ('<code>/</code>') as an HTTP separator when processing cookie
|
||||
headers. If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
|
||||
is set to <code>true</code>, the default of this setting will be
|
||||
<code>true</code>, else the default value will be <code>false</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">sameSiteCookies</code></td><td>
|
||||
<p>Enables setting same-site cookie attribute.</p>
|
||||
|
||||
<p>If value is <code>unset</code> then the same-site cookie attribute
|
||||
won't be set. This is the default value.</p>
|
||||
|
||||
<p>If value is <code>none</code> then the same-site cookie attribute
|
||||
will be set and the cookie will always be sent in cross-site requests.</p>
|
||||
|
||||
<p>If value is <code>lax</code> then the browser only sends the cookie
|
||||
in same-site requests and cross-site top level GET requests.</p>
|
||||
|
||||
<p>If value is <code>strict</code> then the browser prevents sending the
|
||||
cookie in any cross-site request.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>No element may be nested inside a <strong>CookieProcessor</strong>.</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<p>No special features are associated with a <strong>CookieProcessor</strong>
|
||||
element.</p>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
167
tomcat/webapps.dist/docs/config/credentialhandler.html
Normal file
167
tomcat/webapps.dist/docs/config/credentialhandler.html
Normal file
@@ -0,0 +1,167 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The CredentialHandler Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 CredentialHandler Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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="#MessageDigestCredentialHandler">MessageDigestCredentialHandler</a></li><li><a href="#NestedCredentialHandler">NestedCredentialHandler</a></li><li><a href="#SecretKeyCredentialHandler">SecretKeyCredentialHandler</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>CredentialHandler</strong> element represents the component
|
||||
used by a <a href="realm.html">Realm</a> to compare a provided credential such
|
||||
as a password with the version of the credential stored by the
|
||||
<a href="realm.html">Realm</a>. The <strong>CredentialHandler</strong> can
|
||||
also be used to generate a new stored version of a given credential that would
|
||||
be required, for example, when adding a new user to a
|
||||
<a href="realm.html">Realm</a> or when changing a user's password.</p>
|
||||
|
||||
<p>A <strong>CredentialHandler</strong> element MUST be nested inside a
|
||||
<a href="realm.html">Realm</a> component. If it is not included,
|
||||
a default <strong>CredentialHandler</strong> will be created using the
|
||||
<strong>MessageDigestCredentialHandler</strong>.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>CredentialHandler</strong> support the
|
||||
following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.CredentialHandler</code>
|
||||
interface.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<p>Unlike most Catalina components, there are several standard
|
||||
<strong>CredentialHandler</strong> implementations available. As a result,
|
||||
if a <strong>CredentialHandler</strong> element is present then the
|
||||
<code>className</code> attribute MUST be used to select the implementation
|
||||
you wish to use.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="MessageDigestCredentialHandler">MessageDigestCredentialHandler</h4><div class="text">
|
||||
|
||||
<p>The <strong>MessageDigestCredentialHandler</strong> is used when stored
|
||||
passwords are protected by a message digest. This credential handler
|
||||
supports the following forms of stored passwords:</p>
|
||||
<ul>
|
||||
<li><strong>plainText</strong> - the plain text credentials if no
|
||||
algorithm is specified</li>
|
||||
<li><strong>encodedCredential</strong> - a hex encoded digest of the
|
||||
password digested using the configured digest</li>
|
||||
<li><strong>{MD5}encodedCredential</strong> - a Base64 encoded MD5
|
||||
digest of the password</li>
|
||||
<li><strong>{SHA}encodedCredential</strong> - a Base64 encoded SHA1 digest
|
||||
of the password</li>
|
||||
<li><strong>{SSHA}encodedCredential</strong> - 20 character salt followed
|
||||
by the salted SHA1 digest Base64 encoded</li>
|
||||
<li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
|
||||
salt, iteration code and a hex encoded credential, each separated by
|
||||
$</li>
|
||||
</ul>
|
||||
|
||||
<p>If the stored password form does not include an iteration count then an
|
||||
iteration count of 1 is used.</p>
|
||||
|
||||
<p>If the stored password form does not include salt then no salt is
|
||||
used.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">algorithm</code></td><td>
|
||||
<p>The name of the <code>java.security.MessageDigest</code> algorithm
|
||||
used to encode user passwords stored in the database. If not specified,
|
||||
user passwords are assumed to be stored in clear-text.</p>
|
||||
</td></tr><tr><td><code class="attributeName">encoding</code></td><td>
|
||||
<p>Digesting the password requires that it is converted to bytes. This
|
||||
attribute determines the character encoding to use for conversions
|
||||
between characters and bytes. If not specified, UTF-8 will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">iterations</code></td><td>
|
||||
<p>The number of iterations to use when creating a new stored credential
|
||||
from a clear text credential.</p>
|
||||
</td></tr><tr><td><code class="attributeName">saltLength</code></td><td>
|
||||
<p>The length of the randomly generated salt to use when creating a
|
||||
new stored credential from a clear text credential.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="NestedCredentialHandler">NestedCredentialHandler</h4><div class="text">
|
||||
|
||||
<p>The <strong>NestedCredentialHandler</strong> is an implementation of
|
||||
<strong>CredentialHandler</strong> that delegates to one or more
|
||||
sub-CredentialHandlers.</p>
|
||||
|
||||
<p>Using the <strong>NestedCredentialHandler</strong> gives the developer
|
||||
the ability to combine multiple <strong>CredentialHandler</strong>s of the
|
||||
same or different types.</p>
|
||||
|
||||
<p>Sub-CredentialHandlers are defined by nesting CredentialHandler elements
|
||||
inside the <code>CredentialHandler</code> element that defines the
|
||||
NestedCredentialHandler. Credentials will be matched against each
|
||||
<code>CredentialHandler</code> in the order they are listed. A match against
|
||||
any CredentialHandler will be sufficient for the credentials to be
|
||||
considered matched.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="SecretKeyCredentialHandler">SecretKeyCredentialHandler</h4><div class="text">
|
||||
|
||||
<p>The <strong>SecretKeyCredentialHandler</strong> is used when stored
|
||||
passwords are built using <code>javax.crypto.SecretKeyFactory</code>. This
|
||||
credential handler supports the following forms of stored passwords:</p>
|
||||
<ul>
|
||||
<li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
|
||||
salt, iteration code and a hex encoded credential, each separated by
|
||||
$</li>
|
||||
</ul>
|
||||
|
||||
<p>If the stored password form does not include an iteration count then an
|
||||
iteration count of 1 is used.</p>
|
||||
|
||||
<p>If the stored password form does not include salt then no salt is
|
||||
used.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">algorithm</code></td><td>
|
||||
<p>The name of the secret key algorithm used to encode user passwords
|
||||
stored in the database. If not specified, a default of
|
||||
<code>PBKDF2WithHmacSHA1</code> is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">keyLength</code></td><td>
|
||||
<p>The length of key to generate for the stored credential. If not
|
||||
specified, a default of <code>160</code> is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">iterations</code></td><td>
|
||||
<p>The number of iterations to use when creating a new stored credential
|
||||
from a clear text credential.</p>
|
||||
</td></tr><tr><td><code class="attributeName">saltLength</code></td><td>
|
||||
<p>The length of the randomly generated salt to use when creating a
|
||||
new stored credential from a clear text credential.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>If you are using the <em>NestedCredentialHandler Implementation</em> or a
|
||||
CredentialHandler that extends the NestedCredentialHandler one or more
|
||||
<strong><CredentialHandler></strong> elements may be nested inside it.
|
||||
</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<p>No special features are associated with a
|
||||
<strong>CredentialHandler</strong> element.</p>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
219
tomcat/webapps.dist/docs/config/engine.html
Normal file
219
tomcat/webapps.dist/docs/config/engine.html
Normal file
@@ -0,0 +1,219 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Engine Container</title><meta name="author" content="Craig R. McClanahan"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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">
|
||||
<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>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<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>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Engine</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">backgroundProcessorDelay</code></td><td>
|
||||
<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><code class="attributeName">className</code></td><td>
|
||||
<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><strong><code class="attributeName">defaultHost</code></strong></td><td>
|
||||
<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><code class="attributeName">jvmRoute</code></td><td>
|
||||
<p>Identifier which must be used in load balancing scenarios to enable
|
||||
session affinity. The identifier, which must be unique across all
|
||||
Tomcat 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
|
||||
instance.</p>
|
||||
<p>
|
||||
Note that the <code>jvmRoute</code> can also be set using the
|
||||
deprecated <code>jvmRoute</code> system property. The
|
||||
<code>jvmRoute</code> set in an <code><Engine></code>
|
||||
attribute will override any <code>jvmRoute</code> system property.
|
||||
</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">name</code></strong></td><td>
|
||||
<p>Logical name of this Engine, used in log and error messages. <em>When
|
||||
using multiple <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><tr><td><code class="attributeName">startStopThreads</code></td><td>
|
||||
<p>The number of threads this <strong>Engine</strong> will use to start
|
||||
child <a href="host.html">Host</a> elements in parallel. The special
|
||||
value of 0 will result in the value of
|
||||
<code>Runtime.getRuntime().availableProcessors()</code> being used.
|
||||
Negative values will result in
|
||||
<code>Runtime.getRuntime().availableProcessors() + value</code> being
|
||||
used unless this is less than 1 in which case 1 thread will be used. If
|
||||
not specified, the default value of 1 will be used. If 1 thread is
|
||||
used then, rather than using an <code>ExecutorService</code>, the
|
||||
current thread will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<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 class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<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 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>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Logging">Logging</h4><div class="text">
|
||||
|
||||
<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>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Access_Logs">Access Logs</h4><div class="text">
|
||||
|
||||
<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 class="codeBox"><pre><code><Engine name="Standalone" ...>
|
||||
...
|
||||
<Valve className="org.apache.catalina.valves.AccessLogValve"
|
||||
prefix="catalina_access_log" suffix=".txt"
|
||||
pattern="common"/>
|
||||
...
|
||||
</Engine></code></pre></div>
|
||||
|
||||
<p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
|
||||
for more information on the configuration attributes that are
|
||||
supported.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Lifecycle_Listeners">Lifecycle Listeners</h4><div class="text">
|
||||
|
||||
<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 corresponding
|
||||
lifecycle events. Configuration of such a listener looks like this:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Engine name="Standalone" ...>
|
||||
...
|
||||
<Listener className="com.mycompany.mypackage.MyListener" ... >
|
||||
...
|
||||
</Engine></code></pre></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>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Request_Filters">Request Filters</h4><div class="text">
|
||||
|
||||
<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 configured "accept" and/or "deny"
|
||||
filters, which are defined using <code>java.util.regex</code> Regular
|
||||
Expression syntax. Requests that come from locations that are
|
||||
not accepted will be rejected with an HTTP "Forbidden" error.
|
||||
Example filter declarations:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><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\.\d+"/>
|
||||
...
|
||||
</Engine></code></pre></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>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
82
tomcat/webapps.dist/docs/config/executor.html
Normal file
82
tomcat/webapps.dist/docs/config/executor.html
Normal file
@@ -0,0 +1,82 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Executor (thread pool)</title><meta name="author" content="Filip Hanik"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Executor (thread pool)</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Executor</strong> represents a thread pool that can be shared
|
||||
between components in Tomcat. Historically there has been a thread pool per
|
||||
connector created but this allows you to share a thread pool, between (primarily) connector
|
||||
but also other components when those get configured to support executors</p>
|
||||
|
||||
|
||||
<p>The executor has to implement the <code>org.apache.catalina.Executor</code> interface.</p>
|
||||
|
||||
<p>The executor is a nested element to the <a href="service.html">Service</a> element.
|
||||
And in order for it to be picked up by the connectors, the Executor element has to appear
|
||||
prior to the Connector element in server.xml</p>
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Executor</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>The class of the implementation. The implementation has to implement the
|
||||
<code>org.apache.catalina.Executor</code> interface.
|
||||
This interface ensures that the object can be referenced through its <code>name</code> attribute
|
||||
and that implements Lifecycle, so that it can be started and stopped with the container.
|
||||
The default value for the className is <code>org.apache.catalina.core.StandardThreadExecutor</code></p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">name</code></strong></td><td>
|
||||
<p>The name used to reference this pool in other places in server.xml.
|
||||
The name is required and must be unique.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>
|
||||
The default implementation supports the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">threadPriority</code></td><td>
|
||||
<p>(int) The thread priority for threads in the executor, the default is
|
||||
<code>5</code> (the value of the <code>Thread.NORM_PRIORITY</code> constant)</p>
|
||||
</td></tr><tr><td><code class="attributeName">daemon</code></td><td>
|
||||
<p>(boolean) Whether the threads should be daemon threads or not, the default is <code>true</code></p>
|
||||
</td></tr><tr><td><code class="attributeName">namePrefix</code></td><td>
|
||||
<p>(String) The name prefix for each thread created by the executor.
|
||||
The thread name for an individual thread will be <code>namePrefix+threadNumber</code></p>
|
||||
</td></tr><tr><td><code class="attributeName">maxThreads</code></td><td>
|
||||
<p>(int) The max number of active threads in this pool, default is <code>200</code></p>
|
||||
</td></tr><tr><td><code class="attributeName">minSpareThreads</code></td><td>
|
||||
<p>(int) The minimum number of threads (idle and active) always kept alive, default is <code>25</code></p>
|
||||
</td></tr><tr><td><code class="attributeName">maxIdleTime</code></td><td>
|
||||
<p>(int) The number of milliseconds before an idle thread shutsdown, unless the number of active threads are less
|
||||
or equal to minSpareThreads. Default value is <code>60000</code>(1 minute)</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxQueueSize</code></td><td>
|
||||
<p>(int) The maximum number of runnable tasks that can queue up awaiting
|
||||
execution before we reject them. Default value is <code>Integer.MAX_VALUE</code></p>
|
||||
</td></tr><tr><td><code class="attributeName">threadRenewalDelay</code></td><td>
|
||||
<p>(long) If a <a href="listeners.html">ThreadLocalLeakPreventionListener</a> is configured,
|
||||
it will notify this executor about stopped contexts.
|
||||
After a context is stopped, threads in the pool are renewed. To avoid renewing all threads at the same time,
|
||||
this option sets a delay between renewal of any 2 threads. The value is in ms,
|
||||
default value is <code>1000</code> ms. If value is negative, threads are not renewed.</p>
|
||||
</td></tr></table>
|
||||
|
||||
|
||||
</div></div>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
1717
tomcat/webapps.dist/docs/config/filter.html
Normal file
1717
tomcat/webapps.dist/docs/config/filter.html
Normal file
File diff suppressed because one or more lines are too long
220
tomcat/webapps.dist/docs/config/globalresources.html
Normal file
220
tomcat/webapps.dist/docs/config/globalresources.html
Normal file
@@ -0,0 +1,220 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The GlobalNamingResources Component</title><meta name="author" content="Remy Maucherat"><meta name="author" content="Yoav Shapira"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 GlobalNamingResources Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Special_Features">Special Features</a><ol><li><a href="#Environment_Entries">Environment Entries</a></li><li><a href="#Resource_Definitions">Resource Definitions</a></li><li><a href="#Resource_Links">Resource Links</a></li><li><a href="#Transaction">Transaction</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>GlobalNamingResources</strong> element defines the global
|
||||
JNDI resources for the <a href="server.html">Server</a>.</p>
|
||||
|
||||
<p>These resources are listed in the server's global JNDI resource context.
|
||||
This context is distinct from the per-web-application JNDI contexts
|
||||
described in
|
||||
the <a href="../jndi-resources-howto.html">JNDI Resources How-To</a>.
|
||||
The resources defined in this element are <strong>not</strong> visible in
|
||||
the per-web-application contexts unless you explicitly link them with
|
||||
<a href="context.html#Resource_Links"><ResourceLink></a> elements.
|
||||
</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Environment_Entries">Environment Entries</h4><div class="text">
|
||||
|
||||
<p>You can configure named values that will be made visible to all
|
||||
web applications as environment entry resources by nesting
|
||||
<code><Environment></code> entries inside this element. For
|
||||
example, you can create an environment entry like this:</p>
|
||||
<div class="codeBox"><pre><code><GlobalNamingResources ...>
|
||||
...
|
||||
<Environment name="maxExemptions" value="10"
|
||||
type="java.lang.Integer" override="false"/>
|
||||
...
|
||||
</GlobalNamingResources></code></pre></div>
|
||||
|
||||
<p>This is equivalent to the inclusion of the following element in the
|
||||
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
|
||||
</p>
|
||||
<div class="codeBox"><pre><code><env-entry>
|
||||
<env-entry-name>maxExemptions</env-entry-name>
|
||||
<env-entry-value>10</env-entry-value>
|
||||
<env-entry-type>java.lang.Integer</env-entry-type>
|
||||
</env-entry></code></pre></div>
|
||||
<p>but does <em>not</em> require modification of the deployment descriptor
|
||||
to customize this value.</p>
|
||||
|
||||
<p>The valid attributes for an <code><Environment></code> element
|
||||
are as follows:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">description</code></td><td>
|
||||
<p>Optional, human-readable description of this environment entry.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">name</code></strong></td><td>
|
||||
<p>The name of the environment entry to be created, relative to the
|
||||
<code>java:comp/env</code> context.</p>
|
||||
</td></tr><tr><td><code class="attributeName">override</code></td><td>
|
||||
<p>Set this to <code>false</code> if you do <strong>not</strong> want
|
||||
an <code><env-entry></code> for the same environment entry name,
|
||||
found in the web application deployment descriptor, to override the
|
||||
value specified here. By default, overrides are allowed.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">type</code></strong></td><td>
|
||||
<p>The fully qualified Java class name expected by the web application
|
||||
for this environment entry. Must be a legal value for
|
||||
<code><env-entry-type></code> in the web application deployment
|
||||
descriptor.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">value</code></strong></td><td>
|
||||
<p>The parameter value that will be presented to the application
|
||||
when requested from the JNDI context. This value must be convertible
|
||||
to the Java type defined by the <code>type</code> attribute.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Resource_Definitions">Resource Definitions</h4><div class="text">
|
||||
|
||||
<p>You can declare the characteristics of resources
|
||||
to be returned for JNDI lookups of <code><resource-ref></code> and
|
||||
<code><resource-env-ref></code> elements in the web application
|
||||
deployment descriptor by defining them in this element and then linking
|
||||
them with <a href="context.html#Resource_Links"><ResourceLink></a>
|
||||
elements
|
||||
in the <code><strong><Context></strong></code> element.
|
||||
|
||||
You <strong>MUST</strong> also define any other needed parameters using
|
||||
attributes on the Resource element, to configure
|
||||
the object factory to be used (if not known to Tomcat already), and
|
||||
the properties used to configure that object factory.</p>
|
||||
|
||||
<p>For example, you can create a resource definition like this:</p>
|
||||
<div class="codeBox"><pre><code><GlobalNamingResources ...>
|
||||
...
|
||||
<Resource name="jdbc/EmployeeDB" auth="Container"
|
||||
type="javax.sql.DataSource"
|
||||
description="Employees Database for HR Applications"/>
|
||||
...
|
||||
</GlobalNamingResources></code></pre></div>
|
||||
|
||||
<p>This is equivalent to the inclusion of the following element in the
|
||||
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
|
||||
<div class="codeBox"><pre><code><resource-ref>
|
||||
<description>Employees Database for HR Applications</description>
|
||||
<res-ref-name>jdbc/EmployeeDB</res-ref-name>
|
||||
<res-ref-type>javax.sql.DataSource</res-ref-type>
|
||||
<res-auth>Container</res-auth>
|
||||
</resource-ref></code></pre></div>
|
||||
|
||||
<p>but does <em>not</em> require modification of the deployment
|
||||
descriptor to customize this value.</p>
|
||||
|
||||
<p>The valid attributes for a <code><Resource></code> element
|
||||
are as follows:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">auth</code></td><td>
|
||||
<p>Specify whether the web Application code signs on to the
|
||||
corresponding resource manager programmatically, or whether the
|
||||
Container will sign on to the resource manager on behalf of the
|
||||
application. The value of this attribute must be
|
||||
<code>Application</code> or <code>Container</code>. This
|
||||
attribute is <strong>required</strong> if the web application
|
||||
will use a <code><resource-ref></code> element in the web
|
||||
application deployment descriptor, but is optional if the
|
||||
application uses a <code><resource-env-ref></code> instead.</p>
|
||||
</td></tr><tr><td><code class="attributeName">closeMethod</code></td><td>
|
||||
<p>Name of the zero-argument method to call on a singleton resource when
|
||||
it is no longer required. This is intended to speed up clean-up of
|
||||
resources that would otherwise happen as part of garbage collection.
|
||||
This attribute is ignored if the <code>singleton</code> attribute is
|
||||
false. If not specified, no default is defined and no close method will
|
||||
be called.</p>
|
||||
<p>For Apache Commons DBCP 2 and Apache Tomcat JDBC connection pools
|
||||
you can use <code>closeMethod="close"</code>. Note that Apache Commons
|
||||
DBCP 2 requires this to be set for a clean shutdown. When using the
|
||||
default Tomcat connection pool (based on DBCP 2) Tomcat will set this
|
||||
attribute automatically unless it is explicitly set to the empty
|
||||
string.</p>
|
||||
</td></tr><tr><td><code class="attributeName">description</code></td><td>
|
||||
<p>Optional, human-readable description of this resource.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">name</code></strong></td><td>
|
||||
<p>The name of the resource to be created, relative to the
|
||||
<code>java:comp/env</code> context.</p>
|
||||
</td></tr><tr><td><code class="attributeName">scope</code></td><td>
|
||||
<p>Specify whether connections obtained through this resource
|
||||
manager can be shared. The value of this attribute must be
|
||||
<code>Shareable</code> or <code>Unshareable</code>. By default,
|
||||
connections are assumed to be shareable.</p>
|
||||
</td></tr><tr><td><code class="attributeName">singleton</code></td><td>
|
||||
<p>Specify whether this resource definition is for a singleton resource,
|
||||
i.e. one where there is only a single instance of the resource. If this
|
||||
attribute is <code>true</code>, multiple JNDI lookups for this resource
|
||||
will return the same object. If this attribute is <code>false</code>,
|
||||
multiple JNDI lookups for this resource will return different objects.
|
||||
This attribute must be <code>true</code> for
|
||||
<code>javax.sql.DataSource</code> resources to enable JMX registration
|
||||
of the DataSource. The value of this attribute must be <code>true</code>
|
||||
or <code>false</code>. By default, this attribute is <code>true</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">type</code></strong></td><td>
|
||||
<p>The fully qualified Java class name expected by the web
|
||||
application when it performs a lookup for this resource.</p>
|
||||
</td></tr></table>
|
||||
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Resource_Links">Resource Links</h4><div class="text">
|
||||
<p>Use <a href="context.html#Resource_Links"><code><ResourceLink></code></a>
|
||||
elements to link resources from the global context into
|
||||
per-web-application contexts. Here is an example of making a custom
|
||||
factory available to an application, based on the example definition in the
|
||||
<a href="../jndi-resources-howto.html#Generic_JavaBean_Resources">
|
||||
JNDI Resource How-To</a>:
|
||||
</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Context>
|
||||
<ResourceLink
|
||||
name="bean/MyBeanFactory"
|
||||
global="bean/MyBeanFactory"
|
||||
type="com.mycompany.MyBean"
|
||||
/>
|
||||
</Context></code></pre></div>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Transaction">Transaction</h4><div class="text">
|
||||
|
||||
<p>You can declare the characteristics of the UserTransaction
|
||||
to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
|
||||
You <strong>MUST</strong> define an object factory class to instantiate
|
||||
this object as well as the needed resource parameters as attributes of the
|
||||
<code>Transaction</code>
|
||||
element, and the properties used to configure that object factory.</p>
|
||||
|
||||
<p>The valid attributes for the <code><Transaction></code> element
|
||||
are as follows:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">factory</code></strong></td><td>
|
||||
<p>The class name for the JNDI object factory.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
595
tomcat/webapps.dist/docs/config/host.html
Normal file
595
tomcat/webapps.dist/docs/config/host.html
Normal file
@@ -0,0 +1,595 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Host Container</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Remy Maucherat"><meta name="author" content="Yoav Shapira"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Host Container</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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="#Automatic_Application_Deployment">Automatic Application Deployment</a></li><li><a href="#Host_Name_Aliases">Host Name Aliases</a></li><li><a href="#Lifecycle_Listeners">Lifecycle Listeners</a></li><li><a href="#Request_Filters">Request Filters</a></li><li><a href="#Single_Sign_On">Single Sign On</a></li><li><a href="#User_Web_Applications">User Web Applications</a></li><li><a href="#Custom_context.xml_and_web.xml">Custom context.xml and web.xml</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Host</strong> element represents a <em>virtual host</em>,
|
||||
which is an association of a network name for a server (such as
|
||||
"www.mycompany.com") with the particular server on which Tomcat is running.
|
||||
For clients to be able to connect to a Tomcat server using its network name,
|
||||
this name must be registered in the <em>Domain Name Service</em> (DNS) server
|
||||
that manages the Internet domain you belong to - contact your Network
|
||||
Administrator for more information.</p>
|
||||
|
||||
<p>In many cases, System Administrators wish to associate more than
|
||||
one network name (such as <code>www.mycompany.com</code> and
|
||||
<code>company.com</code>) with the same virtual host and applications.
|
||||
This can be accomplished using the <a href="#Host_Name_Aliases">Host
|
||||
Name Aliases</a> feature discussed below.</p>
|
||||
|
||||
<p>One or more <strong>Host</strong> elements are nested inside an
|
||||
<a href="engine.html">Engine</a> element. Inside the Host element, you
|
||||
can nest <a href="context.html">Context</a> elements for the web
|
||||
applications associated with this virtual host. Exactly one of the Hosts
|
||||
associated with each Engine MUST have a name matching the
|
||||
<code>defaultHost</code> attribute of that Engine.</p>
|
||||
|
||||
<p>Clients normally use host names to identify the server they wish to connect
|
||||
to. This host name is also included in the HTTP request headers. Tomcat
|
||||
extracts the host name from the HTTP headers and looks for a
|
||||
<strong>Host</strong> with a matching name. If no match is found, the request
|
||||
is routed to the default host. The name of the default host does not have to
|
||||
match a DNS name (although it can) since any request where the DNS name does
|
||||
not match the name of a <strong>Host</strong> element will be routed to the
|
||||
default host.</p>
|
||||
|
||||
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
|
||||
base directory against which most relative paths are resolved. If you have
|
||||
not configured Tomcat for multiple instances by setting a CATALINA_BASE
|
||||
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
|
||||
the directory into which you have installed Tomcat.</em></p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Host</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">appBase</code></strong></td><td>
|
||||
<p>The <em>Application Base</em> directory for this virtual host.
|
||||
This is the pathname of a directory that may contain web applications
|
||||
to be deployed on this virtual host. You may specify an
|
||||
absolute pathname, or a pathname that is relative to the
|
||||
<code>$CATALINA_BASE</code> directory. See
|
||||
<a href="#Automatic_Application_Deployment">Automatic Application
|
||||
Deployment</a> for more information on automatic recognition and
|
||||
deployment of web applications. If not specified, the default of
|
||||
<code>webapps</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">xmlBase</code></td><td>
|
||||
<p>The <em>XML Base</em> directory for this virtual host.
|
||||
This is the pathname of a directory that may contain context XML
|
||||
descriptors to be deployed on this virtual host. You may specify an
|
||||
absolute pathname for this directory, or a pathname that is relative
|
||||
to the <code>$CATALINA_BASE</code> directory. See
|
||||
<a href="#Automatic_Application_Deployment">Automatic Application
|
||||
Deployment</a> for more information on automatic recognition and
|
||||
deployment of web applications. If not specified the default of
|
||||
<code>conf/<engine_name>/<host_name></code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">createDirs</code></td><td>
|
||||
<p>If set to <code>true</code>, Tomcat will attempt to create the
|
||||
directories defined by the attributes <code>appBase</code> and
|
||||
<code>xmlBase</code> during the startup phase. The default value is
|
||||
<code>true</code>. If set to <code>true</code>, and directory creation
|
||||
fails, an error message will be printed out but will not halt the
|
||||
startup sequence.</p>
|
||||
</td></tr><tr><td><code class="attributeName">autoDeploy</code></td><td>
|
||||
<p>This flag value indicates if Tomcat should check periodically for new
|
||||
or updated web applications while Tomcat is running. If
|
||||
<code>true</code>, Tomcat periodically checks the <code>appBase</code>
|
||||
and <code>xmlBase</code> directories and deploys any new web
|
||||
applications or context XML descriptors found. Updated web applications
|
||||
or context XML descriptors will trigger a reload of the web application.
|
||||
The default is <code>true</code>. See
|
||||
<a href="#Automatic_Application_Deployment">Automatic Application
|
||||
Deployment</a> for more information.</p>
|
||||
</td></tr><tr><td><code class="attributeName">backgroundProcessorDelay</code></td><td>
|
||||
<p>This value represents the delay in seconds between the
|
||||
invocation of the backgroundProcess method on this host and
|
||||
its child containers, including all 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 host
|
||||
and all its child containers. A host will use background processing to
|
||||
perform live web application deployment related tasks. If not
|
||||
specified, the default value for this attribute is -1, which means
|
||||
the host will rely on the background processing setting of its parent
|
||||
engine.</p>
|
||||
</td></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Host</code> interface.
|
||||
If not specified, the standard value (defined below) will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">deployIgnore</code></td><td>
|
||||
<p>A regular expression defining paths to ignore when
|
||||
<code>autoDeploy</code> and <code>deployOnStartup</code> are set. This
|
||||
allows you to keep your configuration in a version control system, for
|
||||
example, and not deploy a <code>.svn</code>, <code>.git</code> or other
|
||||
configuration control system folder that happens to be in the
|
||||
<code>appBase</code>.</p>
|
||||
<p>This regular expression is relative to <code>appBase</code>. It is
|
||||
also <em>anchored</em>, meaning the match is performed against the
|
||||
entire file/directory name. So, <code>foo</code> matches only a file or
|
||||
directory named <code>foo</code> but not <code>foo.war</code>,
|
||||
<code>foobar</code>, or <code>myfooapp</code>. To match anything with
|
||||
"foo", you could use <code>.*foo.*</code>.</p>
|
||||
<p>See <a href="#Automatic_Application_Deployment">Automatic Application
|
||||
Deployment</a> for more information.</p>
|
||||
</td></tr><tr><td><code class="attributeName">deployOnStartup</code></td><td>
|
||||
<p>This flag value indicates if web applications from this host should
|
||||
be automatically deployed when Tomcat starts. The default is
|
||||
<code>true</code>. See
|
||||
<a href="#Automatic_Application_Deployment">Automatic Application
|
||||
Deployment</a> for more information.</p>
|
||||
</td></tr><tr><td><code class="attributeName">failCtxIfServletStartFails</code></td><td>
|
||||
<p>Set to <code>true</code> to have each child contexts fail its startup
|
||||
if any of its servlet that has load-on-startup >=0 fails its own
|
||||
startup.</p>
|
||||
<p>Each child context may override this attribute.</p>
|
||||
<p>If not specified, the default value of <code>false</code> is
|
||||
used.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">name</code></strong></td><td>
|
||||
<p>Usually the network name of this virtual host, as registered in your
|
||||
<em>Domain Name Service</em> server. Regardless of the case used to
|
||||
specify the host name, Tomcat will convert it to lower case internally.
|
||||
One of the Hosts nested within an <a href="engine.html">Engine</a> MUST
|
||||
have a name that matches the <code>defaultHost</code> setting for that
|
||||
Engine. See <a href="#Host_Name_Aliases">Host Name Aliases</a> for
|
||||
information on how to assign more than one network name to the same
|
||||
virtual host. The name can not contain a wildcard, this is only
|
||||
valid in an Alias.</p>
|
||||
</td></tr><tr><td><code class="attributeName">startStopThreads</code></td><td>
|
||||
<p>The number of threads this <strong>Host</strong> will use to start
|
||||
child <a href="context.html">Context</a> elements in parallel. The same
|
||||
thread pool will be used to deploy new
|
||||
<a href="context.html">Context</a>s if automatic deployment is being
|
||||
used.
|
||||
As the thread pool is shared at the Server level, if more than one
|
||||
Host specifies this setting, only the maximum value will apply and will
|
||||
be used for all except for the special value 1. If
|
||||
not specified, the default value of 1 will be used. If 1 thread is
|
||||
used then rather than using an <code>ExecutorService</code> the current
|
||||
thread will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">undeployOldVersions</code></td><td>
|
||||
<p>This flag determines if Tomcat, as part of the auto deployment
|
||||
process, will check for old, unused versions of web applications
|
||||
deployed using parallel deployment and, if any are found, remove them.
|
||||
This flag only applies if <code>autoDeploy</code> is <code>true</code>.
|
||||
If not specified the default value of <code>false</code> will be used.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>Host</strong> is
|
||||
<strong>org.apache.catalina.core.StandardHost</strong>.
|
||||
It supports the following additional attributes (in addition to the
|
||||
common attributes listed above):</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">copyXML</code></td><td>
|
||||
<p>Set to <code>true</code> if you want a context XML descriptor
|
||||
embedded inside the application (located at
|
||||
<code>/META-INF/context.xml</code>) to be copied to <code>xmlBase</code>
|
||||
when the application is deployed. On subsequent starts, the copied
|
||||
context XML descriptor will be used in preference to any context XML
|
||||
descriptor embedded inside the application even if the descriptor
|
||||
embedded inside the application is more recent. The default is
|
||||
<code>false</code>. Note if <strong>deployXML</strong> is
|
||||
<code>false</code>, this attribute will have no effect.</p>
|
||||
</td></tr><tr><td><code class="attributeName">deployXML</code></td><td>
|
||||
<p>Set to <code>false</code> if you want to disable parsing the context
|
||||
XML descriptor embedded inside the application (located at
|
||||
<code>/META-INF/context.xml</code>). Security conscious environments
|
||||
should set this to <code>false</code> to prevent applications from
|
||||
interacting with the container's configuration. The administrator will
|
||||
then be responsible for providing an external context configuration
|
||||
file, and putting it in the location defined by the
|
||||
<strong>xmlBase</strong> attribute. If this flag is <code>false</code>,
|
||||
a descriptor is located at <code>/META-INF/context.xml</code> and no
|
||||
descriptor is present in <strong>xmlBase</strong> then the context will
|
||||
fail to start in case the descriptor contains necessary configuration
|
||||
for secure deployment (such as a RemoteAddrValve) which should not be
|
||||
ignored. The default is <code>true</code> unless a security manager is
|
||||
enabled when the default is <code>false</code>. When running under a
|
||||
security manager this may be enabled on a per web application basis by
|
||||
granting the
|
||||
<code>org.apache.catalina.security.DeployXmlPermission</code> to the web
|
||||
application. The Manager and Host Manager applications are granted this
|
||||
permission by default so that they continue to work when running under a
|
||||
security manager.</p>
|
||||
</td></tr><tr><td><code class="attributeName">errorReportValveClass</code></td><td>
|
||||
<p>Java class name of the error reporting valve which will be used
|
||||
by this Host. The responsibility of this valve is to output error
|
||||
reports. Setting this property allows to customize the look of the
|
||||
error pages which will be generated by Tomcat. This class must
|
||||
implement the
|
||||
<code>org.apache.catalina.Valve</code> interface. If none is specified,
|
||||
the value <code>org.apache.catalina.valves.ErrorReportValve</code>
|
||||
will be used by default. if set to an empty string, the error report
|
||||
will be disabled.</p>
|
||||
</td></tr><tr><td><code class="attributeName">unpackWARs</code></td><td>
|
||||
<p>Set to <code>true</code> if you want web applications that are
|
||||
placed in the <code>appBase</code> directory as web application
|
||||
archive (WAR) files to be unpacked into a corresponding disk directory
|
||||
structure, <code>false</code> to run such web applications directly
|
||||
from a WAR file. The default is <code>true</code>. See
|
||||
<a href="#Automatic_Application_Deployment">Automatic Application
|
||||
Deployment</a> for more information.</p>
|
||||
<p>Note: If Tomcat expands the WAR file then it will add a file
|
||||
(<code>/META-INF/war-tracking</code>) to the unpacked directory
|
||||
structure which it uses to detect changes in the WAR file while Tomcat
|
||||
is not running. Any such change will trigger the deletion of the
|
||||
expanded directory and the deployment of the updated WAR file when
|
||||
Tomcat next starts.</p>
|
||||
<p>Note: Running with this option set to <code>false</code> will incur
|
||||
a performance penalty. To avoid a significant performance penalty, the
|
||||
web application should be configured such that class scanning for
|
||||
Servlet 3.0+ pluggability features is not required. Users may also wish
|
||||
to consider the <strong>ExtractingRoot</strong>
|
||||
<a href="resources.html">Resources</a> implementation.</p>
|
||||
</td></tr><tr><td><code class="attributeName">workDir</code></td><td>
|
||||
<p>Pathname to a scratch directory to be used by applications for
|
||||
this Host. Each application will have its own sub directory with
|
||||
temporary read-write use. Configuring a Context workDir will override
|
||||
use of the Host workDir configuration. This directory will be made
|
||||
visible to servlets in the web application by a servlet context
|
||||
attribute (of type <code>java.io.File</code>) named
|
||||
<code>javax.servlet.context.tempdir</code> as described in the
|
||||
Servlet Specification. If not specified, a suitable directory
|
||||
underneath <code>$CATALINA_BASE/work</code> will be provided.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>You can nest one or more <a href="context.html">Context</a> elements
|
||||
inside this <strong>Host</strong> element, each representing a different web
|
||||
application associated with this virtual host.</p>
|
||||
|
||||
<p>You can nest at most one instance of the following utility components
|
||||
by nesting a corresponding element inside your <strong>Host</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="context.html">Contexts</a> nested inside this Host (unless
|
||||
overridden by a <a href="realm.html">Realm</a> configuration
|
||||
at a lower level).</li>
|
||||
</ul>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Logging">Logging</h4><div class="text">
|
||||
|
||||
<p>A host is associated with the
|
||||
<code>org.apache.catalina.core.ContainerBase.[engine_name].[host_name]</code>
|
||||
log category. Note that the brackets are part of the name,
|
||||
don't omit them.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Access_Logs">Access Logs</h4><div class="text">
|
||||
|
||||
<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 class="codeBox"><pre><code><Host name="localhost" ...>
|
||||
...
|
||||
<Valve className="org.apache.catalina.valves.AccessLogValve"
|
||||
prefix="localhost_access_log" suffix=".txt"
|
||||
pattern="common"/>
|
||||
...
|
||||
</Host></code></pre></div>
|
||||
|
||||
<p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
|
||||
for more information on the configuration attributes that are
|
||||
supported.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Automatic_Application_Deployment">Automatic Application Deployment</h4><div class="text">
|
||||
|
||||
<p>If you are using the standard <strong>Host</strong> implementation with
|
||||
default settings then applications in the <em>appBase</em> or with context
|
||||
files in the <em>configBase</em> are automatically deployed when Tomcat
|
||||
starts (the <code>deployOnStartup</code> property defaults to
|
||||
<code>true</code>) and reloaded or redeployed (as appropriate) when a change
|
||||
is detected while Tomcat is running (the <code>autoDeploy</code> attribute
|
||||
also defaults to <code>true</code>).</p>
|
||||
|
||||
<p><code>deployOnStartup</code> and <code>autoDeploy</code> trigger
|
||||
execution of exactly the same code so the behaviour is very similar.
|
||||
However, there is one key difference. When Tomcat starts it has no knowledge
|
||||
of which files are the same, which have been changed and which are new. It
|
||||
therefore treats all files as new. While Tomcat is running, it can
|
||||
differentiate between unchanged, modified and new files. This leads to some
|
||||
differences in behaviour between files being modified while Tomcat is
|
||||
running and files being modified while Tomcat is stopped.</p>
|
||||
|
||||
<p>When you use automatic deployment, related files (a web application may
|
||||
have a context.xml file, a WAR and a directory) that exist in the
|
||||
<strong>Host</strong>'s <em>appBase</em> and/or <em>configBase</em>
|
||||
must conform to the expected <a href="context.html#Naming">naming
|
||||
convention</a>. In short, this means files for the same web application must
|
||||
share the same <em>base name</em>.</p>
|
||||
|
||||
<p>The automatic deployment process identifies new and/or modified web
|
||||
applications using the following search order:</p>
|
||||
|
||||
<ol>
|
||||
<li>Web applications with a context.xml file located in the Host's
|
||||
<em>configBase</em>.</li>
|
||||
<li>Web applications with a WAR file located in the Host's
|
||||
<em>appBase</em> that have not already been identified during the scan for
|
||||
context.xml files.</li>
|
||||
<li>Web applications with a directory located in the Host's
|
||||
<em>appBase</em> that have not already been identified during the scans
|
||||
for context.xml and/or WAR files.</li>
|
||||
</ol>
|
||||
|
||||
<p>When <code>autoDeploy</code> is <code>true</code>, the automatic
|
||||
deployment process will monitor the deployed web applications for changes.
|
||||
Depending on exactly what changes, the web application will either be
|
||||
re-deployed or reloaded. Re-deployment involves the creation of a new web
|
||||
application and, if using the standard session manager, user sessions will
|
||||
not be retained. Reloading uses the existing web application but re-parses
|
||||
the web.xml and reloads any classes. If using the standard session manager,
|
||||
user sessions will be persisted.</p>
|
||||
|
||||
<p>Users may add to the files that the automatic deployment process monitors
|
||||
for reloading (i.e. any change to one of these files triggers a reload of
|
||||
the web application) by adding a <em>WatchedResources</em> element to the
|
||||
context.xml file. See the
|
||||
<a href="context.html#Nested_Components">Context</a> documentation for
|
||||
further details.</p>
|
||||
|
||||
<p>When using automatic deployment, the <code>docBase</code> defined by
|
||||
an XML <a href="context.html">Context</a> file should be outside of the
|
||||
<code>appBase</code> directory. If this is not the case, difficulties
|
||||
may be experienced deploying the web application or the application may
|
||||
be deployed twice. The <code>deployIgnore</code> attribute can be used
|
||||
to avoid this situation.</p>
|
||||
|
||||
<p>Note that if you are defining contexts explicitly in server.xml, you
|
||||
should probably turn off automatic application deployment or specify
|
||||
<code>deployIgnore</code> carefully. Otherwise, the web applications
|
||||
will each be deployed twice, and that may cause problems for the
|
||||
applications.</p>
|
||||
|
||||
<p>There are many possible combinations of settings, new files, changed
|
||||
files and deleted files. A separate page describes the
|
||||
<a href="automatic-deployment.html">expected behaviour of the automatic
|
||||
deployment process</a> in many of these scenarios.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Host_Name_Aliases">Host Name Aliases</h4><div class="text">
|
||||
|
||||
<p>In many server environments, Network Administrators have configured
|
||||
more than one network name (in the <em>Domain Name Service</em> (DNS)
|
||||
server), that resolve to the IP address of the same server. Normally,
|
||||
each such network name would be configured as a separate
|
||||
<strong>Host</strong> element in <code>conf/server.xml</code>, each
|
||||
with its own set of web applications.</p>
|
||||
|
||||
<p>However, in some circumstances, it is desirable that two or more
|
||||
network names should resolve to the <strong>same</strong> virtual host,
|
||||
running the same set of applications. A common use case for this
|
||||
scenario is a corporate web site, where it is desirable that users
|
||||
be able to utilize either <code>www.mycompany.com</code> or
|
||||
<code>company.com</code> to access exactly the same content and
|
||||
applications.</p>
|
||||
|
||||
<p>This is accomplished by utilizing one or more <strong>Alias</strong>
|
||||
elements nested inside your <strong>Host</strong> element. For
|
||||
example:</p>
|
||||
<div class="codeBox"><pre><code><Host name="www.mycompany.com" ...>
|
||||
...
|
||||
<Alias>mycompany.com</Alias>
|
||||
...
|
||||
</Host></code></pre></div>
|
||||
|
||||
<p>In order for this strategy to be effective, all of the network names
|
||||
involved must be registered in your DNS server to resolve to the
|
||||
same computer that is running this instance of Catalina.</p>
|
||||
|
||||
<p>Aliases may also use the wildcard form (<code>*.domainname</code>),
|
||||
unlike for the <strong>name</strong> attribute of a <strong>Host</strong>.
|
||||
</p>
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Lifecycle_Listeners">Lifecycle Listeners</h4><div class="text">
|
||||
|
||||
<p>If you have implemented a Java object that needs to know when this
|
||||
<strong>Host</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 corresponding
|
||||
lifecycle events. Configuration of such a listener looks like this:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Host name="localhost" ...>
|
||||
...
|
||||
<Listener className="com.mycompany.mypackage.MyListener" ... >
|
||||
...
|
||||
</Host></code></pre></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>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Request_Filters">Request Filters</h4><div class="text">
|
||||
|
||||
<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 configured "accept" and/or "deny"
|
||||
filters, which are defined using <code>java.util.regex</code> Regular
|
||||
Expression syntax. Requests that come from locations that are
|
||||
not accepted will be rejected with an HTTP "Forbidden" error.
|
||||
Example filter declarations:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Host name="localhost" ...>
|
||||
...
|
||||
<Valve className="org.apache.catalina.valves.RemoteHostValve"
|
||||
allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
|
||||
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
|
||||
deny="192\.168\.1\.\d+"/>
|
||||
...
|
||||
</Host></code></pre></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>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Single_Sign_On">Single Sign On</h4><div class="text">
|
||||
|
||||
<p>In many environments, but particularly in portal environments, it
|
||||
is desirable to have a user challenged to authenticate themselves only
|
||||
once over a set of web applications deployed on a particular virtual
|
||||
host. This can be accomplished by nesting an element like this inside
|
||||
the Host element for this virtual host:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Host name="localhost" ...>
|
||||
...
|
||||
<Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
|
||||
...
|
||||
</Host></code></pre></div>
|
||||
|
||||
<p>The Single Sign On facility operates according to the following rules:
|
||||
</p>
|
||||
<ul>
|
||||
<li>All web applications configured for this virtual host must share the
|
||||
same <a href="realm.html">Realm</a>. In practice, that means you can
|
||||
nest the Realm element inside this Host element (or the surrounding
|
||||
<a href="engine.html">Engine</a> element), but not inside a
|
||||
<a href="context.html">Context</a> element for one of the involved
|
||||
web applications.</li>
|
||||
<li>As long as the user accesses only unprotected resources in any of the
|
||||
web applications on this virtual host, they will not be challenged
|
||||
to authenticate themselves.</li>
|
||||
<li>As soon as the user accesses a protected resource in
|
||||
<strong>any</strong> web application associated with this virtual
|
||||
host, the user will be challenged to authenticate himself or herself,
|
||||
using the login method defined for the web application currently
|
||||
being accessed.</li>
|
||||
<li>Once authenticated, the roles associated with this user will be
|
||||
utilized for access control decisions across <strong>all</strong>
|
||||
of the associated web applications, without challenging the user
|
||||
to authenticate themselves to each application individually.</li>
|
||||
<li>As soon as the user logs out of one web application (for example,
|
||||
by invalidating the corresponding session if form
|
||||
based login is used), the user's sessions in <strong>all</strong>
|
||||
web applications will be invalidated. Any subsequent attempt to
|
||||
access a protected resource in any application will require the
|
||||
user to authenticate himself or herself again.</li>
|
||||
<li>The Single Sign On feature utilizes HTTP cookies to transmit a token
|
||||
that associates each request with the saved user identity, so it can
|
||||
only be utilized in client environments that support cookies.</li>
|
||||
</ul>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="User_Web_Applications">User Web Applications</h4><div class="text">
|
||||
|
||||
<p>Many web servers can automatically map a request URI starting with
|
||||
a tilde character ("~") and a username to a directory (commonly named
|
||||
<code>public_html</code>) in that user's home directory on the server.
|
||||
You can accomplish the same thing in Catalina by using a special
|
||||
<strong>Listener</strong> element like this (on a Unix system that
|
||||
uses the <code>/etc/passwd</code> file to identify valid users):</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Host name="localhost" ...>
|
||||
...
|
||||
<Listener className="org.apache.catalina.startup.UserConfig"
|
||||
directoryName="public_html"
|
||||
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
|
||||
...
|
||||
</Host></code></pre></div>
|
||||
|
||||
<p>On a server where <code>/etc/passwd</code> is not in use, you can
|
||||
request Catalina to consider all directories found in a specified base
|
||||
directory (such as <code>c:\Homes</code> in this example) to be
|
||||
considered "user home" directories for the purposes of this directive:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Host name="localhost" ...>
|
||||
...
|
||||
<Listener className="org.apache.catalina.startup.UserConfig"
|
||||
directoryName="public_html"
|
||||
homeBase="c:\Homes"
|
||||
userClass="org.apache.catalina.startup.HomesUserDatabase"/>
|
||||
...
|
||||
</Host></code></pre></div>
|
||||
|
||||
<p>If a user home directory has been set up for a user named
|
||||
<code>craigmcc</code>, then its contents will be visible from a
|
||||
client browser by making a request to a URL like:</p>
|
||||
|
||||
<div class="codeBox"><pre><code>http://www.mycompany.com:8080/~craigmcc</code></pre></div>
|
||||
|
||||
<p>Successful use of this feature requires recognition of the following
|
||||
considerations:</p>
|
||||
<ul>
|
||||
<li>Each user web application will be deployed with characteristics
|
||||
established by the global and host level default context settings.</li>
|
||||
<li>It is legal to include more than one instance of this Listener
|
||||
element. This would only be useful, however, in circumstances
|
||||
where you wanted to configure more than one "homeBase" directory.</li>
|
||||
<li>The operating system username under which Catalina is executed
|
||||
MUST have read access to each user's web application directory,
|
||||
and all of its contents.</li>
|
||||
</ul>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Custom_context.xml_and_web.xml">Custom context.xml and web.xml</h4><div class="text">
|
||||
<p>You can override the default values found in <code>conf/context.xml</code> and
|
||||
<code>conf/web.xml</code> files from <code>$CATALINA_BASE</code> for each virtual host.
|
||||
Tomcat will look for files named <code>context.xml.default</code> and <code>web.xml.default</code>
|
||||
in the directory specified by <code>xmlBase</code> and merge the files into
|
||||
those found in the default ones.</p>
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
1831
tomcat/webapps.dist/docs/config/http.html
Normal file
1831
tomcat/webapps.dist/docs/config/http.html
Normal file
File diff suppressed because it is too large
Load Diff
243
tomcat/webapps.dist/docs/config/http2.html
Normal file
243
tomcat/webapps.dist/docs/config/http2.html
Normal file
@@ -0,0 +1,243 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The HTTP2 Upgrade Protocol</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 HTTP2 Upgrade Protocol</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>HTTP Upgrade Protocol</strong> element represents an
|
||||
<strong>Upgrade Protocol</strong> component that supports the HTTP/2 protocol.
|
||||
An instance of this component must be associated with an existing
|
||||
<a href="http.html">HTTP/1.1 Connector</a>.</p>
|
||||
|
||||
<p>HTTP/2 connectors use non-blocking I/O, only utilising a container thread
|
||||
from the thread pool when there is data to read and write. However, because
|
||||
the Servlet API is fundamentally blocking, each HTTP/2 stream requires a
|
||||
dedicated container thread for the duration of that stream.</p>
|
||||
|
||||
<p>Requests processed using HTTP/2 will have the following additional request
|
||||
attributes available:</p>
|
||||
<ul>
|
||||
<li><code>org.apache.coyote.connectionID</code> will return the HTTP/2
|
||||
connection ID</li>
|
||||
<li><code>org.apache.coyote.streamID</code> will return the HTTP/2 stream
|
||||
ID</li>
|
||||
</ul>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Upgrade Protocol</strong> support the
|
||||
following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>This must be <code>org.apache.coyote.http2.Http2Protocol</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The HTTP/2 <strong>Upgrade Protocol</strong> implementation supports the
|
||||
following attributes in addition to the common attributes listed above.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">allowedTrailerHeaders</code></td><td>
|
||||
<p>By default Tomcat will ignore all trailer headers when processing
|
||||
HTTP/2 connections. For a header to be processed, it must be added to this
|
||||
comma-separated list of header names.</p>
|
||||
</td></tr><tr><td><code class="attributeName">compressibleMimeType</code></td><td>
|
||||
<p>The value is a comma separated list of MIME types for which HTTP
|
||||
compression may be used.
|
||||
The default value is
|
||||
<code>
|
||||
text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json,application/xml
|
||||
</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">compression</code></td><td>
|
||||
<p>The HTTP/2 protocol may use compression in an attempt to save server
|
||||
bandwidth. The acceptable values for the parameter is "off" (disable
|
||||
compression), "on" (allow compression, which causes text data to be
|
||||
compressed), "force" (forces compression in all cases), or a numerical
|
||||
integer value (which is equivalent to "on", but specifies the minimum
|
||||
amount of data before the output is compressed). If the content-length is
|
||||
not known and compression is set to "on" or more aggressive, the output
|
||||
will also be compressed. If not specified, this attribute is set to
|
||||
"off".</p>
|
||||
<p><em>Note</em>: There is a tradeoff between using compression (saving
|
||||
your bandwidth) and using the sendfile feature (saving your CPU cycles).
|
||||
If the connector supports the sendfile feature, e.g. the NIO2 connector,
|
||||
using sendfile will take precedence over compression. The symptoms will
|
||||
be that static files greater that 48 Kb will be sent uncompressed.
|
||||
You can turn off sendfile by setting <code>useSendfile</code> attribute
|
||||
of the protocol, as documented below, or change the sendfile usage
|
||||
threshold in the configuration of the
|
||||
<a href="../default-servlet.html">DefaultServlet</a> in the default
|
||||
<code>conf/web.xml</code> or in the <code>web.xml</code> of your web
|
||||
application.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">compressionMinSize</code></td><td>
|
||||
<p>If <strong>compression</strong> is set to "on" then this attribute
|
||||
may be used to specify the minimum amount of data before the output is
|
||||
compressed. If not specified, this attribute is defaults to "2048".</p>
|
||||
</td></tr><tr><td><code class="attributeName">initialWindowSize</code></td><td>
|
||||
<p>Controls the initial size of the flow control window for streams that
|
||||
Tomcat advertises to clients. If not specified, the default value of
|
||||
<code>65535</code> is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">keepAliveTimeout</code></td><td>
|
||||
<p>The time, in milliseconds, that Tomcat will wait between HTTP/2 frames
|
||||
when there is no active Stream before closing the connection. Negative
|
||||
values will be treated as an infinite timeout. If not specified, a default
|
||||
value of <code>20000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxConcurrentStreamExecution</code></td><td>
|
||||
<p>The controls the maximum number of streams for any one connection that
|
||||
can be allocated threads from the container thread pool. If more streams
|
||||
are active than threads are available, those streams will have to wait
|
||||
for a stream to become available. If not specified, the default value of
|
||||
<code>20</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxConcurrentStreams</code></td><td>
|
||||
<p>The controls the maximum number of active streams permitted for any one
|
||||
connection. If a client attempts to open more active streams than this
|
||||
limit, the stream will be reset with a <code>STREAM_REFUSED</code> error.
|
||||
If not specified, the default value of <code>100</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxHeaderCount</code></td><td>
|
||||
<p>The maximum number of headers in a request that is allowed by the
|
||||
container. A request that contains more headers than the specified limit
|
||||
will be rejected. A value of less than 0 means no limit.
|
||||
If not specified, a default of 100 is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxHeaderSize</code></td><td>
|
||||
<p>The maximum total size for all headers in a request that is allowed by
|
||||
the container. Total size for a header is calculated as the uncompressed
|
||||
size of the header name in bytes, plus the uncompressed size of the header
|
||||
value in bytes plus an HTTP/2 overhead of 3 bytes per header. A request
|
||||
that contains a set of headers that requires more than the specified limit
|
||||
will be rejected. A value of less than 0 means no limit. If not specified,
|
||||
a default of 8192 is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxTrailerCount</code></td><td>
|
||||
<p>The maximum number of trailer headers in a request that is allowed by
|
||||
the container. A request that contains more trailer headers than the
|
||||
specified limit will be rejected. A value of less than 0 means no limit.
|
||||
If not specified, a default of 100 is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxTrailerSize</code></td><td>
|
||||
<p>The maximum total size for all trailer headers in a request that is
|
||||
allowed by the container. Total size for a header is calculated as the
|
||||
uncompressed size of the header name in bytes, plus the uncompressed size
|
||||
of the header value in bytes plus an HTTP/2 overhead of 3 bytes per
|
||||
header. A request that contains a set of trailer headers that requires
|
||||
more than the specified limit will be rejected. A value of less than 0
|
||||
means no limit. If not specified, a default of 8192 is used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">noCompressionStrongETag</code></td><td>
|
||||
<p>This flag configures whether resources with a stong ETag will be
|
||||
considered for compression. If <code>true</code>, resources with a strong
|
||||
ETag will not be compressed. The default value is <code>true</code>.</p>
|
||||
<p>This attribute is deprecated. It will be removed in Tomcat 10 onwards
|
||||
where it will be hard-coded to <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">noCompressionUserAgents</code></td><td>
|
||||
<p>The value is a regular expression (using <code>java.util.regex</code>)
|
||||
matching the <code>user-agent</code> header of HTTP clients for which
|
||||
compression should not be used,
|
||||
because these clients, although they do advertise support for the
|
||||
feature, have a broken implementation.
|
||||
The default value is an empty String (regexp matching disabled).</p>
|
||||
</td></tr><tr><td><code class="attributeName">overheadContinuationThreshold</code></td><td>
|
||||
<p>The threshold below which the payload size of a non-final
|
||||
<code>CONTINUATION</code> frame will trigger an increase in the overhead
|
||||
count (see <strong>overheadCountFactor</strong>). The overhead count will
|
||||
be increased by <code>overheadContinuationThreshold/payloadSize</code> so
|
||||
that the smaller the <code>CONTINUATION</code> frame, the greater the
|
||||
increase in the overhead count. A value of zero or less disables the
|
||||
checking of non-final <code>CONTINUATION</code> frames. If not specified,
|
||||
a default value of <code>1024</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">overheadCountFactor</code></td><td>
|
||||
<p>The factor to apply when counting overhead frames to determine if a
|
||||
connection has too high an overhead and should be closed. The overhead
|
||||
count starts at <code>-10 * overheadCountFactor</code>. The count is
|
||||
decreased by 20 for each data frame sent or received and each headers frame
|
||||
received. The count is increased by the <code>overheadCountFactor</code>
|
||||
for each setting received, priority frame received and ping received. If
|
||||
the overhead count exceeds zero, the connection is closed. A value of less
|
||||
than <code>1</code> disables this protection. In normal usage a value of
|
||||
approximately <code>20</code> or higher will close the connection before
|
||||
any streams can complete. If not specified, a default value of
|
||||
<code>10</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">overheadDataThreshold</code></td><td>
|
||||
<p>The threshold below which the average payload size of the current and
|
||||
previous non-final <code>DATA</code> frames will trigger an increase in
|
||||
the overhead count (see <strong>overheadCountFactor</strong>). The
|
||||
overhead count will be increased by
|
||||
<code>overheadDataThreshold/average</code> so that the smaller the
|
||||
average, the greater the increase in the overhead count. A value of zero
|
||||
or less disables the checking of non-final <code>DATA</code> frames. If
|
||||
not specified, a default value of <code>1024</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">overheadWindowUpdateThreshold</code></td><td>
|
||||
<p>The threshold below which the average size of current and previous
|
||||
<code>WINDOW_UPDATE</code> frame will trigger an increase in the overhead
|
||||
count (see <strong>overheadCountFactor</strong>). The overhead count will
|
||||
be increased by <code>overheadWindowUpdateThreshold/average</code> so
|
||||
that the smaller the average, the greater the increase in the overhead
|
||||
count. A value of zero or less disables the checking of
|
||||
<code>WINDOW_UPDATE</code> frames. If not specified, a default value of
|
||||
<code>1024</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">readTimeout</code></td><td>
|
||||
<p>The time, in milliseconds, that Tomcat will wait for additional data
|
||||
when a partial HTTP/2 frame has been received. Negative values will be
|
||||
treated as an infinite timeout. If not specified, a default value of
|
||||
<code>5000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">streamReadTimeout</code></td><td>
|
||||
<p>The time, in milliseconds, that Tomcat will wait for additional data
|
||||
frames to arrive for the stream when an application is performing a
|
||||
blocking I/O read and additional data is required. Negative values will be
|
||||
treated as an infinite timeout. If not specified, a default value of
|
||||
<code>20000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">streamWriteTimeout</code></td><td>
|
||||
<p>The time, in milliseconds, that Tomcat will wait for additional window
|
||||
update frames to arrive for the stream and/or connection when an
|
||||
application is performing a blocking I/O write and the stream and/or
|
||||
connection flow control window is too small for the write to complete.
|
||||
Negative values will be treated as an infinite timeout. If not specified,
|
||||
a default value of <code>20000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">useSendfile</code></td><td>
|
||||
<p>Use this boolean attribute to enable or disable sendfile capability.
|
||||
The default value is <code>true</code>.</p>
|
||||
<p>This setting is ignored, and the sendfile capability disabled, if the
|
||||
<strong>useAsyncIO</strong> attribute of the associated
|
||||
<strong>Connector</strong> is set to <code>false</code>.</p>
|
||||
<p>The HTTP/2 sendfile capability uses <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/nio/MappedByteBuffer.html">MappedByteBuffer</a> which is known to cause file locking on Windows.</p>
|
||||
</td></tr><tr><td><code class="attributeName">writeTimeout</code></td><td>
|
||||
<p>The time, in milliseconds, that Tomcat will wait to write additional
|
||||
data when an HTTP/2 frame has been partially written. Negative values will
|
||||
be treated as an infinite timeout. If not specified, a default value of
|
||||
<code>5000</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<p>The HTTP/2 upgrade protocol will also inherit the following limits from the
|
||||
<a href="http.html">HTTP Connector</a> it is nested with:</p>
|
||||
|
||||
<ul>
|
||||
<li>maxCookieCount</li>
|
||||
<li>maxParameterCount</li>
|
||||
<li>maxPostSize</li>
|
||||
<li>maxSavePostSize</li>
|
||||
</ul>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>This component does not support any nested components.</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<p>This component does not support any special features.</p>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
65
tomcat/webapps.dist/docs/config/index.html
Normal file
65
tomcat/webapps.dist/docs/config/index.html
Normal file
@@ -0,0 +1,65 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - Overview</title><meta name="author" content="Craig R. McClanahan"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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>Overview</h2><h3 id="Overview">Overview</h3><div class="text">
|
||||
|
||||
<p>This manual contains reference information about all of the configuration
|
||||
directives that can be included in a <code>conf/server.xml</code> file to
|
||||
configure the behavior of the Tomcat Servlet/JSP container. It does not
|
||||
attempt to describe which configuration directives should be used to perform
|
||||
specific tasks - for that, see the various <em>How-To</em> documents on the
|
||||
main index page.</p>
|
||||
|
||||
<p>Tomcat configuration files are formatted as schemaless XML; elements and
|
||||
attributes are case-sensitive. Apache Ant-style variable substitution
|
||||
is supported; a system property with the name <code>propname</code> may be
|
||||
used in a configuration file using the syntax <code>${propname}</code>. All
|
||||
system properties are available including those set using the <code>-D</code>
|
||||
syntax, those automatically made available by the JVM and those configured in
|
||||
the <code>$CATALINA_BASE/conf/catalina.properties</code> file.
|
||||
</p>
|
||||
|
||||
<p>The configuration element descriptions are organized into the following
|
||||
major categories:</p>
|
||||
<ul>
|
||||
<li><strong>Top Level Elements</strong> - <code><Server></code> is the
|
||||
root element of the entire configuration file, while
|
||||
<code><Service></code> represents a group of Connectors that is
|
||||
associated with an Engine.</li>
|
||||
<li><strong>Connectors</strong> - Represent the interface between external
|
||||
clients sending requests to (and receiving responses from) a particular
|
||||
Service.</li>
|
||||
<li><strong>Containers</strong> - Represent components whose function is to
|
||||
process incoming requests, and create the corresponding responses.
|
||||
An Engine handles all requests for a Service, a Host handles all requests
|
||||
for a particular virtual host, and a Context handles all requests for a
|
||||
specific web application.</li>
|
||||
<li><strong>Nested Components</strong> - Represent elements that can be
|
||||
nested inside the element for a Container. Some elements can be nested
|
||||
inside any Container, while others can only be nested inside a
|
||||
Context.</li>
|
||||
</ul>
|
||||
|
||||
<p>For each element, the corresponding documentation follows this general
|
||||
outline:</p>
|
||||
<ul>
|
||||
<li><strong>Introduction</strong> - Overall description of this particular
|
||||
component. There will be a corresponding Java <em>interface</em> (in
|
||||
the <code>org.apache.catalina</code> package) that is implemented by one
|
||||
or more standard implementations.</li>
|
||||
<li><strong>Attributes</strong> - The set of attributes that are legal for
|
||||
this element. Generally, this will be subdivided into <em>Common</em>
|
||||
attributes that are supported by all implementations of the corresponding
|
||||
Java interface, and <em>Standard Implementation</em> attributes that are
|
||||
specific to a particular Java class that implements this interface.
|
||||
The names of required attributes are <strong>bolded</strong>.</li>
|
||||
<li><strong>Nested Components</strong> - Enumerates which of the <em>Nested
|
||||
Components</em> can be legally nested within this element.</li>
|
||||
<li><strong>Special Features</strong> - Describes the configuration of a large
|
||||
variety of special features (specific to each element type) that are
|
||||
supported by the standard implementation of this interface.</li>
|
||||
</ul>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
141
tomcat/webapps.dist/docs/config/jar-scan-filter.html
Normal file
141
tomcat/webapps.dist/docs/config/jar-scan-filter.html
Normal file
@@ -0,0 +1,141 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Jar Scan Filter Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Jar Scan Filter Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Jar Scan Filter</strong> element represents the component that
|
||||
filters results from the <a href="jar-scanner.html">Jar Scanner</a> before
|
||||
they are passed back to the application. It is typically used to skip the
|
||||
scanning of JARs that are known not to be relevant to some or all types of
|
||||
scan.</p>
|
||||
|
||||
<p>A Jar Scan Filter element MAY be nested inside a
|
||||
<a href="jar-scanner.html">Jar Scanner</a> component.</p>
|
||||
|
||||
<p>For example you can specify additional jar files when scanning for pluggable
|
||||
features:</p>
|
||||
<div class="codeBox"><pre><code><Context>
|
||||
...
|
||||
<JarScanner>
|
||||
<JarScanFilter
|
||||
pluggabilityScan="${tomcat.util.scan.StandardJarScanFilter.jarsToScan},
|
||||
my_pluggable_feature.jar"/>
|
||||
</JarScanner>
|
||||
...
|
||||
</Context></code></pre></div>
|
||||
|
||||
<p>If a Jar Scan Filter element is not included, a default Jar Scan Filter
|
||||
configuration will be created automatically, which is sufficient for most
|
||||
requirements.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Jar Scan Filter</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.tomcat.JarScanFilter</code> interface.
|
||||
If not specified, the standard value (defined below) will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>Jar Scan Filter</strong> is
|
||||
<strong>org.apache.tomcat.util.scan.StandardJarScanFilter</strong>.
|
||||
Additional attributes that it supports (in addition to the common attributes
|
||||
listed above) are listed in the table.</p>
|
||||
|
||||
<p>The values for <strong>pluggabilitySkip</strong>,
|
||||
<strong>pluggabilityScan</strong>, <strong>tldSkip</strong>,
|
||||
<strong>tldScan</strong> attributes are lists of file name pattern. The
|
||||
patterns are separated by comma (','). The leading and trailing whitespace
|
||||
characters in a pattern are ignored. The patterns are matched
|
||||
case-sensitively. The following two special characters are supported:</p>
|
||||
|
||||
<ul>
|
||||
<li>'*' - means zero or more characters,</li>
|
||||
<li>'?' - means one and only one character.</li>
|
||||
</ul>
|
||||
|
||||
<p>Note that excluding a JAR from the pluggability scan will prevent a
|
||||
ServletContainerInitializer from being loaded from a web application JAR
|
||||
(i.e. one located in <code>/WEB-INF/lib</code>) but it will not prevent
|
||||
a ServletContainerInitializer from being loaded from the container (Tomcat).
|
||||
To prevent a ServletContainerInitializer provided by container from being
|
||||
loaded, use the <code>containerSciFilter</code> property of the
|
||||
<a href="context.html">Context</a>.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">pluggabilitySkip</code></td><td>
|
||||
<p>The comma separated list of JAR file name patterns
|
||||
to skip when scanning for pluggable features introduced by Servlet 3.0
|
||||
specification. If not specified, the default is obtained from the
|
||||
<code>tomcat.util.scan.StandardJarScanFilter.jarsToSkip</code> system
|
||||
property.</p>
|
||||
</td></tr><tr><td><code class="attributeName">pluggabilityScan</code></td><td>
|
||||
<p>The comma separated list of JAR file name patterns
|
||||
to scan when scanning for pluggable features introduced by Servlet 3.0
|
||||
specification. If not specified, the default is obtained from the
|
||||
<code>tomcat.util.scan.StandardJarScanFilter.jarsToScan</code> system
|
||||
property.</p>
|
||||
</td></tr><tr><td><code class="attributeName">defaultPluggabilityScan</code></td><td>
|
||||
<p>Controls if JARs are scanned or skipped by default when scanning
|
||||
for the pluggable features.
|
||||
If <code>true</code>, a JAR is scanned when its name either matches
|
||||
none of <strong>pluggabilitySkip</strong> patterns or
|
||||
any of <strong>pluggabilityScan</strong> patterns.
|
||||
If <code>false</code>, a JAR is scanned when its name matches
|
||||
any of <strong>pluggabilityScan</strong> patterns and
|
||||
none of <strong>pluggabilitySkip</strong> patterns.
|
||||
If not specified, the default value is <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">tldSkip</code></td><td>
|
||||
<p>The comma separated list of JAR file name patterns
|
||||
to skip when scanning for tag libraries (TLDs).
|
||||
If not specified, the default is obtained
|
||||
from the <code>tomcat.util.scan.StandardJarScanFilter.jarsToSkip</code>
|
||||
system property.</p>
|
||||
</td></tr><tr><td><code class="attributeName">tldScan</code></td><td>
|
||||
<p>The comma separated list of JAR file name patterns
|
||||
to scan when scanning for tag libraries (TLDs).
|
||||
If not specified, the default is obtained
|
||||
from the <code>tomcat.util.scan.StandardJarScanFilter.jarsToScan</code>
|
||||
system property.</p>
|
||||
</td></tr><tr><td><code class="attributeName">defaultTldScan</code></td><td>
|
||||
<p>Controls if JARs are scanned or skipped by default when scanning
|
||||
for TLDs.
|
||||
If <code>true</code>, a JAR is scanned when its name either matches
|
||||
none of <strong>tldSkip</strong> patterns or
|
||||
any of <strong>tldScan</strong> patterns.
|
||||
If <code>false</code>, a JAR is scanned when its name matches
|
||||
any of <strong>tldScan</strong> patterns and
|
||||
none of <strong>tldSkip</strong> patterns.
|
||||
If not specified, the default value is <code>true</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
<p>No components may be nested inside a <strong>Jar Scan Filter</strong> element.
|
||||
</p>
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
<p>No special features are associated with a <strong>Jar Scan Filter</strong>
|
||||
element.</p>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
99
tomcat/webapps.dist/docs/config/jar-scanner.html
Normal file
99
tomcat/webapps.dist/docs/config/jar-scanner.html
Normal file
@@ -0,0 +1,99 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Jar Scanner Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Jar Scanner Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Jar Scanner</strong> element represents the component that is
|
||||
used to scan the web application for JAR files and directories of class files.
|
||||
It is typically used during web application start to identify configuration
|
||||
files such as TLDs or web-fragment.xml files that must be processed as part of
|
||||
the web application initialisation.</p>
|
||||
|
||||
<p>A Jar Scanner element MAY be nested inside a
|
||||
<a href="context.html">Context</a> component.</p>
|
||||
|
||||
<p>For example you can include the bootstrap classpath when scanning for jar
|
||||
files:</p>
|
||||
<div class="codeBox"><pre><code><Context>
|
||||
...
|
||||
<JarScanner scanBootstrapClassPath="true"/>
|
||||
...
|
||||
</Context></code></pre></div>
|
||||
|
||||
<p>If a Jar Scanner element is not included, a default Jar Scanner configuration
|
||||
will be created automatically, which is sufficient for most requirements.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Jar Scanner</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.tomcat.JarScanner</code> interface.
|
||||
If not specified, the standard value (defined below) will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>Jar Scanner</strong> is
|
||||
<strong>org.apache.tomcat.util.scan.StandardJarScanner</strong>.
|
||||
It supports the following additional attributes (in addition to the
|
||||
common attributes listed above):</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">scanAllDirectories</code></td><td>
|
||||
<p>If <code>true</code>, any directories found on the classpath will be
|
||||
checked to see if they are expanded JAR files.
|
||||
The default is <code>false</code>.</p>
|
||||
<p>Tomcat determines if a directory is an expanded JAR file by looking
|
||||
for a META-INF sub-directory. Only if the META-INF sub-directory exists,
|
||||
the directory is assumed to be an expanded JAR file. Note that for scans
|
||||
for matches to <code>@HandlesTypes</code> annotations, all directories
|
||||
will be scanned irrespective of the presence or not of a META-INF
|
||||
sub-directory.</p>
|
||||
</td></tr><tr><td><code class="attributeName">scanAllFiles</code></td><td>
|
||||
<p>If <code>true</code>, any files found on the classpath will be checked
|
||||
to see if they are Jar files rather than relying on the file extension
|
||||
being <code>.jar</code>. The default is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">scanClassPath</code></td><td>
|
||||
<p>If <code>true</code>, the full web application classpath, including
|
||||
the shared and common classloaders and the system classpath (but not the
|
||||
bootstrap classpath) will be scanned for Jar files in addition to the web
|
||||
application. The default is <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">scanBootstrapClassPath</code></td><td>
|
||||
<p>If <strong>scanClassPath</strong> is <code>true</code> and this is
|
||||
<code>true</code> the bootstrap classpath will also be scanned for Jar
|
||||
files. The default is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">scanManifest</code></td><td>
|
||||
<p>If <code>true</code>, the Manifest files of any JARs found will be
|
||||
scanned for additional class path entries and those entries will be added
|
||||
to the URLs to scan. The default is <code>true</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
<p>Only a <a href="jar-scan-filter.html">Jar Scan Filter</a> may be nested
|
||||
inside a <strong>Jar Scanner</strong> element.</p>
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
<p>No special features are associated with a <strong>Jar Scanner</strong>
|
||||
element.</p>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
162
tomcat/webapps.dist/docs/config/jaspic.html
Normal file
162
tomcat/webapps.dist/docs/config/jaspic.html
Normal file
@@ -0,0 +1,162 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - JASPIC</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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>JASPIC</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Static_configuration">Static configuration</a><ol><li><a href="#AuthConfigProvider">AuthConfigProvider</a></li><li><a href="#ServerAuthModule">ServerAuthModule</a></li></ol></li><li><a href="#Dynamic_configuration">Dynamic configuration</a></li><li><a href="#3rd_party_modules">3rd party modules</a><ol><li><a href="#Philip_Green_II's_module_for_Google_OAuth_2">Philip Green II's module for Google OAuth 2</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>Tomcat implements JASPIC 1.1 Maintenance Release B
|
||||
(<a href="https://www.jcp.org/en/jsr/detail?id=196">JSR 196</a>). The
|
||||
implementation is primarily intended to enable the integration of 3rd party
|
||||
JASPIC authentication implementations with Tomcat.</p>
|
||||
|
||||
<p>JASPIC may be configured in one of two ways:</p>
|
||||
<ul>
|
||||
<li>At the container level via the static configuration file
|
||||
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>. With this
|
||||
approach all required classes must be visible to Tomcat's Common class
|
||||
loader which normally means placing a JAR in
|
||||
<code>$CATALINA_BASE/lib</code>.</li>
|
||||
<li>At the web application level via dynamic configuration using the JASPIC
|
||||
API. With this approach all required classes must be visible to the web
|
||||
application class loader which normally means placing a JAR in the web
|
||||
application's <code>WEB-INF/lib</code> directory.</li>
|
||||
</ul>
|
||||
|
||||
<p>Users should be aware that if the static JASPIC configuration file
|
||||
configures JASPIC for a given web application then the JASPIC configuration
|
||||
will take precedence over any <code><login-config></code> present in
|
||||
the web application's <code>WEB-INF/web.xml</code> file.</p>
|
||||
|
||||
</div><h3 id="Static_configuration">Static configuration</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="AuthConfigProvider">AuthConfigProvider</h4><div class="text">
|
||||
|
||||
<p>If the 3rd party implementation includes an
|
||||
<code>AuthConfigProvider</code> then a web application can be configured to
|
||||
use it by nesting the following inside the
|
||||
<code><jaspic-providers></code> element in
|
||||
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
|
||||
<div class="codeBox"><pre><code><provider name="any"
|
||||
className="fully.qualified.implementation.class.Name"
|
||||
layer="HttpServlet"
|
||||
appContext="Catalina/localhost /contextPath"
|
||||
description="any">
|
||||
<property name="see-provider-documentation"
|
||||
value="see-provider-documentation" />
|
||||
</provider></code></pre></div>
|
||||
|
||||
<p>The <code>name</code> and <code>description</code> attributes are not
|
||||
used by Tomcat.</p>
|
||||
|
||||
<p>The <code>className</code> attribute must be the fully qualified class
|
||||
name of the <code>AuthConfigProvider</code>. The implementation may be
|
||||
packaged with the web application or in Tomcat's
|
||||
<code>$CATALINA_BASE/lib</code> directory.</p>
|
||||
|
||||
<p>The <code>layer</code> attribute must be <code>HttpServlet</code>.</p>
|
||||
|
||||
<p>The <code>appContext</code> attribute must be exactly the concatenation
|
||||
of:</p>
|
||||
<ul>
|
||||
<li>The engine name</li>
|
||||
<li>The forward slash character</li>
|
||||
<li>The host name</li>
|
||||
<li>A single space</li>
|
||||
<li>The context path</li>
|
||||
</ul>
|
||||
|
||||
<p>If the <code>AuthConfigProvider</code> supports configuration via
|
||||
properties these may be specified via <code><property></code> elements
|
||||
nesting inside the <code><provide></code> element.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="ServerAuthModule">ServerAuthModule</h4><div class="text">
|
||||
|
||||
<p>If the 3rd party implementation only provides an
|
||||
<code>ServerAuthModule</code> then it will be necessary to provide a number
|
||||
of supporting classes. These may be a custom implementation or,
|
||||
alternatively, Tomcat provides a simple wrapper implementation for
|
||||
<code>ServerAuthModule</code>s.
|
||||
</p>
|
||||
|
||||
<p>Tomcat's wrapper for <code>ServerAuthModule</code> can be configured
|
||||
by nesting the following inside the
|
||||
<code><jaspic-providers></code> element in
|
||||
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
|
||||
<div class="codeBox"><pre><code><provider name="any"
|
||||
className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
|
||||
layer="HttpServlet"
|
||||
appContext="Catalina/localhost /contextPath"
|
||||
description="any">
|
||||
<property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
|
||||
value="fully.qualified.implementation.class.Name" />
|
||||
<property name="see-provider-documentation"
|
||||
value="see-provider-documentation" />
|
||||
</provider></code></pre></div>
|
||||
|
||||
<p>The configuration is similar to the <code>AuthConfigProvider</code> in
|
||||
the previous section but with some key differences.</p>
|
||||
|
||||
<p>The <code>className</code> attribute must be
|
||||
<code>org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider</code>.</p>
|
||||
|
||||
<p>The <code>ServerAuthModule</code>(s) are specified via properties. The
|
||||
property name must be
|
||||
<code>org.apache.catalina.authenticator.jaspic.ServerAuthModule.n</code>
|
||||
where <code>n</code> is the index of the module. The index must start at 1
|
||||
an increment in steps of 1 until all modules are defined. The value of the
|
||||
property must be the fully qualified class name of the module.</p>
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Dynamic_configuration">Dynamic configuration</h3><div class="text">
|
||||
|
||||
<p>JASPIC modules and configuration can be packaged within a WAR file with the
|
||||
web application. The web application can then register the required JASPIC
|
||||
configuration when it starts using the standard JASPIC APIs.</p>
|
||||
|
||||
<p>If parallel deployment is being used then dynamic configuration should not
|
||||
be used. The JASPIC API assumes that a context path is unique for any given
|
||||
host which is not the case when using parallel deployment. When using parallel
|
||||
deployment, static JASPIC configuration should be used. This will require that
|
||||
all versions of the application use the same JASPIC configuration.</p>
|
||||
|
||||
</div><h3 id="3rd_party_modules">3rd party modules</h3><div class="text">
|
||||
|
||||
<p>This is not an exhaustive list. The Tomcat community welcomes contributions
|
||||
that add to this section.</p>
|
||||
|
||||
<div class="subsection"><h4 id="Philip_Green_II's_module_for_Google_OAuth_2">Philip Green II's module for Google OAuth 2</h4><div class="text">
|
||||
|
||||
<p>The source code for this module along with the
|
||||
<a href="https://github.com/phillipgreenii/google-oauth-2.0-serverauthmodule">documentation</a>
|
||||
which includes details of the necessary Google API configuration is
|
||||
available on GitHub.</p>
|
||||
|
||||
<p>A sample configuration for using this module with Tomcat would look like
|
||||
this:</p>
|
||||
<div class="codeBox"><pre><code><jaspic-providers xmlns="https://tomcat.apache.org/xml"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="https://tomcat.apache.org/xml jaspic-providers.xsd"
|
||||
version="1.0">
|
||||
<provider name="google-oauth"
|
||||
className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
|
||||
layer="HttpServlet"
|
||||
appContext="Catalina/localhost /contextPath"
|
||||
description="Google OAuth test">
|
||||
<property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
|
||||
value="com.idmworks.security.google.GoogleOAuthServerAuthModule" />
|
||||
<property name="oauth.clientid"
|
||||
value="obtained-from-Google-console" />
|
||||
<property name="oauth.clientsecret"
|
||||
value="obtained-from-Google-console" />
|
||||
<property name="ignore_missing_login_context"
|
||||
value="true" />
|
||||
</provider>
|
||||
</jaspic-providers></code></pre></div>
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
481
tomcat/webapps.dist/docs/config/listeners.html
Normal file
481
tomcat/webapps.dist/docs/config/listeners.html
Normal file
@@ -0,0 +1,481 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The LifeCycle Listener Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 LifeCycle Listener Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Standard_Implementations">Standard Implementations</a><ol><li><a href="#APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener</a></li><li><a href="#Global_Resources_Lifecycle_Listener_-_org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener</a></li><li><a href="#JNI_Library_Loading_Listener_-_org.apache.catalina.core.JniLifecycleListener">JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener</a></li><li><a href="#JRE_Memory_Leak_Prevention_Listener_-_org.apache.catalina.core.JreMemoryLeakPreventionListener">JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener</a><ol><li><a href="#JreMemoryLeakPreventionListener_Examples">JreMemoryLeakPreventionListener Examples</a></li></ol></li><li><a href="#Security_Lifecycle_Listener_-_org.apache.catalina.security.SecurityListener">Security Lifecycle Listener - org.apache.catalina.security.SecurityListener</a></li><li><a href="#StoreConfig_Lifecycle_Listener_-_org.apache.catalina.storeconfig.StoreConfigLifecycleListener">StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener</a></li><li><a href="#ThreadLocal_Leak_Prevention_Listener_-_org.apache.catalina.core.ThreadLocalLeakPreventionListener">ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener</a></li><li><a href="#UserConfig_-_org.apache.catalina.startup.UserConfig">UserConfig - org.apache.catalina.startup.UserConfig</a></li><li><a href="#Version_Logging_Lifecycle_Listener_-_org.apache.catalina.startup.VersionLoggerListener">Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener</a></li><li><a href="#HTTPD_mod_heartmonitor_Listener_-_org.apache.catalina.ha.backend.HeartbeatListener">HTTPD mod_heartmonitor Listener - org.apache.catalina.ha.backend.HeartbeatListener</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>A <strong>Listener</strong> element defines a component that performs
|
||||
actions when specific events occur, usually Tomcat starting or Tomcat
|
||||
stopping.</p>
|
||||
|
||||
<p>Listeners may be nested inside a <a href="server.html">Server</a>,
|
||||
<a href="engine.html">Engine</a>, <a href="host.html">Host</a> or
|
||||
<a href="context.html">Context</a>. Some Listeners are only intended to be
|
||||
nested inside specific elements. These constraints are noted in the
|
||||
documentation below.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Listener</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.LifecycleListener</code>
|
||||
interface.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>No element may be nested inside a <strong>Listener</strong>.</p>
|
||||
|
||||
</div><h3 id="Standard_Implementations">Standard Implementations</h3><div class="text">
|
||||
|
||||
<p>Unlike most Catalina components, there are several standard
|
||||
<strong>Listener</strong> implementations available. As a result,
|
||||
the <code>className</code> attribute MUST be used to select the
|
||||
implementation you wish to use.</p>
|
||||
|
||||
<div class="subsection"><h4 id="APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
|
||||
the APR/native library and loads the library if it is present. For more
|
||||
information see the <a href="../apr.html">APR/native guide</a>.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the <strong>APR
|
||||
Lifecycle Listener</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">SSLEngine</code></td><td>
|
||||
<p>Name of the SSLEngine to use. <code>off</code>: do not use SSL,
|
||||
<code>on</code>: use SSL but no specific ENGINE.</p>
|
||||
<p>The default value is <b>on</b>. This initializes the
|
||||
native SSL engine, which must be enabled in the APR/native connector by
|
||||
the use of the <code>SSLEnabled</code> attribute.</p>
|
||||
<p>See the <a href="http://www.openssl.org/">Official OpenSSL website</a>
|
||||
for more details on supported SSL hardware engines and manufacturers.
|
||||
</p>
|
||||
<p>Tomcat Native 2.x onwards requires SSL so if SSLEngine is set to
|
||||
<code>off</code> when using Tomcat Native 2.x onwards, the APR/native
|
||||
library will be disabled.</p>
|
||||
</td></tr><tr><td><code class="attributeName">SSLRandomSeed</code></td><td>
|
||||
<p>Entropy source used to seed the SSLEngine's PRNG. The default value
|
||||
is <code>builtin</code>. On development systems, you may want to set
|
||||
this to <code>/dev/urandom</code> to allow quicker start times.</p>
|
||||
</td></tr><tr><td><code class="attributeName">FIPSMode</code></td><td>
|
||||
<p>The behaviour of this attribute depends on whether Tomcat Native has
|
||||
been compiled against OpenSSL 1.x or OpenSSL 3.x.</p>
|
||||
<p>For OpenSSL 1.x: Set to <code>on</code> to request that OpenSSL be in
|
||||
FIPS mode (if OpenSSL is already in FIPS mode, it will remain in FIPS
|
||||
mode).
|
||||
Set to <code>enter</code> to force OpenSSL to enter FIPS mode (an
|
||||
error will occur if OpenSSL is already in FIPS mode).
|
||||
Set to <code>require</code> to require that OpenSSL <i>already</i> be
|
||||
in FIPS mode (an error will occur if OpenSSL is not already in FIPS
|
||||
mode).</p>
|
||||
<p>For OpenSSL 3.x: <code>on</code>, <code>enter</code> and
|
||||
<code>require</code> all behave the same way. If the FIPS provider is
|
||||
the default provider, it will be used. If the FIPS provider is not the
|
||||
default provider, an error will occur.</p>
|
||||
<p>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library</em>.
|
||||
If this attribute is set to anything other than <code>off</code>, the
|
||||
<b>SSLEngine</b> must be enabled as well.</p>
|
||||
<p>The default value is <code>off</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">useAprConnector</code></td><td>
|
||||
<p>This attribute controls the auto-selection of the connector
|
||||
implementation. When the <strong>protocol</strong> is specified as
|
||||
<code>HTTP/1.1</code> or <code>AJP/1.3</code> then if this attribute is
|
||||
<code>true</code> the APR/native connector will be used but if this
|
||||
attribute is false the NIO connector will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">useOpenSSL</code></td><td>
|
||||
<p>This attribute controls the auto-selection of the OpenSSL JSSE
|
||||
implementation. The default is <code>true</code> which will use OpenSSL
|
||||
if the native library is available and a NIO or NIO2 connector is used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Global_Resources_Lifecycle_Listener_-_org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
|
||||
Global JNDI resources defined in server.xml as part of the <a href="globalresources.html">Global Resources</a> element. Without this
|
||||
listener, none of the Global Resources will be available.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements.</p>
|
||||
|
||||
<p>No additional attributes are supported by the <strong>Global Resources
|
||||
Lifecycle Listener</strong>.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="JNI_Library_Loading_Listener_-_org.apache.catalina.core.JniLifecycleListener">JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>JNI Library Loading Listener</strong> makes it possible
|
||||
for multiple Webapps to use a native library, by loading the native
|
||||
library using a shared class loader (typically the Common class loader but
|
||||
may vary in some configurations)</p>
|
||||
|
||||
<p>The listener supports two mutually exclusive attributes, so one of them must be used, but you can not use both together:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">libraryName</code></td><td>
|
||||
<p>The name of the native library, as defined in
|
||||
<code>java.lang.System.loadLibrary()</code>
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">libraryPath</code></td><td>
|
||||
<p>The absolute path of the native library, as defined in
|
||||
<code>java.lang.System.load()</code>
|
||||
</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="JRE_Memory_Leak_Prevention_Listener_-_org.apache.catalina.core.JreMemoryLeakPreventionListener">JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>JRE Memory Leak Prevention Listener</strong> provides
|
||||
work-arounds for known places where the Java Runtime environment uses
|
||||
the context class loader to load a singleton as this will cause a memory
|
||||
leak if a web application class loader happens to be the context class
|
||||
loader at the time. The work-around is to initialise these singletons when
|
||||
this listener starts as Tomcat's common class loader is the context class
|
||||
loader at that time. It also provides work-arounds for known issues that
|
||||
can result in locked JAR files.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the <strong>JRE
|
||||
Memory Leak Prevention Listener</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">appContextProtection</code></td><td>
|
||||
<p>Enables protection so that calls to
|
||||
<code>sun.awt.AppContext.getAppContext()</code> triggered by a web
|
||||
application do not result in a memory leak. Note that enabling this
|
||||
protection will trigger a requirement for a graphical environment unless
|
||||
Java is started in head-less mode. The default is <code>false</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">AWTThreadProtection</code></td><td>
|
||||
<p>Enables protection so that calls to
|
||||
<code>java.awt.Toolkit.getDefaultToolkit()</code> triggered by a web
|
||||
application do not result in a memory leak.
|
||||
Defaults to <code>false</code> because an AWT thread is launched. This
|
||||
protection is disabled if running on Java 9 onwards since the leak has
|
||||
been fixed for Java 9 onwards.</p>
|
||||
</td></tr><tr><td><code class="attributeName">classesToInitialize</code></td><td>
|
||||
<p>List of comma-separated fully qualified class names to load and initialize
|
||||
during the startup of this Listener. This allows to pre-load classes that are
|
||||
known to provoke classloader leaks if they are loaded during a request
|
||||
processing. Non-JRE classes may be referenced, like
|
||||
<code>oracle.jdbc.driver.OracleTimeoutThreadPerVM</code>.
|
||||
The default value is empty, but specific JRE classes are loaded by other leak
|
||||
protection features managed by other attributes of this Listener.</p>
|
||||
</td></tr><tr><td><code class="attributeName">driverManagerProtection</code></td><td>
|
||||
<p>The first use of <code>java.sql.DriverManager</code> will trigger the
|
||||
loading of JDBC Drivers visible to the current class loader and its
|
||||
parents. The web application level memory leak protection can take care
|
||||
of this in most cases but triggering the loading here has fewer
|
||||
side-effects. The default is <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">forkJoinCommonPoolProtection</code></td><td>
|
||||
<p>Enables protection so the threads created for
|
||||
<code>ForkJoinPool.commonPool()</code> do not result in a memory leak.
|
||||
The protection is enabled by setting the
|
||||
<code>java.util.concurrent.ForkJoinPool.common.threadFactory</code>
|
||||
system property. If this property is set when Tomcat starts, Tomcat will
|
||||
not over-ride it even if this protection is explicitly enabled. The
|
||||
default is <code>true</code>. This protection is disabled if running on
|
||||
Java 9 onwards since the leak has been fixed for Java 9 onwards.</p>
|
||||
</td></tr><tr><td><code class="attributeName">gcDaemonProtection</code></td><td>
|
||||
<p>Enables protection so that calls to
|
||||
<code>sun.misc.GC.requestLatency(long)</code> triggered by a web
|
||||
application do not result in a memory leak. Use of RMI is likely to
|
||||
trigger a call to this method. A side effect of enabling this protection
|
||||
is the creation of a thread named "GC Daemon". The protection uses
|
||||
reflection to access internal Sun classes and may generate errors on
|
||||
startup on non-Sun JVMs. The default is <code>true</code>. This
|
||||
protection is disabled if running on Java 9 onwards since the leak has
|
||||
been fixed for Java 9 onwards.</p>
|
||||
</td></tr><tr><td><code class="attributeName">initSeedGenerator</code></td><td>
|
||||
<p>The first use of <code>SeedGenerator</code>, an internal class of
|
||||
the default security spi implementation, might create a thread on some
|
||||
platforms. Depending on the timing of the first use of a secure random
|
||||
this thread might become associated with a webapp classloader, causing
|
||||
a memory leak. Setting this to <code>true</code> will initialize the
|
||||
seed. The default is <code>false</code> to avoid consuming random if
|
||||
not needed.</p>
|
||||
</td></tr><tr><td><code class="attributeName">ldapPoolProtection</code></td><td>
|
||||
<p>Enables protection so that the PoolCleaner thread started by
|
||||
<code>com.sun.jndi.ldap.LdapPoolManager</code> does not result in a
|
||||
memory leak. The thread is started the first time the
|
||||
<code>LdapPoolManager</code> class is used if the system property
|
||||
<code>com.sun.jndi.ldap.connect.pool.timeout</code> is set to a value
|
||||
greater than 0. Without this protection, if a web application uses this
|
||||
class the PoolCleaner thread will be configured with the thread's
|
||||
context class loader set to the web application class loader which in
|
||||
turn will trigger a memory leak on reload. Defaults to
|
||||
<code>true</code>. This protection is disabled if running on Java 9
|
||||
onwards since the leak has been fixed for Java 9 onwards.</p>
|
||||
</td></tr><tr><td><code class="attributeName">tokenPollerProtection</code></td><td>
|
||||
<p>Enables protection so that any token poller thread initialized by
|
||||
<code>sun.security.pkcs11.SunPKCS11.initToken()</code> does not
|
||||
result in a memory leak. The thread is started depending on various
|
||||
conditions as part of the initialization of the Java Cryptography
|
||||
Architecture. Without the protection this can happen during Webapp
|
||||
deployment when the MessageDigest for generating session IDs is
|
||||
initialized. As a result the thread has the Webapp class loader as its
|
||||
thread context class loader. Enabling the protection initializes JCA
|
||||
early during Tomcat startup. Defaults to <code>true</code>. This
|
||||
protection is disabled if running on Java 9 onwards since the leak has
|
||||
been fixed for Java 9 onwards.</p>
|
||||
</td></tr><tr><td><code class="attributeName">urlCacheProtection</code></td><td>
|
||||
<p>Enables protection so that reading resources from JAR files using
|
||||
<code>java.net.URLConnection</code>s does not result in the JAR file
|
||||
being locked. Note that enabling this protection disables caching by
|
||||
default for all resources obtained via
|
||||
<code>java.net.URLConnection</code>s. Caching may be re-enabled on a
|
||||
case by case basis as required. Defaults to <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">xmlParsingProtection</code></td><td>
|
||||
<p>Enables protection so that parsing XML files within a web application
|
||||
does not result in a memory leak. Note that memory profilers may not
|
||||
display the GC root associated with this leak making it particularly
|
||||
hard to diagnose. Defaults to <code>true</code>. This protection is
|
||||
disabled if running on Java 9 onwards since the leak has been fixed for
|
||||
Java 9 onwards.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<div class="subsection"><h4 id="JreMemoryLeakPreventionListener_Examples">JreMemoryLeakPreventionListener Examples</h4><div class="text">
|
||||
|
||||
<p>The following is an example of how to configure the
|
||||
<code>classesToInitialize</code> attribute of this listener.</p>
|
||||
|
||||
<p>If this listener was configured in server.xml as:</p>
|
||||
|
||||
<div class="codeBox"><pre><code> <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
|
||||
classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" /></code></pre></div>
|
||||
|
||||
<p>then the <code>OracleTimeoutThreadPerVM</code> class would be loaded
|
||||
and initialized during listener startup instead of during request
|
||||
processing.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Security_Lifecycle_Listener_-_org.apache.catalina.security.SecurityListener">Security Lifecycle Listener - org.apache.catalina.security.SecurityListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>Security Lifecycle Listener</strong> performs a number of
|
||||
security checks when Tomcat starts and prevents Tomcat from starting if they
|
||||
fail. The listener is not enabled by default. To enabled it uncomment the
|
||||
listener in $CATALINA_BASE/conf/server.xml. For Tomcat versions before 9.0.7,
|
||||
if the operating system supports umask then the line in
|
||||
$CATALINA_HOME/bin/catalina.sh that obtains the umask also needs to be
|
||||
uncommented. For Tomcat 9.0.7 and later, the umask is automatically
|
||||
passed-into Tomcat.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the <strong>Security
|
||||
Lifecycle Listener</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">checkedOsUsers</code></td><td>
|
||||
<p>A comma separated list of OS users that must not be used to start
|
||||
Tomcat. If not specified, the default value of <b>root</b> is used. To
|
||||
disable this check, set the attribute to the empty string. Usernames
|
||||
are checked in a case-insensitive manner.</p>
|
||||
</td></tr><tr><td><code class="attributeName">minimumUmask</code></td><td>
|
||||
<p>The least restrictive umask that must be configured before Tomcat
|
||||
will start. If not specified, the default value of <b>0007</b> is used.
|
||||
To disable this check, set the attribute to the empty string. The check
|
||||
is not performed on Windows platforms.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="StoreConfig_Lifecycle_Listener_-_org.apache.catalina.storeconfig.StoreConfigLifecycleListener">StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>StoreConfig Lifecycle Listener</strong> configures a
|
||||
StoreConfig MBean that may be used to save the current server configuration
|
||||
in server.xml or the current configuration for a web application in a
|
||||
context.xml file.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the
|
||||
<strong>StoreConfig Lifecycle Listener</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">storeConfigClass</code></td><td>
|
||||
<p>The name of the <code>IStoreConfig</code> implementation to use. If
|
||||
not specified the default of
|
||||
<code>org.apache.catalina.storeconfig.StoreConfig</code> will be
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">storeRegistry</code></td><td>
|
||||
<p>The URL of the configuration file that configures how the
|
||||
<code>IStoreConfig</code> is to save the configuration. If not specified
|
||||
the built in resource
|
||||
<code>/org/apache/catalina/storeconfig/server-registry.xml</code> will
|
||||
be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="ThreadLocal_Leak_Prevention_Listener_-_org.apache.catalina.core.ThreadLocalLeakPreventionListener">ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>ThreadLocal Leak Prevention Listener</strong> triggers the
|
||||
renewal of threads in <a href="executor.html">Executor</a> pools when a
|
||||
<a href="context.html">Context</a> is being stopped to avoid thread-local
|
||||
related memory leaks. Active threads will be renewed one by one when they
|
||||
come back to the pool after executing their task. The renewal happens
|
||||
only for contexts that have their <code>renewThreadsWhenStoppingContext</code>
|
||||
attribute set to <code>true</code>.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements.</p>
|
||||
|
||||
<p>No additional attributes are supported by the <strong>ThreadLocal Leak
|
||||
Prevention Listener</strong>.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="UserConfig_-_org.apache.catalina.startup.UserConfig">UserConfig - org.apache.catalina.startup.UserConfig</h4><div class="text">
|
||||
|
||||
<p>The <strong>UserConfig</strong> provides feature of User Web Applications.
|
||||
User Web Applications map a request URI starting with a tilde character ("~")
|
||||
and a username to a directory (commonly named public_html) in that user's
|
||||
home directory on the server.</p>
|
||||
|
||||
<p>See the <a href="host.html#User_Web_Applications">User Web Applications</a>
|
||||
special feature on the <strong>Host</strong> element for more information.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the
|
||||
<strong>UserConfig</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">directoryName</code></td><td>
|
||||
<p>The directory name to be searched for within each user home directory.
|
||||
The default is <code>public_html</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">userClass</code></td><td>
|
||||
<p>The class name of the user database class.
|
||||
There are currently two user database, the
|
||||
<code>org.apache.catalina.startup.PasswdUserDatabase</code> is used on a
|
||||
Unix system that uses the /etc/passwd file to identify valid users.
|
||||
The <code>org.apache.catalina.startup.HomesUserDatabase</code> is used on
|
||||
a server where /etc/passwd is not in use. HomesUserDatabase deploy all
|
||||
directories found in a specified base directory.</p>
|
||||
</td></tr><tr><td><code class="attributeName">homeBase</code></td><td>
|
||||
<p>The base directory containing user home directories. This is effective
|
||||
only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">allow</code></td><td>
|
||||
<p>A regular expression defining user who deployment is allowed. If this
|
||||
attribute is specified, the user to deploy must match for this pattern.
|
||||
If this attribute is not specified, all users will be deployed unless the
|
||||
user matches a deny pattern.</p>
|
||||
</td></tr><tr><td><code class="attributeName">deny</code></td><td>
|
||||
<p>A regular expression defining user who deployment is denied. If this
|
||||
attribute is specified, the user to deploy must not match for this
|
||||
pattern. If this attribute is not specified, deployment of user will be
|
||||
governed by a allow attribute.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Version_Logging_Lifecycle_Listener_-_org.apache.catalina.startup.VersionLoggerListener">Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>Version Logging Lifecycle Listener</strong> logs Tomcat, Java
|
||||
and operating system information when Tomcat starts.</p>
|
||||
|
||||
<p>This listener must only be nested within <a href="server.html">Server</a>
|
||||
elements and should be the first listener defined.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the <strong>Version
|
||||
Logging Lifecycle Listener</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">logArgs</code></td><td>
|
||||
<p>If <code>true</code>, the command line arguments passed to Java when
|
||||
Tomcat started will be logged. If not specified, the default value of
|
||||
<code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">logEnv</code></td><td>
|
||||
<p>If <code>true</code>, the current environment variables when Tomcat
|
||||
starts will be logged. If not specified, the default value of
|
||||
<code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">logProps</code></td><td>
|
||||
<p>If <code>true</code>, the current Java system properties will be
|
||||
logged. If not specified, the default value of
|
||||
<code>false</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="HTTPD_mod_heartmonitor_Listener_-_org.apache.catalina.ha.backend.HeartbeatListener">HTTPD mod_heartmonitor Listener - org.apache.catalina.ha.backend.HeartbeatListener</h4><div class="text">
|
||||
|
||||
<p>The <strong>HTTPD mod_heartmonitor Listener</strong> allows tomcat to send heart beat message to
|
||||
the Apache HTTPD mod_heartmonitor module.</p>
|
||||
|
||||
<p>The following additional attributes are supported by the <strong>HTTPD mod_heartmonitor
|
||||
Listener</strong>:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">Port</code></td><td>
|
||||
<p>Port the connector that will received proxied traffic from HTTPD, default the first connector will be used</p>
|
||||
</td></tr><tr><td><code class="attributeName">Host</code></td><td>
|
||||
<p>Host it is the IP corresponding the <strong>address</strong> of the connector that will received proxied traffic,
|
||||
default empty the <strong>Port</strong> will be used</p>
|
||||
</td></tr><tr><td><code class="attributeName">proxyURL</code></td><td>
|
||||
<p>proxyURL is the URL corresponding to the <strong>Location</strong> in httpd configuration of the heartbeat Handler,
|
||||
default /HeartbeatListener</p>
|
||||
</td></tr><tr><td><code class="attributeName">ProxyList</code></td><td>
|
||||
<p>ProxyList is the list of proxies from which tomcat is going to receive requests,
|
||||
formatted like "address:port,address:port" once filled the multicast logic is disable and the multi parameters are
|
||||
ignored</p>
|
||||
</td></tr><tr><td><code class="attributeName">Group</code></td><td>
|
||||
<p>Group is the Multicast IP to broadcast messages to HTTPD, default 224.0.1.105</p>
|
||||
</td></tr><tr><td><code class="attributeName">Multiport</code></td><td>
|
||||
<p>Multiport is the Multicast port to broadcast messages to HTTPD, default 23364</p>
|
||||
</td></tr><tr><td><code class="attributeName">Ttl</code></td><td>
|
||||
<p>Ttl is the TTL for the broadcast messages, default 16</p>
|
||||
</td></tr></table>
|
||||
</div></div>
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
123
tomcat/webapps.dist/docs/config/loader.html
Normal file
123
tomcat/webapps.dist/docs/config/loader.html
Normal file
@@ -0,0 +1,123 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Loader Component</title><meta name="author" content="Craig R. McClanahan"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Loader Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Loader</strong> element represents the <em>web
|
||||
application class loader</em> that will be used to load Java
|
||||
classes and resources for your web application. Such
|
||||
a class loader must follow the requirements of the Servlet
|
||||
Specification, and load classes from the following locations:</p>
|
||||
<ul>
|
||||
<li>From the <code>/WEB-INF/classes</code> directory inside your
|
||||
web application.</li>
|
||||
<li>From JAR files in the <code>/WEB-INF/lib</code> directory
|
||||
inside your web application.</li>
|
||||
<li>From resources made available by Catalina to all web
|
||||
applications globally.</li>
|
||||
</ul>
|
||||
|
||||
<p>A Loader element MAY be nested inside a <a href="context.html">Context</a>
|
||||
component. If it is not included, a default Loader configuration will be
|
||||
created automatically, which is sufficient for most requirements.</p>
|
||||
|
||||
<p>For a more in-depth description of the class loader hierarchy
|
||||
that is implemented by Catalina, see <a href="../class-loader-howto.html">the ClassLoader HowTo</a>.</p>
|
||||
|
||||
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
|
||||
base directory against which most relative paths are resolved. If you have
|
||||
not configured Tomcat for multiple instances by setting a CATALINA_BASE
|
||||
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
|
||||
the directory into which you have installed Tomcat.</em></p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Loader</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Loader</code> interface.
|
||||
If not specified, the standard value (defined below) will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">delegate</code></td><td>
|
||||
<p>Set to <code>true</code> if you want the class loader to follow
|
||||
the standard Java2 delegation model, and attempt to load classes from
|
||||
parent class loaders <strong>before</strong> looking inside the web
|
||||
application. Set to <code>false</code> (the default) to have the
|
||||
class loader look inside the web application first, before asking
|
||||
parent class loaders to find requested classes or resources.</p>
|
||||
</td></tr><tr><td><code class="attributeName">reloadable</code></td><td>
|
||||
<p><strong>NOTE</strong> - This attribute has been deprecated in Tomcat
|
||||
9 and will be removed in Tomcat 10. Use the equivalent attribute on the
|
||||
surrounding <a href="context.html">Context</a> component.</p>
|
||||
|
||||
<p>Set to <code>true</code> if you want Catalina to monitor classes in
|
||||
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
|
||||
changes, and automatically reload the web application if a change
|
||||
is detected. This feature is very useful during application
|
||||
development, but it requires significant runtime overhead and is
|
||||
not recommended for use on deployed production applications. You
|
||||
can use the <a href="../manager-howto.html">Manager</a> web
|
||||
application, however, to trigger reloads of deployed applications
|
||||
on demand.</p>
|
||||
|
||||
<p><strong>NOTE</strong> - The value for this property will be
|
||||
inherited from the <code>reloadable</code> attribute you set on
|
||||
the surrounding <a href="context.html">Context</a> component,
|
||||
and any value you explicitly set here will be replaced.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>Loader</strong> is
|
||||
<strong>org.apache.catalina.loader.WebappLoader</strong>.
|
||||
It supports the following additional attributes (in addition to the
|
||||
common attributes listed above):</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">loaderClass</code></td><td>
|
||||
<p>Java class name of the <code>java.lang.ClassLoader</code>
|
||||
implementation class to use. Custom implementations must extend
|
||||
<code>org.apache.catalina.loader.WebappClassLoaderBase</code>.
|
||||
</p>
|
||||
|
||||
<p>If not specified, the default value is
|
||||
<code>org.apache.catalina.loader.ParallelWebappClassLoader</code>. The
|
||||
default <strong>loaderClass</strong> is parallel capable, which
|
||||
means that multiple threads may load difference classes in parallel.
|
||||
A non-parallel capable <strong>loaderClass</strong> is available and can
|
||||
be used by specifying
|
||||
<code>org.apache.catalina.loader.WebappClassLoader</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>No components may be nested inside a <strong>Loader</strong> element.</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Logging">Logging</h4><div class="text">
|
||||
|
||||
<p>A loader is associated with the log category based on its classname.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
508
tomcat/webapps.dist/docs/config/manager.html
Normal file
508
tomcat/webapps.dist/docs/config/manager.html
Normal file
@@ -0,0 +1,508 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Manager Component</title><meta name="author" content="Craig R. McClanahan"><meta name="author" content="Yoav Shapira"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Manager Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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="#Persistence_Across_Restarts">Persistence Across Restarts</a></li><li><a href="#Disable_Session_Persistence">Disable Session Persistence</a></li></ol></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Manager</strong> element represents the <em>session
|
||||
manager</em> that will be used to create and maintain HTTP sessions
|
||||
as requested by the associated web application.</p>
|
||||
|
||||
<p>A Manager element MAY be nested inside a
|
||||
<a href="context.html">Context</a> component. If it is not included,
|
||||
a default Manager configuration will be created automatically, which
|
||||
is sufficient for most requirements, — see
|
||||
<em>Standard Manager Implementation</em> below for the details
|
||||
of this configuration.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Manager</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Manager</code> interface.
|
||||
If not specified, the standard value (defined below) will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxActiveSessions</code></td><td>
|
||||
<p>The maximum number of active sessions that will be created by
|
||||
this Manager, or <code>-1</code> (the default) for no limit.</p>
|
||||
|
||||
<p>When the limit is reached, any attempt to create a new session
|
||||
(e.g. with <code>HttpServletRequest.getSession()</code> call)
|
||||
will fail with an <code>IllegalStateException</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">notifyAttributeListenerOnUnchangedValue</code></td><td>
|
||||
<p>If an attribute is added to the session and that attribute is already
|
||||
present in the session under the same name will any
|
||||
<code>HttpSessionAttributeListener</code> be notified that the attribute
|
||||
has been replaced. If not specified, the default value of
|
||||
<code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">notifyBindingListenerOnUnchangedValue</code></td><td>
|
||||
<p>If an attribute is added to the session, that attribute is already
|
||||
present in the session under the same name and the attribute implements
|
||||
<code>HttpSessionBindingListener</code>, will the listener be notified
|
||||
that the attribute has been unbound and bound again. If not specified,
|
||||
the default value of <code>false</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>Tomcat provides two standard implementations of <strong>Manager</strong>
|
||||
for use — the default one stores active sessions, while the optional one
|
||||
stores active sessions that have been swapped out (in addition to saving
|
||||
sessions across a restart of Tomcat) in a storage location that is selected
|
||||
via the use of an appropriate <strong>Store</strong> nested element.</p>
|
||||
|
||||
<h3>Standard Manager Implementation</h3>
|
||||
|
||||
<p>The standard implementation of <strong>Manager</strong> is
|
||||
<strong>org.apache.catalina.session.StandardManager</strong>.
|
||||
It supports the following additional attributes (in addition to the
|
||||
common attributes listed above):</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">pathname</code></td><td>
|
||||
<p>Absolute or relative (to the work directory for this Context)
|
||||
pathname of the file in which session state will be preserved
|
||||
across application restarts, if possible. The default is
|
||||
"SESSIONS.ser".<br>See
|
||||
<a href="#Persistence_Across_Restarts">Persistence Across Restarts</a>
|
||||
for more information. This persistence may be
|
||||
disabled by setting this attribute to an empty string.</p>
|
||||
</td></tr><tr><td><code class="attributeName">persistAuthentication</code></td><td>
|
||||
<p>Should authentication information be included when session state is
|
||||
preserved across application restarts? If <code>true</code>, the session's
|
||||
authentication is preserved so that the session remains authenticated
|
||||
after the application has been restarted. If not specified, the default
|
||||
value of <code>false</code> will be used.<br>See
|
||||
<a href="#Persistence_Across_Restarts">Persistence Across Restarts</a>
|
||||
for more information.</p>
|
||||
|
||||
<p>Please note that the session's <code>Principal</code> class as well
|
||||
as its descendant classes are all subject to the
|
||||
<strong>sessionAttributeValueClassNameFilter</strong>. If such a filter
|
||||
is specified or a <code>SecurityManager</code> is enabled, the names of
|
||||
the <code>Principal</code> class and descendant classes must match that
|
||||
filter pattern in order to be restored.</p>
|
||||
</td></tr><tr><td><code class="attributeName">persistAuthenticationNotes</code></td><td>
|
||||
<p>Should authentication notes (used during FORM authentication) be
|
||||
included when session state is preserved across application restarts?
|
||||
If <code>true</code>, the session's authentication notes are preserved
|
||||
so that an in progress FORM authentication can continue after the
|
||||
application has been restarted. If not specified, the default value of
|
||||
<code>false</code> will be used.<br>See
|
||||
<a href="#Persistence_Across_Restarts">Persistence Across Restarts</a>
|
||||
for more information.</p>
|
||||
</td></tr><tr><td><code class="attributeName">processExpiresFrequency</code></td><td>
|
||||
<p>Frequency of the session expiration, and related manager operations.
|
||||
Manager operations will be done once for the specified amount of
|
||||
backgroundProcess calls (i.e., the lower the amount, the more often the
|
||||
checks will occur). The minimum value is 1, and the default value is 6.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomClass</code></td><td>
|
||||
<p>Name of the Java class that extends
|
||||
<code>java.security.SecureRandom</code> to use to generate session IDs.
|
||||
If not specified, the default value is
|
||||
<code>java.security.SecureRandom</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomProvider</code></td><td>
|
||||
<p>Name of the provider to use to create the
|
||||
<code>java.security.SecureRandom</code> instances that generate session
|
||||
IDs. If an invalid algorithm and/or provider is specified, the Manager
|
||||
will use the platform default provider and the default algorithm. If not
|
||||
specified, the platform default provider will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomAlgorithm</code></td><td>
|
||||
<p>Name of the algorithm to use to create the
|
||||
<code>java.security.SecureRandom</code> instances that generate session
|
||||
IDs. If an invalid algorithm and/or provider is specified, the Manager
|
||||
will use the platform default provider and the default algorithm. If not
|
||||
specified, the default algorithm of SHA1PRNG will be used. If the
|
||||
default algorithm is not supported, the platform default will be used.
|
||||
To specify that the platform default should be used, do not set the
|
||||
secureRandomProvider attribute and set this attribute to the empty
|
||||
string.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
serialized for clustering/replication, or storage to any persistent store.
|
||||
An attribute will only be serialized if its name matches
|
||||
this pattern. If the pattern is zero length or <code>null</code>, all
|
||||
attributes are eligible for distribution. The pattern is anchored so the
|
||||
session attribute name must fully match the pattern. As an example, the
|
||||
value <code>(userName|sessionHistory)</code> will only distribute the
|
||||
two session attributes named <code>userName</code> and
|
||||
<code>sessionHistory</code>. If not specified, the default value of
|
||||
<code>null</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
serialized for clustering/replication, or storage to any persistent store.
|
||||
An attribute will only be serialized if the implementation
|
||||
class name of the value matches this pattern. If the pattern is zero
|
||||
length or <code>null</code>, all attributes are eligible for
|
||||
distribution. The pattern is anchored so the fully qualified class name
|
||||
must fully match the pattern. If not specified, the default value of
|
||||
<code>null</code> will be used unless a <code>SecurityManager</code> is
|
||||
enabled in which case the default will be
|
||||
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String;</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td>
|
||||
<p>If <strong>sessionAttributeNameFilter</strong> or
|
||||
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
|
||||
attribute, should this be logged at <code>WARN</code> level? If
|
||||
<code>WARN</code> level logging is disabled then it will be logged at
|
||||
<code>DEBUG</code>. The default value of this attribute is
|
||||
<code>false</code> unless a <code>SecurityManager</code> is enabled in
|
||||
which case the default will be <code>true</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<h3>Persistent Manager Implementation</h3>
|
||||
|
||||
<p><strong>NOTE:</strong> You must set either the
|
||||
<code>org.apache.catalina.session.StandardSession.ACTIVITY_CHECK</code> or
|
||||
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
|
||||
<a href="systemprops.html">system properties</a> to <code>true</code> for
|
||||
the persistent manager to work correctly.</p>
|
||||
|
||||
<p>The persistent implementation of <strong>Manager</strong> is
|
||||
<strong>org.apache.catalina.session.PersistentManager</strong>. In
|
||||
addition to the usual operations of creating and deleting sessions, a
|
||||
<code>PersistentManager</code> has the capability to swap active (but
|
||||
idle) sessions out to a persistent storage mechanism, as well as to save
|
||||
all sessions across a normal restart of Tomcat. The actual persistent
|
||||
storage mechanism used is selected by your choice of a
|
||||
<strong>Store</strong> element nested inside the <strong>Manager</strong>
|
||||
element - this is required for use of <code>PersistentManager</code>.</p>
|
||||
|
||||
<p>This implementation of Manager supports the following attributes in
|
||||
addition to the <a href="#Common_Attributes">Common Attributes</a>
|
||||
described earlier.</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>It has the same meaning as described in the
|
||||
<a href="#Common_Attributes">Common Attributes</a> above.
|
||||
You <strong>must</strong> specify
|
||||
<code>org.apache.catalina.session.PersistentManager</code> to use
|
||||
this manager implementation.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxIdleBackup</code></td><td>
|
||||
<p>The time interval (in seconds) since the last access to a session
|
||||
before it is eligible for being persisted to the session store, or
|
||||
<code>-1</code> to disable this feature. By default, this feature is
|
||||
disabled.</p>
|
||||
</td></tr><tr><td><code class="attributeName">maxIdleSwap</code></td><td>
|
||||
<p>The maximum time a session may be idle before it is eligible to be
|
||||
swapped to disk due to inactivity. Setting this to <code>-1</code> means
|
||||
sessions should not be swapped out just because of inactivity. If this
|
||||
feature is enabled, the time interval specified here should be equal to
|
||||
or longer than the value specified for <code>maxIdleBackup</code>. By
|
||||
default, this feature is disabled.</p>
|
||||
</td></tr><tr><td><code class="attributeName">minIdleSwap</code></td><td>
|
||||
<p>The minimum time in seconds a session must be idle before it is
|
||||
eligible to be swapped to disk to keep the active session count below
|
||||
maxActiveSessions. Setting to <code>-1</code> means sessions will not be
|
||||
swapped out to keep the active session count down. If specified, this
|
||||
value should be less than that specified by <code>maxIdleSwap</code>.
|
||||
By default, this value is set to <code>-1</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">persistAuthentication</code></td><td>
|
||||
<p>Should authentication information be included when sessions are
|
||||
swapped out to persistent storage? If <code>true</code>, the session's
|
||||
authentication is preserved so that the session remains authenticated
|
||||
after being reloaded (swapped in) from persistent storage. If not
|
||||
specified, the default value of <code>false</code> will be used.</p>
|
||||
|
||||
<p>Please note that the session's <code>Principal</code> class as well
|
||||
as its descendant classes are all subject to the
|
||||
<strong>sessionAttributeValueClassNameFilter</strong>. If such a filter
|
||||
is specified or a <code>SecurityManager</code> is enabled, the names of
|
||||
the <code>Principal</code> class and descendant classes must match that
|
||||
filter pattern in order to be restored.</p>
|
||||
</td></tr><tr><td><code class="attributeName">persistAuthenticationNotes</code></td><td>
|
||||
<p>Should authentication notes (used during FORM authentication) be
|
||||
included when sessions are swapped out to persistent storage? If
|
||||
<code>true</code>, the session's authentication notes (used during
|
||||
FORM authentication) are preserved so that an in progress FORM
|
||||
authentication can continue after being reloaded (swapped in) from
|
||||
persistent storage. If not specified, the default value of
|
||||
<code>false</code> will be used.</p>
|
||||
|
||||
<p>Please note that if it is possible that the session will be swapped
|
||||
in to a different node to the node from which it was swapped out, all
|
||||
nodes must be upgraded to at least 9.0.66 (the version where this
|
||||
feature was introduced) before this feature is enabled else the swapping
|
||||
in may fail.</p>
|
||||
|
||||
<p>This attribute has been removed for Tomcat 10.1.x onwards which
|
||||
always persists FORM authenticaton notes.</p>
|
||||
</td></tr><tr><td><code class="attributeName">processExpiresFrequency</code></td><td>
|
||||
<p>It is the same as described above for the
|
||||
<code>org.apache.catalina.session.StandardManager</code> class.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">saveOnRestart</code></td><td>
|
||||
<p>Should all sessions be persisted and reloaded when Tomcat is shut
|
||||
down and restarted (or when this application is reloaded)? By default,
|
||||
this attribute is set to <code>true</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomClass</code></td><td>
|
||||
<p>It is the same as described above for the
|
||||
<code>org.apache.catalina.session.StandardManager</code> class.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomProvider</code></td><td>
|
||||
<p>It is the same as described above for the
|
||||
<code>org.apache.catalina.session.StandardManager</code> class.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">secureRandomAlgorithm</code></td><td>
|
||||
<p>It is the same as described above for the
|
||||
<code>org.apache.catalina.session.StandardManager</code> class.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
serialized for clustering/replication, or storage to any persistent store.
|
||||
An attribute will only be serialized if its name matches
|
||||
this pattern. If the pattern is zero length or <code>null</code>, all
|
||||
attributes are eligible for distribution. The pattern is anchored so the
|
||||
session attribute name must fully match the pattern. As an example, the
|
||||
value <code>(userName|sessionHistory)</code> will only distribute the
|
||||
two session attributes named <code>userName</code> and
|
||||
<code>sessionHistory</code>. If not specified, the default value of
|
||||
<code>null</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAttributeValueClassNameFilter</code></td><td>
|
||||
<p>A regular expression used to filter which session attributes will be
|
||||
serialized for clustering/replication, or storage to any persistent store.
|
||||
An attribute will only be serialized if the implementation
|
||||
class name of the value matches this pattern. If the pattern is zero
|
||||
length or <code>null</code>, all attributes are eligible for
|
||||
distribution. The pattern is anchored so the fully qualified class name
|
||||
must fully match the pattern. If not specified, the default value of
|
||||
<code>null</code> will be used unless a <code>SecurityManager</code> is
|
||||
enabled in which case the default will be
|
||||
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)|org\\.apache\\.catalina\\.realm\\.GenericPrincipal\\$SerializablePrincipal|\\[Ljava.lang.String;</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">warnOnSessionAttributeFilterFailure</code></td><td>
|
||||
<p>If <strong>sessionAttributeNameFilter</strong> or
|
||||
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
|
||||
attribute, should this be logged at <code>WARN</code> level? If
|
||||
<code>WARN</code> level logging is disabled then it will be logged at
|
||||
<code>DEBUG</code>. The default value of this attribute is
|
||||
<code>false</code> unless a <code>SecurityManager</code> is enabled in
|
||||
which case the default will be <code>true</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<p>In order to successfully use a PersistentManager, you must nest inside
|
||||
it a <strong><Store></strong> element, as described below.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<h3>All Manager Implementations</h3>
|
||||
|
||||
<p>All Manager implementations allow nesting of a
|
||||
<strong><SessionIdGenerator></strong> element. It defines
|
||||
the behavior of session id generation. All implementations
|
||||
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
|
||||
following attributes:
|
||||
</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">sessionIdLength</code></td><td>
|
||||
<p>The length of the session ID may be changed with the
|
||||
<strong>sessionIdLength</strong> attribute.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
|
||||
<h3>Persistent Manager Implementation</h3>
|
||||
|
||||
<p>If you are using the <em>Persistent Manager Implementation</em>
|
||||
as described above, you <strong>MUST</strong> nest a
|
||||
<strong><Store></strong> element inside, which defines the
|
||||
characteristics of the persistent data storage. Two implementations
|
||||
of the <code><Store></code> element are currently available,
|
||||
with different characteristics, as described below.</p>
|
||||
|
||||
<h5>File Based Store</h5>
|
||||
|
||||
<p>The <em>File Based Store</em> implementation saves swapped out
|
||||
sessions in individual files (named based on the session identifier)
|
||||
in a configurable directory. Therefore, you are likely to encounter
|
||||
scalability problems as the number of active sessions increases, and
|
||||
this should primarily be considered a means to easily experiment.</p>
|
||||
|
||||
<p>To configure this, add a <code><Store></code> nested inside
|
||||
your <code><Manager></code> element with the following attributes:
|
||||
</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Store</code> interface. You
|
||||
<strong>must</strong> specify
|
||||
<code>org.apache.catalina.session.FileStore</code>
|
||||
to use this implementation.</p>
|
||||
</td></tr><tr><td><code class="attributeName">directory</code></td><td>
|
||||
<p>Absolute or relative (to the temporary work directory for this web
|
||||
application) pathname of the directory into which individual session
|
||||
files are written. If not specified, the temporary work directory
|
||||
assigned by the container is utilized.</p>
|
||||
</td></tr></table>
|
||||
|
||||
|
||||
<h5>Data source Based Store</h5>
|
||||
|
||||
<p>The <em>Data source Based Store</em> implementation saves swapped out
|
||||
sessions in individual rows of a preconfigured table in a database
|
||||
that is accessed via a data sourcer. With large numbers of swapped out
|
||||
sessions, this implementation will exhibit improved performance over
|
||||
the File Based Store described above.</p>
|
||||
|
||||
<p>To configure this, add a <code><Store></code> nested inside
|
||||
your <code><Manager></code> element with the following attributes:
|
||||
</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Store</code> interface. You
|
||||
<strong>must</strong> specify
|
||||
<code>org.apache.catalina.session.DataSourceStore</code>
|
||||
to use this implementation.</p>
|
||||
</td></tr><tr><td><code class="attributeName">dataSourceName</code></td><td>
|
||||
<p>Name of the JNDI resource for a JDBC DataSource-factory. Since this
|
||||
code uses prepared statements, you might want to configure pooled
|
||||
prepared statements as shown in
|
||||
<a href="../jndi-resources-howto.html">the JNDI resources
|
||||
How-To</a>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">localDataSource</code></td><td>
|
||||
<p>This allows the Store to use a DataSource defined for the Context
|
||||
rather than a global DataSource. If not specified, the default is
|
||||
<code>false</code>: use a global DataSource.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionAppCol</code></td><td>
|
||||
<p>Name of the database column, contained in the specified session table,
|
||||
that contains the Engine, Host, and Web Application Context name in the
|
||||
format <code>/Engine/Host/Context</code>. If not specified the default
|
||||
value of <code>app</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionDataCol</code></td><td>
|
||||
<p>Name of the database column, contained in the specified session table,
|
||||
that contains the serialized form of all session attributes for a swapped
|
||||
out session. The column type must accept a binary object (typically called
|
||||
a BLOB). If not specified the default value of <code>data</code> will be
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionIdCol</code></td><td>
|
||||
<p>Name of the database column, contained in the specified session table,
|
||||
that contains the session identifier of the swapped out session. The
|
||||
column type must accept character string data of at least as many
|
||||
characters as are contained in session identifiers created by Tomcat
|
||||
(typically 32). If not specified the default value of <code>id</code> will
|
||||
be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionLastAccessedCol</code></td><td>
|
||||
<p>Name of the database column, contained in the specified session table,
|
||||
that contains the <code>lastAccessedTime</code> property of this session.
|
||||
The column type must accept a Java <code>long</code> (64 bits). If not
|
||||
specified the default value of <code>maxinactive</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionMaxInactiveCol</code></td><td>
|
||||
<p>Name of the database column, contained in the specified session table,
|
||||
that contains the <code>maxInactiveInterval</code> property of this
|
||||
session. The column type must accept a Java <code>integer</code> (32
|
||||
bits). If not specified, the default value of <code>maxinactive</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionTable</code></td><td>
|
||||
<p>Name of the database table to be used for storing swapped out sessions.
|
||||
This table must contain (at least) the database columns that are
|
||||
configured by the other attributes of this element. If not specified the
|
||||
default value of <code>tomcat$sessions</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionValidCol</code></td><td>
|
||||
<p>Name of the database column, contained in the specified session table,
|
||||
that contains a flag indicating whether this swapped out session is still
|
||||
valid or not. The column type must accept a single character. If not
|
||||
specified the default value of <code>valid</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<p>Before attempting to use the data source Store for the first time,
|
||||
you must create the table that will be used to store swapped out sessions.
|
||||
Detailed SQL commands vary depending on the database you are using, but
|
||||
a script like this will generally be required:</p>
|
||||
|
||||
<div class="codeBox"><pre><code>create table tomcat_sessions (
|
||||
session_id varchar(100) not null primary key,
|
||||
valid_session char(1) not null,
|
||||
max_inactive int not null,
|
||||
last_access bigint not null,
|
||||
app_name varchar(255),
|
||||
session_data mediumblob,
|
||||
KEY kapp_name(app_name)
|
||||
);</code></pre></div>
|
||||
|
||||
<p>Note: The SQL command above does not use the default names for either the
|
||||
table or the columns so the data source Store would need to be configured
|
||||
to reflect this.</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Persistence_Across_Restarts">Persistence Across Restarts</h4><div class="text">
|
||||
|
||||
<p>Whenever Apache Tomcat is shut down normally and restarted, or when an
|
||||
application reload is triggered, the standard Manager implementation
|
||||
will attempt to serialize all currently active sessions to a disk
|
||||
file located via the <code>pathname</code> attribute. All such saved
|
||||
sessions will then be deserialized and activated (assuming they have
|
||||
not expired in the mean time) when the application reload is completed.</p>
|
||||
|
||||
<p>In order to successfully restore the state of session attributes,
|
||||
all such attributes MUST implement the <code>java.io.Serializable</code>
|
||||
interface. You MAY cause the Manager to enforce this restriction by
|
||||
including the <code><distributable></code> element in your web
|
||||
application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
|
||||
|
||||
<p>Note that, if <strong>persistAuthentication</strong> is also set to
|
||||
<code>true</code>, the <code>Principal</code> class present in the session
|
||||
MUST also implement the <code>java.io.Serializable</code> interface in order
|
||||
to make authentication persistence work properly. The actual type of that
|
||||
<code>Principal</code> class is determined by the <a href="realm.html">
|
||||
Realm</a> implementation used with the application. Tomcat's standard
|
||||
<code>Principal</code> class instantiated by most of the Realms (except
|
||||
<code>JAASRealm</code>) implements <code>java.io.Serializable</code>.</p>
|
||||
|
||||
<p>The persistence across restarts provided by the
|
||||
<strong>StandardManager</strong> is a simpler implementation than that
|
||||
provided by the <strong>PersistentManager</strong>. If robust, production
|
||||
quality persistence across restarts is required then the
|
||||
<strong>PersistentManager</strong> should be used with an appropriate
|
||||
configuration.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Disable_Session_Persistence">Disable Session Persistence</h4><div class="text">
|
||||
|
||||
<p>As documented above, every web application by default has
|
||||
standard manager implementation configured, and it performs session
|
||||
persistence across restarts. To disable this persistence feature, create
|
||||
a <a href="context.html">Context</a> configuration file for your web
|
||||
application and add the following element there:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Manager pathname="" /></code></pre></div>
|
||||
</div></div>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
1029
tomcat/webapps.dist/docs/config/realm.html
Normal file
1029
tomcat/webapps.dist/docs/config/realm.html
Normal file
File diff suppressed because it is too large
Load Diff
307
tomcat/webapps.dist/docs/config/resources.html
Normal file
307
tomcat/webapps.dist/docs/config/resources.html
Normal file
@@ -0,0 +1,307 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Resources Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Resources Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>Resources</strong> element represents all the resources
|
||||
available to the web application. This includes classes, JAR files, HTML, JSPs
|
||||
and any other files that contribute to the web application. Implementations
|
||||
are provided to use directories, JAR files and WARs as the source of these
|
||||
resources and the resources implementation may be extended to provide support
|
||||
for files stored in other forms such as in a database or a versioned
|
||||
repository.</p>
|
||||
|
||||
<p>Resources are cached by default.</p>
|
||||
|
||||
<p><strong>Note: Running a webapp with non-filesystem based
|
||||
Resources implementations is only possible when the webapp does not
|
||||
rely on direct filesystem access to its own resources, and uses the methods
|
||||
in the ServletContext interface to access them.</strong></p>
|
||||
|
||||
<p>A Resources element MAY be nested inside a
|
||||
<a href="context.html">Context</a> component. If it is not included,
|
||||
a default filesystem based Resources will be created automatically,
|
||||
which is sufficient for most requirements.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Resources</strong> support the following
|
||||
attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">allowLinking</code></td><td>
|
||||
<p>If the value of this flag is <code>true</code>, symlinks will be
|
||||
allowed inside the web application, pointing to resources inside or
|
||||
outside the web application base path. If not specified, the default
|
||||
value of the flag is <code>false</code>.</p>
|
||||
<p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
|
||||
(or any other OS which does not have a case sensitive filesystem),
|
||||
as it will disable case sensitivity checks, allowing JSP source code
|
||||
disclosure, among other security problems.</b></p>
|
||||
</td></tr><tr><td><code class="attributeName">cacheMaxSize</code></td><td>
|
||||
<p>The maximum size of the static resource cache in kilobytes.
|
||||
If not specified, the default value is <code>10240</code>
|
||||
(10 megabytes). This value may be changed while the web application is
|
||||
running (e.g. via JMX). If the cache is using more memory than the new
|
||||
limit the cache will attempt to reduce in size over time to meet the
|
||||
new limit. If necessary, <strong>cacheObjectMaxSize</strong> will be
|
||||
reduced to ensure that it is no larger than
|
||||
<code>cacheMaxSize/20</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">cacheObjectMaxSize</code></td><td>
|
||||
<p>Maximum size of the static resource that will be placed in the cache.
|
||||
If not specified, the default value is <code>512</code>
|
||||
(512 kilobytes). If this value is greater than
|
||||
<code>cacheMaxSize/20</code> it will be reduced to
|
||||
<code>cacheMaxSize/20</code>. This value may be changed while the web
|
||||
application is running (e.g. via JMX).</p>
|
||||
</td></tr><tr><td><code class="attributeName">cacheTtl</code></td><td>
|
||||
<p>The amount of time in milliseconds between the revalidation of cache
|
||||
entries. If not specified, the default value is <code>5000</code> (5
|
||||
seconds). This value may be changed while the web application is running
|
||||
(e.g. via JMX). When a resource is cached it will inherit the TTL in
|
||||
force at the time it was cached and retain that TTL until the resource
|
||||
is evicted from the cache regardless of any subsequent changes that may
|
||||
be made to this attribute.</p>
|
||||
</td></tr><tr><td><code class="attributeName">cachingAllowed</code></td><td>
|
||||
<p>If the value of this flag is <code>true</code>, the cache for static
|
||||
resources will be used. If not specified, the default value
|
||||
of the flag is <code>true</code>. This value may be changed while the
|
||||
web application is running (e.g. via JMX). When the cache is disabled
|
||||
any resources currently in the cache are cleared from the cache.</p>
|
||||
</td></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.WebResourceRoot</code>
|
||||
interface. If not specified, the standard value (defined below) will be
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">trackLockedFiles</code></td><td>
|
||||
<p>Controls whether the track locked files feature is enabled. If
|
||||
enabled, all calls to methods that return objects that lock a file and
|
||||
need to be closed to release that lock (e.g.
|
||||
<code>ServletContext.getResourceAsStream()</code>) will perform a number
|
||||
of additional tasks.</p>
|
||||
<ul>
|
||||
<li>The stack trace at the point where the method was called will be
|
||||
recorded and associated with the returned object.</li>
|
||||
<li>The returned object will be wrapped so that the point where
|
||||
close() (or equivalent) is called to release the resources can be
|
||||
detected. Tracking of the object will cease once the resources have
|
||||
been released.</li>
|
||||
<li>All remaining locked resources on web application shutdown will be
|
||||
logged and then closed.</li>
|
||||
</ul>
|
||||
<p>If not specified, the default value of <code>false</code> will be
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">archiveIndexStrategy</code></td><td>
|
||||
<p>If this is <code>simple</code> then a hash map will be used for
|
||||
JAR archive lookups, unless useBloomFilterForArchives in
|
||||
<a href="context.html">Context</a> is explicitly defined.</p>
|
||||
<p>If this is <code>bloom</code> then a bloom filter will be used to
|
||||
speed up archive lookups. This can be beneficial to the deployment
|
||||
speed to web applications that contain very large amount of JARs.</p>
|
||||
<p>If this is <code>purged</code> then a bloom filter will be used to
|
||||
speed up archive lookups, but can be purged at runtime. It is recommended
|
||||
to use <code>bloom</code> to avoid reinitializing the bloom filters.</p>
|
||||
<p>If not specified, the default value of <code>simple</code> will be
|
||||
used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<h3>Standard Root Implementation</h3>
|
||||
|
||||
<p>The standard implementation of <strong>Resources</strong> is
|
||||
<strong>org.apache.catalina.webresources.StandardRoot</strong>. It does not
|
||||
support any additional attributes.</p>
|
||||
|
||||
<h3>Extracting Root Implementation</h3>
|
||||
|
||||
<p>The extracting implementation of <strong>Resources</strong> is
|
||||
<strong>org.apache.catalina.webresources.ExtractingRoot</strong>. It does not
|
||||
support any additional attributes.</p>
|
||||
|
||||
<p>When deploying web applications as packed WAR files, the extracting root
|
||||
will extract any JAR files from <code>/WEB-INF/lib</code> to a
|
||||
<code>application-jars</code> directory located in the web
|
||||
application's working directory. These extracted JARs will be removed
|
||||
when the web application stops.</p>
|
||||
|
||||
<p>Extracting JAR files from a packed WAR may provide a performance
|
||||
improvement, particularly at web application start when JAR scanning is
|
||||
required by the application.</p>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>A web application's main resources are defined by the
|
||||
<strong>docBase</strong> defined for the <a href="context.html">Context</a>.
|
||||
Additional configuration settings and/or resources may be made available to
|
||||
the web application by defining one or more nested components.</p>
|
||||
|
||||
<h3>PreResources</h3>
|
||||
|
||||
<p>PreResources are searched before the main resources. They will be searched
|
||||
in the order they are defined. To configure PreResources, nest a
|
||||
<PreResources> element inside the <Resources> element with the
|
||||
following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">base</code></strong></td><td>
|
||||
<p>Identifies where the resources to be used are located. This attribute
|
||||
is required by the <code>org.apache.catalina.WebResourceSet</code>
|
||||
implementations provided by Tomcat and should specify the absolute path to
|
||||
the file, directory or JAR where the resources are located. Custom
|
||||
implementations may not require it.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.WebResourceSet</code> interface.
|
||||
Tomcat provides three standard implementations:
|
||||
<code>org.apache.catalina.webresources.DirResourceSet</code>,
|
||||
<code>org.apache.catalina.webresources.FileResourceSet</code> and
|
||||
<code>org.apache.catalina.webresources.JarResourceSet</code>. Custom
|
||||
implementations may also be used.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">internalPath</code></td><td>
|
||||
<p>Identifies the path within the <strong>base</strong> where the
|
||||
resources are to be found. This is typically only used with JAR files when
|
||||
the resources are not located at the root of the JAR as is the case with
|
||||
resource JARs. This attribute is required by the
|
||||
<code>org.apache.catalina.WebResourceSet</code> implementations provided
|
||||
by Tomcat and must start with '/'. Custom implementations may not require
|
||||
it. If not specified, the default value '/' will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">readOnly</code></td><td>
|
||||
<p>If <code>true</code>, resources within this resource set may not be
|
||||
deleted, created or modified. For instance of
|
||||
<code>org.apache.catalina.webresources.JarResourceSet</code>, this
|
||||
attribute is hard-coded to <code>true</code> and may not be changed. For
|
||||
instances of <code>org.apache.catalina.webresources.DirResourceSet</code>
|
||||
and <code>org.apache.catalina.webresources.FileResourceSet</code> the
|
||||
default value of this attribute is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="attributeName">webAppMount</code></td><td>
|
||||
<p>Identifies the path within the web application that these resources
|
||||
will be made available. For the
|
||||
<code>org.apache.catalina.WebResourceSet</code> implementations provided
|
||||
by Tomcat, this attribute is required and must start with '/'. Custom
|
||||
implementations may not require it. If not specified, the default value of
|
||||
'/' will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
<h3>JAR resources</h3>
|
||||
|
||||
<p>JarResources are searched after the main resources but before the
|
||||
PostResources. They will be searched in the order they are defined. To
|
||||
configure JarResources, nest a <JarResources> element inside the
|
||||
<Resources> element. The configuration attributes are the same as for
|
||||
<strong>PreResources</strong>.
|
||||
</p>
|
||||
|
||||
<p>During web application start, the JAR scanning process checks scanned JARs
|
||||
for content under <code>/META-INF/resources</code>. Where found, this static
|
||||
content is added to the JarResources.
|
||||
</p>
|
||||
|
||||
<h3>Post-resources</h3>
|
||||
|
||||
<p>PostResources are searched after the resource JARs. They will be searched
|
||||
in the order they are defined. To configure PostResources, nest a
|
||||
<PostResources> element inside the <Resources> element. The
|
||||
configuration attributes are the same as for <strong>PreResources</strong>.
|
||||
</p>
|
||||
|
||||
<h3>Ordering</h3>
|
||||
|
||||
<p>In addition to the sets of resources described above, the standard
|
||||
implementation also maintains ClassResources which represent the classes
|
||||
contained in the JAR files mapped to <code>/WEB-INF/classes</code>. This
|
||||
allows other components to search for classes with a single call rather than
|
||||
one call to search <code>/WEB-INF/classes</code> followed by another to search
|
||||
the JARs in <code>/WEB-INF/lib</code>. The ClassResources are populated
|
||||
from the JARs mapped to <code>/WEB-INF/lib</code> when the web application
|
||||
starts.</p>
|
||||
|
||||
<p>Therefore, the complete search order is:</p>
|
||||
<ul>
|
||||
<li>PreResources</li>
|
||||
<li>MainResources</li>
|
||||
<li>ClassResources</li>
|
||||
<li>JarResources</li>
|
||||
<li>PostResources</li>
|
||||
</ul>
|
||||
|
||||
<p>The population of ClassResources and JarResources at web application start
|
||||
means that care needs to be taken to add JAR based resources correctly to
|
||||
obtain the desired behaviour. Consider the following example:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Resources>
|
||||
<PostResources base="D:\Projects\external\classes"
|
||||
className="org.apache.catalina.webresources.DirResourceSet"
|
||||
webAppMount="/WEB-INF/classes"/>
|
||||
<PostResources base="D:\Projects\lib\library1.jar"
|
||||
className="org.apache.catalina.webresources.FileResourceSet"
|
||||
webAppMount="/WEB-INF/lib/library1.jar"/>
|
||||
</Resources></code></pre></div>
|
||||
|
||||
<p>Since both resources are PostResources, it might be expected that
|
||||
<code>D:\Projects\external\classes</code> will be searched for classes before
|
||||
<code>D:\Projects\lib\library1.jar</code>. However, by adding the JAR using a
|
||||
<code>FileResourceSet</code>, the JAR is mapped to <code>/WEB-INF/lib</code>
|
||||
and will be processed at application start along with the other JARs in
|
||||
<code>/WEB-INF/lib</code>. The classes from the JAR file will be added to the
|
||||
ClassResources which means they will be searched before the classes from
|
||||
<code>D:\Projects\external\classes</code>. If the desired behaviour is that
|
||||
<code>D:\Projects\external\classes</code> is searched before
|
||||
<code>D:\Projects\lib\library1.jar</code> then a slightly different
|
||||
configuration is required:</p>
|
||||
|
||||
<div class="codeBox"><pre><code><Resources>
|
||||
<PostResources base="D:\Projects\external\classes"
|
||||
className="org.apache.catalina.webresources.DirResourceSet"
|
||||
webAppMount="/WEB-INF/classes"/>
|
||||
<PostResources base="D:\Projects\lib\library1.jar"
|
||||
className="org.apache.catalina.webresources.JarResourceSet"
|
||||
webAppMount="/WEB-INF/classes"/>
|
||||
</Resources></code></pre></div>
|
||||
|
||||
<p>In short, the JAR file should be added as a <code>JarResourceSet</code>
|
||||
mapped to <code>/WEB-INF/classes</code> rather than using a
|
||||
<code>FileResourceSet</code> mapped to <code>/WEB-INF/lib</code>.
|
||||
</p>
|
||||
|
||||
<h3>Cache Strategy</h3>
|
||||
|
||||
<p>Additional control over the caching of static resources can be obtained by
|
||||
configuring a custom cache strategy. To configure a custom cache strategy,
|
||||
nest a <CacheStrategy> element inside the <Resources> element
|
||||
with the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><strong><code class="attributeName">className</code></strong></td><td>
|
||||
<p>Java class name of the implementation to use. This class must implement
|
||||
the <code>org.apache.catalina.WebResourceRoot$CacheStrategy</code>
|
||||
interface.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<p>No special features are associated with a <strong>Resources</strong>
|
||||
element.</p>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
105
tomcat/webapps.dist/docs/config/server.html
Normal file
105
tomcat/webapps.dist/docs/config/server.html
Normal file
@@ -0,0 +1,105 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Server Component</title><meta name="author" content="Craig R. McClanahan"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Server Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>A <strong>Server</strong> element represents the entire Catalina
|
||||
servlet container. Therefore, it must be the single outermost element
|
||||
in the <code>conf/server.xml</code> configuration file. Its attributes
|
||||
represent the characteristics of the servlet container as a whole.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Server</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Server</code> interface.
|
||||
If no class name is specified, the standard implementation will
|
||||
be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">address</code></td><td>
|
||||
<p>The TCP/IP address on which this server waits for a shutdown
|
||||
command. If no address is specified, <code>localhost</code> is used.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">port</code></strong></td><td>
|
||||
<p>The TCP/IP port number on which this server waits for a shutdown
|
||||
command. Set to <code>-1</code> to disable the shutdown port.</p>
|
||||
<p>Note: Disabling the shutdown port works well when Tomcat is started
|
||||
using <a href="https://commons.apache.org/daemon/">Apache Commons Daemon</a>
|
||||
(running as a service on Windows or with jsvc on un*xes). It cannot be
|
||||
used when running Tomcat with the standard shell scripts though, as it
|
||||
will prevent shutdown.bat|.sh and catalina.bat|.sh from stopping it
|
||||
gracefully.</p>
|
||||
</td></tr><tr><td><code class="attributeName">portOffset</code></td><td>
|
||||
<p>The offset to apply to <code>port</code> and to the ports of any
|
||||
nested connectors. It must be a non-negative integer. If not specified,
|
||||
the default value of <code>0</code> is used.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">shutdown</code></strong></td><td>
|
||||
<p>The command string that must be received via a TCP/IP connection
|
||||
to the specified port number, in order to shut down Tomcat.</p>
|
||||
</td></tr><tr><td><code class="attributeName">utilityThreads</code></td><td>
|
||||
<p>The number of threads this <strong>Service</strong> will use for
|
||||
various utility tasks, including recurring ones. The special value
|
||||
of 0 will result in the value of
|
||||
<code>Runtime.getRuntime().availableProcessors()</code> being
|
||||
used. Negative values will result in
|
||||
<code>Runtime.getRuntime().availableProcessors() + value</code> being
|
||||
used unless this is less than 1 in which case 1 thread will be used.
|
||||
The default value is 1.
|
||||
</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>Server</strong> is
|
||||
<strong>org.apache.catalina.core.StandardServer</strong>.
|
||||
It supports the following additional attributes (in addition to the
|
||||
common attributes listed above):</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">utilityThreadsAsDaemon</code></td><td>
|
||||
<p>Set the daemon flag value for the utility threads. The default value
|
||||
is <code>false</code>.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="attributeName">periodicEventDelay</code></td><td>
|
||||
<p>This value represents the delay in seconds between periodic
|
||||
lifecycle event invocation of the lifecycle listeners configured on this
|
||||
Server. The value is in seconds, and a negative or zero value will
|
||||
disable the invocations. If not specified, the default value for this
|
||||
attribute is 10 seconds.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>The following components may be nested inside a <strong>Server</strong>
|
||||
element:</p>
|
||||
<ul>
|
||||
<li><a href="service.html"><strong>Service</strong></a> -
|
||||
One or more service element.</li>
|
||||
<li><a href="globalresources.html"><strong>GlobalNamingResources</strong></a> -
|
||||
Configure the JNDI global resources for the server.</li>
|
||||
</ul>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<p>There are no special features associated with a <strong>Server</strong>.
|
||||
</p>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
75
tomcat/webapps.dist/docs/config/service.html
Normal file
75
tomcat/webapps.dist/docs/config/service.html
Normal file
@@ -0,0 +1,75 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The Service Component</title><meta name="author" content="Craig R. McClanahan"></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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 Service Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>A <strong>Service</strong> element represents the combination of one or
|
||||
more <strong>Connector</strong> components that share a single
|
||||
<a href="engine.html">Engine</a> component for processing incoming
|
||||
requests. One or more <strong>Service</strong> elements may be nested
|
||||
inside a <a href="server.html">Server</a> element.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>Service</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.Service</code> interface.
|
||||
If no class name is specified, the standard implementation will
|
||||
be used.</p>
|
||||
</td></tr><tr><td><strong><code class="attributeName">name</code></strong></td><td>
|
||||
<p>The display name of this <strong>Service</strong>, which will
|
||||
be included in log messages if you utilize standard Catalina
|
||||
components. The name of each <strong>Service</strong> that is
|
||||
associated with a particular <a href="server.html">Server</a>
|
||||
must be unique.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>The standard implementation of <strong>Service</strong> is
|
||||
<strong>org.apache.catalina.core.StandardService</strong>.
|
||||
It supports the following additional attributes (in addition to the
|
||||
common attributes listed above):</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">gracefulStopAwaitMillis</code></td><td>
|
||||
<p>The time to wait, in milliseconds, when stopping the Service for the
|
||||
client connections to finish processing and close before the Service's
|
||||
container hierarchy is stopped. The wait only applies to Connectors
|
||||
configured with a <code>bindOnInit</code> value of <code>false</code>
|
||||
which is not the default. Any value of zero or less means there will be no
|
||||
wait. If not specified, the default value of zero will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
</div><h3 id="Nested_Components">Nested Components</h3><div class="text">
|
||||
|
||||
<p>The only components that may be nested inside a <strong>Service</strong>
|
||||
element are one or more <strong>Connector</strong> elements,
|
||||
followed by exactly one <a href="engine.html">Engine</a> element.</p>
|
||||
|
||||
</div><h3 id="Special_Features">Special Features</h3><div class="text">
|
||||
|
||||
<p>There are no special features associated with a <strong>Service</strong>.
|
||||
</p>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
89
tomcat/webapps.dist/docs/config/sessionidgenerator.html
Normal file
89
tomcat/webapps.dist/docs/config/sessionidgenerator.html
Normal file
@@ -0,0 +1,89 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - The SessionIdGenerator Component</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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 SessionIdGenerator Component</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<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></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
|
||||
<p>The <strong>SessionIdGenerator</strong> element represents the <em>session
|
||||
id generator</em> that will be used to create session ids used by
|
||||
web application HTTP sessions.</p>
|
||||
|
||||
<p>A SessionIdGenerator element MAY be nested inside a
|
||||
<a href="manager.html">Manager</a> component. If it is not included,
|
||||
a default SessionIdGenerator configuration will be created automatically, which
|
||||
is sufficient for most requirements, — see
|
||||
<em>Standard SessionIdGenerator Implementation</em> below for the details
|
||||
of this configuration.</p>
|
||||
|
||||
</div><h3 id="Attributes">Attributes</h3><div class="text">
|
||||
|
||||
<div class="subsection"><h4 id="Common_Attributes">Common Attributes</h4><div class="text">
|
||||
|
||||
<p>All implementations of <strong>SessionIdGenerator</strong>
|
||||
support the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">className</code></td><td>
|
||||
<p>Java class name of the implementation to use. This class must
|
||||
implement the <code>org.apache.catalina.SessionIdGenerator</code> interface.
|
||||
If not specified, the standard value (defined below) will be used.</p>
|
||||
</td></tr><tr><td><code class="attributeName">jvmRoute</code></td><td>
|
||||
<p>A routing identifier for this Tomcat instance. It will be added
|
||||
to the session id to allow for stateless stickiness routing by
|
||||
load balancers. The details on how the <code>jvmRoute</code>
|
||||
will be included in the id are implementation dependent.
|
||||
See <a href="#Standard_Implementation">Standard Implementation</a>
|
||||
for the default behavior.</p>
|
||||
|
||||
<p><strong>NOTE</strong> - The value for this property is inherited
|
||||
automatically from the <code>jvmRoute</code> attribute of the
|
||||
<a href="engine.html">Engine</a> element.</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionIdLength</code></td><td>
|
||||
<p>The length of session ids created by this SessionIdGenerator.
|
||||
The details on how the <code>sessionIdLength</code>
|
||||
influences the session id length are implementation dependent.
|
||||
See <a href="#Standard_Implementation">Standard Implementation</a>
|
||||
for the default behavior.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
<div class="subsection"><h4 id="Standard_Implementation">Standard Implementation</h4><div class="text">
|
||||
|
||||
<p>Tomcat provides a standard implementations of <strong>SessionIdGenerator</strong>
|
||||
for use.</p>
|
||||
|
||||
<h3>Standard SessionIdGenerator Implementation</h3>
|
||||
|
||||
<p>The standard implementation of <strong>SessionIdGenerator</strong> is
|
||||
<strong>org.apache.catalina.util.StandardSessionIdGenerator</strong>.
|
||||
It supports the following attributes:</p>
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Attribute
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="attributeName">jvmRoute</code></td><td>
|
||||
<p>A routing identifier for this Tomcat instance. It will be added
|
||||
to the end of the session id separated by a ".".</p>
|
||||
</td></tr><tr><td><code class="attributeName">sessionIdLength</code></td><td>
|
||||
<p>The length of session ids created by this SessionIdGenerator.
|
||||
More precisely the session id length is twice the value of
|
||||
<code>sessionIdLength</code> plus the length of the trailing
|
||||
<code>jvmRoute</code> if given. The factor 2 is because
|
||||
the session id is constructed using <code>sessionIdLength</code>
|
||||
random bytes, each byte being encoded in two hex characters
|
||||
in the actual id. The default value is 16.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div>
|
||||
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
528
tomcat/webapps.dist/docs/config/systemprops.html
Normal file
528
tomcat/webapps.dist/docs/config/systemprops.html
Normal file
@@ -0,0 +1,528 @@
|
||||
<!DOCTYPE html SYSTEM "about:legacy-compat">
|
||||
<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.74) - System Properties</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">
|
||||
Version 9.0.74,
|
||||
<time datetime="2023-04-13">Apr 13 2023</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="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>System Properties</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
|
||||
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Property_replacements">Property replacements</a></li><li><a href="#Clustering">Clustering</a></li><li><a href="#Expression_Language">Expression Language</a></li><li><a href="#Jasper">Jasper</a></li><li><a href="#Security">Security</a></li><li><a href="#Specifications">Specifications</a></li><li><a href="#Sessions">Sessions</a></li><li><a href="#Logging">Logging</a></li><li><a href="#JAR_Scanning">JAR Scanning</a></li><li><a href="#Websockets">Websockets</a></li><li><a href="#Other">Other</a></li></ul>
|
||||
</div><h3 id="Introduction">Introduction</h3><div class="text">
|
||||
<p>The following sections list the system properties that may be set to modify
|
||||
the default Tomcat behaviour.</p>
|
||||
</div><h3 id="Property_replacements">Property replacements</h3><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.tomcat.util.digester. PROPERTY_SOURCE</code></td><td>
|
||||
<p>Set this to a comma separated list of fully qualified name of classes
|
||||
that implement
|
||||
<code>org.apache.tomcat.util.IntrospectionUtils.PropertySource</code>.
|
||||
Required to have a public constructor with no arguments.</p>
|
||||
<p>Use this to add a property source, that will be invoked when
|
||||
<code>${parameter:-default-value}</code> denoted parameters (with
|
||||
optional default values) are found in the XML files that Tomcat
|
||||
parses.</p>
|
||||
<p>Property replacement from the specified property source on the JVM
|
||||
system properties can also be done using the
|
||||
<code>REPLACE_SYSTEM_PROPERTIES</code> system property.</p>
|
||||
<p><code>org.apache.tomcat.util.digester.ServiceBindingPropertySource</code>
|
||||
can be used to replace parameters from any Kubernetes service bindings
|
||||
that follows the <a href="https://servicebinding.io/">servicebinding.io</a> spec</p>
|
||||
<p><code>org.apache.tomcat.util.digester.EnvironmentPropertySource</code>
|
||||
can be used to replace parameters from the process' environment
|
||||
variables, e.g. injected ConfigMaps or Secret objects in container
|
||||
based systems like OpenShift or Kubernetes.</p>
|
||||
<p><code>org.apache.tomcat.util.digester.SystemPropertySource</code>
|
||||
does replacement with system properties. It is always enabled,
|
||||
but can also be specified as part of the property value.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.util.digester. REPLACE_SYSTEM_PROPERTIES</code></td><td>
|
||||
<p>Set this boolean system property to <code>true</code> to cause
|
||||
property replacement from the digester property source on the JVM
|
||||
system properties.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Clustering">Clustering</h3><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.catalina. tribes.dns_lookups</code></td><td>
|
||||
<p>This system property is deprecated and will be removed without
|
||||
replacement in Apache Tomcat 10 onwards.</p>
|
||||
<p>If <code>true</code>, the clustering module will attempt to use DNS to
|
||||
resolve any host names provided in the cluster configuration.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Expression_Language">Expression Language</h3><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.el. GET_CLASSLOADER_USE_PRIVILEGED</code></td><td>
|
||||
<p>Controls whether the EL API classes make use of a privileged block to
|
||||
obtain the thread context class loader. When using the EL API within
|
||||
Apache Tomcat this does not need to be set as all calls are already
|
||||
wrapped in a privileged block further up the stack. It may be required if
|
||||
using the EL API under a SecurityManager outside of Apache Tomcat.</p>
|
||||
<p>If not specified, the default of <code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.el.BeanELResolver. CACHE_SIZE</code></td><td>
|
||||
<p>The number of javax.el.BeanELResolver.BeanProperties objects that will
|
||||
be cached by the EL Parser.</p>
|
||||
<p>If not specified, the default of <code>1000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.el.ExpressionBuilder. CACHE_SIZE</code></td><td>
|
||||
<p>The number of parsed EL expressions that will be cached by the EL
|
||||
Parser.</p>
|
||||
<p>If not specified, the default of <code>5000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.el.parser. COERCE_TO_ZERO</code></td><td>
|
||||
<p>If <code>true</code>, when coercing <code>null</code>s to objects of
|
||||
type Number, Character or Boolean the result will be <code>0</code> for
|
||||
Number and Character types and <code>false</code> for Boolean as required
|
||||
by the EL 2.2 and earlier specifications. If this property is
|
||||
<code>false</code> the result of the coercion will be <code>null</code> as
|
||||
required by the EL 3.0 specification.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.el.parser. SKIP_IDENTIFIER_CHECK</code></td><td>
|
||||
<p>If <code>true</code>, when parsing expressions, identifiers will not be
|
||||
checked to ensure that they conform to the Java Language Specification for
|
||||
Java identifiers.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
</div><h3 id="Jasper">Jasper</h3><div class="text">
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.jasper.compiler. Generator.POOL_TAGS_WITH_EXTENDS</code></td><td>
|
||||
<p>By default, JSPs that use their own base class via the extends
|
||||
attribute of the page directive, will have Tag pooling disabled since
|
||||
Jasper cannot guarantee that the necessary initialisation will have taken
|
||||
place. This can have a negative impact on performance. Providing the
|
||||
alternative base class calls _jspInit() from Servlet.init(), setting this
|
||||
property to <code>true</code> will enable pooling with an alternative base
|
||||
class. If the alternative base class does not call _jspInit() and this
|
||||
property is <code>true</code>, NPEs will occur when attempting to use
|
||||
tags.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.compiler. Generator.STRICT_GET_PROPERTY</code></td><td>
|
||||
<p>If <code>true</code>, the requirement to have the object referenced in
|
||||
<code>jsp:getProperty</code> action to be previously "introduced"
|
||||
to the JSP processor, as specified in the chapter JSP.5.3 of JSP 2.0 and
|
||||
later specifications, is enforced.</p>
|
||||
<p>If not specified, the specification compliant default of
|
||||
<code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.compiler. Generator.VAR_EXPRESSIONFACTORY</code></td><td>
|
||||
<p>The name of the variable to use for the expression language expression
|
||||
factory.</p>
|
||||
<p>If not specified, the default value of <code>_el_expressionfactory</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.compiler. Generator.VAR_INSTANCEMANAGER</code></td><td>
|
||||
<p>The name of the variable to use for the instance manager factory.</p>
|
||||
<p>If not specified, the default value of <code>_jsp_instancemanager</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.compiler. Parser.STRICT_WHITESPACE</code></td><td>
|
||||
<p>If <code>false</code> the requirements for whitespace before an
|
||||
attribute name will be relaxed so that the lack of whitespace will not
|
||||
cause an error.</p>
|
||||
<p>If not specified, the specification compliant default of
|
||||
<code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.runtime. BodyContentImpl.BUFFER_SIZE</code></td><td>
|
||||
<p>The size (in characters) to use when creating a tag buffer.</p>
|
||||
<p>If not specified, the default value of
|
||||
<code>org.apache.jasper.Constants.DEFAULT_TAG_BUFFER_SIZE</code> (512)
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.runtime. BodyContentImpl.LIMIT_BUFFER</code></td><td>
|
||||
<p>If <code>true</code>, any tag buffer that expands beyond
|
||||
<code>org.apache.jasper.runtime.BodyContentImpl.BUFFER_SIZE</code> will be
|
||||
destroyed and a new buffer created.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.runtime. JspFactoryImpl.USE_POOL</code></td><td>
|
||||
<p>If <code>true</code>, a ThreadLocal <code>PageContext</code> pool will
|
||||
be used.</p>
|
||||
<p>If not specified, the default value of <code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.runtime. JspFactoryImpl.POOL_SIZE</code></td><td>
|
||||
<p>The size of the ThreadLocal <code>PageContext</code>.</p>
|
||||
<p>If not specified, the default value of <code>8</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. JSP_SERVLET_BASE</code></td><td>
|
||||
<p>The base class of the Servlets generated from the JSPs.</p>
|
||||
<p>If not specified, the default value of
|
||||
<code>org.apache.jasper.runtime.HttpJspBase</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. SERVICE_METHOD_NAME</code></td><td>
|
||||
<p>The name of the service method called by the base class.</p>
|
||||
<p>If not specified, the default value of <code>_jspService</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. SERVLET_CLASSPATH</code></td><td>
|
||||
<p>The name of the ServletContext attribute that provides the classpath
|
||||
for the JSP.</p>
|
||||
<p>If not specified, the default value of
|
||||
<code>org.apache.catalina.jsp_classpath</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. JSP_FILE</code></td><td>
|
||||
<p>The name of the request attribute for <code><jsp-file></code>
|
||||
element of a servlet definition. If present on a request, this overrides
|
||||
the value returned by <code>request.getServletPath()</code> to select the
|
||||
JSP page to be executed.</p>
|
||||
<p>If not specified, the default value of
|
||||
<code>org.apache.catalina.jsp_file</code> will be used.</p>
|
||||
<p><strong>Deprecated:</strong> This will be removed in Tomcat 9.0.x
|
||||
onwards. It is replaced by the use of the jspFile servlet initialisation
|
||||
parameter</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. PRECOMPILE</code></td><td>
|
||||
<p>The name of the query parameter that causes the JSP engine to just
|
||||
pregenerate the servlet but not invoke it.</p>
|
||||
<p>If not specified, the default value of <code>jsp_precompile</code>
|
||||
will be used, as defined by JSP specification (JSP.11.4.2).</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. JSP_PACKAGE_NAME</code></td><td>
|
||||
<p>The default package name for compiled JSPs.</p>
|
||||
<p>If not specified, the default value of <code>org.apache.jsp</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. TAG_FILE_PACKAGE_NAME</code></td><td>
|
||||
<p>The default package name for tag handlers generated from tag files.</p>
|
||||
<p>If not specified, the default value of <code>org.apache.jsp.tag</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. ALT_DD_ATTR</code></td><td>
|
||||
<p>The servlet context attribute under which the alternate deployment
|
||||
descriptor for this web application is stored.</p>
|
||||
<p>If not specified, the default value of
|
||||
<code>org.apache.catalina.deploy.alt_dd</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. TEMP_VARIABLE_NAME_PREFIX</code></td><td>
|
||||
<p>Prefix to use for generated temporary variable names.</p>
|
||||
<p>If not specified, the default value of <code>_jspx_temp</code>
|
||||
will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.jasper.Constants. USE_INSTANCE_MANAGER_FOR_TAGS</code></td><td>
|
||||
<p>If <code>true</code>, the instance manager is used to obtain tag
|
||||
handler instances.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Security">Security</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.catalina.connector. RECYCLE_FACADES</code></td><td>
|
||||
<p>If this is <code>true</code> or if a security manager is in use a new
|
||||
facade object will be created for each request.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.connector. CoyoteAdapter.ALLOW_BACKSLASH</code></td><td>
|
||||
<p>If this is <code>true</code> the '\' character will be permitted as a
|
||||
path delimiter.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.util.buf. UDecoder.ALLOW_ENCODED_SLASH</code></td><td>
|
||||
<p>Use of this system property is deprecated. It will be removed from
|
||||
Tomcat 10 onwards.</p>
|
||||
<p>If this system property is set to <code>true</code>, the default for
|
||||
the <code>encodedSolidusHandling</code> attribute of all Connectors will
|
||||
be changed from <code>reject</code> to <code>decode</code>. If decoded, it
|
||||
will be treated a path delimiter.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Specifications">Specifications</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.catalina. STRICT_SERVLET_COMPLIANCE</code></td><td>
|
||||
<p>The default value of this system property is <code>false</code>.</p>
|
||||
<p>If this is <code>true</code> the default values will be changed for:</p>
|
||||
<ul>
|
||||
<li><code>org.apache.catalina.core.<br>ApplicationContext.GET_RESOURCE_REQUIRE_SLASH</code></li>
|
||||
<li><code>org.apache.catalina.core.<br>ApplicationDispatcher.WRAP_SAME_OBJECT</code></li>
|
||||
<li><code>org.apache.catalina.core.<br>StandardHostValve.ACCESS_SESSION</code></li>
|
||||
<li><code>org.apache.catalina.session.<br>StandardSession.ACTIVITY_CHECK</code></li>
|
||||
<li><code>org.apache.catalina.session.<br>StandardSession.LAST_ACCESS_AT_START</code></li>
|
||||
<li><code>org.apache.tomcat.util.http.<br>ServerCookie.STRICT_NAMING</code></li>
|
||||
<li>The <code>resourceOnlyServlets</code> attribute of any
|
||||
<a href="context.html">Context</a> element.</li>
|
||||
<li>The <code>tldValidation</code> attribute of any
|
||||
<a href="context.html">Context</a> element.</li>
|
||||
<li>The <code>useRelativeRedirects</code> attribute of any
|
||||
<a href="context.html">Context</a> element.</li>
|
||||
<li>The <code>xmlNamespaceAware</code> attribute of any
|
||||
<a href="context.html">Context</a> element.</li>
|
||||
<li>The <code>xmlValidation</code> attribute of any
|
||||
<a href="context.html">Context</a> element.</li>
|
||||
</ul>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.connector. Response.ENFORCE_ENCODING_IN_GET_WRITER</code></td><td>
|
||||
<p>If this is <code>true</code> then
|
||||
a call to <code>Response.getWriter()</code> if no character encoding
|
||||
has been specified will result in subsequent calls to
|
||||
<code>Response.getCharacterEncoding()</code> returning
|
||||
<code>ISO-8859-1</code> and the <code>Content-Type</code> response header
|
||||
will include a <code>charset=ISO-8859-1</code> component. (SRV.15.2.22.1)</p>
|
||||
<p>If not specified, the default specification compliant value of
|
||||
<code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.core.ApplicationContext .GET_RESOURCE_REQUIRE_SLASH</code></td><td>
|
||||
<p>If this is <code>true</code> then the path passed to
|
||||
<code>ServletContext.getResource()</code> or
|
||||
<code>ServletContext.getResourceAsStream()</code> must start with
|
||||
"/". If <code>false</code>, code like
|
||||
<code>getResource("myfolder/myresource.txt")</code> will work as Tomcat
|
||||
will prepend "/" to the provided path.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
|
||||
<code>true</code>, the default of this setting will be <code>true</code>,
|
||||
else the default value will be <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.core. ApplicationDispatcher.WRAP_SAME_OBJECT</code></td><td>
|
||||
<p>If this is <code>true</code> then any wrapped request or response
|
||||
object passed to an application dispatcher will be checked to ensure that
|
||||
it has wrapped the original request or response.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
|
||||
<code>true</code>, the default of this setting will be <code>true</code>,
|
||||
else the default value will be <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.websocket. STRICT_SPEC_COMPLIANCE</code></td><td>
|
||||
<p>The default value of this system property is <code>false</code>.</p>
|
||||
<p>If this is <code>true</code> the default values will be changed for:</p>
|
||||
<ul>
|
||||
<li><code>org.apache.tomcat.websocket.server#isEnforceNoAddAfterHandshake</code>
|
||||
(default changes from <code>false</code> to <code>true</code>)</li>
|
||||
</ul>
|
||||
<p>This system property is deprecated and will be removed in Tomcat
|
||||
10.1.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.util.http. ServerCookie.STRICT_NAMING</code></td><td>
|
||||
<p> If this is <code>true</code> then the requirements of the Servlet specification
|
||||
that Cookie names must adhere to RFC2109 will be enforced. If this is
|
||||
<code>false</code> the naming rules specified in RFC6265 (allow the leading "$")
|
||||
will be used.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
|
||||
<code>true</code>, the default of this setting will be <code>true</code>,
|
||||
else the default value will be <code>false</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Sessions">Sessions</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.catalina.authenticator. Constants.SSO_SESSION_COOKIE_NAME</code></td><td>
|
||||
<p>An alternative name for the single sign on session cookie. Defaults to
|
||||
<code>JSESSIONIDSSO</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.core. StandardHostValve.ACCESS_SESSION</code></td><td>
|
||||
<p>If this is <code>true</code>, every request that is associated with a
|
||||
session will cause the session's last accessed time to be updated
|
||||
regardless of whether or not the request explicitly accesses the session.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
|
||||
<code>true</code>, the default of this setting will be <code>true</code>,
|
||||
else the default value will be <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.session. StandardSession.ACTIVITY_CHECK</code></td><td>
|
||||
<p>If this is <code>true</code>, Tomcat will track the number of active
|
||||
requests for each session. When determining if a session is valid, any
|
||||
session with at least one active request will always be considered valid.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
|
||||
<code>true</code>, the default of this setting will be <code>true</code>,
|
||||
else the default value will be <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.session. StandardSession.LAST_ACCESS_AT_START</code></td><td>
|
||||
<p>If this is <code>true</code>, the last accessed time for sessions will
|
||||
be calculated from the beginning of the previous request. If
|
||||
<code>false</code>, the last accessed time for sessions will be calculated
|
||||
from the end of the previous request. This also affects how the idle time
|
||||
is calculated.</p>
|
||||
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
|
||||
<code>true</code>, the default of this setting will be <code>true</code>,
|
||||
else the default value will be <code>false</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Logging">Logging</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.juli.formatter</code></td><td>
|
||||
<p>If no logging configuration file is specified and no logging configuration class is specified
|
||||
using the <code>java.util.logging.config.class</code> and <code>java.util.logging.config.file</code>
|
||||
properties the default logging framework <code>org.apache.juli</code> will use the default
|
||||
<code>java.util.logging.SimpleFormatter</code> for all console output.
|
||||
To simply override the console output formatter, one can use the described property. Example:
|
||||
<code>-Dorg.apache.juli.formatter=org.apache.juli.OneLineFormatter</code></p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.juli. AsyncMaxRecordCount</code></td><td>
|
||||
<p>The maximum number of log records that the JULI AsyncFileHandler will queue in memory.
|
||||
New records are added to the queue and get asynchronously removed from the queue
|
||||
and written to the files by a single writer thread.
|
||||
When the queue is full and a new record is being logged
|
||||
the log record will be handled based on the <code>org.apache.juli.AsyncOverflowDropType</code> setting.</p>
|
||||
<p>The default value is <code>10000</code> records.
|
||||
This number represents the global number of records, not on a per handler basis.
|
||||
</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.juli. AsyncOverflowDropType</code></td><td>
|
||||
<p>When the queue of log records of the JULI AsyncFileHandler is full,
|
||||
new log records are handled according to the following setting:
|
||||
</p>
|
||||
<ul>
|
||||
<li><code>1</code> - the newest record in the queue will be dropped and not logged</li>
|
||||
<li><code>2</code> - the oldest record in the queue will be dropped and not logged</li>
|
||||
<li><code>3</code> - suspend the logging thread until older records got written to the log file and the queue is no longer full.
|
||||
This is the only setting that ensures that no messages get lost.</li>
|
||||
<li><code>4</code> - drop the current log record</li>
|
||||
</ul>
|
||||
<p>The default value is <code>1</code> (drop the newest record in the queue).</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.juli.logging. UserDataHelper.CONFIG</code></td><td>
|
||||
<p>The type of logging to use for errors generated by invalid input data.
|
||||
The options are: <code>DEBUG_ALL</code>, <code>INFO_THEN_DEBUG</code>,
|
||||
<code>INFO_ALL</code> and <code>NONE</code>. When
|
||||
<code>INFO_THEN_DEBUG</code> is used, the period for which errors are
|
||||
logged at DEBUG rather than INFO is controlled by the system property
|
||||
<code>org.apache.juli.logging.UserDataHelper.SUPPRESSION_TIME</code>.
|
||||
</p>
|
||||
<p>The default value is <code>INFO_THEN_DEBUG</code>.</p>
|
||||
<p>The errors currently logged using this system are:</p>
|
||||
<ul>
|
||||
<li>invalid cookies;</li>
|
||||
<li>invalid parameters;</li>
|
||||
<li>too many headers, too many parameters (hitting
|
||||
<code>maxHeaderCount</code> or <code>maxParameterCount</code> limits
|
||||
of a <a href="http.html">connector</a>).</li>
|
||||
<li>invalid host names</li>
|
||||
<li>HTTP/2 stream closures</li>
|
||||
</ul>
|
||||
<p>Other errors triggered by invalid input data may be added to this
|
||||
system in later versions.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.juli.logging. UserDataHelper.SUPPRESSION_TIME</code></td><td>
|
||||
<p>When using <code>INFO_THEN_DEBUG</code> for
|
||||
<code>org.apache.juli.logging.UserDataHelper.CONFIG</code> this system
|
||||
property controls how long messages are logged at DEBUG after a message
|
||||
has been logged at INFO. Once this period has elapsed, the next message
|
||||
will be logged at INFO followed by a new suppression period where
|
||||
messages are logged at DEBUG and so on. The value is measured
|
||||
in seconds.</p>
|
||||
<p>A value of <code>0</code> is equivalent to using <code>INFO_ALL</code>
|
||||
for <code>org.apache.juli.logging.UserDataHelper.CONFIG</code>.</p>
|
||||
<p>A negative value means an infinite suppression period.</p>
|
||||
<p>The default value is <code>86400</code> (24 hours).</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="JAR_Scanning">JAR Scanning</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">tomcat.util.scan. StandardJarScanFilter.jarsToSkip</code></td><td>
|
||||
<p>A list of comma-separated file name patterns that is used as the default
|
||||
value for <code>pluggabilitySkip</code> and <code>tldSkip</code>
|
||||
attributes of the standard
|
||||
<a href="jar-scan-filter.html">JarScanFilter</a> implementation.</p>
|
||||
<p>The coded default is empty, however the system property is set in
|
||||
a default Tomcat installation via the
|
||||
<code>$CATALINA_BASE/conf/catalina.properties</code> file.</p>
|
||||
</td></tr><tr><td><code class="propertyName">tomcat.util.scan. StandardJarScanFilter.jarsToScan</code></td><td>
|
||||
<p>A list of comma-separated file name patterns that is used as the default
|
||||
value for <code>pluggabilityScan</code> and <code>tldScan</code>
|
||||
attributes of the standard
|
||||
<a href="jar-scan-filter.html">JarScanFilter</a> implementation.</p>
|
||||
<p>The coded default is empty, however the system property is set in
|
||||
a default Tomcat installation via the
|
||||
<code>$CATALINA_BASE/conf/catalina.properties</code> file.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Websockets">Websockets</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">org.apache.tomcat. websocket.ALLOW_UNSUPPORTED_EXTENSIONS</code></td><td>
|
||||
<p>If <code>true</code>, allow unknown extensions to be declared by
|
||||
the user.</p>
|
||||
<p>The default value is <code>false</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat. websocket.DEFAULT_BUFFER_SIZE</code></td><td>
|
||||
<p>The default size for buffers used in the Websockets container.</p>
|
||||
<p>The default value is <code>8192</code> which corresponds to 8KB.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat. websocket.DEFAULT_ORIGIN_HEADER_VALUE</code></td><td>
|
||||
<p>Default value of the origin header that will be sent by the client
|
||||
during the upgrade handshake.</p>
|
||||
<p>The default is null so that no origin header is sent.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat. websocket.DEFAULT_PROCESS_PERIOD</code></td><td>
|
||||
<p>The number of periodic ticks between periodic processing which
|
||||
involves in particular session expiration checks.</p>
|
||||
<p>The default value is <code>10</code> which corresponds to 10
|
||||
seconds.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat. websocket.DISABLE_BUILTIN_EXTENSIONS</code></td><td>
|
||||
<p>If <code>true</code>, disable all built-in extensions provided by the
|
||||
server, such as message compression.</p>
|
||||
<p>The default value is <code>false</code>.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div><h3 id="Other">Other</h3><div class="text">
|
||||
|
||||
<table class="defaultTable"><tr><th style="width: 15%;">
|
||||
Property
|
||||
</th><th style="width: 85%;">
|
||||
Description
|
||||
</th></tr><tr><td><code class="propertyName">catalina.useNaming</code></td><td>
|
||||
<p>If this is <code>false</code> it will override the
|
||||
<code>useNaming</code> attribute for all <a href="context.html">
|
||||
Context</a> elements.</p>
|
||||
</td></tr><tr><td><code class="propertyName">javax.sql.DataSource.Factory</code></td><td>
|
||||
<p>The class name of the factory to use to create resources of type
|
||||
<code>javax.sql.DataSource</code>. If not specified the default of
|
||||
<code>org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory</code> is used
|
||||
which is a package renamed (to avoid conflicts) copy of
|
||||
<a href="https://commons.apache.org/dbcp">Apache Commons DBCP 2</a>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">javax.mail.Session.Factory</code></td><td>
|
||||
<p>The class name of the factory to use to create resources of type
|
||||
<code>javax.mail.Session</code>. If not specified the default of
|
||||
<code>org.apache.naming.factory.MailSessionFactory</code> is used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">jvmRoute</code></td><td>
|
||||
<p>Deprecated. Use the <code>jvmRoute</code> attribute of the
|
||||
<a href="engine.html">Engine</a> element. This will be removed in Tomcat
|
||||
10.1.</p>
|
||||
<p>Provides a default value for the <code>jvmRoute</code> attribute of the
|
||||
<a href="engine.html">Engine</a> element. It does not override the value
|
||||
configured on the <a href="engine.html">Engine</a> element.</p>
|
||||
</td></tr><tr><td><code class="propertyName">catalina.config</code></td><td>
|
||||
<p>The location from which to load the catalina.properties configuration
|
||||
file. This may be an absolute URL, a relative (to the current working
|
||||
directory) URL or an alternative file name in which case Tomcat will
|
||||
attempt to load the file from the default location of
|
||||
<code>$CATALINA_BASE/conf/</code>.</p>
|
||||
</td></tr><tr><td><code class="propertyName">tomcat.util.buf.StringCache.byte.enabled</code></td><td>
|
||||
<p>If <code>true</code>, the String cache is enabled for
|
||||
<code>ByteChunk</code>.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">tomcat.util.buf.StringCache.char.enabled</code></td><td>
|
||||
<p>If <code>true</code>, the String cache is enabled for
|
||||
<code>CharChunk</code>.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">tomcat.util.buf.StringCache.trainThreshold</code></td><td>
|
||||
<p>The number of times <code>toString()</code> must be called before the
|
||||
cache is activated.</p>
|
||||
<p>If not specified, the default value of <code>20000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">tomcat.util.buf.StringCache.cacheSize</code></td><td>
|
||||
<p>The size of the String cache.</p>
|
||||
<p>If not specified, the default value of <code>200</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.util.buf.UriUtil. WAR_SEPARATOR</code></td><td>
|
||||
<p>The character to use to separate the WAR file and WAR content parts of
|
||||
a WAR URL using the custom WAR scheme provided by Tomcat. This is
|
||||
equivalent to how <code>!</code> is used in JAR URLs.</p>
|
||||
<p>If not specified, the default value of <code>*</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">tomcat.util.buf.StringCache.maxStringSize</code></td><td>
|
||||
<p>The maximum length of String that will be cached.</p>
|
||||
<p>If not specified, the default value of <code>128</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.util. http.FastHttpDateFormat.CACHE_SIZE</code></td><td>
|
||||
<p>The size of the cache to use parsed and formatted date value.</p>
|
||||
<p>If not specified, the default value of <code>1000</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.tomcat.util. net.NioSelectorShared</code></td><td>
|
||||
<p>If <code>true</code>, use a shared selector for servlet write/read.</p>
|
||||
<p>If not specified, the default value of <code>true</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.startup. EXIT_ON_INIT_FAILURE</code></td><td>
|
||||
<p>If <code>true</code>, the server will exit if an exception happens
|
||||
during the server initialization phase. To support this feature, this
|
||||
system property is used as the default for the
|
||||
<strong>throwOnFailure</strong> attribute of a Connector.</p>
|
||||
<p>If not specified, the default value of <code>false</code> will be
|
||||
used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.startup. RealmRuleSet.MAX_NESTED_REALM_LEVELS</code></td><td>
|
||||
<p>The CombinedRealm allows nested Realms. This property controls the
|
||||
maximum permitted number of levels of nesting.</p>
|
||||
<p>If not specified, the default value of <code>3</code> will be used.</p>
|
||||
</td></tr><tr><td><code class="propertyName">org.apache.catalina.startup. CredentialHandlerRuleSet.MAX_NESTED_LEVELS</code></td><td>
|
||||
<p>The NestedCredentialHandler allows nested CredentialHandlers. This
|
||||
property controls the maximum permitted number of levels of nesting.</p>
|
||||
<p>If not specified, the default value of <code>3</code> will be used.</p>
|
||||
</td></tr></table>
|
||||
|
||||
</div></div></div></div></div><footer><div id="footer">
|
||||
Copyright © 1999-2023, The Apache Software Foundation
|
||||
</div></footer></div></body></html>
|
||||
2254
tomcat/webapps.dist/docs/config/valve.html
Normal file
2254
tomcat/webapps.dist/docs/config/valve.html
Normal file
File diff suppressed because one or more lines are too long
Reference in New Issue
Block a user