Domino HowTo

print-friendly version

Introduction

Important Note: The JK based connector described here has been superceded by a JK2 based connector that works with all current Tomcat versions. Use of this connector has been deprecated. Go here to find out how to install the new connector.

This document explains how to set up Domino to cooperate with Tomcat.

It is recommended that you also read the Workers HowTo document to learn how to setup the working entities between your WebServer and Tomcat Engines.

Recent versions of the Lotus Domino web server have had the ability to host Java servlets, but at the time of writing the Domino servlet container uses JDK 1.2.2 and it is not (apparently) possible to replace this with JDK 1.3.

That means if you want to use JAAS or any other API that is JDK 1.3 only in your servlets you're stuck.

Document Conventions and Assumptions

${tomcat_home} is the root directory of tomcat. Your Tomcat installation should have the following subdirectories:

• ${tomcat_home}\conf - Where you can place various configuration files
• ${tomcat_home}\webapps - Containing example applications
• ${tomcat_home}\bin - Where you place web server plugins

In all the examples in this document ${tomcat_home} will be c:\jakarta-tomcat . A worker is defined to be a tomcat process that accepts work from the Domino server.

Supported Configuration

The Domino Tomcat redirector was developed and tested on:

• WinNT4.0-i386 SP6a (it should be able to work on other versions of the NT service pack.) and Win2K Professional
• RedHat Linux 7
• Lotus Domino 5.0.6a
• Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x and Tomcat 5

The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. It probably also works with Tomcat in process, but that hasn't been tested.

Who support ajp protocols ?

The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x.

The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead ajp13 which is the only ajp protocol known by Tomcat 4.0.x, 4.1.x and 5.

Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol.

Others servlet engines such as jetty have support for ajp13 protocol

Installation on Windows

The Tomcat redirector requires 3 entities:

• tomcat_redirect.dll - The Domino plugin; either obtain a pre-built DLL or build it yourself (see the build section).
• workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers.properties can be found under the conf directory.
• tomcat_redirector.reg - Registry entries

We'll assume that tomcat redirector is placed in c:\jk\lib\tomcat_redirector.dll , the properties file is in c:\jk\conf and you created a log directory c:\jk\logs

Copy the file tomcat_redirector.dll to 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 tomcat_redirector.reg , which initially will look like this :

Edit this file to reflect the location where Tomcat has been installed, i.e. replace the instances of c:\\jakarta-tomcat and c:\\jk with the appropriate path remembering to retain the double backslashes .

Once you've made the necessary changes save this file and double click on it to enter it into the registry.

Note that the files referred to by the worker_file and worker_mount_file keys need to exist and contain sane values. Default Tomcat installations will have these files. Note also that recent versions of Tomcat write a file called uriworkermap.properties-auto when they start up that can be renamed uriworkermap.properties to obtain default behaviour.

Note for Windows 2000 users

For some reason Windows 2000 seems to have a problem resolving the references to localhost in the default workers.properties.

The easiest solution is to replace 'localhost' with '127.0.0.1' everywhere it appears.

Automatically Starting Tomcat

The last two 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).

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 DSAPIsection and the 'DSAPI filter file names' field on the Internet Protocols tab, HTTP sub-tab. Add "tomcat_redirector.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 may be available, depending on how Tomcat is configured :

If that all works you're done ;-)

Installation on Linux

The Tomcat redirector requires 3 entities:

• libtomcat.so - The Domino plugin; either obtain a pre-built shared lib or build it yourself (see the build section).
• workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). A sample workers.properties can be found under the conf directory.
• libtomcat.ini - configuration entries

Copy the file libtomcat.so to the Domino program directory which may be called something like /opt/lotus/notes/5601/linux , it should contains a file called libnotes.so and copy libtomcat.ini to the Domino data directory.

Note that if you're building the redirector from source these files should already have been copied to the appropriate locations.

Before using the redirector you may like to review the settings in libtomcat.ini which, by default, will look something like this:

If you're building the redirector from the source you may not need to make any changes, otherwise you may have to edit this file to reflect the location where Tomcat has been installed, i.e. replace the instances of /usr/local/apache/tomcat with the appropriate path.

Note that the files referred to by the worker_file and worker_mount_file keys need to exist and contain sane values.

Default Tomcat installations will have these files. Note also that recent versions of Tomcat write a file called uriworkermap.properties-auto when they start up that can be renamed uriworkermap.properties to obtain default behaviour.

Automatically Starting Tomcat

The last two registry entries above provide commands that the redirector 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 deleted.

Configuring Domino

Finally we need to configure Domino to use the DSAPI extension.

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 DSAPIsection and the 'DSAPI filter file names' field on the Internet Protocols tab, HTTP sub-tab.

Add "libtomcat.so" 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 HTTP server.

At the Domino console type

You should see the HTTP server reload along with messages that will confirm that the redirector has loaded and that Tomcat has (if you used Tomcat autostart) started.

You should now be able to visit a URL that is handled by Tomcat. Something like

Building for Windows

To compile it you'll need the JK Domino sources and Microsoft Visual C++ 6.0.

You will probably also want the Lotus Notes C API version 5.0.7 or later. You can build the DLL without the C API, in which case you'll need to define the macro NO_CAPI in config.h. If you do this Domino logging from the DLL will be disabled.

• Change directory to the domino plugin source directory.
• Edit dsapi.dsp and update the include and library path to reflect your own Domino server installation (search for a /I compiler option and /libpath linker option)
• Make the source with MSDEV

Building for Linux

You will probably also want the Lotus Notes C API version 5.0.3 for Unix or later.

You can build the redirector without the C API, in which case you'll need to define the macro NO_CAPI in config.h. If you do this, Domino logging from the redirector will be disabled.

• Change directory to the Domino plugin source directory.
• Edit Makefile and update the include and library path to reflect your own Domino server installation

• Now you should build via make