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

18
webapps/docs/META-INF/context.xml Normal file
View File

@@ -0,0 +1,18 @@
<?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.
-->
<Context antiResourceLocking="false" />

29
webapps/docs/WEB-INF/web.xml Normal file
View File

@@ -0,0 +1,29 @@
<?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.
-->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1"
metadata-complete="true">
<display-name>Tomcat Documentation</display-name>
<description>
Tomcat Documentation.
</description>
</web-app>

88
webapps/docs/aio.xml Normal file
View File

@@ -0,0 +1,88 @@
<?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="aio.html">
&project;
<properties>
<title>Advanced IO and Tomcat</title>
<author>Remy Maucherat</author>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
<b>IMPORTANT NOTE: Usage of these features requires using the
HTTP connectors. The AJP connectors do not support them.</b>
</p>
</section>
<section name="Asynchronous writes">
<p>
When using HTTP connectors (based on APR or NIO/NIO2),
Tomcat supports using sendfile to send large static files.
These writes, as soon as the system load increases, will be performed
asynchronously in the most efficient way. Instead of sending a large response using
blocking writes, it is possible to write content to a static file, and write it
using a sendfile code. A caching valve could take advantage of this to cache the
response data in a file rather than store it in memory. Sendfile support is
available if the request attribute <code>org.apache.tomcat.sendfile.support</code>
is set to <code>Boolean.TRUE</code>.
</p>
<p>
Any servlet can instruct Tomcat to perform a sendfile call by setting the appropriate
request attributes. It is also necessary to correctly set the content length
for the response. When using sendfile, it is best to ensure that neither the
request or response have been wrapped, since as the response body will be sent later
by the connector itself, it cannot be filtered. Other than setting the 3 needed
request attributes, the servlet should not send any response data, but it may use
any method which will result in modifying the response header (like setting cookies).
</p>
<ul>
<li><code>org.apache.tomcat.sendfile.filename</code>: Canonical filename of the file which will be sent as
a String</li>
<li><code>org.apache.tomcat.sendfile.start</code>: Start offset as a Long</li>
<li><code>org.apache.tomcat.sendfile.end</code>: End offset as a Long</li>
</ul>
<p>
In addition to setting these parameters it is necessary to set the content-length header.
Tomcat will not do that for you, since you may have already written data to the output stream.
</p>
<p>
Note that the use of sendfile will disable any compression that Tomcat may
otherwise have performed on the response.
</p>
</section>
</body>
</document>

34
webapps/docs/annotationapi/index.html Normal file
View File

@@ -0,0 +1,34 @@
<!--
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 html>
<html>
<head>
<meta charset="UTF-8" />
<title>API docs</title>
</head>
<body>
The Annotation API Javadoc is not installed by default. Download and install
the "fulldocs" package to get it.
You can also access the javadoc online in the Tomcat
<a href="https://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/">
documentation bundle</a>.
</body>
</html>

34
webapps/docs/api/index.html Normal file
View File

@@ -0,0 +1,34 @@
<!--
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 html>
<html>
<head>
<meta charset="UTF-8" />
<title>API docs</title>
</head>
<body>
Tomcat's internal javadoc is not installed by default. Download and install
the "fulldocs" package to get it.
You can also access the javadoc online in the Tomcat
<a href="https://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/">
documentation bundle</a>.
</body>
</html>

508
webapps/docs/appdev/build.xml.txt Normal file
View File

@@ -0,0 +1,508 @@
<!--
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.
-->
<!--
General purpose build script for web applications and web services,
including enhanced support for deploying directly to a Tomcat
based server.
This build script assumes that the source code of your web application
is organized into the following subdirectories underneath the source
code directory from which you execute the build script:
docs Static documentation files to be copied to
the "docs" subdirectory of your distribution.
src Java source code (and associated resource files)
to be compiled to the "WEB-INF/classes"
subdirectory of your web application.
web Static HTML, JSP, and other content (such as
image files), including the WEB-INF subdirectory
and its configuration file contents.
-->
<!-- A "project" describes a set of targets that may be requested
when Ant is executed. The "default" attribute defines the
target which is executed if no specific target is requested,
and the "basedir" attribute defines the current working directory
from which Ant executes the requested task. This is normally
set to the current working directory.
-->
<project name="My Project" default="compile" basedir=".">
<!-- ===================== Property Definitions =========================== -->
<!--
Each of the following properties are used in the build script.
Values for these properties are set by the first place they are
defined, from the following list:
* Definitions on the "ant" command line (ant -Dfoo=bar compile).
* Definitions from a "build.properties" file in the top level
source directory of this application.
* Definitions from a "build.properties" file in the developer's
home directory.
* Default definitions in this build.xml file.
You will note below that property values can be composed based on the
contents of previously defined properties. This is a powerful technique
that helps you minimize the number of changes required when your development
environment is modified. Note that property composition is allowed within
"build.properties" files as well as in the "build.xml" script.
-->
<property file="build.properties"/>
<property file="${user.home}/build.properties"/>
<!-- ==================== File and Directory Names ======================== -->
<!--
These properties generally define file and directory names (or paths) that
affect where the build process stores its outputs.
app.name Base name of this application, used to
construct filenames and directories.
Defaults to "myapp".
app.path Context path to which this application should be
deployed (defaults to "/" plus the value of the
"app.name" property).
app.version Version number of this iteration of the application.
build.home The directory into which the "prepare" and
"compile" targets will generate their output.
Defaults to "build".
catalina.home The directory in which you have installed
a binary distribution of Tomcat. This will
be used by the "deploy" target.
dist.home The name of the base directory in which
distribution files are created.
Defaults to "dist".
manager.password The login password of a user that is assigned the
"manager-script" role (so that he or she can execute
commands via the "/manager" web application)
manager.url The URL of the "/manager" web application on the
Tomcat installation to which we will deploy web
applications and web services.
manager.username The login username of a user that is assigned the
"manager-script" role (so that he or she can execute
commands via the "/manager" web application)
-->
<property name="app.name" value="myapp"/>
<property name="app.path" value="/${app.name}"/>
<property name="app.version" value="0.1-dev"/>
<property name="build.home" value="${basedir}/build"/>
<property name="catalina.home" value="../../../.."/> <!-- UPDATE THIS! -->
<property name="dist.home" value="${basedir}/dist"/>
<property name="docs.home" value="${basedir}/docs"/>
<property name="manager.url" value="http://localhost:8080/manager/text"/>
<property name="src.home" value="${basedir}/src"/>
<property name="web.home" value="${basedir}/web"/>
<!-- ==================== External Dependencies =========================== -->
<!--
Use property values to define the locations of external JAR files on which
your application will depend. In general, these values will be used for
two purposes:
* Inclusion on the classpath that is passed to the Javac compiler
* Being copied into the "/WEB-INF/lib" directory during execution
of the "deploy" target.
Because we will automatically include all of the Java classes that Tomcat
exposes to web applications, we will not need to explicitly list any of those
dependencies. You only need to worry about external dependencies for JAR
files that you are going to include inside your "/WEB-INF/lib" directory.
-->
<!-- Dummy external dependency -->
<!--
<property name="foo.jar"
value="/path/to/foo.jar"/>
-->
<!-- ==================== Compilation Classpath =========================== -->
<!--
Rather than relying on the CLASSPATH environment variable, Ant includes
features that makes it easy to dynamically construct the classpath you
need for each compilation. The example below constructs the compile
classpath to include the servlet.jar file, as well as the other components
that Tomcat makes available to web applications automatically, plus anything
that you explicitly added.
-->
<path id="compile.classpath">
<!-- Include all JAR files that will be included in /WEB-INF/lib -->
<!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
<!--
<pathelement location="${foo.jar}"/>
-->
<!-- Include all elements that Tomcat exposes to applications -->
<fileset dir="${catalina.home}/bin">
<include name="*.jar"/>
</fileset>
<pathelement location="${catalina.home}/lib"/>
<fileset dir="${catalina.home}/lib">
<include name="*.jar"/>
</fileset>
</path>
<!-- ================== Custom Ant Task Definitions ======================= -->
<!--
These properties define custom tasks for the Ant build tool that interact
with the "/manager" web application installed with Tomcat. Before they
can be successfully utilized, you must perform the following steps:
- Copy the file "lib/catalina-ant.jar" from your Tomcat
installation into the "lib" directory of your Ant installation.
- Create a "build.properties" file in your application's top-level
source directory (or your user login home directory) that defines
appropriate values for the "manager.password", "manager.url", and
"manager.username" properties described above.
For more information about the Manager web application, and the functionality
of these tasks, see <http://localhost:8080/tomcat-docs/manager-howto.html>.
-->
<taskdef resource="org/apache/catalina/ant/catalina.tasks"
classpathref="compile.classpath"/>
<!-- ==================== Compilation Control Options ==================== -->
<!--
These properties control option settings on the Javac compiler when it
is invoked using the <javac> task.
compile.debug Should compilation include the debug option?
compile.deprecation Should compilation include the deprecation option?
-->
<property name="compile.debug" value="true"/>
<property name="compile.deprecation" value="false"/>
<!-- ==================== All Target ====================================== -->
<!--
The "all" target is a shortcut for running the "clean" target followed
by the "compile" target, to force a complete recompile.
-->
<target name="all" depends="clean,compile"
description="Clean build and dist directories, then compile"/>
<!-- ==================== Clean Target ==================================== -->
<!--
The "clean" target deletes any previous "build" and "dist" directory,
so that you can be ensured the application can be built from scratch.
-->
<target name="clean"
description="Delete old build and dist directories">
<delete dir="${build.home}"/>
<delete dir="${dist.home}"/>
</target>
<!-- ==================== Compile Target ================================== -->
<!--
The "compile" target transforms source files (from your "src" directory)
into object files in the appropriate location in the build directory.
This example assumes that you will be including your classes in an
unpacked directory hierarchy under "/WEB-INF/classes".
-->
<target name="compile" depends="prepare"
description="Compile Java sources">
<!-- Compile Java classes as necessary -->
<mkdir dir="${build.home}/WEB-INF/classes"/>
<javac srcdir="${src.home}"
destdir="${build.home}/WEB-INF/classes"
debug="${compile.debug}"
deprecation="${compile.deprecation}">
<classpath refid="compile.classpath"/>
</javac>
<!-- Copy application resources -->
<copy todir="${build.home}/WEB-INF/classes">
<fileset dir="${src.home}" excludes="**/*.java"/>
</copy>
</target>
<!-- ==================== Dist Target ===================================== -->
<!--
The "dist" target creates a binary distribution of your application
in a directory structure ready to be archived in a tar.gz or zip file.
Note that this target depends on two others:
* "compile" so that the entire web application (including external
dependencies) will have been assembled
* "javadoc" so that the application Javadocs will have been created
-->
<target name="dist" depends="compile,javadoc"
description="Create binary distribution">
<!-- Copy documentation subdirectories -->
<mkdir dir="${dist.home}/docs"/>
<copy todir="${dist.home}/docs">
<fileset dir="${docs.home}"/>
</copy>
<!-- Create application JAR file -->
<jar jarfile="${dist.home}/${app.name}-${app.version}.war"
basedir="${build.home}"/>
<!-- Copy additional files to ${dist.home} as necessary -->
</target>
<!-- ==================== Install Target ================================== -->
<!--
The "install" target tells the specified Tomcat installation to dynamically
install this web application and make it available for execution. It does
*not* cause the existence of this web application to be remembered across
Tomcat restarts; if you restart the server, you will need to re-install all
this web application.
If you have already installed this application, and simply want Tomcat to
recognize that you have updated Java classes (or the web.xml file), use the
"reload" target instead.
NOTE: This target will only succeed if it is run from the same server that
Tomcat is running on.
NOTE: This is the logical opposite of the "remove" target.
-->
<target name="install" depends="compile"
description="Install application to servlet container">
<deploy url="${manager.url}"
username="${manager.username}"
password="${manager.password}"
path="${app.path}"
localWar="file://${build.home}"/>
</target>
<!-- ==================== Javadoc Target ================================== -->
<!--
The "javadoc" target creates Javadoc API documentation for the Java
classes included in your application. Normally, this is only required
when preparing a distribution release, but is available as a separate
target in case the developer wants to create Javadocs independently.
-->
<target name="javadoc" depends="compile"
description="Create Javadoc API documentation">
<mkdir dir="${dist.home}/docs/api"/>
<javadoc sourcepath="${src.home}"
destdir="${dist.home}/docs/api"
packagenames="*">
<classpath refid="compile.classpath"/>
</javadoc>
</target>
<!-- ====================== List Target =================================== -->
<!--
The "list" target asks the specified Tomcat installation to list the
currently running web applications, either loaded at startup time or
installed dynamically. It is useful to determine whether or not the
application you are currently developing has been installed.
-->
<target name="list"
description="List installed applications on servlet container">
<list url="${manager.url}"
username="${manager.username}"
password="${manager.password}"/>
</target>
<!-- ==================== Prepare Target ================================== -->
<!--
The "prepare" target is used to create the "build" destination directory,
and copy the static contents of your web application to it. If you need
to copy static files from external dependencies, you can customize the
contents of this task.
Normally, this task is executed indirectly when needed.
-->
<target name="prepare">
<!-- Create build directories as needed -->
<mkdir dir="${build.home}"/>
<mkdir dir="${build.home}/WEB-INF"/>
<mkdir dir="${build.home}/WEB-INF/classes"/>
<!-- Copy static content of this web application -->
<copy todir="${build.home}">
<fileset dir="${web.home}"/>
</copy>
<!-- Copy external dependencies as required -->
<!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
<mkdir dir="${build.home}/WEB-INF/lib"/>
<!--
<copy todir="${build.home}/WEB-INF/lib" file="${foo.jar}"/>
-->
<!-- Copy static files from external dependencies as needed -->
<!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
</target>
<!-- ==================== Reload Target =================================== -->
<!--
The "reload" signals the specified application Tomcat to shut itself down
and reload. This can be useful when the web application context is not
reloadable and you have updated classes or property files in the
/WEB-INF/classes directory or when you have added or updated jar files in the
/WEB-INF/lib directory.
NOTE: The /WEB-INF/web.xml web application configuration file is not reread
on a reload. If you have made changes to your web.xml file you must stop
then start the web application.
-->
<target name="reload" depends="compile"
description="Reload application on servlet container">
<reload url="${manager.url}"
username="${manager.username}"
password="${manager.password}"
path="${app.path}"/>
</target>
<!-- ==================== Remove Target =================================== -->
<!--
The "remove" target tells the specified Tomcat installation to dynamically
remove this web application from service.
NOTE: This is the logical opposite of the "install" target.
-->
<target name="remove"
description="Remove application on servlet container">
<undeploy url="${manager.url}"
username="${manager.username}"
password="${manager.password}"
path="${app.path}"/>
</target>
</project>

249
webapps/docs/appdev/deployment.xml Normal file
View File

@@ -0,0 +1,249 @@
<?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="deployment.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Deployment</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Background">
<p>Before describing how to organize your source code directories,
it is useful to examine the runtime organization of a web application.
Prior to the Servlet API Specification, version 2.2, there was little
consistency between server platforms. However, servers that conform
to the 2.2 (or later) specification are required to accept a
<em>Web Application Archive</em> in a standard format, which is discussed
further below.</p>
<p>A web application is defined as a hierarchy of directories and files
in a standard layout. Such a hierarchy can be accessed in its "unpacked"
form, where each directory and file exists in the filesystem separately,
or in a "packed" form known as a Web ARchive, or WAR file. The former format
is more useful during development, while the latter is used when you
distribute your application to be installed.</p>
<p>The top-level directory of your web application hierarchy is also the
<em>document root</em> of your application. Here, you will place the HTML
files and JSP pages that comprise your application's user interface. When the
system administrator deploys your application into a particular server, he
or she assigns a <em>context path</em> to your application (a later section
of this manual describes deployment on Tomcat). Thus, if the
system administrator assigns your application to the context path
<code>/catalog</code>, then a request URI referring to
<code>/catalog/index.html</code> will retrieve the <code>index.html</code>
file from your document root.</p>
</section>
<section name="Standard Directory Layout">
<p>To facilitate creation of a Web Application Archive file in the required
format, it is convenient to arrange the "executable" files of your web
application (that is, the files that Tomcat actually uses when executing
your app) in the same organization as required by the WAR format itself.
To do this, you will end up with the following contents in your
application's "document root" directory:</p>
<ul>
<li><strong>*.html, *.jsp, etc.</strong> - The HTML and JSP pages, along
with other files that must be visible to the client browser (such as
JavaScript, stylesheet files, and images) for your application.
In larger applications you may choose to divide these files into
a subdirectory hierarchy, but for smaller apps, it is generally
much simpler to maintain only a single directory for these files.
<br/><br/></li>
<li><strong>/WEB-INF/web.xml</strong> - The <em>Web Application Deployment
Descriptor</em> for your application. This is an XML file describing
the servlets and other components that make up your application,
along with any initialization parameters and container-managed
security constraints that you want the server to enforce for you.
This file is discussed in more detail in the following subsection.
<br/><br/></li>
<li><strong>/WEB-INF/classes/</strong> - This directory contains any Java
class files (and associated resources) required for your application,
including both servlet and non-servlet classes, that are not combined
into JAR files. If your classes are organized into Java packages,
you must reflect this in the directory hierarchy under
<code>/WEB-INF/classes/</code>. For example, a Java class named
<code>com.mycompany.mypackage.MyServlet</code>
would need to be stored in a file named
<code>/WEB-INF/classes/com/mycompany/mypackage/MyServlet.class</code>.
<br/><br/></li>
<li><strong>/WEB-INF/lib/</strong> - This directory contains JAR files that
contain Java class files (and associated resources) required for your
application, such as third party class libraries or JDBC drivers.</li>
</ul>
<p>When you install an application into Tomcat (or any other 2.2 or later
Servlet container), the classes in the <code>WEB-INF/classes/</code>
directory, as well as all classes in JAR files found in the
<code>WEB-INF/lib/</code> directory, are made visible to other classes
within your particular web application. Thus, if
you include all of the required library classes in one of these places (be
sure to check licenses for redistribution rights for any third party libraries
you utilize), you will simplify the installation of your web application --
no adjustment to the system class path (or installation of global library
files in your server) will be necessary.</p>
<p>Much of this information was extracted from Chapter 9 of the Servlet
API Specification, version 2.3, which you should consult for more details.</p>
</section>
<section name="Shared Library Files">
<p>Like most servlet containers, Tomcat also supports mechanisms to install
library JAR files (or unpacked classes) once, and make them visible to all
installed web applications (without having to be included inside the web
application itself). The details of how Tomcat locates and shares such
classes are described in the
<a href="../class-loader-howto.html">Class Loader How-To</a> documentation.
The location commonly used within a Tomcat installation for shared code is
<strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to
web applications and internal Tomcat code. This is a good place to put JDBC
drivers that are required for both your application or internal Tomcat use
(such as for a JDBCRealm).</p>
<p>Out of the box, a standard Tomcat installation includes a variety
of pre-installed shared library files, including:</p>
<ul>
<li>The <em>Servlet 3.1</em> and <em>JSP 2.3</em> APIs that are fundamental
to writing servlets and JavaServer Pages.<br/><br/></li>
</ul>
</section>
<section name="Web Application Deployment Descriptor">
<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains the
Web Application Deployment Descriptor for your application. As the filename
extension implies, this file is an XML document, and defines everything about
your application that a server needs to know (except the <em>context path</em>,
which is assigned by the system administrator when the application is
deployed).</p>
<p>The complete syntax and semantics for the deployment descriptor is defined
in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it
is expected that development tools will be provided that create and edit the
deployment descriptor for you. In the meantime, to provide a starting point,
a <a href="web.xml.txt" target="_blank">basic web.xml file</a>
is provided. This file includes comments that describe the purpose of each
included element.</p>
<p><strong>NOTE</strong> - The Servlet Specification includes a Document
Type Descriptor (DTD) for the web application deployment descriptor, and
Tomcat enforces the rules defined here when processing your application's
<code>/WEB-INF/web.xml</code> file. In particular, you <strong>must</strong>
enter your descriptor elements (such as <code>&lt;filter&gt;</code>,
<code>&lt;servlet&gt;</code>, and <code>&lt;servlet-mapping&gt;</code> in
the order defined by the DTD (see Section 13.3).</p>
</section>
<section name="Tomcat Context Descriptor">
<p>A /META-INF/context.xml file can be used to define Tomcat specific
configuration options, such as an access log, data sources, session manager
configuration and more. This XML file must contain one Context element, which
will be considered as if it was the child of the Host element corresponding
to the Host to which the web application is being deployed. The
<a href="../config/context.html">Tomcat configuration documentation</a> contains
information on the Context element.</p>
</section>
<section name="Deployment With Tomcat">
<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>
<p>In order to be executed, a web application must be deployed on
a servlet container. This is true even during development.
We will describe using Tomcat to provide the execution environment.
A web application can be deployed in Tomcat by one of the following
approaches:</p>
<ul>
<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
<code>$CATALINA_BASE/webapps/</code></em>. Tomcat will assign a
context path to your application based on the subdirectory name you
choose. We will use this technique in the <code>build.xml</code>
file that we construct, because it is the quickest and easiest approach
during development. Be sure to restart Tomcat after installing or
updating your application.
<br/><br/></li>
<li><em>Copy the web application archive file into directory
<code>$CATALINA_BASE/webapps/</code></em>. When Tomcat is started, it will
automatically expand the web application archive file into its unpacked
form, and execute the application that way. This approach would typically
be used to install an additional application, provided by a third party
vendor or by your internal development staff, into an existing
Tomcat installation. <strong>NOTE</strong> - If you use this approach,
and wish to update your application later, you must both replace the
web application archive file <strong>AND</strong> delete the expanded
directory that Tomcat created, and then restart Tomcat, in order to reflect
your changes.
<br/><br/></li>
<li><em>Use the Tomcat "Manager" web application to deploy and undeploy
web applications</em>. Tomcat includes a web application, deployed
by default on context path <code>/manager</code>, that allows you to
deploy and undeploy applications on a running Tomcat server without
restarting it. See <a href="../manager-howto.html">Manager App How-To</a>
for more information on using the Manager web application.<br/><br/></li>
<li><em>Use "Manager" Ant Tasks In Your Build Script</em>. Tomcat
includes a set of custom task definitions for the <code>Ant</code>
build tool that allow you to automate the execution of commands to the
"Manager" web application. These tasks are used in the Tomcat deployer.
<br/><br/></li>
<li><em>Use the Tomcat Deployer</em>. Tomcat includes a packaged tool
bundling the Ant tasks, and can be used to automatically precompile JSPs
which are part of the web application before deployment to the server.
<br/><br/></li>
</ul>
<p>Deploying your app on other servlet containers will be specific to each
container, but all containers compatible with the Servlet API Specification
(version 2.2 or later) are required to accept a web application archive file.
Note that other containers are <strong>NOT</strong> required to accept an
unpacked directory structure (as Tomcat does), or to provide mechanisms for
shared library files, but these features are commonly available.</p>
</section>
</body>
</document>

79
webapps/docs/appdev/index.xml Normal file
View File

@@ -0,0 +1,79 @@
<?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>Table of Contents</title>
</properties>
<body>
<section name="Preface">
<p>This manual includes contributions from many members of the Tomcat Project
developer community. The following authors have provided significant content:
</p>
<ul>
<li>Craig R. McClanahan
(<a href="mailto:craigmcc@apache.org">craigmcc@apache.org</a>)</li>
</ul>
</section>
<section name="Table of Contents">
<p>The information presented is divided into the following sections:</p>
<ul>
<li><a href="introduction.html"><strong>Introduction</strong></a> -
Briefly describes the information covered here, with
links and references to other sources of information.</li>
<li><a href="installation.html"><strong>Installation</strong></a> -
Covers acquiring and installing the required software
components to use Tomcat for web application development.</li>
<li><a href="deployment.html"><strong>Deployment Organization</strong></a> -
Discusses the standard directory layout for a web application
(defined in the Servlet API Specification), the Web Application
Deployment Descriptor, and options for integration with Tomcat
in your development environment.</li>
<li><a href="source.html"><strong>Source Organization</strong></a> -
Describes a useful approach to organizing the source code
directories for your project, and introduces the
<code>build.xml</code> used by Ant to manage compilation.</li>
<li><a href="processes.html"><strong>Development Processes</strong></a> -
Provides brief descriptions of typical development processes
utilizing the recommended deployment and source organizations.</li>
<li><a href="sample/" target="_blank"><strong>Example Application</strong></a> -
This directory contains a very simple, but functionally complete,
"Hello, World" application built according to the principles
described in this manual. You can use this application to
practice using the described techniques.</li>
</ul>
</section>
</body>
</document>

105
webapps/docs/appdev/installation.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="installation.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Installation</title>
</properties>
<body>
<section name="Installation">
<p>In order to use Tomcat for developing web applications, you must first
install it (and the software it depends on). The required steps are outlined
in the following subsections.</p>
<subsection name="JDK">
<p>Tomcat <version-major-minor/> was designed to run on Java <min-java-version/> or later.
</p>
<p>Compatible JDKs for many platforms (or links to where they can be found)
are available at
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a>.</p>
</subsection>
<subsection name="Tomcat">
<p>Binary downloads of the <strong>Tomcat</strong> server are available from
<a href="https://tomcat.apache.org/">https://tomcat.apache.org/</a>.
This manual assumes you are using the most recent release
of Tomcat <version-major/>. Detailed instructions for downloading and installing
Tomcat are available <a href="../setup.html">here</a>.</p>
<p>In the remainder of this manual, example shell scripts assume that you have
set an environment variable <code>CATALINA_HOME</code> that contains the
pathname to the directory in which Tomcat has been installed. Optionally, if
Tomcat has been configured for multiple instances, each instance will have its
own <code>CATALINA_BASE</code> configured.</p>
</subsection>
<subsection name="Ant">
<p>Binary downloads of the <strong>Ant</strong> build tool are available from
<a href="https://ant.apache.org/">https://ant.apache.org/</a>.
This manual assumes you are using Ant 1.8 or later. The instructions may
also be compatible with other versions, but this has not been tested.</p>
<p>Download and install Ant.
Then, add the <code>bin</code> directory of the Ant distribution to your
<code>PATH</code> environment variable, following the standard practices for
your operating system platform. Once you have done this, you will be able to
execute the <code>ant</code> shell command directly.</p>
</subsection>
<subsection name="CVS">
<p>Besides the required tools described above, you are strongly encouraged
to download and install a <em>source code control</em> system, such as the
<strong>Concurrent Version System</strong> (CVS), to maintain historical
versions of the source files that make up your web application. Besides
the server, you will also need appropriate client
tools to check out source code files, and check in modified versions.</p>
<p>Detailed instructions for installing and using source code control
applications is beyond the scope of this manual. However, CVS server and
client tools for many platforms (along with documentation) can be downloaded
from <a href="http://www.cvshome.org/">http://www.cvshome.org/</a>.</p>
</subsection>
</section>
</body>
</document>

92
webapps/docs/appdev/introduction.xml Normal file
View File

@@ -0,0 +1,92 @@
<?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="introduction.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Introduction</title>
</properties>
<body>
<section name="Overview">
<p>Congratulations! You've decided to (or been told to) learn how to
build web applications using servlets and JSP pages, and picked the
Tomcat server to use for your learning and development. But now what
do you do?</p>
<p>This manual is a primer covering the basic steps of using Tomcat to
set up a development environment, organize your source code, and then
build and test your application. It does not discuss architectures or
recommended coding practices for web application development,
or provide in depth instructions on operating the development
tools that are discussed. References to sources of additional information
are included in the following subsections.</p>
<p>The discussion in this manual is aimed at developers who will be using
a text editor along with command line tools to develop and debug their
applications. As such, the recommendations are fairly generic &#x2013; but you
should easily be able to apply them in either a Windows-based or Unix-based
development environment. If you are utilizing an Integrated Development
Environment (IDE) tool, you will need to adapt the advice given here to
the details of your particular environment.</p>
</section>
<section name="Links">
<p>The following links provide access to selected sources of online
information, documentation, and software that is useful in developing
web applications with Tomcat.</p>
<ul>
<li><p><a href="https://jcp.org/aboutJava/communityprocess/mrel/jsr245/index2.html">https://jcp.org/aboutJava/communityprocess/mrel/jsr245/index2.html</a> -
<i>JavaServer Pages (JSP) Specification, Version 2.3</i>. Describes
the programming environment provided by standard implementations
of the JavaServer Pages (JSP) technology. In conjunction with
the Servlet API Specification (see below), this document describes
what a portable API page is allowed to contain. Specific
information on scripting (Chapter 9), tag extensions (Chapter 7),
and packaging JSP pages (Appendix A) is useful. The Javadoc
API Documentation is included in the specification, and with the
Tomcat download.</p></li>
<li><p><a href="http://jcp.org/aboutJava/communityprocess/final/jsr340/index.html">http://jcp.org/aboutJava/communityprocess/final/jsr340/index.html</a> -
<i>Servlet API Specification, Version 3.1</i>. Describes the
programming environment that must be provided by all servlet
containers conforming to this specification. In particular, you
will need this document to understand the web application
directory structure and deployment file (Chapter 10), methods of
mapping request URIs to servlets (Chapter 12), container managed
security (Chapter 13), and the syntax of the <code>web.xml</code>
Web Application Deployment Descriptor (Chapter 14). The Javadoc
API Documentation is included in the specification, and with the
Tomcat download.</p></li>
</ul>
</section>
</body>
</document>

304
webapps/docs/appdev/processes.xml Normal file
View File

@@ -0,0 +1,304 @@
<?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="processes.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Development Processes</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Development Processes">
<p>Although application development can take many forms, this manual proposes
a fairly generic process for creating web applications using Tomcat. The
following sections highlight the commands and tasks that you, as the developer
of the code, will perform. The same basic approach works when you have
multiple programmers involved, as long as you have an appropriate source code
control system and internal team rules about who is working on what parts
of the application at any given time.</p>
<p>The task descriptions below assume that you will be using CVS for source
code control, and that you have already configured access to the appropriate
CVS repository. Instructions for doing this are beyond the scope of this
manual. If you are using a different source code control environment, you
will need to figure out the corresponding commands for your system.</p>
<subsection name="One-Time Setup of Ant and Tomcat for Development">
<p>In order to take advantage of the special Ant tasks that interact with the
<em>Manager</em> web application, you need to perform the following tasks
once (no matter how many web applications you plan to develop).</p>
<ul>
<li><p><em>Configure the Ant custom tasks</em>. The implementation code for the
Ant custom tasks is in a JAR file named
<code>$CATALINA_HOME/lib/catalina-ant.jar</code>, which must be
copied in to the <code>lib</code> directory of your Ant installation.
</p></li>
<li><p><em>Define one or more Tomcat users</em>. The <em>Manager</em> web
application runs under a security constraint that requires a user to be
logged in, and have the security role <code>manager-script</code> assigned
to him or her. How such users are defined depends on which Realm you have
configured in Tomcat's <code>conf/server.xml</code> file -- see the
<a href="../realm-howto.html">Realm Configuration How-To</a> for more
information. You may define any number of users (with any username
and password that you like) with the <code>manager-script</code> role.
</p></li>
</ul>
</subsection>
<subsection name="Create Project Source Code Directory">
<p>The first step is to create a new project source directory, and customize
the <code>build.xml</code> and <code>build.properties</code> files you will
be using. The directory structure is described in <a href="source.html">the
previous section</a>, or you can use the
<a href="sample/">sample application</a> as a starting point.</p>
<p>Create your project source directory, and define it within your CVS
repository. This might be done by a series of commands like this, where
<code>{project}</code> is the name under which your project should be
stored in the CVS repository, and {username} is your login username:</p>
<source><![CDATA[cd {my home directory}
mkdir myapp <-- Assumed "project source directory"
cd myapp
mkdir docs
mkdir src
mkdir web
mkdir web/WEB-INF
cvs import -m "Initial Project Creation" {project} \
{username} start]]></source>
<p>Now, to verify that it was created correctly in CVS, we will perform a
checkout of the new project:</p>
<source><![CDATA[cd ..
mv myapp myapp.bu
cvs checkout {project}]]></source>
<p>Next, you will need to create and check in an initial version of the
<code>build.xml</code> script to be used for development. For getting
started quickly and easily, base your <code>build.xml</code> on the
<a href="build.xml.txt">basic build.xml file</a>, included with this manual,
or code it from scratch.</p>
<source><![CDATA[cd {my home directory}
cd myapp
emacs build.xml <-- if you want a real editor :-)
cvs add build.xml
cvs commit]]></source>
<p>Until you perform the CVS commit, your changes are local to your own
development directory. Committing makes those changes visible to other
developers on your team that are sharing the same CVS repository.</p>
<p>The next step is to customize the Ant <em>properties</em> that are
named in the <code>build.xml</code> script. This is done by creating a
file named <code>build.properties</code> in your project's top-level
directory. The supported properties are listed in the comments inside
the sample <code>build.xml</code> script. At a minimum, you will generally
need to define the <code>catalina.home</code> property defining where
Tomcat is installed, and the manager application username and password.
You might end up with something like this:</p>
<source># Context path to install this application on
app.path=/hello
# Tomcat installation directory
catalina.home=/usr/local/apache-tomcat-<version-major-minor/>
# Manager webapp username and password
manager.username=myusername
manager.password=mypassword</source>
<p>In general, you will <strong>not</strong> want to check the
<code>build.properties</code> file in to the CVS repository, because it
is unique to each developer's environment.</p>
<p>Now, create the initial version of the web application deployment
descriptor. You can base <code>web.xml</code> on the
<a href="web.xml.txt">basic web.xml file</a>, or code it from scratch.</p>
<source><![CDATA[cd {my home directory}
cd myapp/web/WEB-INF
emacs web.xml
cvs add web.xml
cvs commit]]></source>
Note that this is only an example web.xml file. The full definition
of the deployment descriptor file is in the
<a href="https://wiki.apache.org/tomcat/Specifications">Servlet Specification.</a>
</subsection>
<subsection name="Edit Source Code and Pages">
<p>The edit/build/test tasks will generally be your most common activities
during development and maintenance. The following general principles apply.
As described in <a href="source.html">Source Organization</a>, newly created
source files should be located in the appropriate subdirectory, under your
project source directory.</p>
<p>Whenever you wish to refresh your development directory to reflect the
work performed by other developers, you will ask CVS to do it for you:</p>
<source><![CDATA[cd {my home directory}
cd myapp
cvs update -dP]]></source>
<p>To create a new file, go to the appropriate directory, create the file,
and register it with CVS. When you are satisfied with it's contents (after
building and testing is successful), commit the new file to the repository.
For example, to create a new JSP page:</p>
<source><![CDATA[cd {my home directory}
cd myapp/web <-- Ultimate destination is document root
emacs mypage.jsp
cvs add mypage.jsp
... build and test the application ...
cvs commit]]></source>
<p>Java source code that is defined in packages must be organized in a
directory hierarchy (under the <strong>src/</strong> subdirectory) that
matches the package names. For example, a Java class named
<code>com.mycompany.mypackage.MyClass.java</code> should be stored in file
<code>src/com/mycompany/mypackage/MyClass.java</code>.
Whenever you create a new subdirectory, don't forget to
register it with CVS.</p>
<p>To edit an existing source file, you will generally just start editing
and testing, then commit the changed file when everything works. Although
CVS can be configured to required you to "check out" or "lock" a file you
are going to be modifying, this is generally not used.</p>
</subsection>
<subsection name="Build the Web Application">
<p>When you are ready to compile the application, issue the following
commands (generally, you will want a shell window open that is set to
the project source directory, so that only the last command is needed):</p>
<source><![CDATA[cd {my home directory}
cd myapp <-- Normally leave a window open here
ant]]></source>
<p>The Ant tool will be execute the default "compile" target in your
<code>build.xml</code> file, which will compile any new or updated Java
code. If this is the first time you compile after a "build clean",
it will cause everything to be recompiled.</p>
<p>To force the recompilation of your entire application, do this instead:</p>
<source><![CDATA[cd {my home directory}
cd myapp
ant all]]></source>
<p>This is a very good habit immediately before checking in changes, to
make sure that you have not introduced any subtle problems that Javac's
conditional checking did not catch.</p>
</subsection>
<subsection name="Test Your Web Application">
<p>To test your application, you will want to install it under Tomcat. The
quickest way to do that is to use the custom Ant tasks that are included in
the sample <code>build.xml</code> script. Using these commands might follow
a pattern like this:</p>
<ul>
<li><p><em>Start Tomcat if needed</em>. If Tomcat is not already running,
you will need to start it in the usual way.
</p></li>
<li><p><em>Compile your application</em>. Use the <code>ant compile</code>
command (or just <code>ant</code>, since this is the default). Make
sure that there are no compilation errors.
</p></li>
<li><p><em>Install the application</em>. Use the <code>ant install</code>
command. This tells Tomcat to immediately start running your app on
the context path defined in the <code>app.path</code> build property.
Tomcat does <strong>NOT</strong> have to be restarted for this to
take effect.
</p></li>
<li><p><em>Test the application</em>. Using your browser or other testing
tools, test the functionality of your application.
</p></li>
<li><p><em>Modify and rebuild as needed</em>. As you discover that changes
are required, make those changes in the original <strong>source</strong>
files, not in the output build directory, and re-issue the
<code>ant compile</code> command. This ensures that your changes will
be available to be saved (via <code>cvs commit</code>) later on --
the output build directory is deleted and recreated as necessary.
</p></li>
<li><p><em>Reload the application</em>. Tomcat will recognize changes in
JSP pages automatically, but it will continue to use the old versions
of any servlet or JavaBean classes until the application is reloaded.
You can trigger this by executing the <code>ant reload</code> command.
</p></li>
<li><p><em>Remove the application when you are done</em>. When you are through
working on this application, you can remove it from live execution by
running the <code>ant remove</code> command.
</p></li>
</ul>
<p>Do not forget to commit your changes to the source code repository when
you have completed your testing!</p>
</subsection>
<subsection name="Creating a Release">
<p>When you are through adding new functionality, and you've tested everything
(you DO test, don't you :-), it is time to create the distributable version
of your web application that can be deployed on the production server. The
following general steps are required:</p>
<ul>
<li><p>Issue the command <code>ant all</code> from the project source
directory, to rebuild everything from scratch one last time.
</p></li>
<li><p>Use the <code>cvs tag</code> command to create an identifier for
all of the source files utilized to create this release. This allows
you to reliably reconstruct a release (from sources) at a later
time.
</p></li>
<li><p>Issue the command <code>ant dist</code> to create a distributable
web application archive (WAR) file, as well as a JAR file containing
the corresponding source code.
</p></li>
<li><p>Package the contents of the <code>dist</code> directory using the
<strong>tar</strong> or <strong>zip</strong> utility, according to
the standard release procedures used by your organization.
</p></li>
</ul>
</subsection>
</section>
</body>
</document>

48
webapps/docs/appdev/project.xml Normal file
View File

@@ -0,0 +1,48 @@
<?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="Application Developer's Guide"
href="https://tomcat.apache.org/">
<title>Application Developer's Guide</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="App Dev Guide Home" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</menu>
<menu name="Contents">
<item name="Contents" href="index.html"/>
<item name="Introduction" href="introduction.html"/>
<item name="Installation" href="installation.html"/>
<item name="Deployment" href="deployment.html"/>
<item name="Source Code" href="source.html"/>
<item name="Processes" href="processes.html"/>
<item name="Example App" href="sample/"/>
</menu>
</body>
</project>

17
webapps/docs/appdev/sample/docs/README.txt Normal file
View File

@@ -0,0 +1,17 @@
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.
This is a dummy README file for the sample
web application.

55
webapps/docs/appdev/sample/index.html Normal file
View File

@@ -0,0 +1,55 @@
<!DOCTYPE html>
<!--
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.
-->
<html>
<head>
<meta charset="UTF-8" />
<meta name="author" content="Ben Souther" />
<title>Sample Application</title>
</head>
<body>
<h2>Sample Application</h2>
<p>
The example app has been packaged as a war file and can be downloaded
<a href="sample.war">here</a> (Note: make sure your browser doesn't
change file extension or append a new one).
</p>
<p>
The easiest way to run this application is simply to move the war file
to your <b>CATALINA_BASE/webapps</b> directory. A default Tomcat install
will automatically expand and deploy the application for you. You can
view it with the following URL (assuming that you're running tomcat on
port 8080 which is the default):
<br />
<a href="http://localhost:8080/sample">http://localhost:8080/sample</a>
</p>
<p>
If you just want to browse the contents, you can unpack the war file
with the <b>jar</b> command.
</p>
<pre>
jar -xvf sample.war
</pre>
<p>
Note: <b>CATALINA_BASE</b> is usually the directory in which you
unpacked the Tomcat distribution. For more information on
<b>CATALINA_HOME</b>, <b>CATALINA_BASE</b> and the difference between
them see <b>RUNNING.txt</b> in the directory you unpacked your Tomcat
distribution.
</p>
</body>
</html>

BIN
webapps/docs/appdev/sample/sample.war Normal file
View File

Binary file not shown.

83
webapps/docs/appdev/sample/src/mypackage/Hello.java Normal file
View File

@@ -0,0 +1,83 @@
/*
* 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.
*/
package mypackage;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
/**
* Simple servlet to validate that the Hello, World example can
* execute servlets. In the web application deployment descriptor,
* this servlet must be mapped to correspond to the link in the
* "index.html" file.
*
* @author Craig R. McClanahan <Craig.McClanahan@eng.sun.com>
*/
public final class Hello extends HttpServlet {
private static final long serialVersionUID = 1L;
/**
* Respond to a GET request for the content produced by
* this servlet.
*
* @param request The servlet request we are processing
* @param response The servlet response we are producing
*
* @exception IOException if an input/output error occurs
* @exception ServletException if a servlet error occurs
*/
@Override
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws IOException, ServletException {
response.setContentType("text/html");
response.setCharacterEncoding("UTF-8");
try (PrintWriter writer = response.getWriter()) {
writer.println("<!DOCTYPE html><html>");
writer.println("<head>");
writer.println("<meta charset=\"UTF-8\" />");
writer.println("<title>Sample Application Servlet Page</title>");
writer.println("</head>");
writer.println("<body>");
writer.println("<div style=\"float: left; padding: 10px;\">");
writer.println("<img src=\"images/tomcat.gif\" alt=\"\" />");
writer.println("</div>");
writer.println("<h1>Sample Application Servlet</h1>");
writer.println("<p>");
writer.println("This is the output of a servlet that is part of");
writer.println("the Hello, World application.");
writer.println("</p>");
writer.println("</body>");
writer.println("</html>");
}
}
}

40
webapps/docs/appdev/sample/web/WEB-INF/web.xml Normal file
View File

@@ -0,0 +1,40 @@
<?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.
-->
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
version="3.1">
<display-name>Hello, World Application</display-name>
<description>
This is a simple web application with a source code organization
based on the recommendations of the Application Developer's Guide.
</description>
<servlet>
<servlet-name>HelloServlet</servlet-name>
<servlet-class>mypackage.Hello</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>HelloServlet</servlet-name>
<url-pattern>/hello</url-pattern>
</servlet-mapping>
</web-app>

37
webapps/docs/appdev/sample/web/hello.jsp Normal file
View File

@@ -0,0 +1,37 @@
<%--
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.
--%>
<%@ page session="false" pageEncoding="UTF-8" contentType="text/html; charset=UTF-8" %>
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8" />
<title>Sample Application JSP Page</title>
</head>
<body>
<div style="float: left; padding: 10px;">
<img src="images/tomcat.gif" alt="" />
</div>
<h1>Sample Application JSP Page</h1>
This is the output of a JSP page that is part of the Hello, World
application.
<%= new String("Hello!") %>
</body>
</html>

BIN
webapps/docs/appdev/sample/web/images/tomcat.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

39
webapps/docs/appdev/sample/web/index.html Normal file
View File

@@ -0,0 +1,39 @@
<!DOCTYPE html><!--
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.
-->
<html>
<head>
<meta charset="UTF-8" />
<title>Sample "Hello, World" Application</title>
</head>
<body>
<div style="float: left; padding: 10px;">
<img src="images/tomcat.gif" alt="" />
</div>
<h1>Sample "Hello, World" Application</h1>
<p>This is the home page for a sample application used to illustrate the
source directory organization of a web application utilizing the principles
outlined in the Application Developer's Guide.
<p>To prove that they work, you can execute either of the following links:</p>
<ul>
<li>To a <a href="hello.jsp">JSP page</a>.</li>
<li>To a <a href="hello">servlet</a>.</li>
</ul>
</body>
</html>

317
webapps/docs/appdev/source.xml Normal file
View File

@@ -0,0 +1,317 @@
<?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="source.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Source Organization</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Directory Structure">
<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>
<p>A key recommendation of this manual is to separate the directory
hierarchy containing your source code (described in this section) from
the directory hierarchy containing your deployable application
(described in the preceding section). Maintaining this separation has
the following advantages:</p>
<ul>
<li><p>The contents of the source directories can be more easily administered,
moved, and backed up if the "executable" version of the application
is not intermixed.
</p></li>
<li><p>Source code control is easier to manage on directories that contain
only source files.
</p></li>
<li><p>The files that make up an installable distribution of your
application are much easier to select when the deployment
hierarchy is separate.</p></li>
</ul>
<p>As we will see, the <code>ant</code> development tool makes the creation
and processing of such directory hierarchies nearly painless.</p>
<p>The actual directory and file hierarchy used to contain the source code
of an application can be pretty much anything you like. However, the
following organization has proven to be quite generally applicable, and is
expected by the example <code>build.xml</code> configuration file that
is discussed below. All of these components exist under a top level
<em>project source directory</em> for your application:</p>
<ul>
<li><strong>docs/</strong> - Documentation for your application, in whatever
format your development team is using.<br/><br/></li>
<li><strong>src/</strong> - Java source files that generate the servlets,
beans, and other Java classes that are unique to your application.
If your source code is organized in packages (<strong>highly</strong>
recommended), the package hierarchy should be reflected as a directory
structure underneath this directory.<br/><br/></li>
<li><strong>web/</strong> - The static content of your web site (HTML pages,
JSP pages, JavaScript files, CSS stylesheet files, and images) that will
be accessible to application clients. This directory will be the
<em>document root</em> of your web application, and any subdirectory
structure found here will be reflected in the request URIs required to
access those files.<br/><br/></li>
<li><strong>web/WEB-INF/</strong> - The special configuration files required
for your application, including the web application deployment descriptor
(<code>web.xml</code>, defined in the
<a href="https://wiki.apache.org/tomcat/Specifications">Servlet Specification</a>),
tag library descriptors for custom tag libraries
you have created, and other resource files you wish to include within
your web application. Even though this directory appears to be a
subdirectory of your <em>document root</em>, the Servlet Specification
prohibits serving the contents of this directory (or any file it contains)
directly to a client request. Therefore, this is a good place to store
configuration information that is sensitive (such as database connection
usernames and passwords), but is required for your application to
operate successfully.</li>
</ul>
<p>During the development process, two additional directories will be
created on a temporary basis:</p>
<ul>
<li><strong>build/</strong> - When you execute a default build
(<code>ant</code>), this directory will contain an exact image
of the files in the web application archive for this application.
Tomcat allows you to deploy an application in an unpacked
directory like this, either by copying it to the
<code>$CATALINA_BASE/webapps</code> directory, or by <em>installing</em>
it via the "Manager" web application. The latter approach is very
useful during development, and will be illustrated below.
<br/><br/></li>
<li><strong>dist/</strong> - When you execute the <code>ant dist</code>
target, this directory will be created. It will create an exact image
of the binary distribution for your web application, including an license
information, documentation, and README files that you have prepared.</li>
</ul>
<p>Note that these two directories should <strong>NOT</strong> be archived in
your source code control system, because they are deleted and recreated (from
scratch) as needed during development. For that reason, you should not edit
any source files in these directories if you want to maintain a permanent
record of the changes, because the changes will be lost the next time that a
build is performed.</p>
<subsection name="External Dependencies">
<p>What do you do if your application requires JAR files (or other
resources) from external projects or packages? A common example is that
you need to include a JDBC driver in your web application, in order to
operate.</p>
<p>Different developers take different approaches to this problem.
Some will encourage checking a copy of the JAR files you depend on into
the source code control archives for every application that requires those
JAR files. However, this can cause significant management issues when you
use the same JAR in many applications - particular when faced with a need
to upgrade to a different version of that JAR file.</p>
<p>Therefore, this manual recommends that you <strong>NOT</strong> store
a copy of the packages you depend on inside the source control archives
of your applications. Instead, the external dependencies should be
integrated as part of the process of <strong>building</strong> your
application. In that way, you can always pick up the appropriate version
of the JAR files from wherever your development system administrator has
installed them, without having to worry about updating your application
every time the version of the dependent JAR file is changed.</p>
<p>In the example Ant <code>build.xml</code> file, we will demonstrate
how to define <em>build properties</em> that let you configure the locations
of the files to be copied, without having to modify <code>build.xml</code>
when these files change. The build properties used by a particular
developer can be customized on a per-application basis, or defaulted to
"standard" build properties stored in the developer's home directory.</p>
<p>In many cases, your development system administrator will have already
installed the required JAR files into the <code>lib</code> directory of Tomcat.
If this has been done, you need
to take no actions at all - the example <code>build.xml</code> file
automatically constructs a compile classpath that includes these files.</p>
</subsection>
</section>
<section name="Source Code Control">
<p>As mentioned earlier, it is highly recommended that you place all of the
source files that comprise your application under the management of a
source code control system like the Concurrent Version System (CVS). If you
elect to do this, every directory and file in the source hierarchy should be
registered and saved -- but none of the generated files. If you register
binary format files (such as images or JAR libraries), be sure to indicate
this to your source code control system.</p>
<p>We recommended (in the previous section) that you should not store the
contents of the <code>build/</code> and <code>dist/</code> directories
created by your development process in the source code control system. An
easy way to tell CVS to ignore these directories is to create a file named
<code>.cvsignore</code> (note the leading period) in your top-level source
directory, with the following contents:</p>
<source>build
dist
build.properties</source>
<p>The reason for mentioning <code>build.properties</code> here will be
explained in the <a href="processes.html">Processes</a> section.</p>
<p>Detailed instructions for your source code control environment are beyond
the scope of this manual. However, the following steps are followed when
using a command-line CVS client:</p>
<ul>
<li>To refresh the state of your source code to that stored in the
the source repository, go to your project source directory, and
execute <code>cvs update -dP</code>.
<br/><br/></li>
<li>When you create a new subdirectory in the source code hierarchy, register
it in CVS with a command like <code>cvs add {subdirname}</code>.
<br/><br/></li>
<li>When you first create a new source code file, navigate to the directory
that contains it, and register the new file with a command like
<code>cvs add {filename}</code>.
<br/><br/></li>
<li>If you no longer need a particular source code file, navigate to the
containing directory and remove the file. Then, deregister it in CVS
with a command like <code>cvs remove {filename}</code>.
<br/><br/></li>
<li>While you are creating, modifying, and deleting source files, changes
are not yet reflected in the server repository. To save your changes in
their current state, go to the project source directory
and execute <code>cvs commit</code>. You will be asked to write a brief
description of the changes you have just completed, which will be stored
with the new version of any updated source file.</li>
</ul>
<p>CVS, like other source code control systems, has many additional features
(such as the ability to tag the files that made up a particular release, and
support for multiple development branches that can later be merged). See the
links and references in the <a href="introduction.html">Introduction</a> for
more information.</p>
</section>
<section name="BUILD.XML Configuration File">
<p>We will be using the <strong>ant</strong> tool to manage the compilation of
our Java source code files, and creation of the deployment hierarchy. Ant
operates under the control of a build file, normally called
<code>build.xml</code>, that defines the processing steps required. This
file is stored in the top-level directory of your source code hierarchy, and
should be checked in to your source code control system.</p>
<p>Like a Makefile, the <code>build.xml</code> file provides several
"targets" that support optional development activities (such as creating
the associated Javadoc documentation, erasing the deployment home directory
so you can build your project from scratch, or creating the web application
archive file so you can distribute your application. A well-constructed
<code>build.xml</code> file will contain internal documentation describing
the targets that are designed for use by the developer, versus those targets
used internally. To ask Ant to display the project documentation, change to
the directory containing the <code>build.xml</code> file and type:</p>
<source>ant -projecthelp</source>
<p>To give you a head start, a <a href="build.xml.txt">basic build.xml file</a>
is provided that you can customize and install in the project source directory
for your application. This file includes comments that describe the various
targets that can be executed. Briefly, the following targets are generally
provided:</p>
<ul>
<li><strong>clean</strong> - This target deletes any existing
<code>build</code> and <code>dist</code> directories, so that they
can be reconstructed from scratch. This allows you to guarantee that
you have not made source code modifications that will result in
problems at runtime due to not recompiling all affected classes.
<br/><br/></li>
<li><strong>compile</strong> - This target is used to compile any source code
that has been changed since the last time compilation took place. The
resulting class files are created in the <code>WEB-INF/classes</code>
subdirectory of your <code>build</code> directory, exactly where the
structure of a web application requires them to be. Because
this command is executed so often during development, it is normally
made the "default" target so that a simple <code>ant</code> command will
execute it.
<br/><br/></li>
<li><strong>all</strong> - This target is a short cut for running the
<code>clean</code> target, followed by the <code>compile</code> target.
Thus, it guarantees that you will recompile the entire application, to
ensure that you have not unknowingly introduced any incompatible changes.
<br/><br/></li>
<li><strong>javadoc</strong> - This target creates Javadoc API documentation
for the Java classes in this web application. The example
<code>build.xml</code> file assumes you want to include the API
documentation with your app distribution, so it generates the docs
in a subdirectory of the <code>dist</code> directory. Because you normally
do not need to generate the Javadocs on every compilation, this target is
usually a dependency of the <code>dist</code> target, but not of the
<code>compile</code> target.
<br/><br/></li>
<li><strong>dist</strong> - This target creates a distribution directory for
your application, including any required documentation, the Javadocs for
your Java classes, and a web application archive (WAR) file that will be
delivered to system administrators who wish to install your application.
Because this target also depends on the <code>deploy</code> target, the
web application archive will have also picked up any external dependencies
that were included at deployment time.</li>
</ul>
<p>For interactive development and testing of your web application using
Tomcat, the following additional targets are defined:</p>
<ul>
<li><strong>install</strong> - Tell the currently running Tomcat to make
the application you are developing immediately available for execution
and testing. This action does not require Tomcat to be restarted, but
it is also not remembered after Tomcat is restarted the next time.
<br/><br/></li>
<li><strong>reload</strong> - Once the application is installed, you can
continue to make changes and recompile using the <code>compile</code>
target. Tomcat will automatically recognize changes made to JSP pages,
but not to servlet or JavaBean classes - this command will tell Tomcat
to restart the currently installed application so that such changes are
recognized.
<br/><br/></li>
<li><strong>remove</strong> - When you have completed your development and
testing activities, you can optionally tell Tomcat to remove this
application from service.
</li>
</ul>
<p>Using the development and testing targets requires some additional
one-time setup that is described on the next page.</p>
</section>
</body>
</document>

166
webapps/docs/appdev/web.xml.txt 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 web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<!-- General description of your web application -->
<display-name>My Web Application</display-name>
<description>
This is version X.X of an application to perform
a wild and wonderful task, based on servlets and
JSP pages. It was written by Dave Developer
(dave@mycompany.com), who should be contacted for
more information.
</description>
<!-- Context initialization parameters that define shared
String constants used within your application, which
can be customized by the system administrator who is
installing your application. The values actually
assigned to these parameters can be retrieved in a
servlet or JSP page by calling:
String value =
getServletContext().getInitParameter("name");
where "name" matches the <param-name> element of
one of these initialization parameters.
You can define any number of context initialization
parameters, including zero.
-->
<context-param>
<param-name>webmaster</param-name>
<param-value>myaddress@mycompany.com</param-value>
<description>
The EMAIL address of the administrator to whom questions
and comments about this application should be addressed.
</description>
</context-param>
<!-- Servlet definitions for the servlets that make up
your web application, including initialization
parameters. With Tomcat, you can also send requests
to servlets not listed here with a request like this:
http://localhost:8080/{context-path}/servlet/{classname}
but this usage is not guaranteed to be portable. It also
makes relative references to images and other resources
required by your servlet more complicated, so defining
all of your servlets (and defining a mapping to them with
a servlet-mapping element) is recommended.
Servlet initialization parameters can be retrieved in a
servlet or JSP page by calling:
String value =
getServletConfig().getInitParameter("name");
where "name" matches the <param-name> element of
one of these initialization parameters.
You can define any number of servlets, including zero.
-->
<servlet>
<servlet-name>controller</servlet-name>
<description>
This servlet plays the "controller" role in the MVC architecture
used in this application. It is generally mapped to the ".do"
filename extension with a servlet-mapping element, and all form
submits in the app will be submitted to a request URI like
"saveCustomer.do", which will therefore be mapped to this servlet.
The initialization parameter names for this servlet are the
"servlet path" that will be received by this servlet (after the
filename extension is removed). The corresponding value is the
name of the action class that will be used to process this request.
</description>
<servlet-class>com.mycompany.mypackage.ControllerServlet</servlet-class>
<init-param>
<param-name>listOrders</param-name>
<param-value>com.mycompany.myactions.ListOrdersAction</param-value>
</init-param>
<init-param>
<param-name>saveCustomer</param-name>
<param-value>com.mycompany.myactions.SaveCustomerAction</param-value>
</init-param>
<!-- Load this servlet at server startup time -->
<load-on-startup>5</load-on-startup>
</servlet>
<servlet>
<servlet-name>graph</servlet-name>
<description>
This servlet produces GIF images that are dynamically generated
graphs, based on the input parameters included on the request.
It is generally mapped to a specific request URI like "/graph".
</description>
</servlet>
<!-- Define mappings that are used by the servlet container to
translate a particular request URI (context-relative) to a
particular servlet. The examples below correspond to the
servlet descriptions above. Thus, a request URI like:
http://localhost:8080/{contextpath}/graph
will be mapped to the "graph" servlet, while a request like:
http://localhost:8080/{contextpath}/saveCustomer.do
will be mapped to the "controller" servlet.
You may define any number of servlet mappings, including zero.
It is also legal to define more than one mapping for the same
servlet, if you wish to.
-->
<servlet-mapping>
<servlet-name>controller</servlet-name>
<url-pattern>*.do</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>graph</servlet-name>
<url-pattern>/graph</url-pattern>
</servlet-mapping>
<!-- Define the default session timeout for your application,
in minutes. From a servlet or JSP page, you can modify
the timeout for a particular session dynamically by using
HttpSession.getMaxInactiveInterval(). -->
<session-config>
<session-timeout>30</session-timeout> <!-- 30 minutes -->
</session-config>
</web-app>

170
webapps/docs/apr.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="apr.html">
&project;
<properties>
<title>Apache Portable Runtime (APR) based Native library for Tomcat</title>
<author>Remy Maucherat</author>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Tomcat can use the <a href="https://apr.apache.org/">Apache Portable Runtime</a> to
provide superior scalability, performance, and better integration with native server
technologies. The Apache Portable Runtime is a highly portable library that is at
the heart of Apache HTTP Server 2.x. APR has many uses, including access to advanced IO
functionality (such as sendfile, epoll and OpenSSL), OS level functionality (random number
generation, system status, etc), and native process handling (shared memory, NT
pipes and Unix sockets).
</p>
<p>
These features allows making Tomcat a general purpose webserver, will enable much better
integration with other native web technologies, and overall make Java much more viable as
a full fledged webserver platform rather than simply a backend focused technology.
</p>
</section>
<section name="Installation">
<p>
APR support requires three main native components to be installed:
</p>
<ul>
<li>APR library</li>
<li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
<li>OpenSSL libraries</li>
</ul>
<subsection name="Windows">
<p>
Windows binaries are provided for tcnative-1, which is a statically compiled .dll which includes
OpenSSL and APR. It can be downloaded from <a href="https://tomcat.apache.org/download-native.cgi">here</a>
as 32bit or AMD x86-64 binaries.
In security conscious production environments, it is recommended to use separate shared dlls
for OpenSSL, APR, and libtcnative-1, and update them as needed according to security bulletins.
Windows OpenSSL binaries are linked from the <a href="https://www.openssl.org">Official OpenSSL
website</a> (see related/binaries).
</p>
</subsection>
<subsection name="Linux">
<p>
Most Linux distributions will ship packages for APR and OpenSSL. The JNI wrapper (libtcnative) will
then have to be compiled. It depends on APR, OpenSSL, and the Java headers.
</p>
<p>
Requirements:
</p>
<ul>
<li>APR 1.2+ development headers (libapr1-dev package)</li>
<li>OpenSSL 1.0.2+ development headers (libssl-dev package)</li>
<li>JNI headers from Java compatible JDK 1.4+</li>
<li>GNU development environment (gcc, make)</li>
</ul>
<p>
The wrapper library sources are located in the Tomcat binary bundle, in the
<code>bin/tomcat-native.tar.gz</code> archive.
Once the build environment is installed and the source archive is extracted, the wrapper library
can be compiled using (from the folder containing the configure script):
</p>
<source>./configure &amp;&amp; make &amp;&amp; make install</source>
</subsection>
</section>
<section name="APR Components">
<p>
Once the libraries are properly installed and available to Java (if loading fails, the library path
will be displayed), the Tomcat connectors will automatically use APR. Configuration of the connectors
is similar to the regular connectors, but have a few extra attributes which are used to configure
APR components. Note that the defaults should be well tuned for most use cases, and additional
tweaking shouldn't be required.
</p>
<p>
When APR is enabled, the following features are also enabled in Tomcat:
</p>
<ul>
<li>Secure session ID generation by default on all platforms (platforms other than Linux required
random number generation using a configured entropy)</li>
<li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by
the status servlet</li>
</ul>
</section>
<section name="APR Lifecycle Listener Configuration">
<p>See <a href="config/listeners.html#APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">the
listener configuration</a>.</p>
</section>
<section name="APR Connectors Configuration">
<subsection name="HTTP/HTTPS">
<p>For HTTP configuration, see the <a href="config/http.html">HTTP</a>
connector configuration documentation.</p>
<p>For HTTPS configuration, see the
<a href="config/http.html#SSL_Support">HTTPS</a> connector configuration
documentation.</p>
<p>An example SSL Connector declaration is:</p>
<source><![CDATA[<Connector port="443" maxHttpHeaderSize="8192"
maxThreads="150"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
SSLEnabled="true"
SSLCertificateFile="${catalina.base}/conf/localhost.crt"
SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />]]></source>
</subsection>
<subsection name="AJP">
<p>For AJP configuration, see the <a href="config/ajp.html">AJP</a>
connector configuration documentation.</p>
</subsection>
</section>
</body>
</document>

69
webapps/docs/architecture/index.xml Normal file
View File

@@ -0,0 +1,69 @@
<?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="yoavs@apache.org">Yoav Shapira</author>
<title>Table of Contents</title>
</properties>
<body>
<section name="Preface">
<p>This section of the Tomcat documentation attempts to explain
the architecture and design of the Tomcat server. It includes significant
contributions from several tomcat developers:
</p>
<ul>
<li>Yoav Shapira
(<a href="mailto:yoavs@apache.org">yoavs@apache.org</a>)</li>
<li>Jeanfrancois Arcand
(<a href="mailto:jfarcand@apache.org">jfarcand@apache.org</a>)</li>
<li>Filip Hanik
(<a href="mailto:fhanik@apache.org">fhanik@apache.org</a>)</li>
</ul>
</section>
<section name="Table of Contents">
<p>The information presented is divided into the following sections:</p>
<ul>
<li><a href="overview.html"><strong>Overview</strong></a> -
An overview of the Tomcat server architecture with key terms
and concepts.</li>
<li><a href="startup.html"><strong>Server Startup</strong></a> -
A detailed description, with sequence diagrams, of how the Tomcat
server starts up.</li>
<li><a href="requestProcess.html"><strong>Request Process Flow</strong></a> -
A detailed description of how Tomcat handles a request.</li>
</ul>
</section>
</body>
</document>

138
webapps/docs/architecture/overview.xml Normal file
View File

@@ -0,0 +1,138 @@
<?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="overview.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Architecture Overview</title>
</properties>
<body>
<section name="Overview">
<p>
This page provides an overview of the Tomcat server architecture.
</p>
</section>
<section name="Terms">
<subsection name="Server">
<p>
In the Tomcat world, a
<a href="../config/server.html">Server</a> represents the whole container.
Tomcat provides a default implementation of the
<a href="../api/org/apache/catalina/Server.html">Server interface</a>
which is rarely customized by users.
</p>
</subsection>
<subsection name="Service">
<p>
A <a href="../config/service.html">Service</a> is an intermediate component
which lives inside a Server and ties one or more Connectors to exactly one
Engine. The Service element is rarely customized by users, as the default
implementation is simple and sufficient:
<a href="../api/org/apache/catalina/Service.html">Service interface</a>.
</p>
</subsection>
<subsection name="Engine">
<p>
An
<a href="../config/engine.html">Engine</a> represents request processing
pipeline for a specific Service. As a Service may have multiple Connectors,
the Engine receives and processes all requests from these connectors, handing
the response back to the appropriate connector for transmission to the client.
The <a href="../api/org/apache/catalina/Engine.html">Engine interface</a>
may be implemented to supply custom Engines, though this is uncommon.
</p>
<p>
Note that the Engine may be used for Tomcat server clustering via the
jvmRoute parameter. Read the Clustering documentation for more information.
</p>
</subsection>
<subsection name="Host">
<p>
A <a href="../config/host.html">Host</a> is an association of a network name,
e.g. www.yourcompany.com, to the Tomcat server. An Engine may contain
multiple hosts, and the Host element also supports network aliases such as
yourcompany.com and abc.yourcompany.com. Users rarely create custom
<a href="../api/org/apache/catalina/Host.html">Hosts</a>
because the
<a href="../api/org/apache/catalina/core/StandardHost.html">StandardHost
implementation</a> provides significant additional functionality.
</p>
</subsection>
<subsection name="Connector">
<p>
A Connector handles communications with the client. There are multiple
connectors available with Tomcat. These include the
<a href="../config/http.html">HTTP connector</a> which is used for
most HTTP traffic, especially when running Tomcat as a standalone server,
and the <a href="../config/ajp.html">AJP connector</a> which implements
the AJP protocol used when connecting Tomcat to a web server such as
Apache HTTPD server. Creating a customized connector is a significant
effort.
</p>
</subsection>
<subsection name="Context">
<p>
A
<a href="../config/context.html">Context</a>
represents a web application. A Host may contain multiple
contexts, each with a unique path. The
<a href="../api/org/apache/catalina/Context.html">Context
interface</a> may be implemented to create custom Contexts, but
this is rarely the case because the
<a href="../api/org/apache/catalina/core/StandardContext.html">
StandardContext</a> provides significant additional functionality.
</p>
</subsection>
</section>
<section name="Comments">
<p>
Tomcat is designed to be a fast and efficient implementation of the
Servlet Specification. Tomcat came about as the reference implementation
of this specification, and has remained rigorous in adhering to the
specification. At the same time, significant attention has been paid
to Tomcat's performance and it is now on par with other servlet containers,
including commercial ones.
</p>
<p>
In recent releases of Tomcat, mostly starting with Tomcat 5,
we have begun efforts to make more aspects of Tomcat manageable via
JMX. In addition, the Manager and Admin webapps have been greatly
enhanced and improved. Manageability is a primary area of concern
for us as the product matures and the specification becomes more
stable.
</p>
</section>
</body>
</document>

45
webapps/docs/architecture/project.xml Normal file
View File

@@ -0,0 +1,45 @@
<?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 Architecture"
href="https://tomcat.apache.org/">
<title>Apache Tomcat 8 Architecture</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="Architecture Home" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</menu>
<menu name="Contents">
<item name="Contents" href="index.html" />
<item name="Overview" href="overview.html" />
<item name="Server Startup" href="startup.html" />
<item name="Request Process" href="requestProcess.html" />
</menu>
</body>
</project>

74
webapps/docs/architecture/requestProcess.xml Normal file
View File

@@ -0,0 +1,74 @@
<?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="requestProcess.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Request Process Flow</title>
</properties>
<body>
<section name="Request Process Flow">
<p>
This page describes the process used by Tomcat to handle
an incoming request. This process is largely defined by
the Servlet Specification, which outlines the order
of events that must take place.
</p>
<subsection name="description">
<p>
TODO
</p>
</subsection>
<subsection name="diagrams">
<p>
A UML sequence diagram of the request process is available
<a href="requestProcess/request-process.png">here.</a>
</p>
<p>
A UML sequence diagram of the authentication process is available
<a href="requestProcess/authentication-process.png">here.</a>
</p>
</subsection>
<subsection name="comments">
<p>
The Servlet Specification provides many opportunities for
listening in (using Listeners) or modifying (using Filters)
the request handling process even before the request arrives
at the servlet that will handle it.
</p>
</subsection>
</section>
</body>
</document>

BIN
webapps/docs/architecture/requestProcess/authentication-process.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
webapps/docs/architecture/requestProcess/request-process.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 107 KiB

73
webapps/docs/architecture/startup.xml Normal file
View File

@@ -0,0 +1,73 @@
<?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="startup.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Startup</title>
</properties>
<body>
<section name="Server Startup">
<p>
This page describes how the Tomcat server starts up. There are several
different ways to start tomcat, including:
</p>
<ul>
<li>From the command line.</li>
<li>From a Java program as an embedded server.</li>
<li>Automatically as a Windows service.</li>
</ul>
<subsection name="description">
<p>
A text description of the startup procedure is available
<a href="startup/serverStartup.txt">here.</a>
</p>
</subsection>
<subsection name="diagram">
<p>
A UML sequence diagram of the startup procedure is available
<a href="startup/serverStartup.pdf">here.</a>
</p>
</subsection>
<subsection name="comments">
<p>
The startup process can be customized in many ways, both
by modifying Tomcat code and by implementing your own
LifecycleListeners which are then registered in the server.xml
configuration file.
</p>
</subsection>
</section>
</body>
</document>

BIN
webapps/docs/architecture/startup/serverStartup.pdf Normal file
View File

Binary file not shown.

139
webapps/docs/architecture/startup/serverStartup.txt Normal file
View File

@@ -0,0 +1,139 @@
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.
Tomcat Startup Sequence
Sequence 1. Start from Command Line
Class: org.apache.catalina.startup.Bootstrap
What it does:
a) Set up classloaders
commonLoader (common)-> System Loader
sharedLoader (shared)-> commonLoader -> System Loader
catalinaLoader(server) -> commonLoader -> System Loader
(by default the commonLoader is used for the
sharedLoader and the serverLoader)
b) Load startup class (reflection)
org.apache.catalina.startup.Catalina
setParentClassloader -> sharedLoader
Thread.contextClassloader -> catalinaLoader
c) Bootstrap.daemon.init() complete
Sequence 2. Process command line argument (start, stop)
Class: org.apache.catalina.startup.Bootstrap (assume command->start)
What it does:
a) Catalina.setAwait(true);
b) Catalina.load()
b1) initDirs() -> set properties like
catalina.home
catalina.base == catalina.home (most cases)
b2) initNaming
setProperty(javax.naming.Context.INITIAL_CONTEXT_FACTORY,
org.apache.naming.java.javaURLContextFactory ->default)
b3) createStartDigester()
Configures a digester for the main server.xml elements like
org.apache.catalina.core.StandardServer (can change of course :)
org.apache.catalina.deploy.NamingResources
Stores naming resources in the J2EE JNDI tree
org.apache.catalina.LifecycleListener
implements events for start/stop of major components
org.apache.catalina.core.StandardService
The single entry for a set of connectors,
so that a container can listen to multiple connectors
ie, single entry
org.apache.catalina.Connector
Connectors to listen for incoming requests only
It also adds the following rulesets to the digester
NamingRuleSet
EngineRuleSet
HostRuleSet
ContextRuleSet
b4) Load the server.xml and parse it using the digester
Parsing the server.xml using the digester is an automatic
XML-object mapping tool, that will create the objects defined in server.xml
Startup of the actual container has not started yet.
b5) Assigns System.out and System.err to the SystemLogHandler class
b6) Calls initialize on all components, this makes each object register itself with the
JMX agent.
During the process call the Connectors also initialize the adapters.
The adapters are the components that do the request pre-processing.
Typical adapters are HTTP1.1 (default if no protocol is specified,
org.apache.coyote.http11.Http11NioProtocol)
AJP1.3 for mod_jk etc.
c) Catalina.start()
c1) Starts the NamingContext and binds all JNDI references into it
c2) Starts the services under <Server> which are:
StandardService -> starts Engine (ContainerBase -> Realm,Cluster etc)
c3) StandardHost (started by the service)
Configures an ErrorReportValve to do proper HTML output for different HTTP
errors codes
Starts the Valves in the pipeline (at least the ErrorReportValve)
Configures the StandardHostValve,
this valves ties the Webapp Class loader to the thread context
it also finds the session for the request
and invokes the context pipeline
Starts the HostConfig component
This component deploys all the webapps
(webapps & conf/Catalina/localhost/*.xml)
HostConfig will create a Digester for your context, this digester
will then invoke ContextConfig.start()
The ContextConfig.start() will process the default web.xml (conf/web.xml)
and then process the applications web.xml (WEB-INF/web.xml)
c4) During the lifetime of the container (StandardEngine) there is a background thread that
keeps checking if the context has changed. If a context changes (timestamp of war file,
context xml file, web.xml) then a reload is issued (stop/remove/deploy/start)
d) Tomcat receives a request on an HTTP port
d1) The request is received by a separate thread which is waiting in the ThreadPoolExecutor
class. It is waiting for a request in a regular ServerSocket.accept() method.
When a request is received, this thread wakes up.
d2) The ThreadPoolExecutor assigns the a TaskThread to handle the request.
It also supplies a JMX object name to the catalina container (not used I believe)
d3) The processor to handle the request in this case is Coyote Http11Processor,
and the process method is invoked.
This same processor is also continuing to check the input stream of the socket
until the keep alive point is reached or the connection is disconnected.
d4) The HTTP request is parsed using an internal buffer class (Http11InputBuffer)
The buffer class parses the request line, the headers, etc and store the result in a
Coyote request (not an HTTP request) This request contains all the HTTP info, such
as servername, port, scheme, etc.
d5) The processor contains a reference to an Adapter, in this case it is the
CoyoteAdapter. Once the request has been parsed, the Http11Processor
invokes service() on the adapter. In the service method, the Request contains a
CoyoteRequest and CoyoteResponse (null for the first time)
The CoyoteRequest(Response) implements HttpRequest(Response) and HttpServletRequest(Response)
The adapter parses and associates everything with the request, cookies, the context through a
Mapper, etc
d6) When the parsing is finished, the CoyoteAdapter invokes its container (StandardEngine)
and invokes the invoke(request,response) method.
This initiates the HTTP request into the Catalina container starting at the engine level
d7) The StandardEngine.invoke() simply invokes the container pipeline.invoke()
d8) By default the engine only has one valve the StandardEngineValve, this valve simply
invokes the invoke() method on the Host pipeline (StandardHost.getPipeLine())
d9) the StandardHost has two valves by default, the StandardHostValve and the ErrorReportValve
d10) The standard host valve associates the correct class loader with the current thread
It also retrieves the Manager and the session associated with the request (if there is one)
If there is a session access() is called to keep the session alive
d11) After that the StandardHostValve invokes the pipeline on the context associated
with the request.
d12) The first valve that gets invoked by the Context pipeline is the FormAuthenticator
valve. Then the StandardContextValve gets invoke.
The StandardContextValve invokes any context listeners associated with the context.
Next it invokes the pipeline on the Wrapper component (StandardWrapperValve)
d13) During the invocation of the StandardWrapperValve, the JSP wrapper (Jasper) gets invoked
This results in the actual compilation of the JSP.
And then invokes the actual servlet.
e) Invocation of the servlet class

55
webapps/docs/balancer-howto.xml Normal file
View File

@@ -0,0 +1,55 @@
<?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="balancer-howto.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<author>Remy Maucherat</author>
<author>Andy Oliver</author>
<title>Load Balancer How-To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Using the JK 1.2.x native connector">
Please refer to the JK 1.2.x documentation.
</section>
<section name="Using Apache HTTP Server 2.x with mod_proxy">
Please refer to the mod_proxy documentation for Apache HTTP Server 2.2. This supports either
HTTP or AJP load balancing. This new version of mod_proxy is also usable with
Apache HTTP Server 2.0, but mod_proxy will have to be compiled separately using the code
from Apache HTTP Server 2.2.
</section>
</body>
</document>

280
webapps/docs/building.xml Normal file
View File

@@ -0,0 +1,280 @@
<?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>
&project;
<properties>
<title>Building Tomcat</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Building Apache Tomcat from source is very easy, and is the first step to
contributing to Tomcat. The complete and comprehensive instructions are
provided in the file <a href="BUILDING.txt">BUILDING.txt</a>.
The following is a quick step by step guide.
</p>
</section>
<section name="Download a Java Development Kit (JDK) version 7">
<p>
Building Apache Tomcat requires a JDK (version 7) to be installed. You can download one from<br />
<a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">http://www.oracle.com/technetwork/java/javase/downloads/index.html</a><br/>
<a href="http://openjdk.java.net/install/index.html">http://openjdk.java.net/install/index.html</a><br/>
or another JDK vendor.
</p>
<p>
<b>IMPORTANT</b>: Set an environment variable JAVA_HOME to the pathname of the
directory into which you installed the JDK release.
</p>
</section>
<section name="Install Apache Ant 1.9.8 or later">
<p>
Download a binary distribution of Ant 1.9.8 or later from
<a href="https://ant.apache.org/bindownload.cgi">here</a>.
</p>
<p>
Unpack the binary distribution into a convenient location so that the
Ant release resides in its own directory (conventionally named
<code>apache-ant-1.9.x</code>). For the remainder of this guide,
the symbolic name <code>${ant.home}</code> is used to refer to the full pathname of
the Ant installation directory.
</p>
<p>
<b>IMPORTANT</b>: Create an ANT_HOME environment variable to point the directory <code>${ant.home}</code>,
and modify the PATH environment variable to include directory
<code>${ant.home}/bin</code> in its list. This makes the <code>ant</code> command line script
available, which will be used to actually perform the build.
</p>
</section>
<section name="Checkout or obtain the Tomcat source code">
<p>
Tomcat SVN repository URL:
<a href="https://svn.apache.org/repos/asf/tomcat/tc8.5.x/trunk/">https://svn.apache.org/repos/asf/tomcat/tc8.5.x/trunk/</a>
</p>
<p>
Tomcat source packages:
<download>https://tomcat.apache.org/download-<version-major/>0.cgi</download>.
</p>
<p>
Checkout the source using SVN, selecting a tag for released version or
trunk for the current development code, or download and unpack a
source package. For the remainder of this guide, the symbolic name
<code>${tomcat.source}</code> is used to refer to the
location where the source has been placed.
</p>
</section>
<section name="Configure download area">
<p>
Building Tomcat involves downloading a number of libraries that it depends on.
It is strongly recommended to configure download area for those libraries.
</p>
<p>
By default the build is configured to download the dependencies into the
<code>${user.home}/tomcat-build-libs</code> directory. You can change this
(see below) but it must be an absolute path.
</p>
<p>
The build is controlled by creating a
<code>${tomcat.source}/build.properties</code> file. It can be used to
redefine any property that is present in <code>build.properties.default</code>
and <code>build.xml</code> files. The <code>build.properties</code> file
does not exist by default. You have to create it.
</p>
<p>
The download area is defined by property <code>base.path</code>. For example:
</p>
<source><![CDATA[# ----- Default Base Path for Dependent Packages -----
# Replace this path with the directory path where
# dependencies binaries should be downloaded.
base.path=/home/me/some-place-to-download-to]]></source>
<p>
Different versions of Tomcat are allowed to share the same download area.
</p>
<p>
Another example:
</p>
<source>base.path=${user.dir}/../libraries-tomcat<version-major-minor/></source>
<p>
Users who access the Internet through a proxy must use the properties
file to indicate to Ant the proxy configuration:
</p>
<source><![CDATA[# ----- Proxy setup -----
proxy.host=proxy.domain
proxy.port=8080
proxy.use=on]]></source>
</section>
<section name="Building Tomcat">
<p>
Use the following commands to build Tomcat:
</p>
<p>
<code>cd ${tomcat.source}</code><br/>
<code>ant</code>
</p>
<p>
Once the build has completed successfully, a usable Tomcat installation will have been
produced in the <code>${tomcat.source}/output/build</code> directory, and can be started
and stopped with the usual scripts.
</p>
</section>
<section name="Building with Eclipse">
<p>
<b>IMPORTANT:</b> This is not a supported means of building Tomcat; this information is
provided without warranty :-).
The only supported means of building Tomcat is with the Ant build described above.
However, some developers like to work on Java code with a Java IDE,
and the following steps have been used by some developers.
</p>
<p>
<b>NOTE:</b> This will not let you build everything under Eclipse;
the build process requires use of Ant for the many stages that aren't
simple Java compilations.
However, it will allow you to view and edit the Java code,
get warnings, reformat code, perform refactorings, run Tomcat
under the IDE, and so on.
</p>
<p>
<b>WARNING:</b> Do not forget to create and configure
<code>${tomcat.source}/build.properties</code> file as described above
before running any Ant targets.
</p>
<p>
Sample Eclipse project files and launch targets are provided in the
<code>res/ide-support/eclipse</code> directory of the source tree.
The instructions below will automatically copy these into the required locations.
</p>
<p>
An Ant target is provided as a convenience to download all binary dependencies, and to create
the Eclipse project and classpath files in the root of the source tree.
</p>
<p>
<code>cd ${tomcat.source}</code><br/>
<code>ant ide-eclipse</code>
</p>
<p>
Start Eclipse and create a new Workspace.
</p>
<p>
Open the <em>Preferences</em> dialog and then select <em>Java-&gt;Build Path-&gt;Classpath
Variables</em> to add two new <em>Classpath Variables</em>:
</p>
<table class="defaultTable">
<tr><td>TOMCAT_LIBS_BASE</td><td>The same location as the <code>base.path</code>
setting in <code>build.properties</code>, where the binary dependencies have been downloaded</td></tr>
<tr><td>ANT_HOME</td><td>the base path of Ant 1.9.8 or later</td></tr>
</table>
<p>
Use <em>File-&gt;Import</em> and choose <em>Existing Projects into Workspace</em>.
From there choose the root directory of the Tomcat source tree (<code>${tomcat.source}</code>)
and import the Tomcat project located there.
</p>
<p>
<code>start-tomcat</code> and <code>stop-tomcat</code> launch configurations are provided in
<code>res/ide-support/eclipse</code> and will be available in the <em>Run-&gt;Run Configurations</em>
dialog. Use these to start and stop Tomcat from Eclipse.
If you want to configure these yourself (or are using a different IDE)
then use <code>org.apache.catalina.startup.Bootstrap</code> as the main class,
<code>start</code>/<code>stop</code> etc. as program arguments, and specify <code>-Dcatalina.home=...</code>
(with the name of your build directory) as VM arguments.
</p>
<p>
Tweaking a few formatting preferences will make it much easier to keep consistent with Tomcat
coding conventions (and have your contributions accepted):
</p>
<table class="defaultTable">
<tr><td>Java -&gt; Code Style -> Formatter -&gt; Edit...</td>
<td>Tab policy: Spaces only<br/>Tab and Indentation size: 4</td></tr>
<tr><td>General -&gt; Editors -> Text Editors</td>
<td>Displayed tab width: 2<br/>Insert spaces for tabs<br/>Show whitespace characters (optional)</td></tr>
<tr><td>XML -&gt; XML Files -> Editor</td><td>Indent using spaces<br/>Indentation size: 2</td></tr>
<tr><td>Ant -&gt; Editor -> Formatter</td><td>Tab size: 2<br/>Use tab character instead of spaces: unchecked</td></tr>
</table>
<p>
The recommended configuration of Compiler Warnings is documented in
<code>res/ide-support/eclipse/java-compiler-errors-warnings.txt</code> file.
</p>
</section>
<section name="Building with other IDEs">
<p>
The same general approach should work for most IDEs; it has been reported
to work in IntelliJ IDEA, for example.
</p>
</section>
</body>
</document>

168
webapps/docs/cgi-howto.xml Normal file
View File

@@ -0,0 +1,168 @@
<?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="cgi-howto.html">
&project;
<properties>
<title>CGI How To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The CGI (Common Gateway Interface) defines a way for a web server to
interact with external content-generating programs, which are often
referred to as CGI programs or CGI scripts.
</p>
<p>Within Tomcat, CGI support can be added when you are using Tomcat as your
HTTP server and require CGI support. Typically this is done
during development when you don't want to run a web server like
Apache httpd.
Tomcat's CGI support is largely compatible with Apache httpd's,
but there are some limitations (e.g., only one cgi-bin directory).
</p>
<p>CGI support is implemented using the servlet class
<code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally,
this servlet is mapped to the URL pattern "/cgi-bin/*".</p>
<p>By default CGI support is disabled in Tomcat.</p>
</section>
<section name="Installation">
<p><strong>CAUTION</strong> - CGI scripts are used to execute programs
external to the Tomcat JVM. If you are using the Java SecurityManager this
will bypass your security policy configuration in <code>catalina.policy.</code></p>
<p>To enable CGI support:</p>
<ol>
<li><p>There are commented-out sample servlet and servlet-mapping elements for
CGI servlet in the default <code>$CATALINA_BASE/conf/web.xml</code> file.
To enable CGI support in your web application, copy that servlet and
servlet-mapping declarations into <code>WEB-INF/web.xml</code> file of your
web application.</p>
<p>Uncommenting the servlet and servlet-mapping in
<code>$CATALINA_BASE/conf/web.xml</code> file enables CGI for all installed
web applications at once.</p>
</li>
<li><p>Set <code>privileged="true"</code> on the Context element for your
web application.</p>
<p>Only Contexts which are marked as privileged are allowed to use the
CGI servlet. Note that modifying the global <code>$CATALINA_BASE/conf/context.xml</code>
file affects all web applications. See
<a href="config/context.html">Context documentation</a> for details.</p>
</li>
</ol>
</section>
<section name="Configuration">
<p>There are several servlet init parameters which can be used to
configure the behaviour of the CGI servlet.</p>
<ul>
<li><strong>cgiMethods</strong> - Comma separated list of HTTP methods. Requests
using one of these methods will be passed to the CGI script for the script to
generate the response. The default value is <code>GET,POST</code>. Use
<code>*</code> for the script to handle all requests regardless of method.
Unless over-ridden by the configuration of this parameter, requests using HEAD,
OPTIONS or TRACE will have handled by the superclass.</li>
<li><strong>cgiPathPrefix</strong> - The CGI search path will start at
the web application root directory + File.separator + this prefix.
By default there is no value, which results in the web application root
directory being used as the search path. The recommended value is
<code>WEB-INF/cgi</code></li>
<li><strong>cmdLineArgumentsDecoded</strong> - If command line argumemnts
are enabled (via <strong>enableCmdLineArguments</strong>) and Tomcat is running
on Windows then each individual decoded command line argument must match this
pattern else the request will be rejected. This is to protect against known
issues passing command line arguments from Java to Windows. These issues can
lead to remote code execution. For more information on these issues see
<a href="https://codewhitesec.blogspot.com/2016/02/java-and-command-line-injections-in-windows.html">Markus
Wulftange&apos;s blog</a> and this archived
<a href="https://web.archive.org/web/20161228144344/https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/">blog
by Daniel Colascione</a>.</li>
<li><strong>cmdLineArgumentsEncoded</strong> - If command line argumemnts
are enabled (via <strong>enableCmdLineArguments</strong>) individual encoded
command line argument must match this pattern else the request will be rejected.
The default matches the allowed values defined by RFC3875 and is
<code>[a-zA-Z0-9\Q%;/?:@&amp;,$-_.!~*'()\E]+</code></li>
<li><strong>enableCmdLineArguments</strong> - Are command line arguments
generated from the query string as per section 4.4 of 3875 RFC? The default is
<code>false</code>.</li>
<li><strong>environment-variable-</strong> - An environment to be set for the
execution environment of the CGI script. The name of variable is taken from the
parameter name. To configure an environment variable named FOO, configure a
parameter named environment-variable-FOO. The parameter value is used as the
environment variable value. The default is no environment variables.</li>
<li><strong>executable</strong> - The name of the executable to be used to
run the script. You may explicitly set this parameter to be an empty string
if your script is itself executable (e.g. an exe file). Default is
<code>perl</code>.</li>
<li><strong>executable-arg-1</strong>, <strong>executable-arg-2</strong>,
and so on - additional arguments for the executable. These precede the
CGI script name. By default there are no additional arguments.</li>
<li><strong>envHttpHeaders</strong> - A regular expression used to select the
HTTP headers passed to the CGI process as environment variables. Note that
headers are converted to upper case before matching and that the entire header
name must match the pattern. Default is
<code>ACCEPT[-0-9A-Z]*|CACHE-CONTROL|COOKIE|HOST|IF-[-0-9A-Z]*|REFERER|USER-AGENT</code>
</li>
<li><strong>parameterEncoding</strong> - Name of the parameter encoding
to be used with the CGI servlet. Default is
<code>System.getProperty("file.encoding","UTF-8")</code>. That is the system
default encoding, or UTF-8 if that system property is not available.</li>
<li><strong>passShellEnvironment</strong> - Should the shell environment
variables from Tomcat process (if any) be passed to the CGI script? Default is
<code>false</code>.</li>
<li><strong>stderrTimeout</strong> - The time (in milliseconds) to wait for
the reading of stderr to complete before terminating the CGI process. Default
is <code>2000</code>.</li>
</ul>
<p>The CGI script executed depends on the configuration of the CGI Servlet and
how the request is mapped to the CGI Servlet. The CGI search path starts at the
web application root directory + File.separator + cgiPathPrefix. The
<strong>pathInfo</strong> is then searched unless it is <code>null</code> - in
which case the <strong>servletPath</strong> is searched.</p>
<p>The search starts with the first path segment and expands one path segment
at a time until no path segments are left (resulting in a 404) or a script is
found. Any remaining path segments are passed to the script in the
<strong>PATH_INFO</strong> environment variable.</p>
</section>
</body>
</document>

7757
webapps/docs/changelog.xml Normal file
View File

File diff suppressed because it is too large Load Diff

292
webapps/docs/class-loader-howto.xml Normal file
View File

@@ -0,0 +1,292 @@
<?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="class-loader-howto.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Class Loader How-To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<p>Like many server applications, Tomcat installs a variety of class loaders
(that is, classes that implement <code>java.lang.ClassLoader</code>) to allow
different portions of the container, and the web applications running on the
container, to have access to different repositories of available classes and
resources. This mechanism is used to provide the functionality defined in the
Servlet Specification, version 2.4&#160;&#8212; in particular, Sections 9.4
and 9.6.</p>
<p>In a Java environment, class loaders are
arranged in a parent-child tree. Normally, when a class loader is asked to
load a particular class or resource, it delegates the request to a parent
class loader first, and then looks in its own repositories only if the parent
class loader(s) cannot find the requested class or resource. Note, that the
model for web application class loaders <em>differs</em> slightly from this,
as discussed below, but the main principles are the same.</p>
<p>When Tomcat is started, it creates a set of class loaders that are
organized into the following parent-child relationships, where the parent
class loader is above the child class loader:</p>
<source> Bootstrap
|
System
|
Common
/ \
Webapp1 Webapp2 ...</source>
<p>The characteristics of each of these class loaders, including the source
of classes and resources that they make visible, are discussed in detail in
the following section.</p>
</section>
<section name="Class Loader Definitions">
<p>As indicated in the diagram above, Tomcat creates the following class
loaders as it is initialized:</p>
<ul>
<li><p><strong>Bootstrap</strong> &#8212; This class loader contains the basic
runtime classes provided by the Java Virtual Machine, plus any classes from
JAR files present in the System Extensions directory
(<code>$JAVA_HOME/jre/lib/ext</code>). <em>Note</em>: some JVMs may
implement this as more than one class loader, or it may not be visible
(as a class loader) at all.</p></li>
<li><p><strong>System</strong> &#8212; This class loader is normally initialized
from the contents of the <code>CLASSPATH</code> environment variable. All
such classes are visible to both Tomcat internal classes, and to web
applications. However, the standard Tomcat startup scripts
(<code>$CATALINA_HOME/bin/catalina.sh</code> or
<code>%CATALINA_HOME%\bin\catalina.bat</code>) totally ignore the contents
of the <code>CLASSPATH</code> environment variable itself, and instead
build the System class loader from the following repositories:
</p>
<ul>
<li><p><em>$CATALINA_HOME/bin/bootstrap.jar</em> &#8212; Contains the
main() method that is used to initialize the Tomcat server, and the
class loader implementation classes it depends on.</p></li>
<li><p><em>$CATALINA_BASE/bin/tomcat-juli.jar</em> or
<em>$CATALINA_HOME/bin/tomcat-juli.jar</em> &#8212; Logging
implementation classes. These include enhancement classes to
<code>java.util.logging</code> API, known as Tomcat JULI,
and a package-renamed copy of Apache Commons Logging library
used internally by Tomcat.
See <a href="logging.html">logging documentation</a> for more
details.</p>
<p>If <code>tomcat-juli.jar</code> is present in
<em>$CATALINA_BASE/bin</em>, it is used instead of the one in
<em>$CATALINA_HOME/bin</em>. It is useful in certain logging
configurations</p></li>
<li><p><em>$CATALINA_HOME/bin/commons-daemon.jar</em> &#8212; The classes
from <a href="https://commons.apache.org/daemon/">Apache Commons
Daemon</a> project.
This JAR file is not present in the <code>CLASSPATH</code> built by
<code>catalina.bat</code>|<code>.sh</code> scripts, but is referenced
from the manifest file of <em>bootstrap.jar</em>.</p></li>
</ul>
</li>
<li><p><strong>Common</strong> &#8212; This class loader contains additional
classes that are made visible to both Tomcat internal classes and to all
web applications.</p>
<p>Normally, application classes should <strong>NOT</strong>
be placed here. The locations searched by this class loader are defined by
the <code>common.loader</code> property in
$CATALINA_BASE/conf/catalina.properties. The default setting will search the
following locations in the order they are listed:</p>
<ul>
<li>unpacked classes and resources in <code>$CATALINA_BASE/lib</code></li>
<li>JAR files in <code>$CATALINA_BASE/lib</code></li>
<li>unpacked classes and resources in <code>$CATALINA_HOME/lib</code></li>
<li>JAR files in <code>$CATALINA_HOME/lib</code></li>
</ul>
<p>By default, this includes the following:</p>
<ul>
<li><em>annotations-api.jar</em> &#8212; JavaEE annotations classes.</li>
<li><em>catalina.jar</em> &#8212; Implementation of the Catalina servlet
container portion of Tomcat.</li>
<li><em>catalina-ant.jar</em> &#8212; Tomcat Catalina Ant tasks.</li>
<li><em>catalina-ha.jar</em> &#8212; High availability package.</li>
<li><em>catalina-storeconfig.jar</em> &#8212; Generation of XML
configuration files from current state</li>
<li><em>catalina-tribes.jar</em> &#8212; Group communication package.</li>
<li><em>ecj-*.jar</em> &#8212; Eclipse JDT Java compiler.</li>
<li><em>el-api.jar</em> &#8212; EL 3.0 API.</li>
<li><em>jasper.jar</em> &#8212; Tomcat Jasper JSP Compiler and Runtime.</li>
<li><em>jasper-el.jar</em> &#8212; Tomcat Jasper EL implementation.</li>
<li><em>jsp-api.jar</em> &#8212; JSP 2.3 API.</li>
<li><em>servlet-api.jar</em> &#8212; Servlet 3.1 API.</li>
<li><em>tomcat-api.jar</em> &#8212; Several interfaces defined by Tomcat.</li>
<li><em>tomcat-coyote.jar</em> &#8212; Tomcat connectors and utility classes.</li>
<li><em>tomcat-dbcp.jar</em> &#8212; Database connection pool
implementation based on package-renamed copy of Apache Commons Pool 2
and Apache Commons DBCP 2.</li>
<li><em>tomcat-i18n-**.jar</em> &#8212; Optional JARs containing resource bundles
for other languages. As default bundles are also included in each
individual JAR, they can be safely removed if no internationalization
of messages is needed.</li>
<li><em>tomcat-jdbc.jar</em> &#8212; An alternative database connection pool
implementation, known as Tomcat JDBC pool. See
<a href="jdbc-pool.html">documentation</a> for more details.</li>
<li><em>tomcat-util.jar</em> &#8212; Common classes used by various components of
Apache Tomcat.</li>
<li><em>tomcat-websocket.jar</em> &#8212; WebSocket 1.1 implementation</li>
<li><em>websocket-api.jar</em> &#8212; WebSocket 1.1 API</li>
</ul></li>
<li><p><strong>WebappX</strong> &#8212; A class loader is created for each web
application that is deployed in a single Tomcat instance. All unpacked
classes and resources in the <code>/WEB-INF/classes</code> directory of
your web application, plus classes and resources in JAR files
under the <code>/WEB-INF/lib</code> directory of your web application,
are made visible to this web application, but not to other ones.</p></li>
</ul>
<p>As mentioned above, the web application class loader diverges from the
default Java delegation model (in accordance with the recommendations in the
Servlet Specification, version 2.4, section 9.7.2 Web Application Classloader).
When a request to load a
class from the web application's <em>WebappX</em> class loader is processed,
this class loader will look in the local repositories <strong>first</strong>,
instead of delegating before looking. There are exceptions. Classes which are
part of the JRE base classes cannot be overridden. There are some exceptions
such as the XML parser components which can be overridden using the appropriate
JVM feature which is the endorsed standards override feature for Java &lt;= 8
and the upgradeable modules feature for Java 9+.
Lastly, the web application class loader will always delegate first for JavaEE
API classes for the specifications implemented by Tomcat
(Servlet, JSP, EL, WebSocket). All other class loaders in Tomcat follow the
usual delegation pattern.</p>
<p>Therefore, from the perspective of a web application, class or resource
loading looks in the following repositories, in this order:</p>
<ul>
<li>Bootstrap classes of your JVM</li>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
<li>System class loader classes (described above)</li>
<li>Common class loader classes (described above)</li>
</ul>
<p>If the web application class loader is
<a href="config/loader.html">configured</a> with
<code>&lt;Loader delegate=&quot;true&quot;/&gt;</code>
then the order becomes:</p>
<ul>
<li>Bootstrap classes of your JVM</li>
<li>System class loader classes (described above)</li>
<li>Common class loader classes (described above)</li>
<li><em>/WEB-INF/classes</em> of your web application</li>
<li><em>/WEB-INF/lib/*.jar</em> of your web application</li>
</ul>
</section>
<section name="XML Parsers and Java">
<p>Starting with Java 1.4 a copy of JAXP APIs and an XML parser are packed
inside the JRE. This has impacts on applications that wish to use their own
XML parser.</p>
<p>In old versions of Tomcat, you could simply replace the XML parser
in the Tomcat libraries directory to change the parser
used by all web applications. However, this technique will not be effective
when you are running modern versions of Java, because the usual class loader
delegation process will always choose the implementation inside the JDK in
preference to this one.</p>
<p>Java &lt;= 8 supports a mechanism called the "Endorsed Standards Override
Mechanism" to allow replacement of APIs created outside of the JCP
(i.e. DOM and SAX from W3C). It can also be used to update the XML parser
implementation. For more information, see:
<a href="http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html">
http://docs.oracle.com/javase/1.5.0/docs/guide/standards/index.html</a>. For
Java 9+, use the upgradeable modules feature.</p>
<p>Tomcat utilizes the endorsed mechanism by including the system property setting
<code>-Djava.endorsed.dirs=$JAVA_ENDORSED_DIRS</code> in the
command line that starts the container. The default value of this option is
<em>$CATALINA_HOME/endorsed</em>. This <em>endorsed</em> directory is not
created by default. Note that the endorsed feature is no longer supported
with Java 9 and the above system property will only be set if either the
directory <em>$CATALINA_HOME/endorsed</em> exists, or the variable
<code>JAVA_ENDORSED_DIRS</code> has been set.
</p>
<p>Note that overriding any JRE component carries risk. If the overriding
component does not provide a 100% compatible API (e.g. the API provided by
Xerces is not 100% compatible with the XML API provided by the JRE) then there
is a risk that Tomcat and/or the deployed application will experience errors.</p>
</section>
<section name="Running under a security manager">
<p>When running under a security manager the locations from which classes
are permitted to be loaded will also depend on the contents of your policy
file. See <a href="security-manager-howto.html">Security Manager How-To</a>
for further information.</p>
</section>
<section name="Advanced configuration">
<p>A more complex class loader hierarchy may also be configured. See the diagram
below. By default, the <strong>Server</strong> and <strong>Shared</strong>
class loaders are not defined and the simplifed hierarchy shown above is used.
This more complex hierarchy may be use by defining values for the
<code>server.loader</code> and/or <code>shared.loader</code> properties in
<code>conf/catalina.properties</code>.</p>
<source>
Bootstrap
|
System
|
Common
/ \
Server Shared
/ \
Webapp1 Webapp2 ...</source>
<p>The <strong>Server</strong> class loader is only visible to Tomcat internals
and is completely invisible to web applications.</p>
<p>The <strong>Shared</strong> class loader is visible to all web applications
and may be used to shared code across all web applications. However, any updates
to this shared code will require a Tomcat restart.</p>
</section>
</body>
</document>

689
webapps/docs/cluster-howto.xml Normal file
View File

@@ -0,0 +1,689 @@
<?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-howto.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<author email="pero@apache.org">Peter Rossbach</author>
<title>Clustering/Session Replication How-To</title>
</properties>
<body>
<section name="Important Note">
<p><b>You can also check the <a href="config/cluster.html">configuration reference documentation.</a></b>
</p>
</section>
<section name="Table of Contents">
<toc/>
</section>
<section name="For the impatient">
<p>
Simply add
</p>
<source>&lt;Cluster className=&quot;org.apache.catalina.ha.tcp.SimpleTcpCluster&quot;/&gt;</source>
<p>
to your <code>&lt;Engine&gt;</code> or your <code>&lt;Host&gt;</code> element to enable clustering.
</p>
<p>
Using the above configuration will enable all-to-all session replication
using the <code>DeltaManager</code> to replicate session deltas. By all-to-all, we mean that <i>every</i>
session gets replicated to <i>all the other nodes</i> in the cluster.
This works great for smaller clusters, but we don't recommend it for larger clusters &#8212; more than 4 nodes or so.
Also, when using the DeltaManager, Tomcat will replicate sessions to <i>all</i> nodes,
<i>even nodes that don't have the application deployed</i>.<br/>
To get around these problem, you'll want to use the <code>BackupManager</code>. The <code>BackupManager</code>
only replicates the session data to <i>one</i> backup node, and only to nodes that have the application deployed.
Once you have a simple cluster running with the <code>DeltaManager</code>, you will probably want to
migrate to the <code>BackupManager</code> as you increase the number of nodes in your cluster.
</p>
<p>
Here are some of the important default values:
</p>
<ol>
<li>Multicast address is 228.0.0.4</li>
<li>Multicast port is 45564 (the port and the address together determine cluster membership.</li>
<li>The IP broadcasted is <code>java.net.InetAddress.getLocalHost().getHostAddress()</code> (make sure you don't broadcast 127.0.0.1, this is a common error)</li>
<li>The TCP port listening for replication messages is the first available server socket in range <code>4000-4100</code></li>
<li>Listener is configured <code>ClusterSessionListener</code></li>
<li>Two interceptors are configured <code>TcpFailureDetector</code> and <code>MessageDispatchInterceptor</code></li>
</ol>
<p>
The following is the default cluster configuration:
</p>
<source><![CDATA[ <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="8">
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"/>
<Channel className="org.apache.catalina.tribes.group.GroupChannel">
<Membership className="org.apache.catalina.tribes.membership.McastService"
address="228.0.0.4"
port="45564"
frequency="500"
dropTime="3000"/>
<Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="4000"
autoBind="100"
selectorTimeout="5000"
maxThreads="6"/>
<Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
</Sender>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
</Channel>
<Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
filter=""/>
<Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/>
<Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
watchEnabled="false"/>
<ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
</Cluster>]]></source>
<p>We will cover this section in more detail later in this document.</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>private LAN</li>
<li>a Virtual Private Network (VPN)</li>
<li>IPSEC</li>
<li>Encrypt cluster traffic using the <a href="config/cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a></li>
</ul>
</section>
<section name="Cluster Basics">
<p>To run session replication in your Tomcat <version-major/> container, the following steps
should be completed:</p>
<ul>
<li>All your session attributes must implement <code>java.io.Serializable</code></li>
<li>Uncomment the <code>Cluster</code> element in server.xml</li>
<li>If you have defined custom cluster valves, make sure you have the <code>ReplicationValve</code> defined as well under the Cluster element in server.xml</li>
<li>If your Tomcat instances are running on the same machine, make sure the <code>Receiver.port</code>
attribute is unique for each instance, in most cases Tomcat is smart enough to resolve this on it's own by autodetecting available ports in the range 4000-4100</li>
<li>Make sure your <code>web.xml</code> has the
<code>&lt;distributable/&gt;</code> element</li>
<li>If you are using mod_jk, make sure that jvmRoute attribute is set at your Engine <code>&lt;Engine name="Catalina" jvmRoute="node01" &gt;</code>
and that the jvmRoute attribute value matches your worker name in workers.properties</li>
<li>Make sure that all nodes have the same time and sync with NTP service!</li>
<li>Make sure that your loadbalancer is configured for sticky session mode.</li>
</ul>
<p>Load balancing can be achieved through many techniques, as seen in the
<a href="balancer-howto.html">Load Balancing</a> chapter.</p>
<p>Note: Remember that your session state is tracked by a cookie, so your URL must look the same from the out
side otherwise, a new session will be created.</p>
<p>The Cluster module uses the Tomcat JULI logging framework, so you can configure logging
through the regular logging.properties file. To track messages, you can enable logging on the key: <code>org.apache.catalina.tribes.MESSAGES</code></p>
</section>
<section name="Overview">
<p>To enable session replication in Tomcat, three different paths can be followed to achieve the exact same thing:</p>
<ol>
<li>Using session persistence, and saving the session to a shared file system (PersistenceManager + FileStore)</li>
<li>Using session persistence, and saving the session to a shared database (PersistenceManager + JDBCStore)</li>
<li>Using in-memory-replication, using the SimpleTcpCluster that ships with Tomcat (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li>
</ol>
<p>Tomcat can perform an all-to-all replication of session state using the <code>DeltaManager</code> or
perform backup replication to only one node using the <code>BackupManager</code>.
The all-to-all replication is an algorithm that is only efficient when the clusters are small. For larger clusters, you
should use the BackupManager to use a primary-secondary session replication strategy where the session will only be
stored at one backup node.<br/>
Currently you can use the domain worker attribute (mod_jk &gt; 1.2.8) to build cluster partitions
with the potential of having a more scalable cluster solution with the DeltaManager
(you'll need to configure the domain interceptor for this).
In order to keep the network traffic down in an all-to-all environment, you can split your cluster
into smaller groups. This can be easily achieved by using different multicast addresses for the different groups.
A very simple setup would look like this:
</p>
<source> DNS Round Robin
|
Load Balancer
/ \
Cluster1 Cluster2
/ \ / \
Tomcat1 Tomcat2 Tomcat3 Tomcat4</source>
<p>What is important to mention here, is that session replication is only the beginning of clustering.
Another popular concept used to implement clusters is farming, i.e., you deploy your apps only to one
server, and the cluster will distribute the deployments across the entire cluster.
This is all capabilities that can go into with the FarmWarDeployer (s. cluster example at <code>server.xml</code>)</p>
<p>In the next section will go deeper into how session replication works and how to configure it.</p>
</section>
<section name="Cluster Information">
<p>Membership is established using multicast heartbeats.
Hence, if you wish to subdivide your clusters, you can do this by
changing the multicast IP address or port in the <code>&lt;Membership&gt;</code> element.
</p>
<p>
The heartbeat contains the IP address of the Tomcat node and the TCP port that
Tomcat listens to for replication traffic. All data communication happens over TCP.
</p>
<p>
The <code>ReplicationValve</code> is used to find out when the request has been completed and initiate the
replication, if any. Data is only replicated if the session has changed (by calling setAttribute or removeAttribute
on the session).
</p>
<p>
One of the most important performance considerations is the synchronous versus asynchronous replication.
In a synchronous replication mode the request doesn't return until the replicated session has been
sent over the wire and reinstantiated on all the other cluster nodes.
Synchronous vs. asynchronous is configured using the <code>channelSendOptions</code>
flag and is an integer value. The default value for the <code>SimpleTcpCluster/DeltaManager</code> combo is
8, which is asynchronous. You can read more on the <a href="tribes/introduction.html">send flag(overview)</a> or the
<doc path="/api/org/apache/catalina/tribes/Channel.html">send flag(javadoc)</doc>.
During async replication, the request is returned before the data has been replicated. async replication yields shorter
request times, and synchronous replication guarantees the session to be replicated before the request returns.
</p>
</section>
<section name="Bind session after crash to failover node">
<p>
If you are using mod_jk and not using sticky sessions or for some reasons sticky session don't
work, or you are simply failing over, the session id will need to be modified as it previously contained
the worker id of the previous tomcat (as defined by jvmRoute in the Engine element).
To solve this, we will use the JvmRouteBinderValve.
</p>
<p>
The JvmRouteBinderValve rewrites the session id to ensure that the next request will remain sticky
(and not fall back to go to random nodes since the worker is no longer available) after a fail over.
The valve rewrites the JSESSIONID value in the cookie with the same name.
Not having this valve in place, will make it harder to ensure stickiness in case of a failure for the mod_jk module.
</p>
<p>
Remember, if you are adding your own valves in server.xml then the defaults are no longer valid,
make sure that you add in all the appropriate valves as defined by the default.
</p>
<p>
<b>Hint:</b><br/>
With attribute <i>sessionIdAttribute</i> you can change the request attribute name that included the old session id.
Default attribute name is <i>org.apache.catalina.ha.session.JvmRouteOrignalSessionID</i>.
</p>
<p>
<b>Trick:</b><br/>
You can enable this mod_jk turnover mode via JMX before you drop a node to all backup nodes!
Set enable true on all JvmRouteBinderValve backups, disable worker at mod_jk
and then drop node and restart it! Then enable mod_jk Worker and disable JvmRouteBinderValves again.
This use case means that only requested session are migrated.
</p>
</section>
<section name="Configuration Example">
<source><![CDATA[ <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="6">
<Manager className="org.apache.catalina.ha.session.BackupManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"
mapSendOptions="6"/>
<!--
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"/>
-->
<Channel className="org.apache.catalina.tribes.group.GroupChannel">
<Membership className="org.apache.catalina.tribes.membership.McastService"
address="228.0.0.4"
port="45564"
frequency="500"
dropTime="3000"/>
<Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="5000"
selectorTimeout="100"
maxThreads="6"/>
<Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
</Sender>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/>
</Channel>
<Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/>
<Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
watchEnabled="false"/>
<ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
</Cluster>]]></source>
<p>
Break it down!!
</p>
<source><![CDATA[ <Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="6">]]></source>
<p>
The main element, inside this element all cluster details can be configured.
The <code>channelSendOptions</code> is the flag that is attached to each message sent by the
SimpleTcpCluster class or any objects that are invoking the SimpleTcpCluster.send method.
The description of the send flags is available at <doc path="/api/org/apache/catalina/tribes/Channel.html">
our javadoc site</doc>
The <code>DeltaManager</code> sends information using the SimpleTcpCluster.send method, while the backup manager
sends it itself directly through the channel.
<br/>For more info, Please visit the <a href="config/cluster.html">reference documentation</a>
</p>
<source><![CDATA[ <Manager className="org.apache.catalina.ha.session.BackupManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"
mapSendOptions="6"/>
<!--
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true"/>
-->]]></source>
<p>
This is a template for the manager configuration that will be used if no manager is defined in the &lt;Context&gt;
element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case
since Tomcat you can define a manager class for each webapp, so that you can mix managers in your cluster.
Obviously the managers on one node's application has to correspond with the same manager on the same application on the other node.
If no manager has been specified for the webapp, and the webapp is marked &lt;distributable/&gt; Tomcat will take this manager configuration
and create a manager instance cloning this configuration.
<br/>For more info, Please visit the <a href="config/cluster-manager.html">reference documentation</a>
</p>
<source><![CDATA[ <Channel className="org.apache.catalina.tribes.group.GroupChannel">]]></source>
<p>
The channel element is <a href="tribes/introduction.html">Tribes</a>, the group communication framework
used inside Tomcat. This element encapsulates everything that has to do with communication and membership logic.
<br/>For more info, Please visit the <a href="config/cluster-channel.html">reference documentation</a>
</p>
<source><![CDATA[ <Membership className="org.apache.catalina.tribes.membership.McastService"
address="228.0.0.4"
port="45564"
frequency="500"
dropTime="3000"/>]]></source>
<p>
Membership is done using multicasting. Please note that Tribes also supports static memberships using the
<code>StaticMembershipInterceptor</code> if you want to extend your membership to points beyond multicasting.
The address attribute is the multicast address used and the port is the multicast port. These two together
create the cluster separation. If you want a QA cluster and a production cluster, the easiest config is to
have the QA cluster be on a separate multicast address/port combination than the production cluster.<br/>
The membership component broadcasts TCP address/port of itself to the other nodes so that communication between
nodes can be done over TCP. Please note that the address being broadcasted is the one of the
<code>Receiver.address</code> attribute.
<br/>For more info, Please visit the <a href="config/cluster-membership.html">reference documentation</a>
</p>
<source><![CDATA[ <Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="5000"
selectorTimeout="100"
maxThreads="6"/>]]></source>
<p>
In tribes the logic of sending and receiving data has been broken into two functional components. The Receiver, as the name suggests
is responsible for receiving messages. Since the Tribes stack is thread less, (a popular improvement now adopted by other frameworks as well),
there is a thread pool in this component that has a maxThreads and minThreads setting.<br/>
The address attribute is the host address that will be broadcasted by the membership component to the other nodes.
<br/>For more info, Please visit the <a href="config/cluster-receiver.html">reference documentation</a>
</p>
<source><![CDATA[ <Sender className="org.apache.catalina.tribes.transport.ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
</Sender>]]></source>
<p>
The sender component, as the name indicates is responsible for sending messages to other nodes.
The sender has a shell component, the <code>ReplicationTransmitter</code> but the real stuff done is done in the
sub component, <code>Transport</code>.
Tribes support having a pool of senders, so that messages can be sent in parallel and if using the NIO sender,
you can send messages concurrently as well.<br/>
Concurrently means one message to multiple senders at the same time and Parallel means multiple messages to multiple senders
at the same time.
<br/>For more info, Please visit the <a href="config/cluster-sender.html">reference documentation</a>
</p>
<source><![CDATA[ <Interceptor className="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor"/>
<Interceptor className="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor"/>
</Channel>]]></source>
<p>
Tribes uses a stack to send messages through. Each element in the stack is called an interceptor, and works much like the valves do
in the Tomcat servlet container.
Using interceptors, logic can be broken into more manageable pieces of code. The interceptors configured above are:<br/>
TcpFailureDetector - verifies crashed members through TCP, if multicast packets get dropped, this interceptor protects against false positives,
ie the node marked as crashed even though it still is alive and running.<br/>
MessageDispatchInterceptor - dispatches messages to a thread (thread pool) to send message asynchronously.<br/>
ThroughputInterceptor - prints out simple stats on message traffic.<br/>
Please note that the order of interceptors is important. The way they are defined in server.xml is the way they are represented in the
channel stack. Think of it as a linked list, with the head being the first most interceptor and the tail the last.
<br/>For more info, Please visit the <a href="config/cluster-interceptor.html">reference documentation</a>
</p>
<source><![CDATA[ <Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt"/>]]></source>
<p>
The cluster uses valves to track requests to web applications, we've mentioned the ReplicationValve and the JvmRouteBinderValve above.
The &lt;Cluster&gt; element itself is not part of the pipeline in Tomcat, instead the cluster adds the valve to its parent container.
If the &lt;Cluster&gt; elements is configured in the &lt;Engine&gt; element, the valves get added to the engine and so on.
<br/>For more info, Please visit the <a href="config/cluster-valve.html">reference documentation</a>
</p>
<source><![CDATA[ <Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
watchEnabled="false"/>]]></source>
<p>
The default tomcat cluster supports farmed deployment, ie, the cluster can deploy and undeploy applications on the other nodes.
The state of this component is currently in flux but will be addressed soon. There was a change in the deployment algorithm
between Tomcat 5.0 and 5.5 and at that point, the logic of this component changed to where the deploy dir has to match the
webapps directory.
<br/>For more info, Please visit the <a href="config/cluster-deployer.html">reference documentation</a>
</p>
<source><![CDATA[ <ClusterListener className="org.apache.catalina.ha.session.ClusterSessionListener"/>
</Cluster>]]></source>
<p>
Since the SimpleTcpCluster itself is a sender and receiver of the Channel object, components can register themselves as listeners to
the SimpleTcpCluster. The listener above <code>ClusterSessionListener</code> listens for DeltaManager replication messages
and applies the deltas to the manager that in turn applies it to the session.
<br/>For more info, Please visit the <a href="config/cluster-listener.html">reference documentation</a>
</p>
</section>
<section name="Cluster Architecture">
<p><b>Component Levels:</b></p>
<source> Server
|
Service
|
Engine
| \
| --- Cluster --*
|
Host
|
------
/ \
Cluster Context(1-N)
| \
| -- Manager
| \
| -- DeltaManager
| -- BackupManager
|
---------------------------
| \
Channel \
----------------------------- \
| \
Interceptor_1 .. \
| \
Interceptor_N \
----------------------------- \
| | | \
Receiver Sender Membership \
-- Valve
| \
| -- ReplicationValve
| -- JvmRouteBinderValve
|
-- LifecycleListener
|
-- ClusterListener
| \
| -- ClusterSessionListener
|
-- Deployer
\
-- FarmWarDeployer
</source>
</section>
<section name="How it Works">
<p>To make it easy to understand how clustering works, we are gonna to take you through a series of scenarios.
In this scenario we only plan to use two tomcat instances <code>TomcatA</code> and <code>TomcatB</code>.
We will cover the following sequence of events:</p>
<ol>
<li><code>TomcatA</code> starts up</li>
<li><code>TomcatB</code> starts up (Wait the TomcatA start is complete)</li>
<li><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</li>
<li><code>TomcatA</code> crashes</li>
<li><code>TomcatB</code> receives a request for session <code>S1</code></li>
<li><code>TomcatA</code> starts up</li>
<li><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</li>
<li><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</li>
<li><code>TomcatA</code> The session <code>S2</code> expires due to inactivity.</li>
</ol>
<p>Ok, now that we have a good sequence, we will take you through exactly what happens in the session replication code</p>
<ol>
<li><b><code>TomcatA</code> starts up</b>
<p>
Tomcat starts up using the standard start up sequence. When the Host object is created, a cluster object is associated with it.
When the contexts are parsed, if the distributable element is in place in the web.xml file,
Tomcat asks the Cluster class (in this case <code>SimpleTcpCluster</code>) to create a manager
for the replicated context. So with clustering enabled, distributable set in web.xml
Tomcat will create a <code>DeltaManager</code> for that context instead of a <code>StandardManager</code>.
The cluster class will start up a membership service (multicast) and a replication service (tcp unicast).
More on the architecture further down in this document.
</p>
</li>
<li><b><code>TomcatB</code> starts up</b>
<p>
When TomcatB starts up, it follows the same sequence as TomcatA did with one exception.
The cluster is started and will establish a membership (TomcatA, TomcatB).
TomcatB will now request the session state from a server that already exists in the cluster,
in this case TomcatA. TomcatA responds to the request, and before TomcatB starts listening
for HTTP requests, the state has been transferred from TomcatA to TomcatB.
In case TomcatA doesn't respond, TomcatB will time out after 60 seconds, issue a log
entry, and continue starting. The session state gets transferred for each web
application that has distributable in its web.xml. (Note: To use session replication
efficiently, all your tomcat instances should be configured the same.)
</p>
</li>
<li><B><code>TomcatA</code> receives a request, a session <code>S1</code> is created.</B>
<p>
The request coming in to TomcatA is handled exactly the same way as without session
replication, until the request is completed, at which time the
<code>ReplicationValve</code> will intercept the request before the response is
returned to the user. At this point it finds that the session has been modified,
and it uses TCP to replicate the session to TomcatB. Once the serialized data has
been handed off to the operating system's TCP logic, the request returns to the user,
back through the valve pipeline. For each request the entire session is replicated,
this allows code that modifies attributes in the session without calling setAttribute
or removeAttribute to be replicated. A useDirtyFlag configuration parameter can
be used to optimize the number of times a session is replicated.
</p>
</li>
<li><b><code>TomcatA</code> crashes</b>
<p>
When TomcatA crashes, TomcatB receives a notification that TomcatA has dropped out
of the cluster. TomcatB removes TomcatA from its membership list, and TomcatA will
no longer be notified of any changes that occurs in TomcatB. The load balancer
will redirect the requests from TomcatA to TomcatB and all the sessions are current.
</p>
</li>
<li><b><code>TomcatB</code> receives a request for session <code>S1</code></b>
<p>Nothing exciting, TomcatB will process the request as any other request.
</p>
</li>
<li><b><code>TomcatA</code> starts up</b>
<p>Upon start up, before TomcatA starts taking new request and making itself
available to it will follow the start up sequence described above 1) 2).
It will join the cluster, contact TomcatB for the current state of all the sessions.
And once it receives the session state, it finishes loading and opens its HTTP/mod_jk ports.
So no requests will make it to TomcatA until it has received the session state from TomcatB.
</p>
</li>
<li><b><code>TomcatA</code> receives a request, invalidate is called on the session (<code>S1</code>)</b>
<p>The invalidate call is intercepted, and the session is queued with invalidated sessions.
When the request is complete, instead of sending out the session that has changed, it sends out
an "expire" message to TomcatB and TomcatB will invalidate the session as well.
</p>
</li>
<li><b><code>TomcatB</code> receives a request, for a new session (<code>S2</code>)</b>
<p>Same scenario as in step 3)
</p>
</li>
<li><code>TomcatA</code> The session <code>S2</code> expires due to inactivity.
<p>The invalidate call is intercepted the same way as when a session is invalidated by the user,
and the session is queued with invalidated sessions.
At this point, the invalidated session will not be replicated across until
another request comes through the system and checks the invalid queue.
</p>
</li>
</ol>
<p>Phuuuhh! :)</p>
<p><b>Membership</b>
Clustering membership is established using very simple multicast pings.
Each Tomcat instance will periodically send out a multicast ping,
in the ping message the instance will broadcast its IP and TCP listen port
for replication.
If an instance has not received such a ping within a given timeframe, the
member is considered dead. Very simple, and very effective!
Of course, you need to enable multicasting on your system.
</p>
<p><b>TCP Replication</b>
Once a multicast ping has been received, the member is added to the cluster
Upon the next replication request, the sending instance will use the host and
port info and establish a TCP socket. Using this socket it sends over the serialized data.
The reason I chose TCP sockets is because it has built in flow control and guaranteed delivery.
So I know, when I send some data, it will make it there :)
</p>
<p><b>Distributed locking and pages using frames</b>
Tomcat does not keep session instances in sync across the cluster.
The implementation of such logic would be to much overhead and cause all
kinds of problems. If your client accesses the same session
simultaneously using multiple requests, then the last request
will override the other sessions in the cluster.
</p>
</section>
<section name="Monitoring your Cluster with JMX">
<p>Monitoring is a very important question when you use a cluster. Some of the cluster objects are JMX MBeans </p>
<p>Add the following parameter to your startup script:</p>
<source>set CATALINA_OPTS=\
-Dcom.sun.management.jmxremote \
-Dcom.sun.management.jmxremote.port=%my.jmx.port% \
-Dcom.sun.management.jmxremote.ssl=false \
-Dcom.sun.management.jmxremote.authenticate=false</source>
<p>
List of Cluster Mbeans
</p>
<table class="defaultTable">
<tr>
<th>Name</th>
<th>Description</th>
<th>MBean ObjectName - Engine</th>
<th>MBean ObjectName - Host</th>
</tr>
<tr>
<td>Cluster</td>
<td>The complete cluster element</td>
<td><code>type=Cluster</code></td>
<td><code>type=Cluster,host=${HOST}</code></td>
</tr>
<tr>
<td>DeltaManager</td>
<td>This manager control the sessions and handle session replication </td>
<td><code>type=Manager,context=${APP.CONTEXT.PATH}, host=${HOST}</code></td>
<td><code>type=Manager,context=${APP.CONTEXT.PATH}, host=${HOST}</code></td>
</tr>
<tr>
<td>FarmWarDeployer</td>
<td>Manages the process of deploying an application to all nodes in the cluster</td>
<td>Not supported</td>
<td><code>type=Cluster, host=${HOST}, component=deployer</code></td>
</tr>
<tr>
<td>Member</td>
<td>Represents a node in the cluster</td>
<td>type=Cluster, component=member, name=${NODE_NAME}</td>
<td><code>type=Cluster, host=${HOST}, component=member, name=${NODE_NAME}</code></td>
</tr>
<tr>
<td>ReplicationValve</td>
<td>This valve control the replication to the backup nodes</td>
<td><code>type=Valve,name=ReplicationValve</code></td>
<td><code>type=Valve,name=ReplicationValve,host=${HOST}</code></td>
</tr>
<tr>
<td>JvmRouteBinderValve</td>
<td>This is a cluster fallback valve to change the Session ID to the current tomcat jvmroute.</td>
<td><code>type=Valve,name=JvmRouteBinderValve,
context=${APP.CONTEXT.PATH}</code></td>
<td><code>type=Valve,name=JvmRouteBinderValve,host=${HOST},
context=${APP.CONTEXT.PATH}</code></td>
</tr>
</table>
</section>
<section name="FAQ">
<p>Please see <a href="https://wiki.apache.org/tomcat/FAQ/Clustering">the clustering section of the FAQ</a>.</p>
</section>
</body>
</document>

118
webapps/docs/comments.xml Normal file
View File

@@ -0,0 +1,118 @@
<?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="comments.html">
&project;
<properties>
<title>Documentation User Comments</title>
</properties>
<body>
<section name="Introduction">
<p>The Tomcat documentation integrates the
<a href="https://comments.apache.org/help.html">Apache Comments System</a>.
It allows users to add comments to most documentation pages. The comments
section can be found at the end of each page.</p>
</section>
<section name="Allowed Content">
<p>Please use the Apache Comments System responsibly. We can only provide
this service to the community as long as it isn't misused.</p>
<p>The comments are not for general Q&amp;A.
Comments should be pointed towards suggestions on improving the documentation
or server. Questions on how to use Apache Tomcat should be directed
to our <a href="https://tomcat.apache.org/lists.html">mailing lists</a>.</p>
<p>Comments may be removed by moderators if they are either
implemented or considered invalid/off-topic.</p>
<p>HTML is not allowed in comments, and will just display as raw source code
if attempted. Links that do not point to an Apache site (*.apache.org) will
need approval by a moderator before the comment is visible to regular visitors.</p>
</section>
<section name="License">
<p>Any submitted comments must be contributed under the terms of the
<a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
</section>
<section name="Verified Users">
<p>Verified users gain the Apache feather next to their name,
and may post comments with links in them without requiring approval
by a moderator before the comments are shown. Being a verified user
in itself does not give you moderating rights. If you are interested
in becoming a verified user, please contact us on the
<a href="https://tomcat.apache.org/lists.html#tomcat-users">users mailing list</a>.</p>
<p>All ASF committers are automatically verified users.</p>
</section>
<section name="Moderators">
<p>Moderators are allowed to mark comments as "Resolved", "Invalid"
or "Sticky", remove marks, approve comments e.g. if they contain
a link, and delete comments. Moderators can also subscribe to new
comments and comment updates and use the dashboard to gain some
overview over all comments of a site.</p>
<p>To use the moderation features, you need to login to the comments
system. Furthermore you will need to allow cookies to be set for
comments.apache.org (this is done using a secure https cookie). Once
logged in as a moderator you will see additional moderation
options attached to each comment.</p>
<p>If you are a long time follower of the Apache Tomcat projects
and you are interested in becoming a moderator, please contact us on the
<a href="https://tomcat.apache.org/lists.html#tomcat-users">users mailing list</a>.</p>
</section>
<section name="Privacy Policy">
<p>No data except what you personally submit is kept on record.
A cookie is used to keep track of moderators and other people
who wish to create an account to avoid having to enter their
credentials whenever they wish to post a comment.</p>
<p>To prevent spam and unsolicited comments, we use a digest of
visitors' IPs to keep track of comments posted by them.</p>
<p>Entering an email address when you post a comment is completely
optional, and will not be shared with anyone. If you enter an
email address, it will be used to notify you when someone posts
a reply to one of your comments, provided you have registered
an account and validated your email address.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,888 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="ajp.html">
&project;
<properties>
<author email="yoavs@apache.org">Yoav Shapira</author>
<author email="arjaquith@mindspring.com">Andrew R. Jaquith</author>
<title>The AJP Connector</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>AJP Connector</strong> element represents a
<strong>Connector</strong> component that communicates with a web
connector via the <code>AJP</code> protocol. This is used for cases
where you wish to invisibly integrate Tomcat into an existing (or new)
Apache installation, and you want Apache to handle the static content
contained in the web application, and/or utilize Apache's SSL
processing.</p>
<p>Use of the AJP protocol requires additional security considerations because
it allows greater direct manipulation of Tomcat's internal data structures
than the HTTP connectors. Particular attention should be paid to the values
used for the <code>address</code>, <code>secret</code>,
<code>secretRequired</code> and <code>allowedRequestAttributesPattern</code>
attributes.</p>
<p>This connector supports load balancing when used in conjunction with
the <code>jvmRoute</code> attribute of the
<a href="engine.html">Engine</a>.</p>
<p>The native connectors supported with this Tomcat release are:</p>
<ul>
<li>JK 1.2.x with any of the supported servers. See
<a href="https://tomcat.apache.org/connectors-doc/">the JK docs</a>
for details.</li>
<li>mod_proxy on Apache httpd 2.x (included by default in Apache HTTP
Server 2.2), with AJP enabled: see
<a href="https://httpd.apache.org/docs/2.2/mod/mod_proxy_ajp.html">the
httpd docs</a> for details.</li>
</ul>
<p><b>Other native connectors supporting AJP may work, but are no longer
supported.</b></p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Connector</strong>
support the following attributes:</p>
<attributes>
<attribute name="ajpFlush" required="false">
<p>A boolean value which can be used to enable or disable sending
AJP flush messages to the fronting proxy whenever an explicit
flush happens. The default value is <code>true</code>.<br/>
An AJP flush message is a SEND_BODY_CHUNK packet with no body content.
Proxy implementations like mod_jk or mod_proxy_ajp will flush the
data buffered in the web server to the client when they receive
such a packet. Setting this to <code>false</code> can reduce
AJP packet traffic but might delay sending packets to the client.
At the end of the response, AJP does always flush to the client.</p>
</attribute>
<attribute name="allowTrace" required="false">
<p>A boolean value which can be used to enable or disable the TRACE
HTTP method. If not specified, this attribute is set to false.</p>
</attribute>
<attribute name="asyncTimeout" required="false">
<p>The default timeout for asynchronous requests in milliseconds. If not
specified, this attribute is set to the Servlet specification default of
30000 (30 seconds).</p>
</attribute>
<attribute name="enableLookups" required="false">
<p>Set to <code>true</code> if you want calls to
<code>request.getRemoteHost()</code> to perform DNS lookups in
order to return the actual host name of the remote client. Set
to <code>false</code> to skip the DNS lookup and return the IP
address in String form instead (thereby improving performance).
By default, DNS lookups are disabled.</p>
</attribute>
<attribute name="maxHeaderCount" required="false">
<p>The maximum number of headers in a request that are allowed by the
container. A request that contains more headers than the specified limit
will be rejected. A value of less than 0 means no limit.
If not specified, a default of 100 is used.</p>
</attribute>
<attribute name="maxParameterCount" required="false">
<p>The maximum number of parameter and value pairs (GET plus POST) which
will be automatically parsed by the container. Parameter and value pairs
beyond this limit will be ignored. A value of less than 0 means no limit.
If not specified, a default of 10000 is used. Note that
<code>FailedRequestFilter</code> <a href="filter.html">filter</a> can be
used to reject requests that hit the limit.</p>
</attribute>
<attribute name="maxPostSize" required="false">
<p>The maximum size in bytes of the POST which will be handled by
the container FORM URL parameter parsing. The limit can be disabled by
setting this attribute to a value less than zero. If not specified, this
attribute is set to 2097152 (2 megabytes). Note that the
<a href="filter.html#Failed_Request_Filter"><code>FailedRequestFilter</code></a>
can be used to reject requests that exceed this limit.</p>
</attribute>
<attribute name="maxSavePostSize" required="false">
<p>The maximum size in bytes of the POST which will be saved/buffered by
the container during FORM or CLIENT-CERT authentication. For both types
of authentication, the POST will be saved/buffered before the user is
authenticated. For CLIENT-CERT authentication, the POST is buffered for
the duration of the SSL handshake and the buffer emptied when the request
is processed. For FORM authentication the POST is saved whilst the user
is re-directed to the login form and is retained until the user
successfully authenticates or the session associated with the
authentication request expires. The limit can be disabled by setting this
attribute to -1. Setting the attribute to zero will disable the saving of
POST data during authentication. If not specified, this attribute is set
to 4096 (4 kilobytes).</p>
</attribute>
<attribute name="parseBodyMethods" required="false">
<p>A comma-separated list of HTTP methods for which request
bodies using <code>application/x-www-form-urlencoded</code> will be parsed
for request parameters identically to POST. This is useful in RESTful
applications that want to support POST-style semantics for PUT requests.
Note that any setting other than <code>POST</code> causes Tomcat
to behave in a way that goes against the intent of the servlet
specification.
The HTTP method TRACE is specifically forbidden here in accordance
with the HTTP specification.
The default is <code>POST</code></p>
</attribute>
<attribute name="port" required="true">
<p>The TCP port number on which this <strong>Connector</strong>
will create a server socket and await incoming connections. Your
operating system will allow only one server application to listen
to a particular port number on a particular IP address. If the special
value of 0 (zero) is used, then Tomcat will select a free port at random
to use for this connector. This is typically only useful in embedded and
testing applications.</p>
</attribute>
<attribute name="protocol" required="false">
<p>Sets the protocol to handle incoming traffic. To configure an AJP
connector this must be specified. If no value for protocol is provided,
an <a href="http.html">HTTP connector</a> rather than an AJP connector
will be configured.<br/>
The standard protocol value for an AJP connector is <code>AJP/1.3</code>
which uses an auto-switching mechanism to select either a Java NIO based
connector or an APR/native based connector. If the
<code>PATH</code> (Windows) or <code>LD_LIBRARY_PATH</code> (on most unix
systems) environment variables contain the Tomcat native library, the
native/APR connector will be used. If the native library cannot be
found, the Java NIO based connector will be used.<br/>
To use an explicit protocol rather than rely on the auto-switching
mechanism described above, the following values may be used:<br/>
<code>org.apache.coyote.ajp.AjpNioProtocol</code>
- non blocking Java NIO connector.<br/>
<code>org.apache.coyote.ajp.AjpNio2Protocol</code>
- non blocking Java NIO2 connector.<br/>
<code>org.apache.coyote.ajp.AjpAprProtocol</code>
- the APR/native connector.<br/>
Custom implementations may also be used.<br/>
Take a look at our <a href="#Connector_Comparison">Connector
Comparison</a> chart.
</p>
</attribute>
<attribute name="proxyName" required="false">
<p>If this <strong>Connector</strong> is being used in a proxy
configuration, configure this attribute to specify the server name
to be returned for calls to <code>request.getServerName()</code>.
See <a href="#Proxy_Support">Proxy Support</a> for more
information.</p>
</attribute>
<attribute name="proxyPort" required="false">
<p>If this <strong>Connector</strong> is being used in a proxy
configuration, configure this attribute to specify the server port
to be returned for calls to <code>request.getServerPort()</code>.
See <a href="#Proxy_Support">Proxy Support</a> for more
information.</p>
</attribute>
<attribute name="redirectPort" required="false">
<p>If this <strong>Connector</strong> is supporting non-SSL
requests, and a request is received for which a matching
<code>&lt;security-constraint&gt;</code> requires SSL transport,
Catalina will automatically redirect the request to the port
number specified here.</p>
</attribute>
<attribute name="scheme" required="false">
<p>Set this attribute to the name of the protocol you wish to have
returned by calls to <code>request.getScheme()</code>. For
example, you would set this attribute to "<code>https</code>"
for an SSL Connector. The default value is "<code>http</code>".
</p>
</attribute>
<attribute name="secure" required="false">
<p>Set this attribute to <code>true</code> if you wish to have
calls to <code>request.isSecure()</code> to return <code>true</code>
for requests received by this Connector. You would want this on an
SSL Connector or a non SSL connector that is receiving data from a
SSL accelerator, like a crypto card, an SSL appliance or even a webserver.
The default value is <code>false</code>.</p>
</attribute>
<attribute name="sendReasonPhrase" required="false">
<p>Set this attribute to <code>true</code> if you wish to have
a reason phrase in the response.
The default value is <code>false</code>.</p>
<p><strong>Note:</strong> This option is deprecated and will be removed
in Tomcat 9. The reason phrase will not be sent.</p>
</attribute>
<attribute name="URIEncoding" required="false">
<p>This specifies the character encoding used to decode the URI bytes,
after %xx decoding the URL. If not specified, UTF-8 will be used unless
the <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system property</a> is set to <code>true</code>
in which case ISO-8859-1 will be used.</p>
</attribute>
<attribute name="useBodyEncodingForURI" required="false">
<p>This specifies if the encoding specified in contentType should be used
for URI query parameters, instead of using the URIEncoding. This
setting is present for compatibility with Tomcat 4.1.x, where the
encoding specified in the contentType, or explicitly set using
Request.setCharacterEncoding method was also used for the parameters from
the URL. The default value is <code>false</code>.
</p>
<p><em>Notes:</em> See notes on this attribute in
<a href="http.html">HTTP Connector</a> documentation.</p>
</attribute>
<attribute name="useIPVHosts" required="false">
<p>Set this attribute to <code>true</code> to cause Tomcat to use
the IP address passed by the native web server to determine the Host
to send the request to. The default value is <code>false</code>.</p>
</attribute>
<attribute name="xpoweredBy" required="false">
<p>Set this attribute to <code>true</code> to cause Tomcat to advertise
support for the Servlet specification using the header recommended in the
specification. The default value is <code>false</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementations">
<p>To use AJP, you must specify the protocol attribute (see above).</p>
<p>The standard AJP connectors (NIO, NIO2 and APR/native) all support the
following attributes in addition to the common Connector attributes listed
above.</p>
<attributes>
<attribute name="acceptCount" required="false">
<p>The maximum queue length for incoming connection requests when
all possible request processing threads are in use. Any requests
received when the queue is full will be refused. The default
value is 100.</p>
</attribute>
<attribute name="acceptorThreadCount" required="false">
<p>The number of threads to be used to accept connections. Increase this
value on a multi CPU machine, although you would never really need more
than <code>2</code>. Also, with a lot of non keep alive connections, you
might want to increase this value as well. Default value is
<code>1</code>.</p>
</attribute>
<attribute name="acceptorThreadPriority" required="false">
<p>The priority of the acceptor threads. The threads used to accept
new connections. The default value is <code>5</code> (the value of the
<code>java.lang.Thread.NORM_PRIORITY</code> constant). See the JavaDoc
for the <code>java.lang.Thread</code> class for more details on what
this priority means.</p>
</attribute>
<attribute name="address" required="false">
<p>For servers with more than one IP address, this attribute
specifies which address will be used for listening on the specified
port. By default, the loopback address will be used.</p>
</attribute>
<attribute name="allowedRequestAttributesPattern" required="false">
<p>The AJP protocol passes some information from the reverse proxy to the
AJP connector using request attributes. These attributes are:</p>
<ul>
<li>javax.servlet.request.cipher_suite</li>
<li>javax.servlet.request.key_size</li>
<li>javax.servlet.request.ssl_session</li>
<li>javax.servlet.request.X509Certificate</li>
<li>AJP_LOCAL_ADDR</li>
<li>AJP_REMOTE_PORT</li>
<li>AJP_SSL_PROTOCOL</li>
<li>JK_LB_ACTIVATION</li>
</ul>
<p>The AJP protocol supports the passing of arbitrary request attributes.
Requests containing arbitrary request attributes will be rejected with a
403 response unless the entire attribute name matches this regular
expression. If not specified, the default value is <code>null</code>.</p>
</attribute>
<attribute name="bindOnInit" required="false">
<p>Controls when the socket used by the connector is bound. By default it
is bound when the connector is initiated and unbound when the connector is
destroyed. If set to <code>false</code>, the socket will be bound when the
connector is started and unbound when it is stopped.</p>
</attribute>
<attribute name="clientCertProvider" required="false">
<p>When client certificate information is presented in a form other than
instances of <code>java.security.cert.X509Certificate</code> it needs to
be converted before it can be used and this property controls which JSSE
provider is used to perform the conversion. For example it is used with
the AJP connectors, the <a href="http.html">HTTP APR connector</a> and
with the <a href="valve.html#SSL_Authenticator_Valve">
org.apache.catalina.valves.SSLValve</a>.If not specified, the default
provider will be used.</p>
</attribute>
<attribute name="connectionLinger" required="false">
<p>The number of seconds during which the sockets used by this
<strong>Connector</strong> will linger when they are closed. The default
value is <code>-1</code> which disables socket linger.</p>
</attribute>
<attribute name="connectionTimeout" required="false">
<p>The number of milliseconds this <strong>Connector</strong> will wait,
after accepting a connection, for the request URI line to be
presented. The default value for AJP protocol connectors
is <code>-1</code> (i.e. infinite).</p>
</attribute>
<attribute name="executor" required="false">
<p>A reference to the name in an <a href="executor.html">Executor</a>
element. If this attribute is set, and the named executor exists, the
connector will use the executor, and all the other thread attributes will
be ignored. Note that if a shared executor is not specified for a
connector then the connector will use a private, internal executor to
provide the thread pool.</p>
</attribute>
<attribute name="executorTerminationTimeoutMillis" required="false">
<p>The time that the private internal executor will wait for request
processing threads to terminate before continuing with the process of
stopping the connector. If not set, the default is <code>5000</code> (5
seconds).</p>
</attribute>
<attribute name="keepAliveTimeout" required="false">
<p>The number of milliseconds this <strong>Connector</strong> will wait for
another AJP request before closing the connection.
The default value is to use the value that has been set for the
connectionTimeout attribute.</p>
</attribute>
<attribute name="maxConnections" required="false">
<p>The maximum number of connections that the server will accept and
process at any given time. When this number has been reached, the server
will accept, but not process, one further connection. This additional
connection be blocked until the number of connections being processed
falls below <strong>maxConnections</strong> at which point the server will
start accepting and processing new connections again. Note that once the
limit has been reached, the operating system may still accept connections
based on the <code>acceptCount</code> setting. The default value varies by
connector type. For NIO and NIO2 the default is <code>10000</code>.
For APR/native, the default is <code>8192</code>.</p>
<p>For NIO/NIO2 only, setting the value to -1, will disable the
maxConnections feature and connections will not be counted.</p>
</attribute>
<attribute name="maxCookieCount" required="false">
<p>The maximum number of cookies that are permitted for a request. A value
of less than zero means no limit. If not specified, a default value of 200
will be used.</p>
</attribute>
<attribute name="maxThreads" required="false">
<p>The maximum number of request processing threads to be created
by this <strong>Connector</strong>, which therefore determines the
maximum number of simultaneous requests that can be handled. If
not specified, this attribute is set to 200. If an executor is associated
with this connector, this attribute is ignored as the connector will
execute tasks using the executor rather than an internal thread pool. Note
that if an executor is configured any value set for this attribute will be
recorded correctly but it will be reported (e.g. via JMX) as
<code>-1</code> to make clear that it is not used.</p>
</attribute>
<attribute name="minSpareThreads" required="false">
<p>The minimum number of threads always kept running. This includes both
active and idle threads. If not specified, the default of <code>10</code>
is used. If an executor is associated with this connector, this attribute
is ignored as the connector will execute tasks using the executor rather
than an internal thread pool. Note that if an executor is configured any
value set for this attribute will be recorded correctly but it will be
reported (e.g. via JMX) as <code>-1</code> to make clear that it is not
used.</p>
</attribute>
<attribute name="packetSize" required="false">
<p>This attribute sets the maximum AJP packet size in Bytes. The maximum
value is 65536. It should be the same as the <code>max_packet_size</code>
directive configured for mod_jk. Normally it is not necessary to change
the maximum packet size. Problems with the default value have been
reported when sending certificates or certificate chains. The default
value is 8192. If set to less than 8192 then the setting will ignored and
the default value of 8192 used.</p>
</attribute>
<attribute name="processorCache" required="false">
<p>The protocol handler caches Processor objects to speed up performance.
This setting dictates how many of these objects get cached.
<code>-1</code> means unlimited, default is <code>200</code>. If not using
Servlet 3.0 asynchronous processing, a good default is to use the same as
the maxThreads setting. If using Servlet 3.0 asynchronous processing, a
good default is to use the larger of maxThreads and the maximum number of
expected concurrent requests (synchronous and asynchronous).</p>
</attribute>
<attribute name="secret" required="false">
<p>Only requests from workers with this secret keyword will be accepted.
The default value is <code>null</code>. This attrbute must be specified
with a non-null, non-zero length value unless
<strong>secretRequired</strong> is explicitly configured to be
<code>false</code>.</p>
</attribute>
<attribute name="secretRequired" required="false">
<p>If this attribute is <code>true</code>, the AJP Connector will only
start if the <strong>secret</strong> attribute is configured with a
non-null, non-zero length value. The default value is <code>true</code>.
This attributue should only be set to <code>false</code> when the
Connector is used on a trusted network.</p>
</attribute>
<attribute name="tcpNoDelay" required="false">
<p>If set to <code>true</code>, the TCP_NO_DELAY option will be
set on the server socket, which improves performance under most
circumstances. This is set to <code>true</code> by default.</p>
</attribute>
<attribute name="threadPriority" required="false">
<p>The priority of the request processing threads within the JVM.
The default value is <code>5</code> (the value of the
<code>java.lang.Thread.NORM_PRIORITY</code> constant). See the JavaDoc
for the <code>java.lang.Thread</code> class for more details on what
this priority means.If an executor is associated
with this connector, this attribute is ignored as the connector will
execute tasks using the executor rather than an internal thread pool. Note
that if an executor is configured any value set for this attribute will be
recorded correctly but it will be reported (e.g. via JMX) as
<code>-1</code> to make clear that it is not used.</p>
</attribute>
<attribute name="tomcatAuthentication" required="false">
<p>If set to <code>true</code>, the authentication will be done in Tomcat.
Otherwise, the authenticated principal will be propagated from the native
webserver and used for authorization in Tomcat. Note that this principal
will have no roles associated with it.
The default value is <code>true</code>. If
<code>tomcatAuthorization</code> is set to <code>true</code> this
attribute has no effect.</p>
</attribute>
<attribute name="tomcatAuthorization" required="false">
<p>If set to <code>true</code>, the authenticated principal will be
propagated from the native webserver and considered already authenticated
in Tomcat. If the web application has one or more security constraints,
authorization will then be performed by Tomcat and roles assigned to the
authenticated principal. If the appropriate Tomcat Realm for the request
does not recognise the provided user name, a Principal will be still be
created but it will have no roles. The default value is
<code>false</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Java TCP socket attributes">
<p>The NIO and NIO2 implementation support the following Java TCP socket
attributes in addition to the common Connector and HTTP attributes listed
above.</p>
<attributes>
<attribute name="socket.rxBufSize" required="false">
<p>(int)The socket receive buffer (SO_RCVBUF) size in bytes. JVM default
used if not set.</p>
</attribute>
<attribute name="socket.txBufSize" required="false">
<p>(int)The socket send buffer (SO_SNDBUF) size in bytes. JVM default
used if not set. Care should be taken if explicitly setting this value.
Very poor performance has been observed on some JVMs with values less
than ~8k.</p>
</attribute>
<attribute name="socket.tcpNoDelay" required="false">
<p>(bool)This is equivalent to standard attribute
<strong>tcpNoDelay</strong>.</p>
</attribute>
<attribute name="socket.soKeepAlive" required="false">
<p>(bool)Boolean value for the socket's keep alive setting
(SO_KEEPALIVE). JVM default used if not set.</p>
</attribute>
<attribute name="socket.ooBInline" required="false">
<p>(bool)Boolean value for the socket OOBINLINE setting. JVM default
used if not set.</p>
</attribute>
<attribute name="socket.soReuseAddress" required="false">
<p>(bool)Boolean value for the sockets reuse address option
(SO_REUSEADDR). JVM default used if not set.</p>
</attribute>
<attribute name="socket.soLingerOn" required="false">
<p>(bool)Boolean value for the sockets so linger option (SO_LINGER).
A value for the standard attribute <strong>connectionLinger</strong>
that is &gt;=0 is equivalent to setting this to <code>true</code>.
A value for the standard attribute <strong>connectionLinger</strong>
that is &lt;0 is equivalent to setting this to <code>false</code>.
Both this attribute and <code>soLingerTime</code> must be set else the
JVM defaults will be used for both.</p>
</attribute>
<attribute name="socket.soLingerTime" required="false">
<p>(int)Value in seconds for the sockets so linger option (SO_LINGER).
This is equivalent to standard attribute
<strong>connectionLinger</strong>.
Both this attribute and <code>soLingerOn</code> must be set else the
JVM defaults will be used for both.</p>
</attribute>
<attribute name="socket.soTimeout" required="false">
<p>This is equivalent to standard attribute
<strong>connectionTimeout</strong>.</p>
</attribute>
<attribute name="socket.performanceConnectionTime" required="false">
<p>(int)The first value for the performance settings. See
<a href="http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setPerformancePreferences(int,%20int,%20int)">Socket Performance Options</a>
All three performance attributes must be set else the JVM defaults will
be used for all three.</p>
</attribute>
<attribute name="socket.performanceLatency" required="false">
<p>(int)The second value for the performance settings. See
<a href="http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setPerformancePreferences(int,%20int,%20int)">Socket Performance Options</a>
All three performance attributes must be set else the JVM defaults will
be used for all three.</p>
</attribute>
<attribute name="socket.performanceBandwidth" required="false">
<p>(int)The third value for the performance settings. See
<a href="http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setPerformancePreferences(int,%20int,%20int)">Socket Performance Options</a>
All three performance attributes must be set else the JVM defaults will
be used for all three.</p>
</attribute>
<attribute name="socket.unlockTimeout" required="false">
<p>(int) The timeout for a socket unlock. When a connector is stopped, it will try to release the acceptor thread by opening a connector to itself.
The default value is <code>250</code> and the value is in milliseconds</p>
</attribute>
</attributes>
</subsection>
<subsection name="NIO specific configuration">
<p>The following attributes are specific to the NIO connector.</p>
<attributes>
<attribute name="socket.directBuffer" required="false">
<p>(bool)Boolean value, whether to use direct ByteBuffers or java mapped
ByteBuffers. Default is <code>false</code>.<br/>
When you are using direct buffers, make sure you allocate the
appropriate amount of memory for the direct memory space. On Sun's JDK
that would be something like <code>-XX:MaxDirectMemorySize=256m</code>.
</p>
</attribute>
<attribute name="socket.appReadBufSize" required="false">
<p>(int)Each connection that is opened up in Tomcat get associated with
a read ByteBuffer. This attribute controls the size of this buffer. By
default this read buffer is sized at <code>8192</code> bytes. For lower
concurrency, you can increase this to buffer more data. For an extreme
amount of keep alive connections, decrease this number or increase your
heap size.</p>
</attribute>
<attribute name="socket.appWriteBufSize" required="false">
<p>(int)Each connection that is opened up in Tomcat get associated with
a write ByteBuffer. This attribute controls the size of this buffer. By
default this write buffer is sized at <code>8192</code> bytes. For low
concurrency you can increase this to buffer more response data. For an
extreme amount of keep alive connections, decrease this number or
increase your heap size.<br/>
The default value here is pretty low, you should up it if you are not
dealing with tens of thousands concurrent connections.</p>
</attribute>
<attribute name="socket.bufferPool" required="false">
<p>(int)The NIO connector uses a class called NioChannel that holds
elements linked to a socket. To reduce garbage collection, the NIO
connector caches these channel objects. This value specifies the size of
this cache. The default value is <code>500</code>, and represents that
the cache will hold 500 NioChannel objects. Other values are
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
</attribute>
<attribute name="socket.bufferPoolSize" required="false">
<p>(int)The NioChannel pool can also be size based, not used object
based. The size is calculated as follows:<br/>
NioChannel
<code>buffer size = read buffer size + write buffer size</code><br/>
SecureNioChannel <code>buffer size = application read buffer size +
application write buffer size + network read buffer size +
network write buffer size</code><br/>
The value is in bytes, the default value is <code>1024*1024*100</code>
(100MB).</p>
</attribute>
<attribute name="socket.processorCache" required="false">
<p>(int)Tomcat will cache SocketProcessor objects to reduce garbage
collection. The integer value specifies how many objects to keep in the
cache at most. The default is <code>500</code>. Other values are
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
</attribute>
<attribute name="socket.keyCache" required="false">
<p>(int)Tomcat will cache KeyAttachment objects to reduce garbage
collection. The integer value specifies how many objects to keep in the
cache at most. The default is <code>500</code>. Other values are
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
</attribute>
<attribute name="socket.eventCache" required="false">
<p>(int)Tomcat will cache PollerEvent objects to reduce garbage
collection. The integer value specifies how many objects to keep in the
cache at most. The default is <code>500</code>. Other values are
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
</attribute>
<attribute name="selectorPool.maxSelectors" required="false">
<p>(int)The max selectors to be used in the pool, to reduce selector
contention. Use this option when the command line
<code>org.apache.tomcat.util.net.NioSelectorShared</code> value is set
to false. Default value is <code>200</code>.</p>
</attribute>
<attribute name="selectorPool.maxSpareSelectors" required="false">
<p>(int)The max spare selectors to be used in the pool, to reduce
selector contention. When a selector is returned to the pool, the system
can decide to keep it or let it be GC'd. Use this option when the
command line <code>org.apache.tomcat.util.net.NioSelectorShared</code>
value is set to false. Default value is <code>-1</code> (unlimited).</p>
</attribute>
<attribute name="command-line-options" required="false">
<p>The following command line options are available for the NIO
connector:<br/>
<code>-Dorg.apache.tomcat.util.net.NioSelectorShared=true|false</code>
- default is <code>true</code>. Set this value to <code>false</code> if you wish to
use a selector for each thread. When you set it to <code>false</code>, you can
control the size of the pool of selectors by using the
<strong>selectorPool.maxSelectors</strong> attribute.</p>
</attribute>
</attributes>
</subsection>
<subsection name="NIO2 specific configuration">
<p>The following attributes are specific to the NIO2 connector.</p>
<attributes>
<attribute name="useCaches" required="false">
<p>(bool)Use this attribute to enable or disable object caching to
reduce the amount of GC objects produced.
The default value is <code>false</code>.</p>
</attribute>
<attribute name="socket.directBuffer" required="false">
<p>(bool)Boolean value, whether to use direct ByteBuffers or java mapped
ByteBuffers. Default is <code>false</code>.<br/>
When you are using direct buffers, make sure you allocate the
appropriate amount of memory for the direct memory space. On Sun's JDK
that would be something like <code>-XX:MaxDirectMemorySize=256m</code>.
</p>
</attribute>
<attribute name="socket.appReadBufSize" required="false">
<p>(int)Each connection that is opened up in Tomcat get associated with
a read ByteBuffer. This attribute controls the size of this buffer. By
default this read buffer is sized at <code>8192</code> bytes. For lower
concurrency, you can increase this to buffer more data. For an extreme
amount of keep alive connections, decrease this number or increase your
heap size.</p>
</attribute>
<attribute name="socket.appWriteBufSize" required="false">
<p>(int)Each connection that is opened up in Tomcat get associated with
a write ByteBuffer. This attribute controls the size of this buffer. By
default this write buffer is sized at <code>8192</code> bytes. For low
concurrency you can increase this to buffer more response data. For an
extreme amount of keep alive connections, decrease this number or
increase your heap size.<br/>
The default value here is pretty low, you should up it if you are not
dealing with tens of thousands concurrent connections.</p>
</attribute>
<attribute name="socket.bufferPoolSize" required="false">
<p>(int)The NIO2 connector uses a class called Nio2Channel that holds
elements linked to a socket. To reduce garbage collection, the NIO
connector caches these channel objects. This value specifies the size of
this cache. The default value is <code>500</code>, and represents that
the cache will hold 500 Nio2Channel objects. Other values are
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
</attribute>
<attribute name="socket.processorCache" required="false">
<p>(int)Tomcat will cache SocketProcessor objects to reduce garbage
collection. The integer value specifies how many objects to keep in the
cache at most. The default is <code>500</code>. Other values are
<code>-1</code> for unlimited cache and <code>0</code> for no cache.</p>
</attribute>
</attributes>
</subsection>
<subsection name="APR/native specific configuration">
<p>The APR/native implementation supports the following attributes in
addition to the common Connector and AJP attributes listed above.</p>
<attributes>
<attribute name="pollTime" required="false">
<p>Duration of a poll call in microseconds. Lowering this value will
slightly decrease latency of connections being kept alive in some cases
, but will use more CPU as more poll calls are being made. The default
value is 2000 (2ms).
</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>None at this time.</p>
</section>
<section name="Special Features">
<subsection name="Proxy Support">
<p>The <code>proxyName</code> and <code>proxyPort</code> attributes can
be used when Tomcat is run behind a proxy server. These attributes
modify the values returned to web applications that call the
<code>request.getServerName()</code> and <code>request.getServerPort()</code>
methods, which are often used to construct absolute URLs for redirects.
Without configuring these attributes, the values returned would reflect
the server name and port on which the connection from the proxy server
was received, rather than the server name and port to whom the client
directed the original request.</p>
<p>For more information, see the
<a href="../proxy-howto.html">Proxy Support How-To</a>.</p>
</subsection>
<subsection name="Connector Comparison">
<p>Below is a small chart that shows how the connectors differ.</p>
<table class="defaultTable" style="text-align: center;">
<tr>
<th />
<th style="text-align: center;">Java Nio Connector<br />NIO</th>
<th style="text-align: center;">Java Nio2 Connector<br />NIO2</th>
<th style="text-align: center;">APR/native Connector<br />APR</th>
</tr>
<tr>
<th>Classname</th>
<td><code class="noHighlight">AjpNioProtocol</code></td>
<td><code class="noHighlight">AjpNio2Protocol</code></td>
<td><code class="noHighlight">AjpAprProtocol</code></td>
</tr>
<tr>
<th>Tomcat Version</th>
<td>7.x onwards</td>
<td>8.x onwards</td>
<td>5.5.x onwards</td>
</tr>
<tr>
<th>Support Polling</th>
<td>YES</td>
<td>YES</td>
<td>YES</td>
</tr>
<tr>
<th>Polling Size</th>
<td><code class="noHighlight">maxConnections</code></td>
<td><code class="noHighlight">maxConnections</code></td>
<td><code class="noHighlight">maxConnections</code></td>
</tr>
<tr>
<th>Read Request Headers</th>
<td>Blocking</td>
<td>Blocking</td>
<td>Blocking</td>
</tr>
<tr>
<th>Read Request Body</th>
<td>Blocking</td>
<td>Blocking</td>
<td>Blocking</td>
</tr>
<tr>
<th>Write Response Headers and Body</th>
<td>Blocking</td>
<td>Blocking</td>
<td>Blocking</td>
</tr>
<tr>
<th>Wait for next Request</th>
<td>Non Blocking</td>
<td>Non Blocking</td>
<td>Non Blocking</td>
</tr>
<tr>
<th>Max Connections</th>
<td><code class="noHighlight">maxConnections</code></td>
<td><code class="noHighlight">maxConnections</code></td>
<td><code class="noHighlight">maxConnections</code></td>
</tr>
</table>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,548 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="automatic-deployment.html">
&project;
<properties>
<title>Automatic Deployment - Use cases</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>This page defines the expected behaviour of the automatic deployer in many
typical use cases. This is a complex area of Tomcat&apos;s functionality.
While any difference between this document and Tomcat&apos;s behaviour is a
bug, the fix may be to change this document, Tomcat&apos;s behaviour or
both.</p>
</section>
<section name="Key">
<table class="detail-table">
<tr>
<th>Term</th><th>Description</th>
</tr>
<tr>
<td>XML</td>
<td>An XML configuration file located in the Host&apos;s
<em>configBase</em>. It must contain a single &lt;Context&gt; element
and may contain optional nested elements. It does not define an
explicit <em>docBase</em> attribute. It represents a single web
application. It is often referred to as a context.xml file.</td>
</tr><tr>
<td>XML+EW</td>
<td>An XML configuration file located in the Host&apos;s
<em>configBase</em>. It must contain a single &lt;Context&gt; element
and may contain optional nested elements. It includes an explicit
<em>docBase</em> attribute that points to an external WAR. It
represents a single web application. It is often referred to as a
context.xml file.</td>
</tr><tr>
<td>XML+ED</td>
<td>An XML configuration file located in the Host&apos;s
<em>configBase</em>. It must contain a single &lt;Context&gt; element
and may contain optional nested elements. It includes an explicit
<em>docBase</em> attribute that points to an external directory. It
represents a single web application. It is often referred to as a
context.xml file.</td>
</tr><tr>
<td>WAR</td>
<td>A WAR file located in the Host&apos;s <em>appBase</em>. The WAR does
not include an embedded context.xml file.</td>
</tr><tr>
<td>WAR+XML</td>
<td>A WAR file located in the Host&apos;s <em>appBase</em>. The WAR does
include an embedded context.xml file.</td>
</tr><tr>
<td>DIR</td>
<td>A directory located in the Host&apos;s <em>appBase</em>. The directory
does not include an embedded context.xml file.</td>
</tr><tr>
<td>DIR+XML</td>
<td>A directory located in the Host&apos;s <em>appBase</em>. The directory
does include an embedded context.xml file.</td>
</tr><tr>
<td>redeploy</td>
<td>The Context object that represents the web application is destroyed
and a new Context object is created. If present and permitted by the
configuration, this new Context object is created by parsing the
context.xml file. The web.xml file is parsed during the application
start process. Any sessions stored in the standard Manager in the
default configuration will not be persisted. Any requests to the web
application during the redeploy will be handled as if the web
application is not deployed.</td>
</tr><tr>
<td>reload</td>
<td>The Context object that represents the web application is stopped and
then started. The web.xml file is parsed during the application start
process. Any sessions stored in the standard Manager in the default
configuration will not be persisted. Any requests to the web
application during the reload will be held until the reload completes
at which point they will continue using the reloaded web application.
</td>
</tr>
</table>
</section>
<section name="New files">
<p>This section describes Tomcat&apos;s behaviour when the automatic
deployment process discovers a new web application.</p>
<table class="detail-table">
<tr>
<th rowspan="2">Starting artifact(s)</th>
<th colspan="3">Configuration Settings</th>
<th colspan="4">Result</th>
</tr>
<tr>
<th>deployXML</th><th>copyXML</th><th>unpackWARs</th>
<th>XML</th><th>WAR</th><th>DIR</th><th>Notes</th>
</tr>
<tr>
<td>XML</td>
<td>either</td><td>either</td><td>either</td>
<td>Y</td><td>N</td><td>N</td><td>1, 2, 3</td>
</tr>
<tr>
<td>XML+EW</td>
<td>either</td><td>either</td><td>false</td>
<td>Y</td><td>N</td><td>N</td><td>1</td>
</tr>
<tr>
<td>XML+EW</td>
<td>either</td><td>either</td><td>true</td>
<td>Y</td><td>N</td><td>Y</td><td>1</td>
</tr>
<tr>
<td>XML+ED</td>
<td>either</td><td>either</td><td>either</td>
<td>Y</td><td>N</td><td>N</td><td>1, 2</td>
</tr>
<tr>
<td>WAR+XML</td>
<td>false</td><td>either</td><td>false</td>
<td>N</td><td>Y</td><td>N</td><td>4</td>
</tr>
<tr>
<td>WAR+XML</td>
<td>false</td><td>either</td><td>true</td>
<td>N</td><td>Y</td><td>Y</td><td>4</td>
</tr>
<tr>
<td>WAR+XML</td>
<td>true</td><td>false</td><td>false</td>
<td>N</td><td>Y</td><td>N</td><td></td>
</tr>
<tr>
<td>WAR+XML</td>
<td>true</td><td>false</td><td>true</td>
<td>N</td><td>Y</td><td>Y</td><td></td>
</tr>
<tr>
<td>WAR+XML</td>
<td>true</td><td>true</td><td>false</td>
<td>Y</td><td>Y</td><td>N</td><td></td>
</tr>
<tr>
<td>WAR+XML</td>
<td>true</td><td>true</td><td>true</td>
<td>Y</td><td>Y</td><td>Y</td><td></td>
</tr>
<tr>
<td>WAR</td>
<td>either</td><td>either</td><td>false</td>
<td>N</td><td>Y</td><td>N</td><td></td>
</tr>
<tr>
<td>WAR</td>
<td>either</td><td>either</td><td>true</td>
<td>N</td><td>Y</td><td>Y</td><td></td>
</tr>
<tr>
<td>DIR+XML</td>
<td>false</td><td>either</td><td>either</td>
<td>N</td><td>N</td><td>Y</td><td>4</td>
</tr>
<tr>
<td>DIR+XML</td>
<td>true</td><td>false</td><td>either</td>
<td>N</td><td>N</td><td>Y</td><td></td>
</tr>
<tr>
<td>DIR+XML</td>
<td>true</td><td>true</td><td>either</td>
<td>Y</td><td>N</td><td>Y</td><td></td>
</tr>
<tr>
<td>DIR</td>
<td>false</td><td>either</td><td>either</td>
<td>N</td><td>N</td><td>Y</td><td></td>
</tr>
</table>
</section>
<section name="Deleted files">
<p>This section describes Tomcat&apos;s behaviour when the automatic
deployment process detects that a web application file has been deleted.</p>
<p>When a file is deleted or modified any redeploy resources that are listed
after the modified/deleted resource are themselves deleted (and possibly
re-created). The order of redeploy resources is:</p>
<ol>
<li>WAR</li>
<li>DIR</li>
<li>XML</li>
<li>global resources</li>
</ol>
<p>There are some exceptions to the deletion rule above:</p>
<ul>
<li>global resources are never deleted</li>
<li>external resources are never deleted</li>
<li>if the WAR or DIR has been modified then the XML file is only deleted if
<em>copyXML</em> is <code>true</code> and <em>deployXML</em> is
<code>true</code></li>
</ul>
<p>In the following table:</p>
<ul>
<li>'-' means "unchanged from not present". i.e. the artifact wasn't present
before the change and isn't present after it either. '-' rather than 'N'
is used to focus attention on what changes.</li>
<li>'R' means that the directory is re-created by expanding the WAR file.
This will only happen if <em>unpackWARs</em> is <code>true</code>.</li>
<li>'XW' means that the if the WAR contains a META-INF/context.xml file it
will be extracted and placed in the Host&apos;s <em>configBase</em>.
This only happens if <em>copyXML</em> is <code>true</code> and
<em>deployXML</em> is <code>true</code>.</li>
<li>'XD' means that the if the directory contains a META-INF/context.xml
file it will be copied to the Host&apos;s <em>configBase</em>. This only
happens if <em>copyXML</em> is <code>true</code> and <em>deployXML</em>
is <code>true</code>.</li>
</ul>
<table class="detail-table">
<tr>
<th colspan="3">Artifacts present</th>
<th rowspan="2">Artifact removed</th>
<th colspan="4">Artifacts remaining</th>
</tr>
<tr>
<th>XML</th><th>WAR</th><th>DIR</th>
<th>XML</th><th>WAR</th><th>DIR</th><th>Notes</th>
</tr>
<tr>
<td>N</td><td>N</td><td>Y</td>
<td>DIR</td>
<td>-</td><td>-</td><td>N</td><td></td>
</tr>
<tr>
<td>N</td><td>Y</td><td>N</td>
<td>WAR</td>
<td>-</td><td>N</td><td>-</td><td></td>
</tr>
<tr>
<td>N</td><td>Y</td><td>Y</td>
<td>DIR</td>
<td>-</td><td>Y</td><td>R</td><td></td>
</tr>
<tr>
<td>N</td><td>Y</td><td>Y</td>
<td>WAR</td>
<td>-</td><td>N</td><td>N</td><td></td>
</tr>
<tr>
<td>Y</td><td>N</td><td>N</td>
<td>XML</td>
<td>N</td><td>-</td><td>-</td><td></td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y</td>
<td>DIR</td>
<td>N</td><td>-</td><td>N</td><td>5</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y</td>
<td>XML</td>
<td>XD</td><td>-</td><td>Y</td><td></td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>N</td>
<td>WAR</td>
<td>N</td><td>N</td><td>-</td><td>5</td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>N</td>
<td>XML</td>
<td>XW</td><td>Y</td><td>-</td><td></td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>Y</td>
<td>DIR</td>
<td>XW</td><td>Y</td><td>R</td><td></td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>Y</td>
<td>WAR</td>
<td>N</td><td>N</td><td>N</td><td></td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>Y</td>
<td>XML</td>
<td>XW</td><td>Y</td><td>Y</td><td></td>
</tr>
<tr>
<td>Y</td><td>Y (external)</td><td>N</td>
<td>WAR</td>
<td>Y</td><td>N</td><td>-</td><td>3</td>
</tr>
<tr>
<td>Y</td><td>Y (external)</td><td>N</td>
<td>XML</td>
<td>N</td><td>Y (external)</td><td>-</td><td>6</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y (external)</td>
<td>DIR</td>
<td>Y</td><td>-</td><td>N</td><td>3</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y (external)</td>
<td>XML</td>
<td>N</td><td>-</td><td>Y (external)</td><td>6</td>
</tr>
<tr>
<td>Y</td><td>Y (external)</td><td>Y</td>
<td>DIR</td>
<td>Y</td><td>Y (external)</td><td>R</td><td></td>
</tr>
<tr>
<td>Y</td><td>Y (external)</td><td>Y</td>
<td>WAR</td>
<td>Y</td><td>N</td><td>N</td><td>3</td>
</tr>
<tr>
<td>Y</td><td>Y (external)</td><td>Y</td>
<td>XML</td>
<td>N</td><td>Y (external)</td><td>N</td><td>6</td>
</tr>
</table>
</section>
<section name="Modified files">
<p>This section describes Tomcat&apos;s behaviour when the automatic
deployment process detects that a web application file has been modified.</p>
<p>In the following table:</p>
<ul>
<li>'-' means "unchanged from not present". i.e. the artifact wasn't present
before the change and isn't present after it either. '-' rather than 'N'
is used to focus attention on what changes.</li>
<li>'M' means that the artifact has been modified.</li>
<li>'R' means that the directory is deleted and re-created by expanding the
WAR file. This will only happen if <em>unpackWARs</em> is
<code>true</code>.</li>
</ul>
<table class="detail-table">
<tr>
<th colspan="3">Artifacts present</th>
<th rowspan="2">Artifact modified</th>
<th colspan="4">Artifacts remaining</th>
</tr>
<tr>
<th>XML</th><th>WAR</th><th>DIR</th>
<th>XML</th><th>WAR</th><th>DIR</th><th>Action</th>
</tr>
<tr>
<td>N</td><td>N</td><td>Y</td>
<td>DIR</td>
<td>-</td><td>-</td><td>M</td><td>None</td>
</tr>
<tr>
<td>N</td><td>Y</td><td>N</td>
<td>WAR</td>
<td>-</td><td>M</td><td>-</td><td>Redeploy</td>
</tr>
<tr>
<td>N</td><td>Y</td><td>Y</td>
<td>DIR</td>
<td>-</td><td>Y</td><td>M</td><td>None</td>
</tr>
<tr>
<td>N</td><td>Y</td><td>Y</td>
<td>WAR</td>
<td>-</td><td>M</td><td>R</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>N</td>
<td>XML</td>
<td>M</td><td>-</td><td>-</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y</td>
<td>DIR</td>
<td>Y</td><td>-</td><td>M</td><td>None</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y</td>
<td>XML</td>
<td>M</td><td>-</td><td>Y</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>N</td>
<td>WAR</td>
<td>Y</td><td>M</td><td>-</td><td>Reload</td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>N</td>
<td>XML</td>
<td>M</td><td>Y</td><td>-</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>Y</td>
<td>DIR</td>
<td>Y</td><td>Y</td><td>M</td><td>None</td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>Y</td>
<td>WAR</td>
<td>Y</td><td>M</td><td>R</td><td>Reload</td>
</tr>
<tr>
<td>Y</td><td>Y</td><td>Y</td>
<td>XML</td>
<td>M</td><td>Y</td><td>Y</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>Y(external)</td><td>N</td>
<td>WAR</td>
<td>Y</td><td>M(external)</td><td>-</td><td>Reload</td>
</tr>
<tr>
<td>Y</td><td>Y(external)</td><td>N</td>
<td>XML</td>
<td>M</td><td>Y(external)</td><td>-</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y(external)</td>
<td>DIR</td>
<td>Y</td><td>-</td><td>M(external)</td><td>None</td>
</tr>
<tr>
<td>Y</td><td>N</td><td>Y(external)</td>
<td>XML</td>
<td>M</td><td>-</td><td>Y(external)</td><td>Redeploy</td>
</tr>
<tr>
<td>Y</td><td>Y(external)</td><td>Y</td>
<td>DIR</td>
<td>Y</td><td>Y(external)</td><td>M</td><td>None</td>
</tr>
<tr>
<td>Y</td><td>Y(external)</td><td>Y</td>
<td>WAR</td>
<td>Y</td><td>M(external)</td><td>R</td><td>Reload</td>
</tr>
<tr>
<td>Y</td><td>Y(external)</td><td>Y</td>
<td>XML</td>
<td>M</td><td>Y(external)</td><td>Y</td><td>Redeploy</td>
</tr>
</table>
</section>
<section name="Added files">
<p>This is treated as if the added file has been modified with the following
additional actions:</p>
<ul>
<li>If a WAR is added, any DIR is removed and may be recreated depending on
<em>unpackWARs</em>.</li>
<li>If an XML file is added that refers to an external <em>docBase</em> any
WAR or DIR in the appBase will be removed. The DIR may be recreated if
the external resource is a WAR and <em>unpackWARs</em> is true.</li>
<li>If a DIR is added when a WAR already exists and <em>unpackWARs</em> is
<code>false</code>, the DIR will be ignored but a warning will be
logged when the DIR is first detected. If the WAR is removed, the DIR
will be left and may be deployed via automatic deployment.</li>
<li>If a WAR is added to the <em>appBase</em> when an external WAR already
exists, the WAR in the <em>appBase</em> will be ignored but a warning
will be logged when the WAR in the <em>appBase</em> is first detected.
If the external WAR is removed, the WAR in the <em>appBase</em> will be
left and may be deployed via automatic deployment.</li>
<li>If an XML file is added to the META-INF directory of an application
deployed from that DIR, the application will always be redeployed. The
result will be the same as for a new deployment.</li>
</ul>
</section>
<section name="Notes">
<ol>
<li><em>deployXML</em> and <em>copyXML</em> are ignored since an XML file
was discovered in the <em>configBase</em>.</li>
<li><em>unpackWARs</em> is ignored since there is no WAR file.</li>
<li>The context will fail to start because there is no content in the
expected <em>docBase</em>.</li>
<li>The web application fails to deploy because it contains an embedded
META-INF/context.xml, <em>deployXML</em> is <code>false</code> and an
XML has not been provided in the <em>configBase</em>.</li>
<li>The XML file is only deleted if <em>copyXML</em> is <code>true</code>
and <em>deployXML</em> is <code>true</code>.</li>
<li>Although the external resource is still present, the web application is
fully undeployed as Tomcat has no knowledge of the external resource.
</li>
</ol>
</section>
</body>
</document>

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

@@ -0,0 +1,146 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-channel.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Channel object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
The cluster channel is the main component of a small framework we've nicknamed Apache Tribes.<br/>
The channel manages a set of sub components and together they create a group communication framework.<br/>
This framework is then used internally by the components that need to send messages between different Tomcat instances.
<br/>
A few examples of these components would be the SimpleTcpCluster that does the messaging for the DeltaManager,
or the BackupManager that uses a different replication strategy. The ReplicatedContext object does also
use the channel object to communicate context attribute changes.
</section>
<section name="Nested Components">
<p><b><a href="cluster-membership.html">Channel/Membership</a>:</b> <br/>
The Membership component is responsible for auto discovering new nodes in the cluster
and also to provide for notifications for any nodes that have not responded with a heartbeat.
The default implementation uses multicast.<br/>
In the membership component you configure how your nodes, aka. members, are to be discovered and/or
divided up.
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-sender.html">Channel/Sender</a>:</b> <br/>
The Sender component manages all outbound connections and data messages that are sent
over the network from one node to another.
This component allows messages to be sent in parallel.
The default implementation uses TCP client sockets, and socket tuning for outgoing messages are
configured here.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-sender.html#transport">Channel/Sender/Transport</a>:</b> <br/>
The Transport component is the bottom IO layer for the sender component.
The default implementation uses non-blocking TCP client sockets.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-receiver.html">Channel/Receiver</a>:</b> <br/>
The receiver component listens for messages from other nodes.
Here you will configure the cluster thread pool, as it will dispatch incoming
messages to a thread pool for faster processing.
The default implementation uses non-blocking TCP server sockets.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-interceptor.html">Channel/Interceptor</a>:</b> <br/>
The channel will send messages through an interceptor stack. Because of this, you have the ability to
customize the way messages are sent and received, and even how membership is handled.<br/>
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
The default value here is <code>org.apache.catalina.tribes.group.GroupChannel</code> and is
currently the only implementation available.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.GroupChannel Attributes">
<attributes>
<attribute name="heartbeat" required="false">
Flag whether the channel manages its own heartbeat.
If set to true, the channel start a local thread for the heart beat.
If set this flag to false, you must set SimpleTcpCluster#heartbeatBackgroundEnabled
to true. default value is true.
</attribute>
<attribute name="heartbeatSleeptime" required="false">
If heartbeat == true, specifies the interval of heartbeat thread in milliseconds.
The default is 5000 (5 seconds).
</attribute>
<attribute name="optionCheck" required="false">
If set to true, the GroupChannel will check the option flags that each
interceptor is using. Reports an error if two interceptor share the same
flag. The default is false.
</attribute>
<attribute name="jmxEnabled" required="false">
Flag whether the channel components register with JMX or not.
The default value is true.
</attribute>
<attribute name="jmxDomain" required="false">
if <code>jmxEnabled</code> set to true, specifies the jmx domain which
this channel should be registered. The ClusterChannel is used as the
default value.
</attribute>
<attribute name="jmxPrefix" required="false">
if <code>jmxEnabled</code> set to true, specifies the jmx prefix which
will be used with channel ObjectName.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,105 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-deployer.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Deployer object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The Farm War Deployer can deploy and undeploy web applications on the other
nodes in the cluster.</p>
<p><strong>Note:</strong> FarmWarDeployer can be configured at host level
cluster only.
</p>
</section>
<section name="org.apache.catalina.ha.deploy.FarmWarDeployer">
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
The cluster deployer class, currently only one is available,
<code>org.apache.catalina.ha.deploy.FarmWarDeployer.</code>
</attribute>
<attribute name="deployDir" required="true">
Deployment directory. This is the pathname of a directory where deploy
the web applications. You may specify an absolute pathname, or a
pathname that is relative to the $CATALINA_BASE directory. In the
current implementation, this attribute must be the same value as the
<strong>Host's appBase</strong>.
</attribute>
<attribute name="tempDir" required="true">
The temporaryDirectory to store binary data when downloading a war from
the cluster. You may specify an absolute pathname, or a pathname that is
relative to the $CATALINA_BASE directory.
</attribute>
<attribute name="watchDir" required="false">
This is the pathname of a directory where watch for changes(add/modify/remove)
of web applications. You may specify an absolute pathname, or a pathname
that is relative to the $CATALINA_BASE directory.
<strong>Note: </strong> if <strong>watchEnabled</strong> is false, this
attribute will have no effect.
</attribute>
<attribute name="watchEnabled" required="false">
Set to true if you want to watch for changes of web applications.
Only when this attribute set to true, you can trigger a deploy/undeploy
of web applications. The flag's value defaults to false.
</attribute>
<attribute name="processDeployFrequency" required="false">
Frequency of the Farm watchDir check. Cluster wide deployment will be
done once for the specified amount of backgroundProcess calls (ie, the
lower the amount, the most often the checks will occur). The minimum
value is 1, and the default value is 2.
<strong>Note: </strong> if <strong>watchEnabled</strong> is false, this
attribute will have no effect.
</attribute>
<attribute name="maxValidTime" required="false">
The maximum valid time(in seconds) of FileMessageFactory.
FileMessageFactory will be removed immediately after receiving the
complete WAR file but when failing to receive a FileMessage which was
sent dividing, FileMessageFactory will leak without being removed.
FileMessageFactory that is leaking will be automatically removed after
maxValidTime. If a negative value specified, FileMessageFactory will
never be removed. If the attribute is not provided, a default of 300
seconds (5 minutes) is used.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,320 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-interceptor.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Channel Interceptor object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Apache Tribes supports an interceptor architecture to intercept both messages and membership notifications.
This architecture allows decoupling of logic and opens the way for some very useful feature add ons.
</p>
</section>
<section name="Available Interceptors">
<ul>
<li><code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.NonBlockingCoordinator</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.OrderInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.SimpleCoordinator</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.TwoPhaseCommitInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.GzipInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor</code></li>
<li><code>org.apache.catalina.tribes.group.interceptors.EncryptInterceptor</code></li>
</ul>
</section>
<section name="Static Membership">
<p>
In addition to dynamic discovery, Apache Tribes also supports static membership, with membership verification.
To achieve this add the <code>org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor</code>
after the <code>org.apache.catalina.tribes.group.interceptors.TcpFailureDetector</code> interceptor.
Inside the <code>StaticMembershipInterceptor</code> you can add the static members you wish to have.
The <code>TcpFailureDetector</code> will do a health check on the static members,and also monitor them for crashes
so they will have the same level of notification mechanism as the members that are automatically discovered.</p>
<source><![CDATA[ <Interceptor className="org.apache.catalina.tribes.group.interceptors.StaticMembershipInterceptor">
<LocalMember className="org.apache.catalina.tribes.membership.StaticMember"
domain="staging-cluster"
uniqueId="{1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,1}"/>
<Member className="org.apache.catalina.tribes.membership.StaticMember"
port="5678"
securePort="-1"
host="tomcat01.mydomain.com"
domain="staging-cluster"
uniqueId="{0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}"/>
</Interceptor>]]></source>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
Required, as there is no default
</attribute>
<attribute name="optionFlag" required="false">
If you want the interceptor to trigger on certain message depending on the message's option flag,
you can setup the interceptors flag here.
The default value is <code>0</code>, meaning this interceptor will trigger on all messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.DomainFilterInterceptor Attributes">
<attributes>
<attribute name="domain" required="true">
The logical cluster domain that this Interceptor accepts.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.<br/>
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="logInterval" required="false">
This value indicates the interval for logging for messages from different domains.
The default is 100, which means that to log per 100 messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.FragmentationInterceptor Attributes">
<attributes>
<attribute name="expire" required="false">
How long do we keep the fragments in memory and wait for the rest to arrive.
The default is 60000 ms.
</attribute>
<attribute name="maxSize" required="false">
The maximum message size in bytes. If the message size exceeds this value, this interceptor fragments the message and sends them.
If it is less than this value, this interceptor does not fragment the message and sent in as one message. The default is 1024*100.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.MessageDispatchInterceptor Attributes">
<attributes>
<attribute name="optionFlag" required="false">
The default and hard coded value is <code>8 (org.apache.catalina.tribes.Channel.SEND_OPTIONS_ASYNCHRONOUS)</code>.
The dispatcher will trigger on this value only, as it is predefined by Tribes.
</attribute>
<attribute name="alwaysSend" required="false">
What behavior should be executed when the dispatch queue is full. If <code>true</code> (default), then the message is
is sent synchronously, if <code>false</code> an error is thrown.
</attribute>
<attribute name="maxQueueSize" required="false">
Size in bytes of the dispatch queue, the default value is <code> 1024*1024*64 (64MB)</code> sets the maximum queue size for the dispatch queue
if the queue fills up, one can trigger the behavior, if <code>alwaysSend</code> is set to true, the message will be sent synchronously
if the flag is false, an error is thrown
</attribute>
<attribute name="maxThreads" required="false">
The maximum number of threads in this pool, default is 10.
</attribute>
<attribute name="maxSpareThreads" required="false">
The number of threads to keep in the pool, default is 2.
</attribute>
<attribute name="keepAliveTime" required="false">
Maximum number of milliseconds of until Idle thread terminates. Default value is 5000(5 seconds).
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.TcpFailureDetector Attributes">
<attributes>
<attribute name="connectTimeout" required="false">
Specifies the timeout, in milliseconds, to use when attempting a TCP connection
to the suspect node. Default is 1000.
</attribute>
<attribute name="performSendTest" required="false">
If true is set, send a test message to the suspect node. Default is true.
</attribute>
<attribute name="performReadTest" required="false">
If true is set, read the response of the test message that sent. Default is false.
<strong>Note:</strong> if <code>performSendTest</code> is false, this attribute will have no effect.
</attribute>
<attribute name="readTestTimeout" required="false">
Specifies the timeout, in milliseconds, to use when performing a read test
to the suspicious node. Default is 5000.
</attribute>
<attribute name="removeSuspectsTimeout" required="false">
The maximum time(in seconds) for remove from removeSuspects. Member of
removeSuspects will be automatically removed after removeSuspectsTimeout.
If a negative value specified, the removeSuspects members never be
removed until disappeared really. If the attribute is not provided,
a default of 300 seconds (5 minutes) is used.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.TcpPingInterceptor Attributes">
<attributes>
<attribute name="interval" required="false">
If useThread == true, defines the interval of sending a ping message.
default is 1000 ms.
</attribute>
<attribute name="useThread" required="false">
Flag of whether to start a thread for sending a ping message.
If set to true, this interceptor will start a local thread for sending a ping message.
if set to false, channel heartbeat will send a ping message.
default is false.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.ThroughputInterceptor Attributes">
<attributes>
<attribute name="interval" required="false">
Defines the interval in number of messages when we are to report the throughput statistics.
The report is logged to the <code>org.apache.juli.logging.LogFactory.getLog(ThroughputInterceptor.class)</code>
logger under the <code>INFO</code> level.
Default value is to report every <code>10000</code> messages.
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.tribes.group.interceptors.EncryptInterceptor Attributes">
<p>
The EncryptInterceptor adds encryption to the channel messages carrying
session data between nodes. Added in Tomcat 9.0.13.
</p>
<p>
If using the <code>TcpFailureDetector</code>, the <code>EncryptInterceptor</code>
<i>must</i> be inserted into the interceptor chain <i>before</i> the
<code>TcpFailureDetector</code>. This is because when validating cluster
members, <code>TcpFailureDetector</code> writes channel data directly
to the other members without using the remainder of the interceptor chain,
but on the receiving side, the message still goes through the chain (in reverse).
Because of this asymmetry, the <code>EncryptInterceptor</code> must execute
<i>before</i> the <code>TcpFailureDetector</code> on the sender and <i>after</i>
it on the receiver, otherwise message corruption will occur.
</p>
<attributes>
<attribute name="encryptionAlgorithm" required="false">
The encryption algorithm to be used, including the mode and padding. Please see
<a href="https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html">https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html</a>
for the standard JCA names that can be used.
EncryptInterceptor currently supports the following
<a href="https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation">block-cipher modes</a>:
CBC, OFB, CFB, and GCM.
The length of the key will specify the flavor of the encryption algorithm
to be used, if applicable (e.g. AES-128 versus AES-256).
The default algorithm is <code>AES/CBC/PKCS5Padding</code>.
</attribute>
<attribute name="encryptionKey" required="true">
The key to be used with the encryption algorithm.
The key should be specified as hex-encoded bytes of the appropriate
length for the algorithm (e.g. 16 bytes / 32 characters / 128 bits for
AES-128, 32 bytes / 64 characters / 256 bits for AES-256, etc.).
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<subsection name="StaticMember Attributes">
<p><b>LocalMember:</b> <br/>
Static member that is the local member of the static cluster group.
</p>
<attributes>
<attribute name="className" required="true">
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
</attribute>
<attribute name="port" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="securePort" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="host" required="false">
There is no need to set.
The value of this attribute inherits from the cluster receiver setting.
</attribute>
<attribute name="domain" required="false">
The logical cluster domain for that this static member listens for cluster messages.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="uniqueId" required="true">
A universally uniqueId for this static member.
The values must be 16 bytes in the following form:<br/>
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br/>
</attribute>
</attributes>
<p><b>Member:</b> <br/>
Static member that add to the static cluster group.
</p>
<attributes>
<attribute name="className" required="true">
Only one implementation available:<code>org.apache.catalina.tribes.membership.StaticMember</code>
</attribute>
<attribute name="port" required="true">
The port that this static member listens to for cluster messages
</attribute>
<attribute name="securePort" required="false">
The secure port this static member listens to for encrypted cluster messages
default value is <code>-1</code>, this value means the member is not listening on a secure port
</attribute>
<attribute name="host" required="true">
The host (or network interface) that this static member listens for cluster messages.
Three different type of values are possible:<br/>
1. IP address in the form of &quot;216.123.1.23&quot;<br/>
2. Hostnames like &quot;tomcat01.mydomain.com&quot; or &quot;tomcat01&quot; as long as they resolve correctly<br/>
3. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="domain" required="false">
The logical cluster domain for that this static member listens for cluster messages.
Two different type of values are possible:<br/>
1. Regular string values like &quot;staging-domain&quot; or &quot;tomcat-cluster&quot; will be converted into bytes
using ISO-8859-1 encoding.<br/>
2. byte array in string form, for example {216,123,12,3}<br/>
</attribute>
<attribute name="uniqueId" required="true">
A universally uniqueId for this static member.
The values must be 16 bytes in the following form:<br/>
1. byte array in string form, for example {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15}<br/>
</attribute>
</attributes>
</subsection>
<!--TODO Document all the interceptors-->
</section>
</body>
</document>

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

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

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

@@ -0,0 +1,293 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-manager.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The ClusterManager object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>A cluster manager is an extension to Tomcat's session manager interface,
<code>org.apache.catalina.Manager</code>.
A cluster manager must implement the
<code>org.apache.catalina.ha.ClusterManager</code> and is solely responsible
for how the session is replicated.<br/>
There are currently two different managers, the
<code>org.apache.catalina.ha.session.DeltaManager</code> replicates deltas of
session data to all members in the cluster. This implementation is proven and
works very well, but has a limitation as it requires the cluster members to be
homogeneous, all nodes must deploy the same applications and be exact
replicas. The <code>org.apache.catalina.ha.session.BackupManager</code> also
replicates deltas but only to one backup node. The location of the backup node
is known to all nodes in the cluster. It also supports heterogeneous
deployments, so the manager knows at what locations the web application is
deployed.</p>
</section>
<section name="The &lt;Manager&gt;">
<p>The <code>&lt;Manager&gt;</code> element defined inside the
<code>&lt;Cluster&gt;</code> element is the template defined for all web
applications that are marked <code>&lt;distributable/&gt;</code> in their
<code>web.xml</code> file. However, you can still override the manager
implementation on a per web application basis, by putting the
<code>&lt;Manager&gt;</code> inside the <code>&lt;Context&gt;</code> element
either in the <code><a href="context.html">context.xml</a></code> file or the
<code><a href="index.html">server.xml</a></code> file.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
</attribute>
<attribute name="name" required="false">
<b>The name of this cluster manager, the name is used to identify a
session manager on a node. The name might get modified by the
<code>Cluster</code> element to make it unique in the container.</b>
</attribute>
<attribute name="notifyListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have session listeners notified
when session attributes are being replicated or removed across Tomcat
nodes in the cluster.
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>Frequency of the session expiration, and related manager operations.
Manager operations will be done once for the specified amount of
backgroundProcess calls (i.e., the lower the amount, the more often the
checks will occur). The minimum value is 1, and the default value is 6.
</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>Name of the Java class that extends
<code>java.security.SecureRandom</code> to use to generate session IDs.
If not specified, the default value is
<code>java.security.SecureRandom</code>.</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>Name of the provider to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the platform default provider will be used.</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>Name of the algorithm to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the default algorithm of SHA1PRNG will be used. If the
default algorithm is not supported, the platform default will be used.
To specify that the platform default should be used, do not set the
secureRandomProvider attribute and set this attribute to the empty
string.</p>
</attribute>
<attribute name="recordAllActions" required="false">
<p>Flag whether send all actions for session across Tomcat cluster
nodes. If set to false, if already done something to the same attribute,
make sure don't send multiple actions across Tomcat cluster nodes.
In that case, sends only the actions that have been added at last.
Default is <code>false</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.DeltaManager Attributes">
<attributes>
<attribute name="expireSessionsOnShutdown" required="false">
When a web application is being shutdown, Tomcat issues an expire call
to each session to notify all the listeners. If you wish for all
sessions to expire on all nodes when a shutdown occurs on one node, set
this value to <code>true</code>.
Default value is <code>false</code>.
</attribute>
<attribute name="maxActiveSessions" required="false">
The maximum number of active sessions that will be created by this
Manager, or -1 (the default) for no limit. For this manager, all
sessions are counted as active sessions irrespective if whether or not
the current node is the primary node for the session.
</attribute>
<attribute name="notifySessionListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have session listeners notified
when sessions are created and expired across Tomcat nodes in the
cluster.
</attribute>
<attribute name="notifyContainerListenersOnReplication" required="false">
Set to <code>true</code> if you wish to have container listeners notified
across Tomcat nodes in the cluster.
</attribute>
<attribute name="stateTransferTimeout" required="false">
The time in seconds to wait for a session state transfer to complete
from another node when a node is starting up.
Default value is <code>60</code> seconds.
</attribute>
<attribute name="sendAllSessions" required="false">
Flag whether send sessions as split blocks.
If set to <code>true</code>, send all sessions as one big block.
If set to <code>false</code>, send sessions as split blocks.
Default value is <code>true</code>.
</attribute>
<attribute name="sendAllSessionsSize" required="false">
The number of sessions in a session block message. This value is
effective only when <code>sendAllSessions</code> is <code>false</code>.
Default is <code>1000</code>.
</attribute>
<attribute name="sendAllSessionsWaitTime" required="false">
Wait time between sending of session block messages. This value is
effective only when <code>sendAllSessions</code> is <code>false</code>.
Default is <code>2000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for replication. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only replicate the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
replication. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="stateTimestampDrop" required="false">
When this node sends a <code>GET_ALL_SESSIONS</code> message to other
node, all session messages that are received as a response are queued.
If this attribute is set to <code>true</code>, the received session
messages (except any <code>GET_ALL_SESSIONS</code> sent by other nodes)
are filtered by their timestamp. A message is dropped if it is not a
<code>GET_ALL_SESSIONS</code> message and its timestamp is earlier than
the timestamp of our <code>GET_ALL_SESSIONS</code> message.
If set to <code>false</code>, all queued session messages are handled.
Default is <code>true</code>.
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="org.apache.catalina.ha.session.BackupManager Attributes">
<attributes>
<attribute name="mapSendOptions" required="false">
The backup manager uses a replicated map, this map is sending and
receiving messages. You can setup the flag for how this map is sending
messages, the default value is <code>6</code>(synchronous).<br/>
Note that if you use asynchronous messaging it is possible for update
messages for a session to be processed by the receiving node in a
different order to the order in which they were sent.
</attribute>
<attribute name="maxActiveSessions" required="false">
The maximum number of active sessions that will be created by this
Manager, or -1 (the default) for no limit. For this manager, only
sessions where the current node is the primary node for the session are
considered active sessions.
</attribute>
<attribute name="rpcTimeout" required="false">
Timeout for RPC message used for broadcast and transfer state from
another map.
Default value is <code>15000</code> milliseconds.
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for replication. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only replicate the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
replicated. An attribute will only be replicated if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
replication. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
Set to true if you wish to terminate replication map when replication
map fails to start. If replication map is terminated, associated context
will fail to start. If you set this attribute to false, replication map
does not end. It will try to join the map membership in the heartbeat.
Default value is <code>false</code> .
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
<attribute name="accessTimeout" required="false">
The timeout for a ping message. If a remote map does not respond within
this timeout period, its regarded as disappeared.
Default value is <code>5000</code> milliseconds.
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong>&lt;SessionIdGenerator&gt;</strong> element. It defines
the behavior of session id generation. All implementations
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
following attributes:
</p>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
</section>
</body>
</document>

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

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-membership.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Membership object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The membership component in the Apache Tribes <a href="cluster-channel.html">Channel</a> is responsible
for dynamic discovery of other members(nodes) in the cluster.
</p>
</section>
<section name="Default Implementation">
<p>
The default implementation of the cluster group notification is built on top of multicast heartbeats
sent using UDP packets to a multicast IP address.
Cluster members are grouped together by using the same multicast address/port combination.
Each member sends out a heartbeat with a given interval (<code>frequency</code>), and this
heartbeat is used for dynamic discovery.
In a similar fashion, if a heartbeat has not been received in a timeframe specified by <code>dropTime</code>
ms. a member is considered suspect and the channel and any membership listener will be notified.
</p>
</section>
<section name="Attributes">
<subsection name="Multicast Attributes">
<attributes>
<attribute name="className" required="true">
<p>
The default value is <code>org.apache.catalina.tribes.membership.McastService</code>
and is currently the only implementation.
This implementation uses multicast heartbeats for member discovery.
</p>
</attribute>
<attribute name="address" required="false">
<p>
The multicast address that the membership will broadcast its presence and listen
for other heartbeats on. The default value is <code>228.0.0.4</code>
Make sure your network is enabled for multicast traffic.<br/>
The multicast address, in conjunction with the <code>port</code> is what
creates a cluster group. To divide up your farm into several different group, or to
split up QA from production, change the <code>port</code> or the <code>address</code>
<br/>Previously known as mcastAddr.
</p>
</attribute>
<attribute name="port" required="false">
<p>
The multicast port, the default value is <code>45564</code><br/>
The multicast port, in conjunction with the <code>address</code> is what
creates a cluster group. To divide up your farm into several different group, or to
split up QA from production, change the <code>port</code> or the <code>address</code>
</p>
</attribute>
<attribute name="frequency" required="false">
<p>
The frequency in milliseconds in which heartbeats are sent out. The default value is <code>500</code> ms.<br/>
In most cases the default value is sufficient. Changing this value, simply changes the interval in between heartbeats.
</p>
</attribute>
<attribute name="dropTime" required="false">
<p>
The membership component will time out members and notify the Channel if a member fails to send a heartbeat within
a give time. The default value is <code>3000</code> ms. This means, that if a heartbeat is not received from a
member in that timeframe, the membership component will notify the cluster of this.<br/>
On a high latency network you may wish to increase this value, to protect against false positives.<br/>
Apache Tribes also provides a <a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.TcpFailureDetector_Attributes"><code>TcpFailureDetector</code></a> that will
verify a timeout using a TCP connection when a heartbeat timeout has occurred. This protects against false positives.
</p>
</attribute>
<attribute name="bind" required="false">
<p>
Use this attribute if you wish to bind your multicast traffic to a specific network interface.
By default, or when this attribute is unset, it tries to bind to <code>0.0.0.0</code> and sometimes on multihomed hosts
this becomes a problem.
</p>
</attribute>
<attribute name="ttl" required="false">
<p>
The time-to-live setting for the multicast heartbeats.
This setting should be a value between 0 and 255. The default value is VM implementation specific.
</p>
</attribute>
<attribute name="domain" required="false">
<p>
Apache Tribes has the ability to logically group members into domains, by using this domain attribute.
The <code>org.apache.catalina.tribes.Member.getDomain()</code> method returns the value specified here.
</p>
</attribute>
<attribute name="soTimeout" required="false">
<p>
The sending and receiving of heartbeats is done on a single thread, hence to avoid blocking this thread forever,
you can control the <code>SO_TIMEOUT</code> value on this socket.<br/>
If a value smaller or equal to 0 is presented, the code will default this value to frequency
</p>
</attribute>
<attribute name="recoveryEnabled" required="false">
<p>
In case of a network failure, Java multicast socket don't transparently fail over, instead the socket will continuously
throw IOException upon each receive request. When recoveryEnabled is set to true, this will close the multicast socket
and open a new socket with the same properties as defined above.<br/>
The default is <code>true</code>. <br/>
</p>
</attribute>
<attribute name="recoveryCounter" required="false">
<p>
When <code>recoveryEnabled==true</code> this value indicates how many
times an error has to occur before recovery is attempted. The default is
<code>10</code>. <br/>
</p>
</attribute>
<attribute name="recoverySleepTime" required="false">
<p>
When <code>recoveryEnabled==true</code> this value indicates how long time (in milliseconds)
the system will sleep in between recovery attempts, until it recovers successfully.
The default is <code>5000</code> (5 seconds). <br/>
</p>
</attribute>
<attribute name="localLoopbackDisabled" required="false">
<p>
Membership uses multicast, it will call <code>java.net.MulticastSocket.setLoopbackMode(localLoopbackDisabled)</code>.
When <code>localLoopbackDisabled==true</code> multicast messages will not reach other nodes on the same local machine.
The default is <code>false</code>. <br/>
</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,171 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-receiver.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Receiver object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The receiver component is responsible for receiving cluster messages.
As you might notice through the configuration, is that the receiving of messages
and sending of messages are two different components, this is different from many other
frameworks, but there is a good reason for it, to decouple the logic for how messages are sent from
how messages are received.<br/>
The receiver is very much like the Tomcat Connector, its the base of the thread pool
for incoming cluster messages. The receiver is straight forward, but all the socket settings
for incoming traffic are managed here.
</p>
</section>
<section name="Blocking vs Non-Blocking Receiver">
<p>
The receiver supports both a non blocking, <code>org.apache.catalina.tribes.transport.nio.NioReceiver</code>, and a
blocking, <code>org.apache.catalina.tribes.transport.bio.BioReceiver</code>. It is preferred to use the non blocking receiver
to be able to grow your cluster without running into thread starvation.<br/>
Using the non blocking receiver allows you to with a very limited thread count to serve a large number of messages.
Usually the rule is to use 1 thread per node in the cluster for small clusters, and then depending on your message frequency
and your hardware, you'll find an optimal number of threads peak out at a certain number.
</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<attributes>
<attribute name="className" required="true">
The implementation of the receiver component. Two implementations available,
<code>org.apache.catalina.tribes.transport.nio.NioReceiver</code> and
<code>org.apache.catalina.tribes.transport.bio.BioReceiver</code>.<br/>
The <code>org.apache.catalina.tribes.transport.nio.NioReceiver</code> is the
preferred implementation
</attribute>
<attribute name="address" required="false">
The address (network interface) to listen for incoming traffic.
Same as the bind address. The default value is <code>auto</code> and translates to
<code>java.net.InetAddress.getLocalHost().getHostAddress()</code>.
</attribute>
<attribute name="direct" required="false">
Possible values are <code>true</code> or <code>false</code>.
Set to true if you want the receiver to use direct bytebuffers when reading data
from the sockets.
</attribute>
<attribute name="port" required="false">
The listen port for incoming data. The default value is <code>4000</code>.
To avoid port conflicts the receiver will automatically bind to a free port within the range of
<code> port &lt;= bindPort &lt; port+autoBind</code>
So for example, if port is 4000, and autoBind is set to 10, then the receiver will open up
a server socket on the first available port in the range 4000-4009.
</attribute>
<attribute name="autoBind" required="false">
Default value is <code>100</code>.
Use this value if you wish to automatically avoid port conflicts the cluster receiver will try to open a
server socket on the <code>port</code> attribute port, and then work up <code>autoBind</code> number of times.
</attribute>
<attribute name="securePort" required="false">
The secure listen port. This port is SSL enabled. If this attribute is omitted no SSL port is opened up.
There default value is unset, meaning there is no SSL socket available.
</attribute>
<attribute name="udpPort" required="false">
The UDP listen port. If this attribute is omitted no UDP port is opened up.
There default value is unset, meaning there is no UDP listener available.
</attribute>
<attribute name="selectorTimeout" required="false">
The value in milliseconds for the polling timeout in the <code>NioReceiver</code>. On older versions of the JDK
there have been bugs, that should all now be cleared out where the selector never woke up.
The default value is a very high <code>5000</code> milliseconds.
</attribute>
<attribute name="maxThreads" required="false">
The maximum number of threads in the receiver thread pool. The default value is <code>15</code>
Adjust this value relative to the number of nodes in the cluster, the number of messages being exchanged and
the hardware you are running on. A higher value doesn't mean more efficiency, tune this value according to your
own test results.
</attribute>
<attribute name="minThreads" required="false">
Minimum number of threads to be created when the receiver is started up. Default value is <code>6</code>
</attribute>
<attribute name="maxIdleTime" required="false">
Maximum number of milliseconds of until Idle thread terminates. Default value is <code>60000</code> milliseconds.
</attribute>
<attribute name="ooBInline" required="false">
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="rxBufSize" required="false">
The receiver buffer size on the receiving sockets. Value is in bytes, the default value is <code>43800</code> bytes.
</attribute>
<attribute name="txBufSize" required="false">
The sending buffer size on the receiving sockets. Value is in bytes, the default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpRxBufSize" required="false">
The receive buffer size on the datagram socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpTxBufSize" required="false">
The send buffer size on the datagram socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="soKeepAlive" required="false">
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soLingerOn" required="false">
Boolean value to determine whether to use the SO_LINGER socket option.
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
</attribute>
<attribute name="soLingerTime" required="false">
Sets the SO_LINGER socket option time value. The value is in seconds.
The default value is <code>3</code> seconds.
</attribute>
<attribute name="soReuseAddress" required="false">
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="tcpNoDelay" required="false">
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
The default value is <code>true</code>
</attribute>
<attribute name="timeout" required="false">
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
milliseconds.
</attribute>
<attribute name="useBufferPool" required="false">
Boolean value whether to use a shared buffer pool of cached <code>org.apache.catalina.tribes.io.XByteBuffer</code>
objects. If set to true, the XByteBuffer that is used to pass a message up the channel, will be recycled at the end
of the requests. This means that interceptors in the channel must not maintain a reference to the object
after the <code>org.apache.catalina.tribes.ChannelInterceptor#messageReceived</code> method has exited.
</attribute>
</attributes>
</subsection>
<subsection name="NioReceiver">
</subsection>
<subsection name="BioReceiver">
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,181 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-sender.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Sender object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The channel sender component is responsible for delivering outgoing cluster messages over the network.
In the default implementation, <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>,
the sender is a fairly empty shell with not much logic around a fairly complex <code>&lt;Transport&gt;</code>
component the implements the actual delivery mechanism.
</p>
</section>
<section name="Concurrent Parallel Delivery">
<p>
In the default <code>transport</code> implementation, <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>,
Apache Tribes implements what we like to call &quot;Concurrent Parallel Delivery&quot;.
This means that we can send a message to more than one destination at the same time(parallel), and
deliver two messages to the same destination at the same time(concurrent). Combine these two and we have
&quot;Concurrent Parallel Delivery&quot;.
</p>
<p>
When is this useful? The simplest example we can think of is when part of your code is sending a 10MB message,
like a war file being deployed, and you need to push through a small 10KB message, say a session being replicated,
you don't have to wait for the 10MB message to finish, as a separate thread will push in the small message
transmission at the same time. Currently there is no interrupt, pause or priority mechanism available, but check back soon.
</p>
</section>
<section name="Nested Elements">
<p>
The nested element <code>&lt;Transport&gt;</code> is not required, but encouraged, as this is where
you would set all the socket options for the outgoing messages. Please see its attributes below.
There are two implementations, in a similar manner to the <a href="cluster-receiver.html">receiver</a>, one is non-blocking
based and the other is built using blocking IO. <br/>
<code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code> is the blocking implementation and
<code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code>.
Parallel delivery is not available for the blocking implementation due to the fact that it is blocking a thread on sending data.
</p>
</section>
<section name="Attributes">
<subsection name="Common Sender Attributes">
<attributes>
<attribute name="className" required="true">
Required, only available implementation is <code>org.apache.catalina.tribes.transport.ReplicationTransmitter</code>
</attribute>
</attributes>
</subsection>
<subsection name="Common Transport Attributes">
<attributes>
<attribute name="className" required="true">
Required, an implementation of the <code>org.apache.catalina.tribes.transport.MultiPointSender</code>.<br/>
Non-blocking implementation is <code>org.apache.catalina.tribes.transport.nio.PooledParallelSender</code><br/>
Blocking implementation is <code>org.apache.catalina.tribes.transport.bio.PooledMultiSender</code>
</attribute>
<attribute name="rxBufSize" required="false">
The receive buffer size on the socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="txBufSize" required="false">
The send buffer size on the socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="udpRxBufSize" required="false">
The receive buffer size on the datagram socket.
Default value is <code>25188</code> bytes.
</attribute>
<attribute name="udpTxBufSize" required="false">
The send buffer size on the datagram socket.
Default value is <code>43800</code> bytes.
</attribute>
<attribute name="directBuffer" required="false">
Possible values are <code>true</code> or <code>false</code>.
Set to true if you want the receiver to use direct bytebuffers when writing data
to the sockets. Default value is <code>false</code>
</attribute>
<attribute name="keepAliveCount" required="false">
The number of requests that can go through the socket before the socket is closed, and reopened
for the next request. The default value is <code>-1</code>, which is unlimited.
</attribute>
<attribute name="keepAliveTime" required="false">
The number of milliseconds a connection is kept open after its been opened.
The default value is <code>-1</code>, which is unlimited.
</attribute>
<attribute name="timeout" required="false">
Sets the SO_TIMEOUT option on the socket. The value is in milliseconds and the default value is <code>3000</code>
milliseconds.(3 seconds) This timeout starts when a message send attempt is starting, until the transfer has been completed.
For the NIO sockets, this will mean, that the caller can guarantee that we will not attempt sending the message
longer than this timeout value. For the blocking IO implementation, this translated directly to the soTimeout.<br/>
A timeout will not spawn a retry attempt, in order to guarantee the return of the application thread.
</attribute>
<attribute name="maxRetryAttempts" required="false">
How many times do we retry a failed message, that received a IOException at the socket level.
The default value is <code>1</code>, meaning we will retry a message that has failed once.
In other words, we will attempt a message send no more than twice. One is the original send, and one is the
<code>maxRetryAttempts</code>.
</attribute>
<attribute name="ooBInline" required="false">
Boolean value for the socket OOBINLINE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soKeepAlive" required="false">
Boolean value for the socket SO_KEEPALIVE option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soLingerOn" required="false">
Boolean value to determine whether to use the SO_LINGER socket option.
Possible values are <code>true</code> or <code>false</code>. Default value is <code>true</code>.
</attribute>
<attribute name="soLingerTime" required="false">
Sets the SO_LINGER socket option time value. The value is in seconds.
The default value is <code>3</code> seconds.
</attribute>
<attribute name="soReuseAddress" required="false">
Boolean value for the socket SO_REUSEADDR option. Possible values are <code>true</code> or <code>false</code>.
</attribute>
<attribute name="soTrafficClass" required="false">
Sets the traffic class level for the socket, the value is between 0 and 255.
Default value is <code>int soTrafficClass = 0x04 | 0x08 | 0x010;</code>
Different values are defined in <a href="http://docs.oracle.com/javase/7/docs/api/java/net/Socket.html#setTrafficClass(int)">
java.net.Socket#setTrafficClass(int)</a>.
</attribute>
<attribute name="tcpNoDelay" required="false">
Boolean value for the socket TCP_NODELAY option. Possible values are <code>true</code> or <code>false</code>.
The default value is <code>true</code>
</attribute>
<attribute name="throwOnFailedAck" required="false">
Boolean value, default value is <code>true</code>.
If set to true, the sender will throw a <code>org.apache.catalina.tribes.RemoteProcessException</code>
when we receive a negative ack from the remote member.
Set to false, and Tribes will treat a positive ack the same way as a negative ack, that the message was received.
</attribute>
</attributes>
</subsection>
<subsection name="Common PooledSender Attributes">
<attributes>
<attribute name="poolSize" required="false">
The maximum number of concurrent connections from A to B.
The value is based on a per-destination count.
The default value is <code>25</code>
</attribute>
<attribute name="maxWait" required="false">
The maximum number of milliseconds that the senderPool will wait when
there are no available senders. The default value is <code>3000</code>
milliseconds.(3 seconds).
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster-valve.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster Valve object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
A cluster valve is no different from any other <a href="valve.html">Tomcat <code>Valve</code></a>.
The cluster valves are interceptors in the invocation chain for HTTP requests, and the clustering implementation
uses these valves to make intelligent decision around data and when data should be replicated.
</p>
<p>
A cluster valve must implement the <code>org.apache.catalina.ha.ClusterValve</code> interface.
This is a simple interface that extends the <code>org.apache.catalina.Valve</code> interface.
</p>
</section>
<section name="org.apache.catalina.ha.tcp.ReplicationValve">
The <code>ReplicationValve</code> will notify the cluster at the end of an HTTP request
so that the cluster can make a decision whether there is data to be replicated or not.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
Set value to <code>org.apache.catalina.ha.tcp.ReplicationValve</code>
</attribute>
<attribute name="filter" required="false">
For known file extensions or urls, you can use this Valve to notify the
cluster that the session has not been modified during this request and
the cluster doesn't have to probe the session managers for changes. If
the request matches this filter pattern, the cluster assumes there has
been no session change. An example filter would look like <code>
filter=&quot;.*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*\.txt&quot;
</code>. The filter is a regular expression using
<code>java.util.regex</code>.
</attribute>
<attribute name="primaryIndicator" required="false">
Boolean value, so to true, and the replication valve will insert a request attribute with the name
defined by the <code>primaryIndicatorName</code> attribute.
The value inserted into the request attribute is either <code>Boolean.TRUE</code> or
<code>Boolean.FALSE</code>
</attribute>
<attribute name="primaryIndicatorName" required="false">
Default value is <code>org.apache.catalina.ha.tcp.isPrimarySession</code>
The value defined here is the name of the request attribute that contains the boolean value
if the session is primary on this server or not.
</attribute>
<attribute name="statistics" required="false">
Boolean value. Set to <code>true</code> if you want the valve to collect request statistics.
Default value is <code>false</code>
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.session.JvmRouteBinderValve">
In case of a mod_jk failover, the <code>JvmRouteBinderValve</code> will replace the
<code>jvmWorker</code> attribute in the session Id, to make future requests stick to this
node. If you want fallback capability, don't enable this valve, but if you want your failover to stick,
and for mod_jk not to have to keep probing the node that went down, you use this valve.
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<code>org.apache.catalina.ha.session.JvmRouteBinderValve</code>
</attribute>
<attribute name="enabled" required="false">
Default value is <code>true</code>
Runtime attribute to turn on and off turn over of the session's jvmRoute value.
</attribute>
<attribute name="sessionIdAttribute" required="false">
Old sessionid before failover is registered in request attributes with this attribute.
Default attribute name is <code>org.apache.catalina.ha.session.JvmRouteOrignalSessionID</code>.
</attribute>
</attributes>
</subsection>
</section>
<section name="org.apache.catalina.ha.authenticator.ClusterSingleSignOn">
The <code>ClusterSingleSignOn</code> supports feature of single sign on in cluster.
By using <code>ClusterSingleSignOn</code>, the security identity authenticated
by one web application is recognized by other web applications on the same virtual host,
and it is propagated to other nodes in the cluster.
<p>See the <a href="host.html#Single_Sign_On">Single Sign On</a> special
feature on the <strong>Host</strong> element for more information.</p>
<p><strong>Note:</strong> ClusterSingleSignOn can be configured at host level cluster only.
</p>
<subsection name="Attributes">
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This MUST be set to
<strong>org.apache.catalina.ha.authenticator.ClusterSingleSignOn</strong>.</p>
</attribute>
<attribute name="cookieDomain" required="false">
<p>Sets the host domain to be used for sso cookies.</p>
</attribute>
<attribute name="mapSendOptions" required="false">
<p>The Valve uses a replicated map. You can setup the flag for how this
map sends messages. The default value is <code>6</code> (synchronous).
Note that if you use asynchronous messaging it is possible for update
messages to be processed by the receiving node in a different order to
the order in which they were sent.</p>
</attribute>
<attribute name="requireReauthentication" required="false">
<p>Default false. Flag to determine whether each request needs to be
reauthenticated to the security <strong>Realm</strong>. If "true", this
Valve uses cached security credentials (username and password) to
reauthenticate to the <strong>Realm</strong> each request associated
with an SSO session. If "false", the Valve can itself authenticate
requests based on the presence of a valid SSO cookie, without
rechecking with the <strong>Realm</strong>.</p>
</attribute>
<attribute name="rpcTimeout" required="false">
<p>The Valve uses a replicated map. This is the timeout for messages
that transfer state to/from the other nodes in the cluster. If not
specified, a default value of <code>15000</code> milliseconds is used.
</p>
</attribute>
<attribute name="terminateOnStartFailure" required="false">
<p>Set to <code>true</code> if you wish this Valve to fail if the
underlying replication fails to start. If the Valve fails, then the
associated container will fail to start. If you set this attribute to
false, and the underlying replications fails to start, the Valve will
start and it will attempt to join the cluster and start replication as
part of the heartbeat process. If not specified, the default value of
<code>false</code> is used.</p>
</attribute>
<attribute name="accessTimeout" required="false">
The timeout for a ping message. If a remote map does not respond within
this timeout period, its regarded as disappeared.
Default value is <code>5000</code> milliseconds.
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,177 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cluster.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Cluster object</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The tomcat cluster implementation provides session replication, context attribute replication and
cluster wide WAR file deployment.
While the <code>Cluster</code> configuration is fairly complex, the default configuration will work
for most people out of the box. </p><p>
The Tomcat Cluster implementation is very extensible, and hence we have exposed a myriad of options,
making the configuration seem like a lot, but don't lose faith, instead you have a tremendous control
over what is going on.</p>
</section>
<section name="Security">
<p>The cluster implementation is written on the basis that a secure, trusted
network is used for all of the cluster related network traffic. It is not safe
to run a cluster on a insecure, untrusted network.</p>
<p>There are many options for providing a secure, trusted network for use by a
Tomcat cluster. These include:</p>
<ul>
<li><a href="cluster-interceptor.html#org.apache.catalina.tribes.group.interceptors.EncryptInterceptor_Attributes">EncryptInterceptor</a></li>
<li>private LAN</li>
<li>a Virtual Private Network (VPN)</li>
<li>IPSEC</li>
</ul>
</section>
<section name="Engine vs Host placement">
<p>
You can place the <code>&lt;Cluster&gt;</code> element inside either the <code>&lt;Engine&gt;</code>
container or the <code>&lt;Host&gt;</code> container.<br/>
Placing it in the engine, means that you will support clustering in all virtual hosts of Tomcat,
and share the messaging component. When you place the <code>&lt;Cluster&gt;</code> inside the <code>&lt;Engine&gt;</code>
element, the cluster will append the host name of each session manager to the managers name so that two contexts with
the same name but sitting inside two different hosts will be distinguishable.
</p>
</section>
<section name="Context Attribute Replication">
<p>To configure context attribute replication, simply do this by swapping out the context implementation
used for your application context.</p>
<source>&lt;Context className=&quot;org.apache.catalina.ha.context.ReplicatedContext&quot;/&gt;</source>
<p>
This context extends the Tomcat <code><a href="context.html">StandardContext</a></code>
so all the options from the <a href="context.html">base implementation</a> are valid.
</p>
</section>
<section name="Nested Components">
<p><b><a href="cluster-manager.html">Manager</a>:</b> <br/>
The session manager element identifies what kind of session manager is used in this cluster implementation.
This manager configuration is identical to the one you would use in a regular <code><a href="context.html#Nested_Components">&lt;Context&gt;</a></code> configuration.
<br/>The default value is the <code>org.apache.catalina.ha.session.DeltaManager</code> that is closely coupled with
the <code>SimpleTcpCluster</code> implementation. Other managers like the <code>org.apache.catalina.ha.session.BackupManager</code>
are/could be loosely coupled and don't rely on the <code>SimpleTcpCluster</code> for its data replication.
</p>
<p><b><a href="cluster-channel.html">Channel</a>:</b> <br/>
The Channel and its sub components are all part of the IO layer
for the cluster group, and is a module in it's own that we have nick named &quot;Tribes&quot;
<br/>
Any configuring and tuning of the network layer, the messaging and the membership logic
will be done in the channel and its nested components.
You can always find out more about <a href="../tribes/introduction.html">Apache Tribes</a>
</p>
<p><b><a href="cluster-valve.html">Valve</a>:</b> <br/>
The Tomcat Cluster implementation uses <code>Tomcat <a href="valve.html">Valves</a></code> to
track when requests enter and exit the servlet container. It uses these valves to be able to make
intelligent decisions on when to replicate data, which is always at the end of a request.
</p>
<p><b><a href="cluster-deployer.html">Deployer</a>:</b> <br/>
The Deployer component is the Tomcat Farm Deployer. It allows you to deploy and undeploy applications
cluster wide.
</p>
<p><b><a href="cluster-listener.html">ClusterListener</a>:</b> <br/>
ClusterListener's are used to track messages sent and received using the <code>SimpleTcpCluster</code>.
If you wish to track messages, you can add a listener here, or you can add a valve to the channel object.
</p>
</section>
<section name="Deprecated configuration options">
<p>
<b>Deprecated settings:</b> In the previous version of Tomcat you were able to control session
manager settings using manager.&lt;property&gt;=value.
This has been discontinued, as the way it was written interferes with
the ability to support multiple different manager classes under one cluster implementation,
as the same properties might have the different effect on different managers.
</p>
</section>
<section name="Attributes">
<subsection name="SimpleTcpCluster Attributes">
<attributes>
<attribute name="className" required="true">
<p>The main cluster class, currently only one is available,
<code>org.apache.catalina.ha.tcp.SimpleTcpCluster</code>
</p>
</attribute>
<attribute name="channelSendOptions" required="true">
<p>The Tribes channel send options, default is <code>8</code>.<br/>
This option is used to set the flag that all messages sent through the
SimpleTcpCluster uses. The flag decides how the messages are sent, and is a simple logical OR.</p>
<source>int options = Channel.SEND_OPTIONS_ASYNCHRONOUS |
Channel.SEND_OPTIONS_SYNCHRONIZED_ACK |
Channel.SEND_OPTIONS_USE_ACK;</source>
<p>Some of the values are:<br/>
<code>Channel.SEND_OPTIONS_SYNCHRONIZED_ACK = 0x0004</code><br/>
<code>Channel.SEND_OPTIONS_ASYNCHRONOUS = 0x0008</code><br/>
<code>Channel.SEND_OPTIONS_USE_ACK = 0x0002</code><br/>
So to use ACK and ASYNC messaging, the flag would be <code>10</code> (8+2)
<br/>
Note that if you use ASYNC messaging it is possible for update messages
for a session to be processed by the receiving nodes in a different order
to the order in which they were sent.</p>
</attribute>
<attribute name="channelStartOptions" required="false">
<p>Sets the start and stop flags for the &lt;Channel&gt; object used by the cluster.
The default is <code>Channel.DEFAULT</code> which starts all the channel services, such as
sender, receiver, multicast sender and multicast receiver.
The following flags are available today:</p>
<source>Channel.DEFAULT = Channel.SND_RX_SEQ (1) |
Channel.SND_TX_SEQ (2) |
Channel.MBR_RX_SEQ (4) |
Channel.MBR_TX_SEQ (8);</source>
<p>To start a channel without multicasting, you would want to use the value <code>Channel.SND_RX_SEQ | Channel.SND_TX_SEQ</code>
that equals to <code>3</code>.
</p>
</attribute>
<attribute name="heartbeatBackgroundEnabled" required="false">
<p>Flag whether invoke channel heartbeat at container background thread. Default value is false.
Enable this flag don't forget to disable the channel heartbeat thread.
</p>
</attribute>
<attribute name="notifyLifecycleListenerOnFailure" required="false">
<p>Flag whether notify LifecycleListeners if all ClusterListener couldn't accept channel message.
Default value is false.
</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

File diff suppressed because it is too large Load Diff

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

@@ -0,0 +1,216 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="cookie-processor.html">
&project;
<properties>
<title>The Cookie Processor Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<p>The <strong>CookieProcessor</strong> element represents the component that
parses received cookie headers into <code>javax.servlet.http.Cookie</code>
objects accessible through <code>HttpServletRequest.getCookies()</code> and
converts <code>javax.servlet.http.Cookie</code> objects added to the response
through <code>HttpServletResponse.addCookie()</code> to the HTTP headers
returned to the client.</p>
<p>A CookieProcessor element MAY be nested inside a
<a href="context.html">Context</a> component. If it is not included, a default
implementation will be created automatically.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>CookieProcessor</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.tomcat.util.http.CookieProcessor</code>
interface. If not specified, the standard value (defined below) will be
used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>CookieProcessor</strong> is
<code>org.apache.tomcat.util.http.Rfc6265CookieProcessor</code>.</p>
<p>This cookie processor is based on RFC6265 with the following changes to
support better interoperability:</p>
<ul>
<li>Values 0x80 to 0xFF are permitted in cookie-octet to support the use
of UTF-8 in cookie values as used by HTML 5.</li>
<li>For cookies without a value, the '=' is not required after the name as
some browsers do not sent it.</li>
</ul>
<p>The RFC 6265 cookie processor is generally more lenient than the legacy
cookie parser. In particular:</p>
<ul>
<li>The '<code>=</code>' and '<code>/</code>' characters are always
permitted in a cookie value.</li>
<li>Name only cookies are always permitted.</li>
<li>The cookie header is always preserved.</li>
</ul>
<p>The <strong>RFC 6265 Cookie Processor</strong> supports the following
additional attributes.</p>
<attributes>
<attribute name="sameSiteCookies" required="false">
<p>Enables setting same-site cookie attribute.</p>
<p>If value is <code>unset</code> then the same-site cookie attribute
won't be set. This is the default value.</p>
<p>If value is <code>none</code> then the same-site cookie attribute
will be set and the cookie will always be sent in cross-site requests.</p>
<p>If value is <code>lax</code> then the browser only sends the cookie
in same-site requests and cross-site top level GET requests.</p>
<p>If value is <code>strict</code> then the browser prevents sending the
cookie in any cross-site request.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Legacy Cookie Processor - org.apache.tomcat.util.http.LegacyCookieProcessor">
<p>This is the legacy cookie parser based on RFC6265, RFC2109 and RFC2616.
It implements a strict interpretation of the cookie specifications. Due to
various interoperability issues with browsers not all strict behaviours
are enabled by default and additional options are available to further
relax the behaviour of this cookie processor if required.</p>
<attributes>
<attribute name="allowEqualsInValue" required="false">
<p>If this is <code>true</code> Tomcat will allow '<code>=</code>'
characters when parsing unquoted cookie values. If <code>false</code>,
cookie values containing '<code>=</code>' will be terminated when the
'<code>=</code>' is encountered and the remainder of the cookie value
will be dropped.</p>
<p>If not set the specification compliant default value of
<code>false</code> will be used.</p>
</attribute>
<attribute name="allowHttpSepsInV0" required="false">
<p>If this is <code>true</code> Tomcat will allow HTTP separators in
cookie names and values.</p>
<p>If not specified, the default specification compliant value of
<code>false</code> will be used.</p>
</attribute>
<attribute name="allowNameOnly" required="false">
<p>If this is <code>true</code> Tomcat will allow name only cookies
(with or without trailing '<code>=</code>') when parsing cookie headers.
If <code>false</code>, name only cookies will be dropped.</p>
<p>If not set the specification compliant default value of
<code>false</code> will be used.</p>
</attribute>
<attribute name="alwaysAddExpires" required="false">
<p>If this is <code>true</code> Tomcat will always add an expires
parameter to a SetCookie header even for cookies with version greater
than zero. This is to work around a known IE6 and IE7 bug that causes I
to ignore the Max-Age parameter in a SetCookie header.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set
to <code>true</code>, the default of this setting will be
<code>false</code>, else the default value will be <code>true</code>.
</p>
</attribute>
<attribute name="forwardSlashIsSeparator" required="false">
<p>If this is <code>true</code> Tomcat will treat the forward slash
character ('<code>/</code>') as an HTTP separator when processing cookie
headers. If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
is set to <code>true</code>, the default of this setting will be
<code>true</code>, else the default value will be <code>false</code>.
</p>
</attribute>
<attribute name="sameSiteCookies" required="false">
<p>Enables setting same-site cookie attribute.</p>
<p>If value is <code>unset</code> then the same-site cookie attribute
won't be set. This is the default value.</p>
<p>If value is <code>none</code> then the same-site cookie attribute
will be set and the cookie will always be sent in cross-site requests.</p>
<p>If value is <code>lax</code> then the browser only sends the cookie
in same-site requests and cross-site top level GET requests.</p>
<p>If value is <code>strict</code> then the browser prevents sending the
cookie in any cross-site request.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No element may be nested inside a <strong>CookieProcessor</strong>.</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>CookieProcessor</strong>
element.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,219 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="credentialhandler.html">
&project;
<properties>
<title>The CredentialHandler Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<p>The <strong>CredentialHandler</strong> element represents the component
used by a <a href="realm.html">Realm</a> to compare a provided credential such
as a password with the version of the credential stored by the
<a href="realm.html">Realm</a>. The <strong>CredentialHandler</strong> can
also be used to generate a new stored version of a given credential that would
be required, for example, when adding a new user to a
<a href="realm.html">Realm</a> or when changing a user&apos;s password.</p>
<p>A <strong>CredentialHandler</strong> element MUST be nested inside a
<a href="realm.html">Realm</a> component. If it is not included,
a default <strong>CredentialHandler</strong> will be created using the
<strong>MessageDigestCredentialHandler</strong>.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>CredentialHandler</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.CredentialHandler</code>
interface.</p>
</attribute>
</attributes>
<p>Unlike most Catalina components, there are several standard
<strong>CredentialHandler</strong> implementations available. As a result,
if a <strong>CredentialHandler</strong> element is present then the
<code>className</code> attribute MUST be used to select the implementation
you wish to use.</p>
</subsection>
<subsection name="MessageDigestCredentialHandler">
<p>The <strong>MessageDigestCredentialHandler</strong> is used when stored
passwords are protected by a message digest. This credential handler
supports the following forms of stored passwords:</p>
<ul>
<li><strong>plainText</strong> - the plain text credentials if no
algorithm is specified</li>
<li><strong>encodedCredential</strong> - a hex encoded digest of the
password digested using the configured digest</li>
<li><strong>{MD5}encodedCredential</strong> - a Base64 encoded MD5
digest of the password</li>
<li><strong>{SHA}encodedCredential</strong> - a Base64 encoded SHA1 digest
of the password</li>
<li><strong>{SSHA}encodedCredential</strong> - 20 character salt followed
by the salted SHA1 digest Base64 encoded</li>
<li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
salt, iteration code and a hex encoded credential, each separated by
$</li>
</ul>
<p>If the stored password form does not include an iteration count then an
iteration count of 1 is used.</p>
<p>If the stored password form does not include salt then no salt is
used.</p>
<attributes>
<attribute name="algorithm" required="false">
<p>The name of the <code>java.security.MessageDigest</code> algorithm
used to encode user passwords stored in the database. If not specified,
user passwords are assumed to be stored in clear-text.</p>
</attribute>
<attribute name="encoding" required="false">
<p>Digesting the password requires that it is converted to bytes. This
attribute determines the character encoding to use for conversions
between characters and bytes. If not specified, UTF-8 will be used.</p>
</attribute>
<attribute name="iterations" required="false">
<p>The number of iterations to use when creating a new stored credential
from a clear text credential.</p>
</attribute>
<attribute name="saltLength" required="false">
<p>The length of the randomly generated salt to use when creating a
new stored credential from a clear text credential.</p>
</attribute>
</attributes>
</subsection>
<subsection name="NestedCredentialHandler">
<p>The <strong>NestedCredentialHandler</strong> is an implementation of
<strong>CredentialHandler</strong> that delegates to one or more
sub-CredentialHandlers.</p>
<p>Using the <strong>NestedCredentialHandler</strong> gives the developer
the ability to combine multiple <strong>CredentialHandler</strong>s of the
same or different types.</p>
<p>Sub-CredentialHandlers are defined by nesting CredentialHandler elements
inside the <code>CredentialHandler</code> element that defines the
NestedCredentialHandler. Credentials will be matched against each
<code>CredentialHandler</code> in the order they are listed. A match against
any CredentialHandler will be sufficient for the credentials to be
considered matched.</p>
</subsection>
<subsection name="SecretKeyCredentialHandler">
<p>The <strong>SecretKeyCredentialHandler</strong> is used when stored
passwords are built using <code>javax.crypto.SecretKeyFactory</code>. This
credential handler supports the following forms of stored passwords:</p>
<ul>
<li><strong>salt$iterationCount$encodedCredential</strong> - a hex encoded
salt, iteration code and a hex encoded credential, each separated by
$</li>
</ul>
<p>If the stored password form does not include an iteration count then an
iteration count of 1 is used.</p>
<p>If the stored password form does not include salt then no salt is
used.</p>
<attributes>
<attribute name="algorithm" required="false">
<p>The name of the secret key algorithm used to encode user passwords
stored in the database. If not specified, a default of
<code>PBKDF2WithHmacSHA1</code> is used.</p>
</attribute>
<attribute name="keyLength" required="false">
<p>The length of key to generate for the stored credential. If not
specified, a default of <code>160</code> is used.</p>
</attribute>
<attribute name="iterations" required="false">
<p>The number of iterations to use when creating a new stored credential
from a clear text credential.</p>
</attribute>
<attribute name="saltLength" required="false">
<p>The length of the randomly generated salt to use when creating a
new stored credential from a clear text credential.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>If you are using the <em>NestedCredentialHandler Implementation</em> or a
CredentialHandler that extends the NestedCredentialHandler one or more
<strong>&lt;CredentialHandler&gt;</strong> elements may be nested inside it.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a
<strong>CredentialHandler</strong> element.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,268 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="engine.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Engine Container</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Engine</strong> element represents the entire request
processing machinery associated with a particular Catalina
<a href="service.html">Service</a>. It receives and processes
<em>all</em> requests from one or more <strong>Connectors</strong>,
and returns the completed response to the Connector for ultimate
transmission back to the client.</p>
<p>Exactly one <strong>Engine</strong> element MUST be nested inside
a <a href="service.html">Service</a> element, following all of the
corresponding Connector elements associated with this Service.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Engine</strong>
support the following attributes:</p>
<attributes>
<attribute name="backgroundProcessorDelay" required="false">
<p>This value represents the delay in seconds between the
invocation of the backgroundProcess method on this engine and
its child containers, including all hosts and contexts.
Child containers will not be invoked if their delay value is not
negative (which would mean they are using their own processing
thread). Setting this to a positive value will cause
a thread to be spawn. After waiting the specified amount of time,
the thread will invoke the backgroundProcess method on this engine
and all its child containers. If not specified, the default value for
this attribute is 10, which represent a 10 seconds delay.</p>
</attribute>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Engine</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="defaultHost" required="true">
<p>The default host name, which identifies the
<a href="host.html">Host</a> that will process requests directed
to host names on this server, but which are not configured in
this configuration file. This name MUST match the <code>name</code>
attributes of one of the <a href="host.html">Host</a> elements
nested immediately inside.</p>
</attribute>
<attribute name="jvmRoute" required="false">
<p>Identifier which must be used in load balancing scenarios to enable
session affinity. The identifier, which must be unique across all
Tomcat servers which participate in the cluster, will be appended to
the generated session identifier, therefore allowing the front end
proxy to always forward a particular session to the same Tomcat
instance.</p>
<p>
Note that the <code>jvmRoute</code> can also be set using the
<code>jvmRoute</code> system property. The <code>jvmRoute</code>
set in an <code>&lt;Engine&gt;</code> attribute will override
any <code>jvmRoute</code> system property.
</p>
</attribute>
<attribute name="name" required="true">
<p>Logical name of this Engine, used in log and error messages. <em>When
using multiple <a href="service.html">Service</a> elements in the same
<a href="server.html">Server</a>, each Engine MUST be assigned a unique
name.</em></p>
</attribute>
<attribute name="startStopThreads" required="false">
<p>The number of threads this <strong>Engine</strong> will use to start
child <a href="host.html">Host</a> elements in parallel. The special
value of 0 will result in the value of
<code>Runtime.getRuntime().availableProcessors()</code> being used.
Negative values will result in
<code>Runtime.getRuntime().availableProcessors() + value</code> being
used unless this is less than 1 in which case 1 thread will be used. If
not specified, the default value of 1 will be used. </p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Engine</strong> is
<strong>org.apache.catalina.core.StandardEngine</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>You can nest one or more <a href="host.html">Host</a> elements inside
this <strong>Engine</strong> element, each representing a different virtual
host associated with this server. At least one <a href="host.html">Host</a>
is required, and one of the nested <a href="host.html">Hosts</a> MUST
have a name that matches the name specified for the
<code>defaultHost</code> attribute, listed above.</p>
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Engine</strong>
element:</p>
<ul>
<li><a href="realm.html"><strong>Realm</strong></a> -
Configure a realm that will allow its
database of users, and their associated roles, to be shared across all
<a href="host.html">Hosts</a> and <a href="context.html">Contexts</a>
nested inside this Engine, unless overridden by a
<a href="realm.html">Realm</a> configuration at a lower level.</li>
</ul>
</section>
<section name="Special Features">
<subsection name="Logging">
<p>An engine is associated with the
<code>org.apache.catalina.core.ContainerBase.[enginename]</code>
log category. Note that the brackets are actually part of the name,
don't omit them.</p>
</subsection>
<subsection name="Access Logs">
<p>When you run a web server, one of the output files normally generated
is an <em>access log</em>, which generates one line of information for
each request processed by the server, in a standard format. Catalina
includes an optional <a href="valve.html">Valve</a> implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.</p>
<p>You can ask Catalina to create an access log for all requests
processed by an <a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
<source><![CDATA[<Engine name="Standalone" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="catalina_access_log" suffix=".txt"
pattern="common"/>
...
</Engine>]]></source>
<p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
for more information on the configuration attributes that are
supported.</p>
</subsection>
<subsection name="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
<strong>Engine</strong> is started or stopped, you can declare it by
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
it will be notified about the occurrence of the corresponding
lifecycle events. Configuration of such a listener looks like this:</p>
<source><![CDATA[<Engine name="Standalone" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Engine>]]></source>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
</subsection>
<subsection name="Request Filters">
<p>You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a> element. The remote address or name
will be checked against configured "accept" and/or "deny"
filters, which are defined using <code>java.util.regex</code> Regular
Expression syntax. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
<source><![CDATA[<Engine name="Standalone" ...>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192\.168\.1\.\d+"/>
...
</Engine>]]></source>
<p>See <a href="valve.html#Remote_Address_Filter">Remote Address Filter</a>
and <a href="valve.html#Remote_Host_Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,130 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="executor.html">
&project;
<properties>
<author email="fhanik@apache.org">Filip Hanik</author>
<title>The Executor (thread pool)</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Executor</strong> represents a thread pool that can be shared
between components in Tomcat. Historically there has been a thread pool per
connector created but this allows you to share a thread pool, between (primarily) connector
but also other components when those get configured to support executors</p>
<p>The executor has to implement the <code>org.apache.catalina.Executor</code> interface.</p>
<p>The executor is a nested element to the <a href="service.html">Service</a> element.
And in order for it to be picked up by the connectors, the Executor element has to appear
prior to the Connector element in server.xml</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Executor</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>The class of the implementation. The implementation has to implement the
<code>org.apache.catalina.Executor</code> interface.
This interface ensures that the object can be referenced through its <code>name</code> attribute
and that implements Lifecycle, so that it can be started and stopped with the container.
The default value for the className is <code>org.apache.catalina.core.StandardThreadExecutor</code></p>
</attribute>
<attribute name="name" required="true">
<p>The name used to reference this pool in other places in server.xml.
The name is required and must be unique.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>
The default implementation supports the following attributes:</p>
<attributes>
<attribute name="threadPriority" required="false">
<p>(int) The thread priority for threads in the executor, the default is
<code>5</code> (the value of the <code>Thread.NORM_PRIORITY</code> constant)</p>
</attribute>
<attribute name="daemon" required="false">
<p>(boolean) Whether the threads should be daemon threads or not, the default is <code>true</code></p>
</attribute>
<attribute name="namePrefix" required="false">
<p>(String) The name prefix for each thread created by the executor.
The thread name for an individual thread will be <code>namePrefix+threadNumber</code></p>
</attribute>
<attribute name="maxThreads" required="false">
<p>(int) The max number of active threads in this pool, default is <code>200</code></p>
</attribute>
<attribute name="minSpareThreads" required="false">
<p>(int) The minimum number of threads (idle and active) always kept alive, default is <code>25</code></p>
</attribute>
<attribute name="maxIdleTime" required="false">
<p>(int) The number of milliseconds before an idle thread shutsdown, unless the number of active threads are less
or equal to minSpareThreads. Default value is <code>60000</code>(1 minute)</p>
</attribute>
<attribute name="maxQueueSize" required="false">
<p>(int) The maximum number of runnable tasks that can queue up awaiting
execution before we reject them. Default value is <code>Integer.MAX_VALUE</code></p>
</attribute>
<attribute name="prestartminSpareThreads" required="false">
<p>(boolean) Whether minSpareThreads should be started when starting the Executor or not,
the default is <code>false</code></p>
</attribute>
<attribute name="threadRenewalDelay" required="false">
<p>(long) If a <a href="listeners.html">ThreadLocalLeakPreventionListener</a> is configured,
it will notify this executor about stopped contexts.
After a context is stopped, threads in the pool are renewed. To avoid renewing all threads at the same time,
this option sets a delay between renewal of any 2 threads. The value is in ms,
default value is <code>1000</code> ms. If value is negative, threads are not renewed.</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

File diff suppressed because it is too large Load Diff

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

@@ -0,0 +1,284 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="globalresources.html">
&project;
<properties>
<author email="remm@apache.org">Remy Maucherat</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>The GlobalNamingResources Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>GlobalNamingResources</strong> element defines the global
JNDI resources for the <a href="server.html">Server</a>.</p>
<p>These resources are listed in the server's global JNDI resource context.
This context is distinct from the per-web-application JNDI contexts
described in
the <a href="../jndi-resources-howto.html">JNDI Resources How-To</a>.
The resources defined in this element are <strong>not</strong> visible in
the per-web-application contexts unless you explicitly link them with
<a href="context.html#Resource_Links">&lt;ResourceLink&gt;</a> elements.
</p>
</section>
<section name="Attributes">
</section>
<section name="Nested Components">
</section>
<section name="Special Features">
<subsection name="Environment Entries">
<p>You can configure named values that will be made visible to all
web applications as environment entry resources by nesting
<code>&lt;Environment&gt;</code> entries inside this element. For
example, you can create an environment entry like this:</p>
<source><![CDATA[<GlobalNamingResources ...>
...
<Environment name="maxExemptions" value="10"
type="java.lang.Integer" override="false"/>
...
</GlobalNamingResources>]]></source>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):
</p>
<source><![CDATA[<env-entry>
<env-entry-name>maxExemptions</env-entry-name>
<env-entry-value>10</env-entry-value>
<env-entry-type>java.lang.Integer</env-entry-type>
</env-entry>]]></source>
<p>but does <em>not</em> require modification of the deployment descriptor
to customize this value.</p>
<p>The valid attributes for an <code>&lt;Environment&gt;</code> element
are as follows:</p>
<attributes>
<attribute name="description" required="false">
<p>Optional, human-readable description of this environment entry.</p>
</attribute>
<attribute name="name" required="true">
<p>The name of the environment entry to be created, relative to the
<code>java:comp/env</code> context.</p>
</attribute>
<attribute name="override" required="false">
<p>Set this to <code>false</code> if you do <strong>not</strong> want
an <code>&lt;env-entry&gt;</code> for the same environment entry name,
found in the web application deployment descriptor, to override the
value specified here. By default, overrides are allowed.</p>
</attribute>
<attribute name="type" required="true">
<p>The fully qualified Java class name expected by the web application
for this environment entry. Must be a legal value for
<code>&lt;env-entry-type&gt;</code> in the web application deployment
descriptor.</p>
</attribute>
<attribute name="value" required="true">
<p>The parameter value that will be presented to the application
when requested from the JNDI context. This value must be convertable
to the Java type defined by the <code>type</code> attribute.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Resource Definitions">
<p>You can declare the characteristics of resources
to be returned for JNDI lookups of <code>&lt;resource-ref&gt;</code> and
<code>&lt;resource-env-ref&gt;</code> elements in the web application
deployment descriptor by defining them in this element and then linking
them with <a href="context.html#Resource_Links">&lt;ResourceLink&gt;</a>
elements
in the <code><strong>&lt;Context&gt;</strong></code> element.
You <strong>MUST</strong> also define any other needed parameters using
attributes on the Resource element, to configure
the object factory to be used (if not known to Tomcat already), and
the properties used to configure that object factory.</p>
<p>For example, you can create a resource definition like this:</p>
<source><![CDATA[<GlobalNamingResources ...>
...
<Resource name="jdbc/EmployeeDB" auth="Container"
type="javax.sql.DataSource"
description="Employees Database for HR Applications"/>
...
</GlobalNamingResources>]]></source>
<p>This is equivalent to the inclusion of the following element in the
web application deployment descriptor (<code>/WEB-INF/web.xml</code>):</p>
<source><![CDATA[<resource-ref>
<description>Employees Database for HR Applications</description>
<res-ref-name>jdbc/EmployeeDB</res-ref-name>
<res-ref-type>javax.sql.DataSource</res-ref-type>
<res-auth>Container</res-auth>
</resource-ref>]]></source>
<p>but does <em>not</em> require modification of the deployment
descriptor to customize this value.</p>
<p>The valid attributes for a <code>&lt;Resource&gt;</code> element
are as follows:</p>
<attributes>
<attribute name="auth" required="false">
<p>Specify whether the web Application code signs on to the
corresponding resource manager programmatically, or whether the
Container will sign on to the resource manager on behalf of the
application. The value of this attribute must be
<code>Application</code> or <code>Container</code>. This
attribute is <strong>required</strong> if the web application
will use a <code>&lt;resource-ref&gt;</code> element in the web
application deployment descriptor, but is optional if the
application uses a <code>&lt;resource-env-ref&gt;</code> instead.</p>
</attribute>
<attribute name="closeMethod" required="false">
<p>Name of the zero-argument method to call on a singleton resource when
it is no longer required. This is intended to speed up clean-up of
resources that would otherwise happen as part of garbage collection.
This attribute is ignored if the <code>singleton</code> attribute is
false. If not specified, no default is defined and no close method will
be called.</p>
<p>For Apache Commons DBCP 2 and Apache Tomcat JDBC connection pools
you can use <code>closeMethod="close"</code>. Note that Apache Commons
DBCP 2 requires this to be set for a clean shutdown. When using the
default Tomcat connection pool (based on DBCP 2) Tomcat will set this
attribute automatically unless it is explictly set to the empty
string.</p>
</attribute>
<attribute name="description" required="false">
<p>Optional, human-readable description of this resource.</p>
</attribute>
<attribute name="name" required="true">
<p>The name of the resource to be created, relative to the
<code>java:comp/env</code> context.</p>
</attribute>
<attribute name="scope" required="false">
<p>Specify whether connections obtained through this resource
manager can be shared. The value of this attribute must be
<code>Shareable</code> or <code>Unshareable</code>. By default,
connections are assumed to be shareable.</p>
</attribute>
<attribute name="singleton" required="false">
<p>Specify whether this resource definition is for a singleton resource,
i.e. one where there is only a single instance of the resource. If this
attribute is <code>true</code>, multiple JNDI lookups for this resource
will return the same object. If this attribute is <code>false</code>,
multiple JNDI lookups for this resource will return different objects.
This attribute must be <code>true</code> for
<code>javax.sql.DataSource</code> resources to enable JMX registration
of the DataSource. The value of this attribute must be <code>true</code>
or <code>false</code>. By default, this attribute is <code>true</code>.
</p>
</attribute>
<attribute name="type" required="true">
<p>The fully qualified Java class name expected by the web
application when it performs a lookup for this resource.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Resource Links">
<p>Use <a href="context.html#Resource_Links"><code>&lt;ResourceLink&gt;</code></a>
elements to link resources from the global context into
per-web-application contexts. Here is an example of making a custom
factory available to an application, based on the example definition in the
<a href="../jndi-resources-howto.html#Generic_JavaBean_Resources">
JNDI Resource How-To</a>:
</p>
<source><![CDATA[<Context>
<ResourceLink
name="bean/MyBeanFactory"
global="bean/MyBeanFactory"
type="com.mycompany.MyBean"
/>
</Context>]]></source>
</subsection>
<subsection name="Transaction">
<p>You can declare the characteristics of the UserTransaction
to be returned for JNDI lookup for <code>java:comp/UserTransaction</code>.
You <strong>MUST</strong> define an object factory class to instantiate
this object as well as the needed resource parameters as attributes of the
<code>Transaction</code>
element, and the properties used to configure that object factory.</p>
<p>The valid attributes for the <code>&lt;Transaction&gt;</code> element
are as follows:</p>
<attributes>
<attribute name="factory" required="true">
<p>The class name for the JNDI object factory.</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,668 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="host.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="remm@apache.org">Remy Maucherat</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>The Host Container</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Host</strong> element represents a <em>virtual host</em>,
which is an association of a network name for a server (such as
"www.mycompany.com") with the particular server on which Tomcat is running.
For clients to be able to connect to a Tomcat server using its network name,
this name must be registered in the <em>Domain Name Service</em> (DNS) server
that manages the Internet domain you belong to - contact your Network
Administrator for more information.</p>
<p>In many cases, System Administrators wish to associate more than
one network name (such as <code>www.mycompany.com</code> and
<code>company.com</code>) with the same virtual host and applications.
This can be accomplished using the <a href="#Host_Name_Aliases">Host
Name Aliases</a> feature discussed below.</p>
<p>One or more <strong>Host</strong> elements are nested inside an
<a href="engine.html">Engine</a> element. Inside the Host element, you
can nest <a href="context.html">Context</a> elements for the web
applications associated with this virtual host. Exactly one of the Hosts
associated with each Engine MUST have a name matching the
<code>defaultHost</code> attribute of that Engine.</p>
<p>Clients normally use host names to identify the server they wish to connect
to. This host name is also included in the HTTP request headers. Tomcat
extracts the host name from the HTTP headers and looks for a
<strong>Host</strong> with a matching name. If no match is found, the request
is routed to the default host. The name of the default host does not have to
match a DNS name (although it can) since any request where the DNS name does
not match the name of a <strong>Host</strong> element will be routed to the
default host.</p>
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat.</em></p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Host</strong>
support the following attributes:</p>
<attributes>
<attribute name="appBase" required="true">
<p>The <em>Application Base</em> directory for this virtual host.
This is the pathname of a directory that may contain web applications
to be deployed on this virtual host. You may specify an
absolute pathname, or a pathname that is relative to the
<code>$CATALINA_BASE</code> directory. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information on automatic recognition and
deployment of web applications. If not specified, the default of
<code>webapps</code> will be used.</p>
</attribute>
<attribute name="xmlBase" required="false">
<p>The <em>XML Base</em> directory for this virtual host.
This is the pathname of a directory that may contain context XML
descriptors to be deployed on this virtual host. You may specify an
absolute pathname for this directory, or a pathname that is relative
to the <code>$CATALINA_BASE</code> directory. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information on automatic recognition and
deployment of web applications. If not specified the default of
<code>conf/&lt;engine_name&gt;/&lt;host_name&gt;</code> will be used.</p>
</attribute>
<attribute name="createDirs" required="false">
<p>If set to true, Tomcat will attempt to create the directories defined
by the attributes <code>appBase</code> and <code>xmlBase</code> during
the startup phase. The default value is <code>true</code>. If set to
true, and directory creation fails, an error message will be printed out
but will not halt the startup sequence.</p>
</attribute>
<attribute name="autoDeploy" required="false">
<p>This flag value indicates if Tomcat should check periodically for new
or updated web applications while Tomcat is running. If true, Tomcat
periodically checks the <code>appBase</code> and <code>xmlBase</code>
directories and deploys any new web applications or context XML
descriptors found. Updated web applications or context XML descriptors
will trigger a reload of the web application. The flag's value defaults
to true. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
</attribute>
<attribute name="backgroundProcessorDelay" required="false">
<p>This value represents the delay in seconds between the
invocation of the backgroundProcess method on this host and
its child containers, including all contexts.
Child containers will not be invoked if their delay value is not
negative (which would mean they are using their own processing
thread). Setting this to a positive value will cause
a thread to be spawn. After waiting the specified amount of time,
the thread will invoke the backgroundProcess method on this host
and all its child containers. A host will use background processing to
perform live web application deployment related tasks. If not
specified, the default value for this attribute is -1, which means
the host will rely on the background processing setting of its parent
engine.</p>
</attribute>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Host</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="deployIgnore" required="false">
<p>A regular expression defining paths to ignore when
<code>autoDeploy</code> and <code>deployOnStartup</code> are set. This
allows you to keep your configuration in a version control system, for
example, and not deploy a .svn or CVS folder that happens to be in the
<code>appBase</code>.</p>
<p>This regular expression is relative to <code>appBase</code>. It is
also <em>anchored</em>, meaning the match is performed against the
entire file/directory name. So, <code>foo</code> matches only a file or
directory named <code>foo</code> but not <code>foo.war</code>,
<code>foobar</code>, or <code>myfooapp</code>. To match anything with
&quot;foo&quot;, you could use <code>.*foo.*</code>.</p>
<p>See <a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
</attribute>
<attribute name="deployOnStartup" required="false">
<p>This flag value indicates if web applications from this host should
be automatically deployed when Tomcat starts. The flag's value defaults
to true. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
</attribute>
<attribute name="failCtxIfServletStartFails" required="false">
<p>Set to <code>true</code> to have each child contexts fail its startup
if any of its servlet that has load-on-startup &gt;=0 fails its own
startup.</p>
<p>Each child context may override this attribute.</p>
<p>If not specified, the default value of <code>false</code> is
used.</p>
</attribute>
<attribute name="name" required="true">
<p>Usually the network name of this virtual host, as registered in your
<em>Domain Name Service</em> server. Regardless of the case used to
specify the host name, Tomcat will convert it to lower case internally.
One of the Hosts nested within an <a href="engine.html">Engine</a> MUST
have a name that matches the <code>defaultHost</code> setting for that
Engine. See <a href="#Host_Name_Aliases">Host Name Aliases</a> for
information on how to assign more than one network name to the same
virtual host. If the name takes the form of <code>*.domainname</code>
(e.g. <code>*.apache.org</code>) then it will be treated as a match for
any host in that domain unless a host that has an exactly matching name
is found.</p>
</attribute>
<attribute name="startStopThreads" required="false">
<p>The number of threads this <strong>Host</strong> will use to start
child <a href="context.html">Context</a> elements in parallel. The same
thread pool will be used to deploy new
<a href="context.html">Context</a>s if automatic deployment is being
used. The special value of 0 will result in the value of
<code>Runtime.getRuntime().availableProcessors()</code> being used.
Negative values will result in
<code>Runtime.getRuntime().availableProcessors() + value</code> being
used unless this is less than 1 in which case 1 thread will be used. If
not specified, the default value of 1 will be used.</p>
</attribute>
<attribute name="undeployOldVersions" required="false">
<p>This flag determines if Tomcat, as part of the auto deployment
process, will check for old, unused versions of web applications
deployed using parallel deployment and, if any are found, remove them.
This flag only applies if <code>autoDeploy</code> is true. If not
specified the default value of false will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Host</strong> is
<strong>org.apache.catalina.core.StandardHost</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="copyXML" required="false">
<p>Set to <code>true</code> if you want a context XML descriptor
embedded inside the application (located at
<code>/META-INF/context.xml</code>) to be copied to <code>xmlBase</code>
when the application is deployed. On subsequent starts, the copied
context XML descriptor will be used in preference to any context XML
descriptor embedded inside the application even if the descriptor
embedded inside the application is more recent. The flag's value
defaults to <code>false</code>. Note if <strong>deployXML</strong>
is <code>false</code>, this attribute will have no effect.</p>
</attribute>
<attribute name="deployXML" required="false">
<p>Set to <code>false</code> if you want to disable parsing the context
XML descriptor embedded inside the application (located at
<code>/META-INF/context.xml</code>). Security conscious environments
should set this to <code>false</code> to prevent applications from
interacting with the container's configuration. The administrator will
then be responsible for providing an external context configuration
file, and putting it in the location defined by the
<strong>xmlBase</strong> attribute. If this flag is <code>false</code>,
a descriptor is located at <code>/META-INF/context.xml</code> and no
descriptor is present in <strong>xmlBase</strong> then the context will
fail to start in case the descriptor contains necessary configuration
for secure deployment (such as a RemoteAddrValve) which should not be
ignored. The flag's value defaults to <code>true</code> unless a
security manager is enabled when the default is <code>false</code>.
When running under a security manager this may be enabled on a per web
application basis by granting the
<code>org.apache.catalina.security.DeployXmlPermission</code> to the web
application. The Manager and Host Manager applications are granted this
permission by default so that they continue to work when running under a
security manager.</p>
</attribute>
<attribute name="errorReportValveClass" required="false">
<p>Java class name of the error reporting valve which will be used
by this Host. The responsibility of this valve is to output error
reports. Setting this property allows to customize the look of the
error pages which will be generated by Tomcat. This class must
implement the
<code>org.apache.catalina.Valve</code> interface. If none is specified,
the value <code>org.apache.catalina.valves.ErrorReportValve</code>
will be used by default.</p>
</attribute>
<attribute name="unpackWARs" required="false">
<p>Set to <code>true</code> if you want web applications that are
placed in the <code>appBase</code> directory as web application
archive (WAR) files to be unpacked into a corresponding disk directory
structure, <code>false</code> to run such web applications directly
from a WAR file. See
<a href="#Automatic_Application_Deployment">Automatic Application
Deployment</a> for more information.</p>
<p>Note: If Tomcat expands the WAR file then it will add a file
(<code>/META-INF/war-tracking</code>) to the unpacked directory
structure which it uses to detect changes in the WAR file while Tomcat
is not running. Any such change will trigger the deletion of the
expanded directory and the deployment of the updated WAR file when
Tomcat next starts.</p>
<p>Note: Running with this option set to <code>false</code> will incur
a performance penalty. To avoid a significant performance penalty, the
web application should be configured such that class scanning for
Servlet 3.0+ pluggability features is not required. Users may also wish
to consider the <strong>ExtractingRoot</strong>
<a href="resources.html">Resources</a> implementation.</p>
</attribute>
<attribute name="workDir" required="false">
<p>Pathname to a scratch directory to be used by applications for
this Host. Each application will have its own sub directory with
temporary read-write use. Configuring a Context workDir will override
use of the Host workDir configuration. This directory will be made
visible to servlets in the web application by a servlet context
attribute (of type <code>java.io.File</code>) named
<code>javax.servlet.context.tempdir</code> as described in the
Servlet Specification. If not specified, a suitable directory
underneath <code>$CATALINA_BASE/work</code> will be provided.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>You can nest one or more <a href="context.html">Context</a> elements
inside this <strong>Host</strong> element, each representing a different web
application associated with this virtual host.</p>
<p>You can nest at most one instance of the following utility components
by nesting a corresponding element inside your <strong>Host</strong>
element:</p>
<ul>
<li><a href="realm.html"><strong>Realm</strong></a> -
Configure a realm that will allow its
database of users, and their associated roles, to be shared across all
<a href="context.html">Contexts</a> nested inside this Host (unless
overridden by a <a href="realm.html">Realm</a> configuration
at a lower level).</li>
</ul>
</section>
<section name="Special Features">
<subsection name="Logging">
<p>A host is associated with the
<code>org.apache.catalina.core.ContainerBase.[engine_name].[host_name]</code>
log category. Note that the brackets are part of the name,
don't omit them.</p>
</subsection>
<subsection name="Access Logs">
<p>When you run a web server, one of the output files normally generated
is an <em>access log</em>, which generates one line of information for
each request processed by the server, in a standard format. Catalina
includes an optional <a href="valve.html">Valve</a> implementation that
can create access logs in the same standard format created by web servers,
or in any number of custom formats.</p>
<p>You can ask Catalina to create an access log for all requests
processed by an <a href="engine.html">Engine</a>,
<a href="host.html">Host</a>, or <a href="context.html">Context</a>
by nesting a <a href="valve.html">Valve</a> element like this:</p>
<source><![CDATA[<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log" suffix=".txt"
pattern="common"/>
...
</Host>]]></source>
<p>See <a href="valve.html#Access_Logging">Access Logging Valves</a>
for more information on the configuration attributes that are
supported.</p>
</subsection>
<subsection name="Automatic Application Deployment">
<p>If you are using the standard <strong>Host</strong> implementation with
default settings then applications in the <em>appBase</em> or with context
files in the <em>configBase</em> are automatically deployed when Tomcat
starts (the <code>deployOnStartup</code> property defaults to
<code>true</code>) and reloaded or redeployed (as appropriate) when a change
is detected while Tomcat is running (the <code>autoDeploy</code> attribute
also defaults to <code>true</code>).</p>
<p><code>deployOnStartup</code> and <code>autoDeploy</code> trigger
execution of exactly the same code so the behaviour is very similar.
However, there is one key difference. When Tomcat starts it has no knowledge
of which files are the same, which have been changed and which are new. It
therefore treats all files as new. While Tomcat is running, it can
differentiate between unchanged, modified and new files. This leads to some
differences in behaviour between files being modified while Tomcat is
running and files being modified while Tomcat is stopped.</p>
<p>When you use automatic deployment, related files (a web application may
have a context.xml file, a WAR and a directory) that exist in the
<strong>Host</strong>&apos;s <em>appBase</em> and/or <em>configBase</em>
must conform to the expected <a href="context.html#Naming">naming
convention</a>. In short, this means files for the same web application must
share the same <em>base name</em>.</p>
<p>The automatic deployment process identifies new and/or modified web
applications using the following search order:</p>
<ol>
<li>Web applications with a context.xml file located in the Host&apos;s
<em>configBase</em>.</li>
<li>Web applications with a WAR file located in the Host&apos;s
<em>appBase</em> that have not already been identified during the scan for
context.xml files.</li>
<li>Web applications with a directory located in the Host&apos;s
<em>appBase</em> that have not already been identified during the scans
for context.xml and/or WAR files.</li>
</ol>
<p>When <code>autoDeploy</code> is <code>true</code>, the automatic
deployment process will monitor the deployed web applications for changes.
Depending on exactly what changes, the web application will either be
re-deployed or reloaded. Re-deployment involves the creation of a new web
application and, if using the standard session manager, user sessions will
not be retained. Reloading uses the existing web application but re-parses
the web.xml and reloads any classes. If using the standard session manager,
user sessions will be persisted.</p>
<p>Users may add to the files that the automatic deployment process monitors
for reloading (i.e. any change to one of these files triggers a reload of
the web application) by adding a <em>WatchedResources</em> element to the
context.xml file. See the
<a href="context.html#Nested_Components">Context</a> documentation for
further details.</p>
<p>When using automatic deployment, the <code>docBase</code> defined by
an XML <a href="context.html">Context</a> file should be outside of the
<code>appBase</code> directory. If this is not the case, difficulties
may be experienced deploying the web application or the application may
be deployed twice. The <code>deployIgnore</code> attribute can be used
to avoid this situation.</p>
<p>Note that if you are defining contexts explicitly in server.xml, you
should probably turn off automatic application deployment or specify
<code>deployIgnore</code> carefully. Otherwise, the web applications
will each be deployed twice, and that may cause problems for the
applications.</p>
<p>There are many possible combinations of settings, new files, changed
files and deleted files. A separate page describes the
<a href="automatic-deployment.html">expected behaviour of the automatic
deployment process</a> in many of these scenarios.</p>
</subsection>
<subsection name="Host Name Aliases">
<p>In many server environments, Network Administrators have configured
more than one network name (in the <em>Domain Name Service</em> (DNS)
server), that resolve to the IP address of the same server. Normally,
each such network name would be configured as a separate
<strong>Host</strong> element in <code>conf/server.xml</code>, each
with its own set of web applications.</p>
<p>However, in some circumstances, it is desirable that two or more
network names should resolve to the <strong>same</strong> virtual host,
running the same set of applications. A common use case for this
scenario is a corporate web site, where it is desirable that users
be able to utilize either <code>www.mycompany.com</code> or
<code>company.com</code> to access exactly the same content and
applications.</p>
<p>This is accomplished by utilizing one or more <strong>Alias</strong>
elements nested inside your <strong>Host</strong> element. For
example:</p>
<source><![CDATA[<Host name="www.mycompany.com" ...>
...
<Alias>mycompany.com</Alias>
...
</Host>]]></source>
<p>In order for this strategy to be effective, all of the network names
involved must be registered in your DNS server to resolve to the
same computer that is running this instance of Catalina.</p>
<p>Aliases may also use the wildcard form (<code>*.domainname</code>)
permitted for the <strong>name</strong> attribute of a
<strong>Host</strong>.</p>
</subsection>
<subsection name="Lifecycle Listeners">
<p>If you have implemented a Java object that needs to know when this
<strong>Host</strong> is started or stopped, you can declare it by
nesting a <strong>Listener</strong> element inside this element. The
class name you specify must implement the
<code>org.apache.catalina.LifecycleListener</code> interface, and
it will be notified about the occurrence of the corresponding
lifecycle events. Configuration of such a listener looks like this:</p>
<source><![CDATA[<Host name="localhost" ...>
...
<Listener className="com.mycompany.mypackage.MyListener" ... >
...
</Host>]]></source>
<p>Note that a Listener can have any number of additional properties
that may be configured from this element. Attribute names are matched
to corresponding JavaBean property names using the standard property
method naming patterns.</p>
</subsection>
<subsection name="Request Filters">
<p>You can ask Catalina to check the IP address, or host name, on every
incoming request directed to the surrounding
<a href="engine.html">Engine</a>, <a href="host.html">Host</a>, or
<a href="context.html">Context</a> element. The remote address or name
will be checked against configured "accept" and/or "deny"
filters, which are defined using <code>java.util.regex</code> Regular
Expression syntax. Requests that come from locations that are
not accepted will be rejected with an HTTP "Forbidden" error.
Example filter declarations:</p>
<source><![CDATA[<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192\.168\.1\.\d+"/>
...
</Host>]]></source>
<p>See <a href="valve.html#Remote_Address_Filter">Remote Address Filter</a>
and <a href="valve.html#Remote_Host_Filter">Remote Host Filter</a> for
more information about the configuration options that are supported.</p>
</subsection>
<subsection name="Single Sign On">
<p>In many environments, but particularly in portal environments, it
is desirable to have a user challenged to authenticate themselves only
once over a set of web applications deployed on a particular virtual
host. This can be accomplished by nesting an element like this inside
the Host element for this virtual host:</p>
<source><![CDATA[<Host name="localhost" ...>
...
<Valve className="org.apache.catalina.authenticator.SingleSignOn"/>
...
</Host>]]></source>
<p>The Single Sign On facility operates according to the following rules:
</p>
<ul>
<li>All web applications configured for this virtual host must share the
same <a href="realm.html">Realm</a>. In practice, that means you can
nest the Realm element inside this Host element (or the surrounding
<a href="engine.html">Engine</a> element), but not inside a
<a href="context.html">Context</a> element for one of the involved
web applications.</li>
<li>As long as the user accesses only unprotected resources in any of the
web applications on this virtual host, they will not be challenged
to authenticate themselves.</li>
<li>As soon as the user accesses a protected resource in
<strong>any</strong> web application associated with this virtual
host, the user will be challenged to authenticate himself or herself,
using the login method defined for the web application currently
being accessed.</li>
<li>Once authenticated, the roles associated with this user will be
utilized for access control decisions across <strong>all</strong>
of the associated web applications, without challenging the user
to authenticate themselves to each application individually.</li>
<li>As soon as the user logs out of one web application (for example,
by invalidating the corresponding session if form
based login is used), the user's sessions in <strong>all</strong>
web applications will be invalidated. Any subsequent attempt to
access a protected resource in any application will require the
user to authenticate himself or herself again.</li>
<li>The Single Sign On feature utilizes HTTP cookies to transmit a token
that associates each request with the saved user identity, so it can
only be utilized in client environments that support cookies.</li>
</ul>
</subsection>
<subsection name="User Web Applications">
<p>Many web servers can automatically map a request URI starting with
a tilde character ("~") and a username to a directory (commonly named
<code>public_html</code>) in that user's home directory on the server.
You can accomplish the same thing in Catalina by using a special
<strong>Listener</strong> element like this (on a Unix system that
uses the <code>/etc/passwd</code> file to identify valid users):</p>
<source><![CDATA[<Host name="localhost" ...>
...
<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
userClass="org.apache.catalina.startup.PasswdUserDatabase"/>
...
</Host>]]></source>
<p>On a server where <code>/etc/passwd</code> is not in use, you can
request Catalina to consider all directories found in a specified base
directory (such as <code>c:\Homes</code> in this example) to be
considered "user home" directories for the purposes of this directive:</p>
<source><![CDATA[<Host name="localhost" ...>
...
<Listener className="org.apache.catalina.startup.UserConfig"
directoryName="public_html"
homeBase="c:\Homes"
userClass="org.apache.catalina.startup.HomesUserDatabase"/>
...
</Host>]]></source>
<p>If a user home directory has been set up for a user named
<code>craigmcc</code>, then its contents will be visible from a
client browser by making a request to a URL like:</p>
<source>http://www.mycompany.com:8080/~craigmcc</source>
<p>Successful use of this feature requires recognition of the following
considerations:</p>
<ul>
<li>Each user web application will be deployed with characteristics
established by the global and host level default context settings.</li>
<li>It is legal to include more than one instance of this Listener
element. This would only be useful, however, in circumstances
where you wanted to configure more than one "homeBase" directory.</li>
<li>The operating system username under which Catalina is executed
MUST have read access to each user's web application directory,
and all of its contents.</li>
</ul>
</subsection>
<subsection name="Custom context.xml and web.xml">
<p>You can override the default values found in <code>conf/context.xml</code> and
<code>conf/web.xml</code> files from <code>$CATALINA_BASE</code> for each virtual host.
Tomcat will look for files named <code>context.xml.default</code> and <code>web.xml.default</code>
in the directory specified by <code>xmlBase</code> and merge the files into
those found in the default ones.</p>
</subsection>
</section>
</body>
</document>

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

File diff suppressed because it is too large Load Diff

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

@@ -0,0 +1,308 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="http2.html">
&project;
<properties>
<title>The HTTP2 Upgrade Protocol</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>HTTP Upgrade Protocol</strong> element represents an
<strong>Upgrade Protocol</strong> component that supports the HTTP/2 protocol.
An instance of this component must be associated with an existing
<a href="http.html">HTTP/1.1 Connector</a>.</p>
<p>HTTP/2 connectors use non-blocking I/O, only utilising a container thread
from the thread pool when there is data to read and write. However, because
the Servlet API is fundamentally blocking, each HTTP/2 stream requires a
dedicated container thread for the duration of that stream.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Upgrade Protocol</strong> support the
following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>This must be <code>org.apache.coyote.http2.Http2Protocol</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The HTTP/2 <strong>Upgrade Protocol</strong> implementation supports the
following attributes in addition to the common attributes listed above.</p>
<attributes>
<attribute name="allowedTrailerHeaders" required="false">
<p>By default Tomcat will ignore all trailer headers when processing
HTTP/2 connections. For a header to be processed, it must be added to this
comma-separated list of header names.</p>
</attribute>
<attribute name="compressibleMimeType" required="false">
<p>The value is a comma separated list of MIME types for which HTTP
compression may be used.
The default value is
<code>
text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json,application/xml
</code>.
</p>
</attribute>
<attribute name="compression" required="false">
<p>The HTTP/2 protocol may use compression in an attempt to save server
bandwidth. The acceptable values for the parameter is "off" (disable
compression), "on" (allow compression, which causes text data to be
compressed), "force" (forces compression in all cases), or a numerical
integer value (which is equivalent to "on", but specifies the minimum
amount of data before the output is compressed). If the content-length is
not known and compression is set to "on" or more aggressive, the output
will also be compressed. If not specified, this attribute is set to
"off".</p>
<p><em>Note</em>: There is a tradeoff between using compression (saving
your bandwidth) and using the sendfile feature (saving your CPU cycles).
If the connector supports the sendfile feature, e.g. the NIO2 connector,
using sendfile will take precedence over compression. The symptoms will
be that static files greater that 48 Kb will be sent uncompressed.
You can turn off sendfile by setting <code>useSendfile</code> attribute
of the protocol, as documented below, or change the sendfile usage
threshold in the configuration of the
<a href="../default-servlet.html">DefaultServlet</a> in the default
<code>conf/web.xml</code> or in the <code>web.xml</code> of your web
application.
</p>
</attribute>
<attribute name="compressionMinSize" required="false">
<p>If <strong>compression</strong> is set to "on" then this attribute
may be used to specify the minimum amount of data before the output is
compressed. If not specified, this attribute is defaults to "2048".</p>
</attribute>
<attribute name="initialWindowSize" required="false">
<p>Controls the initial size of the flow control window for streams that
Tomcat advertises to clients. If not specified, the default value of
<code>65535</code> is used.</p>
</attribute>
<attribute name="keepAliveTimeout" required="false">
<p>The time, in milliseconds, that Tomcat will wait between HTTP/2 frames
when there is no active Stream before closing the connection. Negative
values will be treated as an infinite timeout. If not specified, a default
value of <code>20000</code> will be used.</p>
</attribute>
<attribute name="maxConcurrentStreamExecution" required="false">
<p>The controls the maximum number of streams for any one connection that
can be allocated threads from the container thread pool. If more streams
are active than threads are available, those streams will have to wait
for a stream to become available. If not specified, the default value of
<code>20</code> will be used.</p>
</attribute>
<attribute name="maxConcurrentStreams" required="false">
<p>The controls the maximum number of active streams permitted for any one
connection. If a client attempts to open more active streams than this
limit, the stream will be reset with a <code>STREAM_REFUSED</code> error.
If not specified, the default value of <code>100</code> will be used.</p>
</attribute>
<attribute name="maxHeaderCount" required="false">
<p>The maximum number of headers in a request that is allowed by the
container. A request that contains more headers than the specified limit
will be rejected. A value of less than 0 means no limit.
If not specified, a default of 100 is used.</p>
</attribute>
<attribute name="maxHeaderSize" required="false">
<p>The maximum total size for all headers in a request that is allowed by
the container. Total size for a header is calculated as the uncompressed
size of the header name in bytes, plus the uncompressed size of the header
value in bytes plus an HTTP/2 overhead of 3 bytes per header. A request
that contains a set of headers that requires more than the specified limit
will be rejected. A value of less than 0 means no limit. If not specified,
a default of 8192 is used.</p>
</attribute>
<attribute name="maxTrailerCount" required="false">
<p>The maximum number of trailer headers in a request that is allowed by
the container. A request that contains more trailer headers than the
specified limit will be rejected. A value of less than 0 means no limit.
If not specified, a default of 100 is used.</p>
</attribute>
<attribute name="maxTrailerSize" required="false">
<p>The maximum total size for all trailer headers in a request that is
allowed by the container. Total size for a header is calculated as the
uncompressed size of the header name in bytes, plus the uncompressed size
of the header value in bytes plus an HTTP/2 overhead of 3 bytes per
header. A request that contains a set of trailer headers that requires
more than the specified limit will be rejected. A value of less than 0
means no limit. If not specified, a default of 8192 is used.</p>
</attribute>
<attribute name="noCompressionStrongETag" required="false">
<p>This flag configures whether resources with a stong ETag will be
considered for compression. If <code>true</code>, resources with a strong
ETag will not be compressed. The default value is <code>true</code>.</p>
<p>This attribute is deprecated. It will be removed in Tomcat 10 onwards
where it will be hard-coded to <code>true</code>.</p>
</attribute>
<attribute name="noCompressionUserAgents" required="false">
<p>The value is a regular expression (using <code>java.util.regex</code>)
matching the <code>user-agent</code> header of HTTP clients for which
compression should not be used,
because these clients, although they do advertise support for the
feature, have a broken implementation.
The default value is an empty String (regexp matching disabled).</p>
</attribute>
<attribute name="overheadContinuationThreshold" required="false">
<p>The threshold below which the payload size of a non-final
<code>CONTINUATION</code> frame will trigger an increase in the overhead
count (see <strong>overheadCountFactor</strong>). The overhead count will
be increased by <code>overheadContinuationThreshold/payloadSize</code> so
that the smaller the <code>CONTINUATION</code> frame, the greater the
increase in the overhead count. A value of zero or less disables the
checking of non-final <code>CONTINUATION</code> frames. If not specified,
a default value of <code>1024</code> will be used.</p>
</attribute>
<attribute name="overheadCountFactor" required="false">
<p>The factor to apply when counting overhead frames to determine if a
connection has too high an overhead and should be closed. The overhead
count starts at <code>-10</code>. The count is decreased for each
data frame sent or received and each headers frame received. The count is
increased by the <code>overheadCountFactor</code>for each setting
received, priority frame received and ping received. If the overhead count
exceeds zero, the connection is closed. A value of less than
<code>1</code> disables this protection. In normal usage a value of
<code>3</code> or more will close the connection before any streams can
complete. If not specified, a default value of <code>1</code> will be
used.</p>
</attribute>
<attribute name="overheadDataThreshold" required="false">
<p>The threshold below which the average payload size of the current and
previous non-final <code>DATA</code> frames will trigger an increase in
the overhead count (see <strong>overheadCountFactor</strong>). The
overhead count will be increased by
<code>overheadDataThreshold/average</code> so that the smaller the
average, the greater the increase in the overhead count. A value of zero
or less disables the checking of non-final <code>DATA</code> frames. If
not specified, a default value of <code>1024</code> will be used.</p>
</attribute>
<attribute name="overheadWindowUpdateThreshold" required="false">
<p>The threshold below which the average size of current and previous
<code>WINDOW_UPDATE</code> frame will trigger an increase in the overhead
count (see <strong>overheadCountFactor</strong>). The overhead count will
be increased by <code>overheadWindowUpdateThreshold/average</code> so
that the smaller the average, the greater the increase in the overhead
count. A value of zero or less disables the checking of
<code>WINDOW_UPDATE</code> frames. If not specified, a default value of
<code>1024</code> will be used.</p>
</attribute>
<attribute name="readTimeout" required="false">
<p>The time, in milliseconds, that Tomcat will wait for additional data
when a partial HTTP/2 frame has been received. Negative values will be
treated as an infinite timeout. If not specified, a default value of
<code>5000</code> will be used.</p>
</attribute>
<attribute name="streamReadTimeout" required="false">
<p>The time, in milliseconds, that Tomcat will wait for additional data
frames to arrive for the stream when an application is performing a
blocking I/O read and additional data is required. Negative values will be
treated as an infinite timeout. If not specified, a default value of
<code>20000</code> will be used.</p>
</attribute>
<attribute name="streamWriteTimeout" required="false">
<p>The time, in milliseconds, that Tomcat will wait for additional window
update frames to arrive for the stream and/or conenction when an
application is performing a blocking I/O write and the stream and/or
connection flow control window is too small for the write to complete.
Negative values will be treated as an infinite timeout. If not specified,
a default value of <code>20000</code> will be used.</p>
</attribute>
<attribute name="writeTimeout" required="false">
<p>The time, in milliseconds, that Tomcat will wait to write additional
data when an HTTP/2 frame has been partially written. Negative values will
be treated as an infinite timeout. If not specified, a default value of
<code>5000</code> will be used.</p>
</attribute>
</attributes>
<p>The HTTP/2 upgrade protocol will also inherit the following limits from the
<a href="http.html">HTTP Connector</a> it is nested with:</p>
<ul>
<li>maxCookieCount</li>
<li>maxParameterCount</li>
<li>maxPostSize</li>
<li>maxSavePostSize</li>
</ul>
</subsection>
</section>
<section name="Nested Components">
<p>This component does not support any nested components.</p>
</section>
<section name="Special Features">
<p>This component does not support any special features.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,96 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="index.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>Overview</title>
</properties>
<body>
<section name="Overview">
<p>This manual contains reference information about all of the configuration
directives that can be included in a <code>conf/server.xml</code> file to
configure the behavior of the Tomcat Servlet/JSP container. It does not
attempt to describe which configuration directives should be used to perform
specific tasks - for that, see the various <em>How-To</em> documents on the
main index page.</p>
<p>Tomcat configuration files are formatted as schemaless XML; elements and
attributes are case-sensitive. Apache Ant-style variable substitution
is supported; a system property with the name <code>propname</code> may be
used in a configuration file using the syntax <code>${propname}</code>. All
system properties are available including those set using the <code>-D</code>
syntax, those automatically made available by the JVM and those configured in
the <code>$CATALINA_BASE/conf/catalina.properties</code> file.
</p>
<p>The configuration element descriptions are organized into the following
major categories:</p>
<ul>
<li><strong>Top Level Elements</strong> - <code>&lt;Server&gt;</code> is the
root element of the entire configuration file, while
<code>&lt;Service&gt;</code> represents a group of Connectors that is
associated with an Engine.</li>
<li><strong>Connectors</strong> - Represent the interface between external
clients sending requests to (and receiving responses from) a particular
Service.</li>
<li><strong>Containers</strong> - Represent components whose function is to
process incoming requests, and create the corresponding responses.
An Engine handles all requests for a Service, a Host handles all requests
for a particular virtual host, and a Context handles all requests for a
specific web application.</li>
<li><strong>Nested Components</strong> - Represent elements that can be
nested inside the element for a Container. Some elements can be nested
inside any Container, while others can only be nested inside a
Context.</li>
</ul>
<p>For each element, the corresponding documentation follows this general
outline:</p>
<ul>
<li><strong>Introduction</strong> - Overall description of this particular
component. There will be a corresponding Java <em>interface</em> (in
the <code>org.apache.catalina</code> package) that is implemented by one
or more standard implementations.</li>
<li><strong>Attributes</strong> - The set of attributes that are legal for
this element. Generally, this will be subdivided into <em>Common</em>
attributes that are supported by all implementations of the corresponding
Java interface, and <em>Standard Implementation</em> attributes that are
specific to a particular Java class that implements this interface.
The names of required attributes are <strong>bolded</strong>.</li>
<li><strong>Nested Components</strong> - Enumerates which of the <em>Nested
Components</em> can be legally nested within this element.</li>
<li><strong>Special Features</strong> - Describes the configuration of a large
variety of special features (specific to each element type) that are
supported by the standard implementation of this interface.</li>
</ul>
</section>
</body>
</document>

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

@@ -0,0 +1,191 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="jar-scan-filter.html">
&project;
<properties>
<title>The Jar Scan Filter Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Jar Scan Filter</strong> element represents the component that
filters results from the <a href="jar-scanner.html">Jar Scanner</a> before
they are passed back to the application. It is typically used to skip the
scanning of JARs that are known not to be relevant to some or all types of
scan.</p>
<p>A Jar Scan Filter element MAY be nested inside a
<a href="jar-scanner.html">Jar Scanner</a> component.</p>
<p>For example you can specify additional jar files when scanning for pluggable
features:</p>
<source><![CDATA[<Context>
...
<JarScanner>
<JarScanFilter
pluggabilityScan="${tomcat.util.scan.StandardJarScanFilter.jarsToScan},
my_pluggable_feature.jar"/>
</JarScanner>
...
</Context>]]></source>
<p>If a Jar Scan Filter element is not included, a default Jar Scan Filter
configuration will be created automatically, which is sufficient for most
requirements.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Jar Scan Filter</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.tomcat.JarScanFilter</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Jar Scan Filter</strong> is
<strong>org.apache.tomcat.util.scan.StandardJarScanFilter</strong>.
Additional attributes that it supports (in addition to the common attributes
listed above) are listed in the table.</p>
<p>The values for <strong>pluggabilitySkip</strong>,
<strong>pluggabilityScan</strong>, <strong>tldSkip</strong>,
<strong>tldScan</strong> attributes are lists of file name pattern. The
patterns are separated by comma (','). The leading and trailing whitespace
characters in a pattern are ignored. The patterns are matched
case-sensitively. The following two special characters are supported:</p>
<ul>
<li>'*' - means zero or more characters,</li>
<li>'?' - means one and only one character.</li>
</ul>
<p>Note that excluding a JAR from the pluggability scan will prevent a
ServletContainerInitializer from being loaded from a web application JAR
(i.e. one located in <code>/WEB-INF/lib</code>) but it will not prevent
a ServletContainerInitializer from being loaded from the container (Tomcat).
To prevent a ServletContainerInitializer provided by container from being
loaded, use the <code>containerSciFilter</code> property of the
<a href="context.html">Context</a>.</p>
<attributes>
<attribute name="pluggabilitySkip" required="false">
<p>The comma separated list of JAR file name patterns
to skip when scanning for pluggable features introduced by Servlet 3.0
specification. If not specified, the default is obtained from the
<code>tomcat.util.scan.StandardJarScanFilter.jarsToSkip</code> system
property.</p>
</attribute>
<attribute name="pluggabilityScan" required="false">
<p>The comma separated list of JAR file name patterns
to scan when scanning for pluggable features introduced by Servlet 3.0
specification. If not specified, the default is obtained from the
<code>tomcat.util.scan.StandardJarScanFilter.jarsToScan</code> system
property.</p>
</attribute>
<attribute name="defaultPluggabilityScan" required="false">
<p>Controls if JARs are scanned or skipped by default when scanning
for the pluggable features.
If <code>true</code>, a JAR is scanned when its name either matches
none of <strong>pluggabilitySkip</strong> patterns or
any of <strong>pluggabilityScan</strong> patterns.
If <code>false</code>, a JAR is scanned when its name matches
any of <strong>pluggabilityScan</strong> patterns and
none of <strong>pluggabilitySkip</strong> patterns.
If not specified, the default value is <code>true</code>.</p>
</attribute>
<attribute name="tldSkip" required="false">
<p>The comma separated list of JAR file name patterns
to skip when scanning for tag libraries (TLDs).
If not specified, the default is obtained
from the <code>tomcat.util.scan.StandardJarScanFilter.jarsToSkip</code>
system property.</p>
</attribute>
<attribute name="tldScan" required="false">
<p>The comma separated list of JAR file name patterns
to scan when scanning for tag libraries (TLDs).
If not specified, the default is obtained
from the <code>tomcat.util.scan.StandardJarScanFilter.jarsToScan</code>
system property.</p>
</attribute>
<attribute name="defaultTldScan" required="false">
<p>Controls if JARs are scanned or skipped by default when scanning
for TLDs.
If <code>true</code>, a JAR is scanned when its name either matches
none of <strong>tldSkip</strong> patterns or
any of <strong>tldScan</strong> patterns.
If <code>false</code>, a JAR is scanned when its name matches
any of <strong>tldScan</strong> patterns and
none of <strong>tldSkip</strong> patterns.
If not specified, the default value is <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Jar Scan Filter</strong> element.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Jar Scan Filter</strong>
element.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,147 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="jar-scanner.html">
&project;
<properties>
<title>The Jar Scanner Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Jar Scanner</strong> element represents the component that is
used to scan the web application for JAR files and directories of class files.
It is typically used during web application start to identify configuration
files such as TLDs or web-fragment.xml files that must be processed as part of
the web application initialisation.</p>
<p>A Jar Scanner element MAY be nested inside a
<a href="context.html">Context</a> component.</p>
<p>For example you can include the bootstrap classpath when scanning for jar
files:</p>
<source><![CDATA[<Context>
...
<JarScanner scanBootstrapClassPath="true"/>
...
</Context>]]></source>
<p>If a Jar Scanner element is not included, a default Jar Scanner configuration
will be created automatically, which is sufficient for most requirements.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Jar Scanner</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.tomcat.JarScanner</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Jar Scanner</strong> is
<strong>org.apache.tomcat.util.scan.StandardJarScanner</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="scanAllDirectories" required="false">
<p>If <code>true</code>, any directories found on the classpath will be
checked to see if they are expanded JAR files.
The default is <code>false</code>.</p>
<p>Tomcat determines if a directory is an expanded JAR file by looking
for a META-INF sub-directory. Only if the META-INF sub-directory exists,
the directory is assumed to be an expanded JAR file. Note that for scans
for matches to <code>@HandlesTypes</code> annotations, all directories
will be scanned irrespective of the presence or not of a META-INF
sub-directory.</p>
</attribute>
<attribute name="scanAllFiles" required="false">
<p>If <code>true</code>, any files found on the classpath will be checked
to see if they are Jar files rather than relying on the file extension
being <code>.jar</code>. The default is <code>false</code>.</p>
</attribute>
<attribute name="scanClassPath" required="false">
<p>If <code>true</code>, the full web application classpath, including
the shared and common classloaders and the system classpath (but not the
bootstrap classpath) will be scanned for Jar files in addition to the web
application. The default is <code>true</code>.</p>
</attribute>
<attribute name="scanBootstrapClassPath" required="false">
<p>If <strong>scanClassPath</strong> is <code>true</code> and this is
<code>true</code> the bootstrap classpath will also be scanned for Jar
files. The default is <code>false</code>.</p>
</attribute>
<attribute name="scanManifest" required="false">
<p>If <code>true</code>, the Manifest files of any JARs found will be
scanned for additional class path entries and those entries will be added
to the URLs to scan. The default is <code>true</code>.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>Only a <a href="jar-scan-filter.html">Jar Scan Filter</a> may be nested
inside a <strong>Jar Scanner</strong> element.</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Jar Scanner</strong>
element.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,186 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="jaspic.html">
&project;
<properties>
<title>JASPIC</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<p>Tomcat implements JASPIC 1.1 Maintenance Release B
(<a href="https://www.jcp.org/en/jsr/detail?id=196">JSR 196</a>). The
implementation is primarily intended to enable the integration of 3rd party
JASPIC authentication implementations with Tomcat.</p>
<p>JASPIC may be configured dynamically by an application or statically via
the <code>$CATALINA_BASE/conf/jaspic-providers.xml</code> configuration file.
If present, a JASPIC configuration will over-ride any
<code>&lt;login-config&gt;</code> present in <code>web.xml</code>.</p>
</section>
<section name="Static configuration">
<subsection name="AuthConfigProvider">
<p>If the 3rd party implementation includes an
<code>AuthConfigProvider</code> then a web application can be configured to
use it by nesting the following inside the
<code>&lt;jaspic-providers&gt;</code> element in
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
<source><![CDATA[<provider name="any"
className="fully.qualified.implementation.class.Name"
layer="HttpServlet"
appContext="Catalina/localhost /contextPath"
description="any">
<property name="see-provider-documentation"
value="see-provider-documentation" />
</provider>]]></source>
<p>The <code>name</code> and <code>description</code> attributes are not
used by Tomcat.</p>
<p>The <code>className</code> attribute must be the fully qualified class
name of the <code>AuthConfigProvider</code>. The implementation may be
packaged with the web application or in Tomcat&apos;s
<code>$CATALINA_BASE/lib</code> directory.</p>
<p>The <code>layer</code> attribute must be <code>HttpServlet</code>.</p>
<p>The <code>appContext</code> attribute must be exactly the concatenation
of:</p>
<ul>
<li>The engine name</li>
<li>The forward slash character</li>
<li>The host name</li>
<li>A single space</li>
<li>The context path</li>
</ul>
<p>If the <code>AuthConfigProvider</code> supports configuration via
properties these may be specified via <code>&lt;property&gt;</code> elements
nesting inside the <code>&lt;provide&gt;</code> element.</p>
</subsection>
<subsection name="ServerAuthModule">
<p>If the 3rd party implementation only provides an
<code>ServerAuthModule</code> then it will be necessary to provide a number
of supporting classes. These may be a custom implementation or,
alternatively, Tomcat provides a simple wrapper implementation for
<code>ServerAuthModule</code>s.
</p>
<p>Tomcat&apos;s wrapper for <code>ServerAuthModule</code> can be configured
by nesting the following inside the
<code>&lt;jaspic-providers&gt;</code> element in
<code>$CATALINA_BASE/conf/jaspic-providers.xml</code>.</p>
<source><![CDATA[<provider name="any"
className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
layer="HttpServlet"
appContext="Catalina/localhost /contextPath"
description="any">
<property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
value="fully.qualified.implementation.class.Name" />
<property name="see-provider-documentation"
value="see-provider-documentation" />
</provider>]]></source>
<p>The configuration is similar to the <code>AuthConfigProvider</code> in
the previous section but with some key differences.</p>
<p>The <code>className</code> attribute must be
<code>org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider</code>.</p>
<p>The <code>ServerAuthModule</code>(s) are specified via properties. The
property name must be
<code>org.apache.catalina.authenticator.jaspic.ServerAuthModule.n</code>
where <code>n</code> is the index of the module. The index must start at 1
an increment in steps of 1 until all modules are defined. The value of the
property must be the fully qualified class name of the module.</p>
</subsection>
</section>
<section name="Dynamic configuration">
<p>JASPIC modules and configuration can be packaged within a WAR file with the
web application. The web application can then register the required JASPIC
configuration when it starts using the standard JASPIC APIs.</p>
<p>If parallel deployment is being used then dynamic configuration should not
be used. The JASPIC API assumes that a context path is unique for any given
host which is not the case when using parallel deployment. When using parallel
deployment, static JASPIC configuration should be used. This will require that
all versions of the application use the same JASPIC configuration.</p>
</section>
<section name="3rd party modules">
<p>This is not an exhaustive list. The Tomcat community welcomes contributions
that add to this section.</p>
<subsection name="Philip Green II&apos;s module for Google OAuth 2">
<p>The source code for this module along with the
<a href="https://github.com/phillipgreenii/google-oauth-2.0-serverauthmodule">documentation</a>
which includes details of the necessary Google API configuration is
available on GitHub.</p>
<p>A sample configuration for using this module with Tomcat would look like
this:</p>
<source><![CDATA[<jaspic-providers xmlns="https://tomcat.apache.org/xml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://tomcat.apache.org/xml jaspic-providers.xsd"
version="1.0">
<provider name="google-oauth"
className="org.apache.catalina.authenticator.jaspic.SimpleAuthConfigProvider"
layer="HttpServlet"
appContext="Catalina/localhost /contextPath"
description="Google OAuth test">
<property name="org.apache.catalina.authenticator.jaspic.ServerAuthModule.1"
value="com.idmworks.security.google.GoogleOAuthServerAuthModule" />
<property name="oauth.clientid"
value="obtained-from-Google-console" />
<property name="oauth.clientsecret"
value="obtained-from-Google-console" />
<property name="ignore_missing_login_context"
value="true" />
</provider>
</jaspic-providers>]]></source>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,659 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="listeners.html">
&project;
<properties>
<title>The LifeCycle Listener Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>A <strong>Listener</strong> element defines a component that performs
actions when specific events occur, usually Tomcat starting or Tomcat
stopping.</p>
<p>Listeners may be nested inside a <a href="server.html">Server</a>,
<a href="engine.html">Engine</a>, <a href="host.html">Host</a> or
<a href="context.html">Context</a>. Some Listeners are only intended to be
nested inside specific elements. These constraints are noted in the
documentation below.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Listener</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.LifecycleListener</code>
interface.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No element may be nested inside a <strong>Listener</strong>.</p>
</section>
<section name="Standard Implementations">
<p>Unlike most Catalina components, there are several standard
<strong>Listener</strong> implementations available. As a result,
the <code>className</code> attribute MUST be used to select the
implementation you wish to use.</p>
<subsection name="APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener">
<p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
the APR/native library and loads the library if it is present. For more
information see the <a href="../apr.html">APR/native guide</a>.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<p>The following additional attributes are supported by the <strong>APR
Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="SSLEngine" required="false">
<p>Name of the SSLEngine to use. <code>off</code>: do not use SSL,
<code>on</code>: use SSL but no specific ENGINE.</p>
<p>The default value is <b>on</b>. This initializes the
native SSL engine, which must be enabled in the APR/native connector by
the use of the <code>SSLEnabled</code> attribute.</p>
<p>See the <a href="http://www.openssl.org/">Official OpenSSL website</a>
for more details on supported SSL hardware engines and manufacturers.
</p>
</attribute>
<attribute name="SSLRandomSeed" required="false">
<p>Entropy source used to seed the SSLEngine's PRNG. The default value
is <code>builtin</code>. On development systems, you may want to set
this to <code>/dev/urandom</code> to allow quicker start times.</p>
</attribute>
<attribute name="FIPSMode" required="false">
<p>Set to <code>on</code> to request that OpenSSL be in FIPS mode
(if OpenSSL is already in FIPS mode, it will remain in FIPS mode).
Set to <code>enter</code> to force OpenSSL to enter FIPS mode (an error
will occur if OpenSSL is already in FIPS mode).
Set to <code>require</code> to require that OpenSSL <i>already</i> be
in FIPS mode (an error will occur if OpenSSL is not already in FIPS
mode).</p>
<p>FIPS mode <em>requires you to have a FIPS-capable OpenSSL library which
you must build yourself</em>.
If this attribute is set to any of the above values, the <b>SSLEngine</b>
must be enabled as well.</p>
<p>The default value is <code>off</code>.</p>
</attribute>
<attribute name="useAprConnector" required="false">
<p>This attribute controls the auto-selection of the connector
implementation. When the <strong>protocol</strong> is specified as
<code>HTTP/1.1</code> or <code>AJP/1.3</code> then if this attribute is
<code>true</code> the APR/native connector will be used but if this
attribute is false the NIO connector will be used.</p>
</attribute>
<attribute name="useOpenSSL" required="false">
<p>This attribute controls the auto-selection of the OpenSSL JSSE
implementation. The default is <code>true</code> which will use OpenSSL
if the native library is available and a NIO or NIO2 connector is used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">
<p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
Global JNDI resources defined in server.xml as part of the <a
href="globalresources.html">Global Resources</a> element. Without this
listener, none of the Global Resources will be available.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<p>No additional attributes are supported by the <strong>Global Resources
Lifecycle Listener</strong>.</p>
</subsection>
<subsection name="JNI Library Loading Listener - org.apache.catalina.core.JniLifecycleListener">
<p>The <strong>JNI Library Loading Listener</strong> makes it possible
for multiple Webapps to use a native library, by loading the native
library using a shared class loader (typically the Common class loader but
may vary in some configurations)</p>
<p>The listener supports two mutually exclusive attributes, so one of them must be used, but you can not use both together:</p>
<attributes>
<attribute name="libraryName" required="false">
<p>The name of the native library, as defined in
<code>java.lang.System.loadLibrary()</code>
</p>
</attribute>
<attribute name="libraryPath" required="false">
<p>The absolute path of the native library, as defined in
<code>java.lang.System.load()</code>
</p>
</attribute>
</attributes>
</subsection>
<subsection name="JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener">
<p>The <strong>JRE Memory Leak Prevention Listener</strong> provides
work-arounds for known places where the Java Runtime environment uses
the context class loader to load a singleton as this will cause a memory
leak if a web application class loader happens to be the context class
loader at the time. The work-around is to initialise these singletons when
this listener starts as Tomcat's common class loader is the context class
loader at that time. It also provides work-arounds for known issues that
can result in locked JAR files.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<p>The following additional attributes are supported by the <strong>JRE
Memory Leak Prevention Listener</strong>:</p>
<attributes>
<attribute name="appContextProtection" required="false">
<p>Enables protection so that calls to
<code>sun.awt.AppContext.getAppContext()</code> triggered by a web
application do not result in a memory leak. Note that enabling this
protection will trigger a requirement for a graphical environment unless
Java is started in head-less mode. The default is <code>false</code>.
This protection is disabled if running on Java 8 onwards since the leak
has been fixed for Java 8 onwards.
</p>
</attribute>
<attribute name="AWTThreadProtection" required="false">
<p>Enables protection so that calls to
<code>java.awt.Toolkit.getDefaultToolkit()</code> triggered by a web
application do not result in a memory leak.
Defaults to <code>false</code> because an AWT thread is launched. This
protection is disabled if running on Java 9 onwards since the leak has
been fixed for Java 9 onwards.</p>
</attribute>
<attribute name="classesToInitialize" required="false">
<p>List of comma-separated fully qualified class names to load and initialize
during the startup of this Listener. This allows to pre-load classes that are
known to provoke classloader leaks if they are loaded during a request
processing. Non-JRE classes may be referenced, like
<code>oracle.jdbc.driver.OracleTimeoutThreadPerVM</code>.
The default value is empty, but specific JRE classes are loaded by other leak
protection features managed by other attributes of this Listener.</p>
</attribute>
<attribute name="driverManagerProtection" required="false">
<p>The first use of <code>java.sql.DriverManager</code> will trigger the
loading of JDBC Drivers visible to the current class loader and its
parents. The web application level memory leak protection can take care
of this in most cases but triggering the loading here has fewer
side-effects. The default is <code>true</code>.</p>
</attribute>
<attribute name="forkJoinCommonPoolProtection" required="false">
<p>Enables protection so the threads created for
<code>ForkJoinPool.commonPool()</code> do not result in a memory leak.
The protection is enabled by setting the
<code>java.util.concurrent.ForkJoinPool.common.threadFactory</code>
system property. If this property is set when Tomcat starts, Tomcat will
not over-ride it even if this protection is explicitly enabled. The
default is <code>true</code>. This protection is only used when running
on Java 8. The common pool does not exist in earlier versions and the
leak has been fixed for Java 9 onwards.</p>
</attribute>
<attribute name="gcDaemonProtection" required="false">
<p>Enables protection so that calls to
<code>sun.misc.GC.requestLatency(long)</code> triggered by a web
application do not result in a memory leak. Use of RMI is likely to
trigger a call to this method. A side effect of enabling this protection
is the creation of a thread named "GC Daemon". The protection uses
reflection to access internal Sun classes and may generate errors on
startup on non-Sun JVMs. The default is <code>true</code>. This
protection is disabled if running on Java 9 onwards since the leak has
been fixed for Java 9 onwards.</p>
</attribute>
<attribute name="ldapPoolProtection" required="false">
<p>Enables protection so that the PoolCleaner thread started by
<code>com.sun.jndi.ldap.LdapPoolManager</code> does not result in a
memory leak. The thread is started the first time the
<code>LdapPoolManager</code> class is used if the system property
<code>com.sun.jndi.ldap.connect.pool.timeout</code> is set to a value
greater than 0. Without this protection, if a web application uses this
class the PoolCleaner thread will be configured with the thread's
context class loader set to the web application class loader which in
turn will trigger a memory leak on reload. Defaults to
<code>true</code>. This protection is disabled if running on Java 9
onwards since the leak has been fixed for Java 9 onwards.</p>
</attribute>
<attribute name="securityLoginConfigurationProtection" required="false">
<p>Enables protection so that usage of the
<code>javax.security.auth.login.Configuration</code> class by a web
application does not provoke a memory leak. The first access of this
class will trigger the initializer that will retain a static reference
to the context class loader. The protection loads the class with the
system class loader to ensure that the static initializer is not
triggered by a web application. Defaults to <code>true</code>. This
protection is disabled if running on Java 8 onwards since the leak has
been fixed for Java 8 onwards.</p>
</attribute>
<attribute name="securityPolicyProtection" required="false">
<p>Enables protection so that usage of the deprecated
<code>javax.security.auth.Policy</code> class by a web application does
not result in a memory leak. The first access of this class will trigger
the static initializer that will retain a static reference to the
context class loader. The protection calls the <code>getPolicy()</code>
method of this class to ensure that the static initializer is not
triggered by a web application. Defaults to <code>true</code>.</p>
<p>Note: The underlying leak has been fixed in Java 7 update 51 onwards
and Java 8 onwards. This protection is therefor disabled if running on
Java 8 onwards.</p>
</attribute>
<attribute name="tokenPollerProtection" required="false">
<p>Enables protection so that any token poller thread initialized by
<code>sun.security.pkcs11.SunPKCS11.initToken()</code> does not
result in a memory leak. The thread is started depending on various
conditions as part of the initialization of the Java Cryptography
Architecture. Without the protection this can happen during Webapp
deployment when the MessageDigest for generating session IDs is
initialized. As a result the thread has the Webapp class loader as its
thread context class loader. Enabling the protection initializes JCA
early during Tomcat startup. Defaults to <code>true</code>. This
protection is disabled if running on Java 9 onwards since the leak has
been fixed for Java 9 onwards.</p>
</attribute>
<attribute name="urlCacheProtection" required="false">
<p>Enables protection so that reading resources from JAR files using
<code>java.net.URLConnection</code>s does not result in the JAR file
being locked. Note that enabling this protection disables caching by
default for all resources obtained via
<code>java.net.URLConnection</code>s. Caching may be re-enabled on a
case by case basis as required. Defaults to <code>true</code>.</p>
</attribute>
<attribute name="xmlParsingProtection" required="false">
<p>Enables protection so that parsing XML files within a web application
does not result in a memory leak. Note that memory profilers may not
display the GC root associated with this leak making it particularly
hard to diagnose. Defaults to <code>true</code>. This protection is
disabled if running on Java 9 onwards since the leak has been fixed for
Java 9 onwards.</p>
</attribute>
</attributes>
<subsection name="JreMemoryLeakPreventionListener Examples">
<p>The following is an example of how to configure the
<code>classesToInitialize</code> attribute of this listener.</p>
<p>If this listener was configured in server.xml as:</p>
<source><![CDATA[ <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener"
classesToInitialize="oracle.jdbc.driver.OracleTimeoutThreadPerVM" />]]></source>
<p>then the <code>OracleTimeoutThreadPerVM</code> class would be loaded
and initialized during listener startup instead of during request
processing.</p>
</subsection>
</subsection>
<subsection name="Security Lifecycle Listener - org.apache.catalina.security.SecurityListener">
<p>The <strong>Security Lifecycle Listener</strong> performs a number of
security checks when Tomcat starts and prevents Tomcat from starting if they
fail. The listener is not enabled by default. To enabled it uncomment the
listener in $CATALINA_BASE/conf/server.xml. For Tomcat versions before 8.5.30,
if the operating system supports umask then the line in
$CATALINA_HOME/bin/catalina.sh that obtains the umask also needs to be
uncommented. For Tomcat 8.5.30 and later, the umask is automatically
passed-into Tomcat.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<p>The following additional attributes are supported by the <strong>Security
Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="checkedOsUsers" required="false">
<p>A comma separated list of OS users that must not be used to start
Tomcat. If not specified, the default value of <b>root</b> is used. To
disable this check, set the attribute to the empty string. Usernames
are checked in a case-insensitive manner.</p>
</attribute>
<attribute name="minimumUmask" required="false">
<p>The least restrictive umask that must be configured before Tomcat
will start. If not specified, the default value of <b>0007</b> is used.
To disable this check, set the attribute to the empty string. The check
is not performed on Windows platforms.</p>
</attribute>
</attributes>
</subsection>
<subsection name="StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener">
<p>The <strong>StoreConfig Lifecycle Listener</strong> configures a
StoreConfig MBean that may be used to save the current server configuration
in server.xml or the current configuration for a web application in a
context.xml file.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<p>The following additional attributes are supported by the
<strong>StoreConfig Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="storeConfigClass" required="false">
<p>The name of the <code>IStoreConfig</code> implementation to use. If
not specified the default of
<code>org.apache.catalina.storeconfig.StoreConfig</code> will be
used.</p>
</attribute>
<attribute name="storeRegistry" required="false">
<p>The URL of the configuration file that configures how the
<code>IStoreConfig</code> is to save the configuration. If not specified
the built in resource
<code>/org/apache/catalina/storeconfig/server-registry.xml</code> will
be used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener">
<p>The <strong>ThreadLocal Leak Prevention Listener</strong> triggers the
renewal of threads in <a href="executor.html">Executor</a> pools when a
<a href="context.html">Context</a> is being stopped to avoid thread-local
related memory leaks. Active threads will be renewed one by one when they
come back to the pool after executing their task. The renewal happens
only for contexts that have their <code>renewThreadsWhenStoppingContext</code>
attribute set to <code>true</code>.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements.</p>
<p>No additional attributes are supported by the <strong>ThreadLocal Leak
Prevention Listener</strong>.</p>
</subsection>
<subsection name="UserConfig - org.apache.catalina.startup.UserConfig">
<p>The <strong>UserConfig</strong> provides feature of User Web Applications.
User Web Applications map a request URI starting with a tilde character ("~")
and a username to a directory (commonly named public_html) in that user's
home directory on the server.</p>
<p>See the <a href="host.html#User_Web_Applications">User Web Applications</a>
special feature on the <strong>Host</strong> element for more information.</p>
<p>The following additional attributes are supported by the
<strong>UserConfig</strong>:</p>
<attributes>
<attribute name="directoryName" required="false">
<p>The directory name to be searched for within each user home directory.
The default is <code>public_html</code>.</p>
</attribute>
<attribute name="userClass" required="false">
<p>The class name of the user database class.
There are currently two user database, the
<code>org.apache.catalina.startup.PasswdUserDatabase</code> is used on a
Unix system that uses the /etc/passwd file to identify valid users.
The <code>org.apache.catalina.startup.HomesUserDatabase</code> is used on
a server where /etc/passwd is not in use. HomesUserDatabase deploy all
directories found in a specified base directory.</p>
</attribute>
<attribute name="homeBase" required="false">
<p>The base directory containing user home directories. This is effective
only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is
used.</p>
</attribute>
<attribute name="allow" required="false">
<p>A regular expression defining user who deployment is allowed. If this
attribute is specified, the user to deploy must match for this pattern.
If this attribute is not specified, all users will be deployed unless the
user matches a deny pattern.</p>
</attribute>
<attribute name="deny" required="false">
<p>A regular expression defining user who deployment is denied. If this
attribute is specified, the user to deploy must not match for this
pattern. If this attribute is not specified, deployment of user will be
governed by a allow attribute.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Version Logging Lifecycle Listener - org.apache.catalina.startup.VersionLoggerListener">
<p>The <strong>Version Logging Lifecycle Listener</strong> logs Tomcat, Java
and operating system information when Tomcat starts.</p>
<p>This listener must only be nested within <a href="server.html">Server</a>
elements and should be the first listener defined.</p>
<p>The following additional attributes are supported by the <strong>Version
Logging Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="logArgs" required="false">
<p>If <code>true</code>, the command line arguments passed to Java when
Tomcat started will be logged. If not specified, the default value of
<code>true</code> will be used.</p>
</attribute>
<attribute name="logEnv" required="false">
<p>If <code>true</code>, the current environment variables when Tomcat
starts will be logged. If not specified, the default value of
<code>false</code> will be used.</p>
</attribute>
<attribute name="logProps" required="false">
<p>If <code>true</code>, the current Java system properties will be
logged. If not specified, the default value of
<code>false</code> will be used.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Additional Implementations">
<subsection name="System property replacement - org.apache.catalina.util.SystemPropertyReplacerListener">
<p>This listener performs system property replacement using the property
source configured on the digester. When <code>${parameter}</code>
denoted parameters are found in the values of system properties,
the property source will be invoked to attempt to replace it.</p>
</subsection>
</section>
<section name="Deprecated Implementations">
<subsection name="JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener">
<p><strong>This listener is now deprecated as the features it provides are
now available in the remote JMX capability included with the JRE. This
listener will be removed in Tomcat 10 and may be removed from Tomcat 8 some
time after 2020-12-31.</strong></p>
<p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
directory of the binary download area.</p>
<p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used by
the JMX/RMI Server making things much simpler if you need to connect
jconsole or a similar tool to a remote Tomcat instance that is running
behind a firewall. Only these ports are configured via the listener. The
remainder of the configuration is via the standard system properties for
configuring JMX. For further information on configuring JMX see
<a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html">
Monitoring and Management Using JMX</a> included with the Java SDK
documentation.</p>
<p>This listener must only be nested within a <a href="server.html">Server</a>
element.</p>
<p>The following additional attributes are supported by the <strong>JMX Remote
Lifecycle Listener</strong>:</p>
<attributes>
<attribute name="rmiRegistryPortPlatform" required="true">
<p>The port to be used by the JMX/RMI registry for the Platform MBeans.
This replaces the use of the
<code>com.sun.management.jmxremote.port</code> system property that
should not be set when using this listener.</p>
</attribute>
<attribute name="rmiServerPortPlatform" required="true">
<p>The port to be used by the Platform JMX/RMI server.</p>
</attribute>
<attribute name="rmiBindAddress" required="false">
<p>The address of the interface to be used by JMX/RMI server.</p>
</attribute>
<attribute name="useLocalPorts" required="false">
<p>Should any clients using these ports be forced to use local ports to
connect to the JMX/RMI server. This is useful when tunnelling
connections over SSH or similar. Defaults to <code>false</code>.</p>
</attribute>
</attributes>
<h3>Using file-based Authentication and Authorisation</h3>
<p>If this listener was configured in server.xml as:</p>
<source><![CDATA[ <Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" />]]></source>
<p>with the following system properties set (e.g. in setenv.sh):</p>
<source> -Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false</source>
<p>$CATALINA_BASE/conf/jmxremote.password containing:</p>
<source>admin letmein</source>
<p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
<source>admin readwrite</source>
<p>then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
firewall would enable jconsole to connect to a Tomcat instance running
behind a firewall using a connection string of the form:</p>
<source>service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi</source>
<p>
with a user name of <code>admin</code> and a password of
<code>letmein</code>.
</p>
<h3>Using JAAS</h3>
<p>If we use the following system properties instead:</p>
<source> -Dcom.sun.management.jmxremote.login.config=Tomcat
-Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
-Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
-Dcom.sun.management.jmxremote.ssl=false</source>
<p>$CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:</p>
<source> Tomcat { /* should match to the com.sun.management.jmxremote.login.config property */
/* for illustration purposes only */
com.sun.security.auth.module.LdapLoginModule REQUIRED
userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
userFilter="(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))"
authzIdentity="admin"
debug=true;
};</source>
<p>$CATALINA_BASE/conf/jmxremote.access containing:</p>
<source>admin readwrite</source>
<p>
then we would need to provide LDAP credentials instead.
</p>
<p><strong>Note that the examples above do not use SSL. JMX access should
be considered equivalent to administrative access and secured accordingly.
</strong></p>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,166 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="loader.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Loader Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Loader</strong> element represents the <em>web
application class loader</em> that will be used to load Java
classes and resources for your web application. Such
a class loader must follow the requirements of the Servlet
Specification, and load classes from the following locations:</p>
<ul>
<li>From the <code>/WEB-INF/classes</code> directory inside your
web application.</li>
<li>From JAR files in the <code>/WEB-INF/lib</code> directory
inside your web application.</li>
<li>From resources made available by Catalina to all web
applications globally.</li>
</ul>
<p>A Loader element MAY be nested inside a <a href="context.html">Context</a>
component. If it is not included, a default Loader configuration will be
created automatically, which is sufficient for most requirements.</p>
<p>For a more in-depth description of the class loader hierarchy
that is implemented by Catalina, see <a href="../class-loader-howto.html">the ClassLoader HowTo</a>.</p>
<p><em>The description below uses the variable name $CATALINA_BASE to refer the
base directory against which most relative paths are resolved. If you have
not configured Tomcat for multiple instances by setting a CATALINA_BASE
directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME,
the directory into which you have installed Tomcat.</em></p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Loader</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Loader</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="delegate" required="false">
<p>Set to <code>true</code> if you want the class loader to follow
the standard Java2 delegation model, and attempt to load classes from
parent class loaders <strong>before</strong> looking inside the web
application. Set to <code>false</code> (the default) to have the
class loader look inside the web application first, before asking
parent class loaders to find requested classes or resources.</p>
</attribute>
<attribute name="reloadable" required="false">
<p>Set to <code>true</code> if you want Catalina to monitor classes in
<code>/WEB-INF/classes/</code> and <code>/WEB-INF/lib</code> for
changes, and automatically reload the web application if a change
is detected. This feature is very useful during application
development, but it requires significant runtime overhead and is
not recommended for use on deployed production applications. You
can use the <a href="../manager-howto.html">Manager</a> web
application, however, to trigger reloads of deployed applications
on demand.</p>
<p><strong>NOTE</strong> - The value for this property will be
inherited from the <code>reloadable</code> attribute you set on
the surrounding <a href="context.html">Context</a> component,
and any value you explicitly set here will be replaced.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Loader</strong> is
<strong>org.apache.catalina.loader.WebappLoader</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="loaderClass" required="false">
<p>Java class name of the <code>java.lang.ClassLoader</code>
implementation class to use. Custom implementations must extend
<code>org.apache.catalina.loader.WebappClassLoaderBase</code>.
</p>
<p>If not specified, the default value is
<code>org.apache.catalina.loader.ParallelWebappClassLoader</code>. The
default <strong>loaderClass</strong> is parallel capable, which
means that multiple threads may load difference classes in parallel.
A non-parallel capable <strong>loaderClass</strong> is available and can
be used by specifying
<code>org.apache.catalina.loader.WebappClassLoader</code>.</p>
</attribute>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>No components may be nested inside a <strong>Loader</strong> element.</p>
</section>
<section name="Special Features">
<subsection name="Logging">
<p>A loader is associated with the log category based on its classname.</p>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,558 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="manager.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>The Manager Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>Manager</strong> element represents the <em>session
manager</em> that will be used to create and maintain HTTP sessions
as requested by the associated web application.</p>
<p>A Manager element MAY be nested inside a
<a href="context.html">Context</a> component. If it is not included,
a default Manager configuration will be created automatically, which
is sufficient for most requirements, &#x2014; see
<em>Standard Manager Implementation</em> below for the details
of this configuration.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Manager</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Manager</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="maxActiveSessions" required="false">
<p>The maximum number of active sessions that will be created by
this Manager, or <code>-1</code> (the default) for no limit.</p>
<p>When the limit is reached, any attempt to create a new session
(e.g. with <code>HttpServletRequest.getSession()</code> call)
will fail with an <code>IllegalStateException</code>.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>Tomcat provides two standard implementations of <strong>Manager</strong>
for use &#x2014; the default one stores active sessions, while the optional one
stores active sessions that have been swapped out (in addition to saving
sessions across a restart of Tomcat) in a storage location that is selected
via the use of an appropriate <strong>Store</strong> nested element.</p>
<h3>Standard Manager Implementation</h3>
<p>The standard implementation of <strong>Manager</strong> is
<strong>org.apache.catalina.session.StandardManager</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
<attribute name="pathname" required="false">
<p>Absolute or relative (to the work directory for this Context)
pathname of the file in which session state will be preserved
across application restarts, if possible. The default is
"SESSIONS.ser".<br />See
<a href="#Persistence_Across_Restarts">Persistence Across Restarts</a>
for more information. This persistence may be
disabled by setting this attribute to an empty string.</p>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>Frequency of the session expiration, and related manager operations.
Manager operations will be done once for the specified amount of
backgroundProcess calls (i.e., the lower the amount, the more often the
checks will occur). The minimum value is 1, and the default value is 6.
</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>Name of the Java class that extends
<code>java.security.SecureRandom</code> to use to generate session IDs.
If not specified, the default value is
<code>java.security.SecureRandom</code>.</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>Name of the provider to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the platform default provider will be used.</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>Name of the algorithm to use to create the
<code>java.security.SecureRandom</code> instances that generate session
IDs. If an invalid algorithm and/or provider is specified, the Manager
will use the platform default provider and the default algorithm. If not
specified, the default algorithm of SHA1PRNG will be used. If the
default algorithm is not supported, the platform default will be used.
To specify that the platform default should be used, do not set the
secureRandomProvider attribute and set this attribute to the empty
string.</p>
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for distribution. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only distribute the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
distribution. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
</attributes>
<h3>Persistent Manager Implementation</h3>
<p><strong>NOTE:</strong> You must set either the
<code>org.apache.catalina.session.StandardSession.ACTIVITY_CHECK</code> or
<code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code>
<a href="systemprops.html">system properties</a> to <code>true</code> for
the persistent manager to work correctly.</p>
<p>The persistent implementation of <strong>Manager</strong> is
<strong>org.apache.catalina.session.PersistentManager</strong>. In
addition to the usual operations of creating and deleting sessions, a
<code>PersistentManager</code> has the capability to swap active (but
idle) sessions out to a persistent storage mechanism, as well as to save
all sessions across a normal restart of Tomcat. The actual persistent
storage mechanism used is selected by your choice of a
<strong>Store</strong> element nested inside the <strong>Manager</strong>
element - this is required for use of <code>PersistentManager</code>.</p>
<p>This implementation of Manager supports the following attributes in
addition to the <a href="#Common_Attributes">Common Attributes</a>
described earlier.</p>
<attributes>
<attribute name="className" required="true">
<p>It has the same meaning as described in the
<a href="#Common_Attributes">Common Attributes</a> above.
You <strong>must</strong> specify
<code>org.apache.catalina.session.PersistentManager</code> to use
this manager implementation.</p>
</attribute>
<attribute name="maxIdleBackup" required="false">
<p>The time interval (in seconds) since the last access to a session
before it is eligible for being persisted to the session store, or
<code>-1</code> to disable this feature. By default, this feature is
disabled.</p>
</attribute>
<attribute name="maxIdleSwap" required="false">
<p>The maximum time a session may be idle before it is eligible to be
swapped to disk due to inactivity. Setting this to <code>-1</code> means
sessions should not be swapped out just because of inactivity. If this
feature is enabled, the time interval specified here should be equal to
or longer than the value specified for <code>maxIdleBackup</code>. By
default, this feature is disabled.</p>
</attribute>
<attribute name="minIdleSwap" required="false">
<p>The minimum time in seconds a session must be idle before it is
eligible to be swapped to disk to keep the active session count below
maxActiveSessions. Setting to <code>-1</code> means sessions will not be
swapped out to keep the active session count down. If specified, this
value should be less than that specified by <code>maxIdleSwap</code>.
By default, this value is set to <code>-1</code>.</p>
</attribute>
<attribute name="processExpiresFrequency" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="saveOnRestart" required="false">
<p>Should all sessions be persisted and reloaded when Tomcat is shut
down and restarted (or when this application is reloaded)? By default,
this attribute is set to <code>true</code>.</p>
</attribute>
<attribute name="secureRandomClass" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="secureRandomProvider" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="secureRandomAlgorithm" required="false">
<p>It is the same as described above for the
<code>org.apache.catalina.session.StandardManager</code> class.
</p>
</attribute>
<attribute name="sessionAttributeNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if its name matches
this pattern. If the pattern is zero length or <code>null</code>, all
attributes are eligible for distribution. The pattern is anchored so the
session attribute name must fully match the pattern. As an example, the
value <code>(userName|sessionHistory)</code> will only distribute the
two session attributes named <code>userName</code> and
<code>sessionHistory</code>. If not specified, the default value of
<code>null</code> will be used.</p>
</attribute>
<attribute name="sessionAttributeValueClassNameFilter" required="false">
<p>A regular expression used to filter which session attributes will be
distributed. An attribute will only be distributed if the implementation
class name of the value matches this pattern. If the pattern is zero
length or <code>null</code>, all attributes are eligible for
distribution. The pattern is anchored so the fully qualified class name
must fully match the pattern. If not specified, the default value of
<code>null</code> will be used unless a <code>SecurityManager</code> is
enabled in which case the default will be
<code>java\\.lang\\.(?:Boolean|Integer|Long|Number|String)</code>.</p>
</attribute>
<attribute name="warnOnSessionAttributeFilterFailure" required="false">
<p>If <strong>sessionAttributeNameFilter</strong> or
<strong>sessionAttributeValueClassNameFilter</strong> blocks an
attribute, should this be logged at <code>WARN</code> level? If
<code>WARN</code> level logging is disabled then it will be logged at
<code>DEBUG</code>. The default value of this attribute is
<code>false</code> unless a <code>SecurityManager</code> is enabled in
which case the default will be <code>true</code>.</p>
</attribute>
</attributes>
<p>In order to successfully use a PersistentManager, you must nest inside
it a <strong>&lt;Store&gt;</strong> element, as described below.</p>
</subsection>
</section>
<section name="Nested Components">
<h3>All Manager Implementations</h3>
<p>All Manager implementations allow nesting of a
<strong>&lt;SessionIdGenerator&gt;</strong> element. It defines
the behavior of session id generation. All implementations
of the <a href="sessionidgenerator.html">SessionIdGenerator</a> allow the
following attributes:
</p>
<attributes>
<attribute name="sessionIdLength" required="false">
<p>The length of the session ID may be changed with the
<strong>sessionIdLength</strong> attribute.
</p>
</attribute>
</attributes>
<h3>Persistent Manager Implementation</h3>
<p>If you are using the <em>Persistent Manager Implementation</em>
as described above, you <strong>MUST</strong> nest a
<strong>&lt;Store&gt;</strong> element inside, which defines the
characteristics of the persistent data storage. Two implementations
of the <code>&lt;Store&gt;</code> element are currently available,
with different characteristics, as described below.</p>
<h5>File Based Store</h5>
<p>The <em>File Based Store</em> implementation saves swapped out
sessions in individual files (named based on the session identifier)
in a configurable directory. Therefore, you are likely to encounter
scalability problems as the number of active sessions increases, and
this should primarily be considered a means to easily experiment.</p>
<p>To configure this, add a <code>&lt;Store&gt;</code> nested inside
your <code>&lt;Manager&gt;</code> element with the following attributes:
</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Store</code> interface. You
<strong>must</strong> specify
<code>org.apache.catalina.session.FileStore</code>
to use this implementation.</p>
</attribute>
<attribute name="directory" required="false">
<p>Absolute or relative (to the temporary work directory for this web
application) pathname of the directory into which individual session
files are written. If not specified, the temporary work directory
assigned by the container is utilized.</p>
</attribute>
</attributes>
<h5>JDBC Based Store</h5>
<p>The <em>JDBC Based Store</em> implementation saves swapped out
sessions in individual rows of a preconfigured table in a database
that is accessed via a JDBC driver. With large numbers of swapped out
sessions, this implementation will exhibit improved performance over
the File Based Store described above.</p>
<p>To configure this, add a <code>&lt;Store&gt;</code> nested inside
your <code>&lt;Manager&gt;</code> element with the following attributes:
</p>
<attributes>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Store</code> interface. You
<strong>must</strong> specify
<code>org.apache.catalina.session.JDBCStore</code>
to use this implementation.</p>
</attribute>
<attribute name="connectionName" required="true">
<p>The user name that will be handed to the configured JDBC driver to
establish a connection to the database containing the session table.</p>
</attribute>
<attribute name="connectionPassword" required="true">
<p>The password that will be handed to the configured JDBC driver to
establish a connection to the database containing the session table.</p>
</attribute>
<attribute name="connectionURL" required="true">
<p>The connection URL that will be handed to the configured JDBC
driver to establish a connection to the database containing our
session table.</p>
</attribute>
<attribute name="dataSourceName" required="false">
<p>Name of the JNDI resource for a JDBC DataSource-factory. If this option
is given and a valid JDBC resource can be found, it will be used and any
direct configuration of a JDBC connection via <code>connectionURL</code>,
<code>connectionName</code>, <code>connectionPassword</code> and
<code>driverName</code> will be ignored. Since this code uses prepared
statements, you might want to configure pooled prepared statements as
shown in <a href="../jndi-resources-howto.html">the JNDI resources
How-To</a>.</p>
</attribute>
<attribute name="driverName" required="true">
<p>Java class name of the JDBC driver to be used.</p>
</attribute>
<attribute name="localDataSource" required="false">
<p>This allows the Store to use a DataSource defined for the Context
rather than a global DataSource. If not specified, the default is
<code>false</code>: use a global DataSource.</p>
</attribute>
<attribute name="sessionAppCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the Engine, Host, and Web Application Context name in the
format <code>/Engine/Host/Context</code>. If not specified the default
value of <code>app</code> will be used.</p>
</attribute>
<attribute name="sessionDataCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the serialized form of all session attributes for a swapped
out session. The column type must accept a binary object (typically called
a BLOB). If not specified the default value of <code>data</code> will be
used.</p>
</attribute>
<attribute name="sessionIdCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the session identifier of the swapped out session. The
column type must accept character string data of at least as many
characters as are contained in session identifiers created by Tomcat
(typically 32). If not specified the default value of <code>id</code> will
be used.</p>
</attribute>
<attribute name="sessionLastAccessedCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the <code>lastAccessedTime</code> property of this session.
The column type must accept a Java <code>long</code> (64 bits). If not
specified the default value of <code>maxinactive</code> will be used.</p>
</attribute>
<attribute name="sessionMaxInactiveCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains the <code>maxInactiveInterval</code> property of this
session. The column type must accept a Java <code>integer</code> (32
bits). If not specified, the default value of <code>maxinactive</code>
will be used.</p>
</attribute>
<attribute name="sessionTable" required="false">
<p>Name of the database table to be used for storing swapped out sessions.
This table must contain (at least) the database columns that are
configured by the other attributes of this element. If not specified the
default value of <code>tomcat$sessions</code> will be used.</p>
</attribute>
<attribute name="sessionValidCol" required="false">
<p>Name of the database column, contained in the specified session table,
that contains a flag indicating whether this swapped out session is still
valid or not. The column type must accept a single character. If not
specified the default value of <code>valid</code> will be used.</p>
</attribute>
</attributes>
<p>Before attempting to use the JDBC Based Store for the first time,
you must create the table that will be used to store swapped out sessions.
Detailed SQL commands vary depending on the database you are using, but
a script like this will generally be required:</p>
<source>create table tomcat_sessions (
session_id varchar(100) not null primary key,
valid_session char(1) not null,
max_inactive int not null,
last_access bigint not null,
app_name varchar(255),
session_data mediumblob,
KEY kapp_name(app_name)
);</source>
<p>Note: The SQL command above does not use the default names for either the
table or the columns so the JDBC Store would need to be configured to reflect
this.</p>
<p>In order for the JDBC Based Store to successfully connect to your
database, the JDBC driver you configure must be visible to Tomcat's
internal class loader. Generally, that means you must place the JAR
file containing this driver into the <code>$CATALINA_HOME/lib</code>
directory.</p>
</section>
<section name="Special Features">
<subsection name="Persistence Across Restarts">
<p>Whenever Apache Tomcat is shut down normally and restarted, or when an
application reload is triggered, the standard Manager implementation
will attempt to serialize all currently active sessions to a disk
file located via the <code>pathname</code> attribute. All such saved
sessions will then be deserialized and activated (assuming they have
not expired in the mean time) when the application reload is completed.</p>
<p>In order to successfully restore the state of session attributes,
all such attributes MUST implement the <code>java.io.Serializable</code>
interface. You MAY cause the Manager to enforce this restriction by
including the <code>&lt;distributable&gt;</code> element in your web
application deployment descriptor (<code>/WEB-INF/web.xml</code>).</p>
<p>The persistence across restarts provided by the
<strong>StandardManager</strong> is a simpler implementation than that
provided by the <strong>PersistentManager</strong>. If robust, production
quality persistence across restarts is required then the
<strong>PersistentManager</strong> should be used with an appropriate
configuration.</p>
</subsection>
<subsection name="Disable Session Persistence">
<p>As documented above, every web application by default has
standard manager implementation configured, and it performs session
persistence across restarts. To disable this persistence feature, create
a <a href="context.html">Context</a> configuration file for your web
application and add the following element there:</p>
<source><![CDATA[<Manager pathname="" />]]></source>
</subsection>
</section>
</body>
</document>

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

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

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

File diff suppressed because it is too large Load Diff

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

@@ -0,0 +1,340 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="resources.html">
&project;
<properties>
<title>The Resources Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc />
</section>
<section name="Introduction">
<p>The <strong>Resources</strong> element represents all the resources
available to the web application. This includes classes, JAR files, HTML, JSPs
and any other files that contribute to the web application. Implementations
are provided to use directories, JAR files and WARs as the source of these
resources and the resources implementation may be extended to provide support
for files stored in other forms such as in a database or a versioned
repository.</p>
<p>Resources are cached by default.</p>
<p><strong>Note: Running a webapp with non-filesystem based
Resources implementations is only possible when the webapp does not
rely on direct filesystem access to its own resources, and uses the methods
in the ServletContext interface to access them.</strong></p>
<p>A Resources element MAY be nested inside a
<a href="context.html">Context</a> component. If it is not included,
a default filesystem based Resources will be created automatically,
which is sufficient for most requirements.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Resources</strong> support the following
attributes:</p>
<attributes>
<attribute name="allowLinking" required="false">
<p>If the value of this flag is <code>true</code>, symlinks will be
allowed inside the web application, pointing to resources inside or
outside the web application base path. If not specified, the default
value of the flag is <code>false</code>.</p>
<p><b>NOTE: This flag MUST NOT be set to true on the Windows platform
(or any other OS which does not have a case sensitive filesystem),
as it will disable case sensitivity checks, allowing JSP source code
disclosure, among other security problems.</b></p>
</attribute>
<attribute name="cacheMaxSize" required="false">
<p>The maximum size of the static resource cache in kilobytes.
If not specified, the default value is <code>10240</code>
(10 megabytes). This value may be changed while the web application is
running (e.g. via JMX). If the cache is using more memory than the new
limit the cache will attempt to reduce in size over time to meet the
new limit. If necessary, <strong>cacheObjectMaxSize</strong> will be
reduced to ensure that it is no larger than
<code>cacheMaxSize/20</code>.</p>
</attribute>
<attribute name="cacheObjectMaxSize" required="false">
<p>Maximum size of the static resource that will be placed in the cache.
If not specified, the default value is <code>512</code>
(512 kilobytes). If this value is greater than
<code>cacheMaxSize/20</code> it will be reduced to
<code>cacheMaxSize/20</code>. This value may be changed while the web
application is running (e.g. via JMX).</p>
</attribute>
<attribute name="cacheTtl" required="false">
<p>The amount of time in milliseconds between the revalidation of cache
entries. If not specified, the default value is <code>5000</code> (5
seconds). This value may be changed while the web application is running
(e.g. via JMX). When a resource is cached it will inherit the TTL in
force at the time it was cached and retain that TTL until the resource
is evicted from the cache regardless of any subsequent changes that may
be made to this attribute.</p>
</attribute>
<attribute name="cachingAllowed" required="false">
<p>If the value of this flag is <code>true</code>, the cache for static
resources will be used. If not specified, the default value
of the flag is <code>true</code>. This value may be changed while the
web application is running (e.g. via JMX). When the cache is disabled
any resources currently in the cache are cleared from the cache.</p>
</attribute>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.WebResourceRoot</code>
interface. If not specified, the standard value (defined below) will be
used.</p>
</attribute>
<attribute name="trackLockedFiles" required="false">
<p>Controls whether the track locked files feature is enabled. If
enabled, all calls to methods that return objects that lock a file and
need to be closed to release that lock (e.g.
<code>ServletContext.getResourceAsStream()</code>) will perform a number
of additional tasks.</p>
<ul>
<li>The stack trace at the point where the method was called will be
recorded and associated with the returned object.</li>
<li>The returned object will be wrapped so that the point where
close() (or equivalent) is called to release the resources can be
detected. Tracking of the object will cease once the resources have
been released.</li>
<li>All remaining locked resources on web application shutdown will be
logged and then closed.</li>
</ul>
<p>If not specified, the default value of <code>false</code> will be
used.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<h3>Standard Root Implementation</h3>
<p>The standard implementation of <strong>Resources</strong> is
<strong>org.apache.catalina.webresources.StandardRoot</strong>. It does not
support any additional attributes.</p>
<h3>Extracting Root Implementation</h3>
<p>The extracting implementation of <strong>Resources</strong> is
<strong>org.apache.catalina.webresources.ExtractingRoot</strong>. It does not
support any additional attributes.</p>
<p>When deploying web applications as packed WAR files, the extracting root
will extract any JAR files from <code>/WEB-INF/lib</code> to a
<code>application-jars</code> directory located in the web
application&apos;s working directory. These extracted JARs will be removed
when the web application stops.</p>
<p>Extracting JAR files from a packed WAR may provide a performance
improvement, particularly at web application start when JAR scanning is
required by the application.</p>
</subsection>
</section>
<section name="Nested Components">
<p>A web application&apos;s main resources are defined by the
<strong>docBase</strong> defined for the <a href="context.html">Context</a>.
Additional resources may be made available to the web application by defining
one or more nested components.</p>
<h3>PreResources</h3>
<p>PreResources are searched before the main resources. They will be searched
in the order they are defined. To configure PreResources, nest a
&lt;PreResources&gt; element inside the &lt;Resources&gt; element with the
following attributes:</p>
<attributes>
<attribute name="base" required="true">
<p>Identifies where the resources to be used are located. This attribute
is required by the <code>org.apache.catalina.WebResourceSet</code>
implementations provided by Tomcat and should specify the absolute path to
the file, directory or JAR where the resources are located. Custom
implementations may not require it.</p>
</attribute>
<attribute name="className" required="true">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.WebResourceSet</code> interface.
Tomcat provides three standard implementations:
<code>org.apache.catalina.webresources.DirResourceSet</code>,
<code>org.apache.catalina.webresources.FileResourceSet</code> and
<code>org.apache.catalina.webresources.JarResourceSet</code>. Custom
implementations may also be used.
</p>
</attribute>
<attribute name="internalPath" required="false">
<p>Identifies the path within the <strong>base</strong> where the
resources are to be found. This is typically only used with JAR files when
the resources are not located at the root of the JAR as is the case with
resource JARs. This attribute is required by the
<code>org.apache.catalina.WebResourceSet</code> implementations provided
by Tomcat and must start with '/'. Custom implementations may not require
it. If not specified, the default value '/' will be used.</p>
</attribute>
<attribute name="readOnly" required="false">
<p>If <code>true</code>, resources within this resource set may not be
deleted, created or modified. For instance of
<code>org.apache.catalina.webresources.JarResourceSet</code>, this
attribute is hard-coded to <code>true</code> and may not be changed. For
instances of <code>org.apache.catalina.webresources.DirResourceSet</code>
and <code>org.apache.catalina.webresources.FileResourceSet</code> the
default value of this attribute is <code>false</code>.</p>
</attribute>
<attribute name="webAppMount" required="false">
<p>Identifies the path within the web application that these resources
will be made available. For the
<code>org.apache.catalina.WebResourceSet</code> implementations provided
by Tomcat, this attribute is required and must start with '/'. Custom
implementations may not require it. If not specified, the default value of
'/' will be used.</p>
</attribute>
</attributes>
<h3>JAR resources</h3>
<p>JarResources are searched after the main resources but before the
PostResources. They will be searched in the order they are defined. To
configure JarResources, nest a &lt;JarResources&gt; element inside the
&lt;Resources&gt; element. The configuration attributes are the same as for
<strong>PreResources</strong>.
</p>
<p>During web application start, the JAR scanning process checks scanned JARs
for content under <code>/META-INF/resources</code>. Where found, this static
content is added to the JarResources.
</p>
<h3>Post-resources</h3>
<p>PostResources are searched after the resource JARs. They will be searched
in the order they are defined. To configure PostResources, nest a
&lt;PostResources&gt; element inside the &lt;Resources&gt; element. The
configuration attributes are the same as for <strong>PreResources</strong>.
</p>
<h3>Ordering</h3>
<p>In addition to the sets of resources described above, the standard
implementation also maintains ClassResources which represent the classes
contained in the JAR files mapped to <code>/WEB-INF/classes</code>. This
allows other components to search for classes with a single call rather than
one call to search <code>/WEB-INF/classes</code> followed by another to search
the JARs in <code>/WEB-INF/lib</code>. The ClassResources are populated
from the JARs mapped to <code>/WEB-INF/lib</code> when the web application
starts.</p>
<p>Therefore, the complete search order is:</p>
<ul>
<li>PreResources</li>
<li>MainResources</li>
<li>ClassResources</li>
<li>JarResources</li>
<li>PostResources</li>
</ul>
<p>The population of ClassResources and JarResources at web application start
means that care needs to be taken to add JAR based resources correctly to
obtain the desired behaviour. Consider the following example:</p>
<source><![CDATA[<Resources>
<PostResources base="D:\Projects\external\classes"
className="org.apache.catalina.webresources.DirResourceSet"
webAppMount="/WEB-INF/classes"/>
<PostResources base="D:\Projects\lib\library1.jar"
className="org.apache.catalina.webresources.FileResourceSet"
webAppMount="/WEB-INF/lib/library1.jar"/>
</Resources>]]></source>
<p>Since both resources are PostResources, it might be expected that
<code>D:\Projects\external\classes</code> will be searched for classes before
<code>D:\Projects\lib\library1.jar</code>. However, by adding the JAR using a
<code>FileResourceSet</code>, the JAR is mapped to <code>/WEB-INF/lib</code>
and will be processed at application start along with the other JARs in
<code>/WEB-INF/lib</code>. The classes from the JAR file will be added to the
ClassResources which means they will be searched before the classes from
<code>D:\Projects\external\classes</code>. If the desired behaviour is that
<code>D:\Projects\external\classes</code> is searched before
<code>D:\Projects\lib\library1.jar</code> then a slightly different
configuration is required:</p>
<source><![CDATA[<Resources>
<PostResources base="D:\Projects\external\classes"
className="org.apache.catalina.webresources.DirResourceSet"
webAppMount="/WEB-INF/classes"/>
<PostResources base="D:\Projects\lib\library1.jar"
className="org.apache.catalina.webresources.JarResourceSet"
webAppMount="/WEB-INF/classes"/>
</Resources>]]></source>
<p>In short, the JAR file should be added as a <code>JarResourceSet</code>
mapped to <code>/WEB-INF/classes</code> rather than using a
<code>FileResourceSet</code> mapped to <code>/WEB-INF/lib</code>.
</p>
</section>
<section name="Special Features">
<p>No special features are associated with a <strong>Resources</strong>
element.</p>
</section>
</body>
</document>

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

@@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="server.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Server Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>A <strong>Server</strong> element represents the entire Catalina
servlet container. Therefore, it must be the single outermost element
in the <code>conf/server.xml</code> configuration file. Its attributes
represent the characteristics of the servlet container as a whole.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Server</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Server</code> interface.
If no class name is specified, the standard implementation will
be used.</p>
</attribute>
<attribute name="address" required="false">
<p>The TCP/IP address on which this server waits for a shutdown
command. If no address is specified, <code>localhost</code> is used.</p>
</attribute>
<attribute name="port" required="true">
<p>The TCP/IP port number on which this server waits for a shutdown
command. Set to <code>-1</code> to disable the shutdown port.</p>
<p>Note: Disabling the shutdown port works well when Tomcat is started
using <a href="https://commons.apache.org/daemon/">Apache Commons Daemon</a>
(running as a service on Windows or with jsvc on un*xes). It cannot be
used when running Tomcat with the standard shell scripts though, as it
will prevent shutdown.bat|.sh and catalina.bat|.sh from stopping it
gracefully.</p>
</attribute>
<attribute name="shutdown" required="true">
<p>The command string that must be received via a TCP/IP connection
to the specified port number, in order to shut down Tomcat.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Server</strong> is
<strong>org.apache.catalina.core.StandardServer</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>The following components may be nested inside a <strong>Server</strong>
element:</p>
<ul>
<li><a href="service.html"><strong>Service</strong></a> -
One or more service element.</li>
<li><a href="globalresources.html"><strong>GlobalNamingResources</strong></a> -
Configure the JNDI global resources for the server.</li>
</ul>
</section>
<section name="Special Features">
<p>There are no special features associated with a <strong>Server</strong>.
</p>
</section>
</body>
</document>

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

@@ -0,0 +1,109 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="service.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig R. McClanahan</author>
<title>The Service Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>A <strong>Service</strong> element represents the combination of one or
more <strong>Connector</strong> components that share a single
<a href="engine.html">Engine</a> component for processing incoming
requests. One or more <strong>Service</strong> elements may be nested
inside a <a href="server.html">Server</a> element.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>Service</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.Service</code> interface.
If no class name is specified, the standard implementation will
be used.</p>
</attribute>
<attribute name="name" required="true">
<p>The display name of this <strong>Service</strong>, which will
be included in log messages if you utilize standard Catalina
components. The name of each <strong>Service</strong> that is
associated with a particular <a href="server.html">Server</a>
must be unique.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>The standard implementation of <strong>Service</strong> is
<strong>org.apache.catalina.core.StandardService</strong>.
It supports the following additional attributes (in addition to the
common attributes listed above):</p>
<attributes>
</attributes>
</subsection>
</section>
<section name="Nested Components">
<p>The only components that may be nested inside a <strong>Service</strong>
element are one or more <strong>Connector</strong> elements,
followed by exactly one <a href="engine.html">Engine</a> element.</p>
</section>
<section name="Special Features">
<p>There are no special features associated with a <strong>Service</strong>.
</p>
</section>
</body>
</document>

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

@@ -0,0 +1,131 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="sessionidgenerator.html">
&project;
<properties>
<title>The SessionIdGenerator Component</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The <strong>SessionIdGenerator</strong> element represents the <em>session
id generator</em> that will be used to create session ids used by
web application HTTP sessions.</p>
<p>A SessionIdGenerator element MAY be nested inside a
<a href="manager.html">Manager</a> component. If it is not included,
a default SessionIdGenerator configuration will be created automatically, which
is sufficient for most requirements, &#x2014; see
<em>Standard SessionIdGenerator Implementation</em> below for the details
of this configuration.</p>
</section>
<section name="Attributes">
<subsection name="Common Attributes">
<p>All implementations of <strong>SessionIdGenerator</strong>
support the following attributes:</p>
<attributes>
<attribute name="className" required="false">
<p>Java class name of the implementation to use. This class must
implement the <code>org.apache.catalina.SessionIdGenerator</code> interface.
If not specified, the standard value (defined below) will be used.</p>
</attribute>
<attribute name="jvmRoute" required="false">
<p>A routing identifier for this Tomcat instance. It will be added
to the session id to allow for stateless stickyness routing by
load balancers. The details on how the <code>jvmRoute</code>
will be included in the id are implementation dependent.
See <a href="#Standard_Implementation">Standard Implementation</a>
for the default behavior.</p>
<p><strong>NOTE</strong> - The value for this property is inherited
automatically from the <code>jvmRoute</code> attribute of the
<a href="engine.html">Engine</a> element.</p>
</attribute>
<attribute name="sessionIdLength" required="false">
<p>The length of session ids created by this SessionIdGenerator.
The details on how the <code>sessionIdLength</code>
influences the session id length are implementation dependent.
See <a href="#Standard_Implementation">Standard Implementation</a>
for the default behavior.</p>
</attribute>
</attributes>
</subsection>
<subsection name="Standard Implementation">
<p>Tomcat provides a standard implementations of <strong>SessionIdGenerator</strong>
for use.</p>
<h3>Standard SessionIdGenerator Implementation</h3>
<p>The standard implementation of <strong>SessionIdGenerator</strong> is
<strong>org.apache.catalina.util.StandardSessionIdGenerator</strong>.
It supports the following attributes:</p>
<attributes>
<attribute name="jvmRoute" required="false">
<p>A routing identifier for this Tomcat instance. It will be added
to the end of the session id separated by a &quot;.&quot;.</p>
</attribute>
<attribute name="sessionIdLength" required="false">
<p>The length of session ids created by this SessionIdGenerator.
More precisely the session id length is twice the value of
<code>sessionIdLength</code> plus the length of the trailing
<code>jvmRoute</code> if given. The factor 2 is because
the session id is constructed using <code>sessionIdLength</code>
random bytes, each byte being encoded in two hex characters
in the actual id. The default value is 16.</p>
</attribute>
</attributes>
</subsection>
</section>
</body>
</document>

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

@@ -0,0 +1,693 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="systemprops.html">
&project;
<properties>
<title>System Properties</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>The following sections list the system properties that may be set to modify
the default Tomcat behaviour.</p>
</section>
<section name="Property replacements">
<properties>
<property name="org.apache.tomcat.util.digester. PROPERTY_SOURCE">
<p>Set this to a fully qualified name of a class that implements
<code>org.apache.tomcat.util.IntrospectionUtils.PropertySource</code>.
Required to have a public constructor with no arguments.</p>
<p>Use this to add a property source, that will be invoked when
<code>${parameter}</code> denoted parameters are found in the XML files
that Tomcat parses.</p>
<p>Property replacement from the specified property source on the JVM
system properties can also be done using the
<code>REPLACE_SYSTEM_PROPERTIES</code> system property.</p>
<p><code>org.apache.tomcat.util.digester.Digester$EnvironmentPropertySource</code>
can be used to replace parameters from the process' environment
variables, e.g. injected ConfigMaps or Secret objects in container
based systems like OpenShift or Kubernetes.</p>
</property>
<property name="org.apache.tomcat.util.digester. REPLACE_SYSTEM_PROPERTIES">
<p>Set this boolean system property to <code>true</code> to cause
property replacement from the digester property source on the JVM
system properties.</p>
</property>
</properties>
</section>
<section name="Clustering">
<properties>
<property name="org.apache.catalina. tribes.dns_lookups">
<p>If <code>true</code>, the clustering module will attempt to use DNS to
resolve any host names provided in the cluster configuration.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
</properties>
</section>
<section name="Expression Language">
<properties>
<property name="org.apache.el.BeanELResolver. CACHE_SIZE">
<p>The number of javax.el.BeanELResolver.BeanProperties objects that will
be cached by the EL Parser.</p>
<p>If not specified, the default of <code>1000</code> will be used.</p>
</property>
<property name="org.apache.el.ExpressionBuilder. CACHE_SIZE">
<p>The number of parsed EL expressions that will be cached by the EL
Parser.</p>
<p>If not specified, the default of <code>5000</code> will be used.</p>
</property>
<property name="org.apache.el.parser. COERCE_TO_ZERO">
<p>If <code>true</code>, when coercing <code>null</code>s to objects of
type Number, Character or Boolean the result will be <code>0</code> for
Number and Character types and <code>false</code> for Boolean as required
by the EL 2.2 and earlier specifications. If this property is
<code>false</code> the result of the coercion will be <code>null</code> as
required by the EL 3.0 specification.</p>
<p>If not specified, the default value of <code>false</code> will be
used.</p>
</property>
<property name="org.apache.el.parser. SKIP_IDENTIFIER_CHECK">
<p>If <code>true</code>, when parsing expressions, identifiers will not be
checked to ensure that they conform to the Java Language Specification for
Java identifiers.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
</properties>
</section>
<section name="Jasper">
<properties>
<property name="org.apache.jasper.compiler. Generator.POOL_TAGS_WITH_EXTENDS">
<p>By default, JSPs that use their own base class via the extends
attribute of the page directive, will have Tag pooling disabled since
Jasper cannot guarantee that the necessary initialisation will have taken
place. This can have a negative impact on performance. Providing the
alternative base class calls _jspInit() from Servlet.init(), setting this
property to <code>true</code> will enable pooling with an alternative base
class. If the alternative base class does not call _jspInit() and this
property is <code>true</code>, NPEs will occur when attempting to use
tags.</p>
<p>If not specified, the default value of <code>false</code> will be used.
</p>
</property>
<property name="org.apache.jasper.compiler. Generator.STRICT_GET_PROPERTY">
<p>If <code>true</code>, the requirement to have the object referenced in
<code>jsp:getProperty</code> action to be previously "introduced"
to the JSP processor, as specified in the chapter JSP.5.3 of JSP 2.0 and
later specifications, is enforced.</p>
<p>If not specified, the specification compliant default of
<code>true</code> will be used.</p>
</property>
<property name="org.apache.jasper.compiler. Generator.VAR_EXPRESSIONFACTORY">
<p>The name of the variable to use for the expression language expression
factory.</p>
<p>If not specified, the default value of <code>_el_expressionfactory</code>
will be used.</p>
</property>
<property name="org.apache.jasper.compiler. Generator.VAR_INSTANCEMANAGER">
<p>The name of the variable to use for the instance manager factory.</p>
<p>If not specified, the default value of <code>_jsp_instancemanager</code>
will be used.</p>
</property>
<property name="org.apache.jasper.compiler. Parser.STRICT_WHITESPACE">
<p>If <code>false</code> the requirements for whitespace before an
attribute name will be relaxed so that the lack of whitespace will not
cause an error.</p>
<p>If not specified, the specification compliant default of
<code>true</code> will be used.</p>
</property>
<property name="org.apache.jasper.runtime. BodyContentImpl.BUFFER_SIZE">
<p>The size (in characters) to use when creating a tag buffer.</p>
<p>If not specified, the default value of
<code>org.apache.jasper.Constants.DEFAULT_TAG_BUFFER_SIZE</code> (512)
will be used.</p>
</property>
<property name="org.apache.jasper.runtime. BodyContentImpl.LIMIT_BUFFER">
<p>If <code>true</code>, any tag buffer that expands beyond
<code>org.apache.jasper.runtime.BodyContentImpl.BUFFER_SIZE</code> will be
destroyed and a new buffer created.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property name="org.apache.jasper.runtime. JspFactoryImpl.USE_POOL">
<p>If <code>true</code>, a ThreadLocal <code>PageContext</code> pool will
be used.</p>
<p>If not specified, the default value of <code>true</code> will be used.</p>
</property>
<property name="org.apache.jasper.runtime. JspFactoryImpl.POOL_SIZE">
<p>The size of the ThreadLocal <code>PageContext</code>.</p>
<p>If not specified, the default value of <code>8</code> will be used.</p>
</property>
<property name="org.apache.jasper.Constants. JSP_SERVLET_BASE">
<p>The base class of the Servlets generated from the JSPs.</p>
<p>If not specified, the default value of
<code>org.apache.jasper.runtime.HttpJspBase</code> will be used.</p>
</property>
<property name="org.apache.jasper.Constants. SERVICE_METHOD_NAME">
<p>The name of the service method called by the base class.</p>
<p>If not specified, the default value of <code>_jspService</code>
will be used.</p>
</property>
<property name="org.apache.jasper.Constants. SERVLET_CLASSPATH">
<p>The name of the ServletContext attribute that provides the classpath
for the JSP.</p>
<p>If not specified, the default value of
<code>org.apache.catalina.jsp_classpath</code> will be used.</p>
</property>
<property name="org.apache.jasper.Constants. JSP_FILE">
<p>The name of the request attribute for <code>&lt;jsp-file&gt;</code>
element of a servlet definition. If present on a request, this overrides
the value returned by <code>request.getServletPath()</code> to select the
JSP page to be executed.</p>
<p>If not specified, the default value of
<code>org.apache.catalina.jsp_file</code> will be used.</p>
<p><strong>Deprecated:</strong> This will be removed in Tomcat 9.0.x
onwards. It is replaced by the use of the jspFile servlet initialisation
parameter</p>
</property>
<property name="org.apache.jasper.Constants. PRECOMPILE">
<p>The name of the query parameter that causes the JSP engine to just
pregenerate the servlet but not invoke it.</p>
<p>If not specified, the default value of <code>jsp_precompile</code>
will be used, as defined by JSP specification (JSP.11.4.2).</p>
</property>
<property name="org.apache.jasper.Constants. JSP_PACKAGE_NAME">
<p>The default package name for compiled JSPs.</p>
<p>If not specified, the default value of <code>org.apache.jsp</code>
will be used.</p>
</property>
<property name="org.apache.jasper.Constants. TAG_FILE_PACKAGE_NAME">
<p>The default package name for tag handlers generated from tag files.</p>
<p>If not specified, the default value of <code>org.apache.jsp.tag</code>
will be used.</p>
</property>
<property name="org.apache.jasper.Constants. ALT_DD_ATTR">
<p>The servlet context attribute under which the alternate deployment
descriptor for this web application is stored.</p>
<p>If not specified, the default value of
<code>org.apache.catalina.deploy.alt_dd</code> will be used.</p>
</property>
<property name="org.apache.jasper.Constants. TEMP_VARIABLE_NAME_PREFIX">
<p>Prefix to use for generated temporary variable names.</p>
<p>If not specified, the default value of <code>_jspx_temp</code>
will be used.</p>
</property>
<property name="org.apache.jasper.Constants. USE_INSTANCE_MANAGER_FOR_TAGS">
<p>If <code>true</code>, the instance manager is used to obtain tag
handler instances.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
</properties>
</section>
<section name="Security">
<properties>
<property name="org.apache.catalina.connector. RECYCLE_FACADES">
<p>If this is <code>true</code> or if a security manager is in use a new
facade object will be created for each request.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property
name="org.apache.catalina.connector. CoyoteAdapter.ALLOW_BACKSLASH">
<p>If this is <code>true</code> the '\' character will be permitted as a
path delimiter.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property
name="org.apache.tomcat.util.buf. UDecoder.ALLOW_ENCODED_SLASH">
<p>If this is <code>true</code> '%2F' and '%5C' will be permitted as path
delimiters.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
</properties>
</section>
<section name="Specifications">
<properties>
<property name="org.apache.catalina. STRICT_SERVLET_COMPLIANCE">
<p>The default value of this system property is <code>false</code>.</p>
<p>If this is <code>true</code> the default values will be changed for:</p>
<ul>
<li><code>org.apache.catalina.core.<br/>ApplicationContext.GET_RESOURCE_REQUIRE_SLASH</code></li>
<li><code>org.apache.catalina.core.<br/>ApplicationDispatcher.WRAP_SAME_OBJECT</code></li>
<li><code>org.apache.catalina.core.<br/>StandardHostValve.ACCESS_SESSION</code></li>
<li><code>org.apache.catalina.session.<br/>StandardSession.ACTIVITY_CHECK</code></li>
<li><code>org.apache.catalina.session.<br/>StandardSession.LAST_ACCESS_AT_START</code></li>
<li><code>org.apache.tomcat.util.http.<br/>ServerCookie.STRICT_NAMING</code></li>
<li>The <code>URIEncoding</code> attribute of any
<a href="http.html">HTTP connector</a> or
<a href="ajp.html">AJP connector</a> element.</li>
<li>The <code>resourceOnlyServlets</code> attribute of any
<a href="context.html">Context</a> element.</li>
<li>The <code>tldValidation</code> attribute of any
<a href="context.html">Context</a> element.</li>
<li>The <code>useRelativeRedirects</code> attribute of any
<a href="context.html">Context</a> element.</li>
<li>The <code>xmlNamespaceAware</code> attribute of any
<a href="context.html">Context</a> element.</li>
<li>The <code>xmlValidation</code> attribute of any
<a href="context.html">Context</a> element.</li>
</ul>
</property>
<property name="org.apache.catalina.connector. Response.ENFORCE_ENCODING_IN_GET_WRITER">
<p>If this is <code>true</code> then
a call to <code>Response.getWriter()</code> if no character encoding
has been specified will result in subsequent calls to
<code>Response.getCharacterEncoding()</code> returning
<code>ISO-8859-1</code> and the <code>Content-Type</code> response header
will include a <code>charset=ISO-8859-1</code> component. (SRV.15.2.22.1)</p>
<p>If not specified, the default specification compliant value of
<code>true</code> will be used.</p>
</property>
<property name="org.apache.catalina.core.ApplicationContext .GET_RESOURCE_REQUIRE_SLASH">
<p>If this is <code>true</code> then the path passed to
<code>ServletContext.getResource()</code> or
<code>ServletContext.getResourceAsStream()</code> must start with
&quot;/&quot;. If <code>false</code>, code like
<code>getResource("myfolder/myresource.txt")</code> will work as Tomcat
will prepend &quot;/&quot; to the provided path.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</property>
<property name="org.apache.catalina.core. ApplicationDispatcher.WRAP_SAME_OBJECT">
<p>If this is <code>true</code> then any wrapped request or response
object passed to an application dispatcher will be checked to ensure that
it has wrapped the original request or response.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</property>
<property name="org.apache.tomcat.websocket. STRICT_SPEC_COMPLIANCE">
<p>The default value of this system property is <code>false</code>.</p>
<p>If this is <code>true</code> the default values will be changed for:</p>
<ul>
<li><code>org.apache.tomcat.websocket.server#isEnforceNoAddAfterHandshake</code>
(default changes from <code>false</code> to <code>true</code>)</li>
</ul>
</property>
<property name="org.apache.tomcat.util.http. ServerCookie.STRICT_NAMING">
<p> If this is <code>true</code> then the requirements of the Servlet specification
that Cookie names must adhere to RFC2109 will be enforced. If this is
<code>false</code> the naming rules specified in RFC6265 (allow the leading "$")
will be used.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</property>
</properties>
</section>
<section name="Sessions">
<properties>
<property name="org.apache.catalina.authenticator.
Constants.SSO_SESSION_COOKIE_NAME">
<p>An alternative name for the single sign on session cookie. Defaults to
<code>JSESSIONIDSSO</code>.</p>
</property>
<property name="org.apache.catalina.core. StandardHostValve.ACCESS_SESSION">
<p>If this is <code>true</code>, every request that is associated with a
session will cause the session's last accessed time to be updated
regardless of whether or not the request explicitly accesses the session.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</property>
<property
name="org.apache.catalina.session. StandardSession.ACTIVITY_CHECK">
<p>If this is <code>true</code>, Tomcat will track the number of active
requests for each session. When determining if a session is valid, any
session with at least one active request will always be considered valid.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</property>
<property
name="org.apache.catalina.session. StandardSession.LAST_ACCESS_AT_START">
<p>If this is <code>true</code>, the last accessed time for sessions will
be calculated from the beginning of the previous request. If
<code>false</code>, the last accessed time for sessions will be calculated
from the end of the previous request. This also affects how the idle time
is calculated.</p>
<p>If <code>org.apache.catalina.STRICT_SERVLET_COMPLIANCE</code> is set to
<code>true</code>, the default of this setting will be <code>true</code>,
else the default value will be <code>false</code>.</p>
</property>
</properties>
</section>
<section name="Logging">
<properties>
<property name="org.apache.juli.formatter">
<p>If no logging configuration file is specified and no logging configuration class is specified
using the <code>java.util.logging.config.class</code> and <code>java.util.logging.config.file</code>
properties the default logging framework <code>org.apache.juli</code> will use the default
<code>java.util.logging.SimpleFormatter</code> for all console output.
To simply override the console output formatter, one can use the described property. Example:
<code>-Dorg.apache.juli.formatter=org.apache.juli.OneLineFormatter</code></p>
</property>
<property name="org.apache.juli. AsyncMaxRecordCount">
<p>The maximum number of log records that the JULI AsyncFileHandler will queue in memory.
New records are added to the queue and get asynchronously removed from the queue
and written to the files by a single writer thread.
When the queue is full and a new record is being logged
the log record will be handled based on the <code>org.apache.juli.AsyncOverflowDropType</code> setting.</p>
<p>The default value is <code>10000</code> records.
This number represents the global number of records, not on a per handler basis.
</p>
</property>
<property name="org.apache.juli. AsyncOverflowDropType">
<p>When the queue of log records of the JULI AsyncFileHandler is full,
new log records are handled according to the following setting:
</p>
<ul>
<li><code>1</code> - the newest record in the queue will be dropped and not logged</li>
<li><code>2</code> - the oldest record in the queue will be dropped and not logged</li>
<li><code>3</code> - suspend the logging thread until older records got written to the log file and the queue is no longer full.
This is the only setting that ensures that no messages get lost.</li>
<li><code>4</code> - drop the current log record</li>
</ul>
<p>The default value is <code>1</code> (drop the newest record in the queue).</p>
</property>
<property name="org.apache.juli. AsyncLoggerPollInterval">
<p>The poll interval in milliseconds for the asynchronous logger thread.
If the log queue is empty, the async thread will issue a poll(poll interval)
in order to not wake up too often.</p>
<p>The default value is <code>1000</code> milliseconds.</p>
</property>
<property name="org.apache.juli.logging. UserDataHelper.CONFIG">
<p>The type of logging to use for errors generated by invalid input data.
The options are: <code>DEBUG_ALL</code>, <code>INFO_THEN_DEBUG</code>,
<code>INFO_ALL</code> and <code>NONE</code>. When
<code>INFO_THEN_DEBUG</code> is used, the period for which errors are
logged at DEBUG rather than INFO is controlled by the system property
<code>org.apache.juli.logging.UserDataHelper.SUPPRESSION_TIME</code>.
</p>
<p>The default value is <code>INFO_THEN_DEBUG</code>.</p>
<p>The errors currently logged using this system are:</p>
<ul>
<li>invalid cookies;</li>
<li>invalid parameters;</li>
<li>too many headers, too many parameters (hitting
<code>maxHeaderCount</code> or <code>maxParameterCount</code> limits
of a <a href="http.html">connector</a>).</li>
<li>invalid host names</li>
</ul>
<p>Other errors triggered by invalid input data may be added to this
system in later versions.</p>
</property>
<property name="org.apache.juli.logging. UserDataHelper.SUPPRESSION_TIME">
<p>When using <code>INFO_THEN_DEBUG</code> for
<code>org.apache.juli.logging.UserDataHelper.CONFIG</code> this system
property controls how long messages are logged at DEBUG after a message
has been logged at INFO. Once this period has elapsed, the next message
will be logged at INFO followed by a new suppression period where
messages are logged at DEBUG and so on. The value is measured
in seconds.</p>
<p>A value of <code>0</code> is equivalent to using <code>INFO_ALL</code>
for <code>org.apache.juli.logging.UserDataHelper.CONFIG</code>.</p>
<p>A negative value means an infinite suppression period.</p>
<p>The default value is <code>86400</code> (24 hours).</p>
</property>
</properties>
</section>
<section name="JAR Scanning">
<properties>
<property name="tomcat.util.scan. StandardJarScanFilter.jarsToSkip">
<p>A list of comma-separated file name patters that is used as the default
value for <code>pluggabilitySkip</code> and <code>tldSkip</code>
attributes of the standard
<a href="jar-scan-filter.html">JarScanFilter</a> implementation.</p>
<p>The coded default is empty, however the system property is set in
a default Tomcat installation via the
<code>$CATALINA_BASE/conf/catalina.properties</code> file.</p>
</property>
<property name="tomcat.util.scan. StandardJarScanFilter.jarsToScan">
<p>A list of comma-separated file name patters that is used as the default
value for <code>pluggabilityScan</code> and <code>tldScan</code>
attributes of the standard
<a href="jar-scan-filter.html">JarScanFilter</a> implementation.</p>
<p>The coded default is empty, however the system property is set in
a default Tomcat installation via the
<code>$CATALINA_BASE/conf/catalina.properties</code> file.</p>
</property>
</properties>
</section>
<section name="Websockets">
<properties>
<property name="org.apache.tomcat. websocket.ALLOW_UNSUPPORTED_EXTENSIONS">
<p>If <code>true</code>, allow unknown extensions to be declared by
the user.</p>
<p>The default value is <code>false</code>.</p>
</property>
<property name="org.apache.tomcat. websocket.DEFAULT_ORIGIN_HEADER_VALUE">
<p>Default value of the origin header that will be sent by the client
during the upgrade handshake.</p>
<p>The default is null so that no origin header is sent.</p>
</property>
<property name="org.apache.tomcat. websocket.DEFAULT_PROCESS_PERIOD">
<p>The number of periodic ticks between periodic processing which
involves in particular session expiration checks.</p>
<p>The default value is <code>10</code> which corresponds to 10
seconds.</p>
</property>
<property name="org.apache.tomcat. websocket.DISABLE_BUILTIN_EXTENSIONS">
<p>If <code>true</code>, disable all built-in extensions provided by the
server, such as message compression.</p>
<p>The default value is <code>false</code>.</p>
</property>
</properties>
</section>
<section name="Other">
<properties>
<property
name="org.apache.coyote. USE_CUSTOM_STATUS_MSG_IN_HEADER"><p>If this is
<code>true</code>, custom HTTP status messages will be used within HTTP
headers. If a custom message is specified that is not valid for use in an
HTTP header (as defined by RFC2616) then the custom message will be
ignored and the default message used.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
<p><strong>Note:</strong> This option is deprecated and will be removed
in Tomcat 9. The reason phrase will not be sent.</p>
</property>
<property name="catalina.useNaming">
<p>If this is <code>false</code> it will override the
<code>useNaming</code> attribute for all <a href="context.html">
Context</a> elements.</p>
</property>
<property name="javax.sql.DataSource.Factory">
<p>The class name of the factory to use to create resources of type
<code>javax.sql.DataSource</code>. If not specified the default of
<code>org.apache.tomcat.dbcp.dbcp2.BasicDataSourceFactory</code> is used
which is a package renamed (to avoid conflicts) copy of
<a href="https://commons.apache.org/dbcp">Apache Commons DBCP 2</a>.</p>
</property>
<property name="javax.mail.Session.Factory">
<p>The class name of the factory to use to create resources of type
<code>javax.mail.Session</code>. If not specified the default of
<code>org.apache.naming.factory.MailSessionFactory</code> is used.</p>
</property>
<property name="jvmRoute">
<p>Provides a default value for the <code>jvmRoute</code> attribute of the
<a href="engine.html">Engine</a> element. It does not override the value
configured on the <a href="engine.html">Engine</a> element.</p>
</property>
<property name="catalina.config">
<p>The URL for the catalina.properties configuration file.</p>
</property>
<property name="tomcat.util.buf.StringCache.byte.enabled">
<p>If <code>true</code>, the String cache is enabled for
<code>ByteChunk</code>.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property name="tomcat.util.buf.StringCache.char.enabled">
<p>If <code>true</code>, the String cache is enabled for
<code>CharChunk</code>.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property name="tomcat.util.buf.StringCache.trainThreshold">
<p>The number of times <code>toString()</code> must be called before the
cache is activated.</p>
<p>If not specified, the default value of <code>20000</code> will be used.</p>
</property>
<property name="tomcat.util.buf.StringCache.cacheSize">
<p>The size of the String cache.</p>
<p>If not specified, the default value of <code>200</code> will be used.</p>
</property>
<property name="org.apache.tomcat.util.buf.UriUtil. WAR_SEPARATOR">
<p>The character to use to separate the WAR file and WAR content parts of
a WAR URL using the custom WAR scheme provided by Tomcat. This is
equivalent to how <code>!</code> is used in JAR URLs.</p>
<p>If not specified, the default value of <code>*</code> will be used.</p>
</property>
<property name="tomcat.util.buf.StringCache.maxStringSize">
<p>The maximum length of String that will be cached.</p>
<p>If not specified, the default value of <code>128</code> will be used.</p>
</property>
<property name="org.apache.tomcat.util. http.FastHttpDateFormat.CACHE_SIZE">
<p>The size of the cache to use parsed and formatted date value.</p>
<p>If not specified, the default value of <code>1000</code> will be used.</p>
</property>
<property name="org.apache.tomcat.util. net.NioSelectorShared">
<p>If <code>true</code>, use a shared selector for servlet write/read.</p>
<p>If not specified, the default value of <code>true</code> will be used.</p>
</property>
<property name="org.apache.catalina.startup. EXIT_ON_INIT_FAILURE">
<p>If <code>true</code>, the server will exit if an exception happens
during the server initialization phase.</p>
<p>If not specified, the default value of <code>false</code> will be used.</p>
</property>
<property name="org.apache.catalina.startup. RealmRuleSet.MAX_NESTED_REALM_LEVELS">
<p>The CombinedRealm allows nested Realms. This property controls the
maximum permitted number of levels of nesting.</p>
<p>If not specified, the default value of <code>3</code> will be used.</p>
</property>
<property name="org.apache.catalina.startup. CredentialHandlerRuleSet.MAX_NESTED_LEVELS">
<p>The NestedCredentialHandler allows nested CredentialHandlers. This
property controls the maximum permitted number of levels of nesting.</p>
<p>If not specified, the default value of <code>3</code> will be used.</p>
</property>
<property name="tomcat.util.http.parser.HttpParser. requestTargetAllow">
<p><i>This system property is deprecated. Use the
<code>relaxedPathChars</code> and <code>relaxedQueryChars</code>
attributes of the Connector instead. These attributes permit a wider range
of characters to be configured as valid.</i></p>
<p>A string comprised of characters the server should allow even when they are not encoded.
These characters would normally result in a 400 status.</p>
<p>The acceptable characters for this property are: <code>|</code>, <code>{</code>
, and <code>}</code></p>
<p><strong>WARNING</strong>: Use of this option may expose the server to CVE-2016-6816.
</p>
<p>If not specified, the default value of <code>null</code> will be used.</p>
</property>
</properties>
</section>
</body>
</document>

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

File diff suppressed because it is too large Load Diff

80
webapps/docs/connectors.xml Normal file
View File

@@ -0,0 +1,80 @@
<?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="connectors.html">
&project;
<properties>
<author email="remm@apache.org">Remy Maucherat</author>
<title>Connectors How To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>Choosing a connector to use with Tomcat can be difficult. This page will
list the connectors which are supported with this Tomcat release, and will
hopefully help you make the right choice according to your needs.</p>
</section>
<section name="HTTP">
<p>The HTTP connector is setup by default with Tomcat, and is ready to use. This
connector features the lowest latency and best overall performance.</p>
<p>For clustering, an HTTP load balancer <b>with support for web sessions stickiness</b>
must be installed to direct the traffic to the Tomcat servers. Tomcat supports mod_proxy
(on Apache HTTP Server 2.x, and included by default in Apache HTTP Server 2.2) as the load balancer.
It should be noted that the performance of HTTP proxying is usually lower than the
performance of AJP, so AJP clustering is often preferable.</p>
</section>
<section name="AJP">
<p>When using a single server, the performance when using a native webserver in
front of the Tomcat instance is most of the time significantly worse than a
standalone Tomcat with its default HTTP connector, even if a large part of the web
application is made of static files. If integration with the native webserver is
needed for any reason, an AJP connector will provide faster performance than
proxied HTTP. AJP clustering is the most efficient from the Tomcat perspective.
It is otherwise functionally equivalent to HTTP clustering.</p>
<p>The native connectors supported with this Tomcat release are:</p>
<ul>
<li>JK 1.2.x with any of the supported servers</li>
<li>mod_proxy on Apache HTTP Server 2.x (included by default in Apache HTTP Server 2.2),
with AJP enabled</li>
</ul>
<p><b>Other native connectors supporting AJP may work, but are no longer supported.</b></p>
</section>
</body>
</document>

317
webapps/docs/default-servlet.xml Normal file
View File

@@ -0,0 +1,317 @@
<?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="default-servlet.html">
&project;
<properties>
<author email="funkman@apache.org">Tim Funk</author>
<title>Default Servlet Reference</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section anchor="what" name="What is the DefaultServlet">
<p>
The default servlet is the servlet which serves static resources as well
as serves the directory listings (if directory listings are enabled).
</p>
</section>
<section anchor="where" name="Where is it declared?">
<p>
It is declared globally in <i>$CATALINA_BASE/conf/web.xml</i>.
By default here is it's declaration:
</p>
<source><![CDATA[ <servlet>
<servlet-name>default</servlet-name>
<servlet-class>
org.apache.catalina.servlets.DefaultServlet
</servlet-class>
<init-param>
<param-name>debug</param-name>
<param-value>0</param-value>
</init-param>
<init-param>
<param-name>listings</param-name>
<param-value>false</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
...
<servlet-mapping>
<servlet-name>default</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>]]></source>
So by default, the default servlet is loaded at webapp startup and
directory listings are disabled and debugging is turned off.
</section>
<section anchor="change" name="What can I change?">
<p>
The DefaultServlet allows the following initParamters:
</p>
<properties>
<property name="debug">
Debugging level. It is not very useful unless you are a tomcat
developer. As
of this writing, useful values are 0, 1, 11, 1000. [0]
</property>
<property name="listings">
If no welcome file is present, can a directory listing be
shown?
value may be <b>true</b> or <b>false</b> [false]
<br />
Welcome files are part of the servlet api.
<br />
<b>WARNING:</b> Listings of directories containing many entries are
expensive. Multiple requests for large directory listings can consume
significant proportions of server resources.
</property>
<property name="precompressed">
If a precompressed version of a file exists (a file with <code>.br</code>
or <code>.gz</code> appended to the file name located alongside the
original file), Tomcat will serve the precompressed file if the user
agent supports the matching content encoding (br or gzip) and this
option is enabled. [false]
<br />
The precompressed file with the with <code>.br</code> or <code>.gz</code>
extension will be accessible if requested directly so if the original
resource is protected with a security constraint, the precompressed
versions must be similarly protected.
<br />
It is also possible to configure the list of precompressed formats.
The syntax is comma separated list of
<code>[content-encoding]=[file-extension]</code> pairs. For example:
<code>br=.br,gzip=.gz,bzip2=.bz2</code>. If multiple formats are
specified, the client supports more than one and the client does not
express a preference, the order of the list of formats will be treated
as the server preference order and used to select the format returned.
</property>
<property name="readmeFile">
If a directory listing is presented, a readme file may also
be presented with the listing. This file is inserted as is
so it may contain HTML.
</property>
<property name="globalXsltFile">
If you wish to customize your directory listing, you
can use an XSL transformation. This value is a relative file name (to
either $CATALINA_BASE/conf/ or $CATALINA_HOME/conf/) which will be used
for all directory listings. This can be overridden per context and/or
per directory. See <strong>contextXsltFile</strong> and
<strong>localXsltFile</strong> below. The format of the xml is shown
below.
</property>
<property name="contextXsltFile">
You may also customize your directory listing by context by
configuring <code>contextXsltFile</code>. This must be a context
relative path (e.g.: <code>/path/to/context.xslt</code>) to a file with
a <code>.xsl</code> or <code>.xslt</code> extension. This overrides
<code>globalXsltFile</code>. If this value is present but a file does
not exist, then <code>globalXsltFile</code> will be used. If
<code>globalXsltFile</code> does not exist, then the default
directory listing will be shown.
</property>
<property name="localXsltFile">
You may also customize your directory listing by directory by
configuring <code>localXsltFile</code>. This must be a file in the
directory where the listing will take place to with a
<code>.xsl</code> or <code>.xslt</code> extension. This overrides
<code>globalXsltFile</code> and <code>contextXsltFile</code>. If this
value is present but a file does not exist, then
<code>contextXsltFile</code> will be used. If
<code>contextXsltFile</code> does not exist, then
<code>globalXsltFile</code> will be used. If
<code>globalXsltFile</code> does not exist, then the default
directory listing will be shown.
</property>
<property name="input">
Input buffer size (in bytes) when reading
resources to be served. [2048]
</property>
<property name="output">
Output buffer size (in bytes) when writing
resources to be served. [2048]
</property>
<property name="readonly">
Is this context "read only", so HTTP commands like PUT and
DELETE are rejected? [true]
</property>
<property name="fileEncoding">
File encoding to be used when reading static resources.
[platform default]
</property>
<property name="sendfileSize">
If the connector used supports sendfile, this represents the minimal
file size in KB for which sendfile will be used. Use a negative value
to always disable sendfile. [48]
</property>
<property name="useAcceptRanges">
If true, the Accept-Ranges header will be set when appropriate for the
response. [true]
</property>
<property name="showServerInfo">
Should server information be presented in the response sent to clients
when directory listing is enabled. [true]
</property>
<property name="sortListings">
Should the server sort the listings in a directory. [false]
</property>
<property name="sortDirectoriesFirst">
Should the server list all directories before all files. [false]
</property>
</properties>
</section>
<section anchor="dir" name="How do I customize directory listings?">
<p>You can override DefaultServlet with you own implementation and use that
in your web.xml declaration. If you
can understand what was just said, we will assume you can read the code
to DefaultServlet servlet and make the appropriate adjustments. (If not,
then that method isn't for you)
</p>
<p>
You can use either <code>localXsltFile</code> or
<code>globalXsltFile</code> and DefaultServlet will create
an xml document and run it through an xsl transformation based
on the values provided in <code>localXsltFile</code> and
<code>globalXsltFile</code>. <code>localXsltFile</code> is first
checked, followed by <code>globalXsltFile</code>, then default
behaviors takes place.
</p>
<p>
Format:
</p>
<source><![CDATA[ <listing>
<entries>
<entry type='file|dir' urlPath='aPath' size='###' date='gmt date'>
fileName1
</entry>
<entry type='file|dir' urlPath='aPath' size='###' date='gmt date'>
fileName2
</entry>
...
</entries>
<readme></readme>
</listing>]]></source>
<ul>
<li>size will be missing if <code>type='dir'</code></li>
<li>Readme is a CDATA entry</li>
</ul>
<p>
The following is a sample xsl file which mimics the default tomcat behavior:
</p>
<source>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
&lt;xsl:stylesheet xmlns:xsl=&quot;http://www.w3.org/1999/XSL/Transform&quot;
version=&quot;3.0&quot;&gt;
&lt;xsl:output method=&quot;html&quot; html-version=&quot;5.0&quot;
encoding=&quot;UTF-8&quot; indent=&quot;no&quot;
doctype-system=&quot;about:legacy-compat&quot;/&gt;
&lt;xsl:template match=&quot;listing&quot;&gt;
&lt;html&gt;
&lt;head&gt;
&lt;title&gt;
Sample Directory Listing For
&lt;xsl:value-of select=&quot;@directory&quot;/&gt;
&lt;/title&gt;
&lt;style&gt;
h1 {color : white;background-color : #0086b2;}
h3 {color : white;background-color : #0086b2;}
body {font-family : sans-serif,Arial,Tahoma;
color : black;background-color : white;}
b {color : white;background-color : #0086b2;}
a {color : black;} HR{color : #0086b2;}
table td { padding: 5px; }
&lt;/style&gt;
&lt;/head&gt;
&lt;body&gt;
&lt;h1&gt;Sample Directory Listing For
&lt;xsl:value-of select=&quot;@directory&quot;/&gt;
&lt;/h1&gt;
&lt;hr style=&quot;height: 1px;&quot; /&gt;
&lt;table style=&quot;width: 100%;&quot;&gt;
&lt;tr&gt;
&lt;th style=&quot;text-align: left;&quot;&gt;Filename&lt;/th&gt;
&lt;th style=&quot;text-align: center;&quot;&gt;Size&lt;/th&gt;
&lt;th style=&quot;text-align: right;&quot;&gt;Last Modified&lt;/th&gt;
&lt;/tr&gt;
&lt;xsl:apply-templates select=&quot;entries&quot;/&gt;
&lt;/table&gt;
&lt;xsl:apply-templates select=&quot;readme&quot;/&gt;
&lt;hr style=&quot;height: 1px;&quot; /&gt;
&lt;h3&gt;Apache Tomcat/<version-major-minor/>&lt;/h3&gt;
&lt;/body&gt;
&lt;/html&gt;
&lt;/xsl:template&gt;
&lt;xsl:template match=&quot;entries&quot;&gt;
&lt;xsl:apply-templates select=&quot;entry&quot;/&gt;
&lt;/xsl:template&gt;
&lt;xsl:template match=&quot;readme&quot;&gt;
&lt;hr style=&quot;height: 1px;&quot; /&gt;
&lt;pre&gt;&lt;xsl:apply-templates/&gt;&lt;/pre&gt;
&lt;/xsl:template&gt;
&lt;xsl:template match=&quot;entry&quot;&gt;
&lt;tr&gt;
&lt;td style=&quot;text-align: left;&quot;&gt;
&lt;xsl:variable name=&quot;urlPath&quot; select=&quot;@urlPath&quot;/&gt;
&lt;a href=&quot;{$urlPath}&quot;&gt;
&lt;pre&gt;&lt;xsl:apply-templates/&gt;&lt;/pre&gt;
&lt;/a&gt;
&lt;/td&gt;
&lt;td style=&quot;text-align: right;&quot;&gt;
&lt;pre&gt;&lt;xsl:value-of select=&quot;@size&quot;/&gt;&lt;/pre&gt;
&lt;/td&gt;
&lt;td style=&quot;text-align: right;&quot;&gt;
&lt;pre&gt;&lt;xsl:value-of select=&quot;@date&quot;/&gt;&lt;/pre&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/xsl:template&gt;
&lt;/xsl:stylesheet&gt;</source>
</section>
<section anchor="secure" name="How do I secure directory listings?">
Use web.xml in each individual webapp. See the security section of the
Servlet specification.
</section>
</body>
</document>

353
webapps/docs/deployer-howto.xml Normal file
View File

@@ -0,0 +1,353 @@
<?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="deployer-howto.html">
&project;
<properties>
<author>Allistair Crossley</author>
<title>Tomcat Web Application Deployment</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
Deployment is the term used for the process of installing a web
application (either a 3rd party WAR or your own custom web application)
into the Tomcat server.
</p>
<p>
Web application deployment may be accomplished in a number of ways
within the Tomcat server.
</p>
<ul>
<li>Statically; the web application is setup before Tomcat is started</li>
<li>
Dynamically; by directly manipulating already deployed web
applications (relying on <em>auto-deployment</em>
feature) or remotely by using the Tomcat Manager web
application
</li>
</ul>
<p>
The <a href="manager-howto.html">Tomcat Manager</a> is a web
application that can be used interactively (via HTML GUI) or
programmatically (via URL-based API) to deploy and manage web
applications.
</p>
<p>
There are a number of ways to perform deployment that rely on
the Manager web application. Apache Tomcat provides tasks
for Apache Ant build tool.
<a href="https://tomcat.apache.org/maven-plugin.html">Apache Tomcat Maven Plugin</a>
project provides integration with Apache Maven.
There is also a tool called the Client Deployer, which can be
used from a command line and provides additional functionality
such as compiling and validating web applications as well as
packaging web application into web application resource (WAR)
files.
</p>
</section>
<section name="Installation">
<p>
There is no installation required for static deployment of web
applications as this is provided out of the box by Tomcat. Nor is any
installation required for deployment functions with the Tomcat Manager,
although some configuration is required as detailed in the
<a href="manager-howto.html">Tomcat Manager manual</a>.
An installation is however required if you wish
to use the Tomcat Client Deployer (TCD).
</p>
<p>
The TCD is not packaged with the Tomcat core
distribution, and must therefore be downloaded separately from
the Downloads area. The download is usually labelled
<i>apache-tomcat-<version-major-minor/>.x-deployer</i>.
</p>
<p>
TCD has prerequisites of Apache Ant 1.6.2+ and a Java installation.
Your environment should define an ANT_HOME environment value pointing to
the root of your Ant installation, and a JAVA_HOME value pointing to
your Java installation. Additionally, you should ensure Ant's ant
command, and the Java javac compiler command run from the command shell
that your operating system provides.
</p>
<ol>
<li>Download the TCD distribution</li>
<li>
The TCD package need not be extracted into any existing Tomcat
installation, it can be extracted to any location.
</li>
<li>Read Using the <a href="#Deploying_using_the_Client_Deployer_Package">
Tomcat Client Deployer</a></li>
</ol>
</section>
<section name="A word on Contexts">
<p>
In talking about deployment of web applications, the concept of a
<i>Context</i> is required to be understood. A Context is what Tomcat
calls a web application.
</p>
<p>
In order to configure a Context within Tomcat a <i>Context Descriptor</i>
is required. A Context Descriptor is simply an XML file that contains
Tomcat related configuration for a Context, e.g naming resources or
session manager configuration. In earlier versions of
Tomcat the content of a Context Descriptor configuration was often stored within
Tomcat's primary configuration file <i>server.xml</i> but this is now
discouraged (although it currently still works).
</p>
<p>
Context Descriptors not only help Tomcat to know how to configure
Contexts but other tools such as the Tomcat Manager and TCD often use
these Context Descriptors to perform their roles properly.
</p>
<p>
The locations for Context Descriptors are:
</p>
<ol>
<li>$CATALINA_BASE/conf/[enginename]/[hostname]/[webappname].xml</li>
<li>$CATALINA_BASE/webapps/[webappname]/META-INF/context.xml</li>
</ol>
<p>
Files in (1) are named [webappname].xml but files in (2) are named
context.xml. If a Context Descriptor is not provided for a Context,
Tomcat configures the Context using default values.
</p>
</section>
<section name="Deployment on Tomcat startup">
<p>
If you are not interested in using the Tomcat Manager, or TCD,
then you'll need to deploy your web applications
statically to Tomcat, followed by a Tomcat startup. The location you
deploy web applications to for this type of deployment is called the
<code>appBase</code> which is specified per Host. You either copy a
so-called <i>exploded web application</i>, i.e non-compressed, to this
location, or a compressed web application resource .WAR file.
</p>
<p>
The web applications present in the location specified by the Host's
(default Host is "localhost") <code>appBase</code> attribute (default
appBase is "$CATALINA_BASE/webapps") will be deployed on Tomcat startup
only if the Host's <code>deployOnStartup</code> attribute is "true".
</p>
<p>
The following deployment sequence will occur on Tomcat startup in that
case:
</p>
<ol>
<li>Any Context Descriptors will be deployed first.</li>
<li>
Exploded web applications not referenced by any Context
Descriptor will then be deployed. If they have an associated
.WAR file in the appBase and it is newer than the exploded web application,
the exploded directory will be removed and the webapp will be
redeployed from the .WAR
</li>
<li>.WAR files will be deployed</li>
</ol>
</section>
<section name="Deploying on a running Tomcat server">
<p>
It is possible to deploy web applications to a running Tomcat server.
</p>
<p>
If the Host <code>autoDeploy</code> attribute is "true", the Host will
attempt to deploy and update web applications dynamically, as needed,
for example if a new .WAR is dropped into the <code>appBase</code>.
For this to work, the Host needs to have background processing
enabled which is the default configuration.
</p>
<p>
<code>autoDeploy</code> set to "true" and a running Tomcat allows for:
</p>
<ul>
<li>Deployment of .WAR files copied into the Host <code>appBase</code>.</li>
<li>
Deployment of exploded web applications which are
copied into the Host <code>appBase</code>.
</li>
<li>
Re-deployment of a web application which has already been deployed from
a .WAR when the new .WAR is provided. In this case the exploded
web application is removed, and the .WAR is expanded again.
Note that the explosion will not occur if the Host is configured
so that .WARs are not exploded with a <code>unpackWARs</code>
attribute set to "false", in which case the web application
will be simply redeployed as a compressed archive.
</li>
<li>
Re-loading of a web application if the /WEB-INF/web.xml file (or
any other resource defined as a WatchedResource) is updated.
</li>
<li>
Re-deployment of a web application if the Context Descriptor
file from which the web application has been deployed is
updated.
</li>
<li>
Re-deployment of dependent web applications if the global or
per-host Context Descriptor file used by the web application is
updated.
</li>
<li>
Re-deployment of a web application if a Context Descriptor file (with a
filename corresponding to the Context path of the previously deployed
web application) is added to the
<code>$CATALINA_BASE/conf/[enginename]/[hostname]/</code>
directory.
</li>
<li>
Undeployment of a web application if its document base (docBase)
is deleted. Note that on Windows, this assumes that anti-locking
features (see Context configuration) are enabled, otherwise it is not
possible to delete the resources of a running web application.
</li>
</ul>
<p>
Note that web application reloading can also be configured in the loader, in which
case loaded classes will be tracked for changes.
</p>
</section>
<section name="Deploying using the Tomcat Manager">
<p>
The Tomcat Manager is covered in its <a href="manager-howto.html">own manual page</a>.
</p>
</section>
<section name="Deploying using the Client Deployer Package">
<p>
Finally, deployment of web application may be achieved using the
Tomcat Client Deployer. This is a package which can be used to
validate, compile, compress to .WAR, and deploy web applications to
production or development Tomcat servers. It should be noted that this feature
uses the Tomcat Manager and as such the target Tomcat server should be
running.
</p>
<p>
It is assumed the user will be familiar with Apache Ant for using the TCD.
Apache Ant is a scripted build tool. The TCD comes pre-packaged with a
build script to use. Only a modest understanding of Apache Ant is
required (installation as listed earlier in this page, and familiarity
with using the operating system command shell and configuring
environment variables).
</p>
<p>
The TCD includes Ant tasks, the Jasper page compiler for JSP compilation
before deployment, as well as a task which
validates the web application Context Descriptor. The validator task (class
<code>org.apache.catalina.ant.ValidatorTask</code>) allows only one parameter:
the base path of an exploded web application.
</p>
<p>
The TCD uses an exploded web application as input (see the list of the
properties used below). A web application that is programmatically
deployed with the deployer may include a Context Descriptor in
<code>/META-INF/context.xml</code>.
</p>
<p>
The TCD includes a ready-to-use Ant script, with the following targets:
</p>
<ul>
<li>
<code>compile</code> (default): Compile and validate the web
application. This can be used standalone, and does not need a running
Tomcat server. The compiled application will only run on the associated
<em>Tomcat&#160;X.Y.Z</em> server release, and is not guaranteed to work
on another Tomcat release, as the code generated by Jasper depends on its runtime
component. It should also be noted that this target will also compile
automatically any Java source file located in the
<code>/WEB-INF/classes</code> folder of the web application.</li>
<li>
<code>deploy</code>: Deploy a web application (compiled or not) to
a Tomcat server.
</li>
<li><code>undeploy</code>: Undeploy a web application</li>
<li><code>start</code>: Start web application</li>
<li><code>reload</code>: Reload web application</li>
<li><code>stop</code>: Stop web application</li>
</ul>
<p>
In order for the deployment to be configured, create a file
called <code>deployer.properties</code> in the TCD installation
directory root. In this file, add the following name=value pairs per
line:
</p>
<p>
Additionally, you will need to ensure that a user has been
setup for the target Tomcat Manager (which TCD uses) otherwise the TCD
will not authenticate with the Tomcat Manager and the deployment will
fail. To do this, see the Tomcat Manager page.
</p>
<ul>
<li>
<code>build</code>: The build folder used will be, by default,
<code>${build}/webapp/${path}</code> (<code>${build}</code>, by
default, points to <code>${basedir}/build</code>). After the end
of the execution of the <code>compile</code> target, the web
application .WAR will be located at
<code>${build}/webapp/${path}.war</code>.
</li>
<li>
<code>webapp</code>: The directory containing the exploded web application
which will be compiled and validated. By default, the folder is
<code>myapp</code>.
</li>
<li>
<code>path</code>: Deployed context path of the web application,
by default <code>/myapp</code>.
</li>
<li>
<code>url</code>: Absolute URL to the Tomcat Manager web application of a
running Tomcat server, which will be used to deploy and undeploy the
web application. By default, the deployer will attempt to access
a Tomcat instance running on localhost, at
<code>http://localhost:8080/manager/text</code>.
</li>
<li>
<code>username</code>: Tomcat Manager username (user should have a role of
manager-script)
</li>
<li><code>password</code>: Tomcat Manager password.</li>
</ul>
</section>
</body>
</document>

79
webapps/docs/developers.xml Normal file
View File

@@ -0,0 +1,79 @@
<?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="developers.html">
&project;
<properties>
<author email="remm@apache.org">Remy Maucherat</author>
<author email="yoavs@apache.org">Yoav Shapira</author>
<title>Tomcat Developers</title>
</properties>
<body>
<section name="Active Developers">
<p>
The list indicates the developers' main areas of interest. Feel free to
add to the list :) The developers email addresses are
<code>[login]@apache.org</code>. Please <strong>do not</strong> contact
developers directly for any support issues (please post to the
tomcat-users mailing list instead, or one of the other support
resources; some organizations and individual consultants also offer
for pay Tomcat support, as listed on the
<a href="https://wiki.apache.org/tomcat/SupportAndTraining">support and
training</a> page on the Tomcat Wiki).
</p>
<ul>
<li>Bill Barker (billbarker): Connectors</li>
<li>Costin Manolache (costin): Catalina, Connectors</li>
<li>Filip Hanik (fhanik): Clustering, Release Manager</li>
<li>Jean-Frederic Clere (jfclere): Connectors</li>
<li>Jim Jagielski (jim): Connectors</li>
<li>Konstantin Kolinko (kkolinko): Catalina</li>
<li>Mark Thomas (markt): CGI, SSI, WebDAV, bug fixing</li>
<li>Mladen Turk (mturk): Connectors</li>
<li>Peter Rossbach (pero): Catalina, Clustering, JMX</li>
<li>Rainer Jung (rjung): Catalina, Clustering, Connectors</li>
<li>Remy Maucherat (remm): Catalina, Connectors, Docs</li>
<li>Tim Funk (funkman): Catalina, Docs</li>
<li>Tim Whittington (timw): Connectors</li>
</ul>
</section>
<section name="Retired Developers">
<ul>
<li>Amy Roh (amyroh): Catalina</li>
<li>Glenn Nielsen (glenn): Catalina, Connectors</li>
<li>Henri Gomez (hgomez): Connectors</li>
<li>Jan Luehe (luehe): Jasper</li>
<li>Jean-Francois Arcand (jfarcand): Catalina</li>
<li>Kin-Man Chung (kinman): Jasper</li>
<li>Yoav Shapira (yoavs): Docs, JMX, Catalina, balancer</li>
</ul>
</section>
</body>
</document>

34
webapps/docs/elapi/index.html Normal file
View File

@@ -0,0 +1,34 @@
<!--
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 html>
<html>
<head>
<meta charset="UTF-8" />
<title>API docs</title>
</head>
<body>
The EL Javadoc is not installed by default. Download and install
the "fulldocs" package to get it.
You can also access the javadoc online in the Tomcat
<a href="https://tomcat.apache.org/tomcat-@VERSION_MAJOR_MINOR@-doc/">
documentation bundle</a>.
</body>
</html>

124
webapps/docs/extras.xml Normal file
View File

@@ -0,0 +1,124 @@
<?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="extras.html">
&project;
<properties>
<title>Additional Components</title>
<author>Remy Maucherat</author>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
A number of additional components may be used with Apache Tomcat. These
components may be built by users should they need them or they can be
downloaded from one of the mirrors.
</p>
</section>
<section name="Downloading">
<p>
To download the extras components open the
<download>Tomcat download page</download>
and select "Browse" from the Quick Navigation Links. The extras components
can be found in bin/extras.
</p>
</section>
<section name="Building">
<p>
The additional components are built using the <code>extras</code> target
of the standard Tomcat Ant script which is present in the source bundle of
Tomcat.
</p>
<p>The build process is the following:</p>
<ul>
<li>Follow the <a href="building.html">build instructions</a> to build a
Tomcat binary from the source bundle (note: it will be used by the build
process of the additional components, but does not need to be actually
used later on)</li>
<li>Execute the command <code>ant extras</code> to run the build
script</li>
<li>The additional components JARs will be placed in the
<code>output/extras</code> folder</li>
<li>Refer to the documentation below about the usage of these JARs</li>
</ul>
</section>
<section name="Components list">
<subsection name="Full commons-logging implementation">
<p>
Tomcat uses a package renamed commons-logging API implementation which is
hardcoded to use the java.util.logging API. The commons-logging additional
component builds a full fledged package renamed commons-logging
implementation which can be used to replace the implementation provided with
Tomcat. See the <a href="logging.html">logging</a> page for usage
instructions.
</p>
</subsection>
<subsection name="Web Services support (JSR 109)">
<p>
Tomcat provides factories for JSR 109 which may be used to resolve web
services references. Place the generated catalina-ws.jar as well as
jaxrpc.jar and wsdl4j.jar (or another implementation of JSR 109) in the
Tomcat lib folder.
</p>
<p>
Users should be aware that wsdl4j.jar is licensed under CPL 1.0 and not the
Apache License version 2.0.
</p>
</subsection>
<subsection name="JMX Remote Lifecycle Listener">
<p>
The JMX protocol requires the JMX server (Tomcat in this instance) to listen
on two network ports. One of these ports can be fixed via configuration but
the second is selected randomly. This makes it difficult to use JMX through
a firewall. The JMX Remote Lifecycle Listener allows both ports to be fixed,
simplifying the process of connecting to JMX through a firewall. See the <a
href="config/listeners.html">listeners</a> page for usage instructions.
</p>
</subsection>
</section>
</body>
</document>

299
webapps/docs/funcspecs/fs-admin-apps.xml Normal file
View File

@@ -0,0 +1,299 @@
<?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="fs-admin-apps.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Overall Requirements</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of this specification is to define high level requirements
for administrative applications that can be used to manage the operation
of a running Tomcat container. A variety of <em>Access Methods</em>
to the supported administrative functionality shall be supported, to
meet varying requirements:</p>
<ul>
<li><em>As A Scriptable Web Application</em> - The existing
<code>Manager</code> web application provides a simple HTTP-based
interface for managing Tomcat through commands that are expressed
entirely through a request URI. This is useful in environments
where you wish to script administrative commands with tools that
can generate HTTP transactions.</li>
<li><em>As An HTML-Based Web Application</em> - Use an HTML presentation
to provide a GUI-like user interface for humans to interact with the
administrative capabilities.</li>
<li><em>As SOAP-Based Web Services</em> - The operational commands to
administer Tomcat are made available as web services that utilize
SOAP message formats.</li>
<li><em>As Java Management Extensions (JMX) Commands</em> - The operational
commands to administer Tomcat are made available through JMX APIs,
for integration into management consoles that utilize them.</li>
<li><em>Other Remote Access APIs</em> - Other remote access APIs, such
as JINI, RMI, and CORBA can also be utilized to access administrative
capabilities.</li>
</ul>
<p>Underlying all of the access methods described above, it is assumed
that the actual operations are performed either directly on the
corresponding Catalina components (such as calling the
<code>Deployer.deploy()</code> method to deploy a new web application),
or through a "business logic" layer that can be shared across all of the
access methods. This approach minimizes the cost of adding new
administrative capabilities later -- it is only necessary to add the
corresponding business logic function, and then write adapters to it for
all desired access methods.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/idl">
Java IDL</a> (for CORBA, included in the JDK)</li>
<li><a href="http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html">
Java Management Extensions</a></li>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/rmi">
Remote Method Invocation</a> (Included in the JDK)</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>To the maximum extent feasible, all administrative functions,
and the access methods that support them, shall run portably
on all platforms where Tomcat itself runs.</li>
<li>In a default Tomcat distribution, all administrative capabilities
shall be disabled. It shall be necessary for a system
administrator to specifically enable the desired access methods
(such as by adding a username/password with a specific role to
the Tomcat user's database.</li>
<li>Administrative functions shall be realized as direct calls to
corresponding Catalina APIs, or through a business logic layer
that is independent of the access method used to initiate it.</li>
<li>The common business logic components shall be implemented in
package <code>org.apache.catalina.admin</code>.</li>
<li>The common business logic components shall be built as part of the
standard Catalina build process, and made visible in the
Catalina class loader.</li>
<li>The Java components required for each access method shall be
implemented in subpackages of <code>org.apache.catalina.admin</code>.
</li>
<li>The build scripts should treat each access method as optional,
so that it will be built only if the corresponding required
APIs are present at build time.</li>
<li>It shall be possible to save the configured state of the running
Tomcat container such that this state can be reproduced when the
container is shut down and restarted.</li>
<li>Administrative commands to start up and shut down the overall
Tomcat container are <strong>out of scope</strong> for the
purposes of these applications. It is assumed that other
(usually platform-specific) mechanisms will be used for container
startup and shutdown.</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
administrative applications to operate correctly:</p>
<ul>
<li>For access methods that require creation of server sockets, the
appropriate ports must be configured and available.</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of administrative applications depends on the
following specific features of the surrounding container:</p>
<ul>
<li>To the maximum extent feasible, Catalina components that offer
direct administrative APIs and property setters shall support
"live" changes to their operation, without requiring a container
restart.</li>
</ul>
</subsection>
<subsection name="External Technologies">
<p>The availability of the following technologies can be assumed
for the implementation and operation of the various access methods
and the corresponding administrative business logic:<br/>
<strong>FIXME</strong> - This list below is totally outdated, but nobody
cares about the administrative app anymore. It is removed and unsupported
since Tomcat 6.0.</p>
<ul>
<li><a href="http://www.oracle.com/technetwork/java/javase/overview/index.html">
Java Standard Edition</a> (Version 1.2 or later)</li>
<li><a href="https://www.jcp.org/jsr/detail/154.jsp">Servlet 2.4</a>
(supported natively by Tomcat 5)</li>
<li><a href="https://www.jcp.org/jsr/detail/152.jsp">JavaServer Pages 2.0</a>
(supported natively by Tomcat 5)</li>
<li><a href="https://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">JavaServer Pages Standard Tag Library 1.0 (Jakarta Taglibs-Standard 1.0.3)</a></li>
<li><a href="https://struts.apache.org/">Struts Framework</a>
(Version 1.0) - MVC Framework for Web Applications</li>
<li><strong>TO BE DETERMINED</strong> - Application for hosting SOAP
based web services</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Properties of Administered Objects">
<p>Functional requirements for administrative applications are specified
in terms of <em>Administered Objects</em>, whose definitions and detailed
properties are listed <a href="fs-admin-objects.html">here</a>. In general,
Administered Objects correspond to components in the Catalina architecture,
but these objects are defined separately here for the following reasons:</p>
<ul>
<li>It is possible that the administrative applications do not expose
every possible configurable facet of the underlying components.</li>
<li>In some cases, an Administered Object (from the perspective of an
administrative operation) is realized by more than one Catalina
component, at a finer-grained level of detail.</li>
<li>It is necessary to represent the configuration information for a
component separately from the component itself (for instance, in
order to store that configuration information for later use).</li>
<li>It is necessary to represent configuration information (such as
a Default Context) when there is no corresponding component instance.
</li>
<li>Administered Objects, when realized as Java classes, will include
methods for administrative operations that have no correspondence
to operations performed by the corresponding actual components.</li>
</ul>
<p>It is assumed that the reader is familiar with the overall component
architecture of Catalina. For further information, see the corresponding
Developer Documentation. To distinguish names that are used as both
<em>Administered Objects</em> and <code>Components</code>, different
font presentations are utilized. Default values for many properties
are listed in [square brackets].</p>
</subsection>
<subsection name="Supported Administrative Operations">
<p>The administrative operations that are available are described in terms
of the corresponding Administered Objects (as defined above), in a manner
that is independent of the access method by which these operations are
requested. In general, such operations are relevant only in the context
of a particular Administered Object (and will most likely be realized as
method calls on the corresponding Administered Object classes), so they
are organized based on the currently "focused" administered object.
The available Supported Operations are documented
<a href="fs-admin-opers.html">here</a>.</p>
</subsection>
<subsection name="Access Method Specific Requirements">
<h5>Scriptable Web Application</h5>
<p>An appropriate subset of the administrative operations described above
shall be implemented as commands that can be performed by the "Manager"
web application. <strong>FIXME</strong> - Enumerate them.</p>
<p>In addition, this web application shall conform to the following
requirements:</p>
<ul>
<li>All request URIs shall be protected by security constraints that
require a security role to be assigned for processing.</li>
<li>The default user database shall <strong>not</strong> contain any
user that has been assigned a security role.</li>
</ul>
<h5>HTML-Based Web Application</h5>
<p>The entire suite of administrative operations described above shall be
made available through a web application designed for human interaction.
In addition, this web application shall conform to the following
requirements:</p>
<ul>
<li>Must be implemented using servlet, JSP, and MVC framework technologies
described under "External Technologies", above.</li>
<li>Prompts and error messages must be internationalizable to multiple
languages.</li>
<li>Rendered HTML must be compatible with Netscape Navigator (version 4.7
or later) and Internet Explorer (version 5.0 or later).</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p><strong>FIXME</strong> - Complete this section.</p>
</section>
</body>
</document>

485
webapps/docs/funcspecs/fs-admin-objects.xml Normal file
View File

@@ -0,0 +1,485 @@
<?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="fs-admin-objects.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Administered Objects</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Administered Objects Overview">
<p>This document defines the <em>Administered Objects</em> that represent
the internal architectural components of the Catalina servlet container.
Associated with each is a set of <a href="fs-admin-opers.html">Supported
Operations</a> that can be performed when the administrative application is
"focused" on a particular configurable object.</p>
<p>The following Administered Objects are defined:</p>
<ul>
<li><a href="#Access_Logger">Access Logger</a></li>
<li><a href="#Connector">Connector</a></li>
<li><a href="#Context">Context</a></li>
<li><a href="#Default_Context">Default Context</a></li>
<li><a href="#Default_Deployment_Descriptor">Default Deployment Descriptor</a></li>
<li><a href="#Engine">Engine</a></li>
<li><a href="#Environment_Entry">Environment Entry</a></li>
<li><a href="#Host">Host</a></li>
<li><a href="#JDBC_Resource">JDBC Resource</a></li>
<li><a href="#Loader">Loader</a></li>
<li><a href="#Manager">Manager</a></li>
<li><a href="#Realm">Realm</a></li>
<li><a href="#Request_Filter">Request Filter</a></li>
<li><a href="#Server">Server</a></li>
<li><a href="#Service">Service</a></li>
</ul>
</section>
<section name="Access Logger">
<p>An <em>Access Logger</em> is an optional <code>Valve</code> that can
create request access logs in the same formats as those provided by
web servers. Such access logs are useful input to hit count and user
access tracking analysis programs. An Access Logger can be attached to
an <em>Engine</em>, a <em>Host</em>, a <em>Context</em>, or a <em>Default
Context</em>.</p>
<p>The standard component implementing an <em>Access Logger</em> is
<code>org.apache.catalina.valves.AccessLogValve</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>directory</code> - Absolute or relative (to $CATALINA_BASE) path
of the directory into which access log files are created.
[logs].</li>
<li><code>pattern</code> - Pattern string defining the fields to be
included in the access log output, or "common" for the standard
access log pattern. See
<code>org.apache.catalina.valves.AccessLogValve</code> for more
information. [common]</li>
<li><code>prefix</code> - Prefix added to the beginning of each log file
name created by this access logger.</li>
<li><code>resolveHosts</code> - Should IP addresses be resolved to host
names in the log? [false]</li>
<li><code>suffix</code> - Suffix added to the end of each log file name
created by this access logger.</li>
</ul>
</section>
<section name="Connector">
<p>A <em>Connector</em> is the representation of a communications endpoint
by which requests are received from (and responses returned to) a Tomcat
client. The administrative applications shall support those connectors
that are commonly utilized in Tomcat installations, as described in detail
below.</p>
<p>For standalone use, the standard connector supporting the HTTP/1.1
protocol is <code>org.apache.catalina.connectors.http.HttpConnector</code>.
It supports the following configurable properties:</p>
<ul>
<li><code>acceptCount</code> - The maximum queue length of incoming
connections that have not yet been accepted. [10]</li>
<li><code>address</code> - For servers with more than one IP address, the
address upon which this connector should listen. [All Addresses]</li>
<li><code>bufferSize</code> - Default input buffer size (in bytes) for
requests created by this Connector. [2048]</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>enableLookups</code> - Should we perform DNS lookups on remote
IP addresses when <code>request.getRemoteHost()</code> is called?
[false]</li>
<li><code>maxProcessors</code> - The maximum number of processor threads
supported by this connector. [20]</li>
<li><code>minProcessors</code> - The minimum number of processor threads
to be created at container startup. [5]</li>
<li><code>port</code> - TCP/IP port number on which this Connector should
listen for incoming requests. [8080]</li>
<li><code>proxyName</code> - Host name to be returned when an application
calls <code>request.getServerName()</code>. [Value of Host: header]</li>
<li><code>proxyPort</code> - Port number to be returned when an application
calls <code>request.getServerPort()</code>. [Same as <code>port</code>]
</li>
</ul>
</section>
<section name="Context">
<p>A <em>Context</em> is the representation of an individual web application,
which is associated with a corresponding <em>Host</em>. Note that the
administrable properties of a <em>Context</em> do <strong>not</strong>
include any settings from inside the web application deployment descriptor
for that application.</p>
<p>The standard component implementing a <em>Context</em> is
<code>org.apache.catalina.core.StandardContext</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>cookies</code> - Should be use cookies for session identifier
communication? [true]</li>
<li><code>crossContext</code> - Should calls to
<code>ServletContext.getServletContext()</code> return the actual
context responsible for the specified path? [false]</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>docBase</code> - The absolute or relative (to the
<code>appBase</code> of our owning <em>Host</em>) pathname of a
directory containing an unpacked web application, or of a web
application archive (WAR) file.</li>
<li><code>override</code> - Should settings in this <em>Context</em>
override corresponding settings in the <em>Default Context</em>?
[false]</li>
<li><code>path</code> - Context path for this web application, or an empty
string for the root application of a <em>Host</em>. [Inferred from
directory or WAR file name]</li>
<li><code>reloadable</code> - Should Tomcat monitor classes in the
<code>/WEB-INF/classes</code> directory for changes, and reload the
application if they occur? [false]</li>
<li><code>useNaming</code> - Should Tomcat provide a JNDI naming context,
containing preconfigured entries and resources, corresponding to the
requirements of the Java2 Enterprise Edition specification? [true]</li>
<li><code>workDir</code> - Absolute pathname of a scratch directory that is
provided to this web application. [Automatically assigned relative to
$CATALINA_BASE/work]</li>
</ul>
<p>Each <em>Context</em> is owned by a parent <em>Host</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by this web application.</li>
<li>Zero or more <em>Environment Entries</em> representing environment
entries for the JNDI naming context associated with a web
application.</li>
<li>Zero or more <em>JDBC Resources</em> representing database connection
pools associated with a web application.</li>
<li>A <em>Loader</em> representing the web application class loader used
by this web application.</li>
<li>A <em>Manager</em> representing the session manager used by this
web application.</li>
<li>An optional <em>Realm</em> used to provide authentication and access
control information for this web application.</li>
<li>Zero or more <em>Request Filters</em> used to limit access to this
web application based on remote host name or IP address.</li>
</ul>
</section>
<section name="Default Context">
<p>A <em>Default Context</em> represents a subset of the configurable
properties of a <em>Context</em>, and is used to set defaults for those
properties when web applications are automatically deployed. A <em>Default
Context</em> object can be associated with an <em>Engine</em> or a
<em>Host</em>. The following configurable properties are supported:</p>
<ul>
<li><code>cookies</code> - Should be use cookies for session identifier
communication? [true]</li>
<li><code>crossContext</code> - Should calls to
<code>ServletContext.getServletContext()</code> return the actual
context responsible for the specified path? [false]</li>
<li><code>reloadable</code> - Should Tomcat monitor classes in the
<code>/WEB-INF/classes</code> directory for changes, and reload the
application if they occur? [false]</li>
<li><code>useNaming</code> - Should Tomcat provide a JNDI naming context,
containing preconfigured entries and resources, corresponding to the
requirements of the Java2 Enterprise Edition specification? [true]</li>
</ul>
<p>Each <em>Default Context</em> is owned by a parent <em>Engine</em> or
<em>Host</em>, and is associated with:</p>
<ul>
<li>Zero or more <em>Environment Entries</em> representing environment
entries for the JNDI naming context associated with a web
application.</li>
<li>Zero or more <em>JDBC Resources</em> representing database connection
pools associated with a web application.</li>
<li>An optional <em>Loader</em> representing default configuration
properties for the Loader component of deployed web applications.</li>
<li>An optional <em>Manager</em> representing default configuration
properties for the Manager component of deployed web applications.</li>
</ul>
</section>
<section name="Default Deployment Descriptor">
<p>Default web application characteristics are configured in a special
deployment descriptor named <code>$CATALINA_BASE/conf/web.xml</code>. This
section describes the configurable components that may be stored there.</p>
<p><strong>FIXME</strong> - Complete the description of default servlets,
default mappings, default MIME types, and so on.</p>
</section>
<section name="Engine">
<p>An <em>Engine</em> is the representation of the entire Catalina
servlet container, and processes all requests for all of the associated
virtual hosts and web applications.</p>
<p>The standard component implementing an <em>Engine</em> is
<code>org.apache.catalina.core.StandardEngine</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>defaultHost</code> - Name of the <em>Host</em> to which requests
will be directed if the requested host is unknown. [localhost]</li>
<li><code>name</code> - Logical name of this engine. [Tomcat Stand-Alone]
</li>
</ul>
<p>Each <em>Engine</em> is owned by a parent <em>Service</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by the entire container.</li>
<li>A <em>Default Context</em>, representing default properties of a
<em>Context</em> for automatically deployed applications for all
associated <em>Hosts</em> (unless overridden by a subordinate
component).</li>
<li>One or more <em>Hosts</em> representing individual virtual hosts
supported by this container.</li>
<li>A <em>Realm</em> used to provide authentication and access control
information for all virtual hosts and web applications (unless
overridden by a subordinate component).</li>
<li>Zero or more <em>Request Filters</em> used to limit access to the
entire container based on remote host name or IP address.</li>
</ul>
</section>
<section name="Environment Entry">
<p>An <em>Environment Entry</em> is the representation of a
<code>&lt;env-entry&gt;</code> element from a web application deployment
descriptor. It will cause the creation of a corresponding entry in the
JNDI naming context provided to the corresponding <em>Context</em>. The
following configurable properties are supported:</p>
<ul>
<li><code>description</code> - Description of this environment entry.</li>
<li><code>name</code> - Environment entry name (relative to the
<code>java:comp/env</code> context)</li>
<li><code>type</code> - Environment entry type (must be one of the fully
qualified Java classes listed in the servlet spec).</li>
<li><code>value</code> - Environment entry value (must be convertible from
String to the specified <code>type</code>.</li>
</ul>
</section>
<section name="Host">
<p>A <em>Host</em> is the representation of an individual virtual host,
which has a unique set of associated web applications.</p>
<p>The standard component implementing a <em>Host</em> is
<code>org.apache.catalina.core.StandardHost</code>. It supports the
following configurable properties:</p>
<ul>
<li><code>aliases</code> - Zero or more DNS names that are also associated
with this host (for example, a particular host might be named
<code>www.mycompany.com</code> with an alias <code>company.com</code>).
</li>
<li><code>appBase</code> - Absolute or relative (to $CATALINA_BASE) path
to a directory from which web applications will be automatically
deployed.</li>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>name</code> - DNS Name of the virtual host represented by this
object.</li>
<li><code>unpackWARs</code> - Should web application archive files
deployed by this virtual host be unpacked first? [true]</li>
</ul>
<p>Each <em>Host</em> is owned by a parent <em>Engine</em>, and is
associated with:</p>
<ul>
<li>An optional <em>Access Logger</em> that logs all requests processed
by this virtual host.</li>
<li>One or more <em>Contexts</em> representing the web applications
operating on this <em>Host</em>.</li>
<li>A <em>Default Context</em> representing default <em>Context</em>
properties for web applications that are automatically deployed
by this <em>Host</em>.</li>
<li>A optional <em>Realm</em> used to provide authentication and access
control information for all web applications associated with this
virtual host (unless overridden by a subordinate component).</li>
</ul>
<p><strong>FIXME</strong> - Should we support configuration of the
User Web Applications functionality?</p>
</section>
<section name="JDBC Resource">
<p>A <em>JDBC Resources</em> represents a database connection pool (i.e.
an implementation of <code>javax.sql.DataSource</code> that will be
configured and made available in the JNDI naming context associated with
a web application.</p>
<p><strong>FIXME</strong> - properties of this administered object</p>
</section>
<section name="Loader">
<p>A <em>Loader</em> represents a web application class loader that will
be utilized to provide class loading services for a particular
<em>Context</em>.</p>
<p>The standard component implementing a <em>Loader</em> is
<code>org.apache.catalina.loader.WebappLoader</code>. It supports
the following configurable properties:</p>
<ul>
<li><code>reloadable</code> - Should this class loader check for modified
classes and initiate automatic reloads? [Set automatically from the
<code>reloadable</code> property of the corresponding <em>Context</em>]
</li>
</ul>
<p>Each <em>Loader</em> is owned by a parent <em>Context</em>.</p>
</section>
<section name="Manager">
<p>A <em>Manager</em> represents a session manager that will be associated
with a particular web application. <strong>FIXME</strong> - Add support
for advanced session managers and their associated Stores.</p>
<p>The standard component implementing a <em>Manager</em> is
<code>org.apache.catalina.session.StandardManager</code>. It supports
the following configurable properties:</p>
<ul>
<li><code>maxActiveSessions</code> - The maximum number of active sessions
that are allowed, or -1 for no limit. [-1]</li>
</ul>
<p>Each <em>Manager</em> is owned by a parent <em>Context</em>.</p>
</section>
<section name="Realm">
<p>A <em>Realm</em> represents a "database" of information about authorized
users, their passwords, and the security roles assigned to them. This will
be used by the container in the implementation of container-managed security
in accordance with the Servlet Specification. Several alternative
implementations are supported.</p>
<p><code>org.apache.catalina.realm.MemoryRealm</code> initializes its user
information from a simple XML file at startup time. If changes are made
to the information in this file, the corresponding web applications using
it must be restarted for the changes to take effect. It supports the
following configurable properties:</p>
<ul>
<li><code>debug</code> - Debugging detail level. [0]</li>
<li><code>pathname</code> - Absolute or relative (to $CATALINA_BASE) path to
the XML file containing our user information. [conf/tomcat-users.xml]
</li>
</ul>
<p><code>org.apache.catalina.realm.JDBCRealm</code> uses a relational
database (accessed via JDBC APIs) to contain the user information. Changes
in the contents of this database take effect immediately; however, the roles
assigned to a particular user are calculated only when the user initially
logs on (and not per request). The following configurable properties
are supported:</p>
<ul>
<li><code>connectionName</code> - Database username to use when establishing
a JDBC connection.</li>
<li><code>connectionPassword</code> - Database password to use when
establishing a JDBC connection.</li>
<li><code>connectionURL</code> - Connection URL to use when establishing
a JDBC connection.</li>
<li><code>driverName</code> - Fully qualified Java class name of the JDBC
driver to be utilized.</li>
<li><code>roleNameCol</code> - Name of the column, in the User Roles table,
which contains the role name.</li>
<li><code>userCredCol</code> - Name of the column, in the Users table,
which contains the password (encrypted or unencrypted).</li>
<li><code>userNameCol</code> - Name of the column, in both the Users and
User Roles tables, that contains the username.</li>
<li><code>userRoleTable</code> - Name of the User Roles table, which contains
one row per security role assigned to a particular user. This table must
contain the columns specified by the <code>userNameCol</code> and
<code>roleNameCol</code> properties.</li>
<li><code>userTable</code> - Name of the Users table, which contains one row
per authorized user. This table must contain the columns specified by
the <code>userNameCol</code> and <code>userCredCol</code> properties.
</li>
</ul>
<p><strong>FIXME</strong> - Should we provide mechanisms to edit the contents
of a "tomcat-users.xml" file through the admin applications?</p>
<p>Each <em>Realm</em> is owned by a parent <em>Engine</em>, <em>Host</em>,
or <em>Context</em>.</p>
</section>
<section name="Request Filter">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
<section name="Server">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
<section name="Service">
<p><strong>FIXME</strong> - complete this entry</p>
</section>
</body>
</document>

342
webapps/docs/funcspecs/fs-admin-opers.xml Normal file
View File

@@ -0,0 +1,342 @@
<?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="fs-admin-opers.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Administrative Apps - Supported Operations</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Supported Operations Overview">
<p>This document defines the <em>Supported Operations</em> that may
be performed against the <a href="fs-admin-objects.html">Administered
Objects</a> that are supported by Tomcat administrative applications.
Not all operations are required to be available through every administrative
application that is implemented. However, if a given operation is available,
it should operate consistently with the descriptions found here.</p>
<p>Supported Operations are described for the following Administered
Objects:</p>
<ul>
<li><a href="#Access_Logger">Access Logger</a></li>
<li><a href="#Connector">Connector</a></li>
<li><a href="#Context">Context</a></li>
<li><a href="#Default_Context">Default Context</a></li>
<li><a href="#Engine">Engine</a></li>
<li><a href="#Environment_Entry">Environment Entry</a></li>
<li><a href="#Host">Host</a></li>
<li><a href="#JDBC_Resource">JDBC Resource</a></li>
<li><a href="#Loader">Loader</a></li>
<li><a href="#Manager">Manager</a></li>
<li><a href="#Realm">Realm</a></li>
<li><a href="#Request_Filter">Request Filter</a></li>
<li><a href="#Server">Server</a></li>
<li><a href="#Service">Service</a></li>
</ul>
</section>
<section name="Access Logger">
<p>From the perspective of a particular <em>Access Logger</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>, <em>Host</em>, or
<em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Connector">
<p>From the perspective of a particular <em>Connector</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Service</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Context">
<p>From the perspective of a particular <em>Context</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Host</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Access Logger</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Access
Logger</em>.</li>
<li>Remove the associated <em>Access Logger</em>.</li>
<li>Create and configure a new <em>Environment Entry</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Environment Entry</em>.</li>
<li>Remove an associated <em>Environment Entry</em>.</li>
<li>Create and configure a new <em>JDBC Resource</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>JDBC Resource</em>.</li>
<li>Remove an associated <em>JDBC Resource</em>.</li>
<li>Create and configure a new <em>Loader</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Loader</em>.</li>
<li>Remove the associated <em>Loader</em>.</li>
<li>Create and configure a new <em>Manager</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Manager</em>.</li>
<li>Remove the associated <em>Manager</em>.</li>
<li>Create and configure a new <em>Realm</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Realm</em>.</li>
<li>Remove the associated <em>Realm</em>.</li>
<li>Create and configure a new <em>Request Filter</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Request Filter</em></li>
<li>Remove an associated <em>Request Filter</em>.</li>
</ul>
</section>
<section name="Default Context">
<p>From the perspective of a particular <em>Default Context</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em> or <em>Host</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Environment Entry</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Environment Entry</em>.</li>
<li>Remove an associated <em>Environment Entry</em>.</li>
<li>Create and configure a new <em>JDBC Resource</em> associated
with this object.</li>
<li>Select and edit the configurable properties of an associated
<em>JDBC Resource</em>.</li>
<li>Remove an associated <em>JDBC Resource</em>.</li>
</ul>
</section>
<section name="Engine">
<p>From the perspective of a particular <em>Engine</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Service</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Access Logger</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Access
Logger</em>.</li>
<li>Remove the associated <em>Access Logger</em>.</li>
<li>Create and configure a new <em>Default Context</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Default
Context</em>.</li>
<li>Remove the associated <em>Default Context</em>.</li>
<li>Create and configure a new <em>Host</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Host</em>.</li>
<li>Remove an associated <em>Host</em>.</li>
<li>Create and configure a new <em>Realm</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Realm</em>.</li>
<li>Remove the associated <em>Realm</em>.</li>
<li>Create and configure a new <em>Request Filter</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Request Filter</em></li>
<li>Remove an associated <em>Request Filter</em>.</li>
</ul>
</section>
<section name="Environment Entry">
<p>From the perspective of a particular <em>Environment Entry</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em> or <em>Default Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Host">
<p>From the perspective of a particular <em>Host</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Access Logger</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Access
Logger</em>.</li>
<li>Remove the associated <em>Access Logger</em>.</li>
<li>Create and configure a new <em>Context</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Context</em>.</li>
<li>Remove an associated <em>Context</em>.</li>
<li>Create and configure a new <em>Default Context</em> associated
with this object.</li>
<li>Edit the configurable properties of the associated <em>Default
Context</em>.</li>
<li>Remove the associated <em>Default Context</em>.</li>
<li>Create and configure a new <em>Realm</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Realm</em>.</li>
<li>Remove the associated <em>Realm</em>.</li>
<li>Create and configure a new <em>Request Filter</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an
associated <em>Request Filter</em></li>
<li>Remove an associated <em>Request Filter</em>.</li>
</ul>
</section>
<section name="JDBC Resource">
<p>From the perspective of a particular <em>JDBC Resource</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em> or <em>Default Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Loader">
<p>From the perspective of a particular <em>Loader</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Manager">
<p>From the perspective of a particular <em>Manager</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Realm">
<p>From the perspective of a particular <em>Realm</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>, <em>Host</em>, or
<em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Request Filter">
<p>From the perspective of a particular <em>Request Filter</em>, it shall
be possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Engine</em>, <em>Host</em>, or
<em>Context</em>.</li>
<li>Edit the configurable properties of this object.</li>
</ul>
</section>
<section name="Server">
<p>From the perspective of the overall <em>Server</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Service</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Service</em>.</li>
</ul>
</section>
<section name="Service">
<p>From the perspective of a particular <em>Service</em>, it shall be
possible to perform the following administrative operations:</p>
<ul>
<li>Navigate to the owning <em>Server</em>.</li>
<li>Edit the configurable properties of this object.</li>
<li>Create and configure a new <em>Connector</em> associated with
this object.</li>
<li>Select and edit the configurable properties of an associated
<em>Connector</em>.</li>
<li>Remove an associated <em>Connector</em>.</li>
<li>Create and configure a new <em>Engine</em> associated with
this object.</li>
<li>Edit the configurable properties of the associated <em>Engine</em>.</li>
<li>Remove the associated <em>Engine</em>.</li>
</ul>
</section>
</body>
</document>

270
webapps/docs/funcspecs/fs-default.xml Normal file
View File

@@ -0,0 +1,270 @@
<?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="fs-default.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>Default Servlet</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>Default Servlet</strong> is to serve
static resources of a web application in response to client requests.
As the name implies, it is generally configured as the "default"
servlet for a web application, by being mapped to a URL pattern "/".</p>
</subsection>
<subsection name="External Specifications">
<p>The following external specifications have provisions which
partially define the correct behavior of the default servlet:</p>
<ul>
<li><a href="https://jcp.org/aboutJava/communityprocess/final/jsr340/index.html">
Servlet Specification</a> (Version 3.1)</li>
<li><a href="https://www.rfc-editor.org/rfc/rfc2046.txt">Multipurpose
Internet Mail Extensions (MIME) Part Two: Media Types</a></li>
<li><a href="https://www.rfc-editor.org/rfc/rfc2616.txt">Hypertext
Transfer Protocol &#x2013; HTTP/1.1</a></li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Must be implemented as a servlet.</li>
<li>Must support configurable parameters for debugging detail level,
input buffer size, output buffer size, whether or not to produce
directory listings when no welcome file is present, and whether or not
modifications are supported via DELETE and PUT.</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getServletContext().log()</code> method.</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
the default servlet to operate correctly:</p>
<ul>
<li>The default servlet must be registered in the application deployment
descriptor (or the default deployment descriptor in file
<code>$CATALINA_BASE/conf/web.xml</code>) using a "default servlet"
servlet mapping, signified by URL pattern "/".</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of the default servlet depends on the following
specific features of the surrounding container:</p>
<ul>
<li>The container shall provide a servlet context attribute that
lists the welcome file names that have been defined for this
web application.</li>
<li>The container shall provide a servlet context attribute that
contains a <code>javax.naming.directory.DirContext</code>
implementation representing the static resources of this
web application.</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Initialization Functionality">
<p>The following processing must be performed when the <code>init()</code>
method of the default servlet is called:</p>
<ul>
<li>Process and sanity check configuration parameters.</li>
</ul>
</subsection>
<subsection name="Per-Request Functionality">
<p>For all HTTP request methods, the resource path is determined from
the path information provided to this request, either as request attribute
<code>javax.servlet.include.path_info</code> (for a request dispatcher
access to a static resource) or by calling
<code>request.getPathInfo()</code> directly.</p>
<p>On each HTTP DELETE request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>If modifications to the static resources are not allowed (set by a
configuration parameter), return HTTP status 403 (forbidden).</li>
<li>If an attempt is made to delete a resource from <code>/META-INF</code>
or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
<li>If the requested resource does not exist, return HTTP status 404
(not found)</li>
<li>Unbind the resource from the directory context containing the
static resources for this web application. If successful, return
HTTP status 204 (no content). Otherwise, return HTTP status 405
(method not allowed).</li>
</ul>
<p>On each HTTP GET request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>If the request is for a resource under <code>/META-INF</code> or
<code>/WEB-INF</code>, return HTTP status 404 (not found).</li>
<li>If the requested resource does not exist, return HTTP status 404
(not found).</li>
<li>If the requested resource is not a directory, but the resource
path ends in "/" or "\", return HTTP status 404 (not found).</li>
<li>If the requested resource is a directory:
<ul>
<li>If the request path does not end with "/", redirect to a
corresponding path with "/" appended so that relative references
in welcome files are resolved correctly.</li>
<li>If one of the specified welcome files exists, redirect to the
path for that welcome file so that it will be served explicitly.
</li>
</ul></li>
<li>If the request being processed contains an <code>If-Range</code>
header, perform the processing described in the HTTP/1.1 specification
to determine whether the client's information is up to date.</li>
<li>Determine the content type of the response, by looking up the
corresponding MIME type in our servlet context.</li>
<li>If the requested resource is a directory:
<ul>
<li>If directory listings are suppressed, return HTTP status 404
(not found).</li>
<li>Set the content type to <code>text/html</code>.</li>
</ul></li>
<li>Determine the range(s) to be returned, based on the existence of
any <code>If-Range</code> and <code>Range</code> headers.</li>
<li>If the requested resource is a directory, include an <code>ETag</code>
header in the response, with the value calculated based on the content
of the directory.</li>
<li>Include a <code>Last-Modified</code> header in the response documenting
the date/time that the resource was last modified.</li>
<li>Unless we are processing a HEAD request, include the appropriate
content (or content ranges) in the response.</li>
</ul>
<p>On each HTTP HEAD request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>Processed identically to an HTTP GET request, except that the data
content is not transmitted after the headers.</li>
</ul>
<p>On each HTTP POST request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>Processed identically to an HTTP GET request.</li>
</ul>
<p>On each HTTP PUT request processed by this servlet, the following
processing shall be performed:</p>
<ul>
<li>If modifications to the static resources are not allowed (set by a
configuration parameter), return HTTP status 403 (forbidden).</li>
<li>If an attempt is made to delete a resource from <code>/META-INF</code>
or <code>/WEB-INF</code>, return HTTP status 403 (forbidden).</li>
<li>Create a new resource from the body of this request.</li>
<li>Bind or rebind the specified path to the new resource (depending on
whether it currently exists or not). Return HTTP status as follows:
<ul>
<li>If binding was unsuccessful, return HTTP status 409 (conflict).
</li>
<li>If binding was successful and the resource did not previously
exist, return HTTP status 201 (created).</li>
<li>If binding was successful and the resource previously existed,
return HTTP status 204 (no content).</li>
</ul></li>
</ul>
</subsection>
<subsection name="Finalization Functionality">
<p>No specific processing is required when the <code>destroy()</code>
method is called:</p>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of the default servlet:</p>
<ul>
<li>Requests for resources that do not exist in the web application must
return HTTP status 404 (not found).</li>
<li>The default servlet must operate identically for web applications that
are run out of a WAR file directly, or from an unpacked directory
structure.</li>
<li>If the web application is running out of an unpacked directory
structure, the default servlet must recognize cases where the resource
has been updated through external means.</li>
</ul>
</section>
</body>
</document>

266
webapps/docs/funcspecs/fs-jdbc-realm.xml Normal file
View File

@@ -0,0 +1,266 @@
<?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="fs-jdbc-realm.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>JDBCRealm</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>JDBCRealm</strong> implementation is to
provide a mechanism by which Tomcat can acquire information needed
to authenticate web application users, and define their security roles,
from a relational database accessed via JDBC APIs. For integration
with Catalina, the resulting class(es) must implement the
<code>org.apache.catalina.Realm</code> interface.</p>
<p>This specification reflects a combination of functionality that is
already present in the <code>org.apache.catalina.realm.JDBCRealm</code>
class, as well as requirements for enhancements that have been
discussed. Where appropriate, requirements statements are marked
<em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
Java Database Connectivity</a> (version 2.0 or later)</li>
<li><a href="http://www.oracle.com/technetwork/java/javase/jdbc/index.html">
Java Database Connectivity Optional Package</a> (version 2.0 or later)</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Be realized in one or more implementation classes.</li>
<li>Implement the <code>org.apache.catalina.Realm</code> interface.
[Current]</li>
<li>Implement the <code>org.apache.catalina.Lifecycle</code>
interface. [Current]</li>
<li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
base class.</li>
<li>Live in the <code>org.apache.catalina.realm</code> package.
[Current]</li>
<li>Support a configurable debugging detail level. [Current]</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getContainer().log()</code> method. [Current]</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
JDBCRealm to operate correctly:</p>
<ul>
<li>The desire to utilize JDBCRealm must be registered in
<code>$CATALINA_BASE/conf/server.xml</code>, in a
<code>&lt;Realm&gt;</code> element that is nested inside a
corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
or <code>&lt;Context&gt;</code> element.</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of JDBCRealm depends on the following
specific features of the surrounding container:</p>
<ul>
<li>Interactions with <code>JDBCRealm</code> will be initiated by
the appropriate <code>Authenticator</code> implementation, based
on the login method that is selected.</li>
<li><code>JDBCRealm</code> must have the JDBC standard API classes
available to it. For a JDK 1.2 or later container, these APIs
are included in the standard platform.</li>
<li>When connection pooling is implemented, <code>JDBCRealm</code>
must have the JDBC Optional Package (version 2.0 or later) APIs
available to it. This library is available as a separate
download (and will be included in Tomcat binary distributions).</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Overview of Operation">
<p>The main purpose of <code>JDBCRealm</code> is to allow Catalina to
authenticate users, and look up the corresponding security roles, from
the information found in a relational database accessed via JDBC APIs.
For maximum flexibility, the details of how this is done (for example,
the names of the required tables and columns) should be configurable.</p>
<p>Each time that Catalina needs to authenticate a user, it will call
the <code>authenticate()</code> method of this Realm implementation,
passing the username and password that were specified by the user. If
we find the user in the database (and match on the password), we accumulate
all of the security roles that are defined for this user, and create a
new <code>GenericPrincipal</code> object to be returned. If the user
is not authenticated, we return <code>null</code> instead. The
<code>GenericUser</code> object caches the set of security roles that
were owned by this user at the time of authentication, so that calls to
<code>isUserInRole()</code> can be answered without going back to the
database every time.</p>
</subsection>
<subsection name="Detailed Functional Requirements">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li>Configuration parameters defining the JDBC driver to use, the
database connection URL to be accessed, and the username/password
to use for logging in. [Current]</li>
<li>Configuration parameters describing the connection pool to be
created to support simultaneous authentications. [Requested]</li>
<li>Name of the tables to be searched for users and roles. [Current]</li>
<li>Name of the columns to be used for usernames, passwords, and
role names. [Current]</li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>Establish a connection to the configured database, using the
configured username and password. [Current]</li>
<li>Configure and establish a connection pool of connections to the
database. [Requested]</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>Close any opened connections to the database.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Acquire the one and only connection [Current] or acquire a connection
from the connection pool [Requested].</li>
<li>Select the one and only row from the user's table for this user,
and retrieve the corresponding password column. If zero rows (or
more than one row) are found, return <code>null</code>.</li>
<li>Authenticate the user by comparing the (possibly encrypted) password
value that was received against the password presented by the user.
If there is no match, return <code>null</code>.</li>
<li>Acquire a <code>List</code> of the security roles assigned to the
authenticated user by selecting from the roles table.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
constructor arguments: this realm instance, the authenticated
username, and a <code>List</code> of the security roles associated
with this user.</li>
<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
<code>GenericPrincipal</code> objects for a particular user, because
the information in the directory server might have changed since the
last time this user was authenticated.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of <code>JDBCRealm</code>:</p>
<ul>
</ul>
</section>
</body>
</document>

417
webapps/docs/funcspecs/fs-jndi-realm.xml Normal file
View File

@@ -0,0 +1,417 @@
<?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="fs-jndi-realm.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>JNDIRealm</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>JNDIRealm</strong> implementation is to
provide a mechanism by which Tomcat can acquire information needed
to authenticate web application users, and define their security roles,
from a directory server or other service accessed via JNDI APIs. For
integration with Catalina, this class must implement the
<code>org.apache.catalina.Realm</code> interface.</p>
<p>This specification reflects a combination of functionality that is
already present in the <code>org.apache.catalina.realm.JNDIRealm</code>
class, as well as requirements for enhancements that have been
discussed. Where appropriate, requirements statements are marked
<em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
<p>The code in the current version of <code>JNDIRealm</code>, and the
ideas expressed in this functional specification, are the results of
contributions from many individuals, including (alphabetically):</p>
<ul>
<li>Holman, John &lt;j.g.holman@qmw.ac.uk&gt;</li>
<li>Lockhart, Ellen &lt;elockhart@home.com&gt;</li>
<li>McClanahan, Craig &lt;craigmcc@apache.org&gt;</li>
</ul>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jndi/index.html">
Java Naming and Directory Interface</a> (version 1.2.1 or later)</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Be realized in one or more implementation classes.</li>
<li>Implement the <code>org.apache.catalina.Realm</code> interface.
[Current]</li>
<li>Implement the <code>org.apache.catalina.Lifecycle</code>
interface. [Current]</li>
<li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
base class.</li>
<li>Live in the <code>org.apache.catalina.realm</code> package.
[Current]</li>
<li>Support a configurable debugging detail level. [Current]</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getContainer().log()</code> method. [Current]</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
JNDIRealm to operate correctly:</p>
<ul>
<li>The desire to utilize JNDIRealm must be registered in
<code>$CATALINA_BASE/conf/server.xml</code>, in a
<code>&lt;Realm&gt;</code> element that is nested inside a
corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
or <code>&lt;Context&gt;</code> element.</li>
<li>If the <em>Administrator Login</em> operational mode is selected,
the configured administrator username and password must be configured
in the corresponding directory server.</li>
<li>If the <em>Username Login</em> operational mode is selected,
the corresponding directory server must be configured to accept
logins with the username and password that will be passed to
<code>JNDIRealm</code> by the appropriate <code>Authenticator</code>.
</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of JNDIRealm depends on the following
specific features of the surrounding container:</p>
<ul>
<li>Interactions with <code>JNDIRealm</code> will be initiated by
the appropriate <code>Authenticator</code> implementation, based
on the login method that is selected.</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Operational Modes">
<p>The completed <code>JNDIRealm</code> must support two major operational
modes in order to support all of the required use cases. For the purposes
of this document, the modes are called <em>administrator login</em> and
<em>Username Login</em>. They are described further in the following
paragraphs.</p>
<p>For <em>Administrator Login</em> mode, <code>JNDIRealm</code> will be
configured to establish one or more connections (using a connection pool)
to an appropriate directory server, using JNDI APIs, under a "system
administrator" username and password. This is similar to the approach
normally used to configure <code>JDBCRealm</code> to access authentication
and access control information in a database. It is assumed that the
system administrator username and password that are configured provide
sufficient privileges within the directory server to read (but not modify)
the username, password, and assigned roles for each valid user of the
web application associated with this <code>Realm</code>. The password
can be stored in cleartext, or in one of the digested modes supported by
the <code>org.apache.catalina.realm.RealmBase</code> base class.</p>
<p>For <em>Username Login</em> mode, <code>JNDIRealm</code> does not
normally remain connected to the directory server. Instead, whenever a
user is to be authenticated, a connection to the directory server
(using the username and password received from the authenticator) is
attempted. If this connection is successful, the user is assumed to be
successfully authenticated. This connection is then utilized to read
the corresponding security roles associated with this user, and the
connection is then broken.</p>
<p><strong>NOTE</strong> - <em>Username Login</em> mode cannot be used
if you have selected login method <code>DIGEST</code> in your web
application deployment descriptor (<code>web.xml</code>) file. This
restriction exists because the cleartext password is never available
to the container, so it is not possible to bind to the directory server
using the user's username and password.</p>
<p>Because these operational modes work so differently, the functionality
for each mode will be described separately. Whether or not both modes
are actually supported by a single class (versus a class per mode) is
an implementation detail left to the designer.</p>
<p><strong>NOTE</strong> - The current implementation only implements
part of the <em>Administrator Lookup</em> mode requirements. It does
not support the <em>Username Lookup</em> mode at all, at this point.</p>
</subsection>
<subsection name="Administrator Login Mode Functionality">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li><code>connectionURL</code> - URL of the directory server we will
be contacting.</li>
<li><code>contextFactory</code> - Fully qualified class name of the JNDI
context factory used to retrieve our InitialContext.
[com.sun.jndi.ldap.LdapCtxFactory]</li>
<li>Additional configuration properties required to establish the
appropriate connection. [Requested]</li>
<li>Connection pool configuration properties. [Requested]</li>
<li>Configuration properties defining how a particular user is
authenticated. The following capabilities should be supported:
<ul>
<li>Substitute the specified username into a string. [Requested]</li>
<li>Retrieve the distinguished name (DN) of an authorized user via an
LDAP search string with a replacement placeholder for the
username, and comparison of the password to a configurable
attribute retrieved from the search result. [Current]</li>
</ul></li>
<li>Configuration properties defining how the roles associated with a
particular authenticated user can be retrieved. The following
approaches should be supported:
<ul>
<li>Retrieve a specified attribute (possibly multi-valued)
from an LDAP search expression,
with a replacement placeholder for the DN of the user.
[Current]</li>
<li>Retrieve a set of role names that are defined implicitly (by
selecting principals that match a search pattern) rather than
explicitly (by finding a particular attribute value).
[Requested]</li>
</ul></li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>Establish a connection to the configured directory server, using the
configured system administrator username and password. [Current]</li>
<li>Configure and establish a connection pool of connections to the
directory server. [Requested]</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>Close any opened connections to the directory server.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Acquire the one and only connection [Current] or acquire a connection
from the connection pool [Requested].</li>
<li>Authenticate the user by retrieving the user's Distinguished Name,
based on the specified username and password.</li>
<li>If the user was not authenticated, release the allocated connection
and return <code>null</code>.</li>
<li>Acquire a <code>List</code> of the security roles assigned to the
authenticated user.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
constructor arguments: this realm instance, the authenticated
username, and a <code>List</code> of the security roles associated
with this user.</li>
<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
<code>GenericPrincipal</code> objects for a particular user, because
the information in the directory server might have changed since the
last time this user was authenticated.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
<subsection name="Username Login Mode Functionality">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li><code>connectionURL</code> - URL of the directory server we will
be contacting.</li>
<li><code>contextFactory</code> - Fully qualified class name of the JNDI
context factory used to retrieve our InitialContext.
[com.sun.jndi.ldap.LdapCtxFactory]</li>
<li>Additional configuration properties required to establish the
appropriate connection. [Requested]</li>
<li>Connection pool configuration properties. [Requested]</li>
<li>Configuration properties defining if and how a user might be looked
up before binding to the directory server. The following approaches
should be supported:
<ul>
<li>No previous lookup is required - username specified by the user
is the same as that used to authenticate to the directory
server.</li>
<li>Substitute the specified username into a string.</li>
<li>Search the directory server based on configured criteria to
retrieve the distinguished name of the user, then attempt to
bind with that distinguished name.</li>
</ul></li>
<li>Configuration properties defining how the roles associated with a
particular authenticated user can be retrieved. The following
approaches should be supported:
<ul>
<li>Retrieve a specified attribute (possibly multi-valued)
from an LDAP search expression,
with a replacement placeholder for the DN of the user.
[Current]</li>
</ul></li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>None required.</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>None required.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Attempt to bind to the directory server, using the username and
password provided by the user.</li>
<li>If the user was not authenticated, release the allocated connection
and return <code>null</code>.</li>
<li>Acquire a <code>List</code> of the security roles assigned to the
authenticated user.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code>, passing as
constructor arguments: this realm instance, the authenticated
username, and a <code>List</code> of the security roles associated
with this user.</li>
<li><strong>WARNING</strong> - Do not attempt to cache and reuse previous
<code>GenericPrincipal</code> objects for a particular user, because
the information in the directory server might have changed since the
last time this user was authenticated.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of <code>JNDIRealm</code>:</p>
<ul>
</ul>
</section>
</body>
</document>

253
webapps/docs/funcspecs/fs-memory-realm.xml Normal file
View File

@@ -0,0 +1,253 @@
<?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="fs-memory-realm.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<title>MemoryRealm</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Overview">
<subsection name="Introduction">
<p>The purpose of the <strong>MemoryRealm</strong> implementation is to
provide a mechanism by which Tomcat can acquire information needed
to authenticate web application users, and define their security roles,
from a simple text-based configuration file in XML format. This is
intended to simplify the initial installation and operation of Tomcat,
without the complexity of configuring a database or directory server
based Realm. It is not intended for production use.</p>
<p>This specification reflects a combination of functionality that is
already present in the <code>org.apache.catalina.realm.MemoryRealm</code>
class, as well as requirements for enhancements that have been
discussed. Where appropriate, requirements statements are marked
<em>[Current]</em> and <em>[Requested]</em> to distinguish them.</p>
<p>The current status of this functional specification is
<strong>PROPOSED</strong>. It has not yet been discussed and
agreed to on the TOMCAT-DEV mailing list.</p>
</subsection>
<subsection name="External Specifications">
<p>The implementation of this functionality depends on the following
external specifications:</p>
<ul>
<li>None</li>
</ul>
</subsection>
<subsection name="Implementation Requirements">
<p>The implementation of this functionality shall conform to the
following requirements:</p>
<ul>
<li>Be realized in one or more implementation classes.</li>
<li>Implement the <code>org.apache.catalina.Realm</code> interface.
[Current]</li>
<li>Implement the <code>org.apache.catalina.Lifecycle</code>
interface. [Current]</li>
<li>Subclass the <code>org.apache.catalina.realm.RealmBase</code>
base class.</li>
<li>Live in the <code>org.apache.catalina.realm</code> package.
[Current]</li>
<li>Support a configurable debugging detail level. [Current]</li>
<li>Log debugging and operational messages (suitably internationalized)
via the <code>getContainer().log()</code> method. [Current]</li>
</ul>
</subsection>
</section>
<section name="Dependencies">
<subsection name="Environmental Dependencies">
<p>The following environmental dependencies must be met in order for
MemoryRealm to operate correctly:</p>
<ul>
<li>The desire to utilize MemoryRealm must be registered in
<code>$CATALINA_BASE/conf/server.xml</code>, in a
<code>&lt;Realm&gt;</code> element that is nested inside a
corresponding <code>&lt;Engine&gt;</code>, <code>&lt;Host&gt;</code>,
or <code>&lt;Context&gt;</code> element. (This is already
included in the default <code>server.xml</code> file.)</li>
</ul>
</subsection>
<subsection name="Container Dependencies">
<p>Correct operation of MemoryRealm depends on the following
specific features of the surrounding container:</p>
<ul>
<li>Interactions with <code>MemoryRealm</code> will be initiated by
the appropriate <code>Authenticator</code> implementation, based
on the login method that is selected.</li>
<li><code>MemoryRealm</code> must have an XML parser compatible with
the JAXP/1.1 APIs available to it. This is normally accomplished
by placing the corresponding JAR files in directory
<code>$CATALINA_HOME/lib</code>.</li>
</ul>
</subsection>
</section>
<section name="Functionality">
<subsection name="Overview of Operation">
<p>The main purpose of <code>MemoryRealm</code> is to allow Catalina to
authenticate users, and look up the corresponding security roles, from
the information found in an XML-format configuration file. The format
of this file is described below. When a <code>MemoryRealm</code>
instance is started, it will read the contents of this XML file and create
an "in memory database" of all the valid users and their associated
security roles.</p>
<p>Each time that Catalina needs to authenticate a user, it will call
the <code>authenticate()</code> method of this Realm implementation,
passing the username and password that were specified by the user. If
we find the user in the database (and match on the password), we accumulate
all of the security roles that are defined for this user, and create a
new <code>GenericPrincipal</code> object to be returned. If the user
is not authenticated, we return <code>null</code> instead. The
<code>GenericUser</code> object caches the set of security roles that
were owned by this user at the time of authentication, so that calls to
<code>isUserInRole()</code> can be answered without going back to the
database every time.</p>
</subsection>
<subsection name="Detailed Functional Requirements">
<h3>Configurable Properties</h3>
<p>The implementation shall support the following properties
that can be configured with JavaBeans property setters:</p>
<ul>
<li>Configurable debugging detail level.</li>
<li>Configurable file pathname (absolute or relative to
<code>$CATALINA_BASE</code> of the XML file containing our
defined users. [<code>conf/tomcat-users.xml</code>].</li>
</ul>
<h3>Lifecycle Functionality</h3>
<p>The following processing must be performed when the <code>start()</code>
method is called:</p>
<ul>
<li>Open and parse the specified XML file.</li>
<li>Create an in-memory database representation of the XML file
contents.</li>
<li><strong>NOTE</strong> - There is no requirement to recognize
subsequent changes to the contents of the XML file.</li>
</ul>
<p>The following processing must be performed when the <code>stop()</code>
method is called:</p>
<ul>
<li>Release object references to the in-memory database representation.</li>
</ul>
<h3>Method authenticate() Functionality</h3>
<p>When <code>authenticate()</code> is called, the following processing
is required:</p>
<ul>
<li>Select the one and only "user" instance from the in-memory database,
based on matching the specified username. If there is no such
instance, return <code>null</code>.</li>
<li>Authenticate the user by comparing the (possibly encrypted) password
value that was received against the password presented by the user.
If there is no match, return <code>null</code>.</li>
<li>Construct a new instance of class
<code>org.apache.catalina.realm.GenericPrincipal</code> (if not
already using this as the internal database representation) that
contains the authenticated username and a <code>List</code> of the
security roles associated with this user.</li>
<li>Return the newly constructed <code>GenericPrincipal</code>.</li>
</ul>
<h3>Method hasRole() Functionality</h3>
<p>When <code>hasRole()</code> is called, the following processing
is required:</p>
<ul>
<li>The <code>principal</code> that is passed as an argument SHOULD
be one that we returned (instanceof class
<code>org.apache.catalina.realm.GenericPrincipal</code>, with a
<code>realm</code> property that is equal to our instance.</li>
<li>If the passed <code>principal</code> meets these criteria, check
the specified role against the list returned by
<code>getRoles()</code>, and return <code>true</code> if the
specified role is included; otherwise, return <code>false</code>.</li>
<li>If the passed <code>principal</code> does not meet these criteria,
return <code>false</code>.</li>
</ul>
</subsection>
</section>
<section name="Testable Assertions">
<p>In addition to the assertions implied by the functionality requirements
listed above, the following additional assertions shall be tested to
validate the behavior of <code>MemoryRealm</code>:</p>
<ul>
</ul>
</section>
</body>
</document>

70
webapps/docs/funcspecs/index.xml Normal file
View File

@@ -0,0 +1,70 @@
<?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>Table of Contents</title>
</properties>
<body>
<section name="Catalina Functional Specifications">
<p>This documentation area includes <em>functional specifications</em> for
many features supported by the <strong>Catalina</strong> servlet container
portion of Tomcat. In most cases, these features are not documented in the
underlying Servlet or JSP specifications, so a definition of the expected
correct behavior is important both to implementors of those features, and to
test writers trying to decide what to test.</p>
<p>The functional specifications are divided into the following categories
in the menu (to the left):</p>
<ul>
<li><em>Administrative Apps</em> - Overall requirements for supporting an
ability to configure and operate a Tomcat installation through tools,
as well as detailed requirements for the tools themselves.</li>
<li><em>Internal Servlets</em> - Requirements for Catalina features that are
implemented as internal, container-managed, servlets.</li>
<li><em>Realm Implementations</em> - Requirements for the implementations of
the <code>org.apache.catalina.Realm</code> interface (providing access to
collections of users, passwords and roles) that are included in the
standard Tomcat distribution.</li>
</ul>
<p><em>NOTE</em> - In some cases, the contents of these functional specs has
been "reverse engineered" from existing implementations. This exercise is
still useful, because it provides an introduction to <strong>what</strong>
Catalina does, without being as concerned with <strong>how</strong> this is
accomplished.</p>
<p><strong>TODO</strong> - Obviously, this area has a long way to go before
it is complete. Contributions are welcome!</p>
</section>
</body>
</document>

698
webapps/docs/funcspecs/mbean-names.xml Normal file
View File

@@ -0,0 +1,698 @@
<?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="mbean-names.html">
&project;
<properties>
<author email="craigmcc@apache.org">Craig McClanahan</author>
<author email="amyroh@apache.org">Amy Roh</author>
<title>Tomcat MBean Names</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Background">
<p>We will be using <em>JMX MBeans</em> as the technology for
implementing manageability of Tomcat.</p>
<p>One of the key concepts of JMX is that each management bean has a unique
name in the MBeanServer's registry, and that management applications can
utilize these names to retrieve the MBean of interest to them for a
particular management operation. This document proposes a naming convention
for MBeans that allows easy calculation of the name for a particular MBean.
For background information on JMX MBean names, see the <em>Java Management
Extensions Instrumentation and Agent Specification</em>, version 1.0,
section 6. In particular, we will be discussing the String Representation of
<code>ObjectName</code> instances.</p>
</section>
<section name="Catalina Object Hierarchy">
<p>Tomcat's servlet container implementation, called Catalina, can be
represented as a hierarchy of objects that contain references to each other.
The object hierarchy can be represented as a tree, or (isomorphically) based
on the nesting of configuration elements in the <code>conf/server.xml</code>
file that is traditionally used to configure Tomcat stand-alone.</p>
<p>The valid component nestings for Catalina are depicted in the following
table, with columns that contain the following values:</p>
<ul>
<li><em>Pattern</em> - Nesting pattern of XML elements (in the
<code>conf/server.xml</code> file) used to configure this component.</li>
<li><em>Cardinality</em> - Minimum and maximum number of occurrences of
this element at this nesting position, which also corresponds to the
minimum and maximum number of Catalina components.</li>
<li><em>Identifier</em> - Name of the JavaBeans property of this component
that represents the unique identifier (within the nested hierarchy),
if any.</li>
<li><em>MBean ObjectName</em> - The portion of the MBean object name that
appears <strong>after</strong> the domain name. For now, it should be
assumed that all of these MBeans appear in the default JMX domain.</li>
</ul>
<p>In the <em>MBean ObjectName</em> descriptions, several types of symbolic
expressions are utilized to define variable text that is replaced by
corresponding values:</p>
<ul>
<li><em>${GROUP}</em> - One of the standard MBean names of the specified
"group" category. For example, the expression <code>${REALM}</code>
represents the values like <code>JDBCRealm</code> and <code>JAASRealm</code>
that identify the various MBeans for possible <code>Realm</code> components.</li>
<li><em>${name}</em> - Replaced by the value of property <code>name</code>
from the current component.</li>
<li><em>${parent.name}</em> - Replaced by the value of property
<code>name</code> from a parent of the current component, with the
parent's type identified by <em>parent</em>.</li>
<li><em>${###}</em> - An arbitrary numeric identifier that preserves
order but has no other particular meaning. In general, the server will
assign numeric values to existing instances with large gaps into which
new items can be configured if desired.</li>
</ul>
<table class="defaultTable">
<tr>
<th>Pattern</th>
<th>Cardinality</th>
<th>Identifier</th>
<th>MBean ObjectName</th>
</tr>
<tr>
<td>Server</td>
<td style="text-align: center;">1..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${SERVER}</code></td>
</tr>
<tr>
<td>Server / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}</code></td>
</tr>
<tr>
<td>Server / Service</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">name</code></td>
<td><code class="noHighlight">type=${SERVICE}, name=${name}</code></td>
</tr>
<tr>
<td>Server / Service / Connector</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">address, port</code></td>
<td><code class="noHighlight">type=${CONNECTOR}, service=${service}, port=${port},
address=${address}</code></td>
</tr>
<tr>
<td>Server / Service / Connector / Factory</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td>(Only defined explicitly for an SSL connector, but can be treated
as part of the connector component)</td>
</tr>
<tr>
<td>Server / Service / Connector / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}, service=${service},
port=${connector.port}, address=${connector.address}</code></td>
</tr>
<tr>
<td>Server / Service / Engine</td>
<td style="text-align: center;">1..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${ENGINE}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">name</code></td>
<td><code class="noHighlight">type=${HOST}, host=${name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context</td>
<td style="text-align: center;">1..n</td>
<td style="text-align: center;"><code class="noHighlight">path</code></td>
<td><code class="noHighlight">type=${CONTEXT}, context=${name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}, context=${context.name},
host=${host.name}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Loader</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LOADER}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Manager</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${MANAGER}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Realm</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${REALM}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Resources</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${RESOURCES}, context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Valve</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${VALVE}, sequence=${###}, context=${context.name},
host=${host.name}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / Wrapper</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">j2eeType=Servlet,name=${name},
WebModule=//${host.name}/${context.name},
J2EEApplication=${context.J2EEApplication},
J2EEServer=${context.J2EEServer}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / WrapperLifecycle</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${WRAPPER-LIFECYCLE}, sequence=${###},
context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Context / WrapperListener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${WRAPPER-LISTENER}, sequence=${###},
context=${context.name}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Realm</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${REALM}, host=${host.name},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Host / Valve</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${VALVE}, sequence=${###},
host=${host.name}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}</code>
(<strong>FIXME</strong> - disambiguate from Server / Service /
Listener)</td>
</tr>
<tr>
<td>Server / Service / Engine / Realm</td>
<td style="text-align: center;">0..1</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${REALM}, service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Engine / Valve</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${VALVE}, sequence=${###},
service=${service.name}</code></td>
</tr>
<tr>
<td>Server / Service / Listener</td>
<td style="text-align: center;">0..n</td>
<td style="text-align: center;">(none)</td>
<td><code class="noHighlight">type=${LISTENER}, sequence=${###}</code>
(<strong>FIXME</strong> - disambiguate from Server / Service /
Engine / Listener)</td>
</tr>
</table>
</section>
<section name="MBean Groups and Names">
<p>The following MBean names shall be defined in the resource file
<code>/org/apache/catalina/mbeans/mbeans-descriptors.xml</code> (and
therefore available for use within the Administration/Configuration
web application for Tomcat):</p>
<table class="defaultTable">
<tr>
<th>MBean Name</th>
<th>Group Name</th>
<th>Catalina Interface</th>
<th>Implementation Class</th>
</tr>
<tr>
<td><code class="noHighlight">AccessLogValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.AccessLogValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">BasicAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.BasicAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">CertificatesValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.CertificatesValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextConfig</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.startup.ContextConfig</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextEnvironment</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextEnvironment</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextEnvironment</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextResource</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResource</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResource</code></td>
</tr>
<tr>
<td><code class="noHighlight">ContextResourceLink</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResourceLink</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.ContextResourceLink</code></td>
</tr>
<tr>
<td><code class="noHighlight">CoyoteConnector</code></td>
<td style="text-align: center;"><code class="noHighlight">CONNECTOR</code></td>
<td><code class="noHighlight">org.apache.catalina.Connector</code></td>
<td><code class="noHighlight">org.apache.coyote.tomcat4.CoyoteConnector</code></td>
</tr>
<tr>
<td><code class="noHighlight">DigestAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.DigestAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">EngineConfig</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.startup.EngineConfig</code></td>
</tr>
<tr>
<td><code class="noHighlight">ErrorReportValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.ErrorReportValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">ErrorDispatcherValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.ErrorDispatcherValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">FormAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.FormAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">Group</code></td>
<td style="text-align: center;"><code class="noHighlight">GROUP</code></td>
<td><code class="noHighlight">org.apache.catalina.Group</code></td>
<td><code class="noHighlight">org.apache.catalina.Group</code></td>
</tr>
<tr>
<td><code class="noHighlight">HostConfig</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.startup.HostConfig</code></td>
</tr>
<tr>
<td><code class="noHighlight">HttpConnector10</code></td>
<td style="text-align: center;"><code class="noHighlight">CONNECTOR</code></td>
<td><code class="noHighlight">org.apache.catalina.Connector</code></td>
<td><code class="noHighlight">org.apache.catalina.connector.http10.HttpConnector</code></td>
</tr>
<tr>
<td><code class="noHighlight">HttpConnector11</code></td>
<td style="text-align: center;"><code class="noHighlight">CONNECTOR</code></td>
<td><code class="noHighlight">org.apache.catalina.Connector</code></td>
<td><code class="noHighlight">org.apache.catalina.connector.http.HttpConnector</code></td>
</tr>
<tr>
<td><code class="noHighlight">JAASRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.JAASRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">JDBCRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.JDBCRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">JDBCUserDatabase</code></td>
<td style="text-align: center;"><code class="noHighlight">USERDATABASE</code></td>
<td><code class="noHighlight">org.apache.catalina.users.JDBCUserDatabase</code></td>
<td><code class="noHighlight">org.apache.catalina.users.JDBCUserDatabase</code></td>
</tr>
<tr>
<td><code class="noHighlight">JNDIRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.JNDIRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">MBeanFactory</code></td>
<td style="text-align: center;"><code class="noHighlight"></code></td>
<td><code class="noHighlight"></code></td>
<td><code class="noHighlight">org.apache.catalina.mbeans.MBeanFactory</code></td>
</tr>
<tr>
<td><code class="noHighlight">MemoryRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.MemoryRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">MemoryUserDatabase</code></td>
<td style="text-align: center;"><code class="noHighlight">USERDATABASE</code></td>
<td><code class="noHighlight">org.apache.catalina.users.MemoryUserDatabase</code></td>
<td><code class="noHighlight">org.apache.catalina.users.MemoryUserDatabase</code></td>
</tr>
<tr>
<td><code class="noHighlight">NamingContextListener</code></td>
<td style="text-align: center;"><code class="noHighlight">LISTENER</code></td>
<td><code class="noHighlight">org.apache.catalina.LifecycleListener</code></td>
<td><code class="noHighlight">org.apache.catalina.core.NamingContextListener</code></td>
</tr>
<tr>
<td><code class="noHighlight">NamingResources</code></td>
<td style="text-align: center;"><code class="noHighlight">RESOURCES</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.NamingResources</code></td>
<td><code class="noHighlight">org.apache.catalina.deploy.NamingResources</code></td>
</tr>
<tr>
<td><code class="noHighlight">NonLoginAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.NonLoginAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">PersistentManager</code></td>
<td style="text-align: center;"><code class="noHighlight">MANAGER</code></td>
<td><code class="noHighlight">org.apache.catalina.Manager</code></td>
<td><code class="noHighlight">org.apache.catalina.session.PersistentManager</code></td>
</tr>
<tr>
<td><code class="noHighlight">RemoteAddrValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.RemoteAddrValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">RemoteHostValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.RemoteHostValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">RequestDumperValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.RequestDumperValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">Role</code></td>
<td style="text-align: center;"><code class="noHighlight">ROLE</code></td>
<td><code class="noHighlight">org.apache.catalina.Role</code></td>
<td><code class="noHighlight">org.apache.catalina.Role</code></td>
</tr>
<tr>
<td><code class="noHighlight">SingleSignOn</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.valves.SingleSignOn</code></td>
</tr>
<tr>
<td><code class="noHighlight">SSLAuthenticator</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.authenticator.SSLAuthenticator</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardContext</code></td>
<td style="text-align: center;"><code class="noHighlight">CONTEXT</code></td>
<td><code class="noHighlight">org.apache.catalina.Context</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardContext</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardContextValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardContextValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardEngine</code></td>
<td style="text-align: center;"><code class="noHighlight">ENGINE</code></td>
<td><code class="noHighlight">org.apache.catalina.Engine</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardEngine</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardEngineValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardEngineValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardHost</code></td>
<td style="text-align: center;"><code class="noHighlight">HOST</code></td>
<td><code class="noHighlight">org.apache.catalina.Host</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardHost</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardHostValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardHostValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardManager</code></td>
<td style="text-align: center;"><code class="noHighlight">MANAGER</code></td>
<td><code class="noHighlight">org.apache.catalina.Manager</code></td>
<td><code class="noHighlight">org.apache.catalina.session.StandardManager</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardServer</code></td>
<td style="text-align: center;"><code class="noHighlight">SERVER</code></td>
<td><code class="noHighlight">org.apache.catalina.Server</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardServer</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardService</code></td>
<td style="text-align: center;"><code class="noHighlight">SERVICE</code></td>
<td><code class="noHighlight">org.apache.catalina.Service</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardService</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardWrapper</code></td>
<td style="text-align: center;"><code class="noHighlight">WRAPPER</code></td>
<td><code class="noHighlight">org.apache.catalina.Wrapper</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardWrapper</code></td>
</tr>
<tr>
<td><code class="noHighlight">StandardWrapperValve</code></td>
<td style="text-align: center;"><code class="noHighlight">VALVE</code></td>
<td><code class="noHighlight">org.apache.catalina.Valve</code></td>
<td><code class="noHighlight">org.apache.catalina.core.StandardWrapperValve</code></td>
</tr>
<tr>
<td><code class="noHighlight">User</code></td>
<td style="text-align: center;"><code class="noHighlight">USER</code></td>
<td><code class="noHighlight">org.apache.catalina.User</code></td>
<td><code class="noHighlight">org.apache.catalina.User</code></td>
</tr>
<tr>
<td><code class="noHighlight">UserDatabaseRealm</code></td>
<td style="text-align: center;"><code class="noHighlight">REALM</code></td>
<td><code class="noHighlight">org.apache.catalina.Realm</code></td>
<td><code class="noHighlight">org.apache.catalina.realm.UserDatabaseRealm</code></td>
</tr>
<tr>
<td><code class="noHighlight">WebappLoader</code></td>
<td style="text-align: center;"><code class="noHighlight">LOADER</code></td>
<td><code class="noHighlight">org.apache.catalina.Loader</code></td>
<td><code class="noHighlight">org.apache.catalina.loader.WebappLoader</code></td>
</tr>
</table>
</section>
<section name="JSR-88 Cross Reference">
<p>The deployment objects in the JSR-88 API object hierarchy correspond
to the specified MBean names or groups as follows:</p>
<table class="defaultTable">
<tr>
<th>JSR-88 API Object</th>
<th>MBean Name or Group</th>
<th>Comments</th>
</tr>
<tr>
<td><code class="noHighlight">DeployableObject</code></td>
<td><code class="noHighlight">${CONTEXT}</code></td>
<td>Context deployment info plus the corresponding WAR file</td>
</tr>
<tr>
<td><code class="noHighlight">Target</code></td>
<td><code class="noHighlight">${HOST}</code></td>
<td></td>
</tr>
</table>
</section>
</body>
</document>

56
webapps/docs/funcspecs/project.xml Normal file
View File

@@ -0,0 +1,56 @@
<?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="Catalina Functional Specifications"
href="https://tomcat.apache.org/">
<title>Catalina Functional Specifications</title>
<logo href="/images/tomcat.gif">
Catalina Functional Specifications
</logo>
<body>
<menu name="Links">
<item name="Docs Home" href="../index.html"/>
<item name="Functional Specs" href="index.html"/>
<item name="FAQ" href="https://wiki.apache.org/tomcat/FAQ" />
<item name="User Comments" href="#comments_section"/>
</menu>
<menu name="Administrative Apps">
<item name="Overall Requirements" href="fs-admin-apps.html"/>
<item name="Tomcat MBean Names" href="mbean-names.html"/>
<item name="Administered Objects" href="fs-admin-objects.html"/>
<item name="Supported Operations" href="fs-admin-opers.html"/>
</menu>
<menu name="Internal Servlets">
<item name="Default Servlet" href="fs-default.html"/>
</menu>
<menu name="Realm Implementations">
<item name="JDBC Realm" href="fs-jdbc-realm.html"/>
<item name="JNDI Realm" href="fs-jndi-realm.html"/>
<item name="Memory Realm" href="fs-memory-realm.html"/>
</menu>
</body>
</project>

240
webapps/docs/host-manager-howto.xml Normal file
View File

@@ -0,0 +1,240 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE document [
<!ENTITY project SYSTEM "project.xml">
]>
<document url="host-manager-howto.html">
&project;
<properties>
<title>Host Manager App -- Text Interface</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The <strong>Tomcat Host Manager</strong> application enables you to create,
delete, and otherwise manage virtual hosts within Tomcat. This how-to guide
is best accompanied by the following pieces of documentation:
</p>
<ul>
<li>
<a href="virtual-hosting-howto.html">Virtual Hosting How-To</a> for more
information about virtual hosting.
</li>
<li>
<a href="config/host.html">The Host Container</a> for more information
about the underlying xml configuration of virtual hosts and description
of attributes.
</li>
</ul>
<p>
The <strong>Tomcat Host Manager</strong> application is a part of
Tomcat installation, by default available using the following
context: <code>/host-manager</code>. You can use the host manager in the
following ways:
</p>
<ul>
<li>
Utilizing the graphical user interface, accessible at:
<code>{server}:{port}/host-manager/html</code>.
</li>
<li>
Utilizing a set of minimal HTTP requests suitable for scripting.
You can access this mode at:
<code>{server}:{port}/host-manager/text</code>.
</li>
</ul>
<p>
Both ways enable you to add, remove, start, and stop virtual hosts. Changes
may be presisted by using the <code>persist</code> command. This document
focuses on the text interface. For further information about the graphical
interface, see
<a href="html-host-manager-howto.html">Host Manager App -- HTML Interface</a>.
</p>
</section>
<section name="Configuring Manager Application Access">
<p><em>The description below uses <code>$CATALINA_HOME</code> to refer the
base Tomcat directory. It is the directory in which you installed
Tomcat, for example <code>C:\tomcat8</code>, or
<code>/usr/share/tomcat8</code>.</em></p>
<p>
The Host Manager application requires a user with one of the following
roles:
</p>
<ul>
<li>
<code>admin-gui</code> - use this role for the graphical web interface.
</li>
<li>
<code>admin-script</code> - use this role for the scripting web interface.
</li>
</ul>
<p>
To enable access to the text interface of the Host Manager application,
either grant your Tomcat user the appropriate role, or create a new one with
the correct role. For example, open
<code>${CATALINA_BASE}/conf/tomcat-users.xml</code> and enter the following:
</p>
<source><![CDATA[<user username="test" password="chang3m3N#w" roles="admin-script"/>]]></source>
<p>
No further settings is needed. When you now access
<code>{server}:{port}/host-manager/text/${COMMAND}</code>,you are able to
log in with the created credentials. For example:
<source>$ curl -u ${USERNAME}:${PASSWORD} http://localhost:8080/host-manager/text/list
OK - Listed hosts
localhost:</source>
</p>
<p>
Note that in case you retrieve your users using the
<code>DataSourceRealm</code>, <code>JDBCRealm</code>, or
<code>JNDIRealm</code> mechanism, add the appropriate role in the database
or the directory server respectively.
</p>
</section>
<section name="List of Commands">
<p>The following commands are supported:</p>
<ul>
<li>list</li>
<li>add</li>
<li>remove</li>
<li>start</li>
<li>stop</li>
<li>persist</li>
</ul>
<p>
In the following subsections, the username and password is assumed to be
<b>test:test</b>. For your environment, use credentials created in the
previous sections.
</p>
<subsection name="List command">
<p>
Use the <b>list</b> command to see the available virtual hosts on your
Tomcat instance.
</p>
<p><i>Example command</i>:</p>
<code>curl -u test:test http://localhost:8080/host-manager/text/list</code>
<p><i>Example response</i>:</p>
<source>OK - Listed hosts
localhost:</source>
</subsection>
<subsection name="Add command">
<p>
Use the <b>add</b> command to add a new virtual host. Parameters used
for the <b>add</b> command:
</p>
<ul>
<li>String <b>name</b>: Name of the virtual host. <b>REQUIRED</b></li>
<li>String <b>aliases</b>: Aliases for your virtual host.</li>
<li>String <b>appBase</b>: Base path for the application that will be
served by this virtual host. Provide relative or absolute path.</li>
<li>Boolean <b>manager</b>: If true, the Manager app is added to the
virtual host. You can access it with the <i>/manager</i> context.</li>
<li>Boolean <b>autoDeploy</b>: If true, Tomcat automatically redeploys
applications placed in the appBase directory.</li>
<li>Boolean <b>deployOnStartup</b>: If true, Tomcat automatically deploys
applications placed in the appBase directory on startup.</li>
<li>Boolean <b>deployXML</b>: If true, the <i>/META-INF/context.xml</i>
file is read and used by Tomcat.</li>
<li>Boolean <b>copyXML</b>: If true, Tomcat copies <i>/META-INF/context.xml</i>
file and uses the original copy regardless of updates to the application's
<i>/META-INF/context.xml</i> file.</li>
</ul>
<p><i>Example command</i>:</p>
<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/add?name=www.awesomeserver.com&aliases=awesomeserver.com&appBase/mnt/appDir&deployOnStartup=true]]></source>
<p><i>Example response</i>:</p>
<source>add: Adding host [www.awesomeserver.com]</source>
</subsection>
<subsection name="Remove command">
<p>
Use the <b>remove</b> command to remove a virtual host. Parameters used
for the <b>remove</b> command:
</p>
<ul>
<li>String <b>name</b>: Name of the virtual host to be removed.
<b>REQUIRED</b></li>
</ul>
<p><i>Example command</i>:</p>
<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/remove?name=www.awesomeserver.com]]></source>
<p><i>Example response</i>:</p>
<source>remove: Removing host [www.awesomeserver.com]</source>
</subsection>
<subsection name="Start command">
<p>
Use the <b>start</b> command to start a virtual host. Parameters used
for the <b>start</b> command:
</p>
<ul>
<li>String <b>name</b>: Name of the virtual host to be started.
<b>REQUIRED</b></li>
</ul>
<p><i>Example command</i>:</p>
<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/start?name=www.awesomeserver.com]]></source>
<p><i>Example response</i>:</p>
<source>OK - Host www.awesomeserver.com started</source>
</subsection>
<subsection name="Stop command">
<p>
Use the <b>stop</b> command to stop a virtual host. Parameters used
for the <b>stop</b> command:
</p>
<ul>
<li>String <b>name</b>: Name of the virtual host to be stopped.
<b>REQUIRED</b></li>
</ul>
<p><i>Example command</i>:</p>
<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/stop?name=www.awesomeserver.com]]></source>
<p><i>Example response</i>:</p>
<source>OK - Host www.awesomeserver.com stopped</source>
</subsection>
<subsection name="Persist command">
<p>
Use the <b>persist</b> command to persist a virtual host into
<b>server.xml</b>. Parameters used for the <b>persist</b> command:
</p>
<ul>
<li>String <b>name</b>: Name of the virtual host to be persist.
<b>REQUIRED</b></li>
</ul>
<p>
This functionality is disabled by default. To enable this option, you must
configure the <code>StoreConfigLifecycleListener</code> listener first.
To do so, add the following listener to your <i>server.xml</i>:
</p>
<source><![CDATA[<Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>]]></source>
<p><i>Example command</i>:</p>
<source><![CDATA[curl -u test:test http://localhost:8080/host-manager/text/persist?name=www.awesomeserver.com]]></source>
<p><i>Example response</i>:</p>
<source>OK - Configuration persisted</source>
<p><i>Example manual entry</i>:</p>
<source><![CDATA[<Host appBase="www.awesomeserver.com" name="www.awesomeserver.com" deployXML="false" unpackWARs="false">
</Host>]]></source>
</subsection>
</section>
</body>
</document>

213
webapps/docs/html-host-manager-howto.xml Normal file
View File

@@ -0,0 +1,213 @@
<?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="html-host-manager-howto.html">
&project;
<properties>
<title>Host Manager App -- HTML Interface</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>
The <strong>Tomcat Host Manager</strong> application enables you to create,
delete, and otherwise manage virtual hosts within Tomcat. This how-to guide
is best accompanied by the following pieces of documentation:
</p>
<ul>
<li>
<a href="virtual-hosting-howto.html">Virtual Hosting How-To</a> for more
information about virtual hosting.
</li>
<li>
<a href="config/host.html">The Host Container</a> for more information
about the underlying xml configuration of virtual hosts and description
of attributes.
</li>
<li>
<a href="host-manager-howto.html">Host Manager App -- Text Interface</a>
for full description of the commands.
</li>
</ul>
<p>
The <strong>Tomcat Host Manager</strong> application is a part of
Tomcat installation, by default available using the following
context: <code>/host-manager</code>. You can use the host manager in the
following ways:
</p>
<ul>
<li>
Utilizing the graphical user interface, accessible at:
<code>{server}:{port}/host-manager/html</code>.
</li>
<li>
Utilizing a set of minimal HTTP requests suitable for scripting.
You can access this mode at:
<code>{server}:{port}/host-manager/text</code>.
</li>
</ul>
<p>
Both ways enable you to add, remove, start, and stop virtual hosts.
Changes may be presisted by using the <code>persist</code> command. This
document focuses on the HTML interface. For further information about the
graphical interface, see
<a href="host-manager-howto.html">Host Manager App -- Text Interface</a>.
</p>
</section>
<section name="Configuring Manager Application Access">
<p><em>The description below uses <code>$CATALINA_HOME</code> to refer the
base Tomcat directory. It is the directory in which you installed
Tomcat, for example <code>C:\tomcat8</code>, or
<code>/usr/share/tomcat8</code>.</em></p>
<p>
The Host Manager application requires a user with one of the following
roles:
</p>
<ul>
<li>
<code>admin-gui</code> - use this role for the graphical web interface.
</li>
<li>
<code>admin-script</code> - use this role for the scripting web interface.
</li>
</ul>
<p>
To enable access to the HTML interface of the Host Manager application,
either grant your Tomcat user the appropriate role, or create a new one with
the correct role. For example, open
<code>${CATALINA_BASE}/conf/tomcat-users.xml</code> and enter the following:
</p>
<source><![CDATA[<user username="test" password="chang3m3N#w" roles="admin-gui"/>]]></source>
<p>
No further settings is needed. When you now access
<code>{server}:{port}/host-manager/html</code>,you are able to
log in with the created credentials.
</p>
<p>
Note that in case you retrieve your users using the
<code>DataSourceRealm</code>, <code>JDBCRealm</code>, or
<code>JNDIRealm</code> mechanism, add the appropriate role in the database
or the directory server respectively.
</p>
</section>
<section name="Interface Description">
<p>The interface is divided into six sections:</p>
<ul>
<li><strong>Message</strong> - Displays success and failure messages.</li>
<li><strong>Host Manager</strong> - Provides basic Host Manager operations
, like list and help.</li>
<li><strong>Host name</strong> - Provides a list of virtual Host Names and
enables you to operate them. </li>
<li><strong>Add Virtual Host</strong> - Enables you to add a new Virtual
Host.</li>
<li><strong>Persist configuration</strong> - Enables you to persist your
current Virtual Hosts.</li>
<li><strong>Server Information</strong> - Information about the Tomcat
server.</li>
</ul>
</section>
<section name="Message">
<p>
Displays information about the success or failure of the last Host Manager
command you performed:
</p>
<ul>
<li>Success: <strong>OK</strong> is displayed
and may be followed by a success message.</li>
<li>Failure: <strong>FAIL</strong>
is displayed followed by an error message.</li>
</ul>
<p>
Note that the console of your Tomcat server may reveal more information
about each command.
</p>
</section>
<section name="Host Manager">
<p>The Host Manager section enables you to:</p>
<ul>
<li><strong>List Virtual Hosts</strong> - Refresh a list of
currently-configured virtual hosts.</li>
<li><strong>HTML Host Manager Help</strong> - A documentation link.</li>
<li><strong>Host Manager Help</strong> - A documentation link.</li>
<li><strong>Server Status</strong> - A link to the <strong>Manager</strong>
application. Note that you user must have sufficient permissions to access
the application.</li>
</ul>
</section>
<section name="Host Name">
<p>The Host name section contains a list of currently-configured virtual host
names. It enables you to:</p>
<ul>
<li>View the host names</li>
<li>View the host name aliases</li>
<li>Perform basic commands, that is <strong>start</strong>,
<strong>stop</strong>, and <strong>remove</strong>.</li>
</ul>
</section>
<section name="Add Virtual Host">
<p>The Add Virtual Host section enables you to add a virtual host using a
graphical interface. For a description of each property, see the
<a href="host-manager-howto.html">Host Manager App -- Text Interface</a>
documentation. Note that any configuration added via this interface is
non-persistent.</p>
</section>
<section name="Persist Configuration">
<p>The Persist Configuration section enables you to persist your current
configuration into the <i>server.xml</i> file.</p>
<p> This functionality is disabled by default. To enable this option, you must
configure the <code>StoreConfigLifecycleListener</code> listener first.
To do so, add the following listener to your <i>server.xml</i>:</p>
<source><![CDATA[<Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener"/>]]></source>
<p>After you configure the listener, click <strong>All</strong> to make your
configuration persistent.</p>
</section>
<section name="Server Information">
<p>
Provides a basic information about the currently-running Tomcat instance,
the JVM, and the underlying operating system.
</p>
</section>
</body>
</document>

539
webapps/docs/html-manager-howto.xml Normal file
View File

@@ -0,0 +1,539 @@
<?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="html-manager-howto.html">
&project;
<properties>
<author email="glenn@apache.org">Glenn L. Nielsen</author>
<title>Tomcat Web Application Manager How To</title>
</properties>
<body>
<section name="Table of Contents">
<toc/>
</section>
<section name="Introduction">
<p>In many production environments it is very useful to have the capability
to manage your web applications without having to shut down and restart
Tomcat. This document is for the HTML web interface to the web application
<a href="manager-howto.html">manager</a>.</p>
<p>The interface is divided into six sections:</p>
<ul>
<li><strong>Message</strong> - Displays success and failure messages.</li>
<li><strong>Manager</strong> - General manager operations like list and
help.</li>
<li><strong>Applications</strong> - List of web applications and
commands.</li>
<li><strong>Deploy</strong> - Deploying web applications.</li>
<li><strong>Diagnostics</strong> - Identifying potential problems.</li>
<li><strong>Server Information</strong> - Information about the Tomcat
server.</li>
</ul>
</section>
<section name="Message">
<p>
Displays information about the success or failure of the last web application
manager command you performed. If it succeeded <strong>OK</strong> is displayed
and may be followed by a success message. If it failed <strong>FAIL</strong>
is displayed followed by an error message. Common failure messages are
documented below for each command. The complete list of failure messages for
each command can be found in the <a href="manager-howto.html">manager</a> web
application documentation.
</p>
</section>
<section name="Manager">
<p>The Manager section has three links:</p>
<ul>
<li><strong>List Applications</strong> - Redisplay a list of web
applications.</li>
<li><strong>HTML Manager Help</strong> - A link to this document.</li>
<li><strong>Manager Help</strong> - A link to the comprehensive Manager
App HOW TO.</li>
</ul>
</section>
<section name="Applications">
<p>The Applications section lists information about all the installed web
applications and provides links for managing them. For each web application
the following is displayed:</p>
<ul>
<li><strong>Path</strong> - The web application context path.</li>
<li><strong>Display Name</strong> - The display name for the web application
if it has one configured in its "web.xml" file.</li>
<li><strong>Running</strong> - Whether the web application is running and
available (true), or not running and unavailable (false).</li>
<li><strong>Sessions</strong> - The number of active sessions for remote
users of this web application. The number of sessions is a link which
when submitted displays more details about session usage by the web
application in the Message box.</li>
<li><strong>Commands</strong> - Lists all commands which can be performed on
the web application. Only those commands which can be performed will be
listed as a link which can be submitted. No commands can be performed on
the manager web application itself. The following commands can be
performed:
<ul>
<li><strong>Start</strong> - Start a web application which had been
stopped.</li>
<li><strong>Stop</strong> - Stop a web application which is currently
running and make it unavailable.</li>
<li><strong>Reload</strong> - Reload the web application so that new
".jar" files in <code>/WEB-INF/lib/</code> or new classes in
<code>/WEB-INF/classes/</code> can be used.</li>
<li><strong>Undeploy</strong> - Stop and then remove this web
application from the server.</li>
</ul>
</li>
</ul>
<subsection name="Start">
<p>Signal a stopped application to restart, and make itself available again.
Stopping and starting is useful, for example, if the database required by
your application becomes temporarily unavailable. It is usually better to
stop the web application that relies on this database rather than letting
users continuously encounter database exceptions.</p>
<p>If this command succeeds, you will see a Message like this:</p>
<source>OK - Started application at context path /examples</source>
<p>Otherwise, the Message will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
<p>An exception was encountered trying to start the web application.
Check the Tomcat logs for the details.</p>
</li>
<li><em>Invalid context path was specified</em>
<p>The context path must start with a slash character, unless you are
referencing the ROOT web application -- in which case the context path
must be a zero-length string.</p>
</li>
<li><em>No context exists for path /foo</em>
<p>There is no deployed application on the context path
that you specified.</p>
</li>
<li><em>No context path was specified</em>
<p>
The <code>path</code> parameter is required.
</p>
</li>
</ul>
</subsection>
<subsection name="Stop">
<p>Signal an existing application to make itself unavailable, but leave it
deployed. Any request that comes in while an application is
stopped will see an HTTP error 404, and this application will show as
"stopped" on a list applications command.</p>
<p>If this command succeeds, you will see a Message like this:</p>
<source>OK - Stopped application at context path /examples</source>
<p>Otherwise, the Message will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
<p>An exception was encountered trying to stop the web application.
Check the Tomcat logs for the details.</p>
</li>
<li><em>Invalid context path was specified</em>
<p>The context path must start with a slash character, unless you are
referencing the ROOT web application -- in which case the context path
must be a zero-length string.</p>
</li>
<li><em>No context exists for path /foo</em>
<p>There is no deployed application on the context path
that you specified.</p>
</li>
<li><em>No context path was specified</em>
<p>
The <code>path</code> parameter is required.
</p>
</li>
</ul>
</subsection>
<subsection name="Reload">
<p>Signal an existing application to shut itself down and reload. This can
be useful when the web application context is not reloadable and you have
updated classes or property files in the <code>/WEB-INF/classes</code>
directory or when you have added or updated jar files in the
<code>/WEB-INF/lib</code> directory.
</p>
<p><strong>NOTE:</strong> The <code>/WEB-INF/web.xml</code>
web application configuration file is not checked on a reload;
the previous web.xml configuration is used.
If you have made changes to your web.xml file you must stop
then start the web application.
</p>
<p>If this command succeeds, you will see a Message like this:</p>
<source>
OK - Reloaded application at context path /examples
</source>
<p>Otherwise, the Message will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
<p>An exception was encountered trying to restart the web application.
Check the Tomcat logs for the details.</p>
</li>
<li><em>Invalid context path was specified</em>
<p>The context path must start with a slash character, unless you are
referencing the ROOT web application -- in which case the context path
must be a zero-length string.</p>
</li>
<li><em>No context exists for path /foo</em>
<p>There is no deployed application on the context path
that you specified.</p>
</li>
<li><em>No context path was specified</em>
<p>The <code>path</code> parameter is required.</p>
</li>
<li><em>Reload not supported on WAR deployed at path /foo</em>
<p>Currently, application reloading (to pick up changes to the classes or
<code>web.xml</code> file) is not supported when a web application is
installed directly from a WAR file, which happens when the host is
configured to not unpack WAR files. As it only works when the web
application is installed from an unpacked directory, if you are using
a WAR file, you should <code>undeploy</code> and then <code>deploy</code>
the application again to pick up your changes.</p>
</li>
</ul>
</subsection>
<subsection name="Undeploy">
<p><strong><span style="color: red;">WARNING</span> - This command will delete the
contents of the web application directory and/or ".war" file if it exists within
the <code>appBase</code> directory (typically "webapps") for this virtual host
</strong>. The web application temporary work directory is also deleted. If
you simply want to take an application out of service, you should use the
<code>/stop</code> command instead.</p>
<p>Signal an existing application to gracefully shut itself down, and then
remove it from Tomcat (which also makes this context path available for
reuse later). This command is the logical opposite of the
<code>/deploy</code> Ant command, and the related deploy features available
in the HTML manager.</p>
<p>If this command succeeds, you will see a Message like this:</p>
<source>OK - Undeployed application at context path /examples</source>
<p>Otherwise, the Message will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Encountered exception</em>
<p>An exception was encountered trying to undeploy the web application.
Check the Tomcat logs for the details.</p>
</li>
<li><em>Invalid context path was specified</em>
<p>The context path must start with a slash character, unless you are
referencing the ROOT web application -- in which case the context path
must be a zero-length string.</p>
</li>
<li><em>No context exists for path /foo</em>
<p>There is no deployed application on the context path
that you specified.</p>
</li>
<li><em>No context path was specified</em>
The <code>path</code> parameter is required.
</li>
</ul>
</subsection>
</section>
<section name="Deploy">
<p>Web applications can be deployed using files or directories located
on the Tomcat server or you can upload a web application archive (WAR)
file to the server.</p>
<p>To install an application, fill in the appropriate fields for the type
of install you want to do and then submit it using the <i>Install</i>
button.</p>
<subsection name="Deploy directory or WAR file located on server">
<p>Deploy and start a new web application, attached to the specified <i>Context
Path:</i> (which must not be in use by any other web application).
This command is the logical opposite of the <em>Undeploy</em> command.</p>
<p>There are a number of different ways the deploy command can be used.</p>
<subsection name="Deploy a Directory or WAR by URL">
<p>Install a web application directory or ".war" file located on the Tomcat
server. If no <i>Context Path</i> is specified, the directory name or the
war file name without the ".war" extension is used as the path. The
<i>WAR or Directory URL</i> specifies a URL (including the <code>file:</code>
scheme) for either a directory or a web application archive (WAR) file. The
supported syntax for a URL referring to a WAR file is described on the Javadocs
page for the <code>java.net.JarURLConnection</code> class. Use only URLs that
refer to the entire WAR file.</p>
<p>In this example the web application located in the directory
<code>C:\path\to\foo</code> on the Tomcat server (running on Windows)
is deployed as the web application context named <code>/footoo</code>.</p>
<source>Context Path: /footoo
WAR or Directory URL: file:C:/path/to/foo
</source>
<p>In this example the ".war" file <code>/path/to/bar.war</code> on the
Tomcat server (running on Unix) is deployed as the web application
context named <code>/bar</code>. Notice that there is no <code>path</code>
parameter so the context path defaults to the name of the web application
archive file without the ".war" extension.</p>
<source>WAR or Directory URL: jar:file:/path/to/bar.war!/</source>
</subsection>
<subsection name="Deploy a Directory or War from the Host appBase">
<p>Install a web application directory or ".war" file located in your Host
appBase directory. If no <i>Context Path</i> is specified the directory name
or the war file name without the ".war" extension is used as the path.</p>
<p>In this example the web application located in a subdirectory named
<code>foo</code> in the Host appBase directory of the Tomcat server is
deployed as the web application context named <code>/foo</code>. Notice
that there is no <code>path</code> parameter so the context path defaults
to the name of the web application directory.</p>
<source>WAR or Directory URL: foo</source>
<p>In this example the ".war" file <code>bar.war</code> located in your
Host appBase directory on the Tomcat server is deployed as the web
application context named <code>/bartoo</code>.</p>
<source>Context Path: /bartoo
WAR or Directory URL: bar.war</source>
</subsection>
<subsection name="Deploy using a Context configuration &quot;.xml&quot; file">
<p>If the Host deployXML flag is set to true, you can install a web
application using a Context configuration ".xml" file and an optional
".war" file or web application directory. The <i>Context Path</i>
is not used when installing a web application using a context ".xml"
configuration file.</p>
<p>A Context configuration ".xml" file can contain valid XML for a
web application Context just as if it were configured in your
Tomcat <code>server.xml</code> configuration file. Here is an
example for Tomcat running on Windows:</p>
<source><![CDATA[<Context path="/foobar" docBase="C:\path\to\application\foobar">
</Context>]]></source>
<p>Use of the <i>WAR or Directory URL</i> is optional. When used
to select a web application ".war" file or directory it overrides any
docBase configured in the context configuration ".xml" file.</p>
<p>Here is an example of installing an application using a Context
configuration ".xml" file for Tomcat running on Windows.</p>
<source>XML Configuration file URL: file:C:/path/to/context.xml</source>
<p>Here is an example of installing an application using a Context
configuration ".xml" file and a web application ".war" file located
on the server (Tomcat running on Unix).</p>
<source>XML Configuration file URL: file:/path/to/context.xml
WAR or Directory URL: jar:file:/path/to/bar.war!/</source>
</subsection>
</subsection>
<subsection name="Upload a WAR file to install">
<p>Upload a WAR file from your local system and install it into the
appBase for your Host. The name of the WAR file without the ".war"
extension is used as the context path name.</p>
<p>Use the <i>Browse</i> button to select a WAR file to upload to the
server from your local desktop system.</p>
<p>The .WAR file may include Tomcat specific deployment configuration, by
including a Context configuration XML file in
<code>/META-INF/context.xml</code>.</p>
<p>Upload of a WAR file could fail for the following reasons:</p>
<ul>
<li><em>File uploaded must be a .war</em>
<p>The upload install will only accept files which have the filename
extension of ".war".</p>
</li>
<li><em>War file already exists on server</em>
<p>If a war file of the same name already exists in your Host's
appBase the upload will fail. Either undeploy the existing war file
from your Host's appBase or upload the new war file using a different
name.</p>
</li>
<li><em>File upload failed, no file</em>
<p>The file upload failed, no file was received by the server.</p>
</li>
<li><em>Install Upload Failed, Exception:</em>
<p>The war file upload or install failed with a Java Exception.
The exception message will be listed.</p>
</li>
</ul>
</subsection>
<subsection name="Deployment Notes">
<p>If the Host is configured with unpackWARs=true and you install a war
file, the war will be unpacked into a directory in your Host appBase
directory.</p>
<p>If the application war or directory is deployed in your Host appBase
directory and either the Host is configured with autoDeploy=true the Context
path must match the directory name or war file name without the ".war"
extension.</p>
<p>For security when untrusted users can manage web applications, the
Host deployXML flag can be set to false. This prevents untrusted users
from installing web applications using a configuration XML file and
also prevents them from installing application directories or ".war"
files located outside of their Host appBase.</p>
</subsection>
<subsection name="Deploy Message">
<p>If deployment and startup is successful, you will receive a Message
like this:</p>
<source>OK - Deployed application at context path /foo</source>
<p>Otherwise, the Message will start with <code>FAIL</code> and include an
error message. Possible causes for problems include:</p>
<ul>
<li><em>Application already exists at path /foo</em>
<p>The context paths for all currently running web applications must be
unique. Therefore, you must either undeploy the existing web
application using this context path, or choose a different context path
for the new one.</p>
</li>
<li><em>Document base does not exist or is not a readable directory</em>
<p>The URL specified by the <i>WAR or Directory URL:</i> field must
identify a directory on this server that contains the "unpacked" version
of a web application, or the absolute URL of a web application archive
(WAR) file that contains this application. Correct the value entered for
the <i>WAR or Directory URL:</i> field.</p>
</li>
<li><em>Encountered exception</em>
<p>An exception was encountered trying to start the new web application.
Check the Tomcat logs for the details, but likely explanations include
problems parsing your <code>/WEB-INF/web.xml</code> file, or missing
classes encountered when initializing application event listeners and
filters.</p>
</li>
<li><em>Invalid application URL was specified</em>
<p>The URL for the <i>WAR or Directory URL:</i> field that you specified
was not valid. Such URLs must start with <code>file:</code>, and URLs
for a WAR file must end in ".war".</p>
</li>
<li><em>Invalid context path was specified</em>
<p>The context path must start with a slash character, unless you are
referencing the ROOT web application -- in which case the context path
must be a "/" string.</p>
</li>
<li><em>Context path must match the directory or WAR file name:</em>
<p>If the application war or directory is deployed in your Host appBase
directory and either the Host is configured with autoDeploy=true the Context
path must match the directory name or war file name without the ".war"
extension.</p>
</li>
<li><em>Only web applications in the Host web application directory can
be deployed</em>
<p>
If the Host deployXML flag is set to false this error will happen
if an attempt is made to install a web application directory or
".war" file outside of the Host appBase directory.
</p></li>
</ul>
</subsection>
</section>
<section name="Diagnostics">
<subsection name="Finding memory leaks">
<p><strong>The find leaks diagnostic triggers a full garbage collection. It
should be used with extreme caution on production systems.</strong></p>
<p>The find leaks diagnostic attempts to identify web applications that have
caused memory leaks when they were stopped, reloaded or undeployed. Results
should always be confirmed
with a profiler. The diagnostic uses additional functionality provided by the
StandardHost implementation. It will not work if a custom host is used that
does not extend StandardHost.</p>
<p>This diagnostic will list context paths for the web applications that were
stopped, reloaded or undeployed, but which classes from the previous runs
are still present in memory, thus being a memory leak. If an application
has been reloaded several times, it may be listed several times.</p>
<p>Explicitly triggering a full garbage collection from Java code is documented
to be unreliable. Furthermore, depending on the JVM used, there are options to
disable explicit GC triggering, like <code>-XX:+DisableExplicitGC</code>.
If you want to make sure, that the diagnostics were successfully running a full GC,
you will need to check using tools like GC logging, JConsole or similar.</p>
</subsection>
</section>
<section name="Server Information">
<p>This section displays information about Tomcat, the operating system of the
server Tomcat is hosted on, the Java Virtual Machine Tomcat is running in, the
primary host name of the server (may not be the host name used to access Tomcat)
and the primary IP address of the server (may not be the IP address used to
access Tomcat).</p>
</section>
</body>
</document>

BIN
webapps/docs/images/add.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.0 KiB

226
webapps/docs/images/asf-logo.svg Normal file
View File

@@ -0,0 +1,226 @@
<?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.
-->
<!-- Generator: Adobe Illustrator 19.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_2" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
viewBox="0 0 7127.6 2890" enable-background="new 0 0 7127.6 2890" xml:space="preserve">
<path fill="#6D6E71" d="M7104.7,847.8c15.3,15.3,22.9,33.7,22.9,55.2c0,21.5-7.6,39.9-22.9,55.4c-15.3,15.4-33.8,23.1-55.6,23.1
c-21.8,0-40.2-7.6-55.4-22.9c-15.1-15.3-22.7-33.7-22.7-55.2c0-21.5,7.6-39.9,22.9-55.4c15.3-15.4,33.7-23.1,55.4-23.1
C7070.9,824.9,7089.4,832.5,7104.7,847.8z M7098.1,951.9c13.3-13.6,20-29.8,20-48.7s-6.6-35-19.8-48.5
c-13.2-13.4-29.4-20.1-48.6-20.1c-19.2,0-35.4,6.7-48.7,20.2c-13.3,13.5-19.9,29.7-19.9,48.7c0,19,6.6,35.2,19.7,48.6
c13.1,13.4,29.3,20.1,48.5,20.1S7084.7,965.4,7098.1,951.9z M7087.1,888.1c0,14-6.1,22.8-18.4,26.4l22.5,30.5h-18.2l-20.3-28.3
h-18.6v28.3h-14.7v-84.6h31.8c12.8,0,22,2.2,27.6,6.6C7084.4,871.4,7087.1,878.4,7087.1,888.1z M7068.2,900c3-2.4,4.4-6.5,4.4-12
c0-5.5-1.5-9.4-4.5-11.6c-3-2.2-8.4-3.2-16-3.2h-18v30.5h17.5C7059.7,903.6,7065.3,902.4,7068.2,900z"/>
<path fill="#6D6E71" d="M1803.6,499.8v155.4h-20V499.8h-56.8v-19.2h133.9v19.2H1803.6z"/>
<path fill="#6D6E71" d="M2082.2,655.2v-76.9h-105.2v76.9h-20V480.5h20v78.9h105.2v-78.9h20v174.7H2082.2z"/>
<path fill="#6D6E71" d="M2241.4,499.8v57.4h88.1v19.2h-88.1v59.8h101.8v19h-121.8V480.5H2340v19.2H2241.4z"/>
<path fill="#D22128" d="M1574.5,1852.4l417.3-997.6h80.1l417.3,997.6h-105.4l-129.3-311.9h-448.2l-127.9,311.9H1574.5z M2032.6,970
l-205.1,493.2h404.7L2032.6,970z"/>
<path fill="#D22128" d="M2596.9,1852.4V854.8H3010c171.4,0,295.1,158.8,295.1,313.3c0,163-115.2,316.1-286.6,316.1h-324.6v368.1
H2596.9z M2693.9,1397.1h318.9c118,0,193.9-108.2,193.9-229c0-125.1-92.7-226.2-202.3-226.2h-310.5V1397.1z"/>
<path fill="#D22128" d="M3250.5,1852.4l417.3-997.6h80.1l417.3,997.6h-105.4l-129.3-311.9h-448.2l-127.9,311.9H3250.5z M3708.6,970
l-205.1,493.2h404.7L3708.6,970z"/>
<path fill="#D22128" d="M4637.3,849.1c177,0,306.3,89.9,368.1,217.8l-78.7,47.8c-63.2-132.1-186.9-177-295.1-177
c-238.9,0-369.5,213.6-369.5,414.5c0,220.6,161.6,420.1,373.7,420.1c112.4,0,244.5-56.2,307.7-185.5l81.5,42.1
c-64.6,148.9-241.7,231.8-394.8,231.8c-274,0-466.5-261.3-466.5-514.2C4163.8,1106.3,4336.6,849.1,4637.3,849.1z"/>
<path fill="#D22128" d="M5949.1,854.8v997.6h-98.4v-466.5h-591.5v466.5h-96.9V854.8h96.9v444h591.5v-444H5949.1z"/>
<path fill="#D22128" d="M6844.6,1765.2v87.1h-670.2V854.8H6832v87.1h-560.6v359.7h489v82.9h-489v380.8H6844.6z"/>
<path fill="#6D6E71" d="M1667.6,2063.6c11.8,3.5,22.2,8.3,31,14.2l-10.3,22.6c-9-6-18.6-10.4-28.9-13.4c-10.2-2.9-20-4.4-29.2-4.4
c-13.6,0-24.5,2.4-32.6,7.3c-8.1,4.9-12.2,11.8-12.2,20.7c0,7.6,2.3,14,6.8,19c4.5,5,10.2,8.9,17,11.7c6.8,2.8,16.1,6,28,9.6
c14.4,4.6,26,8.9,34.7,12.9c8.8,4,16.3,9.9,22.5,17.8c6.2,7.8,9.3,18.2,9.3,31c0,11.7-3.2,21.8-9.5,30.6
c-6.3,8.7-15.3,15.5-26.8,20.3c-11.6,4.8-24.9,7.2-40,7.2c-15.1,0-29.7-2.9-43.9-8.7c-14.2-5.8-26.4-13.6-36.6-23.4l10.7-21.6
c9.6,9.4,20.7,16.7,33.3,21.9c12.6,5.2,24.8,7.8,36.8,7.8c15.3,0,27.3-3,36.1-8.9c8.8-5.9,13.2-13.9,13.2-23.9
c0-7.8-2.3-14.3-6.9-19.4c-4.6-5.1-10.3-9-17.1-11.9c-6.8-2.8-16.1-6-28-9.6c-14.2-4.2-25.7-8.3-34.6-12.2
c-8.9-3.9-16.4-9.7-22.5-17.5c-6.1-7.7-9.2-17.9-9.2-30.6c0-10.9,3-20.4,9-28.6c6-8.2,14.6-14.6,25.6-19.1
c11.1-4.5,23.8-6.8,38.2-6.8C1643.8,2058.3,1655.7,2060.1,1667.6,2063.6z"/>
<path fill="#6D6E71" d="M1980.1,2072.8c16.8,9.4,30.2,22.3,40,38.4c9.8,16.2,14.8,33.9,14.8,53.3c0,19.5-4.9,37.4-14.8,53.6
c-9.8,16.3-23.2,29.1-40,38.6c-16.8,9.5-35.3,14.3-55.2,14.3c-20.3,0-38.8-4.7-55.7-14.3c-16.8-9.5-30.2-22.4-40-38.6
c-9.8-16.3-14.8-34.1-14.8-53.6c0-19.5,4.9-37.3,14.8-53.5c9.8-16.2,23.2-29,40-38.3c16.8-9.4,35.4-14,55.7-14
C1944.8,2058.6,1963.2,2063.3,1980.1,2072.8z M1881.9,2092.7c-13.1,7.4-23.6,17.5-31.4,30.1c-7.8,12.6-11.8,26.5-11.8,41.7
c0,15.3,3.9,29.3,11.8,42c7.8,12.7,18.3,22.8,31.4,30.2c13.1,7.4,27.4,11.1,42.9,11.1c15.5,0,29.7-3.7,42.7-11.1
c13-7.4,23.3-17.4,31.1-30.2c7.7-12.7,11.6-26.7,11.6-42s-3.9-29.2-11.6-41.8c-7.7-12.6-18.1-22.6-31.1-30
c-13-7.4-27.2-11.2-42.6-11.2C1909.4,2081.5,1895.1,2085.2,1881.9,2092.7z"/>
<path fill="#6D6E71" d="M2186.5,2082.4v74h98.4v23.2h-98.4v90.2h-24.1v-210.6h133.8v23.2H2186.5z"/>
<path fill="#6D6E71" d="M2491.6,2082.4v187.4h-24.1v-187.4h-68.4v-23.2h161.4v23.2H2491.6z"/>
<path fill="#6D6E71" d="M2871.8,2269.8l-56.8-177.4l-57.6,177.4h-24.5l-70.5-210.6h25.9l57.9,182.7l57.1-182.4l24.1-0.3l57.7,182.7
l57.1-182.7h25l-70.6,210.6H2871.8z"/>
<path fill="#6D6E71" d="M3087.3,2216.6l-23.5,53.2h-25.6l94.4-210.6h25l94.1,210.6h-26.1l-23.5-53.2H3087.3z M3144.5,2086.6
l-46.9,106.8h94.4L3144.5,2086.6z"/>
<path fill="#6D6E71" d="M3461.1,2202.7c-6,0.4-10.7,0.6-14.1,0.6h-56v66.5H3367v-210.6h80c26.2,0,46.6,6.2,61.2,18.5
c14.5,12.3,21.8,29.8,21.8,52.3c0,17.2-4.1,31.7-12.2,43.3c-8.1,11.6-19.8,20-35,25l49.2,71.5h-27.3L3461.1,2202.7z M3491.3,2167.6
c10.3-8.4,15.5-20.8,15.5-37c0-15.9-5.2-27.9-15.5-36c-10.3-8.1-25.1-12.2-44.3-12.2h-56v97.8h56
C3466.2,2180.2,3481,2176,3491.3,2167.6z"/>
<path fill="#6D6E71" d="M3688.3,2082.4v69.2h106.2v23.2h-106.2v72.1h122.8v22.9h-146.9v-210.6h142.9v23.2H3688.3z"/>
<path fill="#6D6E71" d="M4147,2082.4v74h98.4v23.2H4147v90.2h-24.1v-210.6h133.8v23.2H4147z"/>
<path fill="#6D6E71" d="M4523.3,2072.8c16.8,9.4,30.2,22.3,40,38.4c9.8,16.2,14.8,33.9,14.8,53.3c0,19.5-4.9,37.4-14.8,53.6
c-9.8,16.3-23.2,29.1-40,38.6c-16.8,9.5-35.3,14.3-55.2,14.3c-20.3,0-38.8-4.7-55.7-14.3c-16.8-9.5-30.2-22.4-40-38.6
c-9.8-16.3-14.8-34.1-14.8-53.6c0-19.5,4.9-37.3,14.8-53.5c9.8-16.2,23.2-29,40-38.3c16.8-9.4,35.4-14,55.7-14
C4488.1,2058.6,4506.5,2063.3,4523.3,2072.8z M4425.2,2092.7c-13.1,7.4-23.6,17.5-31.4,30.1c-7.8,12.6-11.8,26.5-11.8,41.7
c0,15.3,3.9,29.3,11.8,42c7.8,12.7,18.3,22.8,31.4,30.2c13.1,7.4,27.4,11.1,42.9,11.1c15.5,0,29.7-3.7,42.7-11.1
c13-7.4,23.3-17.4,31.1-30.2c7.7-12.7,11.6-26.7,11.6-42s-3.9-29.2-11.6-41.8c-7.7-12.6-18.1-22.6-31.1-30
c-13-7.4-27.2-11.2-42.6-11.2C4452.6,2081.5,4438.3,2085.2,4425.2,2092.7z"/>
<path fill="#6D6E71" d="M4854.7,2247.7c-15.7,15.5-37.3,23.3-64.8,23.3c-27.7,0-49.4-7.8-65.1-23.3c-15.7-15.5-23.6-37-23.6-64.6
v-124h24.1v124c0,20.3,5.8,36.1,17.3,47.5c11.6,11.4,27.3,17.1,47.3,17.1c20.1,0,35.8-5.7,47.1-17c11.4-11.3,17-27.2,17-47.7v-124
h24.1v124C4878.2,2210.7,4870.4,2232.2,4854.7,2247.7z"/>
<path fill="#6D6E71" d="M5169.5,2269.8l-126.3-169.1v169.1h-24.1v-210.6h25l126.3,169.3v-169.3h23.8v210.6H5169.5z"/>
<path fill="#6D6E71" d="M5478.4,2073.1c16.4,9.3,29.4,21.9,38.9,37.9c9.6,16,14.3,33.9,14.3,53.5s-4.8,37.6-14.3,53.6
c-9.5,16.1-22.6,28.7-39.3,37.9c-16.6,9.2-35.2,13.8-55.5,13.8h-84.3v-210.6h85.2C5443.7,2059.2,5462,2063.8,5478.4,2073.1z
M5362.3,2246.9h61.4c15.5,0,29.6-3.5,42.3-10.6c12.7-7.1,22.8-16.9,30.2-29.5c7.4-12.5,11.1-26.5,11.1-42
c0-15.5-3.8-29.4-11.3-41.9c-7.5-12.5-17.7-22.3-30.6-29.6c-12.8-7.2-27-10.9-42.6-10.9h-60.5V2246.9z"/>
<path fill="#6D6E71" d="M5668.6,2216.6l-23.5,53.2h-25.6l94.4-210.6h25l94.1,210.6H5807l-23.5-53.2H5668.6z M5725.8,2086.6
l-46.9,106.8h94.4L5725.8,2086.6z"/>
<path fill="#6D6E71" d="M5991,2082.4v187.4H5967v-187.4h-68.4v-23.2h161.4v23.2H5991z"/>
<path fill="#6D6E71" d="M6175.9,2269.8v-210.6h24.1v210.6H6175.9z"/>
<path fill="#6D6E71" d="M6493.7,2072.8c16.8,9.4,30.2,22.3,40,38.4c9.8,16.2,14.8,33.9,14.8,53.3c0,19.5-4.9,37.4-14.8,53.6
c-9.8,16.3-23.2,29.1-40,38.6c-16.8,9.5-35.3,14.3-55.2,14.3c-20.3,0-38.8-4.7-55.7-14.3c-16.8-9.5-30.2-22.4-40-38.6
c-9.8-16.3-14.8-34.1-14.8-53.6c0-19.5,4.9-37.3,14.8-53.5c9.8-16.2,23.2-29,40-38.3c16.8-9.4,35.4-14,55.7-14
C6458.5,2058.6,6476.9,2063.3,6493.7,2072.8z M6395.6,2092.7c-13.1,7.4-23.6,17.5-31.4,30.1c-7.8,12.6-11.8,26.5-11.8,41.7
c0,15.3,3.9,29.3,11.8,42c7.8,12.7,18.3,22.8,31.4,30.2c13.1,7.4,27.4,11.1,42.9,11.1c15.5,0,29.7-3.7,42.7-11.1
c13-7.4,23.3-17.4,31.1-30.2c7.7-12.7,11.6-26.7,11.6-42s-3.9-29.2-11.6-41.8c-7.7-12.6-18.1-22.6-31.1-30
c-13-7.4-27.2-11.2-42.6-11.2C6423,2081.5,6408.8,2085.2,6395.6,2092.7z"/>
<path fill="#6D6E71" d="M6826.5,2269.8l-126.3-169.1v169.1h-24.1v-210.6h25l126.3,169.3v-169.3h23.8v210.6H6826.5z"/>
<linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="-4516.6152" y1="-2338.7222" x2="-4108.4111" y2="-1861.3982" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0" style="stop-color:#F69923"/>
<stop offset="0.3123" style="stop-color:#F79A23"/>
<stop offset="0.8383" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_1_)" d="M1230.1,13.7c-45.3,26.8-120.6,102.5-210.5,212.3l82.6,155.9c58-82.9,116.9-157.5,176.3-221.2
c4.6-5.1,7-7.5,7-7.5c-2.3,2.5-4.6,5-7,7.5c-19.2,21.2-77.5,89.2-165.5,224.4c84.7-4.2,214.9-21.6,321.1-39.7
c31.6-177-31-258-31-258S1323.4-41.4,1230.1,13.7z"/>
<path fill="none" d="M1090.2,903.1c0.6-0.1,1.2-0.2,1.8-0.3l-11.9,1.3c-0.7,0.3-1.4,0.7-2.1,1
C1082.1,904.4,1086.2,903.7,1090.2,903.1z"/>
<path fill="none" d="M1005.9,1182.3c-6.7,1.5-13.7,2.7-20.7,3.7C992.3,1185,999.2,1183.8,1005.9,1182.3z"/>
<path fill="none" d="M432.9,1808.8c0.9-2.3,1.8-4.7,2.6-7c18.2-48,36.2-94.7,54-140.1c20-51,39.8-100.4,59.3-148.3
c20.6-50.4,40.9-99.2,60.9-146.3c21-49.4,41.7-97,62-142.8c16.5-37.3,32.8-73.4,48.9-108.3c5.4-11.7,10.7-23.2,16-34.6
c10.5-22.7,21-44.8,31.3-66.5c9.5-20,19-39.6,28.3-58.8c3.1-6.4,6.2-12.8,9.3-19.1c0.5-1,1-2,1.5-3.1l-10.2,1.1l-8-15.9
c-0.8,1.6-1.6,3.1-2.4,4.6c-14.5,28.8-28.9,57.9-43.1,87.2c-8.2,16.9-16.4,34-24.6,51c-22.6,47.4-44.8,95.2-66.6,143.3
c-22.1,48.6-43.7,97.5-64.9,146.5c-20.8,48.1-41.3,96.2-61.2,144.2c-20,48-39.5,95.7-58.5,143.2c-19.9,49.5-39.2,98.7-58,147.2
c-4.2,10.9-8.5,21.9-12.7,32.8c-15,39.2-29.7,77.8-44,116l12.7,25.1l11.4-1.2c0.4-1.1,0.8-2.3,1.3-3.4
C396.7,1905.4,414.9,1856.4,432.9,1808.8z"/>
<path fill="none" d="M980,1186.8L980,1186.8c0.1,0,0.1,0,0.1-0.1C980.1,1186.8,980.1,1186.8,980,1186.8z"/>
<path fill="#BE202E" d="M952.6,1323c-10.6,1.9-21.4,3.8-32.5,5.7c-0.1,0-0.1,0.1-0.2,0.1c5.6-0.8,11.2-1.7,16.6-2.6
C942,1325.2,947.3,1324.1,952.6,1323z"/>
<path opacity="0.35" fill="#BE202E" d="M952.6,1323c-10.6,1.9-21.4,3.8-32.5,5.7c-0.1,0-0.1,0.1-0.2,0.1c5.6-0.8,11.2-1.7,16.6-2.6
C942,1325.2,947.3,1324.1,952.6,1323z"/>
<path fill="#BE202E" d="M980.3,1186.7C980.2,1186.7,980.2,1186.7,980.3,1186.7c-0.1,0.1-0.2,0.1-0.2,0.1c1.8-0.2,3.5-0.5,5.2-0.8
c7-1,13.9-2.2,20.7-3.7C997.5,1183.8,989,1185.2,980.3,1186.7L980.3,1186.7L980.3,1186.7z"/>
<path opacity="0.35" fill="#BE202E" d="M980.3,1186.7C980.2,1186.7,980.2,1186.7,980.3,1186.7c-0.1,0.1-0.2,0.1-0.2,0.1
c1.8-0.2,3.5-0.5,5.2-0.8c7-1,13.9-2.2,20.7-3.7C997.5,1183.8,989,1185.2,980.3,1186.7L980.3,1186.7L980.3,1186.7z"/>
<linearGradient id="SVGID_2_" gradientUnits="userSpaceOnUse" x1="-7537.7339" y1="-2391.4075" x2="-4625.4141" y2="-2391.4075" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_2_)" d="M858.6,784.7c25.1-46.9,50.5-92.8,76.2-137.4c26.7-46.4,53.7-91.3,80.9-134.7
c1.6-2.6,3.2-5.2,4.8-7.7c27-42.7,54.2-83.7,81.6-122.9L1019.5,226c-6.2,7.6-12.5,15.3-18.8,23.2c-23.8,29.7-48.6,61.6-73.9,95.5
c-28.6,38.2-58,78.9-87.8,121.7c-27.6,39.5-55.5,80.9-83.5,123.7c-23.8,36.5-47.7,74-71.4,112.5c-0.9,1.4-1.8,2.9-2.6,4.3
l107.5,212.3C811.8,873.6,835.1,828.7,858.6,784.7z"/>
<linearGradient id="SVGID_3_" gradientUnits="userSpaceOnUse" x1="-7186.1777" y1="-2099.3059" x2="-5450.7183" y2="-2099.3059" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0" style="stop-color:#282662"/>
<stop offset="9.548390e-02" style="stop-color:#662E8D"/>
<stop offset="0.7882" style="stop-color:#9F2064"/>
<stop offset="0.9487" style="stop-color:#CD2032"/>
</linearGradient>
<path fill="url(#SVGID_3_)" d="M369,1981c-14.2,39.1-28.5,78.9-42.9,119.6c-0.2,0.6-0.4,1.2-0.6,1.8c-2,5.7-4.1,11.5-6.1,17.2
c-9.7,27.4-18,52.1-37.3,108.2c31.7,14.5,57.1,52.5,81.1,95.6c-2.6-44.7-21-86.6-56.2-119.1c156.1,7,290.6-32.4,360.1-146.6
c6.2-10.2,11.9-20.9,17-32.2c-31.6,40.1-70.8,57.1-144.5,53c-0.2,0.1-0.3,0.1-0.5,0.2c0.2-0.1,0.3-0.1,0.5-0.2
c108.6-48.6,163.1-95.3,211.2-172.6c11.4-18.3,22.5-38.4,33.8-60.6c-94.9,97.5-205,125.3-320.9,104.2l-86.9,9.5
C374.4,1966.3,371.7,1973.6,369,1981z"/>
<linearGradient id="SVGID_4_" gradientUnits="userSpaceOnUse" x1="-7374.1626" y1="-2418.5454" x2="-4461.8428" y2="-2418.5454" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_4_)" d="M409.6,1786.3c18.8-48.5,38.1-97.7,58-147.2c19-47.4,38.5-95.2,58.5-143.2
c20-48,40.4-96.1,61.2-144.2c21.2-49,42.9-97.8,64.9-146.5c21.8-48.1,44-95.9,66.6-143.3c8.1-17.1,16.3-34.1,24.6-51
c14.2-29.3,28.6-58.4,43.1-87.2c0.8-1.6,1.6-3.1,2.4-4.6L681.4,706.8c-1.8,2.9-3.5,5.8-5.3,8.6c-25.1,40.9-50,82.7-74.4,125.4
c-24.7,43.1-49,87.1-72.7,131.7c-20,37.6-39.6,75.6-58.6,113.9c-3.8,7.8-7.6,15.5-11.3,23.2c-23.4,48.2-44.6,94.8-63.7,139.5
c-21.7,50.7-40.7,99.2-57.5,145.1c-11,30.2-21,59.4-30.1,87.4c-7.5,24-14.7,47.9-21.5,71.8c-16,56.3-29.9,112.4-41.2,168.3
L353,1935.1c14.3-38.1,28.9-76.8,44-116C401.1,1808.2,405.4,1797.3,409.6,1786.3z"/>
<linearGradient id="SVGID_5_" gradientUnits="userSpaceOnUse" x1="-7161.7642" y1="-2379.1431" x2="-5631.2524" y2="-2379.1431" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0" style="stop-color:#282662"/>
<stop offset="9.548390e-02" style="stop-color:#662E8D"/>
<stop offset="0.7882" style="stop-color:#9F2064"/>
<stop offset="0.9487" style="stop-color:#CD2032"/>
</linearGradient>
<path fill="url(#SVGID_5_)" d="M243.5,1729.4c-13.6,68.2-23.2,136.2-28,203.8c-0.2,2.4-0.4,4.7-0.5,7.1
c-33.7-54-124-106.8-123.8-106.2c64.6,93.7,113.7,186.7,120.9,278c-34.6,7.1-82-3.2-136.8-23.3c57.1,52.5,100,67,116.7,70.9
c-52.5,3.3-107.1,39.3-162.1,80.8c80.5-32.8,145.5-45.8,192.1-35.3C148.1,2414.2,74.1,2645,0,2890c22.7-6.7,36.2-21.9,43.9-42.6
c13.2-44.4,100.8-335.6,238-718.2c3.9-10.9,7.8-21.8,11.8-32.9c1.1-3,2.2-6.1,3.3-9.2c14.5-40.1,29.5-81.1,45.1-122.9
c3.5-9.5,7.1-19,10.7-28.6c0.1-0.2,0.1-0.4,0.2-0.6l-107.9-213.2C244.6,1724.4,244,1726.9,243.5,1729.4z"/>
<linearGradient id="SVGID_6_" gradientUnits="userSpaceOnUse" x1="-7374.1626" y1="-2117.1309" x2="-4461.8428" y2="-2117.1309" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_6_)" d="M805.6,937c-3.1,6.3-6.2,12.7-9.3,19.1c-9.3,19.2-18.8,38.8-28.3,58.8
c-10.3,21.7-20.7,43.9-31.3,66.5c-5.3,11.4-10.6,22.9-16,34.6c-16.1,35-32.4,71.1-48.9,108.3c-20.3,45.8-41,93.4-62,142.8
c-20,47.1-40.3,95.9-60.9,146.3c-19.5,47.9-39.3,97.3-59.3,148.3c-17.8,45.4-35.9,92.1-54,140.1c-0.9,2.3-1.8,4.7-2.6,7
c-18,47.6-36.2,96.6-54.6,146.8c-0.4,1.1-0.8,2.3-1.3,3.4l86.9-9.5c-1.7-0.3-3.5-0.5-5.2-0.9c103.9-13,242.1-90.6,331.4-186.5
c41.1-44.2,78.5-96.3,113-157.3c25.7-45.4,49.8-95.8,72.8-151.5c20.1-48.7,39.4-101.4,58-158.6c-23.9,12.6-51.2,21.8-81.4,28.2
c-5.3,1.1-10.7,2.2-16.1,3.1c-5.5,1-11,1.8-16.6,2.6l0,0l0,0c0.1,0,0.1-0.1,0.2-0.1c96.9-37.3,158-109.2,202.4-197.4
c-25.5,17.4-66.9,40.1-116.6,51.1c-6.7,1.5-13.7,2.7-20.7,3.7c-1.7,0.3-3.5,0.6-5.2,0.8l0,0l0,0c0.1,0,0.1,0,0.1-0.1
c0,0,0.1,0,0.1,0l0,0c33.6-14.1,62-29.8,86.6-48.4c5.3-4,10.4-8.1,15.3-12.3c7.5-6.5,14.7-13.3,21.5-20.5c4.4-4.6,8.6-9.3,12.7-14.2
c9.6-11.5,18.7-23.9,27.1-37.3c2.6-4.1,5.1-8.3,7.6-12.6c3.2-6.2,6.3-12.3,9.3-18.3c13.5-27.2,24.4-51.5,33-72.8
c4.3-10.6,8.1-20.5,11.3-29.7c1.3-3.7,2.5-7.2,3.7-10.6c3.4-10.2,6.2-19.3,8.4-27.3c3.3-12,5.3-21.5,6.4-28.4l0,0l0,0
c-3.3,2.6-7.1,5.2-11.3,7.7c-29.3,17.5-79.5,33.4-119.9,40.8l79.8-8.8l-79.8,8.8c-0.6,0.1-1.2,0.2-1.8,0.3c-4,0.7-8.1,1.3-12.2,2
c0.7-0.3,1.4-0.7,2.1-1l-273,29.9C806.6,935,806.1,936,805.6,937z"/>
<linearGradient id="SVGID_7_" gradientUnits="userSpaceOnUse" x1="-7554.8232" y1="-2132.0981" x2="-4642.5034" y2="-2132.0981" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_7_)" d="M1112.9,385.1c-24.3,37.3-50.8,79.6-79.4,127.5c-1.5,2.5-3,5.1-4.5,7.6
c-24.6,41.5-50.8,87.1-78.3,137c-23.8,43.1-48.5,89.3-74.3,139c-22.4,43.3-45.6,89.2-69.4,137.8l273-29.9
c79.5-36.6,115.1-69.7,149.6-117.6c9.2-13.2,18.4-27,27.5-41.3c28-43.8,55.6-92,80.1-139.9c23.7-46.3,44.7-92.2,60.7-133.5
c10.2-26.3,18.4-50.8,24.1-72.3c5-19,8.9-36.9,11.9-54.1C1327.9,363.5,1197.6,380.9,1112.9,385.1z"/>
<path fill="#BE202E" d="M936.5,1326.1c-5.5,1-11,1.8-16.6,2.6l0,0C925.5,1328,931,1327.1,936.5,1326.1z"/>
<path opacity="0.35" fill="#BE202E" d="M936.5,1326.1c-5.5,1-11,1.8-16.6,2.6l0,0C925.5,1328,931,1327.1,936.5,1326.1z"/>
<linearGradient id="SVGID_8_" gradientUnits="userSpaceOnUse" x1="-7374.1626" y1="-2027.484" x2="-4461.8433" y2="-2027.484" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_8_)" d="M936.5,1326.1c-5.5,1-11,1.8-16.6,2.6l0,0C925.5,1328,931,1327.1,936.5,1326.1z"/>
<path fill="#BE202E" d="M980,1186.8c1.8-0.2,3.5-0.5,5.2-0.8C983.5,1186.3,981.8,1186.6,980,1186.8L980,1186.8z"/>
<path opacity="0.35" fill="#BE202E" d="M980,1186.8c1.8-0.2,3.5-0.5,5.2-0.8C983.5,1186.3,981.8,1186.6,980,1186.8L980,1186.8z"/>
<linearGradient id="SVGID_9_" gradientUnits="userSpaceOnUse" x1="-7374.1626" y1="-2037.7417" x2="-4461.8433" y2="-2037.7417" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_9_)" d="M980,1186.8c1.8-0.2,3.5-0.5,5.2-0.8C983.5,1186.3,981.8,1186.6,980,1186.8L980,1186.8z"/>
<path fill="#BE202E" d="M980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7L980.2,1186.7L980.2,1186.7L980.2,1186.7
C980.2,1186.7,980.2,1186.7,980.2,1186.7z"/>
<path opacity="0.35" fill="#BE202E" d="M980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7L980.2,1186.7L980.2,1186.7
L980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7z"/>
<linearGradient id="SVGID_10_" gradientUnits="userSpaceOnUse" x1="-5738.0635" y1="-2039.799" x2="-5094.3457" y2="-2039.799" gradientTransform="matrix(0.4226 -0.9063 0.9063 0.4226 5117.8774 -2859.9343)">
<stop offset="0.3233" style="stop-color:#9E2064"/>
<stop offset="0.6302" style="stop-color:#C92037"/>
<stop offset="0.7514" style="stop-color:#CD2335"/>
<stop offset="1" style="stop-color:#E97826"/>
</linearGradient>
<path fill="url(#SVGID_10_)" d="M980.2,1186.7C980.2,1186.7,980.2,1186.7,980.2,1186.7L980.2,1186.7L980.2,1186.7L980.2,1186.7
C980.2,1186.7,980.2,1186.7,980.2,1186.7z"/>
</svg>

BIN
webapps/docs/images/code.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 394 B

BIN
webapps/docs/images/cors-flowchart.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 84 KiB

BIN
webapps/docs/images/design.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 608 B

Some files were not shown because too many files have changed in this diff Show More