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]>