Running Tomcat in Apache in Mandrake 9.0

The guidelines on this page refer specifically to running Tomcat-4.1.12 (which I downloaded) in Apache 1.3.26 as found in Mandrake 9.0. However, they should apply to any Apache 1.3.x and Tomcat-4.1.x. I've followed these guidelines on the Apache contained in Mandrake 8.2 and it worked fine.

What Happens?

What happens is that when a request is received by the Apache web server, under certain circumstances (certain requests) these requests are relayed to be served by Tomcat. The requests passed to Tomcat as configured in the following examples are those for *.jsp and /*/servlet/*. Static files, such as *.html, *.txt and any image files are served by Apache. More on this later.

How do I get this to happen?

Tomcat 4.1.12 (and others) comes with the ability to communicate with Apache, but this ability is disabled in the binary version downloadable from Jakarta. Enabling it is straightforward. Go to your server.xml file which is in $TOMCAT_HOME/conf. Note that Tomcat uses $CATALINA_HOME in version 4.1.12 (and maybe in all of version 4.1.x) instead of $TOMCAT_HOME. If you downloaded the RPM version of Tomcat your server.xml may be in /etc/tomcatx, x being a digit, most likely 4.

Search for

Define an AJP 1.3 Connector on port 8009

and uncomment the following below it:

<Connector className="org.apache.ajp.tomcat4.Ajp13Connector"
               port="8009" minProcessors="5" maxProcessors="175"
               acceptCount="10" debug="1"/>

As you can see, this points to a class file. This class file is in tomcat-jk.jar in $TOMCAT_HOME/server/lib, and it handles communication with Apache. This connector will listen on port 8009.

Theoretically, Tomcat can now communicate with Apache. You are now done with Tomcat.

To give Apache the ability to communicate with Tomcat do the following:
Go here and download mod_jk-1.3-eapi.so (if you want to use SSL) or mod_jk-1.3-noeapi.so (if you are not interested in SSL). You can also download versions 1.2.0 or 1.2.2. I downloaded v1.2.1 and know that it works.

Move whichever file you downloaded to /usr/lib/apache and rename it to "mod_jk.so". Apache now has the latent ability to communicate with Tomcat.

Now to awake all this latent potential. On starting up Apache must load mod_jk.so. On receiving requests that should go to Tomcat mod_jk.so should do what it has to do and communicate with Tomcat.

To do this Apache, and through Apache mod_jk.so, should know where to find any needed resources and the port numbers that should be used for communication. Note that for this example we assume that both Apache and Tomcat are running on localhost.

Apache and Tomcat use a "worker" object (no doubt instantiated by the class Ajp13Connector with the help of mod_jk.so) that will take care of the communication. This worker object should be instantiated with the knowledge of resources needed (ports, directories/folders where to find what it needs). This knowledge is contained in a workers.properties file and the httpd.conf file used by Apache.

Let's do workers.properties first. This is what mine looks like:

worker.list=defaultWorker
worker.defaultWorker.port=8009
worker.defaultWorker.host=localhost
worker.defaultWorker.type=ajp13

workers.java_home=/usr/java/j2sdk1.4.0
workers.catalina_home=/usr/local/tomcat-4.1.12

Note that I called my worker "defaultWorker". You can call your worker anything you like. Note also that workers.properties can contain any number of workers (comma separated), any of which may be invoked under certain circumstances. This file contains only one worker, which is all you need for now. If your workers.properties contains many workers you of course have to specify the port, host and type of worker for each one declared. The syntax is worker.workerName.parameter=value. Refer to the example above for a concrete example.

Note that the port to use is the same one mentioned in defining an AJP connector in server.xml as explained earlier.

In reality you can save this file anywhere on your disk. The logical places are the $TOMCAT_HOME/conf (which may be /etc/tomcat4) or /etc/httpd/conf/ directories, depending on whether you think workers.properties has a closer relationship to Tomcat than Apache, or vice versa.

On loading mod_jk.so Apache must now be able to tell it about the workers.properties file which will tell it about the port and host settings Tomcat is listening on. A worker with all this knowledge is then instantiated and does the communication. This is how you get this all to happen:
Open /etc/httpd/httpd.conf in a text editor. At the end of the file add the following:

LoadModule jk_module	modules/mod_jk.so
AddModule mod_jk.c
JkWorkersFile /etc/httpd/conf/workers.properties 
JkLogFile /usr/local/tomcat-4.1.12/logs/jk_log.txt
JkLogLevel error
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
           
JkAutoAlias /usr/local/tomcat-4.1.12/webapps
JkMount /*/servlet/ defaultWorker
JkMount /*.jsp defaultWorker

<Location /*/WEB-INF/>
AllowOverride None 
deny from all 
</Location>

The first line should hold no surprises for you. It tells Apache to load mod_jk.so, which you personally installed in /usr/lib/apache.

The second line may surprise you. It did surprise me. I have no mod_jk.c anywhere on my system. This line is required and everything works. There must be an explanation somewhere, I don't have it. Just put the line there and forget about it.

Change the logfile line to point to wherever you want the log written to.

The two JkMount lines tell Apache to invoke a worker, defaultWorker in this case, whenever a request for a *.jsp is received or the second part of a request is "servlet" with whatever as the last part.

The line just above these two lines, the JkAutoAlias line, tells these invoked workers to append whatever the request was for at the end of /usr/local/tomcat-4.1.12/webapps. It will of course be different on your system and you must change this line to reflect the /webapps location for things to work.

As an example, if you requested http://localhost/myDatabase/loginPage.jsp defaultWorker will look for this file at /usr/local/tomcat-4.1.12/webapps/myDatabase/loginPage.jsp, which is of course where it is. Of course, defaultWorker will hand the request over to the an object of class Ajp13Connector (or via static method calls, I don't know the innards of the class) which will hand it to Tomcat which will return the results back to Ajp13Connector which will return the results back to defaultWorker which will turn that over to Apache which will serve it to the requesting browser. Is your head spinning?

The last bit about the location is to prevent people from prying around in any of the WEB-INF directories in Tomcat. It seems to work.

The static pages

You will have to make a directory under /var/www/html to mirror the directory your files are in in Tomcat. As an example if your files are in $TOMCAT_HOME/webapps/myDatabase you must create a /var/www/html/myDatabase. The static *.html pages can go directly here as well as any other static content, like images. I have my images under a subdirectory called, very unoriginally, images.

You will find that you have no permission for Apache to access this static content the way your /etc/httpd/commonhttp.conf file is set up under Mandrake. Open this file in a text editor and change lines 35 to 42, both inclusive, to look like this:

# Liberal set of options allowing all access to 
/var/www/html and its subdirectories
# Note that /var/www/html is specified in httpd.conf
<Directory />
  Options All Multiviews
  AllowOverride None
  Order deny,allow
  Allow from all
</Directory>

You will have to take away a few - signs. I may have been too liberal. Changing from the default as found in Mandrake is absolutely essential if you want to access static content directly from Apache.

You may think this double entering of files (both to Apache in /var/www/html and to Tomcat wherever you have it installed) is just too much, but if you use Ant to build with you can tweak the build.xml file to do it all in one go.

Now first restart Tomcat and then restart Apache. All should be well. If you enter http://localhost/index.jsp you should get the default Tomcat page that you get when doing http://localhost:8080/index.jsp, except the static content, some of the images, is not loaded. If you move those to /var/www/html they will be loaded, but why bother? Test one of your own web applications.

I have a small start and shutdown script for Tomcat in /etc/rc.d/init.d and the kill and start links in /etc/rc.d/rc5.d Everything works well.

I would appreciate any needed fine tuning tips. Please e-mail me. The link is below.

E-mail me