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/17 22:18:08 UTC
cvs commit: jakarta-tomcat/src/doc/uguide readme.txt
alex 00/08/17 13:18:08
Added: src/doc index.html style.css tomcat-apache-howto.html
tomcat-ug.html tomcat_security.txt
src/doc/images banner.gif tomcat.gif
src/doc/uguide readme.txt
Log:
Moved files from uguide subdirectory into this one
Split tomcat_ug.html into tomcat-ug.html and tomcat-apache-howto.html
Revised tomcat-ug.html (still needs work)
Added index.html with list of links to all files herein
Revision Changes Path
1.1 jakarta-tomcat/src/doc/index.html
Index: index.html
===================================================================
<html>
<head>
<!-- $Id: index.html,v 1.1 2000/08/17 20:18:06 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 Documentation</title>
</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 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="NT-Service-howto.html">NT-Service-howto.html</A>
</li>
<li> <A HREF="Tomcat-Workers-HowTo.html">Tomcat-Workers-HowTo.html</A>
</li>
<li> <A HREF="faq">faq</A> [obsolete?]
</li>
<li> <A HREF="in-process-howto.html">in-process-howto.html</A>
</li>
<li> <A HREF="internal.html">internal.html</A>
</li>
<li> <A HREF="mod_jk-howto.html">mod_jk-howto.html</A>
</li>
<li> <A HREF="readme">Tomcat 3.1 readme</A>
</li>
<li> <A HREF="tomcat-apache-howto.html">tomcat-apache-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>
</ul>
</body>
</html>
1.1 jakarta-tomcat/src/doc/style.css
Index: style.css
===================================================================
body {
font-family: "Times New Roman", Times, serif;
font-style: normal;
color: #000000;
background-color: #FFFFFF;
}
h1 {
font-family: Arial, Helvetica, sans-serif;
color: #0033CC
}
h2 {
font-family: Arial, Helvetica, sans-serif;
color: #0033CC
}
h3 {
font-family: Arial, Helvetica, sans-serif;
color: #0033CC
}
b {
font-weight: bold;
}
.code {
font-family: Courier, mono;
}
.codeblock {
font-family: Courier, mono;
}
.navheading {
font-family: Arial, Helvetica, sans-serif;
font-weight: bold;
color: #0033CC
}
.navitem {
font-family: "Times New Roman", Times, serif;
margin-left: 10pt;
color: #000000
}
.itemdef {
font-family: "Times New Roman", Times, serif;
font-size: smaller;
color: #000000
}
.fineprint {
font-family: Arial, Helvetica, sans-serif;
font-size: smaller;
color: #000000
}
1.1 jakarta-tomcat/src/doc/tomcat-apache-howto.html
Index: tomcat-apache-howto.html
===================================================================
<html>
<head>
<!-- $Id: tomcat-apache-howto.html,v 1.1 2000/08/17 20:18:06 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-Apache HOWTO</title>
</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-Apache HOWTO</H1>
<p>This document explains how to connect Tomcat to the popular
open source web server, Apache. It was originally part of
<i>Tomcat: A Minimalistic User's Guide</i> by Gal Shachor, but
has been split off for organizational reasons. 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>
Other important documents: <ul>
<li><a href="tomcat-ug.html">Tomcat User's Guide</a></li>
<li><a href="mod_jk-howto.html">mod_jk HOWTO</a> [??? should be rolled into tomcat-apache howto]</li>
<li><a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</a></li>
</ul>
<h3>Table of Contents</h3>
<ul>
[write me]
</ul>
<hr size="5">
<h3><a name="apache_tomcat_coop">Apache - Tomcat Cooperation - Sample Server
Integration</a></h3>
<p> Up until now we have not discussed Tomcat as a server add on,
instead we have considered it as a <a href="#type_1"> stand-alone</a> container and discussed
how it can be used. There are however a few problems with this
picture:
<ol>
<li> Tomcat is not as fast as Apache when it comes to static pages. </li>
<li> Tomcat is not as configurable as Apache. </li>
<li> Tomcat is not as robust as Apache. </li>
<li> There are many sites with long time investment in certain web servers,
for example, sites that are using CGI scripts/Server API modules/perl/php.
We cannot assume that all of them will want to ditch this legacy. </li>
</ol>
<p> For all these reasons it is recommended that real world sites
use an industrial strength web server, such as Apache, for serving the static content of
the site, and use Tomcat as a Servlet/JSP add-on.</p>
<p> Our agenda:
<ol>
<li> Cover the fundamental behavior of the web server. </li>
<li> Explain what configuration is needed. </li>
<li> Demonstrate this on Apache. </li>
</ol>
<hr size="5">
<h3><a name="common_errors">Common Installation and Configuration Problems</a></h3>
<blockquote>
<p>This section isn't meant to be your one-stop shop for all troubles
Tomcat, but a resource for stumbling blocks common to many first-time
Tomcat'ers. See the <a href="#where_help">help section</a> for
additional links.</p>
</blockquote>
<h4> <a name="error_8007">http://webserver:8007/ gives a
500</a></h4>
<blockquote>
<p>This is what you should see in your tomcat.log file:</p>
<blockquote>
<p class="code">HANDLER THREAD PROBLEM: java.io.IOException: Stream
broken</p>
</blockquote>
<p>By default, Tomcat listens for AJP connections on port 8007. AJP
is the protocol used to communicate between the web server and Tomcat, <b>not</b>
Tomcat and your browser. To test your Tomcat installation, FIX ME ?</p>
</blockquote>
<h4> <a name="error_ignore_directives"><Directory>
and <Location> directives ignored</a></h4>
<blockquote>
<p>FIX ME Apache never applies because forwarded to Tomcat.</p>
</blockquote>
<h4> <a name="error_web_server">Web server won't start
when Tomcat is running</a></h4>
<blockquote>
<p>FIX ME Port conflict.</p>
</blockquote>
<h4> <a name="error_bad_command">"Bad command or
filename" when executing Tomcat scripts</a></h4>
<blockquote>
<p>[FIX ME] UNIX file format on DOS. Because Tomcat is developed on
*nix (rather, the jars are built and distributed there), you may have to
convert the files to PC (versus UNIX) format.</p>
</blockquote>
<hr size="5">
<h3> Starting Tomcat From Another Directory </h3>
<h2>Setting Tomcat to Cooperate with the Apache Web Server </h2>
<h3> Web Server Operation </h3>
<p> In a nutshell a web server is waiting for client HTTP requests.
When these requests arrive the server does whatever is needed to
serve the requests by providing the necessary content. Adding a
servlet container may somewhat change this behavior. Now the web
server needs also to perform the following:
<ul>
<li> Load the servlet container adapter library and initialize it (prior
to serving requests). </li>
<li> When a request arrives, it needs to check and see if a certain
request belongs to a servlet, if so it needs to let the adapter
take the request and handle it.</li>
</ul>
The adapter on the other hand needs to know what requests it is
going to serve, usually based on some pattern in the request URL, and to
where to direct these requests.
<p>
Things are even more complex when the user wants to set a configuration
that uses virtual hosts, or when they want multiple developers to work
on the same web server but on different servlet container JVMs. We
will cover these two cases in the advanced sections.
</p>
<h3> What is the Needed Configuration </h3>
<p> The most obvious configuration that one can think of is the identity of the servlet URLs
that are under the responsibility of the servlet container. This is clear; someone must
know what requests to transmit to the servlet container...
Yet there are additional configuration items that we should provide to
the web-server/servlet-container combination:
<ul>
<li>We also need to provide configuration regarding the available Tomcat processes
and on which TCP/IP host/port they are listening. </li>
<li> We need to tell the web server the location of the adapter library (so it
will be able to load it on startup). </li>
<li> We need to set adapter internal information such as where and how much to log, etc. </li>
</ul>
All this information must appear either in the web server configuration, or in a private
configuration files used by the adapter. The next section will demonstrate how configuration
can be implemented on Apache.
<h3> Making it on Apache </h3>
<p> This section shows you how to configure Apache to work with Tomcat;
it tries to provide explanations as well as insight for the
configuration directives that you should use. You can find
additional information in the
<a href="http://java.apache.org/jserv/install/index.html">
jserv install page </a>.
</p>
<p> When Tomcat starts up it will automatically generate a configuration
file for Apache in <tt>TOMCAT_HOME/conf/tomcat-apache.conf</tt>. Most
of the time you don't need to do anything but include this file
(appending "Include TOMCAT_HOME/conf/tomcat-apache.conf") in your
httpd.conf. If you have special needs, for example an AJP port other
the 8007, you can use this file as a base for your customized
configuration and save the results in another file. If you manage
the Apache configuration yourself you'll need to update it whenever
you add a new context.
</p>
<p>
<b>Tomcat 3.1:</b> you must restart tomcat and apache after adding
a new context; Apache doesn't support configuration changes without a
restart. Also the file <tt>TOMCAT_HOME/conf/tomcat-apache.conf</tt> is
generated when tomcat starts, so you'll need to start Tomcat before
Apache. Tomcat will overwrite <tt>TOMCAT_HOME/conf/tomcat-apache.conf</tt>
each startup so customized configuration should be kept elsewhere.
</p>
<p> The Apache-Tomcat configuration uses Apache core configuration directives
as well as Jserv unique directives so it may confuse you at first, there are
however two things simplifying it:
<ul>
<li> In general you can distinguish between the two directive
"families" by noting that all the Jserv unique directives start
with an "ApJServ" prefix. </li>
<li> The entire Tomcat related configuration is concentrated in a
single configuration file named tomcat.conf, or the automatically
generated tomcat-apache.conf, so you can look at a single file.
</li>
</ul>
Lets look now at a sample tomcat.conf file.
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom">
<em>A Minimalistic Apache-Tomcat Configuration </em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
###########################################################
# A minimalistic Apache-Tomcat Configuration File #
###########################################################
# Note: this file should be appended or included into your httpd.conf
# (1) Loading the jserv module that serves as Tomcat's apache adapter.
LoadModule jserv_module libexec/mod_jserv.so
# (1a) Module dependent configuration.
<IfModule mod_jserv.c>
# (2) Meaning, Apache will not try to start Tomcat.
ApJServManual on
# (2a) Meaning, secure communication is off
ApJServSecretKey DISABLED
# (2b) Meaning, when virtual hosts are used, copy the mount
# points from the base server
ApJServMountCopy on
# (2c) Log level for the jserv module.
ApJServLogLevel notice
# (3) Meaning, the default communication protocol is ajpv12
ApJServDefaultProtocol ajpv12
# (3a) Default location for the Tomcat connectors.
# Located on the same host and on port 8007
ApJServDefaultHost localhost
ApJServDefaultPort 8007
# (4)
ApJServMount /examples /root
# Full URL mount
# ApJServMount /examples ajpv12://hostname:port/root
</IfModule>
</pre>
</td>
</tr>
</table>
<p>As you can see the configuration process was split into 4 steps
that will now be explained:
<ol>
<li> In this step we instruct Apache to load the jserv
shared-object (or the NT world dll). This is a well known Apache
directive. If the loading went well and the module came from a
file named mod_jserv.c (1a) we can start with the rest of the
Jserv-Tomcat configuration. </li>
<li> This step sets various Jserv internal parameters, these
parameters:
<ul>
<li> Instruct jserv not to start the Tomcat process. Automatically
starting Tomcat is not implemented yet.</li>
<li> Disable the secret key challenge/response between Apache and Tomcat.
Again, the secret key work is not implemented yet.</li>
<li> Instruct jserv to copy the base server mount points (see next
section) in case of virtual hosting. </li>
<li> Instruct jserv to use the notice log level. Other log levels
include emerg, alert, crit, error, warn, info and debug.</li>
</ul>
</li>
<li> This step sets the default communication parameters.
Basically it says that the default protocol used for the communication
is ajpv12 (do not mess with this one) and that the Tomcat process runs on
the same machine and listens on port 8007. If you run Tomcat on a
machine other than the one used
for Apache you should either update your ApJServDefaultHost or use a full
URL when mounting contexts (see next). Also, if you configured the Tomcat
connectors to use a port other then 8007, you should update your
ApJServDefaultPort or use a full URL when mounting contexts.
</li>
<li> This step mounts a context to Tomcat. Basically it says that
all the web server paths that start with /examples go to Tomcat. This
ApJServMount example is a rather simple one, in fact ApJServMount can
also provide information regarding the communication protocol to be used
and the location where the Tomcat process listens, for example:
<div><tt>ApJServMount /examples ajpv12://hostname:port/root</tt></div>
mounts the context /examples to a Tomcat process that runs on host
"hostname" and listens on port number "port".
</li>
</ol>
Now that you understand the different configuration instructions in the sample
file, how can you add it to the Apache configuration? One "simple" method is to
write it's content in the httpd.conf (the Apache configuration file), this however
can be very messy. Instead you should use the Apache include directive. At the end
of the Apache configuration file (httpd.conf) add the following directive:
<div> <tt>include <full path to the Tomcat configuration file> </tt></div>
for example:
<div> <tt>include /tome/tomcat/conf/tomcat.conf </tt></div> This
will add your Tomcat configuration to Apache, after that you should copy
the jserv module to the Apache libexec (or modules in the Win32 case)
directory and restart (stop+start) Apache. It should now be able to
connect to Tomcat.
<h3> Obtaining the Jserv Module (mod_jserv) </h3>
<p> As previously stated, we need a web server adapter to sit in Apache and redirect
requests to Tomcat. For Apache, this adapter is a slightly modified version of
mod_jserv.
</p>
<p> You may try to look <a href="http://jakarta.apache.org/downloads/binindex.html">
here </a> and see if there is an already pre-built version of mod_jserv that
suites your OS (Usually there is one for NT), however, being a native library you
should not expect that yet (too many OS's, not enough developers, life
too short...).
Moreover, small variations in the way you built Apache/Your specific UNIX variant may
result in dynamic linking errors. You should really try to build mod_jserv for your
system (don't panic, it is not that hard!).
</p>
<p>
Building mod_jserv on <b>UNIX</b> involves the following:
<ol>
<li> Download the source distribution of Tomcat from
<a href="http://jakarta.apache.org/downloads/sourceindex.html"> here</a>. </li>
<li> Uncompress it into some directory. </li>
<li> Building the module:
<ul>
<li> Change directory into jakarta-tomcat/src/native/apache/jserv/</li>
<li> Execute the build command <div><tt> apxs -c -o mod_jserv.so *.c </tt></div>
apxs is part of the Apache distribution and should be located in your
APACHE_HOME/bin.</li>
</ul>
</li>
</ol>
Building mod_jserv for <b>Win32</b> is less likely (you already have a downloadable dll
for Win32). Yet if you <em>want</em> to build it you should install Visual C++ and
perform the following:
<ol>
<li> Download the source distribution of Tomcat from
<a href="http://jakarta.apache.org/downloads/sourceindex.html"> here</a>. </li>
<li> Unzip it into some directory. </li>
<li> Building the module:
<ul>
<li> Change directory into jakarta-tomcat\src\native\apache\jserv</li>
<li> Add Visual C++ into your environment by executing the script
VCVARS32.BAT. </li>
<li> Execute the build command <div><tt> nmake -f Makefile.win32 </tt></div>
nmake is the Visual C++ make program.</li>
</ul>
</li>
</ol>
That's it; you have built mod_jserv...
<h3> Making Apache Serve your Context's Static Files </h3>
<p> The previous Apache-Tomcat configuration file was somewhat
inefficient, it instructed Apache to send any request for a resource
that starts with the <tt>/examples</tt> prefix to be served by
Tomcat. Do we really want that? There are many static files that may
be a part of our servlet context (for example images and static
HTML), why should Tomcat serve these files?
</p>
<p>You may actually have reasons for doing that, for example:
<ol>
<li>You may want to configure Tomcat based security for these
resources. </li>
<li>You may want to follow users requests for static resources
using interceptors. </li>
</ol>
In general however, this is not that case; and making Tomcat save
static files is just a CPU waste. We should instead have Apache serve
these static files and not Tomcat. Lets look now at a sample
tomcat.conf file that does exactly that:
<p> Having Apache serve the static files requires the following:
<ol>
<li>Instructing Apache to send all servlet requests to Tomcat. </li>
<li>Instructing Apache to send all JSP requests to Tomcat. </li>
</ol>
and leaving Apache to handle the rest. Lets look now at a sample
tomcat.conf file that does exactly that:
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom">
<em>Apache-Tomcat Configuration where Apache Serves the Static Content</em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
######################################################################
# Apache-Tomcat Smart Context Redirection #
######################################################################
LoadModule jserv_module modules/ApacheModuleJServ.dll
<IfModule mod_jserv.c>
ApJServManual on
ApJServDefaultProtocol ajpv12
ApJServSecretKey DISABLED
ApJServMountCopy on
ApJServLogLevel notice
ApJServDefaultHost localhost
ApJServDefaultPort 8007
#
# Mounting a single smart context:
#
# (1) Make Apache know about the context location.
Alias /examples D:\tomcat\webapps\examples
# (2) Optional, customize Apache context service.
<Directory "D:\tomcat\webapps\examples">
Options Indexes FollowSymLinks
# (2a) No directory indexing for the context root.
# Options -Indexes
# (2b) Set index.jsp to be the directory index file.
# DirectoryIndex index.jsp
</Directory>
# (3) Protect the WEB-INF directory from tampering.
<Location /examples/WEB-INF/>
AllowOverride None
deny from all
</Location>
# (4) Instructing Apache to send all the .jsp files under the context to the
# jserv servlet handler.
<LocationMatch /examples/*.jsp>
SetHandler jserv-servlet
</LocationMatch>
# (5) Direct known servlet URLs to Tomcat.
ApJServMount /examples/servlet /examples
# (6) Optional, direct servlet only contexts to Tomcat.
ApJServMount /servlet /ROOT
</IfModule>
</pre>
</td>
</tr>
</table>
<p>
As you can see, the beginning of this configuration file is the same
as seen in the previous example. The last step (mounting a context),
however, was replaced in a long series of Apache and ApJServ
configuration directives that will now be explained:
<ol>
<li> This step informs Apache of the context location and aliases it
to an Apache virtual directory. This way Apache can serve files
from this directory.</li>
<li> This optional step instructs Apache more about how to serve the
context; for example you can decide if Apache will allow
directory indexing (listing) or set a special index file.</li>
<li> This step instructs Apache to protect the WEB-INF directory
from client access. For security reasons it is important to
prevent visitors from viewing the content of the WEB-INF
directory, for example web.xml can provide valuable information
for intruders. This step blocks the WEB-INF content from
visitors. </li>
<li> This step instructs Apache to serve all the jsp locations
within the context using the jserv servlet handler. The servlet
handler redirects these requests based on the default host and
port.</li>
<li> This step mounts specific servlet URLs to Tomcat. You should
note that you should have as many such mount directives as the
number of specific servlet URLs. </li>
<li> This last step is an example for the addition of servlet only
context to Tomcat. </li>
</ol>
It is easy to see that this configuration is much more complex and
error prone then the first example, this however is the price that you
should (for now) pay for improved performance.
<h3> Configuring for Multiple Tomcat JVMs </h3>
<p>
Sometimes it is useful to have different contexts handled by
different JVMs, for example:
<ul>
<li> When each context serves a different, specific task and runs
on a different machine. </li>
<li> When we want to have multiple developers work on a private
Tomcat process but use the same web server. </li>
</ul>
Implementing such schemes where different contexts are served by
different JVMs is very easy and the following configuration file
demonstrates this:
<p>
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom" width="100%">
<em>Apache-Tomcat Configuration with per Context JVM </em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
######################################################################
# Apache-Tomcat with JVM per Context #
######################################################################
LoadModule jserv_module modules/ApacheModuleJServ.dll
<IfModule mod_jserv.c>
ApJServManual on
ApJServDefaultProtocol ajpv12
ApJServSecretKey DISABLED
ApJServMountCopy on
ApJServLogLevel notice
ApJServDefaultHost localhost
ApJServDefaultPort 8007
# Mounting the first context.
ApJServMount /joe ajpv12://joe.corp.com:8007/joe
# Mounting the second context.
ApJServMount /bill ajpv12://bill.corp.com:8007/bill
</IfModule>
</pre>
</td>
</tr>
</table>
<p>
As you can see in the previous example, using several JVMs (even even
those that run on different machines) can be accomplished easily by
using a full ajp URL mount. In this full URL we actually specify the
host where the Tomcat process is located and it's port.
</p>
<p>
Had the two Tomcat processes run on the same machine, we would have to
configure each of them with different connector ports. For example,
assuming that the two JVMs runs on localhost, the Apache-Tomcat
configuration should have something that looks like:
</p>
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom" width="100%">
<em> Same Machine Multiple JVM Apache-Tomcat Configuration </em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
######################################################################
# Apache-Tomcat with Same Machine JVM per Context #
######################################################################
LoadModule jserv_module modules/ApacheModuleJServ.dll
<IfModule mod_jserv.c>
ApJServManual on
ApJServDefaultProtocol ajpv12
ApJServSecretKey DISABLED
ApJServMountCopy on
ApJServLogLevel notice
ApJServDefaultHost localhost
ApJServDefaultPort 8007
# Mounting the first context.
ApJServMount /joe ajpv12://localhost:8007/joe
# Mounting the second context.
ApJServMount /bill ajpv12://localhost:8009/bill
</IfModule>
</pre>
</td>
</tr>
</table>
<p>
Looking at the above file you can see that we have two explicit ApJServ
mount points each pointing to a different port on the same machine. It
is clear that this configuration requires support from the configuration
found in the server.xml files. We will need in these files different
<Connector> configurations, for the different Tomcat processes. We
will actually need two different server.xml files (lets call them
server_joe.xml and server_bill.xml) with different <Connector>
entries as shown in the next two samples:
</p>
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom" width="100%">
<em> Joe's server.xml file </em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
<?xml version="1.0" encoding="ISO-8859-1"?>
<Server>
<!-- Debug low-level events in XmlMapper startup -->
<xmlmapper:debug level="0" />
<!-- @@@
Note, the log files are suffixed with _joe to distinguish
them from the bill files.
-->
<Logger name="tc_log"
path="logs/tomcat_joe.log"
customOutput="yes" />
<Logger name="servlet_log"
path="logs/servlet_joe.log"
customOutput="yes" />
<Logger name="JASPER_LOG"
path="logs/jasper_joe.log"
verbosityLevel = "INFORMATION" />
<!-- @@@
Note, the work directory is suffixed with _joe to distinguish
it from the bill work directory.
-->
<ContextManager debug="0" workDir="work_joe" >
<!-- Context level Setup -->
<ContextInterceptor
className="org.apache.tomcat.context.AutoSetup" />
<ContextInterceptor
className="org.apache.tomcat.context.DefaultCMSetter" />
<ContextInterceptor
className="org.apache.tomcat.context.WorkDirInterceptor" />
<ContextInterceptor
className="org.apache.tomcat.context.WebXmlReader" />
<ContextInterceptor
className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
<!-- Request processing -->
<RequestInterceptor
className="org.apache.tomcat.request.SimpleMapper" debug="0" />
<RequestInterceptor
className="org.apache.tomcat.request.SessionInterceptor" />
<RequestInterceptor
className="org.apache.tomcat.request.SecurityCheck" />
<RequestInterceptor
className="org.apache.tomcat.request.FixHeaders" />
<!-- @@@ This connector uses port number 8007 for it's ajp communication -->
<Connector
className="org.apache.tomcat.service.SimpleTcpConnector">
<Parameter
name="handler"
value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
<Parameter name="port" value="8007"/>
</Connector>
<!-- @@@ the /jow context -->
<Context path="/joe" docBase="webapps/joe" debug="0" reloadable="true" >
</Context>
</ContextManager>
</Server>
</pre>
</td>
</tr>
</table>
<p>
When looking at server_joe.xml you can see that the
<Connector> is configured for port 8007. In server_bill.xml
(see next) on the other hand the <Connector> is configured for
port 8009.
</p>
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom" width="100%">
<em> Bill's server.xml file </em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
<?xml version="1.0" encoding="ISO-8859-1"?>
<Server>
<!-- Debug low-level events in XmlMapper startup -->
<xmlmapper:debug level="0" />
<!-- @@@
Note, the log files are suffixed with _bill to distinguish
them from the joe files.
-->
<Logger name="tc_log"
path="logs/tomcat_bill.log"
customOutput="yes" />
<Logger name="servlet_log"
path="logs/servlet_bill.log"
customOutput="yes" />
<Logger name="JASPER_LOG"
path="logs/jasper_bill.log"
verbosityLevel = "INFORMATION" />
<!-- @@@
Note, the work directory is suffixed with _bill to distinguish
it from the joe work directory.
-->
<ContextManager debug="0" workDir="work_bill" >
<!-- Context level Setup -->
<ContextInterceptor
className="org.apache.tomcat.context.AutoSetup" />
<ContextInterceptor
className="org.apache.tomcat.context.DefaultCMSetter" />
<ContextInterceptor
className="org.apache.tomcat.context.WorkDirInterceptor" />
<ContextInterceptor
className="org.apache.tomcat.context.WebXmlReader" />
<ContextInterceptor
className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
<!-- Request processing -->
<RequestInterceptor
className="org.apache.tomcat.request.SimpleMapper" debug="0" />
<RequestInterceptor
className="org.apache.tomcat.request.SessionInterceptor" />
<RequestInterceptor
className="org.apache.tomcat.request.SecurityCheck" />
<RequestInterceptor
className="org.apache.tomcat.request.FixHeaders" />
<!-- @@@ This connector uses port number 8009 for it's ajp communication -->
<Connector className="org.apache.tomcat.service.SimpleTcpConnector">
<Parameter
name="handler"
value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
<Parameter name="port" value="8009"/>
</Connector>
<!-- @@@ the /bill context -->
<Context path="/bill" docBase="webapps/bill" debug="0" reloadable="true" >
</Context>
</ContextManager>
</Server>
</pre>
</td>
</tr>
</table>
<p>
The port configuration is not the only place where the joe and bill
configuration differs. We have @@@ marks in the xml files marking
the four places where changes had to be made. As you can see, this
difference is necessary to avoid the two Tomcat processes from
overwriting each other's logs and workspace.
</p>
<p>
Then we should start the two tomcat processes using the -f command
line option:
<div> bin\starup -f conf\server_joe.xml</div>
<div> bin\starup -f conf\server_bill.xml</div>
and then access them from Apache based on the different URL path
prefixes.
<h3> Configuring Virtual Hosting </h3>
<p>
It is possible to support virtual hosts under Tomcat Ver3.1, in fact
the virtual host configuration is very similar to configuring for
multiple JVM (as explained in the previous section) and the reason
is simple; in Tomcat 3.1 each virtual host is implemented by a
different Tomcat process.
</p>
<p>
With the current (Ver3.1) Tomcat, virtual hosting awareness is
provided by the web server (Apache/Netscape�). The web server
virtual hosting support is used by the Tomcat adapter to
redirect requests belonging to a certain virtual host to the JVM(s)
containing the contexts of this virtual host. This means that if (for
example) we have two virtual hosts (vhost1 and vhost2), we will have
two JVMs: one running the contexts of vhost1 and the other running
the contexts of vhost2. These JVMs are not aware of each others
existence, in fact, they are not aware of the concept of virtual
hosting. All the virtual hosting logic is inside the web-server
adapter. To make things clearer, lets look at the following sample
Apache-Tomcat configuration file:
</p>
<p>
<table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom" width="100%">
<em> Apache-Tomcat Configuration with Virtual Hosts Support </em>
</caption>
<tr>
<td bgcolor="#c0c0c0">
<pre>
######################################################################
# Apache Tomcat Virtual Hosts Sample Configuration #
######################################################################
LoadModule jserv_module modules/ApacheModuleJServ.dll
<IfModule mod_jserv.c>
ApJServManual on
ApJServDefaultProtocol ajpv12
ApJServSecretKey DISABLED
ApJServMountCopy on
ApJServLogLevel notice
ApJServDefaultHost localhost
ApJServDefaultPort 8007
# 1 Creating an Apache virtual host configuration
NameVirtualHost 9.148.16.139
# 2 Mounting the first virtual host
<VirtualHost 9.148.16.139>
ServerName www.vhost1.com
ApJServMount /examples ajpv12://localhost:8007/examples
</VirtualHost>
# 3 Mounting the second virtual host
<VirtualHost 9.148.16.139>
ServerName www.vhost2.com
ApJServMount /examples ajpv12://localhost:8009/examples
</VirtualHost>
</IfModule>
</pre>
</td>
</tr>
</table>
<p>
As can be seen, steps 1,2 and 3 define two Apache virtual hosts and
for each of them, mount the /examples context to a certain ajpv12 URL.
Each such ajpv12 URL points to a JVM that contains the virtual host.
The configuration of the two JVMs is very similar to the one
demonstrated in the previous section, we will need again to use two
different server.xml files (one for each virtual host process) and
we will need to start the Tomcat processes with the -f command line
option. After doing that we will be able to approach Apache, each
time with a different host name, and the adapter will redirect us to
the appropriate JVM.
</p>
<p>
<strong><u>The need for improved virtual host support</u></strong><br>
Having each virtual host implemented by a different JVM is a huge
scalability problem. The next versions of Tomcat will make it
possible to support several virtual hosts within the same Tomcat
JVM.
</p>
<a name="credits">
<h2>Credits</h2>
<p> This document was created by
<a href="mailto:shachor@il.ibm.com"> Gal Shachor</a>. It was split
off into a separate document and revised by Alex Chaffee and Rob
Slifka.
</ul>
With help from (in alphabetical order):
<ul>
Jonathan Bnayahu<br>
Alex Chaffee<br>
Fiona Czuczman<br>
Costin Manolache<br>
Rob Slifka<br>
</ul>
</p>
<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>
</html>
1.1 jakarta-tomcat/src/doc/tomcat-ug.html
Index: tomcat-ug.html
===================================================================
<html>
<head>
<!-- $Id: tomcat-ug.html,v 1.1 2000/08/17 20:18:06 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><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>
</p>
<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><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>
</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://http://jakarta.apache.org/jyve-faq/Turbine/screen/DisplayTopics/action/SetAll/project_id/2/faq_id/12"> 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.
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>
<a name="webapp">
<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>
<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>
</ul>
</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><big>/index.html
/howto.jsp
/feedback.jsp
/images/banner.gif
/images/jumping.gif
/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
</big></pre>
</blockquote>
</blockquote>
</p>
<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>
<a name="deploying_war">
<h4>Deploying WAR files in Tomcat</h4>
<blockquote>
<p>
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 <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>
</p>
<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>
</blockquote>
<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>
</html>
1.1 jakarta-tomcat/src/doc/tomcat_security.txt
Index: tomcat_security.txt
===================================================================
Using the Java SecurityManager with Tomcat
Why use a SecurityManager?
--------------------------
The Java SecurityManager is what allows your browser to run an applet
in its own sandbox to prevent untrusted code from accessing files
on your local system, connecting to a host other than the one the
applet was loaded from, etc.
In the same way the SecurityManager protects you from an untrusted
applet running in your browser, use of a SecurityManager while running
Tomcat can protect your server from trojan servlets, JSP's, JSP beans,
and tag libraries. Or even inadvertant mistakes.
Imagine if someone who is authorized to publish JSP's on your site
invadvertantly included the following in their JSP:
<% System.exit(1); %>
Everytime that JSP was executed by Tomcat, Tomcat would exit.
Using the Java SecurityManager is just one more line of defense
a system administrator can use to keep the server secure and reliable.
System Requirements
-------------------
Use of the SecurityManager requires a JVM that supports JDK 1.2.
Precautions
-----------
Implementation of a SecurityManager in Tomcat has not been fully
tested to ensure the security of Tomcat. No special Permissions
have been created to prevent access to internal Tomcat classes
by JSP's, web applications, servlets, beans, and tag libraries.
Make sure that you are satisfied with your SecurityManager
configuration before allowing untrusted users to publish
web applications, JSP's, servlets, beans, or tag-libraries.
Still, running with a SecurityManager is definitely better than
running without one.
Types of Permissions
--------------------
Permission classes are used to define what Permissions
a class loaded by Tomcat will have. There are a number
of Permission classes as part of the JDK and you can even
create your own Permission class for use in your own
web applications.
This is just a short summary of the System SecurityManager
Permission classes applicable to Tomcat. Please refer to
the JDK documenation for more information on using the below
Permissions.
java.util.PropertyPermission
Controls read/write access to JVM properties such as java.home.
java.lang.RuntimePermission
Controls use of some System/Runtime functions like exit() and exec().
java.io.FilePermission
Controls read/write/execute access to files and directories.
java.net.SocketPermission
Controls use of network sockets.
java.net.NetPermission
Controls use of multicast network connections.
java.lang.reflect.ReflectPermission
Controls use of reflection to do class introspection.
java.security.SecurityPermission
Controls access to Security methods.
java.security.AllPermission
Allows access to all permissions, just as if you were running
Tomcat without a SecurityManager.
Configuring Tomcat for use with a SecurityManager
-------------------------------------------------
conf/tomcat.policy
Used to configure global Permissions for java packages installed
in classpaths searchable by the JVM and for specifying default
Permissions for classes loaded from other sources. This is not
where Permissions are configured for web application Context's.
There should be entries with a codeBase of "file:${java.home}/lib/ext/-"
and "file:${tomcat.home}/lib/-" which grant AllPermissions.
And a default grant entry with no codeBase which has very
restrictive Permissions configured.
If tomcat generates an AccessControlException when you try to
start it with -security you need to edit the conf/tomcat.policy
file and replace ${tomcat.home} with the path to your Tomcat home directory.
By default read access on webapp dir and write in workdir is
granted to a web application.
The tomcat.policy file has an example of how to configure
additional permissions for a web application.
The tomcat.policy file replaces any system java.policy file.
conf/server.xml
Uncomment out the entry in server.xml for the ContextInterceptor
which defines the PolicyInterceptor.
Starting Tomcat with a SecurityManager
--------------------------------------
Once you have configured the tomcat.policy and server.xml
files for use with a SecurityManager, Tomcat can be started
with the SecurityManager in place by using the "-security"
opton to bin/startup.bat or bin/startup.sh.
What happens when the SecurityManager detects a Security violation?
-------------------------------------------------------------------
The JVM will throw an AccessControlException or a SecurityException
when the SecurityManager detects a security policy violation.
1.1 jakarta-tomcat/src/doc/images/banner.gif
<<Binary file>>
1.1 jakarta-tomcat/src/doc/images/tomcat.gif
<<Binary file>>
1.1 jakarta-tomcat/src/doc/uguide/readme.txt
Index: readme.txt
===================================================================
Files moved to src/doc