open-source/apache-tomcat-8.5.51
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
xieyinlu
2024-11-30 19:03:49 +08:00
commit 1e6763c160
3806 changed files with 737676 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

888
webapps/docs/config/ajp.xml Normal file
View File

@@ -0,0 +1,888 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="ajp.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<author email="arjaquith@mindspring.com">Andrew R. Jaquith</author>
<title>The AJP Connector</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Connector</strong>
support the following attributes:</p>
<attributes>
<attribute name="ajpFlush" required="false">
<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>
</attribute>
<attribute name="allowTrace" required="false">
<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.</p>
</attribute>
<attribute name="asyncTimeout" required="false">
<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>
</attribute>
<attribute name="enableLookups" required="false">
<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>
</attribute>
<attribute name="maxHeaderCount" required="false">
<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>
</attribute>
<attribute name="maxParameterCount" required="false">
<p>The maximum number of parameter and value pairs (GET plus POST) which
will be automatically parsed by the container. Parameter and value pairs
beyond this limit will be ignored. A value of less than 0 means no limit.
If not specified, a default of 10000 is used. Note that
<code>FailedRequestFilter</code> <a href="filter.html">filter</a> can be
used to reject requests that hit the limit.</p>
</attribute>
<attribute name="maxPostSize" required="false">
<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>
</attribute>
<attribute name="maxSavePostSize" required="false">
<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>
</attribute>
<attribute name="parseBodyMethods" required="false">
<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>
</attribute>
<attribute name="port" required="true">
<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>
</attribute>
<attribute name="protocol" required="false">
<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>
</attribute>
<attribute name="proxyName" required="false">
<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>
</attribute>
<attribute name="proxyPort" required="false">
<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>
</attribute>
<attribute name="redirectPort" required="false">
<p>If this <strong>Connector</strong> is supporting non-SSL
requests, and a request is received for which a matching
<code>&lt;security-constraint&gt;</code> requires SSL transport,
Catalina will automatically redirect the request to the port
number specified here.</p>
</attribute>
<attribute name="scheme" required="false">
<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>
</attribute>
<attribute name="secure" required="false">
<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>
</attribute>
<attribute name="sendReasonPhrase" required="false">
<p>Set this attribute to <code>true</code> if you wish to have
a reason phrase in the response.
The default value is <code>false</code>.</p>
<p><strong>Note:</strong> This option is deprecated and will be removed
in Tomcat 9. The reason phrase will not be sent.</p>
</attribute>
<attribute name="URIEncoding" required="false">
<p>This specifies the character encoding used to decode the URI bytes,
after %xx decoding the URL. If not specified, UTF-8 will be used unless
the <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to <code>true</code>
in which case ISO-8859-1 will be used.</p>
</attribute>
<attribute name="useBodyEncodingForURI" required="false">
<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>
</attribute>
<attribute name="useIPVHosts" required="false">
<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>
</attribute>
<attribute name="xpoweredBy" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementations">
<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>
<attributes>
<attribute name="acceptCount" required="false">
<p>The maximum queue length for incoming connection requests when
all possible request processing threads are in use. Any requests
received when the queue is full will be refused. The default
value is 100.</p>
</attribute>
<attribute name="acceptorThreadCount" required="false">
<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>
</attribute>
<attribute name="acceptorThreadPriority" required="false">
<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>
</attribute>
<attribute name="address" required="false">
<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 loopback address will be used.</p>
</attribute>
<attribute name="allowedRequestAttributesPattern" required="false">
<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>
</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>
</attribute>
<attribute name="bindOnInit" required="false">
<p>Controls when the socket used by the connector is bound. By default 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.</p>
</attribute>
<attribute name="clientCertProvider" required="false">
<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>
</attribute>
<attribute name="connectionLinger" required="false">
<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>
</attribute>
<attribute name="connectionTimeout" required="false">
<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>
</attribute>
<attribute name="executor" required="false">
<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>
</attribute>
<attribute name="executorTerminationTimeoutMillis" required="false">
<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>
</attribute>
<attribute name="keepAliveTimeout" required="false">
<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>
</attribute>
<attribute name="maxConnections" required="false">
<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 varies by
connector type. For NIO and NIO2 the default is <code>10000</code>.
For APR/native, the default 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>
</attribute>
<attribute name="maxCookieCount" required="false">
<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>
</attribute>
<attribute name="maxThreads" required="false">
<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>
</attribute>
<attribute name="minSpareThreads" required="false">
<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>
</attribute>
<attribute name="packetSize" required="false">
<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>
</attribute>
<attribute name="processorCache" required="false">
<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>
</attribute>
<attribute name="secret" required="false">
<p>Only requests from workers with this secret keyword will be accepted.
The default value is <code>null</code>. This attrbute must be specified
with a non-null, non-zero length value unless
<strong>secretRequired</strong> is explicitly configured to be
<code>false</code>.</p>
</attribute>
<attribute name="secretRequired" required="false">
<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. The default value is <code>true</code>.
This attributue should only be set to <code>false</code> when the
Connector is used on a trusted network.</p>
</attribute>
<attribute name="tcpNoDelay" required="false">
<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>
</attribute>
<attribute name="threadPriority" required="false">
<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>
</attribute>
<attribute name="tomcatAuthentication" required="false">
<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. Note that this principal
will have no roles associated with it.
The default value is <code>true</code>. If
<code>tomcatAuthorization</code> is set to <code>true</code> this
attribute has no effect.</p>
</attribute>
<attribute name="tomcatAuthorization" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Java TCP socket attributes">
<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>
<attributes>
<attribute name="socket.rxBufSize" required="false">
<p>(int)The socket receive buffer (SO_RCVBUF) size in bytes. JVM default
used if not set.</p>
</attribute>
<attribute name="socket.txBufSize" required="false">
<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>
</attribute>
<attribute name="socket.tcpNoDelay" required="false">
<p>(bool)This is equivalent to standard attribute
<strong>tcpNoDelay</strong>.</p>
</attribute>
<attribute name="socket.soKeepAlive" required="false">
<p>(bool)Boolean value for the socket's keep alive setting
(SO_KEEPALIVE). JVM default used if not set.</p>
</attribute>
<attribute name="socket.ooBInline" required="false">
<p>(bool)Boolean value for the socket OOBINLINE setting. JVM default
used if not set.</p>
</attribute>
<attribute name="socket.soReuseAddress" required="false">
<p>(bool)Boolean value for the sockets reuse address option
(SO_REUSEADDR). JVM default used if not set.</p>
</attribute>
<attribute name="socket.soLingerOn" required="false">
<p>(bool)Boolean value for the sockets so linger option (SO_LINGER).
A value for the standard attribute <strong>connectionLinger</strong>
that is &gt;=0 is equivalent to setting this to <code>true</code>.
A value for the standard attribute <strong>connectionLinger</strong>
that is &lt;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>
</attribute>
<attribute name="socket.soLingerTime" required="false">
<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>
</attribute>
<attribute name="socket.soTimeout" required="false">
<p>This is equivalent to standard attribute
<strong>connectionTimeout</strong>.</p>
</attribute>
<attribute name="socket.performanceConnectionTime" required="false">
<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>
</attribute>
<attribute name="socket.performanceLatency" required="false">
<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>
</attribute>
<attribute name="socket.performanceBandwidth" required="false">
<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>
</attribute>
<attribute name="socket.unlockTimeout" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="NIO specific configuration">
<p>The following attributes are specific to the NIO connector.</p>
<attributes>
<attribute name="socket.directBuffer" required="false">
<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>
</attribute>
<attribute name="socket.appReadBufSize" required="false">
<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>
</attribute>
<attribute name="socket.appWriteBufSize" required="false">
<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>
</attribute>
<attribute name="socket.bufferPool" required="false">
<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>
</attribute>
<attribute name="socket.bufferPoolSize" required="false">
<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>
</attribute>
<attribute name="socket.processorCache" required="false">
<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>
</attribute>
<attribute name="socket.keyCache" required="false">
<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>
</attribute>
<attribute name="socket.eventCache" required="false">
<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>
</attribute>
<attribute name="selectorPool.maxSelectors" required="false">
<p>(int)The max selectors to be used in the pool, to reduce selector
contention. Use this option when the command line
<code>org.apache.tomcat.util.net.NioSelectorShared</code> value is set
to false. Default value is <code>200</code>.</p>
</attribute>
<attribute name="selectorPool.maxSpareSelectors" required="false">
<p>(int)The max spare selectors to be used in the pool, to reduce
selector contention. When a selector is returned to the pool, the system
can decide to keep it or let it be GC'd. Use this option when the
command line <code>org.apache.tomcat.util.net.NioSelectorShared</code>
value is set to false. Default value is <code>-1</code> (unlimited).</p>
</attribute>
<attribute name="command-line-options" required="false">
<p>The following command line options are available for the NIO
connector:<br/>
<code>-Dorg.apache.tomcat.util.net.NioSelectorShared=true|false</code>
- default is <code>true</code>. Set this value to <code>false</code> if you wish to
use a selector for each thread. When you set it to <code>false</code>, you can
control the size of the pool of selectors by using the
<strong>selectorPool.maxSelectors</strong> attribute.</p>
</attribute>
</attributes>
</subsection>
<subsection name="NIO2 specific configuration">
<p>The following attributes are specific to the NIO2 connector.</p>
<attributes>
<attribute name="useCaches" required="false">
<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>
</attribute>
<attribute name="socket.directBuffer" required="false">
<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>
</attribute>
<attribute name="socket.appReadBufSize" required="false">
<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>
</attribute>
<attribute name="socket.appWriteBufSize" required="false">
<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>
</attribute>
<attribute name="socket.bufferPoolSize" required="false">
<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>
</attribute>
<attribute name="socket.processorCache" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="APR/native specific configuration">
<p>The APR/native implementation supports the following attributes in
addition to the common Connector and AJP attributes listed above.</p>
<attributes>
<attribute name="pollTime" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>None at this time.</p>
</section>
<section name="Special Features">
<subsection name="Proxy Support">
<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>
</subsection>
<subsection name="Connector Comparison">
<p>Below is a small chart that shows how the connectors differ.</p>
<table class="defaultTable" style="text-align: center;">
<tr>
<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>
</subsection>
</section>
</body>
</document>

548
webapps/docs/config/automatic-deployment.xml Normal file
View File

@@ -0,0 +1,548 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="automatic-deployment.html">
&project;
<properties>
<title>Automatic Deployment - Use cases</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>This page defines the expected behaviour of the automatic deployer in many
typical use cases. This is a complex area of Tomcat&apos;s functionality.
While any difference between this document and Tomcat&apos;s behaviour is a
bug, the fix may be to change this document, Tomcat&apos;s behaviour or
both.</p>
</section>
<section name="Key">
<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&apos;s
<em>configBase</em>. It must contain a single &lt;Context&gt; 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&apos;s
<em>configBase</em>. It must contain a single &lt;Context&gt; 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&apos;s
<em>configBase</em>. It must contain a single &lt;Context&gt; 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&apos;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&apos;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&apos;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&apos;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>
</section>
<section name="New files">
<p>This section describes Tomcat&apos;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>
</section>
<section name="Deleted files">
<p>This section describes Tomcat&apos;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&apos;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&apos;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>
</section>
<section name="Modified files">
<p>This section describes Tomcat&apos;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>
</section>
<section name="Added files">
<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>
</section>
<section name="Notes">
<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>
</section>
</body>
</document>

146
webapps/docs/config/cluster-channel.xml Normal file
View File

@@ -0,0 +1,146 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-channel.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Channel object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
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.
</section>
<section name="Nested Components">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
The default value here is <code>org.apache.catalina.tribes.group.GroupChannel</code> and is
currently the only implementation available.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.GroupChannel Attributes">
<attributes>
<attribute name="heartbeat" required="false">
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.
</attribute>
<attribute name="heartbeatSleeptime" required="false">
If heartbeat == true, specifies the interval of heartbeat thread in milliseconds.
The default is 5000 (5 seconds).
</attribute>
<attribute name="optionCheck" required="false">
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.
</attribute>
<attribute name="jmxEnabled" required="false">
Flag whether the channel components register with JMX or not.
The default value is true.
</attribute>
<attribute name="jmxDomain" required="false">
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.
</attribute>
<attribute name="jmxPrefix" required="false">
if <code>jmxEnabled</code> set to true, specifies the jmx prefix which
will be used with channel ObjectName.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

105
webapps/docs/config/cluster-deployer.xml Normal file
View File

@@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-deployer.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Deployer object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="org.apache.catalina.ha.deploy.FarmWarDeployer">
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
The cluster deployer class, currently only one is available,
<code>org.apache.catalina.ha.deploy.FarmWarDeployer.</code>
</attribute>
<attribute name="deployDir" required="true">
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>.
</attribute>
<attribute name="tempDir" required="true">
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.
</attribute>
<attribute name="watchDir" required="false">
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.
</attribute>
<attribute name="watchEnabled" required="false">
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.
</attribute>
<attribute name="processDeployFrequency" required="false">
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.
</attribute>
<attribute name="maxValidTime" required="false">
The maximum valid time(in seconds) of FileMessageFactory.
FileMessageFactory will be removed immediately after receiving the
complete WAR file but when failing to receive a FileMessage which was
sent dividing, FileMessageFactory will leak without being removed.
FileMessageFactory that is leaking will be automatically removed after
maxValidTime. If a negative value specified, FileMessageFactory will
never be removed. If the attribute is not provided, a default of 300
seconds (5 minutes) is used.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

320
webapps/docs/config/cluster-interceptor.xml Normal file
View File

@@ -0,0 +1,320 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-interceptor.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Channel Interceptor object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Available Interceptors">
<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>
</section>
<section name="Static Membership">
<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>
<source><![CDATA[ <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>]]></source>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
Required, as there is no default
</attribute>
<attribute name="optionFlag" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes">
<attributes>
<attribute name="domain" required="true">
The logical cluster domain that this Interceptor accepts.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.<br/>
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="logInterval" required="false">
This value indicates the interval for logging for messages from different domains.
The default is 100, which means that to log per 100 messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes">
<attributes>
<attribute name="expire" required="false">
How long do we keep the fragments in memory and wait for the rest to arrive.
The default is 60000 ms.
</attribute>
<attribute name="maxSize" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes">
<attributes>
<attribute name="optionFlag" required="false">
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.
</attribute>
<attribute name="alwaysSend" required="false">
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.
</attribute>
<attribute name="maxQueueSize" required="false">
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
</attribute>
<attribute name="maxThreads" required="false">
The maximum number of threads in this pool, default is 10.
</attribute>
<attribute name="maxSpareThreads" required="false">
The number of threads to keep in the pool, default is 2.
</attribute>
<attribute name="keepAliveTime" required="false">
Maximum number of milliseconds of until Idle thread terminates. Default value is 5000(5 seconds).
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes">
<attributes>
<attribute name="connectTimeout" required="false">
Specifies the timeout, in milliseconds, to use when attempting a TCP connection
to the suspect node. Default is 1000.
</attribute>
<attribute name="performSendTest" required="false">
If true is set, send a test message to the suspect node. Default is true.
</attribute>
<attribute name="performReadTest" required="false">
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.
</attribute>
<attribute name="readTestTimeout" required="false">
Specifies the timeout, in milliseconds, to use when performing a read test
to the suspicious node. Default is 5000.
</attribute>
<attribute name="removeSuspectsTimeout" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes">
<attributes>
<attribute name="interval" required="false">
If useThread == true, defines the interval of sending a ping message.
default is 1000 ms.
</attribute>
<attribute name="useThread" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes">
<attributes>
<attribute name="interval" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes">
<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>
<attributes>
<attribute name="encryptionAlgorithm" required="false">
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>.
</attribute>
<attribute name="encryptionKey" required="true">
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.).
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<subsection name="StaticMember Attributes">
<p><b>LocalMember:</b> <br/>
Static member that is the local member of the static cluster group.
</p>
<attributes>
<attribute name="className" required="true">
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
</attribute>
<attribute name="port" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="securePort" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="host" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="domain" required="false">
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 &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="uniqueId" required="true">
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/>
</attribute>
</attributes>
<p><b>Member:</b> <br/>
Static member that add to the static cluster group.
</p>
<attributes>
<attribute name="className" required="true">
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
</attribute>
<attribute name="port" required="true">
The port that this static member listens to for cluster messages
</attribute>
<attribute name="securePort" required="false">
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
</attribute>
<attribute name="host" required="true">
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 &quot;216.123.1.23&quot;<br/>
2. Hostnames like &quot;tomcat01.mydomain.com&quot; or &quot;tomcat01&quot; as long as they resolve correctly<br/>
3. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="domain" required="false">
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 &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.<br/>
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="uniqueId" required="true">
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/>
</attribute>
</attributes>
</subsection>
<!--TODO Document all the interceptors-->
</section>
</body>
</document>

72
webapps/docs/config/cluster-listener.xml Normal file
View File

@@ -0,0 +1,72 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-listener.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The ClusterListener object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="org.apache.catalina.ha.session.ClusterSessionListener">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

293
webapps/docs/config/cluster-manager.xml Normal file
View File

@@ -0,0 +1,293 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-manager.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The ClusterManager object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="The &lt;Manager&gt;">
<p>The <code>&lt;Manager&gt;</code> element defined inside the
<code>&lt;Cluster&gt;</code> element is the template defined for all web
applications that are marked <code>&lt;distributable/&gt;</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>&lt;Manager&gt;</code> inside the <code>&lt;Context&gt;</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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
</attribute>
<attribute name="name" required="false">
<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>
</attribute>
<attribute name="notifyListenersOnReplication" required="false">
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.
</attribute>
<attribute name="processExpiresFrequency" required="false">
<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>
</attribute>
<attribute name="secureRandomClass" required="false">
<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>
</attribute>
<attribute name="secureRandomProvider" required="false">
<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>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<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>
</attribute>
<attribute name="recordAllActions" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.DeltaManager Attributes">
<attributes>
<attribute name="expireSessionsOnShutdown" required="false">
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>.
</attribute>
<attribute name="maxActiveSessions" required="false">
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.
</attribute>
<attribute name="notifySessionListenersOnReplication" required="false">
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.
</attribute>
<attribute name="notifyContainerListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have container listeners notified
across Tomcat nodes in the cluster.
</attribute>
<attribute name="stateTransferTimeout" required="false">
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.
</attribute>
<attribute name="sendAllSessions" required="false">
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>.
</attribute>
<attribute name="sendAllSessionsSize" required="false">
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>.
</attribute>
<attribute name="sendAllSessionsWaitTime" required="false">
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.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<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>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<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>
</attribute>
<attribute name="stateTimestampDrop" required="false">
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>.
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.BackupManager Attributes">
<attributes>
<attribute name="mapSendOptions" required="false">
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.
</attribute>
<attribute name="maxActiveSessions" required="false">
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.
</attribute>
<attribute name="rpcTimeout" required="false">
Timeout for RPC message used for broadcast and transfer state from
another map.
Default value is <code>15000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<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>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<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>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
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> .
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<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>
</attribute>
<attribute name="accessTimeout" required="false">
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.
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong>&lt;SessionIdGenerator&gt;</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>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
</section>
</body>
</document>

170
webapps/docs/config/cluster-membership.xml Normal file
View File

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-membership.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Membership object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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.
</p>
</section>
<section name="Default Implementation">
<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>
</section>
<section name="Attributes">
<subsection name="Multicast Attributes">
<attributes>
<attribute name="className" required="true">
<p>
The default value is <code>org.apache.catalina.tribes.membership.McastService</code>
and is currently the only implementation.
This implementation uses multicast heartbeats for member discovery.
</p>
</attribute>
<attribute name="address" required="false">
<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>
</attribute>
<attribute name="port" required="false">
<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>
</attribute>
<attribute name="frequency" required="false">
<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>
</attribute>
<attribute name="dropTime" required="false">
<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>
</attribute>
<attribute name="bind" required="false">
<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>
</attribute>
<attribute name="ttl" required="false">
<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>
</attribute>
<attribute name="domain" required="false">
<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>
</attribute>
<attribute name="soTimeout" required="false">
<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>
</attribute>
<attribute name="recoveryEnabled" required="false">
<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>
</attribute>
<attribute name="recoveryCounter" required="false">
<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>
</attribute>
<attribute name="recoverySleepTime" required="false">
<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>
</attribute>
<attribute name="localLoopbackDisabled" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

171
webapps/docs/config/cluster-receiver.xml Normal file
View File

@@ -0,0 +1,171 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-receiver.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Receiver object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Blocking vs Non-Blocking Receiver">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
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
</attribute>
<attribute name="address" required="false">
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>.
</attribute>
<attribute name="direct" required="false">
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.
</attribute>
<attribute name="port" required="false">
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 &lt;= bindPort &lt; 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.
</attribute>
<attribute name="autoBind" required="false">
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.
</attribute>
<attribute name="securePort" required="false">
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.
</attribute>
<attribute name="udpPort" required="false">
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.
</attribute>
<attribute name="selectorTimeout" required="false">
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.
</attribute>
<attribute name="maxThreads" required="false">
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.
</attribute>
<attribute name="minThreads" required="false">
Minimum number of threads to be created when the receiver is started up. Default value is <code>6</code>
</attribute>
<attribute name="maxIdleTime" required="false">
Maximum number of milliseconds of until Idle thread terminates. Default value is <code>60000</code> milliseconds.
</attribute>
<attribute name="ooBInline" required="false">
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="rxBufSize" required="false">
The receiver buffer size on the receiving sockets. Value is in bytes, the default value is <code>43800</code> bytes.
</attribute>
<attribute name="txBufSize" required="false">
The sending buffer size on the receiving sockets. Value is in bytes, the default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpRxBufSize" required="false">
The receive buffer size on the datagram socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpTxBufSize" required="false">
The send buffer size on the datagram socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="soKeepAlive" required="false">
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soLingerOn" required="false">
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>.
</attribute>
<attribute name="soLingerTime" required="false">
Sets the SO_LINGER socket option time value. The value is in seconds.
The default value is <code>3</code> seconds.
</attribute>
<attribute name="soReuseAddress" required="false">
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="tcpNoDelay" required="false">
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>
</attribute>
<attribute name="timeout" required="false">
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
milliseconds.
</attribute>
<attribute name="useBufferPool" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="NioReceiver">
</subsection>
<subsection name="BioReceiver">
</subsection>
</section>
</body>
</document>

181
webapps/docs/config/cluster-sender.xml Normal file
View File

@@ -0,0 +1,181 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-sender.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Sender object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>&lt;Transport&gt;</code>
component the implements the actual delivery mechanism.
</p>
</section>
<section name="Concurrent Parallel Delivery">
<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 &quot;Concurrent Parallel Delivery&quot;.
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
&quot;Concurrent Parallel Delivery&quot;.
</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>
</section>
<section name="Nested Elements">
<p>
The nested element <code>&lt;Transport&gt;</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>
</section>
<section name="Attributes">
<subsection name="Common Sender Attributes">
<attributes>
<attribute name="className" required="true">
Required, only available implementation is <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>
</attribute>
</attributes>
</subsection>
<subsection name="Common Transport Attributes">
<attributes>
<attribute name="className" required="true">
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>
</attribute>
<attribute name="rxBufSize" required="false">
The receive buffer size on the socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="txBufSize" required="false">
The send buffer size on the socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="udpRxBufSize" required="false">
The receive buffer size on the datagram socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpTxBufSize" required="false">
The send buffer size on the datagram socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="directBuffer" required="false">
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>
</attribute>
<attribute name="keepAliveCount" required="false">
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.
</attribute>
<attribute name="keepAliveTime" required="false">
The number of milliseconds a connection is kept open after its been opened.
The default value is <code>-1</code>, which is unlimited.
</attribute>
<attribute name="timeout" required="false">
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.
</attribute>
<attribute name="maxRetryAttempts" required="false">
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>.
</attribute>
<attribute name="ooBInline" required="false">
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soKeepAlive" required="false">
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soLingerOn" required="false">
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>.
</attribute>
<attribute name="soLingerTime" required="false">
Sets the SO_LINGER socket option time value. The value is in seconds.
The default value is <code>3</code> seconds.
</attribute>
<attribute name="soReuseAddress" required="false">
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soTrafficClass" required="false">
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>.
</attribute>
<attribute name="tcpNoDelay" required="false">
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>
</attribute>
<attribute name="throwOnFailedAck" required="false">
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.
</attribute>
</attributes>
</subsection>
<subsection name="Common PooledSender Attributes">
<attributes>
<attribute name="poolSize" required="false">
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>
</attribute>
<attribute name="maxWait" required="false">
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).
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

170
webapps/docs/config/cluster-valve.xml Normal file
View File

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-valve.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Valve object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="org.apache.catalina.ha.tcp.ReplicationValve">
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.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
Set value to <code>org.apache.catalina.ha.tcp.ReplicationValve</code>
</attribute>
<attribute name="filter" required="false">
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=&quot;.*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt&quot;
</code>. The filter is a regular expression using
<code>java.util.regex</code>.
</attribute>
<attribute name="primaryIndicator" required="false">
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>
</attribute>
<attribute name="primaryIndicatorName" required="false">
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.
</attribute>
<attribute name="statistics" required="false">
Boolean value. Set to <code>true</code> if you want the valve to collect request statistics.
Default value is <code>false</code>
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.session.JvmRouteBinderValve">
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.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<code>org.apache.catalina.ha.session.JvmRouteBinderValve</code>
</attribute>
<attribute name="enabled" required="false">
Default value is <code>true</code>
Runtime attribute to turn on and off turn over of the session's jvmRoute value.
</attribute>
<attribute name="sessionIdAttribute" required="false">
Old sessionid before failover is registered in request attributes with this attribute.
Default attribute name is <code>org.apache.catalina.ha.session.JvmRouteOrignalSessionID</code>.
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.authenticator.ClusterSingleSignOn">
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>
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This MUST be set to
<strong>org.apache.catalina.ha.authenticator.ClusterSingleSignOn</strong>.</p>
</attribute>
<attribute name="cookieDomain" required="false">
<p>Sets the host domain to be used for sso cookies.</p>
</attribute>
<attribute name="mapSendOptions" required="false">
<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>
</attribute>
<attribute name="requireReauthentication" required="false">
<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>
</attribute>
<attribute name="rpcTimeout" required="false">
<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>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
<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>
</attribute>
<attribute name="accessTimeout" required="false">
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.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

177
webapps/docs/config/cluster.xml Normal file
View File

@@ -0,0 +1,177 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Security">
<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><a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a></li>
<li>private LAN</li>
<li>a Virtual Private Network (VPN)</li>
<li>IPSEC</li>
</ul>
</section>
<section name="Engine vs Host placement">
<p>
You can place the <code>&lt;Cluster&gt;</code> element inside either the <code>&lt;Engine&gt;</code>
container or the <code>&lt;Host&gt;</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>&lt;Cluster&gt;</code> inside the <code>&lt;Engine&gt;</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>
</section>
<section name="Context Attribute Replication">
<p>To configure context attribute replication, simply do this by swapping out the context implementation
used for your application context.</p>
<source>&lt;Context className=&quot;org.apache.catalina.ha.context.ReplicatedContext&quot;/&gt;</source>
<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>
</section>
<section name="Nested Components">
<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">&lt;Context&gt;</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 &quot;Tribes&quot;
<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>
</section>
<section name="Deprecated configuration options">
<p>
<b>Deprecated settings:</b> In the previous version of Tomcat you were able to control session
manager settings using manager.&lt;property&gt;=value.
This has been discontinued, as the way it was written interferes with
the ability to support multiple different manager classes under one cluster implementation,
as the same properties might have the different effect on different managers.
</p>
</section>
<section name="Attributes">
<subsection name="SimpleTcpCluster Attributes">
<attributes>
<attribute name="className" required="true">
<p>The main cluster class, currently only one is available,
<code>org.apache.catalina.ha.tcp.SimpleTcpCluster</code>
</p>
</attribute>
<attribute name="channelSendOptions" required="true">
<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>
<source>int options = Channel.SEND_OPTIONS_ASYNCHRONOUS |
Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
Channel.SEND_OPTIONS_USE_ACK;</source>
<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>
</attribute>
<attribute name="channelStartOptions" required="false">
<p>Sets the start and stop flags for the &lt;Channel&gt; object used by the cluster.
The default is <code>Channel.DEFAULT</code> which starts all the channel services, such as
sender, receiver, multicast sender and multicast receiver.
The following flags are available today:</p>
<source>Channel.DEFAULT = Channel.SND_RX_SEQ (1) |
Channel.SND_TX_SEQ (2) |
Channel.MBR_RX_SEQ (4) |
Channel.MBR_TX_SEQ (8);</source>
<p>To start a channel without multicasting, you would want to use the value <code>Channel.SND_RX_SEQ | Channel.SND_TX_SEQ</code>
that equals to <code>3</code>.
</p>
</attribute>
<attribute name="heartbeatBackgroundEnabled" required="false">
<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>
</attribute>
<attribute name="notifyLifecycleListenerOnFailure" required="false">
<p>Flag whether notify LifecycleListeners if all ClusterListener couldn't accept channel message.
Default value is false.
</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

1401
webapps/docs/config/context.xml Normal file
View File

File diff suppressed because it is too large Load Diff

216
webapps/docs/config/cookie-processor.xml Normal file
View File

@@ -0,0 +1,216 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cookie-processor.html">
&project;
<properties>
<title>The Cookie Processor Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>CookieProcessor</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
<attribute name="sameSiteCookies" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Legacy Cookie Processor - org.apache.tomcat.util.http.LegacyCookieProcessor">
<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>
<attributes>
<attribute name="allowEqualsInValue" required="false">
<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>
</attribute>
<attribute name="allowHttpSepsInV0" required="false">
<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>
</attribute>
<attribute name="allowNameOnly" required="false">
<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>
</attribute>
<attribute name="alwaysAddExpires" required="false">
<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>
</attribute>
<attribute name="forwardSlashIsSeparator" required="false">
<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>
</attribute>
<attribute name="sameSiteCookies" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No element may be nested inside a <strong>CookieProcessor</strong>.</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>CookieProcessor</strong>
element.</p>
</section>
</body>
</document>

219
webapps/docs/config/credentialhandler.xml Normal file
View File

@@ -0,0 +1,219 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="credentialhandler.html">
&project;
<properties>
<title>The CredentialHandler Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<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&apos;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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>CredentialHandler</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.CredentialHandler</code>
interface.</p>
</attribute>
</attributes>
<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>
</subsection>
<subsection name="MessageDigestCredentialHandler">
<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>
<attributes>
<attribute name="algorithm" required="false">
<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>
</attribute>
<attribute name="encoding" required="false">
<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>
</attribute>
<attribute name="iterations" required="false">
<p>The number of iterations to use when creating a new stored credential
from a clear text credential.</p>
</attribute>
<attribute name="saltLength" required="false">
<p>The length of the randomly generated salt to use when creating a
new stored credential from a clear text credential.</p>
</attribute>
</attributes>
</subsection>
<subsection name="NestedCredentialHandler">
<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>
</subsection>
<subsection name="SecretKeyCredentialHandler">
<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>
<attributes>
<attribute name="algorithm" required="false">
<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>
</attribute>
<attribute name="keyLength" required="false">
<p>The length of key to generate for the stored credential. If not
specified, a default of <code>160</code> is used.</p>
</attribute>
<attribute name="iterations" required="false">
<p>The number of iterations to use when creating a new stored credential
from a clear text credential.</p>
</attribute>
<attribute name="saltLength" required="false">
<p>The length of the randomly generated salt to use when creating a
new stored credential from a clear text credential.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>If you are using the <em>NestedCredentialHandler Implementation</em> or a
CredentialHandler that extends the NestedCredentialHandler one or more
<strong>&lt;CredentialHandler&gt;</strong> elements may be nested inside it.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a
<strong>CredentialHandler</strong> element.</p>
</section>
</body>
</document>

268
webapps/docs/config/engine.xml Normal file
View File

@@ -0,0 +1,268 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="engine.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Engine Container</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Engine</strong>
support the following attributes:</p>
<attributes>
<attribute name="backgroundProcessorDelay" required="false">
<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>
</attribute>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="defaultHost" required="true">
<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>
</attribute>
<attribute name="jvmRoute" required="false">
<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
<code>jvmRoute</code> system property. The <code>jvmRoute</code>
set in an <code>&lt;Engine&gt;</code> attribute will override
any <code>jvmRoute</code> system property.
</p>
</attribute>
<attribute name="name" required="true">
<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>
</attribute>
<attribute name="startStopThreads" required="false">
<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. </p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<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>
</section>
<section name="Special Features">
<subsection name="Logging">
<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>
</subsection>
<subsection name="Access Logs">
<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>
<source><![CDATA[<Engine name="Standalone" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="catalina_access_log" suffix=".txt"
pattern="common"/>
...
</Engine>]]></source>
<p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
for more information on the configuration attributes that are
supported.</p>
</subsection>
<subsection name="Lifecycle Listeners">
<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>
<source><![CDATA[<Engine name="Standalone" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Engine>]]></source>
<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>
</subsection>
<subsection name="Request Filters">
<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>
<source><![CDATA[<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>]]></source>
<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>
</subsection>
</section>
</body>
</document>

130
webapps/docs/config/executor.xml Normal file
View File

@@ -0,0 +1,130 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="executor.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Executor (thread pool)</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Executor</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="name" required="true">
<p>The name used to reference this pool in other places in server.xml.
The name is required and must be unique.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>
The default implementation supports the following attributes:</p>
<attributes>
<attribute name="threadPriority" required="false">
<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>
</attribute>
<attribute name="daemon" required="false">
<p>(boolean) Whether the threads should be daemon threads or not, the default is <code>true</code></p>
</attribute>
<attribute name="namePrefix" required="false">
<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>
</attribute>
<attribute name="maxThreads" required="false">
<p>(int) The max number of active threads in this pool, default is <code>200</code></p>
</attribute>
<attribute name="minSpareThreads" required="false">
<p>(int) The minimum number of threads (idle and active) always kept alive, default is <code>25</code></p>
</attribute>
<attribute name="maxIdleTime" required="false">
<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>
</attribute>
<attribute name="maxQueueSize" required="false">
<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>
</attribute>
<attribute name="prestartminSpareThreads" required="false">
<p>(boolean) Whether minSpareThreads should be started when starting the Executor or not,
the default is <code>false</code></p>
</attribute>
<attribute name="threadRenewalDelay" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

1845
webapps/docs/config/filter.xml Normal file
View File

File diff suppressed because it is too large Load Diff

284
webapps/docs/config/globalresources.xml Normal file
View File

@@ -0,0 +1,284 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="globalresources.html">
&project;
<properties>
<author email="remm@apache.org">Remy Maucherat</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>The GlobalNamingResources Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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">&lt;ResourceLink&gt;</a> elements.
</p>
</section>
<section name="Attributes">
</section>
<section name="Nested Components">
</section>
<section name="Special Features">
<subsection name="Environment Entries">
<p>You can configure named values that will be made visible to all
web applications as environment entry resources by nesting
<code>&lt;Environment&gt;</code> entries inside this element. For
example, you can create an environment entry like this:</p>
<source><![CDATA[<GlobalNamingResources ...>
...
<Environment name="maxExemptions" value="10"
type="java.lang.Integer" override="false"/>
...
</GlobalNamingResources>]]></source>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
</p>
<source><![CDATA[<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>]]></source>
<p>but does <em>not</em> require modification of the deployment descriptor
to customize this value.</p>
<p>The valid attributes for an <code>&lt;Environment&gt;</code> element
are as follows:</p>
<attributes>
<attribute name="description" required="false">
<p>Optional, human-readable description of this environment entry.</p>
</attribute>
<attribute name="name" required="true">
<p>The name of the environment entry to be created, relative to the
<code>java:comp/env</code> context.</p>
</attribute>
<attribute name="override" required="false">
<p>Set this to <code>false</code> if you do <strong>not</strong> want
an <code>&lt;env-entry&gt;</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>
</attribute>
<attribute name="type" required="true">
<p>The fully qualified Java class name expected by the web application
for this environment entry. Must be a legal value for
<code>&lt;env-entry-type&gt;</code> in the web application deployment
descriptor.</p>
</attribute>
<attribute name="value" required="true">
<p>The parameter value that will be presented to the application
when requested from the JNDI context. This value must be convertable
to the Java type defined by the <code>type</code> attribute.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Resource Definitions">
<p>You can declare the characteristics of resources
to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
<code>&lt;resource-env-ref&gt;</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">&lt;ResourceLink&gt;</a>
elements
in the <code><strong>&lt;Context&gt;</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>
<source><![CDATA[<GlobalNamingResources ...>
...
<Resource name="jdbc/EmployeeDB" auth="Container"
type="javax.sql.DataSource"
description="Employees Database for HR Applications"/>
...
</GlobalNamingResources>]]></source>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
<source><![CDATA[<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>]]></source>
<p>but does <em>not</em> require modification of the deployment
descriptor to customize this value.</p>
<p>The valid attributes for a <code>&lt;Resource&gt;</code> element
are as follows:</p>
<attributes>
<attribute name="auth" required="false">
<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>&lt;resource-ref&gt;</code> element in the web
application deployment descriptor, but is optional if the
application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
</attribute>
<attribute name="closeMethod" required="false">
<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 explictly set to the empty
string.</p>
</attribute>
<attribute name="description" required="false">
<p>Optional, human-readable description of this resource.</p>
</attribute>
<attribute name="name" required="true">
<p>The name of the resource to be created, relative to the
<code>java:comp/env</code> context.</p>
</attribute>
<attribute name="scope" required="false">
<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>
</attribute>
<attribute name="singleton" required="false">
<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>
</attribute>
<attribute name="type" required="true">
<p>The fully qualified Java class name expected by the web
application when it performs a lookup for this resource.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Resource Links">
<p>Use <a href="context.html#Resource_Links"><code>&lt;ResourceLink&gt;</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>
<source><![CDATA[<Context>
<ResourceLink
name="bean/MyBeanFactory"
global="bean/MyBeanFactory"
type="com.mycompany.MyBean"
/>
</Context>]]></source>
</subsection>
<subsection name="Transaction">
<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>&lt;Transaction&gt;</code> element
are as follows:</p>
<attributes>
<attribute name="factory" required="true">
<p>The class name for the JNDI object factory.</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

668
webapps/docs/config/host.xml Normal file
View File

@@ -0,0 +1,668 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="host.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="remm@apache.org">Remy Maucherat</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>The Host Container</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Host</strong>
support the following attributes:</p>
<attributes>
<attribute name="appBase" required="true">
<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>
</attribute>
<attribute name="xmlBase" required="false">
<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/&lt;engine_name&gt;/&lt;host_name&gt;</code> will be used.</p>
</attribute>
<attribute name="createDirs" required="false">
<p>If set to true, 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
true, and directory creation fails, an error message will be printed out
but will not halt the startup sequence.</p>
</attribute>
<attribute name="autoDeploy" required="false">
<p>This flag value indicates if Tomcat should check periodically for new
or updated web applications while Tomcat is running. If true, 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 flag's value defaults
to true. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
</attribute>
<attribute name="backgroundProcessorDelay" required="false">
<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>
</attribute>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="deployIgnore" required="false">
<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 .svn or CVS 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
&quot;foo&quot;, you could use <code>.*foo.*</code>.</p>
<p>See <a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
</attribute>
<attribute name="deployOnStartup" required="false">
<p>This flag value indicates if web applications from this host should
be automatically deployed when Tomcat starts. The flag's value defaults
to true. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
</attribute>
<attribute name="failCtxIfServletStartFails" required="false">
<p>Set to <code>true</code> to have each child contexts fail its startup
if any of its servlet that has load-on-startup &gt;=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>
</attribute>
<attribute name="name" required="true">
<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. If the name takes the form of <code>*.domainname</code>
(e.g. <code>*.apache.org</code>) then it will be treated as a match for
any host in that domain unless a host that has an exactly matching name
is found.</p>
</attribute>
<attribute name="startStopThreads" required="false">
<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. 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.</p>
</attribute>
<attribute name="undeployOldVersions" required="false">
<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 true. If not
specified the default value of false will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
<attribute name="copyXML" required="false">
<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 flag's value
defaults to <code>false</code>. Note if <strong>deployXML</strong>
is <code>false</code>, this attribute will have no effect.</p>
</attribute>
<attribute name="deployXML" required="false">
<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 flag's value defaults to <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>
</attribute>
<attribute name="errorReportValveClass" required="false">
<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.</p>
</attribute>
<attribute name="unpackWARs" required="false">
<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. 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>
</attribute>
<attribute name="workDir" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<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>
</section>
<section name="Special Features">
<subsection name="Logging">
<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>
</subsection>
<subsection name="Access Logs">
<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>
<source><![CDATA[<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log" suffix=".txt"
pattern="common"/>
...
</Host>]]></source>
<p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
for more information on the configuration attributes that are
supported.</p>
</subsection>
<subsection name="Automatic Application Deployment">
<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>&apos;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&apos;s
<em>configBase</em>.</li>
<li>Web applications with a WAR file located in the Host&apos;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&apos;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>
</subsection>
<subsection name="Host Name Aliases">
<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>
<source><![CDATA[<Host name="www.mycompany.com" ...>
...
<Alias>mycompany.com</Alias>
...
</Host>]]></source>
<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>)
permitted for the <strong>name</strong> attribute of a
<strong>Host</strong>.</p>
</subsection>
<subsection name="Lifecycle Listeners">
<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>
<source><![CDATA[<Host name="localhost" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Host>]]></source>
<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>
</subsection>
<subsection name="Request Filters">
<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>
<source><![CDATA[<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>]]></source>
<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>
</subsection>
<subsection name="Single Sign On">
<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>
<source><![CDATA[<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
...
</Host>]]></source>
<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>
</subsection>
<subsection name="User Web Applications">
<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>
<source><![CDATA[<Host name="localhost" ...>
...
<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
...
</Host>]]></source>
<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>
<source><![CDATA[<Host name="localhost" ...>
...
<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
homeBase="c:\Homes"
userClass="org.apache.catalina.startup.HomesUserDatabase"/>
...
</Host>]]></source>
<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>
<source>http://www.mycompany.com:8080/~craigmcc</source>
<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>
</subsection>
<subsection name="Custom context.xml and web.xml">
<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>
</subsection>
</section>
</body>
</document>

2031
webapps/docs/config/http.xml Normal file
View File

File diff suppressed because it is too large Load Diff

308
webapps/docs/config/http2.xml Normal file
View File

@@ -0,0 +1,308 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="http2.html">
&project;
<properties>
<title>The HTTP2 Upgrade Protocol</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Upgrade Protocol</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>This must be <code>org.apache.coyote.http2.Http2Protocol</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The HTTP/2 <strong>Upgrade Protocol</strong> implementation supports the
following attributes in addition to the common attributes listed above.</p>
<attributes>
<attribute name="allowedTrailerHeaders" required="false">
<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>
</attribute>
<attribute name="compressibleMimeType" required="false">
<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>
</attribute>
<attribute name="compression" required="false">
<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>
</attribute>
<attribute name="compressionMinSize" required="false">
<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>
</attribute>
<attribute name="initialWindowSize" required="false">
<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>
</attribute>
<attribute name="keepAliveTimeout" required="false">
<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>
</attribute>
<attribute name="maxConcurrentStreamExecution" required="false">
<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>
</attribute>
<attribute name="maxConcurrentStreams" required="false">
<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>
</attribute>
<attribute name="maxHeaderCount" required="false">
<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>
</attribute>
<attribute name="maxHeaderSize" required="false">
<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>
</attribute>
<attribute name="maxTrailerCount" required="false">
<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>
</attribute>
<attribute name="maxTrailerSize" required="false">
<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>
</attribute>
<attribute name="noCompressionStrongETag" required="false">
<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>
</attribute>
<attribute name="noCompressionUserAgents" required="false">
<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>
</attribute>
<attribute name="overheadContinuationThreshold" required="false">
<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>
</attribute>
<attribute name="overheadCountFactor" required="false">
<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</code>. The count is decreased 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
<code>3</code> or more will close the connection before any streams can
complete. If not specified, a default value of <code>1</code> will be
used.</p>
</attribute>
<attribute name="overheadDataThreshold" required="false">
<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>
</attribute>
<attribute name="overheadWindowUpdateThreshold" required="false">
<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>
</attribute>
<attribute name="readTimeout" required="false">
<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>
</attribute>
<attribute name="streamReadTimeout" required="false">
<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>
</attribute>
<attribute name="streamWriteTimeout" required="false">
<p>The time, in milliseconds, that Tomcat will wait for additional window
update frames to arrive for the stream and/or conenction 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>
</attribute>
<attribute name="writeTimeout" required="false">
<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>
</attribute>
</attributes>
<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>
</subsection>
</section>
<section name="Nested Components">
<p>This component does not support any nested components.</p>
</section>
<section name="Special Features">
<p>This component does not support any special features.</p>
</section>
</body>
</document>

96
webapps/docs/config/index.xml Normal file
View File

@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="index.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Overview</title>
</properties>
<body>
<section name="Overview">
<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>&lt;Server&gt;</code> is the
root element of the entire configuration file, while
<code>&lt;Service&gt;</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>
</section>
</body>
</document>

191
webapps/docs/config/jar-scan-filter.xml Normal file
View File

@@ -0,0 +1,191 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="jar-scan-filter.html">
&project;
<properties>
<title>The Jar Scan Filter Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
<source><![CDATA[<Context>
...
<JarScanner>
<JarScanFilter
pluggabilityScan="${tomcat.util.scan.StandardJarScanFilter.jarsToScan},
my_pluggable_feature.jar"/>
</JarScanner>
...
</Context>]]></source>
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Jar Scan Filter</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
<attribute name="pluggabilitySkip" required="false">
<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>
</attribute>
<attribute name="pluggabilityScan" required="false">
<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>
</attribute>
<attribute name="defaultPluggabilityScan" required="false">
<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>
</attribute>
<attribute name="tldSkip" required="false">
<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>
</attribute>
<attribute name="tldScan" required="false">
<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>
</attribute>
<attribute name="defaultTldScan" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Jar Scan Filter</strong> element.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Jar Scan Filter</strong>
element.</p>
</section>
</body>
</document>

147
webapps/docs/config/jar-scanner.xml Normal file
View File

@@ -0,0 +1,147 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="jar-scanner.html">
&project;
<properties>
<title>The Jar Scanner Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
<source><![CDATA[<Context>
...
<JarScanner scanBootstrapClassPath="true"/>
...
</Context>]]></source>
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Jar Scanner</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
<attribute name="scanAllDirectories" required="false">
<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>
</attribute>
<attribute name="scanAllFiles" required="false">
<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>
</attribute>
<attribute name="scanClassPath" required="false">
<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>
</attribute>
<attribute name="scanBootstrapClassPath" required="false">
<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>
</attribute>
<attribute name="scanManifest" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>Only a <a href="jar-scan-filter.html">Jar Scan Filter</a> may be nested
inside a <strong>Jar Scanner</strong> element.</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Jar Scanner</strong>
element.</p>
</section>
</body>
</document>

186
webapps/docs/config/jaspic.xml Normal file
View File

@@ -0,0 +1,186 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="jaspic.html">
&project;
<properties>
<title>JASPIC</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<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 dynamically by an application or statically via
the <code>$CATALINA_BASE/conf/jaspic-providers.xml</code> configuration file.
If present, a JASPIC configuration will over-ride any
<code>&lt;login-config&gt;</code> present in <code>web.xml</code>.</p>
</section>
<section name="Static configuration">
<subsection name="AuthConfigProvider">
<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>&lt;jaspic-providers&gt;</code> element in
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
<source><![CDATA[<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>]]></source>
<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&apos;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>&lt;property&gt;</code> elements
nesting inside the <code>&lt;provide&gt;</code> element.</p>
</subsection>
<subsection name="ServerAuthModule">
<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&apos;s wrapper for <code>ServerAuthModule</code> can be configured
by nesting the following inside the
<code>&lt;jaspic-providers&gt;</code> element in
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
<source><![CDATA[<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>]]></source>
<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>
</subsection>
</section>
<section name="Dynamic configuration">
<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>
</section>
<section name="3rd party modules">
<p>This is not an exhaustive list. The Tomcat community welcomes contributions
that add to this section.</p>
<subsection name="Philip Green II&apos;s module for Google OAuth 2">
<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>
<source><![CDATA[<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>]]></source>
</subsection>
</section>
</body>
</document>

659
webapps/docs/config/listeners.xml Normal file
View File

@@ -0,0 +1,659 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="listeners.html">
&project;
<properties>
<title>The LifeCycle Listener Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Listener</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.LifecycleListener</code>
interface.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No element may be nested inside a <strong>Listener</strong>.</p>
</section>
<section name="Standard Implementations">
<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>
<subsection name="APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener">
<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>
<attributes>
<attribute name="SSLEngine" required="false">
<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>
</attribute>
<attribute name="SSLRandomSeed" required="false">
<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>
</attribute>
<attribute name="FIPSMode" required="false">
<p>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>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library which
you must build yourself</em>.
If this attribute is set to any of the above values, the <b>SSLEngine</b>
must be enabled as well.</p>
<p>The default value is <code>off</code>.</p>
</attribute>
<attribute name="useAprConnector" required="false">
<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>
</attribute>
<attribute name="useOpenSSL" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">
<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>
</subsection>
<subsection name="JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener">
<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>
<attributes>
<attribute name="libraryName" required="false">
<p>The name of the native library, as defined in
<code>java.lang.System.loadLibrary()</code>
</p>
</attribute>
<attribute name="libraryPath" required="false">
<p>The absolute path of the native library, as defined in
<code>java.lang.System.load()</code>
</p>
</attribute>
</attributes>
</subsection>
<subsection name="JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener">
<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>
<attributes>
<attribute name="appContextProtection" required="false">
<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>.
This protection is disabled if running on Java 8 onwards since the leak
has been fixed for Java 8 onwards.
</p>
</attribute>
<attribute name="AWTThreadProtection" required="false">
<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>
</attribute>
<attribute name="classesToInitialize" required="false">
<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>
</attribute>
<attribute name="driverManagerProtection" required="false">
<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>
</attribute>
<attribute name="forkJoinCommonPoolProtection" required="false">
<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 only used when running
on Java 8. The common pool does not exist in earlier versions and the
leak has been fixed for Java 9 onwards.</p>
</attribute>
<attribute name="gcDaemonProtection" required="false">
<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>
</attribute>
<attribute name="ldapPoolProtection" required="false">
<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>
</attribute>
<attribute name="securityLoginConfigurationProtection" required="false">
<p>Enables protection so that usage of the
<code>javax.security.auth.login.Configuration</code> class by a web
application does not provoke a memory leak. The first access of this
class will trigger the initializer that will retain a static reference
to the context class loader. The protection loads the class with the
system class loader to ensure that the static initializer is not
triggered by a web application. Defaults to <code>true</code>. This
protection is disabled if running on Java 8 onwards since the leak has
been fixed for Java 8 onwards.</p>
</attribute>
<attribute name="securityPolicyProtection" required="false">
<p>Enables protection so that usage of the deprecated
<code>javax.security.auth.Policy</code> class by a web application does
not result in a memory leak. The first access of this class will trigger
the static initializer that will retain a static reference to the
context class loader. The protection calls the <code>getPolicy()</code>
method of this class to ensure that the static initializer is not
triggered by a web application. Defaults to <code>true</code>.</p>
<p>Note: The underlying leak has been fixed in Java 7 update 51 onwards
and Java 8 onwards. This protection is therefor disabled if running on
Java 8 onwards.</p>
</attribute>
<attribute name="tokenPollerProtection" required="false">
<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>
</attribute>
<attribute name="urlCacheProtection" required="false">
<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>
</attribute>
<attribute name="xmlParsingProtection" required="false">
<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>
</attribute>
</attributes>
<subsection name="JreMemoryLeakPreventionListener Examples">
<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>
<source><![CDATA[ <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" />]]></source>
<p>then the <code>OracleTimeoutThreadPerVM</code> class would be loaded
and initialized during listener startup instead of during request
processing.</p>
</subsection>
</subsection>
<subsection name="Security Lifecycle Listener - org.apache.catalina.security.SecurityListener">
<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 8.5.30,
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 8.5.30 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>
<attributes>
<attribute name="checkedOsUsers" required="false">
<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>
</attribute>
<attribute name="minimumUmask" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener">
<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>
<attributes>
<attribute name="storeConfigClass" required="false">
<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>
</attribute>
<attribute name="storeRegistry" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener">
<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>
</subsection>
<subsection name="UserConfig - org.apache.catalina.startup.UserConfig">
<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>
<attributes>
<attribute name="directoryName" required="false">
<p>The directory name to be searched for within each user home directory.
The default is <code>public_html</code>.</p>
</attribute>
<attribute name="userClass" required="false">
<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>
</attribute>
<attribute name="homeBase" required="false">
<p>The base directory containing user home directories. This is effective
only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is
used.</p>
</attribute>
<attribute name="allow" required="false">
<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>
</attribute>
<attribute name="deny" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener">
<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>
<attributes>
<attribute name="logArgs" required="false">
<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>
</attribute>
<attribute name="logEnv" required="false">
<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>
</attribute>
<attribute name="logProps" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Additional Implementations">
<subsection name="System property replacement - org.apache.catalina.util.SystemPropertyReplacerListener">
<p>This listener performs system property replacement using the property
source configured on the digester. When <code>${parameter}</code>
denoted parameters are found in the values of system properties,
the property source will be invoked to attempt to replace it.</p>
</subsection>
</section>
<section name="Deprecated Implementations">
<subsection name="JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener">
<p><strong>This listener is now deprecated as the features it provides are
now available in the remote JMX capability included with the JRE. This
listener will be removed in Tomcat 10 and may be removed from Tomcat 8 some
time after 2020-12-31.</strong></p>
<p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
directory of the binary download area.</p>
<p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used by
the JMX/RMI Server making things much simpler if you need to connect
jconsole or a similar tool to a remote Tomcat instance that is running
behind a firewall. Only these ports are configured via the listener. The
remainder of the configuration is via the standard system properties for
configuring JMX. For further information on configuring JMX see
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html">
Monitoring and Management Using JMX</a> included with the Java SDK
documentation.</p>
<p>This listener must only be nested within a <a href="server.html">Server</a>
element.</p>
<p>The following additional attributes are supported by the <strong>JMX Remote
Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="rmiRegistryPortPlatform" required="true">
<p>The port to be used by the JMX/RMI registry for the Platform MBeans.
This replaces the use of the
<code>com.sun.management.jmxremote.port</code> system property that
should not be set when using this listener.</p>
</attribute>
<attribute name="rmiServerPortPlatform" required="true">
<p>The port to be used by the Platform JMX/RMI server.</p>
</attribute>
<attribute name="rmiBindAddress" required="false">
<p>The address of the interface to be used by JMX/RMI server.</p>
</attribute>
<attribute name="useLocalPorts" required="false">
<p>Should any clients using these ports be forced to use local ports to
connect to the JMX/RMI server. This is useful when tunnelling
connections over SSH or similar. Defaults to <code>false</code>.</p>
</attribute>
</attributes>
<h3>Using file-based Authentication and Authorisation</h3>
<p>If this listener was configured in server.xml as:</p>
<source><![CDATA[ <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />]]></source>
<p>with the following system properties set (e.g. in setenv.sh):</p>
<source> -Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false</source>
<p>$CATALINA_BASE/conf/jmxremote.password containing:</p>
<source>admin letmein</source>
<p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
<source>admin readwrite</source>
<p>then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
firewall would enable jconsole to connect to a Tomcat instance running
behind a firewall using a connection string of the form:</p>
<source>service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi</source>
<p>
with a user name of <code>admin</code> and a password of
<code>letmein</code>.
</p>
<h3>Using JAAS</h3>
<p>If we use the following system properties instead:</p>
<source> -Dcom.sun.management.jmxremote.login.config=Tomcat
-Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false</source>
<p>$CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:</p>
<source> Tomcat { /* should match to the com.sun.management.jmxremote.login.config property */
/* for illustration purposes only */
com.sun.security.auth.module.LdapLoginModule REQUIRED
userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
userFilter="(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))"
authzIdentity="admin"
debug=true;
};</source>
<p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
<source>admin readwrite</source>
<p>
then we would need to provide LDAP credentials instead.
</p>
<p><strong>Note that the examples above do not use SSL. JMX access should
be considered equivalent to administrative access and secured accordingly.
</strong></p>
</subsection>
</section>
</body>
</document>

166
webapps/docs/config/loader.xml Normal file
View File

@@ -0,0 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="loader.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Loader Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Loader</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="delegate" required="false">
<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>
</attribute>
<attribute name="reloadable" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
<attribute name="loaderClass" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Loader</strong> element.</p>
</section>
<section name="Special Features">
<subsection name="Logging">
<p>A loader is associated with the log category based on its classname.</p>
</subsection>
</section>
</body>
</document>

558
webapps/docs/config/manager.xml Normal file
View File

@@ -0,0 +1,558 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="manager.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>The Manager Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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, &#x2014; see
<em>Standard Manager Implementation</em> below for the details
of this configuration.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Manager</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="maxActiveSessions" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>Tomcat provides two standard implementations of <strong>Manager</strong>
for use &#x2014; 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>
<attributes>
<attribute name="pathname" required="false">
<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>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<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>
</attribute>
<attribute name="secureRandomClass" required="false">
<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>
</attribute>
<attribute name="secureRandomProvider" required="false">
<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>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<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>
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed 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>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed 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)</code>.</p>
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<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>
</attribute>
</attributes>
<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>
<attributes>
<attribute name="className" required="true">
<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>
</attribute>
<attribute name="maxIdleBackup" required="false">
<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>
</attribute>
<attribute name="maxIdleSwap" required="false">
<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>
</attribute>
<attribute name="minIdleSwap" required="false">
<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>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="saveOnRestart" required="false">
<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>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed 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>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed 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)</code>.</p>
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<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>
</attribute>
</attributes>
<p>In order to successfully use a PersistentManager, you must nest inside
it a <strong>&lt;Store&gt;</strong> element, as described below.</p>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong>&lt;SessionIdGenerator&gt;</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>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
<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>&lt;Store&gt;</strong> element inside, which defines the
characteristics of the persistent data storage. Two implementations
of the <code>&lt;Store&gt;</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>&lt;Store&gt;</code> nested inside
your <code>&lt;Manager&gt;</code> element with the following attributes:
</p>
<attributes>
<attribute name="className" required="true">
<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>
</attribute>
<attribute name="directory" required="false">
<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>
</attribute>
</attributes>
<h5>JDBC Based Store</h5>
<p>The <em>JDBC Based Store</em> implementation saves swapped out
sessions in individual rows of a preconfigured table in a database
that is accessed via a JDBC driver. 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>&lt;Store&gt;</code> nested inside
your <code>&lt;Manager&gt;</code> element with the following attributes:
</p>
<attributes>
<attribute name="className" required="true">
<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.JDBCStore</code>
to use this implementation.</p>
</attribute>
<attribute name="connectionName" required="true">
<p>The user name that will be handed to the configured JDBC driver to
establish a connection to the database containing the session table.</p>
</attribute>
<attribute name="connectionPassword" required="true">
<p>The password that will be handed to the configured JDBC driver to
establish a connection to the database containing the session table.</p>
</attribute>
<attribute name="connectionURL" required="true">
<p>The connection URL that will be handed to the configured JDBC
driver to establish a connection to the database containing our
session table.</p>
</attribute>
<attribute name="dataSourceName" required="false">
<p>Name of the JNDI resource for a JDBC DataSource-factory. If this option
is given and a valid JDBC resource can be found, it will be used and any
direct configuration of a JDBC connection via <code>connectionURL</code>,
<code>connectionName</code>, <code>connectionPassword</code> and
<code>driverName</code> will be ignored. 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>
</attribute>
<attribute name="driverName" required="true">
<p>Java class name of the JDBC driver to be used.</p>
</attribute>
<attribute name="localDataSource" required="false">
<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>
</attribute>
<attribute name="sessionAppCol" required="false">
<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>
</attribute>
<attribute name="sessionDataCol" required="false">
<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>
</attribute>
<attribute name="sessionIdCol" required="false">
<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>
</attribute>
<attribute name="sessionLastAccessedCol" required="false">
<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>
</attribute>
<attribute name="sessionMaxInactiveCol" required="false">
<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>
</attribute>
<attribute name="sessionTable" required="false">
<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>
</attribute>
<attribute name="sessionValidCol" required="false">
<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>
</attribute>
</attributes>
<p>Before attempting to use the JDBC Based 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>
<source>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)
);</source>
<p>Note: The SQL command above does not use the default names for either the
table or the columns so the JDBC Store would need to be configured to reflect
this.</p>
<p>In order for the JDBC Based Store to successfully connect to your
database, the JDBC driver you configure must be visible to Tomcat's
internal class loader. Generally, that means you must place the JAR
file containing this driver into the <code>$CATALINA_HOME/lib</code>
directory.</p>
</section>
<section name="Special Features">
<subsection name="Persistence Across Restarts">
<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>&lt;distributable&gt;</code> element in your web
application deployment descriptor (<code>/WEB-INF/web.xml</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>
</subsection>
<subsection name="Disable Session Persistence">
<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>
<source><![CDATA[<Manager pathname="" />]]></source>
</subsection>
</section>
</body>
</document>

97
webapps/docs/config/project.xml Normal file
View File

@@ -0,0 +1,97 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<project name="Apache Tomcat 8 Configuration Reference"
href="https://tomcat.apache.org/">
<title>Apache Tomcat 8 Configuration Reference</title>
<logo href="/images/tomcat.gif">
The Apache Tomcat Servlet/JSP Container
</logo>
<body>
<menu name="Links">
<item name="Docs Home" href="../index.html"/>
<item name="Config Ref. Home" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</menu>
<menu name="Top Level Elements">
<item name="Server" href="server.html"/>
<item name="Service" href="service.html"/>
</menu>
<menu name="Executors">
<item name="Executor" href="executor.html"/>
</menu>
<menu name="Connectors">
<item name="HTTP/1.1" href="http.html"/>
<item name="HTTP/2" href="http2.html"/>
<item name="AJP" href="ajp.html"/>
</menu>
<menu name="Containers">
<item name="Context" href="context.html"/>
<item name="Engine" href="engine.html"/>
<item name="Host" href="host.html"/>
<item name="Cluster" href="cluster.html"/>
</menu>
<menu name="Nested Components">
<item name="CookieProcessor" href="cookie-processor.html"/>
<item name="CredentialHandler" href="credentialhandler.html"/>
<item name="Global Resources" href="globalresources.html"/>
<item name="JarScanner" href="jar-scanner.html"/>
<item name="JarScanFilter" href="jar-scan-filter.html"/>
<item name="Listeners" href="listeners.html"/>
<item name="Loader" href="loader.html"/>
<item name="Manager" href="manager.html"/>
<item name="Realm" href="realm.html"/>
<item name="Resources" href="resources.html"/>
<item name="SessionIdGenerator" href="sessionidgenerator.html"/>
<item name="Valve" href="valve.html"/>
</menu>
<menu name="Cluster Elements">
<item name="Cluster" href="cluster.html"/>
<item name="Manager" href="cluster-manager.html"/>
<item name="Channel" href="cluster-channel.html"/>
<item name="Channel/Membership" href="cluster-membership.html"/>
<item name="Channel/Sender" href="cluster-sender.html"/>
<item name="Channel/Receiver" href="cluster-receiver.html"/>
<item name="Channel/Interceptor" href="cluster-interceptor.html"/>
<item name="Valve" href="cluster-valve.html"/>
<item name="Deployer" href="cluster-deployer.html"/>
<item name="ClusterListener" href="cluster-listener.html"/>
</menu>
<menu name="web.xml">
<item name="Filter" href="filter.html"/>
</menu>
<menu name="Other">
<item name="System properties" href="systemprops.html"/>
<item name="JASPIC" href="jaspic.html"/>
</menu>
</body>
</project>

1179
webapps/docs/config/realm.xml Normal file
View File

File diff suppressed because it is too large Load Diff

340
webapps/docs/config/resources.xml Normal file
View File

@@ -0,0 +1,340 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="resources.html">
&project;
<properties>
<title>The Resources Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Resources</strong> support the following
attributes:</p>
<attributes>
<attribute name="allowLinking" required="false">
<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>
</attribute>
<attribute name="cacheMaxSize" required="false">
<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>
</attribute>
<attribute name="cacheObjectMaxSize" required="false">
<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>
</attribute>
<attribute name="cacheTtl" required="false">
<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>
</attribute>
<attribute name="cachingAllowed" required="false">
<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>
</attribute>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="trackLockedFiles" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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&apos;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>
</subsection>
</section>
<section name="Nested Components">
<p>A web application&apos;s main resources are defined by the
<strong>docBase</strong> defined for the <a href="context.html">Context</a>.
Additional 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
&lt;PreResources&gt; element inside the &lt;Resources&gt; element with the
following attributes:</p>
<attributes>
<attribute name="base" required="true">
<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>
</attribute>
<attribute name="className" required="true">
<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>
</attribute>
<attribute name="internalPath" required="false">
<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>
</attribute>
<attribute name="readOnly" required="false">
<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>
</attribute>
<attribute name="webAppMount" required="false">
<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>
</attribute>
</attributes>
<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 &lt;JarResources&gt; element inside the
&lt;Resources&gt; 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
&lt;PostResources&gt; element inside the &lt;Resources&gt; 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>
<source><![CDATA[<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>]]></source>
<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>
<source><![CDATA[<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>]]></source>
<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>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Resources</strong>
element.</p>
</section>
</body>
</document>

126
webapps/docs/config/server.xml Normal file
View File

@@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="server.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Server Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Server</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="address" required="false">
<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>
</attribute>
<attribute name="port" required="true">
<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>
</attribute>
<attribute name="shutdown" required="true">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<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>
</section>
<section name="Special Features">
<p>There are no special features associated with a <strong>Server</strong>.
</p>
</section>
</body>
</document>

109
webapps/docs/config/service.xml Normal file
View File

@@ -0,0 +1,109 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="service.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Service Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Service</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="name" required="true">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<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>
</section>
<section name="Special Features">
<p>There are no special features associated with a <strong>Service</strong>.
</p>
</section>
</body>
</document>

131
webapps/docs/config/sessionidgenerator.xml Normal file
View File

@@ -0,0 +1,131 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="sessionidgenerator.html">
&project;
<properties>
<title>The SessionIdGenerator Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<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, &#x2014; see
<em>Standard SessionIdGenerator Implementation</em> below for the details
of this configuration.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>SessionIdGenerator</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<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>
</attribute>
<attribute name="jvmRoute" required="false">
<p>A routing identifier for this Tomcat instance. It will be added
to the session id to allow for stateless stickyness 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>
</attribute>
<attribute name="sessionIdLength" required="false">
<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>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<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>
<attributes>
<attribute name="jvmRoute" required="false">
<p>A routing identifier for this Tomcat instance. It will be added
to the end of the session id separated by a &quot;.&quot;.</p>
</attribute>
<attribute name="sessionIdLength" required="false">
<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>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

693
webapps/docs/config/systemprops.xml Normal file
View File

@@ -0,0 +1,693 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="systemprops.html">
&project;
<properties>
<title>System Properties</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The following sections list the system properties that may be set to modify
the default Tomcat behaviour.</p>
</section>
<section name="Property replacements">
<properties>
<property name="org.apache.tomcat.util.digester. PROPERTY_SOURCE">
<p>Set this to a fully qualified name of a class that implements
<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}</code> denoted parameters 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.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>
</property>
<property name="org.apache.tomcat.util.digester. REPLACE_SYSTEM_PROPERTIES">
<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>
</property>
</properties>
</section>
<section name="Clustering">
<properties>
<property name="org.apache.catalina. tribes.dns_lookups">
<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>
</property>
</properties>
</section>
<section name="Expression Language">
<properties>
<property name="org.apache.el.BeanELResolver. CACHE_SIZE">
<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>
</property>
<property name="org.apache.el.ExpressionBuilder. CACHE_SIZE">
<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>
</property>
<property name="org.apache.el.parser. COERCE_TO_ZERO">
<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>
</property>
<property name="org.apache.el.parser. SKIP_IDENTIFIER_CHECK">
<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>
</property>
</properties>
</section>
<section name="Jasper">
<properties>
<property name="org.apache.jasper.compiler. Generator.POOL_TAGS_WITH_EXTENDS">
<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>
</property>
<property name="org.apache.jasper.compiler. Generator.STRICT_GET_PROPERTY">
<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>
</property>
<property name="org.apache.jasper.compiler. Generator.VAR_EXPRESSIONFACTORY">
<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>
</property>
<property name="org.apache.jasper.compiler. Generator.VAR_INSTANCEMANAGER">
<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>
</property>
<property name="org.apache.jasper.compiler. Parser.STRICT_WHITESPACE">
<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>
</property>
<property name="org.apache.jasper.runtime. BodyContentImpl.BUFFER_SIZE">
<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>
</property>
<property name="org.apache.jasper.runtime. BodyContentImpl.LIMIT_BUFFER">
<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>
</property>
<property name="org.apache.jasper.runtime. JspFactoryImpl.USE_POOL">
<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>
</property>
<property name="org.apache.jasper.runtime. JspFactoryImpl.POOL_SIZE">
<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>
</property>
<property name="org.apache.jasper.Constants. JSP_SERVLET_BASE">
<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>
</property>
<property name="org.apache.jasper.Constants. SERVICE_METHOD_NAME">
<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>
</property>
<property name="org.apache.jasper.Constants. SERVLET_CLASSPATH">
<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>
</property>
<property name="org.apache.jasper.Constants. JSP_FILE">
<p>The name of the request attribute for <code>&lt;jsp-file&gt;</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>
</property>
<property name="org.apache.jasper.Constants. PRECOMPILE">
<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>
</property>
<property name="org.apache.jasper.Constants. JSP_PACKAGE_NAME">
<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>
</property>
<property name="org.apache.jasper.Constants. TAG_FILE_PACKAGE_NAME">
<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>
</property>
<property name="org.apache.jasper.Constants. ALT_DD_ATTR">
<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>
</property>
<property name="org.apache.jasper.Constants. TEMP_VARIABLE_NAME_PREFIX">
<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>
</property>
<property name="org.apache.jasper.Constants. USE_INSTANCE_MANAGER_FOR_TAGS">
<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>
</property>
</properties>
</section>
<section name="Security">
<properties>
<property name="org.apache.catalina.connector. RECYCLE_FACADES">
<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>
</property>
<property
name="org.apache.catalina.connector. CoyoteAdapter.ALLOW_BACKSLASH">
<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>
</property>
<property
name="org.apache.tomcat.util.buf. UDecoder.ALLOW_ENCODED_SLASH">
<p>If this is <code>true</code> '%2F' and '%5C' will be permitted as path
delimiters.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
</properties>
</section>
<section name="Specifications">
<properties>
<property name="org.apache.catalina. STRICT_SERVLET_COMPLIANCE">
<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>URIEncoding</code> attribute of any
<a href="http.html">HTTP connector</a> or
<a href="ajp.html">AJP connector</a> element.</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>
</property>
<property name="org.apache.catalina.connector. Response.ENFORCE_ENCODING_IN_GET_WRITER">
<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>
</property>
<property name="org.apache.catalina.core.ApplicationContext .GET_RESOURCE_REQUIRE_SLASH">
<p>If this is <code>true</code> then the path passed to
<code>ServletContext.getResource()</code> or
<code>ServletContext.getResourceAsStream()</code> must start with
&quot;/&quot;. If <code>false</code>, code like
<code>getResource("myfolder/myresource.txt")</code> will work as Tomcat
will prepend &quot;/&quot; 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>
</property>
<property name="org.apache.catalina.core. ApplicationDispatcher.WRAP_SAME_OBJECT">
<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>
</property>
<property name="org.apache.tomcat.websocket. STRICT_SPEC_COMPLIANCE">
<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>
</property>
<property name="org.apache.tomcat.util.http. ServerCookie.STRICT_NAMING">
<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>
</property>
</properties>
</section>
<section name="Sessions">
<properties>
<property name="org.apache.catalina.authenticator.
Constants.SSO_SESSION_COOKIE_NAME">
<p>An alternative name for the single sign on session cookie. Defaults to
<code>JSESSIONIDSSO</code>.</p>
</property>
<property name="org.apache.catalina.core. StandardHostValve.ACCESS_SESSION">
<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>
</property>
<property
name="org.apache.catalina.session. StandardSession.ACTIVITY_CHECK">
<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>
</property>
<property
name="org.apache.catalina.session. StandardSession.LAST_ACCESS_AT_START">
<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>
</property>
</properties>
</section>
<section name="Logging">
<properties>
<property name="org.apache.juli.formatter">
<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>
</property>
<property name="org.apache.juli. AsyncMaxRecordCount">
<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>
</property>
<property name="org.apache.juli. AsyncOverflowDropType">
<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>
</property>
<property name="org.apache.juli. AsyncLoggerPollInterval">
<p>The poll interval in milliseconds for the asynchronous logger thread.
If the log queue is empty, the async thread will issue a poll(poll interval)
in order to not wake up too often.</p>
<p>The default value is <code>1000</code> milliseconds.</p>
</property>
<property name="org.apache.juli.logging. UserDataHelper.CONFIG">
<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>
</ul>
<p>Other errors triggered by invalid input data may be added to this
system in later versions.</p>
</property>
<property name="org.apache.juli.logging. UserDataHelper.SUPPRESSION_TIME">
<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>
</property>
</properties>
</section>
<section name="JAR Scanning">
<properties>
<property name="tomcat.util.scan. StandardJarScanFilter.jarsToSkip">
<p>A list of comma-separated file name patters 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>
</property>
<property name="tomcat.util.scan. StandardJarScanFilter.jarsToScan">
<p>A list of comma-separated file name patters 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>
</property>
</properties>
</section>
<section name="Websockets">
<properties>
<property name="org.apache.tomcat. websocket.ALLOW_UNSUPPORTED_EXTENSIONS">
<p>If <code>true</code>, allow unknown extensions to be declared by
the user.</p>
<p>The default value is <code>false</code>.</p>
</property>
<property name="org.apache.tomcat. websocket.DEFAULT_ORIGIN_HEADER_VALUE">
<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>
</property>
<property name="org.apache.tomcat. websocket.DEFAULT_PROCESS_PERIOD">
<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>
</property>
<property name="org.apache.tomcat. websocket.DISABLE_BUILTIN_EXTENSIONS">
<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>
</property>
</properties>
</section>
<section name="Other">
<properties>
<property
name="org.apache.coyote. USE_CUSTOM_STATUS_MSG_IN_HEADER"><p>If this is
<code>true</code>, custom HTTP status messages will be used within HTTP
headers. If a custom message is specified that is not valid for use in an
HTTP header (as defined by RFC2616) then the custom message will be
ignored and the default message used.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
<p><strong>Note:</strong> This option is deprecated and will be removed
in Tomcat 9. The reason phrase will not be sent.</p>
</property>
<property name="catalina.useNaming">
<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>
</property>
<property name="javax.sql.DataSource.Factory">
<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>
</property>
<property name="javax.mail.Session.Factory">
<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>
</property>
<property name="jvmRoute">
<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>
</property>
<property name="catalina.config">
<p>The URL for the catalina.properties configuration file.</p>
</property>
<property name="tomcat.util.buf.StringCache.byte.enabled">
<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>
</property>
<property name="tomcat.util.buf.StringCache.char.enabled">
<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>
</property>
<property name="tomcat.util.buf.StringCache.trainThreshold">
<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>
</property>
<property name="tomcat.util.buf.StringCache.cacheSize">
<p>The size of the String cache.</p>
<p>If not specified, the default value of <code>200</code> will be used.</p>
</property>
<property name="org.apache.tomcat.util.buf.UriUtil. WAR_SEPARATOR">
<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>
</property>
<property name="tomcat.util.buf.StringCache.maxStringSize">
<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>
</property>
<property name="org.apache.tomcat.util. http.FastHttpDateFormat.CACHE_SIZE">
<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>
</property>
<property name="org.apache.tomcat.util. net.NioSelectorShared">
<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>
</property>
<property name="org.apache.catalina.startup. EXIT_ON_INIT_FAILURE">
<p>If <code>true</code>, the server will exit if an exception happens
during the server initialization phase.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property name="org.apache.catalina.startup. RealmRuleSet.MAX_NESTED_REALM_LEVELS">
<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>
</property>
<property name="org.apache.catalina.startup. CredentialHandlerRuleSet.MAX_NESTED_LEVELS">
<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>
</property>
<property name="tomcat.util.http.parser.HttpParser. requestTargetAllow">
<p><i>This system property is deprecated. Use the
<code>relaxedPathChars</code> and <code>relaxedQueryChars</code>
attributes of the Connector instead. These attributes permit a wider range
of characters to be configured as valid.</i></p>
<p>A string comprised of characters the server should allow even when they are not encoded.
These characters would normally result in a 400 status.</p>
<p>The acceptable characters for this property are: <code>|</code>, <code>{</code>
, and <code>}</code></p>
<p><strong>WARNING</strong>: Use of this option may expose the server to CVE-2016-6816.
</p>
<p>If not specified, the default value of <code>null</code> will be used.</p>
</property>
</properties>
</section>
</body>
</document>

2206
webapps/docs/config/valve.xml Normal file
View File

File diff suppressed because it is too large Load Diff