<section name="Shared Library Files">
-<p>Like most servlet containers, Tomcat 6 also supports mechanisms to install
+<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 6 installation for shared code is
+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 6 installation includes a variety
+<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.0</em> and <em>JSP 2.1</em> APIs that are fundamental
<p><strong>NOTE</strong> - The Servlet Specification includes a Document
Type Descriptor (DTD) for the web application deployment descriptor, and
-Tomcat 6 enforces the rules defined here when processing your application's
+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><filter></code>,
<code><servlet></code>, and <code><servlet-mapping></code> in
</section>
-<section name="Deployment With Tomcat 6">
+<section name="Deployment With Tomcat">
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
<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 6 to provide the execution environment.
+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>
directory that Tomcat created, and then restart Tomcat, in order to reflect
your changes.
<br/><br/></li>
-<li><em>Use the Tomcat 6 "Manager" web application to deploy and undeploy
- web applications</em>. Tomcat 6 includes a web application, deployed
+<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 the administrator documentation (TODO: hyperlink)
for more information on using the Manager web application.<br/><br/></li>
-<li><em>Use "Manager" Ant Tasks In Your Build Script</em>. Tomcat 6
+<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 6 includes a packaged tool
+<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>
<section name="Installation">
-<p>In order to use Tomcat 6 for developing web applications, you must first
+<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>
<p>Binary downloads of the <strong>Tomcat</strong> server are available from
<a href="http://tomcat.apache.org/download-60.cgi">http://tomcat.apache.org/download-60.cgi</a>.
This manual assumes you are using the most recent release
-of Tomcat 6. Detailed instructions for downloading and installing
-Tomcat
6 are available <a href="../setup.html">here</a>.</p>
+of Tomcat 7. 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 6 has been installed. Optionally, if
+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>
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 6 is installed, and the manager application username and password.
+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
the sample <code>build.xml</code> script. Using these commands might follow
a pattern like this:</p>
<ul>
-<li><em>Start Tomcat 6 if needed</em>. If Tomcat 6 is not already running,
+<li><em>Start Tomcat if needed</em>. If Tomcat is not already running,
you will need to start it in the usual way.
<br/><br/></li>
<li><em>Compile your application</em>. Use the <code>ant compile</code>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
<p>A key recommendation of this manual is to separate the directory
<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 6 allows you to deploy an application in an unpacked
+ 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
"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 Tomcat 6's <code>lib</code> directory.
+ 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>
</ul>
<p>For interactive development and testing of your web application using
-Tomcat 6, the following additional targets are defined:</p>
+Tomcat, the following additional targets are defined:</p>
<ul>
-<li><strong>install</strong> - Tell the currently running Tomcat 6 to make
+<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 6 to be restarted, but
+ 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 6 will automatically recognize changes made to JSP pages,
+ 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 6 to remove this
+ testing activities, you can optionally tell Tomcat to remove this
application from service.
</li>
</ul>
<section name="Overview">
-<p>Like many server applications, Tomcat 6 installs a variety of class loaders
+<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
web application class loaders differs slightly from this, as discussed below,
but the main principles are the same.</p>
-<p>When Tomcat 6 is started, it creates a set of class loaders that are
+<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>
<section name="Class Loader Definitions">
-<p>As indicated in the diagram above, Tomcat 6 creates the following class
+<p>As indicated in the diagram above, Tomcat creates the following class
loaders as it is initialized:</p>
<ul>
<li><strong>Bootstrap</strong> - This class loader contains the basic runtime
<li><strong>System</strong> - 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 6 startup scripts
+ 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:
<ul>
<li><em>$CATALINA_HOME/bin/bootstrap.jar</em> - Contains the main() method
- that is used to initialize the Tomcat 6 server, and the class loader
+ that is used to initialize the Tomcat server, and the class loader
implementation classes it depends on.</li>
<li><em>$CATALINA_HOME/bin/tomcat-juli.jar</em> - Package renamed Commons
logging API, and java.util.logging LogManager.</li>
<ul>
<li><em>annotations-api.jar</em> - JEE annotations classes.</li>
<li><em>catalina.jar</em> - Implementation of the Catalina servlet
- container portion of Tomcat 6.</li>
+ container portion of Tomcat.</li>
<li><em>catalina-ant.jar</em> - Tomcat Catalina Ant tasks.</li>
<li><em>catalina-ha.jar</em> - High availability package.</li>
<li><em>catalina-tribes.jar</em> - Group communication package.</li>
of messages is needed.</li>
</ul></li>
<li><strong>WebappX</strong> - A class loader is created for each web
- application that is deployed in a single Tomcat 6 instance. All unpacked
+ 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 archive, plus classes and resources in JAR files
under the <code>/WEB-INF/lib</code> directory of your web application
used.
Last, any JAR containing servlet API classes will be ignored by the
classloader.
-All other class loaders in Tomcat 6 follow the usual delegation pattern.</p>
+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>
<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 6 (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li>
+ <li>Using in-memory-replication, using the SimpleTcpCluster that ships with Tomcat (lib/catalina-tribes.jar + lib/catalina-ha.jar)</li>
</ol>
<p>In this release of session replication, Tomcat can perform an all-to-all replication of session state using the <code>DeltaManager</code> or
<p>
This is a template for the manager configuration that will be used if no manager is defined in the <Context>
element. In Tomcat 5.x each webapp marked distributable had to use the same manager, this is no longer the case
- since Tomcat 6 you can define a manager class for each webapp, so that you can mix managers in your cluster.
+ 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 <distributable/> Tomcat will take this manager configuration
and create a manager instance cloning this configuration.
<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 6 into an existing (or new)
+ 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>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
<p>The <strong>Context</strong> element represents a <em>web
web application for this virtual host, and is used to process all
requests that do not match any other Context's context path.</p>
- <p><b>For Tomcat 6, unlike Tomcat 4.x, it is NOT recommended to place
+ <p><b>For the current versions of Tomcat, unlike Tomcat 4.x,
+ it is NOT recommended to place
<Context> elements directly in the server.xml file.</b> This
is because it makes modifying the <strong>Context</strong> configuration
more invasive since the main <code>conf/server.xml</code> file cannot be
<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 6 servers which participate in the cluster, will be appended to
+ 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 6
+ proxy to always forward a particular session to the same Tomcat
instance.</p>
</attribute>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
</section>
<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 6 Servlet/JSP container. It does not
+configure the behavior of the Tomcat 7 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>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
</section>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
</section>
<h3>JAAS Realm (org.apache.catalina.realm.JAASRealm)</h3>
- <p><strong>JAASRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>JAASRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that authenticates users through the Java
Authentication & Authorization Service (JAAS) framework which is now
provided as part of the standard J2SE API.</p>
<h3>Combined Realm (org.apache.catalina.realm.CombinedRealm)</h3>
- <p><strong>CombinedRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that authenticates users through one or more
sub-Realms.</p>
<h3>LockOut Realm (org.apache.catalina.realm.LockOutRealm)</h3>
- <p><strong>LockOutRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that extends the CombinedRealm to provide lock
out functionality to provide a user lock out mechanism if there are too many
failed authentication attempts in a given period of time.</p>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
</section>
<section name="Downloading">
<p>
- To down load the extras components open the Tomcat 6 download page and
- select browse from the Quick Navigation Links. The extras components can be
+ To download the extras components open the Tomcat download page and
+ select "browse" from the Quick Navigation Links. The extras components can be
found in bin/extras.
</p>
</section>
<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 6 container. A variety of <em>Access Methods</em>
+ 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>
<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 6 itself runs.</li>
+ 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
<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:</p>
+ 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://java.sun.com/j2se/">Java 2 Standard Edition</a>
(Version 1.2 or later)</li>
<li><a href="http://www.jcp.org/jsr/detail/154.jsp">Servlet 2.4</a>
- (supported natively by Tomcat 6)</li>
+ (supported natively by Tomcat 5)</li>
<li><a href="http://www.jcp.org/jsr/detail/152.jsp">JavaServer Pages 2.0</a>
- (supported natively by Tomcat 6)</li>
+ (supported natively by Tomcat 5)</li>
<li><a href="http://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="http://struts.apache.org/">Struts Framework</a>
(Version 1.0) - MVC Framework for Web Applications</li>
<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 6 administrative applications.
+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>
<subsection name="Introduction">
<p>The purpose of the <strong>JDBCRealm</strong> implementation is to
- provide a mechanism by which Tomcat 6 can acquire information needed
+ 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
<subsection name="Introduction">
<p>The purpose of the <strong>JNDIRealm</strong> implementation is to
- provide a mechanism by which Tomcat 6 can acquire information needed
+ 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
<subsection name="Introduction">
<p>The purpose of the <strong>MemoryRealm</strong> implementation is to
- provide a mechanism by which Tomcat 6 can acquire information needed
+ 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 6,
+ 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 documentation area includes <em>functional specifications</em> for
many features supported by the <strong>Catalina</strong> servlet container
-portion of Tomcat 6. In most cases, these features are not documented in the
+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>
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 6 installation through tools,
+ 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 6 distribution.</li>
+ standard Tomcat distribution.</li>
</ul>
<p><em>NOTE</em> - In some cases, the contents of these functional specs has
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to start the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to stop the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to restart the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to start the new web application.
- Check the Tomcat 6 logs for the details, but likely explanations include
+ 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>
<section name="Apache Tomcat User Guide">
<p>The following documents will assist you in downloading, installing
-Apache Tomcat 6, and using many of the Apache Tomcat features.</p>
+Apache Tomcat 7, and using many of the Apache Tomcat features.</p>
<ol>
<li><a href="introduction.html"><strong>Introduction</strong></a> - A
- Configuring a JNDI DataSoure with a DB connection pool.
Examples for many popular databases.</li>
<li><a href="class-loader-howto.html"><strong>Classloading</strong></a>
- - Information about class loading in Apache Tomcat 6, including where to place
+ - Information about class loading in Apache Tomcat, including where to place
your application classes so that they are visible.</li>
<li><a href="jasper-howto.html"><strong>JSPs</strong></a>
- Information about Jasper configuration, as well as the JSP compiler
<li><a href="cgi-howto.html"><strong>CGI</strong></a> -
Using CGIs with Apache Tomcat.</li>
<li><a href="proxy-howto.html"><strong>Proxy Support</strong></a> -
- Configuring Apache Tomcat 6 to run behind a proxy server (or a web server
+ Configuring Apache Tomcat to run behind a proxy server (or a web server
functioning as a proxy server).</li>
<li><a href="mbeans-descriptor-howto.html"><strong>MBean Descriptor</strong></a> -
Configuring MBean descriptors files for custom components.</li>
<section name="Reference">
<p>The following documents are aimed at <em>System Administrators</em> who
-are responsible for installing, configuring, and operating a Apache Tomcat 6 server.
+are responsible for installing, configuring, and operating an Apache Tomcat server.
</p>
<ul>
<li><a href="RELEASE-NOTES.txt"><strong>Release notes</strong></a>
</li>
<li><a href="config/index.html"><strong>Apache Tomcat Server Configuration Reference</strong></a>
- Reference manual that documents all available elements and attributes
- that may be placed into a Apache Tomcat 6 <code>conf/server.xml</code> file.
+ that may be placed into the Apache Tomcat <code>conf/server.xml</code> file.
</li>
<li><a href="http://tomcat.apache.org/connectors-doc/index.html"><strong>JK Documentation</strong></a>
- Complete documentation and HOWTOs on the JK native webserver connector,
the development of the <em>Apache Tomcat</em> project.</p>
<ul>
<li><a href="building.html"><strong>Building from Source</strong></a> -
- Details the steps necessary to download Apache Tomcat 6 source code (and the
+ Details the steps necessary to download Apache Tomcat source code (and the
other packages that it depends on), and build a binary distribution from
those sources.
</li>
</li>
<li><a href="funcspecs/index.html"><strong>Functional Specifications</strong></a>
- Requirements specifications for features of the <em>Catalina</em> servlet
- container portion of Apache Tomcat 6.</li>
+ container portion of Apache Tomcat.</li>
<li><a href="api/index.html"><strong>Javadocs</strong></a>
- Javadoc API documentation for Apache Tomcat's internals.</li>
<li><a href="architecture/index.html"><strong>Apache Tomcat Architecture</strong></a>
written and easy to understand, we may have missed something. Provided
below are various web sites and mailing lists in case you get stuck.</p>
-<p>As Tomcat 6 is a new release of Tomcat, keep in mind that some of the
-issues and solutions vary between the major versions of Tomcat (4.x versus
-5). As you search around the web, there will be some documentation that
-is not relevant to Tomcat 6, but 3.x, 4.x and 5.x. Doing 3.x or 4.x things to 6
-will probably not work in most cases as the server.xml files are very
-different.</p>
+<p>As Tomcat 7 is a new release of Tomcat, keep in mind that some of the
+issues and solutions vary between the major versions of Tomcat (6.x versus
+7.x). As you search around the web, there will be some documentation that
+is not relevant to Tomcat 7, but 6.x, 5.x or earlier versions. Doing 3.x
+or 4.x things to 7 will probably not work in most cases as the server.xml
+files are very different.</p>
<ul>
<li>Current document - most documents will list potential hangups. Be sure
to fully read the relevant documentation as it will save you much time
and effort. There's nothing like scouring the web only to find out that
the answer was right in front of you all along!</li>
-<li><a href="http://wiki.apache.org/tomcat/FAQ">Tomcat FAQ</a> as maintained by the developers.</li>
+<li><a href="http://wiki.apache.org/tomcat/FAQ">Tomcat FAQ</a></li>
<li><a href="http://wiki.apache.org/tomcat/">Tomcat WIKI</a></li>
<li>Tomcat FAQ at <a href="http://www.jguru.com/faq/home.jsp?topic=Tomcat">jGuru</a></li>
<li>Tomcat mailing list archives - numerous sites archive the Tomcat mailing
</ul>
<p>And, if you think something should be in the docs, by all means let us know
-on the TOMCAT-DEV list, or send one of the doc authors email.</p>
+on the TOMCAT-DEV list.</p>
</section>
<section name="Introduction">
-<p>Tomcat 6 provides a JNDI <strong>InitialContext</strong> implementation
+<p>Tomcat provides a JNDI <strong>InitialContext</strong> implementation
instance for each web application running under it, in a manner that is
compatible with those provided by a
<a href="http://java.sun.com/j2ee">Java2 Enterprise Edition</a> application
<li><code><strong><resource-ref></strong></code> - Resource reference,
which is typically to an object factory for resources such as a JDBC
<code>DataSource</code>, a JavaMail <code>Session</code>, or custom
- object factories configured into Tomcat 6.</li>
+ object factories configured into Tomcat.</li>
<li><code><strong><resource-env-ref></strong></code> - Resource
environment reference, a new variation of <code>resource-ref</code>
added in Servlet 2.4 that is simpler to configure for resources
<section name="Global configuration">
-<p>Tomcat 6 maintains a separate namespace of global resources for the
+<p>Tomcat maintains a separate namespace of global resources for the
entire server. These are configured in the
<a href="config/globalresources.html">
<code><strong><GlobalNameingResources></strong></code></a> element of
<section name="Tomcat Standard Resource Factories">
- <p>Tomcat 6 includes a series of standard resource factories that can
+ <p>Tomcat includes a series of standard resource factories that can
provide services to your web applications, but give you configuration
flexibility (via the
<a href="config/context.html"><code><Context></code></a> element)
<p>See <a href="#Adding Custom Resource Factories">Adding Custom
Resource Factories</a> for information about how to create, install,
configure, and use your own custom resource factory classes with
- Tomcat 6.</p>
+ Tomcat.</p>
<p><em>NOTE</em> - Of the standard resource factories, only the
"JDBC Data Source" and "User Transaction" factories are mandated to
configuration details that the client application must be aware of
(including the name of the SMTP host to be used for message sending).</p>
- <p>Tomcat 6 includes a standard resource factory that will create
+ <p>Tomcat includes a standard resource factory that will create
<code>javax.mail.Session</code> session instances for you, already
configured to connect to an SMTP server.
In this way, the application is totally insulated from changes in the
to support the functionality required by that application. The J2EE
Platform Specification requires J2EE Application Servers to make
available a <em>DataSource</em> implementation (that is, a connection
- pool for JDBC connections) for this purpose. Tomcat 6 offers exactly
+ pool for JDBC connections) for this purpose. Tomcat offers exactly
the same support, so that database-based applications you develop on
Tomcat using this service will run unchanged on any J2EE server.</p>
<section name="Adding Custom Resource Factories">
<p>If none of the standard resource factories meet your needs, you can write
- your own factory and integrate it into Tomcat 6, and then configure the use
+ your own factory and integrate it into Tomcat, and then configure the use
of this factory in the
<a href="config/context.html"><code><Context></code></a> element for
the web application. In the example below, we will create a factory that only
to deploy a new web application, or undeploy an existing one, without having
to shut down and restart the entire container. In addition, you can request
an existing application to reload itself, even if you have not declared it
-to be <code>reloadable</code> in the Tomcat 6 server
+to be <code>reloadable</code> in the Tomcat server
configuration file.</p>
-<p>To support these capabilities, Tomcat 6 includes a web application
+<p>To support these capabilities, Tomcat includes a web application
(installed by default on context path <code>/manager</code>) that supports
the following functions:</p>
<ul>
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
<p>It would be quite unsafe to ship Tomcat with default settings that allowed
<ul>
<li><em>MemoryRealm</em> - If you have not customized your
<code>$CATALINA_BASE/conf/server.xml</code> to select a different one,
- Tomcat 6 defaults to an XML-format file stored at
+ Tomcat defaults to an XML-format file stored at
<code>$CATALINA_BASE/conf/tomcat-users.xml</code>, which can be
edited with any text editor. This file contains an XML
<code><user></code> for each individual user, which might
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to start the new web application.
- Check the Tomcat 6 logs for the details, but likely explanations include
+ 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><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to start the new web application.
- Check the Tomcat 6 logs for the details, but likely explanations include
+ 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><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to restart the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to enumerate the system properties.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
</ul>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to enumerate the global JNDI
- resources. Check the Tomcat 6 logs for the details.</p>
+ resources. Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>No global JNDI resources are available</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to start the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to stop the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<li><em>Encountered exception</em>
<blockquote>
<p>An exception was encountered trying to undeploy the web application.
- Check the Tomcat 6 logs for the details.</p>
+ Check the Tomcat logs for the details.</p>
</blockquote></li>
<li><em>Invalid context path was specified</em>
<blockquote>
<section name="Executing Manager Commands With Ant">
<p>In addition to the ability to execute Manager commands via HTTP requests,
-as documented above, Tomcat 6 includes a convenient set of Task definitions
+as documented above, Tomcat includes a convenient set of Task definitions
for the <em>Ant</em> (version 1.4 or later) build tool. In order to use these
commands, you must perform the following setup operations:</p>
<ul>
You must use version <strong>1.4</strong> or later.</li>
<li>Install the Ant distribution in a convenient directory (called
ANT_HOME in the remainder of these instructions).</li>
-<li>Copy the file <code>server/lib/catalina-ant.jar</code> from your Tomcat 6
+<li>Copy the file <code>server/lib/catalina-ant.jar</code> from your Tomcat
installation into Ant's library directory (<code>$ANT_HOME/lib</code>).
</li>
<li>Add the <code>$ANT_HOME/bin</code> directory to your <code>PATH</code>
<section name="Introduction">
-<p>Tomcat 6 uses JMX MBeans as the technology for implementing
+<p>Tomcat uses JMX MBeans as the technology for implementing
manageability of Tomcat.</p>
<p>The descriptions of JMX MBeans for Catalina are in the mbeans-descriptor.xml
<p>Apache 1.3 supports an optional module (<code>mod_proxy</code>) that
configures the web server to act as a proxy server. This can be used to
-forward requests for a particular web application to a Tomcat 6 instance,
+forward requests for a particular web application to a Tomcat instance,
without having to configure a web connector such as <code>mod_jk</code>.
To accomplish this, you need to perform the following tasks:</p>
<ol>
AddModule mod_proxy.c
</source></li>
<li>Include two directives in your <code>httpd.conf</code> file for
- each web application that you wish to forward to Tomcat 6. For
+ each web application that you wish to forward to Tomcat. For
example, to forward an application at context path <code>/myapp</code>:
<source>
ProxyPass /myapp http://localhost:8081/myapp
ProxyPassReverse /myapp http://localhost:8081/myapp
</source>
which tells Apache to forward URLs of the form
- <code>http://localhost/myapp/*</code> to the Tomcat 6 connector
+ <code>http://localhost/myapp/*</code> to the Tomcat connector
listening on port 8081.</li>
-<li>Configure your copy of Tomcat 6 to include a special
+<li>Configure your copy of Tomcat to include a special
<code><Connector></code> element, with appropriate
proxy settings, for example:
<source>
Specification (Version 2.4)</a>, Section 12.</p>
<p>For information about utilizing the <em>Single Sign On</em> feature of
-Tomcat 6 (allowing a user to authenticate themselves once across the entire
+Tomcat (allowing a user to authenticate themselves once across the entire
set of web applications associated with a virtual host), see
<a href="config/host.html#Single Sign On">here</a>.</p>
defining the interface between a servlet container and the associated user
and role information. In many cases, however, it is desirable to "connect"
a servlet container to some existing authentication database or mechanism
-that already exists in the production environment. Therefore, Tomcat 6
+that already exists in the production environment. Therefore, Tomcat
defines a Java interface (<code>org.apache.catalina.Realm</code>) that
can be implemented by "plug in" components to establish this connection.
Five standard plug-ins are provided, supporting connections to various
</ul>
<p>It is also possible to write your own <code>Realm</code> implementation,
-and integrate it with Tomcat 6. To do so, you need to:
+and integrate it with Tomcat. To do so, you need to:
<ul>
<li>Implement <code>org.apache.catalina.Realm</code>,</li>
<li>Place your compiled realm in $CATALINA_HOME/lib,</li>
<subsection name="Example Application">
-<p>The example application shipped with Tomcat 6 includes an area that is
+<p>The example application shipped with Tomcat includes an area that is
protected by a security constraint, utilizing form-based login. To access it,
point your browser at
<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a>
<subsection name="Manager Application">
<p>If you wish to use the <a href="manager-howto.html">Manager Application</a>
-to deploy and undeploy applications in a running Tomcat 6 installation, you
+to deploy and undeploy applications in a running Tomcat installation, you
MUST add the "manager" role to at least one username in your selected Realm
implementation. This is because the manager web application itself uses a
security constraint that requires role "manager" to access ANY request URI
<h3>Introduction</h3>
-<p><strong>JDBCRealm</strong> is an implementation of the Tomcat 6
+<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in a relational database
accessed via a JDBC driver. There is substantial configuration flexibility
that lets you adapt to existing table and column names, as long as your
Note that <strong>only</strong> JAR files are recognized!</li>
<li>Set up a <code><Realm></code> element, as described below, in your
<code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 6 if it is already running.</li>
+<li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
<p>JDBCRealm operates according to the following rules:</p>
<ul>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>. Thus, any changes you have made to the database
directly (new users, changed passwords or roles, etc.) will be immediately
reflected.</li>
<h3>Introduction</h3>
-<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat 6
+<p><strong>DataSourceRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in a relational database
accessed via a JNDI named JDBC DataSource. There is substantial configuration
flexibility that lets you adapt to existing table and column names, as long
for information on how to configure a JNDI named JDBC DataSource.</li>
<li>Set up a <code><Realm></code> element, as described below, in your
<code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 6 if it is already running.</li>
+<li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
<p>DataSourceRealm operates according to the following rules:</p>
<ul>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>. Thus, any changes you have made to the database
directly (new users, changed passwords or roles, etc.) will be immediately
reflected.</li>
<h3>Introduction</h3>
-<p><strong>JNDIRealm</strong> is an implementation of the Tomcat 6
+<p><strong>JNDIRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in an LDAP directory
server accessed by a JNDI provider (typically, the standard LDAP
provider that is available with the JNDI API classes). The realm
<code>$CATALINA_HOME/lib</code> directory.</li>
<li>Set up a <code><Realm></code> element, as described below, in your
<code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat 6 if it is already running.</li>
+<li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
<p>JNDIRealm operates according to the following rules:</p>
<ul>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>. Thus, any changes you have made to the directory
(new users, changed passwords or roles, etc.) will be immediately
reflected.</li>
<h3>Introduction</h3>
-<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat 6
+<p><strong>UserDatabaseRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that uses a JNDI resource to store user
information. By default, the JNDI resource is backed by an XML file. It is not
designed for large-scale production use. At startup time, the UserDatabaseRealm
<h3>Example</h3>
-<p>The default installation of Tomcat 6 is configured with a UserDatabaseRealm
+<p>The default installation of Tomcat is configured with a UserDatabaseRealm
nested inside the <code><Engine></code> element, so that it applies
to all virtual hosts and web applications. The default contents of the
<code>conf/tomcat-users.xml</code> file is:</p>
restarted. Changes may be made via the UserDatabase resource. Tomcat
provides MBeans that may be accessed via JMX for this purpose.</li>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>.</li>
<li>Once a user has been authenticated, the user (and his or her associated
roles) are cached within Tomcat for the duration of the user's login.
<h3>Introduction</h3>
<p><strong>MemoryRealm</strong> is a simple demonstration implementation of the
-Tomcat 6 <code>Realm</code> interface. It is not designed for production use.
+Tomcat <code>Realm</code> interface. It is not designed for production use.
At startup time, MemoryRealm loads information about all users, and their
corresponding roles, from an XML document (by default, this document is loaded
from <code>$CATALINA_BASE/conf/tomcat-users.xml</code>). Changes to the data
this file will <strong>not</strong> be recognized until Tomcat is
restarted.</li>
<li>When a user attempts to access a protected resource for the first time,
- Tomcat 6 will call the <code>authenticate()</code> method of this
+ Tomcat will call the <code>authenticate()</code> method of this
<code>Realm</code>.</li>
<li>Once a user has been authenticated, the user (and his or her associated
roles) are cached within Tomcat for the duration of the user's login.
<li>Configure your security-constraints in your web.xml for
the resources you want to protect</li>
<li>Configure the JAASRealm module in your server.xml </li>
- <li>Restart Tomcat 6 if it is already running.</li>
+ <li>Restart Tomcat if it is already running.</li>
</ol>
<h3>Realm Element Attributes</h3>
<p>To configure JAASRealm as for step 6 above, you create
<h3>Additional Notes</h3>
<ul>
<li>When a user attempts to access a protected resource for
- the first time, Tomcat 6 will call the <code>authenticate()</code>
+ the first time, Tomcat will call the <code>authenticate()</code>
method of this <code>Realm</code>. Thus, any changes you have made in
the security mechanism directly (new users, changed passwords or
roles, etc.) will be immediately reflected.</li>
<h3>Introduction</h3>
- <p><strong>CombinedRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>CombinedRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that authenticates users through one or more
sub-Realms.</p>
<h3>Introduction</h3>
- <p><strong>LockOutRealm</strong> is an implementation of the Tomcat 6
+ <p><strong>LockOutRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that extends the CombinedRealm to provide lock
out functionality to provide a user lock out mechanism if there are too many
failed authentication attempts in a given period of time.</p>
system administrator can use to keep the server secure and reliable.</p>
<p><strong>WARNING</strong> - A security audit
- have been conducted using the Tomcat 6 codebase. Most of the critical
+ have been conducted using the Tomcat codebase. Most of the critical
package have been protected and a new security package protection mechanism
has been implemented. Still, make sure that you are satisfied with your SecurityManager
configuration before allowing untrusted users to publish web applications,
by Tomcat will have. There are a number of Permission classes that are
a standard part of the JDK, and you can create your own Permission class
for use in your own web applications. Both techniques are used in
- Tomcat 6.</p>
+ Tomcat.</p>
<subsection name="Standard Permissions">
<blockquote><em>
<p>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 6 for multiple instances by setting a CATALINA_BASE
+ 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 6.</p>
+ the directory into which you have installed Tomcat.</p>
</em></blockquote>
-<p>To install and configure SSL support on Tomcat 6, you need to follow
+<p>To install and configure SSL support on Tomcat, you need to follow
these simple steps. For more information, read the rest of this HOW-TO.</p>
<ol>
<li>Create a certificate keystore by executing the following command:
<p>The final step is to configure the Connector in the
<code>$CATALINA_BASE/conf/server.xml</code> file, where
<code>$CATALINA_BASE</code> represents the base directory for the
-Tomcat 6 instance. An example <code><Connector></code> element
+Tomcat instance. An example <code><Connector></code> element
for an SSL connector is included in the default <code>server.xml</code>
file installed with Tomcat. For JSSE, it should look something like this:</p>
<source>
projects / tomcat7.0 / commitdiff