larryi 01/02/08 18:28:03
Modified: src/doc tomcat-iis-howto.html
Log:
Port 3.2 changes. Add other miscellaneous changes.
Need to address what the example directory should be for Tomcat 3.3.
This document assumes it will be c:\jakarta-tomcat.
Revision Changes Path
1.2 +210 -33 jakarta-tomcat/src/doc/tomcat-iis-howto.html
Index: tomcat-iis-howto.html
===================================================================
RCS file: /home/cvs/jakarta-tomcat/src/doc/tomcat-iis-howto.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tomcat-iis-howto.html 2000/05/03 12:48:19 1.1
+++ tomcat-iis-howto.html 2001/02/09 02:28:03 1.2
@@ -1,7 +1,10 @@
<html>
-
<head>
-<title>Tomcat IIS HowTo</title>
+ <!-- $Id: tomcat-iis-howto.html,v 1.2 2001/02/09 02:28:03 larryi Exp $ -->
+ <!-- Copyright 1999-2001, Apache Software Foundation -->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" href="style.css">
+ <title>Tomcat IIS HowTo</title>
</head>
<body>
@@ -26,7 +29,7 @@
<li><tomcat_home>\bin - Where you place web server plugins </li>
</ol>
-<p>In all the examples in this document <tomcat_home> will be d:\tomcat.</p>
+<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>
@@ -37,21 +40,27 @@
<ol>
<li>WinNT4.0-i386 SP4/SP5/SP6a (it should be able to work on other
- versions of the NT service pack.) </li>
+ versions of the NT service pack.) and Win98 </li>
<li>IIS4.0 and PWS4.0 </li>
- <li>Tomcat3.0 - Tomcat3.1beta</li>
+ <li>Tomcat3.0 - Tomcat3.3</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 in process howto.</p>
+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/site/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>The IIS redirector is not part of the "official" build of Jakarta, You
-can obtain the code and binaries needed for it by accessing
-http://jakarta.apache.org/builds/tomcat/release/v3.1_beta_1/bin/win32/i386/.
-The redirector related file is <tt>isapi_redirect.dll</tt>.</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:
@@ -60,10 +69,10 @@
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 <tt>tomcat/conf</tt>. </li>
+ 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 in the CVS
- under <tt>tomcat/conf</tt>. </li>
+ 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:
@@ -77,8 +86,8 @@
<h3>Configuring the ISAPI Redirector</h3>
<p>In this document I will assume that isapi_redirect.dll is placed in
-d:\tomcat\bin\iis\i386\isapi_redirect.dll and that you created the properties
-files are in d:\tomcat\conf.</p>
+c:\jakarta-tomcat\bin\win32\i386\isapi_redirect.dll and that you created the
properties
+files are in c:\jakarta-tomcat\conf.</p>
<ol>
<li>In the registry, create a new registry key named <br>
@@ -87,31 +96,30 @@
<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>d:\tomcat\isapi.log)</tt></li>
+ 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>inform</tt>, <tt>error</tt>
- or <tt>emerg</tt>). </li>
- <li>Add a string value with the name <tt>worker_file</tt> and a value of
- <tt>D:\tomcat\conf\workers.properties</tt> (you can copy this file
- from the CVS)</li>
- <li>Add a string value with the name <tt>worker_mount_file</tt>and a value of
- <tt>D:\tomcat\conf\uriworkermap.properties</tt> (you can copy this file
- from the CVS) </li>
+ 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
+ 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 d:\tomcat\bin\iis\i386). While creating this new
+ (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>d:\tomcat\bin\iis\i386\isapi_redirect.dll</tt>. For PWS, you'll need
+ <tt>c:\jakarta-tomcat\bin\win32\i386\isapi_redirect.dll</tt>. For PWS, 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 admin server), make sure that the
+ <li>Restart IIS (stop + start the IIS service), make sure that the
jakarta filter is marked with a green up-pointing arrow. <br>(costin)Under
Win98 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
@@ -119,7 +127,11 @@
</li>
</ol>
-<p>That's all, you should now start tomcat and ask IIS to serve you the /examples
context.</p>
+<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>
@@ -145,6 +157,16 @@
<p>After saving <tt>uriworkermap.properties</tt> restart IIS and it will serve the
new context.</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
@@ -194,7 +216,7 @@
<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 d:\tomkat\webapps\examples directory. </p>
+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).
@@ -210,8 +232,11 @@
<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>. You can
even be
-more explicit and provide lines such as:</p>
+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>
@@ -255,6 +280,158 @@
<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</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.</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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
