larryi 01/10/18 20:18:44
Modified: src/doc tomcat-ug.html
Log:
Another round of updates. Finish the default server.xml section and
provide info on common customizations.
Revision Changes Path
1.18 +206 -46 jakarta-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.17
retrieving revision 1.18
diff -u -r1.17 -r1.18
--- tomcat-ug.html 2001/10/10 17:37:30 1.17
+++ tomcat-ug.html 2001/10/19 03:18:44 1.18
@@ -1,7 +1,7 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
- <!-- $Id: tomcat-ug.html,v 1.17 2001/10/10 17:37:30 larryi Exp $ -->
+ <!-- $Id: tomcat-ug.html,v 1.18 2001/10/19 03:18:44 larryi Exp $ -->
<!-- Copyright 1999-2001 Apache Software Foundation -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" type="text/css" href="style.css">
@@ -95,6 +95,7 @@
<li><a href="#configuring_classes">Configuring Classes</a></li>
<li><a href="#configuring_server">Configuring the Server</a></li>
</ul>
+ </li>
<li><a href="#container_types">Servlet Container Types</a></li>
<li><a href="#webapps">Deploying Web Applications</a></li>
<li><a href="#webapp">What is a Web Application?</a></li>
@@ -269,8 +270,7 @@
<ul>
<li><a href="http://jakarta.apache.org/site/binindex.html";>Download</a> the
- appropriate jakarta-tomcat-<i><version></i> binary archive file.</li>
- <br><br>
+ appropriate jakarta-tomcat-<i><version></i> binary archive
file.<br><br></li>
<li>Expand the archive into some directory (say /usr/local or C:\). This
should create a new subdirectory named
@@ -290,8 +290,7 @@
<ul>
<li>In a shell or DOS window, change to the
- <code>"jakarta-tomcat-<i><version></i>"</code> directory.</li>
- <br><br>
+ <code>"jakarta-tomcat-<i><version></i>"</code>
directory.<br><br></li>
<li>Set the environment variable JAVA_HOME to point to the root
directory of your JDK hierarchy. You may optionally add the Java
@@ -318,8 +317,7 @@
setenv PATH=$JAVA_HOME/bin:$PATH<br>
</big></tt>
</li>
- </ol></li>
- <br><br>
+ </ol><br><br></li>
<li>You may optionally set the TOMCAT_HOME environment variable. If
the supplied shell/batch scripts are executed from
@@ -339,8 +337,7 @@
<li>On UNIX (using tcsh) you should type: <br>
<tt><big>setenv
TOMCAT_HOME=/usr/local/jakarta-tomcat-<i><version></i>
</big></tt></li>
- </ol></li>
- <br><br>
+ </ol><br><br></li>
<li><a name="out_of_env"></a>If you are using Win9x, you will need to deal
with the potential <b>"Out of environment space"</b> problem, if you
@@ -540,7 +537,7 @@
<code>org.apache.tomcat.startup.Main</code> class in a Java VM. This class
and some classes it uses also accept arguments. To take advantage of the
full capabilities of Tomcat, you will need to become familiar with these
-arguments as will. See <a href="main_args">Tomcat's Main class arguments</a>
+arguments as well. See <a href="#tomcat_task_args">Tomcat Task Arguments</a>
for those details.</p>
<h3><a name="tomcat_actions">tomcat.sh/tomcat.bat Actions</a></h3>
@@ -705,13 +702,13 @@
<p>Customizing Tomcat will involve adding or modifying one or more files
involved with Tomcat. The next section describes the
-<a href="directory_structure">directory structure</a> of Tomcat 3.3 to document
+<a href="#directory_structure">directory structure</a> of Tomcat 3.3 to document
where files are found. Following that are sections document the two parts to
Tomcat configuration.</p>
<ul>
- <li><a href="configuring_classes">Configuring classes</a></li>
- <li><a href="configuring_server">Configuring the server</a></li>
+ <li><a href="#configuring_classes">Configuring classes</a></li>
+ <li><a href="#configuring_server">Configuring the server</a></li>
</ul>
<h3><a name="directory_structure">Tomcat Directory Structure</a></h3>
@@ -925,6 +922,16 @@
System property are added to the <b>Common Classloader</b> and entries found in
an <code>org.apache.tomcat.apps.classpath</code> are added to the <b>Apps
CLassloader</b>.</p>
+<p><b>Note:</b> In an instance of Tomcat 3.3 which is using
+<a href="serverxml.html#ReloadInterceptor">ReloadInterceptor</a> (the default),
+the <b>Webapp Classloader</b>, <b>Apps Classloader</b>, and <b>Common
classloader</b>
+are "wrapped" into a single classloader. This classloader will be an
+instance of <code>org.apache.tomcat.util.depend.DependClassLoader</code> or
+<code>org.apache.tomcat.util.depend.DependClassLoader12</code>, depending
+on which JDK you are using. This classloader checks for updates when classes
+are loaded from the "wrapped" classloaders so that reloads can
+be triggered when needed.</p>
+
<h3><a name="configuring_server">Configuring the Server</a></h3>
<h4>Overview</h4>
@@ -994,27 +1001,27 @@
<h4>Default Tomcat Configuration</h4>
-<p><i>This section will describe the default configuration supplied with Tomcat
3.3</i></p>
+<p>The default <code>server.xml</code> contains the following configuration.</p>
<table border="1">
<tr><th>Module Entry</th><th>Status</th><th>Description</th></tr>
<tr><td><<a href="serverxml.html#LoaderInterceptor11">LoaderInterceptor11</a>
useApplicationLoader="true" /></td><td> </td>
- <td> </td></tr>
+ <td>Constructs and sets the classloader for each context</td></tr>
<tr><td><<a href="serverxml.html#TrustedLoader">TrustedLoader</a> /></td>
<td> </td>
<td>Provides special handling for "trusted" contexts which have
a <code>interceptors.xml</code> file in their <code>WEB-INF</code>
directory.</td></tr>
<tr><td><<a href="serverxml.html#LogSetter">LogSetter</a>
- name="tc_log" timestamps="true"<br>
- verbosityLevel="INFORMATION"
/></td><td> </td>
+ name="tc_log" timestamps="true"<br>
+ verbosityLevel="INFORMATION"
/></td><td> </td>
<td>Sets up Tomcat's log output channel. In the absence of a <code>path</code>
setting, output goes to <code>stderr</code>.</td></tr>
- <tr><td><<a href="serverxml.html#LogEvents">LogEvents</a> enabled="false"
/></td><td> </td>
- <td> </td></tr>
+ <tr><td><<a href="serverxml.html#LogEvents">LogEvents</a>
enabled="false" /></td><td> </td>
+ <td>When enabled, logs when module methods are called.</td></tr>
<tr><td><<a href="serverxml.html#ContextXmlReader">ContextXmlReader</a>
- config="conf/server.xml" /></td><td> </td>
+ config="conf/server.xml" /></td><td> </td>
<td>Reads context definitions from the <code>server.xml</code> file for
backwards compatibility. This may be removed if you don't put
context definitions in your <code>server.xml</code> file.</td></tr>
@@ -1082,7 +1089,8 @@
execution.</td></tr>
<tr><td><<a href="serverxml.html#InvokerInterceptor">InvokerInterceptor</a>
/></td><td> </td>
- <td> </td></tr>
+ <td>Handles the "/servlet/<i>class name</i>" legacy method of
+ invoking servlets</td></tr>
<tr><td><<a href="serverxml.html#JspInterceptor">JspInterceptor</a>
keepGenerated="true"<br>
largeFile="false"<br>
@@ -1110,7 +1118,7 @@
against data obtained from an XML file. Since this module appears outside
of a Context definition, the user names and passwords in the specified
file apply to all contexts.</td></tr>
- <tr><td><JDBCRealm<br>
+ <tr><td><<a href="serverxml.html#JDBCRealm">JDBCRealm</a><br>
debug="99"<br>
driverName="sun.jdbc.odbc.JdbcOdbcDriver"<br>
connectionURL="jdbc:odbc:TOMCAT"<br>
@@ -1118,55 +1126,207 @@
userCredCol="user_pass"<br>
userRoleTable="user_roles"<br>
roleNameCol="role_name"
/></td><td>Disabled</td>
- <td> </td></tr>
+ <td>A replacement for SimpleRealm that reads usernames, passwords, and roles
+ from tables using JDBC.</td></tr>
<tr><td><<a
href="serverxml.html#LoadOnStartupInterceptor">LoadOnStartupInterceptor</a>
/></td><td> </td>
<td>Pre-loads servlets indicated as <load-on-startup> in a web.xml
file.</td></tr>
- <tr><td><Servlet22Interceptor /></td><td> </td>
- <td> </td></tr>
+ <tr><td><<a href="serverxml.html#Servlet22Interceptor">Servlet22Interceptor</a>
+ /></td><td> </td>
+ <td>Handles miscellaneous tasks that help implement behavior related to the
+ Servlet 2.2 specification.</td></tr>
<tr><td><<a href="serverxml.html#LogSetter">LogSetter</a>
name="tag_pool_log" timestamps="true"<br>
path="logs/tagpool-${yyyyMMdd}.log"<br>
verbosityLevel="INFORMATION"
/></td><td>Disabled</td>
- <td> </td></tr>
+ <td>Sets up the "tag_pool_log" log output channel.</td></tr>
<tr><td><<a
href="serverxml.html#TagPoolManagerInterceptor">TagPoolManagerInterceptor</a>
/></td><td>Disabled</td>
<td>Manages a pool of custom tag libary tag objects.</td></tr>
<tr><td><<a href="serverxml.html#DecodeInterceptor">DecodeInterceptor</a>
/></td><td> </td>
<td>Handles the determination of the encoding of a request.</td></tr>
- <tr><td><SessionId cookiesFirst="true" noCookies="false"
/></td><td> </td>
- <td> </td></tr>
+ <tr><td><<a href="serverxml.html#SessionId">SessionId</a>
+ cookiesFirst="true" noCookies="false"
/></td><td> </td>
+ <td>Handles associating sessions with requests and responses.</td></tr>
<tr><td><<a href="serverxml.html#ApacheConfig">ApacheConfig</a>
noRoot="true" /></td><td> </td>
- <td>Auto-generates a configuration file for use with
<code>mod_jk</code>.</td></tr>
+ <td>Generates a configuration file for use with <code>mod_jk</code>.</td></tr>
<tr><td><<a href="serverxml.html#IISConfig">IISConfig</a>
noRoot="true" /></td><td> </td>
- <td>Auto-generates a configuration file for use with
<code>isapi_redirect.dll</code>.</td></tr>
- <tr><td><NSConfig noRoot="true" /></td><td> </td>
- <td> </td></tr>
- <tr><td><AccessLogInterceptor/></td><td>Disabled</td>
- <td> </td></tr>
- <tr><td><Http10Connector port="8080"<br>
+ <td>Generates a configuration file for use with
<code>isapi_redirect.dll</code>.</td></tr>
+ <tr><td><<a href="serverxml.html#NSConfig">NSConfig</a>
+ noRoot="true" /></td><td> </td>
+ <td>Generates a configuration file for use with
<code>nsapi_redirect</code>.</td></tr>
+ <tr><td><<a href="serverxml.html#AccessLogInterceptor">AccessLogInterceptor</a>
+ /></td><td>Disabled</td>
+ <td>Writes a log file like Apache's AccessLog</td></tr>
+ <tr><td><<a href="serverxml.html#Http10Connector">Http10Connector</a>
port="8080"<br>
secure="false"<br>
maxThreads="100"<br>
maxSpareThreads="50"<br>
minSpareThreads="10"
/></td><td> </td>
- <td> </td></tr>
- <tr><td><Http10Connector port="8443" secure="true"
/></td><td>Disabled</td>
- <td> </td></tr>
- <tr><td><JniConnector /></td><td> </td>
- <td> </td></tr>
- <tr><td><Ajp12Connector tomcatAuthentication="false"
port="8007" /></td><td> </td>
- <td> </td></tr>
- <tr><td><Ajp13Connector port="8009" /></td><td> </td>
- <td> </td></tr>
+ <td>Handles incomming HTTP requests.</td></tr>
+ <tr><td><<a href="serverxml.html#Http10Connector">Http10Connector</a>
+ port="8443" secure="true" /></td><td>Disabled</td>
+ <td>Handles incomming HTTPS requests.</td></tr>
+ <tr><td><<a href="serverxml.html#JniConnector">JniConnector</a>
/></td><td> </td>
+ <td>Handles requests processed by Tomcat running in-process, provided
+ Tomcat was started in-process.</td></tr>
+ <tr><td><<a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
+ port="8007" /></td><td> </td>
+ <td>Handles Ajp12 protocol requests and Tomcat shutdown.</td></tr>
+ <tr><td><<a href="serverxml.html#Ajp13Connector">Ajp13Connector</a>
+ port="8009" /></td><td> </td>
+ <td>Handles Ajp13 protocol requests.</td></tr>
</table>
<h4>Tomcat Server Customization</h4>
+
+<p>The following are some of the more common customization made to the
+<code>server.xml</code> file.</p>
+
+<ol>
+<li><a href="#cust_chgports">Change ports for Http, Https, and Web Server
connectors</a></li>
+<li><a href="#cust_session">Speed up initial session creation for
development</a></li>
+<li><a href="#cust_auth">Configure whether Tomcat or a web server does
authentication</a></li>\
+<li><a href="#cust_dirlist">Turn off directory lisings</a></li>
+<li><a href="#cust_jikes">Use Jikes as the Java compiler</a></li>
+<li><a href="#cust_bind">Bind a connector to a single IP address</a></li>
+<li><a href="#cust_redeploy">Enable redeploying of WAR files</a></li>
+<li><a href="#cust_session">Disable cookie based sessions</a></li>
+</ol>
+
+<hr>
+
+<p>1. <a name="cust_chgports">Change ports for Http or Web Server connectors</a></p>
+
+<p>To change a port, search the <code>server.xml</code> file for the default
+value of the port and change it to the desired value.</p>
+
+<table border="1">
+ <tr><th>Connector</th><th>Default Port</th></tr>
+ <tr><td>Http</td><td>8080</td></tr>
+ <tr><td>Https</td><td>8443</td></tr>
+ <tr><td>Ajp12Connector</td><td>8007</td></tr>
+ <tr><td>Ajp13Connector</td><td>8009</td></tr>
+</table>
+<p>For example:</p>
+<pre>
+ <Http10Connector port="80" secure="false"
+ maxThreads="100" maxSpareThreads="50"
minSpareThreads="10" />
+</pre>
+
+<hr>
+
+<p>2. <a name="cust_session">Speed up initial session creation for
development</a></p>
+
+<p>The first request that requires a session can incur a delay when the
+<a href="serverxml.html#SessionIdGenerator">SessionIdGenerator</a> initializes
+the random number generator. This delay can be relatively long when using
+the default <code>java.security.SecureRandom</code> class. For development
+purposes, you can speed this up by switching to the <code>java.util.Random</code>
+class. For example:</p>
+<pre>
+ <SessionIdGenerator randomClass="java.util.Random"
randomFile="/dev/urandom" />
+</pre>
+<p>You should only use <code>java.util.Random</code> for development
+since the random sequence generated is predictable.</p>
+
+<hr>
+
+<p>3. <a name="cust_auth">Configure whether Tomcat or a web server does
authentication</a></p>
+
+<p>When Tomcat is used with a web server, such as Apache, the default is to have
+Tomcat continue to handle authentication. Any authenticated user specified in
+the request forwarded from the web server to Tomcat will be ignored.</p>
+
+<p>If you want Tomcat to make use of the authenticated user provided by
+the web server, add:</p>
+<pre>
+ tomcatAuthentication="false"
+</pre>
+<p>to the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a> or
+<a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> as appropriate.
+For example:</p>
+<pre>
+ <Ajp13Connector port="8009" tomcatAuthentication="false"
/>
+</pre>
+
+<hr>
+
+<p>4. <a name="cust_dirlist">Turn off directory lisings</a></p>
+
+<p>To turn off directory listings, change the <code>listings</code> attribute of
+the <a href="serverxml.html#StaticInterceptor">StaticInterceptor</a> to
+<code>false</code>. For example:</p>
+<pre>
+ <StaticInterceptor listings="false" />
+</pre>
+
+<hr>
+
+<p>5. <a name="cust_jikes">Use Jikes as the Java compiler</a></p>
+
+<p>To have Tomcat use Jikes as the Java compiler, add:</p>
+<pre>
+ javaCompiler="jikes"
+</pre>
+<p>to the <a href="serverxml.html#JspInterceptor">JspInterceptor</a>. For
example:</p>
+<pre>
+ <JspInterceptor javaCompiler="jikes" />
+</pre>
+
+<p>You may want to also set the <code>jikesClasspath</code> attribute to
+include any jars from the <code>jre/lib/ext</code> entensions directory, or any
+classes or jars not otherwise found in the <code>WEB-INF/classes</code> and
+<code>WEB-INF/lib</code> directories.</p>
+
+<p>If the Jikes executable isn't in your <code>PATH</code> environment
+variable, you will also need to set the <code>jspCompilerPath</code> attribute
+to the full path of the Jikes executable.</p>
+<hr>
+
+<p>6. <a name="cust_bind">Bind a connector to a single IP address</a></p>
+
+<p>By default, the <a href="serverxml.html#Ajp12Connector">Ajp12Connector</a>
+and <a href="serverxml.html#Ajp13Connector">Ajp13Connector</a> will accept
+connections from any IP address. To bind the connector to a single IP address,
+add an <code>address</code> attribute specifying the desired IP address.
+For example:</p>
+<pre>
+ <Ajp13Connector port="8009" address="127.0.0.1" />
+</pre>
+
+<hr>
+
+<p>7. <a name="cust_redeploy">Enable redeploying of WAR files</a></p>
+
+<p>The default behavior is to only deploy a WAR file if the target directory
+doesn't already exists. To enable automatic redeployment of WAR files, add:</p>
+<pre>
+ redeploy="true"
+</pre>
+<p>to the <a href="serverxml.html#AutoDeploy">AutoDeploy</a> with
+<code>source="webapps"</code>. In addition to re-deploying WAR files
+at startup, because a <a
href="serverxml.html#ReloadInterceptor">ReloadInterceptor</a>
+is part of the default configuration, WAR files will re-deploy and reload if
+updated while Tomcat is running.</p>
+
+<hr>
+
+<p>8. <a name="cust_session">Disable cookie based sessions</a></p>
+
+<p>To assist with testing a web application against browsers that have
+cookies disabled, you can disable the use of cookie bases sessions. Change the
+<code>noCookies</code> attribute of the <a
href="serverxml.html#SessionId">SessionId</a>
+module to <code>true</code>. For example:</p>
+<pre>
+ <SessionId cookiesFirst="true" noCookies="true" />
+</pre>
-<p><i>This section will describe the most common customizations</i></p>
+<hr>
<h4><a name="standard_contexts">Tomcat's Standard Contexts</a></h4>
@@ -1241,7 +1401,7 @@
<h2><a name="webapps">Deploying Web Applications</a></h2>
-<h3>What is a Web Application?</h3>
+<h3><a name="webapp">What is a Web Application?</a></h3>
<p>[??? - move this section up above the Configuring Tomcat section? It's
not clear whether we should teach about webapps before or after we
