| <?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>Netscape/iPlanet HowTo</title> |
| <author email="hgomez@apache.org">Henri Gomez</author> |
| <author email="shachor@il.ibm.com">Gal Shachor</author> |
| <date>$Date$</date> |
| </properties> |
| |
| <section name="Introduction"> |
| <p> |
| This document explains how to set up Netscape web servers to cooperate with Tomcat. |
| </p> |
| |
| <p> |
| Normally the Netscape web servers come with their own Servlet engine, |
| but you can also configure them to send servlet and JSP requests to Tomcat |
| using the Tomcat redirector plugin. |
| </p> |
| |
| <p> |
| It is recommanded 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> |
| |
| |
| <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 Netscape/iPlanet server. |
| </p> |
| </subsection> |
| |
| |
| <subsection name="Supported Configuration"> |
| <p> |
| The Netscape-Tomcat redirector was developed and tested on: |
| <ul> |
| <li> |
| WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs) and some Unixes |
| </li> |
| <li> |
| Netscape Enterprise 3.0 and 3.61 |
| </li> |
| <li> |
| Tomcat 3.2.x, 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. |
| There is also an option to use Tomcat in process, |
| more about the in-process mode can be found in the in process howto. |
| </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> |
| |
| |
| <subsection name="How does it work ?"> |
| <p> |
| <ol> |
| <li> |
| The Netscape-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. |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| 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 <b>defworker</b>). |
| the workers properties files, <b>workers.properties</b>, will indicate that defworker use ajp13 protocol. |
| </li> |
| <li> |
| The extension collects the response from the worker and returns it to the browser. |
| </li> |
| </ol> |
| </p> |
| </subsection> |
| |
| </section> |
| |
| <section name="Installation"> |
| <p> |
| A pre-built version of the Netscape redirector, nsapi_redirect.dll, may be available under |
| the win32/i386 directory of jakarta-tomcat-connectors distribution. |
| For those using Netscape as your browser, try downloading a zip version of the file, if available. |
| There can be problems using Netscape to download DLL files. |
| |
| You can also build a copy locally from the source present in jakarta-tomcat-connectors distribution. |
| |
| |
| The Tomcat redirector requires two entities: |
| <ul> |
| <li> |
| nsapi_redirect.dll - The Netscape server 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> |
| </ul> |
| |
| The installation includes the following parts: |
| |
| <ul> |
| <li> |
| Configuring the NSAPI redirector with a default /examples context and checking that you can serve servlets |
| with Netscape. |
| </li> |
| <li> |
| Adding more contexts to the configuration. |
| </li> |
| </ul> |
| |
| </p> |
| </section> |
| |
| <section name="Configuring the NSAPI Redirector"> |
| <p> |
| In this document we'll assume that nsapi_redirect.dll is placed in |
| <b>c:\jk\lib\nsapi_redirect.dll</b>, the properties file is in<b>c:\jk\conf</b> |
| and you created a log directory <b>c:\jk\logs</b> |
| </p> |
| |
| <ul> |
| <li> |
| If the Netscape built in servlet support is working disable it. |
| </li> |
| <li> |
| Add the redirector plugin into the Netscape server configuration. |
| Edit your server <b>obj.conf</b> and add the following lines: |
| </li> |
| </ul> |
| |
| <screen> |
| <note>In the Init section:</note> |
| <read>Init fn="load-modules" funcs="jk_init,jk_service" shlib="c:/jk/lib/nsapi_redirect.dll"</read> |
| <read>Init fn="jk_init" worker_file="c:/jk/conf/workers.properties" log_level="debug" log_file="c:/jk/logs/nsapi.log"</read> |
| <note>In the default object NameTrans section</note> |
| <read>NameTrans fn="assign-name" from="/servlet/*" name="servlet"</read> |
| <read>NameTrans fn="assign-name" from="/examples/*" name="servlet"</read> |
| <note>Create a new configuration object by adding the following lines to the end of the obj.conf file</note> |
| <read><Object name=servlet></read> |
| <read>ObjectType fn=force-type type=text/plain</read> |
| <read>Service fn="jk_service" worker="worker1"</read> |
| <read></Object></read> |
| </screen> |
| |
| <ul> |
| <li> |
| Restart Netscape (stop and start the server) |
| </li> |
| </ul> |
| |
| <p> |
| That's all, now you should start tomcat and ask Netscape for http://server:port/examples/ |
| </p> |
| |
| <subsection name="Adding additional Contexts"> |
| <p> |
| 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: |
| </p> |
| <ul> |
| <li> |
| Adding the context to Tomcat (I am not going to talk about this). |
| </li> |
| <li> |
| Assigning the NSAPI redirector to handle this context. |
| </li> |
| </ul> |
| |
| <p> |
| Assigning the NSAPI redirector to handle this context is simple, |
| all you need to do is to edit <b>obj.conf</b> and add a NameTrans line that looks like: |
| </p> |
| |
| <screen> |
| <read>NameTrans fn="assign-name" from="/<context name>/*" name="servlet"</read> |
| </screen> |
| |
| <p> |
| After saving <b>obj.conf</b> restart Netscape and it will serve the new context. |
| </p> |
| </subsection> |
| |
| <subsection name="Advanced Context Configuration"> |
| <p> |
| 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. |
| </p> |
| <p> |
| Making Netscape serve static files that are part of the Tomcat contexts requires the following: |
| </p> |
| <ul> |
| <li> |
| Configuring Netscape to know about the Tomcat contexts |
| </li> |
| <li> |
| Make sure that the WEB-INF directory is protected from access. |
| </li> |
| <li> |
| Configuring Netscape to assign the NSAPI redirector only specific requests that requires JSP/Servlet handling. |
| </li> |
| </ul> |
| |
| <p> |
| Adding a Tomcat context to Netscape requires the addition of a new Netscape virtual directory |
| that covers the Tomcat context. |
| </p> |
| |
| <p> |
| For example, adding a /example Netscape virtual directory that |
| covers the <b>c:\jakarta-tomcat\webapps\examples</b> directory. |
| </p> |
| |
| <p> |
| To add a new virtual directory add the following line to your <b>obj.conf</b>: |
| </p> |
| |
| <screen> |
| <read>NameTrans fn=pfx2dir from=/examples dir="c:/jakarta-tomcat/webapps/examples"</read> |
| </screen> |
| |
| <p> |
| WEB-INF protection requires some explanation; Each servlet application (context) has a special directory named <b>WEB-INF</b>, |
| 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: |
| </p> |
| |
| <screen> |
| <read>PathCheck fn="deny-existence" path="*/WEB-INF/*"</read> |
| <note>This line instructs the Netscape server to reject any request with a URL that contain the path /WEB-INF/.</note> |
| </screen> |
| |
| <p> |
| 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). |
| </p> |
| |
| <p> |
| This requires a change to NemaTrans portion of <b>obj.conf</b>. |
| </p> |
| |
| <screen> |
| <note>For the examples context it requires to replace the following line:</note> |
| <read>NameTrans fn="assign-name" from="/examples/*" name="servlet"</read> |
| <note>with the following two lines:</note> |
| <read>NameTrans fn="assign-name" from="/examples/jsp/*.jsp" name="servlet"</read> |
| <read>NameTrans fn="assign-name" from="/examples/servlet/*" name="servlet"</read> |
| </screen> |
| |
| <p> |
| As you can see the second configuration is more explicit, it actually instructs |
| Netscape to assign the redirector with only requests to resources under |
| <b>/examples/servlet/</b> and resources under <b>/examples/</b> whose name ends with <b>.jsp</b>. |
| </p> |
| |
| <p> |
| You can be even more explicit and provide lines such as: |
| </p> |
| |
| <screen> |
| <read>NameTrans fn="assign-name" from="/examples/servletname" name="servlet"</read> |
| <note>Instructs Netscape to assign the redirector request whose URL-Path equals /example/servletname</note> |
| </screen> |
| |
| </subsection> |
| |
| <subsection name="Advanced Worker Configuration"> |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| Defining workers is done in <b>workers.properties</b>, this file includes two types of entries: |
| </p> |
| |
| <screen> |
| <note>An entry that lists all the workers defined. For example:</note> |
| <read>worker.list=worker1, worker2</read> |
| <note>Entries that define the host and port associated with these workers.</note> |
| <read>worker.worker1.host=localhost</read> |
| <read>worker.worker1.port=8009</read> |
| <read>worker.worker1.type=ajp13</read> |
| <read>worker.worker2.host=otherhost</read> |
| <read>worker.worker2.port=8009</read> |
| <read>worker.worker2.type=ajp13</read> |
| </screen> |
| |
| <p> |
| 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. |
| </p> |
| |
| <p> |
| For example, if we want to submit the <b>/examples</b> context to the worker named <b>worker1</b> and the |
| <b>/webpages</b> context to the worker named <b>worker2</b> we should use the following configuration: |
| </p> |
| |
| <screen> |
| <read><Object name=servlet></read> |
| <read>ObjectType fn=force-type type=text/plain</read> |
| <read>Service fn="jk_service" worker="worker1" path="/examples/*"</read> |
| <read>Service fn="jk_service" worker="worker2" path="/webpages/*"</read> |
| <read>Service fn="jk_service" worker="worker1"</read> |
| <read></Object></read> |
| </screen> |
| |
| <p> |
| More informations on using and configuring workers in the <a href="jk/workershowto.html">Workers HowTO</a> |
| </p> |
| </subsection> |
| |
| </section> |
| |
| <section name="Building NSAPI redirector"> |
| <p> |
| 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: |
| <ul> |
| <li> |
| Change directory to the nsapi plugins source directory. |
| </li> |
| <li> |
| Edit <b>nsapi.dsp</b> and update the include and library path to reflect your own Netscape 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 nsapi plugins source directory</notedos> |
| <typedos>cd c:\home\apache\jk\nsapi</typedos> |
| <notedos>Build the sources using MSDEV</notedos> |
| <typedos>MSDEV nsapi.dsp /MAKE ALL</typedos> |
| </screendos> |
| </p> |
| <p> |
| 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. |
| </p> |
| </section> |
| |
| </document> |