diff options
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml')
| -rw-r--r-- | rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml new file mode 100644 index 00000000..6f86efde --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="nes.html"> + + &project; +<copyright> + 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. +</copyright> +<properties> +<title>SunOne -- Netscape/iPlanet HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<author email="jim@apache.org">Jim Jagielski</author> +<author email="shachor@il.ibm.com">Gal Shachor</author> +<author email="mturk@apache.org">Mladen Turk</author> +<date>$Date: 2009-04-07 23:11:25 +0200 (Tue, 07 Apr 2009) $</date> +</properties> +<body> +<section name="Introduction"> +<p> +This document explains how to set up Sun ONE Web Server previously known as +Netscape web servers to cooperate with Tomcat. +</p> + +<p> +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. +</p> + +<p> +It is recommended that you also read the <a href="../generic_howto/workers.html">Workers HowTo</a> document +to learn how to setup the working entities between your web server 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:\tomcat</b>. +A worker is defined to be a tomcat process that accepts work from the Sun ONE Web Server. +</p> +</subsection> + + +<subsection name="Supported Configuration"> +<p> +The NSAPI-Tomcat redirector was developed and tested on: +<ul> +<li> +WINNT 2000/XP/2003 (should be able to work with other service packs) and some Unixes +</li> +<li> +Sun ONE Web Server 6.1 +</li> +<li> +Tomcat 4.1.x , Tomcat 5.0.x and Tomcat 5.5.x +</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, 5.0.x, 5.5.x and 6. +</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 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. +</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 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: +<ul> +<li> +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). +</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 built in servlet support is working disable it. +</li> +<li> +Add the redirector plugin into the Netscape server configuration. +Edit your server <b>magnus.conf</b> and add the following lines: +</li> +</ul> + +<source> + + 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" +</source> +<ul> +<li> +Edit your server <b>obj.conf</b> and add the following lines: +</li> +</ul> +<source> + + + 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> +</source> + +<ul> +<li> +Edit your worker definition file <b>workers.properties</b>. You should at least choose a connection pool size: +</li> +</ul> + +<source> + #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 +</source> + +<ul> +<li> +Restart Web Server (stop and start the server) +</li> +</ul> + +<p> +That's all, now you should start tomcat and ask for http://server:port/servlets-examples/ +</p> +<warn> +The file <b>obj.conf</b> seems to be sensitive to leading white space in lines, especially in +the <b>Object</b> element. Make sure you have no leading white space (no indentation) +on any line of this file. +</warn> + +<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> + +<source> + NameTrans fn="assign-name" from="/<context name>/*" name="jknsapi" +</source> + +<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:\tomcat\webapps\examples</b> directory. +</p> + +<p> +To add a new virtual directory add the following line to your <b>obj.conf</b>: +</p> + +<source> + NameTrans fn=pfx2dir from=/examples dir="c:/tomcat/webapps/examples" +</source> + +<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> + +<source> + 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/. +</source> + +<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 NameTrans portion of <b>obj.conf</b>. +</p> + +<source> + 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" +</source> + +<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> + +<source> + NameTrans fn="assign-name" from="/examples/servletname" name="jknsapi" + + Instructs Netscape to assign the redirector request whose URL-Path equals /example/servletname +</source> + +</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> + +<source> + #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 +</source> + +<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> + +<source> + <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> +</source> + +<p> +More informations on using and configuring workers in the <a href="../generic_howto/workers.html">Workers HowTo</a> +and in the <a href="../reference/workers.html">worker.properties configuration reference</a>. + +</p> +</subsection> + +</section> + +<section name="Building NSAPI DLL redirector for Windows"> +<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> +<section name="Building NSAPI so plugin redirector for Unix"> +<p> +The redirector requires either gcc (Linux) or gcc or the Sun cc compiler (Solaris). + +The steps that you need to take are: +<ul> +<li> +Change directory to the nsapi plugins source directory (src/native). +</li> +<li> +configure for Netscape/iPlanet/SunONE webserver. +</li> +<li> +Change directory to the nsapi netscape directory (./netstape). +</li> +<li> +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. +</li> +<li> +Edit <b>Makefile.solaris</b> resp. <b>Makefile.linux</b> 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. +</li> +<li> +Make the source with gmake. +</li> +</ul> +<screendos> +<notedos>Change directory to the nsapi plugins source directory</notedos> +<typedos>cd /usr/local/src/tomcat-connectors-xxx-src/native</typedos> +<notedos>configure for Netscape/iPlanet/SunONE webserver</notedos> +<typedos>./configure --enable-netscape</typedos> +<notedos>Change directory to the nsapi netscape directory</notedos> +<typedos>cd netscape</typedos> +<notedos>Set JAVA_HOME (ksh example)</notedos> +<typedos>export JAVA_HOME=/path/to/my/java</typedos> +<notedos>Set SUITSPOT_HOME (ksh example)</notedos> +<typedos>export SUITSPOT_HOME=/path/to/my/netscape/server</typedos> +<notedos>Edit the Makefile</notedos> +<typedos>vi Makefile.solaris</typedos> +<notedos>Make the source with gmake</notedos> +<typedos>gmake -f Makefile.solaris</typedos> +</screendos> +</p> +<p> +After the build, you will have the required nsapi_redirector.so plugin. +</p> +</section> +</body> +</document> |