You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/25 21:52:06 UTC
svn commit: r1305109 [4/6] - in /tomcat/site/trunk/docs/tomcat-3.2-doc: ./
appdev/ appdev/sample/ appdev/sample/etc/ appdev/sample/src/
appdev/sample/web/ appdev/sample/web/images/ uguide/ uguide/images/
Added: tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-apache-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-apache-howto.html?rev=1305109&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-apache-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-apache-howto.html Sun Mar 25 19:52:05 2012
@@ -0,0 +1,1337 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+ <head>
+ <!-- $Id: tomcat-apache-howto.html,v 1.2.2.3 2001/02/01 16:52:21 danmil Exp $ -->
+ <!-- Copyright 1999, Apache Software Foundation -->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" href="uguide/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="uguide/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="uguide/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>
+ <p>
+ Other important documents: <ul>
+<li><a href="uguide/tomcat_ug.html">Tomcat User's Guide</a></li>
+<li><a href="http://jakarta.apache.org/faq/faqindex.html">Tomcat FAQ</a></li>
+<li><a href="mod_jk-howto.html">mod_jk HOWTO</a></li>
+</ul>
+ <h3>Table of Contents</h3>
+ <ul>
+ <li><a href="#intro">Introduction</a><br>
+ <a href="#cooperation_need">Need for cooperation</a><br>
+ <a href="#work_together">How will they work together?</a><br>
+ <a href="#pull_off">What's required to pull this off?</a><br>
+ </li>
+ <li><a href="#running_examples">Running Examples</a><br>
+
+ </li>
+ <li><a href="#configuring_tomcat">Configuring Tomcat</a><br>
+ <a href="#configuring_contexts">Setting up the
+ Contexts<br>
+ </a> <a href="#configuring_works">Making sure it all works
+ </a><br>
+ <a href="#configuring_connector">The AJP Connector<br>
+ </a>
+ </li>
+ <li>Configuring Apache
+ <ul>
+ <li><a href="#adapter">Web Server Adapter</a><br>
+ <a href="#adapter_jk_vs_js">mod_jk versus mod_jserv</a><br>
+ <a href="#adapter_where">Where do I get them?<br>
+ </a> <a href="#adapter_build">How do I build them?</a><br>
+ <a href="#adapter_configuration">Configuration implications</a></li>
+ <li><a href="#httpd">httpd.conf - Apache's main configuration file</a><br>
+ <a href="#httpd_jk">mod_jk.conf-auto</a><br>
+ <a href="#httpd_jserv">tomcat-apache.conf</a><br>
+ </li>
+ </ul>
+ </li>
+ <li><a href="#multiple">Multiple Tomcat JVMs</a><br>
+ <a href="#multiple_tomcat">Configuring Tomcat</a><br>
+ <a href="#multiple_apache">Configuring Apache</a><br>
+ </li>
+ <li><a href="#virtual_hosting">Virtual Hosting</a><br>
+ </li>
+ <li><a href="#common_errors">Common Installation and Configuration
+ Problems / Questions<br>
+ </a> <a href="#error_8007">Requesting <b>http://webserver:8007/</b>
+ produces an HTTP 500 error<br>
+ </a> <a href="#error_no_apache">Apache won't
+ start when Tomcat is running</a> / <a href="#error_no_apache">"BindException:
+ Address already in use"<br>
+ </a> <a href="#error_ignore_directives">Apache's <Directory>
+ and <Location> directives seemingly ignored<br>
+ </a> <a href="#error_no_requests">Tomcat isn't
+ receiving requests under /servlet</a><br>
+ <a href="#error_start_nobody">How do I get Tomcat to
+ start automatically as "nobody"?</a><br>
+ <a href="#error_same_machine">Can I run both
+ Apache/JServ and JServ/Tomcat on the same machine?</a><br>
+ <a href="#error_migrating_jhtml">Migrating from
+ Apache/JServ JSSI to Apache/Tomcat</a><br>
+ <a href="#error_jk_where">mod_jk - I want to use it,
+ but I can't find it. Where is it?</a><br>
+ <a href="#error_jk_apache_lock">mod_jk - Apache locks
+ up when requesting a Servlet or JSP</a><br>
+ <a href="#error_rewrite_usedto">mod_rewrite - Used to
+ work fine with Apache/JServ, what gives?</a><br>
+ <a href="#error_ssl_ie">mod_ssl - pages sometimes
+ don't finish loading using Internet Explorer<br>
+ </a> <a href="#error_ssl_http">mod_ssl - getScheme()
+ always returns HTTP!</a><br>
+ <br>
+ </li>
+ <li><a href="#credits">Credits</a></li>
+ </ul>
+
+ <hr size="5">
+ <h3><a name="intro">Introduction</a></h3>
+
+ <blockquote>
+ <h4><a name="cooperation_need">Need for cooperation</a></h4>
+
+ <blockquote>
+ <p>As stated in the Tomcat <a href="uguide/tomcat_ug.html">User's Guide</a>,
+ Tomcat currently supports <a href="uguide/tomcat_ug.html#container_types">three
+ modes</a> of execution. While it is entirely possible to have
+ Tomcat serve both your static and dynamic document provision needs, there
+ are several reasons why you might not want want to do this.
+ With respect to the Apache web server,
+ <p> 1. Tomcat is not as fast as Apache when it comes to static pages.<br>
+ 2. Tomcat is not as configurable as Apache.<br>
+ 3. Tomcat is not as robust as Apache.<br>
+ 4. Tomcat may not address many
+ sites' need for functionality found only in Apache modules (e.g. Perl,
+ PHP, etc.).
+
+ <p> For all these reasons it is recommended that real-world sites
+ use an industrial-strength web server, such as Apache, for serving static content, and use Tomcat as a Servlet/JSP add-on.</p>
+
+ </blockquote>
+ <h4><a name="work_together">How will they work together?</a></h4>
+
+ <blockquote>
+ <p> In a nutshell a web server is waiting for requests. When
+ these requests arrive the server does whatever is needed to
+ serve the requests by providing the necessary content. Adding
+ Tomcat to the mix may somewhat change this behavior. Now the web
+ server needs to perform the following:
+ <ul>
+ <li> Before the first request can be served, Apache needs to load a web
+ server adapter library (so Tomcat can communicate with Apache)
+ and initialize it. </li>
+ <li> When a request arrives, Apache needs to check and see if it
+ belongs to a servlet; if so it needs to let the adapter
+ take the request and handle it.</li>
+ </ul>
+
+ <p>We'd like Apache to handle our static content, such as
+ images and HTML documents, and forward all requests for
+ dynamic content to Tomcat. More specifically, we need answers to the following questions:</p>
+
+ <blockquote>
+ <p>1. How will Apache know which request / type of
+ requests should be forwarded to Tomcat?<br>
+ 2. How will Apache forward these requests to
+ Tomcat?<br>
+ 3. How will Tomcat accept and handle these requests?</p>
+ </blockquote>
+ <p>The majority of our time will be spent dealing with points 1 and 2;
+ 3 should be a snap!</p>
+ </blockquote>
+ <h4><a name="pull_off">What's required to pull this off?</a></h4>
+
+ <blockquote>
+ <p>Answers to the above three questions!</p>
+
+ <blockquote>
+ <p>1. Modify Apache's httpd.conf file.<br>
+ 2. Install a web server adapter.<br>
+ 3. Modify Tomcat's <a href="uguide/tomcat_ug.html#server_xml"> server.xml</a> file.</p>
+
+ </blockquote>
+ <p>It is assumed that you are comfortable modifying the configuration of Tomcat
+ and Apache separately before you've attempted to integrate the
+ two. As such, we speak in Tomcat/Apache/Servlet lingo, not pausing
+ to explain what's already been taught in their respective user
+ guides. Details on Tomcat setup can be found in the <a href="uguide/tomcat_ug.html">Tomcat
+ User's Guide</a>, while Apache configuration information can be found in
+ the <a href="http://www.apache.org/docs/">Apache User's Guide</a>.</p>
+
+ </blockquote>
+ </blockquote>
+
+ <hr size="5">
+
+
+ <h3><a name="running_examples">Running Examples</a></h3>
+
+ <p>Throughout this document, we'll refer back to these examples,
+ as these run the gambit of the commonly-desired Apache installs.</p>
+
+ <blockquote>
+ <p><b>Non-virtual Hosts</b></p>
+
+ <p><a name="example_1">1</a>. All JSP and Servlet
+ requests consisting of <a href="http://localhost/">http://localhost/</a>
+ are sent to the "rootExample" Context.<br>
+ <a name="example_2">2</a>. All JSP and Servlet
+ requests consisting of <a href="http://localhost/rootExample/">http://localhost/subdirExample/</a>
+ are sent to the "slifkaExample" Context.</p>
+
+ <p><b>Virtual Hosts</b><br>
+ <br>
+ <a name="example_3">3</a>. All JSP and Servlet
+ requests consisting of <a href="http://virtualhost/">http://virtualhost/</a>
+ are sent to "vhostExample" Context.<br>
+ <a name="example_4">4</a>. All JSP and Servlet
+ requests consisting of <a href="http://virtualhost/vhostSubdir/">http://virtualhost/vhostSubdir/</a>
+ are sent to the "vhostSubdir" Context.
+ </p>
+
+ </blockquote>
+
+ <p>As part of all of these configurations, servlets will be mounted as
+ well. To reach a servlet registered via a particular Context's
+ WEB-INF/<a href="uguide/tomcat_ug.html#web_xml">web.xml</a> file, we'll configure
+ it so that appending /servlet/registeredServletName to the URL does the
+ trick. For Example (2), let's say we had the
+ following as part of our web.xml for this context:
+ </p>
+
+ <blockquote>
+ <p class="code"> <servlet><br>
+
+ <servlet-name>SlifkaWorld</servlet-name><br>
+
+ <servlet-class>foo.bar.baz.SomeClass</servlet-class><br>
+ <init-param><br>
+
+ <param-name>someParameter</param-name><br>
+
+ <param-value>A value</param-value><br>
+ </init-param><br>
+ </servlet>
+ </p>
+
+ </blockquote>
+ <p>To reach this servlet, we would request: <a href="http://localhost/servlet/SimpleServlet">http://localhost/subdirExample/servlet/SlifkaWorld</a>
+ </p>
+
+ <p>If you're unsure as to what web.xml, Contexts, servlets, or webapps are,
+ then you probably haven't read through the Tomcat <a href="uguide/tomcat_ug.html">User's
+ Guide</a>. Get to it!
+ </p>
+
+ <hr size="5">
+
+
+ <h3><a name="configuring_tomcat">Configuring Tomcat</a></h3>
+
+ <p>We can configure Tomcat independantly of the other two items on our to-do
+ list. At this point,
+ we're assuming that you've followed the directions in the <a href="uguide/tomcat_ug.html">User's
+ Guide</a> and have Tomcat up and running in <a href="uguide/tomcat_ug.html#type_1">stand-alone</a>
+ mode.</p>
+
+ <blockquote>
+ <h4><a name="configuring_contexts">Setting up the Contexts</a></h4>
+
+ <blockquote>
+ <p>First off, let's explicitly define our example Contexts in Tomcat's <a href="uguide/tomcat_ug.html#server_xml">server.xml</a>.
+ The numbers preceding each configuration snippet refer to the
+ aforementioned <a href="#running_examples">Running Examples</a>.</p>
+
+ <blockquote>
+
+ <p class="code">1. <Context path="/"<br>
+
+ docBase="webapps/rootExample"/><br>
+ <br>
+ 2. <Context path="/slifkaExample"<br>
+
+ docBase="webapps/slifkaExample"/></p>
+
+ </blockquote>
+
+ <p>Example (3) must be placed inside a <Host> element in server.xml.
+ This is because a <Context> with the same path attribute exists
+ already; Example (1) is located at "/" as is (3). We place (4)
+ inside the <Host> element as well, because we only want it to be
+ accessible when people specify this virtual host in the
+ request. For more information on the <Host>
+ element, see the server.xml section of the User's Guide, and the <a href="#virtual_hosting">Virtual
+ Hosting</a> section below.</p>
+
+ <p>Remember
+ to omit the numbers 3 and 4 if you plan on pasting this in!</p>
+
+ <blockquote>
+ <p class="code"><Host name="fully-qualified name or IP of the
+ virtual host"><br>
+ <br>
+ 3. <Context path="/"<br>
+
+ docBase="webapps/vhostExample"/><br>
+ 4. <Context path="/vhostSubdir"<br>
+
+ docBase="webapps/vhostSubdir"/><br>
+ <br>
+ </Host></p>
+
+ </blockquote>
+ <p>After you've made the appropriate changes to server.xml, remember to
+ restart Tomcat.</p>
+
+ </blockquote>
+ <h4><a name="configuring_works">Making sure it all works</a></h4>
+
+ <blockquote>
+ <p>Where do we stand now? So
+ far it's just a normal Tomcat install, which you should be well-familiar
+ with by now from the <a href="uguide/tomcat_ug.html">User's Guide</a>. Tomcat should be serving all the
+ documents, both static and dynamic, for all of your Contexts. An
+ easy way to see which Contexts are serving which requests is to watch
+ your Tomcat log output, either via stdout/err or the log file.</p>
+
+ </blockquote>
+ <h4><a name="configuring_connector">The AJP Connector</a></h4>
+
+ <blockquote>
+ <p>Before we leave this section, there's one more Tomcat aspect to
+ discuss, the AJP <Connector> element in server.xml. This is
+ the mechanism by which Tomcat will communicate with Apache.</p>
+
+ <blockquote>
+ <p class="code"><!-- Apache AJP12 support. This is also used to shut down tomcat.
+ --><br>
+ <Connector
+ className="org.apache.tomcat.service.PoolTcpConnector"><br>
+ <Parameter name="handler"<br>
+
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/><br>
+ <Parameter name="port"<br>
+ value="8007"/><br>
+ </Connector></p>
+
+ </blockquote>
+ <p>To ensure that it is indeed listening on that port, Telnet to it or
+ HTTP request it. The Ajp12ConnectionHandler will throw an
+ exception (visible in the tomcat log file), and you'll know it's listening. As far as the web
+ server adapter goes, this is all you really need to know on the Tomcat
+ side for now.</p>
+
+ <p>Tomcat also supports AJP v1.3 via the Ajp13ConnectionHandler.
+ We'll get to this when we discuss mod_jk and mod_jserv later on.</p>
+
+ </blockquote>
+ </blockquote>
+
+ <hr size="5">
+
+
+ <h3> <a name="adapter">The Web Server Adapter</a> </h3>
+
+ <p> The next step in integrating Apache with Tomcat is to install a web
+ server adapter. This is the piece of software that will relay
+ information between Tomcat and Apache.
+ It doesn't really belong under Apache configuration, and it doesn't
+ really belong under Tomcat configuration, but it's required for both of them
+ to work together. </p>
+
+
+ <p> The web server adapter answers <a href="#pull_off"> question 2</a> posed above,
+ "How will Apache forward these requests to
+ Tomcat?" </p>
+ <blockquote>
+ <h4> <a name="adapter_jk_vs_js">mod_jk versus mod_jserv</a>
+ </h4>
+
+ <blockquote>
+ <p>Currently there are two adapters available - jk and JServ.
+ </p>
+
+ <p> Taken from our, "<a href="mod_jk-howto.html">mod_jk HOWTO</a>",
+ </p>
+
+ <blockquote>
+ <p>mod_jk is a replacement to the elderly mod_jserv. It is a completely new
+Tomcat-Apache plugin that passed adaptation to Tomcat. With some luck, working
+with it is going to be simpler for everyone. Here are some things to
+ consider:</p>
+
+<ul>
+ <li>mod_jserv was too complex
+ because it supported JServ specific requirements that Tomcat does not
+ pose.</li>
+ <li>mod_jserv supported only
+ Apache; on the other hand Tomcat supports many web servers through a
+ compatibility layer named the jk library. Supporting two different modes
+ of work became problematic in terms of support, documentation and bug
+ fixes. mod_jk should fix that.</li>
+ <li>The layered approach provided
+ by the jk library makes it easier to support both Apache1.3.x and
+ Apache2.xx.</li>
+ <li>mod_jserv only supports AJP v1.2. JServ is feature complete, and
+ won't be enhanced aside from bug fixes.</li>
+ <li>mod_jk supports
+ <ul>
+ <li>AJP v1.3 - reuse the TCP connection between Apache and Tomcat, much
+ faster.</li>
+ <li>JNI - the fastest if you have a multithreaded server like Apache 2.0.</li>
+ </ul>
+ </li>
+</ul>
+
+ </blockquote>
+ <font SIZE="2">
+ </font>
+
+ </blockquote>
+ <h4><a name="adapter_where">Where do I get them?</a></h4>
+ <blockquote>
+ <p>Binaries are available for Linux and Win32 under the bin directory where
+ you obtained the Tomcat distribution file. For Linux, JServ is available
+ as mod_jserv.so and Jk is available as mod_jk.so. For Win32, JServ is
+ available as ApacheModuleJServ.dll and Jk is available as mod_jk.dll.</p>
+ <p>For UNIX, JServ and Jk must be build from source. Source is available
+ as part of the Tomcat source distribution. JServ source is found in the
+ src/native/apache/jServ directory, which contains make files for UNIX and
+ Win32. Jk source is found in src/native/jk plus src/native/apache1.3 or
+ src/native/apache2.0 depending on which Apache is the target. Jk make files
+ for FreeBSD, Linux, Netware, and Win32 (as a Visual C++ 6 project file)
+ are found in the apache1.3 and apache2.0 directories. </p>
+ </blockquote>
+ <h4><a name="adapter_build">How do I build them?</a></h4>
+ <blockquote>
+ <p>The make files for JServ contain a small amount of documentation within.
+ A little more can be found in <a href="uguide/tomcat_ug.html#jserv_build">
+ User's Guide</a>. What we have below serves as a brief treatment of
+ the mod_jk build steps for Win32 and *nix. This is by no means meant
+ to be a complete treatment of the build process in all environments, just a
+ quick hit to get you started.</p>
+ <p>Win32 (an excerpt from our <a href="mod_jk-howto.html">mod_jk HOWTO</a>):</p>
+ <blockquote>
+
+<p>The redirector was developed using Visual C++ Ver.6.0, so having this
+environment is a prereq if you want to perform a custom build. The steps that you need to take are:</p>
+
+<ol>
+ <li>Change to the desired Apache (as explained above) source directory. </li>
+ <li>Set an APACHE1_HOME environment variable which points to where your Apache is
+ installed.</li>
+ <li>Execute the following
+ command:<br>
+ <span><tt><br>
+ </tt></span> <span><tt>MSDEV mod_jk.dsp /MAKE ALL</tt></span><br>
+ <br>
+ NOTE: If msdev is not in your path, enter the full path to msdev.exe. Also, ApacheCore.lib
+ is expected to exist in the APACHE1_HOME\src\CoreD and APACHE1_HOME\src\CoreR
+ directories before linking will succeed. You will need to build enough of the
+ Apache source to create these libraries.</li>
+ <li>Copy mod_jk.dll to Apache's modules directory.</li>
+</ol>
+
+<p>This will build both release and debug versions of the redirector plugin (mod_jk).
+An alternative will be to open <tt>mod_jk.dsp</tt> in msdev and build it using the build
+menu. </p>
+
+ </blockquote>
+ <p>UNIX:</p>
+ <blockquote>
+
+<ol>
+ <li>Change to the desired Apache (as explained above) source directory. </li>
+ <li>Set the environment variable $APACHE_HOME to the root of the Apache source
+ tree. </li>
+ <li>Execute the following command:<br>
+ <br>
+ ./build.sh </li>
+</ol>
+
+ </blockquote>
+ <p>That's it!</p>
+ </blockquote>
+ <h4> <a name="adapter_configuration">Configuration implications</a>
+ </h4>
+
+ <blockquote>
+ <p>The effects we're concerned with relate to the different
+ Apache directives each adapter makes available to us. Conceptually, we'll be
+ adding Apache directives to get the same job done, but depending on which
+ adapter you've chosen, they will differ. We will take both
+ adapters into consideration while explaining the Apache configuration in
+ subsequent sections.
+ </p>
+
+ </blockquote>
+ </blockquote>
+
+ <hr size="5">
+
+ <h3> <a name="httpd">httpd.conf - Apache's main configuration file</a>
+ </h3>
+
+ <p>Now that we've answered <a href="#pull_off">questions (2) and (3)</a>,
+ we're ready to dive into question (1) - Apache itself. We need to tell
+ Apache how to load and initialize our adapter, and that certain requests should be handled by
+ this adapter and
+ forwarded onto Tomcat. Which requests depends on your
+ configuration. Surprisingly enough, this part can be just as simple as
+ the previous two, considering that (surprise!) Tomcat does most of the work
+ for you.
+ </p>
+
+ <p> Each time you start Tomcat, after it loads Contexts (both from the
+ server.xml and automatically from $TOMCAT_HOME/webapps), it automagically
+ generates a number of files for you. The two that we're concerned with
+ are:
+ </p>
+
+ <ul>
+ <li>tomcat-apache.conf (should really be named mod_jserv.conf-auto)</li>
+ <li>mod_jk.conf-auto</li>
+ </ul>
+ <p>Both of these files do exactly what we want - supplement Apache's
+ httpd.conf file with the directives necessary to have Apache (Tomcat) serve
+ our static (dynamic) content needs. We'll be examining each file in
+ the coming sections. For many users, directly including one of these files in httpd.conf,
+ depending on the adapter you're using, suffices. For example, if
+ you're using mod_jk (which we suggest!), you would insert the following:
+ </p>
+
+ <blockquote>
+ <p><tt>include /tomcat/conf/mod_jk.conf-auto</tt>
+ </p>
+
+ </blockquote>
+ <p>...of course substituting in the directory you've installed Tomcat into,
+ in place of /tomcat. <b>NOTE: These files are generated each time Tomcat
+ starts, and a Tomcat configuration change affecting whichever file you're
+ including necessitates
+ an Apache restart. If you plan on customizing this file, do it
+ elsewhere, as it is overwritten at each restart.</b>
+ </p>
+
+ <blockquote>
+ <h4><a name="httpd_jk"> mod_jk.conf-auto</a>
+ </h4>
+
+ <blockquote>
+ <p>For now, refer to the comments in the mod_jk.conf-auto file and
+ <a href="mod_jk-howto.html">mod_jk HOWTO</a> for details.</p>
+
+ </blockquote>
+ <h4><a name="httpd_jserv">tomcat-apache.conf</a>
+ </h4>
+
+ <blockquote>
+ <p>This isn't nearly as verbose as the
+ mod_jk file, and is therefore a bit trickier to read through. What
+ you will see below is a condensed version of the .conf file generated from a server.xml
+ containing our <a href="#running_examples">Running Examples</a>. To
+ aid in our explanation of the file's contents, we've inserted comments
+ directly, and funked with the formatting.
+ </p>
+
+ <p>Before we get started, there is one JServ directive used extensively
+ that you should know about: ApJServMount. ApJServMount has the
+ following syntax:
+ </p>
+
+ <blockquote>
+ <p>ApJServMount <URI> <Tomcat process location and context in URI
+ format (relative or full)>
+ </p>
+
+ </blockquote>
+ <p>In English, this says, "Any request that starts with <URI>
+ should be passed on to <Tomcat process location and context> for
+ execution." Don't worry if it's not quite clear yet, examples
+ follow!
+ </p>
+
+ <p>This file has been modified quite a bit as the auto-generated one doesn't do
+ exactly what we want, and isn't laden with comments :-) but it comes pretty close! With the knowledge
+ gained thus far, this shouldn't be too much of a leap, so here goes:
+ </p>
+
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle" width="625">
+ <caption valign="bottom">
+ <em><b>Apache-Tomcat Configuration where Apache Serves the Static Content</b> </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0" width="621">
+ <pre>#######################################################
+#
+# BEGIN JServ Configuration
+#
+# Step (1) - See description following this sample file
+LoadModule jserv_module libexec/mod_jserv.so
+<IfModule mod_jserv.c></pre>
+ <pre># Step (2) - See description following this sample file
+ApJServManual on
+ApJServSecretKey DISABLED
+ApJServMountCopy on
+ApJServLogLevel notice</pre>
+ <pre># Step (3) - See description following this sample file
+ApJServDefaultProtocol ajpv12
+ApJServDefaultPort 8007
+# ADDED THIS LAST ONE MANUALLY - ed.
+ApJServDefaultHost localhost</pre>
+ <pre>#
+# END JServ Configuration
+#
+#######################################################</pre>
+ <pre># The following two lines register the JSP type with
+# Apache and instruct it to have all JSP requests
+# handled by the jserv-servlet handler.
+AddType text/jsp .jsp
+AddHandler jserv-servlet .jsp</pre>
+ <pre># WAS: ApJServMount /servlet /ROOT
+# WHY: We changed it because we want to explicitly state
+# that all requests to /servlet are sent to our
+# "/rootExample" context in Tomcat. See the details
+# of <a href="#example_1">Example (1)</a> above for more information.
+
+ApJServMount /servlet /rootExample</pre>
+ <pre>#######################################################
+#
+# Step (4) - BEGIN <a href="#example_1">Example (1)</a> Configuration
+#</pre>
+ <pre># Step (4a)
+# WAS: Alias /rootExample "/home/rslifka/tomcat/webapps/rootExample"
+# WHY: Why did we remove it? Well, this was here so that requests
+# to <a href="http://localhost/rootExample">http://localhost/rootExample</a> would serve the right
+# static documents. Unfortunately, we wanted our application residing
+# at the root of the server, and not under the /rootExample directory.
+#
+# The DocumentRoot should be set instead.</pre>
+ <pre>DocumentRoot /home/rslifka/tomcat/webapps/rootExample</pre>
+ <pre># Step (4b)
+# WHY: Just like a regular Apache setup, we're setting some
+# traits of how we'd like requests handled. See the Apache
+# <a href="http://www.apache.org/docs/">documentation</a> for more detail than you could ever want. ;)
+# This particular setup leaves directory indices on, which
+# most people turn off. To do that, you'd use the uncommented
+# line in the middle of the <Directory> element.
+<Directory "/home/rslifka/tomcat/webapps/rootExample">
+ Options Indexes FollowSymLinks
+# Options -Indexes
+</Directory></pre>
+ <pre># Step 4(c)
+# WAS: ApJServMount /rootExample/servlet /rootExample
+# WHY: Why did we remove it? Because we remapped the first
+# ApJServMount further up, before the configuration for
+# this context.</pre>
+ <pre># Step 4(d)
+# WHY: As per the <a href="http://java.sun.com/products/servlet/download.html">servlet spec</a>, nothing under WEB-INF should
+# be viewable since that's where all your gold (web.xml, etc.) is.
+# See the <a href="uguide/tomcat_ug.html">User's Guide</a> and servlet spec for more information on
+# the application hierarchy.
+<Location "/home/rslifka/tomcat/webapps/rootExample/WEB-INF/">
+ AllowOverride None
+ deny from all
+</Location></pre>
+ <pre>#
+# END Example(1) Configuration
+#
+#######################################################</pre>
+ <pre>#######################################################
+#
+# Step (5) - BEGIN <a href="#example_2">Example (2)</a> Configuration
+#</pre>
+ <pre>Alias /subdirExample /home/rslifka/tomcat/webapps/slifkaExample
+ApJServMount /subdirExample/servlet /slifkaExample</pre>
+ <pre><Location "/home/rslifka/tomcat/webapps/slifkaExample/WEB-INF/">
+ AllowOverride None
+ deny from all
+</Location></pre>
+ <pre><Directory "/home/rslifka/tomcat/webapps/slifkaExample">
+ Options Indexes FollowSymLinks
+</Directory></pre>
+ <pre>#
+# END Example(2) Configuration
+#
+#######################################################</pre>
+ <pre></IfModule></pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>All of the above directives, with the exception of anything prefixed
+ by "ApJServ" are extensively documented in the <a href="http://www.apache.org/docs/">Apache
+ User's Guide</a>. If you find our coverage brief, please look
+ there for the desired information.
+ </p>
+
+ <p>Below, we go into further detail about each commented step:
+ </p>
+
+ <blockquote>
+ <p>1. Instruct Apache to load the jserv
+ shared-object (or the NT world dll).
+ </p>
+
+ <blockquote>
+ <p>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 configuration.
+ </p>
+
+ </blockquote>
+ <p>2. This step sets various JServ internal
+ parameters, in order:</p>
+ <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>
+ <p>3. This step sets JServ's default communication
+ parameters.</p>
+ <blockquote>
+ <p>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.</p>
+ </blockquote>
+ <p>4. These steps "register" (for lack of
+ a better word) our <a href="#example_1">Example (1)</a> context
+ w/Apache.</p>
+ <blockquote>
+ <p> Most everything is explained up inside the example, but there
+ are a few things you should know. The first is that, as you
+ can see, contexts mounted at the root of your web (e.g. <a href="http://localhost/">http://localhost/</a>
+ versus <a href="http://localhost/myApp">http://localhost/myApp</a>)
+ server require a little more work than they would otherwise.
+ Second, don't take anything auto-generated for granted. It's a
+ very nice feature and works in many, many cases. Still though,
+ you're setting up two complicated pieces of software and should
+ probably be familiar with what it all means and why/how it all
+ works! Tomcat has no way of knowing how you're going to
+ "register" the context in Apache, and does its best to
+ guess.</p>
+ </blockquote>
+ <p> 5. These steps register our <a href="#example_2">Example
+ (2)</a> context w/Apache.</p>
+ <blockquote>
+ <p>There are two differences between Example (1) and Example (2)'s
+ setup. First, since the DocumentRoot is already defined and
+ mounted to our rootExample content (Example (1)), we use an Alias to
+ tell Apache how to serve up our static documents. Second, we
+ modify the ApJServMount directive to reflect the path that the
+ context resides in (/subdirExample).</p>
+ </blockquote>
+ </blockquote>
+ <p>Your configuration is complete! All you have to do now is
+ restart Apache, and you're cooking with gas.</p>
+ </blockquote>
+ </blockquote>
+
+ <hr size="5">
+
+ <h3><a name="multiple">Multiple Tomcat JVMs</a>
+ </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:
+ <blockquote>
+ <h4><a name="multiple_tomcat">Tomcat Configuration</a></h4>
+ <blockquote>
+ <p>Here's where we have to step back to Tomcat. First, you
+ have to be running two separate instances of Tomcat, hence the "mutliple
+ JVMs". Of course, each instance of Tomcat will need its web
+ adapter Connector listening on a unique port. You'll remember the
+ following snippet from server.xml in our AJP section:</p>
+ <blockquote>
+ <p class="code"><!-- Apache AJP12 support. This is also used to shut down tomcat.
+ --<<br>
+ <Connector className="org.apache.tomcat.service.PoolTcpConnector"><br>
+ <Parameter name="handler" <br>
+
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/><br>
+ <Parameter name="port"<br>
+
+ value="8007"/><br>
+ </Connector></p>
+ </blockquote>
+ <p>The key here is that each port parameter's "value"
+ attribute must have a different value. To keep in sync, let's
+ pretend that our <a href="#example_1">Example (1)</a> has its own
+ instance of Tomcat, as does <a href="#example_2">Example (2)</a>.
+ Example(1)'s port is 8007 and Example (2)'s port is 8009; they are both
+ running on the localhost.</p>
+ <p><b>NOTE: There are other changes required to run multiple instances
+ of Tomcat (e.g. specifying different logging directories). Those changes and more are covered in the <a href="uguide/tomcat_ug.html">User's
+ Guide</a>.</b></p>
+ </blockquote>
+ <h4><a name="multiple_apache">Apache Configuration</a></h4>
+ <blockquote>
+ <p>We've snipped out the irrelevant sections (at least to this example)
+ of the .conf file. The only change(s) you need to make, is to be a
+ bit more specific when instructing the web server adapter on how to find the Tomcat process
+ responsible for your context.</p>
+ <blockquote>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle" width="615">
+ <caption valign="bottom" width="100%">
+ <em>Apache-Tomcat Configuration with per Context JVM </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0" width="611">
+ <pre>
+[ snip! ]
+
+# Mounting Example (1)
+ApJServMount /servlet ajpv12://localhost:8007/rootExample
+
+
+# Mounting Example (2)
+ApJServMount /subdirExample/servlet ajpv12://localhost:8009/slifkaExample</pre>
+ <pre>[ snip! ]
+ </pre>
+ </td>
+ </tr>
+ </table>
+ </blockquote>
+ <p>As you can see, the key to integrating multiple instances with Apache
+ is to specify the full URL when mounting via the ApJServMount
+ directive. This is how you're able to tell JServ that the Tomcat
+ processes are each listening on separate ports. If the Tomcat
+ instances were running on separate machines, you would change the "localhost"
+ to the appropriate machine name in the ApJServMount directive(s).<p><b>NOTE:
+ Your $TOMCAT_HOME/conf/tomcat-apache.conf file is overwritten each time
+ you restart Tomcat. This configuration requires a custom tomcat-apache.conf,
+ so making your changes to, and subsequently including, one of the
+ auto-generated ones is a *bad idea*. Your changes will be
+ overwritten each time Tomcat restarts.</b>
+ </blockquote>
+ </blockquote>
+
+ <hr size="5">
+
+ <h3> <a name="virtual_hosting"> Virtual Hosting</a> </h3>
+ <p>Once you've got Apache configured correctly with the <VirtualHost>
+ entries (discussed in part below), getting virtual hosting working under Tomcat isn't that difficult.
+ There are two ways achieving this:</p>
+ <ol>
+ <li><b>Use a different Tomcat port (and therefore <a href="#multiple">multiple
+ instances</a> of Tomcat) between Apache and Tomcat per virtual
+ host.</b><br>
+
+ <ul>
+ <li>Advantages
+ <ul>
+ <li>Works in Tomcat 3.1 and 3.2</li>
+ <li>Because it sends calls for different Virtual Hosts to
+ different Tomcat JVMs, this can be used to spread the load over
+ several machines</li>
+ <li>Development can occur in isolation (an instance per developer)
+ but still use the same machine, and same overall installation of
+ Tomcat<br>
+ </li>
+ </ul>
+ </li>
+ <li>Disadvantages
+ <ul>
+ <li>Doesn't scale well (an instance of Tomcat per virtual host is
+ required)</li>
+ <li>Difficult to maintain for more than
+ a few hosts (requires a different server.xml for each virtual
+ host)<br>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li><b>Use the <Host> directive in Tomcats' server.xml file<br>
+ </b>
+ <ul>
+ <li>Advantages
+ <ul>
+ <li>Easier to set up</li>
+ <li>Uses less system resources => scales much better (only one
+ Tomcat instance, single adapter connector port)<br>
+ </li>
+ </ul>
+ </li>
+ <li>Disadvantages
+ <ul>
+ <li>Only works under Tomcat 3.2</li>
+ <li>If Tomcat needs to be restarted for one virtual host, it needs
+ to be restarted for all of them</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ol>
+ <p>To set up Apache and Tomcat using the first method, you need to set up a
+ different ports for Apache and Tomcat to communicate for each host. Here's a
+ sample Apache configuration (which uses mod_jserv):</p>
+
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle" width="536">
+ <caption valign="bottom" width="100%">
+ <em><b>Option 1 - Different Tomcat for each Apache Virtual Host</b></em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0" width="532">
+ <pre>
+[ snip! ]</pre>
+ <pre># Mount Example (3)s virtual host
+<VirtualHost 9.148.16.139>
+ServerName www.virtualhost.com
+DocumentRoot path-to-your-docbase
+ApJServMount /servlet ajpv12://localhost:8007/vhostExample
+</VirtualHost>
+
+# Mount Example (4)s virtual host
+<VirtualHost 9.148.16.139>
+ServerName www.virtualhost.com
+ApJServMount /servlet ajpv12://localhost:8009/examples
+DocumentRoot path-to-your-docbase
+</VirtualHost></pre>
+ <pre>[ snip! ]
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ <p><b>NOTE</b>: Remember to set the DocumentRoot so Apache knows where to
+ serve the static files from. In our mod_jserv and mod_jk examples,
+ this was done by specifying an Alias since the DocumentRoot was already
+ defined. Keep in mind that the ApJServMount is relative from the
+ DocumentRoot. What's a DocumentRoot and what's an Alias? See the <a href="http://www.apache.org/docs/">Apache
+ User's Guide</a>!
+ </p>
+
+ <p>
+ As you can see from the above example, using Tomcat in a virtual hosting environment isn't that different
+ insofar as Apache is concerned. Of course, you'll need to setup
+ the appropriate <VirtualHost> entries, but other than
+ that, there isn't much difference. Inside each virtual host entry,
+ you have all of your context-specific information in the usual way, and
+ that's it really.
+ </p>
+
+ <p>
+ Here is an example setup for a machine serving virtual hosts using the
+ second method described above.
+ </p>
+
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle" width="536">
+ <caption valign="bottom" width="100%">
+ <em><b>Option 2 - Same Tomcat for all Virtual Hosts (httpd.conf)</b></em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0" width="532">
+ <pre>
+[ snip! ]</pre>
+ <pre># Minimalistic Virtual Host configuration</pre>
+ <pre><VirtualHost 192.168.0.1>
+ServerName host1
+DocumentRoot /web/host1/html
+ApJServMount /servlet /ROOT
+<Directory "/web/host1/html/WEB-INF">
+Options None
+Deny from all
+</Directory>
+</VirtualHost>
+
+<VirtualHost 192.168.0.1>
+ServerName host2
+DocumentRoot /web/host2/html
+ApJServMount /servlet /ROOT
+<Directory "/web/host2/html/WEB-INF">
+Options None
+Deny from all
+</Directory>
+</VirtualHost></pre>
+ <pre>[ snip! ]
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ This creates two virtual hosts, host1 and host2, both running off of the
+ same IP - 192.168.0.1. Any requests for paths beginning with
+ "/servlet" are passed to Tomcat for processing, as are JSP
+ requests, providing of course that you've added the aforementioned
+ AddType and AddHandler directives.
+ </p>
+
+ <p>
+ Next, you need to configure Tomcat's <b>server.xml</b> file.
+ </p>
+
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle" width="536">
+ <caption valign="bottom" width="100%">
+ <em><b>Option 2 - Same Tomcat for all Virtual Hosts (server.xml)</b></em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0" width="532">
+ <pre>
+[ snip! ]</pre>
+ <pre># Minimalistic Virtual Host configuration</pre>
+ <pre><VirtualHost 192.168.0.1>
+ServerName host1
+DocumentRoot /web/host1/html
+ApJServMount /servlet /ROOT
+<Directory "/web/host1/html/WEB-INF">
+Options None
+Deny from all
+</Directory>
+</VirtualHost>
+
+<VirtualHost 192.168.0.1>
+ServerName host2
+DocumentRoot /web/host2/html
+ApJServMount /servlet /ROOT
+<Directory "/web/host2/html/WEB-INF">
+Options None
+Deny from all
+</Directory>
+</VirtualHost></pre>
+ <pre>[ snip! ]
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ That's it! Place your servlets in the WEB-INF/classes directory
+ for each virtual host, restart Tomcat and Apache, and you should be
+ away. If not, be sure to check the <a href="#common_errors">Common
+ Problems</a> section.
+ </p>
+
+ <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-Apache, but a resource for stumbling blocks common to many first-time
+ Tomcat'ers. See the <a href="uguide/tomcat_ug.html#where_help">help section</a>
+ of the <a href="uguide/tomcat_ug.html">User's Guide</a> for
+ additional links.</p>
+ <p>One thing that many users don't recall is that there is a
+ wealth of information to be found in the log files! Primarily, the tomcat.log
+ file in your $TOMCAT_HOME/logs directory, or wherever you've configured
+ it. If you want more detail, see the User's Guide for instructions
+ on how to edit your server.xml to have more verbose logging.</p>
+ <p>In addition, the web server adapter has a log file as well. It's
+ usually <adapter_name>.log (e.g. mod_jserv.log).</p>
+ <h4> <a name="error_8007">Requesting <b>http://webserver:8007/</b>
+ produces an HTTP 500 error</a></h4>
+ <blockquote>
+ <p>If this occurs, you should see a stack trace in your tomcat.log file, starting with:</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 a protocol used to communicate between the web server and Tomcat, <b>not</b>
+ Tomcat and your browser. Many first-time users mistakenly assume
+ that this is how you test your Tomcat installation or Tomcat-Apache
+ integration, while this is not the case.</p>
+ </blockquote>
+ <h4> <a name="error_no_apache">Apache doesn't start
+ when Tomcat is running</a></h4>
+ <blockquote>
+ <p>This most likely means that Tomcat is trying to use a port that is
+ already being used by someone else - usually Apache or another instance of
+ Tomcat. By default, Tomcat's comes configured to run an HTTP server on port
+ 8080. If you examine the supplied server.xml file, you'll see the
+ following element:</p>
+ <blockquote>
+ <p class="code"> <!-- Normal HTTP --><br>
+ <Connector className="org.apache.tomcat.service.PoolTcpConnector"><br>
+ <Parameter name="handler" <br>
+ value="org.apache.tomcat.service.http.HttpConnectionHandler"/><br>
+ <Parameter name="port" <br>
+ value="8080"/><br>
+ </Connector></p>
+ </blockquote>
+ <p>To disable this, just comment out the entire <Connector>
+ element. Otherwise, just change it to a port that doesn't conflict
+ with Apache. If you're not going to use the Tomcat HTTP server, and
+ you probably won't be if you are reading this document, disable it.</p>
+ <p>If you're running Apache / JServ, JServ may be clashing with Tomcat on
+ port 8007 as well.</p>
+ </blockquote>
+
+ <h4><a name="error_same_machine">Can I run both Apache/JServ and
+ Apache/Tomcat on the same machine?</a></h4>
+ <blockquote>
+ <p>Apparently you can, but you'll need to use mod_jserv rather than mod_jk.
+ As of Tomcat 3.2b2, the mod_jserv.so is the same as that used by
+ Apache/JServ. You will need to run Apache/JServ on a different port
+ to Tomcat, then you can control which servlet engine/container handles
+ which requests by specifying the appropriate port via the ApJServMount
+ directive in Apache's httpd.conf.</p>
+ </blockquote>
+
+ <h4> <a name="error_ignore_directives"><Directory>
+ and <Location> directives ignored</a></h4>
+ <blockquote>
+ <p>Apache forwards all requests underneath a mounting to Tomcat.
+ Let's say you had the following at the root-level of your httpd.conf
+ file. You're thinking, "I'll forward all JSP and Servlet
+ requests to Tomcat". What Apache thinks is, "I'll forward
+ EVERYTHING to Tomcat":</p>
+ <blockquote>
+
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle" width="536">
+ <caption valign="bottom" width="100%">
+ <em>Counter-intuitive Tomcat-Apache configuration</em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0" width="532">
+ <pre>
+[ snip! ]</pre>
+ <pre># OOPS! - Forward everything to Tomcat
+ApJServMount / ajpv12://myTomcatHost:1234/blah</pre>
+ <pre># Do not show directory indicies
+<Directory "/home/myApp">
+ AllowOverride AuthConfig
+ Options -Indexes
+</Directory>
+
+# Block WEB-INF from all viewing
+<Location "/home/myApp/WEB-INF/">
+ AllowOverride None
+ deny from all
+</Location>
+
+[ snip! ]
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ </blockquote>
+ <p><br>
+ What's happened here is that the first ApJServMount is saying,
+ "Anything under the root '/' should be forwarded to the following
+ Tomcat process/path for handling." This results in requests for
+ static documents being forwarded as well, which isn't what we want.
+ If I was told to 'fix' the above conf file, I would just change the '/'
+ after ApJServMount to "/servlet". You would have
+ already defined earlier up that all JSP requests go to the jserv-servlet
+ handler (see our <a href="#httpd_jserv">Apache-mod_jserv</a> configuration
+ section).
+ </p>
+ </blockquote>
+ <h4><a name="error_ssl_ie">mod_ssl - pages sometimes don't finish loading
+ using Internet Explorer</a>
+ </h4>
+ <blockquote>
+ <p>Tomcat sends data back to the browser using the Transfer-Encoding:
+ Chunked method. This causes problems with Internet Explorer when
+ using SSL. The solution is to make sure the first line of the
+ returned file isn't blank.
+ </p>
+ </blockquote>
+ <h4><a name="error_ssl_http">mod_ssl - getScheme() always returns HTTP!</a>
+ </h4>
+ <blockquote>
+ <p>The protocol used by mod_jserv can't identify whether a page was
+ requested via HTTP or HTTPS. Yes, Apache/JServ did it, but that
+ was a hack (just checked for requests on port 443). The solution
+ is either to check for port 443 yourself, or to upgrade to mod_jk and
+ the ajpv13 protocol. Another symptom of this is finding requests
+ redirected to <a href="http://yourserver.com:443">http://yourserver.com:443</a>
+ rather than <a href="https://yourserver.com/">https://yourserver.com/</a>.
+ </p>
+ </blockquote>
+ <h4><a name="error_migrating_jhtml">Migrating from Apache/JServ JSSI
+ to Apache/Tomcat</a>
+ </h4>
+ <blockquote>
+ <p>Tomcat doesn't support JSSI. Until someone writes an Interceptor to
+ handle them, the easiest way is to convert your .jhtml files to .jsp
+ files. Just replace:
+ </p>
+ <blockquote>
+ <p class="code"><font SIZE="2"><servlet name=myServlet><br>
+ <param name=aParam value=aValue><br>
+ </servlet></font></p>
+ </blockquote>
+ <p>with
+ </p>
+ <blockquote>
+ <p class="code"><font
+ SIZE="2"><jsp:include page="/servlet/myServlet"
+ flush="true" ><br>
+ <jsp:param name="aParam"
+ value="aValue" /><br>
+ </jsp:include></font></p>
+ </blockquote>
+ </blockquote>
+ <h4><a name="error_rewrite_usedto">mod_rewrite - Used to work fine with
+ Apache/JServ, what gives?</a>
+ </h4>
+ <blockquote>
+ <p>Tomcat implements the servlet specification v2.2, whereas JServ
+ implemented version 2.1. In the newer version, there are tighter
+ restrictions on the mapping from URL (what the user requests) to the
+ filename (what they get). Specifically, it insists that:
+ </p>
+ <blockquote>
+ <p class="code">request URI = context path + servlet path + path info
+ </p>
+ </blockquote>
+ <p>This means that the arbitrary mappings that mod_rewrite is capable of
+ simply won't work without breaking the Servlet specification. One
+ solutions is to use the [R] flag on the RewriteRule directive to
+ "externally redirect" the request.
+ </p>
+ </blockquote>
+ <h4><a name="error_no_requests">Tomcat isn't receiving requests under
+ /servlet</a>
+ </h4>
+ <blockquote>
+ <p>If you have a "<Location />" directive in your
+ httpd.conf file, this will take precedence over any ApJServMount
+ directives. The following example won't forward "/servlet"
+ requests to Tomcat.
+ </p>
+ <blockquote>
+ <p class="code">ApJServMount /servlet /ROOT<br>
+ <Location /><br>
+ Options Indexes Multiviews<br>
+ </Location>
+ </p>
+ </blockquote>
+ <p>A workaround is to use <Directory> instead of <Location>
+ </p>
+ </blockquote>
+ <h4><a name="error_start_nobody">How do I get Tomcat to start
+ automatically as "nobody"?</a></h4>
+ <blockquote>
+ <p>If your UNIX-style box has an "rc.d"-style boot directory
+ (Solaris, RedHat, etc.), then the simplest way is to create a file in the
+ appropriate boot directory which looks something like this:
+ </p>
+ <blockquote>
+ <p class="code">#!/bin/sh<br>
+ CLASSPATH=/your/classpath/here<br>
+ export CLASSPATH<br>
+ su - nobody -c "/tomcat/bin/tomcat.sh $@"
+ </p>
+ </blockquote>
+ <p>You can then invoke this as /etc/rc.d/init.d/tomcat (start | stop) from
+ your boot sequence in the same way that you start Apache (for instance).
+ </p>
+ </blockquote>
+ <h4><a name="error_jk_where">mod_jk - I want to use it, but I can't find
+ it. Where is it?</a>
+ </h4>
+ <blockquote>
+ <p>As of this writing (Sept. 30, 2000) mod_jk has to be built from the
+ Tomcat source distibution.
+ </p>
+ </blockquote>
+ <h4><a name="error_jk_apache_lock">mod_jk - Apache locks up when
+ requesting a Servlet or JSP</a>
+ </h4>
+ <blockquote>
+ <p>mod_jk reuses the same port when talking to Tomcat, unlike mod_jserv.
+ You'll need to restart Apache whenever you restart Tomcat.
+ </p>
+ </blockquote>
+ </blockquote>
+
+ <hr size="5">
+ <h2><a name="credits">Credits</a></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 Rob Slifka and Mike Bremford.
+ Contributors, listed in alphabetical order:
+ <ul>
+ <li>Jonathan Bnayahu<br>
+ <li>Mike Bremford<br>
+ <li>Alex Chaffee<br>
+ <li>Fiona Czuczman<br>
+ <li>Costin Manolache<br>
+ <li>Chris Pepper<br>
+ <li>Rob Slifka<br>
+ <li>...the countless many on the tomcat-dev and tomcat-user lists!
+ </ul>
+
+ <table width="100%" border="0" cellpadding="10" cellspacing="0">
+ <tr>
+ <td>
+ <p class="fineprint">
+ Copyright ©1999-2000 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>
Propchange: tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-apache-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-iis-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-iis-howto.html?rev=1305109&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-iis-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-iis-howto.html Sun Mar 25 19:52:05 2012
@@ -0,0 +1,457 @@
+<html>
+
+<head>
+<title>Tomcat IIS HowTo</title>
+</head>
+
+<body>
+
+<h1>Tomcat IIS HowTo</h1>
+
+<p>By Gal Shachor <tt><shachor@il.ibm.com></tt></p>
+
+<p>This document explains how to set up IIS to cooperate with Tomcat.
+Normally IIS can not execute Servlets and Java Server Pages (JSPs),
+configuring IIS to use the Tomcat redirector plugin will let IIS send servlet
+and JSP requests to Tomcat (and this way, serve them to clients). </p>
+
+<h2>Document Conventions and Assumptions</h2>
+
+<p><tomcat_home> is the root directory of tomcat. Your Tomcat
+installation should have the following subdirectories:
+
+<ol>
+ <li><tomcat_home>\conf - Where you can place various configuration files</li>
+ <li><tomcat_home>\webapps - Containing example applications </li>
+ <li><tomcat_home>\bin - Where you place web server plugins </li>
+</ol>
+
+<p>In all the examples in this document <tomcat_home> will be c:\jakarta-tomcat.</p>
+
+<p>A <tt>worker</tt> is defined to be a tomcat process that accepts work from the IIS
+server.</p>
+
+<h2>Supported Configuration</h2>
+
+<p>The IIS-Tomcat redirector was developed and tested on:
+
+<ol>
+ <li>Win2k, WinNT4.0-i386 SP4/SP5/SP6a (it should be able to work on other
+ versions of the NT service pack.) and Win98 </li>
+ <li>IIS4.0 and PWS4.0 </li>
+ <li>Tomcat3.0 - Tomcat3.2</li>
+</ol>
+
+<p>The redirector uses <b>ajp12</b> to send requests to the Tomcat
+containers. There is also an option to use Tomcat in process, more about the
+in-process mode can be found in the <a href="in-process-howto.html">in process
+howto.</a></p>
+
+<h2>Installation</h2>
+
+<p>As of Tomcat 3.2, a pre-built version of the ISAPI redirector server plugin,
+<tt>isapi_redirect.dll</tt>, is available under the win32/i386 directory where you
+downloaded the <a href="http://jakarta.apache.org/downloads/binindex.html">
+Tomcat binary distribution.</a> For those using Netscape as your browser, try
+downloading a zip version of the file, if available. There can be problems using
+Netscape to download DLL files.</p>
+
+<p>You can also build a copy locally from the source in Tomcat's source
+distribution.</p>
+
+<p>The Tomcat redirector requires three entities:
+
+<ol>
+ <li>isapi_redirect.dll - The IIS server plugin, either obtain a pre-built
+ DLL or build it yourself (see the build section).</li>
+ <li>workers.properties - A file that describes the host(s) and port(s) used
+ by the workers (Tomcat processes). A sample <tt>workers.properties</tt> can
+ be found under the <tt>conf</tt> directory. </li>
+ <li>uriworkermap.properties - A file that maps URL-Path patterns to
+ workers. A sample <tt>uriworkermap.properties</tt> can be found under the
+ <tt>conf</tt> directory as well.</li>
+</ol>
+
+<p>The installation includes the following parts:
+
+<ol>
+ <li>Configuring the ISAPI redirector with a default /examples context and
+ checking that you can serve servlets with IIS.</li>
+ <li>Adding more contexts to the configuration.</li>
+</ol>
+
+<h3>Configuring the ISAPI Redirector</h3>
+
+<p>In this document I will assume that isapi_redirect.dll is placed in
+c:\jakarta-tomcat\bin\win32\i386\isapi_redirect.dll and that you created the properties
+files are in c:\jakarta-tomcat\conf.</p>
+
+<p><b>Note:</b> The first six of the following steps may be simplified by
+using the iis_redirect.reg-auto file that is auto-generated when Tomcat
+is stared. Rename this file to iis_redirect.reg and update the settings it
+contains as needed. For example, you could change the <tt>log_level</tt>
+or switch the <tt>worker_file</tt> from worker.properties to
+worker.properties-auto. Then apply the settings to the registry from
+Windows Explorer by double-clicking the file or right clicking the file and
+selecting Merge.</p>
+
+<ol>
+ <li>In the registry, create a new registry key named <br>
+ <tt>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi
+ Redirector\1.0"</tt></li>
+ <li>Add a string value with the name <tt>extension_uri</tt> and a value of
+ /jakarta/isapi_redirect.dll</li>
+ <li>Add a string value with the name <tt>log_file</tt> and a value pointing
+ to where you want your log file to be (for example <tt>c:\jakarta-tomcat\logs\isapi.log)</tt>.</li>
+ <li>Add a string value with the name <tt>log_level</tt> and a value for
+ your log level (can be <tt>debug</tt>, <tt>info</tt>, <tt>error</tt>
+ or <tt>emerg</tt>). </li>
+ <li>Add a string value with the name <tt>worker_file</tt> and a value which
+ is the full path to your workers.properties file (for example
+ <tt>c:\jakarta-tomcat\conf\workers.properties</tt>)</li>
+ <li>Add a string value with the name <tt>worker_mount_file</tt> and a value
+ which is the full path to your uriworkermap.properties file (for example
+ <tt>c:\jakarta-tomcat\conf\uriworkermap.properties</tt>)</li>
+ <li>Using the IIS management console, add a new virtual directory to your
+ IIS/PWS web site. The name of the virtual directory must be jakarta. Its
+ physical path should be the directory where you placed isapi_redirect.dll
+ (in our example it is c:\jakarta-tomcat\bin\win32\i386). While creating this new
+ virtual directory assign it with execute access.</li>
+ <li>Using the IIS management console, add isapi_redirect.dll as a filter
+ in your IIS/PWS web site. The name of the filter should reflect its task
+ (I use the name jakarta), its executable must be our
+ <tt>c:\jakarta-tomcat\bin\win32\i386\isapi_redirect.dll</tt>. For PWS on Win98, you'll need
+ to use regedit and add/edit the "Filter DLLs" key under
+ HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters. This key
+ contains a "," separated list of dlls ( full paths ) - you need to insert the
+ full path to isapi_redirect.dll.</li>
+ <li>Restart IIS (stop + start the IIS service), make sure that the
+ jakarta filter is marked with a green up-pointing arrow.
+ <br><strong>Windows NT/2000:</strong> note that
+ the stop/start feature of the Microsoft Management Console does not actually stop
+ and start the IIS service. You need to use the services control panel (or the net command)
+ to stop and start the "World Wide Web Publishing Service".
+ <br><strong>Win98:</strong> (costin) you may
+ need to cd WINDOWS\SYSTEM\inetsrv and type PWS /stop ( the DLL and log files are locked -
+ even if you click the stop button, PWS will still keep the DLLs in memory. ). Type pws
+ to start it again.
+ </li>
+</ol>
+
+<p>That's all, you should now start Tomcat and ask IIS to serve you the /examples context.
+Try <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a>
+for example and execute some of the JSP examples. If this does not work successfully,
+refer to the <a href="#troubleshoot">Troubleshooting</a> section below for help
+on correcting the problem.</p>
+
+<h3>Adding additional Contexts</h3>
+
+<p>The examples context is useful for verifying your installation, but you will also need
+to add your own contexts. Adding a new context requires two operations:
+
+<ol>
+ <li>Adding the context to Tomcat (I am not going to talk about this).</li>
+ <li>Adding the context to the ISAPI redirector.</li>
+</ol>
+
+<p>Adding a context to the ISAPI redirector is simple, all you need to do is to edit your
+<tt>uriworkermap.properties</tt> and to add a line that looks like: </p>
+
+<p><tt>/context/*=worker_name</tt></p>
+
+<p>Workers and their name are defined in workers.properties, by default workers.properties
+comes with a single pre-configured worker named "ajp12" so you can use it. As an
+example, if you want to add a context named "shop", the line that you should add
+to <tt>uriworkermap.properties</tt> will be:</p>
+
+<p><tt>/shop/*=ajp12</tt></p>
+
+<p>After saving <tt>uriworkermap.properties</tt> restart IIS and it will serve the new context.
+As described in step 9 above, you must actually stop and start the IIS service from the service control
+panel. Stopping and starting using the MMC will not pick up the changes to the
+uriworkermap.properties file.</p>
+
+<p>As a new feature in Tomcat 3.2, a <tt>uriworkermap.properties-auto</tt> is
+automatically written each time Tomcat is started. This file includes settings
+for each of the contexts that Tomcat will serve during its run. Each context
+has settings to have Tomcat handle servlet and JSP requests, but by default static
+content is left to be served by IIS. Each context also has a commented out setting
+to have Tomcat handle all requests to the context. You can rename this file (so it won't
+be overwritten the next time Tomcat is started) and uncomment this setting or make
+other customizations. You may also use this file as is in your <tt>worker_mount_file</tt>
+setting.</p>
+
+<h2>Building the redirector</h2>
+
+<p>The redirector was developed using Visual C++ Ver.6.0, so having this environment is a
+prereq if you want to perform a custom build.</p>
+
+<p>The steps that you need to take are:
+
+<ol>
+ <li>Change directory to the isapi plugins source directory.</li>
+ <li>Execute the following command:<br>
+ <tt>MSDEV isapi.dsp /MAKE ALL</tt><br>
+ If msdev is not in your path, enter the full path to msdev.exe</li>
+</ol>
+
+<p>This will build both release and debug versions of the redirector plugin. </p>
+
+<p>An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and build
+it using the build menu.</p>
+
+<h2>How does it work? </h2>
+
+<ol>
+ <li>The IIS-Tomcat redirector is an IIS plugin (filter + extension), IIS load the redirector
+ plugin and calls its filter function for each in-coming request. </li>
+ <li>The filter then tests the request URL against a list of URI-paths held inside
+ <tt>uriworkermap.properties</tt>, If the current request matches one of the entries in the list of
+ URI-paths, the filter transfer the request to the extension.</li>
+ <li>The extension collects the request parameters and forwards them to the appropriate
+ worker using the ajp12 protocol.</li>
+ <li>The extension collects the response from the worker and returns it to the browser.</li>
+</ol>
+
+<h2>Advanced Context Configuration</h2>
+
+<p>Sometimes it is better to have IIS serve the static pages (html, gif, jpeg etc.) even
+if these files are part of a context served by Tomcat. For example, consider the html and
+gif files in the examples context, there is no need to serve them from the Tomcat process,
+IIS will suffice.</p>
+
+<p>Making IIS serve static files that are part of the Tomcat contexts requires the
+following:
+
+<ol>
+ <li>Configuring IIS to know about the Tomcat contexts</li>
+ <li>Configuring the redirector to leave the static files for IIS</li>
+</ol>
+
+<p>Adding a Tomcat context to IIS requires the addition of a new IIS virtual directory
+that covers the Tomcat context. For example adding a /example IIS virtual directory that
+covers the c:\jakarta-tomcat\webapps\examples directory. </p>
+
+<p>Configuring the redirector is somewhat harder, you will need to specify the exact
+URL-Path pattern(s) that you want Tomcat to handle (usually only JSP files and servlets).
+This requires a change to the <tt>uriworkermap.properties</tt>. For the examples context it
+requires to replace the following line:</p>
+
+<p><tt>/examples/*=ajp12</tt></p>
+
+<p>with the following two lines:</p>
+
+<p><tt>/examples/*.jsp=ajp12 <br>
+/examples/servlet/*=ajp12 </tt></p>
+
+<p>As you can see the second configuration is more explicit, it actually instruct the
+redirector to redirect only requests to resources under <tt>/examples/servlet/</tt> and
+resources under <tt>/examples/ </tt>whose name ends with <tt>.jsp</tt>. This is
+similar to what is automically written to the <tt>uriworkermap.properties-auto</tt>
+file for each context.</p>
+
+<p>You can even be more explicit and provide lines such as:</p>
+
+<p><tt>/example/servletname=ajp12</tt> </p>
+
+<p>that instructs the redirector to redirect request whose URL-Path equals
+<tt>/example/servletname </tt>to the worker named ajp12.</p>
+
+<h3>Protecting the WEB-INF Directory</h3>
+
+<p>Each servlet application (context) has a special directory named WEB-INF, this
+directory contains sensitive configurations data and Java classes and must be kept hidden
+from web users. Using the IIS management console it is possible to protect the WEB-INF
+directory from user access, this however requires the administrator to remember that. To
+avoid this need the redirector plugin automatically protects your WEB-INF directories by
+rejecting any request that contains WEB-INF in its URL-Path.</p>
+
+<h2>Advanced Worker Configuration</h2>
+
+<p>Sometimes you want to serve different contexts with different Tomcat processes (for
+example to spread the load among different machines). To achieve such goal you will need
+to define several workers and assign each context with its own worker.</p>
+
+<p>Defining workers is done in <tt>workers.properties</tt>, this file includes
+two types of entries:
+
+<ol>
+ <li>An entry that lists all the workers defined. For example:<br>
+ <tt>worker.list=ajp12, ajp12second</tt></li>
+ <li>Entries that define the host and port associated with these workers. For example:<br>
+ <tt>worker.ajp12.host=localhost<br>
+ worker.ajp12.port=8007<br>
+ worker.ajp12second.host=otherhost<br>
+ worker.ajp12second.port=8007</tt></li>
+</ol>
+
+<p>The above examples defined two workers, now we can use these workers to serve two
+different contexts each with its own worker. For example look at the following
+<tt>uriworkermap.properties</tt> fragment:</p>
+
+<p><tt>/examples/*=ajp12 <br>
+/webpages/*=ajp12second </tt></p>
+
+<p>As you can see the examples context is served by ajp12 while the webpages context is
+served by ajp12second.</p>
+
+<h2><a name="troubleshoot">Troubleshooting</a></h2>
+
+<p>It is easy to have the ISAPI redirector not work the first time you try to install
+it. If this happens to you, here are some steps to follow to try to correct the
+problem. These steps aren't guaranteed to cover all possible problems, but they
+should help find the typical mistakes. If you make any corrections during these
+steps, restart the IIS service as described above in the last step of the installation,
+then retry the step.</p>
+
+<p><b>Note:</b> These steps assume your <tt>worker_mount_file</tt> setting points
+to an unmodified copy of the uriworkermap.properties file. Results may be misleading
+if <tt>worker_mount_file</tt> points to a modified uriworkermap.properties or
+the uriworkermap.properties-auto file. It is also assumed that the "/examples"
+context works correcly if you access Tomcat directly.</p>
+
+<h3>Win98</h3>
+
+<ol>
+ <li>Make sure web site activity is being logged. For PWS 4.0 make sure
+ "Save Web Site Activity Log" is checked in the Advanced Options of
+ the Personal Web Manager.</li>
+ <li>Start the IIS service and Tomcat.</li>
+ <li>Check for the presence of the ISAPI redirector log file you specified in the
+ <tt>log_file</tt> setting. If not found, check the following:
+ <ol type="A">
+ <li>Check the "Filter DLLs" setting in the
+ "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters"
+ key and make sure the path is correct.</li>
+ <li>Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software
+ Foundation\Jakarta Isapi Redirector\1.0" key. Case isn't important,
+ but an incorrect letter will prevent the isapi_redirect.dll from finding
+ its registry settings.</li>
+ <li>Check the <tt>log_file</tt> setting for typos, name and data. Also
+ insure the directory in which the log file will appear already exists.</li>
+ </ol>
+ If the above are set correctly, the ISAPI redirector should be able to create
+ the log file.</li>
+ <li>Invoke the URL "http://localhost/examples/jsp/index.html" in your
+ browser. Case is important in Tomcat 3.2. The characters following
+ "localhost" in the URL must be lower case. If the page fails to
+ appear, stop the IIS service (required to view the IIS log file). Then
+ examine the last line in the IIS log file in found in SYSTEM/LogFiles/W3SVC1.
+ <ol type="A">
+ <li>If the last line contains: <tt>GET "/examples/jsp/index.html HTTP/1.1" 404</tt>,
+ then the ISAPI redirector is not recognizing that it should be handling
+ requests for the "/examples" context. Check the following:
+ <ol>
+ <li>Check the <tt>extension_uri</tt> name for typos.</li>
+ <li>Check the <tt>worker_file</tt> setting for typos, name and data.</li>
+ <li>Check the <tt>worker_mount_file</tt> setting typos, name and data.</li>
+ </ol>
+ If these are set correctly, the ISAPI redirector should recognize that it
+ should handle requests for the "/examples" context.</li>
+ <li>If the last line contains something like: <tt>GET "/jakarta/isapi_redirect.dll
+ HTTP1.1"</tt>, then the ISAPI redirector is recognizing that it should
+ handle the request, but is not successful at getting Tomcat to service
+ the request.
+ <ol>
+ <li>If the number following <tt>GET "/..."</tt> is 404, check
+ the following:
+ <ol type="a">
+ <li>Make sure you entered the URL correctly.</li>
+ <li>Make sure the virtual directory created was called "jakarta".
+ It should display in Personal Web Manager as "/jakarta"
+ (without the quotes).</li>
+ <li>Make sure the <tt>extension_uri</tt> data begins with
+ "/jakarta/" (without the quotes).</li>
+ </ol></li>
+ <li>If the number following <tt>GET "/..."</tt> is 500, check
+ the following:
+ <ol type="a">
+ <li>Make sure that "isapi_redirect.dll" follows
+ "/jakarta/" in the <tt>extension_uri</tt> setting.</li>
+ <li>Check the workers.properties file and make sure the port setting for
+ <tt>worker.ajp12.port</tt> is the same as the port specified in the server.xml
+ for the "Apache AJP12 support".</li>
+ </ol>
+ </li>
+ <li>If the number following <tt>GET "/..."</tt> is 200 or 403,
+ make sure you have checked Execute Access for the jakarta virtual
+ directory in the Advanced Options of the Personal Web Manager.</li>
+ </ol>
+ </ol>
+ If the above settings are correct, the index.html page should appear in your
+ browser. You should also be able to click the <b>Execute</b> links to
+ execute the JSP examples.</li>
+</ol>
+
+<h3>WinNT/Win2K</h3>
+
+<ol>
+ <li>Make sure web site activity is being logged. For PWS 4.0 make sure
+ "Save Web Site Activity Log" is checked in the Advanced Options of
+ the Personal Web Manager.</li>
+ <li>Start the World Wide Web Publishing Service and Tomcat.</li>
+ <li>Check for the presence of the ISAPI redirector log file you specified in the
+ <tt>log_file</tt> setting. If not found, check the following:
+ <ol type="A">
+ <li>Check the "executable" you set for the filter in the IIS
+ Management Console and make sure the path is correct.</li>
+ <li>Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software
+ Foundation\Jakarta Isapi Redirector\1.0" key. Case isn't important,
+ but an incorrect letter will prevent the isapi_redirect.dll from finding
+ its registry settings.</li>
+ <li>Check the <tt>log_file</tt> setting for typos, name and data. Also
+ insure the directory in which the log file will appear already exists.</li>
+ </ol>
+ If the above are set correctly, the ISAPI redirector should be able to create
+ the log file.</li>
+ <li>Check the jakarta filter you added and make sure its status shows a green
+ upward-pointing arrow. If not, check the following:
+ <ol type="A">
+ <li>Check the <tt>worker_file</tt> setting for typos, name and data.</li>
+ <li>Check the <tt>worker_mount_file</tt> setting typos, name and data.</li>
+ </ol>
+ If the above are set correctly, the green upward-pointing arrow should appear,
+ even if the other settings are wrong.</li>
+ <li>Invoke the URL "http://localhost/examples/jsp/index.html" in your
+ browser. Case is important in Tomcat 3.2. The characters following
+ "localhost" in the URL must be lower case. If the page fails to
+ appear, examine the last line in the IIS server log file in found in
+ SYSTEM32/LogFiles/W3SVC1.
+ <ol type="A">
+ <li>The last line should contain something like: <tt>GET "/jakarta/isapi_redirect.dll
+ HTTP1.1"</tt>, which indicates the ISAPI redirector is recognizing
+ that it should handle the request.
+ <ol>
+ <li>If the number following <tt>GET "/..."</tt> is 404, check
+ the following:
+ <ol type="a">
+ <li>Make sure you entered the URL correctly.</li>
+ </ol></li>
+ <li>If the number following <tt>GET "/..."</tt> is 500, check
+ the following:
+ <ol type="a">
+ <li>Make sure the virtual directory created was called "jakarta".</li>
+ <li>Make sure that the <tt>extension_uri</tt> setting is correct.</li>
+ <li>Check the workers.properties file and make sure the port setting for
+ <tt>worker.ajp12.port</tt> is the same as the port specified in the server.xml
+ for the "Apache AJP12 support".</li>
+ </ol>
+ </li>
+ <li>If the number following <tt>GET "/..."</tt> is 200 or 403,
+ make sure you have checked Execute Access for the jakarta virtual
+ directory in the Advanced Options of the Personal Web Manager. If
+ you created the "Filter DLLs" key in the registry, delete
+ it. That registry key is only used on Win9x.</li>
+ </ol>
+ </ol>
+ If the above settings are correct, the index.html page should appear in your
+ browser. You should also be able to click the <b>Execute</b> links to
+ execute the JSP examples.</li>
+</ol>
+
+<h2>Feedback</h2>
+
+<p>Please send feedback, bug report or any additional information to
+<tt>tomcat-user@jakarta.apache.org</tt></p>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.2-doc/tomcat-iis-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org