Author: markt
Date: Fri Nov 17 14:22:15 2017
New Revision: 1815568
URL: http://svn.apache.org/viewvc?rev=1815568&view=rev
Log:
Update the installation instructions for the ISAPI redirector.
Modified:
tomcat/jk/trunk/xdocs/webserver_howto/iis.xml
Modified: tomcat/jk/trunk/xdocs/webserver_howto/iis.xml
URL:
http://svn.apache.org/viewvc/tomcat/jk/trunk/xdocs/webserver_howto/iis.xml?rev=1815568&r1=1815567&r2=1815568&view=diff
==============================================================================
--- tomcat/jk/trunk/xdocs/webserver_howto/iis.xml (original)
+++ tomcat/jk/trunk/xdocs/webserver_howto/iis.xml Fri Nov 17 14:22:15 2017
@@ -77,61 +77,23 @@ A worker is defined to be a tomcat proce
<subsection name="Supported Configuration">
<p>
-The IIS to Tomcat redirector works for:
+The IIS to Tomcat redirector is supported for:
+</p>
<ul>
-<li>
-WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs),
Win98, WinXP, Win2K,
-and probably also Win2K3, Vista and Windows 7.
-</li>
-<li>
-IIS4.0 and PWS4.0, IIS 5 to IIS 7.
-</li>
-<li>
-Tomcat 3.2 to Tomcat 8.
-</li>
+<li>IIS running on Windows 7 or later</li>
+<li>IIS running on Windows Server 2008 SP2 or later</li>
+<li>Tomcat 7 or later</li>
</ul>
-</p>
-
-<p>
-The mod_jk module uses the AJP protocol to send requests to the Tomcat
containers.
-The AJP version typically used is <b>ajp13</b>.
-</p>
-</subsection>
-
-<subsection name="IIS 5 and 6 Notes">
-<p>
-There are extra steps you need to take for configuring Tomcat with IIS 5 and
6. Please see the appropriate links from
-<a href="http://wiki.apache.org/tomcat/Tomcat/Links";>Tomcat Useful Links</a>.
-</p>
-</subsection>
-
-<subsection name="IIS 7 notes">
-<p>
-There is a known bug in IIS that may result in incomplete log messages. See <a
-href="https://issues.apache.org/bugzilla/show_bug.cgi?id=45769";>bug 45769</a>
-for further details.
-</p>
-</subsection>
-
-<subsection name="64 Bit notes">
-<p>
-In a 64 Bit environment - at least for IIS 7 - the used IIS Application Pool
-should have "Enable 32-bit Applications" set to "False". Otherwise the
redirector will
-not be called and returns an http code 404. If you think, the 32bit version of
-isapi_redirect.dll would do the job instead, you will get an http code 500,
-because the library is not loadable into a 64 Bit IIS.
-</p>
-</subsection>
-
-<subsection name="Who supports AJP protocols?">
<p>
-Tomcat supports ajp13 since Tomcat 3.2.
-Others servlet engines such as <b>Jetty</b> or <b>JBoss</b> also support the
ajp13 protocol
+The redirector may work with IIS running on older versions of Windows but such
+configurations are not supported.
</p>
<p>
-The <b>ajp12</b> protocol has been <b>deprecated</b> and you should no longer
use it.
-The <b>ajp14</b> protocol is considered experimental.
+The mod_jk module uses the AJP protocol to send requests to the Tomcat
+containers. The AJP version used is <b>ajp13</b>. All current versions Tomcat
+support the ajp13 protocol. Others servlet engines such as <b>Jetty</b> and
+<b>JBoss</b> also support the ajp13 protocol.
</p>
</subsection>
@@ -140,20 +102,21 @@ The <b>ajp14</b> protocol is considered
<p>
<ol>
<li>
-The ISAPI redirector is a Microsoft IIS plugin (filter + extension). IIS loads
the redirector plugin and calls its
-filter function for each in-coming request.
+The ISAPI redirector is a Microsoft IIS plugin (filter + extension). IIS loads
+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
uriworkermap.properties,
-If the current request matches one of the entries in the list of URI-paths,
-the filter transfers the request to the extension.
+The filter then tests the request URL against a list of URI-paths held inside
+uriworkermap.properties. If the current request matches one of the entries in
+the list of URI-paths, the filter transfers the request to the extension.
</li>
<li>
-The extension collects the request parameters and forwards them to the
appropriate worker using the defined
-protocol like <b>ajp13</b>.
+The extension collects the request parameters and forwards them to the
+appropriate worker using the defined protocol like <b>ajp13</b>.
</li>
<li>
-The extension collects the response from the worker and returns it to the
browser.
+The extension collects the response from the worker and returns it to the
+browser.
</li>
</ol>
</p>
@@ -163,23 +126,29 @@ The extension collects the response from
<section name="Installation">
<p>
-A pre-built version of the ISAPI redirector plugin, isapi_redirect.dll, is
available under
-the win32/i386 directory of the Tomcat Connectors distribution.
+Pre-built versions of the ISAPI redirector plugin, isapi_redirect.dll, for
+32-bit and 64-bit environments are available from the
+<a href="https://tomcat.apache.org/download-connectors.cgi";>Apache Tomcat
+Connectors Downloads</a> page.
-You can also build a copy locally from the Tomcat Connectors source
distribution.
+You can also build a copy locally from the Tomcat Connectors source
+distribution.
The ISAPI redirector requires three entities:
<ul>
<li>
-<b>isapi_redirect.dll</b> - The ISAPI redirector for Microsoft IIS plugin,
either obtain a pre-built DLL or build it yourself (see the build section).
+<b>isapi_redirect.dll</b> - The ISAPI redirector for Microsoft IIS plugin,
+either obtain a pre-built DLL or build it yourself (see the build section).
</li>
<li>
-<b><a href="../reference/workers.html">workers.properties</a></b> - A file
that describes the host(s) and port(s) used by the workers (Tomcat processes).
+<b><a href="../reference/workers.html">workers.properties</a></b> - A file that
+describes the host(s) and port(s) used by the workers (Tomcat processes).
A sample workers.properties can be found under the conf directory.
</li>
<li>
-<b><a href="../reference/uriworkermap.html">uriworkermap.properties</a></b> -
A file that maps URL-Path patterns to workers.
+<b><a href="../reference/uriworkermap.html">uriworkermap.properties</a></b> - A
+file that maps URL-Path patterns to workers.
A sample uriworkermap.properties can be found under the conf directory as well.
</li>
</ul>
@@ -190,7 +159,8 @@ The installation includes the following
<ul>
<li>
-Configuring the ISAPI redirector with a default /examples context and checking
that you can serve servlets with IIS.
+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.
@@ -198,15 +168,117 @@ Adding more contexts to the configuratio
</ul>
</p>
-</section>
+<subsection name="Configuring the ISAPI Redirector">
+
+<p><i>These instructions have been written based on Windows Server 2012 R2.
+Other versions should be broadly the same. As the installation process is
tested
+on other Windows versions, these instructions will be upadted to note any
+version specific information.</i>
+</p>
-<section name="Configuring the ISAPI Redirector">
<p>
-In this document I will assume that isapi_redirect.dll is placed in
-<b>c:\tomcat\bin\win32\i386\isapi_redirect.dll</b> and
-that the properties files which you created are in <b>c:\tomcat\conf</b>.
+These installation instructions have been tested with a default installation of
+IIS plus ISAPI Extensions and Filters on a clean, fully patched OS installation
+with Tomcat 9 installed in <b>C:\Program Files\Apache Software
Foundation\Tomcat
+9.0</b>. This is referred to as ${tomcat_home} for the remainder of this
+document.
+</p>
+
+<ol>
+<li>
+Create a directory <b>${tomcat_home}\isapi</b>
+</li>
+<li>
+Allow the IIS process to create the ISAPI redirector log file. Enter the
+following at a command prompt:
+<source>
+>icacls "C:\Program Files\Apache Software Foundation\Tomcat 9.0\isapi" /grant
"IIS APPPOOL\DefaultAppPool":(OI)(CI)M
+</source>
+</li>
+<li>
+Download the appropriate (32-bit or 64-bit) isapi_redirect.dll for your
+operating system and place it in <b>${tomcat_home}\isapi</b>
+</li>
+<li>
+Create <b>${tomcat_home}\isapi\isapi_redirect.properties</b> to configure the
ISAPI
+redirctor. Configuration can also be performed via registry settings - see
+below. The contents of this file should be:
+<source>
+extension_uri=/jakarta/isapi_redirect.dll
+log_file=C:\Program Files\Apache Software Foundation\Tomcat
9.0\isapi\isapi_redirect.log
+log_level=info
+worker_file=C:\Program Files\Apache Software Foundation\Tomcat
9.0\isapi\workers.properties
+worker_mount_file=C:\Program Files\Apache Software Foundation\Tomcat
9.0\isapi\uriworkermap.properties
+</source>
+Be careful Windows doesn't add a <b>.txt</b> extension to the file.
+</li>
+<li>
+Create <b>${tomcat_home}\isapi\workers.properties</b> to configure the Tomcat
+instances that requests will be passed to. For a single Tomcat instance on the
+local machine the contents of this file should be:
+<source>
+worker.list=tomcat01
+worker.tomcat01.type=ajp13
+worker.tomcat01.host=localhost
+worker.tomcat01.port=8009
+</source>
+</li>
+<li>
+Create <b>${tomcat_home}\isapi\uriworkermap.properties</b> to configure which
+requests will be passed to Tomcat. To expose the examples web application the
+contents of this file should be:
+<source>
+/examples/*=tomcat01
+</source>
+</li>
+<li>
+Using the IIS management console, add a new virtual directory to your IIS web
+site. In a clean install, this will be the <b>Default Web Site</b>. The name of
+the virtual directory must be <b>jakarta</b>. Its physical path should be the
+directory where you placed <b>isapi_redirect.dll</b>.
+</li>
+<li>
+Select the newly created vitual directory in the management console and then
+double-click <b>Handler Mappings</b>. Select the (currently disabled)
+<b>ISAPI-dll</b> entry and then click <b>Edit Feature Permissions</b> in the
+action pane. In the dialog box that opens, select <b>Execute</b> so all three
+permissions are selected. Click <b>OK</b> and <b>ISAPI-dll</b> should now be in
+the enabled state.
+</li>
+<li>
+Again using the IIS management console, add the ISAPI redirector as a filter to
+your web site. Select your web site and then double-click <b>ISAPI Filters</b>.
+From the action pane, click <b>Add...</b>. For the filter name use
<b>tomcat</b>
+and the executable should be the full path to <b>isapi_redirect.dll</b>. Once
+configured, click <b>OK</b>.
+</li>
+<li>
+Still using the IIS managament console configure the ISAPI redirector as
+allowed. Select your server (not the web site) and then double-click on
<b>ISAPI
+and CGI Restrictions</b>. From the action pane, click <b>Add...</b>. Select the
+isapi_redirect.dll, add a descripion (e.g. tomcat) and select the <b>Allow
+extension path to execute</b> and then click <b>OK</b>.
+</li>
+<li>
+Restart IIS (stop + start the IIS service).
+</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/";>http://localhost/examples/</a>
+for example and execute some of the Servlet or JSP examples.
</p>
<p>
+If this does not work successfully, refer to the Troubleshooting section below
for help on correcting the problem.
+</p>
+</subsection>
+
+<subsection name="Registry configuration">
+
+As an alternative to useing the <b>isapi_redirector.properties</b> file, the
+ISAPI redirector may be configured via the registry. To do this, follow these
+steps:
<ol>
<li>
In the registry, create a new registry key named
@@ -231,52 +303,26 @@ to your workers.properties file (for exa
Add a string value with the name <b>worker_mount_file</b> and a value which is
the full path
to your uriworkermap.properties file (for example
<b>c:\tomcat\conf\uriworkermap.properties</b>)
</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:\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 tomcat),
-its executable must be our c:\tomcat\bin\win32\i386\isapi_redirect.dll.
-For PWS, you'll need to use regedit and add/edit the <b>"Filter DLLs"</b> key
under
-<b>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters</b>.
-This key contains a "," separated list of dlls (full paths) -
-you need to insert the full path to isapi_redirect.dll.
-</li>
-<li>
-If you're using IIS 6.0 you must also do the following:
-<br />
-Using the IIS management console, add the ISAPI Redirector to the Web
-Service Extensions.
-<ol>
-<li>Right-click on Web Service Extensions and choose Add a new Web Service
-Extension.</li>
-<li>Enter tomcat for the Extension Name.</li>
-<li>Add the isapi_redirect.dll to the required files.</li>
-<li>Check the Set extension status to Allowed.</li>
-<li>Click on OK.</li>
-</ol>
-</li>
-<li>
-Restart IIS (stop + start the IIS service), make sure that the tomcat filter
is marked with a green up-pointing arrow.
-Under Win98 you may need to <b>cd WINDOWS\SYSTEM\inetsrv</b> 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>
+
+</subsection>
+
+<subsection name="64 Bit notes">
<p>
-That's all, you should now start Tomcat and ask IIS to serve you the /examples
context.
-Try <a href="http://localhost/examples/";>http://localhost/examples/</a> for
example and
-execute some of the Servlet or JSP examples.
+In a 64 Bit environment the used IIS Application Pool should have "Enable
32-bit
+Applications" set to "False". To check this, select <b>Application Pools</b> in
+the IIS management console, then right-click on the pool you are using and
+select <b>Set Application Pool Defaults...</b>. <b>Enable 32-Bit
+Applications</b> may be found in the <b>General</b> section. If this is not
+configured correctly, the redirector will not be called and IIS will return an
+HTTP code 404.
</p>
<p>
-If this does not work successfully, refer to the Troubleshooting section below
for help on correcting the problem.
+You must use the 64-bit version of the ISAPI redirector on 64-bit operating
+systems. If you attempt to use the 32bit version, you will get an HTTP code 500
+for every request because the library is not loadable into a 64-bit IIS.
</p>
+</subsection>
<subsection name="Adding additional Contexts">
<p>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
