rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/faq.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE document [
   3   <!ENTITY project SYSTEM "project.xml">
   4 ]>
   5 <document url="faq.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>FAQ</title>
  26 <author email="hgomez@apache.org">Henri Gomez</author>
  27 <date>$Date: 2009-03-05 12:42:14 +0100 (Thu, 05 Mar 2009) $</date>
  28 </properties>
  29 <body>
  30 <section name="General">
  31 <p>
  32 General Informations and FAQ about JK
  33 </p>
  34 <subsection name="Where can I get help/support for JK ?">
  35 <p>
  36 The primary mechanism for support is through the JK
  37 documentation included in the doc directory.
  38 Documentation is also available on the Apache Tomcat web site devoted to the
  39 <a href="http://tomcat.apache.org/connectors-doc/">
  40 Apache Tomcat Connectors Project</a>
  41 For additional help, the best resource is the Tomcat Users Discussion list.
  42 You should start by searching
  43 <a href="http://mail-archives.apache.org/mod_mbox/tomcat-users/">
  44 the mail list archive</a>
  45 before you post questions to the list.
  46 If you are unable to locate the answer to your question in the archive,
  47 you can post questions about JK to the user list for assistance.
  48 Make sure that you include the version of your Webserver,
  49 that you are using as well as the platform you are running on
  50 and go
  51 <a href="http://tomcat.apache.org/lists.html">
  52 here</a>
  53 to determine how to subscribe to tomcat mailing list.
  54 </p>
  55 </subsection>
  56
  57 <subsection name="I can't find JK anywhere. Where is it?">
  58 <p>
  59 Now that JK moved to the <b>tomcat-connectors</b> repository,
  60 the source and the binaries for JK can be downloaded from a mirror at the
  61 <a href="http://tomcat.apache.org/download-connectors.cgi">
  62 Tomcat Connectors (mod_jk, mod_jk2) Downloads</a> page.
  63 </p>
  64 </subsection>
  65
  66 <subsection name="What's the difference between JK and mod_jk ?">
  67 <br />
  68 <p>
  69 <b>JK</b> is a project covering web-servers to Tomcat connectors,
  70 whereas <b>mod_jk</b> is the <a href="../webserver_howto/apache.html">Apache module</a> developed in JK.
  71 </p>
  72
  73 <p>
  74 <a href="../webserver_howto/iis.html">IIS webserver</a>support is implemented on JK, using a redirector
  75 called <b>isapi redirector</b>.
  76 </p>
  77
  78 <p>
  79 <a href="../webserver_howto/nes.html">Netscape/SunONE/Sun webserver</a>webserver support is implemented on JK, using a redirector
  80 called <b>nsapi redirector</b>.
  81 </p>
  82
  83 </subsection>
  84
  85 <subsection name="Where can I get more information ?">
  86 <p>
  87 For <b>JK 1.2.x</b>, you should read :
  88 </p>
  89
  90 <ul>
  91
  92 <li>
  93 <a href="../generic_howto/quick.html">For the impatient</a>
  94 </li>
  95
  96 <li>
  97 <a href="../webserver_howto/apache.html">Apache and JK</a>
  98 </li>
  99
 100 <li>
 101 <a href="../webserver_howto/iis.html">IIS and JK</a>
 102 </li>
 103
 104 <li>
 105 <a href="../webserver_howto/nes.html">Netscape/SunONE/Sun and JK</a>
 106 </li>
 107
 108 <li>
 109 <a href="../generic_howto/workers.html">Workers configuration</a>
 110 </li>
 111 </ul>
 112
 113 <p>
 114 For more detailed information, have a look at the Reference Guide.
 115 You could also try searching the mailing list archives for "JK" or look at the source.
 116 </p>
 117 </subsection>
 118
 119 <subsection name="Which protocol should I use? Ajp12 or Ajp13?">
 120 <p>
 121 <a href="../ajp/ajpv13a.html">Ajp13</a> is a newer protocol, it's faster, and it works better with SSL.
 122 You almost certainly want to use it now that <strong>ajp12 is deprecated</strong>.
 123 </p>
 124 <p>
 125 Also ajp13 is supported by all Apache Tomcat including 3.2.x , 3.3.x, 4.0.x, 4.1.x, 5.0.x, 5.5.x
 126 and the new tomcat 6.
 127 </p>
 128
 129 <p>
 130 Others Servlet engines like <b>jetty</b> have support for Ajp13.
 131 </p>
 132 </subsection>
 133
 134 <subsection name="I've got a firewall between my web server and Tomcat which drops ajp13 connections after some time">
 135 <p>
 136 Ajp13 uses persistant connections where the traffic could be null if there is no request to be sent to Tomcat.
 137 Firewalls use to drop inactive connections and will make your web server and Tomcat think the connection is valid.
 138 </p>
 139 <p>
 140 Starting with JK 1.2.0, a <b>socket_keepalive</b> property as been added to ajp13 settings, and you should take a look at
 141 it in <a href="../generic_howto/workers.html">Workers HowTo</a> and
 142 <a href="../reference/workers.html">workers.properties reference</a>.
 143 If nothing else helps, you can try <b>JkOptions +DisableReuse</b>, but this will have strong performance implications.
 144 </p>
 145 </subsection>
 146
 147 <subsection name="Under heavy load, I've got many threads in Tomcat even if my Apache Web Server handles much of the load">
 148 <p>
 149 Under heavy load, Apache Web Server creates many children to handle the load,
 150 which will in turn create many connections
 151 to Tomcat to forward the requests they should handle.
 152 Apache Web Server will normally kill the children/threads when the load decreases.
 153 But if the load is still there and even if only Apache handles the requests,
 154 ie static contents, the children are kept and with them all the ajp13 connections,
 155 even if they are no more used.
 156 </p>
 157 <p>
 158 To close connections after some time of inactivity you can use <b>connection_pool_timeout</b>,
 159 for more informations refer to <a href="../reference/workers.html">workers.properties reference</a>.
 160 </p>
 161 </subsection>
 162
 163 </section>
 164
 165 <section name="Apache">
 166 <p>
 167 Informations and FAQ about mod_jk and Apache Web Servers.
 168 </p>
 169 <subsection name="Whenever I restart Tomcat, Apache locks up!">
 170 <p>
 171 The Ajp13 protocol keeps an open socket between Tomcat and Apache.
 172 Release of mod_jk present in J-T-C handles the network failure.
 173 But with very ancient releases of mod_jk, you may have to restart Apache as well.
 174 </p>
 175 </subsection>
 176
 177 <subsection name="Why do there exist two files mod_jk.so (-eapi ad -noeapi) in download directories for Apache 1.3?">
 178 <p>
 179 Many versions of Apache use a modified API, known at Extended API, developed for use with the
 180 <a href="http://www.modssl.org">mod_ssl module</a>. Starting with Apache 2.0 there is no more difference.
 181 </p>
 182
 183 <p>
 184 For example, Apache 1.3 present in certains recent Linux distributions include the
 185 <b>mod_ssl</b> module.
 186 </p>
 187
 188 <p>
 189 So if you got such 'Extended Apache', you need to use <b>mod_jk.so-eapi</b>.
 190 </p>
 191
 192 <p>
 193 You should use <b>mod_jk.so-noeapi</b> only for 'Standard Apache' (ie without mod_ssl).
 194 </p>
 195
 196 <p>
 197 It's wise to avoid using EAPI modules on STD API Apache or to use standard API modules on EAPI Apache.
 198 Allways be sure to have the <b>mod_jk.so</b> witch match your version of Apache
 199 </p>
 200 </subsection>
 201
 202 <subsection name="What's that message about 'garbled DSO ?'">
 203 <p>
 204 It's related to Apache EAPI, the message <code>'mod_jk.so is garbled - perhaps this is not an Apache module DSO ?'</code>
 205 just told you, that your're trying to install a mod_jk.so DSO module that was compiled on an Apache using EAPI,
 206 like apache-mod_ssl or apache from Redhat distro 6.2/7.0 but your system use the standard apache with normal API.
 207 </p>
 208 </subsection>
 209
 210 <subsection name="And the message about 'module might crash under EAPI!">
 211 <p>
 212 Also related to EAPI, the message <code>'[warn] Loaded DSO /usr/lib/apache/mod_jk.so uses plain Apache 1.3 API,
 213 this module might crash under EAPI! (please recompile it with -DEAPI)'</code>, the mod_jk.so was compiled under normal
 214 Apache with standard API and you try to install the module on an Apache using EAPI.
 215 </p>
 216 </subsection>
 217
 218 <subsection name="APXS is getting an error during the build of mod_jk, like rc=0 or rc=255.  I tried all of the steps in the build section, what do I do now ?">
 219 <p>
 220 APXS is a Perl script that is created when you build the Apache web server from source.
 221 Chances are that if you are getting these errors and you obtained Apache as a binary distribution,
 222 that APXS is not configured correctly for your system.
 223 Your best bet is to get the Apache source from http://httpd.apache.org and build it yourself.
 224 Use the following for a basic build (read the Apache docs for other options):
 225 <screen>
 226 <type>cd /usr/local/src</type><br/>
 227 <type>gzip -dc apache_1.3.19.tar.gz|tar xvf -</type><br/>
 228 <type>cd apache_1.3.19</type><br/>
 229 <type>./configure --prefix=/usr/local/apache \</type><br/>
 230 <type>            --enable-module=most \</type><br/>
 231 <type>            --enable-shared=max</type><br/>
 232 <type>make</type><br/>
 233 <type>make install</type><br/>
 234 </screen>
 235 </p>
 236 <p>
 237 Note: The above steps assume that you downloaded the Apache source and placed it in your /usr/local/src directory.
 238 </p>
 239 </subsection>
 240
 241 <subsection name="Apache 2.0 complains about incorrect module version">
 242 <p>
 243 Since Apache 2.0 API still change often, the Apache 2.0 teams decide to put in headers of compiled modules the
 244 Apache 2.0 version used to compile the module. This check is called Magic Module Number bump.
 245 </p>
 246 <p>
 247 At start time Apache 2.0 check that version in modules headers and stop if it detect that a module was compiled
 248 for another Apache 2.0 version. As such you should allways use modules compiled for the same Apache 2.0 version.
 249 This check may be removed if the future.
 250 </p>
 251 </subsection>
 252
 253 <subsection name="Does it work for Apache 2.2?">
 254 <p>
 255 mod_jk works well with Apache 2.2. You need a binary module compiled for version 2.2 of the Apache web server.
 256 A binary compiled for version 2.0 will not work.
 257 </p>
 258 <p>
 259 Important parts of the functionality of mod_jk have been reimplemented as Apache httpd modules mod_proxy_ajp
 260 and mod_proxy_balancer. These are part of the standard distributoin of Apache 2.2. The new modules do not contain
 261 all features of mod_jk, but you get them automatically with every Apache 2.2.
 262 </p>
 263 </subsection>
 264
 265 <subsection name="JNI doesn't work with Apache 1.3">
 266 <warn>JNI workers have been deprecated. They will likely not work. Do not use them.</warn>
 267 <p>
 268 JNI support requires a multi-threaded environment which is not the general case for Apache 1.3.
 269 You should verify if Apache 1.3 has been build with thread support and if not you could add the
 270 the pthreads library to your <b>httpd.conf</b> file.
 271 </p>
 272
 273 <source>
 274   # Add pthread to Apache in httpd.conf
 275   LoadModule "/usr/lib/libpthreads.so"
 276 </source>
 277
 278 <p>
 279 Also keep in mind that JNI is suited for multi-threaded servers and you should consider upgrading
 280 to Apache 2.x to support JNI.
 281 </p>
 282 </subsection>
 283
 284 <subsection name="JNI report that JVM couldn't be started under Linux">
 285 <warn>JNI workers have been deprecated. They will likely not work. Do not use them.</warn>
 286 <p>
 287 Under Linux, you should set some environment variables BEFORE launching your Apache server :
 288 </p>
 289
 290 <screen>
 291 <read>export LD_LIBRARY_PATH=$jre/bin:$jre/bin/classic:$LD_LIBRARY_PATH</read>
 292 </screen>
 293
 294 <p>
 295 Also some Linux distributions have enabled a GLIBC feature called 'floating stacks' which may not works with kernel
 296 less than 2.4.10 on SMP machines. You should disable floating stacks by exporting an environment variable :
 297 </p>
 298
 299 <screen>
 300 <read>export LD_ASSUME_KERNEL=2.2.5</read>
 301 </screen>
 302
 303 <p>
 304 You could have to update your service scripts, ie <b>/etc/rc.d/init.d/httpd</b>, to set these env vars
 305 before your httpd server starts.
 306 </p>
 307 </subsection>
 308
 309 <subsection name="Mixed errors when building via configure">
 310 <p>
 311 configure assume you have some GNU tools already installed and configured for your system, and ad minima <b>libtool</b>.
 312 </p>
 313 <p>
 314 Also some systems may have mixed cc and gcc setup which may make you puzzled when trying to link an Apache built with native
 315 c compiler with a jk/jk2 build with gcc.
 316 </p>
 317 <p>
 318 In case the make processing doesn't work as expected, you should use a GNU make <b>gmake</b>.
 319 </p>
 320 </subsection>
 321
 322 </section>
 323 </body>
 324 </document>