Tomcat-Apache using JK2 connector

There are a couple of ways of using the JK2 connector to connect Apache and Tomcat together. One way is to run both Tomcat and Apache as standalone servers and create a TCP socket connection between them. The other method is by calling Tomcat, from inside of Apache, as an in-process Servlet container. The two methods are outlined below. Please note that this document only works for Apache 2.x and Tomcat 4.1.x. It has been tested with Apache 2.0.45 and Tomcat 4.1.24 on Windows XP Professional SP1. The JRE used was Sun 1.4.2. As of testing this was a beta product.

JK2 connector using TCP Sockets

The advantage to using TCP sockets to connect Apache and Tomcat is that both servers can be configured and run independently. Another advantage to this method is that the configuration is fairly straight forward. The disadvantage is that Tomcat must be started separately and be kept running.

Please note the following convention that is used in this section. Substitute the appropriate string for your configuration. Note that those that I meant for substitution are in bold font.

$APACHE_HOME – This is the full path to where Apache is installed. In our testing it was ¡®c:/Apache2¡¯.
$TOMCAT_HOME –This is the full path to where Tomcat is installed. In our testing it was ¡®d:/Tomcat4.1¡¯.
$CATALINA_HOME –This is the same as $TOMCAT_HOME.

For example if I write, ¡®$APACHE_HOME/conf/httpd.conf¡¯. Please substitute it with ¡®c:/Apache2/conf/httpd.conf¡¯.

Step one–Preliminary testing

First install and configure both Apache and Tomcat, as discussed in another document. The following conventions are used.

Before beginning, ensure that both Apache and Tomcat are running and configured properly. Test the examples from Tomcat and try to browse the on-line documents in Apache. If you can run both concurrently you are ready to connect the two. I do not discuss here how to perform the test as it depends on your configuration and thus outside the scope of this document. You should refer to your document on configuring Apache and configuring Tomcat for this.

Step two–Getting the connector

The second thing to do is to download the mod_jk2 connector DSO. In Windows this will be a dll. The connector will most likely come as a file called, ¡®mod_jk2-2.0.24.dll¡¯. Rename it to ¡®mod_jk2.dll¡¯. This makes it easier to deal with. Save the file in the modules directory. This should be, ¡®$APACHE_HOME/modules¡¯.

Step three—Editing the configuration files

There are four files that must be edited for the connector. They are; the httpd.conf file, the jk2.properties file, the server.xml file, and the workers2.properties.

The ¡®httpd.conf¡¯ file

The httpd.conf file should be at ¡®$APACHE_HOME/conf/httpd.conf¡¯. This file contains the main configuration data for Apache. We will use this file to tell Apache to load the mod_jk2 DSO module. Locate the portion of the where other modules are being loaded. To be safe we enclose it inside of an ¡®if¡¯ statement. That way if we accidentally try to load the module twice we won¡¯t get into trouble.

For more information about the httpd.conf file refer to the documentation included in the Apache distribution or the book available in our library.

The ¡®jk2.properties¡¯ file

The jk2.properties file should be in the directory ¡®$TOMCAT_HOME/conf¡¯. This file contains all of the JK2 configuration information. Here we will set up the shared memory directive. This directive is necessary for Apache and Tomcat to communicate. A good place to have the file is the ¡®$APACHE_HOME/logs¡¯ directory. The file can be named anything but the convention is ¡®jk2.shm¡¯.
TODO: What to do in case Tomcat and Apache reside on different machines.

This default is fine and no other directives need to go in this file.

Unfortunately there is sparse documentation for the jk2.properties. Documentation for this file is available in the tomcat-connectors section of the Apache Software Group¡¯s Jakarta website. This documentation is incomplete and contains many mistakes. A more through set of documents is included in the source distribution of the JK2 connector; however it is also incomplete and contains many errors. I have found few on-line resources for this and most books covering this are totally incorrect.

The ¡®server.xml¡¯ file

The server.xml file is located in the ¡®$TOMCAT_HOME/conf¡¯ directory. This file contains all of the configuration data for Tomcat. By default Tomcat runs as a Standalone server and it also opens a JK2 connector over TCP sockets. We will disable the Standalone service and just use the JK2 connector.

The default port for the JK2 connector is 8009. This is an uncommon port number so we should just keep it. Remember the port number for the workers2.properties file.

There is a lot of on-line help for configuring the server.xml file. There is some help in the Tomcat configuration document also. The best is to get a book on Tomcat, it will most definitely have loads of information on this, but probably not too much on the JK2 connector.

The ¡®workers2.properties¡¯ file

This file is the workhorse of the JK2 connector. In order for the JK2 connector to work it must be created in the ¡®$APACHE_HOME/conf¡¯ directory. This file sets up the workers that will carry out the work of the servlet container. The simplest file needs only two directives for the JK2 connector. The first is the SHM file directive. This entry must match what went into the jk2.properties file. The second directive defines the worker. In this case the worker is a TCP socket connection called channel.socket. Of course you should define an URI directive to translate your requests to Tomcat. Otherwise what¡¯s the point in using the JK2 connector? But strictly speaking it is not necessary.

In the above example we have defined the SHM file exactly as in the jk2.properties file. Also we have defined the channel.socket worker to work from the localhost and on port 8009. This assumes that the Tomcat server is running on this machine. The directive of most relevance is the uri directive. Above we forward all URIs with the directory starting with ¡®/examples/¡¯ to the Tomcat server. Note that if we try an URL such as, ¡®http://localhost/examples¡¯, the request will not get forwarded. Note that the final ¡®/¡¯ must be present in the URL. You could of course add another URI directive for ¡®/examples¡¯. This URL is forwarded to Tomcat and depending on what is in the Tomcat configuration it will be processed just as if the Tomcat standalone server received this request.

Like the jk2.properties file, the workers2.properties file does not have many supporting references. Most of the references on-line and in books are wrong or misleading. The documents posted on the tomcat-connectors portion of the Jakarta website contain many errors but may be a good place to begin looking.

Step four—Running and testing

Once the configuration is finished you can start the testing. The thing to do is to open two command prompts. In one command prompt go to, ¡®$TOMCAT_HOME/bin¡¯ and start Tomcat with the command, ¡®startup¡¯. A new window should open up with some start-up data. In the other command prompt go to, ¡®$APACHE_HOME/bin¡¯ and start the Apache web server with the command, ¡®apache –k start¡¯. If your configuration had no errors in it a few seconds later you will be returned to the prompt. Note that it is important to start Tomcat before Apache, otherwise the connectors cannot initialize. You can now check that the connector is running by trying to go to the examples web-app. In the default Tomcat configuration this should be at, ¡®http://localhost/examples/¡¯. If a Tomcat directory listing is shown then you have successfully configured the Apache-Tomcat connector. If you get a 500 series error then obviously a configuration error has occurred.

Troubleshooting is beyond the scope of this document but in case of an error; check that all the paths are correct. Also note that it is best to have installed Apache and Tomcat in directories without spaces. Additionally it is a good idea to create a status context where you can check the status of the connector. You can do this by initializing a status worker and defining a status URI. In the workers2.properties file make the following additions.

In order to check the status page go to, ¡®http://localhost/status/¡¯.

JK2 connector using JNI and TCP Sockets

The JK2 connector has the ability to use JNI to facilitate communications between Apache and Tomcat. This kind of configuration is more complicated and prevents changes being made to the Servlet container without first shutting down Apache. Also a TCP socket must be opened just like the previous method. The advantage is that there are performance improvements because it uses the JNI and Tomcat is started by Apache when needed. This makes for better performance when we are talking about a production environment not a development one.

Please note the following convention that is used in this section. Substitute the appropriate string for your configuration. Note that those that I meant for substitution are in bold font.

$APACHE_HOME – This is the full path to where Apache is installed. In our testing it was ¡®c:/Apache2¡¯.
$TOMCAT_HOME –This is the full path to where Tomcat is installed. In our testing it was ¡®d:/Tomcat4.1¡¯.
$CATALINA_HOME –This is the same as $TOMCAT_HOME.

For example if I write, ¡®$APACHE_HOME/conf/httpd.conf¡¯. Please substitute it with ¡®c:/Apache2/conf/httpd.conf¡¯.

Step one–Preliminary testing

First install and configure both Apache and Tomcat, as discussed in another document. The following conventions are used.

Before beginning, ensure that both Apache and Tomcat are running and configured properly. Test the examples from Tomcat and try to browse the on-line documents in Apache. If you can run both concurrently you are ready to connect the two. I do not discuss here how to perform the test as it depends on your configuration and thus outside the scope of this document. You should refer to your document on configuring Apache and configuring Tomcat for this.

Step two–Getting the connector

The second thing to do is to download the mod_jk2 connector DSO. In Windows this will be a dll. The connector will most likely come as a file called, ¡®mod_jk2-2.0.24.dll¡¯. Rename it to ¡®mod_jk2.dll¡¯. This makes it easier to deal with. Save the file in the modules directory. This should be, ¡®$APACHE_HOME/modules¡¯.

Step three—Editing the configuration files

Configuring the JNI version of the JK2 connector is almost identical to the TCP socket version. There are four files that must be edited for the connector. They are; the httpd.conf file, the jk2.properties file, the server.xml file, and the workers2.properties.

The ¡®httpd.conf¡¯ file

The httpd.conf file should be at ¡®$APACHE_HOME/conf/httpd.conf¡¯. This file contains the main configuration data for Apache. We will use this file to tell Apache to load the mod_jk2 DSO module. Locate the portion of the where other modules are being loaded. To be safe we enclose it inside of an ¡®if¡¯ statement. That way if we accidentally try to load the module twice we won¡¯t get into trouble.

For more information about the httpd.conf file refer to the documentation included in the Apache distribution or the book available in our library.

The ¡®jk2.properties¡¯ file

The jk2.properties file should be in the directory ¡®$TOMCAT_HOME/conf¡¯. This file contains all of the JK2 configuration information. Here we will set up the shared memory directive. This directive is necessary for Apache and Tomcat to communicate. A good place to have the file is the ¡®$APACHE_HOME/logs¡¯ directory. The file can be named anything but the convention is ¡®jk2.shm¡¯. A list of handlers must also be declared in this file. Finally the arp handler should be declared inprocess so that Apache can start it directly.

This default is fine and no other directives need to go in this file.

Unfortunately there is sparse documentation for the jk2.properties. Documentation for this file is available in the tomcat-connectors section of the Apache Software Group¡¯s Jakarta website. This documentation is incomplete and contains many mistakes. A more through set of documents is included in the source distribution of the JK2 connector; however it is also incomplete and contains many errors. I have found few on-line resources for this and most books covering this are totally incorrect.

The ¡®server.xml¡¯ file

The server.xml file is located in the ¡®$TOMCAT_HOME/conf¡¯ directory. This file contains all of the configuration data for Tomcat. By default Tomcat runs as a Standalone server and it also opens a JK2 connector over TCP sockets. We will disable the Standalone service and just use the JK2 connector.

The default port for the JK2 connector is 8009. This is an uncommon port number so we should just keep it. Remember the port number for the workers2.properties file.

There is a lot of on-line help for configuring the server.xml file. There is some help in the Tomcat configuration document also. The best is to get a book on Tomcat, it will most definitely have loads of information on this, but probably not too much on the JK2 connector.

The ¡®workers2.properties¡¯ file

This file is the workhorse of the JK2 connector. In order for the JK2 connector to work it must be created in the ¡®$APACHE_HOME/conf¡¯ directory. This file sets up the workers that will carry out the work of the servlet container. The simplest file needs only two directives for the JK2 connector. The first is the SHM file directive. This entry must match what went into the jk2.properties file. The second directive defines the worker. The worker definition using the JNI is a little bit more complicated as it requires us to define the startup and shutdown parameters as well as configuring the JVM. A problem occurred in accessing all of the Tomcat libraries so I had placed all of the JAR files included in the Tomcat distribution in ¡®$TOMCAT_HOME/lib¡¯. We also implement the config directive. I cannot find any reason why this is necessary, but the connector refused to run without it.

Like the jk2.properties file, the workers2.properties file does not have many supporting references. Most of the references on-line and in books are wrong or misleading. The documents posted on the tomcat-connectors portion of the Jakarta website contain many errors but may be a good place to begin looking.

Step four—Running and testing

Once the configuration is finished you can start the testing. The thing to do is to open two command prompts. In one command prompt go to, ¡®$TOMCAT_HOME/bin¡¯ and start Tomcat with the command, ¡®startup¡¯. A new window should open up with some start-up data. In the other command prompt go to, ¡®$APACHE_HOME/bin¡¯ and start the Apache web server with the command, ¡®apache –k start¡¯. If your configuration had no errors in it a few seconds later you will be returned to the prompt. Note that it is important to start Tomcat before Apache, otherwise the connectors cannot initialize. You can now check that the connector is running by trying to go to the examples web-app. In the default Tomcat configuration this should be at, ¡®http://localhost/examples/¡¯. If a Tomcat directory listing is shown then you have successfully configured the Apache-Tomcat connector. If you get a 500 series error then obviously a configuration error has occurred.

Troubleshooting is beyond the scope of this document but in case of an error; check that all the paths are correct. Also note that it is best to have installed Apache and Tomcat in directories without spaces. Additionally it is a good idea to create a status context where you can check the status of the connector. You can do this by initializing a status worker and defining a status URI. In the workers2.properties file make the following additions.

In order to check the status page go to, ¡®http://localhost/status/¡¯.