| <?xml version="1.0"?> |
| <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>Installation of jk2 in the Web Server</title> |
| |
| <author email="jfrederic.clere@fujitsu-siemens.com">Jean-Frederic Clere</author> |
| <author email="andy@tagish.com">Andy Armstrng</author> |
| <author email="yoavs@apache.org">Yoav Shapira</author> |
| |
| <date>$Date$</date> |
| </properties> |
| |
| <section name="Installation"> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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 |
| </p> |
| <subsection name="Apache 1.3"> |
| <p> |
| In the following example Apache-1.3 is installed in |
| /home/apache13/ and the commands are executed in |
| the jakarta-tomcat-connectors directory. |
| </p> |
| <p> |
| 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 : |
| <ul> |
| <li> |
| Rebuild Apache 1.3 with pthread support (recommanded) |
| </li> |
| <li> |
| Add the LoadFile /usr/lib/pthread.so in beginning of your httpd.conf |
| </li> |
| </ul> |
| </p> |
| <p> |
| You should also ensure that the linker will be able to locate the apr shared libraries, |
| <code>libapr.so</code>, and <code>libaprutil.so</code>, make sure they have been installed |
| in linker search locations. |
| </p> |
| <screen> |
| <note>Copy the dso files in the modules location:</note> |
| <type>cp jk/build/jk2/apache13/mod_jk2.so /home/apache13/modules</type> |
| <note>Copy jkjni.so if you're using JNI</note> |
| <type>cp jk/build/jk2/apache13/jkjni.so /home/apache13/modules</type> |
| <note>You may have to add pthread library in the httpd.conf:</note> |
| <read>LoadFile /usr/lib/pthread.so</read> |
| <note>Add mod_jk2 loading in the httpd.conf</note> |
| <read>LoadModule jk2_module modules/mod_jk2.so</read> |
| </screen> |
| </subsection> |
| <subsection name="Apache 2"> |
| <p> |
| In the following example Apache-2.0 is installed in |
| /home/apache20/apache40 and the commands are executed in |
| the jakarta-tomcat-connectors directory. |
| </p> |
| <screen> |
| <note>Copy the dso files in the modules location:</note> |
| <type>cp jk/build/jk2/apache2/mod_jk2.so /home/apache20/apache40/modules</type> |
| <note>Copy jkjni.so if you're using JNI</note> |
| <type>cp jk/build/jk2/apache2/jkjni.so /home/apache20/apache40/modules</type> |
| <note>Add mod_jk2 loading in the httpd.conf:</note> |
| <read>LoadModule jk2_module modules/mod_jk2.so</read> |
| </screen> |
| </subsection> |
| <subsection name="IIS"> |
| <p>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.<br />The Tomcat redirector requires three entities: |
| <ul> |
| <li> |
| <b>isapi_redirector2.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). |
| </li><li> |
| <b>workers2.properties</b> - 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. |
| </li><li> |
| <b>jk2.properties</b> - A configuration file used by mod_jk2 on the Tomcat side. |
| </li> |
| </ul> |
| </p> |
| <p> |
| <ol><li>In the registry, create a new registry key named |
| <b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\2.0"</b> |
| </li><li> |
| Add a string value with the name <b>serverRoot</b> and a value which is a full path |
| to your Tomcat installation (for example <b>c:\jakarta-tomcat</b>). If Tomcat is installed |
| on a different server, this entry must point to the location (directory) where the |
| workers2.properties file resides. |
| </li><li> |
| Add a string value with the name <b>extensionUri</b> and a value of <b>/jakarta/isapi_redirector2.dll</b> |
| </li><li> |
| Add a string value with the name <b>workersFile</b> and a value which is the full path |
| to your workers2.properties file (for example <b>c:\jakarta-tomcat\conf\workers2.properties</b>) |
| </li><li> |
| Add a string value with the name <b>logLevel</b> and a value for your log level |
| (can be DEBUG, INFO or ERROR). |
| </li><li>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. |
| </li><li> |
| 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. |
| </li> |
| </ol> |
| </p> |
| <p>Install using provided script <b>install4iis.js</b><br/> |
| This script creates the virtual directory and installs ISAPI filter for Default webserver<br/> |
| <i>C:\Program Files\Apache Software Foundation\Tomcat 5.0</i> |
| <screen> |
| <note>Open the command prompt and cd to bin folder</note> |
| <type>cd C:\Program Files\Apache Software Foundation\Tomcat 5.0\bin</type> |
| <note>Copy the isapi_redirector2.dll and install4iis.js to that folder</note> |
| <type>cscript install4iis.js</type> |
| </screen> |
| </p> |
| <p> |
| You may modify the default installation using various command line options. |
| To see what the options are type <b>csrcipt install4iis.js -h</b> |
| </p> |
| <p> |
| That's all, you should now start Tomcat and ask IIS to serve you the /examples context. |
| Try <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> for example and |
| execute some of the JSP examples. |
| </p> |
| </subsection> |
| <subsection name="Lotus Domino"> |
| <p><i>At the time of writing these instruction are applicable to Windows only. |
| As soon as there are versions of the Domino redirector available for other |
| platforms these instructions will be updated.</i></p> |
| |
| <p>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</p> |
| |
| <screen> |
| <read>Windows Registry Editor Version 5.00</read> |
| <read></read> |
| <read>[HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Dsapi Redirector\2.0]</read> |
| <read>"serverRoot"="D:\\Works\\Tomcat\\jakarta-tomcat-4.1.27"</read> |
| <read>"workersFile"="conf\\workers2.properties"</read> |
| <read>"tomcatStart"="bin\\startup.bat"</read> |
| <read>"tomcatStop"="bin\\shutdown.bat"</read> |
| <read>"tomcatTimeout"="30000"</read> |
| </screen> |
| |
| <p>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.</p> |
| |
| <p><b>Starting Tomcat:</b> 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).</p> |
| |
| <p><b>The Workers file:</b> 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.</p> |
| |
| <p><b>Configuring Domino:</b> 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.</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 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.</p> |
| |
| <p><b>Restart Domino:</b> 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.</p> |
| |
| <screen> |
| <read>14/11/2003 13:02:18 Attempting to start Tomcat: D:\...\startup.bat</read> |
| <read>Using CATALINA_BASE: D:\Works\Tomcat\jakarta-tomcat-4.1.27</read> |
| <read>Using CATALINA_HOME: D:\Works\Tomcat\jakarta-tomcat-4.1.27</read> |
| <read>Using CATALINA_TMPDIR: D:\Works\Tomcat\jakarta-tomcat-4.1.27\temp</read> |
| <read>Using JAVA_HOME: C:\JBuilder8\jdk1.4</read> |
| <read>14/11/2003 13:02:18 Apache Tomcat Interceptor (Jakarta/DSAPI/2.0.0) loaded</read> |
| <read>14/11/2003 13:02:19 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). You should now be able |
| to visit a URL that is handled by Tomcat. Something like</p> |
| |
| <p><code>http://name-of-server/servlet/SnoopServlet</code></p> |
| |
| <p>may be available, depending on how Tomcat is configured. If that all works |
| you're done.</p> |
| |
| <p><b>Mailing Lists:</b> There are two mailing lists dedicated to the Domino |
| Tomcat redirector:</p> |
| |
| <p><a href="http://nomen.tagish.co.uk/mailman/listinfo/domino-tomcat-l">domino-tomcat-l</a></p> |
| |
| <p><b>domino-tomcat-l</b> 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.</p> |
| |
| <p><a href="http://nomen.tagish.co.uk/mailman/listinfo/domino-tomcat-announce-l">domino-tomcat-announce-l</a></p> |
| |
| <p><b>domino-tomcat-announce-l</b> 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.</p> |
| |
| </subsection> |
| </section> |
| </document> |