Using the AJP Connector | Pro Apache Tomcat 5/5.5 (Experts Voice in Java)

If you want another Web server, such as Apache or IIS, to handle the static content while Tomcat handles the dynamic content, you need the AJP connector. It works in conjunction with Apache’s mod_jk or an IIS ISAPI module to deploy Web applications with the combination of Tomcat and another Web server. The following sections cover Apache 1.3.x, Apache 2.0.50, and IIS. A basic knowledge of Apache is assumed; the following URL may be of use as a quick reference: http://httpd.apache.org/docs/install.html.

Introducing mod_jk and mod_jk2

To integrate Tomcat with a Web server, you need a redirector module that will forward client requests for JSP pages and servlets from the Web server to Tomcat. You do this by matching the URL pattern of the request to a mapping in a configuration file. The JSP pages/servlets then handle the forwarded request, generate an appropriate dynamic response, and send it to the client via the module. To address this requirement, the Jakarta project provides modules called mod_jk and mod_jk2. The mod_jk2 module is a refactored version of mod_jk and has been designed with Apache 2.0, Microsoft IIS, and other multithreaded Web servers in mind, though it still works with older Web servers such as Apache 1.3. Both modules use the same protocol to link Tomcat with the external Web server: the differences for the administrator are configuration and performance.

If you’ve previously configured Apache to use mod_jserv, remove any ApJServMount directives from your httpd.conf file. If you’re including tomcat-apache.conf or tomcat.conf, you’ll want to remove them as well, as they’re specific to mod_jserv. These steps are necessary because the mod_jserv configuration directives aren’t compatible with mod_jk and mod_jk2.

Note

mod_jserv was a port of Apache JServ, the Apache server’s servlet engine module. Unfortunately, this meant that a lot of unnecessary functionality was included with mod_jserv. After all, the idea was to talk to Tomcat, not do its job for it. This was not the only problem with the mod_jserv module. The fact that it could be used only on Apache running on Unix was a particularly limiting attribute.

The Apache JServ Protocol

The Apache JServ Protocol (AJP) is a packet-oriented, TCP/IP-based protocol. It provides a communication channel between the Apache Web server process and running instances of Tomcat. Various versions of this protocol are available, including versions 1.2, 1.3, and 1.4. AJP 1.3 is the most commonly used and well-tested version used by Tomcat, so it’s the only version of the protocol I’ll discuss.

AJP ensures good performance by reusing already open TCP-level connections with the Tomcat container and as such saves the overhead of opening new socket connections for each request. This is a concept similar to that of a connection pool and makes things simple by avoiding the cost of more opened connections. In the request-response cycle, when a connection is assigned to a particular request, it will not be reused until that request-response cycle is completed.

Note

When integrating with IIS, you also use AJP as your protocol. Don’t be deceived by the Apache in its name. This simply refers to the provider of the protocol and the module, not to the Web server.

Worker Implementations

A worker is a Tomcat instance that serves JSP/servlet requests coming from another Web server. In most cases, there’s only a single Tomcat process, but sometimes you’ll need to run multiple workers to implement load balancing or site partitioning (mainly required for sites with heavy traffic). You’ll see how to achieve this with both versions of Apache and IIS in the following sections.

Each worker is identified by a host name/IP and port number combination. Here host means the machine on which the given Tomcat instance is running, and port refers to the port on which that instance is listening for any requests.

Multiple Tomcat Workers

You may use a multiple worker setup in a number of situations:

You may want different contexts to be served by different Tomcat workers. This setup will provide a development environment where all the developers share the same Web server but own a Tomcat worker of their own.
You may want different virtual hosts served by different Tomcat processes to provide a clear separation between sites belonging to different entities.
You may want to provide load balancing, where you run multiple Tomcat workers each on a machine of its own (or maybe on the same machine) and distribute the requests between them.

Integrating Tomcat with Apache 1.3 Using mod_jk

mod_jk isn’t available as a binary for Apache 1.3 if you’re using Linux, though you can build it from source, as shown next. It’s available as a binary for Apache 2.0. A Windows DLL (rename it to mod_jk.dll) and shared objects exist for other platforms. You can find all these via the Jakarta binaries download page. After downloading the DLL or shared object, move it to the modules subdirectory of Apache.

To build the module on Linux (and other Unix-like systems), extract the download to a convenient location and navigate to the jk/native subdirectory. Here you should run the following commands (modifying the path to your Apache 1.3 apxs):

 > ./configure --with-apxs=/usr/sbin/apxs  > make  > cp ./apache-1.3/mod_jk.so /usr/lib/apache/modules

The first command configures the build so that the resultant module is compatible with Apache 1.3 (or whichever version of Apache you specify because this command is equally applicable to Apache 2.0). The make command builds the module, and the final command copies the built module to Apache’s modules directory.

Configuring the AJP Connector in server.xml

The AJP connector configuration in server.xml is already present. This makes configuration easy, as you don’t need to do anything at all.

Setting the workers.properties File

Each running Tomcat instance is represented as a single worker. You can set up Tomcat workers for the Web server plug-in by using a simple properties file called workers.properties, which is used only with mod_jk and not mod_jk2. This file consists of entries that will convey information about Tomcat workers to the Web server plug-in.

Format of workers.properties File

The format used by workers.properties for defining a list of available workers is as follows:

 worker.list = <comma-separated list of worker names>

For example, here you define two workers named worker1 and worker2:

 worker.list = worker1, worker2

You can also define a property for a given worker, as follows:

 worker.<worker name>.<property> = <property value>

For example, you can assign the value localhost to the host attribute of worker1, like so:

 worker.worker1.host = localhost

Types of Workers in mod_jk

Any defined Tomcat worker needs to be assigned a type. You can assign the following types to various Tomcat workers:

ajp13: This type of worker uses the AJP 1.3 protocol to forward requests to out-of-process Tomcat workers.
lb: This type of worker is used for load balancing. In a load-balancing scenario, this type of worker doesn’t handle any processing; it just handles the communication between a Web server and other defined Tomcat workers of type ajp13. This kind of worker supports round-robin load balancing with a certain level of fault tolerance. You’ll see this in more detail in the “Understanding Tomcat Load Balancing” section.

For example, the following line sets the type of worker1 to ajp13, meaning it will use the AJP 1.3 protocol:

 worker.worker1.type=ajp13

Worker Properties

After you’ve set a worker’s type, you can set a number of other properties. You can set the port on which the worker listens as shown next. However, if your worker is of type ajp13, it will listen for AJP requests, by default, on port 8009.

 worker.worker1.port=8009

Next you configure the host where the Tomcat worker is listening for requests. For example, if worker1 is running on localhost, then set the entry as follows:

 worker.worker1.host=localhost

When working with a load balancer worker, you need to set the load-balancing factor for this worker. For example, if worker1 is running with a load balancer, then, depending on the hardware condition of the machine, you can set the corresponding load factor as follows:

 worker.worker1.lbfactor=5

Some Web servers (for example, Apache 2.0 and IIS) are multithreaded, and Tomcat can take advantage of this by keeping a number of connections open as a cache, though you shouldn’t use mod_jk with these servers because of mod_jk2’s superior multithreaded abilities. An appropriately high value based on the average number of concurrent users for Tomcat can prove beneficial from a performance point of view (the default is 1).

 worker.worker1.cachesize=20

Configuring a Tomcat Worker

Create workers.properties in CATALINA_HOME/conf, as shown in Listing 9-5.

Listing 9-5: workers.properties for mod_jk

 # For Windows:  # Setting Tomcat & Java Home  workers.tomcat_home="c:\jakarta-tomcat"  workers.java_home="c:\j2sdk1.4.2"  ps=\  worker.list=worker1  # Settings for worker1 worker  worker.worker1.port=8009  worker.worker1.host=localhost  worker.worker1.type=ajp13  # ----------------------- # For Linux/Unix systems:  # Setting Tomcat & Java Home  workers.tomcat_home=/usr/java/jakarta-tomcat  workers.java_home=/usr/java/j2sdk1.4.2  ps=/  worker.list=worker1  # Settings for worker1 worker  worker.worker1.port=8009  worker.worker1.host=localhost  worker.worker1.type=ajp13

The ps=\ line sets the path separator for the operating system on which Tomcat is running.

Configuration Settings for Apache

Tomcat and Apache can communicate once the information about the available Tomcat workers is included in the httpd.conf Apache Web server configuration file. You have two ways in which to do this, both of which are discussed next.

Autogenerating Configuration Settings

You can configure Tomcat to automatically generate a configuration file called mod_jk.conf. You can then include this in the main Apache configuration file.

The mod_jk.conf file is created every time Tomcat starts, so make sure you really can afford this overhead. Also, this will reset all your deployment settings, as Tomcat overwrites the file every time.

To generate the settings, you need to add special listeners at the server and host levels. Just add the code in Listing 9-6 after the <Server port="8005"> declaration.

Listing 9-6: A Listener That Will Autogenerate mod_jk Settings

 <Listener className="org.apache.jk.config.ApacheConfig"      modJk="C:/Program Files/Apache Group/Apache/modules/mod_jk.dll"      workersConfig="C:/jakarta-tomcat/conf/workers.properties"      jkLog="C:/jakarta-tomcat/logs/mod_jk.log"      jkDebug="info"  />

Here you provide the necessary information to the listener. It creates appropriate entries, such as the LoadModule entries for mod_jk, in the autogenerated mod_jk.conf file using this information. Here you provide the location of the workers.properties file, the location of the mod_jk module, the location of the log file, and the level of logging information you require.

Table 9-1 describes the attributes supported by the ApacheConfig listener.

Table 9-1: The Attributes of the ApacheConfig Listener
Attribute	Description	Required?
configHome	The default parent directory for all the paths provided as attribute values. It’s overridden when absolute paths are provided for any attribute value. The default is CATALINA_HOME.	No
jkConfig	The location of the Apache mod_jk.conf file. The default is CATALINA_HOME/conf/auto/mod_jk.conf.	No
workersConfig	The path to the workers.properties file used by mod_jk. The default is CATALINA_HOME/conf/jk/workers.properties.	No
modJk	The path to the Apache mod_jk module. If not set, this defaults to modules/mod_jk.dll on Windows and modules/mod_jk.so on Linux/Unix systems.	No
jkLog	The path to the log file that mod_jk uses.	No
jkDebug	The level of logging to be done by mod_jk. May be debug, info, error, or emerg. If not set, this defaults to emerg.	No
jkWorker	The desired worker. This must be set to one of the workers defined in the workers.properties file and defaults to ajp13.	No
forwardAll	If this is set to true (the default), mod_jk will forward all requests to Tomcat. This ensures that all the behavior configured in web.xml functions correctly. If false, Apache will serve static resources. Note that when set to false, some of Tomcat’s configuration may not be duplicated in Apache, so check the generated mod_jk.conf file to see what configuration is actually being set in Apache.	No
noRoot	If this attribute is set to true, the ROOT context isn’t mapped to Tomcat. If false and forwardAll is true, all requests to the ROOT context are mapped to Tomcat. If false and forwardAll is false, only JSP page and servlet requests to the ROOT context are mapped to Tomcat. When false, to correctly serve Tomcat’s ROOT context, you must also modify the DocumentRoot setting in Apache’s httpd.conf file to point to Tomcat’s ROOT context directory. Otherwise, Apache will serve some content, such as index.html, before mod_jk can get the request and pass it on to Tomcat. The default is true.	No
append	Append the generated configuration file to the current configuration file. The default is false. Therefore, it’s a good idea to back up the values in another file and reference it from Apache.	No

The next step is to create an Apache <VirtualHost> entry in the resultant mod_jk.conf file. This ensures that all requests to the Tomcat host are mapped to the Apache host correctly. Add a listener below each <Host> entry that you’re integrating, as shown in Listing 9-7.

Listing 9-7: A Listener That Will Define Virtual Hosts in mod_jk.conf

 <Listener className="org.apache.jk.config.ApacheConfig"            append="true"            jkWorker="worker1" />

You can also choose individual Tomcat contexts by adding the listener after the <Context> in the context XML file. Now start Tomcat, and open the CATALINA_HOME/conf/auto/mod_jk.conf file. If you had used the previous values, your file should look like the one in Listing 9-8.

Listing 9-8: The Autogenerated mod_jk.conf File

 <IfModule !mod_jk.c>    LoadModule jk_module "C:/Program Files/Apache Group/Apache/modules/mod_jk.dll"  </IfModule>  JkWorkersFile "C:/jakarta-tomcat/conf/workers.properties"  JkLogFile "C:/jakarta-tomcat/logs/mod_jk.log"  JkLogLevel info  <VirtualHost localhost>      ServerName localhost      JkMount /admin worker1      JkMount /admin/* worker1      JkMount /servlets-examples worker1      JkMount /servlets-examples/* worker1      JkMount /webdav worker1      JkMount /webdav/* worker1      JkMount /jsp-examples worker1      JkMount /jsp-examples/* worker1      JkMount /balancer worker1      JkMount /balancer/* worker1      JkMount /tomcatBook worker1      JkMount /tomcatBook/* worker1      JkMount /tomcat-docs worker1      JkMount /tomcat-docs/* worker1      JkMount /manager worker1      JkMount /manager/* worker1  </VirtualHost>

The JkMount directive mounts a Tomcat directory onto the Apache root Web context. The other three JK directives are pretty self-explanatory.

 JkWorkersFile "C:/jakarta-tomcat/conf/workers.properties"  JkLogFile "C:/jakarta-tomcat/logs/mod_jk.log"  JkLogLevel info

The log file is where any AJP-specific information is placed. Access logs for resources on Tomcat and Apache function as normal.

Each time Tomcat is started, it will write the configuration file to CATALINA_HOME/conf/ auto/mod_jk.conf. As a result, your settings will be overwritten. Therefore, you should either disable the autogeneration option by commenting out the directive in server.xml or copy the file to another location.

The final step is to include this file in Apache’s httpd.conf file as follows. Place this entry at the end of the file.

 Include "C:/jakarta-tomcat/conf/auto/mod_jk.conf"

Adding Configuration Settings Manually

If you don’t want to use ApacheConfig, you need to append the previous settings to the end of your httpd.conf or save them as mod_jk.conf in CATALINA_HOME/conf/auto.

Testing the Final Setup

Next, you’ll see how Apache accepts every request. All the requests for any dynamic processing, like JSP pages or servlets, will be handed over to Tomcat. Similarly, any response from them will be sent to the client through Apache.

The first step for testing will be to check the JSP examples Web application by pointing a browser at http://localhost/jsp-examples/. If everything is set up correctly, you should see the list of examples.

This shows that the integrated combination of Tomcat and Apache is working fine for serving static content. Now check whether mod_jk is doing its job equally well for serving dynamic content by clicking one of the examples.

After testing the deployment from a local machine, test the installation from any other machine across the network. This will make sure the settings you made are working as expected.

Integrating Tomcat with Apache 2.0 Using mod_jk2

Using mod_jk2 is similar to the previous instructions, though Tomcat is no longer the place to generate mappings.

Configuring the AJP Connector in server.xml

The AJP connector configuration in server.xml is already present. This makes configuration easy, as you don’t need to do anything at all.

Setting the workers2.properties File

Each running Tomcat instance is represented as a single worker. You can set up Tomcat workers for the Web server plug-in by using a simple properties file called workers2.properties. This file consists of entries that will convey information about Tomcat workers to the Web server plug-in. The workers2.properties is kept in Apache’s conf directory by default.

Format of workers2.properties File

The format used by workers2.properties for defining a list of available workers is as follows:

 [TYPE:NAME]  PROPERTY=VALUE

You also have the option of using the old format from mod_jk.

To define a connection to a running Tomcat instance, you should define a channel.socket component:

 [channel.socket:localhost:8009]

This example will communicate with a Tomcat instance running on the localhost host that listens on port 8009. Once you’ve defined a connection, you must add a worker and assign it to an existing channel:

 [ajp13:localhost:8009]  channel=channel.socket:localhost:8009

In this case, ajp13 is the type of worker and localhost:8009 is the name of the worker. The name has been chosen as a reminder of its host and port, though changing these in the name won’t change the actual connection to the Tomcat instance.

Types of Workers in mod_jk2

Any defined Tomcat worker needs to be assigned a type. You can assign the following types to various Tomcat workers:

ajp13: This type of worker uses the AJP 1.3 protocol to forward requests to out-of-process Tomcat workers.
lb: This type of worker is used for load balancing. In a load-balancing scenario, this type of worker doesn’t handle any processing; it just handles the communication between a Web server and other defined Tomcat workers of type ajp13. This kind of worker supports round-robin load balancing with a certain level of fault tolerance. You’ll see this in more detail in the “Understanding Tomcat Load Balancing” section.
status: This is an internal mod_jk2 worker, which displays monitoring information as HTML. As such, it doesn’t connect to any Tomcat instance.

Worker Properties

After you’ve set a worker’s type, you can set a number of other properties. The host and port on which the worker listens is defined on the channel to which it belongs.

When working with a load balancer worker, you need to set the load-balancing factor for this worker. For example, if localhost:8009 is running with a load balancer, then, depending on the hardware condition of the machine, you can set the corresponding load factor.

 [ajp13:localhost:8009]  channel=channel.socket:localhost:8009  lb_factor=2

Some Web servers (for example, Apache 2.0 and IIS) are multithreaded, and Tomcat can take advantage of this by keeping a number of connections open as a cache. An appropriately high value based on the average number of concurrent users for Tomcat can prove beneficial from a performance point of view (the default is 0).

 [ajp13:localhost:8009]  channel=channel.socket:localhost:8009  lb_factor=2  max_connections=10

Configuring a Tomcat Worker

Create workers2.properties in Apache 2.0’s conf directory, as shown in Listing 9-9.

Listing 9-9: workers2.properties

 [channel.socket:localhost:8009]  [ajp13:localhost:8009]  channel=channel.socket:localhost:8009  [status:statusWorker]  styleMode=1  [uri:/jkstatus]  group=status:statusWorker  [uri:/jsp-examples/*]  worker=ajp13:localhost:8009

This defines an ajp13 worker called localhost:8009 and a status worker called statusWorker. The [uri:] sections assign a URI to a worker. So, /jkstatus is assigned to statusWorker, and everything under /jsp-examples is assigned to localhost:8009. This configuration uses the default logger, which on an Apache server is the error.log log file.

Configuration Settings for Apache

Tomcat and Apache can communicate once the information about the available Tomcat workers is included in the httpd.conf Apache Web server configuration file. You have two ways to do this, both of which I discuss next.

Autogenerating Configuration Settings

You have two ways to autoconfigure settings, though they use the same Java class. This class is called org.apache.jk.config.WebXml2Jk, and it converts web.xml settings into mod_jk2 settings.

The first method is at the command line. Run the following command, which specifies the location of the web.xml file you want to convert:

 > java -classpath    %CATALINA_HOME%/server/lib/jkconfig.jar;    %CATALINA_HOME%/bin/commons-logging-api.jar;    %CATALINA_HOME%/server/lib/tomcat-util.jar      org.apache.jk.config.WebXml2Jk      -context /jsp-examples      -docBase %CATALINA_HOME%/webapps/jsp-examples      -host localhost

This creates three files in WEB-INF/jk2 of the Web application specified with the -docBase switch. You can use the jk.conf file with mod_jk though it’s not as efficient as the techniques used previously. The jk2.conf file is the mod_jk2 version, and you include it in Apache’s httpd.conf file. The jk2map.properties file contains the mappings for workers2.properties. Copy these settings across to workers2.properties, and add the following include to Apache’s httpd.conf file:

 Include "C:/jakarta-tomcat/webapps/jsp-examples/WEB-INF/jk2/jk2.conf"

The second way to autogenerate settings is to use org.apache.jk.config.WebXml2Jk through Ant. You may already have a build.xml file from an earlier chapter. If that’s the case, just add the task definition and the target from Listing 9-10 to it. If not, create a file called build.xml and add the code from Listing 9-10.

Listing 9-10: Using Ant to Generate mod_jk2 Settings

 <project name="Jk2Application" default="jk2Generate" basedir=".">    <taskdef name="jk2Generate"             classname="org.apache.jk.config.WebXml2Jk"/>    <target name="jk2Generate" description="Generate JK2 Settings">      <jk2Generate        docBase="C:/jakarta-tomcat-5.0.27/webapps/jsp-examples"        context="/jsp-examples"        host="localhost" />    </target>  </project>

You must make sure that commons-logging-api.jar, tomcat-util.jar, and jkconfig.jar are in Ant’s classpath. (Placing them in ANT_HOME/lib is one way to do this.) Once this is done, you simply have to run the following command to create the mod_jk2 configuration, assuming you’re in the same directory as the previous build.xml file:

 > ant

Testing the Final Setup

In this section, you’ll see how Apache accepts every request. All the requests for any dynamic processing, such as JSP pages or servlets, will be handed over to Tomcat. Similarly, any response from them will be sent to the client through Apache.

This shows that the integrated combination of Tomcat and Apache is working fine for serving static content. Now check whether mod_jk2 is doing its job equally well for serving dynamic content by clicking one of the examples.

After testing the deployment from a local machine, test the installation from any other machine across the network. This will make sure that the settings you made are working as expected.

Finally, visit http://localhost/jkstatus, and you’ll see a screen similar to that in Figure 9-2. You can use various pieces of information to analyze and monitor the Tomcat-Apache bridge.

image from book
Figure 9-2: mod_jk2’s status screen

Integrating Tomcat with IIS

IIS is Microsoft’s Web server and is optimized for the Windows operating system. Why would you want to run IIS with Tomcat? You may want to do this in an environment that needs to be capable of supporting multiple development platforms, such as Microsoft’s ASP and the alternative JSP. Also, you get better performance on Windows by using the Web serving capability of IIS and Tomcat as the servlet/JSP container instead of using Tomcat as both a Web server and a servlet container.

IIS is a Web server but can also process ASP, which is Microsoft’s answer to server-side scripting. It doesn’t have a servlet container and can’t by default process JSP pages and servlets. However, you can extend IIS by adding ISAPI filters, which you can then use to configure third-party components such as servlets and JSP pages. ISAPI filters are plug-ins to IIS that filter incoming requests, perform custom processing, call other applications, and perform filtering functions on output that’s to be sent to the client. The Apache group has created an ISAPI filter that can be added to IIS and configured so that IIS handles all requests except for JSP pages and servlets, which it redirects to Tomcat.

Introducing ISAPI

The ISAPI redirector that enables integration between IIS and Tomcat is available for download as a DLL called isapi_redirector2.dll from the usual range of Apache mirrors. ISAPI is Microsoft’s answer to CGI, and it allows Microsoft to customize and extend the functionality of IIS. The isapi_redirector2.dll file is referred to as a redirector because it filters incoming URL requests and redirects some of them to Tomcat using AJP.

The filters processed by isapi_redirector2.dll are configurable. As this redirector is based on mod_jk2, these are specified in a file called workers2.properties, which uses the same settings as the Apache configuration described previously. This makes it extremely easy to port your Apache mod_jk2 settings over to an IIS setup.

You can specify which incoming requests IIS should forward to Tomcat by editing the contents of this file. The Tomcat process that receives and processes requests from the ISAPI redirector is called the worker. The Tomcat worker exists as out of process, that is, as a distinct process within the operating system.

The ISAPI redirector communicates with an out-of-process Tomcat worker over TCP/IP using AJP and must know the specifics of the Tomcat worker. The specific configuration information could be an IP port number and machine name, and the administrator configures this information in the workers2.properties file. This file also has a list of the defined workers. Note that since AJP 1.3 runs over TCP/IP, it lends itself to distributed client-server configurations.

Installing IIS

Check to verify that IIS is installed on your Windows machine. If not, you’ll need to install IIS by going to Start Settings Control Panel and selecting the Add/Remove Programs application. Look under the Add/Remove Windows Components section to install IIS.

Downloading the isapi_redirector2.dll

Once you have IIS on your system, the next thing to do is download the ISAPI redirector (isapi_redirector2.dll) from an Apache mirror. Place this file in the CATLINA_HOME\bin directory. Note that you can also build a copy of this .dll from source, but the easiest thing to do is to download the binary version.

Configuring the AJP Connector in server.xml

The AJP connector configuration in server.xml is already present. This makes configuration easy, as you don’t need to do anything at all.

Setting the workers2.properties File

As mentioned, you set up Tomcat workers for the Web server plug-in by using the simple properties file called workers2.properties. This file consists of entries that will convey information about Tomcat workers to the Web server plug-in. Unlike with Apache, you can place workers2.properties wherever you like, though you must tell IIS where it is. You’ll see how to do this in the next section. For a description of the workers2.properties file, see the Apache 2.0 “Setting the workers2.properties File” section.

Creating the Registry Entries

The ISAPI redirector (isapi_redirector2.dll) uses certain registry entries to initialize its configuration. These entries need to be created so that Tomcat can locate the configuration files that tell the redirector where to send incoming requests for servlets and how to log messages. Create a file called iis_redirect.reg, and edit it as follows:

 REGEDIT4  [HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi  Redirector\2.0]  "serverRoot"="C:\\jakarta-tomcat"  "extensionUri"="/jakarta/isapi_redirector2.dll"  "workersFile"="C:\\jakarta-tomcat\\conf\\workers2IIS.properties"

Don’t use relative path names. Most problems with registering the isapi_redirector2.dll filter in IIS are associated with incorrect path names in the registry.

Let’s take a look at each of the registry entries.

serverRoot: This is the directory where you’ve installed Tomcat.
extensionUri: This is the URL to the isapi-redirector extension. Note that jakarta is a virtual directory within IIS that you’ll create later in the installation procedure.
workersFile: This is the path to the workers2.properties file.

To create the registry entries, double-click the iis_redirect.reg file, and you’ll get a warning message box. Select Yes to create the registry entries, and the script will create the values in the registry. At this point, you should open the registry using the regedt32 utility and verify the registry entry keys that were created for you under HKEY_LOCAL_MACHINE\SOFTWARE\ Apache Software Foundation\Jakarta Isapi Redirector\2.0.

Note that you could also have created these entries manually, but the previous procedure creates an easy starting point. If you need to uninstall Tomcat at some point, you can remove these registry entries manually by deleting them using the regedt32 utility.

Caution

You should be cautious while modifying the registry, as mistakes can prevent a Windows application from working correctly.

Configuring a Tomcat Worker

Create workers2IIS.properties as shown in Listing 9-11. You need to place this file in the directory you specified in the “Creating the Registry Entries” section. The path in the registry to this key is HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\ 2.0\workerFile. In your case, the directory is the %CATALINA_HOME%\conf directory.

Listing 9-11: workers2IIS.properties

 [channel.socket:localhost:8009]  [ajp13:localhost:8009]  channel=channel.socket:localhost:8009  [status:statusWorker]  styleMode=1  [uri:/jkstatus]  group=status:statusWorker  [uri:/jsp-examples/*]  worker=ajp13:localhost:8009

This defines an ajp13 worker called localhost:8009 and a status worker called statusWorker. The [uri:] sections assign a URI to a worker. So, /jkstatus is assigned to statusWorker, and everything under /jsp-examples is assigned to localhost:8009. You set a log file when you configured the registry entries previously.

Configuration Settings for IIS

You need to create a virtual directory within IIS for the ISAPI redirector because the IIS redirector is an IIS plug-in; that is, it’s a filter and an extension. IIS calls the filter function for incoming requests. If the incoming URL matches the list of filters maintained in workers2IIS.properties, control is transferred to the extension in the form /jakarta/isapi_redirector2.dll—you may remember this entry from the registry setting for the extensionUri that you set up. To create the virtual directory, you should do the following:

Open IIS Manager (Internet Services Manager).
Right-click Default Web Site, and select New Virtual Directory.
The Virtual Directory Creation Wizard will open. Use jakarta as the name of the virtual directory alias. Note that the name of the virtual directory has to be jakarta because of the previous registry entry.
The wizard will prompt you for a directory. Specify the directory of the installed isapi_redirector2.dll. This is the bin\ directory under the root Tomcat install.
The wizard will prompt you for access permissions. The access permissions should be just read and execute.

Once you’ve created the jakarta virtual directory, it’s a good idea to open it to review the properties you’ve set for the virtual directory. You can do this by right-clicking the virtual directory and selecting Properties.

You can now install the ISAPI redirector in IIS. To do this, follow these steps:

In IIS Manager, right-click Default Web Site, select Properties from the drop-down menu, and click it to open the Properties window.
In the Properties window, click the ISAPI Filters tab.
Click the Add button.

You’ll be prompted for the name of the filter and the location of isapi_redirector2.dll. For the name of the filter, use jakarta. Use the Browse button to select isapi_redirector2.dll, which is in %CATALINA_HOME%\bin directory.

Close IIS Manager if you have it open, and restart IIS. Make sure you do this using the Services management console in the Control Panel. Don’t do this using IIS Manager. You’ll need to restart two services—these are the IIS Admin service and the World Wide Web Publishing service, though the console may do this automatically.

After you’ve restarted IIS, open up IIS Manager, check to see that there’s a green arrow pointing upward next to the ISAPI redirector that you’ve just installed. If you don’t see the green arrow, then there’s a problem with the install of the ISAPI redirector. This is a common error encountered during a first install.

Check your registry entries and the configuration files. Nine times out of ten, problems with this part of the install occur because the paths set in the registry settings for workersFile (workers2IIS.properties) are wrong. If these files are in the correct locations and the registry keys are defined properly, that is, names are spelled correctly, the ISAPI redirector should load regardless of the content in these files and regardless of the values of the other registry settings. As an experiment, place a blank workers2IIS.properties file in the correct location and restart IIS.

Restart IIS by restarting the IIS Admin service and the World Wide Web Publishing service. Verify that the path you’ve specified to isapi_redirector2.dll when adding the filter is valid.

Testing the Final Setup

In this section, you’ll see how IIS accepts every request. All the requests for any dynamic processing, such as JSP pages or servlets, will be handed over to Tomcat. Similarly, any response from them will be sent to the client through IIS.

This shows that the integrated combination of Tomcat and IIS is working fine for serving static content. Now check whether the ISAPI redirector is doing its job equally well for serving dynamic content by clicking one of the examples.

After testing the deployment from a local machine, test the installation from any other machine across the network. This will make sure that the settings you made are working as expected.

Finally, visit http://localhost/jkstatus, and you’ll see a screen similar to that in Figure 9-2. You can use various pieces of information to analyze and monitor the Tomcat-Apache bridge.

Troubleshooting the IIS Setup

If you don’t see the screens described in the previous figures, then one of a number of things could have gone wrong with your setup. Verify that IIS is running. You can do this in the Services console. At a minimum, you need to have the IIS Admin service and the World Wide Web Publishing service running.

Within IIS check that you’ve installed the ISAPI redirector properly. If you’ve installed it properly, it should have a green arrow next to it.

Verify that you’ve defined the jakarta virtual directory properly. If there’s something wrong with it, IIS will indicate this by flagging it with a red symbol. Check that the name of this virtual directory is indeed jakarta.

Look within the IIS log. The IIS log is by default located in C:\WINNT\system32\LogFiles\ W3SVC1; you can also click the Properties button in the Web site Properties window to see where it is. By default a different log file is generated every day. In the log file you should see the following entry:

 01:10:33 127.0.0.1 GET /jakarta/isapi_redirector2.dll 200

If this entry doesn’t exist in the IIS log, then the ISAPI redirector isn’t called by IIS. The value 200 is the HTTP status code. If the call to isapi_redirector2.dll exists but you’re getting a status code such as 400, 404, or 500, then you have an error.

Make sure Tomcat is running and that the connector is listening on the correct port. This is port 8009 by default and is defined in the server.xml file. You can review this by opening a DOS prompt and running the command netstat -a from the command line. You should see a line similar to the following line as one of the entries:

 TCP  localaddress:8009 foreignaddress:0  LISTENING

You may want to check that you don’t have any additional filters defined besides the ISAPI redirector, which may be creating a conflict. If you do have additional filters defined in IIS, you may want to try removing them.

Verify the content of the workers2IIS.properties file. Check that you’ve defined the worker correctly.