Installation of jk2 in the Web Server

print-friendly version

Installation

The actual build mechanism creates the dso files in the build/jk2/${servername} subdirectory of the jakarta-tomcat-connectors/jk. When configure --with-jni is used 2 dso files are created. These files have to be copied in the right location of the web server installation.

JNI support in JK2 require APR, which is provded in Apache 2.0, and is available for many platforms, so Apache 1.3, IIS and NES/iPlanet should be able to use it

Apache 1.3

In the following example Apache-1.3 is installed in /home/apache13/ and the commands are executed in the jakarta-tomcat-connectors directory.

Apache 1.3 require APR, and if APR has been built with pthread support and your Apache 1.3 wasn't (general case in Unix platforms) you should :

• Rebuild Apache 1.3 with pthread support (recommanded)
• Add the LoadFile /usr/lib/pthread.so in beginning of your httpd.conf

You should also ensure that the linker will be able to locate the apr shared libraries, libapr.so, and libaprutil.so, make sure they have been installed in linker search locations.

Apache 2

In the following example Apache-2.0 is installed in /home/apache20/apache40 and the commands are executed in the jakarta-tomcat-connectors directory.

IIS

A pre-built version of the ISAPI redirector server plugin, isapi_redirector2.dll, is available under the win32/i386 directory of jakarta-tomcat-connectors distribution. You can also build a copy locally from the source present in jakarta-tomcat-connectors distribution.
The Tomcat redirector requires three entities:

• isapi_redirector2.dll - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section).
• workers2.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers2.properties can be found under the conf directory.
• jk2.properties - A configuration file used by mod_jk2 on the Tomcat side.

1. In the registry, create a new registry key named "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\2.0"
2. Add a string value with the name serverRoot and a value which is a full path to your Tomcat installation (for example c:\jakarta-tomcat ). If Tomcat is installed on a different server, this entry must point to the location (directory) where the workers2.properties file resides.
3. Add a string value with the name extensionUri and a value of /jakarta/isapi_redirector2.dll
4. Add a string value with the name workersFile and a value which is the full path to your workers2.properties file (for example c:\jakarta-tomcat\conf\workers2.properties )
5. Add a string value with the name logLevel and a value for your log level (can be DEBUG, INFO or ERROR).
6. Using the IIS management console, add a new virtual directory to your IIS web site. The name of the virtual directory must be jakarta. Its physical path should be the directory where you placed isapi_redirector2.dll While creating this new virtual directory assign it with execute access.
7. Using the IIS management console, add isapi_redirector2.dll as a filter in your IIS web site. The name of the filter should reflect its task (I use the name jakarta), its executable must full path to the isapi_redirector2.dll.

Install using provided script install4iis.js
This script creates the virtual directory and installs ISAPI filter for Default webserver

You may modify the default installation using various command line options. To see what the options are type csrcipt install4iis.js -h

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.

Lotus Domino

If necessary build dsapi_redirector2.dll as per the instructions in the jk/native2/server/dsapi directory. Copy the DLL into the Domino program directory (this is the directory, which may be called something like C:\Lotus\Domino, that contains a file called nlnotes.exe). Shortly we will tell Domino where to find this file, but before we do that we need to make some registry entries. The simplest way is to edit the supplied file dsapi_redirector2.reg, which initially will look like this

Change serverRoot to reflect the location of your Tomcat installation. The other filename parameters can either be relative to serverRoot or absolute paths. Once edited double click on dsapi_redirector2.reg to enter it into the registry.

Starting Tomcat: The last three registry entries above provide commands that the redirector DLL will use to start and stop Tomcat when the Domino http server starts and stops respectively. If you don't require this behaviour these two lines can be omitted (or deleted if you've already placed them in the registry).

The Workers file: If necessary take the sample workers2.properties file from jakarta- tomcat- connectors\jk\conf and place it in the location specified in the registry settings above (typically the conf directory of your Tomcat installation). Edit the file to suit your Tomcat setup.

Configuring Domino: Finally we need to configure Domino to use the DSAPI extension DLL. For those who are unfamiliar with Domino server configuration most of a server's configurable behavior is dictated by a document called the "server document" in a database called the "Public Name and Address Book" or "NAB" for short (N.B. Lotus have renamed the NAB to "Domino Directory" from Domino 5 onwards). Each Domino server will have a NAB (called names.nsf) and each NAB will have a number of server documents including one for the current server. If you have not previously configured a Domino server you may need to refer to the supplied documentation, or you may need to pass this document to your tame Domino administrator.

Assuming you know your way around a Domino server document what we're going to do is actually quite simple. Open the server document for this server, place it in Edit mode, then locate the DSAPI section and the 'DSAPI filter file names' field on the Internet Protocols tab, HTTP sub- tab. Add "dsapi_redirector2.dll" to the DSAPI field, then save and close the document.

Restart Domino: In order to get these settings to take effect and make sure that you haven't disrupted anything else you should now restart the Domino server. If the server is running as a service and you have changed any relevant system variables (JAVA_HOME, TOMCAT_HOME, CLASSPATH) since the last time you restarted the computer you should do a complete restart now because updates to system variables are not seen by services until after a reboot. If all goes well you should see something like this on the server console when the web server starts up.

At about the same time Tomcat should open in a new window (assuming you enabled the autostart option in the registry settings). You should now be able to visit a URL that is handled by Tomcat. Something like

http://name-of-server/servlet/SnoopServlet

may be available, depending on how Tomcat is configured. If that all works you're done.

Mailing Lists: There are two mailing lists dedicated to the Domino Tomcat redirector:

domino-tomcat-l

domino-tomcat-l is a general discussion list for issues with the redirector and also wider Tomcat/Domino integration issues such as calling the Domino Java API from a Tomcat servlet. This list is fairly low volume so please subscribe if you're actively using the redirector. If you have an issue with the redirector please post it to the list where it will be seen not only by the author but by other users who may be able to help with any problems.

domino-tomcat-announce-l

domino-tomcat-announce-l is for announcements about the Domino Tomcat redirector. Mainly this list will be used for new releases but serious bugs will also be posted to it. This list will be very low volume; not more than a few posts per month. For this reason if you'd like to keep track of new redirector versions please subscribe to this list.