You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/25 21:53:01 UTC
svn commit: r1305110 [7/10] - in /tomcat/site/trunk/docs/tomcat-3.3-doc: ./
appdev/ appdev/sample/ appdev/sample/etc/ appdev/sample/lib/
appdev/sample/src/ appdev/sample/web/ appdev/sample/web/images/ images/
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/serverxml.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/style.css
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/style.css?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/style.css (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/style.css Sun Mar 25 19:52:59 2012
@@ -0,0 +1,81 @@
+body {
+ font-family: "Times New Roman", Times, serif;
+ font-style: normal;
+ color: #000000;
+ background-color: #FFFFFF;
+}
+
+h1 {
+ font-family: Arial, Helvetica, sans-serif;
+ color: #0033CC
+}
+
+h2 {
+ font-family: Arial, Helvetica, sans-serif;
+ color: #0033CC
+}
+
+h3 {
+ color: #0033CC
+; font: 110% Arial, Helvetica, sans-serif
+}
+
+b {
+ font-weight: bold;
+}
+
+.code {
+ font-family: Courier, mono;
+}
+
+.codeblock {
+ font-family: Courier, mono;
+}
+
+.navheading {
+ font-family: Arial, Helvetica, sans-serif;
+ font-weight: bold;
+ color: #0033CC
+}
+
+.navitem {
+ font-family: "Times New Roman", Times, serif;
+ margin-left: 10pt;
+ color: #000000
+}
+
+.itemdef {
+ font-family: "Times New Roman", Times, serif;
+ font-size: smaller;
+ color: #000000
+}
+
+.fineprint {
+ font-family: Arial, Helvetica, sans-serif;
+ font-size: smaller;
+ color: #000000
+}
+
+/* Classloader table classes */
+
+.cltable {
+ background-color : #E0E0E0;
+ text-align : center;
+}
+
+.clt_loader {
+ text-align : center;
+ font-weight : bold;
+ color : #0033CC;
+}
+
+.clt_label {
+ text-align : left;
+ font-weight : bolder;
+}
+
+.clt_data {
+ text-align : center;
+ vertical-align : top;
+ font-size : smaller;
+}
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/style.css
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-apache-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-apache-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-apache-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-apache-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,897 @@
+<html>
+ <head>
+ <!-- $Id: tomcat-apache-howto.html,v 1.5 2004/02/29 22:42:50 billbarker Exp $ -->
+<!--
+ 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.
+-->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" href="style.css">
+ <title>Tomcat-Apache HOWTO</title>
+ </head>
+ <body link="#0000ff" vlink="#800080">
+ <!-- Banner element, all hail the Project! -->
+ <table border="0" width="100%" cellspacing="0" cellpadding="0">
+ <tr>
+ <td width="50%">
+ <p align="left">
+ <a href="http://jakarta.apache.org/index.html">
+ <img src="images/banner.gif"
+ width="505"
+ height="48"
+ alt="The Jakarta Project"
+ border="0"></a>
+ </td>
+ <td width="50%">
+ <p align="right"><img border="0" src="images/tomcat.gif" width="100" height="71" alt="The mighty Tomcat - Meow!"></p>
+ </td>
+ </tr>
+ </table>
+
+ <H1>Tomcat-Apache HOWTO</H1>
+
+ <p>This document explains how to connect Tomcat to the popular
+ open source web server, Apache. It was originally part of
+ <i>Tomcat: A Minimalistic User's Guide</i> by Gal Shachor, but
+ has been split off for organizational reasons. It should be
+ considered a <b>work in progress</b>. Since the Tomcat source
+ tree is constantly changing, the information herein may be out
+ of date. The only definitive reference at this point is the <a
+ href="http://jakarta.apache.org/site/sourceindex.html">source
+ code</a>.</p>
+
+ <p>
+ Other important documents: <ul>
+<li><a href="tomcat-ug.html">Tomcat User's Guide</a></li>
+<li><a href="mod_jk-howto.html">mod_jk HOWTO</a> [??? should be rolled into tomcat-apache howto]</li>
+<li><a href="http://jakarta.apache.org/site/faqs.html">Jakarta FAQ Page</a></li>
+</ul>
+
+<p>
+Other Tomcat-Apache HOWTOs: [should be integrated into this one?] <ul>
+<li><a href="http://satori.com/~avm/tomcat.html">Howto Configure Tomcat 3.1 with Apache</a> by Freddie Mendoza
+</li>
+<li><a href="http://www.ccl.net/cca/software/UNIX/apache/index.shtml">Apache Web Server / JServ / Tomcat / SSL Installation on UNIX</a> by Jan K. Labanowski
+</li>
+<li><a href="http://www.oop-reserch.com/tomcat_3_1/">Tomcat and JServ</a> by Jun Inamori
+</li>
+<li><a href="http://www.dmz.hitachi-sk.co.jp/Java/Tech/servlet/tomcat.html">http://www.dmz.hitachi-sk.co.jp/Java/Tech/servlet/tomcat.html</a> in Japanese
+</li>
+</ul>
+</p>
+
+ <h3>Table of Contents</h3>
+ <ul>
+ [write me]
+ </ul>
+
+ <hr size="5">
+ <h3><a name="apache_tomcat_coop">Apache - Tomcat Cooperation - Sample Server
+ Integration</a></h3>
+
+ <p> Up until now we have not discussed Tomcat as a server add on,
+ instead we have considered it as a <a href="tomcat-ug.html#type_1"> stand-alone</a> container and discussed
+ how it can be used. There are however a few problems with this
+ picture:
+ <ol>
+ <li> Tomcat is not as fast as Apache when it comes to static pages. </li>
+ <li> Tomcat is not as configurable as Apache. </li>
+ <li> Tomcat is not as robust as Apache. </li>
+ <li> There are many sites with long time investment in certain web servers,
+ for example, sites that are using CGI scripts/Server API modules/perl/php.
+ We cannot assume that all of them will want to ditch this legacy. </li>
+ </ol>
+
+ <p> For all these reasons it is recommended that real world sites
+ use an industrial strength web server, such as Apache, for serving the static content of
+ the site, and use Tomcat as a Servlet/JSP add-on.</p>
+
+ <p> Our agenda:
+ <ol>
+ <li> Cover the fundamental behavior of the web server. </li>
+ <li> Explain what configuration is needed. </li>
+ <li> Demonstrate this on Apache. </li>
+ </ol>
+
+ <hr size="5">
+ <h3><a name="common_errors">Common Installation and Configuration Problems</a></h3>
+ <blockquote>
+ <p>This section isn't meant to be your one-stop shop for all troubles
+ Tomcat, but a resource for stumbling blocks common to many first-time
+ Tomcat'ers. See the <a href="tomcat-ug.html#where_help">help section</a> for
+ additional links.</p>
+ </blockquote>
+ <h4> <a name="error_8007">http://webserver:8007/ gives a
+ 500</a></h4>
+ <blockquote>
+ <p>This is what you should see in your tomcat.log file:</p>
+ <blockquote>
+ <p class="code">HANDLER THREAD PROBLEM: java.io.IOException: Stream
+ broken</p>
+ </blockquote>
+ <p>By default, Tomcat listens for AJP connections on port 8007. AJP
+ is the protocol used to communicate between the web server and Tomcat, <b>not</b>
+ Tomcat and your browser. To test your Tomcat installation, FIX ME ?</p>
+ </blockquote>
+ <h4> <a name="error_ignore_directives"><Directory>
+ and <Location> directives ignored</a></h4>
+ <blockquote>
+ <p>FIX ME Apache never applies because forwarded to Tomcat.</p>
+ </blockquote>
+ <h4> <a name="error_web_server">Web server won't start
+ when Tomcat is running</a></h4>
+ <blockquote>
+ <p>FIX ME Port conflict.</p>
+ </blockquote>
+ <h4> <a name="error_bad_command">"Bad command or
+ filename" when executing Tomcat scripts</a></h4>
+ <blockquote>
+ <p>[FIX ME] UNIX file format on DOS. Because Tomcat is developed on
+ *nix (rather, the jars are built and distributed there), you may have to
+ convert the files to PC (versus UNIX) format.</p>
+ </blockquote>
+
+ <hr size="5">
+ <h3> Starting Tomcat From Another Directory </h3>
+
+ <h2>Setting Tomcat to Cooperate with the Apache Web Server </h2>
+
+ <h3> Web Server Operation </h3>
+ <p> In a nutshell a web server is waiting for client HTTP requests.
+ When these requests arrive the server does whatever is needed to
+ serve the requests by providing the necessary content. Adding a
+ servlet container may somewhat change this behavior. Now the web
+ server needs also to perform the following:
+ <ul>
+ <li> Load the servlet container adapter library and initialize it (prior
+ to serving requests). </li>
+ <li> When a request arrives, it needs to check and see if a certain
+ request belongs to a servlet, if so it needs to let the adapter
+ take the request and handle it.</li>
+ </ul>
+
+ The adapter on the other hand needs to know what requests it is
+ going to serve, usually based on some pattern in the request URL, and to
+ where to direct these requests.
+
+ <p>
+ Things are even more complex when the user wants to set a configuration
+ that uses virtual hosts, or when they want multiple developers to work
+ on the same web server but on different servlet container JVMs. We
+ will cover these two cases in the advanced sections.
+ </p>
+
+ <h3> What is the Needed Configuration </h3>
+ <p> The most obvious configuration that one can think of is the identity of the servlet URLs
+ that are under the responsibility of the servlet container. This is clear; someone must
+ know what requests to transmit to the servlet container...
+ Yet there are additional configuration items that we should provide to
+ the web-server/servlet-container combination:
+ <ul>
+ <li>We also need to provide configuration regarding the available Tomcat processes
+ and on which TCP/IP host/port they are listening. </li>
+ <li> We need to tell the web server the location of the adapter library (so it
+ will be able to load it on startup). </li>
+ <li> We need to set adapter internal information such as where and how much to log, etc. </li>
+ </ul>
+ All this information must appear either in the web server configuration, or in a private
+ configuration files used by the adapter. The next section will demonstrate how configuration
+ can be implemented on Apache.
+
+
+ <h3> Making it on Apache </h3>
+ <p> This section shows you how to configure Apache to work with Tomcat;
+ it tries to provide explanations as well as insight for the
+ configuration directives that you should use. You can find
+ additional information in the
+ <a href="http://java.apache.org/jserv/install/index.html">
+ jserv install page </a>.
+ </p>
+
+ <p> When Tomcat starts up it will automatically generate a configuration
+ file for Apache in <tt>TOMCAT_HOME/conf/jserv/tomcat-apache.conf</tt>. Most
+ of the time you don't need to do anything but include this file
+ (appending "Include TOMCAT_HOME/conf/jserv/tomcat-apache.conf") in your
+ httpd.conf. If you have special needs, for example an AJP port other
+ the 8007, you can use this file as a base for your customized
+ configuration and save the results in another file. If you manage
+ the Apache configuration yourself you'll need to update it whenever
+ you add a new context.
+ </p>
+ <p>
+ <b>Tomcat:</b> you must restart tomcat and apache after adding
+ a new context; Apache doesn't support configuration changes without a
+ restart. Also the file <tt>TOMCAT_HOME/conf/jserv/tomcat-apache.conf</tt> is
+ generated when tomcat starts, so you'll need to start Tomcat before
+ Apache. Tomcat will overwrite <tt>TOMCAT_HOME/conf/tomcat-apache.conf</tt>
+ each startup so customized configuration should be kept elsewhere.
+ </p>
+
+ <p> The Apache-Tomcat configuration uses Apache core configuration directives
+ as well as Jserv unique directives so it may confuse you at first, there are
+ however two things simplifying it:
+ <ul>
+ <li> In general you can distinguish between the two directive
+ "families" by noting that all the Jserv unique directives start
+ with an "ApJServ" prefix. </li>
+ <li> The entire Tomcat related configuration is concentrated in a
+ single configuration file named tomcat.conf, or the automatically
+ generated tomcat-apache.conf, so you can look at a single file.
+ </li>
+ </ul>
+ Lets look now at a sample tomcat.conf file.
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom">
+ <em>A Minimalistic Apache-Tomcat Configuration </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+###########################################################
+# A minimalistic Apache-Tomcat Configuration File #
+###########################################################
+
+# Note: this file should be appended or included into your httpd.conf
+
+# (1) Loading the jserv module that serves as Tomcat's apache adapter.
+LoadModule jserv_module libexec/mod_jserv.so
+
+# (1a) Module dependent configuration.
+<IfModule mod_jserv.c>
+
+# (2) Meaning, Apache will not try to start Tomcat.
+ApJServManual on
+# (2a) Meaning, secure communication is off
+ApJServSecretKey DISABLED
+# (2b) Meaning, when virtual hosts are used, copy the mount
+# points from the base server
+ApJServMountCopy on
+# (2c) Log level for the jserv module.
+ApJServLogLevel notice
+
+# (3) Meaning, the default communication protocol is ajpv12
+ApJServDefaultProtocol ajpv12
+# (3a) Default location for the Tomcat connectors.
+# Located on the same host and on port 8007
+ApJServDefaultHost localhost
+ApJServDefaultPort 8007
+
+# (4)
+ApJServMount /examples /root
+# Full URL mount
+# ApJServMount /examples ajpv12://hostname:port/root
+</IfModule>
+ </pre>
+ </td>
+ </tr>
+ </table>
+ <p>As you can see the configuration process was split into 4 steps
+ that will now be explained:
+ <ol>
+ <li> In this step we instruct Apache to load the jserv
+ shared-object (or the NT world dll). This is a well known Apache
+ directive. If the loading went well and the module came from a
+ file named mod_jserv.c (1a) we can start with the rest of the
+ Jserv-Tomcat configuration. </li>
+ <li> This step sets various Jserv internal parameters, these
+ parameters:
+ <ul>
+ <li> Instruct jserv not to start the Tomcat process. Automatically
+ starting Tomcat is not implemented yet.</li>
+ <li> Disable the secret key challenge/response between Apache and Tomcat.
+ Again, the secret key work is not implemented yet.</li>
+ <li> Instruct jserv to copy the base server mount points (see next
+ section) in case of virtual hosting. </li>
+ <li> Instruct jserv to use the notice log level. Other log levels
+ include emerg, alert, crit, error, warn, info and debug.</li>
+ </ul>
+ </li>
+ <li> This step sets the default communication parameters.
+ Basically it says that the default protocol used for the communication
+ is ajpv12 (do not mess with this one) and that the Tomcat process runs on
+ the same machine and listens on port 8007. If you run Tomcat on a
+ machine other than the one used
+ for Apache you should either update your ApJServDefaultHost or use a full
+ URL when mounting contexts (see next). Also, if you configured the Tomcat
+ connectors to use a port other then 8007, you should update your
+ ApJServDefaultPort or use a full URL when mounting contexts.
+ </li>
+ <li> This step mounts a context to Tomcat. Basically it says that
+ all the web server paths that start with /examples go to Tomcat. This
+ ApJServMount example is a rather simple one, in fact ApJServMount can
+ also provide information regarding the communication protocol to be used
+ and the location where the Tomcat process listens, for example:
+ <div><tt>ApJServMount /examples ajpv12://hostname:port/root</tt></div>
+ mounts the context /examples to a Tomcat process that runs on host
+ "hostname" and listens on port number "port".
+ </li>
+ </ol>
+ Now that you understand the different configuration instructions in the sample
+ file, how can you add it to the Apache configuration? One "simple" method is to
+ write it's content in the httpd.conf (the Apache configuration file), this however
+ can be very messy. Instead you should use the Apache include directive. At the end
+ of the Apache configuration file (httpd.conf) add the following directive:
+ <div> <tt>include <full path to the Tomcat configuration file> </tt></div>
+ for example:
+ <div> <tt>include /tome/tomcat/conf/tomcat.conf </tt></div> This
+ will add your Tomcat configuration to Apache, after that you should copy
+ the jserv module to the Apache libexec (or modules in the Win32 case)
+ directory and restart (stop+start) Apache. It should now be able to
+ connect to Tomcat.
+
+ <h3> Obtaining the Jserv Module (mod_jserv) </h3>
+ <p> As previously stated, we need a web server adapter to sit in Apache and redirect
+ requests to Tomcat. For Apache, this adapter is a slightly modified version of
+ mod_jserv.
+ </p>
+ <p> You may try to look <a href="http://jakarta.apache.org/site/binindex.html">
+ here </a> and see if there is an already pre-built version of mod_jserv that
+ suites your OS (Usually there is one for NT), however, being a native library you
+ should not expect that yet (too many OS's, not enough developers, life
+ too short...).
+ Moreover, small variations in the way you built Apache/Your specific UNIX variant may
+ result in dynamic linking errors. You should really try to build mod_jserv for your
+ system (don't panic, it is not that hard!).
+ </p>
+ <p>
+ Building mod_jserv on <b>UNIX</b> involves the following:
+ <ol>
+ <li> Download the source distribution of Tomcat from
+ <a href="http://jakarta.apache.org/site/sourceindex.html"> here</a>. </li>
+ <li> Uncompress it into some directory. </li>
+ <li> Building the module:
+ <ul>
+ <li> Change directory into jakarta-tomcat/src/native/apache/jserv/</li>
+ <li> Execute the build command <div><tt> apxs -c -o mod_jserv.so *.c </tt></div>
+ apxs is part of the Apache distribution and should be located in your
+ APACHE_HOME/bin.</li>
+ </ul>
+ </li>
+ </ol>
+ Building mod_jserv for <b>Win32</b> is less likely (you already have a downloadable dll
+ for Win32). Yet if you <em>want</em> to build it you should install Visual C++ and
+ perform the following:
+ <ol>
+ <li> Download the source distribution of Tomcat from
+ <a href="http://jakarta.apache.org/site/sourceindex.html"> here</a>. </li>
+ <li> Unzip it into some directory. </li>
+ <li> Building the module:
+ <ul>
+ <li> Change directory into jakarta-tomcat\src\native\apache\jserv</li>
+ <li> Add Visual C++ into your environment by executing the script
+ VCVARS32.BAT. </li>
+ <li> Execute the build command <div><tt> nmake -f Makefile.win32 </tt></div>
+ nmake is the Visual C++ make program.</li>
+ </ul>
+ </li>
+ </ol>
+ That's it; you have built mod_jserv...
+ <h3> Making Apache Serve your Context's Static Files </h3>
+ <p> The previous Apache-Tomcat configuration file was somewhat
+ inefficient, it instructed Apache to send any request for a resource
+ that starts with the <tt>/examples</tt> prefix to be served by
+ Tomcat. Do we really want that? There are many static files that may
+ be a part of our servlet context (for example images and static
+ HTML), why should Tomcat serve these files?
+ </p>
+ <p>You may actually have reasons for doing that, for example:
+ <ol>
+ <li>You may want to configure Tomcat based security for these
+ resources. </li>
+ <li>You may want to follow users requests for static resources
+ using interceptors. </li>
+ </ol>
+ In general however, this is not that case; and making Tomcat save
+ static files is just a CPU waste. We should instead have Apache serve
+ these static files and not Tomcat. Lets look now at a sample
+ tomcat.conf file that does exactly that:
+ <p> Having Apache serve the static files requires the following:
+ <ol>
+ <li>Instructing Apache to send all servlet requests to Tomcat. </li>
+ <li>Instructing Apache to send all JSP requests to Tomcat. </li>
+ </ol>
+ and leaving Apache to handle the rest. Lets look now at a sample
+ tomcat.conf file that does exactly that:
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom">
+ <em>Apache-Tomcat Configuration where Apache Serves the Static Content</em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+######################################################################
+# Apache-Tomcat Smart Context Redirection #
+######################################################################
+LoadModule jserv_module modules/ApacheModuleJServ.dll
+<IfModule mod_jserv.c>
+ApJServManual on
+ApJServDefaultProtocol ajpv12
+ApJServSecretKey DISABLED
+ApJServMountCopy on
+ApJServLogLevel notice
+
+ApJServDefaultHost localhost
+ApJServDefaultPort 8007
+
+#
+# Mounting a single smart context:
+#
+# (1) Make Apache know about the context location.
+Alias /examples D:\tomcat\webapps\examples
+# (2) Optional, customize Apache context service.
+<Directory "D:\tomcat\webapps\examples">
+ Options Indexes FollowSymLinks
+# (2a) No directory indexing for the context root.
+# Options -Indexes
+# (2b) Set index.jsp to be the directory index file.
+# DirectoryIndex index.jsp
+</Directory>
+# (3) Protect the WEB-INF directory from tampering.
+<Location /examples/WEB-INF/>
+ AllowOverride None
+ deny from all
+</Location>
+# (4) Instructing Apache to send all the .jsp files under the context to the
+# jserv servlet handler.
+<LocationMatch /examples/*.jsp>
+ SetHandler jserv-servlet
+</LocationMatch>
+# (5) Direct known servlet URLs to Tomcat.
+ApJServMount /examples/servlet /examples
+
+# (6) Optional, direct servlet only contexts to Tomcat.
+ApJServMount /servlet /ROOT
+</IfModule>
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ As you can see, the beginning of this configuration file is the same
+ as seen in the previous example. The last step (mounting a context),
+ however, was replaced in a long series of Apache and ApJServ
+ configuration directives that will now be explained:
+ <ol>
+ <li> This step informs Apache of the context location and aliases it
+ to an Apache virtual directory. This way Apache can serve files
+ from this directory.</li>
+ <li> This optional step instructs Apache more about how to serve the
+ context; for example you can decide if Apache will allow
+ directory indexing (listing) or set a special index file.</li>
+ <li> This step instructs Apache to protect the WEB-INF directory
+ from client access. For security reasons it is important to
+ prevent visitors from viewing the content of the WEB-INF
+ directory, for example web.xml can provide valuable information
+ for intruders. This step blocks the WEB-INF content from
+ visitors. </li>
+ <li> This step instructs Apache to serve all the jsp locations
+ within the context using the jserv servlet handler. The servlet
+ handler redirects these requests based on the default host and
+ port.</li>
+ <li> This step mounts specific servlet URLs to Tomcat. You should
+ note that you should have as many such mount directives as the
+ number of specific servlet URLs. </li>
+ <li> This last step is an example for the addition of servlet only
+ context to Tomcat. </li>
+ </ol>
+
+ It is easy to see that this configuration is much more complex and
+ error prone then the first example, this however is the price that you
+ should (for now) pay for improved performance.
+
+ <h3> Configuring for Multiple Tomcat JVMs </h3>
+ <p>
+ Sometimes it is useful to have different contexts handled by
+ different JVMs, for example:
+ <ul>
+ <li> When each context serves a different, specific task and runs
+ on a different machine. </li>
+ <li> When we want to have multiple developers work on a private
+ Tomcat process but use the same web server. </li>
+ </ul>
+ Implementing such schemes where different contexts are served by
+ different JVMs is very easy and the following configuration file
+ demonstrates this:
+ <p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em>Apache-Tomcat Configuration with per Context JVM </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+######################################################################
+# Apache-Tomcat with JVM per Context #
+######################################################################
+LoadModule jserv_module modules/ApacheModuleJServ.dll
+<IfModule mod_jserv.c>
+ApJServManual on
+ApJServDefaultProtocol ajpv12
+ApJServSecretKey DISABLED
+ApJServMountCopy on
+ApJServLogLevel notice
+
+ApJServDefaultHost localhost
+ApJServDefaultPort 8007
+
+# Mounting the first context.
+ApJServMount /joe ajpv12://joe.corp.com:8007/joe
+
+# Mounting the second context.
+ApJServMount /bill ajpv12://bill.corp.com:8007/bill
+</IfModule>
+ </pre>
+ </td>
+ </tr>
+ </table>
+ <p>
+ As you can see in the previous example, using several JVMs (even even
+ those that run on different machines) can be accomplished easily by
+ using a full ajp URL mount. In this full URL we actually specify the
+ host where the Tomcat process is located and it's port.
+ </p>
+ <p>
+ Had the two Tomcat processes run on the same machine, we would have to
+ configure each of them with different connector ports. For example,
+ assuming that the two JVMs runs on localhost, the Apache-Tomcat
+ configuration should have something that looks like:
+ </p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> Same Machine Multiple JVM Apache-Tomcat Configuration </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+######################################################################
+# Apache-Tomcat with Same Machine JVM per Context #
+######################################################################
+LoadModule jserv_module modules/ApacheModuleJServ.dll
+<IfModule mod_jserv.c>
+ApJServManual on
+ApJServDefaultProtocol ajpv12
+ApJServSecretKey DISABLED
+ApJServMountCopy on
+ApJServLogLevel notice
+
+ApJServDefaultHost localhost
+ApJServDefaultPort 8007
+
+# Mounting the first context.
+ApJServMount /joe ajpv12://localhost:8007/joe
+
+# Mounting the second context.
+ApJServMount /bill ajpv12://localhost:8009/bill
+</IfModule>
+ </pre>
+ </td>
+ </tr>
+ </table>
+ <p>
+ Looking at the above file you can see that we have two explicit ApJServ
+ mount points each pointing to a different port on the same machine. It
+ is clear that this configuration requires support from the configuration
+ found in the server.xml files. We will need in these files different
+ <Connector> configurations, for the different Tomcat processes. We
+ will actually need two different server.xml files (lets call them
+ server_joe.xml and server_bill.xml) with different <Connector>
+ entries as shown in the next two samples:
+ </p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> Joe's server.xml file </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<Server>
+ <!-- Debug low-level events in XmlMapper startup -->
+ <xmlmapper:debug level="0" />
+
+ <!-- @@@
+ Note, the log files are suffixed with _joe to distinguish
+ them from the bill files.
+ -->
+
+ <Logger name="tc_log"
+ path="logs/tomcat_joe.log"
+ customOutput="yes" />
+
+ <Logger name="servlet_log"
+ path="logs/servlet_joe.log"
+ customOutput="yes" />
+
+ <Logger name="JASPER_LOG"
+ path="logs/jasper_joe.log"
+ verbosityLevel = "INFORMATION" />
+
+ <!-- @@@
+ Note, the work directory is suffixed with _joe to distinguish
+ it from the bill work directory.
+ -->
+ <ContextManager debug="0" workDir="work_joe" >
+ <!-- Context level Setup -->
+ <ContextInterceptor
+ className="org.apache.tomcat.context.AutoSetup" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.DefaultCMSetter" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.WorkDirInterceptor" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.WebXmlReader" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
+ <!-- Request processing -->
+ <RequestInterceptor
+ className="org.apache.tomcat.request.SimpleMapper" debug="0" />
+ <RequestInterceptor
+ className="org.apache.tomcat.request.SessionInterceptor" />
+ <RequestInterceptor
+ className="org.apache.tomcat.request.SecurityCheck" />
+ <RequestInterceptor
+ className="org.apache.tomcat.request.FixHeaders" />
+
+ <!-- @@@ This connector uses port number 8007 for it's ajp communication -->
+ <Connector
+ className="org.apache.tomcat.service.SimpleTcpConnector">
+ <Parameter
+ name="handler"
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ <Parameter name="port" value="8007"/>
+ </Connector>
+
+ <!-- @@@ the /jow context -->
+ <Context path="/joe" docBase="webapps/joe" debug="0" reloadable="true" >
+ </Context>
+ </ContextManager>
+</Server>
+ </pre>
+ </td>
+ </tr>
+ </table>
+ <p>
+ When looking at server_joe.xml you can see that the
+ <Connector> is configured for port 8007. In server_bill.xml
+ (see next) on the other hand the <Connector> is configured for
+ port 8009.
+ </p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> Bill's server.xml file </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<Server>
+ <!-- Debug low-level events in XmlMapper startup -->
+ <xmlmapper:debug level="0" />
+
+ <!-- @@@
+ Note, the log files are suffixed with _bill to distinguish
+ them from the joe files.
+ -->
+
+ <Logger name="tc_log"
+ path="logs/tomcat_bill.log"
+ customOutput="yes" />
+
+ <Logger name="servlet_log"
+ path="logs/servlet_bill.log"
+ customOutput="yes" />
+
+ <Logger name="JASPER_LOG"
+ path="logs/jasper_bill.log"
+ verbosityLevel = "INFORMATION" />
+
+ <!-- @@@
+ Note, the work directory is suffixed with _bill to distinguish
+ it from the joe work directory.
+ -->
+ <ContextManager debug="0" workDir="work_bill" >
+ <!-- Context level Setup -->
+ <ContextInterceptor
+ className="org.apache.tomcat.context.AutoSetup" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.DefaultCMSetter" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.WorkDirInterceptor" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.WebXmlReader" />
+ <ContextInterceptor
+ className="org.apache.tomcat.context.LoadOnStartupInterceptor" />
+ <!-- Request processing -->
+ <RequestInterceptor
+ className="org.apache.tomcat.request.SimpleMapper" debug="0" />
+ <RequestInterceptor
+ className="org.apache.tomcat.request.SessionInterceptor" />
+ <RequestInterceptor
+ className="org.apache.tomcat.request.SecurityCheck" />
+ <RequestInterceptor
+ className="org.apache.tomcat.request.FixHeaders" />
+
+ <!-- @@@ This connector uses port number 8009 for it's ajp communication -->
+ <Connector className="org.apache.tomcat.service.SimpleTcpConnector">
+ <Parameter
+ name="handler"
+ value="org.apache.tomcat.service.connector.Ajp12ConnectionHandler"/>
+ <Parameter name="port" value="8009"/>
+ </Connector>
+
+ <!-- @@@ the /bill context -->
+ <Context path="/bill" docBase="webapps/bill" debug="0" reloadable="true" >
+ </Context>
+ </ContextManager>
+</Server>
+ </pre>
+ </td>
+ </tr>
+ </table>
+ <p>
+ The port configuration is not the only place where the joe and bill
+ configuration differs. We have @@@ marks in the xml files marking
+ the four places where changes had to be made. As you can see, this
+ difference is necessary to avoid the two Tomcat processes from
+ overwriting each other's logs and workspace.
+ </p>
+ <p>
+ Then we should start the two tomcat processes using the -f command
+ line option:
+ <div> bin\starup -f conf\server_joe.xml</div>
+ <div> bin\starup -f conf\server_bill.xml</div>
+ and then access them from Apache based on the different URL path
+ prefixes.
+
+ <h3> Configuring Virtual Hosting </h3>
+ <p>
+ It is possible to support virtual hosts under Tomcat Ver3.1, in fact
+ the virtual host configuration is very similar to configuring for
+ multiple JVM (as explained in the previous section) and the reason
+ is simple; in Tomcat 3.1 each virtual host is implemented by a
+ different Tomcat process.
+ </p>
+
+ <p>
+ With the current (Ver3.1) Tomcat, virtual hosting awareness is
+ provided by the web server (Apache/Netscape
). The web server
+ virtual hosting support is used by the Tomcat adapter to
+ redirect requests belonging to a certain virtual host to the JVM(s)
+ containing the contexts of this virtual host. This means that if (for
+ example) we have two virtual hosts (vhost1 and vhost2), we will have
+ two JVMs: one running the contexts of vhost1 and the other running
+ the contexts of vhost2. These JVMs are not aware of each others
+ existence, in fact, they are not aware of the concept of virtual
+ hosting. All the virtual hosting logic is inside the web-server
+ adapter. To make things clearer, lets look at the following sample
+ Apache-Tomcat configuration file:
+ </p>
+
+ <p>
+ <table border="1"
+ cellspacing="0"
+ cellpadding="0"
+ valign="middle">
+ <caption valign="bottom" width="100%">
+ <em> Apache-Tomcat Configuration with Virtual Hosts Support </em>
+ </caption>
+ <tr>
+ <td bgcolor="#c0c0c0">
+ <pre>
+######################################################################
+# Apache Tomcat Virtual Hosts Sample Configuration #
+######################################################################
+LoadModule jserv_module modules/ApacheModuleJServ.dll
+<IfModule mod_jserv.c>
+ApJServManual on
+ApJServDefaultProtocol ajpv12
+ApJServSecretKey DISABLED
+ApJServMountCopy on
+ApJServLogLevel notice
+
+ApJServDefaultHost localhost
+ApJServDefaultPort 8007
+
+# 1 Creating an Apache virtual host configuration
+NameVirtualHost 9.148.16.139
+
+# 2 Mounting the first virtual host
+<VirtualHost 9.148.16.139>
+ServerName www.vhost1.com
+ApJServMount /examples ajpv12://localhost:8007/examples
+</VirtualHost>
+
+# 3 Mounting the second virtual host
+<VirtualHost 9.148.16.139>
+ServerName www.vhost2.com
+ApJServMount /examples ajpv12://localhost:8009/examples
+</VirtualHost>
+</IfModule>
+ </pre>
+ </td>
+ </tr>
+ </table>
+
+ <p>
+ As can be seen, steps 1,2 and 3 define two Apache virtual hosts and
+ for each of them, mount the /examples context to a certain ajpv12 URL.
+ Each such ajpv12 URL points to a JVM that contains the virtual host.
+ The configuration of the two JVMs is very similar to the one
+ demonstrated in the previous section, we will need again to use two
+ different server.xml files (one for each virtual host process) and
+ we will need to start the Tomcat processes with the -f command line
+ option. After doing that we will be able to approach Apache, each
+ time with a different host name, and the adapter will redirect us to
+ the appropriate JVM.
+ </p>
+ <p>
+ <strong><u>The need for improved virtual host support</u></strong><br>
+ Having each virtual host implemented by a different JVM is a huge
+ scalability problem. The next versions of Tomcat will make it
+ possible to support several virtual hosts within the same Tomcat
+ JVM.
+ </p>
+
+ <a name="credits">
+ <h2>Credits</h2>
+
+ <p> This document was created by
+ <a href="mailto:shachor@il.ibm.com"> Gal Shachor</a>. It was split
+ off into a separate document and revised by Alex Chaffee and Rob
+ Slifka.
+ </ul>
+ With help from (in alphabetical order):
+ <ul>
+ Jonathan Bnayahu<br>
+ Alex Chaffee<br>
+ Fiona Czuczman<br>
+ Costin Manolache<br>
+ Rob Slifka<br>
+ </ul>
+ </p>
+
+ <table width="100%" border="0" cellpadding="10" cellspacing="0">
+ <tr>
+ <td>
+ <p class="fineprint">
+ Copyright ©1999-2001 The Apache Software Foundation<br>
+ <a href="http://jakarta.apache.org/legal.html">Legal Stuff They Make Us Say</a><br>
+ <a href="http://jakarta.apache.org/contact.html">Contact Information</a> </p>
+ </td>
+ </tr>
+ </table>
+
+ </body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-apache-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-iis-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-iis-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-iis-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-iis-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,601 @@
+<html>
+<head>
+ <!-- $Id: tomcat-iis-howto.html,v 1.8 2004/02/29 22:42:50 billbarker Exp $ -->
+<!--
+ 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.
+-->
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <link rel="stylesheet" href="style.css">
+ <title>Tomcat IIS HowTo</title>
+</head>
+
+<body>
+
+<h1>Tomcat IIS HowTo</h1>
+
+<p>By Gal Shachor <tt><shachor@il.ibm.com></tt></p>
+
+<p>This document explains how to set up IIS to cooperate with Tomcat.
+Normally IIS can not execute Servlets and Java Server Pages (JSPs),
+configuring IIS to use the Tomcat redirector plugin will let IIS send servlet
+and JSP requests to Tomcat (and this way, serve them to clients). </p>
+
+<h2>Document Conventions and Assumptions</h2>
+
+<p><tomcat_home> is the root directory of tomcat. Your Tomcat
+installation should have the following subdirectories:</p>
+
+<ol>
+ <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 may place web server plugins </li>
+</ol>
+
+<p>In all the examples in this document <tomcat_home> will be c:\jakarta-tomcat.</p>
+
+<p>A <tt>worker</tt> is defined to be a tomcat process that accepts work from the IIS
+server.</p>
+
+<h2>Supported Configuration</h2>
+
+<p>The IIS-Tomcat redirector was developed and tested on:</p>
+
+<ol>
+ <li>Win2k SP2, WinNT4.0-i386 SP4/SP5/SP6a, and Win98 </li>
+ <li>IIS 5.0, PWS 5.0, IIS4.0 and PWS4.0 </li>
+ <li>Tomcat3.0 - Tomcat3.3</li>
+</ol>
+
+<p><b>Note:</b> Due to some feature additions, the IIS-Tomcat redirector from
+earlier Tomcat's can't be used with Tomcat 3.3. Only use the IIS-Tomcat
+redirector from Tomcat 3.3, or newer versions from the jakarta-tomcat-connectors
+Jakarta project.</p>
+
+<p>The redirector uses <b>ajp13</b> or <b>ajp12</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 <a href="in-process-howto.html">in process
+ howto.</a></p>
+
+<h2>Installation</h2>
+
+<p>As of Tomcat 3.2, a pre-built version of the Tomcat redirector plugin,
+<tt>isapi_redirect.dll</tt>, is available under the win32/i386 directory where you
+downloaded the <a href="http://jakarta.apache.org/site/binindex.html">
+Tomcat binary distribution.</a> 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.</p>
+
+<p>You can also build a copy locally from the source in Tomcat's source
+distribution.</p>
+
+<p>The Tomcat redirector requires three entities:</p>
+
+<ol>
+ <li>isapi_redirect.dll - The Tomcat redirector 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 <tt>workers.properties</tt> can
+ be found under the <tt>conf/jk</tt> directory. </li>
+ <li>uriworkermap.properties - A file that maps URL-Path patterns to
+ workers. A sample <tt>uriworkermap.properties</tt> can be found under the
+ <tt>conf/jk</tt> directory as well. Also, this is one of the files generated
+ by the <a href="serverxml.html#IISConfig">IISConfig</a> module included by
+ default in the <code>server.xml</code> file. The
+ <code>uriworkermap.properties</code> file it generates is written to the
+ <code>conf/auto</code> directory.</li>
+</ol>
+
+<p>The installation includes the following parts:</p>
+
+<ol>
+ <li>Start Tomcat 3.3 with the "jkconf" specified so configuration
+ files are written.</li>
+ <li>Configure the Tomcat redirector plugin with the configuration files and
+ check that you can serve servlets and JSPs with IIS.</li>
+ <li>Repeat the appropriate portions of the previous steps when changes to
+ configuration or contexts occur.</li>
+</ol>
+
+<h3>Creating the Configuration Files</h3>
+
+<p>The default installation of Tomcat 3.3 includes the
+<a href="serverxml.html#IISConfig">IISConfig</a> module in the
+<code>server.xml</code> file. This module is responsible for writting the
+configuration files used for Tomcat redirector plugin installation and operation.</p>
+
+<p>In Tomcat 3.3, configuration files are written on demand. You must start
+Tomcat 3.3 with the "jkconf" option specified. Tomcat 3.3 will
+initialize, write the configuration files, and then exit. This may be done,
+while an instance of Tomcat 3.3 is running. This differs from prior versions
+of Tomcat where the configuration files are written each time Tomcat is
+started.</p>
+
+<p>The IISConfig module in Tomcat 3.3 writes two configuration files. The first
+is the registry configuration file, which by default will be
+<code>conf/auto/iis_redirect.reg</code>. The second is the worker map
+configuration file, which by default will be
+<code>conf/auto/uriworkermap.properties</code>.</p>
+
+<p>The IISConfig module in Tomcat 3.3.1 writes a third configuration file. This
+file contains the same settings as the registry configuration file and
+provides an alternate means of configuring the Tomcat redirector plugin
+without relying on the registry. It defaults to writing
+<code>conf/auto/isapi_redirect.properties</code>.</p>
+
+<p>To use the "properties" file instead of registry settings,
+the "properties" file must have the same name as the redirector
+plugin DLL, except with a ".properties" extension. It must also be
+located in the same directory as the DLL. If both the "properties"
+file and registry settings exist, the "properties" file will be
+used.</p>
+
+<h3>Configuring the ISAPI Tomcat Redirector</h3>
+
+<p>The following steps show how to configure the Tomcat redirector plugin.</p>
+
+<ol>
+ <li>Build or download the Tomcat redirector plugin DLL,
+ <code>isapi_redirect.dll</code>, and place it in a suitable location.
+ A typical location is <code>TOMCAT_HOME\bin\native</code>. If you are
+ installing on WinNT or Win2k, make sure IIS runs with a user that can
+ access this directory.<br>
+ <br></li>
+ <li>Use either of the following two methods to provide configuration settings
+ to the redirector plugin DLL.<br>
+ <br>
+ <ol type="a">
+ <li>Copy the <code>IISConfig</code> generated "proprties" file,
+ <code>isapi_redirect.properties</code>, or a manually created one,
+ to the directory where the redirector plugin DLL is found. Rename this
+ file to have the same base name as the redirector plugin DLL should they
+ happen to be different.</li>
+ <li>Enter the registry settings from the registry configuration file into
+ the registry. This can be done from Windows Explorer by double-clicking
+ the file or by right-clicking the file and selecting <code>Open</code>
+ or <code>Merge</code>.</li>
+ </ol>
+ <b>Note:</b> If both are done, the "properties" file takes
+ priority.<br>
+ <br></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 <b>jakarta</b>.
+ Its physical path should be the directory where you placed the redirector
+ plugin DLL, <code>isapi_redirect.dll</code>
+ (for example c:\jakarta-tomcat\bin\native). While creating this new
+ virtual directory, assign it with execute access.<br>
+ <br></li>
+ <li>Add the redirector plugin DLL, <code>isapi_redirect.dll</code>, as a
+ filter to your IIS/PWS web site. The name of the filter should reflect its task
+ (for example, "Jakarta Redirector"). Its executable must be the
+ redirector plugin DLL, <code>isapi_redirect.dll</code>.<br>
+ <br>
+ On WinNT and Win2k, you can use the IIS Management console to add the filter.<br>
+ <br>
+ For PWS on Win98, you'll need to use regedit and add/edit the
+ "Filter DLLs" key under
+ <code>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters.</code>
+ This key contains a comma separated list of dlls ( full paths ). You need to
+ add the full path to redirector plugin DLL, isapi_redirect.dll, to this key.<br>
+ <br></li>
+ <li>Restart IIS/PWS (stop + start the IIS service). If you are using WinNT
+ or Win2k, you can make sure that the jakarta filter is successfully loaded
+ by checking for a green up-pointing arrow.<br>
+ <br>
+ On Win98, to properly stop and restart PWS, you should open an MS-DOS window,
+ navigate to the <code>WINDOWS\SYSTEM\inetsrv</code> directory and execute
+ <code>PWS /stop</code>. Then execute <code>PWS</code> to start it again.
+ </li>
+</ol>
+
+<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. If this does not work successfully,
+refer to the <a href="#troubleshoot">Troubleshooting</a> section below for help
+on correcting the problem.</p>
+
+<h3>Adding additional Contexts</h3>
+
+<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>
+
+<ol>
+ <li>Adding the context to Tomcat (This is covered in the
+ <a href="tomcat-ug.html#context_addcust">Tomcat User's Guide</a>).</li>
+ <li>Adding the context to the Tomcat redirector plugin.</li>
+</ol>
+
+<p>Adding a context to the Tomcat redirector plugin is simple, all you need to do is to
+start Tomcat 3.3 with "jkconf" option specified again. After the
+worker map file is rewritten, restart IIS/PWS.</p>
+
+<p>If you are using a manually modified URI to worker map file, edit the file
+to add a line that looks like: </p>
+
+<p><tt>/context/*=worker_name</tt></p>
+
+<p>Workers and their name are defined in workers.properties, by default workers.properties
+ comes with 2 pre-configured workers named "<b>ajp13</b>" and "<b>ajp12</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 <tt>uriworkermap.properties</tt> will be:</p>
+
+<p><tt>/shop/*=ajp13</tt></p>
+
+<p>After saving <tt>uriworkermap.properties</tt> restart IIS/PWS and it will
+serve the new context.</p>
+
+<h3>The Tomcat Redirector Plugin Configuration Settings</h3>
+
+<p>The following is an example isapi_redirect.properties file which contains
+the default settings for Tomcat 3.3.</p>
+
+<pre>
+extension_uri=/jakarta/isapi_redirect.dll
+log_file=E:\Jakarta\Tc33x\jakarta-tomcat\dist\tomcat\logs\iis_redirect.log
+log_level=emerg
+worker_file=E:\Jakarta\Tc33x\jakarta-tomcat\dist\tomcat\conf\jk\workers.properties
+worker_mount_file=E:\Jakarta\Tc33x\jakarta-tomcat\dist\tomcat\conf\auto\uriworkermap.properties
+</pre>
+
+<p>The Tomcat redirector plugin for Tomcat 3.3.1 supporta an additional setting
+with the following default.</p>
+
+<pre>
+uri_select=parsed
+</pre>
+
+<p>The following table describes the use of each of these settings:</p>
+
+<table border="1" cellpadding="2">
+<tr><th align="left">Setting</th><th align="left">Description</th>
+ <th align="left">Default</th></tr>
+<tr><td valign="top">extension_uri</td>
+ <td>The URI used by the redirector plugin's filter to redirect the request
+ to the extension. This setting consists of the name of the
+ virtual directory followed by the name of the DLL.</td>
+ <td>/jakarta/isapi_redirect.dll</td></tr>
+<tr><td valign="top">log_file</td>
+ <td>The path of the log file for the redirector plugin DLL</td>
+ <td><i>must be specified</i></td></tr>
+<tr><td>log_level</td>
+ <td>The quantity of log output desired. Valid values are
+ debug, info, error, and emerg.</td><td>emerg</td></tr>
+<tr><td valign="top">worker_file</td>
+ <td>The path to the workers definition file, typically named
+ <code>worker.properties</code></td>
+ <td><i>must be specified</i></td></tr>
+<tr><td valign="top">worker_mount_file</td>
+ <td>The path to the URI to worker map file, typically named
+ <code>uriworkermap.properties</code>.</td>
+ <td><i>must be specified</i></td></tr>
+<tr><td valign="top">uri_select<br>
+ <b>[Tomcat 3.3.1]</b></td>
+ <td>This settings controls which of several forms of
+ the URI is passed to Tomcat. The following are the valid values:<br>
+ <br>
+ <table>
+ <tr><th align="left">Value</th><th align="left">Description</th></tr>
+ <tr><td valign="top">parsed</td><td>Internally, the redirector plugin
+ normalizes and decodes the request URI before checking the request
+ against the URI to worker mappings. This value passes this
+ normalized/decoded version of the URI to Tomcat.</td></tr>
+ <tr><td valign="top">unparsed</td>
+ <td>Passes the original (i.e. unnormalized and undecoded) request URI
+ to Tomcat.</td></tr>
+ <tr><td valign="top">escaped</td>
+ <td>Passes a re-encoded version normalized/decoded request URI to
+ Tomcat.</td></tr>
+ </table>
+ <br>
+ Setting this value properly is important so that request data, such as
+ HttpServletRequest.getRequestURI(), are returned with the proper encoding.
+ Tomcat 3.3 and later requires the <code>parsed</code> setting. Tomcat 3.2.x
+ can use either <code>unparsed</code> or <code>escaped</code>. For
+ Tomcat 3.2.1 and earlier, <code>escaped</code> should be used since it
+ does not do its own normalization.
+ </td><td valign="top">parsed</td></tr>
+</table>
+
+<h2>Building the Tomcat redirector</h2>
+
+<p>The Tomcat redirector was developed using Visual C++ Ver.6.0, so having this
+environment is a prerequisite if you want to perform a custom build.</p>
+
+<p>The steps that you need to take are:</p>
+
+<ol>
+ <li>Change directory to the isapi redirector plugins source directory.</li>
+ <li>Execute the following command:<br>
+ <tt>MSDEV isapi.dsp /MAKE ALL</tt><br>
+ If msdev is not in your path, enter the full path to msdev.exe</li>
+</ol>
+
+<p>This will build both release and debug versions of the redirector plugin. </p>
+
+<p>An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and build
+it using the build menu.</p>
+
+<h2>How does it work? </h2>
+
+<ol>
+ <li>The IIS-Tomcat redirector is an IIS plugin (filter + extension), IIS loads 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
+ <tt>uriworkermap.properties</tt>, 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 ajp1X protocol.</li>
+ <li>The extension collects the response from the worker and returns it to the browser.</li>
+</ol>
+
+<h2>Advanced Context Configuration</h2>
+
+<p>Unlike prior versions, Tomcat 3.3 writes config files which default to
+sending all requests, including those for static pages, to Tomcat for processing.
+This gives the best chance for the web application configuration specified in the
+<code>web.xml</code> file to work successfully.</p>
+
+<p>Also, unlike prior versions, the default worker map file does not try
+to add servlet or JSP operation to the IIS/PWS main virtual directory. To
+see how to control the manner in which Tomcat writes the worker map file see
+the reference information on the <a href="serverxml.html#IISConfig">IISConfig</a>
+module.</p>
+
+<p>Sometimes it is better to have IIS 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,
+IIS will suffice.</p>
+
+<p>Making IIS serve static files that are part of the Tomcat contexts requires the
+following:</p>
+
+<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>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:\jakarta-tomcat\webapps\examples directory. </p>
+
+<p>Configuring the redirector 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 the <tt>uriworkermap.properties</tt>. For the examples context it
+requires to replace the following line:</p>
+
+<p><tt>/examples/*=ajp13</tt></p>
+
+<p>with the following two lines:</p>
+
+<p><tt>/examples/*.jsp=ajp13<br>
+ /examples/servlet/*=ajp13</tt></p>
+<p>As you can see the second configuration is more explicit, it actually instruct the
+redirector to redirect only requests to resources under <tt>/examples/servlet/</tt> and
+resources under <tt>/examples/ </tt>whose name ends with <tt>.jsp</tt>. This is
+similar to what is automatically written to the <tt>uriworkermap.properties-auto</tt>
+file for each context.</p>
+
+<p>You can even be more explicit and provide lines such as:</p>
+
+<p><tt>/example/servletname=ajp13</tt> </p>
+
+<p>that instructs the redirector to redirect request whose URL-Path equals <tt>/example/servletname
+ </tt>to the worker named ajp13.</p>
+
+<h3>Protecting the WEB-INF Directory</h3>
+
+<p>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. Using the IIS management console it is possible to protect the WEB-INF
+directory from user access, this however requires the administrator to remember that. To
+avoid this need the redirector plugin automatically protects your WEB-INF directories by
+rejecting any request that contains WEB-INF in its URL-Path.</p>
+
+<h2>Advanced Worker Configuration</h2>
+
+<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 <tt>workers.properties</tt>, this file includes
+two types of entries:</p>
+
+<ol>
+ <li>An entry that lists all the workers defined. For example:<br>
+ <tt>worker.list=ajp12, ajp13, ajp13second</tt></li>
+ <li>Entries that define the host and port associated with these workers. For
+ example:<br>
+ <tt>worker.ajp12.host=farhost<br>
+ worker.ajp12.port=8007<br>
+ worker.ajp13.host=localhost<br>
+ worker.ajp13.port=8009<br>
+ worker.ajp13second.host=otherhost<br>
+ worker.ajp13second.port=8009</tt></li>
+</ol>
+
+<p>The above examples defined three workers, now we can use these workers to serve two
+different contexts each with its own worker. For example look at the following
+<tt>uriworkermap.properties</tt> fragment:</p>
+
+<p><tt>/examples/*=ajp12 <br>
+ /webapp1/*=ajp13 <br>
+ /webapp2/*=ajp13second </tt></p>
+
+<p>As you can see the examples context is served by ajp12 while the webapp1 context
+ is served by ajp13, and the webapp2 context is served by the ajp13second worker.
+</p>
+
+<h2><a name="troubleshoot">Troubleshooting</a></h2>
+
+<p>It is easy to have the Tomcat redirector not work the first time you try to install
+it. If this happens to you, here are some steps to follow to try to correct the
+problem. These steps aren't guaranteed to cover all possible problems, but they
+should help find the typical mistakes. 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><b>Note:</b> These steps assume your <tt>worker_mount_file</tt> setting points
+to an unmodified copy of the <code>conf/auto/uriworkermap.properties</code> file.
+Results may be misleading if <tt>worker_mount_file</tt> points to a modified
+version of the file. It is also assumed that the "/examples"
+context works correctly if you access Tomcat directly.</p>
+
+<h3>Win98</h3>
+
+<ol>
+ <li>Make sure web site activity is being logged. For PWS make sure "Save
+ Web Site Activity Log" is checked in the Advanced Options of the Personal
+ Web Manager.</li>
+ <li>Start the PWS service and Tomcat.</li>
+ <li>Check for the presence of the Tomcat redirector log file you specified in
+ the <tt>log_file</tt> setting. If not found, check the following:
+ <ol type="A">
+ <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 <tt>log_file</tt> setting for typos, name and data. Also ensure
+ the directory in which the log file will appear already exists.</li>
+ </ol>
+ If the above are set correctly, the Tomcat redirector should be able to create
+ the log file.</li>
+ <li>Invoke the URL "http://localhost/examples/jsp/index.html" in your
+ browser. Case is important. The characters following "localhost"
+ in the URL must be lower case. If the page fails to appear, stop the PWS service
+ (required to view the PWS log file). Then examine the last line in the PWS
+ log file in found in SYSTEM/LogFiles/W3SVC1.
+ <ol type="A">
+ <li>If the last line contains: <tt>GET "/examples/jsp/index.html HTTP/1.1"
+ 404</tt>, then the Tomcat redirector is not recognizing that it should
+ be handling requests for the "/examples" context. Check the
+ following:
+ <ol>
+ <li>Check the <tt>extension_uri</tt> name for typos.</li>
+ <li>Check the <tt>worker_file</tt> setting for typos, name and data.</li>
+ <li>Check the <tt>worker_mount_file</tt> setting typos, name and data.</li>
+ </ol>
+ If these are set correctly, the Tomcat redirector should recognize that
+ it should handle requests for the "/examples" context.</li>
+ <li>If the last line contains something like: <tt>GET "/jakarta/isapi_redirect.dll
+ HTTP1.1"</tt>, then the Tomcat redirector is recognizing that it should
+ handle the request, but is not successful at getting Tomcat to service
+ the request.
+ <ol>
+ <li>If the number following <tt>GET "/..."</tt> is 404, check
+ the following:
+ <ol type="a">
+ <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 <tt>extension_uri</tt> data begins with "/jakarta/"
+ (without the quotes).</li>
+ </ol>
+ </li>
+ <li>If the number following <tt>GET "/..."</tt> is 500, check
+ the following:
+ <ol type="a">
+ <li>Make sure that "isapi_redirect.dll" follows "/jakarta/"
+ in the <tt>extension_uri</tt> setting.</li>
+ <li>Check the workers.properties file and make sure the port setting
+ for <tt>workers used</tt> is the same as the port specified in
+ the server.xml for the ajp13 or ajp12 connectors, normally this
+ ports are 8007 for ajp12 and 8009 for ajp13.</li>
+ </ol>
+ </li>
+ <li>If the number following <tt>GET "/..."</tt> is 200 or
+ 403, make sure you have checked Execute Access for the jakarta virtual
+ directory in the Advanced Options of the Personal Web Manager.</li>
+ </ol>
+ </ol>
+ If the above settings are correct, the index.html page should appear in your
+ browser. You should also be able to click the <b>Execute</b> links to execute
+ the JSP examples.</li>
+</ol>
+
+<h3>WinNT/Win2k</h3>
+
+<ol>
+ <li>Make sure web site activity is being logged. For IIS/PWS make sure
+ "Save Web Site Activity Log" is checked in the Advanced Options of
+ the Personal Web Manager.</li>
+ <li>Start the World Wide Web Publishing Service and Tomcat.</li>
+ <li>Check for the presence of the Tomcat redirector log file you specified in the
+ <tt>log_file</tt> setting. If not found, check the following:
+ <ol type="A">
+ <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 Tomcat 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 <tt>log_file</tt> setting for typos, name and data. Also
+ ensure the directory in which the log file will appear already exists.</li>
+ </ol>
+ If the above are set correctly, the Tomcat redirector should be able to create
+ the log file.</li>
+ <li>Check the jakarta filter you added and make sure its status shows a green
+ upward-pointing arrow. If not, check the following:
+ <ol type="A">
+ <li>Check the <tt>worker_file</tt> setting for typos, name and data.</li>
+ <li>Check the <tt>worker_mount_file</tt> setting typos, name and data.</li>
+ </ol>
+ If the above are set correctly, the green upward-pointing arrow should appear,
+ even if the other settings are wrong.</li>
+ <li>Invoke the URL "http://localhost/examples/jsp/index.html" in your
+ browser. Case is important. 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.
+ <ol type="A">
+ <li>The last line should contain something like: <tt>GET "/jakarta/isapi_redirect.dll
+ HTTP1.1"</tt>, which indicates the Tomcat redirector is recognizing
+ that it should handle the request.
+ <ol>
+ <li>If the number following <tt>GET "/..."</tt> is 404, check
+ the following:
+ <ol type="a">
+ <li>Make sure you entered the URL correctly.</li>
+ </ol></li>
+ <li>If the number following <tt>GET "/..."</tt> is 500, check
+ the following:
+ <ol type="a">
+ <li>Make sure the virtual directory created was called "jakarta".</li>
+ <li>Make sure that the <tt>extension_uri</tt> setting is correct.</li>
+ <li>Check the workers.properties file and make sure the port setting
+ for <tt>workers used </tt> is the same as the port specified in
+ the server.xml for the ajp13 or ajp12 connectors, normally this
+ ports are 8007 for ajp12 and 8009 for ajp13.</li>
+ </ol>
+ </li>
+ <li>If the number following <tt>GET "/..."</tt> is 200 or 403,
+ make sure you have checked Execute Access for the jakarta virtual
+ directory in the Advanced Options of the Personal Web Manager. If
+ you created the "Filter DLLs" key in the registry, delete
+ it. That registry key is only used on Win98.</li>
+ </ol>
+ </ol>
+ If the above settings are correct, the index.html page should appear in your
+ browser. You should also be able to click the <b>Execute</b> links to
+ execute the JSP examples.</li>
+</ol>
+
+<h2>Feedback</h2>
+
+<p>Please send feedback, bug report or any additional information to
+<tt>tomcat-user@jakarta.apache.org</tt></p>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-iis-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-netscape-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-netscape-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-netscape-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-netscape-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,280 @@
+<html>
+
+<head>
+<!--
+ 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.
+-->
+<title>Jakarta IIS Howto</title>
+</head>
+
+<body>
+
+<h1>Tomcat Netscape HowTo</h1>
+
+<p>By Gal Shachor <shachor@il.ibm.com></p>
+
+<p>This document explains how to set up Netscape web servers to cooperate with
+Tomcat. 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>
+
+<h2>Document Conventions and Assumptions</h2>
+
+<p><tomcat_home> is the root directory of tomcat. Your Tomcat
+installation should have the following subdirectories:
+
+<ol>
+ <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>
+</ol>
+
+<p>In all the examples in this document <tomcat_home> will be d:\tomcat.</p>
+
+<p>A <tt>worker</tt> is defined to be a tomcat process that accepts work from
+the Netscape server.</p>
+
+<h2>Supported Configuration</h2>
+
+<p>The Netscape-Tomcat redirector was developed and tested on:
+
+<ol>
+ <li>WinNT4.0-i386 SP4/SP5/SP6a (it should be able to work on other versions
+ of the NT service pack and also UNIX) </li>
+ <li>Netscape Enterprise 3.0 and 3.61</li>
+ <li>Tomcat3.0 - Tomcat3.1beta1 </li>
+</ol>
+
+<p>The redirector uses <b>ajp12</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>
+
+<h2>Installation</h2>
+
+<p>The Netscape redirector is not part of the "official" build of Jakarta, You
+can obtain the code and binaries needed for it by accessing
+http://jakarta.apache.org/builds/tomcat/release/v3.1_beta_1/bin/win32/i386/.
+The redirector related file is <tt>nsapi_redirect.dll</tt>.</p>
+
+<p>The Tomcat redirector requires two entities:
+
+<ol>
+ <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). This file is located
+ in (<tt>tomcat/conf/workers.properties</tt>).</li>
+</ol>
+
+<p>The installation includes the following parts:
+
+<ol>
+ <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>
+</ol>
+
+<h3>Configuring the NSAPI Redirector</h3>
+
+<p>In this document I will assume that nsapi_redirect.dll is placed in
+d:\tomcat\bin\netscape\nt4\i386\nsapi_redirect.dll and that you created the
+properties files are in d:\tomcat\conf.</p>
+
+<ol>
+ <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
+ obj.conf and add the following lines:</li>
+ <ul>
+ <li>In the Init section:<br>
+ <tt>Init fn="load-modules" funcs="jk_init,jk_service"
+ shlib="d:/tomcat/bin/netscape/nt4/i386/nsapi_redirect.dll"<br>
+ Init fn="jk_init" worker_file="d:/tomcat/conf/workers.properties"
+ log_level="debug" log_file="d:/tomcat/nsapi.log"</tt> </li>
+ <li>In the default object NameTrans section<br>
+ <tt>NameTrans fn="assign-name" from="/servlet/*"
+ name="servlet"<br>
+ NameTrans fn="assign-name" from="/examples/*" name="servlet"</tt></li>
+ <li>Create a new configuration object by adding the following lines to the end of the
+ obj.conf file:<br>
+ <tt><Object name=servlet> <br>
+ ObjectType fn=force-type type=text/plain <br>
+ Service fn="jk_service" worker="ajp12" <br>
+ </Object></tt></li>
+ </ul>
+ <li>Restart Netscape (stop and start the server)</li>
+</ol>
+
+<p>That's all, now you should start tomcat and ask Netscape for
+http://server:port/examples/</p>
+
+<h3>Adding additional Contexts</h3>
+
+<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:
+
+<ol>
+ <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>
+</ol>
+
+<p>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:</p>
+
+<p><tt>NameTrans fn="assign-name" from="/<context name>/*"
+name="servlet" </tt></p>
+
+<p>After saving obj.conf restart Netscape and it will serve the new context.</p>
+
+<h2>Building the redirector</h2>
+
+<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.</p>
+
+<p>The steps that you need to take are:
+
+<ol>
+ <li>Change directory to the nsapi plugins source directory.</li>
+ <li>Edit <tt>nsapi.dsp</tt> and update the include and library path to reflect your own
+ Netscape server installation (search for a <tt>/I</tt> compiler option and <tt>/libpath</tt>
+ linker option)</li>
+ <li>Execute the following command:<br>
+ <tt>MSDEV nsapi.dsp /MAKE ALL</tt><br>
+ If msdev is not in your path, enter the full path to msdev.exe</li>
+</ol>
+
+<p>This will build both release and debug versions of the redirector plugin. </p>
+
+<p>An alternative will be to open the nsapi workspace file (nsapi.dsw) in msdev and build
+it using the build menu.</p>
+
+<h2>How does it work? </h2>
+
+<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 ajp12 protocol (the
+ worker="ajp12" parameter in jk_service inform it that the worker for this
+ request is named ajp12).</li>
+ <li>The extension collects the response from the worker and returns it to the browser.</li>
+</ol>
+
+<h2>Advanced Context Configuration</h2>
+
+<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:
+
+<ol>
+ <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>
+</ol>
+
+<p>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 d:\tomkat\webapps\examples
+directory.
+
+To add a new virtual directory add the following line to your obj.conf:</p>
+
+<p><tt>NameTrans fn=pfx2dir from=/examples dir="d:/tomcat/webapps/examples"</tt></p>
+
+<p>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:</p>
+
+<p><tt>PathCheck fn="deny-existence" path="*/WEB-INF/*"</tt></p>
+
+<p>This line instructs the Netscape server to reject any request with a URL that contain
+the path /WEB-INF/.</p>
+
+<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). This requires a change to NemaTrans portion
+of obj.conf. For the examples context it requires to replace the following line:</p>
+
+<p><tt>NameTrans fn="assign-name" from="/examples/*"
+name="servlet"</tt> </p>
+
+<p>with the following two lines:</p>
+
+<p><tt>NameTrans fn="assign-name" from="/examples/jsp/*.jsp"
+name="servlet"<br>
+NameTrans fn="assign-name" from="/examples/servlet/*"
+name="servlet" </tt></p>
+
+<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 <tt>/examples/servlet/</tt>
+and resources under <tt>/examples/ </tt>whose name ends with <tt>.jsp</tt>. You can be
+even more explicit and provide lines such as:</p>
+
+<p><tt>NameTrans fn="assign-name" from="/examples/servletname"
+name="servlet"</tt></p>
+
+<p>that instructs Netscape to assign the redirector request whose URL-Path equals <tt>/example/servletname</tt>.</p>
+
+<h2>Advanced Worker Configuration</h2>
+
+<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 workers.properties, this file includes two types of entries:
+
+<ol>
+ <li>An entry that lists all the workers defined. For example:<br>
+ <tt>worker.list=ajp12, ajp12second</tt></li>
+ <li>Entries that define the host and port associated with these workers. For example:<br>
+ <tt>worker.ajp12.host=localhost<br>
+ worker.ajp12.port=8007<br>
+ worker.ajp12second.host=otherhost<br>
+ worker.ajp12second.port=8007</tt></li>
+</ol>
+
+<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. For example, if we want to submit
+the /servlet context to a worker named ajp12 and the /examples context to a worker named
+ajp12second we should use the following configuration:</p>
+
+<p><tt><Object name=servlet><br>
+ObjectType fn=force-type type=text/plain<br>
+Service fn="jk_service" worker="ajp12" path="/servlet/*"<br>
+Service fn="jk_service" worker="ajp12second"
+path="/examples/*"<br>
+Service fn="jk_service" worker="ajp12"<br>
+</Object></tt></p>
+
+<h2>Feedback</h2>
+
+<p>Please send feedback, bug report or any additional information to
+<tt>tomcat-user@jakarta.apache.org</tt>.
+</p>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-netscape-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org