How To for Apache2, Tomcat4.1.x, mod_jk2, JSDK1.4 on Win2k

Quick and Dirty, no thinking version here for those who just want to blast it in.

Note: In an effort to reduce convoluted path names in windows try to choose install directories with short names. Also try not to use spaces in the names, Apache and Tomcat and as far as I know all XML files have problems with it and require you to double quote any path name that includes spaces. Save yourself some headaches and just don’t do it.

Note: Careful planning of installation paths can be a good thing. For instance, combining the DocumentRoot of Apache and the webapp directory of Tomcat can lead to automatic application configuration by Tomcat 4.1.10. I haven’t tried it so it’s just a theory mind you, but it sounds good.

Install J2sdk1.4.x

J2sdk

(Make sure you get the windows version, of the latest available, but it should work with any 1.4 version)

No need to install src or demos. You will need to check the “JRE for windows drive only” option unless you want to edit the registry and point the key to the jvm.dll in the JDSK. It’s easier to go ahead and take the default though. No matter where you choose to install the JSDK sun’s install still puts the JRE in the “Program Files” directory. I chose an install path of c:\java. So try to keep it simple.

Set system environment variables for Java home.

JAVA_HOME=C:\java

Add JAVA_HOME and JAVA_HOME\bin directory to the system PATH variable in my case it is

C:\java;C:\java\bin

Install Apache 2.0.43

Apache2

Get the latest available. Download the correct program for your system. The one ending in .exe is for people who do not have the msi installer yet, most do, so the smaller .msi package should work for most people. Make a nice short path without any blank spaces for the installation. Mine is C:\Apache2

During installation set domain and ServerName to Your Server Name or just localhost if you’re just testing. It will only be accessible from the local machine.

Install Tomcat 4.1.x

Tomcat

Get the latest release version. At the time of this writing it was 4.1.12. You must get the LE version of Tomcat. JDK 1.4.x has an XML parser installed so the LE version of Tomcat was made for this reason. During installation you don’t have to select the check box for NT service. Again make sure to choose a nice short install path without any blanks in the names. Mine is C:\Tomcat

Set system environment variables for Tomcat home. It might also be a good idea to add a Catalina home too.

TOMCAT_HOME= C:\Tomcat

CATALINA_HOME=C:\Tomcat

Install and configure mod_jk2.dll

mod_jk2.dll

Get the latest version of mod_jk2.dll and save it to the APACHE_HOME/modules directory. The new modules are version named to ID them to different Apache versions. You can rename them to mod_jk2.dll or change the LoadModule statement to match the version you are installing. In either case the module name and the LoadModule statement have to match. I just renamed the module to be mod_jk2.dll.

In your httpd.conf file add this LoadModule statement to the beginning of the LoadModule section.

LoadModule jk2_module modules/mod_jk2.dll

In your APACHE_HOME/logs directory you will need to create three empty files.

stdout.log

stderr.log

jk2.shm

Add workers2.properties

Cut and paste the following workers2.properties file into the APACHE_HOME/conf directory. There’s lots of extra stuff to experiment with here later. (Edit paths to suit)

[logger]

level=DEBUG

[config:]

#file=${serverRoot}/conf/workers2.properties

file=c:/Apache2/conf/workers2.properties

debug=0

debugEnv=0

[uriMap:]

info=Maps the requests. Options: debug

debug=0

# Alternate file logger

#[logger.file:0]

#level=DEBUG

#file=${serverRoot}/logs/jk2.log

[shm:]

info=Scoreboard. Required for reconfiguration and status with multiprocess servers

file=${serverRoot}/logs/jk2.shm

size=1000000

debug=0

disabled=0

[workerEnv:]

info=Global server options

timing=1

debug=0

# Default Native Logger (apache2 or win32 )

# can be overriden to a file logger, useful

# when tracing win32 related issues

#logger=logger.file:0

[lb:lb]

info=Default load balancer.

debug=0

#[lb:lb_1]

#info=A second load balancer.

#debug=0

[channel.socket:localhost:8009]

info=Ajp13 forwarding over socket

debug=0

tomcatId=localhost:8009

#[channel.socket:localhost:8019]

#info=A second tomcat instance.

#debug=0

#tomcatId=localhost:8019

#lb_factor=1

#group=lb

#group=lb_1

#disabled=0

#[channel.un:/opt/33/work/jk2.socket]

#info=A second channel connecting to localhost:8019 via unix socket

#tomcatId=localhost:8019

#lb_factor=1

#debug=0

[channel.jni:jni]

info=The jni channel, used if tomcat is started inprocess

[status:]

info=Status worker, displays runtime informations

[vm:]

info=Parameters used to load a JVM in the server process

#JVM=C:\jdk\jre\bin\hotspot\jvm.dll

OPT=-Djava.class.path=c:/Tomcat/bin/tomcat-jni.jar;c:/Tomcat/server/lib/commons-logging.jar

OPT=-Dtomcat.home=${TOMCAT_HOME}

OPT=-Dcatalina.home=${TOMCAT_HOME}

OPT=-Xmx128M

#OPT=-Djava.compiler=NONE

disabled=0

[worker.jni:onStartup]

info=Command to be executed by the VM on startup. This one will start tomcat.

class=org/apache/jk/apr/TomcatStarter

ARG=start

disabled=0

stdout=c:/Apache2/logs/stdout.log

stderr=c:/Apache2/logs/stderr.log

[worker.jni:onShutdown]

info=Command to be executed by the VM on shutdown. This one will stop tomcat.

class=org/apache/jk/apr/TomcatStarter

ARG=stop

disabled=0

[uri:/jkstatus/*]

info=Display status information and checks the config file for changes.

group=status:

#[uri:127.0.0.1:8003]

#info=Example virtual host. Make sure myVirtualHost is in /etc/hosts to test it

#alias=myVirtualHost:8003

#[uri:127.0.0.1:8003/ex]

#info=Example webapp in the virtual host. It'll go to lb_1 ( i.e. localhost:8019 )

#context=/ex

#group=lb_1

[uri:/examples]

info=Example webapp in the default context.

context=/examples

debug=0

#[uri:/examples1/*]

#info=A second webapp, this time going to the second tomcat only.

#group=lb_1

#debug=0

[uri:/examples/servlets/*]

info=Prefix mapping

[uri:/examples/*.jsp]

info=Extension mapping

[uri:/examples/*]

info=Map the whole webapp

[uri:/examples/servlets/HelloW]

info=Exampel with debug enabled.

debug=10

Add jk2.properties

Cut and paste the following jk2.properties file into the TOMCAT_HOME\conf directory. (Edit paths to suit)

## THIS FILE MAY BE OVERRIDEN AT RUNTIME. MAKE SURE TOMCAT IS STOPED

## WHEN YOU EDIT THE FILE.

## COMMENTS WILL BE _LOST_

## DOCUMENTATION OF THE FORMAT IN JkMain javadoc.

# Override the default port for the socketChannel

# channelSocket.port=8019

# Default:

# channelUnix.file=${jkHome}/work/jk2.socket

# Just to check if the the config is working

shm.file=c:/Apache2/logs/jk2.shm

# In order to enable jni use any channelJni directive

channelJni.disabled = 0

# And one of the following directives:

# apr.jniModeSo=/opt/apache2/modules/mod_jk2.so

# If set to inprocess the mod_jk2 will Register natives itself

# This will enable the starting of the Tomcat from mod_jk2

apr.jniModeSo=inprocess

You must reboot to make all the variables active

Remember Tomcat does not run as a service in this version so you don’t have to start it. It will start when called by Apache and run in process with it. You should set the Tomcat service to manual and not automatic.

Yippee now we get to test it all, keep your fingers crossed. Click on http://localhost/examples. If you have been very, very good and shared your candy with the other children then you should see the familiar tomcat example directory. If the examples worked then check out the extra cool jkstatus page athttp://localhost/jkstatus

`If not, well then, you don’t play well with others, so go back to the start, erase everything and start over. LOL.J`

Quick and Dirty

Install the software, get the latest of each

1. Take all the defaults during installation, except for the install paths. Choose custom install and change the Apache install directory to C:\ this will in fact install it to c:\Apache2, and Tomcat to c:\Tomcat, java to c:\Java.

2. Stop Apache and place mod_jk2.dll in the APACHE_HOME/modules directory.

3. Edit httpd.conf, add LoadModule jk2_module modules/mod_jk2.dll to the end of the LoadModules section.

4. Add system environment variables and modify system PATH.

CATALINA_HOME=c:\Tomcat

JAVA_HOME=c:\Java

TOMCAT_HOME=c:\Tomcat

Add to system PATH c:\Java;c:\Java\bin

5. Add a jk2.properties file to TOMCAT_HOME\conf and edit paths. File is here, use with no changes.

6. Add a workers2.properties file to APACHE2_HOME\conf and edit paths. File is here, do not change.

7. Create three empty files in the APACHE2_HOME\logs directory

stdout.log

stderr.log

jk2.shm

8. Reboot system.

9. Give it a whirl http://localhost/examples

If You Have Trouble

If Apache fails to start, and it was fine before you started this, then there is probably something wrong with the LoadModule line you added to the httpd.conf. Open a cmd window in the bin directory of Apache and type in “apache –t” without the quotes. This will check the syntax of the httpd.conf file. If the LoadModule syntax is correct you may have the wrong mod_jk2.dll installed. It should throw an error complaining about incorrect versions in the cmd window.

Review the Apache error log to see problems with the in-process startup of Tomcat. If it complains about not finding the jvm.dll and can’t finish the vm setup or says there’s no installed jvm.dll in the path then check to make sure the JRE got installed correctly. Tomcat reads the registry to find the location of the jvm.dll. For example since I took the defaults during the installation of J2SDK my registry shows the installed JRE at;

[HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment\1.4.0_01]

"JavaHome"="C:\Program Files\Java\j2re1.4.0_02"

"MicroVersion"="0"

"RuntimeLib"="C:\Program Files\Java\j2re1.4.0_02\bin\client\jvm.dll"

Navigate to the indicated RuntimeLib directory and see if it’s actually there. If everything thing looks fine and it still throws errors then you can point mod_jk2 to it with a path statement in the [vm] section of the worker2.properties file, but normally this is not needed.

Mod_jk2 can tell you allot about your installation and configuration. You can see what it thinks at http://locahost/jkstatus.

Check the stdout and stderr logs for more clues, pay attention to the [error] lines, [warning] are ok.

Other problems I’ve seen is jk2 complaining that it can’t find the class path for Tomcat starter, this turned out to be a mangled mod_jk2.dll and was fixed by simply replacing the file.

If you get errors about AJP13 forwarding then check your jk2.properties file for a “channelJni.disable=0” statement. Jni has to have a channel statement to run. Any channelJni statement will do, the previous one simply says it is not disabled.

Did you remember to reboot? More than once I have forgotten this simple step, and without it Tomcat will not be able to find the jvm.dll or any of the other java stuff.

Double-check your environment variables for the correct paths. Make sure you have a tomcat-jni.jar in the TOMCAT_HOME/bin directory. Make sure the paths are correct in the jk2.properties and the workers2.properties file. The path for the jk2.shm should be correct, especially important if you have multiple processors.

BTW, if you use this “How to” and improve on it, how’s about sharing it back with me. rsowders@usgs.gov

I put this together after lurking on Tomcat-users and picking up some pointers from Malden Turk, Andy Eastham, and lots of others.

Robert Sowders

Senior Unix Administrator

Western Geographic Science Center

rsowders@usgs.gov