rubbos/app/tomcat-connectors-1.2.32-src/docs/webserver_howto/apache.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Webserver HowTo - Apache HTTP Server HowTo</title><meta name="author" value="Henri Gomez"><meta name="email" value="hgomez@apache.org"><meta name="author" value="Gal Shachor"><meta name="email" value="shachor@il.ibm.com"><link href="../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap="true"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li></ul><p><strong>Reference Guide</strong></p><ul><li><a href="../reference/workers.html">workers.properties</a></li><li><a href="../reference/uriworkermap.html">uriworkermap.properties</a></li><li><a href="../reference/status.html">Status Worker</a></li><li><a href="../reference/apache.html">Apache HTTP Server</a></li><li><a href="../reference/iis.html">IIS</a></li></ul><p><strong>Generic HowTo</strong></p><ul><li><a href="../generic_howto/quick.html">For the impatient</a></li><li><a href="../generic_howto/workers.html">All about workers</a></li><li><a href="../generic_howto/timeouts.html">Timeouts</a></li><li><a href="../generic_howto/loadbalancers.html">Load Balancing</a></li><li><a href="../generic_howto/proxy.html">Reverse Proxy</a></li></ul><p><strong>Webserver HowTo</strong></p><ul><li><a href="../webserver_howto/apache.html">Apache HTTP Server</a></li><li><a href="../webserver_howto/iis.html">IIS</a></li><li><a href="../webserver_howto/nes.html">Netscape/SunOne/Sun</a></li></ul><p><strong>AJP Protocol Reference</strong></p><ul><li><a href="../ajp/ajpv13a.html">AJPv13</a></li><li><a href="../ajp/ajpv13ext.html">AJPv13 Extension Proposal</a></li></ul><p><strong>Miscellaneous Documentation</strong></p><ul><li><a href="../miscellaneous/faq.html">Frequently asked questions</a></li><li><a href="../miscellaneous/changelog.html">Changelog</a></li><li><a href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;product=Tomcat+Connectors&amp;long_desc_type=substring&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;keywords_type=allwords&amp;keywords=&amp;bug_status=NEW&amp;bug_status=ASSIGNED&amp;bug_status=REOPENED&amp;emailassigned_to1=1&amp;emailtype1=substring&amp;email1=&amp;emailassigned_to2=1&amp;emailreporter2=1&amp;emailcc2=1&amp;emailtype2=substring&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=Reuse+same+sort+as+last+time&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=">Current Tomcat Connectors bugs</a></li><li><a href="../miscellaneous/doccontrib.html">Contribute documentation</a></li><li><a href="../miscellaneous/jkstatustasks.html">JK Status Ant Tasks</a></li><li><a href="../miscellaneous/reporttools.html">Reporting Tools</a></li><li><a href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html">Old JK/JK2 documentation</a></li></ul><p><strong>News</strong></p><ul><li><a href="../news/20110701.html">2011</a></li><li><a href="../news/20100101.html">2010</a></li><li><a href="../news/20090301.html">2009</a></li><li><a href="../news/20081001.html">2008</a></li><li><a href="../news/20070301.html">2007</a></li><li><a href="../news/20060101.html">2006</a></li><li><a href="../news/20050101.html">2005</a></li><li><a href="../news/20041100.html">2004</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - Webserver HowTo</h1><h2>Apache HTTP Server HowTo</h2></td><td align="right" valign="top" nowrap="true"><small><a href="printer/apache.html"><img src="../images/printer.gif" border="0" alt="Printer Friendly Version"><br>print-friendly<br>version
   2                     </a></small></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
   3 <p>
   4 This document explains how to connect Tomcat to the popular open source web server, Apache httpd.
   5 There is actually three versions of Apache HTTP Server, 1.3, 2.0 and 2.2 and all can be used with mod_jk,
   6 the Tomcat redirector module.
   7 </p>
   8
   9 <p>
  10 It is recommended that you also read the
  11 <a href="../generic_howto/workers.html">Workers HowTo</a> document
  12 to learn how to setup the working entities between your web server and Tomcat Engines.
  13 For more detailed configuration information consult the Reference Guide for
  14 <a href="../reference/worker.html">workers.properties</a>,
  15 <a href="../reference/uriworkermap.html">uriworkermap</a>
  16 and <a href="../reference/apache.html">Apache</a>.
  17 </p>
  18
  19 <p><b>Waring: If Apache HTTP Server and Tomcat are configured to serve content from
  20 the same filing system location then care must be taken to ensure that httpd is
  21 not able to serve inappropriate content such as the contents of the WEB-INF
  22 directory or JSP source code.</b> This could occur if the httpd DocumentRoot
  23 overlaps with a Tomcat Host's appBase or the docBase of any Context. It could
  24 also occur when using the httpd Alias directive with a Tomcat Host's appBase or
  25 the docBase of any Context.
  26 </p>
  27
  28 <p>
  29 This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
  30 but has been split off for organisational reasons.
  31 </p>
  32
  33 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Document Conventions and Assumptions"><strong>Document Conventions and Assumptions</strong></a></font></td></tr><tr><td><blockquote>
  34 <p>
  35 ${tomcat_home} is the root directory of tomcat.
  36 Your Tomcat installation should have the following subdirectories:
  37
  38 <ul>
  39 <li>
  40 ${tomcat_home}\conf - Where you can place various configuration files
  41 </li>
  42 <li>
  43 ${tomcat_home}\webapps - Containing example applications
  44 </li>
  45 <li>
  46 ${tomcat_home}\bin - Where you place web server plugins
  47 </li>
  48 </ul>
  49 </p>
  50 <p>
  51 In all the examples in this document ${tomcat_home} will be <b>/var/tomcat3</b>.
  52 A <a href="../generic_howto/workers.html">worker</a> is defined to be a tomcat process that accepts work from the Apache server.
  53 </p>
  54 </blockquote></td></tr></table>
  55
  56 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Supported Configuration"><strong>Supported Configuration</strong></a></font></td></tr><tr><td><blockquote>
  57 <p>
  58 The mod_jk module was developed and tested on:
  59 <ul>
  60 <li>
  61 Linux, FreeBSD, AIX, HP-UX, MacOS X, Solaris and should works on major Unixes platforms
  62 supporting Apache 1.3 and/or 2.0/2.2
  63 </li>
  64 <li>
  65 WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98
  66 </li>
  67 <li>
  68 Cygwin (until you have an apache server and autoconf/automake support tools)
  69 </li>
  70 <li>
  71 Netware
  72 </li>
  73 <li>
  74 i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed.
  75 </li>
  76 <li>
  77 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.
  78 </li>
  79 </ul>
  80 </p>
  81
  82 <p>
  83 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,
  84 more about the in-process mode can be found in the in process howto.
  85 </p>
  86 </blockquote></td></tr></table>
  87
  88 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Who support ajp protocols ?"><strong>Who support ajp protocols ?</strong></a></font></td></tr><tr><td><blockquote>
  89 <p>
  90 The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x.
  91 </p>
  92
  93 <p>
  94 The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead
  95 <b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x, 5 and 5.5 and Tomcat 6.
  96 </p>
  97
  98 <p>
  99 Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol.
 100 </p>
 101
 102 <p>
 103 Others servlet engines such as <b>jetty</b> have support for ajp13 protocol
 104 </p>
 105
 106 </blockquote></td></tr></table>
 107
 108 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="How does it work ?"><strong>How does it work ?</strong></a></font></td></tr><tr><td><blockquote>
 109 <p>
 110 In a nutshell a web server is waiting for client HTTP requests.
 111 When these requests arrive the server does whatever is needed to serve the
 112 requests by providing the necessary content.
 113 </p>
 114
 115 <p>
 116 Adding a servlet container may somewhat change this behaviour.
 117 Now the web server needs also to perform the following:
 118 </p>
 119
 120 <ul>
 121 <li>
 122 Load the servlet container adaptor library and initialise it (prior to serving requests).
 123 </li>
 124 <li>
 125 When a request arrives, it needs to check and see if a certain request belongs to a servlet,
 126 if so it needs to let the adaptor take the request and handle it.
 127 </li>
 128 </ul>
 129
 130 <p>
 131 The adaptor on the other hand needs to know what requests it is going to serve,
 132 usually based on some pattern in the request URL, and to where to direct these requests.
 133 </p>
 134
 135 <p>
 136 Things are even more complex when the user wants to set a configuration that uses virtual hosts,
 137 or when they want multiple developers to work on the same web server
 138 but on different servlet container JVMs.
 139 We will cover these two cases in the advanced sections.
 140 </p>
 141
 142 </blockquote></td></tr></table>
 143
 144 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Obtaining mod_jk"><strong>Obtaining mod_jk</strong></a></font></td></tr><tr><td><blockquote>
 145 <p>
 146 mod_jk can be obtained in two formats - binary and source.
 147 Depending on the platform you are running your web server on, a binary version of mod_jk may be available.
 148 </p>
 149
 150 <p>
 151 It is recommended to use the binary version if one is available.
 152 If the binary is not available, follow the instructions for building mod_jk from source.
 153 The mod_jk source can be downloaded from a mirror
 154 <a href="http://tomcat.apache.org/download-connectors.cgi">
 155 here</a>
 156 </p>
 157
 158 <p>
 159 The binaries for mod_jk are now available for several platforms.
 160 The binaries are located in subdirectories by platform.
 161 </p>
 162
 163 <p>
 164 For some platforms, such as Windows, this is the typical way of obtaining mod_jk
 165 since most Windows systems do not have C compilers.
 166 </p>
 167
 168 <p>
 169 For others, the binary distribution of mod_jk offers simpler installation.
 170 </p>
 171
 172 <p>
 173 For example JK 1.2.x can be downloaded from a mirror
 174 <a href="http://tomcat.apache.org/download-connectors.cgi">
 175 here</a> (look for JK 1.2 Binary Releases). The "JK 1.2 Binary Releases" link contains binary version for a variety of
 176 operating systems for both Apache 1.3 and Apache 2.
 177 </p>
 178
 179 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
 180 <p>
 181 mod_jk requires two entities:
 182
 183 <ul>
 184 <li>
 185 <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
 186 or MOD_JK.SRVPGM (see the build section).
 187 </li>
 188 <li>
 189 <b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes).
 190 A sample workers.properties can be found under the conf directory in the source download.
 191 </li>
 192 </ul>
 193 </p>
 194
 195 <p>
 196 Also as with other Apache HTTP Server modules, mod_jk should be first installed on the modules directory of your
 197 Apache webserver, ie : /usr/lib/apache and you should update your <b>httpd.conf</b> file.
 198 </p>
 199
 200
 201 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Disabling old mod_jserv"><strong>Disabling old mod_jserv</strong></a></font></td></tr><tr><td><blockquote>
 202 <p>
 203 If you've previously configured Apache to use <b>mod_jserv</b>, remove any <b>ApJServMount</b> directives
 204 from your httpd.conf.
 205 </p>
 206
 207 <p>If you're including <b>tomcat-apache.conf</b> or <b>tomcat.conf</b>, you'll want to remove them as well -
 208 they are specific to <b>mod_jserv</b>.
 209 </p>
 210
 211 <p>
 212 The mod_jserv configuration directives are not compatible with mod_jk !
 213 </p>
 214 </blockquote></td></tr></table>
 215
 216 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using Tomcat auto-configure"><strong>Using Tomcat auto-configure</strong></a></font></td></tr><tr><td><blockquote>
 217 <p>
 218 The auto-configure works only for a single Tomcat running on the same machine where Apache HTTP Server is running.
 219 The simplest way to configure Apache HTTP Server to use mod_jk is to turn on the Apache HTTP Server auto-configure setting
 220 in Tomcat and put the following include directive at the end of your Apache httpd.conf file
 221 (make sure you replace $TOMCAT_HOME with the correct path for your Tomcat installation:
 222 </p>
 223
 224 <div class="example"><pre>
 225     #To be added at the end of your httpd.conf
 226     Include $TOMCAT_HOME/conf/jk/mod_jk.conf-auto
 227 </pre></div>
 228
 229 <p>
 230 Note: this file may also be generated as $TOMCAT_HOME/conf/auto/mod_jk.conf
 231 </p>
 232
 233 <p>
 234 This will tell Apache HTTP Server to use directives in the <b>mod_jk.conf-auto</b> file in
 235 the Apache configuration. This file is created by enabling the Apache
 236 auto-configuration by creating your workers.properties file at
 237 $TOMCAT_HOME/conf/jk/workers.properties and adding the listener to the Engine
 238 element in the server.xml file as per the following example.
 239 <b>Please note that this example is specific to Tomcat 5.x, unlike other sections of this document
 240    which also apply to previous Tomcat branches.</b>
 241 </p>
 242 <div class="example"><pre>
 243   ...
 244   &lt;Engine ...&gt;
 245     ...
 246     &lt;Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" /&gt;
 247     ...
 248   &lt;/Engine&gt;
 249   ...
 250 </pre></div>
 251
 252 <p>
 253 Then restart Tomcat and mod_jk.conf should be generated. For more information on
 254 this topic, please refer to the API documentation at the
 255 <a href="http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/jk/config/ApacheConfig.html">
 256 Tomcat docs website</a>.
 257 </p>
 258
 259 </blockquote></td></tr></table>
 260
 261 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Custom mod_jk configuration"><strong>Custom mod_jk configuration</strong></a></font></td></tr><tr><td><blockquote>
 262 <p>
 263 You should use custom configuration when :
 264 </p>
 265 <ul>
 266 <li>
 267 You couldn't use <b>mod_jk.conf-auto</b> since Tomcat engine isn't on the same machine that your Apache web server,
 268 ie when you have an Apache in front of a Tomcat Farm.
 269 </li>
 270 <li>
 271 Another case for custom configuration is when your Apache is in front of many different Tomcat engines,
 272 each one having it's own configuration, a general case in ISP hosting
 273 </li>
 274 <li>
 275 Also all Apache webmaster will retain custom configuration to be able to tune the settings
 276 to their real needs.
 277 </li>
 278 </ul>
 279
 280 </blockquote></td></tr></table>
 281
 282 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Simple configuration example"><strong>Simple configuration example</strong></a></font></td></tr><tr><td><blockquote>
 283 <p>
 284 Here is a simple configuration:
 285 </p>
 286
 287 <div class="example"><pre>
 288     # Load mod_jk module
 289     LoadModule    jk_module  libexec/mod_jk.so
 290     # Declare the module for &lt;IfModule directive&gt; (remove this line on Apache 2.0.x)
 291     AddModule     mod_jk.c
 292     # Where to find workers.properties
 293     JkWorkersFile /etc/httpd/conf/workers.properties
 294     # Where to put jk shared memory
 295     JkShmFile     /var/log/httpd/mod_jk.shm
 296     # Where to put jk logs
 297     JkLogFile     /var/log/httpd/mod_jk.log
 298     # Set the jk log level [debug/error/info]
 299     JkLogLevel    info
 300     # Select the timestamp log format
 301     JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
 302     # Send servlet for context /examples to worker named worker1
 303     JkMount  /examples/servlet/* worker1
 304     # Send JSPs  for context /examples to worker named worker1
 305     JkMount  /examples/*.jsp worker1
 306 </pre></div>
 307
 308 </blockquote></td></tr></table>
 309 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="mod_jk Directives"><strong>mod_jk Directives</strong></a></font></td></tr><tr><td><blockquote>
 310 <p>
 311 We'll discuss here the mod_jk directives and details behind them
 312 </p>
 313
 314 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Define workers"><strong>Define workers</strong></a></font></td></tr><tr><td><blockquote>
 315 <p>
 316 <b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions.
 317
 318 <div class="example"><pre>
 319   JkWorkersFile     /etc/httpd/conf/workers.properties
 320 </pre></div>
 321
 322 <br>
 323 <br>
 324 </p>
 325 </blockquote></td></tr></table>
 326
 327 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Logging"><strong>Logging</strong></a></font></td></tr><tr><td><blockquote>
 328 <p>
 329 <b>JkLogFile</b> specify the location where mod_jk is going to place its log file.
 330 </p>
 331
 332 <div class="example"><pre>
 333   JkLogFile     /var/log/httpd/mod_jk.log
 334 </pre></div>
 335
 336 <p>
 337 Since JK 1.2.3 for Apache 2.0/2.2 and JK 1.2.16 for Apache 1.3 this can also
 338 be used for piped logging:
 339 </p>
 340
 341 <div class="example"><pre>
 342   JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
 343 </pre></div>
 344
 345 <p>
 346 <b>JkLogLevel</b>
 347 set the log level between :
 348 </p>
 349
 350 <ul>
 351 <li>
 352 <b>info</b> log will contains standard mod_jk activity (default).
 353 </li>
 354 <li>
 355 <b>error</b> log will contains also error reports.
 356 </li>
 357 <li>
 358 <b>debug</b> log will contains all information on mod_jk activity
 359 </li>
 360 </ul>
 361
 362 <div class="example"><pre>
 363   JkLogLevel    info
 364 </pre></div>
 365
 366 <p>
 367 <b class="code">info</b> should be your default selection for normal operations.
 368 <br>
 369 <br>
 370 </p>
 371
 372 <p>
 373 <b>JkLogStampFormat</b> will configure the date/time format found on mod_jk logfile.
 374 Using the strftime() format string it's set by default to <b>"[%a %b %d %H:%M:%S %Y]"</b>
 375 </p>
 376
 377 <div class="example"><pre>
 378   JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
 379 </pre></div>
 380
 381 <p>
 382 <br>
 383 <br>
 384 </p>
 385
 386 <p>
 387 <b>JkRequestLogFormat</b> will configure the format of mod_jk individual request logging.
 388 Request logging is configured and enabled on a per virtual host basis.
 389 To enable request logging for a virtual host just add a JkRequestLogFormat config.
 390 The syntax of the format string is similar to the Apache LogFormat command,
 391 here is a list of the available request log format options:
 392 </p>
 393
 394 <p>
 395 <table>
 396   <tr><th>Options</th><th>Description</th></tr>
 397   <tr><td>%b</td><td>Bytes sent, excluding HTTP headers (CLF format)</td></tr>
 398   <tr><td>%B</td><td>Bytes sent, excluding HTTP headers</td></tr>
 399   <tr><td>%H</td><td>The request protocol</td></tr>
 400   <tr><td>%m</td><td>The request method</td></tr>
 401   <tr><td>%p</td><td>The canonical Port of the server serving the request</td></tr>
 402   <tr><td>%q</td><td>The query string (prepended with a ? if a query string exists, otherwise an empty string)</td></tr>
 403   <tr><td>%r</td><td>First line of request</td></tr>
 404   <tr><td>%s</td><td>Request HTTP status code</td></tr>
 405   <tr><td>%T</td><td>Request duration, elapsed time to handle request in seconds '.' micro seconds</td></tr>
 406   <tr><td>%U</td><td>The URL path requested, not including any query string.</td></tr>
 407   <tr><td>%v</td><td>The canonical ServerName of the server serving the request</td></tr>
 408   <tr><td>%V</td><td>The server name according to the UseCanonicalName setting</td></tr>
 409   <tr><td>%w</td><td>Tomcat worker name</td></tr>
 410   <tr><td>%R</td><td>Session route name (available with 1.2.19 and up)</td></tr>
 411 </table>
 412
 413 <div class="example"><pre>
 414   JkRequestLogFormat     "%w %V %T"
 415 </pre></div>
 416
 417 <br>
 418 <br>
 419 </p>
 420
 421 </blockquote></td></tr></table>
 422
 423 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Forwarding"><strong>Forwarding</strong></a></font></td></tr><tr><td><blockquote>
 424 <p>
 425 The directive JkOptions allow you to set many forwarding options which will enable (+)
 426 or disable (-) following option. Without any leading signs, options will be enabled.
 427 <br>
 428 <br>
 429 </p>
 430
 431 <p>
 432 The four following options <b>+ForwardURIxxx</b> are mutually exclusive.
 433 Exactly one of them is required, a negative sign prefix is not allowed with them.
 434 The default value is "ForwardURIProxy" since version 1.2.24.
 435 It was "ForwardURICompatUnparsed" in version 1.2.23 and
 436 "ForwardURICompat" until version 1.2.22.
 437 You can turn the default off by switching on one of the other two options.
 438 You should leave this at it's default value, unless you have a very good
 439 reason to change it.
 440 <br>
 441 <br>
 442 </p>
 443
 444 <p>
 445 All options are inherited from the global server to virtual hosts.
 446 Options that support enabling (plus options) and disabling (minus options),
 447 are inherited in the following way:
 448 <br>
 449 <br>
 450 options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)
 451 <br>
 452 <br>
 453 </p>
 454
 455 <p>
 456 Using JkOptions <b>ForwardURIProxy</b>, the forwarded URI
 457 will be partially reencoded after processing inside Apache httpd and
 458 before forwarding to Tomcat. This will be compatible with local
 459 URL manipulation by mod_rewrite and with URL encoded session ids.
 460
 461 <div class="example"><pre>
 462   JkOptions     +ForwardURIProxy
 463 </pre></div>
 464
 465 <br>
 466 <br>
 467 </p>
 468
 469 <p>
 470 Using JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI
 471 will be unparsed. It's spec compliant and secure.
 472 It will always forward the original request URI, so rewriting
 473 URIs with mod_rewrite and then forwarding the rewritten URI
 474 will not work.
 475
 476 <div class="example"><pre>
 477   JkOptions     +ForwardURICompatUnparsed
 478 </pre></div>
 479
 480 <br>
 481 <br>
 482 </p>
 483 <p>
 484 Using JkOptions <b>ForwardURICompat</b>, the forwarded URI will
 485 be decoded by Apache httpd. Encoded characters will be decoded and
 486 explicit path components like ".." will already be resolved.
 487 This is less spec compliant and is <b>not safe</b> if you are using
 488 prefix JkMount. This option will allow to rewrite URIs with
 489 mod_rewrite before forwarding.
 490
 491 <div class="example"><pre>
 492   JkOptions     +ForwardURICompat
 493 </pre></div>
 494
 495 <br>
 496 <br>
 497 </p>
 498 <p>
 499 Using JkOptions <b>ForwardURIEscaped</b>, the forwarded URI will
 500 be the encoded form of the URI used by ForwardURICompat.
 501 Explicit path components like ".." will already be resolved.
 502 This will not work in combination with URL encoded session IDs,
 503 but it will allow to rewrite URIs with mod_rewrite before forwarding.
 504
 505 <div class="example"><pre>
 506   JkOptions     +ForwardURIEscaped
 507 </pre></div>
 508
 509 <br>
 510 <br>
 511 </p>
 512
 513 <p>
 514 JkOptions <b>RejectUnsafeURI</b> will block all
 515 URLs, which contain percent signs '%' or backslashes '\'
 516 after decoding.
 517 <br>
 518 <br>
 519 </p>
 520 <p>
 521 Most web apps do not use such URLs. Using the option RejectUnsafeURI, you
 522 can block several well known URL encoding attacks. By default, this option
 523 is not set.
 524 </p>
 525 <p>
 526 You can also realise such a check with mod_rewrite, which is more powerful
 527 but also slightly more complicated.
 528
 529 <div class="example"><pre>
 530   JkOptions     +RejectUnsafeURI
 531 </pre></div>
 532
 533 <br>
 534 <br>
 535 </p>
 536
 537 <p>
 538 JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b>
 539 directive of Apache web server. As such mod_dir should be available to Apache,
 540 statically or dynamically (DSO)
 541 <br>
 542 <br>
 543 </p>
 544
 545 <p>
 546 When DirectoryIndex is configured, Apache will create sub-requests for
 547 each of the local-url's specified in the directive, to determine if there is a
 548 local file that matches (this is done by stat-ing the file).
 549 </p>
 550
 551 <p>
 552 If ForwardDirectories is set to false (default) and Apache doesn't find any
 553 files that match, Apache will serve the content of the directory (if directive
 554 Options specifies Indexes for that directory) or a <b class="code">403 Forbidden</b> response (if
 555 directive Options doesn't specify Indexes for that directory).
 556 </p>
 557
 558 <p>
 559 If ForwarDirectories is set to true and Apache doesn't find any files that
 560 match, the request will be forwarded to Tomcat for resolution. This is used in
 561 cases when Apache cannot see the index files on the file system for various
 562 reasons: Tomcat is running on a different machine, the JSP file has been
 563 precompiled etc.
 564 </p>
 565
 566 <p>Note that locally visible files will take precedence over the
 567 ones visible only to Tomcat (i.e. if Apache can see the file, that's the one
 568 that's going to get served). This is important if there is more then one type of
 569 file that Tomcat normally serves - for instance Velocity pages and JSP pages.
 570
 571 <div class="example"><pre>
 572   JkOptions     +ForwardDirectories
 573 </pre></div>
 574 <br>
 575 <br>
 576 </p>
 577
 578 <p>
 579 JkOptions <b>ForwardLocalAddress</b>, you ask mod_jk to send the local address,
 580 of the Apache web server instead remote client address. This can be used by
 581 Tomcat remote address valve for allowing connections only from registered Apache
 582 web servers.
 583
 584 <div class="example"><pre>
 585   JkOptions     +ForwardLocalAddress
 586 </pre></div>
 587
 588 <br>
 589 <br>
 590 </p>
 591
 592 <p>
 593 JkOptions <b>FlushPackets</b>, you ask mod_jk to flush Apache's connection
 594 buffer after each AJP packet chunk received from Tomcat. This option can have
 595 a strong performance penalty for Apache and Tomcat as writes are performed
 596 more often than would normally be required (ie: at the end of each
 597 response).
 598
 599 <div class="example"><pre>
 600   JkOptions     +FlushPackets
 601 </pre></div>
 602
 603 <br>
 604 <br>
 605 </p>
 606
 607 <p>
 608 JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection
 609 buffer after the response headers have been  received from Tomcat.
 610
 611 <div class="example"><pre>
 612   JkOptions     +FlushHeader
 613 </pre></div>
 614
 615 <br>
 616 <br>
 617 </p>
 618
 619 <p>
 620 JkOptions <b>DisableReuse</b>, you ask mod_jk to close connections immediately
 621 after their use. Normally mod_jk uses persistent connections and pools idle
 622 connections to reuse them, when new requests have to be sent to Tomcat.
 623 </p>
 624
 625 <p>
 626 Using this option will have a strong performance penalty for Apache and Tomcat.
 627 Use this only as a last resort in case of unfixable network problems.
 628 If a firewall between Apache and Tomcat silently kills idle connections,
 629 try to use the worker attribute socket_keepalive in combination with an appropriate
 630 TCP keepalive value in your OS.
 631
 632 <div class="example"><pre>
 633   JkOptions     +DisableReuse
 634 </pre></div>
 635
 636 <br>
 637 <br>
 638 </p>
 639
 640 <p>
 641 JkOptions <b>ForwardKeySize</b>, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as
 642 required by Servlet API 2.3.
 643 This flag shouldn't be set when servlet engine is Tomcat 3.2.x (off by default).
 644
 645 <div class="example"><pre>
 646   JkOptions     +ForwardKeySize
 647 </pre></div>
 648
 649 <br>
 650 <br>
 651 </p>
 652
 653 <p>
 654 JkOptions <b>ForwardSSLCertChain</b>,  you ask mod_jk, when using ajp13,
 655 to forward SSL certificate chain (off by default).
 656 Mod_jk only passes the <b class="code">SSL_CLIENT_CERT</b> to the AJP connector. This is not a
 657 problem with self-signed certificates or certificates directly signed by the
 658 root CA certificate. However, there's a large number of certificates signed by
 659 an intermediate CA certificate, where this is a significant problem: A servlet
 660 will not have the possibility to validate the client certificate on its own. The
 661 bug would be fixed by passing on the <b class="code">SSL_CLIENT_CERT_CHAIN</b> to Tomcat via the AJP connector.
 662 <br>
 663 This directive exists only since version 1.2.22.
 664 <div class="example"><pre>
 665   JkOptions     +ForwardSSLCertChain
 666 </pre></div>
 667
 668 <br>
 669 <br>
 670 </p>
 671
 672 <p>
 673 The directive <b>JkEnvVar</b> allows you to forward environment variables
 674 from Apache server to Tomcat engine.
 675 You can add a default value as a second parameter to the directive.
 676 If the default value is not given explicitly, the variable
 677 will only be send, if it is set during runtime.
 678 <br>
 679 The variables can be retrieved on the Tomcat side as request attributes
 680 via request.getAttribute(attributeName).
 681 Note that the variables send via JkEnvVar will not be listed
 682 in request.getAttributeNames().
 683 <br>
 684 <br>
 685 The variables are inherited from the global server to virtual hosts.
 686
 687 <div class="example"><pre>
 688   JkEnvVar     SSL_CLIENT_V_START     undefined
 689 </pre></div>
 690 <br>
 691 <br>
 692 </p>
 693
 694 </blockquote></td></tr></table>
 695
 696 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Assigning URLs to Tomcat"><strong>Assigning URLs to Tomcat</strong></a></font></td></tr><tr><td><blockquote>
 697 <p>
 698 If you have created a custom or local version of mod_jk.conf-local as noted above,
 699 you can change settings such as the workers or URL prefix.
 700 </p>
 701
 702 <p>
 703 <b>JkMount</b> directive assign specific URLs to Tomcat.
 704 In general the structure of a JkMount directive is:
 705 </p>
 706
 707 <div class="example"><pre>  JkMount [URL prefix] [Worker name]</pre></div>
 708
 709 <div class="example"><pre>
 710   # send all requests ending in .jsp to worker1
 711   JkMount /*.jsp worker1
 712   # send all requests ending /servlet to worker1
 713   JkMount /*/servlet/ worker1
 714   # send all requests jsp requests to files located in /otherworker will go worker2
 715   JkMount /otherworker/*.jsp worker2
 716 </pre></div>
 717
 718 <p>
 719 You can use the JkMount directive at the top level or inside &lt;VirtualHost&gt; sections of your httpd.conf file.
 720 </p>
 721 </blockquote></td></tr></table>
 722
 723 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Configuring Apache to serve static web application files"><strong>Configuring Apache to serve static web application files</strong></a></font></td></tr><tr><td><blockquote>
 724 <p>
 725 If the Tomcat Host appBase (webapps) directory is accessible by the Apache web server,
 726 Apache can be configured to serve web application context directory static files instead
 727 of passing the request to Tomcat.
 728 </p>
 729
 730 <p>
 731 Caution: For security reasons is is strongly recommended that JkMount is used to
 732 pass all requests to Tomcat by default and JkUnMount is used to explicitly
 733 exclude static content to be served by httpd. It should also be noted that
 734 content served by httpd will bypass any security constraints defined in the
 735 application's web.xml.
 736 </p>
 737
 738 <p>Use Apache's <b>Alias</b> directive to map a single web application context directory into Apache's
 739 document space for a VirtualHost:
 740 </p>
 741
 742 <div class="example"><pre>
 743   # Static files in the examples webapp are served by apache
 744   Alias /examples /vat/tomcat3/webapps/examples
 745   # All requests go to worker1 by default
 746   JkMount /* worker1
 747   # Serve html, jpg and gif using httpd
 748   JkUnMount /*.html worker1
 749   JkUnMount /*.jpg  worker1
 750   JkUnMount /*.gif  worker1
 751 </pre></div>
 752
 753 <p>
 754 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
 755 jk processing by setting the env var <b>no-jk</b>, for example with the SetEnvIf Directive.
 756 </p>
 757
 758 <p>
 759 You could use <b>no-jk</b> env var to fix problem with mod_alias or mod_userdir
 760 directive when jk and alias/userdir URLs matches.
 761 </p>
 762
 763 <div class="example"><pre>
 764   # All URL goes to tomcat except the one containing /home
 765   &lt;VirtualHost *:80&gt;
 766       ServerName testxxx.mysys
 767       DocumentRoot /www/testxxx/htdocs
 768
 769   # Use SetEnvIf to st no-jk when /home/ is encountered
 770       SetEnvIf Request_URI "/home/*" no-jk
 771
 772   # Now /home will goes to /home/dataxxx/
 773       Alias /home /home/dataxxx/
 774
 775       &lt;Directory "/home/dataxxx"&gt;
 776           Options Indexes MultiViews
 777           AllowOverride None
 778           Order allow,deny
 779           Allow from all
 780       &lt;/Directory&gt;
 781
 782       JkMount /* myssys-xxx
 783
 784   &lt;/VirtualHost&gt;
 785 </pre></div>
 786
 787
 788 <p>
 789 Use the mod_jk <b>JkAutoAlias</b> directive to map all web application context directories
 790 into Apache's document space.
 791 </p>
 792
 793 <p>
 794 Attempts to access the WEB-INF or META-INF directories within a web application context
 795 or a Web Archive *.war within the Tomcat Host appBase (webapps) directory will fail with an
 796 <b class="code">HTTP 403, Access Forbidden</b>
 797 </p>
 798
 799 <div class="example"><pre>
 800   # Static files in all Tomcat webapp context directories are served by apache
 801   JkAutoAlias /var/tomcat3/webapps
 802
 803   # All requests go to worker1 by default
 804   JkMount /* ajp13
 805   # Serve html, jpg and gif using httpd
 806   JkUnMount /*.html ajp13
 807   JkUnMount /*.jpg  ajp13
 808   JkUnMount /*.gif  ajp13
 809 </pre></div>
 810
 811 <p>
 812 If you encoded all your URLs to contain the session id
 813 (<b class="code">;jsessionid=...</b>), and you later decide, you want to
 814 move part of the content to Apache httpd, you can tell
 815 mod_jk to strip off all session ids from URLs for
 816 those requests, that do not get forwarded via mod_jk.
 817 </p>
 818
 819 <p>
 820 You enable this feature by setting JkStripSession to On.
 821 It can be enabled individually for virtual servers. The default
 822 value is Off.
 823 </p>
 824
 825 </blockquote></td></tr></table>
 826 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building mod_jk on Unix"><strong>Building mod_jk on Unix</strong></a></font></td></tr><tr><td><blockquote>
 827 <p>
 828 The mod_jk build use the widely used configure system.
 829 </p>
 830 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Prepare your mod_jk configure from subversion"><strong>Prepare your mod_jk configure from subversion</strong></a></font></td></tr><tr><td><blockquote>
 831 In case you get source from subversion, ie without an existing configure script,
 832 you should have autoconf for configuration and installation.
 833 <p>
 834 To create tomcat-connectors's autoconf script, you will need libtool
 835 1.5.2, automake 1.10 and autoconf 2.59 or newer. The use of more recent
 836 versions is encouraged, e.g. for reliable detection of the features of
 837 recent version of operating systems.
 838 </p><p>
 839 Those tools will not be required if you are just using a package downloaded from apache.org,
 840 they are only required for developers.
 841 </p>
 842 <p>
 843 To create the configure script just type :
 844
 845 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./buildconf.sh</b></nobr></code><br></td></tr></table></div></p>
 846 </p>
 847 </blockquote></td></tr></table>
 848
 849 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Using configure to build mod_jk"><strong>Using configure to build mod_jk</strong></a></font></td></tr><tr><td><blockquote>
 850 <p>Here's how to use configure to prepare mod_jk for building, just type:
 851 <div class="example"><pre>
 852 ./configure [autoconf arguments] [tomcat-connectors arguments]
 853 </pre></div>
 854 </p>
 855
 856 <p>
 857 You could set <b>CFLAGS</b> and <b>LDFLAGS</b> to add some platform specifics:
 858 </p>
 859
 860 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs</b></nobr></code><br></td></tr></table></div></p>
 861
 862 <p>
 863 If you want to build mod_jk for different version of Apache httpd, like 1.3, 2.0 and 2.2,
 864 you need to go through the full build process for each of them.
 865 Please note, that httpd 2.0 and 2.2 modules are <b>not</b> compatible. The mod_jk directory
 866 used is "apache-2.0" in both cases, but you need to compile separately.
 867 <ul>
 868 <li>
 869 use configure and indicate the correct Apache httpd apxs location (--with-apxs)
 870 </li>
 871 <li>
 872 use make
 873 </li>
 874 <li>
 875 copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory
 876 to the Apache httpd modules location.
 877 </li>
 878 <li>
 879 make clean (to remove all previously compiled object files)
 880 </li>
 881 <li>
 882 Start over with the apxs location for your next Apache httpd version.
 883 </li>
 884 </ul>
 885
 886 </p>
 887 </blockquote></td></tr></table>
 888
 889 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="configure arguments"><strong>configure arguments</strong></a></font></td></tr><tr><td><blockquote>
 890 <p>
 891 <table>
 892   <tr valign="top"><th>Apache related parameters</th><th></th></tr>
 893   <tr valign="top">
 894   <td>--with-apxs[=FILE]</td>
 895   <td>FILE is the location of the apxs tool. Default is finding apxs in PATH.
 896 It builds a shared Apache module. It detects automatically the Apache version.
 897 (2.0/2.2 and 1.3)</td>
 898   </tr>
 899   <tr valign="top"><td>--with-apache=DIR</td>
 900   <td>DIR is the path where apache sources are located.
 901 The apache sources should have been configured before configuring mod_jk.
 902 DIR is something like: /home/apache/apache_1.3.19
 903 It builds a static Apache module.</td>
 904   </tr>
 905   <tr valign="top"><td>--enable-EAPI</td>
 906   <td>This parameter is needed when using Apache-1.3 and mod_ssl, otherwise you will get the error message:
 907 "this module might crash under EAPI!" when loading mod_jk.so in httpd.
 908 Not needed when --with-apxs has been used</td>
 909 </tr>
 910   <tr valign="top"><td>--enable-prefork</td>
 911   <td>
 912 In case you build mod_jk for a multi-threaded Apache httpd 2.0/2.2 MPM (Multi-Processing Module),
 913 some areas of mod_jk code need to be synchronised to make it thread-safe.
 914 Because configure can not easily detect, whether your are using a multi-threaded MPM,
 915 mod_jk by default is always build thread-safe for Apache httpd 2.0/2.2.
 916 If you are sure, that your MPM is not multi-threaded, you can use "--enable-prefork"
 917 to force the removal of the synchronisation code (thus increasing performance a bit).
 918 For instance, the prefork MPM is not multi-threaded. For Apache httpd 1.3
 919 this flag will be set automatically.</td>
 920 </tr>
 921   <tr valign="top"><td>--disable-trace</td>
 922   <td>
 923 When using log level "trace", mod_jk traces a lot of function calls with
 924 "enter" and "exit" log messages. Even if the log level is not "trace",
 925 comparing the log levels to decide about logging has some performance
 926 impact.<br>
 927 If you use "--disable-trace", then the trace log code doesn't get compiled
 928 into the module binary and you might save some cycles during execution.<br>
 929 Even with "--disable-trace" logging debug messages with debug log level
 930 will still be possible.</td>
 931 </tr>
 932   <tr valign="top"><td>--enable-api-compatibility</td>
 933   <td>
 934 Only use httpd API functions available in all httpd production releases
 935 of the chosen major httpd release branch. This improves binary
 936 compatibility of module builds with httpd releases older than the release
 937 against mod_jk is build (only between minor httpd versions).</td>
 938 </tr>
 939   <tr valign="top"><td>--enable-flock</td>
 940   <td>
 941 In case the operating system supports flock system call use this flag to enable this
 942 faster locks that are implemented as system call instead emulated by GNU C library.<br>
 943 However those locks does not work on NFS mounted volumes, so you can use
 944 "--enable-flock" during compile time to force the flocks() calls.</td>
 945 </tr>
 946
 947 </table>
 948 <br>
 949 <table>
 950   <tr valign="top"><th>DEPRECATED: JNI related parameters</th><th></th></tr>
 951   <tr valign="top"><td>--enable-jni</td>
 952   <td>Build the JNI worker and so the build process will require
 953 some information about your Java Environment</td>
 954   </tr>
 955   <tr valign="top"><td>--with-java-home=DIR</td>
 956   <td>DIR is the  patch to the JDK root directory. Something like: /opt/java/jdk12</td>
 957   </tr>
 958   <tr valign="top"><td>--with-os-type=SUBDIR</td><td>SUBDIR is the os-type subdirectory,
 959   configure should guess it correctly.</td>
 960   </tr>
 961   <tr valign="top"><td>--with-arch-type=SUBDIR</td><td>SUBDIR is the arch subdirectory,
 962   configure should guess it correctly.</td>
 963   </tr>
 964   <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,
 965   configure should guess it correctly.</td>
 966   </tr>
 967 </table>
 968 </p>
 969 <p><font color="#ff0000">The JNI option has been deprecated. It will likely not work. Do not use it.</font></p>
 970 </blockquote></td></tr></table>
 971
 972 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Examples of configure use"><strong>Examples of configure use</strong></a></font></td></tr><tr><td><blockquote>
 973
 974 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Apache 1.3 and 2.0/2.2 build</div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apxs=/usr/sbin/apxs</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cp ./apache-1.3/mod_jk.so /usr/lib/apache</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make clean</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apxs=/usr/sbin/apxs2</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cp ./apache-2.0/mod_jk.so /usr/lib/apache2</b></nobr></code><br></td></tr></table></div></p>
 975
 976 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Apache 2.0/2.2 build with JNI support</div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apxs2=/opt/apache2/bin/apxs \</b></nobr></code><br><code><nobr><em class="screen"> </em><b class="screen">--with-java-home=${JAVA_HOME} --with-java-platform=2 \</b></nobr></code><br><code><nobr><em class="screen"> </em><b class="screen">--enable-jni</b></nobr></code><br></td></tr></table></div></p>
 977 <p><font color="#ff0000">The JNI option has been deprecated. It will likely not work. Do not use it.</font></p>
 978 </blockquote></td></tr></table>
 979
 980 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building mod_jk for Apache on Windows NT/2K/XP"><strong>Building mod_jk for Apache on Windows NT/2K/XP</strong></a></font></td></tr><tr><td><blockquote>
 981 <p>
 982 The module was developed using Visual C++ version 6.0, so having this environment is a prerequisite
 983 if you want to perform a custom build.
 984 </p>
 985 <p>
 986 The steps that you need to take are:
 987 </p>
 988 <ul>
 989 <li>
 990 Change directory to the apache 1.3 or apache 2.0 source directory depending on your version of Apache.
 991 </li>
 992 <li>
 993 If you want to build mod_jk for Apache 1.3, set an <b>APACHE1_HOME</b> environment variable which points
 994 to where your Apache 1.3 is installed.
 995 A mod_jk module for Apache 2.0 build will require <b>APACHE2_HOME</b> environment variable to be set.
 996 </li>
 997 <li>
 998 Copy mod_jk.so to Apache's modules directory.
 999 </li>
1000 </ul>
1001 <p>
1002 An example on how to build mod_jk for Apache 1.3:
1003 </p>
1004 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Set location for Apache 1.3 sources</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">set APACHE1_HOME=c:\apache13</b></nobr></code><br><div class="screen">Change directory to the mod_jk module for Apache 1.3</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">cd c:\home\apache\jk\native\apache-1.3</b></nobr></code><br><div class="screen">Build the sources using MSDEV</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">MSDEV mod_jk.dsp /MAKE ALL</b></nobr></code><br><div class="screen">Copy the dll to your apache modules directory</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">cp release\mod_jk.so c:\apache13\modules\</b></nobr></code><br></td></tr></table></div></p>
1005
1006 <p>
1007 An example on how to build mod_jk for Apache 2.0:
1008 </p>
1009 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Set location for Apache 2.0 sources</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">set APACHE2_HOME=c:\apache20</b></nobr></code><br><div class="screen">Change directory to the mod_jk module for Apache 2.0</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">cd c:\home\apache\jk\native\apache-2.0</b></nobr></code><br><div class="screen">Build the sources using MSDEV</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">MSDEV mod_jk.dsp /MAKE ALL</b></nobr></code><br><div class="screen">Copy the dll to your apache modules directory</div><code><nobr><em class="screen">c:\&gt;</em><b class="screen">cp release\mod_jk.so c:\apache20\modules\</b></nobr></code><br></td></tr></table></div></p>
1010
1011 <p>
1012 If msdev is not in your path, enter the full path to msdev.exe.
1013 Also, ApacheCore.lib is expected to exist in the <b>${APACHEX_HOME}\src\CoreD</b> and
1014 <b>${APACHEX_HOME}\src\CoreR</b> directories before linking will succeed.
1015 You will need to build enough of the Apache source to create these libraries.
1016 This will build both release and debug versions of the redirector plug-in (mod_jk).
1017 An alternative will be to open mod_jk.dsp in msdev and build it using the build menu.
1018 </p>
1019 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building mod_jk for Apache on System I - i5/OS (OS400)"><strong>Building mod_jk for Apache on System I - i5/OS (OS400)</strong></a></font></td></tr><tr><td><blockquote>
1020 <p>
1021 Since OS400 V4R5, System I (AS/400) has used Apache 2.0 as their primary web server,
1022 replacing the old IBM webserver.
1023 It's now possible to build mod_jk on System I thanks to the help of the IBM
1024 Rochester Labs which has provided information and patches to adapt mod_jk to i5/OS.
1025 </p>
1026 <p>
1027 You should have at least Apache 2.0.58 (product 5722DG1), a C Compiler and IFS.
1028 Apache 2.0.58 is provided with the most recent set of PTFs for the iSeries Apache
1029 server, which can be found at <a href="http://www.ibm.com/servers/eserver/iseries/software/http/">
1030 http://www.ibm.com/servers/eserver/iseries/software/http/</a>
1031 </p>
1032 <p>
1033 The all latest Apache 2 for i5/OS V5R3 (or V5R4) is now 2.0.58 (as of 2007/04/17).
1034 Be sure to have the latest PTFs loaded if you want to make use of jk 1.2.15 and higher.
1035 NB: The latest mod_jk known to work on i5/OS V5R3 was 1.2.19.
1036 </p>
1037 <p>
1038 New in i5/OS V5R4, UTF is required, also for Apache modules, as such Apache modules do not require
1039 translations to/from EBCDIC but works should be done to port mod_jk 1.2.23 (and higher) to V5R4.
1040
1041 From the V5R4 Infocenter :
1042
1043 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
1044 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.
1045 Additionally, input data from the client will no longer be converted to EBCDIC but will be passed as-is.
1046 Output data sent from the module is not converted either so it must be encoded in ASCII or UTF8 as required.
1047 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
1048 indicate the encoding of the parameters being passed. Conversion functions between UTF-8 and EBCDIC have been added.
1049 Be sure to review APIs used by your module to be aware of current changes.
1050
1051 </p>
1052 <p>
1053 To configure mod_jk on System I use the CL source provided with the mod_jk source.
1054 </p>
1055 <ul>
1056 <li>
1057 Get the latest mod_jk source and untar it on a Windows or Unix boxes
1058 </li>
1059 <li>
1060 Create a directory in IFS, ie /home/apache
1061 </li>
1062 <li>
1063 Send the whole jk source directory to System I directory via FTP.
1064 </li>
1065 <li>
1066 Then go to the System I command line :
1067 </li>
1068 </ul>
1069 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Create mod_jk library</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTLIB MOD_JK TEXT(&#145;Apache mod'jk tomcat connector module')</b></nobr></code><br><div class="screen">Create service program source file</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTSRCPF MOD_JK/QSRVSRC TEXT(&#145;Service program source file&#146;)</b></nobr></code><br><div class="screen">Create the CL build program source file</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTSRCPF FILE(MOD_JK/QCLSRC) TEXT(&#145;Build program source file&#146;)</b></nobr></code><br><div class="screen">Edit the service program source file</div><code><nobr><em class="screen">===&gt;</em><b class="screen">STRSEU MOD_JK/QSRVSRC MOD_JK</b></nobr></code><br></td></tr></table></div></p>
1070 <p>
1071 In the edited file, specify that only jk_module should be exported :
1072 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen"> Columns   . . :    1  71     Edit                               MOD_JK/QSRVSRC </div><div class="screen"> SEU==&gt;                                                                  MOD_JK </div><div class="screen">        *************** Beginning of data ************************************* </div><div class="screen">0001.00 STRPGMEXP PGMLVL(*CURRENT)                                              </div><div class="screen">0002.00 EXPORT SYMBOL("jk_module")                                              </div><div class="screen">0003.00 ENDPGMEXP                                                               </div><div class="screen">        ****************** End of data **************************************** </div></td></tr></table></div></p>
1073 </p>
1074 <p>
1075 You could start to build all the modules of mod_jk (cases for V5R4 or previous releases):
1076 </p>
1077 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Copy the CL build program source for i5/OS before V5R4 from IFS</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk.qclsrc') +</b></nobr></code><br><div class="screen">TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK.MBR') MBROPT(*REPLACE)</div><div class="screen">Build the CL build program</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTCLPGM PGM(MOD_JK/BLDJK) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program')</b></nobr></code><br><div class="screen">Launch the build</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CALL MOD_JK/BLDJK</b></nobr></code><br><div class="screen">If the build if successfull, copy the new mod_jk module</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</b></nobr></code><br></td></tr></table></div></p>
1078 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">Copy the CL build program source for i5/OS V5R4 from IFS</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk54.qclsrc') +</b></nobr></code><br><div class="screen">TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK54.MBR') MBROPT(*REPLACE)</div><div class="screen">Build the CL build program for i5/OS V5R4</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTCLPGM PGM(MOD_JK/BLDJK54) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program') TGTRLS(*CURRENT)</b></nobr></code><br><div class="screen">Launch the build for i5/OS V5R4</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CALL MOD_JK/BLDJK54</b></nobr></code><br><div class="screen">If the build if successfull, copy the new mod_jk module</div><code><nobr><em class="screen">===&gt;</em><b class="screen">CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</b></nobr></code><br></td></tr></table></div></p>
1079 <p>
1080 Next, you should restart your Apache 2.0 instance and enjoy this piece of OpenSource on System I.
1081 </p>
1082 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">ENDTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</div><div class="screen">STRTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</div></td></tr></table></div></p>
1083 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Building mod_jk for Apache on MacOS/X"><strong>Building mod_jk for Apache on MacOS/X</strong></a></font></td></tr><tr><td><blockquote>
1084 <p>
1085 Mac OS X (10.2.x) build notes :
1086 </p>
1087 <p>
1088 Assuming that you are root :
1089 </p>
1090 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen">For Apache 1.3:</div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apxs=/usr/sbin/apxs</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cd apache-1.3</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make -f Makefile.apxs</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cp mod_jk.so /etc/libexec/httpd</b></nobr></code><br><div class="screen">For Apache 2.0:</div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apxs=/usr/local/apache2/bin/apxs</b></nobr></code><br><div class="screen">(you should point to the directory where you installed Apache 2.0)</div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cd apache-2.0</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make -f Makefile.apxs install</b></nobr></code><br></td></tr></table></div></p>
1091 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Getting mod_jk linked statically with Apache"><strong>Getting mod_jk linked statically with Apache</strong></a></font></td></tr><tr><td><blockquote>
1092 <p>
1093 mod_jk allows to install mod_jk in the Apache source tree to get a statically
1094 linked mod_jk. Having mod_jk in the httpd executable brings some performance
1095 improvements. The configure option --with-apache prepare mod_jk to install it
1096 in the Apache source tree.
1097 The option --with-apache works both for Apache-1.3 and Apache-2.0.
1098 The examples below show how to get mod_jk in the httpd process.
1099 </p>
1100
1101 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation in Apache-2.0"><strong>Installation in Apache-2.0</strong></a></font></td></tr><tr><td><blockquote>
1102 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen"> /home/apache20/httpd-2.0.43 is the directory where the httpd-2.0 sources
1103 are located. </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apache=/home/apache20/httpd-2.0.43</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make</b></nobr></code><br><div class="screen">Install the mod_jk library and other files in
1104 /home/apache20/httpd-2.0.43/modules: </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make install</b></nobr></code><br><div class="screen"> It is not possible to configure Apache directly because the config.m4 of mod_jk must
1105 be added to the configure of httpd-2.0. </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cd /home/apache20/httpd-2.0.43</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">sh buildconf</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">configure ... --with-mod_jk</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make install</b></nobr></code><br></td></tr></table></div></p>
1106 <p>
1107 The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only
1108 allow static linking of mod_jk.
1109 </p>
1110 </blockquote></td></tr></table>
1111
1112 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation in Apache-1.3"><strong>Installation in Apache-1.3</strong></a></font></td></tr><tr><td><blockquote>
1113 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen"> /home/apache/apache_1.3.27 is the directory where the apache-1.3 sources
1114 are located. </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">./configure --with-apache=/home/apache/apache_1.3.27</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make</b></nobr></code><br><div class="screen">Install the libjk library, mod_jk.c, includes and other files in
1115 /home/apache/apache_1.3.27/src/modules/jk: </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make install</b></nobr></code><br><div class="screen"> Configure in the Apache sources: </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">cd /home/apache/apache_1.3.27</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">configure ... --enable-module=dir --disable-shared=dir \</b></nobr></code><br><code><nobr><em class="screen"> </em><b class="screen">              --activate-module=src/modules/jk/libjk.a \</b></nobr></code><br><code><nobr><em class="screen"> </em><b class="screen">              --disable-shared=jk</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make</b></nobr></code><br><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">make install</b></nobr></code><br></td></tr></table></div></p>
1116 <p>
1117 The --enable-shared=jk is also working and builds a dso file.
1118 </p>
1119 <p class="screen"><div align="left"><table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"><tr><td bgcolor="#000000" align="left"><div class="screen"> Just change the configure in the Apache sources: </div><code><nobr><em class="screen">[user@host] ~ $ </em><b class="screen">configure ... --enable-module=dir --enable-shared=dir \</b></nobr></code><br><code><nobr><em class="screen"> </em><b class="screen">              --activate-module=src/modules/jk/libjk.a \</b></nobr></code><br><code><nobr><em class="screen"> </em><b class="screen">              --enable-shared=jk</b></nobr></code><br></td></tr></table></div></p>
1120 </blockquote></td></tr></table>
1121
1122 </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
1123         Copyright &copy; 1999-2011, Apache Software Foundation
1124         </em></font></div></td></tr></table></body></html>