You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/25 21:53:01 UTC
svn commit: r1305110 [9/10] - in /tomcat/site/trunk/docs/tomcat-3.3-doc: ./
appdev/ appdev/sample/ appdev/sample/etc/ appdev/sample/lib/
appdev/sample/src/ appdev/sample/web/ appdev/sample/web/images/ images/
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ug.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ug.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ug.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ug.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,1783 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <!-- $Id: tomcat-ug.html,v 1.28 2004/02/29 22:42:50 billbarker Exp $ -->
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" type="text/css" href="style.css">
+ <title>Tomcat User's Guide</title>
+ <!-- Changed by: Costin Manolache, 20-Mar-2000 -->
+ <!-- Changed by: Gal Shachor, 27-Mar-2000 -->
+</head>
+
+<body link="#0000ff" vlink="#800080">
+
+<!-- Banner element, all hail the Project! -->
+
+<table border="0" width="100%" cellspacing="0" cellpadding="0">
+ <tr>
+ <td width="50%"><a
+ href="http://jakarta.apache.org/index.html"><img
+ src="images/banner.gif" width="505" height="48"
+ alt="The Jakarta Project" border="0"></a></td>
+ <td width="50%" align="right"><img border="0" src="images/tomcat.gif" width="100" height="71" alt="The mighty Tomcat - Meow!"></td>
+ </tr>
+</table>
+
+
+<H1>Tomcat 3.3 User's Guide</H1>
+
+<p>This document is an introduction to the Tomcat 3.3 servlet
+ container. It should be enough for anyone to install,
+ configure and deploy Tomcat 3.3, or it's maintenance releases.
+ As well, it answers many questions common to new users. If you have any
+ comments or suggestions about this document don't hesitate to send them to the
+ Tomcat <a href="http://jakarta.apache.org/site/mail.html">mailing
+ lists</a>.</p>
+
+<p>Since Tomcat 3.3 is a reference implementation of the Servlet 2.2 and
+JSP 1.1 specification, it would be very beneficial to become familiar
+with these documents, to better understand much of the behavior that Tomcat
+3.3 implements. The Servlet 2.2 specification may be obtained
+<a href="http://java.sun.com/products/servlet/download.html">here</a> and the
+JSP 1.1 specification obtained
+<a href="http://java.sun.com/products/jsp/download.html">here</a></p>
+
+<p>One of the features of Tomcat 3.3 is its upgradability via add-on modules
+(though this feature is not yet well documented). Where such an add-on module
+affects Tomcat's behavior with respect to the Servlet 2.2/JSP 1.1 specifications,
+Tomcat's status as a reference implementation is invalided.</p>
+
+<p>Tomcat 3.3 can operate as a standalone web server. In addition, it can operate
+as an out-of-process servlet container for other web servers, such as Apache.
+For some webservers, such as IIS, it can operate as an in-process servlet
+container. Most if this document involves information that is independent
+of the mode of operation. For details about the use of Tomcat 3.3 with other
+web servers, refer to the "Tomcat Documentation" given below.</p>
+
+<p>Other important documents:</p>
+
+<ul>
+ <li><a href="http://jakarta.apache.org/site/faqs.html">Jakarta FAQ Page</a></li>
+ <li><A HREF="appdev/contents.html">Application Development
+ manual</A> - an alternative to the User's Guide,
+ somewhat out-of-date</li>
+ <li>Other <a href="index.html">Tomcat Documentation</a>
+ including HOWTOs for various web servers</li>
+</ul>
+
+<h2>Table of Contents</h2>
+
+<ul>
+ <li><a href="#about_tomcat">About Tomcat</a>
+ <ul>
+ <li><a href="#what_is_tomcat">What is Tomcat?</a></li>
+ <li><a href="#where_download">Where can I download
+ Tomcat?</a></li>
+ <li><a href="#what_servlets_jsps">What are
+ servlets? What are JSPs?</a></li>
+ <li><a href="#contribute">How do/can I contribute?</a></li>
+ <li><a href="#where_help">How come X, Y, or Z isn't
+ working? Help!</a>
+ </ul>
+ </li>
+ <li><a href="#using_tomcat">Using Tomcat 3.3</a>
+ <ul>
+ <li><a href="#install_tomcat">Installing Tomcat</a></li>
+ <li><a href="#env_setup">Environment Setup</a></li>
+ <li><a href="#starting_tomcat">Starting Tomcat</a></li>
+ <li><a href="#stopping_tomcat">Stopping Tomcat</a></li>
+ <li><a href="#tomcat_scripts">Tomcat Shell and Batch Files</a></li>
+ <li><a href="#tomcat_actions">tomcat/tomcat.bat Actions</a></li>
+ <li><a href="#tomcat_task_args">Tomcat Task Arguments</a></li>
+ </ul>
+ </li>
+ <li><a href="#configuring_tomcat">Configuring Tomcat</a>
+ <ul>
+ <li><a href="#directory_structure">Tomcat Directory Structure</a></li>
+ <li><a href="#configuring_classes">Configuring Classes</a></li>
+ <li><a href="#configuring_server">Configuring the Server</a>
+ <ul>
+ <li><a href="#conf_svr_overview">Overview</a></li>
+ <li><a href="#conf_svr_default">Default Tomcat Configuration</a></li>
+ <li><a href="#conf_svr_cust">Tomcat Server.xml Customization</a></li>
+ <li><a href="#standard_contexts">Tomcat's Standard Contexts</a></li>
+ <li><a href="#context_addcust">Adding and Customizing Contexts</a></li>
+ <li><a href="#deploy_war">Deploying WAR Files</a></li>
+ </ul></li>
+ </ul>
+ </li>
+ <li><a href="#real_world_tips">Real World Configuration Tips</a></li>
+ <li><a href="#credits">Credits</a></li>
+</ul>
+
+<hr size="5">
+
+<h2><a name="about_tomcat">About Tomcat: Q&A</a></h2>
+
+<p>See also the official <a
+ href="http://jakarta.apache.org/site/faqs.html">Jakarta FAQ Page</a>.</p>
+
+<dl>
+ <dt><strong><a name="what_is_tomcat">What is Tomcat?</a></strong></dt>
+ <dd>Tomcat is the official reference implementation of the <a
+ href="http://java.sun.com/products/servlet/">Java
+ Servlet 2.2</a> and <a
+ href="http://java.sun.com/products/jsp/">JavaServer
+ Pages 1.1</a> technologies. Developed under the Apache
+ license in an open and participatory environment, it is
+ intended to be a collaboration of the best-of-breed
+ developers from around the world.</dd>
+
+ <dt><strong><a name="where_download">Where can I download
+ Tomcat?</a></strong></dt>
+ <dd>At the <a
+ href="http://jakarta.apache.org/site/binindex.html">Jakarta
+ download page</a>!</dd>
+
+ <dt><strong><a name="what_servlets_jsps">What are servlets? What
+ are JSPs?</a></strong></dt>
+ <dd>In a nutshell, servlets are memory-resident Java programs,
+ running inside a servlet container (<em>e.g.,</em>
+ Tomcat!). Because they're memory-resident, they can
+ quickly respond to requests, as they do not incur the
+ overhead of process creation and subsequent cleanup,
+ unlike CGI-based scripting, e.g. perl, etc.
+
+ <p>From <a href="http://java.sun.com/products/servlet/">Sun's
+ servlet site</a>:</p>
+
+ <blockquote>"The <strong>Java<sup><font
+ size="-2">TM</font></sup> Servlet API</strong>
+ provides web developers with a simple,
+ consistent mechanism for extending the
+ functionality of a web server and for accessing
+ existing business systems. A servlet can almost
+ be thought of as an applet that runs on the
+ server side -- without a face."</blockquote>
+
+ <p>...and about JSPs (JavaServer Pages), again from <a
+ href="http://java.sun.com/products/servlet/">Sun's
+ servlet site</a>:</p>
+
+ <blockquote>"JSP technology is an extension of the
+ servlet technology created to support authoring
+ of HTML and XML pages. It makes it easier to
+ combine fixed or static template data with
+ dynamic content."</blockquote>
+
+ <p>JSP is comparable to other technologies such as PHP
+ and ASP, which combine programming/scripting
+ with a markup language like HTML. The key
+ difference being the programming language of
+ choice. For example, PHP uses a C/C++/Java
+ hybrid, ASP uses VBScript, and JSP utilizes the
+ full power of the Java programming language.
+ There have been many comparisons of these
+ technologies, and each has its place in the
+ astute developer's toolbox.</p>
+
+ <p>All of the above information is available at <a
+ href="http://java.sun.com/">Sun's Java
+ website</a>, which is a starting place for all
+ the ins and outs of JSPs, servlets, etc.
+ <strong>Your time spent with these technologies
+ will be much more rewarding if you first read
+ through the <a
+ href="http://java.sun.com/products/jsp/download.html">JavaServer
+ Pages</a> and <a
+ href="http://java.sun.com/products/servlet/download.html">servlet</a>
+ specifications!</strong></p>
+ </dd>
+
+ <dt><strong><a name="contribute">How do/can I contribute?</a></strong></dt>
+ <dd>Please do! See the Jakarta project contribution page, right
+ <a
+ href="http://jakarta.apache.org/site/getinvolved.html">here</a>.
+ You'll probably want to <a
+ href="mailto:tomcat-dev-subscribe@jakarta.apache.org">subscribe</a>
+ to the <strong>tomcat-dev</strong> mailing list.</dd>
+
+ <dt><strong><a name="where_help">How come X, Y, or Z isn't
+ working? Help!</a></strong></dt>
+ <dd>While we hope to cater to many common issues, we have
+ undoubtedly missed some. For more help, try (in this
+ order):
+
+<ol>
+ <li>Your log files, in the <a href="#logs_dir_defn">logs</a>
+ subdirectory of your Tomcat installation. These are an
+ untapped resource!</li>
+ <li>Have a look through the <a
+ href="http://jakarta.apache.org/site/faqs.html">
+ Jakarta FAQ Page</a>. Most installation and configuration
+ questions can be found here.</li>
+ <li>Search the Tomcat User List archive
+ <a href="http://www.mail-archive.com/tomcat-user@jakarta.apache.org/">here</a>
+ or <a href="http://mikal.org/interests/java/tomcat/index.html">here</a>
+ and the Tomcat Developer List archive
+ <a href="http://www.mail-archive.com/tomcat-dev@jakarta.apache.org/">here</a>
+ or <a href="http://www.metronet.com/~wjm/tomcat/">here</a>.</li>
+ <li>Post a question to the <strong> tomcat-user</strong> <a
+ href="http://jakarta.apache.org/site/mail.html">
+ mailing list</a>, to which you must first <a
+ href="mailto:tomcat-user-subscribe@jakarta.apache.org">subscribe</a>
+ before posting your question.</li>
+</ol>
+
+ </dd>
+</dl>
+
+<hr size="5">
+
+<h2><a name="using_tomcat">Using Tomcat 3.3</a></h2>
+
+<p>A lot of effort has been put into making Tomcat easy to use as well as flexible.
+It comes with a default configuration which should be a good starting point
+for most users. Once you have Tomcat 3.3 up and running, there are many
+customizations from which you can choose.</p>
+
+<p>To help identify which version of Tomcat you have, a "version"
+name has been incorporated in a number of places. It is in the name of
+the binary and source archives as well as the directory to which the archives
+expand. <i><version></i> will appear in the text below where this
+"version" name appears. The version will be "3.3" for the
+initial Tomcat 3.3 release, and "3.3.<i>x</i>" for subsequent
+maintenance releases.</p>
+
+<h3><a name="install_tomcat">Installing Tomcat</a></h3>
+
+<p>This section deals with installing the Tomcat 3.3 binary archive available
+from the Jakarta Project. It is also possible to install Tomcat 3.3 by
+building it from source, but that isn't covered in this document.</p>
+
+<ul>
+ <li><a href="http://jakarta.apache.org/site/binindex.html">Download</a> the
+ appropriate jakarta-tomcat-<i><version></i> binary archive file. For
+ Linux, RPMs are available.<br><br></li>
+
+ <li>Expand the archive into some directory (say /usr/local or C:\). This
+ should create a new subdirectory named
+ <code>"jakarta-tomcat-<i><version></i>"</code>. You may
+ rename this directory if you wish. Just remember to adjust
+ the instructions that follow to use the new name. If you are using
+ Linux, RPMs may be installed with the command "rpm -Uvh". Type
+ <strong>man rpm</strong> for more info.</li>
+</ul>
+
+<h3><a name="env_setup">Environment Setup</a></h3>
+
+<p>There are a number of different methods to start and stop Tomcat 3.3. There
+are differences in the environmental setup needed for these methods. This
+section addresses the environmental setup needed for using the shell scripts
+and batch files provided to simplify starting and stopping Tomcat. This
+section also assumes you will be manually starting and stopping Tomcat from
+a shell or MS-DOS window.</p>
+
+<ul>
+ <li>In a shell or DOS window, change to the
+ <code>"jakarta-tomcat-<i><version></i>"</code> directory.<br><br></li>
+
+ <li>Set the environment variable JAVA_HOME to point to the root
+ directory of your JDK hierarchy. You may optionally add the Java
+ interpreter to your PATH environment variable. The exact directory
+ may vary from system to system. Check your local file system to be sure
+ where Java is installed.
+ <br><br>
+ <ol>
+ <li>Win32:<br>
+ <tt><big>
+ set JAVA_HOME=c:/jdk1.3.1<br>
+ set PATH=%JAVA_HOME%\bin;%PATH%
+ </big></tt>
+ </li>
+ <li>Unix (bash/sh):<br>
+ <tt><big>
+ JAVA_HOME=/usr/local/java/jdk1.3.1; export JAVA_HOME<br>
+ PATH=$JAVA_HOME/bin:$PATH; export PATH<br>
+ </big></tt>
+ </li>
+ <li>Unix (tcsh):<br>
+ <tt><big>
+ setenv JAVA_HOME=/usr/local/java/jdk1.3.1<br>
+ setenv PATH $JAVA_HOME/bin:$PATH<br>
+ </big></tt>
+ </li>
+ </ol><br><br></li>
+
+ <li>You may optionally set the TOMCAT_HOME environment variable. If
+ the supplied shell/batch scripts are executed from
+ <tt>"jakarta-tomcat-<i><version></i>"</tt> or from
+ its "bin" subdirectory, then they will successfully set
+ TOMCAT_HOME for you if not already set. If you wish to execute
+ these shell/batch scripts from other directories, you must set
+ TOMCAT_HOME explicitly.
+ <br><br>
+ <ol>
+ <li>On Win32 systems you should type: <br>
+ <tt><big>set TOMCAT_HOME=c:\jakarta-tomcat-<i><version></i>
+ </big></tt></li>
+ <li>On UNIX (using bash/sh) you should type: <br>
+ <tt><big>TOMCAT_HOME=/usr/local/jakarta-tomcat-<i><version></i> ; export TOMCAT_HOME
+ </big></tt></li>
+ <li>On UNIX (using tcsh) you should type: <br>
+ <tt><big>setenv TOMCAT_HOME /usr/local/jakarta-tomcat-<i><version></i>
+ </big></tt></li>
+ </ol><br><br></li>
+
+ <li><a name="out_of_env"></a>If you are using Win9x, you will need to deal
+ with the potential <b>"Out of environment space"</b> problem, if you
+ haven't already. In the standard installation of Win9x, the default
+ amount of environment space provided to MS-DOS windows is too small for
+ Tomcat's batch files to run. There are several ways to increase the
+ size of the environment space.
+ <br><br>
+ <ol>
+ <li>A global solution is to add a "SHELL" command to your
+ <code>CONFIG.SYS</code> file. Click Start -> Run and
+ enter <code>sysedit</code>. Then click OK. In the
+ <code>C:\CONFIG.SYS</code> window, add the line:
+ <pre>SHELL=C:\COMMAND.COM /E:4096 /P</pre>
+ and click File -> Save. Then click File -> Exit and
+ reboot your system. The default amount of environment space will
+ now be 4096 bytes, more than enough for Tomcat.</li>
+ <li>If you plan on always starting Tomcat 3.3 from the
+ "MS-DOS Prompt", open a "MS-DOS Prompt".
+ Right click on the icon in the upper left corner of the DOS
+ window and select Properties. In this dialog, select the Memory
+ tab and change the "Initial environment:" setting
+ to 4096. Click OK and close the MS-DOS window. Now, whenever you
+ open an "MS-DOS Prompt", you will have enough environment
+ space to start and stop Tomcat.</li>
+ <li>If you like double-clicking files in Windows Explorer to run them,
+ you can execute <code>sysedit</code> as described in the first
+ method and add the <code>"set JAVA_HOME ..."</code> line
+ from above to the <code>AUTOEXEC.BAT</code> file. Next in Windows
+ Explorer, navigate to Tomcat's <code>bin</code> directory. Right
+ click on the <code>startup.bat</code> file and select Properties.
+ Set the "Initial environment:" as described in the second
+ method. Also select the Program tab and check the "Close on
+ exit" option. Repeat this procedure for the <code>shutdown.bat</code>
+ file. Reboot the system so the change to the <code>AUTOEXEC.BAT</code>
+ file can take effect. Now you should be able to double-click
+ on the <code>startup.bat</code> and <code>shutdown.bat</code> files
+ in Windows Explorer to start and stop Tomcat.</li>
+ </ol></li>
+</ul>
+
+<p>Once you're sure they work, you may wish to set the environment
+variables in a configuration file: C:/AUTOEXEC.BAT for Windows, ~/.bash_profile
+or ~/.cshrc, etc. Alternatively, you could customize Tomcat's script or
+batch files to incorporate the environment settings.</p>
+
+<h3><a name="starting_tomcat">Starting Tomcat</a></h3>
+
+<p>Assuming you have opened a shell or MS-DOS window and set the environment
+as described in the prior section, you are now ready to start and later
+stop Tomcat 3.3.</p>
+
+<p>To start Tomcat 3.3, execute:</p>
+
+<ul>
+ <li>On UNIX: bin/startup</li>
+ <li>On Win32: bin\startup</li>
+</ul>
+
+<p>This will start Tomcat 3.3 in the background on Unix based systems, or in
+a new MS-DOS window on Windows based systems. If you are using Win9x, and
+you see "Out of environment space", double check your setup for
+the last item in the prior section.</p>
+
+<p>You will need to wait a short period of time before Tomcat 3.3 is ready
+to serve requests. The very first use will need a little extra time since
+some WAR files will be expanded by default.</p>
+
+<p>You can tell when Tomcat 3.3 has completed its startup when text like the
+following appears in the log output.</p>
+<pre>
+2001-09-01 14:23:30 - Http10Interceptor: Starting on 8080
+2001-09-01 14:23:30 - Ajp12Interceptor: Starting on 8007
+2001-09-01 14:23:30 - Ajp13Interceptor: Starting on 8009
+</pre>
+
+<p>In Tomcat's default configuration, Tomcat's output log is not assigned to
+a file. Instead, Tomcat's log output goes <code>stderr</code>. On Windows
+systems, you can switch to the MS-DOS window to see if this test has
+appeared.</p>
+
+<p>As you might guess from the above log text, the default Tomcat 3.3 configuration
+will service HTTP requests on port 8080. If you start your browser and open
+<a href="http://localhost:8080/">http://localhost:8080/</a> you will see Tomcat
+3.3's Welcome page.</p>
+
+<p>In addition to serving HTTP, the default configuration will service Ajp12
+protocol requests on port 8007 and Ajp13 protocol requests on 8009. These
+protocols are used by the "connectors" which allow Tomcat to be used
+as a Servlet/JSP container for an external web server, such as Apache. Also,
+the Ajp12 protocol is used by the Tomcat shutdown process.</p>
+
+<p>Though documented below, here are a couple of items that you may find
+useful.</p>
+
+<ul>
+ <li>You may pass options and system property settings to the Java VM by
+ specifying them in an environment variable called TOMCAT_OPTS (for
+ instance: '-server' is useful as a performance enhancement if you're
+ running Sun's HotSpot VM).<br>
+ <b>Note:</b> On Win9x, you will not be able so include system property
+ settings in TOMCAT_OPTS because the <code>SET</code> command won't
+ accept a line with more than one equals sign.</li>
+ <li>The "auto-generated" configuration files for external web
+ servers, such as Apache, are not written during a normal startup of
+ Tomcat. To write the configuration files, append <code>jkconf</code>
+ to the startup command. Tomcat will initialize sufficiently to write
+ the files and then exit. This may be done while the Tomcat 3.3 is
+ running as a web server. </li>
+</ul>
+
+<h3><a name="stopping_tomcat">Stopping Tomcat</a></h3>
+
+<p>To perform a normal shutdown of Tomcat 3.3, a special "shutdown"
+request must be send from a separate process, or possibly a different computer.
+In the default configuration, that "shutdown" request must be made
+using the Ajp12 protocol. If the shell or MS-DOS window used to start Tomcat
+is not still open, first open a new one and set the environment the same as for
+starting Tomcat.</p>
+
+<p>To stop Tomcat 3.3, execute:</p>
+
+<ul>
+ <li>On UNIX: bin/shutdown</li>
+ <li>On Win32: bin\shutdown</li>
+</ul>
+
+<p>The shutdown process incorporates a <code>host</code>, <code>port</code>,
+and a <code>password</code>. In the default configuration, the <code>host</code>
+defaults to <code>localhost</code>. This means that Tomcat 3.3 can only be
+shutdown from the same computer that started it. The <code>port</code>
+automatically defaults to the port being used by the Ajp12 protocol. The
+<code>password</code> defaults to "not specified". This means that
+a password will not be required to shutdown Tomcat 3.3.</p>
+
+<h3><a name="tomcat_scripts">Tomcat Shell and Batch Files</a></h3>
+
+<p>Tomcat's shell and batch files are found in Tomcat's <code>bin</code>
+directory. These files support "actions" beyond starting and
+stopping Tomcat. To help make better use of the functionality provided, the
+following table describes each of these files. If desired, you can customize
+these batch files to suit your needs.</p>
+
+<h4>Tomcat Shell and Batch files</h4>
+<table border="1">
+ <tr><th bgcolor="#c0c0c0">File</th><th bgcolor="#c0c0c0">Description</th></tr>
+ <tr><td>cpappend.bat</td><td>This batch file is used by <code>tomcat.bat</code>
+ to build a classpath in a couple of <code>tomcat.bat</code>'s other
+ functions. It is not executed during Tomcat start and stop functions.</td></tr>
+ <tr><td>jspc</td><td>Shell script to invoke JSPC on Unix based systems. It
+ uses <code>tomcat</code> with the "jspc" option to pre-translate
+ JSP pages to Java files.</td></tr>
+ <tr><td>jspc.bat</td><td>Batch file to invoke JSPC on Windows based systems.
+ It uses <code>tomcat.bat</code> with the "jspc" option to
+ pre-translate JSP pages to Java files.</td></tr>
+ <tr><td>shutdown.bat</td><td>Batch file for stopping Tomcat on Windows based
+ systems. If TOMCAT_HOME is not set, it should be executed from Tomcat's home
+ directory, or one of its subdirectories. It executes <code>tomcat.bat</code>
+ with the "start" argument. Features and limitations of
+ <code>tomcat.bat</code> apply to this batch file.</td></tr>
+ <tr><td>shutdown</td><td>Shell script for stopping Tomcat on Unix based
+ systems. It executes <code>tomcat</code> with the "stop"
+ argument. Features and limitations of <code>tomcat</code> apply to
+ this script.</td></tr>
+ <tr><td>tomcat</td><td>The main script for Unix based systems. It can start
+ and stop Tomcat, as well as perform other functions. It makes a number of
+ attempts to guess TOMCAT_HOME if not set explicitly (see script contents
+ for details). It can also guess your JAVA_HOME if it is in your PATH
+ environment variable.</td></tr>
+ <tr><td>startup.bat</td><td>Batch file for starting Tomcat on Windows based
+ systems. If TOMCAT_HOME is not set, it should be executed from Tomcat's home
+ directory, or one of its subdirectories. It executes <code>tomcat.bat</code>
+ with the "start" argument. Features and limitations of
+ <code>tomcat.bat</code> apply to this batch file.</td></tr>
+ <tr><td>startup</td><td>Shell script for starting Tomcat on Unix based
+ systems. It executes <code>tomcat</code> with the "start"
+ argument. Features and limitations of <code>tomcat</code> apply to
+ this script.</td></tr>
+ <tr><td>tomcat.bat</td><td>The main batch file for Windows based systems. It
+ can start and stop Tomcat, as well as perform other functions. It can guess
+ TOMCAT_HOME if it isn't set explicitly, provided this batch file is executed
+ from Tomcat's home directory or one of its subdirectories. JAVA_HOME must
+ be set for this batch file to function. An error message is displayed if
+ not set.</td></tr>
+ <tr><td>tomcatEnv.bat</td><td>A batch file that executes <code>tomcat.bat</code>
+ with the "env" option to set Tomcat's runtime environment in your
+ MS-DOS window.</td></tr>
+</table>
+
+<p>You may have noted that <code>tomcat</code> and <code>tomcat.bat</code>
+are the primary scripts. They are the scripts that actually perform the
+"actions". The list of actions, as well as additional environment
+variables they support, are described in the
+<a href="#tomcat_actions">next section</a>.</p>
+
+<p>Note that most actions involve starting the
+<code>org.apache.tomcat.startup.Main</code> class in a Java VM. This class
+and some classes it uses also accept arguments. To take advantage of the
+full capabilities of Tomcat, you will need to become familiar with these
+arguments as well. See <a href="#tomcat_task_args">Tomcat Task Arguments</a>
+for those details.</p>
+
+<h3><a name="tomcat_actions">tomcat/tomcat.bat Actions</a></h3>
+
+<p>The <code>tomcat</code> shell script and <code>tomcat.bat</code> batch
+files contain the code that invokes the various features of Tomcat 3.3. It
+supports a number of actions specified by the first argument. The following
+table lists the supported actions. Almost all of the actions involve starting
+a Java VM. An environment variable, TOMCAT_OPTS or JSPC_OPTS, is provided for
+specifying Java VM options, such as "-Xmx256m" and system property
+settings, such as "-Dmy.prop=myvalue". The <code>jspc</code> action
+uses the <code>JSPC_OPTS</code> environment variable. All other actions with
+support this environment variable use <code>TOMCAT_OPTS</code>.</p>
+
+<p><b>Note:</b> On Win9x, you will not be able to include system property
+settings in <code>TOMCAT_OPTS</code> or <code>JSPC_OPTS</code> because the
+<code>SET</code> command will not accept a line with more than one equals
+sign. If you need an additional system property setting, you will need to
+modify your <code>tomcat.bat</code> to include it on the command line.</p>
+
+<h4>Actions supported by the tomcat and tomcat.bat scripts</h4>
+<table border="1">
+ <tr><th bgcolor="#c0c0c0">Action</th><th bgcolor="#c0c0c0">Description</th></tr>
+ <tr><td>start</td><td>This action starts up Tomcat in the background on Unix
+ based systems, and in a new MS-DOS window on Windows based systems.
+ Java VM options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
+ <tr><td>stop</td><td>This actions tries to stop the running Tomcat. Java VM
+ options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
+ <tr><td>run</td><td>This action starts up Tomcat in the foreground on Unix
+ based systems, and in the current MS-DOS window on Windows based systems.
+ Java VM options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
+ <tr><td>enableAdmin</td><td>Rewrites the <code>apps-admin.xml</code> file in
+ Tomcat's <code>conf</code> directory so that the admin web application is
+ "trusted". For security reasons, the admin web application is
+ "untrusted" by default. If you plan to leave the admin web
+ application trusted, you should change the admin password found in the
+ <code>admin-users.xml</code> file in the <code>conf/users</code> directory.
+ Java VM options may be specified in the TOMCAT_OPTS environment variable.</td></tr>
+ <tr><td>env</td><td>Sets the TOMCAT_HOME and CLASSPATH environment variables
+ to match Tomcat's runtime environment. This is useful for compiling
+ servlets or other Java files for use within Tomcat. For best results, ensure
+ TOMCAT_HOME is set to an absolute path. If set to "."
+ or "..", the CLASSPATH environment variable will be invalid if
+ you leave the current directory.</td></tr>
+ <tr><td>jspc</td><td>Pre-translates specified JSP pages to Java files.
+ Java VM options may be specified in the JSPC_OPTS environment variable.</td></tr>
+ <tr><td>estart</td><td>Starts Tomcat without reading the server.xml file.
+ Instead, the set of modules making up the instance of Tomcat is created
+ internally by org.apache.tomcat.startup.EmbededTomcat. This command is
+ useful for testing customized versions of the EmbededTomcat class when
+ trying to embed Tomcat in an application. Java VM options may be specified
+ in the TOMCAT_OPTS environment variable.</td></tr>
+</table>
+
+<p>Except for the <code>env</code> action, each action corresponds to a
+"task" supported by the <code>org.apache.tomcat.startup.Main</code>
+class. The <code>tomcat</code> and <code>tomcat.bat</code> files, as well
+as the files that call them, will pass additional arguments on the command line
+to the <code>Main</code> class as arguments. See the next section for what
+arguments are supported by each of the tasks.</p>
+
+<p>Also note that the TOMCAT_HOME environment variable is passed to the
+startup class via a <code>tomcat.home</code> system property.</p>
+
+<h3><a name="tomcat_task_args">Tomcat Task Arguments</a></h3>
+
+<p>The <code>org.apache.tomcat.startup.Main</code> class is the primary class
+used for executing a Tomcat "task", i.e. start, stop, etc. The term
+"task" is used instead of "action" because it is more than
+just an argument here. Each task has an associated class which will be executed
+to perform the task. The first argument passed to the <code>main()</code>
+method of <code>org.apache.tomcat.startup.Main</code> will determine which
+"task" class gets executed. Each of the "task" classes
+supports its own set of arguments. These arguments are documented in the
+table that follows.</p>
+
+<p><b>Note:</b> The arguments to each of the tasks may be optionally preceded
+by a '-'. However, the "task" argument must not be preceded by a '-'.
+If you specified <code>-stop</code> as the task, the default "start"
+task would be executed and <code>-stop</code> passed to the "start"
+task as an argument.</p>
+
+<h4>Tasks supported by org.apache.tomcat.startup.Main</h4>
+<table border="1">
+ <tr><th bgcolor="#c0c0c0">Task</th><th bgcolor="#c0c0c0">Argument</th>
+ <th bgcolor="#c0c0c0">Description</th></tr>
+ <tr><td>start<br>run<br>estart</td><td> </td>
+ <td>Starts Tomcat using the org.apache.tomcat.startup.EmbededTomcat class.
+ This is the default action.</td></tr>
+ <tr><td> </td><td>config <i><file></i><br>
+ or<br>f <i><file></i></td>
+ <td>Use specified server configuration file instead of the default
+ <code>server.xml</code>.</td></tr>
+ <tr><td> </td><td>debug <i><level></i></td>
+ <td>Set the debug level for the ContextManager.</td></tr>
+ <tr><td> </td><td>estart</td>
+ <td>Starts Tomcat without reading the server.xml file. Instead, the Tomcat
+ instance is constructed internally by this class.</td></tr>
+ <tr><td> </td><td>help</td><td>Display usage information.</td></tr>
+ <tr><td> </td><td>home <i><dir></i><br>
+ or<br>h <i><dir></i></td>
+ <td>Use specified directory as Tomcat's home directory, i.e. the directory
+ under which the <code>conf</code>, <code>webapps</code>, <code>logs</code>,
+ and <code>work</code> directories are found.</td></tr>
+ <tr><td> </td><td><span>install <i><dir></i></span><br>
+ or<br>i <i><dir></i></td>
+ <td>Use specified directory as Tomcat's install director, i.e. where the
+ <code>lib</code> directory is found.</td></tr>
+ <tr><td> </td><td>sandbox</td>
+ <td>Run Tomcat with a security manager.</td></tr>
+ <tr><td> </td><td>jkconf</td>
+ <td>Generate configuration files instead of starting Tomcat.</td></tr>
+
+ <tr><td>stop</td><td> </td>
+ <td>Stops Tomcat using the org.apache.tomcat.startup.StopTomcat class.</td></tr>
+ <tr><td> </td><td>ajpid <i><file></i><br>
+ or<br>secretFile <i><file></i></td>
+ <td>Specify the defaults file written by the
+ <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> or
+ <a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> module. It
+ contains default values for <code>port</code>, <code>host</code>, and
+ <code>pass</code> arguments. The default value is
+ <code>TOMCAT_HOME/conf/ajp12.id</code> or <code>TOMCAT_HOME/conf/ajp13.id</code>
+ if <code>ajp12</code> or <code>ajp13</code> is specified, respectively.
+ If neither <code>ajp12</code> or <code>ajp13</code> is specified, the
+ ajpid file defaults first to <code>TOMCAT_HOME/conf/ajp13.id</code>, and
+ if not found, defaults to <code>TOMCAT_HOME/conf/ajp12.id</code>.</td></tr>
+ <tr><td> </td><td>ajp12</td><td>Specifies that the ajp12 protocol should
+ be used for shutdown. It implies the format of the ajpid file as that
+ written by the Ajp12Connector.</td></tr>
+ <tr><td> </td><td>ajp13</td><td>Specifies that the ajp13 protocol should
+ be used for shutdown. It implies the format of the ajpid file as that
+ written by the Ajp13Connector.</td></tr>
+ <tr><td> </td><td>ajpid12 <i><file></i><br><b>[Tomcat 3.3.1]</b></td>
+ <td>Equivalent to specifying <code>ajpid <i><file></i></code>
+ and <code>ajp12</code>.</td></tr>
+ <tr><td> </td><td>ajpid13 <i><file></i><br><b>[Tomcat 3.3.1]</b></td>
+ <td>Equivalent to specifying <code>ajpid <i><file></i></code>
+ and <code>ajp13</code>.</td></tr>
+ <tr><td> </td><td>help</td><td>Display usage information.</td></tr>
+ <tr><td> </td><td>home <i><dir></i><br>
+ or<br>h <i><dir></i></td>
+ <td>Use specified directory as Tomcat's home directory, i.e. the directory
+ under which the <code>conf</code> directory is found.</td></tr>
+ <tr><td> </td><td>host <i><host></i></td>
+ <td>The host running the Tomcat instance you wish to shutdown. Defaults to
+ value in defaults file if available. Otherwise it defaults to the local
+ system.</td></tr>
+ <tr><td> </td><td>port <i><port></i></td>
+ <td>The port of the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
+ in the Tomcat instance you wish to shutdown. Must be specified if
+ a default value can not be read from the defaults file.</td></tr>
+ <tr><td> </td><td>pass <i><string></i><br>
+ or<br>secret <i><string></i></td>
+ <td>The "secret" password string expected by the
+ <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> for a shutdown
+ request. The Ajp12Connector defaults to not using a "secret"
+ string, in which case this argument may be omitted. If the
+ Ajp12Connector is using a "secret" string, you must specify
+ the same string if the default can not be read from the defaults file or
+ the shutdown will fail.</td></tr>
+
+ <tr><td>enableAdmin</td><td> </td>
+ <td>Rewrites the TOMCAT_HOME/conf/apps-admin.xml context configuration file
+ using the org.apache.tomcat.startup.EnableAdmin class.</td></tr>
+ <tr><td> </td><td>home <i><dir></i><br>
+ or<br>h <i><dir></i></td>
+ <td>Use specified directory as Tomcat's home directory, i.e. the directory
+ under which the <code>conf/apps-admin.xml</code> file is found.</td></tr>
+ <tr><td>jspc</td><td> </td>
+ <td>Pre-compiles JSP pages using the org.apache.tomcat.startup.Jspc class.</td></tr>
+ <tr><td> </td><td> </td><td><i>arguments not yet documented</i></td></tr>
+</table>
+
+<p>The <code>start</code>, <code>run</code>, and <code>estart</code> tasks
+assume a command line argument that doesn't match one of the predefined
+arguments is a ContextManager property name and the next command line argument
+is its value. Thus a command such as:</p>
+
+<pre>bin/startup myprop myvalue</pre>
+
+<p>would define a ContextManager property named "myprop" with a
+String value of "myvalue". ContextManager properties can used for
+parameter substitution in the <code>server.xml</code> file. Set the
+<a href="serverxml.html#substitution">Variable substitution</a> section of
+the Server.xml document for details. There are also some ContextManager
+properties supported by certain modules. These are listed in the following
+table.</p>
+
+<table border="1">
+ <tr><th bgcolor="#c0c0c0">Module</th>
+ <th bgcolor="#c0c0c0">Context Property</th>
+ <th bgcolor="#c0c0c0">Description</th></tr>
+ <tr><td><a href="serverxml.html#Ajp12Connector">Ajp12Connector</a></td>
+ <td>ajpid12</td>
+ <td>Overrides the <code>ajpidFile</code> attribute to specify the file
+ in which to record Ajp12 connector info and password.</td></tr>
+ <tr><td><a href="serverxml.html#Ajp13Connector">Ajp13Connector</a></td>
+ <td>ajpid13</td>
+ <td>Overrides the <code>ajpidFile</code> attribute to specify the file
+ in which to record Ajp13 connector info and password.</td></tr>
+ <tr><td><a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a></td>
+ <td>additionalJars</td>
+ <td>List of jars to be added to each web application.</td></tr>
+</table>
+
+<p></p>
+
+<hr size="5">
+
+<h2><a name="configuring_tomcat">Configuring Tomcat 3.3 </a></h2>
+
+<p>Customizing Tomcat will involve adding or modifying one or more files
+involved with Tomcat. The next section describes the
+<a href="#directory_structure">directory structure</a> of Tomcat 3.3 to document
+where files are found. Following that are sections document the two parts to
+Tomcat configuration.</p>
+
+<ul>
+ <li><a href="#configuring_classes">Configuring classes</a></li>
+ <li><a href="#configuring_server">Configuring the server</a></li>
+</ul>
+
+<h3><a name="directory_structure">Tomcat Directory Structure</a></h3>
+
+<p>After installing Tomcat 3.3, you should have the following directory
+structure under <code>"jakarta-tomcat-<i><version></i>"</code>.
+Customization of Tomcat 3.3 will involve adding or modifying files in one
+or more of these directories.</p>
+
+<table border=1 width="75%" valign="center">
+ <tr>
+ <th bgcolor="#c0c0c0" WIDTH="15%">Directory</th>
+ <th bgcolor="#c0c0c0" WIDTH="85%">Contents</th>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left">bin</td>
+ <td WIDTH="85%"> Startup/shutdown scripts and other useful files.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left">conf</td>
+ <td WIDTH="85%"> <a href="#configuring_server">Configuration files</a>,
+ including modules.xml, server.xml, and a number of apps-<i><name></i>.xml.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">conf/auto</td>
+ <td width="85%">Directory where auto-generated configuration files are
+ written.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">conf/jk</td>
+ <td width="85%">Directory containing mod_jk specific configuration files.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">conf/jserv</td>
+ <td width="85%">Directory containing mod_jserv specific configuration files.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">conf/users</td>
+ <td width="85%">Directory containing user name/password configuration files.
+ These are used by the SimpleRealm module for authentication.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left">doc</td>
+ <td WIDTH="85%">Miscellaneous documents regarding Tomcat.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left">lib</td>
+ <td WIDTH="85%">Jar files that are used for starting and stopping Tomcat.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">lib/container</td>
+ <td width="85%">Jar files that make up the Tomcat server classes. Any
+ Jar file in this directory is automatically included in Tomcat's
+ <b>Server Classloader</b>. See
+ <a href="#configuring_classes">Configuring Classes</a>.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">lib/common</td>
+ <td width="85%">Jar files that contain classes shared between the Tomcat
+ server and all web applications. Any Jar file in this directory is
+ automatically included in Tomcat's <b>Common Classloader</b>. See
+ <a href="#configuring_classes">Configuring Classes</a>.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">lib/apps</td>
+ <td width="85%">Jar files that contain classes shared between all web
+ applications. Any Jar file in this directory is automatically included
+ in Tomcat's <b>Apps Classloader</b>. See
+ <a href="#configuring_classes">Configuring Classes</a>.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left"><a name="logs_dir_defn">logs</a></td>
+ <td WIDTH="85%"> This is where Tomcat places its log files by default.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">modules</td>
+ <td width="85%">Directory where "add-on" WARs are placed.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">native</td>
+ <td width="85%">Base directory for native source code.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left">src</td>
+ <td WIDTH="85%">Currently empty. Tomcat's source code isn't currently
+ part of the binary distribution.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="left">webapps</td>
+ <td WIDTH="85%"> Sample web applications. Any .war files placed
+ here will be automatically expanded. See <a href="#deploy_war">Deploying WAR Files</a>.</td>
+ </tr>
+</table>
+
+<p>Additionally you can, or Tomcat will, create the following
+directories:</p>
+
+<table border="1" width="75%" VALIGN="center">
+ <tr>
+ <td width="15%" align="left"> <a name="work_dir_defn"> work</a></td>
+ <td width="85%"> Where Tomcat
+ places intermediate files (such as compiled JSP files) during
+ its work. If you delete this directory while Tomcat is running
+ you will not be able to execute JSP pages.
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" align="left">classes</td>
+ <td width="85%"> Any class that you add to this directory will
+ find its place in Tomcat's classpath.
+ </td>
+ </tr>
+</table>
+
+<h3><a name="configuring_classes">Configuring Classes</a></h3>
+
+<p>Configuring classes refers to configuring what classes are available and the
+scope of their availability when Tomcat 3.3 is running. You may wish to add
+additional classes and jars. Also, a web application may need some modification
+based on what Tomcat 3.3 makes available by default.</p>
+
+<p>The available classes are determined by the classloader hierarchy that
+Tomcat 3.3 creates when it starts up. The classloader hierarchy built by
+Tomcat 3.3 looks like this:</p>
+
+<table align="center" class="cltable" border="0" cellspacing="0">
+ <tr><td>
+ <table align="center">
+ <tr><td class="clt_loader">Server Classloader</td></tr>
+ <tr><td class="clt_label">directory:</td></tr>
+ <tr><td class="clt_data">lib/container</td></tr>
+ <tr><td class="clt_label">default contents:</td></tr>
+ <tr>
+ <td class="clt_data">crimson.jar<br>facade22.jar<br>
+ jasper.jar<br>tomcat_modules.jar<br>tomcat_util.jar<br>xalan.jar<br>
+ (if RPM)commons-collections.jar<br>commons-dbcp.jar<br>
+ commons-pool.jar<br></td></tr>
+ </table></td>
+ <td> </td><td> </td><td> </td><td>
+ <table align="center">
+ <tr><td class="clt_loader">Webapp Classloader(s)</td></tr>
+ <tr><td class="clt_label">directory:</td></tr>
+ <tr><td class="clt_data">WEB-INF/classes<br>WEB-INF/lib</td></tr>
+ <tr><td align="center">|</td></tr>
+ <tr><td class="clt_loader">Apps Classloader</td></tr>
+ <tr><td class="clt_label">directory:</td></tr>
+ <tr><td class="clt_data">lib/apps</td></tr>
+ <tr><td class="clt_label">default contents:</td></tr>
+ <tr><td class="clt_data"><i>empty</i></td></tr>
+ </table>
+ </td></tr>
+ <tr><td> </td><td align="center">\</td><td> </td><td align="center">/</td><td> </td></tr>
+ <tr><td> </td><td> </td><td>
+ <table align="center">
+ <tr><td class="clt_loader">Common Classloader</td></tr>
+ <tr><td class="clt_label">directory:</td></tr>
+ <tr><td class="clt_data">lib/common</td></tr>
+ <tr><td class="clt_label">default contents:</td></tr>
+ <tr><td class="clt_data">connector_util.jar<br>core_util.jar<br>
+ etomcat.jar<br>jasper-runtime.jar<br>servlet.jar<br>tomcat_core.jar</td></tr>
+ </table>
+ </td>
+ <td> </td><td> </td></tr>
+ <tr><td> </td><td> </td><td align="center">|</td><td> </td><td> </td></tr>
+ <tr><td> </td><td> </td><td>
+ <table align="center">
+ <tr><td class="clt_loader">Application Classloader</td></tr>
+ <tr><td class="clt_data">the CLASSPATH classloader</td></tr>
+ <tr><td class="clt_label">default contents:</td></tr>
+ <tr><td class="clt_data">tomcat.jar</td></tr>
+ </table>
+ </td><td> </td><td> </td></tr>
+ <tr><td> </td><td> </td><td align="center">|</td><td> </td><td> </td></tr>
+ <tr><td> </td><td> </td><td>
+ <table align="center">
+ <tr><td class="clt_loader">JDK Extensions Classloader</td></tr>
+ <tr><td class="clt_label">directory:</td></tr>
+ <tr><td class="clt_data"><i>jdk</i>/jre/lib/ext</td></tr>
+ </table></td>
+ <td> </td><td> </td></tr>
+</table>
+
+<p>In this classloader hierarchy, classloaders can access classes in
+classloaders beneath them. They can not access classes in classloaders to the
+side or above! To understand why this is important, consider whether web
+applications would have access to an XML parser in this classloader hierarchy.
+A brief inspection should reveal that in Tomcat 3.3, web applications would
+not normally have access to an XML parser. The <code>crimson.jar</code> and
+<code>xalan.jar</code> are tucked away in the <b>Server Classloader</b> where
+they are accessible only within that classloader. The same is true for the
+other jars in <code>Server Classloader</code> are not visible to web applications
+as well.</p>
+
+<p>The primary benefit of this new classloader hierarchy is that you can put
+your own XML parser in your web application without running into conflicts with
+the XML parser being used by the server. However, since having an XML parser
+by default has been the norm in the past, Tomcat 3.3 tries to maintain this
+behavior should your web application not already contain an XML parser. The
+default configuration for the
+<a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a> in
+<code>server.xml</code> is to provide an XML parser to web applications
+that don't already contain one. It accomplishes this by adding entries to
+the <code>Webapp Classloader</code> as if you had included the
+<code>crimson.jar</code> and <code>xalan.jar</code> in your web application's
+<code>WEB-INF/lib</code>.</p>
+
+<p>Along with this classloader hierarchy comes the need to decide which
+classloader is the appropriate one in which to add classes or jars.
+Note that if you have a jar containing classes that depend on
+<code>servlet.jar</code>, putting that jar on the CLASSPATH wouldn't work.
+<code>servlet.jar</code> isn't accessible to the <b>Application Classloader</b>.
+This is why in Tomcat 3.3, your CLASSPATH environment variable is ignored. The
+appropriate classloader would be the <b>Common Classloader</b> or above.</p>
+
+<p>Classes that are used in one particular web application should be placed
+in that web application's <code>WEB-INF/classes</code> or in a jar in the
+<code>WEB-INF/lib</code> as defined by the Servlet 2.2 specification. If you
+want to give the classes wider scope by putting them in the
+<code>Common Classloader</code> or <code>Apps Classloader</code>, or want them
+to be part of the <code>Server Classloader</code>, use one of the following two
+methods to have those classes included in that classloader:
+
+<ol>
+ <li>If the classes are in a jar file, place the jar file in the directory
+ that corresponds to the chosen classloader. If the classes exist as
+ class files, create a <code>classes</code> under the corresponding
+ directory if it doesn't already exist. Then add the class files into
+ the appropriate package directory under the <code>classes</code>
+ directory.</li>
+ <li>If the chosen classloader is the <code>Common Classloader</code> or
+ <code>Apps classloader</code> you include a directory or jar these
+ classloaders by listing them a System property. For the
+ <code>Common Classloader</code>, include the directory or jar file in a
+ System property named <code>org.apache.tomcat.common.classpath</code>.
+ For the <code>Apps classloader</code>, use a System property named
+ <code>org.apache.tomcat.apps.classpath</code>.</li>
+</ol>
+
+<p><b>Note:</b> In an instance of Tomcat 3.3 which is using
+<a href="serverxml.html#ReloadInterceptor">ReloadInterceptor</a> (the default),
+the <b>Webapp Classloader</b>, <b>Apps Classloader</b>, and <b>Common classloader</b>
+are "wrapped" into a single classloader. This classloader will be an
+instance of <code>org.apache.tomcat.util.depend.DependClassLoader</code> or
+<code>org.apache.tomcat.util.depend.DependClassLoader12</code>, depending
+on which JDK you are using. This classloader checks for updates when classes
+are loaded from the "wrapped" classloaders so that reloads can
+be triggered when needed.</p>
+
+<h3><a name="configuring_server">Configuring the Server</a></h3>
+
+<h4><a name="conf_svr_overview"></a>Overview</h4>
+
+<p>By default, Tomcat's configuration is determined by the contents of the
+<code>server.xml</code> file found in Tomcat's <code>conf</code> directory.
+This file specifies the sequence of <strong>modules</strong> (a.k.a. interceptors)
+that should participate in the operation of this instance of Tomcat. This file
+also includes the operating parameters for those modules.</p>
+
+<p>Prior to reading the <code>server.xml</code> file, Tomcat reads the
+<code>modules.xml</code> file which is also found in the <code>conf</code>
+directory. This file specifies mappings between module names and the class
+that implements the module. This simplifies the syntax in <code>servers.xml</code>
+and allows you to update a module's class by updating just <code>modules.xml</code>.
+The <code>server.xml</code>, and possibly other files, do not have to change.</p>
+
+<p>To allow for customization of Tomcat's configuration without requiring
+modification of <code>modules.xml</code> and <code>server.xml</code>, Tomcat
+will read additional files during startup. In addition to <code>modules.xml</code>,
+Tomcat will read any file in the <code>conf</code> directory that matches the
+pattern <code>modules-*.xml</code>. Likewise for <code>server.xml</code>,
+by default Tomcat will read additional files which match the pattern
+<code>server-*.xml</code>.</p>
+
+<p>If you specify the configuration file (i.e. the file to use in place of
+<code>server.xml</code>) as a command line argument, the additional files read
+will be derived from the base name of the file you specify. For example, if
+the configuration file specified was <code>myserver.xml</code>, then the file
+pattern would be <code>myserver-*.xml</code>. Because of this, you should avoid
+using '-' in your configuration file names except when taking advantage of this
+feature.</p>
+
+<p>When using additional configuration files in conjunction with
+<code>server.xml</code> it is important to note that these configuration files
+apply to a single Tomcat 3.3 server instance. In other words, all
+<ContextManager> elements in these files refer to the same ContextManager
+instance. ContextManager is the controlling class for the Tomcat 3.3 server.</p>
+
+<p>Other files may be read as well for configuration. These, however, are determined
+by the <strong>modules</strong> that are included by <code>server.xml</code>
+and associated files. The primary example of this is <code>ContextXmlReader</code>.
+It is responsible for reading files containing Context declarations in the form:</p>
+<pre><Context path="/myapp" docBase="<i>somepath</i>" ... /></pre> or
+<pre><Context path="/myapp" docBase="<i>somepath</i>" ...>
+ <i>context local modules</i>
+</Context></pre>
+
+<p>By separating the reading of "context" configurations from the
+server configuration, you can manually add additional contexts without
+modifying the <code>server.xml</code> file.</p>
+
+<p>The <code>ContextXmlReader</code> module supports a <code>config</code>
+parameter which specifies the file to read. Like <code>server.xml</code>,
+additional files are read based on the pattern <code><base>-*.xml</code>.
+Thus, specifying <code>config="conf/myapps.xml"</code> would read
+<code>conf/myapps.xml</code>, if it exists, plus all files in the
+<code>conf</code> directory matching the pattern <code>myapps-*.xml</code>.</p>
+
+<p>Tomcat 3.3's default <code>server.xml</code> includes two instances of the
+<code>ContextXmlReader</code> module. One reads <code>conf/apps.xml</code>,
+which reads all the "apps" files found in the <code>conf</code>
+directory by default. For backward compatibility with having "context"
+declarations in <code>server.xml</code>, the second instance of
+<code>ContextXmlReader</code> reads <code>conf/server.xml</code>, processing
+only the <code><Context></code> entries.</p>
+
+<p>For additional information about contexts and their configuration, see
+<a href="#standard_contexts">Tomcat's Standard Contexts</a> and
+<a href="#context_addcust">Adding and Customizing Contexts</a>.</p>
+
+<h4><a name="conf_svr_default">Default Tomcat Configuration</a></h4>
+
+<p>The default <code>server.xml</code> contains the following configuration.</p>
+
+<table border="1">
+ <tr><th>Module Entry</th><th>Status</th><th>Description</th></tr>
+ <tr><td><<a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a>
+ useApplicationLoader="true" /></td><td> </td>
+ <td>Constructs and sets the classloader for each context</td></tr>
+ <tr><td><<a href="serverxml.html#TrustedLoader">TrustedLoader</a> /></td>
+ <td> </td>
+ <td>Provides special handling for "trusted" contexts which have
+ a <code>interceptors.xml</code> file in their <code>WEB-INF</code>
+ directory.</td></tr>
+ <tr><td><<a href="serverxml.html#LogSetter">LogSetter</a>
+ name="tc_log" timestamps="true"<br>
+ verbosityLevel="INFORMATION" /></td><td> </td>
+ <td>Sets up Tomcat's log output channel. In the absence of a <code>path</code>
+ setting, output goes to <code>stderr</code>.</td></tr>
+ <tr><td><<a href="serverxml.html#LogEvents">LogEvents</a> enabled="false" /></td><td> </td>
+ <td>When enabled, logs when module methods are called.</td></tr>
+ <tr><td><<a href="serverxml.html#ContextXmlReader">ContextXmlReader</a>
+ config="conf/server.xml" /></td><td> </td>
+ <td>Reads context definitions from the <code>server.xml</code> file for
+ backwards compatibility. This may be removed if you don't put
+ context definitions in your <code>server.xml</code> file.</td></tr>
+ <tr><td><<a href="serverxml.html#ContextXmlReader">ContextXmlReader</a>
+ config="conf/apps.xml" /></td><td> </td>
+ <td>Reads context definitions from the <code>conf/apps.xml</code> file
+ and any files matching the pattern <code>apps-*.xml</code> in the
+ <code>conf</code> directory.</td></tr>
+ <tr><td><<a href="serverxml.html#AutoDeploy">AutoDeploy</a>
+ source="modules" target="modules"
+ redeploy="true" /></td><td> </td>
+ <td>Expands ".war" files in the <code>modules</code> directory.</td></tr>
+ <tr><td><<a href="serverxml.html#AutoWebApp">AutoWebApp</a>
+ dir="modules" host="DEFAULT" trusted="true"/></td><td> </td>
+ <td>Auto-creates contexts for subdirectories in the <code>modules</code>
+ directory. These contexts are defaulted to "trusted".</td></tr>
+ <tr><td><<a href="serverxml.html#AutoDeploy">AutoDeploy</a>
+ source="webapps" target="webapps" /></td><td> </td>
+ <td>Expands ".war" files in the <code>webapps</code> directory.</td></tr>
+ <tr><td><<a href="serverxml.html#AutoWebApp">AutoWebApp</a>
+ dir="webapps" host="DEFAULT" /></td><td> </td>
+ <td>Auto-creates contexts for the subdirectories in the <code>webapps</code>
+ directory.</td></tr>
+ <tr><td><<a href="serverxml.html#PolicyLoader">PolicyLoader</a><br>
+ securityManagerClass="java.lang.SecurityManager"<br>
+ policyFile="conf/tomcat.policy" /></td><td> </td>
+ <td>Sets a policy file and security manager if "sandbox" is
+ specified on the command line without also specifying a policy file
+ on the command line.</td></tr>
+ <tr><td><<a href="serverxml.html#SimpleMapper1">SimpleMapper1</a> /></td><td> </td>
+ <td>Handles the mapping of requests to contexts.</td></tr>
+ <tr><td><<a href="serverxml.html#SessionExpirer">SessionExpirer</a>
+ checkInterval="60" /></td><td> </td>
+ <td>Handles the destruction of sessions after they expire.</td></tr>
+ <tr><td><<a href="serverxml.html#SessionIdGenerator">SessionIdGenerator</a><br>
+ randomClass="java.security.SecureRandom"<br>
+ randomFile="/dev/urandom" /></td><td> </td>
+ <td>Generates session IDs for requests that need a new session.</td></tr>
+ <tr><td><<a href="serverxml.html#LogSetter">LogSetter</a>
+ name="servlet_log"<br>
+ timestamps="true"<br>
+ verbosityLevel = "INFORMATION"<br>
+ path="logs/servlet-${yyyyMMdd}.log"
+ /></td><td> </td>
+ <td>Sets up the "servlet" log output channel.</td></tr>
+ <tr><td><<a href="serverxml.html#LogSetter">LogSetter</a>
+ name="JASPER_LOG"<br>
+ timestamps="true"<br>
+ path="logs/jasper-${yyyyMMdd}.log"<br>
+ verbosityLevel = "INFORMATION" /></td><td> </td>
+ <td>Sets up the Jasper's log output channel.</td></tr>
+ <tr><td><<a href="serverxml.html#WebXmlReader">WebXmlReader</a>
+ validate="true" /></td><td> </td>
+ <td>Reads the <code>web.xml</code> file for each context.</td></tr>
+ <tr><td><<a href="serverxml.html#ErrorHandler">ErrorHandler</a>
+ showDebugInfo="true" /></td><td> </td>
+ <td>Provides error handling for requests that encounter an error.</td></tr>
+ <tr><td><<a href="serverxml.html#WorkDirSetup">WorkDirSetup</a>
+ cleanWorkDir="false" /></td><td> </td>
+ <td>Sets the "work" directory for contexts which don't have the
+ "work" directory set explicitly.</td></tr>
+ <tr><td><<a href="serverxml.html#Jdk12Interceptor">Jdk12Interceptor</a>
+ /></td><td> </td>
+ <td>Insures the proper context classloader is in effect during servlet
+ execution.</td></tr>
+ <tr><td><<a href="serverxml.html#InvokerInterceptor">InvokerInterceptor</a>
+ /></td><td> </td>
+ <td>Handles the "/servlet/<i>class name</i>" legacy method of
+ invoking servlets</td></tr>
+ <tr><td><<a href="serverxml.html#JspInterceptor">JspInterceptor</a>
+ keepGenerated="true"<br>
+ largeFile="false"<br>
+ useJspServlet="false" /></td><td> </td>
+ <td>Handles translation, compilation, and loading of JSP pages.</td></tr>
+ <tr><td><<a href="serverxml.html#StaticInterceptor">StaticInterceptor</a>
+ listings="true"<br>
+ useAcceptLanguage="true"<br>
+ useCharset="locale" /></td><td> </td>
+ <td>Generates the response for requests for static files and directories.<br>
+ <b>Note:</b> The last two attributes were added in Tomcat 3.3.1 to
+ provide improved behavior with the addition of Japanese resource strings.</td></tr>
+ <tr><td><ReloadInterceptor fullReload="true" /></td><td> </td>
+ <td> </td></tr>
+ <tr><td><<a href="serverxml.html#SimpleSessionStore">SimpleSessionStore</a>
+ maxActiveSessions="-1" /></td><td> </td>
+ <td>Creates, stores, and maintains session objects.</td></tr>
+ <tr><td><<a href="serverxml.html#AccessInterceptor">AccessInterceptor</a>
+ /></td><td> </td>
+ <td>Checks if requests require authentication. Provides the basic handling
+ for BASIC and FORM authentication.</td></tr>
+ <tr><td><<a href="serverxml.html#CredentialsInterceptor">CredentialsInterceptor</a>
+ /></td><td> </td>
+ <td>Extracts user name and password information for use by an
+ "authentication" module.</td></tr>
+ <tr><td><<a href="serverxml.html#SimpleRealm">SimpleRealm</a>
+ filename="conf/users/global-users.xml" /></td><td> </td>
+ <td>"authentication" module that checks user name and passwords
+ against data obtained from an XML file. Since this module appears outside
+ of a Context definition, the user names and passwords in the specified
+ file apply to all contexts.</td></tr>
+ <tr><td><<a href="serverxml.html#JDBCRealm">JDBCRealm</a><br>
+ debug="99"<br>
+ driverName="sun.jdbc.odbc.JdbcOdbcDriver"<br>
+ connectionURL="jdbc:odbc:TOMCAT"<br>
+ userTable="users" userNameCol="user_name"<br>
+ userCredCol="user_pass"<br>
+ userRoleTable="user_roles"<br>
+ roleNameCol="role_name" /></td><td>Disabled</td>
+ <td>A replacement for SimpleRealm that reads usernames, passwords, and roles
+ from tables using JDBC.</td></tr>
+ <tr><td><<a href="serverxml.html#LoadOnStartupInterceptor">LoadOnStartupInterceptor</a>
+ /></td><td> </td>
+ <td>Pre-loads servlets indicated as <load-on-startup> in a web.xml
+ file.</td></tr>
+ <tr><td><<a href="serverxml.html#Servlet22Interceptor">Servlet22Interceptor</a>
+ /></td><td> </td>
+ <td>Handles miscellaneous tasks that help implement behavior related to the
+ Servlet 2.2 specification.</td></tr>
+ <tr><td><<a href="serverxml.html#LogSetter">LogSetter</a>
+ name="tag_pool_log" timestamps="true"<br>
+ path="logs/tagpool-${yyyyMMdd}.log"<br>
+ verbosityLevel="INFORMATION" /></td><td>Disabled</td>
+ <td>Sets up the "tag_pool_log" log output channel.</td></tr>
+ <tr><td><<a href="serverxml.html#TagPoolManagerInterceptor">TagPoolManagerInterceptor</a>
+ /></td><td>Disabled</td>
+ <td>Manages a pool of custom tag libary tag objects.</td></tr>
+ <tr><td><<a href="serverxml.html#DecodeInterceptor">DecodeInterceptor</a>
+ /></td><td> </td>
+ <td>Handles the determination of the encoding of a request.</td></tr>
+ <tr><td><<a href="serverxml.html#SessionId">SessionId</a>
+ cookiesFirst="true" noCookies="false" /></td><td> </td>
+ <td>Handles associating sessions with requests and responses.</td></tr>
+ <tr><td><<a href="serverxml.html#ApacheConfig">ApacheConfig</a>
+ noRoot="true" /></td><td> </td>
+ <td>Generates a configuration file for use with <code>mod_jk</code>.</td></tr>
+ <tr><td><<a href="serverxml.html#IISConfig">IISConfig</a>
+ noRoot="true" /></td><td> </td>
+ <td>Generates a configuration file for use with <code>isapi_redirect.dll</code>.</td></tr>
+ <tr><td><<a href="serverxml.html#NSConfig">NSConfig</a>
+ noRoot="true" /></td><td> </td>
+ <td>Generates a configuration file for use with <code>nsapi_redirect</code>.</td></tr>
+ <tr><td><<a href="serverxml.html#AccessLogInterceptor">AccessLogInterceptor</a>
+ /></td><td>Disabled</td>
+ <td>Writes a log file like Apache's AccessLog</td></tr>
+ <tr><td><<a href="serverxml.html#Http10Connector">Http10Connector</a> port="8080"<br>
+ secure="false"<br>
+ maxThreads="100"<br>
+ maxSpareThreads="50"<br>
+ minSpareThreads="10" /></td><td> </td>
+ <td>Handles incoming HTTP requests.</td></tr>
+ <tr><td><<a href="serverxml.html#Http10Connector">Http10Connector</a>
+ port="8443" secure="true" /></td><td>Disabled</td>
+ <td>Handles incoming HTTPS requests.</td></tr>
+ <tr><td><<a href="serverxml.html#JniConnector">JniConnector</a> /></td><td> </td>
+ <td>Handles requests processed by Tomcat running in-process, provided
+ Tomcat was started in-process.</td></tr>
+ <tr><td><<a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
+ port="8007" /></td><td> </td>
+ <td>Handles Ajp12 protocol requests and Tomcat shutdown.</td></tr>
+ <tr><td><<a href="serverxml.html#Ajp13Connector">Ajp13Connector</a>
+ port="8009" /></td><td> </td>
+ <td>Handles Ajp13 protocol requests.</td></tr>
+</table>
+
+<h4><a name="conf_svr_cust">Tomcat Server.xml Customization</a></h4>
+
+<p>The following are some of the more common customizations made to the
+<code>server.xml</code> file.</p>
+
+<ol>
+<li><a href="#cust_chgports">Change ports for Http, Https, and Web Server connectors</a></li>
+<li><a href="#cust_session">Speed up initial session creation for development</a></li>
+<li><a href="#cust_auth">Configure whether Tomcat or a web server does authentication</a></li>
+<li><a href="#cust_dirlist">Turn off directory listings</li>
+<li><a href="#cust_jikes">Use Jikes as the Java compiler</a></li>
+<li><a href="#cust_bind">Bind a connector to a single IP address</a></li>
+<li><a href="#cust_redeploy">Enable redeploying of WAR files</a></li>
+<li><a href="#cust_session">Disable cookie based sessions</a></li>
+</ol>
+
+<hr>
+
+<p>1. <a name="cust_chgports">Change ports for Http or Web Server connectors</a></p>
+
+<p>To change a port, search the <code>server.xml</code> file for the default
+value of the port and change it to the desired value.</p>
+
+<table border="1">
+ <tr><th>Connector</th><th>Default Port</th></tr>
+ <tr><td>Http</td><td>8080</td></tr>
+ <tr><td>Https</td><td>8443</td></tr>
+ <tr><td>Ajp12Connector</td><td>8007</td></tr>
+ <tr><td>Ajp13Connector</td><td>8009</td></tr>
+</table>
+<p>For example:</p>
+<pre>
+ <Http10Connector port="80" secure="false"
+ maxThreads="100" maxSpareThreads="50" minSpareThreads="10" />
+</pre>
+
+<hr>
+
+<p>2. <a name="cust_session">Speed up initial session creation for development</a></p>
+
+<p>The first request that requires a session can incur a delay when the
+<a href="serverxml.html#SessionIdGenerator">SessionIdGenerator</a> initializes
+the random number generator. This delay can be relatively long when using
+the default <code>java.security.SecureRandom</code> class. For development
+purposes, you can speed this up by switching to the <code>java.util.Random</code>
+class. For example:</p>
+<pre>
+ <SessionIdGenerator randomClass="java.util.Random" randomFile="/dev/urandom" />
+</pre>
+<p>You should only use <code>java.util.Random</code> for development
+since the random sequence generated is predictable.</p>
+
+<hr>
+
+<p>3. <a name="cust_auth">Configure whether Tomcat or a web server does authentication</a></p>
+
+<p>When Tomcat is used with a web server, such as Apache, the default is to have
+Tomcat continue to handle authentication. Any authenticated user specified in
+the request forwarded from the web server to Tomcat will be ignored.</p>
+
+<p>If you want Tomcat to make use of the authenticated user provided by
+the web server, add:</p>
+<pre>
+ tomcatAuthentication="false"
+</pre>
+<p>to the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> or
+<a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> as appropriate.
+For example:</p>
+<pre>
+ <Ajp13Connector port="8009" tomcatAuthentication="false" />
+</pre>
+
+<hr>
+
+<p>4. <a name="cust_dirlist">Turn off directory listings</a></p>
+
+<p>To turn off directory listings, change the <code>listings</code> attribute of
+the <a href="serverxml.html#StaticInterceptor">StaticInterceptor</a> to
+<code>false</code>. For example:</p>
+<pre>
+ <StaticInterceptor listings="false" />
+</pre>
+
+<hr>
+
+<p>5. <a name="cust_jikes">Use Jikes as the Java compiler</a></p>
+
+<p>To have Tomcat use Jikes as the Java compiler, add:</p>
+<pre>
+ javaCompiler="jikes"
+</pre>
+<p>to the <a href="serverxml.html#JspInterceptor">JspInterceptor</a>. For example:</p>
+<pre>
+ <JspInterceptor javaCompiler="jikes" />
+</pre>
+
+<p>You may want to also set the <code>jikesClasspath</code> attribute to
+include any jars from the <code>jre/lib/ext</code> extensions directory, or any
+classes or jars not otherwise found in the <code>WEB-INF/classes</code> and
+<code>WEB-INF/lib</code> directories.</p>
+
+<p>If the Jikes executable isn't in your <code>PATH</code> environment
+variable, you will also need to set the <code>jspCompilerPath</code> attribute
+to the full path of the Jikes executable.</p>
+<hr>
+
+<p>6. <a name="cust_bind">Bind a connector to a single IP address</a></p>
+
+<p>By default, the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
+and <a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> will accept
+connections from any IP address. To bind the connector to a single IP address,
+add an <code>address</code> attribute specifying the desired IP address.
+For example:</p>
+<pre>
+ <Ajp13Connector port="8009" address="127.0.0.1" />
+</pre>
+
+<hr>
+
+<p>7. <a name="cust_redeploy">Enable redeploying of WAR files</a></p>
+
+<p>The default behavior is to only deploy a WAR file if the target directory
+doesn't already exists. To enable automatic redeployment of WAR files, add:</p>
+<pre>
+ redeploy="true"
+</pre>
+<p>to the <a href="serverxml.html#AutoDeploy">AutoDeploy</a> with
+<code>source="webapps"</code>. In addition to re-deploying WAR files
+at startup, because a <a href="serverxml.html#ReloadInterceptor">ReloadInterceptor</a>
+is part of the default configuration, WAR files will re-deploy and reload if
+updated while Tomcat is running.</p>
+
+<hr>
+
+<p>8. <a name="cust_session">Disable cookie based sessions</a></p>
+
+<p>To assist with testing a web application against browsers that have
+cookies disabled, you can disable the use of cookie bases sessions. Change the
+<code>noCookies</code> attribute of the <a href="serverxml.html#SessionId">SessionId</a>
+module to <code>true</code>. For example:</p>
+<pre>
+ <SessionId cookiesFirst="true" noCookies="true" />
+</pre>
+
+<hr>
+
+<h4><a name="standard_contexts">Tomcat's Standard Contexts</a></h4>
+
+<p>A context is an instance of a web application's resources being served
+with a unique context path. The default Tomcat 3.3 installation comes with
+three web applications which are served as the following contexts.</p>
+
+<table border="1">
+ <tr><th>Context</th><th>path</th><th>docBase</th><th>WAR File</th><th>Context Config File</th></tr>
+ <tr><td><i>default</i></td><td><i>empty</i>, i.e. ""</td>
+ <td>webapps/ROOT</td><td>ROOT.war</td><td> </td></tr>
+ <tr><td>admin</td><td>/admin</td><td>webapps/admin</td><td>admin.war</td>
+ <td>apps-admin.xml</td></tr>
+ <tr><td>examples</td><td>/examples</td><td>webapps/examples</td>
+ <td>examples.war</td><td>apps-example.xml</td></tr>
+</table>
+
+<p>The <i>default</i> context is the context that will handle requests that
+don't match up with any of the other contexts being served.</p>
+
+<p>Each of these contexts have their WAR file auto-deployed by the
+<a href="serverxml.html#AutoDeploy">AutoDeploy</a> module and the deployed
+directory auto-served by the <a href="serverxml.html#AutoWebApp">AutoWebApp</a>
+module. The <code>apps-admin.xml</code> and <code>apps-example.xml</code>
+files found in the <code>conf</code> directory provide additional configuration
+for the <code>admin</code> and <code>examples</code> contexts, respectively.
+Both configuration files add a local <a href="serverxml.html#SimpleRealm">SimpleRealm</a>
+module which defines additional users that may use the secure portions of
+those contexts. The <code>apps-example.xml</code> also configures local log
+channels for the internal context log and the servlet log.</p>
+
+<p>For the <code>admin</code> context to function properly, you will need
+to update the <code>apps-admin.xml</code> file to set the context's
+<code>trusted</code> attribute to <code>true</code>. You can do this from
+the command line using the "tomcat" script/batch file and the
+<code>enableAdmin</code> action (see
+<a href="#tomcat_actions">tomcat/tomcat.bat Actions</a> for details).
+The <code>trusted</code> attribute is set <code>false</code> by default for
+security reasons. When you change it to <code>true</code>, it is also
+recommended that you change the password in the
+<code>conf/users/admin-users.xml</code> file.</p>
+
+<p>There is an additional context configuration file, named
+<code>apps-127.0.0.1.xml</code>. This file contains a <b>disabled</b> example
+of defining contexts that are associated with a virtual host. In this case, a
+host with a name that matches it's IP address, 127.0.0.1. To enable, uncomment
+the <code>Host</code> element in this file.</p>
+
+<p>Tomcat 3.3 first tries to match a request to a context that has a virtual
+host name that matches the server name in the request. If unable to do so,
+the request will be matched to one of the other contexts, which don't have a
+virtual host associated. Note that this means that contexts associated with a
+virtual host are separate from other contexts not associated with a virtual
+host.</p>
+
+<p>In this virtual host example, the <code><i>default</i></code> and
+<code>examples</code> contexts are swapped. Thus, the URL
+<a href="http://127.0.0.1:8080/examples/">http://127.0.0.1:8080/examples/</a>
+will show you the Tomcat main page instead of the examples directory. The
+URL <a href="http://localhost:8080/examples/">http://localhost:8080/</a>
+would be the normal way to reach the Tomcat main page. To illustrate that
+a context associated with a virtual host is a separate context, you can
+invoke <a href="http://127.0.0.1:8080/jsp/security/protected/index.jsp">
+http://127.0.0.1:8080/jsp/security/protected/index.jsp</a> in your browser.
+Since this, <i>default</i>, context is serving the "examples" web
+application, but without an additional <a href="serverxml.html#SimpleRealm">SimpleRealm</a>
+defined, only the "global user" <code>root</code> (defined by
+the SimpleRealm in <code>server.xml</code>) can login.</p>
+
+<h4><a name="context_addcust">Adding and Customizing Contexts</a></h4>
+
+<p>To serve a context, Tomcat 3.3 requires a directory that contains the
+resources for the context. This directory must match the structure and
+requirements defined for a web application. Once this directory exists,
+it may be served as a context using one or both of the following mechanisms.</p>
+
+<ol>
+ <li>Specify the context in a context configuration file read by a
+ <a href="serverxml.html#ContextXmlReader">ContextXmlReader</a> module.
+ This module will read a specified context configuration file, if it
+ exists, and all files with an associated pattern. The default Tomcat 3.3
+ installation has a ContextXmlReader that reads the "apps.xml" file.
+ Though this file doesn't exist, the associated pattern is
+ <code>"apps-*.xml"</code> which picks up the
+ <code>apps-admin.xml</code>, <code>apps-example.xml</code>, and
+ <code>apps-127.0.0.1</code>. You can create an <code>apps.xml</code>
+ or <code>apps-myapps.xml</code> file, for example, to add your own context
+ definitions.<br><br></li>
+ <li>If the context's directory is a subdirectory of an directory
+ named in an <a href="serverxml.html#AutoWebApp">AutoWebApp</a> module,
+ it will be served using the context's directory name as the context path.
+ The default installation of Tomcat 3.3 has one such AutoWebApp module
+ which serves subdirectories of Tomcat's <code>webapps</code> directory.
+ The contexts served in this manner will receive the default context
+ settings unless overridden by a context configuration file for that
+ context.<br>
+ <br>
+ <b>Note:</b> The AutoWebApp module which serves the <code>modules</code>
+ directory is reserved for Tomcat Add-on modules and should not be used
+ for serving contexts.</li>
+</ol>
+
+<p>The format of context configuration files differs depending on whether
+the context is for the default host or a virtual host. For contexts not
+associated with a virtual host, use:</p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<webapps>
+ <Context ... >
+ <<i>local_module</i> ... />
+ ...
+ </Context>
+ ...
+</webapps>
+</pre>
+
+<p>For contexts that are to be associated with virtual hosts, use:</p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<Server>
+ <Host ... >
+ <Alias ... />
+ <Context ... >
+ <<i>local_module</i> ... />
+ ...
+ </Context>
+ ...
+ </Host>
+ ...
+</Server>
+</pre>
+
+<p>The following table provides the attributes available on these elements.</p>
+
+<table border="1">
+ <tr valign="top"><th>Element</th><th>Attribute</th><th>Description</th><th>Default</th></tr>
+ <tr valign="top"><td>Context</td><td>path</td>
+ <td>The URL fragment to use to identify this context. This is a required
+ attribute.</td>
+ <td><i>none, must be specified</i></td></tr>
+ <tr valign="top"><td> </td><td>docBase</td>
+ <td>Path to the directory containing the web application's resources for
+ the context. This is a required attribute.</td>
+ <td><i>none, must be specified</i></td></tr>
+ <tr valign="top"><td> </td><td>reloadable</td><td>Enables reloading of
+ servlets for this context.</td><td>true</td></tr>
+ <tr valign="top"><td> </td><td>trusted</td><td>Controls whether the
+ context is "trusted". If "trusted", the
+ <code>Webapp Classloader's</code> parent will be the
+ <code>Server Classloader</code> rather than the <code>Apps Classloader</code>.
+ This gives the context access to classes in the Tomcat server instance.
+ </td><td>false</td></tr>
+ <tr valign="top"><td> </td><td>debug</td><td>Debug level for logging</td><td>0</td></tr>
+ <tr valign="top"><td>Host</td><td>name</td><td>Name of the virtual host. This is a
+ required attribute.</td>
+ <td><i>none, must be specified</i></td></tr>
+ <tr valign="top"><td> </td><td>address</td><td>IP address for this virtual host. This
+ attribute is optional. Currently, this attribute only affects how the
+ <a href="serverxml.html#ApacheConfig">ApacheConfig</a> module writes the
+ configuration file.</td>
+ <td><i>none, must be specified.</i></td></tr>
+ <tr valign="top"><td>Alias</td><td>name</td><td>Name of the virtual host alias.<br>
+ <b>Note:</b> All <code>Alias</code> specifications must come before any
+ <code>Context</code> declarations.</td><td><i>none, must be specified</i></td></tr>
+</table>
+
+<p>In Tomcat 3.3.1, each attribute value may use the ant-style variable
+substitution by using "${<i>variable</i>}" in the attribute string, i.e.
+<i>attribute</i>="<i>text</i>${<i>variable</i>}<i>text</i>".</p>
+
+<p>The <i>variable</i> must specify a Context property, a ContextManager
+property, or System property. The Context properties take precedence, followed
+by ContextManager propertiers, and finally System properties. If a matching
+property isn't found, the attribute string is left as is. Note that properties
+are not the same as attributes, and attributes are not accessible via
+"variable substitution".</p>
+
+<p><a name="context_prop"></a>There are two methods for setting Context properties.</p>
+
+<ol>
+ <li>Include a <code><i>name</i>="<i>value</i>"</code>
+ specification on the Context element, where <i>name</i> doesn't correspond
+ to a Context attribute. For example:<br>
+ <pre> <Context ... my.prop="myvalue" ... ></pre></li>
+ <li>Include a <code>Property</code> element within the scope of the
+ Context element. For example:<br>
+ <pre>
+ <Context ... >
+ <Property name="my.prop" value="myvalue" />
+ ...
+ </Context></pre>
+ This form of setting properties is logged if the Context's debug
+ level is one or greater.<br><br></li>
+</ol>
+
+<p><b>Note:</b> The property values may themselves use "variable
+substitution", provided the specified property is already defined.</p>
+
+<p>Currently the <a href="serverxml.html#SimpleRealm">SimpleRealm</a>,
+<a href="serverxml.html#JDBCRealm">JDBCRealm</a>, and
+<a href="serverxml.html#LogSetter">Logsetter</a> modules are known to work
+successfully as "context local" modules. Other modules that can
+be used as "context local" modules and would be useful have yet to
+be identified.</p>
+
+<p>To add, or remove, a context while Tomcat 3.3 is running, use the Admin
+web application provided in the <code>admin</code> context. Note that the
+<code>admin</code> context must be "trusted" before it can perform
+the admin functions successfully.</p>
+
+<h4><a name="deploy_war">Deploying WAR Files</a></h4>
+
+<p>The Servlet 2.2 specification introduced the Web Application Archive, or WAR
+file. A WAR file is the deployable version of a web application, where the
+directory structure and the files they contain are combined into an archive file.</p>
+
+<p>To deploy a WAR file to Tomcat 3.3, you can manually expand the archive to a
+directory and have that directory served as a context as described above. You
+can also have the <a href="serverxml.html#AutoDeploy">AutoDeploy</a> module
+do the expansion automatically if the WAR file is placed in its "source"
+directory. The default installation of Tomcat 3.3 includes an AutoDeploy
+module which expands WAR files found in Tomcat's <code>webapps</code>
+directory.</p>
+
+<p>To add a WAR file while Tomcat 3.3 is running, you will need to manually
+expand the WAR file. Then use the Admin web application to add the
+context.</p>
+
+<hr size="5">
+
+<h2><a name="real_world_tips">Real World Configuration Tips</a></h2>
+
+<p>By default the Tomcat distribution comes with a naive
+ configuration whose main goal is to promote first time
+ user experience and an "out of the box" operation...
+ This configuration however is not the best way to deploy
+ Tomcat on real sites. For example, real sites may
+ require some performance tuning and site-specific
+ settings (additional path elements for example). This
+ section will try to get you started by directing you to
+ the first steps that should be taken before publishing a
+ Tomcat based site.</p>
+
+<h3>Modify and Customize the Batch Files</h3>
+
+<p>As stated in the previous sections, the startup scripts are
+ here for your convenience. Yet, sometimes the scripts
+ that are needed for deployment should be modified:</p>
+
+<ul>
+ <li> To set resource limits such as maximum number of
+ descriptors. </li>
+ <li> To add new PATH/LD_LIBRARY_PATH entries (for example, JDBC
+ drivers DLLs). </li>
+ <li> To modify the JVM command line settings. </li>
+ <li> Make sure that you are using a specific JVM (out of the two
+ or three JVMs installed on your machine). </li>
+ <li> To switch user from root to some other user using the "su"
+ UNIX command. </li>
+ <li> Your pet reason. </li>
+</ul>
+
+<p>Some of these changes can be done without explicit changes to
+ the basic scripts; for example, the tomcat script can
+ use an environment variable named <tt>TOMCAT_OPTS</tt>
+ to set extra command line parameters to the JVM (such as
+ memory setting etc.). On <em>UNIX</em> you can also
+ create a file named <tt>".tomcatrc"</tt> in your home
+ directory and Tomcat will take environment information
+ such as PATH, JAVA_HOME, TOMCAT_HOME and TOMCAT_INSTALL from
+ this file. On NT however (and also on UNIX when the
+ modifications are for something such as the JVM command
+ line) you are forced to rewrite some of the startup
+ script...</p>
+
+<div><strong>Do not hesitate, just do it.</strong></div>
+
+<h3>Modify the Default JVM Settings</h3>
+
+<p>The default JVM settings in the tomcat script are very
+ naïve; everything is left for defaults. There are a
+ few things that you should consider to improve your
+ Tomcat performance:</p>
+
+ <ol>
+ <li> Modify your JVM memory configuration. Normally the JVM
+ allocates an initial size for the Java heap and that's it, if
+ you need more then this amount of memory you will not get it.<br>
+ Nevertheless, in loaded sites, giving more memory to the JVM
+ improves Tomcat's performance. You should use command line
+ parameters such as -Xms/-Xmx/-ms/-mx to set the minimum/maximum
+ size of the Java heap (and check to see if the performance was
+ improved). </li>
+
+ <li> Modify your JVM threading configuration. The SUN JDK1.2.2 for
+ Linux comes with support for both, green and native threads. In
+ general native threads are known to provide improved performance
+ for I/O bound applications, green threads on the other hand put
+ less stress on the machine. You should experiment with these two
+ threading models and see which model is better for your site (in
+ general, native threads are better).</li>
+
+ <li> Select the best JVM for the task. If your application
+ does not require a specific JDK functionality, you should
+ benchmark the two JVMs and select the better one.</li>
+ </ol>
+
[... 63 lines stripped ...]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org