You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by al...@locus.apache.org on 2000/08/26 00:13:13 UTC
cvs commit: jakarta-tomcat/src/doc index.html mod_jk-howto.html tomcat-ug.html
alex 00/08/25 15:13:12
Modified: src/doc index.html mod_jk-howto.html tomcat-ug.html
Log:
Rolled back glenn's change. Please do not edit this file with Netscape/Mozilla -- it totally messes up the HTML, adds s everywhere, and messes up version control.
Also, it seems to mess up the image links (should be images/banner.gif, turned into banner.gif)
Replaced list of other documents with a pointer to index.html
If you add a document to this directory, please add a link inside index.html
Cleaned up index.html list
used good styles.css file in mod_jk
Revision Changes Path
1.4 +16 -22 jakarta-tomcat/src/doc/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/index.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- index.html 2000/08/17 21:05:54 1.3
+++ index.html 2000/08/25 22:13:09 1.4
@@ -1,7 +1,7 @@
<html>
<head>
- <!-- $Id: index.html,v 1.3 2000/08/17 21:05:54 alex Exp $ -->
+ <!-- $Id: index.html,v 1.4 2000/08/25 22:13:09 alex Exp $ -->
<!-- Copyright 1999, Apache Software Foundation -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="style.css">
@@ -28,36 +28,30 @@
<h1>Tomcat Documentation</h1>
<ul>
+
<li> <A HREF="tomcat-ug.html">Tomcat User's Guide</A>
</li>
<li> <A HREF="appdev/contents.html">Application Development manual</A> -
an alternative to the User's Guide, by Craig McClanahan, somewhat
out of date
-</li>
-<li> <A HREF="tomcat-apache-howto.html">tomcat-apache-howto.html</A>
-</li>
-<li> <A HREF="mod_jk-howto.html">mod_jk-howto.html</A>
-</li>
-<li> <A HREF="tomcat-iis-howto.html">tomcat-iis-howto.html</A>
</li>
-<li> <A HREF="tomcat-netscape-howto.html">tomcat-netscape-howto.html</A>
-</li>
-<li> <A HREF="tomcat_security.txt">tomcat_security.txt</A>
-</li>
+
<li> <A HREF="faq">faq</A> [obsolete?]
</li>
-<li> <A HREF="NT-Service-howto.html">NT-Service-howto.html</A>
+<li> <A HREF="readme">Tomcat 3.1 readme</A> [obsolete?]
</li>
-<li> <A HREF="Tomcat-Workers-HowTo.html">Tomcat-Workers-HowTo.html</A>
-</li>
-<li> <A HREF="in-process-howto.html">in-process-howto.html</A>
-</li>
-<li> <A HREF="JDBCRealm.howto">JDBCRealm.howto</A>
-</li>
-<li> <A HREF="internal.html">Tomcat Internals doc</A>
-</li>
-<li> <A HREF="readme">Tomcat 3.1 readme</A>
-</li>
+
+<li><a href="tomcat-apache-howto.html">Tomcat-Apache HOWTO</a></li>
+<li><a href="mod_jk-howto.html">mod_jk HOWTO</a> [??? should be rolled into tomcat-apache howto]</li>
+<li><a href="tomcat-iis-howto.html">Tomcat-IIS HOWTO</a></li>
+<li><a href="tomcat-netscape-howto.html">Tomcat-Netscape HOWTO</a></li>
+<li><a href="tomcat-security.html">Using the Java SecurityManager with Tomcat</a></li>
+<li><a href="JDBCRealm.howto">JDBC Realm HOWTO</a></li>
+<li><a href="NT-Service-howto.html">NT Service HOWTO</a></li>
+<li><a href="Tomcat-Workers-HowTo.html">Tomcat Workers HOWTO</a></li>
+<li><a href="in-process-howto.html">In-process HOWTO</a></li>
+<li><a href="internal.html">Tomcat Internals documentation</a></li>
+
</ul>
</body>
1.2 +1 -1 jakarta-tomcat/src/doc/mod_jk-howto.html
Index: mod_jk-howto.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/mod_jk-howto.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- mod_jk-howto.html 2000/06/20 08:12:35 1.1
+++ mod_jk-howto.html 2000/08/25 22:13:09 1.2
@@ -4,7 +4,7 @@
<!-- Copyright 1999, Apache Software Foundation -->
<meta http-equiv=Content-Type content="text/html">
- <link rel="stylesheet" href=uguide/style.css>
+ <link rel="stylesheet" href="style.css">
<style type="text/css">
td {
background-color: #E0E0E0;
1.4 +1314 -1319jakarta-tomcat/src/doc/tomcat-ug.html
Index: tomcat-ug.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/tomcat-ug.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- tomcat-ug.html 2000/08/24 22:00:50 1.3
+++ tomcat-ug.html 2000/08/25 22:13:09 1.4
@@ -1,979 +1,933 @@
-<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
-<html>
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; I; SunOS 5.7 i86pc) [Netscape]">
- <title>Tomcat User's Guide</title>
-<!-- $Id: tomcat-ug.html,v 1.3 2000/08/24 22:00:50 glenn Exp $ -->
-<!-- Copyright 1999, Apache Software Foundation -->
-<link rel="stylesheet" href="style.css">
-<!-- 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 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" >
-<tr>
-<td WIDTH="50%"><a href="http://jakarta.apache.org/index.html"><img SRC="banner.gif" ALT="The Jakarta Project" BORDER=0 height=100 width=350></a></td>
-
-<td WIDTH="50%">
-<div align=right><img SRC="tomcat.gif" ALT="The mighty Tomcat - Meow!" BORDER=0 height=71 width=100></div>
-</td>
-</tr>
-</table>
-
-<h1>
-Tomcat User's Guide</h1>
-This document is an introduction to the Tomcat servlet container. It should
-be enough for anyone to install, configure, and deploy Tomcat. As well,
-it answers many questions common to new users. We encourage all users to
-add answers to questions into the <a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat
-FAQ</a> and/or this document, if they don't already exist. 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/getinvolved/mail.html">mailing
-lists</a>.
-<p>This document began life as <i>Tomcat: A Minimalistic User's Guide</i>
-by Gal Shachor, and has been revised by many others. It should be considered
-a <b>work in progress</b>. Since the Tomcat source tree is constantly changing,
-the information herein may be out of date. The only definitive reference
-at this point is the <a href="http://jakarta.apache.org/downloads/sourceindex.html">source
-code</a>.
-<p>"???" means I'm not sure if this should go in, or where it should go
-or be referred to as, if it does indeed belong. Other editorial comments
-are surrounded in [square brackets].
-<p>Other important documents:
-<ul>
-<li>
-<a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</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>
-<a href="tomcat-apache-howto.html">Tomcat-Apache HOWTO</a></li>
-
-<li>
-<a href="mod_jk-howto.html">mod_jk HOWTO</a> [??? should be rolled into
-tomcat-apache howto]</li>
-
-<li>
-<a href="tomcat-iis-howto.html">Tomcat-IIS HOWTO</a></li>
-
-<li>
-<a href="tomcat-netscape-howto.html">Tomcat-Netscape HOWTO</a></li>
-
-<li>
-<a href="tomcat_security.txt">Using the Java SecurityManager with Tomcat</a></li>
-
-<li>
-<a href="JDBCRealm.howto">JDBC Realm HOWTO</a></li>
-
-<li>
-<a href="NT-Service-howto.html">NT Service HOWTO</a></li>
-
-<li>
-<a href="Tomcat-Workers-HowTo.html">Tomcat Workers HOWTO</a></li>
-
-<li>
-<a href="in-process-howto.html">In-process HOWTO</a></li>
-
-<li>
-<a href="internal.html">Tomcat Internals documentation</a></li>
-</ul>
-
-<h3>
-Table of Contents</h3>
-[This section needs to be revised to match current outline. Wouldn't it
-be nice if we used XSL to generate this file from an XML source?]
-<ul>
-<li>
-<a href="#about_tomcat">About Tomcat</a></li>
-
-<br> <a href="#what_is_tomcat">What is Tomcat?</a>
-<br> <a href="#where_download">Where can I download Tomcat?</a>
-<br> <a href="#just_jserv">Isn't Tomcat just JServ?</a>
-<br> <a href="#what_servlets_jsps">What are servlets?
-What are JSPs?</a>
-<br> <a href="#contribute">How do/can I contribute?</a>
-<br> <a href="#where_help">How come X, Y, or Z isn't
-working? Help!</a>
-<br>
-<li>
-<a href="#installing_tomcat">Installing Tomcat</a></li>
-
-<br> <a href="#file_placement">File placement and environment
-setup</a>
-<br> <a href="#starting_and_stopping">Starting and stopping
-Tomcat</a>
-<br> <a href="#starting_another_dir">Starting multiple
-instances w/individual server.xml files</a>
-<br> <a href="#directory_structure">Tomcat directory
-structure</a>
-<br> <a href="#tomcat_scripts">Tomcat scripts</a>
-<br>
-<li>
-<a href="#configuring_tomcat">Configuring Tomcat</a></li>
-
-<br> <a href="#container_types">Types of servlet containers</a>
-<br> <a href="#server_xml">server.xml - Tomcat's main
-configuration file</a>
-<br> <a href="#web_xml">web.xml - Default deployment
-descriptor</a>
-<br> <a href="tomcat-security.html">Using the Java SecurityManager
-with Tomcat</a>
-<br> Web application/context security and authorization
-<br> tomcat-users.xml
-<br> JDBC realms
-<br>
-<li>
-<a href="#webapps">Deploying Web Applications</a></li>
-
-<br> <a href="#webapp">What is a Web Application?</a>
-<br> <a href="#what_is_war">What is a WAR file?</a>
-<br> <a href="#deploying_war">Deploying WAR files in
-Tomcat</a>
-<br>
-<li>
-<a href="#tutorials">Tomcat Tutorials</a> - ???</li>
-
-<br> Deploying application
-<br> Creating your first web application ???
-<br> Creating and configuring your first servlet ???
-<br>
-<li>
-<a href="#real_world_tips">Real World Configuration Tips</a></li>
-
-<br>
-<li>
-<a href="#common_errors">Common Installation and Configuration Problems</a></li>
-
-<br> <a href="#error_bad_command">"Bad command or filename"
-when executing Tomcat scripts</a>
-<br> <a href="#error_8007">http://webserver:8007/ gives
-an HTTP 500</a>
-<br> <a href="#error_ignore_directives">Apache <Directory>
-and <Location> directives ignored</a>
-<br> <a href="#error_web_server">Web server won't start
-when Tomcat is running</a>
-<br>
-<li>
-<a href="#credits">Credits</a></li>
-</ul>
-
-<hr size="5">
-<h3>
-<a NAME="about_tomcat"></a>About Tomcat</h3>
-See also the official <a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat
-FAQ</a>.
-<h4>
- <a NAME="what_is_tomcat"></a>What is Tomcat?</h4>
-
-<blockquote>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.</blockquote>
-
-<h4>
- <a NAME="where_download"></a>Where can I download Tomcat?</h4>
-
-<blockquote>At the <a href="http://jakarta.apache.org/downloads/binindex.html">Jakarta
-download page</a>!</blockquote>
-
-<h4>
- <a NAME="just_jserv"></a>Isn't Tomcat just JServ?</h4>
-
-<blockquote>This is a common misunderstanding. <a href="http://java.apache.org/jserv">JServ</a>
-is a Servlet API 2.0-compliant container that was created to be used with
-Apache. Tomcat is a complete re-write and is a Servlet API 2.2 and JSP
-1.1-compliant container. Tomcat uses some of the code written for JServ,
-especially JServ's Apache server adapter, but this is where the similarities
-end.</blockquote>
-
-<h4>
- <a NAME="what_servlets_jsps"></a>What are servlets? What are JSPs?</h4>
-
-<blockquote>In a nutshell, servlets are memory-resident Java programs,
-running inside a servlet container (e.g. 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>:
-<blockquote>"The <b>Java<sup><font size=-2>TM</font></sup> Servlet API</b>
-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>
-...and about JSPs (JavaServer Pages), again from <a href="http://java.sun.com/products/servlet/">Sun's
-servlet site</a>:
-<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>
-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>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. <b>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!</b></blockquote>
-
-<h4>
- <a NAME="contribute"></a>How do/can I contribute?</h4>
-
-<blockquote>Please do! See the Jakarta project contribution page, right
-<a href="http://jakarta.apache.org/getinvolved/getinvolvedindex.html">here</a>.
-You'll probably want to <a href="mailto:tomcat-dev-subscribe@jakarta.apache.org">subscribe</a>
-to the <b>tomcat-dev</b> mailing list.</blockquote>
-
-<h4>
- <a NAME="where_help"></a>How come X, Y, or Z isn't working? Help!</h4>
-
-<blockquote>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>
-The <a href="#common_errors">Common problems</a> section of this document.</li>
-
-<li>
-Have a look through the <a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat
-FAQ</a>. Most installation and configuration questions can be found here.</li>
-
-<li>
-Search the Tomcat <a href="http://mikal.org/interests/java/tomcat/index.html">user</a>
-and <a href="http://www.metronet.com/~wjm/tomcat/">developer</a> list archives.</li>
-
-<li>
-Post a question to the <b>tomcat-user</b> <a href="http://jakarta.apache.org/getinvolved/mail.html">mailing
-list</a>, which you must first <a href="mailto:tomcat-user-subscribe@jakarta.apache.org">subscribe</a>
-to if you'd like to see any replies!</li>
-</ol>
-</blockquote>
-
-<hr size="5">
-<h3>
-<a NAME="installing_tomcat"></a>Installing Tomcat</h3>
-
-<h4>
- <a NAME="file_placement"></a>File placement and environment setup</h4>
-
-<blockquote>
-<ul>
-<li>
-<a href="http://jakarta.apache.org/downloads/binindex.html">Download</a>
-the appropriate jakarta-tomcat [.zip | .gz | .Z] file.</li>
-
-<li>
-Unzip the file into some directory (say /usr/local or C:\). This should
-create a new subdirectory named "tomcat". [Does it still create "jakarta-tomcat"
-instead? If so, just rename it "tomcat".]</li>
-
-<li>
-Change directory to "tomcat" and set a new environment variable (<a NAME="tomcat_home_env"></a>TOMCAT_HOME)
-to point to the root directory of your Tomcat hierarchy. The exact directory
-may change from system to system; check your local filesystem to be sure
-where Tomcat is installed.</li>
-
-<ol>
-<li>
-On Win32 systems you should type:</li>
-
-<br><tt><font size=+1>set TOMCAT_HOME=c:\tomcat</font></tt>
-<li>
-On UNIX (using bash/sh) you should type:</li>
-
-<br><tt><font size=+1>TOMCAT_HOME=/usr/local/tomcat ; export TOMCAT_HOME</font></tt>
-<li>
-On UNIX (using tcsh) you should type:</li>
-
-<br><tt><font size=+1>setenv TOMCAT_HOME=/usr/local/tomcat</font></tt></ol>
-
-<li>
-Set the environment variable JAVA_HOME to point to the root directory of
-your JDK hierarchy, then add the Java interpreter to your PATH environment
-variable. The exact directory may change from system to system; check your
-local filesystem to be sure where Java is installed.</li>
-<ol>
-<li>
-Win32:</li>
-
-<br><tt><font size=+1>set JAVA_HOME=c:/jdk1.2</font></tt>
-<br><tt><font size=+1>set PATH=%PATH%;%JAVA_HOME%\bin</font></tt>
-<li>
-Unix (bash/sh):</li>
-
-<br><tt><font size=+1>set JAVA_HOME=/user/local/java/jdk1.2; export JAVA_HOME</font></tt>
-<br><tt><font size=+1>set PATH=$PATH:$JAVA_HOME/bin; export PATH</font></tt>
-<li>
-Unix (tcsh):</li>
-
-<br><tt><font size=+1>setenv JAVA_HOME=/user/local/java/jdk1.2</font></tt>
-<br><tt><font size=+1>setenv PATH=$PATH:$JAVA_HOME/bin</font></tt></ol>
-</ul>
-That's it! You can now <a href="#starting_and_stopping">execute Tomcat</a>
-and it will run as a <a href="#type_1">stand-alone</a> servlet container.
-<p>Once you're sure they work, these environment variables should probably
-be set in a config file: C:/AUTOEXEC.BAT for Windows, ~/bash_profile or
-~/[what is it for tcsh?]</blockquote>
-
-<h4>
- <a NAME="starting_and_stopping"></a>Starting and stopping Tomcat</h4>
-
-<blockquote>You start and stop Tomcat using the scripts in the bin subdirectory
-of <a href="#tomcat_home_env">TOMCAT_HOME</a>.
-<p>To start Tomcat execute:
-<blockquote style="margin-right: 0px">On UNIX: bin/startup.sh
-<p>On Win32: bin\startup</blockquote>
-To stop Tomcat execute:
-<blockquote style="margin-right: 0px">On UNIX: bin/shutdown.sh
-<p>On Win32: bin\shutdown</blockquote>
-</blockquote>
-
-<h4>
- <a NAME="starting_another_dir"></a>Starting multiple instances with
-individual server.xml files</h4>
-
-<blockquote>This might not make a whole lot of sense until you read the
-next section explaining Tomcat's <a href="#directory_structure">directory
-structure</a>, as well as <a href="#configuring_tomcat">Configuring Tomcat</a>.
-You may want to come back here afterwards.
-<p>By default, Tomcat will use TOMCAT_HOME/conf/server.xml for configuration,
-which by default, uses TOMCAT_HOME as its base for the contexts. You can
-change this by using the "-f /path/to/server.xml" option, with a different
-server configuration file and setting the home attribute of the <a href="#context_manager_element">ContextManager</a>
-element. You need to set up the required files inside the home:
-<ul>
-<li>
-webapps/ - all war files will be expanded and all subdirectories added
-as contexts.</li>
-
-<li>
-conf/ directory - you can store a special web.xml and other configuration
-files.</li>
-
-<li>
-logs/ - all logs will go to this directory instead of the main TOMCAT_HOME/logs/.</li>
-
-<li>
-work/ - work directories for the contexts.</li>
+<html>
+ <head>
+ <!-- $Id: tomcat-ug.html,v 1.4 2000/08/25 22:13:09 alex Exp $ -->
+ <!-- Copyright 1999, Apache Software Foundation -->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" 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%">
+ <p align="left">
+ <a href="http://jakarta.apache.org/index.html">
+ <img src="images/banner.gif"
+ width="350"
+ height="100"
+ alt="The Jakarta Project"
+ border="0"></a>
+ </td>
+ <td width="50%">
+ <p align="right"><img border="0" src="images/tomcat.gif" width="100" height="71" alt="The mighty Tomcat - Meow!"></p>
+ </td>
+ </tr>
+ </table>
+
+ <H1>Tomcat User's Guide</H1>
+ <p>This document is an introduction to the Tomcat servlet container.
+ It should be enough for anyone to install, configure, and deploy
+ Tomcat. As well, it answers many questions common to new users. We encourage all users to add answers to questions into the
+ <a href="http://jakarta.apache.org/faq/faqindex.html">
+ Tomcat FAQ</a> and/or this document, if they don't already exist.
+ 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/getinvolved/mail.html">mailing lists</a>.
+
+ <p>This document began life as <i>Tomcat: A Minimalistic User's
+ Guide</i> by Gal Shachor, and has been revised by many others.
+ It should be considered a <b>work in progress</b>. Since the
+ Tomcat source tree is constantly changing, the information
+ herein may be out of date. The only definitive reference at
+ this point is the <a
+ href="http://jakarta.apache.org/downloads/sourceindex.html">source
+ code</a>.</p>
+
+
+ <p>"???" means I'm not sure if this should go in, or
+ where it should go or be referred to as, if it does indeed
+ belong. Other editorial comments are surrounded in [square brackets].
+ </p>
+
+ <p>
+ Other important documents: <ul>
+<li><a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</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>
-If the home attribute of the ContextManager element in server.xml is relative,
-it will be relative to the current working directory.</blockquote>
-
-<h4>
- <a NAME="directory_structure"></a>The Tomcat directory structure</h4>
-
-<blockquote>Assuming you extracted the Tomcat binary distribution you should
-have the following directory structure under <a href="#tomcat_home_env">TOMCAT_HOME</a>:
-<br>
-<table BORDER WIDTH="75%" valign="MIDDLE" >
-<tr>
-<th WIDTH="15%" BGCOLOR="#C0C0C0">Directory</th>
-
-<th WIDTH="85%" BGCOLOR="#C0C0C0">Contents</th>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">bin </td>
-
-<td WIDTH="85%">Startup/shutdown scripts and other useful files.</td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">conf </td>
-
-<td WIDTH="85%">Configuration files including <a href="#server_xml">server.xml</a>
-(Tomcat's main configuration file) and <a href="#web_xml">web.xml</a> (default
-values for the various web applications deployed in Tomcat.). </td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">doc </td>
-
-<td WIDTH="85%">Miscellaneous documents regarding Tomcat.</td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">lib </td>
-
-<td WIDTH="85%">Various jar files that are used by Tomcat. Any file in
-this directory is appended to Tomcat's classpath. </td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%"><a NAME="logs_dir_defn"></a>logs</td>
-
-<td WIDTH="85%">This is where Tomcat places its log files by default.</td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">src </td>
-
-<td WIDTH="85%">The servlet API source files. Don't get excited, though;
-these are only the empty interfaces and abstract classes that should be
-implemented by any servlet container.</td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">webapps </td>
-
-<td WIDTH="85%">Sample web applications. Any .war files placed here will
-be automatically expanded. See <a href="#deploying_war">Deploying WAR files</a>. </td>
-</tr>
-</table>
-
-<p>Additionally you can, or Tomcat will, create the following directories:
-<br>
-<table BORDER WIDTH="75%" VALIGN="MIDDLE" >
-<tr>
-<td ALIGN=CENTER WIDTH="15%"><a NAME="work_dir_defn"></a>work</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 ALIGN=CENTER WIDTH="15%">classes </td>
-
-<td WIDTH="85%">Any class that you add to this directory will find its
-place in Tomcat's classpath. </td>
-</tr>
-</table>
-</blockquote>
-
-<h4>
- <a NAME="tomcat_scripts"></a>Tomcat scripts</h4>
-
-<blockquote>This section is not required reading, as the default functionality
-provided by the aforementioned startup and shutdown scripts is sufficient
-for most users to get started. If everything is working so far, skip ahead
-to <a href="#configuring_tomcat">Configuring Tomcat</a>. Come back to this
-section when you'd like more information on these scripts, which you undoubtedly
-will.
-<p>Tomcat is a Java program, and therefore it is possible to execute it
-from the command line, after setting several environment variables. However,
-setting each environment variable and following the command line parameters
-used by Tomcat is error prone and tedious. Instead, the Tomcat development
-team provides a few scripts to ease starting and stopping Tomcat.
-<p><b>Note: The scripts are only a convenient way to start/stop. You can
-modify them to customize the CLASSPATH, environment variables such as PATH
-and LD_LIBRARY_PATH, etc., so long as a correct command line is generated
-for Tomcat.</b>
-<p>The following table presents the scripts that are most important for
-the common user:
-<br>
-<table BORDER WIDTH="75%" valign="MIDDLE" >
-<tr>
-<th WIDTH="15%" BGCOLOR="#C0C0C0">Script name </th>
-
-<th WIDTH="85%" BGCOLOR="#C0C0C0">Description </th>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">tomcat </td>
-
-<td WIDTH="85%">The main script. Sets the proper environment, including
-CLASSPATH, TOMCAT_HOME and JAVA_HOME, and starts Tomcat with the proper
-command line parameters.</td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">startup </td>
-
-<td WIDTH="85%">Starts tomcat in the background. Shortcut for "tomcat start" </td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">shutdown </td>
-
-<td WIDTH="85%">Stops tomcat (shutting it down). Shortcut for "tomcat stop" </td>
-</tr>
-</table>
-
-<p>The script which has the most significance for users is tomcat (tomcat.sh/tomcat.bat).
-The other Tomcat related scripts serve as a simplified single-task oriented
-entry point to the tomcat script (set different command line parameters
-etc.).</blockquote>
-
-<h4>
- <a NAME="tomcat_scripts_closer"></a>Tomcat scripts: a closer look</h4>
-
-<blockquote>A closer look at tomcat.sh/tomcat.bat yields that it performs
-the following actions:
-<p>These behaviors, especially CLASSPATH setting, have changed with Tomcat
-3.2. It is best to look directly at the scripts for details on what variables
-are set and what class files are loaded. [??? - delete entire section pending
-reexamination?]
-<br>
-<table BORDER WIDTH="75%" valign="MIDDLE" >
-<tr>
-<th WIDTH="15%" BGCOLOR="#C0C0C0">Operating System </th>
-
-<th WIDTH="85%" BGCOLOR="#C0C0C0">Actions </th>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">Unix </td>
-
-<td WIDTH="85%">
-<ul>
-<li>
-Guessing what is TOMCAT_HOME if it is not specified. </li>
-
-<li>
-Guessing what is JAVA_HOME if it is not specified. </li>
-
-<li>
-Setting up a CLASSPATH that contains - </li>
-
-<ol>
-<li>
-The ${TOMCAT_HOME}/classes directory (if available).</li>
-
-<li>
-All the contents of ${TOMCAT_HOME}/lib. </li>
-
-<li>
-${JAVA_HOME}/lib/tools.jar (this jar file contains the tool javac, we need
-javac for jsp files).</li>
-</ol>
-
-<li>
-Executes java with command line parameters that set up a java system environment,
-called tomcat.home, with org.apache.tomcat.startup.Tomcat as the startup
-class. It also passes command line parameters to org.apache.tomcat.startup.Tomcat,
-such as: </li>
-
-<ol>
-<li>
-The operation to perform start/stop/run/etc. </li>
-
-<li>
-A path to the server.xml used by this Tomcat process. </li>
-</ol>
-For example if server.xml is located in /etc/server_1.xml and the user
-wants to start apache in the background they should provide the following
-command line: bin/tomcat.sh start -f /etc/server_1.xml</ul>
-</td>
-</tr>
-
-<tr>
-<td ALIGN=CENTER WIDTH="15%">Win32 </td>
+ </p>
-<td WIDTH="85%">
-<ul>
-<li>
-Setting up a CLASSPATH that contains - </li>
-
-<ol>
-<li>
-servlet.jar, webserver.jar, jasper.jar, xml.jar from the %TOMCAT_HOME%\lib
-directory, </li>
-
-<li>
-%TOMCAT_HOME%\classes (even if does not exist), </li>
-
-<li>
-%JAVA_HOME%\lib\tools.jar (this jar file contains the tool javac, we need
-javac for jsp files).</li>
-</ol>
-<li>
-Executes java, assuming that it is in the PATH, with command line parameters
-that set up a java system environment, called tomcat.home, with org.apache.tomcat.startup.Tomcat
-as the startup class. It also passes command line parameters to org.apache.tomcat.startup.Tomcat,
-such as: </li>
+ <h3>Table of Contents</h3>
-<ol>
-<li>
-The operation to perform start/stop/run/etc. </li>
+[This section needs to be revised to match current outline. Wouldn't
+it be nice if we used XSL to generate this file from an XML source?]
-<li>
-A path to the server.xml used by this Tomcat process. </li>
-</ol>
-For example if server.xml is located in conf\server_1.xml and the user
-wants to start apache in the background they should provide the following
-command line: bin\tomcat.bat start -f conf\server_1.xml</ul>
-</td>
-</tr>
-</table>
-
-<p>As you can see, the Win32 version of tomcat.bat pales in comparison
-to the Unix one. Especially it does not guess the values of TOMCAT_HOME
-and JAVA_HOME and it also doesn't take add all of the .jar files into the
-classpath.</blockquote>
-
-<hr size="5">
-<h3>
-<a NAME="container_types"></a>Servlet Container Types</h3>
-Tomcat, like any servlet container, is meant to run behind a web server.
-The web server takes care of receiving HTTP requests from client browsers;
-the servlet container takes care of serving Servlets and JSPs for those
-URLs that request them.
-<p>In Tomcat's case, there are three different modes of execution Tomcat
-supports.
-<ol>
-<li>
-<a NAME="type_1"></a><b><u>Stand-alone servlet containers</u></b></li>
-
-<br>These are an integral part of the web server. This is the case when
-using a Java-based web server, for example the servlet container that is
-part of the JavaWebServer. Stand-alone is the default mode used by Tomcat.
-Most web servers, however, are not Java-based, which leads us to the next
-two container types.
-<li>
-<b><u>In-process servlet containers</u></b></li>
-
-<br>The servlet container is a combination of a web server plugin and a
-Java container implementation. The web server plugin opens a JVM inside
-the web server's address space and lets the servlet container run in it.
-If a certain request should execute a servlet, the plugin takes control
-over the request and passes it (using <a href="http://java.sun.com/products/jdk/1.2/docs/guide/jni/index.html">JNI</a>)
-to the servlet container. An in-process container is suitable for multi-threaded
-single-process servers and provides good performance but is limited in
-scalability.
-<li>
-<b><u>Out-of-process servlet containers</u></b></li>
-
-<br>The servlet container is a combination of a web server plugin and a
-Java container implementation that runs in a JVM outside the web server.
-The web server plugin and the Java container JVM communicate using some
-IPC mechanism (usually TCP/IP sockets). If a certain request should execute
-a servlet the plugin takes control over the request and passes it (using
-IPC) to the servlet container. The response time of an out-of-process engine
-is not as good as in the in-process one but the out-of-process engine performs
-better in many measurable ways (scalability, stability, etc.).</ol>
-Tomcat can be used as either a stand-alone container (mainly for development
-and debugging) or as an add-on to an existing web server (currently Apache,
-IIS and Netscape servers are supported). This means that whenever you are
-deploying Tomcat you will have to decide how to use it and, if you select
-options 2 or 3, you will also need to install a web server adapter.
-<p>If this is your first time configuring Tomcat and you plan on integrating
-it with a web server, you're better off initially running it stand-alone.
-You'll be better able to isolate errors during integration with your web
-server when you do so in the future - "Is Tomcat or my web server at fault
-for the error I'm seeing?"
+ <ul>
+ <li><a href="#about_tomcat">About Tomcat</a><br>
+ <a href="#what_is_tomcat">What is Tomcat?</a><br>
+ <a href="#where_download">Where can I download
+ Tomcat?</a><br>
+ <a href="#just_jserv">Isn't Tomcat just JServ?</a><br>
+ <a href="#what_servlets_jsps">What are
+ servlets? What are JSPs?<br>
+ </a> <a href="#contribute">How do/can I contribute?<br>
+ </a> <a href="#where_help">How come X, Y, or Z isn't
+ working? Help!<br>
+ </a>
+
+ </li>
+ <li><a href="#installing_tomcat">Installing Tomcat</a><br>
+ <a href="#file_placement">File placement and
+ environment setup<br>
+ </a> <a href="#starting_and_stopping">Starting and
+ stopping Tomcat<br>
+ </a> <a href="#starting_another_dir">Starting
+ multiple instances w/individual server.xml files<br>
+ </a> <a href="#directory_structure">Tomcat directory
+ structure<br>
+ </a> <a href="#tomcat_scripts">Tomcat scripts</a><br>
+
+ </li>
+ <li><a href="#configuring_tomcat">Configuring Tomcat<br>
+ </a> <a href="#container_types">Types of servlet
+ containers</a><br>
+ <a href="#server_xml">server.xml - Tomcat's main configuration
+ file<br>
+ </a> <a href="#web_xml">web.xml - Default
+ deployment descriptor<br>
+ </a>
+ Web application/context security and authorization<br>
+ tomcat-users.xml<br>
+ JDBC realms<br>
+
+ </li>
+ <li><a href="#webapps">Deploying Web Applications</a><br>
+ <a href="#webapp">What is a Web Application?</a><br>
+ <a href="#what_is_war">What is a WAR file?</a><br>
+ <a href="#deploying_war">Deploying WAR files in Tomcat</a><br>
<br>
-<hr size="5">
-<h3>
-<a NAME="configuring_tomcat"></a>Configuring Tomcat</h3>
-Tomcat's configuration is based on two files:
-<ol>
-<li>
-<a href="#server_xml">server.xml</a> - Tomcat's global configuration file.</li>
-
-<li>
-<a href="#web_xml">web.xml</a> - Default deployment descriptor.</li>
-</ol>
-
-<h4>
- <a NAME="server_xml"></a>server.xml - Tomcat's main configuration
-file</h4>
-
-<blockquote>The elements in server.xml (found in the conf subdirectory
-of TOMCAT_HOME) are described below. Following along with the default server.xml
-in another window is helpful. The default server.xml file has many comments
-which may supersede the comments below. This is more of a reference section
-than a how-to.
-<br>
-<table BORDER=0 WIDTH="90%" >
-<tr>
-<td VALIGN=TOP WIDTH="10%"><b><Server></b></td>
-
-<td VALIGN=TOP WIDTH="90%">The topmost element. <Server> defines a single
-Tomcat server. Generally you should not bother with it.</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="10%"></td>
-
-<td VALIGN=TOP WIDTH="90%">
-<table BORDER=0 WIDTH="100%" >
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><xmlmapper:debug> </b></td>
-
-<td WIDTH="85%">You'll most likely never have to touch this, unless you're
-worried about how Tomcat is registering the contents of this server.xml
-file. Even if you are concerned, the startup output found in Tomcat's main
-log file will usually be sufficient for this purpose.
-<p>Attributes:
-<ul>
-<li>
-<b>level</b>. A value of "0" means "no output". "9" meaning "most everything".</li>
-</ul>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><Logger></b></td>
-
-<td WIDTH="85%">This element defines a Logger object, equivalent to a log
-file. Currently there are loggers for the servlets (where the ServletContext.log()
-goes), JSP files and the tomcat runtime.
-<p>Attributes:
-<ul>
-<li>
-<b>name. </b>Identifies the logger. One of "tc_log", "servlet_log", or
-"JASPER_LOG".</li>
-
-<li>
-<b>path. </b>Output file, relative to TOMCAT_HOME. If you omit a "path"
-value, then stderr & stdout are used.</li>
-
-<li>
-<b>verbosityLevel.</b> In order of increasing verbosity; one of "FATAL",
-"ERROR", "WARNING", "INFORMATION", or "DEBUG".</li>
-</ul>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"><a NAME="context_manager_element"></a><b><ContextManager></b></td>
-
-<td WIDTH="85%">A ContextManager specifies the configuration and structure
-for a set of ContextInterceptors, RequestInterceptors, Contexts and their
-Connectors.
-<p>Attributes:
-<ul>
-<li>
-<b>debug.</b> A value of "0" means "no output". "9" meaning "most everything".</li>
-
-<li>
-<b>home.</b> The base location for the webapps, conf, and logs directories,
-as well as all defined contexts. It is used to start Tomcat from a directory
-other than TOMCAT_HOME. The default value for this attribute is TOMCAT_HOME.</li>
-
-<li>
-<b>workDir.</b> The name of the <a href="#work_dir_defn">working directory</a>,
-relative to the above home attribute.</li>
-</ul>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"></td>
-
-<td WIDTH="85%">
-<table BORDER=0 WIDTH="100%" >
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><ContextInterceptor></b>
-<br><b><RequestInterceptor></b></td>
-
-<td WIDTH="85%">These interceptors listen for certain events that happen
-in the ContextManager. For example, the ContextInterceptor listens for
-startup and shutdown events of Tomcat, and the RequestInterceptor watches
-the various phases that user requests need to pass during its service.
-Tomcat's administrator doesn't need to know much about the interceptors;
-a developer on the other hand should know that this is how "global" type
-of operations can be implemented in Tomcat (for example, security and per
-request logging).</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><Connector> </b></td>
-
-<td WIDTH="85%">The Connector represents a connection to the user, either
-through a web server or directly to the user's browser (in a <a href="#type_1">stand-alone</a>
-configuration). The Connector object is the one responsible for the management
-of the Tomcat worker threads and for read/write requests/responses from
-the sockets connecting to the various clients.
-<p>Attributes:
-<ul>
-<li>
-<b>className.</b> Which Connector to use.</li>
-</ul>
-We will describe how to use this Connector configuration later in the document.</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"></td>
-
-<td WIDTH="85%">
-<table BORDER=0 WIDTH="100%" >
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><Parameter></b></td>
-
-<td WIDTH="85%">Connector initialization parameters. You may have as many
-of these elements as required under each Connector.
-<p>Attributes:
-<ul>
-<li>
-<b>name.</b> So far, one of "handler", "port", "socketFactory".</li>
-
-<li>
-<b>value.</b> The appropriate value.</li>
-</ul>
-</td>
-</tr>
-</table>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><Context> </b></td>
-
-<td WIDTH="85%">Each Context represents a path in the Tomcat hierarchy
-where you place a web application.
-<p>Attributes:
-<ul>
-<li>
-<b>path. </b>The <i>context path</i> for a particular web application,
-which is the prefix of a request URI that tells Tomcat which Context should
-be used to process this request. This attribute is required, and must start
-with a slash ('/') character.</li>
-
-<li>
-<b>docBase.</b> The root of your web application. This can be a full path
-or relative to the <a href="#context_manager_element">ContextManager's</a>
-home. This is Tomcat's version of Apache's "DocumentRoot" directive.</li>
-
-<li>
-<b>reloadable.</b> When developing a servlet it is very convenient to have
-Tomcat automatically reload it, allowing you to fix bugs and have Tomcat
-test the new code without the need to restart the container. To turn on
-servlet reloading set the reloadable flag to true. Detecting changes however
-is time consuming; moreover, since the new servlets are getting loaded
-in a new class-loader object there are cases where this class-reloading
-trigger casts errors. To avoid these problems you can set the reloadable
-flag to false; this will disable the autoreload feature.</li>
-
-<li>
-<b>trusted.</b> Trusted allows you to access tomcat internal objects with
-FacadeManager.</li>
-
-<li>
-<b>debug.</b> A value of "0" means "no output". "9" meaning "most everything".</li>
-</ul>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b><Host> </b></td>
+ </li>
+ <li><a href="#tutorials">Tomcat Tutorials</a> - ???<br>
+ Deploying application<br>
+ Creating your first web application ???<br>
+ Creating and configuring your first servlet ???<br>
+<br>
+ </a>
+ </li>
+ <li><a href="#real_world_tips">Real World Configuration Tips</a><br>
+<br>
+
+ </li>
+ <li><a href="#common_errors">Common Installation and Configuration
+ Problems<br>
+ </a> <a href="#error_bad_command">"Bad command or
+ filename" when executing Tomcat scripts<br>
+ </a> <a href="#error_8007">http://webserver:8007/
+ gives an HTTP 500<br>
+ </a> <a href="#error_ignore_directives">Apache <Directory>
+ and <Location> directives ignored<br>
+ </a> <a href="#error_web_server">Web server won't
+ start when Tomcat is running<br>
+ </a>
+<br>
+</li>
+ <li><a href="#credits">Credits</a></li>
+ </ul>
+
+ <hr size="5">
+ <h3><a name="about_tomcat">About Tomcat</a></h3>
+
+ See also the official
+ <a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</a>.
+
+ <h4> <a name="what_is_tomcat">What is Tomcat?</a></h4>
+ <blockquote>
+ <p>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.
+
+ </blockquote>
+ <h4> <a name="where_download">Where can I download Tomcat?</a></h4>
+ <blockquote>
+ <p>At the <a href="http://jakarta.apache.org/downloads/binindex.html">Jakarta
+ download page</a>!
+ </blockquote>
+ <h4> <a name="just_jserv">Isn't Tomcat just JServ?</a></h4>
+ <blockquote>
+ <p>
+ This is a common misunderstanding. <a href="http://java.apache.org/jserv">JServ</a> is a Servlet API
+ 2.0-compliant container that was created to be used with Apache.
+ Tomcat is a complete re-write and is a Servlet API 2.2 and JSP
+ 1.1-compliant container. Tomcat uses some of the code written for
+ JServ, especially JServ's Apache server adapter, but this is where the
+ similarities end.
+ </p>
+ </blockquote>
+ <h4> <a name="what_servlets_jsps">What are servlets?
+ What are JSPs?</a></h4>
+ <blockquote>
+ <p>In a nutshell, servlets are memory-resident Java programs, running
+ inside a servlet container (e.g. 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>:
+ <blockquote>
+ <p>"The <b>Java<sup><font size="-2">TM</font></sup> Servlet API</b>
+ 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>:
+ <blockquote>
+ <p>"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>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. <b>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!</b>
+ </blockquote>
+ <h4> <a name="contribute">How do/can I contribute?</a></h4>
+ <blockquote>
+ <p>Please do! See the Jakarta project contribution page, right <a href="http://jakarta.apache.org/getinvolved/getinvolvedindex.html">here</a>.
+ You'll probably want to <a href="mailto:tomcat-dev-subscribe@jakarta.apache.org">subscribe</a>
+ to the <b> tomcat-dev</b> mailing list.</p>
+ </blockquote>
+ <h4> <a name="where_help">How come X, Y, or Z isn't
+ working? Help!</a></h4>
+ <blockquote>
+ 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>The <a href="#common_errors">Common problems</a> section of this
+ document.</li>
+ <li>Have a look through the <a href="http://jakarta.apache.org/faq/faqindex.html"> Tomcat
+ FAQ</a>. Most installation and configuration questions can be found here.</li>
+ <li>Search the Tomcat <a href="http://mikal.org/interests/java/tomcat/index.html">user</a>
+ and <a href="http://www.metronet.com/~wjm/tomcat/">developer</a> list
+ archives. </li>
+ <li>Post a question to the <b> tomcat-user</b> <a href="http://jakarta.apache.org/getinvolved/mail.html">
+ mailing list</a>, which you must first <a href="mailto:tomcat-user-subscribe@jakarta.apache.org">subscribe</a>
+ to if you'd like to see any replies!
+ </ol>
+ </blockquote>
+ <hr size="5">
+ <h3><a name="installing_tomcat">Installing Tomcat</a></h3>
+ <h4> <a name="file_placement">File placement and
+ environment setup</a></h4>
+ <blockquote>
+
+ <ul>
+ <li><a href="http://jakarta.apache.org/downloads/binindex.html">Download</a> the
+ appropriate jakarta-tomcat [.zip | .gz | .Z] file.
+
+ <li>Unzip the file into some directory (say /usr/local or C:\). This
+ should create a new subdirectory named "tomcat". [Does it still create "jakarta-tomcat" instead? If so, just rename it "tomcat".] </li>
+
+ <li>Change directory to "tomcat" and set a new environment
+ variable (<a name="tomcat_home_env">TOMCAT_HOME</a>) to point to the root directory of your
+ Tomcat hierarchy. The exact directory may change from system to system; check your local filesystem to be sure where Tomcat is installed.
+ <ol>
+ <li>On Win32 systems you should type: <br>
+ <tt><big>set TOMCAT_HOME=c:\tomcat
+ </big></tt></li>
+ <li>On UNIX (using bash/sh) you should type: <br>
+ <tt><big>TOMCAT_HOME=/usr/local/tomcat ; export TOMCAT_HOME
+ </big></tt></li>
+ <li>On UNIX (using tcsh) you should type: <br>
+ <tt><big>setenv TOMCAT_HOME=/usr/local/tomcat
+ </big></tt></li>
+ </ol>
+ </li>
+
+ <li>Set the environment variable JAVA_HOME to point to the root
+ directory of your JDK hierarchy, then add the Java interpreter to your PATH environment variable. The exact directory may change from system to system; check your local filesystem to be sure where Java is installed.
+ <ol>
+ <li>Win32:<br>
+ <tt><big>
+ set JAVA_HOME=c:/jdk1.2<br>
+ set PATH=%PATH%;%JAVA_HOME%\bin
+ </big></tt>
+ </li>
+ <li>Unix (bash/sh):<br>
+ <tt><big>
+ set JAVA_HOME=/user/local/java/jdk1.2; export JAVA_HOME<br>
+ set PATH=$PATH:$JAVA_HOME/bin; export PATH<br>
+ </big></tt>
+ </li>
+ <li>Unix (tcsh):<br>
+ <tt><big>
+ setenv JAVA_HOME=/user/local/java/jdk1.2<br>
+ setenv PATH=$PATH:$JAVA_HOME/bin <br>
+ </big></tt>
+ </li>
+ </ol>
+ </li>
+
+ </ul>
+
+ <p> That's it! You can now <a href="#starting_and_stopping"> execute Tomcat</a> and it will run as a
+ <a href="#type_1">
+ stand-alone</a> servlet container.
+ </p>
+
+ <p>
+ Once you're sure they work, these environment variables should probably be set in a
+ config file: C:/AUTOEXEC.BAT for Windows, ~/bash_profile
+ or ~/[what is it for tcsh?]
+ </p>
+
+ </blockquote>
+
+ <h4> <a name="starting_and_stopping">Starting and
+ stopping Tomcat</a>
+ </h4>
+
+ <blockquote>
+ <p>You start and stop Tomcat using the scripts in
+ the bin subdirectory of <a href="#tomcat_home_env">TOMCAT_HOME</a>.</p>
+ <P>To start Tomcat execute:</P>
+ <blockquote style="margin-right: 0px">
+ <p>On UNIX: bin/startup.sh</p>
+ <p>On Win32: bin\startup</p>
+ </blockquote>
+ <p>To stop Tomcat execute: </p>
+ <blockquote style="margin-right: 0px">
+ <p>On UNIX: bin/shutdown.sh </p>
+ <p>On Win32: bin\shutdown</p>
+ </blockquote>
+
+ </blockquote>
+
+ <h4> <a name="starting_another_dir">Starting multiple
+ instances with individual server.xml files</a>
+ </h4>
+
+ <blockquote>
+
+ <p>This might not make a whole lot of sense until you read the next section
+ explaining Tomcat's <a href="#directory_structure">directory structure</a>,
+ as well as <a href="#configuring_tomcat">Configuring Tomcat</a>. You
+ may want to come back here afterwards. </p>
+
+ <p>By default, Tomcat will use TOMCAT_HOME/conf/server.xml for
+ configuration, which by default, uses TOMCAT_HOME as its base for the contexts.
+ You can change this by using the "-f /path/to/server.xml" option, with a
+ different server configuration file and setting the home attribute of
+ the <a href="#context_manager_element">ContextManager</a> element. You need to set up the required files inside the
+ home: </p>
+ <ul>
+ <li>webapps/ - all war files will
+ be expanded and all subdirectories added as contexts.</li>
+ <li>conf/ directory - you can store a special web.xml and other
+ configuration files.</li>
+ <li>logs/ - all logs will go to this directory instead of the main
+ TOMCAT_HOME/logs/.</li>
+ <li>work/ - work directories for the contexts.
+ </li>
+ </ul>
+
+ <p>If the home attribute of the ContextManager element in server.xml is relative, it
+ will be relative to the current working directory.</p>
+
+ </blockquote>
+
+ <h4> <a name="directory_structure">The Tomcat directory
+ structure</a>
+ </h4>
+
+ <blockquote>
+ <p>Assuming you extracted the Tomcat binary distribution
+ you should have the following directory structure under <a href="#tomcat_home_env">TOMCAT_HOME</a>:</p>
+ <table border width="75%" valign="MIDDLE">
+ <tr>
+ <th bgcolor="#c0c0c0" WIDTH="15%"> Directory</th>
+ <th bgcolor="#c0c0c0" WIDTH="85%"> Contents</th>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="center"> bin </td>
+ <td WIDTH="85%"> Startup/shutdown scripts and other useful files.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="center"> conf </td>
+ <td WIDTH="85%"> Configuration files including <a href="#server_xml">server.xml</a> (Tomcat's main configuration file) and
+ <a href="#web_xml">
+ web.xml</a> (default values for the various web applications deployed in
+ Tomcat.).
+ </td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="center"> doc </td>
+ <td WIDTH="85%">Miscellaneous documents regarding Tomcat.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="center"> lib </td>
+ <td WIDTH="85%"> Various jar files that are used by Tomcat.
+ Any file in this directory is appended to Tomcat's classpath.
+ </td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="center"> <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="center"> src </td>
+ <td WIDTH="85%"> The servlet API source files. Don't get excited,
+ though; these are only the empty interfaces and abstract
+ classes that should be implemented by any servlet
+ container.</td>
+ </tr>
+ <tr>
+ <td WIDTH="15%" align="center"> webapps </td>
+ <td WIDTH="85%"> Sample web applications. Any .war files placed
+ here will be automatically expanded. See <a href="#deploying_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="MIDDLE">
+ <tr>
+ <td width="15%" align="center"> <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="center"> classes </td>
+ <td width="85%"> Any class that you add to this directory will
+ find its place in Tomcat's classpath.
+ </td>
+ </tr>
+ </table>
+
+ </blockquote>
+
+ <h4> <a name="tomcat_scripts">Tomcat scripts</a></h4>
+ <blockquote>
+ <p>This section is not required reading, as the default functionality
+ provided by the aforementioned startup and shutdown scripts is sufficient
+ for most users to get started. If everything is working so far, skip ahead to <a href="#configuring_tomcat">Configuring
+ Tomcat</a>. Come back to this section when you'd like more information
+ on these scripts, which you undoubtedly will.</p>
+
+ <p>Tomcat is a Java program, and therefore it is possible to execute
+ it from the command line, after setting several environment
+ variables. However, setting each environment variable and following
+ the command line parameters used by Tomcat is error prone and
+ tedious. Instead, the Tomcat development team provides a few scripts
+ to ease starting and stopping Tomcat.</p>
+
+ <p><b>Note: The scripts are only a convenient way to start/stop. You can modify them to customize the
+ CLASSPATH, environment
+ variables such as PATH and LD_LIBRARY_PATH, etc., so long as a
+ correct command line is generated for Tomcat.</b>
+ </p>
+
+ <p> The following table presents the scripts that are
+ most important for the common user:</p>
+ <table border width="75%" valign="MIDDLE">
+ <tr>
+ <th bgcolor="#c0c0c0" width="15%"> Script name </th>
+ <th bgcolor="#c0c0c0" width="85%"> Description </th>
+ </tr>
+ <tr>
+ <td width="15%" align="center"> tomcat </td>
+ <td width="85%"> The main script. Sets the proper environment, including
+ CLASSPATH, TOMCAT_HOME and JAVA_HOME, and starts Tomcat with
+ the proper command line parameters.</td>
+ </tr>
+ <tr>
+ <td width="15%" align="center"> startup </td>
+ <td width="85%"> Starts tomcat in the background. Shortcut for "tomcat start" </td>
+ </tr>
+ <tr>
+ <td width="15%" align="center"> shutdown </td>
+ <td width="85%"> Stops tomcat (shutting it down). Shortcut for "tomcat stop" </td>
+ </tr>
+ </table>
+
+ <p>The script which has the most significance for users is tomcat
+ (tomcat.sh/tomcat.bat). The other Tomcat related scripts serve as a
+ simplified single-task oriented entry point to the tomcat script (set
+ different command line parameters etc.).</p>
+ </blockquote>
+
+ <h4> <a name="tomcat_scripts_closer">Tomcat scripts: a closer look</a></h4>
+ <blockquote>
+ <p>
+ A closer look at tomcat.sh/tomcat.bat yields that it performs the
+ following actions:</p>
+
+ <p>These behaviors, especially CLASSPATH setting, have changed
+ with Tomcat 3.2. It is best to look directly at the scripts for
+ details on what variables are set and what class files are
+ loaded. [??? - delete entire section pending reexamination?]</p>
+
+ <table border =1 width="75%" valign="MIDDLE">
+ <tr>
+ <th bgcolor="#c0c0c0" width="15%"> Operating System </th>
+ <th bgcolor="#c0c0c0" width="85%"> Actions </th>
+ </tr>
+ <tr>
+ <td width="15%" align="center"> Unix </td>
+ <td width="85%">
+ <ul>
+ <li>Guessing what is TOMCAT_HOME if it is not
+ specified.
+
+ <li>Guessing what is JAVA_HOME if it is not
+ specified.
+
+ <li>Setting up a CLASSPATH that contains -
+
+ <ol>
+ <li>The ${TOMCAT_HOME}/classes directory (if available).</li>
+
+ <li>All the contents of ${TOMCAT_HOME}/lib. </li>
+
+ <li>${JAVA_HOME}/lib/tools.jar (this jar file contains the tool
+ javac, we need javac for jsp files).</li>
+ </ol>
+ <li>Executes java with command line parameters that set up a java
+ system environment, called tomcat.home, with
+ org.apache.tomcat.startup.Tomcat as the startup class. It also
+ passes command line parameters to
+ org.apache.tomcat.startup.Tomcat, such as:
+
+ <ol>
+ <li>The operation to perform start/stop/run/etc.
+
+ <li>A path to the server.xml used by this Tomcat process. </li>
+ </ol>
+ <p>For example if server.xml is located in /etc/server_1.xml and
+ the user wants to start apache in the background they should
+ provide the following command line:
+ <div>bin/tomcat.sh start -f /etc/server_1.xml</div></p>
+ </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" align="center"> Win32 </td>
+ <td width="85%">
+ <ul>
+ <li>Setting up a CLASSPATH that contains -
+
+ <ol>
+ <li> servlet.jar, webserver.jar, jasper.jar, xml.jar from the
+ %TOMCAT_HOME%\lib directory, </li>
+ <li> %TOMCAT_HOME%\classes (even if does not exist), </li>
+ <li> %JAVA_HOME%\lib\tools.jar (this jar file contains the tool
+ javac, we need javac for jsp files).</li>
+ </ol>
+ <li>Executes java, assuming that it is in the PATH, with command line
+ parameters that set up a java system environment, called tomcat.home,
+ with org.apache.tomcat.startup.Tomcat as the startup class. It also
+ passes command line parameters to org.apache.tomcat.startup.Tomcat,
+ such as:
+
+ <ol>
+ <li>The operation to perform start/stop/run/etc.
+
+ <li>A path to the server.xml used by this Tomcat process. </li>
+ </ol>
+ <p>For example if server.xml is located in conf\server_1.xml and
+ the user wants to start apache in the background they should
+ provide the following command line:
+ <div>bin\tomcat.bat start -f conf\server_1.xml</div>
+
+ </li></ul>
+ </td>
+ </tr>
+ </table>
+
+ <p>As you can see, the Win32 version of tomcat.bat pales in comparison to the Unix
+ one. Especially it does not guess the values of TOMCAT_HOME and
+ JAVA_HOME and it also doesn't take add all of the .jar files into the classpath.</p>
+
+ </blockquote>
+
+ <hr size="5">
+ <h3><a name="container_types">Servlet Container Types</a></h3>
+
+ Tomcat, like any servlet container, is meant to run behind a web
+ server. The web server takes care of receiving HTTP requests from
+ client browsers; the servlet container takes care of serving
+ Servlets and JSPs for those URLs that request them.
+ <p>
+ In Tomcat's case, there are three different modes of execution
+ Tomcat supports.
+
+ <ol>
+ <li><strong><u><a name="type_1">Stand-alone servlet containers</a></u></strong><br>
+ These are an integral part of the web server. This
+ is the case when using a Java-based web server, for example the
+ servlet container that is part of the JavaWebServer. Stand-alone
+ is the default mode used by Tomcat. Most web servers, however, are not Java-based, which leads us to
+ the next two container types.<br>
+ </li>
+
+ <li><strong><u>In-process servlet containers</u></strong><br>
+ The servlet container is a combination of a web server plugin and a
+ Java container implementation. The web server plugin opens a JVM
+ inside the web server's address space and lets the servlet container
+ run in it. If a certain request should execute a servlet, the plugin
+ takes control over the request and passes it (using <a href="http://java.sun.com/products/jdk/1.2/docs/guide/jni/index.html">JNI</a>) to the
+ servlet
+ container. An in-process container is suitable for multi-threaded
+ single-process servers and provides good performance but is limited
+ in scalability.<br>
+ </li>
+
+ <li><strong><u>Out-of-process servlet containers</u></strong><br>
+ The servlet container is a combination of a
+ web server plugin and a Java container implementation that runs
+ in a JVM outside the web server. The web server plugin and the
+ Java container JVM communicate using some IPC mechanism (usually
+ TCP/IP sockets).
+ If a certain request should execute a servlet the plugin takes
+ control over the request and passes it (using IPC) to the servlet container.
+ The response time of an out-of-process engine is not as good as
+ in the in-process one but the out-of-process engine performs
+ better in many measurable ways (scalability, stability, etc.).
+ </li>
+ </ol>
+
+ <p>Tomcat can be used as either a stand-alone container
+ (mainly for development and debugging) or as an add-on to an
+ existing web server (currently Apache, IIS and Netscape servers are
+ supported). This means that whenever you are deploying Tomcat you will
+ have to decide how to use it and, if you select options 2 or 3, you
+ will also need to install a web server adapter.</p>
+
+ <p>If this is your first time configuring Tomcat and you plan on integrating
+ it with a web server, you're better off initially running it
+ stand-alone. You'll be better able to isolate errors during
+ integration with your web server when you do so in the future - "Is
+ Tomcat or my web server at fault for the error I'm seeing?"</p>
+
+
+ <hr size="5">
+ <h3><a name="configuring_tomcat">Configuring Tomcat</a></h3>
+ <p> Tomcat's configuration is based on two files:
+ <ol>
+ <li> <a href="#server_xml"> server.xml</a> - Tomcat's global configuration file. </li>
+ <li> <a href="#web_xml"> web.xml</a> - Default deployment descriptor. </li>
+ </ol>
+
+ <h4> <a name="server_xml">server.xml - Tomcat's main configuration
+ file</a></h4>
+ <blockquote>
+ <p>
+ The elements in server.xml (found in the conf subdirectory of
+ TOMCAT_HOME) are described below. Following along with the
+ default server.xml in another window is helpful. The default
+ server.xml file has many comments which may supersede the
+ comments below. This is more of a reference section than a
+ how-to.</p>
+ <table border="0" width="90%">
+ <tr>
+ <td width="10%" valign="top"><b><Server></b></td>
+ <td width="90%" valign="top">The topmost element. <Server>
+ defines a single Tomcat server. Generally you should not bother with
+ it.<br>
+ </td>
+ </tr>
+ <tr>
+ <td width="10%" valign="top"></td>
+ <td width="90%" valign="top">
+ <table border="0" width="100%">
+ <tr>
+ <td width="15%" valign="top"><b><xmlmapper:debug>
+ </b></td>
+ <td width="85%">You'll most likely never have to touch this, unless you're
+ worried about how Tomcat is registering the contents of this server.xml file. Even if you are concerned, the startup output
+ found in Tomcat's main log
+ file will usually be sufficient for this purpose.
+ <p>Attributes:</p>
+ <ul>
+ <li> <b>level</b>. A value of "0"
+ means "no output". "9" meaning
+ "most everything".</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"><b><Logger></b></td>
+ <td width="85%">
+ This element defines a Logger object, equivalent to a log file. Currently there are loggers for the servlets (where the
+ ServletContext.log() goes),
+ JSP files and the tomcat runtime.
+ <p>Attributes:</p>
+ <ul>
+ <li><b>name. </b> Identifies
+ the logger. One of "tc_log", "servlet_log",
+ or "JASPER_LOG".</li>
+ <li><b>path. </b>Output file, relative to
+ TOMCAT_HOME. If you omit a "path" value, then stderr &
+ stdout are used.</li>
+ <li><b>verbosityLevel.</b> In order of increasing verbosity; one of "FATAL", "ERROR",
+ "WARNING", "INFORMATION", or "DEBUG".</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"><b><a name="context_manager_element"><ContextManager></a></b></td>
+ <td width="85%">
+ A ContextManager specifies the configuration and structure for a set of
+ ContextInterceptors, RequestInterceptors, Contexts and their Connectors.
+ <p>
+ Attributes:</p>
+ <ul>
+ <li><b>debug.</b> A value of "0"
+ means "no output". "9" meaning
+ "most everything".</li>
+ <li><b>home.</b> The base location for the
+ webapps, conf, and logs directories, as well as all defined contexts.
+ It is used to start Tomcat from a directory other than
+ TOMCAT_HOME. The default value for this attribute is
+ TOMCAT_HOME.</li>
+ <li><b>workDir.</b> The name of the <a href="#work_dir_defn"> working
+ directory</a>, relative to the above home attribute.</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"></td>
+ <td width="85%">
+ <table border="0" width="100%">
+ <tr>
+ <td width="15%" valign="top"><b><ContextInterceptor><br>
+ <RequestInterceptor></b></td>
+ <td width="85%"> These interceptors listen for certain events that happen in
+ the ContextManager. For example, the ContextInterceptor listens for
+ startup and shutdown events of Tomcat, and the RequestInterceptor
+ watches the various phases that user requests need to pass during its service.
+ Tomcat's administrator doesn't need to know much about the
+ interceptors; a developer on the other hand should know that this
+ is how "global" type of operations can be implemented in Tomcat
+ (for example, security and per request logging).<br>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"><b><Connector>
+ </b></td>
+ <td width="85%">The Connector represents a connection to the user, either
+ through a web server or directly to the user's browser (in a <a href="#type_1">
+ stand-alone</a> configuration).
+ The Connector object is the one responsible for the management of
+ the Tomcat worker threads and for read/write requests/responses
+ from the sockets connecting to the various clients.
+ <p>Attributes:</p>
+ <ul>
+ <li><b>className.</b> Which Connector to use.</li>
+ </ul>
+ We will describe how to use this Connector configuration later in the document.<br>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"></td>
+ <td width="85%">
+ <table border="0" width="100%">
+ <tr>
+ <td width="15%" valign="top"><b><Parameter></b></td>
+ <td width="85%">Connector initialization
+ parameters. You may have as many of these
+ elements as required under each Connector.
+ <p>Attributes:</p>
+ <ul>
+ <li><b>name.</b> So far, one of
+ "handler", "port", "socketFactory".</li>
+ <li><b>value.</b> The appropriate value.</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"><b><Context>
+ </b> </td>
+ <td width="85%"> Each Context represents a path in the Tomcat hierarchy where you
+ place a web application.
+ <p>
+ Attributes:</p>
+ <ul>
+ <li><b>path. </b>The <i>context path</i> for a
+ particular web application, which
+ is the prefix of a request URI that tells Tomcat which Context
+ should be used to process this request. This attribute is
+ required,
+ and must start with a slash ('/') character.</li>
+ <li><b>docBase.</b> The root of your web
+ application. This can be a full path or relative to the <a href="#context_manager_element">
+ ContextManager's</a> home. This is Tomcat's version of
+ Apache's "DocumentRoot" directive.</li>
+ <li><b>reloadable.</b> When developing a servlet it is very
+ convenient to have Tomcat automatically reload it, allowing you to fix bugs and have Tomcat test the new code without the need to
+ restart the container. To turn on servlet reloading set the
+ reloadable flag to true. Detecting changes however is time
+ consuming; moreover, since the new servlets are getting loaded
+ in a new class-loader object there are cases where this
+ class-reloading trigger casts errors. To avoid these problems
+ you can set the reloadable flag to false; this will disable the
+ autoreload feature.</li>
+ <li><b>trusted.</b> Trusted allows you to access tomcat internal objects with FacadeManager.</li>
+ <li><b>debug.</b> A value of "0"
+ means "no output". "9" meaning
+ "most everything".</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"><b><Host>
+ </b></td>
+ <td width="85%">Contains <Context> elements. The <Host>
+ element is used to configure per-virtual host Contexts.
+ <p>
+ Attributes:</p>
+ <ul>
+ <li><b>name</b>: The fully-qualified hostname
+ or IP address of the virtual host.</li>
+ </ul>
+ </td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr>
+ <td width="15%" valign="top"><b></ContextManager></b></td>
+ <td width="85%"></td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr>
+ <td width="10%" valign="top"><b></Server></b></td>
+ <td width="90%" valign="top"></td>
+ </tr>
+ </table>
+ </blockquote>
+ <h4> <a name="web_xml">web.xml - Default deployment descriptor</a></h4>
+ <blockquote>
+ <p>
+ A detailed description of web.xml and the web application structure
+ (including directory structure and configuration) is available in
+ chapters 9, 10 and 13 of the <a href="http://java.sun.com/products/servlet/download.html">Servlet API Spec</a>
+ and we are not going to write about it. <a href="../appdev/index.html">Developing Applications with Tomcat</a>
+ covers web application and deployment with Tomcat. <b>It is required reading if you're not going to
+ take the time to read through the <a href="http://java.sun.com/products/servlet/download.html">Servlet API Spec</a>!</b> </p>
+ <p>
+ There is a small Tomcat "feature" that is related
+ to web.xml. Tomcat lets the user define default web.xml values for all
+ contexts by putting a default web.xml file in the conf subdirectory of
+ TOMCAT_HOME. When
+ constructing a new Context, Tomcat uses the default web.xml file as the
+ base configuration, and then applies the application specific web.xml (the
+ application's WEB-INF/web.xml file) settings.
-<td WIDTH="85%">Contains <Context> elements. The <Host> element is
-used to configure per-virtual host Contexts.
-<p>Attributes:
-<ul>
-<li>
-<b>name</b>: The fully-qualified hostname or IP address of the virtual
-host.</li>
-</ul>
-</td>
-</tr>
-</table>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="15%"><b></ContextManager></b></td>
-
-<td WIDTH="85%"></td>
-</tr>
-</table>
-</td>
-</tr>
-
-<tr>
-<td VALIGN=TOP WIDTH="10%"><b></Server></b></td>
-
-<td VALIGN=TOP WIDTH="90%"></td>
-</tr>
-</table>
-</blockquote>
+This means that in Tomcat, you can get away with an empty
+web.xml file, containing only the element
+<tt><big><web-app/></big></tt>, or (more realistically)
+containing only the elements (e.g. mappings and mime-types) you need. However, this will limit your
+webapp's portability, so it is recommended to use a full web.xml
+file. You may instead want to copy TOMCAT_HOME/conf/web.xml and modify it.
+
+ </p>
+
+ <p>
+ We cover certain aspects of web.xml in subsequent sections, where it
+ pertains to application deployment and interaction with Tomcat.
+ </p>
+
+ </blockquote>
+
+ <hr size="5">
+ <a name="webapps">
+ <h3>Deploying Web Applications</h3>
-<h4>
- <a NAME="web_xml"></a>web.xml - Default deployment descriptor</h4>
+ <a name="webapp">
+ <h4>What is a Web Application?</h4>
-<blockquote>A detailed description of web.xml and the web application structure
-(including directory structure and configuration) is available in chapters
-9, 10 and 13 of the <a href="http://java.sun.com/products/servlet/download.html">Servlet
-API Spec</a> and we are not going to write about it. <a href="../appdev/index.html">Developing
-Applications with Tomcat</a> covers web application and deployment with
-Tomcat. <b>It is required reading if you're not going to take the time
-to read through the <a href="http://java.sun.com/products/servlet/download.html">Servlet
-API Spec</a>!</b>
-<p>There is a small Tomcat "feature" that is related to web.xml. Tomcat
-lets the user define default web.xml values for all contexts by putting
-a default web.xml file in the conf subdirectory of TOMCAT_HOME. When constructing
-a new Context, Tomcat uses the default web.xml file as the base configuration,
-and then applies the application specific web.xml (the application's WEB-INF/web.xml
-file) settings. This means that in Tomcat, you can get away with an empty
-web.xml file, containing only the element
-<tt><font size=+1><web-app/></font></tt>,
-or (more realistically) containing only the elements (e.g. mappings and
-mime-types) you need. However, this will limit your webapp's portability,
-so it is recommended to use a full web.xml file. You may instead want to
-copy TOMCAT_HOME/conf/web.xml and modify it.
-<p>We cover certain aspects of web.xml in subsequent sections, where it
-pertains to application deployment and interaction with Tomcat.</blockquote>
-
-<hr size="5"><a NAME="webapps"></a>
-<h3>
-Deploying Web Applications</h3>
-<a NAME="webapp"></a>
-<h4>
-What is a Web Application?</h4>
[??? - move this section up above the Configuring Tomcat section? It's
-not clear whether we should teach about webapps before or after we introduce
-server.xml et al.]
-<p>A Web Application (or "webapp") is a concept that was introduced in
-the <a href="http://java.sun.com/products/servlet/2.2/">Servlet Specification</a>
-version 2.2. [2.1?] You should definitely read the spec for the full story.
-From the spec (chapter 9):
-<blockquote>A web application is a collection of servlets, html pages,
-classes, and other resources that can be bundled and run on multiple containers
-from multiple vendors. A web application is rooted at a specific path within
-a web server. For example, a catalog application could be located at http://
-www.mycorp.com/catalog. All requests that start with this prefix will be
-routed to the ServletContext which represents the catalog application.
-<p>A servlet container can also establish rules for automatic generation
-of web applications. For example a ~user/ mapping could be used to map
-to a web application based at /home/user/ public_html/.
-<p>[...]
-<p>A web application exists as a structured hierarchy of directories. The
-root of this hierarchy serves as a document root for serving files that
-are part of this context. For example, for a web application located at
-/catalog in a web server, the index.html file located at the base of the
-web application hierarchy can be served to satisfy a request to /catalog/index.html.
-<p>A special directory exists within the application hierarchy named "WEB-INF".
-This directory contains all things related to the application that aren't
-in the document root of the application. It is important to note that the
-WEB-INF node is not part of the public document tree of the application.
-No file contained in the WEB-INF directory may be served directly to a
-client.
-<p>The contents of the WEB-INF directory are:
+not clear whether we should teach about webapps before or after we
+introduce server.xml et al.]
+<p>
+A Web Application (or "webapp") is a concept that was introduced in
+the <a href="http://java.sun.com/products/servlet/2.2/">Servlet
+Specification</a> version 2.2. [2.1?] You should definitely read the
+spec for the full story. From the spec (chapter 9):
+<blockquote>
+<p>
+A web application is a collection of servlets, html pages, classes, and other resources that can be
+bundled and run on multiple containers from multiple vendors. A web application is rooted at a
+specific path within a web server. For example, a catalog application could be located at http://
+www.mycorp.com/catalog. All requests that start with this prefix will be routed to the
+ServletContext which represents the catalog application.
+</p>
+<p>
+A servlet container can also establish rules for automatic generation of web applications. For
+example a ~user/ mapping could be used to map to a web application based at /home/user/
+public_html/.
+</p>
+<p>[...]</p>
+<p>
+A web application exists as a structured hierarchy of directories. The
+root of this hierarchy serves as a document root for serving files
+that are part of this context. For example, for a web application
+located at /catalog in a web server, the index.html file located at
+the base of the web application hierarchy can be served to satisfy a
+request to /catalog/index.html.
+</p>
+<p>
+A special directory exists within the application hierarchy named "WEB-INF". This directory
+contains all things related to the application that aren't in the document root of the application. It is
+important to note that the WEB-INF node is not part of the public document tree of the application.
+No file contained in the WEB-INF directory may be served directly to a client.
+</p>
+<p>
+The contents of the WEB-INF directory are:
<ul>
-<li>
-/WEB-INF/web.xml deployment descriptor</li>
-
-<li>
-/WEB-INF/classes/* directory for servlet and utility classes. The classes
-in this directory are used by the application class loader to load classes
-from.</li>
-
-<li>
-/WEB-INF/lib/*.jar area for Java ARchive files which contain servlets,
-beans, and other utility classes useful to the web application. All such
-archive files are used by the web application class loader to load classes
-from.</li>
+<li> /WEB-INF/web.xml deployment descriptor </li>
+<li> /WEB-INF/classes/* directory for servlet and utility classes. The classes in this directory
+are used by the application class loader to load classes from. </li>
+<li> /WEB-INF/lib/*.jar area for Java ARchive files which contain servlets, beans, and other
+utility classes useful to the web application. All such archive files are used by the web
+application class loader to load classes from. </li>
</ul>
-
-<h3>
-Sample Web Application Directory Structure</h3>
+</p>
+<h3>Sample Web Application Directory Structure</h3>
+<p>
Illustrated here is a listing of all the files in a sample web application:
-<blockquote>
-<pre><font size=+1>/index.html
+<blockquote><pre><big>/index.html
/howto.jsp
/feedback.jsp
/images/banner.gif
@@ -981,372 +935,413 @@
/WEB-INF/web.xml
/WEB-INF/lib/jspbean.jar
/WEB-INF/classes/com/mycorp/servlets/MyServlet.class
-/WEB-INF/classes/com/mycorp/util/MyUtils.class</font></pre>
+/WEB-INF/classes/com/mycorp/util/MyUtils.class
+</big></pre>
</blockquote>
</blockquote>
-You can deploy a WAR file that is present on the local filesystem by adding
-a <Context> tag to TOMCAT_HOME/conf/server.xml. For example:
-<blockquote>
-<pre><font size=+1><Context path="/mywebapp"
- docBase="/home/alex/webapps/mywebapp"
- reloadable="true" >
-</Context></font></pre>
-</blockquote>
-<a NAME="what_is_war"></a>
-<h4>
-What is a WAR file?</h4>
-<i>"WAR. Huh! What is it good for?" - Edwin Starr</i>
-<p>A WAR (or "web archive") file is simply a packaged webapp directory.
-It is created using the standard Java <tt><font size=+1>jar</font></tt>
-tool. For example:
-<blockquote>
-<pre><font size=+1>cd /home/alex/webapps/mywebapp
-jar cf mywebapp.war *</font></pre>
-</blockquote>
-<a NAME="deploying_war"></a>
-<h4>
-Deploying WAR files in Tomcat</h4>
-
-<blockquote>Currently (as of version 3.2) the procedure for deploying a
-new WAR file is:
-<ol>
-<li>
-<b>Stop Tomcat</b>.</li>
-
-<li>
-<b>Delete existing deployment.</b> If you have previously deployed "foo.war"
-in TOMCAT_HOME/webapps, then it has been unpacked into webapps/foo/...
-You must delete this directory and all its contents. On Unix, this can
-be done with</li>
-
-<pre><font size=+1>rm -r $TOMCAT_HOME/webapps/foo</font></pre>
-
-<li>
-<b>Copy WAR file to TOMCAT_HOME/webapps/</b>.</li>
-
-<li>
-<b>Start Tomcat</b>.</li>
-</ol>
-This process may become easier in the future. A "deploy tool" is on the
-Tomcat "to-do" list.
-<p>Note that if you deploy a WAR file in this manner, you do not need to
-make any changes to <tt><font size=+1>server.xml</font></tt> -- it will
-automatically be recognized and activated when the server starts. However,
-if you wish to specify non-default options for this webapp, you may do
-so by adding an element like <tt><font size=+1><Context docBase="webapps/foo"
-...</font></tt> to server.xml.
-<p>See also <a href="http://www.jguru.com/jguru/faq/view.jsp?EID=123229">How
-do I deploy a WAR file in Tomcat?</a> in the jGuru FAQ.</blockquote>
-
-<hr size="5"><a NAME="tutorials"></a>
-<h3>
-Tomcat Tutorials</h3>
-These tutorials will be run with the assumption that Tomcat is operating
-as a stand-alone container. Like we said before, it can be helpful to understand
-Tomcat's functionality, irrespective of the particular web server you're
-using. Trying to get more than one thing working at once usually leads
-to more problems than its worth. Integration will be covered later in subsequent
-sections.
-<br>[Note: add some tutorials here :-) ]
-<h2>
-Real World Configuration Tips</h2>
-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.
-<h3>
-Modify and Customize the Batch Files</h3>
-As stated in the previous sections, the startup scripts are here for your
-convenient. Yet, sometimes the scripts that are needed for deployment should
-be modified:
-<ul>
-<li>
-To set resource limits such as maximum number of descriptors.</li>
-
-<li>
-To add new CLASSPATH entries (for example, JDBC drivers).</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>
+</p>
-<li>
-Make sure that you are using a specific JVM (out of the two or three JVMs
-installed on your machine).</li>
+<p>
+You can deploy a WAR file that is present on the local filesystem by
+adding a <Context> tag to TOMCAT_HOME/conf/server.xml. For
+example:
+<blockquote><pre><big><Context path="/mywebapp"
+ docBase="/home/alex/webapps/mywebapp"
+ reloadable="true" >
+</Context>
+</big></pre></blockquote>
+</p>
+
+<a name="what_is_war">
+ <h4>What is a WAR file?</h4>
+
+<p><i>"WAR. Huh! What is it good for?" - Edwin Starr</i></p>
+
+<p>
+A WAR (or "web archive") file is simply a packaged webapp directory.
+It is created using the standard Java <tt><big>jar</big></tt> tool.
+For example:
+<blockquote><pre><big>cd /home/alex/webapps/mywebapp
+jar cf mywebapp.war * </big></pre></blockquote>
+</p>
-<li>
-To switch user from root to some other user using the "su" UNIX command.</li>
+ <a name="deploying_war">
+ <h4>Deploying WAR files in Tomcat</h4>
-<li>
-Your pet reason.</li>
-</ul>
-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 <i>UNIX</i> 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 CLASSPATH
-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...<b>Do not hesitate, just do it.</b>
-<h3>
-Modify the Default JVM Settings</h3>
-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:
-<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.</li>
-
-<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>
-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. There are several JVM vendors, for example
-on Linux there are today (21/03/2000) two product level JVMs: the SUN JDK1.2.2
-and the IBM JDK1.1.8. If your application does not require a specific JDK
-functionality, you should benchmark the two JVMs and select the better
-one. In my (Gal Shachor) internal tests I found the IBM JVM significantly
-faster than the one created by SUN, you should check that for yourself
-and make a calculated decision.</li>
-</ol>
-
-<h3>
-Modify your Connectors</h3>
-The Connectors, as configured in Tomcat's default server.xml contains two
-Connectors configured as in the next server.xml fragment:
-<table BORDER CELLSPACING=0 CELLPADDING=0 valign="middle" >
-<caption valign="bottom" width="100%"><i>The two default Connectors in
-server.xml </i></caption>
-
-<tr>
-<td BGCOLOR="#C0C0C0">
-<pre> <!-- (1) HTTP Connector for stand-alone operation -->
- <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
- <Parameter
- name="handler"
- value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
- <Parameter
- name="port"
- value="8080"/>
- </Connector>
-
- <!-- (2) AJPV12 Connector for out-of-process operation -->
- <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
- <Parameter
- name="handler"
- value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
- <Parameter
- name="port"
- value="8007"/>
- </Connector>
- </pre>
-</td>
-</tr>
-</table>
-
+<blockquote>
+<p>
+Currently (as of version 3.2) the procedure for deploying a new WAR file is:
<ol>
-<li>
-Is a Connector that listens on port 8080 for incoming HTTP requests. This
-connector is needed for stand-alone operation.</li>
-
-<li>
-Is a Connector that listens on port 8007 for incoming AJPV12 requests.
-This connector is needed for web-server integration (out-of-process servlet
-integration).</li>
+<li><b>Stop Tomcat</b>.
+</li>
+<li><b>Delete existing deployment.</b>
+If you have previously deployed "foo.war" in TOMCAT_HOME/webapps, then it has been unpacked into webapps/foo/... You must delete this directory and all its contents. On Unix, this can be done with <pre><big>rm -r $TOMCAT_HOME/webapps/foo</big></pre>
+</li>
+<li><b>Copy WAR file to TOMCAT_HOME/webapps/</b>.
+</li>
+<li><b>Start Tomcat</b>.
+</li>
</ol>
-It is clear that a sane Tomcat deployment will use either an out-of-process
-servlet integration or a stand-alone operation, removing the unnecessary
-Connector is important.
-<h3>
-Use a Thread Pool in your Connectors</h3>
-Tomcat is a multi-threaded servlet container this means that each request
-needs to be executed by some thread. By default when a request arrives
-Tomcat creates a new thread, starts it and has it serve the request. This
-behavior is problematic for loaded sites because:
-<ul>
-<li>
-Starting and stopping a thread for every request puts a needless burden
-on the operating system and the JVM.</li>
-
-<li>
-It is hard to limit the resource consumption. If 300 requests arrive concurrently
-Tomcat will open 300 threads to serve them and allocate all the resources
-needed to serve all the 300 requests at the same time. This causes Tomcat
-to allocate much more resources (CPU, Memory, Descriptors...) than it should
-and it can lead to low performance and even crashes if resources are exhausted.</li>
-</ul>
-The solution for these problems is to use a <b>thread pool</b>. Servlet
-containers that are using a thread pool relieve themselves from directly
-managing their threads. Instead of allocating new threads; whenever they
-need a thread they ask for it from the pool, and when they are done, the
-thread is returned to the pool. The thread pool can now be used to implement
-sophisticated thread management techniques, such as:
-<ol>
-<li>
-Keeping threads "open" and reusing them over and over again. This saves
-the trouble associated with creating and destroying threads continuously.</li>
-
-<ul>
-<li>
-Usually the administrator can instruct the pool not to keep too many idle
-threads, freeing them if needed.</li>
-</ul>
+</p>
-<li>
-Setting an upper bound on the number of threads used concurrently. This
-prevents the resources allocation problem associated with unlimited thread
-allocation.</li>
+<p>
+This process may become easier in the future. A "deploy tool" is on the Tomcat "to-do" list.
+</p>
+
+<p>
+Note that if you deploy a WAR file in this manner, you do not need to
+make any changes to <tt><big>server.xml</big></tt> -- it will
+automatically be recognized and activated when the server starts.
+However, if you wish to specify non-default options for this webapp,
+you may do so by adding an element like <tt><big><Context
+docBase="webapps/foo" ...</big></tt> to server.xml.
+</p>
+
+<p>
+See also <a href="http://www.jguru.com/jguru/faq/view.jsp?EID=123229">How do I
+deploy a WAR file in Tomcat?</a> in the jGuru FAQ.
+</p>
-<ul>
-<li>
-If the container maxed out to the threads upper limit, and a new request
-arrives, the new request will have to wait for some other (previous) request
-to finish and free the thread used to service it.</li>
-</ul>
-</ol>
-You can refine the techniques described above in various ways, but these
-are only refinements. The main contribution of thread pools is thread-reuse
-and having a concurrency upper bound that limits resource usage.
-<p>Using a thread pool in Tomcat is a simple move; all you need to do is
-to use a <tt>PoolTcpConnector</tt> in your <Connector> configuration.
-For example the following server.xml fragment defines ajpv12, pooled Connector:
-<table BORDER CELLSPACING=0 CELLPADDING=0 valign="middle" >
-<caption valign="bottom" width="100%"><i>Pooled ajpv12 Connector </i></caption>
-
-<tr>
-<td BGCOLOR="#C0C0C0">
-<pre> <!-- A pooled AJPV12 Connector for out-of-process operation -->
- <Connector className="org.apache.tomcat.service.PoolTcpConnector">
- <Parameter
- name="handler"
- value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
- <Parameter
- name="port"
- value="8007"/>
- </Connector>
- </pre>
-</td>
-</tr>
-</table>
-This fragment is very simple and the (default) pool behaviour instructed
-by it is:
-<ul>
-<li>
-Upper bound for concurrency of 50 threads.</li>
+</blockquote>
-<li>
-When the pool has more then 25 threads standing idle it will start to kill
-them.</li>
-
-<li>
-The pool will start 10 threads on creation, and it will try to keep 10
-vacant threads (as long as the upper bound is kept).</li>
-</ul>
-The default configuration is suitable for medium load sites with an average
-of 10-40 concurrent requests. If your site differs you should modify this
-configuration (for example reduce the upper limit). Configuring the pool
-can be done through the <Connector> element in server.xml as demonstrated
-in the next fragment:
-<table BORDER CELLSPACING=0 CELLPADDING=0 valign="middle" >
-<caption valign="bottom" width="100%"><i>Configuring the Thread Pool </i></caption>
-
-<tr>
-<td BGCOLOR="#C0C0C0">
-<pre> <!-- A pooled AJPV12 Connector for out-of-process operation -->
- <Connector className="org.apache.tomcat.service.PoolTcpConnector">
- <Parameter
- name="handler"
- value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
- <Parameter
- name="port"
- value="8007"/>
- <Parameter
- name="max_threads"
- value="30"/>
- <Parameter
- name="max_spare_threads"
- value="20"/>
- <Parameter
- name="min_spare_threads"
- value="5" />
- </Connector>
- </pre>
-</td>
-</tr>
-</table>
-As can be seen the pool has 3 configuration parameters:
-<ul>
-<li>
-max_threads - defines the upper bound to the for the concurrency, the pool
-will not create more then this number of threads.</li>
-
-<li>
-max_spare_threads - defines the maximum number of threads that the pool
-will keep idle. If the number of idle threads passes the value of max_spare_threads
-the pool will kill these threads.</li>
-
-<li>
-min_spare_threads - the pool will try to make sure that at any time there
-is at least this number of idle threads waiting for new requests to arrive.
-min_spare_threads must be bigger then 0.</li>
-</ul>
-You should use the above parameters to adjust the pool behavior to your
-needs.
-<h3>
-Disable Servlet Auto-Reloading</h3>
-Servlet auto-reloading is really useful for development time. However it
-is very expensive (in performance degradation terms) and may put your application
-in strange conflicts when classes that were loaded by a certain classloader
-cannot co-operate with classes loaded by the current classloader.
-<p>So, unless you have a real need for class reloading during your deployment
-you should turn off the reloadable flag in your contexts.
-<h3>
-Start Tomcat from /etc/inittab</h3>
-Unfortunately the adapters developed for Apache (or for any of the other
-servers) cannot start Tomcat yet. On UNIX however, you can use the init
-table to start Tomcat automatically upon machine startup. FIXME:
-<br><a NAME="credits"></a>
-<h2>
-Credits</h2>
-Tomcat was originally written by Sun Microsystems, and has been improved
-(we hope) by a <a href="http://jakarta.apache.org/credits/whoweare.html">cast
-of thousands</a>.
-<p>This document was created by:
-<ul><a href="mailto:shachor@il.ibm.com">Gal Shachor</a></ul>
-With help from (in alphabetical order):
-<ul>Jonathan Bnayahu
-<br>Alex Chaffee
-<br>Fiona Czuczman
-<br>Costin Manolache
-<br>Rob Slifka</ul>
-
-<table BORDER=0 CELLSPACING=0 CELLPADDING=10 WIDTH="100%" >
-<tr>
-<td>
-<div class="fineprint">Copyright ©1999 The Apache Software Foundation</div>
-
-<br><a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make
-Us Say</a>
-<br><a href="http://jakarta.apache.org/contact.html">Contact Information</a></td>
-</tr>
-</table>
+ <hr size="5">
+ <a name="tutorials">
+ <h3>Tomcat Tutorials</h3>
+
+ <p>These tutorials will be run with the assumption that Tomcat is operating
+ as a stand-alone container. Like we said before, it can be helpful to
+ understand Tomcat's functionality, irrespective of the particular web server
+ you're using. Trying to get more than one thing working at once
+ usually leads to more problems than its worth. Integration will be
+ covered later in subsequent sections.</p>
+
+ [Note: add some tutorials here :-) ]
+
+
+ <h2> Real World Configuration Tips </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 convenient. Yet, sometimes the scripts that are needed for
+ deployment should be modified:
+ <ul>
+ <li> To set resource limits such as maximum number of
+ descriptors. </li>
+ <li> To add new CLASSPATH entries (for example, JDBC drivers). </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>
+
+ 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 CLASSPATH 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... <div><b> Do not hesitate, just do it.</b> </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:
+ <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. There are several JVM vendors,
+ for example on Linux there are today (21/03/2000) two product level
+ JVMs: the SUN JDK1.2.2 and the IBM JDK1.1.8. If your application
+ does not require a specific JDK functionality, you should
+ benchmark the two JVMs and select the better one. In my (Gal
+ Shachor) internal tests I found the IBM JVM significantly faster
+ than the one created by SUN, you should check that for yourself
+ and make a calculated decision.
+ </li>
+ </ol>
+
+ <h3> Modify your Connectors </h3>
+ <p>
+ The Connectors, as configured in Tomcat's default server.xml
+ contains two Connectors configured as in the next server.xml
+ fragment:
+
+ <p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> The two default Connectors in server.xml </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+ <!-- (1) HTTP Connector for stand-alone operation -->
+ <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
+ <Parameter
+ name="handler"
+ value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
+ <Parameter
+ name="port"
+ value="8080"/>
+ </Connector>
+
+ <!-- (2) AJPV12 Connector for out-of-process operation -->
+ <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
+ <Parameter
+ name="handler"
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ <Parameter
+ name="port"
+ value="8007"/>
+ </Connector>
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ <ol>
+ <li> Is a Connector that listens on port 8080 for incoming HTTP
+ requests. This connector is needed for stand-alone
+ operation.
+ <li> Is a Connector that listens on port 8007 for incoming AJPV12
+ requests. This connector is needed for web-server
+ integration (out-of-process servlet integration).
+ </ol>
+
+ It is clear that a sane Tomcat deployment will use either an
+ out-of-process servlet integration or a stand-alone operation,
+ removing the unnecessary Connector is important.
+ <h3> Use a Thread Pool in your Connectors </h3>
+ <p>
+ Tomcat is a multi-threaded servlet container this means that each
+ request needs to be executed by some thread. By default when a
+ request arrives Tomcat creates a new thread, starts it and has it
+ serve the request. This behavior is problematic for loaded sites
+ because:
+ <ul>
+ <li>Starting and stopping a thread for every request puts a
+ needless burden on the operating system and the JVM. </li>
+ <li>It is hard to limit the resource consumption. If 300
+ requests arrive concurrently Tomcat will open 300
+ threads to serve them and allocate all the resources needed
+ to serve all the 300 requests at the same time. This causes
+ Tomcat to allocate much more resources (CPU, Memory,
+ Descriptors...) than it should and it can lead to low
+ performance and even crashes if resources are exhausted. </li>
+ </ul>
+ The solution for these problems is to use a <b>thread pool</b>.
+ Servlet containers that are using a thread pool relieve themselves
+ from directly managing their threads. Instead of allocating new
+ threads; whenever they need a thread they ask for it from the pool,
+ and when they are done, the thread is returned to the pool. The
+ thread pool can now be used to implement sophisticated thread
+ management techniques, such as:
+ <ol>
+ <li> Keeping threads "open" and reusing them over and over
+ again. This saves the trouble associated with creating and
+ destroying threads continuously.
+ <ul> <li>
+ Usually the administrator can instruct the pool not to keep
+ too many idle threads, freeing them if needed.
+ </li> </ul>
+ </li>
+ <li> Setting an upper bound on the number of threads used
+ concurrently. This prevents the resources allocation
+ problem associated with unlimited thread allocation.
+ <ul> <li>
+ If the container maxed out to the threads upper limit, and a new
+ request arrives, the new request will have to wait for
+ some other (previous) request to finish and free the thread
+ used to service it.
+ </li> </ul>
+ </li>
+ </ol>
+ You can refine the techniques described above in various ways, but
+ these are only refinements. The main contribution of thread pools is
+ thread-reuse and having a concurrency upper bound that limits
+ resource usage.
+
+ <p>
+ Using a thread pool in Tomcat is a simple move; all you need to do
+ is to use a <tt>PoolTcpConnector</tt> in your <Connector>
+ configuration. For example the following server.xml fragment defines
+ ajpv12, pooled Connector:
+
+ <p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> Pooled ajpv12 Connector </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+ <!-- A pooled AJPV12 Connector for out-of-process operation -->
+ <Connector className="org.apache.tomcat.service.PoolTcpConnector">
+ <Parameter
+ name="handler"
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ <Parameter
+ name="port"
+ value="8007"/>
+ </Connector>
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ This fragment is very simple and the (default) pool behaviour
+ instructed by it is:
+ <ul>
+ <li> Upper bound for concurrency of 50 threads. </li>
+ <li> When the pool has more then 25 threads standing idle it
+ will start to kill them. </li>
+ <li> The pool will start 10 threads on creation, and it will try
+ to keep 10 vacant threads (as long as the upper bound is
+ kept). </li>
+ </ul>
+ The default configuration is suitable for medium load sites with an
+ average of 10-40 concurrent requests. If your site differs you
+ should modify this configuration (for example reduce the upper
+ limit). Configuring the pool can be done through the <Connector>
+ element in server.xml as demonstrated in the next fragment:
+ <p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> Configuring the Thread Pool </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+ <!-- A pooled AJPV12 Connector for out-of-process operation -->
+ <Connector className="org.apache.tomcat.service.PoolTcpConnector">
+ <Parameter
+ name="handler"
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ <Parameter
+ name="port"
+ value="8007"/>
+ <Parameter
+ name="max_threads"
+ value="30"/>
+ <Parameter
+ name="max_spare_threads"
+ value="20"/>
+ <Parameter
+ name="min_spare_threads"
+ value="5" />
+ </Connector>
+ </pre>
+ </td>
+ </tr>
+ </table>
+ As can be seen the pool has 3 configuration parameters:
+ <ul>
+ <li> max_threads - defines the upper bound to the for the
+ concurrency, the pool will not create more then this number
+ of threads. </li>
+ <li> max_spare_threads - defines the maximum number of threads
+ that the pool will keep idle. If the number of idle threads
+ passes the value of max_spare_threads the pool will kill
+ these threads. </li>
+ <li> min_spare_threads - the pool will try to make sure that at
+ any time there is at least this number of idle threads
+ waiting for new requests to arrive. min_spare_threads must
+ be bigger then 0.</li>
+ </ul>
+
+ You should use the above parameters to adjust the pool behavior to
+ your needs.
+
+ <h3> Disable Servlet Auto-Reloading </h3>
+ <p>
+ Servlet auto-reloading is really useful for development time.
+ However it is very expensive (in performance degradation terms) and
+ may put your application in strange conflicts when classes that were
+ loaded by a certain classloader cannot co-operate with classes
+ loaded by the current classloader.
+ </p>
+ <p>
+ So, unless you have a real need for class reloading during your
+ deployment you should turn off the reloadable flag in your contexts.
+ </p>
+
+ <h3> Start Tomcat from /etc/inittab </h3>
+ <p>
+ Unfortunately the adapters developed for Apache (or for any of the
+ other servers) cannot start Tomcat yet. On UNIX however, you can
+ use the init table to start Tomcat automatically upon machine
+ startup. FIXME:
+ </p>
+
+<a name="credits">
+ <h2>Credits</h2>
+<p>Tomcat was originally written by Sun Microsystems, and has been improved (we hope) by a <a href="http://jakarta.apache.org/credits/whoweare.html">cast of thousands</a>.</p>
+ <p>
+ This document was created by:
+ <ul>
+ <a href="mailto:shachor@il.ibm.com"> Gal Shachor</a>
+ </ul>
+ With help from (in alphabetical order):
+ <ul>
+ Jonathan Bnayahu<br>
+ Alex Chaffee<br>
+ Fiona Czuczman<br>
+ Costin Manolache<br>
+ Rob Slifka<br>
+ </ul>
+
+ <table width="100%" border="0" cellpadding="10" cellspacing="0">
+ <tr>
+ <td>
+ <p class="fineprint">
+ Copyright ©1999 The Apache Software Foundation<br>
+ <a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make Us Say</a><br>
+ <a href="http://jakarta.apache.org/contact.html">Contact Information</a> </p>
+ </td>
+ </tr>
+ </table>
-</body>
+ </body>
</html>