diff options
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml')
| -rw-r--r-- | rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml | 1119 |
1 files changed, 0 insertions, 1119 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml deleted file mode 100644 index e4ad0360..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml +++ /dev/null @@ -1,1119 +0,0 @@ -<?xml version="1.0"?> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You under the Apache License, Version 2.0 - (the "License"); you may not use this file except in compliance with - the License. You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. ---> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="apache.html"> - - &project; - - <properties> - <author email="mturk@apache.org">Mladen Turk</author> - <title>Configuring Apache</title> - </properties> - -<body> - -<section name="Configuration Directives"> -<p> -Most of the directives are allowed once in the global part of the Apache httpd -configuration and once in every <VirtualHost> elements. Exceptions from this rule are -explicitly listed in the table below. -</p> -<p> -Most values are inherited from the main server to the virtual hosts. -Since version 1.2.20 they can be overwritten in the virtual hosts. -Exceptions from this rule are again explicitly listed in the table below. -See especially JkMountCopy. -</p> -<warn> -Warning: If Apache httpd and Tomcat are configured to serve content from -the same filing system location then care must be taken to ensure that httpd is -not able to serve inappropriate content such as the contents of the WEB-INF -directory or JSP source code. -</warn> -<p> -This could occur if the httpd DocumentRoot -overlaps with a Tomcat Host's appBase or the docBase of any Context. It could -also occur when using the httpd Alias directive with a Tomcat Host's appBase or -the docBase of any Context. -</p> -<p> -Here are the all directives supported by Apache: -</p> -<attributes name="Directive"> -<attribute name="JkWorkersFile" required="false"><p> -The name of a worker file for the Tomcat servlet containers. -<br/> -This directive is only allowed once. It must be put into -the global part of the configuration. -<br/> -If you don't use the JkWorkerProperty directives, then you must -define your workers with a valid JkWorkersFile. There is no default -value. -</p></attribute> -<attribute name="JkWorkerProperty" required="false"><p> -Enables setting worker properties inside Apache configuration file. -The syntax is the same as in the JkWorkersFile (usually workers.properties). -Simply prefix each line with "JkWorkerProperty" to put it directly into -the Apache httpd config files. -<br/> -This directive is allowed multiple times. -It must be put into the global part of the configuration. -<br/> -If you don't use the JkWorkerProperty directives, then you must -define your workers with a valid JkWorkersFile. There is no default -value. -<br/> -This directive is available in jk1.2.7 version and later. -</p></attribute> -<attribute name="JkShmFile" required="false"><p> -Shared memory file name. Used only on unix platforms. -The shm file is used by balancer and status workers. -<br/> -This directive is only allowed once. It must be put into -the global part of the configuration. -<br/> -The default value is logs/jk-runtime-status. -It is highly recommended that the shm file be placed on a local -drive and not an NFS share. -</p> -<p> -The shared memory contains configuration and runtime information for load balancer -workers and their members. It is need in order that all apache children -<ul> -<li>share the same status information for load balancing members (OK, ERROR, ...),</li> -<li>share the information about load taken by the individual workers,</li> -<li>share the information for the parts of the configuration, which are changeable -during runtime by status workers.</li> -</ul> -</p> -</attribute> -<attribute name="JkShmSize" required="false"><p> -Size of the shared memory file name. -<br/> -This directive is only allowed once. It must be put into -the global part of the configuration. -<br/> -The default value depends on the platform. It is usually less than 64KB. -</p></attribute> -<p>Starting with version 1.2.27 the size of the shared memory is determined -automatically, even for large numbers of workers. This attribute is not -needed any longer.</p> -<attribute name="JkMountFile" required="false"><p> -File containing multiple mappings from a context to a Tomcat worker. -It is usually called uriworkermap.properties. -<br/> -For inheritance rules, see: JkMountCopy. -<br/> -There is no default value. -</p></attribute> -<attribute name="JkMountFileReload" required="false"><p> -This directive configures the reload check interval in seconds. -The JkMountFile is checked periodically for changes. -A changed file gets reloaded automatically. If you set -this directive to "0", reload checking is turned off. -<br/> -The default value is 60 seconds. -<br/> -This directive has been added in version 1.2.20 of mod_jk. -</p></attribute> -<attribute name="JkMount" required="false"><p> -A mount point from a context to a Tomcat worker. -<br/> -This directive is allowed multiple times. -It is allowed in the global configuration and in VirtualHost. -You can also use it inside Location with a different syntax. -Inside Location, one omits the first argument (path), -which gets inherited from the Location. -<br/> -By default JkMount entries are not inherited from the global -server to other VirtualHosts or between VirtualHosts. -For the complete inheritance rules, see: JkMountCopy. -</p></attribute> -<attribute name="JkUnMount" required="false"><p> -An exclusion mount point from a context to a Tomcat worker. -All exclusion mounts are checked after mapping a request -to a tomcat worker. If the request maps also to an exclusion, -it will not be forwarded to tomcat, and instead be served locally. -<br/> -This directive is allowed multiple times. -It is allowed in the global configuration and in VirtualHost. -You can also use it inside Location with a different syntax. -Inside Location, one omits the first argument (path), -which gets inherited from the Location. -For inheritance rules, see: JkMountCopy. -<br/> -This directive is available in jk1.2.7 version and later. -</p></attribute> -<attribute name="JkAutoAlias" required="false"><p> -Automatically Alias webapp context directories into the Apache -document space. -<br/> -Care should be taken to ensure that only static content is served via httpd as a -result of using this directive. Any static content served by httpd will bypass any -security constraints defined in the application's web.xml. -<br/> -For inheritance rules, see: JkMountCopy. -<br/> -There is no default value. -</p></attribute> -<attribute name="JkMountCopy" required="false"><p> -If this directive is set to "On" in some virtual server, -the mounts from the global server will be copied to this -virtual server, more precisely all mounts defined by JkMount -or JkUnMount. The Mounts defined by JkMountFile and JkAutoAlias -will only be inherited, if the VirtualHost does not define -it's own JkMountFile or JkAutoAlias. -<br/> -If you want all vhost to inherit mounts from the main server, -you can set JkMountCopy to 'All' in the main server. -<br/> -This directive is only allowed inside VirtualHost (with value "On") -and in the global server (with value "All"). -<br/> -The default is Off, so no mounts will be inherited from the global -server to any VirtualHost. -<br/> -Starting with version 1.2.26 you can also set it to "All" in the -global virtual server. This will switch the default to On. -</p></attribute> -<attribute name="JkWorkerIndicator" required="false"><p> -Name of the Apache environment variable that can be used to set worker names -in combination with SetHandler jakarta-servlet. -<br/> -This directive is only allowed once per virtual server. -It is allowed in the global configuration and in VirtualHost. -<br/> -The default value is JK_WORKER_NAME. -</p></attribute> -<attribute name="JkWatchdogInterval" required="false"><p> -This directive configures the watchdog thread interval in seconds. -The workers are maintained periodically by a background thread -running periodically every watchdog_interval seconds. Worker maintenance -checks for idle connections, corrects load status and is able -to detect backend health status. -<br/> -The maintenance only happens, if since the last maintenance at -least <a href="workers.html"><code>worker.maintain</code></a> -seconds have passed. So setting the JkWatchdogInterval -much smaller than <code>worker.maintain</code> is not useful. -<br/> -The default value is 0 seconds, meaning the watchdog thread -will not be created, and the maintenance is done in combination -with normal requests instead. -<br/> -This directive is only allowed once. It must be put into -the global part of the configuration. -<br/> -This directive has been added in version 1.2.27 of mod_jk. -It is available only for httpd 2.x and above using APR libraries -including thread support. -</p></attribute> -<attribute name="JkLogFile" required="false"><p> -Full or server relative path to the Tomcat Connector module log file. -It will also work with pipe, by using a value of the form "| ...". -<br/> -The default value is logs/mod_jk.log. -<br/> -Pipes are supported for Apache 1.3 only since version 1.2.16. -The default value exists only since version 1.2.20. -</p></attribute> -<attribute name="JkLogLevel" required="false"><p> -The Tomcat Connector module log level, can be debug, info, warn -error or trace. -<br/> -The default value is info. -</p></attribute> -<attribute name="JkLogStampFormat" required="false"><p> -The Tomcat Connector module <b>date</b> log format, using an -extended strftime syntax. -This format will be used for the time stamps in the JkLogFile. -The maximum length of the format is 63 characters. -<br/> -Starting with version 1.2.24 of mod_jk you can also use %Q -for adding milliseconds to the log and %q for microseconds. -These conversion specifiers are an extension to strftime. -They will only work on platforms with a gettimeofday() function. -You can use %Q and %q only once in the pattern and also not both -together in the same pattern. -<br/> -The default value is "[%a %b %d %H:%M:%S %Y] " and beginning -with version 1.2.24 on platforms with a gettimeofday() -function it is "[%a %b %d %H:%M:%S.%Q %Y] ". -</p></attribute> -<attribute name="JkRequestLogFormat" required="false"><p> -Request log format string. See detailed description below. -<br/> -There is no default value. Without defining a value, the request logging -is turned off. -</p></attribute> -<attribute name="JkExtractSSL" required="false"><p> -Turns on SSL processing and information gathering by mod_jk -<br/> -The default value is On. -<br/> -In order to make SSL data available for mod_jk in Apache, you need to -set <code>SSLOptions +StdEnvVars</code>. For the certificate information you also need -to add <code>SSLOptions +ExportCertData</code>. -</p> -<p> - Specifically, mod_jk will export the following environment variables from - Apache httpd to Tomcat under these request attributes as per the - Servlet Specification 3.0, section 3.8: -</p> -<table> - <tr><th>Env Var</th><th>Request Attribute Name</th><th>Type</th><th>Example</th></tr> - <tr> - <td>SSL_CIPHER<br/>(or <code>JkKEYSIZEIndicator</code>)</td> - <td>javax.servlet.request.cipher_suite</td> - <td>java.lang.String</td> - <td>DHE-RSA-AES256-SHA</td> - </tr> - <tr> - <td>SSL_CIPHER_USEKEYSIZE<br/>(or <code>JkKEYSIZEIndicator</code>)</td> - <td>javax.servlet.request.key_size</td> - <td>java.lang.Integer</td> - <td>256</td> - </tr> - <tr> - <td>SSL_SESSION_ID<br/>(or <code>JkSESSIONIndicator</code>)</td> - <td>javax.servlet.request.ssl_session</td> - <td>java.lang.String</td> - <td>905...32E (a hex string)</td> - </tr> - <tr> - <td>SSL_CLIENT_CERT_CHAIN_<i>n</i><br/>(or <code>JkCERTCHAINPrefix</code><i>n</i>)</td> - <td>javax.servlet.request.X509Certificate</td> - <td>java.security.X509Certificate[]</td> - <td>(A chain of certs in ascending order of trust, the first one being - ths client's certificate, the second being the signer of that - certificate, and so on)</td> - </tr> -</table> -<p> - For all other SSL-related variables, use <code>JkEnvVar</code> for each - variable you want. Please note that, like <code>JkEnvVar</code>, these - variables are available from the request <i><b>attributes</b></i>, not as - environment variables or as request headers. -</p> -</attribute> -<attribute name="JkHTTPSIndicator" required="false"><p> -Name of the Apache environment variable that contains SSL indication. -<br/> -The default value is "HTTPS". -</p></attribute> -<attribute name="JkCERTSIndicator" required="false"><p> -Name of the Apache environment variable that contains SSL client certificates. -<br/> -The default value is "SSL_CLIENT_CERT". -</p></attribute> -<attribute name="JkCIPHERIndicator" required="false"><p> -Name of the Apache environment variable that contains SSL client cipher. -<br/> -The default value is "SSL_CIPHER". -</p></attribute> -<attribute name="JkCERTCHAINPrefix" required="false"><p> -Name of the Apache environment (prefix) that contains SSL client chain certificates. -<br/> -The default value is "SSL_CLIENT_CERT_CHAIN_". -</p></attribute> -<attribute name="JkSESSIONIndicator" required="false"><p> -Name of the Apache environment variable that contains SSL session. -<br/> -The default value is "SSL_SESSION_ID". -</p></attribute> -<attribute name="JkKEYSIZEIndicator" required="false"><p> -Name of the Apache environment variable that contains SSL key size in use. -<br/> -The default value is "SSL_CIPHER_USEKEYSIZE". -</p></attribute> -<attribute name="JkLocalNameIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded local name. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_LOCAL_NAME". -<br/> -This directive has been added in version 1.2.28 of mod_jk. -</p></attribute> -<attribute name="JkLocalPortIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded local port. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_LOCAL_PORT". -<br/> -This directive has been added in version 1.2.28 of mod_jk. -</p></attribute> -<attribute name="JkRemoteHostIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded remote (client) host name. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_REMOTE_HOST". -<br/> -This directive has been added in version 1.2.28 of mod_jk. -</p></attribute> -<attribute name="JkRemoteAddrIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded remote (client) IP address. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_REMOTE_ADDR". -<br/> -This directive has been added in version 1.2.28 of mod_jk. -</p></attribute> -<attribute name="JkRemotePortIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded remote (client) IP address. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_REMOTE_PORT". -<br/> -This directive has been added in version 1.2.32 of mod_jk. -</p></attribute> -<attribute name="JkRemoteUserIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded user name. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_REMOTE_USER". -<br/> -This directive has been added in version 1.2.28 of mod_jk. -</p></attribute> -<attribute name="JkAuthTypeIndicator" required="false"><p> -Name of the Apache environment variable which can be used to overwrite -the forwarded authentication type. -Use this only if you need to adjust the data (see the -<a href="../generic_howto/proxy.html">proxy</a> documentation). -<br/> -The default value is "JK_AUTH_TYPE". -<br/> -This directive has been added in version 1.2.28 of mod_jk. -</p></attribute> -<attribute name="JkOptions" required="false"><p> -Set one of more options to configure the mod_jk module. See below for -details about this directive. -<br/> -This directive can be used multiple times per virtual server. -<br/> -The default value is "ForwardURIProxy" since version 1.2.24. -It was "ForwardURICompatUnparsed" in version 1.2.23 and -"ForwardURICompat" until version 1.2.22. -</p></attribute> -<attribute name="JkEnvVar" required="false"><p> -Adds a name and an optional default value of environment variable -that should be sent to servlet-engine as a request attribute. -If the default value is not given explicitly, the variable -will only be send, if it is set during runtime. -<br/> -The default is empty, so no additional variables will be sent. -<br/> -This directive can be used multiple times per virtual server. -The settings will be merged between the global server and any -virtual server. -<br/> -You can retrieve the variables on Tomcat as request attributes -via request.getAttribute(attributeName). Note that the variables -send via JkEnvVar will not be listed in request.getAttributeNames(). -<br/> -Empty default values are supported since version 1.2.20. -Not sending variables with empty defaults and empty runtime value -has been introduced in version 1.2.21. -</p></attribute> -<attribute name="JkStripSession" required="false"><p> -If this directive is set to On in some virtual server, -the session IDs <code>;jsessionid=...</code> will be -removed for non matched URLs. -<br/> -This directive is only allowed inside VirtualHost. -<br/> -The default is Off. -<br/> -This directive has been introduced in version 1.2.21. -<br/>With version 1.2.27 and later this directive can have optional -session ID identifier. If not specified it defaults to -<code>;jsessionid</code>. -</p> -</attribute> - -</attributes> -</section> - -<section name="Configuration Directives Types"> -<p> -We'll discuss here the mod_jk directive types. -</p> - -<subsection name="Define workers"> -<p> -<b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions. -Take a look at <a href="workers.html">Workers documentation</a> for detailed description. - -<source> - JkWorkersFile /etc/httpd/conf/workers.properties -</source> - -<br/> -<br/> -</p> - -</subsection> - -<subsection name="Logging"> -<p> -<b>JkLogFile</b> specify the location where mod_jk is going to place its log file. -</p> - -<source> - JkLogFile /var/log/httpd/mod_jk.log -</source> - -<p> -Since JK 1.2.3 for Apache 2.x and JK 1.2.16 for Apache 1.3 this can also -be used for piped logging: -</p> - -<source> - JkLogFile "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400" -</source> - -<p> -<b>JkLogLevel</b> -set the log level between : -</p> - -<ul> -<li> -<b>info</b> log will contain standard mod_jk activity (default). -</li> -<li> -<b>warn</b> log will contain non fatal error reports. -</li> -<li> -<b>error</b> log will contain also error reports. -</li> -<li> -<b>debug</b> log will contain all information on mod_jk activity -</li> -<li> -<b>trace</b> log will contain all tracing information on mod_jk activity -</li> -</ul> - -<source> - JkLogLevel info -</source> - -<p> -<code>info</code> should be your default selection for normal operations. -<br/> -<br/> -</p> - -<p> -<b>JkLogStampFormat</b> will configure the date/time format found on mod_jk log file. -Using the strftime() format string it's set by<br /> -default to <b>"[%a %b %d %H:%M:%S %Y]"</b> -</p> - -<source> - JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " -</source> - -<p> -<br/> -<br/> -</p> - -<p> -<b>JkRequestLogFormat</b> will configure the format of mod_jk individual request logging. -Request logging is configured and enabled on a per virtual host basis. -To enable request logging for a virtual host just add a JkRequestLogFormat config. -The syntax of the format string is similar to the Apache LogFormat command, -here is a list of the available request log format options: -</p> - -<p> -<attributes name="Options"> - <attribute name="%b" required="false">Bytes sent, excluding HTTP headers (CLF format)</attribute> - <attribute name="%B" required="false">Bytes sent, excluding HTTP headers</attribute> - <attribute name="%H" required="false">The request protocol</attribute> - <attribute name="%m" required="false">The request method</attribute> - <attribute name="%p" required="false">The canonical Port of the server serving the request</attribute> - <attribute name="%q" required="false">The query string (prepended with a ? if a query string exists, otherwise an empty string)</attribute> - <attribute name="%r" required="false">First line of request</attribute> - <attribute name="%s" required="false">Request HTTP status code</attribute> - <attribute name="%T" required="false">Request duration, elapsed time to handle request in seconds '.' micro seconds</attribute> - <attribute name="%U" required="false">The URL path requested, not including any query string.</attribute> - <attribute name="%v" required="false">The canonical ServerName of the server serving the request</attribute> - <attribute name="%V" required="false">The server name according to the UseCanonicalName setting</attribute> - <attribute name="%w" required="false">Tomcat worker name</attribute> - <attribute name="%R" required="false">Real worker name</attribute> -</attributes> - -<source> - JkRequestLogFormat "%w %V %T" -</source> - -<br/> -<br/> -</p> - -<p> -You can also log mod_jk information using the Apache standard module <b>mod_log_config</b>. -The module sets several notes in the Apache httpd notes table. -Most of them are are only useful in combination with a load balancer worker. -</p> - -<p> -<attributes name="Note"> - <attribute name="JK_WORKER_NAME" required="false">Name of the worker selected by the URI mapping</attribute> - <attribute name="JK_WORKER_TYPE" required="false">Type of the worker selected by the URI mapping</attribute> - <attribute name="JK_WORKER_ROUTE" required="false">Actual worker name selected by the URI mapping (usually a member of the load balancer).<br/> - Before version 1.2.26 only available if JkRequestLogFormat is set.</attribute> - <attribute name="JK_REQUEST_DURATION" required="false">Request duration in seconds and microseconds.<br/> - Before version 1.2.26 only available if JkRequestLogFormat is set.</attribute> - <attribute name="JK_LB_FIRST_NAME" required="false">Load-Balancer: Name of the first worker tried</attribute> - <attribute name="JK_LB_FIRST_TYPE" required="false">Load-Balancer: Type of the first worker tried</attribute> - <attribute name="JK_LB_FIRST_ACCESSED" required="false">Load-Balancer: Access count for the first worker tried</attribute> - <attribute name="JK_LB_FIRST_READ" required="false">Load-Balancer: Bytes read for the first worker tried</attribute> - <attribute name="JK_LB_FIRST_TRANSFERRED" required="false">Load-Balancer: Bytes transferred for the first worker tried</attribute> - <attribute name="JK_LB_FIRST_ERRORS" required="false">Load-Balancer: Error count for the first worker tried</attribute> - <attribute name="JK_LB_FIRST_BUSY" required="false">Load-Balancer: Busy count for the first worker tried</attribute> - <attribute name="JK_LB_FIRST_ACTIVATION" required="false">Load-Balancer: Activation state for the first worker tried</attribute> - <attribute name="JK_LB_FIRST_STATE" required="false">Load-Balancer: Error state for the first worker tried</attribute> - <attribute name="JK_LB_LAST_NAME" required="false">Load-Balancer: Name of the last worker tried</attribute> - <attribute name="JK_LB_LAST_TYPE" required="false">Load-Balancer: Type of the last worker tried</attribute> - <attribute name="JK_LB_LAST_ACCESSED" required="false">Load-Balancer: Access count for the last worker tried</attribute> - <attribute name="JK_LB_LAST_READ" required="false">Load-Balancer: Bytes read for the last worker tried</attribute> - <attribute name="JK_LB_LAST_TRANSFERRED" required="false">Load-Balancer: Bytes transferred for the last worker tried</attribute> - <attribute name="JK_LB_LAST_ERRORS" required="false">Load-Balancer: Error count for the last worker tried</attribute> - <attribute name="JK_LB_LAST_BUSY" required="false">Load-Balancer: Busy count for the last worker tried</attribute> - <attribute name="JK_LB_LAST_ACTIVATION" required="false">Load-Balancer: Activation state for the last worker tried</attribute> - <attribute name="JK_LB_LAST_STATE" required="false">Load-Balancer: Error state for the last worker tried</attribute> -</attributes> - -<source> - LogFormat "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \ - %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log - CustomLog logs/access_log mod_jk_log -</source> - -<br/> -<br/> -</p> - -</subsection> - -<subsection name="Forwarding"> -<p> -The directive JkOptions allow you to set many forwarding options which will enable (+) -or disable (-) following option. Without any leading signs, options will be enabled. -<br/> -<br/> -</p> - -<p> -The four following options <b>+ForwardURIxxx</b> are mutually exclusive. -Exactly one of them is required, a negative sign prefix is not allowed with them. -The default value is "ForwardURIProxy" since version 1.2.24. -It was "ForwardURICompatUnparsed" in version 1.2.23 and -"ForwardURICompat" until version 1.2.22. -You can turn the default off by switching on one of the other two options. -You should leave this at it's default value, unless you have a very good -reason to change it. -<br/> -<br/> -</p> - -<p> -All options are inherited from the global server to virtual hosts. -Options that support enabling (plus options) and disabling (minus options), -are inherited in the following way: -<br/> -<br/> -options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost) -<br/> -<br/> -</p> - -<p> -Using JkOptions <b>ForwardURIProxy</b>, the forwarded URI -will be partially reencoded after processing inside Apache httpd and -before forwarding to Tomcat. This will be compatible with local -URL manipulation by mod_rewrite and with URL encoded session ids. - -<source> - JkOptions +ForwardURIProxy -</source> - -<br/> -<br/> -</p> - -<p> -Using JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI -will be unparsed. It's spec compliant and secure. -It will always forward the original request URI, so rewriting -URIs with mod_rewrite and then forwarding the rewritten URI -will not work. - -<source> - JkOptions +ForwardURICompatUnparsed -</source> - -<br/> -<br/> -</p> - -<p> -Using JkOptions <b>ForwardURICompat</b>, the forwarded URI will -be decoded by Apache httpd. Encoded characters will be decoded and -explicit path components like ".." will already be resolved. -This is less spec compliant and is <b>not safe</b> if you are using -prefix JkMount. This option will allow to rewrite URIs with -mod_rewrite before forwarding. - -<source> - JkOptions +ForwardURICompat -</source> - -<br/> -<br/> -</p> - -<p> -Using JkOptions <b>ForwardURIEscaped</b>, the forwarded URI will -be the encoded form of the URI used by ForwardURICompat. -Explicit path components like ".." will already be resolved. -This will not work in combination with URL encoded session IDs, -but it will allow to rewrite URIs with mod_rewrite before forwarding. - -<source> - JkOptions +ForwardURIEscaped -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>RejectUnsafeURI</b> will block all -URLs, which contain percent signs '%' or backslashes '\' -after decoding. -<br/> -<br/> -</p> -<p> -Most web apps do not use such URLs. Using the option RejectUnsafeURI, you -can block several well known URL encoding attacks. By default, this option -is not set. -</p> -<p> -You can also realise such a check with mod_rewrite, which is more powerful -but also slightly more complicated. - -<source> - JkOptions +RejectUnsafeURI -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b> -directive of Apache web server. As such mod_dir should be available to Apache, -statically or dynamically (DSO) -<br/> -<br/> -</p> - -<p> -When DirectoryIndex is configured, Apache will create sub-requests for -each of the local-url's specified in the directive, to determine if there is a -local file that matches (this is done by stat-ing the file). -</p> - -<p> -If ForwardDirectories is set to false (default) and Apache doesn't find any -files that match, Apache will serve the content of the directory (if directive -Options specifies Indexes for that directory) or a <code>403 Forbidden</code> response (if -directive Options doesn't specify Indexes for that directory). -</p> - -<p> -If ForwardDirectories is set to true and Apache doesn't find any files that -match, the request will be forwarded to Tomcat for resolution. This is used in -cases when Apache cannot see the index files on the file system for various -reasons: Tomcat is running on a different machine, the JSP file has been -precompiled etc. -</p> - -<p>Note that locally visible files will take precedence over the -ones visible only to Tomcat (i.e. if Apache can see the file, that's the one -that's going to get served). This is important if there is more then one type of -file that Tomcat normally serves - for instance Velocity pages and JSP pages. - -<source> - JkOptions +ForwardDirectories -</source> -<br/> -<br/> -</p> - -<p> -JkOptions <b>ForwardLocalAddress</b>, you ask mod_jk to send the local address, -of the Apache web server instead remote client address. This can be used by -Tomcat remote address valve for allowing connections only from registered Apache -web servers. - -<source> - JkOptions +ForwardLocalAddress -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>FlushPackets</b>, you ask mod_jk to flush Apache's connection -buffer after each AJP packet chunk received from Tomcat. This option can have -a strong performance penalty for Apache and Tomcat as writes are performed -more often than would normally be required (ie: at the end of each -response). - -<source> - JkOptions +FlushPackets -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection -buffer after the response headers have been received from Tomcat. - -<source> - JkOptions +FlushHeader -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>DisableReuse</b>, you ask mod_jk to close connections immediately -after their use. Normally mod_jk uses persistent connections and pools idle -connections to reuse them, when new requests have to be sent to Tomcat. -</p> - -<p> -Using this option will have a strong performance penalty for Apache and Tomcat. -Use this only as a last resort in case of unfixable network problems. -If a firewall between Apache and Tomcat silently kills idle connections, -try to use the worker attribute socket_keepalive in combination with an appropriate -TCP keepalive value in your OS. - -<source> - JkOptions +DisableReuse -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>ForwardKeySize</b>, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as -required by Servlet API 2.3. -This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default). - -<source> - JkOptions +ForwardKeySize -</source> - -<br/> -<br/> -</p> - -<p> -JkOptions <b>ForwardSSLCertChain</b>, you ask mod_jk, when using ajp13, -to forward SSL certificate chain (off by default). -Mod_jk only passes the <code>SSL_CLIENT_CERT</code> to the AJP connector. This is not a -problem with self-signed certificates or certificates directly signed by the -root CA certificate. However, there's a large number of certificates signed by -an intermediate CA certificate, where this is a significant problem: A servlet -will not have the possibility to validate the client certificate on its own. The -bug would be fixed by passing on the <code>SSL_CLIENT_CERT_CHAIN</code> to Tomcat via the AJP connector. -<br/> -This directive exists only since version 1.2.22. -<source> - JkOptions +ForwardSSLCertChain -</source> - -<br/> -<br/> -</p> - -<p> -The directive <b>JkEnvVar</b> allows you to forward environment variables -from Apache server to Tomcat engine. -You can add a default value as a second parameter to the directive. -If the default value is not given explicitly, the variable -will only be send, if it is set during runtime. -<br/> -The variables can be retrieved on the Tomcat side as request attributes -via request.getAttribute(attributeName). -Note that the variables send via JkEnvVar will not be listed -in request.getAttributeNames(). -<br/> -<br/> -The variables are inherited from the global server to virtual hosts. - -<source> - JkEnvVar SSL_CLIENT_V_START undefined -</source> -<br/> -<br/> -</p> - -</subsection> - -<subsection name="Assigning URLs to Tomcat"> -<p> -If you have created a custom or local version of mod_jk.conf-local as noted above, -you can change settings such as the workers or URL prefix. -</p> -<p> -<b>JkMount</b> directive assign specific URLs to Tomcat. -In general the structure of a JkMount directive is: -</p> - -<source> - JkMount [URL prefix] [Worker name] -</source> - -<source> - # send all requests ending in .jsp to worker1 - JkMount /*.jsp worker1 - # send all requests ending /servlet to worker1 - JkMount /*/servlet/ worker1 - # send all requests jsp requests to files located in /otherworker will go worker2 - JkMount /otherworker/*.jsp worker2 -</source> - -<p> -You can use the JkMount directive at the top level or inside <VirtualHost> -sections of your httpd.conf file. -</p> -<p><b>JkUnMount</b> directive acts as an opposite to JkMount and blocks access -to a particular URL. The purpose is to be able to filter out the particular content -types from mounted context. The following example mounts /servlet/* -context, but all .gif files that belongs to that context are not served. -</p> -<source> - # send all requests ending with /servlet to worker1 - JkMount /servlet/* worker1 - # do not send requests ending with .gif to worker1 - JkUnMount /servlet/*.gif worker1 -</source> -<p> -JkUnMount takes precedence over JkMount directives, meaning that the JK -will first try to mount and then checks, if there is an exclusion defined by a -JkUnMount. A JkUnMount overrides a JkMount only, if the worker names in the -JkMount and in the JkUnMount are the same. -</p> -<p> -The following example will block all .gif files although there is a JkMount for them: -</p> -<source> - # do not send requests ending with .gif to worker1 - JkUnMount /*.gif worker1 - # The .gif files will not be mounted cause JkUnMount takes - # precedence over JkMount directive - JkMount /servlet/*.gif worker1 -</source> -<p> -Starting with version 1.2.26 of JK you can apply a JkUnMount to any worker, -by using the star character '*' as the worker name in the JkUnMount. -More complex patterns in JkUnMount worker names are not allowed. -</p> -<source> - # Mapping the webapps myapp1 and myapp2: - /myapp1/*=worker1 - /myapp2/*=worker2 - # Exclude the all subdirectories static for all workers: - !/*/static/*=* - # Exclude some suffixes for all workers: - !*.html=* -</source> -<p> -<b>JkAutoAlias</b> directive automatically <b>Alias</b> webapp context directories into -the Apache document space. It enables Apache to serve a static context while Tomcat -serving dynamic context. This directive is used for convenience so that you don't -have to put an apache Alias directive for each application directory inside Tomcat's -webapp directory. For security reasons is is strongly recommended that JkMount -is used to pass all requests to Tomcat by default and JkUnMount is used to -explicitly exclude static content to be served by httpd. It should also be noted -that content served by httpd will bypass any security constraints defined in the -application's web.xml. -</p> -<source> - # enter the full path to the tomcat webapps directory - JkAutoAlias /opt/tomtact/webapps -</source> -<p>The following example shows how to serve a dynamic context by -Tomcat and static using Apache. The webapps directory has to -be accessible by apache.</p> - -<source> - # enter the full path to the tomcat webapps directory - JkAutoAlias /opt/tomtact/webapps - - # Mount 'servlets-examples' directory. It's physical location - # is assumed to be in the /opt/tomtact/webapps/servlets-examples - # ajp13w is a worker defined in the workers.properties - JkMount /servlets-examples/* ajp13w - - # Unmount desired static content from servlets-examples webapp. - # This content will be served by the httpd directly. - JkUnMount /servlets-examples/*.gif ajp13w - JkUnMount /servlets-examples/*.jpg ajp13w -</source> -<p>Note that you can have a single JkAutoAlias directive per virtual -host inside your httpd.conf -</p> -<p> -<b>JkWorkerProperty</b> is a new directive available from JK 1.2.7 -version. It is a convenient method for setting directives that are -usually set inside <b>workers.propeties</b> file. The parameter for -that directive is raw line from workers.properties file. -</p> -<source> - # Just like workers.properties but exact line is prefixed - # with JkWorkerProperty - - # Minimal jk configuration - JkWorkerProperty worker.list=ajp13w - JkWorkerProperty worker.ajp13w.type=ajp13 - JkWorkerProperty worker.ajp13w.host=localhost - JkWorkerProperty worker.ajp13w.port=8009 -</source> -<p> -<b>JkMountFile</b> is a new directive available from JK 1.2.9 -version. It is used for dynamic updates of mount points at runtime. -When the mount file is changed, JK will reload it's content. -</p> -<source> - # Load mount points - - JkMountFile conf/uriworkermap.properties -</source> -<p>If the mount point uri starts with an exclamation mark '!' -it defines an exclusion in the same way JkUnMount does. -If the mount point uri starts with minus sign '-' -the mount point will only be disabled. A disabled mount can be reenabled -by deleting the minus sign and waiting for the JkMountFile to reload. -An exclusion can be disabled by prefixing it with a minus sign. -</p> -<source> - # Sample uriworkermap.properties file - - /servlets-examples/*=ajp13w - # Do not map .jpeg files - !/servlets-examples/*.jpeg=ajp13w - # Make jsp examples initially disabled - -/jsp-examples/*=ajp13w -</source> -<p>At run time you can change the content of this file. For example -removing minus signs will enable the previously disabled uri mappings. -You can add any number of new entries at runtime that reflects the newly deployed -applications. Apache will reload the file and update the mount -points within 60 second interval. -</p> -<p> -There is no way to delete entries by dynamic reloading, but you can disable or -exclude mappings. -<br/> -<br/> -</p> - -</subsection> - -<subsection name="Using SetHandler and Environment Variables"> -<p> -Alternatively to the mod_jk specific directives, you can also use -SetHandler and environment variables to control, which requests -are being forwarded via which worker. This gives you more flexibility, -but the results might be more difficult to understand. If you mix both -ways of defining the forwards, in general to mod_jk directives will win. -</p> -<p> -<b>SetHandler jakarta-servlet</b> forces requests to be handled by mod_jk. -If you neither specify any workers via JkMount and the related directives, -not via the environment variable described below, -the first worker in the list of all worker will be chosen. You can use SetHandler -for example in Location blocks or with Apache 2.2 also in RewriteRule. -</p> -<p> -In order to control the worker using <b>SetEnvIf</b> or <b>RewriteRule</b> -for more complex rules, you can set the environment variable <b>JK_WORKER_NAME</b> -to the name of your chosen target worker. This enables you to decide on -the chosen worker in a more flexible way, including dependencies on cookie values. -This feature has been added in version 1.2.19 of mod_jk. -</p> -<p> -In order to use another variable than <b>JK_WORKER_NAME</b>, you can set the name -of this variable via the <b>JkWorkerIndicator</b> directive. -</p> -<p> -You can also define exclusions from mod_jk forwards by setting the environment -variable <b>no-jk</b>. -</p> -<source> - # Automatically map all encoded urls - <Location *;jsessionid=> - SetHandler jakarta-servlet - SetEnv JK_WORKER_NAME my_worker - </Location> - - # Map all subdirs to workers via naming rule - # and exclude static content. - <Location /apps/> - SetHandler jakarta-servlet - SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1 - SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk - </Location> -</source> -<p> -Finally, starting with version 1.2.27 you can use the environment variable -<b>JK_REPLY_TIMEOUT</b> to dynamically set a reply timeout. -</p> -</subsection> - </section> -</body> -</document> |