From 9401f816dd0d9d550fe98a8507224bde51c4b847 Mon Sep 17 00:00:00 2001 From: hongbotian Date: Mon, 30 Nov 2015 02:41:33 -0500 Subject: upload tomcat JIRA: BOTTLENECK-7 Change-Id: I875d474869efd76ca203c30b60ebc0c3ee606d0e Signed-off-by: hongbotian --- .../docs/webserver_howto/apache.html | 1124 ++++++++++++++++++++ .../docs/webserver_howto/iis.html | 685 ++++++++++++ .../docs/webserver_howto/nes.html | 483 +++++++++ .../docs/webserver_howto/printer/apache.html | 1123 +++++++++++++++++++ .../docs/webserver_howto/printer/iis.html | 684 ++++++++++++ .../docs/webserver_howto/printer/nes.html | 482 +++++++++ 6 files changed, 4581 insertions(+) create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/apache.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/nes.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/apache.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/iis.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/nes.html (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto') diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/apache.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/apache.html new file mode 100644 index 00000000..a60cc43c --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/apache.html @@ -0,0 +1,1124 @@ +The Apache Tomcat Connector - Webserver HowTo - Apache HTTP Server HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Webserver HowTo

Apache HTTP Server HowTo

print-friendly
version +

Introduction

+
+This document explains how to connect Tomcat to the popular open source web server, Apache httpd. +There is actually three versions of Apache HTTP Server, 1.3, 2.0 and 2.2 and all can be used with mod_jk, +the Tomcat redirector module. +
+ +
+It is recommended that you also read the +Workers HowTo document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +workers.properties, +uriworkermap +and Apache. +
+ +
Waring: If Apache HTTP Server and Tomcat are configured to serve content from +the same filing system location then care must be taken to ensure that httpd is +not able to serve inappropriate content such as the contents of the WEB-INF +directory or JSP source code. This could occur if the httpd DocumentRoot +overlaps with a Tomcat Host's appBase or the docBase of any Context. It could +also occur when using the httpd Alias directive with a Tomcat Host's appBase or +the docBase of any Context. +
+ +
+This document was originally part of Tomcat: A Minimalistic User's Guide written by Gal Shachor, +but has been split off for organisational reasons. +
+ +
Document Conventions and Assumptions
+
+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +
+
+${tomcat_home}\conf - Where you can place various configuration files +
+
+${tomcat_home}\webapps - Containing example applications +
+
+${tomcat_home}\bin - Where you place web server plugins +
+
+
+
+In all the examples in this document ${tomcat_home} will be /var/tomcat3. +A worker is defined to be a tomcat process that accepts work from the Apache server. +
+
+ +
Supported Configuration
+
+The mod_jk module was developed and tested on: +
+
+Linux, FreeBSD, AIX, HP-UX, MacOS X, Solaris and should works on major Unixes platforms +supporting Apache 1.3 and/or 2.0/2.2 +
+
+WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +
+
+Cygwin (until you have an apache server and autoconf/automake support tools) +
+
+Netware +
+
+i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed. +
+
+Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x, Tomcat 5.0.x, Tomcat 5.5.x and Tomcat 6. +
+
+
+ +
+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +
+
+ +
Who support ajp protocols ?
+
+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +
+ +
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. +
+ +
+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +
+ +
+Others servlet engines such as jetty have support for ajp13 protocol +
+ +
+ +
How does it work ?
+
+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 behaviour. +Now the web server needs also to perform the following: +
+ +
+
+Load the servlet container adaptor library and initialise it (prior to serving requests). +
+
+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 adaptor take the request and handle it. +
+
+ +
+The adaptor 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. +
+ +
+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. +
+ +
+ +

Obtaining mod_jk

+
+mod_jk can be obtained in two formats - binary and source. +Depending on the platform you are running your web server on, a binary version of mod_jk may be available. +
+ +
+It is recommended to use the binary version if one is available. +If the binary is not available, follow the instructions for building mod_jk from source. +The mod_jk source can be downloaded from a mirror + +here +
+ +
+The binaries for mod_jk are now available for several platforms. +The binaries are located in subdirectories by platform. +
+ +
+For some platforms, such as Windows, this is the typical way of obtaining mod_jk +since most Windows systems do not have C compilers. +
+ +
+For others, the binary distribution of mod_jk offers simpler installation. +
+ +
+For example JK 1.2.x can be downloaded from a mirror + +here (look for JK 1.2 Binary Releases). The "JK 1.2 Binary Releases" link contains binary version for a variety of +operating systems for both Apache 1.3 and Apache 2. +
+ +

Installation

+
+mod_jk requires two entities: + +
+
+mod_jk.xxx - The Apache HTTP Server module, depending on your operating system, it will be mod_jk.so, mod_jk.nlm or +or MOD_JK.SRVPGM (see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory in the source download. +
+
+
+ +
+Also as with other Apache HTTP Server modules, mod_jk should be first installed on the modules directory of your +Apache webserver, ie : /usr/lib/apache and you should update your httpd.conf file. +
+ + +
Disabling old mod_jserv
+
+If you've previously configured Apache to use mod_jserv, remove any ApJServMount directives +from your httpd.conf. +
+ +
If you're including tomcat-apache.conf or tomcat.conf, you'll want to remove them as well - +they are specific to mod_jserv. +
+ +
+The mod_jserv configuration directives are not compatible with mod_jk ! +
+
+ +
Using Tomcat auto-configure
+
+The auto-configure works only for a single Tomcat running on the same machine where Apache HTTP Server is running. +The simplest way to configure Apache HTTP Server to use mod_jk is to turn on the Apache HTTP Server auto-configure setting +in Tomcat and put the following include directive at the end of your Apache httpd.conf file +(make sure you replace $TOMCAT_HOME with the correct path for your Tomcat installation: +
+ +
+    #To be added at the end of your httpd.conf
+    Include $TOMCAT_HOME/conf/jk/mod_jk.conf-auto
+
+ +
+Note: this file may also be generated as $TOMCAT_HOME/conf/auto/mod_jk.conf +
+ +
+This will tell Apache HTTP Server to use directives in the mod_jk.conf-auto file in +the Apache configuration. This file is created by enabling the Apache +auto-configuration by creating your workers.properties file at +$TOMCAT_HOME/conf/jk/workers.properties and adding the listener to the Engine +element in the server.xml file as per the following example. +Please note that this example is specific to Tomcat 5.x, unlike other sections of this document + which also apply to previous Tomcat branches. +
+
+  ...
+  <Engine ...>
+    ...
+    <Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" />
+    ...
+  </Engine>
+  ...
+
+ +
+Then restart Tomcat and mod_jk.conf should be generated. For more information on +this topic, please refer to the API documentation at the + +Tomcat docs website. +
+ +
+ +
Custom mod_jk configuration
+
+You should use custom configuration when : +
+
+
+You couldn't use mod_jk.conf-auto since Tomcat engine isn't on the same machine that your Apache web server, +ie when you have an Apache in front of a Tomcat Farm. +
+
+Another case for custom configuration is when your Apache is in front of many different Tomcat engines, +each one having it's own configuration, a general case in ISP hosting +
+
+Also all Apache webmaster will retain custom configuration to be able to tune the settings +to their real needs. +
+
+ +
+ +
Simple configuration example
+
+Here is a simple configuration: +
+ +
+    # Load mod_jk module
+    LoadModule    jk_module  libexec/mod_jk.so
+    # Declare the module for <IfModule directive> (remove this line on Apache 2.0.x)
+    AddModule     mod_jk.c
+    # Where to find workers.properties
+    JkWorkersFile /etc/httpd/conf/workers.properties
+    # Where to put jk shared memory
+    JkShmFile     /var/log/httpd/mod_jk.shm
+    # Where to put jk logs
+    JkLogFile     /var/log/httpd/mod_jk.log
+    # Set the jk log level [debug/error/info]
+    JkLogLevel    info
+    # Select the timestamp log format
+    JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+    # Send servlet for context /examples to worker named worker1
+    JkMount  /examples/servlet/* worker1
+    # Send JSPs  for context /examples to worker named worker1
+    JkMount  /examples/*.jsp worker1
+
+ +
+

mod_jk Directives

+
+We'll discuss here the mod_jk directives and details behind them +
+ +
Define workers
+
+JkWorkersFile specify the location where mod_jk will find the workers definitions. + +
+  JkWorkersFile     /etc/httpd/conf/workers.properties
+
+ +
+
+
+
+ +
Logging
+
+JkLogFile specify the location where mod_jk is going to place its log file. +
+ +
+  JkLogFile     /var/log/httpd/mod_jk.log
+
+ +
+Since JK 1.2.3 for Apache 2.0/2.2 and JK 1.2.16 for Apache 1.3 this can also +be used for piped logging: +
+ +
+  JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
+
+ +
+JkLogLevel +set the log level between : +
+ +
+
+info log will contains standard mod_jk activity (default). +
+
+error log will contains also error reports. +
+
+debug log will contains all information on mod_jk activity +
+
+ +
+  JkLogLevel    info
+
+ +
+info should be your default selection for normal operations. +
+
+
+ +
+JkLogStampFormat will configure the date/time format found on mod_jk logfile. +Using the strftime() format string it's set by default to "[%a %b %d %H:%M:%S %Y]" +
+ +
+  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+
+ +
+
+
+
+ +
+JkRequestLogFormat will configure the format of mod_jk individual request logging. +Request logging is configured and enabled on a per virtual host basis. +To enable request logging for a virtual host just add a JkRequestLogFormat config. +The syntax of the format string is similar to the Apache LogFormat command, +here is a list of the available request log format options: +
+ +
+ + + + + + + + + + + + + + + + +
Options Description
%b Bytes sent, excluding HTTP headers (CLF format)
%B Bytes sent, excluding HTTP headers
%H The request protocol
%m The request method
%p The canonical Port of the server serving the request
%q The query string (prepended with a ? if a query string exists, otherwise an empty string)
%r First line of request
%s Request HTTP status code
%T Request duration, elapsed time to handle request in seconds '.' micro seconds
%U The URL path requested, not including any query string.
%v The canonical ServerName of the server serving the request
%V The server name according to the UseCanonicalName setting
%w Tomcat worker name
%R Session route name (available with 1.2.19 and up)
+ +
+  JkRequestLogFormat     "%w %V %T"
+
+ +
+
+
+ +
+ +
Forwarding
+
+The directive JkOptions allow you to set many forwarding options which will enable (+) +or disable (-) following option. Without any leading signs, options will be enabled. +
+
+
+ +
+The four following options +ForwardURIxxx are mutually exclusive. +Exactly one of them is required, a negative sign prefix is not allowed with them. +The default value is "ForwardURIProxy" since version 1.2.24. +It was "ForwardURICompatUnparsed" in version 1.2.23 and +"ForwardURICompat" until version 1.2.22. +You can turn the default off by switching on one of the other two options. +You should leave this at it's default value, unless you have a very good +reason to change it. +
+
+
+ +
+All options are inherited from the global server to virtual hosts. +Options that support enabling (plus options) and disabling (minus options), +are inherited in the following way: +
+
+options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost) +
+
+
+ +
+Using JkOptions ForwardURIProxy, the forwarded URI +will be partially reencoded after processing inside Apache httpd and +before forwarding to Tomcat. This will be compatible with local +URL manipulation by mod_rewrite and with URL encoded session ids. + +
+  JkOptions     +ForwardURIProxy
+
+ +
+
+
+ +
+Using JkOptions ForwardURICompatUnparsed, the forwarded URI +will be unparsed. It's spec compliant and secure. +It will always forward the original request URI, so rewriting +URIs with mod_rewrite and then forwarding the rewritten URI +will not work. + +
+  JkOptions     +ForwardURICompatUnparsed
+
+ +
+
+
+
+Using JkOptions ForwardURICompat, the forwarded URI will +be decoded by Apache httpd. Encoded characters will be decoded and +explicit path components like ".." will already be resolved. +This is less spec compliant and is not safe if you are using +prefix JkMount. This option will allow to rewrite URIs with +mod_rewrite before forwarding. + +
+  JkOptions     +ForwardURICompat
+
+ +
+
+
+
+Using JkOptions ForwardURIEscaped, the forwarded URI will +be the encoded form of the URI used by ForwardURICompat. +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs, +but it will allow to rewrite URIs with mod_rewrite before forwarding. + +
+  JkOptions     +ForwardURIEscaped
+
+ +
+
+
+ +
+JkOptions RejectUnsafeURI will block all +URLs, which contain percent signs '%' or backslashes '\' +after decoding. +
+
+
+
+Most web apps do not use such URLs. Using the option RejectUnsafeURI, you +can block several well known URL encoding attacks. By default, this option +is not set. +
+
+You can also realise such a check with mod_rewrite, which is more powerful +but also slightly more complicated. + +
+  JkOptions     +RejectUnsafeURI
+
+ +
+
+
+ +
+JkOptions ForwardDirectories is used in conjunction with DirectoryIndex +directive of Apache web server. As such mod_dir should be available to Apache, +statically or dynamically (DSO) +
+
+
+ +
+When DirectoryIndex is configured, Apache will create sub-requests for +each of the local-url's specified in the directive, to determine if there is a +local file that matches (this is done by stat-ing the file). +
+ +
+If ForwardDirectories is set to false (default) and Apache doesn't find any +files that match, Apache will serve the content of the directory (if directive +Options specifies Indexes for that directory) or a 403 Forbidden response (if +directive Options doesn't specify Indexes for that directory). +
+ +
+If ForwarDirectories is set to true and Apache doesn't find any files that +match, the request will be forwarded to Tomcat for resolution. This is used in +cases when Apache cannot see the index files on the file system for various +reasons: Tomcat is running on a different machine, the JSP file has been +precompiled etc. +
+ +
Note that locally visible files will take precedence over the +ones visible only to Tomcat (i.e. if Apache can see the file, that's the one +that's going to get served). This is important if there is more then one type of +file that Tomcat normally serves - for instance Velocity pages and JSP pages. + +
+  JkOptions     +ForwardDirectories
+
+
+
+
+ +
+JkOptions ForwardLocalAddress, you ask mod_jk to send the local address, +of the Apache web server instead remote client address. This can be used by +Tomcat remote address valve for allowing connections only from registered Apache +web servers. + +
+  JkOptions     +ForwardLocalAddress
+
+ +
+
+
+ +
+JkOptions FlushPackets, you ask mod_jk to flush Apache's connection +buffer after each AJP packet chunk received from Tomcat. This option can have +a strong performance penalty for Apache and Tomcat as writes are performed +more often than would normally be required (ie: at the end of each +response). + +
+  JkOptions     +FlushPackets
+
+ +
+
+
+ +
+JkOptions FlushHeader, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +
+  JkOptions     +FlushHeader
+
+ +
+
+
+ +
+JkOptions DisableReuse, you ask mod_jk to close connections immediately +after their use. Normally mod_jk uses persistent connections and pools idle +connections to reuse them, when new requests have to be sent to Tomcat. +
+ +
+Using this option will have a strong performance penalty for Apache and Tomcat. +Use this only as a last resort in case of unfixable network problems. +If a firewall between Apache and Tomcat silently kills idle connections, +try to use the worker attribute socket_keepalive in combination with an appropriate +TCP keepalive value in your OS. + +
+  JkOptions     +DisableReuse
+
+ +
+
+
+ +
+JkOptions ForwardKeySize, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as +required by Servlet API 2.3. +This flag shouldn't be set when servlet engine is Tomcat 3.2.x (off by default). + +
+  JkOptions     +ForwardKeySize
+
+ +
+
+
+ +
+JkOptions ForwardSSLCertChain, you ask mod_jk, when using ajp13, +to forward SSL certificate chain (off by default). +Mod_jk only passes the SSL_CLIENT_CERT to the AJP connector. This is not a +problem with self-signed certificates or certificates directly signed by the +root CA certificate. However, there's a large number of certificates signed by +an intermediate CA certificate, where this is a significant problem: A servlet +will not have the possibility to validate the client certificate on its own. The +bug would be fixed by passing on the SSL_CLIENT_CERT_CHAIN to Tomcat via the AJP connector. +
+This directive exists only since version 1.2.22. +
+  JkOptions     +ForwardSSLCertChain
+
+ +
+
+
+ +
+The directive JkEnvVar allows you to forward environment variables +from Apache server to Tomcat engine. +You can add a default value as a second parameter to the directive. +If the default value is not given explicitly, the variable +will only be send, if it is set during runtime. +
+The variables can be retrieved on the Tomcat side as request attributes +via request.getAttribute(attributeName). +Note that the variables send via JkEnvVar will not be listed +in request.getAttributeNames(). +
+
+The variables are inherited from the global server to virtual hosts. + +
+  JkEnvVar     SSL_CLIENT_V_START     undefined
+
+
+
+
+ +
+ +
Assigning URLs to Tomcat
+
+If you have created a custom or local version of mod_jk.conf-local as noted above, +you can change settings such as the workers or URL prefix. +
+ +
+JkMount directive assign specific URLs to Tomcat. +In general the structure of a JkMount directive is: +
+ +
  JkMount [URL prefix] [Worker name]
+ +
+  # send all requests ending in .jsp to worker1
+  JkMount /*.jsp worker1
+  # send all requests ending /servlet to worker1
+  JkMount /*/servlet/ worker1
+  # send all requests jsp requests to files located in /otherworker will go worker2
+  JkMount /otherworker/*.jsp worker2
+
+ +
+You can use the JkMount directive at the top level or inside <VirtualHost> sections of your httpd.conf file. +
+
+ +
Configuring Apache to serve static web application files
+
+If the Tomcat Host appBase (webapps) directory is accessible by the Apache web server, +Apache can be configured to serve web application context directory static files instead +of passing the request to Tomcat. +
+ +
+Caution: For security reasons is is strongly recommended that JkMount is used to +pass all requests to Tomcat by default and JkUnMount is used to explicitly +exclude static content to be served by httpd. It should also be noted that +content served by httpd will bypass any security constraints defined in the +application's web.xml. +
+ +
Use Apache's Alias directive to map a single web application context directory into Apache's +document space for a VirtualHost: +
+ +
+  # Static files in the examples webapp are served by apache
+  Alias /examples /vat/tomcat3/webapps/examples
+  # All requests go to worker1 by default
+  JkMount /* worker1
+  # Serve html, jpg and gif using httpd
+  JkUnMount /*.html worker1
+  JkUnMount /*.jpg  worker1
+  JkUnMount /*.gif  worker1
+
+ +
+Starting with mod_jk 1.2.6 for Apache 2.0/2.2 and 1.2.19 for Apache 1.3, it's possible to exclude some URL/URI from +jk processing by setting the env var no-jk, for example with the SetEnvIf Directive. +
+ +
+You could use no-jk env var to fix problem with mod_alias or mod_userdir +directive when jk and alias/userdir URLs matches. +
+ +
+  # All URL goes to tomcat except the one containing /home
+  <VirtualHost *:80>
+      ServerName testxxx.mysys
+      DocumentRoot /www/testxxx/htdocs
+
+  # Use SetEnvIf to st no-jk when /home/ is encountered
+      SetEnvIf Request_URI "/home/*" no-jk
+
+  # Now /home will goes to /home/dataxxx/
+      Alias /home /home/dataxxx/
+
+      <Directory "/home/dataxxx">
+          Options Indexes MultiViews
+          AllowOverride None
+          Order allow,deny
+          Allow from all
+      </Directory>
+
+      JkMount /* myssys-xxx
+
+  </VirtualHost>
+
+ + +
+Use the mod_jk JkAutoAlias directive to map all web application context directories +into Apache's document space. +
+ +
+Attempts to access the WEB-INF or META-INF directories within a web application context +or a Web Archive *.war within the Tomcat Host appBase (webapps) directory will fail with an +HTTP 403, Access Forbidden +
+ +
+  # Static files in all Tomcat webapp context directories are served by apache
+  JkAutoAlias /var/tomcat3/webapps
+
+  # All requests go to worker1 by default
+  JkMount /* ajp13
+  # Serve html, jpg and gif using httpd
+  JkUnMount /*.html ajp13
+  JkUnMount /*.jpg  ajp13
+  JkUnMount /*.gif  ajp13
+
+ +
+If you encoded all your URLs to contain the session id +(;jsessionid=...), and you later decide, you want to +move part of the content to Apache httpd, you can tell +mod_jk to strip off all session ids from URLs for +those requests, that do not get forwarded via mod_jk. +
+ +
+You enable this feature by setting JkStripSession to On. +It can be enabled individually for virtual servers. The default +value is Off. +
+ +
+

Building mod_jk on Unix

+
+The mod_jk build use the widely used configure system. +
+
Prepare your mod_jk configure from subversion
+In case you get source from subversion, ie without an existing configure script, +you should have autoconf for configuration and installation. +
+To create tomcat-connectors's autoconf script, you will need libtool +1.5.2, automake 1.10 and autoconf 2.59 or newer. The use of more recent +versions is encouraged, e.g. for reliable detection of the features of +recent version of operating systems. +
+Those tools will not be required if you are just using a package downloaded from apache.org, +they are only required for developers. +
+
+To create the configure script just type : + +
[user@host] ~ $ ./buildconf.sh
+
+
+ +
Using configure to build mod_jk
+
Here's how to use configure to prepare mod_jk for building, just type: +
+./configure [autoconf arguments] [tomcat-connectors arguments]
+
+
+ +
+You could set CFLAGS and LDFLAGS to add some platform specifics: +
+ +
[user@host] ~ $ LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs
+ +
+If you want to build mod_jk for different version of Apache httpd, like 1.3, 2.0 and 2.2, +you need to go through the full build process for each of them. +Please note, that httpd 2.0 and 2.2 modules are not compatible. The mod_jk directory +used is "apache-2.0" in both cases, but you need to compile separately. +
+
+use configure and indicate the correct Apache httpd apxs location (--with-apxs) +
+
+use make +
+
+copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory +to the Apache httpd modules location. +
+
+make clean (to remove all previously compiled object files) +
+
+Start over with the apxs location for your next Apache httpd version. +
+
+ +
+
+ +
configure arguments
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Apache related parameters
--with-apxs[=FILE] FILE is the location of the apxs tool. Default is finding apxs in PATH. +It builds a shared Apache module. It detects automatically the Apache version. +(2.0/2.2 and 1.3)
--with-apache=DIR DIR is the path where apache sources are located. +The apache sources should have been configured before configuring mod_jk. +DIR is something like: /home/apache/apache_1.3.19 +It builds a static Apache module.
--enable-EAPI This parameter is needed when using Apache-1.3 and mod_ssl, otherwise you will get the error message: +"this module might crash under EAPI!" when loading mod_jk.so in httpd. +Not needed when --with-apxs has been used
--enable-prefork +In case you build mod_jk for a multi-threaded Apache httpd 2.0/2.2 MPM (Multi-Processing Module), +some areas of mod_jk code need to be synchronised to make it thread-safe. +Because configure can not easily detect, whether your are using a multi-threaded MPM, +mod_jk by default is always build thread-safe for Apache httpd 2.0/2.2. +If you are sure, that your MPM is not multi-threaded, you can use "--enable-prefork" +to force the removal of the synchronisation code (thus increasing performance a bit). +For instance, the prefork MPM is not multi-threaded. For Apache httpd 1.3 +this flag will be set automatically.
--disable-trace +When using log level "trace", mod_jk traces a lot of function calls with +"enter" and "exit" log messages. Even if the log level is not "trace", +comparing the log levels to decide about logging has some performance +impact.
+If you use "--disable-trace", then the trace log code doesn't get compiled +into the module binary and you might save some cycles during execution.
+Even with "--disable-trace" logging debug messages with debug log level +will still be possible.
--enable-api-compatibility +Only use httpd API functions available in all httpd production releases +of the chosen major httpd release branch. This improves binary +compatibility of module builds with httpd releases older than the release +against mod_jk is build (only between minor httpd versions).
--enable-flock +In case the operating system supports flock system call use this flag to enable this +faster locks that are implemented as system call instead emulated by GNU C library.
+However those locks does not work on NFS mounted volumes, so you can use +"--enable-flock" during compile time to force the flocks() calls.
+
+ + + + + + + + + + + + + + +
DEPRECATED: JNI related parameters
--enable-jni Build the JNI worker and so the build process will require +some information about your Java Environment
--with-java-home=DIR DIR is the patch to the JDK root directory. Something like: /opt/java/jdk12
--with-os-type=SUBDIR SUBDIR is the os-type subdirectory, + configure should guess it correctly.
--with-arch-type=SUBDIR SUBDIR is the arch subdirectory, + configure should guess it correctly.
--with-java-platform=VAL VAL is the Java platform 1 is 1.1.x and 2 is for 1.2 and higher, + configure should guess it correctly.
+
+
The JNI option has been deprecated. It will likely not work. Do not use it.
+
+ +
Examples of configure use
+ +
Apache 1.3 and 2.0/2.2 build
[user@host] ~ $ ./configure --with-apxs=/usr/sbin/apxs
[user@host] ~ $ make
[user@host] ~ $ cp ./apache-1.3/mod_jk.so /usr/lib/apache
[user@host] ~ $ make clean
[user@host] ~ $ ./configure --with-apxs=/usr/sbin/apxs2
[user@host] ~ $ make
[user@host] ~ $ cp ./apache-2.0/mod_jk.so /usr/lib/apache2
+ +
Apache 2.0/2.2 build with JNI support
[user@host] ~ $ ./configure --with-apxs2=/opt/apache2/bin/apxs \
--with-java-home=${JAVA_HOME} --with-java-platform=2 \
--enable-jni
+
The JNI option has been deprecated. It will likely not work. Do not use it.
+
+ +

Building mod_jk for Apache on Windows NT/2K/XP

+
+The module was developed using Visual C++ version 6.0, so having this environment is a prerequisite +if you want to perform a custom build. +
+
+The steps that you need to take are: +
+
+
+Change directory to the apache 1.3 or apache 2.0 source directory depending on your version of Apache. +
+
+If you want to build mod_jk for Apache 1.3, set an APACHE1_HOME environment variable which points +to where your Apache 1.3 is installed. +A mod_jk module for Apache 2.0 build will require APACHE2_HOME environment variable to be set. +
+
+Copy mod_jk.so to Apache's modules directory. +
+
+
+An example on how to build mod_jk for Apache 1.3: +
+
Set location for Apache 1.3 sources
c:\>set APACHE1_HOME=c:\apache13
Change directory to the mod_jk module for Apache 1.3
c:\>cd c:\home\apache\jk\native\apache-1.3
Build the sources using MSDEV
c:\>MSDEV mod_jk.dsp /MAKE ALL
Copy the dll to your apache modules directory
c:\>cp release\mod_jk.so c:\apache13\modules\
+ +
+An example on how to build mod_jk for Apache 2.0: +
+
Set location for Apache 2.0 sources
c:\>set APACHE2_HOME=c:\apache20
Change directory to the mod_jk module for Apache 2.0
c:\>cd c:\home\apache\jk\native\apache-2.0
Build the sources using MSDEV
c:\>MSDEV mod_jk.dsp /MAKE ALL
Copy the dll to your apache modules directory
c:\>cp release\mod_jk.so c:\apache20\modules\
+ +
+If msdev is not in your path, enter the full path to msdev.exe. +Also, ApacheCore.lib is expected to exist in the ${APACHEX_HOME}\src\CoreD and +${APACHEX_HOME}\src\CoreR directories before linking will succeed. +You will need to build enough of the Apache source to create these libraries. +This will build both release and debug versions of the redirector plug-in (mod_jk). +An alternative will be to open mod_jk.dsp in msdev and build it using the build menu. +
+

Building mod_jk for Apache on System I - i5/OS (OS400)

+
+Since OS400 V4R5, System I (AS/400) has used Apache 2.0 as their primary web server, +replacing the old IBM webserver. +It's now possible to build mod_jk on System I thanks to the help of the IBM +Rochester Labs which has provided information and patches to adapt mod_jk to i5/OS. +
+
+You should have at least Apache 2.0.58 (product 5722DG1), a C Compiler and IFS. +Apache 2.0.58 is provided with the most recent set of PTFs for the iSeries Apache +server, which can be found at +http://www.ibm.com/servers/eserver/iseries/software/http/ +
+
+The all latest Apache 2 for i5/OS V5R3 (or V5R4) is now 2.0.58 (as of 2007/04/17). +Be sure to have the latest PTFs loaded if you want to make use of jk 1.2.15 and higher. +NB: The latest mod_jk known to work on i5/OS V5R3 was 1.2.19. +
+
+New in i5/OS V5R4, UTF is required, also for Apache modules, as such Apache modules do not require +translations to/from EBCDIC but works should be done to port mod_jk 1.2.23 (and higher) to V5R4. + +From the V5R4 Infocenter : + +As of i5/OS(tm) V5R4, modules must be recompiled with a UTF locale. This creates an environment where locale-dependent C runtime functions assume +that string data is encoded in UTF-8. Any hardcoded constants can be encoded in UTF-8 by adding a #pragma convert(1208) statement in the module. +Additionally, input data from the client will no longer be converted to EBCDIC but will be passed as-is. +Output data sent from the module is not converted either so it must be encoded in ASCII or UTF8 as required. +APR and HTTP APIs as of V5R4, expect data in UTF-8. Note that several APIs have additional functions that allow a CCSID to be set to +indicate the encoding of the parameters being passed. Conversion functions between UTF-8 and EBCDIC have been added. +Be sure to review APIs used by your module to be aware of current changes. + +
+
+To configure mod_jk on System I use the CL source provided with the mod_jk source. +
+
+
+Get the latest mod_jk source and untar it on a Windows or Unix boxes +
+
+Create a directory in IFS, ie /home/apache +
+
+Send the whole jk source directory to System I directory via FTP. +
+
+Then go to the System I command line : +
+
+
Create mod_jk library
===>CRTLIB MOD_JK TEXT(‘Apache mod'jk tomcat connector module')
Create service program source file
===>CRTSRCPF MOD_JK/QSRVSRC TEXT(‘Service program source file’)
Create the CL build program source file
===>CRTSRCPF FILE(MOD_JK/QCLSRC) TEXT(‘Build program source file’)
Edit the service program source file
===>STRSEU MOD_JK/QSRVSRC MOD_JK
+
+In the edited file, specify that only jk_module should be exported : +
Columns . . : 1 71 Edit MOD_JK/QSRVSRC
SEU==> MOD_JK
*************** Beginning of data *************************************
0001.00 STRPGMEXP PGMLVL(*CURRENT)
0002.00 EXPORT SYMBOL("jk_module")
0003.00 ENDPGMEXP
****************** End of data ****************************************
+
+
+You could start to build all the modules of mod_jk (cases for V5R4 or previous releases): +
+
Copy the CL build program source for i5/OS before V5R4 from IFS
===>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk.qclsrc') +
TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK.MBR') MBROPT(*REPLACE)
Build the CL build program
===>CRTCLPGM PGM(MOD_JK/BLDJK) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program')
Launch the build
===>CALL MOD_JK/BLDJK
If the build if successfull, copy the new mod_jk module
===>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)
+
Copy the CL build program source for i5/OS V5R4 from IFS
===>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk54.qclsrc') +
TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK54.MBR') MBROPT(*REPLACE)
Build the CL build program for i5/OS V5R4
===>CRTCLPGM PGM(MOD_JK/BLDJK54) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program') TGTRLS(*CURRENT)
Launch the build for i5/OS V5R4
===>CALL MOD_JK/BLDJK54
If the build if successfull, copy the new mod_jk module
===>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)
+
+Next, you should restart your Apache 2.0 instance and enjoy this piece of OpenSource on System I. +
+
ENDTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)
STRTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)
+

Building mod_jk for Apache on MacOS/X

+
+Mac OS X (10.2.x) build notes : +
+
+Assuming that you are root : +
+
For Apache 1.3:
[user@host] ~ $ ./configure --with-apxs=/usr/sbin/apxs
[user@host] ~ $ cd apache-1.3
[user@host] ~ $ make -f Makefile.apxs
[user@host] ~ $ cp mod_jk.so /etc/libexec/httpd
For Apache 2.0:
[user@host] ~ $ ./configure --with-apxs=/usr/local/apache2/bin/apxs
(you should point to the directory where you installed Apache 2.0)
[user@host] ~ $ cd apache-2.0
[user@host] ~ $ make -f Makefile.apxs install
+

Getting mod_jk linked statically with Apache

+
+mod_jk allows to install mod_jk in the Apache source tree to get a statically +linked mod_jk. Having mod_jk in the httpd executable brings some performance +improvements. The configure option --with-apache prepare mod_jk to install it +in the Apache source tree. +The option --with-apache works both for Apache-1.3 and Apache-2.0. +The examples below show how to get mod_jk in the httpd process. +
+ +
Installation in Apache-2.0
+
/home/apache20/httpd-2.0.43 is the directory where the httpd-2.0 sources +are located.
[user@host] ~ $ ./configure --with-apache=/home/apache20/httpd-2.0.43
[user@host] ~ $ make
Install the mod_jk library and other files in +/home/apache20/httpd-2.0.43/modules:
[user@host] ~ $ make install
It is not possible to configure Apache directly because the config.m4 of mod_jk must +be added to the configure of httpd-2.0.
[user@host] ~ $ cd /home/apache20/httpd-2.0.43
[user@host] ~ $ sh buildconf
[user@host] ~ $ configure ... --with-mod_jk
[user@host] ~ $ make
[user@host] ~ $ make install
+
+The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only +allow static linking of mod_jk. +
+
+ +
Installation in Apache-1.3
+
/home/apache/apache_1.3.27 is the directory where the apache-1.3 sources +are located.
[user@host] ~ $ ./configure --with-apache=/home/apache/apache_1.3.27
[user@host] ~ $ make
Install the libjk library, mod_jk.c, includes and other files in +/home/apache/apache_1.3.27/src/modules/jk:
[user@host] ~ $ make install
Configure in the Apache sources:
[user@host] ~ $ cd /home/apache/apache_1.3.27
[user@host] ~ $ configure ... --enable-module=dir --disable-shared=dir \
--activate-module=src/modules/jk/libjk.a \
--disable-shared=jk
[user@host] ~ $ make
[user@host] ~ $ make install
+
+The --enable-shared=jk is also working and builds a dso file. +
+
Just change the configure in the Apache sources:
[user@host] ~ $ configure ... --enable-module=dir --enable-shared=dir \
--activate-module=src/modules/jk/libjk.a \
--enable-shared=jk
+
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html new file mode 100644 index 00000000..5dc4ea1b --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/iis.html @@ -0,0 +1,685 @@ +The Apache Tomcat Connector - Webserver HowTo - IIS HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Webserver HowTo

IIS HowTo

print-friendly
version +

Introduction

+
+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 JK ISAPI redirector plugin will let IIS send servlet and +JSP requests to Tomcat (and this way, serve them to clients). +
+ +
+It is recommended that you also read the +Workers HowTo document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +workers.properties, +uriworkermap +and IIS. +
+ + +
Document Conventions and Assumptions
+
+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +
+
+${tomcat_home}\conf - Where you can place various configuration files +
+
+${tomcat_home}\webapps - Containing example applications +
+
+${tomcat_home}\bin - Where you place web server plugins +
+
+
+
+In all the examples in this document ${tomcat_home} will be c:\tomcat. +A worker is defined to be a tomcat process that accepts work from the IIS server. +
+
+ + +
Supported Configuration
+
+The IIS-Tomcat redirector was developed and tested on: +
+
+WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +
+
+IIS4.0 and PWS4.0 (numerous people have working IIS 5 and IIS 6 configurations) +
+
+Tomcat 3.2 and later, Tomcat 4.x, Tomcat 5 and 5.5 and Tomcat 6 +
+
+
+ +
+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +
+
+ +
IIS 5 and 6 Notes
+
+There are extra steps you need to take for configuring Tomcat with IIS 5 and 6. Please see the appropriate links from +Tomcat Useful Links. +
+
+ +
IIS 7 notes
+
+There is a known bug in IIS that may result in incomplete log messages. See bug 45769 +for further details. +
+
+ +
Who support ajp protocols ?
+
+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +
+ +
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. +
+ +
+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +
+ +
+Others servlet engines such as jetty have support for ajp13 protocol +
+ +
+ +
How does it work ?
+
+
+
+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. +
+
+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. +
+
+The extension collects the request parameters and forwards them to the appropriate worker using the defined +protocol like ajp13. +
+
+The extension collects the response from the worker and returns it to the browser. +
+
+
+
+ +

Installation

+
+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: + +
+
+isapi_redirect.dll - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +
+
+uriworkermap.properties - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +
+
+
+ +
+The installation includes the following parts: + +
+
+Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +
+
+Adding more contexts to the configuration. +
+
+
+ +

Configuring the ISAPI Redirector

+
+In this document I will assume that isapi_redirect.dll is placed in +c:\tomcat\bin\win32\i386\isapi_redirect.dll and +that the properties files which you created are in c:\tomcat\conf. +
+
+
+
+In the registry, create a new registry key named +"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" +
+
+Add a string value with the name extension_uri and a value of /jakarta/isapi_redirect.dll +
+
+Add a string value with the name log_file and a value pointing to where you want your +log file to be (for example c:\tomcat\logs\isapi.log). +
+
+Add a string value with the name log_level and a value for your log level +(can be debug, info, error or emerg). +
+
+Add a string value with the name worker_file and a value which is the full path +to your workers.properties file (for example c:\tomcat\conf\workers.properties) +
+
+Add a string value with the name worker_mount_file and a value which is the full path +to your uriworkermap.properties file (for example c:\tomcat\conf\uriworkermap.properties) +
+
+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. +
+
+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 "Filter DLLs" key under +HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters. +This key contains a "," separated list of dlls (full paths) - +you need to insert the full path to isapi_redirect.dll. +
+
+If you're using IIS 6.0 you must also do the following: +
+Using the IIS management console, add the Jakarta Isapi Redirector to the Web +Service Extensions. +
+
Right-click on Web Service Extensions and choose Add a new Web Service +Extension.
+
Enter tomcat for the Extension Name.
+
Add the isapi_redirect.dll to the required files.
+
Check the Set extension status to Allowed.
+
Click on OK.
+
+
+
+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 cd WINDOWS\SYSTEM\inetsrv 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. +
+
+
+
+That's all, you should now start Tomcat and ask IIS to serve you the /examples context. +Try http://localhost/examples/jsp/index.html for example and +execute some of the JSP examples. +
+
+If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem. +
+ +
Adding additional Contexts
+
+The examples context is useful for verifying your installation, +but you will also need to add your own contexts. Adding a new context requires two operations: +
+
+
+
+Adding the context to Tomcat (I am not going to talk about this). +
+
+Adding the context to the ISAPI redirector. +
+
+
+
+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: +
+ +
+  /context/*=worker_name
+
+ +
+Workers and their name are defined in workers.properties, by default workers.properties comes +with a single pre-configured worker named "defworker" 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: +
+ +
+  /shop/*=defworker
+
+ +After saving uriworkermap.properties restart IIS and it will serve the new context. +
+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). +
+
+ +
Advanced Context Configuration
+
+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). +
+
+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. +
+
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.
+
+Making IIS serve static files that are part of the Tomcat contexts requires the following: +
+
+Configuring IIS to know about the Tomcat contexts +
+
+Configuring the redirector to leave the static files for IIS +
+
+
+ +
+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. +
+ +
+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 : + +
+  For the examples context it requires to replace the following line
+  /examples/*=defworker
+  with the following two lines
+  /examples/*.jsp=defworker
+  /examples/servlet/*=defworker
+
+
+ +
+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. +
+ +
+You can even be more explicit and provide lines such as: + +
+  /example/servletname=defworker
+
+
+ +
+that instructs the redirector to redirect all requests whose URL-path matches the leading string "/example/servletname" +to the worker named defworker. +
+ +
+ +
Protecting the content of your Tomcat contexts
+
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. +
+
+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. +
+
+ +
Advanced Worker Configuration
+
+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. +
+
+Defining additional workers is done in the workers.properties file. This file includes two types of entries: +
+ +
+
+  # 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
+
+
+ +
+The above example defined two workers, now we can use these workers to serve two different contexts +each with its own worker: +
+  example uriworkermap.properties fragment
+  /examples/*=worker1
+  /webpages/*=worker2
+
+
+ +
+As you can see the examples context is served by worker1 while the +webpages context is served by worker2. +
+ +
+More information on using and configuring workers in the Workers HowTo +and in the worker.properties configuration reference. +
+ +
+ +

Building ISAPI redirector

+
+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: +
+
+Change directory to the isapi plugins source directory. +
+
+Make the source with MSDEV +
+
+
Change directory to the isapi plugins source directory
c:\>cd c:\home\apache\jk\iis
Build the sources using MSDEV
c:\>MSDEV isapi.dsp /MAKE ALL
+
+
+If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and +build it using the build menu. +
+

Troubleshooting

+
+It is easy to have the ISAPI 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. +
+ +
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. +
+ +
+Note: These steps assume your worker_mount_file setting points to an unmodified copy of the +uriworkermap.properties file.
+Results may be misleading if worker_mount_file points to a modified uriworkermap.properties +or the uriworkermap.properties-auto file.
+It is also assumed that the "/examples" context works correctly if you access Tomcat directly. +
+ +
Win98
+
+Start the IIS service and Tomcat. +
+
+Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, verify the following: +
+
+
+Check the "Filter DLLs" setting in the "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters" +key and make sure the path is correct. +
+
+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. +
+
+Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +
+If the above are set correctly, the ISAPI redirector should be able to create the log file. +
+
+Invoke the URL http://localhost/examples/jsp/index.html +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 : +
+
+If the last line contains: +
+
+  GET "/examples/jsp/index.html HTTP/1.1" 404
+
+
+then the ISAPI redirector is not recognising that it should be handling requests for the "/examples" context. +Check the following: +
+
+
+Check the extension_uri name for typos. +
+
+Check the worker_file setting for typos, name and data. +
+
+Check the worker_mount_file setting typos, name and data. +
+If these are set correctly, the ISAPI redirector should recognise that it should handle requests for the "/examples" context. +
+ +
If the last line contains something like: +
+ +
+  GET "/jakarta/isapi_redirect.dll HTTP1.1"
+
+ +
+then the ISAPI redirector is recognising that it should handle the request, +but is not successful at getting Tomcat to service the request. +
+ +
+You should check the HTTP error code following GET "/..." : +
+ +
+  Error 404
+  GET "/..." 404
+
+ +
+
+Make sure you entered the URL correctly. +
+
+Make sure the virtual directory created was called "jakarta". +It should display in Personal Web Manager as "/jakarta" (without the quotes). +
+
+Make sure the extension_uri data begins with "/jakarta/" (without the quotes). +
+
+ +
+  Error 500
+  GET "/..." 500
+
+ +
+
+Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri setting. +
+
+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". +
+
+ +
+  Error 200 or 403
+  GET "/..." 200
+  GET "/..." 403
+
+ +
+
+Make sure you have checked Execute Access +for the jakarta virtual directory in the Advanced Options of the Personal Web Manager. +
+
+ +
+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. +
+ +
+ +
WinNT/Win2K/WinXP
+
+Start the World Wide Web Publishing Service and Tomcat. +
+
+Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, check the following: +
+
+
+Check the "executable" you set for the filter in the IIS Management Console and make sure the path is correct. +
+
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. +
+
+Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +
+If the above are set correctly, the ISAPI redirector should be able to create the log file. +
+ +
+Check the tomcat filter you added and make sure its status shows a green upward-pointing arrow. +If not, check the following: +
+
+
+Check the worker_file setting for typos, name and data. +
+
+Check the worker_mount_file setting typos, name and data. +
+If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong. +
+ +
+Invoke the URL http://localhost/examples/jsp/index.html +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. +
+ +
+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. +
+ +
+You should check the HTTP error code following GET "/..." : +
+ +
+  Error 404
+  GET "/..." 404
+
+ +
+
+Make sure you entered the URL correctly. +
+
+ +
+  Error 500
+  GET "/..." 500
+
+ +
+
+Make sure the virtual directory created was called "jakarta". +
+
+Make sure that the extension_uri setting is correct. +
+
+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". +
+
+ +
+  Error 200 or 403
+  GET "/..." 200
+  GET "/..." 403
+
+ +
+
+Make sure you have checked Execute Access for the jakarta virtual directory in the +Advanced Options of the Personal Web Manager. +
+
+ +
+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. +
+
+ + +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/nes.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/nes.html new file mode 100644 index 00000000..e9d60a2e --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/nes.html @@ -0,0 +1,483 @@ +The Apache Tomcat Connector - Webserver HowTo - SunOne -- Netscape/iPlanet HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Webserver HowTo

SunOne -- Netscape/iPlanet HowTo

print-friendly
version +

Introduction

+
+This document explains how to set up Sun ONE Web Server previously known as +Netscape web servers to cooperate with Tomcat. +
+ +
+Normally the Sun ONE Web Servers come with their own Servlet engine, +but you can also configure them to send servlet and JSP requests to Tomcat +using the NSAPI redirector plugin. +
+ +
+It is recommended that you also read the Workers HowTo document +to learn how to setup the working entities between your web server and Tomcat Engines. +
+ + +
Document Conventions and Assumptions
+
+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +
+
+${tomcat_home}\conf - Where you can place various configuration files +
+
+${tomcat_home}\webapps - Containing example applications +
+
+${tomcat_home}\bin - Where you place web server plugins +
+
+
+
+In all the examples in this document ${tomcat_home} will be c:\tomcat. +A worker is defined to be a tomcat process that accepts work from the Sun ONE Web Server. +
+
+ + +
Supported Configuration
+
+The NSAPI-Tomcat redirector was developed and tested on: +
+
+WINNT 2000/XP/2003 (should be able to work with other service packs) and some Unixes +
+
+Sun ONE Web Server 6.1 +
+
+Tomcat 4.1.x , Tomcat 5.0.x and Tomcat 5.5.x +
+
+
+ +
+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. +There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +
+
+ +
Who support ajp protocols ?
+
+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +
+ +
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6. +
+ +
+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +
+ +
+Others servlet engines such as jetty have support for ajp13 protocol +
+ +
+ + +
How does it work ?
+
+
+
+The NSAPI-Tomcat redirector is an Netscape service step plugin, +Netscape load the redirector plugin and calls its service handler +function for request that are assigned to the "servlet" configuration object. +
+
+For each in-coming request Netscape will execute the set of NameTrans directives +that we added to obj.conf, the assign-name function will check if it's from +parameter matches the request URL. +
+
+If a match is found, assign-name will assign the servlet object name to the request. +This will cause Netscape to send the request to the servlet configuration object. +
+
+Netscape will execute our jk_service extension. The extension collects the +request parameters and forwards them to the appropriate worker using the ajp13 protocol +(the worker="defworker" parameter in jk_service inform it that the worker for this request is named defworker). +the workers properties files, workers.properties, will indicate that defworker use ajp13 protocol. +
+
+The extension collects the response from the worker and returns it to the browser. +
+
+
+
+ +

Installation

+
+A pre-built version of the NSAPI redirector, nsapi_redirect.dll, may be available under +the win32/i386 directory of tomcat-connectors distribution. +For those using Netscape as your browser, try downloading a zip version of the file, if available. + +You can also build a copy locally from the source present in tomcat-connectors distribution. + + +The Tomcat redirector requires two entities: +
+
+nsapi_redirect.dll (Windows) -or- nsapi_redirector.so (Unix) - The NSAPI server plugin, either obtain a pre-built DLL/so or build it yourself +(see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +
+
+ +The installation includes the following parts: + +
+
+Configuring the NSAPI redirector with a default /examples context and checking that you can serve servlets +with Netscape. +
+
+Adding more contexts to the configuration. +
+
+ +
+

Configuring the NSAPI Redirector

+
+In this document we'll assume that nsapi_redirect.dll is placed in +c:\jk\lib\nsapi_redirect.dll, the properties file is inc:\jk\conf +and you created a log directory c:\jk\logs +
+ +
+
+If the built in servlet support is working disable it. +
+
+Add the redirector plugin into the Netscape server configuration. +Edit your server magnus.conf and add the following lines: +
+
+ +
+  
+  Init fn="load-modules" funcs="jk_init,jk_service" shlib="c:/jk/lib/nsapi_redirect.dll" shlib_flags="(global|now)"
+  Init fn="jk_init" worker_file="c:/jk/conf/workers.properties" log_level="debug" log_file="c:/jk/logs/nsapi.log" shm_file="c:/jk/logs/jk_shm"
+
+
+
+Edit your server obj.conf and add the following lines: +
+
+
+
+  
+  In the default object NameTrans section
+  <Object name="default">
+      
+  NameTrans fn="assign-name" from="/servlets-examples(|/*)" name="jknsapi" 
+  NameTrans fn="assign-name" from="/jsp-examples(|/*)" name="jknsapi"
+  ....
+  </Object>
+  
+  Create a new configuration object by adding the following lines to the end of the obj.conf file
+  
+  <Object name="jknsapi">
+  ObjectType fn=force-type type=text/plain
+  Service fn="jk_service" method="*" worker="worker1"
+  </Object>
+
+ +
+
+Edit your worker definition file workers.properties. You should at least choose a connection pool size: +
+
+ +
+  #An entry that lists all the workers defined. For example:
+  worker.list=worker1
+  
+  # Entries that define the host and port associated with these workers.
+  worker.worker1.host=localhost
+  worker.worker1.port=8009
+  worker.worker1.type=ajp13
+  worker.worker1.connection_pool_size=50
+
+ +
+
+Restart Web Server (stop and start the server) +
+
+ +
+That's all, now you should start tomcat and ask for http://server:port/servlets-examples/ +
+
+The file obj.conf seems to be sensitive to leading white space in lines, especially in +the Object element. Make sure you have no leading white space (no indentation) +on any line of this file. +
+ +
Adding additional Contexts
+
+The examples context is useful for verifying your installation, but you will also need to add your own contexts. +Adding a new context requires two operations: +
+
+
+Adding the context to Tomcat (I am not going to talk about this). +
+
+Assigning the NSAPI redirector to handle this context. +
+
+ +
+Assigning the NSAPI redirector to handle this context is simple, +all you need to do is to edit obj.conf and add a NameTrans line that looks like: +
+ +
+  NameTrans fn="assign-name" from="/<context name>/*" name="jknsapi"
+
+ +
+After saving obj.conf restart Netscape and it will serve the new context. +
+
+ +
Advanced Context Configuration
+
+Sometimes it is better to have Netscape serve the static pages (html, gif, jpeg etc.) +even if these files are part of a context served by Tomcat. For example, consider the html and gif files in the examples context, there is no need to serve them from the Tomcat process, Netscape will suffice. +
+
+Making Netscape serve static files that are part of the Tomcat contexts requires the following: +
+
+
+Configuring Netscape to know about the Tomcat contexts +
+
+Make sure that the WEB-INF directory is protected from access. +
+
+Configuring Netscape to assign the NSAPI redirector only specific requests that requires JSP/Servlet handling. +
+
+ +
+Adding a Tomcat context to Netscape requires the addition of a new Netscape virtual directory +that covers the Tomcat context. +
+ +
+For example, adding a /example Netscape virtual directory that +covers the c:\tomcat\webapps\examples directory. +
+ +
+To add a new virtual directory add the following line to your obj.conf: +
+ +
+  NameTrans fn=pfx2dir from=/examples dir="c:/tomcat/webapps/examples"
+
+ +
+WEB-INF protection requires some explanation; Each servlet application (context) has a special directory named WEB-INF, +this directory contains sensitive configurations data and Java classes and must be kept hidden from web users. +WEB-INF can be protected by adding the following line to the PathCheck section in the default configuration object: +
+ +
+  PathCheck fn="deny-existence" path="*/WEB-INF/*"
+  
+  This line instructs the Netscape server to reject any request with a URL that contain the path /WEB-INF/.
+
+ +
+Configuring Netscape to assign the NSAPI redirector only specific requests is somewhat harder, +you will need to specify the exact URL-Path pattern(s) that you want Tomcat to handle +(usually only JSP files and servlets). +
+ +
+This requires a change to NameTrans portion of obj.conf. +
+ +
+  For the examples context it requires to replace the following line:
+  
+  NameTrans fn="assign-name" from="/examples/*" name="jknsapi"
+  
+  with the following two lines:
+  
+  NameTrans fn="assign-name" from="/examples/jsp/*.jsp" name="jknsapi"
+  NameTrans fn="assign-name" from="/examples/servlet/*" name="jknsapi"
+
+ +
+As you can see the second configuration is more explicit, it actually instructs +Netscape to assign the redirector with only requests to resources under +/examples/servlet/ and resources under /examples/ whose name ends with .jsp. +
+ +
+You can be even more explicit and provide lines such as: +
+ +
+  NameTrans fn="assign-name" from="/examples/servletname" name="jknsapi"
+  
+  Instructs Netscape to assign the redirector request whose URL-Path equals /example/servletname
+
+ +
+ +
Advanced Worker Configuration
+
+Sometimes you want to serve different contexts with different Tomcat processes +(for example to spread the load among different machines). +To achieve such goal you will need to define several workers and assign each context with its own worker. +
+ +
+Defining workers is done in workers.properties, this file includes two types of entries: +
+ +
+  #An entry that lists all the workers defined. For example:
+  worker.list=worker1,worker2
+  
+  # Entries that define the host and port associated with these workers.
+  worker.worker1.host=localhost
+  worker.worker1.port=8009
+  worker.worker1.type=ajp13
+
+  worker.worker2.host=otherhost
+  worker.worker2.port=8009
+  worker.worker2.type=ajp13
+
+ +
+The above examples defined two workers, now we can use these workers to serve two different +contexts each with it's own worker. +Submitting requests to different workers is accomplished by using multiple Service directives +in the servlet configuration Object, each with a different path pattern parameter. +
+ +
+For example, if we want to submit the /examples context to the worker named worker1 and the +/webpages context to the worker named worker2 we should use the following configuration: +
+ +
+  <Object name="jknsapi">
+  ObjectType fn=force-type type=text/plain
+  Service fn="jk_service" worker="worker1" path="/examples/*"
+  Service fn="jk_service" worker="worker2" path="/webpages/*"
+  Service fn="jk_service" worker="worker1"
+  </Object>
+
+ +
+More informations on using and configuring workers in the Workers HowTo +and in the worker.properties configuration reference. + +
+
+ +

Building NSAPI DLL redirector for Windows

+
+The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want +to perform a custom build. You should also have NES developer SDK + +The steps that you need to take are: +
+
+Change directory to the nsapi plugins source directory. +
+
+Edit nsapi.dsp and update the include and library path to reflect your own Netscape server installation +(search for a /I compiler option and /libpath linker option) +
+
+Make the source with MSDEV +
+
+ +Change directory to the nsapi plugins source directory +c:\>cd c:\home\apache\jk\nsapi
+Build the sources using MSDEV +c:\>MSDEV nsapi.dsp /MAKE ALL
+ +
+
+If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the nsapi workspace file (nsapi.dsw) in msdev and +build it using the build menu. +
+

Building NSAPI so plugin redirector for Unix

+
+The redirector requires either gcc (Linux) or gcc or the Sun cc compiler (Solaris). + +The steps that you need to take are: +
+
+Change directory to the nsapi plugins source directory (src/native). +
+
+configure for Netscape/iPlanet/SunONE webserver. +
+
+Change directory to the nsapi netscape directory (./netstape). +
+
+Set environment variables JAVA_HOME resp. SUITSPOT_HOME to the location of your Java installation +resp. Netscape server installation. Depending on the web server version, you must add the subdirectory +"plugins" to SUITSPOT_HOME. +The variable is correct, if the file $SUITSPOT_HOME/include/nsapi.h exists. +
+
+Edit Makefile.solaris resp. Makefile.linux and update the variables according to your needs. +In the Solaris Makefile, you need to switch the commented lines in order to use the Sun compiler cc +instead of GNU gcc. +
+
+Make the source with gmake. +
+
+ +Change directory to the nsapi plugins source directory +c:\>cd /usr/local/src/tomcat-connectors-xxx-src/native
+configure for Netscape/iPlanet/SunONE webserver +c:\>./configure --enable-netscape
+Change directory to the nsapi netscape directory +c:\>cd netscape
+Set JAVA_HOME (ksh example) +c:\>export JAVA_HOME=/path/to/my/java
+Set SUITSPOT_HOME (ksh example) +c:\>export SUITSPOT_HOME=/path/to/my/netscape/server
+Edit the Makefile +c:\>vi Makefile.solaris
+Make the source with gmake +c:\>gmake -f Makefile.solaris
+ +
+
+After the build, you will have the required nsapi_redirector.so plugin. +
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/apache.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/apache.html new file mode 100644 index 00000000..ab972c65 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/apache.html @@ -0,0 +1,1123 @@ +The Apache Tomcat Connector - Webserver HowTo - Apache HTTP Server HowTo

The Apache Tomcat Connector - Webserver HowTo

Apache HTTP Server HowTo

Introduction

+
+This document explains how to connect Tomcat to the popular open source web server, Apache httpd. +There is actually three versions of Apache HTTP Server, 1.3, 2.0 and 2.2 and all can be used with mod_jk, +the Tomcat redirector module. +
+ +
+It is recommended that you also read the +Workers HowTo document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +workers.properties, +uriworkermap +and Apache. +
+ +
Waring: If Apache HTTP Server and Tomcat are configured to serve content from +the same filing system location then care must be taken to ensure that httpd is +not able to serve inappropriate content such as the contents of the WEB-INF +directory or JSP source code. This could occur if the httpd DocumentRoot +overlaps with a Tomcat Host's appBase or the docBase of any Context. It could +also occur when using the httpd Alias directive with a Tomcat Host's appBase or +the docBase of any Context. +
+ +
+This document was originally part of Tomcat: A Minimalistic User's Guide written by Gal Shachor, +but has been split off for organisational reasons. +
+ +
Document Conventions and Assumptions
+
+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +
+
+${tomcat_home}\conf - Where you can place various configuration files +
+
+${tomcat_home}\webapps - Containing example applications +
+
+${tomcat_home}\bin - Where you place web server plugins +
+
+
+
+In all the examples in this document ${tomcat_home} will be /var/tomcat3. +A worker is defined to be a tomcat process that accepts work from the Apache server. +
+
+ +
Supported Configuration
+
+The mod_jk module was developed and tested on: +
+
+Linux, FreeBSD, AIX, HP-UX, MacOS X, Solaris and should works on major Unixes platforms +supporting Apache 1.3 and/or 2.0/2.2 +
+
+WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +
+
+Cygwin (until you have an apache server and autoconf/automake support tools) +
+
+Netware +
+
+i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed. +
+
+Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x, Tomcat 5.0.x, Tomcat 5.5.x and Tomcat 6. +
+
+
+ +
+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +
+
+ +
Who support ajp protocols ?
+
+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +
+ +
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. +
+ +
+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +
+ +
+Others servlet engines such as jetty have support for ajp13 protocol +
+ +
+ +
How does it work ?
+
+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 behaviour. +Now the web server needs also to perform the following: +
+ +
+
+Load the servlet container adaptor library and initialise it (prior to serving requests). +
+
+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 adaptor take the request and handle it. +
+
+ +
+The adaptor 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. +
+ +
+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. +
+ +
+ +

Obtaining mod_jk

+
+mod_jk can be obtained in two formats - binary and source. +Depending on the platform you are running your web server on, a binary version of mod_jk may be available. +
+ +
+It is recommended to use the binary version if one is available. +If the binary is not available, follow the instructions for building mod_jk from source. +The mod_jk source can be downloaded from a mirror + +here +
+ +
+The binaries for mod_jk are now available for several platforms. +The binaries are located in subdirectories by platform. +
+ +
+For some platforms, such as Windows, this is the typical way of obtaining mod_jk +since most Windows systems do not have C compilers. +
+ +
+For others, the binary distribution of mod_jk offers simpler installation. +
+ +
+For example JK 1.2.x can be downloaded from a mirror + +here (look for JK 1.2 Binary Releases). The "JK 1.2 Binary Releases" link contains binary version for a variety of +operating systems for both Apache 1.3 and Apache 2. +
+ +

Installation

+
+mod_jk requires two entities: + +
+
+mod_jk.xxx - The Apache HTTP Server module, depending on your operating system, it will be mod_jk.so, mod_jk.nlm or +or MOD_JK.SRVPGM (see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory in the source download. +
+
+
+ +
+Also as with other Apache HTTP Server modules, mod_jk should be first installed on the modules directory of your +Apache webserver, ie : /usr/lib/apache and you should update your httpd.conf file. +
+ + +
Disabling old mod_jserv
+
+If you've previously configured Apache to use mod_jserv, remove any ApJServMount directives +from your httpd.conf. +
+ +
If you're including tomcat-apache.conf or tomcat.conf, you'll want to remove them as well - +they are specific to mod_jserv. +
+ +
+The mod_jserv configuration directives are not compatible with mod_jk ! +
+
+ +
Using Tomcat auto-configure
+
+The auto-configure works only for a single Tomcat running on the same machine where Apache HTTP Server is running. +The simplest way to configure Apache HTTP Server to use mod_jk is to turn on the Apache HTTP Server auto-configure setting +in Tomcat and put the following include directive at the end of your Apache httpd.conf file +(make sure you replace $TOMCAT_HOME with the correct path for your Tomcat installation: +
+ +
+    #To be added at the end of your httpd.conf
+    Include $TOMCAT_HOME/conf/jk/mod_jk.conf-auto
+
+ +
+Note: this file may also be generated as $TOMCAT_HOME/conf/auto/mod_jk.conf +
+ +
+This will tell Apache HTTP Server to use directives in the mod_jk.conf-auto file in +the Apache configuration. This file is created by enabling the Apache +auto-configuration by creating your workers.properties file at +$TOMCAT_HOME/conf/jk/workers.properties and adding the listener to the Engine +element in the server.xml file as per the following example. +Please note that this example is specific to Tomcat 5.x, unlike other sections of this document + which also apply to previous Tomcat branches. +
+
+  ...
+  <Engine ...>
+    ...
+    <Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" />
+    ...
+  </Engine>
+  ...
+
+ +
+Then restart Tomcat and mod_jk.conf should be generated. For more information on +this topic, please refer to the API documentation at the + +Tomcat docs website. +
+ +
+ +
Custom mod_jk configuration
+
+You should use custom configuration when : +
+
+
+You couldn't use mod_jk.conf-auto since Tomcat engine isn't on the same machine that your Apache web server, +ie when you have an Apache in front of a Tomcat Farm. +
+
+Another case for custom configuration is when your Apache is in front of many different Tomcat engines, +each one having it's own configuration, a general case in ISP hosting +
+
+Also all Apache webmaster will retain custom configuration to be able to tune the settings +to their real needs. +
+
+ +
+ +
Simple configuration example
+
+Here is a simple configuration: +
+ +
+    # Load mod_jk module
+    LoadModule    jk_module  libexec/mod_jk.so
+    # Declare the module for <IfModule directive> (remove this line on Apache 2.0.x)
+    AddModule     mod_jk.c
+    # Where to find workers.properties
+    JkWorkersFile /etc/httpd/conf/workers.properties
+    # Where to put jk shared memory
+    JkShmFile     /var/log/httpd/mod_jk.shm
+    # Where to put jk logs
+    JkLogFile     /var/log/httpd/mod_jk.log
+    # Set the jk log level [debug/error/info]
+    JkLogLevel    info
+    # Select the timestamp log format
+    JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+    # Send servlet for context /examples to worker named worker1
+    JkMount  /examples/servlet/* worker1
+    # Send JSPs  for context /examples to worker named worker1
+    JkMount  /examples/*.jsp worker1
+
+ +
+

mod_jk Directives

+
+We'll discuss here the mod_jk directives and details behind them +
+ +
Define workers
+
+JkWorkersFile specify the location where mod_jk will find the workers definitions. + +
+  JkWorkersFile     /etc/httpd/conf/workers.properties
+
+ +
+
+
+
+ +
Logging
+
+JkLogFile specify the location where mod_jk is going to place its log file. +
+ +
+  JkLogFile     /var/log/httpd/mod_jk.log
+
+ +
+Since JK 1.2.3 for Apache 2.0/2.2 and JK 1.2.16 for Apache 1.3 this can also +be used for piped logging: +
+ +
+  JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
+
+ +
+JkLogLevel +set the log level between : +
+ +
+
+info log will contains standard mod_jk activity (default). +
+
+error log will contains also error reports. +
+
+debug log will contains all information on mod_jk activity +
+
+ +
+  JkLogLevel    info
+
+ +
+info should be your default selection for normal operations. +
+
+
+ +
+JkLogStampFormat will configure the date/time format found on mod_jk logfile. +Using the strftime() format string it's set by default to "[%a %b %d %H:%M:%S %Y]" +
+ +
+  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+
+ +
+
+
+
+ +
+JkRequestLogFormat will configure the format of mod_jk individual request logging. +Request logging is configured and enabled on a per virtual host basis. +To enable request logging for a virtual host just add a JkRequestLogFormat config. +The syntax of the format string is similar to the Apache LogFormat command, +here is a list of the available request log format options: +
+ +
+ + + + + + + + + + + + + + + + +
Options Description
%b Bytes sent, excluding HTTP headers (CLF format)
%B Bytes sent, excluding HTTP headers
%H The request protocol
%m The request method
%p The canonical Port of the server serving the request
%q The query string (prepended with a ? if a query string exists, otherwise an empty string)
%r First line of request
%s Request HTTP status code
%T Request duration, elapsed time to handle request in seconds '.' micro seconds
%U The URL path requested, not including any query string.
%v The canonical ServerName of the server serving the request
%V The server name according to the UseCanonicalName setting
%w Tomcat worker name
%R Session route name (available with 1.2.19 and up)
+ +
+  JkRequestLogFormat     "%w %V %T"
+
+ +
+
+
+ +
+ +
Forwarding
+
+The directive JkOptions allow you to set many forwarding options which will enable (+) +or disable (-) following option. Without any leading signs, options will be enabled. +
+
+
+ +
+The four following options +ForwardURIxxx are mutually exclusive. +Exactly one of them is required, a negative sign prefix is not allowed with them. +The default value is "ForwardURIProxy" since version 1.2.24. +It was "ForwardURICompatUnparsed" in version 1.2.23 and +"ForwardURICompat" until version 1.2.22. +You can turn the default off by switching on one of the other two options. +You should leave this at it's default value, unless you have a very good +reason to change it. +
+
+
+ +
+All options are inherited from the global server to virtual hosts. +Options that support enabling (plus options) and disabling (minus options), +are inherited in the following way: +
+
+options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost) +
+
+
+ +
+Using JkOptions ForwardURIProxy, the forwarded URI +will be partially reencoded after processing inside Apache httpd and +before forwarding to Tomcat. This will be compatible with local +URL manipulation by mod_rewrite and with URL encoded session ids. + +
+  JkOptions     +ForwardURIProxy
+
+ +
+
+
+ +
+Using JkOptions ForwardURICompatUnparsed, the forwarded URI +will be unparsed. It's spec compliant and secure. +It will always forward the original request URI, so rewriting +URIs with mod_rewrite and then forwarding the rewritten URI +will not work. + +
+  JkOptions     +ForwardURICompatUnparsed
+
+ +
+
+
+
+Using JkOptions ForwardURICompat, the forwarded URI will +be decoded by Apache httpd. Encoded characters will be decoded and +explicit path components like ".." will already be resolved. +This is less spec compliant and is not safe if you are using +prefix JkMount. This option will allow to rewrite URIs with +mod_rewrite before forwarding. + +
+  JkOptions     +ForwardURICompat
+
+ +
+
+
+
+Using JkOptions ForwardURIEscaped, the forwarded URI will +be the encoded form of the URI used by ForwardURICompat. +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs, +but it will allow to rewrite URIs with mod_rewrite before forwarding. + +
+  JkOptions     +ForwardURIEscaped
+
+ +
+
+
+ +
+JkOptions RejectUnsafeURI will block all +URLs, which contain percent signs '%' or backslashes '\' +after decoding. +
+
+
+
+Most web apps do not use such URLs. Using the option RejectUnsafeURI, you +can block several well known URL encoding attacks. By default, this option +is not set. +
+
+You can also realise such a check with mod_rewrite, which is more powerful +but also slightly more complicated. + +
+  JkOptions     +RejectUnsafeURI
+
+ +
+
+
+ +
+JkOptions ForwardDirectories is used in conjunction with DirectoryIndex +directive of Apache web server. As such mod_dir should be available to Apache, +statically or dynamically (DSO) +
+
+
+ +
+When DirectoryIndex is configured, Apache will create sub-requests for +each of the local-url's specified in the directive, to determine if there is a +local file that matches (this is done by stat-ing the file). +
+ +
+If ForwardDirectories is set to false (default) and Apache doesn't find any +files that match, Apache will serve the content of the directory (if directive +Options specifies Indexes for that directory) or a 403 Forbidden response (if +directive Options doesn't specify Indexes for that directory). +
+ +
+If ForwarDirectories is set to true and Apache doesn't find any files that +match, the request will be forwarded to Tomcat for resolution. This is used in +cases when Apache cannot see the index files on the file system for various +reasons: Tomcat is running on a different machine, the JSP file has been +precompiled etc. +
+ +
Note that locally visible files will take precedence over the +ones visible only to Tomcat (i.e. if Apache can see the file, that's the one +that's going to get served). This is important if there is more then one type of +file that Tomcat normally serves - for instance Velocity pages and JSP pages. + +
+  JkOptions     +ForwardDirectories
+
+
+
+
+ +
+JkOptions ForwardLocalAddress, you ask mod_jk to send the local address, +of the Apache web server instead remote client address. This can be used by +Tomcat remote address valve for allowing connections only from registered Apache +web servers. + +
+  JkOptions     +ForwardLocalAddress
+
+ +
+
+
+ +
+JkOptions FlushPackets, you ask mod_jk to flush Apache's connection +buffer after each AJP packet chunk received from Tomcat. This option can have +a strong performance penalty for Apache and Tomcat as writes are performed +more often than would normally be required (ie: at the end of each +response). + +
+  JkOptions     +FlushPackets
+
+ +
+
+
+ +
+JkOptions FlushHeader, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +
+  JkOptions     +FlushHeader
+
+ +
+
+
+ +
+JkOptions DisableReuse, you ask mod_jk to close connections immediately +after their use. Normally mod_jk uses persistent connections and pools idle +connections to reuse them, when new requests have to be sent to Tomcat. +
+ +
+Using this option will have a strong performance penalty for Apache and Tomcat. +Use this only as a last resort in case of unfixable network problems. +If a firewall between Apache and Tomcat silently kills idle connections, +try to use the worker attribute socket_keepalive in combination with an appropriate +TCP keepalive value in your OS. + +
+  JkOptions     +DisableReuse
+
+ +
+
+
+ +
+JkOptions ForwardKeySize, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as +required by Servlet API 2.3. +This flag shouldn't be set when servlet engine is Tomcat 3.2.x (off by default). + +
+  JkOptions     +ForwardKeySize
+
+ +
+
+
+ +
+JkOptions ForwardSSLCertChain, you ask mod_jk, when using ajp13, +to forward SSL certificate chain (off by default). +Mod_jk only passes the SSL_CLIENT_CERT to the AJP connector. This is not a +problem with self-signed certificates or certificates directly signed by the +root CA certificate. However, there's a large number of certificates signed by +an intermediate CA certificate, where this is a significant problem: A servlet +will not have the possibility to validate the client certificate on its own. The +bug would be fixed by passing on the SSL_CLIENT_CERT_CHAIN to Tomcat via the AJP connector. +
+This directive exists only since version 1.2.22. +
+  JkOptions     +ForwardSSLCertChain
+
+ +
+
+
+ +
+The directive JkEnvVar allows you to forward environment variables +from Apache server to Tomcat engine. +You can add a default value as a second parameter to the directive. +If the default value is not given explicitly, the variable +will only be send, if it is set during runtime. +
+The variables can be retrieved on the Tomcat side as request attributes +via request.getAttribute(attributeName). +Note that the variables send via JkEnvVar will not be listed +in request.getAttributeNames(). +
+
+The variables are inherited from the global server to virtual hosts. + +
+  JkEnvVar     SSL_CLIENT_V_START     undefined
+
+
+
+
+ +
+ +
Assigning URLs to Tomcat
+
+If you have created a custom or local version of mod_jk.conf-local as noted above, +you can change settings such as the workers or URL prefix. +
+ +
+JkMount directive assign specific URLs to Tomcat. +In general the structure of a JkMount directive is: +
+ +
  JkMount [URL prefix] [Worker name]
+ +
+  # send all requests ending in .jsp to worker1
+  JkMount /*.jsp worker1
+  # send all requests ending /servlet to worker1
+  JkMount /*/servlet/ worker1
+  # send all requests jsp requests to files located in /otherworker will go worker2
+  JkMount /otherworker/*.jsp worker2
+
+ +
+You can use the JkMount directive at the top level or inside <VirtualHost> sections of your httpd.conf file. +
+
+ +
Configuring Apache to serve static web application files
+
+If the Tomcat Host appBase (webapps) directory is accessible by the Apache web server, +Apache can be configured to serve web application context directory static files instead +of passing the request to Tomcat. +
+ +
+Caution: For security reasons is is strongly recommended that JkMount is used to +pass all requests to Tomcat by default and JkUnMount is used to explicitly +exclude static content to be served by httpd. It should also be noted that +content served by httpd will bypass any security constraints defined in the +application's web.xml. +
+ +
Use Apache's Alias directive to map a single web application context directory into Apache's +document space for a VirtualHost: +
+ +
+  # Static files in the examples webapp are served by apache
+  Alias /examples /vat/tomcat3/webapps/examples
+  # All requests go to worker1 by default
+  JkMount /* worker1
+  # Serve html, jpg and gif using httpd
+  JkUnMount /*.html worker1
+  JkUnMount /*.jpg  worker1
+  JkUnMount /*.gif  worker1
+
+ +
+Starting with mod_jk 1.2.6 for Apache 2.0/2.2 and 1.2.19 for Apache 1.3, it's possible to exclude some URL/URI from +jk processing by setting the env var no-jk, for example with the SetEnvIf Directive. +
+ +
+You could use no-jk env var to fix problem with mod_alias or mod_userdir +directive when jk and alias/userdir URLs matches. +
+ +
+  # All URL goes to tomcat except the one containing /home
+  <VirtualHost *:80>
+      ServerName testxxx.mysys
+      DocumentRoot /www/testxxx/htdocs
+
+  # Use SetEnvIf to st no-jk when /home/ is encountered
+      SetEnvIf Request_URI "/home/*" no-jk
+
+  # Now /home will goes to /home/dataxxx/
+      Alias /home /home/dataxxx/
+
+      <Directory "/home/dataxxx">
+          Options Indexes MultiViews
+          AllowOverride None
+          Order allow,deny
+          Allow from all
+      </Directory>
+
+      JkMount /* myssys-xxx
+
+  </VirtualHost>
+
+ + +
+Use the mod_jk JkAutoAlias directive to map all web application context directories +into Apache's document space. +
+ +
+Attempts to access the WEB-INF or META-INF directories within a web application context +or a Web Archive *.war within the Tomcat Host appBase (webapps) directory will fail with an +HTTP 403, Access Forbidden +
+ +
+  # Static files in all Tomcat webapp context directories are served by apache
+  JkAutoAlias /var/tomcat3/webapps
+
+  # All requests go to worker1 by default
+  JkMount /* ajp13
+  # Serve html, jpg and gif using httpd
+  JkUnMount /*.html ajp13
+  JkUnMount /*.jpg  ajp13
+  JkUnMount /*.gif  ajp13
+
+ +
+If you encoded all your URLs to contain the session id +(;jsessionid=...), and you later decide, you want to +move part of the content to Apache httpd, you can tell +mod_jk to strip off all session ids from URLs for +those requests, that do not get forwarded via mod_jk. +
+ +
+You enable this feature by setting JkStripSession to On. +It can be enabled individually for virtual servers. The default +value is Off. +
+ +
+

Building mod_jk on Unix

+
+The mod_jk build use the widely used configure system. +
+
Prepare your mod_jk configure from subversion
+In case you get source from subversion, ie without an existing configure script, +you should have autoconf for configuration and installation. +
+To create tomcat-connectors's autoconf script, you will need libtool +1.5.2, automake 1.10 and autoconf 2.59 or newer. The use of more recent +versions is encouraged, e.g. for reliable detection of the features of +recent version of operating systems. +
+Those tools will not be required if you are just using a package downloaded from apache.org, +they are only required for developers. +
+
+To create the configure script just type : + +
[user@host] ~ $ ./buildconf.sh
+
+
+ +
Using configure to build mod_jk
+
Here's how to use configure to prepare mod_jk for building, just type: +
+./configure [autoconf arguments] [tomcat-connectors arguments]
+
+
+ +
+You could set CFLAGS and LDFLAGS to add some platform specifics: +
+ +
[user@host] ~ $ LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs
+ +
+If you want to build mod_jk for different version of Apache httpd, like 1.3, 2.0 and 2.2, +you need to go through the full build process for each of them. +Please note, that httpd 2.0 and 2.2 modules are not compatible. The mod_jk directory +used is "apache-2.0" in both cases, but you need to compile separately. +
+
+use configure and indicate the correct Apache httpd apxs location (--with-apxs) +
+
+use make +
+
+copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory +to the Apache httpd modules location. +
+
+make clean (to remove all previously compiled object files) +
+
+Start over with the apxs location for your next Apache httpd version. +
+
+ +
+
+ +
configure arguments
+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
Apache related parameters
--with-apxs[=FILE] FILE is the location of the apxs tool. Default is finding apxs in PATH. +It builds a shared Apache module. It detects automatically the Apache version. +(2.0/2.2 and 1.3)
--with-apache=DIR DIR is the path where apache sources are located. +The apache sources should have been configured before configuring mod_jk. +DIR is something like: /home/apache/apache_1.3.19 +It builds a static Apache module.
--enable-EAPI This parameter is needed when using Apache-1.3 and mod_ssl, otherwise you will get the error message: +"this module might crash under EAPI!" when loading mod_jk.so in httpd. +Not needed when --with-apxs has been used
--enable-prefork +In case you build mod_jk for a multi-threaded Apache httpd 2.0/2.2 MPM (Multi-Processing Module), +some areas of mod_jk code need to be synchronised to make it thread-safe. +Because configure can not easily detect, whether your are using a multi-threaded MPM, +mod_jk by default is always build thread-safe for Apache httpd 2.0/2.2. +If you are sure, that your MPM is not multi-threaded, you can use "--enable-prefork" +to force the removal of the synchronisation code (thus increasing performance a bit). +For instance, the prefork MPM is not multi-threaded. For Apache httpd 1.3 +this flag will be set automatically.
--disable-trace +When using log level "trace", mod_jk traces a lot of function calls with +"enter" and "exit" log messages. Even if the log level is not "trace", +comparing the log levels to decide about logging has some performance +impact.
+If you use "--disable-trace", then the trace log code doesn't get compiled +into the module binary and you might save some cycles during execution.
+Even with "--disable-trace" logging debug messages with debug log level +will still be possible.
--enable-api-compatibility +Only use httpd API functions available in all httpd production releases +of the chosen major httpd release branch. This improves binary +compatibility of module builds with httpd releases older than the release +against mod_jk is build (only between minor httpd versions).
--enable-flock +In case the operating system supports flock system call use this flag to enable this +faster locks that are implemented as system call instead emulated by GNU C library.
+However those locks does not work on NFS mounted volumes, so you can use +"--enable-flock" during compile time to force the flocks() calls.
+
+ + + + + + + + + + + + + + +
DEPRECATED: JNI related parameters
--enable-jni Build the JNI worker and so the build process will require +some information about your Java Environment
--with-java-home=DIR DIR is the patch to the JDK root directory. Something like: /opt/java/jdk12
--with-os-type=SUBDIR SUBDIR is the os-type subdirectory, + configure should guess it correctly.
--with-arch-type=SUBDIR SUBDIR is the arch subdirectory, + configure should guess it correctly.
--with-java-platform=VAL VAL is the Java platform 1 is 1.1.x and 2 is for 1.2 and higher, + configure should guess it correctly.
+
+
The JNI option has been deprecated. It will likely not work. Do not use it.
+
+ +
Examples of configure use
+ +
Apache 1.3 and 2.0/2.2 build
[user@host] ~ $ ./configure --with-apxs=/usr/sbin/apxs
[user@host] ~ $ make
[user@host] ~ $ cp ./apache-1.3/mod_jk.so /usr/lib/apache
[user@host] ~ $ make clean
[user@host] ~ $ ./configure --with-apxs=/usr/sbin/apxs2
[user@host] ~ $ make
[user@host] ~ $ cp ./apache-2.0/mod_jk.so /usr/lib/apache2
+ +
Apache 2.0/2.2 build with JNI support
[user@host] ~ $ ./configure --with-apxs2=/opt/apache2/bin/apxs \
--with-java-home=${JAVA_HOME} --with-java-platform=2 \
--enable-jni
+
The JNI option has been deprecated. It will likely not work. Do not use it.
+
+ +

Building mod_jk for Apache on Windows NT/2K/XP

+
+The module was developed using Visual C++ version 6.0, so having this environment is a prerequisite +if you want to perform a custom build. +
+
+The steps that you need to take are: +
+
+
+Change directory to the apache 1.3 or apache 2.0 source directory depending on your version of Apache. +
+
+If you want to build mod_jk for Apache 1.3, set an APACHE1_HOME environment variable which points +to where your Apache 1.3 is installed. +A mod_jk module for Apache 2.0 build will require APACHE2_HOME environment variable to be set. +
+
+Copy mod_jk.so to Apache's modules directory. +
+
+
+An example on how to build mod_jk for Apache 1.3: +
+
Set location for Apache 1.3 sources
c:\>set APACHE1_HOME=c:\apache13
Change directory to the mod_jk module for Apache 1.3
c:\>cd c:\home\apache\jk\native\apache-1.3
Build the sources using MSDEV
c:\>MSDEV mod_jk.dsp /MAKE ALL
Copy the dll to your apache modules directory
c:\>cp release\mod_jk.so c:\apache13\modules\
+ +
+An example on how to build mod_jk for Apache 2.0: +
+
Set location for Apache 2.0 sources
c:\>set APACHE2_HOME=c:\apache20
Change directory to the mod_jk module for Apache 2.0
c:\>cd c:\home\apache\jk\native\apache-2.0
Build the sources using MSDEV
c:\>MSDEV mod_jk.dsp /MAKE ALL
Copy the dll to your apache modules directory
c:\>cp release\mod_jk.so c:\apache20\modules\
+ +
+If msdev is not in your path, enter the full path to msdev.exe. +Also, ApacheCore.lib is expected to exist in the ${APACHEX_HOME}\src\CoreD and +${APACHEX_HOME}\src\CoreR directories before linking will succeed. +You will need to build enough of the Apache source to create these libraries. +This will build both release and debug versions of the redirector plug-in (mod_jk). +An alternative will be to open mod_jk.dsp in msdev and build it using the build menu. +
+

Building mod_jk for Apache on System I - i5/OS (OS400)

+
+Since OS400 V4R5, System I (AS/400) has used Apache 2.0 as their primary web server, +replacing the old IBM webserver. +It's now possible to build mod_jk on System I thanks to the help of the IBM +Rochester Labs which has provided information and patches to adapt mod_jk to i5/OS. +
+
+You should have at least Apache 2.0.58 (product 5722DG1), a C Compiler and IFS. +Apache 2.0.58 is provided with the most recent set of PTFs for the iSeries Apache +server, which can be found at +http://www.ibm.com/servers/eserver/iseries/software/http/ +
+
+The all latest Apache 2 for i5/OS V5R3 (or V5R4) is now 2.0.58 (as of 2007/04/17). +Be sure to have the latest PTFs loaded if you want to make use of jk 1.2.15 and higher. +NB: The latest mod_jk known to work on i5/OS V5R3 was 1.2.19. +
+
+New in i5/OS V5R4, UTF is required, also for Apache modules, as such Apache modules do not require +translations to/from EBCDIC but works should be done to port mod_jk 1.2.23 (and higher) to V5R4. + +From the V5R4 Infocenter : + +As of i5/OS(tm) V5R4, modules must be recompiled with a UTF locale. This creates an environment where locale-dependent C runtime functions assume +that string data is encoded in UTF-8. Any hardcoded constants can be encoded in UTF-8 by adding a #pragma convert(1208) statement in the module. +Additionally, input data from the client will no longer be converted to EBCDIC but will be passed as-is. +Output data sent from the module is not converted either so it must be encoded in ASCII or UTF8 as required. +APR and HTTP APIs as of V5R4, expect data in UTF-8. Note that several APIs have additional functions that allow a CCSID to be set to +indicate the encoding of the parameters being passed. Conversion functions between UTF-8 and EBCDIC have been added. +Be sure to review APIs used by your module to be aware of current changes. + +
+
+To configure mod_jk on System I use the CL source provided with the mod_jk source. +
+
+
+Get the latest mod_jk source and untar it on a Windows or Unix boxes +
+
+Create a directory in IFS, ie /home/apache +
+
+Send the whole jk source directory to System I directory via FTP. +
+
+Then go to the System I command line : +
+
+
Create mod_jk library
===>CRTLIB MOD_JK TEXT(‘Apache mod'jk tomcat connector module')
Create service program source file
===>CRTSRCPF MOD_JK/QSRVSRC TEXT(‘Service program source file’)
Create the CL build program source file
===>CRTSRCPF FILE(MOD_JK/QCLSRC) TEXT(‘Build program source file’)
Edit the service program source file
===>STRSEU MOD_JK/QSRVSRC MOD_JK
+
+In the edited file, specify that only jk_module should be exported : +
Columns . . : 1 71 Edit MOD_JK/QSRVSRC
SEU==> MOD_JK
*************** Beginning of data *************************************
0001.00 STRPGMEXP PGMLVL(*CURRENT)
0002.00 EXPORT SYMBOL("jk_module")
0003.00 ENDPGMEXP
****************** End of data ****************************************
+
+
+You could start to build all the modules of mod_jk (cases for V5R4 or previous releases): +
+
Copy the CL build program source for i5/OS before V5R4 from IFS
===>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk.qclsrc') +
TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK.MBR') MBROPT(*REPLACE)
Build the CL build program
===>CRTCLPGM PGM(MOD_JK/BLDJK) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program')
Launch the build
===>CALL MOD_JK/BLDJK
If the build if successfull, copy the new mod_jk module
===>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)
+
Copy the CL build program source for i5/OS V5R4 from IFS
===>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk54.qclsrc') +
TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK54.MBR') MBROPT(*REPLACE)
Build the CL build program for i5/OS V5R4
===>CRTCLPGM PGM(MOD_JK/BLDJK54) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program') TGTRLS(*CURRENT)
Launch the build for i5/OS V5R4
===>CALL MOD_JK/BLDJK54
If the build if successfull, copy the new mod_jk module
===>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)
+
+Next, you should restart your Apache 2.0 instance and enjoy this piece of OpenSource on System I. +
+
ENDTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)
STRTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)
+

Building mod_jk for Apache on MacOS/X

+
+Mac OS X (10.2.x) build notes : +
+
+Assuming that you are root : +
+
For Apache 1.3:
[user@host] ~ $ ./configure --with-apxs=/usr/sbin/apxs
[user@host] ~ $ cd apache-1.3
[user@host] ~ $ make -f Makefile.apxs
[user@host] ~ $ cp mod_jk.so /etc/libexec/httpd
For Apache 2.0:
[user@host] ~ $ ./configure --with-apxs=/usr/local/apache2/bin/apxs
(you should point to the directory where you installed Apache 2.0)
[user@host] ~ $ cd apache-2.0
[user@host] ~ $ make -f Makefile.apxs install
+

Getting mod_jk linked statically with Apache

+
+mod_jk allows to install mod_jk in the Apache source tree to get a statically +linked mod_jk. Having mod_jk in the httpd executable brings some performance +improvements. The configure option --with-apache prepare mod_jk to install it +in the Apache source tree. +The option --with-apache works both for Apache-1.3 and Apache-2.0. +The examples below show how to get mod_jk in the httpd process. +
+ +
Installation in Apache-2.0
+
/home/apache20/httpd-2.0.43 is the directory where the httpd-2.0 sources +are located.
[user@host] ~ $ ./configure --with-apache=/home/apache20/httpd-2.0.43
[user@host] ~ $ make
Install the mod_jk library and other files in +/home/apache20/httpd-2.0.43/modules:
[user@host] ~ $ make install
It is not possible to configure Apache directly because the config.m4 of mod_jk must +be added to the configure of httpd-2.0.
[user@host] ~ $ cd /home/apache20/httpd-2.0.43
[user@host] ~ $ sh buildconf
[user@host] ~ $ configure ... --with-mod_jk
[user@host] ~ $ make
[user@host] ~ $ make install
+
+The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only +allow static linking of mod_jk. +
+
+ +
Installation in Apache-1.3
+
/home/apache/apache_1.3.27 is the directory where the apache-1.3 sources +are located.
[user@host] ~ $ ./configure --with-apache=/home/apache/apache_1.3.27
[user@host] ~ $ make
Install the libjk library, mod_jk.c, includes and other files in +/home/apache/apache_1.3.27/src/modules/jk:
[user@host] ~ $ make install
Configure in the Apache sources:
[user@host] ~ $ cd /home/apache/apache_1.3.27
[user@host] ~ $ configure ... --enable-module=dir --disable-shared=dir \
--activate-module=src/modules/jk/libjk.a \
--disable-shared=jk
[user@host] ~ $ make
[user@host] ~ $ make install
+
+The --enable-shared=jk is also working and builds a dso file. +
+
Just change the configure in the Apache sources:
[user@host] ~ $ configure ... --enable-module=dir --enable-shared=dir \
--activate-module=src/modules/jk/libjk.a \
--enable-shared=jk
+
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/iis.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/iis.html new file mode 100644 index 00000000..498b71f0 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/iis.html @@ -0,0 +1,684 @@ +The Apache Tomcat Connector - Webserver HowTo - IIS HowTo

The Apache Tomcat Connector - Webserver HowTo

IIS HowTo

Introduction

+
+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 JK ISAPI redirector plugin will let IIS send servlet and +JSP requests to Tomcat (and this way, serve them to clients). +
+ +
+It is recommended that you also read the +Workers HowTo document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +workers.properties, +uriworkermap +and IIS. +
+ + +
Document Conventions and Assumptions
+
+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +
+
+${tomcat_home}\conf - Where you can place various configuration files +
+
+${tomcat_home}\webapps - Containing example applications +
+
+${tomcat_home}\bin - Where you place web server plugins +
+
+
+
+In all the examples in this document ${tomcat_home} will be c:\tomcat. +A worker is defined to be a tomcat process that accepts work from the IIS server. +
+
+ + +
Supported Configuration
+
+The IIS-Tomcat redirector was developed and tested on: +
+
+WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +
+
+IIS4.0 and PWS4.0 (numerous people have working IIS 5 and IIS 6 configurations) +
+
+Tomcat 3.2 and later, Tomcat 4.x, Tomcat 5 and 5.5 and Tomcat 6 +
+
+
+ +
+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +
+
+ +
IIS 5 and 6 Notes
+
+There are extra steps you need to take for configuring Tomcat with IIS 5 and 6. Please see the appropriate links from +Tomcat Useful Links. +
+
+ +
IIS 7 notes
+
+There is a known bug in IIS that may result in incomplete log messages. See bug 45769 +for further details. +
+
+ +
Who support ajp protocols ?
+
+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +
+ +
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. +
+ +
+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +
+ +
+Others servlet engines such as jetty have support for ajp13 protocol +
+ +
+ +
How does it work ?
+
+
+
+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. +
+
+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. +
+
+The extension collects the request parameters and forwards them to the appropriate worker using the defined +protocol like ajp13. +
+
+The extension collects the response from the worker and returns it to the browser. +
+
+
+
+ +

Installation

+
+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: + +
+
+isapi_redirect.dll - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +
+
+uriworkermap.properties - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +
+
+
+ +
+The installation includes the following parts: + +
+
+Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +
+
+Adding more contexts to the configuration. +
+
+
+ +

Configuring the ISAPI Redirector

+
+In this document I will assume that isapi_redirect.dll is placed in +c:\tomcat\bin\win32\i386\isapi_redirect.dll and +that the properties files which you created are in c:\tomcat\conf. +
+
+
+
+In the registry, create a new registry key named +"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" +
+
+Add a string value with the name extension_uri and a value of /jakarta/isapi_redirect.dll +
+
+Add a string value with the name log_file and a value pointing to where you want your +log file to be (for example c:\tomcat\logs\isapi.log). +
+
+Add a string value with the name log_level and a value for your log level +(can be debug, info, error or emerg). +
+
+Add a string value with the name worker_file and a value which is the full path +to your workers.properties file (for example c:\tomcat\conf\workers.properties) +
+
+Add a string value with the name worker_mount_file and a value which is the full path +to your uriworkermap.properties file (for example c:\tomcat\conf\uriworkermap.properties) +
+
+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. +
+
+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 "Filter DLLs" key under +HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters. +This key contains a "," separated list of dlls (full paths) - +you need to insert the full path to isapi_redirect.dll. +
+
+If you're using IIS 6.0 you must also do the following: +
+Using the IIS management console, add the Jakarta Isapi Redirector to the Web +Service Extensions. +
+
Right-click on Web Service Extensions and choose Add a new Web Service +Extension.
+
Enter tomcat for the Extension Name.
+
Add the isapi_redirect.dll to the required files.
+
Check the Set extension status to Allowed.
+
Click on OK.
+
+
+
+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 cd WINDOWS\SYSTEM\inetsrv 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. +
+
+
+
+That's all, you should now start Tomcat and ask IIS to serve you the /examples context. +Try http://localhost/examples/jsp/index.html for example and +execute some of the JSP examples. +
+
+If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem. +
+ +
Adding additional Contexts
+
+The examples context is useful for verifying your installation, +but you will also need to add your own contexts. Adding a new context requires two operations: +
+
+
+
+Adding the context to Tomcat (I am not going to talk about this). +
+
+Adding the context to the ISAPI redirector. +
+
+
+
+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: +
+ +
+  /context/*=worker_name
+
+ +
+Workers and their name are defined in workers.properties, by default workers.properties comes +with a single pre-configured worker named "defworker" 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: +
+ +
+  /shop/*=defworker
+
+ +After saving uriworkermap.properties restart IIS and it will serve the new context. +
+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). +
+
+ +
Advanced Context Configuration
+
+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). +
+
+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. +
+
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.
+
+Making IIS serve static files that are part of the Tomcat contexts requires the following: +
+
+Configuring IIS to know about the Tomcat contexts +
+
+Configuring the redirector to leave the static files for IIS +
+
+
+ +
+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. +
+ +
+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 : + +
+  For the examples context it requires to replace the following line
+  /examples/*=defworker
+  with the following two lines
+  /examples/*.jsp=defworker
+  /examples/servlet/*=defworker
+
+
+ +
+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. +
+ +
+You can even be more explicit and provide lines such as: + +
+  /example/servletname=defworker
+
+
+ +
+that instructs the redirector to redirect all requests whose URL-path matches the leading string "/example/servletname" +to the worker named defworker. +
+ +
+ +
Protecting the content of your Tomcat contexts
+
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. +
+
+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. +
+
+ +
Advanced Worker Configuration
+
+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. +
+
+Defining additional workers is done in the workers.properties file. This file includes two types of entries: +
+ +
+
+  # 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
+
+
+ +
+The above example defined two workers, now we can use these workers to serve two different contexts +each with its own worker: +
+  example uriworkermap.properties fragment
+  /examples/*=worker1
+  /webpages/*=worker2
+
+
+ +
+As you can see the examples context is served by worker1 while the +webpages context is served by worker2. +
+ +
+More information on using and configuring workers in the Workers HowTo +and in the worker.properties configuration reference. +
+ +
+ +

Building ISAPI redirector

+
+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: +
+
+Change directory to the isapi plugins source directory. +
+
+Make the source with MSDEV +
+
+
Change directory to the isapi plugins source directory
c:\>cd c:\home\apache\jk\iis
Build the sources using MSDEV
c:\>MSDEV isapi.dsp /MAKE ALL
+
+
+If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and +build it using the build menu. +
+

Troubleshooting

+
+It is easy to have the ISAPI 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. +
+ +
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. +
+ +
+Note: These steps assume your worker_mount_file setting points to an unmodified copy of the +uriworkermap.properties file.
+Results may be misleading if worker_mount_file points to a modified uriworkermap.properties +or the uriworkermap.properties-auto file.
+It is also assumed that the "/examples" context works correctly if you access Tomcat directly. +
+ +
Win98
+
+Start the IIS service and Tomcat. +
+
+Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, verify the following: +
+
+
+Check the "Filter DLLs" setting in the "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters" +key and make sure the path is correct. +
+
+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. +
+
+Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +
+If the above are set correctly, the ISAPI redirector should be able to create the log file. +
+
+Invoke the URL http://localhost/examples/jsp/index.html +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 : +
+
+If the last line contains: +
+
+  GET "/examples/jsp/index.html HTTP/1.1" 404
+
+
+then the ISAPI redirector is not recognising that it should be handling requests for the "/examples" context. +Check the following: +
+
+
+Check the extension_uri name for typos. +
+
+Check the worker_file setting for typos, name and data. +
+
+Check the worker_mount_file setting typos, name and data. +
+If these are set correctly, the ISAPI redirector should recognise that it should handle requests for the "/examples" context. +
+ +
If the last line contains something like: +
+ +
+  GET "/jakarta/isapi_redirect.dll HTTP1.1"
+
+ +
+then the ISAPI redirector is recognising that it should handle the request, +but is not successful at getting Tomcat to service the request. +
+ +
+You should check the HTTP error code following GET "/..." : +
+ +
+  Error 404
+  GET "/..." 404
+
+ +
+
+Make sure you entered the URL correctly. +
+
+Make sure the virtual directory created was called "jakarta". +It should display in Personal Web Manager as "/jakarta" (without the quotes). +
+
+Make sure the extension_uri data begins with "/jakarta/" (without the quotes). +
+
+ +
+  Error 500
+  GET "/..." 500
+
+ +
+
+Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri setting. +
+
+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". +
+
+ +
+  Error 200 or 403
+  GET "/..." 200
+  GET "/..." 403
+
+ +
+
+Make sure you have checked Execute Access +for the jakarta virtual directory in the Advanced Options of the Personal Web Manager. +
+
+ +
+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. +
+ +
+ +
WinNT/Win2K/WinXP
+
+Start the World Wide Web Publishing Service and Tomcat. +
+
+Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, check the following: +
+
+
+Check the "executable" you set for the filter in the IIS Management Console and make sure the path is correct. +
+
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. +
+
+Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +
+If the above are set correctly, the ISAPI redirector should be able to create the log file. +
+ +
+Check the tomcat filter you added and make sure its status shows a green upward-pointing arrow. +If not, check the following: +
+
+
+Check the worker_file setting for typos, name and data. +
+
+Check the worker_mount_file setting typos, name and data. +
+If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong. +
+ +
+Invoke the URL http://localhost/examples/jsp/index.html +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. +
+ +
+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. +
+ +
+You should check the HTTP error code following GET "/..." : +
+ +
+  Error 404
+  GET "/..." 404
+
+ +
+
+Make sure you entered the URL correctly. +
+
+ +
+  Error 500
+  GET "/..." 500
+
+ +
+
+Make sure the virtual directory created was called "jakarta". +
+
+Make sure that the extension_uri setting is correct. +
+
+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". +
+
+ +
+  Error 200 or 403
+  GET "/..." 200
+  GET "/..." 403
+
+ +
+
+Make sure you have checked Execute Access for the jakarta virtual directory in the +Advanced Options of the Personal Web Manager. +
+
+ +
+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. +
+
+ + +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/nes.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/nes.html new file mode 100644 index 00000000..efb8f5a5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/printer/nes.html @@ -0,0 +1,482 @@ +The Apache Tomcat Connector - Webserver HowTo - SunOne -- Netscape/iPlanet HowTo

The Apache Tomcat Connector - Webserver HowTo

SunOne -- Netscape/iPlanet HowTo

Introduction

+
+This document explains how to set up Sun ONE Web Server previously known as +Netscape web servers to cooperate with Tomcat. +
+ +
+Normally the Sun ONE Web Servers come with their own Servlet engine, +but you can also configure them to send servlet and JSP requests to Tomcat +using the NSAPI redirector plugin. +
+ +
+It is recommended that you also read the Workers HowTo document +to learn how to setup the working entities between your web server and Tomcat Engines. +
+ + +
Document Conventions and Assumptions
+
+${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +
+
+${tomcat_home}\conf - Where you can place various configuration files +
+
+${tomcat_home}\webapps - Containing example applications +
+
+${tomcat_home}\bin - Where you place web server plugins +
+
+
+
+In all the examples in this document ${tomcat_home} will be c:\tomcat. +A worker is defined to be a tomcat process that accepts work from the Sun ONE Web Server. +
+
+ + +
Supported Configuration
+
+The NSAPI-Tomcat redirector was developed and tested on: +
+
+WINNT 2000/XP/2003 (should be able to work with other service packs) and some Unixes +
+
+Sun ONE Web Server 6.1 +
+
+Tomcat 4.1.x , Tomcat 5.0.x and Tomcat 5.5.x +
+
+
+ +
+The redirector uses ajp12 and ajp13 to send requests to the Tomcat containers. +There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +
+
+ +
Who support ajp protocols ?
+
+The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +
+ +
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6. +
+ +
+Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +
+ +
+Others servlet engines such as jetty have support for ajp13 protocol +
+ +
+ + +
How does it work ?
+
+
+
+The NSAPI-Tomcat redirector is an Netscape service step plugin, +Netscape load the redirector plugin and calls its service handler +function for request that are assigned to the "servlet" configuration object. +
+
+For each in-coming request Netscape will execute the set of NameTrans directives +that we added to obj.conf, the assign-name function will check if it's from +parameter matches the request URL. +
+
+If a match is found, assign-name will assign the servlet object name to the request. +This will cause Netscape to send the request to the servlet configuration object. +
+
+Netscape will execute our jk_service extension. The extension collects the +request parameters and forwards them to the appropriate worker using the ajp13 protocol +(the worker="defworker" parameter in jk_service inform it that the worker for this request is named defworker). +the workers properties files, workers.properties, will indicate that defworker use ajp13 protocol. +
+
+The extension collects the response from the worker and returns it to the browser. +
+
+
+
+ +

Installation

+
+A pre-built version of the NSAPI redirector, nsapi_redirect.dll, may be available under +the win32/i386 directory of tomcat-connectors distribution. +For those using Netscape as your browser, try downloading a zip version of the file, if available. + +You can also build a copy locally from the source present in tomcat-connectors distribution. + + +The Tomcat redirector requires two entities: +
+
+nsapi_redirect.dll (Windows) -or- nsapi_redirector.so (Unix) - The NSAPI server plugin, either obtain a pre-built DLL/so or build it yourself +(see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +
+
+ +The installation includes the following parts: + +
+
+Configuring the NSAPI redirector with a default /examples context and checking that you can serve servlets +with Netscape. +
+
+Adding more contexts to the configuration. +
+
+ +
+

Configuring the NSAPI Redirector

+
+In this document we'll assume that nsapi_redirect.dll is placed in +c:\jk\lib\nsapi_redirect.dll, the properties file is inc:\jk\conf +and you created a log directory c:\jk\logs +
+ +
+
+If the built in servlet support is working disable it. +
+
+Add the redirector plugin into the Netscape server configuration. +Edit your server magnus.conf and add the following lines: +
+
+ +
+  
+  Init fn="load-modules" funcs="jk_init,jk_service" shlib="c:/jk/lib/nsapi_redirect.dll" shlib_flags="(global|now)"
+  Init fn="jk_init" worker_file="c:/jk/conf/workers.properties" log_level="debug" log_file="c:/jk/logs/nsapi.log" shm_file="c:/jk/logs/jk_shm"
+
+
+
+Edit your server obj.conf and add the following lines: +
+
+
+
+  
+  In the default object NameTrans section
+  <Object name="default">
+      
+  NameTrans fn="assign-name" from="/servlets-examples(|/*)" name="jknsapi" 
+  NameTrans fn="assign-name" from="/jsp-examples(|/*)" name="jknsapi"
+  ....
+  </Object>
+  
+  Create a new configuration object by adding the following lines to the end of the obj.conf file
+  
+  <Object name="jknsapi">
+  ObjectType fn=force-type type=text/plain
+  Service fn="jk_service" method="*" worker="worker1"
+  </Object>
+
+ +
+
+Edit your worker definition file workers.properties. You should at least choose a connection pool size: +
+
+ +
+  #An entry that lists all the workers defined. For example:
+  worker.list=worker1
+  
+  # Entries that define the host and port associated with these workers.
+  worker.worker1.host=localhost
+  worker.worker1.port=8009
+  worker.worker1.type=ajp13
+  worker.worker1.connection_pool_size=50
+
+ +
+
+Restart Web Server (stop and start the server) +
+
+ +
+That's all, now you should start tomcat and ask for http://server:port/servlets-examples/ +
+
+The file obj.conf seems to be sensitive to leading white space in lines, especially in +the Object element. Make sure you have no leading white space (no indentation) +on any line of this file. +
+ +
Adding additional Contexts
+
+The examples context is useful for verifying your installation, but you will also need to add your own contexts. +Adding a new context requires two operations: +
+
+
+Adding the context to Tomcat (I am not going to talk about this). +
+
+Assigning the NSAPI redirector to handle this context. +
+
+ +
+Assigning the NSAPI redirector to handle this context is simple, +all you need to do is to edit obj.conf and add a NameTrans line that looks like: +
+ +
+  NameTrans fn="assign-name" from="/<context name>/*" name="jknsapi"
+
+ +
+After saving obj.conf restart Netscape and it will serve the new context. +
+
+ +
Advanced Context Configuration
+
+Sometimes it is better to have Netscape serve the static pages (html, gif, jpeg etc.) +even if these files are part of a context served by Tomcat. For example, consider the html and gif files in the examples context, there is no need to serve them from the Tomcat process, Netscape will suffice. +
+
+Making Netscape serve static files that are part of the Tomcat contexts requires the following: +
+
+
+Configuring Netscape to know about the Tomcat contexts +
+
+Make sure that the WEB-INF directory is protected from access. +
+
+Configuring Netscape to assign the NSAPI redirector only specific requests that requires JSP/Servlet handling. +
+
+ +
+Adding a Tomcat context to Netscape requires the addition of a new Netscape virtual directory +that covers the Tomcat context. +
+ +
+For example, adding a /example Netscape virtual directory that +covers the c:\tomcat\webapps\examples directory. +
+ +
+To add a new virtual directory add the following line to your obj.conf: +
+ +
+  NameTrans fn=pfx2dir from=/examples dir="c:/tomcat/webapps/examples"
+
+ +
+WEB-INF protection requires some explanation; Each servlet application (context) has a special directory named WEB-INF, +this directory contains sensitive configurations data and Java classes and must be kept hidden from web users. +WEB-INF can be protected by adding the following line to the PathCheck section in the default configuration object: +
+ +
+  PathCheck fn="deny-existence" path="*/WEB-INF/*"
+  
+  This line instructs the Netscape server to reject any request with a URL that contain the path /WEB-INF/.
+
+ +
+Configuring Netscape to assign the NSAPI redirector only specific requests is somewhat harder, +you will need to specify the exact URL-Path pattern(s) that you want Tomcat to handle +(usually only JSP files and servlets). +
+ +
+This requires a change to NameTrans portion of obj.conf. +
+ +
+  For the examples context it requires to replace the following line:
+  
+  NameTrans fn="assign-name" from="/examples/*" name="jknsapi"
+  
+  with the following two lines:
+  
+  NameTrans fn="assign-name" from="/examples/jsp/*.jsp" name="jknsapi"
+  NameTrans fn="assign-name" from="/examples/servlet/*" name="jknsapi"
+
+ +
+As you can see the second configuration is more explicit, it actually instructs +Netscape to assign the redirector with only requests to resources under +/examples/servlet/ and resources under /examples/ whose name ends with .jsp. +
+ +
+You can be even more explicit and provide lines such as: +
+ +
+  NameTrans fn="assign-name" from="/examples/servletname" name="jknsapi"
+  
+  Instructs Netscape to assign the redirector request whose URL-Path equals /example/servletname
+
+ +
+ +
Advanced Worker Configuration
+
+Sometimes you want to serve different contexts with different Tomcat processes +(for example to spread the load among different machines). +To achieve such goal you will need to define several workers and assign each context with its own worker. +
+ +
+Defining workers is done in workers.properties, this file includes two types of entries: +
+ +
+  #An entry that lists all the workers defined. For example:
+  worker.list=worker1,worker2
+  
+  # Entries that define the host and port associated with these workers.
+  worker.worker1.host=localhost
+  worker.worker1.port=8009
+  worker.worker1.type=ajp13
+
+  worker.worker2.host=otherhost
+  worker.worker2.port=8009
+  worker.worker2.type=ajp13
+
+ +
+The above examples defined two workers, now we can use these workers to serve two different +contexts each with it's own worker. +Submitting requests to different workers is accomplished by using multiple Service directives +in the servlet configuration Object, each with a different path pattern parameter. +
+ +
+For example, if we want to submit the /examples context to the worker named worker1 and the +/webpages context to the worker named worker2 we should use the following configuration: +
+ +
+  <Object name="jknsapi">
+  ObjectType fn=force-type type=text/plain
+  Service fn="jk_service" worker="worker1" path="/examples/*"
+  Service fn="jk_service" worker="worker2" path="/webpages/*"
+  Service fn="jk_service" worker="worker1"
+  </Object>
+
+ +
+More informations on using and configuring workers in the Workers HowTo +and in the worker.properties configuration reference. + +
+
+ +

Building NSAPI DLL redirector for Windows

+
+The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want +to perform a custom build. You should also have NES developer SDK + +The steps that you need to take are: +
+
+Change directory to the nsapi plugins source directory. +
+
+Edit nsapi.dsp and update the include and library path to reflect your own Netscape server installation +(search for a /I compiler option and /libpath linker option) +
+
+Make the source with MSDEV +
+
+ +Change directory to the nsapi plugins source directory +c:\>cd c:\home\apache\jk\nsapi
+Build the sources using MSDEV +c:\>MSDEV nsapi.dsp /MAKE ALL
+ +
+
+If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the nsapi workspace file (nsapi.dsw) in msdev and +build it using the build menu. +
+

Building NSAPI so plugin redirector for Unix

+
+The redirector requires either gcc (Linux) or gcc or the Sun cc compiler (Solaris). + +The steps that you need to take are: +
+
+Change directory to the nsapi plugins source directory (src/native). +
+
+configure for Netscape/iPlanet/SunONE webserver. +
+
+Change directory to the nsapi netscape directory (./netstape). +
+
+Set environment variables JAVA_HOME resp. SUITSPOT_HOME to the location of your Java installation +resp. Netscape server installation. Depending on the web server version, you must add the subdirectory +"plugins" to SUITSPOT_HOME. +The variable is correct, if the file $SUITSPOT_HOME/include/nsapi.h exists. +
+
+Edit Makefile.solaris resp. Makefile.linux and update the variables according to your needs. +In the Solaris Makefile, you need to switch the commented lines in order to use the Sun compiler cc +instead of GNU gcc. +
+
+Make the source with gmake. +
+
+ +Change directory to the nsapi plugins source directory +c:\>cd /usr/local/src/tomcat-connectors-xxx-src/native
+configure for Netscape/iPlanet/SunONE webserver +c:\>./configure --enable-netscape
+Change directory to the nsapi netscape directory +c:\>cd netscape
+Set JAVA_HOME (ksh example) +c:\>export JAVA_HOME=/path/to/my/java
+Set SUITSPOT_HOME (ksh example) +c:\>export SUITSPOT_HOME=/path/to/my/netscape/server
+Edit the Makefile +c:\>vi Makefile.solaris
+Make the source with gmake +c:\>gmake -f Makefile.solaris
+ +
+
+After the build, you will have the required nsapi_redirector.so plugin. +
+

\ No newline at end of file -- cgit 1.2.3-korg