tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lar...@apache.org
Subject cvs commit: jakarta-tomcat/src/doc tomcat-iis-howto.html
Date Fri, 09 Feb 2001 02:28:04 GMT
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>&lt;tomcat_home&gt;\bin - Where you place web server plugins </li>
   </ol>
   
  -<p>In all the examples in this document &lt;tomcat_home&gt; will be d:\tomcat.</p>
  +<p>In all the examples in this document &lt;tomcat_home&gt; 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
  +    &quot;Save Web Site Activity Log&quot; 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 &quot;Filter DLLs&quot; setting in the
  +        &quot;HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters&quot;
  +        key and make sure the path is correct.</li>
  +      <li>Check the spelling of the &quot;HKEY_LOCAL_MACHINE\SOFTWARE\Apache
Software
  +        Foundation\Jakarta Isapi Redirector\1.0&quot; 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 &quot;http://localhost/examples/jsp/index.html&quot;
in your
  +    browser. Case is important in Tomcat 3.2.  The characters following
  +    &quot;localhost&quot; 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 &quot;/examples/jsp/index.html
HTTP/1.1&quot; 404</tt>,
  +        then the ISAPI redirector is not recognizing that it should be handling
  +        requests for the &quot;/examples&quot; 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 &quot;/examples&quot; context.</li>
  +      <li>If the last line contains something like: <tt>GET &quot;/jakarta/isapi_redirect.dll
  +        HTTP1.1&quot;</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 &quot;/...&quot;</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 &quot;jakarta&quot;.
  +                It should display in Personal Web Manager as &quot;/jakarta&quot;
  +                (without the quotes).</li>
  +              <li>Make sure the <tt>extension_uri</tt> data begins with

  +                &quot;/jakarta/&quot; (without the quotes).</li>
  +            </ol></li>
  +          <li>If the number following <tt>GET &quot;/...&quot;</tt>
is 500, check
  +            the following:
  +            <ol type="a">
  +              <li>Make sure that &quot;isapi_redirect.dll&quot; follows
  +                &quot;/jakarta/&quot; 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 &quot;Apache AJP12 support&quot;.</li>
  +            </ol>
  +            </li>
  +          <li>If the number following <tt>GET &quot;/...&quot;</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
  +    &quot;Save Web Site Activity Log&quot; 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 &quot;executable&quot; you set for the filter in the
IIS
  +        Management Console and make sure the path is correct.</li>
  +      <li>Check the spelling of the &quot;HKEY_LOCAL_MACHINE\SOFTWARE\Apache
Software
  +        Foundation\Jakarta Isapi Redirector\1.0&quot; 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 &quot;http://localhost/examples/jsp/index.html&quot;
in your
  +    browser. Case is important in Tomcat 3.2.  The characters following
  +    &quot;localhost&quot; 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 &quot;/jakarta/isapi_redirect.dll
  +        HTTP1.1&quot;</tt>, which indicates the ISAPI redirector is recognizing
  +        that it should handle the request.
  +        <ol>
  +          <li>If the number following <tt>GET &quot;/...&quot;</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 &quot;/...&quot;</tt>
is 500, check
  +            the following:
  +            <ol type="a">
  +              <li>Make sure the virtual directory created was called &quot;jakarta&quot;.</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 &quot;Apache AJP12 support&quot;.</li>
  +            </ol>
  +            </li>
  +          <li>If the number following <tt>GET &quot;/...&quot;</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>
   
  
  
  

Mime
View raw message