You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by sh...@locus.apache.org on 2000/04/01 00:50:48 UTC
cvs commit: jakarta-tomcat/src/doc/uguide tomcat_ug.html
shachor 00/03/31 14:50:48
Modified: src/doc/uguide tomcat_ug.html
Log:
Covering the TOMCAT_OPTS variable and adding a few
cosmetic changes
Revision Changes Path
1.6 +246 -237 jakarta-tomcat/src/doc/uguide/tomcat_ug.html
Index: tomcat_ug.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/uguide/tomcat_ug.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- tomcat_ug.html 2000/03/30 11:45:52 1.5
+++ tomcat_ug.html 2000/03/31 22:50:47 1.6
@@ -1,7 +1,7 @@
<html>
<head>
- <!-- $Id: tomcat_ug.html,v 1.5 2000/03/30 11:45:52 shachor Exp $ -->
+ <!-- $Id: tomcat_ug.html,v 1.6 2000/03/31 22:50:47 shachor Exp $ -->
<!-- Copyright 1999, Apache Software Foundation -->
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href=style.css>
@@ -29,8 +29,8 @@
<H1>Tomcat - A Minimalistic User's Guide</H1>
<p>This document provides some basic information about Tomcat. Some of
- the issues covered here are:
-
+ the topics covered here are:
+
<ol>
<li>The installation of the Tomcat binary version. </li>
<li>The main issues related to scripts used by Tomcat. </li>
@@ -102,7 +102,7 @@
(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
+ 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>
<h2>What is the Difference Between Tomcat and Jserv? Isn't Tomcat==Jserv?</h2>
@@ -147,11 +147,11 @@
to your PATH environment variable.
</li>
</ul>
-
+
<p> That's it! You can now execute Tomcat and it will run as a
stand-alone (type 1) servlet container.
</p>
-
+
<h2>Starting and Stopping Tomcat</h2>
<p>You start and stop Tomcat using the scripts in
the bin directory.</p>
@@ -205,7 +205,7 @@
<tr>
<td> src </td>
<td> The servlet APIs source files. Don't get excited,
- though - these are only the empty interfaces and abstract
+ though; these are only the empty interfaces and abstract
classes that should be implemented by any servlet
container.</td>
</tr>
@@ -214,7 +214,7 @@
<td> Contains sample web applications. </td>
</tr>
</table>
-
+
<p>Additionally you can, or Tomcat will, create the following
directories:</p>
<table border width="75%" VALIGN="MIDDLE">
@@ -411,8 +411,9 @@
The ContextManager has a few attributes that provides it with:
<ol>
<li> Debug level used for logging debug messages. </li>
- <li> The base location for webapps/, conf/, logs/ and all defined contexts.
- It is used to start tomcat from directory different from TOMCAT_HOME.
+ <li> The base location for webapps/, conf/, logs/ and all defined contexts.
+ It is used to start Tomcat from a directory other than
+ TOMCAT_HOME.
</li>
<li> The name of the working directory. </li>
</ol>
@@ -421,21 +422,22 @@
<tr>
<td> ContextInterceptor & RequestInterceptor </td>
<td> These interceptors listen for certain events that happen in
- the ConetexManager. 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
+ 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
it's service.
- Tomcat's administrator does need to know much about the interceptors; a developer
- on the other hand should know that this is how "global" type of operations can be
- implemented in Tomcat (for example security and per request logging). </td>
+ Tomcat's administrator doesn't need to know much about the
+ interceptors; a developer on the other hand should know that this
+ is how "global" type of operations can be implemented in Tomcat
+ (for example, security and per request logging). </td>
</tr>
<tr>
<td> Connector </td>
- <td>The Connector represents a connection to the user, either
- through a web server or directly to the user's browser (in a
- stand-alone configuration).
+ <td>The Connector represents a connection to the user, either
+ through a web server or directly to the user's browser (in a
+ stand-alone configuration).
The connector object is the one responsible for the management of
- the Tomcat worker threads and for read/write requests/responses
+ the Tomcat worker threads and for read/write requests/responses
from the sockets connecting to the various clients.
The configuration of the connectors includes information such as:
@@ -449,20 +451,23 @@
</tr>
<tr>
<td> Context </td>
- <td> Each Context represents a path in the Tomcat hierarchy where you
- place a web application. A Tomcat Context has the following
+ <td> Each Context represents a path in the Tomcat hierarchy where you
+ place a web application. A Tomcat Context has the following
configuration:
<ol>
<li> The path where the context is located. This can be a full path
or relative to the ContextManager's home. </li>
<li> Debug level used for logging debug messages. </li>
- <li> A reloadable flag. When developing a servlet it is very convenient to have Tomcat
- reload it upon change, this let you fix bugs and have Tomcat test the new code without
- the need to shutdown and restart. 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 cast errors. To avoid these problems, you can set the reloadable flag to false;
- this will disable the autoreload feature.</li>
+ <li> A reloadable flag. When developing a servlet it is very
+ convenient to have Tomcat reload it upon change, this lets you
+ fix bugs and have Tomcat test the new code without the need to
+ shutdown and restart. 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>
</ol>
</td>
</tr>
@@ -472,23 +477,23 @@
<h3> Starting Tomcat From Another Directory </h3>
<p>By default tomcat will use TOMCAT_HOME/conf/server.xml for configuration. The default
- configuration will use TOMCAT_HOME as base for the contexts. </p>
- <p>You can change this by using "-f /path/to/server.xml" option, and a
- different server configuration file and setting the home property of
- the context manger. You need to set up the required files inside the
+ configuration will use TOMCAT_HOME as it's base for the contexts. </p>
+ <p>You can change this by using the "-f /path/to/server.xml" option, with a
+ different server configuration file and setting the home property of
+ the context manger. You need to set up the required files inside the
home: </p>
<ul>
- <li>A webapps/ directory (if you create one) - all war files will
+ <li>A webapps/ directory (if you created one) - 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>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 ContextManager.home property in server.xml is relative, it
+ <p>If the ContextManager.home property in server.xml is relative, it
will be relative to the current working directory.</p>
<h3> web.xml </h3>
@@ -509,7 +514,7 @@
<h2>Setting Tomcat to Cooperate with the Apache Web Server </h2>
- <p> Up until now, we have not discussed Tomcat as a server add on,
+ <p> Up until now we have not discussed Tomcat as a server add on,
instead we have considered it as a stand-alone container and discussed
how it can be used. There are however a few problems with this
picture:<p>
@@ -581,10 +586,10 @@
<h3> Making it on Apache </h3>
<p> This section shows you how to configure Apache to work with Tomcat;
- it tries to provide explainations as well as insight for the
- configuration directives that you should use. You can find
- additional information the
- <a href="in http://java.apache.org/jserv/install/index.html">
+ 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="in http://java.apache.org/jserv/install/index.html">
jserv install page </a>.
</p>
@@ -599,12 +604,12 @@
you add a new context.
</p>
<p>
- <b>Tomcat 3.1:</b> you must to restart tomcat and apache after adding
+ <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 Apache config file 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.
+ 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
@@ -692,14 +697,14 @@
</ul>
</li>
<li> This step sets the default communication parameters.
- Basically is says that the default protocol used for the communication
+ 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.
+ 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
@@ -708,13 +713,13 @@
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".
+ "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
+ 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
+ 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:
@@ -733,7 +738,7 @@
<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
+ 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
@@ -774,23 +779,23 @@
That's it; you have built mod_jserv...
</p>
<h3> Making Apache Serve your Context's Static Files </h3>
- <p> The previous Apache-Tomcat configuration file was a 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
+ <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
+ <li>You may want to configure Tomcat based security for these
resources. </li>
- <li>You may want to follow users requests for static resources
+ <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
+ 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>
<p> Having Apache serve the static files requires the following:
@@ -861,35 +866,35 @@
</p>
<p>
- As you can see, the beginning of this configuration file is the same
- as see in the previous example. The last step (mounting a context),
- however, was replaced in a long series of Apache and Ajp
+ 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 Ajp
configuration directives that will now be explained:
<ol>
- <li> This step informs Apache of the context location and alias it
- to an Apache virtual directory. This way Apache can serve files
+ <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
+ <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
+ <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 redirect these requests based on the default host and
+ <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
+ <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 s much more complex and
+ 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.
</p>
@@ -899,14 +904,14 @@
Sometimes it is useful to have different contexts handled by
different JVMs, for example:
<ul>
- <li> When each context serve a different specific task and runs
+ <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 using the same web server. </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 scheme where different contexts are served by
- different JVMs is very easy and the following configuration file
- demonstrates it:
+ Implementing such schemes where different contexts are served by
+ different JVMs is very easy and the following configuration file
+ demonstrates this:
</p>
<p>
<table border="1"
@@ -945,18 +950,18 @@
</table>
</p>
<p>
- As you can see in the previous example, using several JVMs (even such
- that runs 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.
+ 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 a different connector ports. For example,
- assuming that the two JVMs runs on localhost, the Apache-Tomcat
+ 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"
+ <table border="1"
cellspacing="0"
cellpadding="0"
valign="middle">
@@ -991,13 +996,13 @@
</tr>
</table>
<p>
- Looking at the above file you can see that we have two explicit Ajp
+ Looking at the above file you can see that we have two explicit Ajp
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> configuration 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>
+ <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"
@@ -1161,47 +1166,47 @@
</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 comes to avoid the two Tomcat processes from overwrite
- each other's logs and workspace.
+ 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
+ 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.
+ and then access them from Apache based on the different URL path
+ prefixes.
</p>
-
+
<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; you see, in Tomcat 3.1 each virtual host is implemented
- by a different Tomcat process.
+ 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 about each other,
- and in fact are not aware about 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:
+ 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"
+ <table border="1"
+ cellspacing="0"
cellpadding="0"
valign="middle">
<caption valign="bottom" width="100%">
@@ -1266,74 +1271,77 @@
</p>
<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 "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.
+ 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 previous section, the startup scripts are here for your
- convenient. Yet, sometimes the scripts that are needed for
+ 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
+ <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
+ <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
+ <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"
+ <li> To switch user from root to some other user using the "su"
UNIX command. </li>
<li> Your pet reason. </li>
</ul>
- On UNIX some of these changes can be done without explicit change to
- the basic scripts; you can create a file named <tt>".tomcatrc"</tt> in
+ 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
+ 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>
</p>
-
+
<h3> Modify the Default JVM Settings </h3>
- <p>
+ <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
+ 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
+ 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
+ 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
+ <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 is better).</li>
+ 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
+ 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>
@@ -1341,122 +1349,122 @@
<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
+ 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"
+ <p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
valign="middle">
- <caption valign="bottom" width="100%">
+ <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 -->
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+ <!-- (1) HTTP Connector for stand-alone operation -->
<Connector className="org.apache.tomcat.service.SimpleTcpConnector">
- <Parameter
- name="handler"
+ <Parameter
+ name="handler"
value="org.apache.tomcat.service.http.HttpConnectionHandler"/>
- <Parameter
+ <Parameter
name="port"
value="8080"/>
</Connector>
- <!-- (2) AJPV12 Connector for out-of-processs operation -->
+ <!-- (2) AJPV12 Connector for out-of-processs operation -->
<Connector className="org.apache.tomcat.service.SimpleTcpConnector">
- <Parameter
+ <Parameter
name="handler"
value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
- <Parameter
+ <Parameter
name="port"
value="8007"/>
</Connector>
- </pre>
- </td>
- </tr>
+ </pre>
+ </td>
+ </tr>
</table>
</p>
<ol>
- <li> Is Connector that listens on port 8080 for incoming HTTP
- requests. This connector is needed for stand-alone
+ <li> Is a Connector that listens on port 8080 for incoming HTTP
+ requests. This connector is needed for stand-alone
operation.
- <li> Is Connector that listens on port 8007 for incoming AJPV12
- requests. This connector is needed for web-server
+ <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>
+ </ol>
- It is clear that a sane Tomcat deployment will use either
- out-of-process servlet integration or stand-alone operation,
- removing the un-necessary Connector is important.
+ 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.
</p>
<h3> Use a Thread Pool in your Connectors </h3>
- <p>
- Tomcat is a multi-threaded servlet container this means that each
- request need to be executed by some thread. By default when a
- request arrives Tomcat creates a new thread, start it and have it
- serve the request. This behavior is problematic for loaded sites
+ <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
+ <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 will 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,
+ <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 relive 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
+ 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
+ <li> Keeping threads "open" and reusing them over and over
again. This saves the trouble associated with creating and
- destructing threads over and over again.
+ destructing threads continuously.
<ul> <li>
- Usually the administrator can instruct the pool not to keep
- too many idle threads freeing them if needed.
+ 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
+ <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 the thread upper bound and a
- new request arrive, that new request will have to wait for
+ 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
+ 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>
-
+ </p>
+
<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>
+ 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"
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
valign="middle">
- <caption valign="bottom" width="100%">
+ <caption valign="bottom" width="100%">
<em> Pooled ajpv12 Connector </em>
</caption>
<tr>
@@ -1487,10 +1495,10 @@
to keep 10 vacant threads (as long as the upper bound is
kept). </li>
</ul>
- The default configuration is suitable for medium load site with an
- average of 10-40 concurrent requests. If your site differs, you
+ 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 trough the <Connector>
+ limit). Configuring the pool can be done through the <Connector>
element in server.xml as demonstrated in the next fragment:
<p>
<table border="1"
@@ -1500,9 +1508,9 @@
<caption valign="bottom" width="100%">
<em> Configuring the Thread Pool </em>
</caption>
- <tr>
- <td bgcolor="#c0c0c0">
- <pre>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
<!-- A pooled AJPV12 Connector for out-of-processs operation -->
<Connector className="org.apache.tomcat.service.PoolTcpConnector">
<Parameter
@@ -1526,10 +1534,11 @@
</tr>
</table>
</p>
- As can be seen the pool as 3 configuration parametes:
+ As can be seen the pool has 3 configuration parametes:
<ul>
- <li> max_threads - defines the upper bound to the concurrency,
- the pool for not create more then this number of threads. </li>
+ <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
Re: cvs commit: jakarta-tomcat/src/doc/uguide tomcat_ug.html
Posted by Jean-Luc Rochat <jn...@cybercable.fr>.
Costin Manolache wrote:
>
> Jean-Luc Rochat wrote:
>
> > "Craig R. McClanahan" wrote:
> > >
> > > shachor@locus.apache.org wrote:
> > >
> > > > shachor 00/03/31 14:50:48
> > > >
> > > > Modified: src/doc/uguide tomcat_ug.html
> > > > Log:
> > > > Covering the TOMCAT_OPTS variable and adding a few
> > > > cosmetic changes
> > > >
> > >
> > > Thanks, Gal, you beat me to it. :-)
> > >
> > > I just checked in one more change you might want to mention -- you can now specify "-home {path}" or "-h
> > > {path}" on the Tomcat command line (i.e. as an argument to Tomcat) to set tomcat.home, in addition to the
> > > other methods. This was added to make it easier to integrate Tomcat into a development tool that SAS has
> > > built.
> > >
> > > Craig
> > Hi,
> >
> > just trying to use the automatic startup mode from apache, it appears
> > that another path could be made passed as a parameter : workDir
> > This one has now to be absolute in server.xml started by mod_jserv.
> > (or did I miss something ?)
> > Jean-Luc
>
> I thought I fixed that one.... It's not a show-stoper, but we can try to
> fix that too.
>
> Please don't make automatic startup the default - for apache 2.0 we'll
> probably use the IIS/NSAPI connector as a base - and the wrapper is
> not yet ported.
OK, I just committed changes in the wrapper that solve the problem. But
of course this does not affect the default which is still Manual mode.
I did not take care of these failures before, as I always started JServ
manually on remote machine(s) before.
>
> IMHO we should make the wrapper a standalone module, it doesn't
> have too many dependencies to the rest of the code.
> ( but that's a 3.2 discussion )
>
> Costin
Jean-Luc
Re: cvs commit: jakarta-tomcat/src/doc/uguide tomcat_ug.html
Posted by Costin Manolache <co...@eng.sun.com>.
Jean-Luc Rochat wrote:
> "Craig R. McClanahan" wrote:
> >
> > shachor@locus.apache.org wrote:
> >
> > > shachor 00/03/31 14:50:48
> > >
> > > Modified: src/doc/uguide tomcat_ug.html
> > > Log:
> > > Covering the TOMCAT_OPTS variable and adding a few
> > > cosmetic changes
> > >
> >
> > Thanks, Gal, you beat me to it. :-)
> >
> > I just checked in one more change you might want to mention -- you can now specify "-home {path}" or "-h
> > {path}" on the Tomcat command line (i.e. as an argument to Tomcat) to set tomcat.home, in addition to the
> > other methods. This was added to make it easier to integrate Tomcat into a development tool that SAS has
> > built.
> >
> > Craig
> Hi,
>
> just trying to use the automatic startup mode from apache, it appears
> that another path could be made passed as a parameter : workDir
> This one has now to be absolute in server.xml started by mod_jserv.
> (or did I miss something ?)
> Jean-Luc
I thought I fixed that one.... It's not a show-stoper, but we can try to
fix that too.
Please don't make automatic startup the default - for apache 2.0 we'll
probably use the IIS/NSAPI connector as a base - and the wrapper is
not yet ported.
IMHO we should make the wrapper a standalone module, it doesn't
have too many dependencies to the rest of the code.
( but that's a 3.2 discussion )
Costin
Re: cvs commit: jakarta-tomcat/src/doc/uguide tomcat_ug.html
Posted by Jean-Luc Rochat <jn...@cybercable.fr>.
"Craig R. McClanahan" wrote:
>
> shachor@locus.apache.org wrote:
>
> > shachor 00/03/31 14:50:48
> >
> > Modified: src/doc/uguide tomcat_ug.html
> > Log:
> > Covering the TOMCAT_OPTS variable and adding a few
> > cosmetic changes
> >
>
> Thanks, Gal, you beat me to it. :-)
>
> I just checked in one more change you might want to mention -- you can now specify "-home {path}" or "-h
> {path}" on the Tomcat command line (i.e. as an argument to Tomcat) to set tomcat.home, in addition to the
> other methods. This was added to make it easier to integrate Tomcat into a development tool that SAS has
> built.
>
> Craig
Hi,
just trying to use the automatic startup mode from apache, it appears
that another path could be made passed as a parameter : workDir
This one has now to be absolute in server.xml started by mod_jserv.
(or did I miss something ?)
Jean-Luc
Re: cvs commit: jakarta-tomcat/src/doc/uguide tomcat_ug.html
Posted by "Craig R. McClanahan" <Cr...@eng.sun.com>.
shachor@locus.apache.org wrote:
> shachor 00/03/31 14:50:48
>
> Modified: src/doc/uguide tomcat_ug.html
> Log:
> Covering the TOMCAT_OPTS variable and adding a few
> cosmetic changes
>
Thanks, Gal, you beat me to it. :-)
I just checked in one more change you might want to mention -- you can now specify "-home {path}" or "-h
{path}" on the Tomcat command line (i.e. as an argument to Tomcat) to set tomcat.home, in addition to the
other methods. This was added to make it easier to integrate Tomcat into a development tool that SAS has
built.
Craig