You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by la...@locus.apache.org on 2000/10/12 08:21:26 UTC
cvs commit: jakarta-tomcat/src/doc tomcat-iis-howto.html
larryi 00/10/11 23:21:26
Modified: src/doc Tag: tomcat_32 tomcat-iis-howto.html
Log:
Made Tomcat 3.2 appropriate updates.
Added a Troubleshooting section
Revision Changes Path
No revision
No revision
1.1.2.1 +211 -26 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.1.2.1
diff -u -r1.1 -r1.1.2.1
--- tomcat-iis-howto.html 2000/05/03 12:48:19 1.1
+++ tomcat-iis-howto.html 2000/10/12 06:21:26 1.1.2.1
@@ -37,22 +37,31 @@
<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.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 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>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>As of Tomcat 3.2, a pre-built version of the ISAPI redirector server plugin,
+<tt>isapi_redirect.dll</tt>, is available from two locations. First, it may be found under
+the win32/i386 directory where you got the <a href="http://jakarta.apache.org/downloads/binindex.html">
+Tomcat binary distribution.</a> Second, it may be found in the Tomcat source
+distribution under jakarta-tomcat\bin\iis\nt4\i386. The <tt>isapi_redirect.dll</tt>
+may be used on Win98 systems in spite of the "nt4" in the sequence of subdirectories.
+For those using Netscape as your browser, your best bet is to download the Tomcat
+source distribution since there have been reported problems with Netscape downloading
+DLLs directly.</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>
@@ -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:
@@ -87,19 +96,18 @@
<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>d:\tomcat\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>D:\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>D:\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
virtual directory assign it with execute access.</li>
@@ -111,7 +119,7 @@
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 d:\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,9 +232,12 @@
<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>
<p>that instructs the redirector to redirect request whose URL-Path equals
@@ -255,6 +280,166 @@
<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.</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" 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 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" 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>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 the <tt>extension_uri</tt>
+ name for typos. If this is set correctly, the ISAPI redirector should
+ recognize that it should handle requests 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 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>
<h2>Feedback</h2>