From 9401f816dd0d9d550fe98a8507224bde51c4b847 Mon Sep 17 00:00:00 2001
From: hongbotian
+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.
+
+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.
+
+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.
+
+Here are the all directives supported by Apache:
+
+The name of a worker file for the Tomcat servlet containers.
+
+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.
+
+Shared memory file name. Used only on unix platforms.
+The shm file is used by balancer and status workers.
+
+The shared memory contains configuration and runtime information for load balancer
+workers and their members. It is need in order that all apache children
+
+This directive is only allowed once. It must be put into
+the global part of the configuration.
+
+If you don't use the JkWorkerProperty directives, then you must
+define your workers with a valid JkWorkersFile. There is no default
+value.
+
+This directive is allowed multiple times.
+It must be put into the global part of the configuration.
+
+If you don't use the JkWorkerProperty directives, then you must
+define your workers with a valid JkWorkersFile. There is no default
+value.
+
+This directive is available in jk1.2.7 version and later.
+
+This directive is only allowed once. It must be put into
+the global part of the configuration.
+
+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.
+
+
+
+Size of the shared memory file name.
+
+This directive is only allowed once. It must be put into
+the global part of the configuration.
+
+The default value depends on the platform. It is usually less than 64KB.
+
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.
+
+File containing multiple mappings from a context to a Tomcat worker.
+It is usually called uriworkermap.properties.
+
+For inheritance rules, see: JkMountCopy.
+
+There is no default value.
+
+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.
+
+The default value is 60 seconds.
+
+This directive has been added in version 1.2.20 of mod_jk.
+
+A mount point from a context to a Tomcat worker.
+
+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.
+
+By default JkMount entries are not inherited from the global
+server to other VirtualHosts or between VirtualHosts.
+For the complete inheritance rules, see: JkMountCopy.
+
+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.
+
+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.
+
+This directive is available in jk1.2.7 version and later.
+
+Automatically Alias webapp context directories into the Apache
+document space.
+
+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.
+
+For inheritance rules, see: JkMountCopy.
+
+There is no default value.
+
+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.
+
+If you want all vhost to inherit mounts from the main server,
+you can set JkMountCopy to 'All' in the main server.
+
+This directive is only allowed inside VirtualHost (with value "On")
+and in the global server (with value "All").
+
+The default is Off, so no mounts will be inherited from the global
+server to any VirtualHost.
+
+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.
+
+Name of the Apache environment variable that can be used to set worker names
+in combination with SetHandler jakarta-servlet.
+
+This directive is only allowed once per virtual server.
+It is allowed in the global configuration and in VirtualHost.
+
+The default value is JK_WORKER_NAME.
+
+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.
+
+The maintenance only happens, if since the last maintenance at
+least worker.maintain
+seconds have passed. So setting the JkWatchdogInterval
+much smaller than worker.maintain
is not useful.
+
+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.
+
+This directive is only allowed once. It must be put into
+the global part of the configuration.
+
+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.
+
+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 "| ...".
+
+The default value is logs/mod_jk.log.
+
+Pipes are supported for Apache 1.3 only since version 1.2.16.
+The default value exists only since version 1.2.20.
+
+The Tomcat Connector module log level, can be debug, info, warn
+error or trace.
+
+The default value is info.
+
+The Tomcat Connector module date 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.
+
+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.
+
+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] ".
+
+Request log format string. See detailed description below.
+
+There is no default value. Without defining a value, the request logging
+is turned off.
+
+Turns on SSL processing and information gathering by mod_jk
+
+The default value is On.
+
+In order to make SSL data available for mod_jk in Apache, you need to
+set SSLOptions +StdEnvVars
. For the certificate information you also need
+to add SSLOptions +ExportCertData
.
+
+ 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: +
+Env Var | Request Attribute Name | Type | Example |
---|---|---|---|
SSL_CIPHER (or JkKEYSIZEIndicator ) |
+ javax.servlet.request.cipher_suite | +java.lang.String | +DHE-RSA-AES256-SHA | +
SSL_CIPHER_USEKEYSIZE (or JkKEYSIZEIndicator ) |
+ javax.servlet.request.key_size | +java.lang.Integer | +256 | +
SSL_SESSION_ID (or JkSESSIONIndicator ) |
+ javax.servlet.request.ssl_session | +java.lang.String | +905...32E (a hex string) | +
SSL_CLIENT_CERT_CHAIN_n (or JkCERTCHAINPrefix n) |
+ javax.servlet.request.X509Certificate | +java.security.X509Certificate[] | +(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) | +
+ For all other SSL-related variables, use JkEnvVar
for each
+ variable you want. Please note that, like JkEnvVar
, these
+ variables are available from the request attributes, not as
+ environment variables or as request headers.
+
+Name of the Apache environment variable that contains SSL indication.
+
+The default value is "HTTPS".
+
+Name of the Apache environment variable that contains SSL client certificates.
+
+The default value is "SSL_CLIENT_CERT".
+
+Name of the Apache environment variable that contains SSL client cipher.
+
+The default value is "SSL_CIPHER".
+
+Name of the Apache environment (prefix) that contains SSL client chain certificates.
+
+The default value is "SSL_CLIENT_CERT_CHAIN_".
+
+Name of the Apache environment variable that contains SSL session.
+
+The default value is "SSL_SESSION_ID".
+
+Name of the Apache environment variable that contains SSL key size in use.
+
+The default value is "SSL_CIPHER_USEKEYSIZE".
+
+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
+proxy documentation).
+
+The default value is "JK_LOCAL_NAME".
+
+This directive has been added in version 1.2.28 of mod_jk.
+
+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
+proxy documentation).
+
+The default value is "JK_LOCAL_PORT".
+
+This directive has been added in version 1.2.28 of mod_jk.
+
+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
+proxy documentation).
+
+The default value is "JK_REMOTE_HOST".
+
+This directive has been added in version 1.2.28 of mod_jk.
+
+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
+proxy documentation).
+
+The default value is "JK_REMOTE_ADDR".
+
+This directive has been added in version 1.2.28 of mod_jk.
+
+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
+proxy documentation).
+
+The default value is "JK_REMOTE_PORT".
+
+This directive has been added in version 1.2.32 of mod_jk.
+
+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
+proxy documentation).
+
+The default value is "JK_REMOTE_USER".
+
+This directive has been added in version 1.2.28 of mod_jk.
+
+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
+proxy documentation).
+
+The default value is "JK_AUTH_TYPE".
+
+This directive has been added in version 1.2.28 of mod_jk.
+
+Set one of more options to configure the mod_jk module. See below for
+details about this directive.
+
+This directive can be used multiple times per virtual server.
+
+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.
+
+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.
+
+The default is empty, so no additional variables will be sent.
+
+This directive can be used multiple times per virtual server.
+The settings will be merged between the global server and any
+virtual server.
+
+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().
+
+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.
+
+If this directive is set to On in some virtual server,
+the session IDs ;jsessionid=...
will be
+removed for non matched URLs.
+
+This directive is only allowed inside VirtualHost.
+
+The default is Off.
+
+This directive has been introduced in version 1.2.21.
+
With version 1.2.27 and later this directive can have optional
+session ID identifier. If not specified it defaults to
+;jsessionid
.
+
+We'll discuss here the mod_jk directive types. +
+ +
+JkWorkersFile specify the location where mod_jk will find the workers definitions.
+Take a look at Workers documentation for detailed description.
+
+
+
+
+
+
+JkLogFile specify the location where mod_jk is going to place its log file. +
+ + + ++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: +
+ + + ++JkLogLevel +set the log level between : +
+ +
+info
should be your default selection for normal operations.
+
+
+
+JkLogStampFormat will configure the date/time format found on mod_jk log file.
+Using the strftime() format string it's set by
+default to "[%a %b %d %H:%M:%S %Y]"
+
+
+
+
+JkRequestLogFormat 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: +
+ +
+
+
+
+You can also log mod_jk information using the Apache standard module mod_log_config. +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. +
+ +
+
+ Before version 1.2.26 only available if JkRequestLogFormat is set.
+ Before version 1.2.26 only available if JkRequestLogFormat is set.
+
+
+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.
+
+
+
+The four following options +ForwardURIxxx 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.
+
+
+
+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:
+
+
+options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost)
+
+
+
+Using JkOptions ForwardURIProxy, 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.
+
+
+
+
+
+
+Using JkOptions ForwardURICompatUnparsed, 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.
+
+
+
+
+
+
+Using JkOptions ForwardURICompat, 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 not safe if you are using
+prefix JkMount. This option will allow to rewrite URIs with
+mod_rewrite before forwarding.
+
+
+
+
+
+
+Using JkOptions ForwardURIEscaped, 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.
+
+
+
+
+
+
+JkOptions RejectUnsafeURI will block all
+URLs, which contain percent signs '%' or backslashes '\'
+after decoding.
+
+
+
+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. +
+
+You can also realise such a check with mod_rewrite, which is more powerful
+but also slightly more complicated.
+
+
+
+
+
+
+JkOptions ForwardDirectories is used in conjunction with DirectoryIndex
+directive of Apache web server. As such mod_dir should be available to Apache,
+statically or dynamically (DSO)
+
+
+
+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). +
+ +
+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 403 Forbidden
response (if
+directive Options doesn't specify Indexes for that directory).
+
+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. +
+ +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.
+
+
+
+
+
+JkOptions ForwardLocalAddress, 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.
+
+
+
+
+
+
+JkOptions FlushPackets, 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).
+
+
+
+
+
+
+JkOptions FlushHeader, you ask mod_jk to flush Apache's connection
+buffer after the response headers have been received from Tomcat.
+
+
+
+
+
+
+JkOptions DisableReuse, 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. +
+ +
+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.
+
+
+
+
+
+
+JkOptions ForwardKeySize, 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).
+
+
+
+
+
+
+JkOptions ForwardSSLCertChain, you ask mod_jk, when using ajp13,
+to forward SSL certificate chain (off by default).
+Mod_jk only passes the SSL_CLIENT_CERT
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 SSL_CLIENT_CERT_CHAIN
to Tomcat via the AJP connector.
+
+This directive exists only since version 1.2.22.
+
+
+
+
+
+The directive JkEnvVar 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.
+
+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().
+
+
+The variables are inherited from the global server to virtual hosts.
+
+
+
+
+
+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. +
++JkMount directive assign specific URLs to Tomcat. +In general the structure of a JkMount directive is: +
+ + + + + ++You can use the JkMount directive at the top level or inside <VirtualHost> +sections of your httpd.conf file. +
+JkUnMount 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. +
+ ++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. +
++The following example will block all .gif files although there is a JkMount for them: +
+ ++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. +
+ ++JkAutoAlias directive automatically Alias 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. +
+ +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.
+ + +Note that you can have a single JkAutoAlias directive per virtual +host inside your httpd.conf +
++JkWorkerProperty is a new directive available from JK 1.2.7 +version. It is a convenient method for setting directives that are +usually set inside workers.propeties file. The parameter for +that directive is raw line from workers.properties file. +
+ ++JkMountFile 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. +
+ +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. +
+ +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. +
+
+There is no way to delete entries by dynamic reloading, but you can disable or
+exclude mappings.
+
+
+
+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. +
++SetHandler jakarta-servlet 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. +
++In order to control the worker using SetEnvIf or RewriteRule +for more complex rules, you can set the environment variable JK_WORKER_NAME +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. +
++In order to use another variable than JK_WORKER_NAME, you can set the name +of this variable via the JkWorkerIndicator directive. +
++You can also define exclusions from mod_jk forwards by setting the environment +variable no-jk. +
+ ++Finally, starting with version 1.2.27 you can use the environment variable +JK_REPLY_TIMEOUT to dynamically set a reply timeout. +
+