hgomez 2002/09/05 05:51:26
Added: jk/xdocs/jk domhowto.xml
Log:
Domino/JK initial documentation
Revision Changes Path
1.1 jakarta-tomcat-connectors/jk/xdocs/jk/domhowto.xml
Index: domhowto.xml
===================================================================
<?xml version="1.0" encoding="ISO-8859-1" ?>
<document>
<properties>
<title>Domino HowTo</title>
<author email="[EMAIL PROTECTED]">Andy Armstrong</author>
<author email="[EMAIL PROTECTED]">Henri Gomez</author>
</properties>
<section name="Introduction">
<p>
This document explains how to set up Domino to cooperate with Tomcat.
</p>
<p>
Recent version 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.
</p>
<p>
That means if you want to use JAAS or any other API
that is JDK 1.3 only in your servlets you're stuck.
</p>
<subsection name="Document Conventions and Assumptions">
<p>
${tomcat_home} is the root directory of tomcat.
Your Tomcat installation should have the following subdirectories:
<ul>
<li>
${tomcat_home}\conf - Where you can place various configuration files
</li>
<li>
${tomcat_home}\webapps - Containing example applications
</li>
<li>
${tomcat_home}\bin - Where you place web server plugins
</li>
</ul>
</p>
<p>
In all the examples in this document ${tomcat_home} will be <b>c:\jakarta-tomcat</b>.
A worker is defined to be a tomcat process that accepts work from the IIS server.
</p>
</subsection>
<subsection name="Supported Configuration">
<p>
The Domino Tomcat redirector was developed and tested on:
<ul>
<li>
WinNT4.0-i386 SP6a (it should be able to work on other versions of the NT service
pack.) and Win2K Professional
</li>
<li>
RedHat Linux 7
</li>
<li>
Lotus Domino 5.0.6a
</li>
<li>
Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x and Tomcat 5
</li>
</ul>
</p>
<p>
The redirector uses <b>ajp12</b> and <b>ajp13</b> to send requests to the Tomcat
containers.
It probably also works with Tomcat in process, but that hasn't been tested.
</p>
</subsection>
<subsection name="Who support ajp protocols ?">
<p>
The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x.
</p>
<p>
The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use
instead
<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.0.x, 4.1.x and 5.
</p>
<p>
Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol.
</p>
<p>
Others servlet engines such as <b>jetty</b> have support for ajp13 protocol
</p>
</subsection>
</section>
<section name="Installation on Windows">
<p>
The Tomcat redirector requires 3 entities:
</p>
<ul>
<li>
tomcat_redirect.dll - The Domino plugin, either obtain a pre-built DLL or build it
yourself
(see the build section).
</li>
<li>
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.
</li>
<li>
tomcat_redirector.reg - Registry entries
</li>
</ul>
<p>
We'll assume that tomcat redirector is placed in
<b>c:\jk\lib\tomcat_redirector.dll</b>,
the properties file is in<b>c:\jk\conf</b>
and you created a log directory <b>c:\jk\logs</b>
</p>
<p>
Copy the file <b>tomcat_redirector.dll</b> to the Domino program directory
(this is the directory, which may be called something like <b>c:\Lotus\Domino</b>,
that contains a file called
<b>nlnotes.exe</b>).
</p>
<screendos>
<notedos>Copy redirector dll to Domino program directory</notedos>
<typedos>copy c:\jk\lib\tomcat_redirector.dll c:\Lotus\Domino</typedos>
</screendos>
<p>
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 <b>tomcat_redirector.reg</b>, which
initially will look like this :
</p>
<screen>
<read>REGEDIT4</read>
<read/>
<read>[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Dsapi
Redirector\1.0]</read>
<read>"log_file"="c:\\jk\\logs\\domino.log"</read>
<read>"log_level"="debug"</read>
<read>"worker_file"="c:\\jk\\conf\\workers.properties"</read>
<read>"worker_mount_file"="c:\\jk\\conf\\uriworkermap.properties"</read>
<read>"tomcat_start"="c:\\jakarta-tomcat\\bin\\tomcat.bat start"</read>
<read>"tomcat_stop"="c:\\jakarta-tomcat\\bin\\tomcat.bat stop"</read>
</screen>
<p>
Edit this file to reflect the location where Tomcat has been installed, i.e. replace
the instances
of <b>c:\\jakarta-tomcat</b> and <b>c:\\jk</b> with the appropriate path remembering
to <b>retain the double backslashes</b>.
</p>
<p>
Once you've made the necessary changes save this file and double click on it to
enter it into the registry.
</p>
<p>
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.
</p>
<subsection name="Note for Windows 2000 users">
<p>
For some reason Windows 2000 seems to have a problem resolving the references to
localhost
in the default workers.properties.
</p>
<p>
The easiest solution is to replace 'localhost' with '127.0.0.1' everywhere it
appears.
</p>
</subsection>
<subsection name="Automatically Starting Tomcat">
<p>
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.
</p>
<p>
If you don't require this behaviour these two lines can be omitted
(or deleted if you've already placed them in the registry).
</p>
</subsection>
<subsection name="Configuring Domino">
<p>
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
<b>"Public Name and Address Book"</b> or <b>"NAB"</b> for short
</p>
<p>
(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.
</p>
<p>
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.
</p>
<p>
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.
</p>
</subsection>
<subsection name="Restart Domino">
<p>
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.
</p>
<p>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.
</p>
<p>
If all goes well you should see something like this on the server console when the
web server starts up :
</p>
<screen>
<read>29/05/2001 18:54:13 JVM: Java Virtual Machine initialized.</read>
<read>29/05/2001 18:54:14 Attempting to start Tomcat:
c:\jakarta-tomcat\bin\tomcat.bat start</read>
<read>Including all jars in c:\jakarta-tomcat\lib in your CLASSPATH.</read>
<read/>
<read>Using CLASSPATH:
c:\jakarta-tomcat\classes;c:\jakarta-tomcat\lib\ant.jar;c:\jakarta-tomcat\lib\servlet.jar</read>
<read/>
<read>Starting Tomcat in new window</read>
<read>29/05/2001 18:54:15 Apache Tomcat Interceptor (Jakarta/DSAPI/1.0)
loaded</read>
<read>29/05/2001 18:54:16 HTTP Web Server started</read>
</screen>
<p>
At about the same time Tomcat should open in a new window (assuming you enabled the
autostart option in the registry settings).
</p>
<p>
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 :
</p>
<source>
http://name of server/servlet/SnoopServlet
</source>
<p>
If that all works you're done ;-)
</p>
</subsection>
</section>
<section name="Installation on Linux">
<p>
The Tomcat redirector requires 3 entities:
</p>
<ul>
<li>
libtomcat.so - The Domino plugin, either obtain a pre-built shared lib or build it
yourself
(see the build section).
</li>
<li>
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.
</li>
<li>
libtomcat.ini - configuration entries
</li>
</ul>
<p>
Copy the file <b>libtomcat.so</b> to the Domino program directory which may be
called
something like <b>/opt/lotus/notes/5601/linux</b>, it should contains a file called
<b>libnotes.so</b>
and copy <b>libtomcat.ini</b> to the Domino data directory.
</p>
<screen>
<note>Copy redirector shared lib to Domino program directory</note>
<type>cp c:\jk\lib\libtomcat.so /opt/lotus/notes/5601/linux</type>
<note>Copy config to Domino data directory</note>
<type>cp c:\jk\conf\libtomcat.ini /opt/datalotus</type>
</screen>
<p>
Note that if you're building the redirector from source these files should already
have been copied to the appropriate locations.
</p>
<p>
Before using the redirector you may like to review the settings in
<b>libtomcat.ini</b> which,
by default, will look something like this:
</p>
<screen>
<read>log_file=/var/log/domino.log</read>
<read>log_level=debug</read>
<read>worker_file=/var/tomcat3/conf/workers.properties</read>
<read>worker_mount_file=/var/tomcat3/conf/uriworkermap.properties</read>
<read>tomcat_start=/var/tomcat3/bin/tomcat.sh start</read>
<read>tomcat_stop=/var/tomcat3/bin/tomcat.sh stop</read>
</screen>
<p>
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.
</p>
<p>
Note that the files referred to by the <b>worker_file</b> and
<b>worker_mount_file</b> keys need to exist
and contain sane values.
</p>
<p>
Default Tomcat installations will have these files.
Note also that recent versions of Tomcat write a file called
<b>uriworkermap.properties-auto</b>
when they start up that can be renamed <b>uriworkermap.properties</b> to obtain
default behaviour.
</p>
<subsection name="Automatically Starting Tomcat">
<p>
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.
</p>
<p>
If you don't require this behaviour these two lines can be deleted.
</p>
</subsection>
<subsection name="Configuring Domino">
<p>
Finally we need to configure Domino to use the DSAPI extension.
</p>
<p>
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
<b>"Public Name and Address Book"</b> or <b>"NAB"</b> for short
</p>
<p>
N.B. Lotus have renamed the NAB to "Domino Directory" from Domino 5 onwards).
</p>
<p>
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.
</p>
<p>
Assuming you know your way around a Domino server document what we're going to do is
actually quite simple.
</p>
<p>
Open the server document for this server, place it in Edit mode, then locate the
<b>DSAPIsection</b> and the <b>'DSAPI filter file names'</b> field on the Internet
Protocols tab,
HTTP sub-tab.
</p>
<p>
Add <b>"libtomcat.so"</b> to the DSAPI field, then save and close the document.
</p>
</subsection>
<subsection name="Restart Domino">
<p>
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.
</p>
<p>
At the Domino console type
</p>
<screen>
<type>tell http quit</type>
<type>load http</type>
</screen>
<p>
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.
</p>
<p>
You should now be able to visit a URL that is handled by Tomcat. Something like
</p>
<source>
http://name of server/servlet/SnoopServlet
</source>
may be available, depending on how Tomcat is configured.
</subsection>
</section>
<section name="Building for Windows">
<p>
To compile it you'll need the jk domino source and Microsoft Visual C++ 6.0.
</p>
<p>
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.
</p>
<ul>
<li>
Change directory to the domino plugin source directory.
</li>
<li>
Edit <b>dsapi.dsp</b> and update the include and library path to reflect your own
Domino server installation
(search for a <b>/I compiler</b> option and <b>/libpath</b> linker option)
</li>
<li>
Make the source with MSDEV
</li>
</ul>
<screendos>
<notedos>Change directory to the dsapi plugins source directory</notedos>
<typedos>cd c:\home\apache\jk\domino</typedos>
<notedos>Build the sources using MSDEV</notedos>
<typedos>MSDEV dsapi.dsp /MAKE ALL</typedos>
</screendos>
</section>
<section name="Building for Linux">
<p>
You will probably also want the Lotus Notes C API version 5.0.3 for Unix or later.
</p>
<p>
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.
</p>
<ul>
<li>
Change directory to the domino plugin source directory.
</li>
<li>
Edit <b>Makefile</b> and update the include and library path to reflect your own
Domino server installation
</li>
</ul>
<screen>
<note>edit the Makefile providing appropriate values for these variables</note>
<read># The root of your Domino installation. Mine's in /usr/local/lotus, but
your's</read>
<read># may well be /opt/lotus</read>
<read>NOTESROOT=/usr/local/lotus</read>
<read/>
<read># The place where the Notes API is installed</read>
<read>NOTESAPI=$(NOTESROOT)/notesapi</read>
<read/>
<read># The Domino program directory.</read>
<read>NOTESHOME=$(NOTESROOT)/notes/5061/linux</read>
<read/>
<read># The Domino data directory (the directory containing names.nsf)</read>
<read>NOTESDATA=$(NOTESROOT)/notes/data</read>
<read/>
<read># The include path for the Notes C API headers</read>
<read>NOTESINC=$(NOTESAPI)/include</read>
<read/>
<read># Where tomcat is installed. This is where conf, lib, webapps et al normally
are</read>
<read>TOMCATHOME=/var/tomcat3</read>
<read/>
<read># Your JDK's include directory</read>
<read>JAVAINC=$(JAVA_HOME)/include</read>
</screen>
<ul>
<li>
Now you should build via make
</li>
</ul>
<screen>
<note>Launch build via make</note>
<type>make</type>
<note>place the redirector (libtomcat.so) and its settings file (libtomcat.ini) in
the appropriate places</note>
<type>make install</type>
</screen>
</section>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
