diff options
| author |   hongbotian <hongbo.tianhongbo@huawei.com> | 2015-11-30 02:41:33 -0500 |
|---|---|---|
| committer | hongbotian <hongbo.tianhongbo@huawei.com> | 2015-11-30 02:43:36 -0500 |
| commit | 9401f816dd0d9d550fe98a8507224bde51c4b847 (patch) | |
| tree | 94f2d7a7893a787bafdca8b5ef063ea316938874 /rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml | |
| parent | e8ec7aa8e38a93f5b034ac74cebce5de23710317 (diff) | |
upload tomcat
JIRA: BOTTLENECK-7
Change-Id: I875d474869efd76ca203c30b60ebc0c3ee606d0e
Signed-off-by: hongbotian <hongbo.tianhongbo@huawei.com>
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml')
| -rw-r--r-- | rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml | 1287 |
1 files changed, 1287 insertions, 0 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml new file mode 100644 index 00000000..7e35b0e9 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml @@ -0,0 +1,1287 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="apache.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Apache HTTP Server HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<author email="shachor@il.ibm.com">Gal Shachor</author> +<date>$Date: 2011-06-30 21:16:43 +0200 (Thu, 30 Jun 2011) $</date> +</properties> +<body> +<section name="Introduction"> +<p> +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. +</p> + +<p> +It is recommended that you also read the +<a href="../generic_howto/workers.html">Workers HowTo</a> document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +<a href="../reference/worker.html">workers.properties</a>, +<a href="../reference/uriworkermap.html">uriworkermap</a> +and <a href="../reference/apache.html">Apache</a>. +</p> + +<p><b>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.</b> 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. +</p> + +<p> +This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor, +but has been split off for organisational reasons. +</p> + +<subsection name="Document Conventions and Assumptions"> +<p> +${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +<ul> +<li> +${tomcat_home}\conf - Where you can place various configuration files +</li> +<li> +${tomcat_home}\webapps - Containing example applications +</li> +<li> +${tomcat_home}\bin - Where you place web server plugins +</li> +</ul> +</p> +<p> +In all the examples in this document ${tomcat_home} will be <b>/var/tomcat3</b>. +A <a href="../generic_howto/workers.html">worker</a> is defined to be a tomcat process that accepts work from the Apache server. +</p> +</subsection> + +<subsection name="Supported Configuration"> +<p> +The mod_jk module was developed and tested on: +<ul> +<li> +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 +</li> +<li> +WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +</li> +<li> +Cygwin (until you have an apache server and autoconf/automake support tools) +</li> +<li> +Netware +</li> +<li> +i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed. +</li> +<li> +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. +</li> +</ul> +</p> + +<p> +The redirector uses <b>ajp12</b> and <b>ajp13</b> to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +</p> +</subsection> + +<subsection name="Who support ajp protocols ?"> +<p> +The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +</p> + +<p> +The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead +<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6. +</p> + +<p> +Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +</p> + +<p> +Others servlet engines such as <b>jetty</b> have support for ajp13 protocol +</p> + +</subsection> + +<subsection name="How does it work ?"> +<p> +In a nutshell a web server is waiting for client HTTP requests. +When these requests arrive the server does whatever is needed to serve the +requests by providing the necessary content. +</p> + +<p> +Adding a servlet container may somewhat change this behaviour. +Now the web server needs also to perform the following: +</p> + +<ul> +<li> +Load the servlet container adaptor library and initialise it (prior to serving requests). +</li> +<li> +When a request arrives, it needs to check and see if a certain request belongs to a servlet, +if so it needs to let the adaptor take the request and handle it. +</li> +</ul> + +<p> +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. +</p> + +<p> +Things are even more complex when the user wants to set a configuration that uses virtual hosts, +or when they want multiple developers to work on the same web server +but on different servlet container JVMs. +We will cover these two cases in the advanced sections. +</p> + +</subsection> + +</section> + +<section name="Obtaining mod_jk"> +<p> +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. +</p> + +<p> +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 +<a href="http://tomcat.apache.org/download-connectors.cgi"> +here</a> +</p> + +<p> +The binaries for mod_jk are now available for several platforms. +The binaries are located in subdirectories by platform. +</p> + +<p> +For some platforms, such as Windows, this is the typical way of obtaining mod_jk +since most Windows systems do not have C compilers. +</p> + +<p> +For others, the binary distribution of mod_jk offers simpler installation. +</p> + +<p> +For example JK 1.2.x can be downloaded from a mirror +<a href="http://tomcat.apache.org/download-connectors.cgi"> +here</a> (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. +</p> + +</section> + +<section name="Installation"> +<p> +mod_jk requires two entities: + +<ul> +<li> +<b>mod_jk.xxx</b> - 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). +</li> +<li> +<b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory in the source download. +</li> +</ul> +</p> + +<p> +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 <b>httpd.conf</b> file. +</p> + + +<subsection name="Disabling old mod_jserv"> +<p> +If you've previously configured Apache to use <b>mod_jserv</b>, remove any <b>ApJServMount</b> directives +from your httpd.conf. +</p> + +<p>If you're including <b>tomcat-apache.conf</b> or <b>tomcat.conf</b>, you'll want to remove them as well - +they are specific to <b>mod_jserv</b>. +</p> + +<p> +The mod_jserv configuration directives are not compatible with mod_jk ! +</p> +</subsection> + +<subsection name="Using Tomcat auto-configure"> +<p> +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: +</p> + +<source> + #To be added at the end of your httpd.conf + Include $TOMCAT_HOME/conf/jk/mod_jk.conf-auto +</source> + +<p> +Note: this file may also be generated as $TOMCAT_HOME/conf/auto/mod_jk.conf +</p> + +<p> +This will tell Apache HTTP Server to use directives in the <b>mod_jk.conf-auto</b> 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. +<b>Please note that this example is specific to Tomcat 5.x, unlike other sections of this document + which also apply to previous Tomcat branches.</b> +</p> +<source> + ... + <Engine ...> + ... + <Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" /> + ... + </Engine> + ... +</source> + +<p> +Then restart Tomcat and mod_jk.conf should be generated. For more information on +this topic, please refer to the API documentation at the +<a href="http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/jk/config/ApacheConfig.html"> +Tomcat docs website</a>. +</p> + +</subsection> + +<subsection name="Custom mod_jk configuration"> +<p> +You should use custom configuration when : +</p> +<ul> +<li> +You couldn't use <b>mod_jk.conf-auto</b> 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. +</li> +<li> +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 +</li> +<li> +Also all Apache webmaster will retain custom configuration to be able to tune the settings +to their real needs. +</li> +</ul> + +</subsection> + +<subsection name="Simple configuration example"> +<p> +Here is a simple configuration: +</p> + +<source> + # 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 +</source> + +</subsection> +</section> + +<section name="mod_jk Directives"> +<p> +We'll discuss here the mod_jk directives and details behind them +</p> + +<subsection name="Define workers"> +<p> +<b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions. + +<source> + JkWorkersFile /etc/httpd/conf/workers.properties +</source> + +<br/> +<br/> +</p> +</subsection> + +<subsection name="Logging"> +<p> +<b>JkLogFile</b> specify the location where mod_jk is going to place its log file. +</p> + +<source> + JkLogFile /var/log/httpd/mod_jk.log +</source> + +<p> +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: +</p> + +<source> + JkLogFile "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400" +</source> + +<p> +<b>JkLogLevel</b> +set the log level between : +</p> + +<ul> +<li> +<b>info</b> log will contains standard mod_jk activity (default). +</li> +<li> +<b>error</b> log will contains also error reports. +</li> +<li> +<b>debug</b> log will contains all information on mod_jk activity +</li> +</ul> + +<source> + JkLogLevel info +</source> + +<p> +<code>info</code> should be your default selection for normal operations. +<br/> +<br/> +</p> + +<p> +<b>JkLogStampFormat</b> will configure the date/time format found on mod_jk logfile. +Using the strftime() format string it's set by default to <b>"[%a %b %d %H:%M:%S %Y]"</b> +</p> + +<source> + JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " +</source> + +<p> +<br/> +<br/> +</p> + +<p> +<b>JkRequestLogFormat</b> 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: +</p> + +<p> +<table> + <tr><th>Options</th><th>Description</th></tr> + <tr><td>%b</td><td>Bytes sent, excluding HTTP headers (CLF format)</td></tr> + <tr><td>%B</td><td>Bytes sent, excluding HTTP headers</td></tr> + <tr><td>%H</td><td>The request protocol</td></tr> + <tr><td>%m</td><td>The request method</td></tr> + <tr><td>%p</td><td>The canonical Port of the server serving the request</td></tr> + <tr><td>%q</td><td>The query string (prepended with a ? if a query string exists, otherwise an empty string)</td></tr> + <tr><td>%r</td><td>First line of request</td></tr> + <tr><td>%s</td><td>Request HTTP status code</td></tr> + <tr><td>%T</td><td>Request duration, elapsed time to handle request in seconds '.' micro seconds</td></tr> + <tr><td>%U</td><td>The URL path requested, not including any query string.</td></tr> + <tr><td>%v</td><td>The canonical ServerName of the server serving the request</td></tr> + <tr><td>%V</td><td>The server name according to the UseCanonicalName setting</td></tr> + <tr><td>%w</td><td>Tomcat worker name</td></tr> + <tr><td>%R</td><td>Session route name (available with 1.2.19 and up)</td></tr> +</table> + +<source> + JkRequestLogFormat "%w %V %T" +</source> + +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Forwarding"> +<p> +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. +<br/> +<br/> +</p> + +<p> +The four following options <b>+ForwardURIxxx</b> 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. +<br/> +<br/> +</p> + +<p> +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: +<br/> +<br/> +options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost) +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURIProxy</b>, 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. + +<source> + JkOptions +ForwardURIProxy +</source> + +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURICompatUnparsed</b>, 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. + +<source> + JkOptions +ForwardURICompatUnparsed +</source> + +<br/> +<br/> +</p> +<p> +Using JkOptions <b>ForwardURICompat</b>, 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 <b>not safe</b> if you are using +prefix JkMount. This option will allow to rewrite URIs with +mod_rewrite before forwarding. + +<source> + JkOptions +ForwardURICompat +</source> + +<br/> +<br/> +</p> +<p> +Using JkOptions <b>ForwardURIEscaped</b>, 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. + +<source> + JkOptions +ForwardURIEscaped +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>RejectUnsafeURI</b> will block all +URLs, which contain percent signs '%' or backslashes '\' +after decoding. +<br/> +<br/> +</p> +<p> +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. +</p> +<p> +You can also realise such a check with mod_rewrite, which is more powerful +but also slightly more complicated. + +<source> + JkOptions +RejectUnsafeURI +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b> +directive of Apache web server. As such mod_dir should be available to Apache, +statically or dynamically (DSO) +<br/> +<br/> +</p> + +<p> +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). +</p> + +<p> +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 <code>403 Forbidden</code> response (if +directive Options doesn't specify Indexes for that directory). +</p> + +<p> +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. +</p> + +<p>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. + +<source> + JkOptions +ForwardDirectories +</source> +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardLocalAddress</b>, 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. + +<source> + JkOptions +ForwardLocalAddress +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>FlushPackets</b>, 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). + +<source> + JkOptions +FlushPackets +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +<source> + JkOptions +FlushHeader +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>DisableReuse</b>, 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. +</p> + +<p> +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. + +<source> + JkOptions +DisableReuse +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardKeySize</b>, 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). + +<source> + JkOptions +ForwardKeySize +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardSSLCertChain</b>, you ask mod_jk, when using ajp13, +to forward SSL certificate chain (off by default). +Mod_jk only passes the <code>SSL_CLIENT_CERT</code> 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 <code>SSL_CLIENT_CERT_CHAIN</code> to Tomcat via the AJP connector. +<br/> +This directive exists only since version 1.2.22. +<source> + JkOptions +ForwardSSLCertChain +</source> + +<br/> +<br/> +</p> + +<p> +The directive <b>JkEnvVar</b> 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. +<br/> +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(). +<br/> +<br/> +The variables are inherited from the global server to virtual hosts. + +<source> + JkEnvVar SSL_CLIENT_V_START undefined +</source> +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Assigning URLs to Tomcat"> +<p> +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. +</p> + +<p> +<b>JkMount</b> directive assign specific URLs to Tomcat. +In general the structure of a JkMount directive is: +</p> + +<source> JkMount [URL prefix] [Worker name]</source> + +<source> + # 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 +</source> + +<p> +You can use the JkMount directive at the top level or inside <VirtualHost> sections of your httpd.conf file. +</p> +</subsection> + +<subsection name="Configuring Apache to serve static web application files"> +<p> +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. +</p> + +<p> +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. +</p> + +<p>Use Apache's <b>Alias</b> directive to map a single web application context directory into Apache's +document space for a VirtualHost: +</p> + +<source> + # 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 +</source> + +<p> +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 <b>no-jk</b>, for example with the SetEnvIf Directive. +</p> + +<p> +You could use <b>no-jk</b> env var to fix problem with mod_alias or mod_userdir +directive when jk and alias/userdir URLs matches. +</p> + +<source> + # 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> +</source> + + +<p> +Use the mod_jk <b>JkAutoAlias</b> directive to map all web application context directories +into Apache's document space. +</p> + +<p> +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 +<code>HTTP 403, Access Forbidden</code> +</p> + +<source> + # 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 +</source> + +<p> +If you encoded all your URLs to contain the session id +(<code>;jsessionid=...</code>), 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. +</p> + +<p> +You enable this feature by setting JkStripSession to On. +It can be enabled individually for virtual servers. The default +value is Off. +</p> + +</subsection> +</section> + +<section name="Building mod_jk on Unix"> +<p> +The mod_jk build use the widely used configure system. +</p> +<subsection name="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. +<p> +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. +</p><p> +Those tools will not be required if you are just using a package downloaded from apache.org, +they are only required for developers. +</p> +<p> +To create the configure script just type : + +<screen> +<type>./buildconf.sh</type> +</screen> +</p> +</subsection> + +<subsection name="Using configure to build mod_jk"> +<p>Here's how to use configure to prepare mod_jk for building, just type: +<source> +./configure [autoconf arguments] [tomcat-connectors arguments] +</source> +</p> + +<p> +You could set <b>CFLAGS</b> and <b>LDFLAGS</b> to add some platform specifics: +</p> + +<screen> +<type>LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs</type> +</screen> + +<p> +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 <b>not</b> compatible. The mod_jk directory +used is "apache-2.0" in both cases, but you need to compile separately. +<ul> +<li> +use configure and indicate the correct Apache httpd apxs location (--with-apxs) +</li> +<li> +use make +</li> +<li> +copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory +to the Apache httpd modules location. +</li> +<li> +make clean (to remove all previously compiled object files) +</li> +<li> +Start over with the apxs location for your next Apache httpd version. +</li> +</ul> + +</p> +</subsection> + +<subsection name="configure arguments"> +<p> +<table> + <tr valign="top"><th>Apache related parameters</th><th></th></tr> + <tr valign="top"> + <td>--with-apxs[=FILE]</td> + <td>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)</td> + </tr> + <tr valign="top"><td>--with-apache=DIR</td> + <td>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.</td> + </tr> + <tr valign="top"><td>--enable-EAPI</td> + <td>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</td> +</tr> + <tr valign="top"><td>--enable-prefork</td> + <td> +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.</td> +</tr> + <tr valign="top"><td>--disable-trace</td> + <td> +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.<br/> +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.<br/> +Even with "--disable-trace" logging debug messages with debug log level +will still be possible.</td> +</tr> + <tr valign="top"><td>--enable-api-compatibility</td> + <td> +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).</td> +</tr> + <tr valign="top"><td>--enable-flock</td> + <td> +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.<br/> +However those locks does not work on NFS mounted volumes, so you can use +"--enable-flock" during compile time to force the flocks() calls.</td> +</tr> + +</table> +<br/> +<table> + <tr valign="top"><th>DEPRECATED: JNI related parameters</th><th></th></tr> + <tr valign="top"><td>--enable-jni</td> + <td>Build the JNI worker and so the build process will require +some information about your Java Environment</td> + </tr> + <tr valign="top"><td>--with-java-home=DIR</td> + <td>DIR is the patch to the JDK root directory. Something like: /opt/java/jdk12</td> + </tr> + <tr valign="top"><td>--with-os-type=SUBDIR</td><td>SUBDIR is the os-type subdirectory, + configure should guess it correctly.</td> + </tr> + <tr valign="top"><td>--with-arch-type=SUBDIR</td><td>SUBDIR is the arch subdirectory, + configure should guess it correctly.</td> + </tr> + <tr valign="top"><td>--with-java-platform=VAL</td><td>VAL is the Java platform 1 is 1.1.x and 2 is for 1.2 and higher, + configure should guess it correctly.</td> + </tr> +</table> +</p> +<warn>The JNI option has been deprecated. It will likely not work. Do not use it.</warn> +</subsection> + +<subsection name="Examples of configure use"> + +<screen> +<note>Apache 1.3 and 2.0/2.2 build</note> +<type>./configure --with-apxs=/usr/sbin/apxs</type><br/> +<type>make</type><br/> +<type>cp ./apache-1.3/mod_jk.so /usr/lib/apache</type><br/> +<type>make clean</type><br/> +<type>./configure --with-apxs=/usr/sbin/apxs2</type><br/> +<type>make</type><br/> +<type>cp ./apache-2.0/mod_jk.so /usr/lib/apache2</type><br/> +</screen> + +<screen> +<note>Apache 2.0/2.2 build with JNI support</note> +<type>./configure --with-apxs2=/opt/apache2/bin/apxs \</type> +<typenext>--with-java-home=${JAVA_HOME} --with-java-platform=2 \</typenext> +<typenext>--enable-jni</typenext><br/> +</screen> +<warn>The JNI option has been deprecated. It will likely not work. Do not use it.</warn> +</subsection> + +</section> + +<section name="Building mod_jk for Apache on Windows NT/2K/XP"> +<p> +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. +</p> +<p> +The steps that you need to take are: +</p> +<ul> +<li> +Change directory to the apache 1.3 or apache 2.0 source directory depending on your version of Apache. +</li> +<li> +If you want to build mod_jk for Apache 1.3, set an <b>APACHE1_HOME</b> environment variable which points +to where your Apache 1.3 is installed. +A mod_jk module for Apache 2.0 build will require <b>APACHE2_HOME</b> environment variable to be set. +</li> +<li> +Copy mod_jk.so to Apache's modules directory. +</li> +</ul> +<p> +An example on how to build mod_jk for Apache 1.3: +</p> +<screen> +<note>Set location for Apache 1.3 sources</note> +<typedos>set APACHE1_HOME=c:\apache13</typedos> +<note>Change directory to the mod_jk module for Apache 1.3</note> +<typedos>cd c:\home\apache\jk\native\apache-1.3</typedos> +<note>Build the sources using MSDEV</note> +<typedos>MSDEV mod_jk.dsp /MAKE ALL</typedos> +<note>Copy the dll to your apache modules directory</note> +<typedos>cp release\mod_jk.so c:\apache13\modules\</typedos> +</screen> + +<p> +An example on how to build mod_jk for Apache 2.0: +</p> +<screen> +<note>Set location for Apache 2.0 sources</note> +<typedos>set APACHE2_HOME=c:\apache20</typedos> +<note>Change directory to the mod_jk module for Apache 2.0</note> +<typedos>cd c:\home\apache\jk\native\apache-2.0</typedos> +<note>Build the sources using MSDEV</note> +<typedos>MSDEV mod_jk.dsp /MAKE ALL</typedos> +<note>Copy the dll to your apache modules directory</note> +<typedos>cp release\mod_jk.so c:\apache20\modules\</typedos> +</screen> + +<p> +If msdev is not in your path, enter the full path to msdev.exe. +Also, ApacheCore.lib is expected to exist in the <b>${APACHEX_HOME}\src\CoreD</b> and +<b>${APACHEX_HOME}\src\CoreR</b> 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. +</p> +</section> + +<section name="Building mod_jk for Apache on System I - i5/OS (OS400)"> +<p> +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. +</p> +<p> +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 <a href="http://www.ibm.com/servers/eserver/iseries/software/http/"> +http://www.ibm.com/servers/eserver/iseries/software/http/</a> +</p> +<p> +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. +</p> +<p> +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. + +</p> +<p> +To configure mod_jk on System I use the CL source provided with the mod_jk source. +</p> +<ul> +<li> +Get the latest mod_jk source and untar it on a Windows or Unix boxes +</li> +<li> +Create a directory in IFS, ie /home/apache +</li> +<li> +Send the whole jk source directory to System I directory via FTP. +</li> +<li> +Then go to the System I command line : +</li> +</ul> +<screen> +<note>Create mod_jk library</note> +<type5250>CRTLIB MOD_JK TEXT(‘Apache mod'jk tomcat connector module')</type5250> +<note>Create service program source file</note> +<type5250>CRTSRCPF MOD_JK/QSRVSRC TEXT(‘Service program source file’)</type5250> +<note>Create the CL build program source file</note> +<type5250>CRTSRCPF FILE(MOD_JK/QCLSRC) TEXT(‘Build program source file’)</type5250> +<note>Edit the service program source file</note> +<type5250>STRSEU MOD_JK/QSRVSRC MOD_JK</type5250> +</screen> +<p> +In the edited file, specify that only jk_module should be exported : +<screen> +<note> Columns . . : 1 71 Edit MOD_JK/QSRVSRC </note> +<note> SEU==> MOD_JK </note> +<note> *************** Beginning of data ************************************* </note> +<note>0001.00 STRPGMEXP PGMLVL(*CURRENT) </note> +<note>0002.00 EXPORT SYMBOL("jk_module") </note> +<note>0003.00 ENDPGMEXP </note> +<note> ****************** End of data **************************************** </note> +</screen> +</p> +<p> +You could start to build all the modules of mod_jk (cases for V5R4 or previous releases): +</p> +<screen> +<note>Copy the CL build program source for i5/OS before V5R4 from IFS</note> +<type5250>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk.qclsrc') +</type5250> +<note>TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK.MBR') MBROPT(*REPLACE)</note> +<note>Build the CL build program</note> +<type5250>CRTCLPGM PGM(MOD_JK/BLDJK) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program')</type5250> +<note>Launch the build</note> +<type5250>CALL MOD_JK/BLDJK</type5250><br/> +<note>If the build if successfull, copy the new mod_jk module</note> +<type5250>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</type5250> +</screen> +<screen> +<note>Copy the CL build program source for i5/OS V5R4 from IFS</note> +<type5250>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk54.qclsrc') +</type5250> +<note>TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK54.MBR') MBROPT(*REPLACE)</note> +<note>Build the CL build program for i5/OS V5R4</note> +<type5250>CRTCLPGM PGM(MOD_JK/BLDJK54) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program') TGTRLS(*CURRENT)</type5250> +<note>Launch the build for i5/OS V5R4</note> +<type5250>CALL MOD_JK/BLDJK54</type5250><br/> +<note>If the build if successfull, copy the new mod_jk module</note> +<type5250>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</type5250> +</screen> +<p> +Next, you should restart your Apache 2.0 instance and enjoy this piece of OpenSource on System I. +</p> +<screen> +<note>ENDTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</note> +<note>STRTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</note> +</screen> +</section> + +<section name="Building mod_jk for Apache on MacOS/X"> +<p> +Mac OS X (10.2.x) build notes : +</p> +<p> +Assuming that you are root : +</p> +<screen> +<note>For Apache 1.3:</note> +<type>./configure --with-apxs=/usr/sbin/apxs</type> +<type>cd apache-1.3</type> +<type>make -f Makefile.apxs</type> +<type>cp mod_jk.so /etc/libexec/httpd</type> + +<note>For Apache 2.0:</note> +<type>./configure --with-apxs=/usr/local/apache2/bin/apxs</type> +<note>(you should point to the directory where you installed Apache 2.0)</note> +<type>cd apache-2.0</type> +<type>make -f Makefile.apxs install</type> +</screen> +</section> + +<section name="Getting mod_jk linked statically with Apache"> +<p> +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. +</p> + +<subsection name="Installation in Apache-2.0"> +<screen> +<note> /home/apache20/httpd-2.0.43 is the directory where the httpd-2.0 sources +are located. </note> +<type>./configure --with-apache=/home/apache20/httpd-2.0.43</type><br/> +<type>make</type><br/> +<note>Install the mod_jk library and other files in +/home/apache20/httpd-2.0.43/modules: </note> +<type>make install</type><br/> +<note> 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. </note> +<type>cd /home/apache20/httpd-2.0.43</type> +<type>sh buildconf</type> +<type>configure ... --with-mod_jk</type> +<type>make</type> +<type>make install</type><br/> +</screen> +<p> +The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only +allow static linking of mod_jk. +</p> +</subsection> + +<subsection name="Installation in Apache-1.3"> +<screen> +<note> /home/apache/apache_1.3.27 is the directory where the apache-1.3 sources +are located. </note> +<type>./configure --with-apache=/home/apache/apache_1.3.27</type><br/> +<type>make</type><br/> +<note>Install the libjk library, mod_jk.c, includes and other files in +/home/apache/apache_1.3.27/src/modules/jk: </note> +<type>make install</type><br/> +<note> Configure in the Apache sources: </note> +<type>cd /home/apache/apache_1.3.27</type> +<type>configure ... --enable-module=dir --disable-shared=dir \</type> +<typenext> --activate-module=src/modules/jk/libjk.a \</typenext> +<typenext> --disable-shared=jk</typenext> +<type>make</type> +<type>make install</type><br/> +</screen> +<p> +The --enable-shared=jk is also working and builds a dso file. +</p> +<screen> +<note> Just change the configure in the Apache sources: </note> +<type>configure ... --enable-module=dir --enable-shared=dir \</type> +<typenext> --activate-module=src/modules/jk/libjk.a \</typenext> +<typenext> --enable-shared=jk</typenext> +</screen> +</subsection> + +</section> +</body> +</document> |