diff options
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml')
| -rw-r--r-- | rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml | 729 |
1 files changed, 0 insertions, 729 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml deleted file mode 100644 index e79c1611..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml +++ /dev/null @@ -1,729 +0,0 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="iis.html"> - - &project; -<copyright> - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. -</copyright> -<properties> -<title>IIS HowTo</title> -<author email="hgomez@apache.org">Henri Gomez</author> -<author email="shachor@il.ibm.com">Gal Shachor</author> -<author email="yoavs@apache.org">Yoav Shapira</author> -<date>$Date: 2010-03-15 16:40:37 +0100 (Mon, 15 Mar 2010) $</date> -</properties> -<body> -<section name="Introduction"> -<p> -This document explains how to set up IIS to cooperate with Tomcat. -</p> - -<p> -Normally IIS can not execute Servlets and Java Server Pages (JSPs), -configuring IIS to use the JK ISAPI redirector plugin will let IIS send servlet and -JSP requests to Tomcat (and this way, serve them to clients). -</p> - -<p> -It is recommended that you also read the -<a href="../generic_howto/workers.html">Workers HowTo</a> document -to learn how to setup the working entities between your web server and Tomcat Engines. -For more detailed configuration information consult the Reference Guide for -<a href="../reference/workers.html">workers.properties</a>, -<a href="../reference/uriworkermap.html">uriworkermap</a> -and <a href="../reference/iis.html">IIS</a>. -</p> - - -<subsection name="Document Conventions and Assumptions"> -<p> -${tomcat_home} is the root directory of tomcat. -Your Tomcat installation should have the following subdirectories: - -<ul> -<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> -</ul> -</p> -<p> -In all the examples in this document ${tomcat_home} will be <b>c:\tomcat</b>. -A worker is defined to be a tomcat process that accepts work from the IIS server. -</p> -</subsection> - - -<subsection name="Supported Configuration"> -<p> -The IIS-Tomcat redirector was developed and tested on: -<ul> -<li> -WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 -</li> -<li> -IIS4.0 and PWS4.0 (numerous people have working IIS 5 and IIS 6 configurations) -</li> -<li> -Tomcat 3.2 and later, Tomcat 4.x, Tomcat 5 and 5.5 and Tomcat 6 -</li> -</ul> -</p> - -<p> -The redirector uses <b>ajp12</b> and <b>ajp13</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> -</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="Who support ajp protocols ?"> -<p> -The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. -</p> - -<p> -The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead -<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. -</p> - -<p> -Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. -</p> - -<p> -Others servlet engines such as <b>jetty</b> have support for ajp13 protocol -</p> - -</subsection> - -<subsection name="How does it work ?"> -<p> -<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 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>. -</li> -<li> -The extension collects the response from the worker and returns it to the browser. -</li> -</ol> -</p> -</subsection> - -</section> - -<section name="Installation"> -<p> -A pre-built version of the ISAPI redirector server plugin, isapi_redirect.dll, is available under -the win32/i386 directory of tomcat-connectors distribution. -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. - -You can also build a copy locally from the source present in tomcat-connectors distribution. - -The Tomcat redirector requires three entities: - -<ul> -<li> -<b>isapi_redirect.dll</b> - The IIS server 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). -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. -A sample uriworkermap.properties can be found under the conf directory as well. -</li> -</ul> -</p> - -<p> -The installation includes the following parts: - -<ul> -<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> -</ul> -</p> - -</section> - -<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>. -</p> -<p> -<ol> -<li> -In the registry, create a new registry key named -<b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b> -</li> -<li> -Add a string value with the name <b>extension_uri</b> and a value of <b>/jakarta/isapi_redirect.dll</b> -</li> -<li> -Add a string value with the name <b>log_file</b> and a value pointing to where you want your -log file to be (for example <b>c:\tomcat\logs\isapi.log</b>). -</li> -<li> -Add a string value with the name <b>log_level</b> and a value for your log level -(can be debug, info, error or emerg). -</li> -<li> -Add a string value with the name <b>worker_file</b> and a value which is the full path -to your workers.properties file (for example <b>c:\tomcat\conf\workers.properties</b>) -</li> -<li> -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 Jakarta 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> -<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. -</p> -<p> -If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem. -</p> - -<subsection name="Adding additional Contexts"> -<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: -</p> -<p> -<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> -<p> -Adding a context to the ISAPI redirector is simple, all you need to do is to edit -your uriworkermap.properties and to add a line that looks like: -</p> - -<source> - /context/*=worker_name -</source> - -<p> -Workers and their name are defined in workers.properties, by default workers.properties comes -with a single pre-configured worker named <b>"defworker"</b> so you can use it. -As an example, if you want to add a context named "shop", the line that you should add to -uriworkermap.properties will be: -</p> - -<source> - /shop/*=defworker -</source> - -After saving uriworkermap.properties restart IIS and it will serve the new context. -<p> -The above should be all you need for IIS to pass through to Tomcat any request for any URI which corresponds -to a Tomcat context (webapp). -</p> -</subsection> - -<subsection name="Advanced Context Configuration"> -<p> -If your webiste is very busy (more than 100 requests/second, or more than 100 simultaneous client connections), -it might sometimes be desirable to have IIS serve static content (html, gif, jpeg etc.) directly, -even if these files are part of a context served by Tomcat. Allowing IIS to serve such files directly may - avoid the small overhead consisting of passing the request to Tomcat via the redirector, and may free up - Tomcat somewhat, by using it only to process requests that only Tomcat can handle (e.g. requests to JSP pages and java servlets). -</p> -<p> -For example, consider the html and gif files in the examples context : you could serve these files directly -with IIS; there is no need to serve them from the Tomcat process. -</p> -<warn>However, you should be very careful when you implement the following configuration style, because by doing so you are -in fact providing a "back-door" to IIS, and allowing it to serve files out of a Tomcat context without Tomcat's knowledge, -thus bypassing any security -restrictions which Tomcat itself and the Tomcat context (webapp) may place on those files.</warn> -<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> - -<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:\tomcat\webapps\examples directory. -</p> - -<p> -Configuring the redirector is somewhat harder, you will need to specify the exact -URL-Path pattern(s) which you want Tomcat to handle (usually only JSP files and servlets). -This requires a change to the uriworkermap.properties : - -<source> - For the examples context it requires to replace the following line - /examples/*=defworker - with the following two lines - /examples/*.jsp=defworker - /examples/servlet/*=defworker -</source> -</p> - -<p> -As you can see the second configuration is more explicit, it actually instruct the redirector -to redirect only requests to resources under /examples/servlet/ and resources under /examples/ -whose name ends with .jsp. -</p> - -<p> -You can even be more explicit and provide lines such as: - -<source> - /example/servletname=defworker -</source> -</p> - -<p> -that instructs the redirector to redirect all requests whose URL-path matches the leading string "/example/servletname" -to the worker named defworker. -</p> - -</subsection> - -<subsection name="Protecting the content of your Tomcat contexts"> -<p>Once again, be aware that by allowing IIS to access the content of your Tomcat context directly, you are -potentially bypassing Tomcat's protection of that content. You should thus make sure to protect this content -at the IIS level if needed, by using the corresponding IIS management console functions. -</p> -<p> -In particular, each servlet application (context) has a special directory named WEB-INF, -which contains sensitive configuration data and Java classes, and which should always be kept hidden from web users. -Using the IIS management console it is possible to protect the WEB-INF directory from user access, but considering that -this is a general requirement, and considering that it is easy to forget to implement this protection -at the IIS level, the redirector plugin does it automatically for you, and it will reject any request -which contains WEB-INF in its URL-path. -</p> -</subsection> - -<subsection name="Advanced Worker Configuration"> -<p> -Sometimes you may want to serve different contexts with different Tomcat processes -(for example to spread the load among different machines). -To achieve such a goal you will need to define several workers and assign each context to its own worker. -</p> -<p> -Defining additional workers is done in the workers.properties file. This file includes two types of entries: -</p> - -<p> -<source> - # An entry that lists all the workers defined - worker.list=worker1, worker2 - # Entries that define the host and port associated with each of these workers - worker.worker1.host=localhost - worker.worker1.port=8009 - worker.worker1.type=ajp13 - worker.worker2.host=otherhost - worker.worker2.port=8009 - worker.worker2.type=ajp13 -</source> -</p> - -<p> -The above example defined two workers, now we can use these workers to serve two different contexts -each with its own worker: -<source> - example uriworkermap.properties fragment - /examples/*=worker1 - /webpages/*=worker2 -</source> -</p> - -<p> -As you can see the <b>examples</b> context is served by <b>worker1</b> while the -<b>webpages</b> context is served by <b>worker2</b>. -</p> - -<p> -More information on using and configuring workers in the <a href="../generic_howto/workers.html">Workers HowTo</a> -and in the <a href="../reference/workers.html">worker.properties configuration reference</a>. -</p> - -</subsection> - -</section> - -<section name="Building ISAPI redirector"> -<p> -The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prerequisite if you want -to perform a custom build. You should also have the IIS developer SDK. - -The steps that you need to take are: -<ul> -<li> -Change directory to the isapi plugins source directory. -</li> -<li> -Make the source with MSDEV -</li> -</ul> -<screen> -<note>Change directory to the isapi plugins source directory</note> -<typedos>cd c:\home\apache\jk\iis</typedos> -<note>Build the sources using MSDEV</note> -<typedos>MSDEV isapi.dsp /MAKE ALL</typedos> -</screen> -</p> -<p> -If msdev is not in your path, enter the full path to msdev.exe. -This will build both release and debug versions of the redirector plugin. -An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and -build it using the build menu. -</p> -</section> - -<section name="Troubleshooting"> -<p> -It is easy to have the ISAPI redirector not work the first time you try to install it. -</p> -<p> -If this happens to you, here are some steps to follow to try to correct the problem. -</p> -<p> -These steps aren't guaranteed to cover all possible problems, -but they should help find the typical mistakes. -</p> -<p> -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>To enable error tracking, 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. -</p> - -<p> -Note: These steps assume your <b>worker_mount_file</b> setting points to an unmodified copy of the -<b>uriworkermap.properties</b> file.<br/> -Results may be misleading if <b>worker_mount_file</b> points to a modified <b>uriworkermap.properties</b> -or the <b>uriworkermap.properties-auto</b> file.<br/> -It is also assumed that the <b>"/examples" context</b> works correctly if you access Tomcat directly. -</p> - -<subsection name="Win98"> -<p> -Start the IIS service and Tomcat. -</p> -<p> -Check for the presence of the ISAPI redirector log file you specified in the log_file setting. -If not found, verify the following: -</p> -<ul> -<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 log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. -</li> -If the above are set correctly, the ISAPI redirector should be able to create the log file. -</ul> -<p> -Invoke the URL <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> -in your browser. -Case is important in Tomcat. 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 : -</p> -<p> -If the last line contains: -</p> -<source> - GET "/examples/jsp/index.html HTTP/1.1" 404 -</source> -<p> -then the ISAPI redirector is not recognising that it should be handling requests for the "/examples" context. -Check the following: -</p> -<ul> -<li> -Check the extension_uri name for typos. -</li> -<li> -Check the worker_file setting for typos, name and data. -</li> -<li> -Check the worker_mount_file setting typos, name and data. -</li> -If these are set correctly, the ISAPI redirector should recognise that it should handle requests for the "/examples" context. -</ul> - -<p>If the last line contains something like: -</p> - -<source> - GET "/jakarta/isapi_redirect.dll HTTP1.1" -</source> - -<p> -then the ISAPI redirector is recognising that it should handle the request, -but is not successful at getting Tomcat to service the request. -</p> - -<p> -You should check the HTTP error code following GET "/..." : -</p> - -<source> - Error 404 - GET "/..." 404 -</source> - -<ul> -<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 extension_uri data begins with "/jakarta/" (without the quotes). -</li> -</ul> - -<source> - Error 500 - GET "/..." 500 -</source> - -<ul> -<li> -Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri setting. -</li> -<li> -Check the workers.properties file and make sure the port setting for worker.ajp12.port is the same as the port specified in the server.xml for the "Apache AJP12 support". -</li> -</ul> - -<source> - Error 200 or 403 - GET "/..." 200 - GET "/..." 403 -</source> - -<ul> -<li> -Make sure you have checked Execute Access -for the jakarta virtual directory in the Advanced Options of the Personal Web Manager. -</li> -</ul> - -<p> -If the above settings are correct, the index.html page should appear in your browser. -You should also be able to click the Execute links to execute the JSP examples. -</p> - -</subsection> - -<subsection name="WinNT/Win2K/WinXP"> -<p> -Start the World Wide Web Publishing Service and Tomcat. -</p> -<p> -Check for the presence of the ISAPI redirector log file you specified in the log_file setting. -If not found, check the following: -</p> -<ul> -<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 log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. -</li> -If the above are set correctly, the ISAPI redirector should be able to create the log file. -</ul> - -<p> -Check the tomcat filter you added and make sure its status shows a green upward-pointing arrow. -If not, check the following: -</p> -<ul> -<li> -Check the worker_file setting for typos, name and data. -</li> -<li> -Check the worker_mount_file setting typos, name and data. -</li> -If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong. -</ul> - -<p> -Invoke the URL <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> -in your browser. Case is important in Tomcat. 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. -</p> - -<p> -The last line should contain something like: GET "/jakarta/isapi_redirect.dll HTTP1.1", -which indicates the ISAPI redirector is recognising that it should handle the request. -</p> - -<p> -You should check the HTTP error code following GET "/..." : -</p> - -<source> - Error 404 - GET "/..." 404 -</source> - -<ul> -<li> -Make sure you entered the URL correctly. -</li> -</ul> - -<source> - Error 500 - GET "/..." 500 -</source> - -<ul> -<li> -Make sure the virtual directory created was called "jakarta". -</li> -<li> -Make sure that the extension_uri setting is correct. -</li> -<li> -Check the workers.properties file and make sure the port setting for worker.ajp12.port is the same as the port specified in the server.xml for the "Apache AJP12 support". -</li> -</ul> - -<source> - Error 200 or 403 - GET "/..." 200 - GET "/..." 403 -</source> - -<ul> -<li> -Make sure you have checked Execute Access for the jakarta virtual directory in the -Advanced Options of the Personal Web Manager. -</li> -</ul> - -<p> -If the above settings are correct, the index.html page should appear in your browser. -You should also be able to click the Execute links to execute the JSP examples. -</p> -</subsection> - - -</section> -</body> -</document> |