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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff

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

File diff suppressed because it is too large Load Diff