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

   1 <?xml version="1.0"?>
   2 <!--
   3   Licensed to the Apache Software Foundation (ASF) under one or more
   4   contributor license agreements.  See the NOTICE file distributed with
   5   this work for additional information regarding copyright ownership.
   6   The ASF licenses this file to You under the Apache License, Version 2.0
   7   (the "License"); you may not use this file except in compliance with
   8   the License.  You may obtain a copy of the License at
   9
  10       http://www.apache.org/licenses/LICENSE-2.0
  11
  12   Unless required by applicable law or agreed to in writing, software
  13   distributed under the License is distributed on an "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15   See the License for the specific language governing permissions and
  16   limitations under the License.
  17 -->
  18 <!DOCTYPE document [
  19   <!ENTITY project SYSTEM "project.xml">
  20 ]>
  21 <document url="apache.html">
  22
  23     &project;
  24
  25     <properties>
  26         <author email="mturk@apache.org">Mladen Turk</author>
  27         <title>Configuring Apache</title>
  28     </properties>
  29
  30 <body>
  31
  32 <section name="Configuration Directives">
  33 <p>
  34 Most of the directives are allowed once in the global part of the Apache httpd
  35 configuration and once in every &lt;VirtualHost&gt; elements. Exceptions from this rule are
  36 explicitly listed in the table below.
  37 </p>
  38 <p>
  39 Most values are inherited from the main server to the virtual hosts.
  40 Since version 1.2.20 they can be overwritten in the virtual hosts.
  41 Exceptions from this rule are again explicitly listed in the table below.
  42 See especially JkMountCopy.
  43 </p>
  44 <warn>
  45 Warning: If Apache httpd and Tomcat are configured to serve content from
  46 the same filing system location then care must be taken to ensure that httpd is
  47 not able to serve inappropriate content such as the contents of the WEB-INF
  48 directory or JSP source code.
  49 </warn>
  50 <p>
  51 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 <p>
  57 Here are the all directives supported by Apache:
  58 </p>
  59 <attributes name="Directive">
  60 <attribute name="JkWorkersFile" required="false"><p>
  61 The name of a worker file for the Tomcat servlet containers.
  62 <br/>
  63 This directive is only allowed once. It must be put into
  64 the global part of the configuration.
  65 <br/>
  66 If you don't use the JkWorkerProperty directives, then you must
  67 define your workers with a valid JkWorkersFile. There is no default
  68 value.
  69 </p></attribute>
  70 <attribute name="JkWorkerProperty" required="false"><p>
  71 Enables setting worker properties inside Apache configuration file.
  72 The syntax is the same as in the JkWorkersFile (usually workers.properties).
  73 Simply prefix each line with "JkWorkerProperty" to put it directly into
  74 the Apache httpd config files.
  75 <br/>
  76 This directive is allowed multiple times.
  77 It must be put into the global part of the configuration.
  78 <br/>
  79 If you don't use the JkWorkerProperty directives, then you must
  80 define your workers with a valid JkWorkersFile. There is no default
  81 value.
  82 <br/>
  83 This directive is available in jk1.2.7 version and later.
  84 </p></attribute>
  85 <attribute name="JkShmFile" required="false"><p>
  86 Shared memory file name. Used only on unix platforms.
  87 The shm file is used by balancer and status workers.
  88 <br/>
  89 This directive is only allowed once. It must be put into
  90 the global part of the configuration.
  91 <br/>
  92 The default value is logs/jk-runtime-status.
  93 It is highly recommended that the shm file be placed on a local
  94 drive and not an NFS share.
  95 </p>
  96 <p>
  97 The shared memory contains configuration and runtime information for load balancer
  98 workers and their members. It is need in order that all apache children
  99 <ul>
 100 <li>share the same status information for load balancing members (OK, ERROR, ...),</li>
 101 <li>share the information about load taken by the individual workers,</li>
 102 <li>share the information for the parts of the configuration, which are changeable
 103 during runtime by status workers.</li>
 104 </ul>
 105 </p>
 106 </attribute>
 107 <attribute name="JkShmSize" required="false"><p>
 108 Size of the shared memory file name.
 109 <br/>
 110 This directive is only allowed once. It must be put into
 111 the global part of the configuration.
 112 <br/>
 113 The default value depends on the platform. It is usually less than 64KB.
 114 </p></attribute>
 115 <p>Starting with version 1.2.27 the size of the shared memory is determined
 116 automatically, even for large numbers of workers. This attribute is not
 117 needed any longer.</p>
 118 <attribute name="JkMountFile" required="false"><p>
 119 File containing multiple mappings from a context to a Tomcat worker.
 120 It is usually called uriworkermap.properties.
 121 <br/>
 122 For inheritance rules, see: JkMountCopy.
 123 <br/>
 124 There is no default value.
 125 </p></attribute>
 126 <attribute name="JkMountFileReload" required="false"><p>
 127 This directive configures the reload check interval in seconds.
 128 The JkMountFile is checked periodically for changes.
 129 A changed file gets reloaded automatically. If you set
 130 this directive to "0", reload checking is turned off.
 131 <br/>
 132 The default value is 60 seconds.
 133 <br/>
 134 This directive has been added in version 1.2.20 of mod_jk.
 135 </p></attribute>
 136 <attribute name="JkMount" required="false"><p>
 137 A mount point from a context to a Tomcat worker.
 138 <br/>
 139 This directive is allowed multiple times.
 140 It is allowed in the global configuration and in VirtualHost.
 141 You can also use it inside Location with a different syntax.
 142 Inside Location, one omits the first argument (path),
 143 which gets inherited from the Location.
 144 <br/>
 145 By default JkMount entries are not inherited from the global
 146 server to other VirtualHosts or between VirtualHosts.
 147 For the complete inheritance rules, see: JkMountCopy.
 148 </p></attribute>
 149 <attribute name="JkUnMount" required="false"><p>
 150 An exclusion mount point from a context to a Tomcat worker.
 151 All exclusion mounts are checked after mapping a request
 152 to a tomcat worker. If the request maps also to an exclusion,
 153 it will not be forwarded to tomcat, and instead be served locally.
 154 <br/>
 155 This directive is allowed multiple times.
 156 It is allowed in the global configuration and in VirtualHost.
 157 You can also use it inside Location with a different syntax.
 158 Inside Location, one omits the first argument (path),
 159 which gets inherited from the Location.
 160 For inheritance rules, see: JkMountCopy.
 161 <br/>
 162 This directive is available in jk1.2.7 version and later.
 163 </p></attribute>
 164 <attribute name="JkAutoAlias" required="false"><p>
 165 Automatically Alias webapp context directories into the Apache
 166 document space.
 167 <br/>
 168 Care should be taken to ensure that only static content is served via httpd as a
 169 result of using this directive. Any static content served by httpd will bypass any
 170 security constraints defined in the application's web.xml.
 171 <br/>
 172 For inheritance rules, see: JkMountCopy.
 173 <br/>
 174 There is no default value.
 175 </p></attribute>
 176 <attribute name="JkMountCopy" required="false"><p>
 177 If this directive is set to "On" in some virtual server,
 178 the mounts from the global server will be copied to this
 179 virtual server, more precisely all mounts defined by JkMount
 180 or JkUnMount. The Mounts defined by JkMountFile and JkAutoAlias
 181 will only be inherited, if the VirtualHost does not define
 182 it's own JkMountFile or JkAutoAlias.
 183 <br/>
 184 If you want all vhost to inherit mounts from the main server,
 185 you can set JkMountCopy to 'All' in the main server.
 186 <br/>
 187 This directive is only allowed inside VirtualHost (with value "On")
 188 and in the global server (with value "All").
 189 <br/>
 190 The default is Off, so no mounts will be inherited from the global
 191 server to any VirtualHost.
 192 <br/>
 193 Starting with version 1.2.26 you can also set it to "All" in the
 194 global virtual server. This will switch the default to On.
 195 </p></attribute>
 196 <attribute name="JkWorkerIndicator" required="false"><p>
 197 Name of the Apache environment variable that can be used to set worker names
 198 in combination with SetHandler jakarta-servlet.
 199 <br/>
 200 This directive is only allowed once per virtual server.
 201 It is allowed in the global configuration and in VirtualHost.
 202 <br/>
 203 The default value is JK_WORKER_NAME.
 204 </p></attribute>
 205 <attribute name="JkWatchdogInterval" required="false"><p>
 206 This directive configures the watchdog thread interval in seconds.
 207 The workers are maintained periodically by a background thread
 208 running periodically every watchdog_interval seconds. Worker maintenance
 209 checks for idle connections, corrects load status and is able
 210 to detect backend health status.
 211 <br/>
 212 The maintenance only happens, if since the last maintenance at
 213 least <a href="workers.html"><code>worker.maintain</code></a>
 214 seconds have passed. So setting the JkWatchdogInterval
 215 much smaller than <code>worker.maintain</code> is not useful.
 216 <br/>
 217 The default value is 0 seconds, meaning the watchdog thread
 218 will not be created, and the maintenance is done in combination
 219 with normal requests instead.
 220 <br/>
 221 This directive is only allowed once. It must be put into
 222 the global part of the configuration.
 223 <br/>
 224 This directive has been added in version 1.2.27 of mod_jk.
 225 It is available only for httpd 2.x and above using APR libraries
 226 including thread support.
 227 </p></attribute>
 228 <attribute name="JkLogFile" required="false"><p>
 229 Full or server relative path to the Tomcat Connector module log file.
 230 It will also work with pipe, by using a value of the form "| ...".
 231 <br/>
 232 The default value is logs/mod_jk.log.
 233 <br/>
 234 Pipes are supported for Apache 1.3 only since version 1.2.16.
 235 The default value exists only since version 1.2.20.
 236 </p></attribute>
 237 <attribute name="JkLogLevel" required="false"><p>
 238 The Tomcat Connector module log level, can be debug, info, warn
 239 error or trace.
 240 <br/>
 241 The default value is info.
 242 </p></attribute>
 243 <attribute name="JkLogStampFormat" required="false"><p>
 244 The Tomcat Connector module <b>date</b> log format, using an
 245 extended strftime syntax.
 246 This format will be used for the time stamps in the JkLogFile.
 247 The maximum length of the format is 63 characters.
 248 <br/>
 249 Starting with version 1.2.24 of mod_jk you can also use %Q
 250 for adding milliseconds to the log and %q for microseconds.
 251 These conversion specifiers are an extension to strftime.
 252 They will only work on platforms with a gettimeofday() function.
 253 You can use %Q and %q only once in the pattern and also not both
 254 together in the same pattern.
 255 <br/>
 256 The default value is "[%a %b %d %H:%M:%S %Y] " and beginning
 257 with version 1.2.24 on platforms with a gettimeofday()
 258 function it is "[%a %b %d %H:%M:%S.%Q %Y] ".
 259 </p></attribute>
 260 <attribute name="JkRequestLogFormat" required="false"><p>
 261 Request log format string. See detailed description below.
 262 <br/>
 263 There is no default value. Without defining a value, the request logging
 264 is turned off.
 265 </p></attribute>
 266 <attribute name="JkExtractSSL" required="false"><p>
 267 Turns on SSL processing and information gathering by mod_jk
 268 <br/>
 269 The default value is On.
 270 <br/>
 271 In order to make SSL data available for mod_jk in Apache, you need to
 272 set <code>SSLOptions +StdEnvVars</code>. For the certificate information you also need
 273 to add <code>SSLOptions +ExportCertData</code>.
 274 </p>
 275 <p>
 276   Specifically, mod_jk will export the following environment variables from
 277   Apache httpd to Tomcat under these request attributes as per the
 278   Servlet Specification 3.0, section 3.8:
 279 </p>
 280 <table>
 281   <tr><th>Env Var</th><th>Request Attribute Name</th><th>Type</th><th>Example</th></tr>
 282   <tr>
 283     <td>SSL_CIPHER<br/>(or <code>JkKEYSIZEIndicator</code>)</td>
 284     <td>javax.servlet.request.cipher_suite</td>
 285     <td>java.lang.String</td>
 286     <td>DHE-RSA-AES256-SHA</td>
 287   </tr>
 288   <tr>
 289     <td>SSL_CIPHER_USEKEYSIZE<br/>(or <code>JkKEYSIZEIndicator</code>)</td>
 290     <td>javax.servlet.request.key_size</td>
 291     <td>java.lang.Integer</td>
 292     <td>256</td>
 293   </tr>
 294   <tr>
 295     <td>SSL_SESSION_ID<br/>(or <code>JkSESSIONIndicator</code>)</td>
 296     <td>javax.servlet.request.ssl_session</td>
 297     <td>java.lang.String</td>
 298     <td>905...32E (a hex string)</td>
 299   </tr>
 300   <tr>
 301     <td>SSL_CLIENT_CERT_CHAIN_<i>n</i><br/>(or <code>JkCERTCHAINPrefix</code><i>n</i>)</td>
 302     <td>javax.servlet.request.X509Certificate</td>
 303     <td>java.security.X509Certificate[]</td>
 304     <td>(A chain of certs in ascending order of trust, the first one being
 305         ths client's certificate, the second being the signer of that
 306         certificate, and so on)</td>
 307   </tr>
 308 </table>
 309 <p>
 310   For all other SSL-related variables, use <code>JkEnvVar</code> for each
 311   variable you want. Please note that, like <code>JkEnvVar</code>, these
 312   variables are available from the request <i><b>attributes</b></i>, not as
 313   environment variables or as request headers.
 314 </p>
 315 </attribute>
 316 <attribute name="JkHTTPSIndicator" required="false"><p>
 317 Name of the Apache environment variable that contains SSL indication.
 318 <br/>
 319 The default value is "HTTPS".
 320 </p></attribute>
 321 <attribute name="JkCERTSIndicator" required="false"><p>
 322 Name of the Apache environment variable that contains SSL client certificates.
 323 <br/>
 324 The default value is "SSL_CLIENT_CERT".
 325 </p></attribute>
 326 <attribute name="JkCIPHERIndicator" required="false"><p>
 327 Name of the Apache environment variable that contains SSL client cipher.
 328 <br/>
 329 The default value is "SSL_CIPHER".
 330 </p></attribute>
 331 <attribute name="JkCERTCHAINPrefix" required="false"><p>
 332 Name of the Apache environment (prefix) that contains SSL client chain certificates.
 333 <br/>
 334 The default value is "SSL_CLIENT_CERT_CHAIN_".
 335 </p></attribute>
 336 <attribute name="JkSESSIONIndicator" required="false"><p>
 337 Name of the Apache environment variable that contains SSL session.
 338 <br/>
 339 The default value is "SSL_SESSION_ID".
 340 </p></attribute>
 341 <attribute name="JkKEYSIZEIndicator" required="false"><p>
 342 Name of the Apache environment variable that contains SSL key size in use.
 343 <br/>
 344 The default value is "SSL_CIPHER_USEKEYSIZE".
 345 </p></attribute>
 346 <attribute name="JkLocalNameIndicator" required="false"><p>
 347 Name of the Apache environment variable which can be used to overwrite
 348 the forwarded local name.
 349 Use this only if you need to adjust the data (see the
 350 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 351 <br/>
 352 The default value is "JK_LOCAL_NAME".
 353 <br/>
 354 This directive has been added in version 1.2.28 of mod_jk.
 355 </p></attribute>
 356 <attribute name="JkLocalPortIndicator" required="false"><p>
 357 Name of the Apache environment variable which can be used to overwrite
 358 the forwarded local port.
 359 Use this only if you need to adjust the data (see the
 360 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 361 <br/>
 362 The default value is "JK_LOCAL_PORT".
 363 <br/>
 364 This directive has been added in version 1.2.28 of mod_jk.
 365 </p></attribute>
 366 <attribute name="JkRemoteHostIndicator" required="false"><p>
 367 Name of the Apache environment variable which can be used to overwrite
 368 the forwarded remote (client) host name.
 369 Use this only if you need to adjust the data (see the
 370 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 371 <br/>
 372 The default value is "JK_REMOTE_HOST".
 373 <br/>
 374 This directive has been added in version 1.2.28 of mod_jk.
 375 </p></attribute>
 376 <attribute name="JkRemoteAddrIndicator" required="false"><p>
 377 Name of the Apache environment variable which can be used to overwrite
 378 the forwarded remote (client) IP address.
 379 Use this only if you need to adjust the data (see the
 380 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 381 <br/>
 382 The default value is "JK_REMOTE_ADDR".
 383 <br/>
 384 This directive has been added in version 1.2.28 of mod_jk.
 385 </p></attribute>
 386 <attribute name="JkRemotePortIndicator" required="false"><p>
 387 Name of the Apache environment variable which can be used to overwrite
 388 the forwarded remote (client) IP address.
 389 Use this only if you need to adjust the data (see the
 390 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 391 <br/>
 392 The default value is "JK_REMOTE_PORT".
 393 <br/>
 394 This directive has been added in version 1.2.32 of mod_jk.
 395 </p></attribute>
 396 <attribute name="JkRemoteUserIndicator" required="false"><p>
 397 Name of the Apache environment variable which can be used to overwrite
 398 the forwarded user name.
 399 Use this only if you need to adjust the data (see the
 400 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 401 <br/>
 402 The default value is "JK_REMOTE_USER".
 403 <br/>
 404 This directive has been added in version 1.2.28 of mod_jk.
 405 </p></attribute>
 406 <attribute name="JkAuthTypeIndicator" required="false"><p>
 407 Name of the Apache environment variable which can be used to overwrite
 408 the forwarded authentication type.
 409 Use this only if you need to adjust the data (see the
 410 <a href="../generic_howto/proxy.html">proxy</a> documentation).
 411 <br/>
 412 The default value is "JK_AUTH_TYPE".
 413 <br/>
 414 This directive has been added in version 1.2.28 of mod_jk.
 415 </p></attribute>
 416 <attribute name="JkOptions" required="false"><p>
 417 Set one of more options to configure the mod_jk module. See below for
 418 details about this directive.
 419 <br/>
 420 This directive can be used multiple times per virtual server.
 421 <br/>
 422 The default value is "ForwardURIProxy" since version 1.2.24.
 423 It was "ForwardURICompatUnparsed" in version 1.2.23 and
 424 "ForwardURICompat" until version 1.2.22.
 425 </p></attribute>
 426 <attribute name="JkEnvVar" required="false"><p>
 427 Adds a name and an optional default value of environment variable
 428 that should be sent to servlet-engine as a request attribute.
 429 If the default value is not given explicitly, the variable
 430 will only be send, if it is set during runtime.
 431 <br/>
 432 The default is empty, so no additional variables will be sent.
 433 <br/>
 434 This directive can be used multiple times per virtual server.
 435 The settings will be merged between the global server and any
 436 virtual server.
 437 <br/>
 438 You can retrieve the variables on Tomcat as request attributes
 439 via request.getAttribute(attributeName). Note that the variables
 440 send via JkEnvVar will not be listed in request.getAttributeNames().
 441 <br/>
 442 Empty default values are supported since version 1.2.20.
 443 Not sending variables with empty defaults and empty runtime value
 444 has been introduced in version 1.2.21.
 445 </p></attribute>
 446 <attribute name="JkStripSession" required="false"><p>
 447 If this directive is set to On in some virtual server,
 448 the session IDs <code>;jsessionid=...</code> will be
 449 removed for non matched URLs.
 450 <br/>
 451 This directive is only allowed inside VirtualHost.
 452 <br/>
 453 The default is Off.
 454 <br/>
 455 This directive has been introduced in version 1.2.21.
 456 <br/>With version 1.2.27 and later this directive can have optional
 457 session ID identifier. If not specified it defaults to
 458 <code>;jsessionid</code>.
 459 </p>
 460 </attribute>
 461
 462 </attributes>
 463 </section>
 464
 465 <section name="Configuration Directives Types">
 466 <p>
 467 We'll discuss here the mod_jk directive types.
 468 </p>
 469
 470 <subsection name="Define workers">
 471 <p>
 472 <b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions.
 473 Take a look at <a href="workers.html">Workers documentation</a> for detailed description.
 474
 475 <source>
 476   JkWorkersFile     /etc/httpd/conf/workers.properties
 477 </source>
 478
 479 <br/>
 480 <br/>
 481 </p>
 482
 483 </subsection>
 484
 485 <subsection name="Logging">
 486 <p>
 487 <b>JkLogFile</b> specify the location where mod_jk is going to place its log file.
 488 </p>
 489
 490 <source>
 491   JkLogFile     /var/log/httpd/mod_jk.log
 492 </source>
 493
 494 <p>
 495 Since JK 1.2.3 for Apache 2.x and JK 1.2.16 for Apache 1.3 this can also
 496 be used for piped logging:
 497 </p>
 498
 499 <source>
 500   JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
 501 </source>
 502
 503 <p>
 504 <b>JkLogLevel</b>
 505 set the log level between :
 506 </p>
 507
 508 <ul>
 509 <li>
 510 <b>info</b> log will contain standard mod_jk activity (default).
 511 </li>
 512 <li>
 513 <b>warn</b> log will contain non fatal error reports.
 514 </li>
 515 <li>
 516 <b>error</b> log will contain also error reports.
 517 </li>
 518 <li>
 519 <b>debug</b> log will contain all information on mod_jk activity
 520 </li>
 521 <li>
 522 <b>trace</b> log will contain all tracing information on mod_jk activity
 523 </li>
 524 </ul>
 525
 526 <source>
 527   JkLogLevel    info
 528 </source>
 529
 530 <p>
 531 <code>info</code> should be your default selection for normal operations.
 532 <br/>
 533 <br/>
 534 </p>
 535
 536 <p>
 537 <b>JkLogStampFormat</b> will configure the date/time format found on mod_jk log file.
 538 Using the strftime() format string it's set by<br />
 539 default to <b>"[%a %b %d %H:%M:%S %Y]"</b>
 540 </p>
 541
 542 <source>
 543   JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
 544 </source>
 545
 546 <p>
 547 <br/>
 548 <br/>
 549 </p>
 550
 551 <p>
 552 <b>JkRequestLogFormat</b> will configure the format of mod_jk individual request logging.
 553 Request logging is configured and enabled on a per virtual host basis.
 554 To enable request logging for a virtual host just add a JkRequestLogFormat config.
 555 The syntax of the format string is similar to the Apache LogFormat command,
 556 here is a list of the available request log format options:
 557 </p>
 558
 559 <p>
 560 <attributes name="Options">
 561   <attribute name="%b" required="false">Bytes sent, excluding HTTP headers (CLF format)</attribute>
 562   <attribute name="%B" required="false">Bytes sent, excluding HTTP headers</attribute>
 563   <attribute name="%H" required="false">The request protocol</attribute>
 564   <attribute name="%m" required="false">The request method</attribute>
 565   <attribute name="%p" required="false">The canonical Port of the server serving the request</attribute>
 566   <attribute name="%q" required="false">The query string (prepended with a ? if a query string exists, otherwise an empty string)</attribute>
 567   <attribute name="%r" required="false">First line of request</attribute>
 568   <attribute name="%s" required="false">Request HTTP status code</attribute>
 569   <attribute name="%T" required="false">Request duration, elapsed time to handle request in seconds '.' micro seconds</attribute>
 570   <attribute name="%U" required="false">The URL path requested, not including any query string.</attribute>
 571   <attribute name="%v" required="false">The canonical ServerName of the server serving the request</attribute>
 572   <attribute name="%V" required="false">The server name according to the UseCanonicalName setting</attribute>
 573   <attribute name="%w" required="false">Tomcat worker name</attribute>
 574   <attribute name="%R" required="false">Real worker name</attribute>
 575 </attributes>
 576
 577 <source>
 578   JkRequestLogFormat     "%w %V %T"
 579 </source>
 580
 581 <br/>
 582 <br/>
 583 </p>
 584
 585 <p>
 586 You can also log mod_jk information using the Apache standard module <b>mod_log_config</b>.
 587 The module sets several notes in the Apache httpd notes table.
 588 Most of them are are only useful in combination with a load balancer worker.
 589 </p>
 590
 591 <p>
 592 <attributes name="Note">
 593   <attribute name="JK_WORKER_NAME" required="false">Name of the worker selected by the URI mapping</attribute>
 594   <attribute name="JK_WORKER_TYPE" required="false">Type of the worker selected by the URI mapping</attribute>
 595   <attribute name="JK_WORKER_ROUTE" required="false">Actual worker name selected by the URI mapping (usually a member of the load balancer).<br/>
 596                                                          Before version 1.2.26 only available if JkRequestLogFormat is set.</attribute>
 597   <attribute name="JK_REQUEST_DURATION" required="false">Request duration in seconds and microseconds.<br/>
 598                                                          Before version 1.2.26 only available if JkRequestLogFormat is set.</attribute>
 599   <attribute name="JK_LB_FIRST_NAME" required="false">Load-Balancer: Name of the first worker tried</attribute>
 600   <attribute name="JK_LB_FIRST_TYPE" required="false">Load-Balancer: Type of the first worker tried</attribute>
 601   <attribute name="JK_LB_FIRST_ACCESSED" required="false">Load-Balancer: Access count for the first worker tried</attribute>
 602   <attribute name="JK_LB_FIRST_READ" required="false">Load-Balancer: Bytes read for the first worker tried</attribute>
 603   <attribute name="JK_LB_FIRST_TRANSFERRED" required="false">Load-Balancer: Bytes transferred for the first worker tried</attribute>
 604   <attribute name="JK_LB_FIRST_ERRORS" required="false">Load-Balancer: Error count for the first worker tried</attribute>
 605   <attribute name="JK_LB_FIRST_BUSY" required="false">Load-Balancer: Busy count for the first worker tried</attribute>
 606   <attribute name="JK_LB_FIRST_ACTIVATION" required="false">Load-Balancer: Activation state for the first worker tried</attribute>
 607   <attribute name="JK_LB_FIRST_STATE" required="false">Load-Balancer: Error state for the first worker tried</attribute>
 608   <attribute name="JK_LB_LAST_NAME" required="false">Load-Balancer: Name of the last worker tried</attribute>
 609   <attribute name="JK_LB_LAST_TYPE" required="false">Load-Balancer: Type of the last worker tried</attribute>
 610   <attribute name="JK_LB_LAST_ACCESSED" required="false">Load-Balancer: Access count for the last worker tried</attribute>
 611   <attribute name="JK_LB_LAST_READ" required="false">Load-Balancer: Bytes read for the last worker tried</attribute>
 612   <attribute name="JK_LB_LAST_TRANSFERRED" required="false">Load-Balancer: Bytes transferred for the last worker tried</attribute>
 613   <attribute name="JK_LB_LAST_ERRORS" required="false">Load-Balancer: Error count for the last worker tried</attribute>
 614   <attribute name="JK_LB_LAST_BUSY" required="false">Load-Balancer: Busy count for the last worker tried</attribute>
 615   <attribute name="JK_LB_LAST_ACTIVATION" required="false">Load-Balancer: Activation state for the last worker tried</attribute>
 616   <attribute name="JK_LB_LAST_STATE" required="false">Load-Balancer: Error state for the last worker tried</attribute>
 617 </attributes>
 618
 619 <source>
 620   LogFormat     "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \
 621                  %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log
 622   CustomLog     logs/access_log     mod_jk_log
 623 </source>
 624
 625 <br/>
 626 <br/>
 627 </p>
 628
 629 </subsection>
 630
 631 <subsection name="Forwarding">
 632 <p>
 633 The directive JkOptions allow you to set many forwarding options which will enable (+)
 634 or disable (-) following option. Without any leading signs, options will be enabled.
 635 <br/>
 636 <br/>
 637 </p>
 638
 639 <p>
 640 The four following options <b>+ForwardURIxxx</b> are mutually exclusive.
 641 Exactly one of them is required, a negative sign prefix is not allowed with them.
 642 The default value is "ForwardURIProxy" since version 1.2.24.
 643 It was "ForwardURICompatUnparsed" in version 1.2.23 and
 644 "ForwardURICompat" until version 1.2.22.
 645 You can turn the default off by switching on one of the other two options.
 646 You should leave this at it's default value, unless you have a very good
 647 reason to change it.
 648 <br/>
 649 <br/>
 650 </p>
 651
 652 <p>
 653 All options are inherited from the global server to virtual hosts.
 654 Options that support enabling (plus options) and disabling (minus options),
 655 are inherited in the following way:
 656 <br/>
 657 <br/>
 658 options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)
 659 <br/>
 660 <br/>
 661 </p>
 662
 663 <p>
 664 Using JkOptions <b>ForwardURIProxy</b>, the forwarded URI
 665 will be partially reencoded after processing inside Apache httpd and
 666 before forwarding to Tomcat. This will be compatible with local
 667 URL manipulation by mod_rewrite and with URL encoded session ids.
 668
 669 <source>
 670   JkOptions     +ForwardURIProxy
 671 </source>
 672
 673 <br/>
 674 <br/>
 675 </p>
 676
 677 <p>
 678 Using JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI
 679 will be unparsed. It's spec compliant and secure.
 680 It will always forward the original request URI, so rewriting
 681 URIs with mod_rewrite and then forwarding the rewritten URI
 682 will not work.
 683
 684 <source>
 685   JkOptions     +ForwardURICompatUnparsed
 686 </source>
 687
 688 <br/>
 689 <br/>
 690 </p>
 691
 692 <p>
 693 Using JkOptions <b>ForwardURICompat</b>, the forwarded URI will
 694 be decoded by Apache httpd. Encoded characters will be decoded and
 695 explicit path components like ".." will already be resolved.
 696 This is less spec compliant and is <b>not safe</b> if you are using
 697 prefix JkMount. This option will allow to rewrite URIs with
 698 mod_rewrite before forwarding.
 699
 700 <source>
 701   JkOptions     +ForwardURICompat
 702 </source>
 703
 704 <br/>
 705 <br/>
 706 </p>
 707
 708 <p>
 709 Using JkOptions <b>ForwardURIEscaped</b>, the forwarded URI will
 710 be the encoded form of the URI used by ForwardURICompat.
 711 Explicit path components like ".." will already be resolved.
 712 This will not work in combination with URL encoded session IDs,
 713 but it will allow to rewrite URIs with mod_rewrite before forwarding.
 714
 715 <source>
 716   JkOptions     +ForwardURIEscaped
 717 </source>
 718
 719 <br/>
 720 <br/>
 721 </p>
 722
 723 <p>
 724 JkOptions <b>RejectUnsafeURI</b> will block all
 725 URLs, which contain percent signs '%' or backslashes '\'
 726 after decoding.
 727 <br/>
 728 <br/>
 729 </p>
 730 <p>
 731 Most web apps do not use such URLs. Using the option RejectUnsafeURI, you
 732 can block several well known URL encoding attacks. By default, this option
 733 is not set.
 734 </p>
 735 <p>
 736 You can also realise such a check with mod_rewrite, which is more powerful
 737 but also slightly more complicated.
 738
 739 <source>
 740   JkOptions     +RejectUnsafeURI
 741 </source>
 742
 743 <br/>
 744 <br/>
 745 </p>
 746
 747 <p>
 748 JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b>
 749 directive of Apache web server. As such mod_dir should be available to Apache,
 750 statically or dynamically (DSO)
 751 <br/>
 752 <br/>
 753 </p>
 754
 755 <p>
 756 When DirectoryIndex is configured, Apache will create sub-requests for
 757 each of the local-url's specified in the directive, to determine if there is a
 758 local file that matches (this is done by stat-ing the file).
 759 </p>
 760
 761 <p>
 762 If ForwardDirectories is set to false (default) and Apache doesn't find any
 763 files that match, Apache will serve the content of the directory (if directive
 764 Options specifies Indexes for that directory) or a <code>403 Forbidden</code> response (if
 765 directive Options doesn't specify Indexes for that directory).
 766 </p>
 767
 768 <p>
 769 If ForwardDirectories is set to true and Apache doesn't find any files that
 770 match, the request will be forwarded to Tomcat for resolution. This is used in
 771 cases when Apache cannot see the index files on the file system for various
 772 reasons: Tomcat is running on a different machine, the JSP file has been
 773 precompiled etc.
 774 </p>
 775
 776 <p>Note that locally visible files will take precedence over the
 777 ones visible only to Tomcat (i.e. if Apache can see the file, that's the one
 778 that's going to get served). This is important if there is more then one type of
 779 file that Tomcat normally serves - for instance Velocity pages and JSP pages.
 780
 781 <source>
 782   JkOptions     +ForwardDirectories
 783 </source>
 784 <br/>
 785 <br/>
 786 </p>
 787
 788 <p>
 789 JkOptions <b>ForwardLocalAddress</b>, you ask mod_jk to send the local address,
 790 of the Apache web server instead remote client address. This can be used by
 791 Tomcat remote address valve for allowing connections only from registered Apache
 792 web servers.
 793
 794 <source>
 795   JkOptions     +ForwardLocalAddress
 796 </source>
 797
 798 <br/>
 799 <br/>
 800 </p>
 801
 802 <p>
 803 JkOptions <b>FlushPackets</b>, you ask mod_jk to flush Apache's connection
 804 buffer after each AJP packet chunk received from Tomcat. This option can have
 805 a strong performance penalty for Apache and Tomcat as writes are performed
 806 more often than would normally be required (ie: at the end of each
 807 response).
 808
 809 <source>
 810   JkOptions     +FlushPackets
 811 </source>
 812
 813 <br/>
 814 <br/>
 815 </p>
 816
 817 <p>
 818 JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection
 819 buffer after the response headers have been  received from Tomcat.
 820
 821 <source>
 822   JkOptions     +FlushHeader
 823 </source>
 824
 825 <br/>
 826 <br/>
 827 </p>
 828
 829 <p>
 830 JkOptions <b>DisableReuse</b>, you ask mod_jk to close connections immediately
 831 after their use. Normally mod_jk uses persistent connections and pools idle
 832 connections to reuse them, when new requests have to be sent to Tomcat.
 833 </p>
 834
 835 <p>
 836 Using this option will have a strong performance penalty for Apache and Tomcat.
 837 Use this only as a last resort in case of unfixable network problems.
 838 If a firewall between Apache and Tomcat silently kills idle connections,
 839 try to use the worker attribute socket_keepalive in combination with an appropriate
 840 TCP keepalive value in your OS.
 841
 842 <source>
 843   JkOptions     +DisableReuse
 844 </source>
 845
 846 <br/>
 847 <br/>
 848 </p>
 849
 850 <p>
 851 JkOptions <b>ForwardKeySize</b>,  you ask mod_jk, when using ajp13, to forward also the SSL Key Size  as
 852 required by Servlet API 2.3.
 853 This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default).
 854
 855 <source>
 856   JkOptions     +ForwardKeySize
 857 </source>
 858
 859 <br/>
 860 <br/>
 861 </p>
 862
 863 <p>
 864 JkOptions <b>ForwardSSLCertChain</b>,  you ask mod_jk, when using ajp13,
 865 to forward SSL certificate chain (off by default).
 866 Mod_jk only passes the <code>SSL_CLIENT_CERT</code> to the AJP connector. This is not a
 867 problem with self-signed certificates or certificates directly signed by the
 868 root CA certificate. However, there's a large number of certificates signed by
 869 an intermediate CA certificate, where this is a significant problem: A servlet
 870 will not have the possibility to validate the client certificate on its own. The
 871 bug would be fixed by passing on the <code>SSL_CLIENT_CERT_CHAIN</code> to Tomcat via the AJP connector.
 872 <br/>
 873 This directive exists only since version 1.2.22.
 874 <source>
 875   JkOptions     +ForwardSSLCertChain
 876 </source>
 877
 878 <br/>
 879 <br/>
 880 </p>
 881
 882 <p>
 883 The directive <b>JkEnvVar</b> allows you to forward environment variables
 884 from Apache server to Tomcat engine.
 885 You can add a default value as a second parameter to the directive.
 886 If the default value is not given explicitly, the variable
 887 will only be send, if it is set during runtime.
 888 <br/>
 889 The variables can be retrieved on the Tomcat side as request attributes
 890 via request.getAttribute(attributeName).
 891 Note that the variables send via JkEnvVar will not be listed
 892 in request.getAttributeNames().
 893 <br/>
 894 <br/>
 895 The variables are inherited from the global server to virtual hosts.
 896
 897 <source>
 898   JkEnvVar     SSL_CLIENT_V_START     undefined
 899 </source>
 900 <br/>
 901 <br/>
 902 </p>
 903
 904 </subsection>
 905
 906 <subsection name="Assigning URLs to Tomcat">
 907 <p>
 908 If you have created a custom or local version of mod_jk.conf-local as noted above,
 909 you can change settings such as the workers or URL prefix.
 910 </p>
 911 <p>
 912 <b>JkMount</b> directive assign specific URLs to Tomcat.
 913 In general the structure of a JkMount directive is:
 914 </p>
 915
 916 <source>
 917   JkMount [URL prefix] [Worker name]
 918 </source>
 919
 920 <source>
 921   # send all requests ending in .jsp to worker1
 922   JkMount /*.jsp worker1
 923   # send all requests ending /servlet to worker1
 924   JkMount /*/servlet/ worker1
 925   # send all requests jsp requests to files located in /otherworker will go worker2
 926   JkMount /otherworker/*.jsp worker2
 927 </source>
 928
 929 <p>
 930 You can use the JkMount directive at the top level or inside &lt;VirtualHost&gt;
 931 sections of your httpd.conf file.
 932 </p>
 933 <p><b>JkUnMount</b> directive acts as an opposite to JkMount and blocks access
 934 to a particular URL. The purpose is to be able to filter out the particular content
 935 types from mounted context. The following example mounts /servlet/*
 936 context, but all .gif files that belongs to that context are not served.
 937 </p>
 938 <source>
 939   # send all requests ending with /servlet to worker1
 940   JkMount /servlet/* worker1
 941   # do not send requests ending with .gif to worker1
 942   JkUnMount /servlet/*.gif worker1
 943 </source>
 944 <p>
 945 JkUnMount takes precedence over JkMount directives, meaning that the JK
 946 will first try to mount and then checks, if there is an exclusion defined by a
 947 JkUnMount. A JkUnMount overrides a JkMount only, if the worker names in the
 948 JkMount and in the JkUnMount are the same.
 949 </p>
 950 <p>
 951 The following example will block all .gif files although there is a JkMount for them:
 952 </p>
 953 <source>
 954   # do not send requests ending with .gif to worker1
 955   JkUnMount /*.gif worker1
 956   # The .gif files will not be mounted cause JkUnMount takes
 957   # precedence over JkMount directive
 958   JkMount /servlet/*.gif worker1
 959 </source>
 960 <p>
 961 Starting with version 1.2.26 of JK you can apply a JkUnMount to any worker,
 962 by using the star character '*' as the worker name in the JkUnMount.
 963 More complex patterns in JkUnMount worker names are not allowed.
 964 </p>
 965 <source>
 966   # Mapping the webapps myapp1 and myapp2:
 967   /myapp1/*=worker1
 968   /myapp2/*=worker2
 969   # Exclude the all subdirectories static for all workers:
 970   !/*/static/*=*
 971   # Exclude some suffixes for all workers:
 972   !*.html=*
 973 </source>
 974 <p>
 975 <b>JkAutoAlias</b> directive automatically <b>Alias</b> webapp context directories into
 976 the Apache document space. It enables Apache to serve a static context while Tomcat
 977 serving dynamic context. This directive is used for convenience so that you don't
 978 have to put an apache Alias directive for each application directory inside Tomcat's
 979 webapp directory. For security reasons is is strongly recommended that JkMount
 980 is used to pass all requests to Tomcat by default and JkUnMount is used to
 981 explicitly exclude static content to be served by httpd. It should also be noted
 982 that content served by httpd will bypass any security constraints defined in the
 983 application's web.xml.
 984 </p>
 985 <source>
 986   # enter the full path to the tomcat webapps directory
 987   JkAutoAlias /opt/tomtact/webapps
 988 </source>
 989 <p>The following example shows how to serve a dynamic context by
 990 Tomcat and static using Apache. The webapps directory has to
 991 be accessible by apache.</p>
 992
 993 <source>
 994   # enter the full path to the tomcat webapps directory
 995   JkAutoAlias /opt/tomtact/webapps
 996
 997   # Mount 'servlets-examples' directory. It's physical location
 998   # is assumed to be in the /opt/tomtact/webapps/servlets-examples
 999   # ajp13w is a worker defined in the workers.properties
1000   JkMount /servlets-examples/* ajp13w
1001
1002   # Unmount desired static content from servlets-examples webapp.
1003   # This content will be served by the httpd directly.
1004   JkUnMount /servlets-examples/*.gif ajp13w
1005   JkUnMount /servlets-examples/*.jpg ajp13w
1006 </source>
1007 <p>Note that you can have a single JkAutoAlias directive per virtual
1008 host inside your httpd.conf
1009 </p>
1010 <p>
1011 <b>JkWorkerProperty</b> is a new directive available from JK 1.2.7
1012 version. It is a convenient method for setting directives that are
1013 usually set inside <b>workers.propeties</b> file. The parameter for
1014 that directive is raw line from workers.properties file.
1015 </p>
1016 <source>
1017   # Just like workers.properties but exact line is prefixed
1018   # with JkWorkerProperty
1019
1020   # Minimal jk configuration
1021   JkWorkerProperty worker.list=ajp13w
1022   JkWorkerProperty worker.ajp13w.type=ajp13
1023   JkWorkerProperty worker.ajp13w.host=localhost
1024   JkWorkerProperty worker.ajp13w.port=8009
1025 </source>
1026 <p>
1027 <b>JkMountFile</b> is a new directive available from JK 1.2.9
1028 version. It is used for dynamic updates of mount points at runtime.
1029 When the mount file is changed, JK will reload it's content.
1030 </p>
1031 <source>
1032   # Load mount points
1033
1034   JkMountFile conf/uriworkermap.properties
1035 </source>
1036 <p>If the mount point uri starts with an exclamation mark '!'
1037 it defines an exclusion in the same way JkUnMount does.
1038 If the mount point uri starts with minus sign '-'
1039 the mount point will only be disabled. A disabled mount can be reenabled
1040 by deleting the minus sign and waiting for the JkMountFile to reload.
1041 An exclusion can be disabled by prefixing it with a minus sign.
1042 </p>
1043 <source>
1044   # Sample uriworkermap.properties file
1045
1046   /servlets-examples/*=ajp13w
1047   # Do not map .jpeg files
1048   !/servlets-examples/*.jpeg=ajp13w
1049   # Make jsp examples initially disabled
1050   -/jsp-examples/*=ajp13w
1051 </source>
1052 <p>At run time you can change the content of this file. For example
1053 removing minus signs will enable the previously disabled uri mappings.
1054 You can add any number of new entries at runtime that reflects the newly deployed
1055 applications. Apache will reload the file and update the mount
1056 points within 60 second interval.
1057 </p>
1058 <p>
1059 There is no way to delete entries by dynamic reloading, but you can disable or
1060 exclude mappings.
1061 <br/>
1062 <br/>
1063 </p>
1064
1065 </subsection>
1066
1067 <subsection name="Using SetHandler and Environment Variables">
1068 <p>
1069 Alternatively to the mod_jk specific directives, you can also use
1070 SetHandler and environment variables to control, which requests
1071 are being forwarded via which worker. This gives you more flexibility,
1072 but the results might be more difficult to understand. If you mix both
1073 ways of defining the forwards, in general to mod_jk directives will win.
1074 </p>
1075 <p>
1076 <b>SetHandler jakarta-servlet</b> forces requests to be handled by mod_jk.
1077 If you neither specify any workers via JkMount and the related directives,
1078 not via the environment variable described below,
1079 the first worker in the list of all worker will be chosen. You can use SetHandler
1080 for example in Location blocks or with Apache 2.2 also in RewriteRule.
1081 </p>
1082 <p>
1083 In order to control the worker using <b>SetEnvIf</b> or <b>RewriteRule</b>
1084 for more complex rules, you can set the environment variable <b>JK_WORKER_NAME</b>
1085 to the name of your chosen target worker. This enables you to decide on
1086 the chosen worker in a more flexible way, including dependencies on cookie values.
1087 This feature has been added in version 1.2.19 of mod_jk.
1088 </p>
1089 <p>
1090 In order to use another variable than <b>JK_WORKER_NAME</b>, you can set the name
1091 of this variable via the <b>JkWorkerIndicator</b> directive.
1092 </p>
1093 <p>
1094 You can also define exclusions from mod_jk forwards by setting the environment
1095 variable <b>no-jk</b>.
1096 </p>
1097 <source>
1098   # Automatically map all encoded urls
1099   &lt;Location *;jsessionid=&gt;
1100     SetHandler jakarta-servlet
1101     SetEnv JK_WORKER_NAME my_worker
1102   &lt;/Location&gt;
1103
1104   # Map all subdirs to workers via naming rule
1105   # and exclude static content.
1106   &lt;Location /apps/&gt;
1107     SetHandler jakarta-servlet
1108     SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1
1109     SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk
1110   &lt;/Location&gt;
1111 </source>
1112 <p>
1113 Finally, starting with version 1.2.27 you can use the environment variable
1114 <b>JK_REPLY_TIMEOUT</b> to dynamically set a reply timeout.
1115 </p>
1116 </subsection>
1117  </section>
1118 </body>
1119 </document>