SunOne -- Netscape/iPlanet HowTo

+ + &project; + + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You 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. + + +SunOne -- Netscape/iPlanet HowTo +Henri Gomez +Jim Jagielski +Gal Shachor +Mladen Turk +$Date: 2009-04-07 23:11:25 +0200 (Tue, 07 Apr 2009) $ + + +

+This document explains how to set up Sun ONE Web Server previously known as +Netscape web servers to cooperate with Tomcat. +

+ +

+Normally the Sun ONE Web Servers come with their own Servlet engine, +but you can also configure them to send servlet and JSP requests to Tomcat +using the NSAPI redirector plugin. +

+ +

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

+ + + +

+${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:\tomcat. +A worker is defined to be a tomcat process that accepts work from the Sun ONE Web Server. +

+ + + + +

+The NSAPI-Tomcat redirector was developed and tested on: +

+WINNT 2000/XP/2003 (should be able to work with other service packs) and some Unixes +
+Sun ONE Web Server 6.1 +
+Tomcat 4.1.x , Tomcat 5.0.x and Tomcat 5.5.x +

+ +

+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. +There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +

+ + + +

+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, 5.0.x, 5.5.x and 6. +

+ +

+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 +

+ + + + + +

+The NSAPI-Tomcat redirector is an Netscape service step plugin, +Netscape load the redirector plugin and calls its service handler +function for request that are assigned to the "servlet" configuration object. +
+For each in-coming request Netscape will execute the set of NameTrans directives +that we added to obj.conf, the assign-name function will check if it's from +parameter matches the request URL. +
+If a match is found, assign-name will assign the servlet object name to the request. +This will cause Netscape to send the request to the servlet configuration object. +
+Netscape will execute our jk_service extension. The extension collects the +request parameters and forwards them to the appropriate worker using the ajp13 protocol +(the worker="defworker" parameter in jk_service inform it that the worker for this request is named defworker). +the workers properties files, workers.properties, will indicate that defworker use ajp13 protocol. +
+The extension collects the response from the worker and returns it to the browser. +

+ + +

+ +

+A pre-built version of the NSAPI redirector, nsapi_redirect.dll, may be available under +the win32/i386 directory of tomcat-connectors distribution. +For those using Netscape as your browser, try downloading a zip version of the file, if available. + +You can also build a copy locally from the source present in tomcat-connectors distribution. + + +The Tomcat redirector requires two entities: +

+nsapi_redirect.dll (Windows) -or- nsapi_redirector.so (Unix) - The NSAPI server plugin, either obtain a pre-built DLL/so 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. +

+ +The installation includes the following parts: + +

+Configuring the NSAPI redirector with a default /examples context and checking that you can serve servlets +with Netscape. +
+Adding more contexts to the configuration. +

+ +

+In this document we'll assume that nsapi_redirect.dll is placed in +c:\jk\lib\nsapi_redirect.dll, the properties file is inc:\jk\conf +and you created a log directory c:\jk\logs +

+ +

+If the built in servlet support is working disable it. +
+Add the redirector plugin into the Netscape server configuration. +Edit your server magnus.conf and add the following lines: +

+ + + + Init fn="load-modules" funcs="jk_init,jk_service" shlib="c:/jk/lib/nsapi_redirect.dll" shlib_flags="(global|now)" + Init fn="jk_init" worker_file="c:/jk/conf/workers.properties" log_level="debug" log_file="c:/jk/logs/nsapi.log" shm_file="c:/jk/logs/jk_shm" + +

+Edit your server obj.conf and add the following lines: +

+ + + + In the default object NameTrans section + <Object name="default"> + + NameTrans fn="assign-name" from="/servlets-examples(|/*)" name="jknsapi" + NameTrans fn="assign-name" from="/jsp-examples(|/*)" name="jknsapi" + .... + </Object> + + Create a new configuration object by adding the following lines to the end of the obj.conf file + + <Object name="jknsapi"> + ObjectType fn=force-type type=text/plain + Service fn="jk_service" method="*" worker="worker1" + </Object> + + +

+Edit your worker definition file workers.properties. You should at least choose a connection pool size: +

+ + + #An entry that lists all the workers defined. For example: + worker.list=worker1 + + # Entries that define the host and port associated with these workers. + worker.worker1.host=localhost + worker.worker1.port=8009 + worker.worker1.type=ajp13 + worker.worker1.connection_pool_size=50 + + +

+Restart Web Server (stop and start the server) +

+ +

+That's all, now you should start tomcat and ask for http://server:port/servlets-examples/ +

+ +The file obj.conf seems to be sensitive to leading white space in lines, especially in +the Object element. Make sure you have no leading white space (no indentation) +on any line of this file. + + + +

+The examples context is useful for verifying your installation, but you will also need to add your own contexts. +Adding a new context requires two operations: +

+Adding the context to Tomcat (I am not going to talk about this). +
+Assigning the NSAPI redirector to handle this context. +

+ +

+Assigning the NSAPI redirector to handle this context is simple, +all you need to do is to edit obj.conf and add a NameTrans line that looks like: +

+ + + NameTrans fn="assign-name" from="/<context name>/*" name="jknsapi" + + +

+After saving obj.conf restart Netscape and it will serve the new context. +

+ + + +

+Sometimes it is better to have Netscape serve the static pages (html, gif, jpeg etc.) +even if these files are part of a context served by Tomcat. For example, consider the html and gif files in the examples context, there is no need to serve them from the Tomcat process, Netscape will suffice. +

+Making Netscape serve static files that are part of the Tomcat contexts requires the following: +

+Configuring Netscape to know about the Tomcat contexts +
+Make sure that the WEB-INF directory is protected from access. +
+Configuring Netscape to assign the NSAPI redirector only specific requests that requires JSP/Servlet handling. +

+ +

+Adding a Tomcat context to Netscape requires the addition of a new Netscape virtual directory +that covers the Tomcat context. +

+ +

+For example, adding a /example Netscape virtual directory that +covers the c:\tomcat\webapps\examples directory. +

+ +

+To add a new virtual directory add the following line to your obj.conf: +

+ + + NameTrans fn=pfx2dir from=/examples dir="c:/tomcat/webapps/examples" + + +

+WEB-INF protection requires some explanation; Each servlet application (context) has a special directory named WEB-INF, +this directory contains sensitive configurations data and Java classes and must be kept hidden from web users. +WEB-INF can be protected by adding the following line to the PathCheck section in the default configuration object: +

+ + + PathCheck fn="deny-existence" path="*/WEB-INF/*" + + This line instructs the Netscape server to reject any request with a URL that contain the path /WEB-INF/. + + +

+Configuring Netscape to assign the NSAPI redirector only specific requests is somewhat harder, +you will need to specify the exact URL-Path pattern(s) that you want Tomcat to handle +(usually only JSP files and servlets). +

+ +

+This requires a change to NameTrans portion of obj.conf. +

+ + + For the examples context it requires to replace the following line: + + NameTrans fn="assign-name" from="/examples/*" name="jknsapi" + + with the following two lines: + + NameTrans fn="assign-name" from="/examples/jsp/*.jsp" name="jknsapi" + NameTrans fn="assign-name" from="/examples/servlet/*" name="jknsapi" + + +

+As you can see the second configuration is more explicit, it actually instructs +Netscape to assign the redirector with only requests to resources under +/examples/servlet/ and resources under /examples/ whose name ends with .jsp. +

+ +

+You can be even more explicit and provide lines such as: +

+ + + NameTrans fn="assign-name" from="/examples/servletname" name="jknsapi" + + Instructs Netscape to assign the redirector request whose URL-Path equals /example/servletname + + + + + +

+Sometimes you want to serve different contexts with different Tomcat processes +(for example to spread the load among different machines). +To achieve such goal you will need to define several workers and assign each context with its own worker. +

+ +

+Defining workers is done in workers.properties, this file includes two types of entries: +

+ + + #An entry that lists all the workers defined. For example: + worker.list=worker1,worker2 + + # Entries that define the host and port associated with these workers. + worker.worker1.host=localhost + worker.worker1.port=8009 + worker.worker1.type=ajp13 + + worker.worker2.host=otherhost + worker.worker2.port=8009 + worker.worker2.type=ajp13 + + +

+The above examples defined two workers, now we can use these workers to serve two different +contexts each with it's own worker. +Submitting requests to different workers is accomplished by using multiple Service directives +in the servlet configuration Object, each with a different path pattern parameter. +

+ +

+For example, if we want to submit the /examples context to the worker named worker1 and the +/webpages context to the worker named worker2 we should use the following configuration: +

+ + + <Object name="jknsapi"> + ObjectType fn=force-type type=text/plain + Service fn="jk_service" worker="worker1" path="/examples/*" + Service fn="jk_service" worker="worker2" path="/webpages/*" + Service fn="jk_service" worker="worker1" + </Object> + + +

+More informations on using and configuring workers in the Workers HowTo +and in the worker.properties configuration reference. + +

+ + +

+ +

+The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want +to perform a custom build. You should also have NES developer SDK + +The steps that you need to take are: +

+Change directory to the nsapi plugins source directory. +
+Edit nsapi.dsp and update the include and library path to reflect your own Netscape server installation +(search for a /I compiler option and /libpath linker option) +
+Make the source with MSDEV +

+ +Change directory to the nsapi plugins source directory +cd c:\home\apache\jk\nsapi +Build the sources using MSDEV +MSDEV nsapi.dsp /MAKE ALL + +

+If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the nsapi workspace file (nsapi.dsw) in msdev and +build it using the build menu. +

+The redirector requires either gcc (Linux) or gcc or the Sun cc compiler (Solaris). + +The steps that you need to take are: +

+Change directory to the nsapi plugins source directory (src/native). +
+configure for Netscape/iPlanet/SunONE webserver. +
+Change directory to the nsapi netscape directory (./netstape). +
+Set environment variables JAVA_HOME resp. SUITSPOT_HOME to the location of your Java installation +resp. Netscape server installation. Depending on the web server version, you must add the subdirectory +"plugins" to SUITSPOT_HOME. +The variable is correct, if the file $SUITSPOT_HOME/include/nsapi.h exists. +
+Edit Makefile.solaris resp. Makefile.linux and update the variables according to your needs. +In the Solaris Makefile, you need to switch the commented lines in order to use the Sun compiler cc +instead of GNU gcc. +
+Make the source with gmake. +

+ +Change directory to the nsapi plugins source directory +cd /usr/local/src/tomcat-connectors-xxx-src/native +configure for Netscape/iPlanet/SunONE webserver +./configure --enable-netscape +Change directory to the nsapi netscape directory +cd netscape +Set JAVA_HOME (ksh example) +export JAVA_HOME=/path/to/my/java +Set SUITSPOT_HOME (ksh example) +export SUITSPOT_HOME=/path/to/my/netscape/server +Edit the Makefile +vi Makefile.solaris +Make the source with gmake +gmake -f Makefile.solaris + +

+After the build, you will have the required nsapi_redirector.so plugin. +

+ +