rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml

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