connectors/jk/xdocs/jk/domhowto.xml - tomcat55 - Git at Google

 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <document>
 <copyright>
    Copyright 1999-2004 The Apache Software Foundation

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
 </copyright>
 <properties>
 <title>Domino HowTo</title>
 <author email="andy@tagish.com">Andy Armstrong</author>
 <author email="hgomez@apache.org">Henri Gomez</author>
 <date>$Date$</date>
 </properties>

 <section name="Introduction">
 <p><b>Important Note:</b> 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
 <a href="jk2/installhowto.html">here</a> to find out how to install the new connector.</p>

 <p>
 This document explains how to set up Domino to cooperate with Tomcat.
 </p>

 <p>
 It is recommended that you also read the <a href="jk/workershowto.html">Workers HowTo</a> document
 to learn how to setup the working entities between your WebServer and Tomcat Engines.
 </p>

 <p>
 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.
 </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 Domino 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 sources 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>
	<?xml version="1.0" encoding="ISO-8859-1" ?>
	<document>
	<copyright>
	Copyright 1999-2004 The Apache Software Foundation

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	</copyright>
	<properties>
	<title>Domino HowTo</title>
	<author email="andy@tagish.com">Andy Armstrong</author>
	<author email="hgomez@apache.org">Henri Gomez</author>
	<date>$Date$</date>
	</properties>

	<section name="Introduction">
	<p><b>Important Note:</b> 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
	<a href="jk2/installhowto.html">here</a> to find out how to install the new connector.</p>

	<p>
	This document explains how to set up Domino to cooperate with Tomcat.
	</p>

	<p>
	It is recommended that you also read the <a href="jk/workershowto.html">Workers HowTo</a> document
	to learn how to setup the working entities between your WebServer and Tomcat Engines.
	</p>

	<p>
	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.
	</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 Domino 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 sources 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>