Added: tomcat/site/trunk/docs/connectors-doc/webserver_howto/iis.html
URL:
http://svn.apache.org/viewvc/tomcat/site/trunk/docs/connectors-doc/webserver_howto/iis.html?rev=1307873&view=auto
==============================================================================
--- tomcat/site/trunk/docs/connectors-doc/webserver_howto/iis.html (added)
+++ tomcat/site/trunk/docs/connectors-doc/webserver_howto/iis.html Sat Mar 31
18:52:20 2012
@@ -0,0 +1,696 @@
+<html><head><META http-equiv="Content-Type" content="text/html;
charset=iso-8859-1"><title>The Apache Tomcat Connector - Webserver HowTo - IIS
HowTo</title><meta name="author" value="Henri Gomez"><meta name="email"
value="hgo...@apache.org"><meta name="author" value="Gal Shachor"><meta
name="email" value="shac...@il.ibm.com"><meta name="author" value="Yoav
Shapira"><meta name="email" value="yo...@apache.org"><link href="../style.css"
type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000"
link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%"
cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a
href="http://tomcat.apache.org/";><img src="../images/tomcat.gif" align="left"
alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a
href="http://www.apache.org/";><img
src="http://www.apache.org/images/asf-logo.gif"; align="right" alt=" :: Apache
Software Foundation" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr
><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE
>NAVIGATION--><td width="20%" valign="top"
>nowrap="true"><p><strong>Links</strong></p><ul><li><a
>href="../index.html">Docs Home</a></li></ul><p><strong>Reference
>Guide</strong></p><ul><li><a
>href="../reference/workers.html">workers.properties</a></li><li><a
>href="../reference/uriworkermap.html">uriworkermap.properties</a></li><li><a
>href="../reference/status.html">Status Worker</a></li><li><a
>href="../reference/apache.html">Apache HTTP Server</a></li><li><a
>href="../reference/iis.html">IIS</a></li></ul><p><strong>Generic
>HowTo</strong></p><ul><li><a href="../generic_howto/quick.html">For the
>impatient</a></li><li><a href="../generic_howto/workers.html">All about
>workers</a></li><li><a
>href="../generic_howto/timeouts.html">Timeouts</a></li><li><a
>href="../generic_howto/loadbalancers.html">Load Balancing</a></li><li><a
>href="../generic_howto/proxy.html">Reverse
>Proxy</a></li></ul><p><strong>Webserver HowTo</stron
g></p><ul><li><a href="../webserver_howto/apache.html">Apache HTTP
Server</a></li><li><a href="../webserver_howto/iis.html">IIS</a></li><li><a
href="../webserver_howto/nes.html">Netscape/SunOne/Sun</a></li></ul><p><strong>AJP
Protocol Reference</strong></p><ul><li><a
href="../ajp/ajpv13a.html">AJPv13</a></li><li><a
href="../ajp/ajpv13ext.html">AJPv13 Extension
Proposal</a></li></ul><p><strong>Miscellaneous
Documentation</strong></p><ul><li><a
href="../miscellaneous/faq.html">Frequently asked questions</a></li><li><a
href="../miscellaneous/changelog.html">Changelog</a></li><li><a
href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=su
bstring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=">Current
Tomcat Connectors bugs</a></li><li><a
href="../miscellaneous/doccontrib.html">Contribute documentation</a></li><li><a
href="../miscellaneous/jkstatustasks.html">JK Status Ant Tasks</a></li><li><a
href="../miscellaneous/reporttools.html">Reporting Tools</a></li><li><a
href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html";>Old
JK/JK2 documentation</a></li></ul><p><strong>News</strong></p><ul><li><a
href="../news/20120301.html">2012</a></li><li><a
href="../news/20110701.html">2011</a></li><li><a
href="../news/20100101.html">2010</a></li><li><a
href="../news/20090301.html">2009</a></li><li><a
href="../news/20081001.html">2008</a></li><
li><a href="../news/20070301.html">2007</a></li><li><a
href="../news/20060101.html">2006</a></li><li><a
href="../news/20050101.html">2005</a></li><li><a
href="../news/20041100.html">2004</a></li></ul></td><!--RIGHT SIDE MAIN
BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%"
cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat
Connector - Webserver HowTo</h1><h2>IIS HowTo</h2></td><td align="right"
valign="top" nowrap="true"><small><a href="printer/iis.html"><img
src="../images/printer.gif" border="0" alt="Printer Friendly
Version"><br>print-friendly<br>version
+ </a></small></td></tr></table><table border="0"
cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font
color="#ffffff" face="arial,helvetica.sanserif"><a
name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+This document explains how to set up IIS to cooperate with Tomcat.
+</p>
+
+<p>
+Normally IIS can not execute Servlets and Java Server Pages (JSPs),
+configuring IIS to use the JK ISAPI redirector plugin will let IIS send
servlet and
+JSP requests to Tomcat (and this way, serve them to clients).
+</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.
+For more detailed configuration information consult the Reference Guide for
+<a href="../reference/workers.html">workers.properties</a>,
+<a href="../reference/uriworkermap.html">uriworkermap</a>
+and <a href="../reference/iis.html">IIS</a>.
+</p>
+
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Document Conventions and Assumptions"><strong>Document Conventions and
Assumptions</strong></a></font></td></tr><tr><td><blockquote>
+<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 IIS
server.
+</p>
+</blockquote></td></tr></table>
+
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Supported Configuration"><strong>Supported
Configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+The IIS-Tomcat redirector works for:
+<ul>
+<li>
+WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs),
Win98, WinXP, Win2K,
+and probably also Win2K3, Vista and Windows 7.
+</li>
+<li>
+IIS4.0 and PWS4.0, IIS 5 to IIS 7.
+</li>
+<li>
+Tomcat 3.2 to Tomcat 7.
+</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>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="IIS 5 and 6 Notes"><strong>IIS 5 and 6
Notes</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+There are extra steps you need to take for configuring Tomcat with IIS 5 and
6. Please see the appropriate links from
+<a href="http://wiki.apache.org/tomcat/Tomcat/Links";>Tomcat Useful Links</a>.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="IIS 7 notes"><strong>IIS 7
notes</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+There is a known bug in IIS that may result in incomplete log messages. See <a
href="https://issues.apache.org/bugzilla/show_bug.cgi?id=45769";>bug 45769</a>
+for further details.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="64 Bit notes"><strong>64 Bit
notes</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+In a 64 Bit environment - at least for IIS 7 - the used IIS Application Pool
+should have "Enable 32-bit Applications" set to "False". Otherwise the
redirector will
+not be called and returns an http code 404. If you think, the 32bit version of
+isapi_redirect.dll would do the job instead, you will get an http code 500,
+because the library is not loadable into a 64 Bit IIS.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Who support ajp protocols ?"><strong>Who support ajp protocols
?</strong></a></font></td></tr><tr><td><blockquote>
+<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.x, 5 and 5.5 and
Tomcat 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>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="How does it work ?"><strong>How does it work
?</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+<ol>
+<li>
+The IIS-Tomcat redirector is an IIS plugin (filter + extension), IIS load the
redirector plugin and calls its
+filter function for each in-coming request.
+</li>
+<li>
+The filter then tests the request URL against a list of URI-paths held inside
uriworkermap.properties,
+If the current request matches one of the entries in the list of URI-paths,
+the filter transfers the request to the extension.
+</li>
+<li>
+The extension collects the request parameters and forwards them to the
appropriate worker using the defined
+protocol like <b>ajp13</b>.
+</li>
+<li>
+The extension collects the response from the worker and returns it to the
browser.
+</li>
+</ol>
+</p>
+</blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a
name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+A pre-built version of the ISAPI redirector server plugin, isapi_redirect.dll,
is 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.
+There can be problems using Netscape to download DLL files.
+
+You can also build a copy locally from the source present in tomcat-connectors
distribution.
+
+The Tomcat redirector requires three entities:
+
+<ul>
+<li>
+<b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built
DLL or build it yourself (see the build section).
+</li>
+<li>
+<b><a href="../reference/workers.html">workers.properties</a></b> - 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>
+<li>
+<b><a href="../reference/uriworkermap.html">uriworkermap.properties</a></b> -
A file that maps URL-Path patterns to workers.
+A sample uriworkermap.properties can be found under the conf directory as well.
+</li>
+</ul>
+</p>
+
+<p>
+The installation includes the following parts:
+
+<ul>
+<li>
+Configuring the ISAPI redirector with a default /examples context and checking
that you can serve servlets with IIS.
+</li>
+<li>
+Adding more contexts to the configuration.
+</li>
+</ul>
+</p>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a name="Configuring the ISAPI
Redirector"><strong>Configuring the ISAPI
Redirector</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+In this document I will assume that isapi_redirect.dll is placed in
+<b>c:\tomcat\bin\win32\i386\isapi_redirect.dll</b> and
+that the properties files which you created are in <b>c:\tomcat\conf</b>.
+</p>
+<p>
+<ol>
+<li>
+In the registry, create a new registry key named
+<b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi
Redirector\1.0"</b>
+</li>
+<li>
+Add a string value with the name <b>extension_uri</b> and a value of
<b>/jakarta/isapi_redirect.dll</b>
+</li>
+<li>
+Add a string value with the name <b>log_file</b> and a value pointing to where
you want your
+log file to be (for example <b>c:\tomcat\logs\isapi.log</b>).
+</li>
+<li>
+Add a string value with the name <b>log_level</b> and a value for your log
level
+(can be debug, info, error or emerg).
+</li>
+<li>
+Add a string value with the name <b>worker_file</b> and a value which is the
full path
+to your workers.properties file (for example
<b>c:\tomcat\conf\workers.properties</b>)
+</li>
+<li>
+Add a string value with the name <b>worker_mount_file</b> and a value which is
the full path
+to your uriworkermap.properties file (for example
<b>c:\tomcat\conf\uriworkermap.properties</b>)
+</li>
+<li>
+Using the IIS management console, add a new virtual directory to your IIS/PWS
web site.
+The name of the virtual directory must be jakarta.
+Its physical path should be the directory where you placed isapi_redirect.dll
+(in our example it is c:\tomcat\bin\win32\i386).
+While creating this new virtual directory assign it with execute access.
+</li>
+<li>
+Using the IIS management console, add isapi_redirect.dll as a filter in your
IIS/PWS web site.
+The name of the filter should reflect its task (I use the name tomcat),
+its executable must be our c:\tomcat\bin\win32\i386\isapi_redirect.dll.
+For PWS, you'll need to use regedit and add/edit the <b>"Filter DLLs"</b> key
under
+<b>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters</b>.
+This key contains a "," separated list of dlls (full paths) -
+you need to insert the full path to isapi_redirect.dll.
+</li>
+<li>
+If you're using IIS 6.0 you must also do the following:
+<br>
+Using the IIS management console, add the Jakarta Isapi Redirector to the Web
+Service Extensions.
+<ol>
+<li>Right-click on Web Service Extensions and choose Add a new Web Service
+Extension.</li>
+<li>Enter tomcat for the Extension Name.</li>
+<li>Add the isapi_redirect.dll to the required files.</li>
+<li>Check the Set extension status to Allowed.</li>
+<li>Click on OK.</li>
+</ol>
+</li>
+<li>
+Restart IIS (stop + start the IIS service), make sure that the tomcat filter
is marked with a green up-pointing arrow.
+Under Win98 you may need to <b>cd WINDOWS\SYSTEM\inetsrv</b> and type PWS
/stop
+( the DLL and log files are locked - even if you click the stop button,
+PWS will still keep the DLLs in memory. ). Type pws to start it again.
+</li>
+</ol>
+</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>
+<p>
+If this does not work successfully, refer to the Troubleshooting section below
for help on correcting the problem.
+</p>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Adding additional Contexts"><strong>Adding additional
Contexts</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+<p>
+<ol>
+<li>
+Adding the context to Tomcat (I am not going to talk about this).
+</li>
+<li>
+Adding the context to the ISAPI redirector.
+</li>
+</ol>
+</p>
+<p>
+Adding a context to the ISAPI redirector is simple, all you need to do is to
edit
+your uriworkermap.properties and to add a line that looks like:
+</p>
+
+<div class="example"><pre>
+ /context/*=worker_name
+</pre></div>
+
+<p>
+Workers and their name are defined in workers.properties, by default
workers.properties comes
+with a single pre-configured worker named <b>"defworker"</b> so you can use
it.
+As an example, if you want to add a context named "shop", the line that you
should add to
+uriworkermap.properties will be:
+</p>
+
+<div class="example"><pre>
+ /shop/*=defworker
+</pre></div>
+
+After saving uriworkermap.properties restart IIS and it will serve the new
context.
+<p>
+The above should be all you need for IIS to pass through to Tomcat any request
for any URI which corresponds
+to a Tomcat context (webapp).
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Advanced Context Configuration"><strong>Advanced Context
Configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+If your webiste is very busy (more than 100 requests/second, or more than 100
simultaneous client connections),
+it might sometimes be desirable to have IIS serve static content (html, gif,
jpeg etc.) directly,
+even if these files are part of a context served by Tomcat. Allowing IIS to
serve such files directly may
+ avoid the small overhead consisting of passing the request to Tomcat via the
redirector, and may free up
+ Tomcat somewhat, by using it only to process requests that only Tomcat can
handle (e.g. requests to JSP pages and java servlets).
+</p>
+<p>
+For example, consider the html and gif files in the examples context : you
could serve these files directly
+with IIS; there is no need to serve them from the Tomcat process.
+</p>
+<p><font color="#ff0000">However, you should be very careful when you
implement the following configuration style, because by doing so you are
+in fact providing a "back-door" to IIS, and allowing it to serve files out of
a Tomcat context without Tomcat's knowledge,
+thus bypassing any security
+restrictions which Tomcat itself and the Tomcat context (webapp) may place on
those files.</font></p>
+<p>
+Making IIS serve static files that are part of the Tomcat contexts requires
the following:
+<ol>
+<li>
+Configuring IIS to know about the Tomcat contexts
+</li>
+<li>
+Configuring the redirector to leave the static files for IIS
+</li>
+</ol>
+</p>
+
+<p>
+Adding a Tomcat context to IIS requires the addition of a new IIS virtual
directory that covers the Tomcat context.
+For example adding a /example IIS virtual directory that covers the
c:\tomcat\webapps\examples directory.
+</p>
+
+<p>
+Configuring the redirector is somewhat harder, you will need to specify the
exact
+URL-Path pattern(s) which you want Tomcat to handle (usually only JSP files
and servlets).
+This requires a change to the uriworkermap.properties :
+
+<div class="example"><pre>
+ For the examples context it requires to replace the following line
+ /examples/*=defworker
+ with the following two lines
+ /examples/*.jsp=defworker
+ /examples/servlet/*=defworker
+</pre></div>
+</p>
+
+<p>
+As you can see the second configuration is more explicit, it actually instruct
the redirector
+to redirect only requests to resources under /examples/servlet/ and resources
under /examples/
+whose name ends with .jsp.
+</p>
+
+<p>
+You can even be more explicit and provide lines such as:
+
+<div class="example"><pre>
+ /example/servletname=defworker
+</pre></div>
+</p>
+
+<p>
+that instructs the redirector to redirect all requests whose URL-path matches
the leading string "/example/servletname"
+to the worker named defworker.
+</p>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Protecting the content of your Tomcat contexts"><strong>Protecting the
content of your Tomcat
contexts</strong></a></font></td></tr><tr><td><blockquote>
+<p>Once again, be aware that by allowing IIS to access the content of your
Tomcat context directly, you are
+potentially bypassing Tomcat's protection of that content. You should thus
make sure to protect this content
+at the IIS level if needed, by using the corresponding IIS management console
functions.
+</p>
+<p>
+In particular, each servlet application (context) has a special directory
named WEB-INF,
+which contains sensitive configuration data and Java classes, and which should
always be kept hidden from web users.
+Using the IIS management console it is possible to protect the WEB-INF
directory from user access, but considering that
+this is a general requirement, and considering that it is easy to forget to
implement this protection
+at the IIS level, the redirector plugin does it automatically for you, and it
will reject any request
+which contains WEB-INF in its URL-path.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Advanced Worker Configuration"><strong>Advanced Worker
Configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Sometimes you may want to serve different contexts with different Tomcat
processes
+(for example to spread the load among different machines).
+To achieve such a goal you will need to define several workers and assign each
context to its own worker.
+</p>
+<p>
+Defining additional workers is done in the workers.properties file. This file
includes two types of entries:
+</p>
+
+<p>
+<div class="example"><pre>
+ # An entry that lists all the workers defined
+ worker.list=worker1, worker2
+ # Entries that define the host and port associated with each of 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
+</pre></div>
+</p>
+
+<p>
+The above example defined two workers, now we can use these workers to serve
two different contexts
+each with its own worker:
+<div class="example"><pre>
+ example uriworkermap.properties fragment
+ /examples/*=worker1
+ /webpages/*=worker2
+</pre></div>
+</p>
+
+<p>
+As you can see the <b>examples</b> context is served by <b>worker1</b> while
the
+<b>webpages</b> context is served by <b>worker2</b>.
+</p>
+
+<p>
+More information 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>
+
+</blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a name="Building ISAPI
redirector"><strong>Building ISAPI
redirector</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+The redirector was developed using Visual C++ Ver.6.0, so having this
environment is a prerequisite if you want
+to perform a custom build. You should also have the IIS developer SDK.
+
+The steps that you need to take are:
+<ul>
+<li>
+Change directory to the isapi plugins source directory.
+</li>
+<li>
+Make the source with MSDEV
+</li>
+</ul>
+<p class="screen"><div align="left"><table width="80%" border="1"
cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000"
align="left"><div class="screen">Change directory to the isapi plugins source
directory</div><code><nobr><em class="screen">c:\></em><b class="screen">cd
c:\home\apache\jk\iis</b></nobr></code><br><div class="screen">Build the
sources using MSDEV</div><code><nobr><em class="screen">c:\></em><b
class="screen">MSDEV isapi.dsp /MAKE
ALL</b></nobr></code><br></td></tr></table></div></p>
+</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 isapi workspace file (isapi.dsw) in msdev
and
+build it using the build menu.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a
name="Troubleshooting"><strong>Troubleshooting</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+It is easy to have the ISAPI redirector not work the first time you try to
install it.
+</p>
+<p>
+If this happens to you, here are some steps to follow to try to correct the
problem.
+</p>
+<p>
+These steps aren't guaranteed to cover all possible problems,
+but they should help find the typical mistakes.
+</p>
+<p>
+If you make any corrections during these steps, restart the IIS service as
described above in the last step
+of the installation, then retry the step.
+</p>
+
+<p>To enable error tracking, make sure web site activity is being logged.
+For PWS 4.0 make sure "Save Web Site Activity Log" is checked in the Advanced
Options of the Personal Web Manager.
+</p>
+
+<p>
+Note: These steps assume your <b>worker_mount_file</b> setting points to an
unmodified copy of the
+<b>uriworkermap.properties</b> file.<br>
+Results may be misleading if <b>worker_mount_file</b> points to a modified
<b>uriworkermap.properties</b>
+or the <b>uriworkermap.properties-auto</b> file.<br>
+It is also assumed that the <b>"/examples" context</b> works correctly if you
access Tomcat directly.
+</p>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Win98"><strong>Win98</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Start the IIS service and Tomcat.
+</p>
+<p>
+Check for the presence of the ISAPI redirector log file you specified in the
log_file setting.
+If not found, verify the following:
+</p>
+<ul>
+<li>
+Check the "Filter DLLs" setting in the
"HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters"
+key and make sure the path is correct.
+</li>
+<li>
+Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software
Foundation\Jakarta Isapi Redirector\1.0" key.
+Case isn't important, but an incorrect letter will prevent the
isapi_redirect.dll from finding its registry settings.
+</li>
+<li>
+Check the log_file setting for typos, name and data. Also insure the directory
in which the log file will appear already exists.
+</li>
+If the above are set correctly, the ISAPI redirector should be able to create
the log file.
+</ul>
+<p>
+Invoke the URL <a
href="http://localhost/examples/jsp/index.html";>http://localhost/examples/jsp/index.html</a>
+in your browser.
+Case is important in Tomcat. The characters following "localhost" in the URL
must be lower case.
+If the page fails to appear, stop the IIS service (required to view the IIS
log file).
+Then examine the last line in the IIS log file in found in
SYSTEM/LogFiles/W3SVC1 :
+</p>
+<p>
+If the last line contains:
+</p>
+<div class="example"><pre>
+ GET "/examples/jsp/index.html HTTP/1.1" 404
+</pre></div>
+<p>
+then the ISAPI redirector is not recognising that it should be handling
requests for the "/examples" context.
+Check the following:
+</p>
+<ul>
+<li>
+Check the extension_uri name for typos.
+</li>
+<li>
+Check the worker_file setting for typos, name and data.
+</li>
+<li>
+Check the worker_mount_file setting typos, name and data.
+</li>
+If these are set correctly, the ISAPI redirector should recognise that it
should handle requests for the "/examples" context.
+</ul>
+
+<p>If the last line contains something like:
+</p>
+
+<div class="example"><pre>
+ GET "/jakarta/isapi_redirect.dll HTTP1.1"
+</pre></div>
+
+<p>
+then the ISAPI redirector is recognising that it should handle the request,
+but is not successful at getting Tomcat to service the request.
+</p>
+
+<p>
+You should check the HTTP error code following GET "/..." :
+</p>
+
+<div class="example"><pre>
+ Error 404
+ GET "/..." 404
+</pre></div>
+
+<ul>
+<li>
+Make sure you entered the URL correctly.
+</li>
+<li>
+Make sure the virtual directory created was called "jakarta".
+It should display in Personal Web Manager as "/jakarta" (without the quotes).
+</li>
+<li>
+Make sure the extension_uri data begins with "/jakarta/" (without the quotes).
+</li>
+</ul>
+
+<div class="example"><pre>
+ Error 500
+ GET "/..." 500
+</pre></div>
+
+<ul>
+<li>
+Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri
setting.
+</li>
+<li>
+Check the workers.properties file and make sure the port setting for
worker.ajp12.port is the same as the port specified in the server.xml for the
"Apache AJP12 support".
+</li>
+</ul>
+
+<div class="example"><pre>
+ Error 200 or 403
+ GET "/..." 200
+ GET "/..." 403
+</pre></div>
+
+<ul>
+<li>
+Make sure you have checked Execute Access
+for the jakarta virtual directory in the Advanced Options of the Personal Web
Manager.
+</li>
+</ul>
+
+<p>
+If the above settings are correct, the index.html page should appear in your
browser.
+You should also be able to click the Execute links to execute the JSP examples.
+</p>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="WinNT/Win2K/WinXP"><strong>WinNT/Win2K/WinXP</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Start the World Wide Web Publishing Service and Tomcat.
+</p>
+<p>
+Check for the presence of the ISAPI redirector log file you specified in the
log_file setting.
+If not found, check the following:
+</p>
+<ul>
+<li>
+Check the "executable" you set for the filter in the IIS Management Console
and make sure the path is correct.
+</li>
+<li>Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software
Foundation\Jakarta Isapi Redirector\1.0" key.
+Case isn't important, but an incorrect letter will prevent the
isapi_redirect.dll from finding its registry settings.
+</li>
+<li>
+Check the log_file setting for typos, name and data. Also insure the directory
in which the log file will appear already exists.
+</li>
+If the above are set correctly, the ISAPI redirector should be able to create
the log file.
+</ul>
+
+<p>
+Check the tomcat filter you added and make sure its status shows a green
upward-pointing arrow.
+If not, check the following:
+</p>
+<ul>
+<li>
+Check the worker_file setting for typos, name and data.
+</li>
+<li>
+Check the worker_mount_file setting typos, name and data.
+</li>
+If the above are set correctly, the green upward-pointing arrow should appear,
even if the other settings are wrong.
+</ul>
+
+<p>
+Invoke the URL <a
href="http://localhost/examples/jsp/index.html";>http://localhost/examples/jsp/index.html</a>
+in your browser. Case is important in Tomcat. The characters following
"localhost" in the URL must be lower case.
+If the page fails to appear, examine the last line in the IIS server log file
in found in SYSTEM32/LogFiles/W3SVC1.
+</p>
+
+<p>
+The last line should contain something like: GET "/jakarta/isapi_redirect.dll
HTTP1.1",
+which indicates the ISAPI redirector is recognising that it should handle the
request.
+</p>
+
+<p>
+You should check the HTTP error code following GET "/..." :
+</p>
+
+<div class="example"><pre>
+ Error 404
+ GET "/..." 404
+</pre></div>
+
+<ul>
+<li>
+Make sure you entered the URL correctly.
+</li>
+</ul>
+
+<div class="example"><pre>
+ Error 500
+ GET "/..." 500
+</pre></div>
+
+<ul>
+<li>
+Make sure the virtual directory created was called "jakarta".
+</li>
+<li>
+Make sure that the extension_uri setting is correct.
+</li>
+<li>
+Check the workers.properties file and make sure the port setting for
worker.ajp12.port is the same as the port specified in the server.xml for the
"Apache AJP12 support".
+</li>
+</ul>
+
+<div class="example"><pre>
+ Error 200 or 403
+ GET "/..." 200
+ GET "/..." 403
+</pre></div>
+
+<ul>
+<li>
+Make sure you have checked Execute Access for the jakarta virtual directory in
the
+Advanced Options of the Personal Web Manager.
+</li>
+</ul>
+
+<p>
+If the above settings are correct, the index.html page should appear in your
browser.
+You should also be able to click the Execute links to execute the JSP examples.
+</p>
+</blockquote></td></tr></table>
+
+
+</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td
colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td
colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/connectors-doc/webserver_howto/iis.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/connectors-doc/webserver_howto/nes.html
URL:
http://svn.apache.org/viewvc/tomcat/site/trunk/docs/connectors-doc/webserver_howto/nes.html?rev=1307873&view=auto
==============================================================================
--- tomcat/site/trunk/docs/connectors-doc/webserver_howto/nes.html (added)
+++ tomcat/site/trunk/docs/connectors-doc/webserver_howto/nes.html Sat Mar 31
18:52:20 2012
@@ -0,0 +1,483 @@
+<html><head><META http-equiv="Content-Type" content="text/html;
charset=iso-8859-1"><title>The Apache Tomcat Connector - Webserver HowTo -
SunOne -- Netscape/iPlanet HowTo</title><meta name="author" value="Henri
Gomez"><meta name="email" value="hgo...@apache.org"><meta name="author"
value="Jim Jagielski"><meta name="email" value="j...@apache.org"><meta
name="author" value="Gal Shachor"><meta name="email"
value="shac...@il.ibm.com"><meta name="author" value="Mladen Turk"><meta
name="email" value="mt...@apache.org"><link href="../style.css" type="text/css"
rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76"
alink="#525D76" vlink="#525D76"><table border="0" width="100%"
cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a
href="http://tomcat.apache.org/";><img src="../images/tomcat.gif" align="left"
alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a
href="http://www.apache.org/";><img src="http://www.apache.org/images/asf-logo.g
if" align="right" alt=" :: Apache Software Foundation"
border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade
size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top"
nowrap="true"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs
Home</a></li></ul><p><strong>Reference Guide</strong></p><ul><li><a
href="../reference/workers.html">workers.properties</a></li><li><a
href="../reference/uriworkermap.html">uriworkermap.properties</a></li><li><a
href="../reference/status.html">Status Worker</a></li><li><a
href="../reference/apache.html">Apache HTTP Server</a></li><li><a
href="../reference/iis.html">IIS</a></li></ul><p><strong>Generic
HowTo</strong></p><ul><li><a href="../generic_howto/quick.html">For the
impatient</a></li><li><a href="../generic_howto/workers.html">All about
workers</a></li><li><a
href="../generic_howto/timeouts.html">Timeouts</a></li><li><a
href="../generic_howto/loadbalancers.html">Load Balancing</a><
/li><li><a href="../generic_howto/proxy.html">Reverse
Proxy</a></li></ul><p><strong>Webserver HowTo</strong></p><ul><li><a
href="../webserver_howto/apache.html">Apache HTTP Server</a></li><li><a
href="../webserver_howto/iis.html">IIS</a></li><li><a
href="../webserver_howto/nes.html">Netscape/SunOne/Sun</a></li></ul><p><strong>AJP
Protocol Reference</strong></p><ul><li><a
href="../ajp/ajpv13a.html">AJPv13</a></li><li><a
href="../ajp/ajpv13ext.html">AJPv13 Extension
Proposal</a></li></ul><p><strong>Miscellaneous
Documentation</strong></p><ul><li><a
href="../miscellaneous/faq.html">Frequently asked questions</a></li><li><a
href="../miscellaneous/changelog.html">Changelog</a></li><li><a
href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&am
p;bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=">Current
Tomcat Connectors bugs</a></li><li><a
href="../miscellaneous/doccontrib.html">Contribute documentation</a></li><li><a
href="../miscellaneous/jkstatustasks.html">JK Status Ant Tasks</a></li><li><a
href="../miscellaneous/reporttools.html">Reporting Tools</a></li><li><a
href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html";>Old
JK/JK2 documentation</a></li></ul><p><strong>News</strong></p><ul><li><a
href="../news/20120301.html">2012</a></li><li><a
href="../news/20110701.html">2011</a></li><li><a
href="../news/20100101.html">2010</
a></li><li><a href="../news/20090301.html">2009</a></li><li><a
href="../news/20081001.html">2008</a></li><li><a
href="../news/20070301.html">2007</a></li><li><a
href="../news/20060101.html">2006</a></li><li><a
href="../news/20050101.html">2005</a></li><li><a
href="../news/20041100.html">2004</a></li></ul></td><!--RIGHT SIDE MAIN
BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%"
cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat
Connector - Webserver HowTo</h1><h2>SunOne -- Netscape/iPlanet
HowTo</h2></td><td align="right" valign="top" nowrap="true"><small><a
href="printer/nes.html"><img src="../images/printer.gif" border="0"
alt="Printer Friendly Version"><br>print-friendly<br>version
+ </a></small></td></tr></table><table border="0"
cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font
color="#ffffff" face="arial,helvetica.sanserif"><a
name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Document Conventions and Assumptions"><strong>Document Conventions and
Assumptions</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+</blockquote></td></tr></table>
+
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Supported Configuration"><strong>Supported
Configuration</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Who support ajp protocols ?"><strong>Who support ajp protocols
?</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+
+</blockquote></td></tr></table>
+
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="How does it work ?"><strong>How does it work
?</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+</blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a
name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a name="Configuring the NSAPI
Redirector"><strong>Configuring the NSAPI
Redirector</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+
+<div class="example"><pre>
+
+ 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"
+</pre></div>
+<ul>
+<li>
+Edit your server <b>obj.conf</b> and add the following lines:
+</li>
+</ul>
+<div class="example"><pre>
+
+
+ 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>
+</pre></div>
+
+<ul>
+<li>
+Edit your worker definition file <b>workers.properties</b>. You should at
least choose a connection pool size:
+</li>
+</ul>
+
+<div class="example"><pre>
+ #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
+</pre></div>
+
+<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>
+<p><font color="#ff0000">
+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.
+</font></p>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Adding additional Contexts"><strong>Adding additional
Contexts</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+
+<div class="example"><pre>
+ NameTrans fn="assign-name" from="/<context name>/*" name="jknsapi"
+</pre></div>
+
+<p>
+After saving <b>obj.conf</b> restart Netscape and it will serve the new
context.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Advanced Context Configuration"><strong>Advanced Context
Configuration</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+
+<div class="example"><pre>
+ NameTrans fn=pfx2dir from=/examples dir="c:/tomcat/webapps/examples"
+</pre></div>
+
+<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>
+
+<div class="example"><pre>
+ 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/.
+</pre></div>
+
+<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>
+
+<div class="example"><pre>
+ 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"
+</pre></div>
+
+<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>
+
+<div class="example"><pre>
+ NameTrans fn="assign-name" from="/examples/servletname" name="jknsapi"
+
+ Instructs Netscape to assign the redirector request whose URL-Path equals
/example/servletname
+</pre></div>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td
bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a
name="Advanced Worker Configuration"><strong>Advanced Worker
Configuration</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+
+<div class="example"><pre>
+ #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
+</pre></div>
+
+<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>
+
+<div class="example"><pre>
+ <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>
+</pre></div>
+
+<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>
+</blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a name="Building NSAPI DLL redirector for
Windows"><strong>Building NSAPI DLL redirector for
Windows</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+<code><nobr><em class="screen">c:\></em><b class="screen">cd
c:\home\apache\jk\nsapi</b></nobr></code><br>
+<notedos>Build the sources using MSDEV</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">MSDEV nsapi.dsp
/MAKE ALL</b></nobr></code><br>
+</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>
+</blockquote></td></tr></table><table border="0" cellspacing="0"
cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff"
face="arial,helvetica.sanserif"><a name="Building NSAPI so plugin redirector
for Unix"><strong>Building NSAPI so plugin redirector for
Unix</strong></a></font></td></tr><tr><td><blockquote>
+<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>
+<code><nobr><em class="screen">c:\></em><b class="screen">cd
/usr/local/src/tomcat-connectors-xxx-src/native</b></nobr></code><br>
+<notedos>configure for Netscape/iPlanet/SunONE webserver</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">./configure
--enable-netscape</b></nobr></code><br>
+<notedos>Change directory to the nsapi netscape directory</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">cd
netscape</b></nobr></code><br>
+<notedos>Set JAVA_HOME (ksh example)</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">export
JAVA_HOME=/path/to/my/java</b></nobr></code><br>
+<notedos>Set SUITSPOT_HOME (ksh example)</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">export
SUITSPOT_HOME=/path/to/my/netscape/server</b></nobr></code><br>
+<notedos>Edit the Makefile</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">vi
Makefile.solaris</b></nobr></code><br>
+<notedos>Make the source with gmake</notedos>
+<code><nobr><em class="screen">c:\></em><b class="screen">gmake -f
Makefile.solaris</b></nobr></code><br>
+</screendos>
+</p>
+<p>
+After the build, you will have the required nsapi_redirector.so plugin.
+</p>
+</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td
colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td
colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/connectors-doc/webserver_howto/nes.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
![http://www.apache.org/images/asf-logo.gif"](http://www.apache.org/images/asf-logo.gif"){kind=link}