hgomez 2002/09/06 05:24:32
Modified: jk/xdocs/jk aphowto.xml
Log:
Udate apache-howto (still in works)
Revision Changes Path
1.2 +371 -1 jakarta-tomcat-connectors/jk/xdocs/jk/aphowto.xml
Index: aphowto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk/aphowto.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- aphowto.xml 5 Sep 2002 08:38:50 -0000 1.1
+++ aphowto.xml 6 Sep 2002 12:24:32 -0000 1.2
@@ -35,7 +35,7 @@
</ul>
</p>
<p>
-In all the examples in this document ${tomcat_home} will be
<b>c:\jakarta-tomcat</b>.
+In all the examples in this document ${tomcat_home} will be <b>/var/tomcat3</b>.
A worker is defined to be a tomcat process that accepts work from the IIS server.
</p>
</subsection>
@@ -127,6 +127,376 @@
</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.
+</p>
+
+<p>
+The binaries for mod_jk are now available, for several platforms, in a separate
area as the Tomcat Binary Release.
+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 mod_jk 1.2.0 could be find <a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/";>
+here</a> and contains the following:
+</p>
+
+<p>
+<table>
+ <tr><th>Location</th><th>Contents</th></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/iseries/";>iseries</a></td><td>SAVF
including mod_jk for Apache 2.0 for iSeries V5R1/V5R2</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/linux/";>linux</a></td><td>mod_jk.so
(Apache 1.3 standard API and EAPI and Apache 2.0) for some Linux Archs</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/macosx/";>macosx</a></td><td>Contains
the mod_jk.so for MacOS X</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/netware/";>netware</a></td><td>mod_jk.nlm
and nsapi.nlm for Netware</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/rpms/";>rpms</a></td><td>Contains
the rpms (including sources and i386/ppc architectures)</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/solaris6/";>solaris6</a></td><td>Contains
the mod_jk.so for Solaris 6</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/solaris8/";>solaris8</a></td><td>Contains
the mod_jk.so for Solaris 8</td></tr>
+ <tr><td><a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/win32/";>win32</a></td><td>Contains
the mod_jk.dll for Windows as well as other useful binaries.</td></tr>
+</table>
+</p>
+
+<p>
+If you don't see your Operating System here, the doc may be outdated so just go
+<a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/";>
+here</a> and check if one of the directory didn't cover your os
+</p>
+
+</section>
+
+<section name="Installation">
+<p>
+mod_jk requires two entities:
+
+<ul>
+<li>
+<b>mod_jk.xxx</b> - The Apache module, depending on your operating system, it will
be mod_jk.so, mod_jk.dll, mod_jk,nlm or
+or QZTCJK.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.
+</li>
+</ul>
+</p>
+
+<p>
+Also as with other Apache 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 simplest way to configure Apache to use mod_jk is to turn on the Apache
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>
+
+<screen>
+<note>To be added at the end of your httpd.conf</note>
+<read>Include /var/tomcat3/conf/jk/mod_jk.conf-auto</read>
+</screen>
+
+<p>
+This will tell Apache 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 as described in the
Tomcat documentation.
+</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 WebServer,
+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
differents 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>
+
+<screen>
+<note># Load mod_jk module</note>
+<read>LoadModule jk_module libexec/mod_jk.so</read>
+<note># Declare the module for <IfModule directive></note>
+<read>AddModule mod_jk.c</read>
+<note># Where to find workers.properties</note>
+<read>JkWorkersFile /etc/httpd/conf/workers.properties</read>
+<note># Where to put jk logs</note>
+<read>JkLogFile /var/log/httpd/mod_jk.log</read>
+<note># Set the jk log level [debug/error/info]</note>
+<read>JkLogLevel info</read>
+<note># Select the log format</note>
+<read>JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "</read>
+<note># JkOptions indicate to send SSL KEY SIZE, </note>
+<read>JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories</read>
+<note># JkRequestLogFormat set the request format </note>
+<read>JkRequestLogFormat "%w %V %T"</read>
+<note># Send servlet for context /examples to worker named worker1</note>
+<read>JkMout /examples/servlet/* </read>
+<note># Send JSPs for context /examples to worker named worker1</note>
+<read>JkMount /examples/*.jsp</read>
+</screen>
+
+</subsection>
+</section>
+
+<section name="mod_jk Directives">
+<p>
+We'll discuss here about mod_jk directives and details them
+</p>
+
+<subsection name="Logging">
+<p>
+<b>JkLogFile</b> specify the location where mod_jk is going to place its log file.
+
+<screen>
+<read>JkLogFile /var/log/httpd/mod_jk.log</read>
+</screen>
+
+</p>
+<p>
+<b>JkLogLevel</b> set the log level between :
+<ul>
+<li>
+<b>info</b> log will contains standard mod_jk activity.
+</li>
+<li>
+<b>error</b> log will contains also error reports.
+</li>
+<li>
+<b>debug</b> log will contains all informations on mod_jk activity
+</li>
+</ul>
+
+<p>
+<b>info</b> should be your default selection for normal operations.
+</p>
+
+<screen>
+<read>JkLogLevel info</read>
+</screen>
+
+</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>
+
+<screen>
+<read>JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "</read>
+</screen>
+
+</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 similiar to the Apache LogFormat command,
+here is a list of the avaialbe 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>%r</td><td>First line of request</td></tr>
+ <tr><td>%r</td><td>First line of request</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>
+</table>
+
+<screen>
+<read>JkRequestLogFormat "%w %V %T"</read>
+</screen>
+
+</p>
+
+</subsection>
+
+<subsection name="Forwarding">
+<p>
+The directive JkOptions allow you to set many forwarding options :
+</p>
+
+<p>
+With <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 (on by default).
+</p>
+
+<p>
+With <b>ForwardURICompat</b>, you told mod_jk to send the URI to Tomcat normally,
+which is less spec compliant but mod_rewrite compatible,
+use it for compatibility with Tomcat 3.2.x engines (on by default).
+</p>
+
+<p>
+With <b>ForwardURICompatUnparsed</b>, the forwarded URI is unparsed, it's spec
compliant but broke mod_rewrite.
+</p>
+
+<p>
+With <b>ForwardURIEscaped</b>, the forwarded URI is escaped and Tomcat (since 3.3
rc2) will do the decoding part.
+</p>
+
+<p>
+With <b>ForwardDirectories</b>, This option is used in conjunction with
DirectoryIndex directive of Apache web
+server. 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 JkForwardDirectories 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 JkForwarDirectories 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.
+.
+</p>
+
+<p>
+The directive <b>JkEnvVar</b> allow you to forward an environment vars from Apache
server to Tomcat engine.
+</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>
+Use mod_jk's <b>JkMount</b> directive to assign specific URLs to Tomcat.
+In general the structure of a JkMount directive is:
+</p>
+
+<source>JkMount [URL prefix] [Worker name]</source>
+
+<screen>
+<note># send all requests ending in .jsp to worker1</note>
+<read>JkMount /*.jsp worker1</read>
+<note># send all requests ending /servlet to worker1</note>
+<read>JkMount /*/servlet/ worker1</read>
+<note># send all requests jsp requests to files located in /otherworker will go
worker2</note>
+<read>JkMount /otherworker/*.jsp worker2</read>
+</screen>
+
+<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: If Apache is configured to serve static pages for a web application it
bypasses
+any security contraints you may have configured in your web application web.xml
config file.
+</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>
+
+<screen>
+<note># Static files in the examples webapp are served by apache</note>
+<read>Alias /examples /vat/tomcat3/webapps/examples</read>
+<read>JkMount /*.jsp worker1</read>
+<read>JkMount /*/servlet/ worker1</read>
+</screen>
+
+<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
+<source>HTTP 403, Access Forbidden</source>
+</p>
+
+<screen>
+<note># Static files in all Tomcat webapp context directories are served by
apache</note>
+<read>JkAutoAlias /var/tomcat3/webapps</read>
+<read>JkMount /*.jsp ajp13</read>
+<read>JkMount /*/servlet/ ajp13</read>
+</screen>
+
+</subsection>
</section>
<section name="Building mod_jk on Unix">
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
