The Jakarta Project
The mighty Tomcat - Meow!

Tomcat on NetWare HowTo

By Mike Anderson mmanders@novell.com

This document explains how to setup Tomcat to run on NetWare. Sections are provided for running Tomcat standalone, running with the NetWare Enterprise Web Server, and running with Apache on NetWare. There is also a section describing how to build the web server connectors for NetWare. A lot of this is duplicated from the Tomcat Netscape HowTo and Working with mod_jk, both written by Gal Shachor shachor@il.ibm.com with NetWare specific information added.

Table of Contents

Document Conventions and Assumptions

<tomcat_home> is the root directory of Tomcat. By default this is at the root of the SYS: volume (SYS:\jakarta-tomcat-3.3 by default for Tomcat 3.3) but it can be placed anywhere, on any volume. Your installation should have the following sub-directories:
  1. <tomcat_home>\conf - Where you can place various configuration files
  2. <tomcat_home>\webapps - Contains example applications and is the default place for adding your applications
  3. <tomcat_home>\bin - Where you place web server connectors and startup scripts
In all the examples in this document, <tomcat_home> will be SYS:\jakarta-tomcat-3.3.

A worker is the tomcat process that accepts work from the web server.

Tested Configurations

Tomcat and the web server connectors described here have been tested on:
  1. NetWare 5.1 with both the 1.1.7b JVM and the 1.2.2 JVM.
  2. NetWare 6 with the 1.2.2 JVM and the 1.3 JVM.
The connectors have been tested with the ajp12 worker and the ajp13 worker with all JVMs. 

Installation

Builds of Tomcat are available as binary distributions and the web server connectors for NetWare are available in the netware/i386 directory relative to the specific build of tomcat.  The mod_jk.nlm file is the connector for Apache, the nsapi_rd.nlm file is the connector for the NetWare Enterprise Web Server, and the jni_conn.nlm file is the native method library if you use the jni worker with the 1.2.2 or 1.3 JVM.  Once you have downloaded the appropriate zip file and unzipped it to your NetWare server, you can run Tomcat in standalone mode.  To run with another web server providing static content, you will need to configure the web server appropriately and copy the necessary connector(s) to the appropriate directories.
 

1. Running Tomcat Standalone

To run Tomcat standalone, it is easiest to create an NCF file to start Tomcat. A sample TOMCAT.NCF could look like this:

; This is a sample NCF file for starting TOMCAT on NetWare. The TOMCAT_HOME
; environment variable and the tomcat.home define on the java command line
; should be modified to reflect the directory where you actually install
; Tomcat.

envset TOMCAT_HOME=SYS:\jakarta-tomcat-3.3

envset TOMCAT_CLASSPATH=sys:\java\lib\classes.zip
envset TOMCAT_CLASSPATH=$TOMCAT_CLASSPATH;$TOMCAT_HOME\lib\tomcat.jar

; The following command line starts Tomcat with it's own Console Screen
; that will automatically close (-nsac) with the screen called Tomcat
; (-snTomcat) and the current working directory set  to TOMCAT_HOME
; (-envCWD=$TOMCAT_HOME)
java -nsac -snTomcat -envCWD=$TOMCAT_HOME -classpath $TOMCAT_CLASSPATH -Dtomcat.home=SYS:\jakarta-tomcat-3.3 org.apache.tomcat.startup.Main %1 %2 %3 %3 %5 %6 %7 %8 %9

As the comment states, you will need to make sure that TOMCAT_HOME points to the correct directory.

By putting this NCF file in SYS:\System you can start Tomcat by just typing tomcat start at the system console. You can also add this to your autoexec.ncf to automatically start Tomcat when your system comes up. The %1 ... %9 at the end of the command line allows you also pass in additional parameters to Tomcat.  Try tomcat help to see a base list of parameters available.
 

2. Running Tomcat with the NetWare Enterprise Web Server

To run Tomcat with the NetWare Enterprise Web Server, you need to download nsapi_rd.nlm and copy it to your NetWare server. A good location is <tomcat_home>\bin\netscape\netware\i386. You will then need to add the following to your obj.conf file located in SYS:\novonyx\suitespot\https-<servername>\config. This will tell the NetWare Enterprise Web Server to let Tomcat handle the /servlet/* and /examples/* URIs.
  1. If you are currently running the Novell Servlet Gateway, disable it using the NetWare Web Manager.
  2. In the Init section add the following 2 lines (if you see more than 2 lines, your browser is wrapping the lines):

    3. Init fn="load-modules" funcs="jk_init,jk_service" shlib="sys:/jakarta-tomcat-3.3/bin/netscape/netware/i386/nsapi_rd.nlm"
    Init fn="jk_init" worker_file="sys:/jakarta-tomcat-3.3/conf/jk/workers.properties" log_level="debug" log_file="sys:/jakarta-tomcat-3.3/logs/nsapi.log"
  3. In the default object NameTrans section add the following 3 lines:

    4. NameTrans fn="assign-name" from="/servlet/*" name="Tomcat"
    NameTrans fn="assign-name" from="/*.jsp" name="Tomcat"
    NameTrans fn="assign-name" from="/examples/*" name="Tomcat"
  4. Create a new configuration object by adding the following 4 lines to the end of the obj.conf file:

    5. <Object name="Tomcat">
    ObjectType fn="force-type" type="text/plain"
    Service fn="jk_service" worker="ajp13"
    </Object>
Now stop and restart the NetWare Enterprise Web Server, make sure that Tomcat is running (i.e. run the tomcat.ncf file mentioned in Running Tomcat Standalone) and you should be able to access http://server:port/examples/.  Additional configuration information can be found in Tomcat Netscape HowTo.

3. Running Tomcat with Apache on NetWare

To run Tomcat with Apache on NetWare, you need to download mod_jk.nlm and copy it to you NetWare server.  A good location is the modules directory under your Apache installation.  If you copy mod_jk.nlm there, then a base configuration file called mod_jk.conf can be generated by Tomcat that has a default set of Apache configuration directives that map appropriate URIs from Apache to Tomcat.  First, run tomcat jkconf (i.e. run the tomcat.ncf file mentioned in Running Tomcat Standalone with a jkconf parameter) to generate the file <tomcat_home>/conf/auto/mod_jk.conf.  Then add the following line to your httpd.conf file, replacing SYS:/jakarta-tomcat-3.3 with the directory where Tomcat is installed:

Include "SYS:/jakarta-tomcat-3.3/conf/auto/mod_jk.conf"

You can also just copy the appropriate configuration directives from the generated mod_jk.conf file to your httpd.conf file.  For additional information, look in  Working with mod_jk.

Building Tomcat for use on NetWare

Building the Java portion of Tomcat is the same for any platform.  First download the  source, unzip it and read the README document.  After getting the JDK and other tools required for building ( Ant, JAXP, and possibly JSSE), you just run the Ant command as described in the README.  Building the native connectors requires MetroWerks CodeWarrior 5 or greater, GNU make (version 3.78.1), the WinSock 2 Developer Components for NetWare, WinSock 2 components from the Microsoft Platform SDK, the JNI headers from SYS:\java\include\netware (download and install the Novell JVM for NetWare v1.1.7b or v1.2.2 to get these), and the  NLM and NetWare Libraries for C.  Once you have all of the tools and SDKs necessary, it is recommended that you install MetroWerks and the NetWare SDK components to a common directory structure such as D:\Tools (the default in the makefiles.) Next create a directory structure for the MetroWerks command line tools that matches what the makefile expects.  The final Tools directory structure would look something like this:

D:\Tools
     |
     +CodeWarrior (base directory for MetroWerks CodeWarrior installation)
     |    |
     |    |
     |    +5.3   (this is optional but it makes it easier to use different versions)
     |        |
     |        +bin (CodeWarrior IDE binaries)
     |        |
     |       ... (all the other CodeWarrior directories)
     |        |
     |        +Tools (location for Command Line Tools.  See the MW directory structure)
     |        |
     |        +Novell Support (location for Novell Specific files.  See the MW directory structure)
     +mw
     |    |
     |    +5.3   (this is optional but it makes it easier to use different versions)
     |        |
     |        +bin (copy mwccnlm.exe and mwldnlm.exe from \Tools\CodeWarrior\Tools\Command Line Tools)
     |        |
     |        +include (copy all files from \Tools\CodeWarrior\Novell Support\Metrowerks Support\Headers and
     |        |              \Tools\CodeWarrior\Novell Support\Metrowerks Support\Libraries\MSL C++\Include)
     |        +lib  (copy *.lib and *.obj from \Tools\CodeWarrior\Novell Support\Metrowerks Support\Libraries\Runtime)
     |
     +nwsdk (All of the NetWare SDK components.  Change default install directory to D:\Tools instead of C:\Novell)
     |
     +jdk
         |
         +jdk-1_2_2 (JDK installation)

Once you have the tools set up, here are the environment variables you can define to point to your tools and SDKs.

Environment Variable Name Description
TOOLPATH The base path where the tools are install.  Defaults to D:\Tools
JDKPATH The base path for the jdk.  Defaults to $(TOOLPATH)\jdk\jdk-1_2_2.  Copy the JNI headers from your NetWare server's SYS:\java\include\netware directory to $(JDKPATH)\include\netware
NOVELLNDK The base path for the NetWare SDK files.  Defaults to $(TOOLPATH)\nwsdk
METROWERKSPATH The base path for the mw directory structure defined above.  Defaults to $(TOOLPATH)\mw\5.3
WINSOCK_INCDIR The base path for winsock headers.  Defaults to $(NOVELLNDK)\include\winsock.  Only needed for the Apache connector.
APACHE_SRC The path to the Apache src directory.  Defaults to d:\apache_1.3.19\src.  Only needed for the Apache connector.

Copy the GNUmake executable (referred to a gmake hereafter) to a directory that is in your path and change to the directory of the connector that you wish to build.  If your tools are set up as described above, you just need to set the APACHE_SRC environment variable to an appropriate directory and type gmake -f Makefile.nw in the main directory for the connector you wish to build.