From 9401f816dd0d9d550fe98a8507224bde51c4b847 Mon Sep 17 00:00:00 2001 From: hongbotian Date: Mon, 30 Nov 2015 02:41:33 -0500 Subject: upload tomcat JIRA: BOTTLENECK-7 Change-Id: I875d474869efd76ca203c30b60ebc0c3ee606d0e Signed-off-by: hongbotian --- .../docs/webserver_howto/iis.html | 685 +++++++++++++++++++++ 1 file changed, 685 insertions(+) create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html') diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html new file mode 100644 index 00000000..5dc4ea1b --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html @@ -0,0 +1,685 @@ +The Apache Tomcat Connector - Webserver HowTo - IIS HowTo
Apache TomcatApache Logo

Links

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Webserver HowTo

IIS HowTo

Printer Friendly Version
print-friendly
version +
Introduction
+

+This document explains how to set up IIS to cooperate with Tomcat. +

+ +

+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). +

+ +

+It is recommended that you also read the +Workers HowTo 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 +workers.properties, +uriworkermap +and IIS. +

+ + +
Document Conventions and Assumptions
+

+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +

    +
  • +${tomcat_home}\conf - Where you can place various configuration files +
  • +
  • +${tomcat_home}\webapps - Containing example applications +
  • +
  • +${tomcat_home}\bin - Where you place web server plugins +
  • +
+

+

+In all the examples in this document ${tomcat_home} will be c:\tomcat. +A worker is defined to be a tomcat process that accepts work from the IIS server. +

+
+ + +
Supported Configuration
+

+The IIS-Tomcat redirector was developed and tested on: +

    +
  • +WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +
  • +
  • +IIS4.0 and PWS4.0 (numerous people have working IIS 5 and IIS 6 configurations) +
  • +
  • +Tomcat 3.2 and later, Tomcat 4.x, Tomcat 5 and 5.5 and Tomcat 6 +
  • +
+

+ +

+The redirector uses ajp12 and ajp13 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. +

+
+ +
IIS 5 and 6 Notes
+

+There are extra steps you need to take for configuring Tomcat with IIS 5 and 6. Please see the appropriate links from +Tomcat Useful Links. +

+
+ +
IIS 7 notes
+

+There is a known bug in IIS that may result in incomplete log messages. See bug 45769 +for further details. +

+
+ +
Who support ajp protocols ?
+

+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +

+ +

+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. +

+ +

+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +

+ +

+Others servlet engines such as jetty have support for ajp13 protocol +

+ +
+ +
How does it work ?
+

+

    +
  1. +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. +
  2. +
  3. +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. +
  4. +
  5. +The extension collects the request parameters and forwards them to the appropriate worker using the defined +protocol like ajp13. +
  6. +
  7. +The extension collects the response from the worker and returns it to the browser. +
  8. +
+

+
+ +
Installation
+

+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: + +

    +
  • +isapi_redirect.dll - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +
  • +
  • +workers.properties - 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. +
  • +
  • +uriworkermap.properties - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +
  • +
+

+ +

+The installation includes the following parts: + +

    +
  • +Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +
  • +
  • +Adding more contexts to the configuration. +
  • +
+

+ +
Configuring the ISAPI Redirector
+

+In this document I will assume that isapi_redirect.dll is placed in +c:\tomcat\bin\win32\i386\isapi_redirect.dll and +that the properties files which you created are in c:\tomcat\conf. +

+

+

    +
  1. +In the registry, create a new registry key named +"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" +
  2. +
  3. +Add a string value with the name extension_uri and a value of /jakarta/isapi_redirect.dll +
  4. +
  5. +Add a string value with the name log_file and a value pointing to where you want your +log file to be (for example c:\tomcat\logs\isapi.log). +
  6. +
  7. +Add a string value with the name log_level and a value for your log level +(can be debug, info, error or emerg). +
  8. +
  9. +Add a string value with the name worker_file and a value which is the full path +to your workers.properties file (for example c:\tomcat\conf\workers.properties) +
  10. +
  11. +Add a string value with the name worker_mount_file and a value which is the full path +to your uriworkermap.properties file (for example c:\tomcat\conf\uriworkermap.properties) +
  12. +
  13. +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. +
  14. +
  15. +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 "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. +
  16. +
  17. +If you're using IIS 6.0 you must also do the following: +
    +Using the IIS management console, add the Jakarta Isapi Redirector to the Web +Service Extensions. +
      +
    1. Right-click on Web Service Extensions and choose Add a new Web Service +Extension.
    2. +
    3. Enter tomcat for the Extension Name.
    4. +
    5. Add the isapi_redirect.dll to the required files.
    6. +
    7. Check the Set extension status to Allowed.
    8. +
    9. Click on OK.
    10. +
    +
  18. +
  19. +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 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 to start it again. +
  20. +
+

+

+That's all, you should now start Tomcat and ask IIS to serve you the /examples context. +Try http://localhost/examples/jsp/index.html for example and +execute some of the JSP examples. +

+

+If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem. +

+ +
Adding additional Contexts
+

+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: +

+

+

    +
  1. +Adding the context to Tomcat (I am not going to talk about this). +
  2. +
  3. +Adding the context to the ISAPI redirector. +
  4. +
+

+

+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: +

+ +
+  /context/*=worker_name
+
+ +

+Workers and their name are defined in workers.properties, by default workers.properties comes +with a single pre-configured worker named "defworker" 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: +

+ +
+  /shop/*=defworker
+
+ +After saving uriworkermap.properties restart IIS and it will serve the new context. +

+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). +

+
+ +
Advanced Context Configuration
+

+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). +

+

+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. +

+

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.

+

+Making IIS serve static files that are part of the Tomcat contexts requires the following: +

    +
  1. +Configuring IIS to know about the Tomcat contexts +
  2. +
  3. +Configuring the redirector to leave the static files for IIS +
  4. +
+

+ +

+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. +

+ +

+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 : + +

+  For the examples context it requires to replace the following line
+  /examples/*=defworker
+  with the following two lines
+  /examples/*.jsp=defworker
+  /examples/servlet/*=defworker
+
+

+ +

+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. +

+ +

+You can even be more explicit and provide lines such as: + +

+  /example/servletname=defworker
+
+

+ +

+that instructs the redirector to redirect all requests whose URL-path matches the leading string "/example/servletname" +to the worker named defworker. +

+ +
+ +
Protecting the content of your Tomcat contexts
+

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. +

+

+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. +

+
+ +
Advanced Worker Configuration
+

+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. +

+

+Defining additional workers is done in the workers.properties file. This file includes two types of entries: +

+ +

+

+  # 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
+
+

+ +

+The above example defined two workers, now we can use these workers to serve two different contexts +each with its own worker: +

+  example uriworkermap.properties fragment
+  /examples/*=worker1
+  /webpages/*=worker2
+
+

+ +

+As you can see the examples context is served by worker1 while the +webpages context is served by worker2. +

+ +

+More information on using and configuring workers in the Workers HowTo +and in the worker.properties configuration reference. +

+ +
+ +
Building ISAPI redirector
+

+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: +

    +
  • +Change directory to the isapi plugins source directory. +
  • +
  • +Make the source with MSDEV +
  • +
+

Change directory to the isapi plugins source directory
c:\>cd c:\home\apache\jk\iis
Build the sources using MSDEV
c:\>MSDEV isapi.dsp /MAKE ALL

+

+

+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. +

+
Troubleshooting
+

+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. +

+ +

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. +

+ +

+Note: These steps assume your worker_mount_file setting points to an unmodified copy of the +uriworkermap.properties file.
+Results may be misleading if worker_mount_file points to a modified uriworkermap.properties +or the uriworkermap.properties-auto file.
+It is also assumed that the "/examples" context works correctly if you access Tomcat directly. +

+ +
Win98
+

+Start the IIS service and Tomcat. +

+

+Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, verify the following: +

+
    +
  • +Check the "Filter DLLs" setting in the "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters" +key and make sure the path is correct. +
  • +
  • +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. +
  • +
  • +Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +
  • +If the above are set correctly, the ISAPI redirector should be able to create the log file. +
+

+Invoke the URL http://localhost/examples/jsp/index.html +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 : +

+

+If the last line contains: +

+
+  GET "/examples/jsp/index.html HTTP/1.1" 404
+
+

+then the ISAPI redirector is not recognising that it should be handling requests for the "/examples" context. +Check the following: +

+
    +
  • +Check the extension_uri name for typos. +
  • +
  • +Check the worker_file setting for typos, name and data. +
  • +
  • +Check the worker_mount_file setting typos, name and data. +
  • +If these are set correctly, the ISAPI redirector should recognise that it should handle requests for the "/examples" context. +
+ +

If the last line contains something like: +

+ +
+  GET "/jakarta/isapi_redirect.dll HTTP1.1"
+
+ +

+then the ISAPI redirector is recognising that it should handle the request, +but is not successful at getting Tomcat to service the request. +

+ +

+You should check the HTTP error code following GET "/..." : +

+ +
+  Error 404
+  GET "/..." 404
+
+ +
    +
  • +Make sure you entered the URL correctly. +
  • +
  • +Make sure the virtual directory created was called "jakarta". +It should display in Personal Web Manager as "/jakarta" (without the quotes). +
  • +
  • +Make sure the extension_uri data begins with "/jakarta/" (without the quotes). +
  • +
+ +
+  Error 500
+  GET "/..." 500
+
+ +
    +
  • +Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri setting. +
  • +
  • +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". +
  • +
+ +
+  Error 200 or 403
+  GET "/..." 200
+  GET "/..." 403
+
+ +
    +
  • +Make sure you have checked Execute Access +for the jakarta virtual directory in the Advanced Options of the Personal Web Manager. +
  • +
+ +

+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. +

+ +
+ +
WinNT/Win2K/WinXP
+

+Start the World Wide Web Publishing Service and Tomcat. +

+

+Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, check the following: +

+
    +
  • +Check the "executable" you set for the filter in the IIS Management Console and make sure the path is correct. +
  • +
  • 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. +
  • +
  • +Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +
  • +If the above are set correctly, the ISAPI redirector should be able to create the log file. +
+ +

+Check the tomcat filter you added and make sure its status shows a green upward-pointing arrow. +If not, check the following: +

+
    +
  • +Check the worker_file setting for typos, name and data. +
  • +
  • +Check the worker_mount_file setting typos, name and data. +
  • +If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong. +
+ +

+Invoke the URL http://localhost/examples/jsp/index.html +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. +

+ +

+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. +

+ +

+You should check the HTTP error code following GET "/..." : +

+ +
+  Error 404
+  GET "/..." 404
+
+ +
    +
  • +Make sure you entered the URL correctly. +
  • +
+ +
+  Error 500
+  GET "/..." 500
+
+ +
    +
  • +Make sure the virtual directory created was called "jakarta". +
  • +
  • +Make sure that the extension_uri setting is correct. +
  • +
  • +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". +
  • +
+ +
+  Error 200 or 403
+  GET "/..." 200
+  GET "/..." 403
+
+ +
    +
  • +Make sure you have checked Execute Access for the jakarta virtual directory in the +Advanced Options of the Personal Web Manager. +
  • +
+ +

+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. +

+
+ + +

+ Copyright © 1999-2011, Apache Software Foundation +
\ No newline at end of file -- cgit 1.2.3-korg