From 9401f816dd0d9d550fe98a8507224bde51c4b847 Mon Sep 17 00:00:00 2001 From: hongbotian Date: Mon, 30 Nov 2015 02:41:33 -0500 Subject: upload tomcat JIRA: BOTTLENECK-7 Change-Id: I875d474869efd76ca203c30b60ebc0c3ee606d0e Signed-off-by: hongbotian --- .../docs/reference/apache.html | 1011 ++++++++++++++++++++ .../docs/reference/iis.html | 332 +++++++ .../docs/reference/printer/apache.html | 1010 +++++++++++++++++++ .../docs/reference/printer/iis.html | 331 +++++++ .../docs/reference/printer/status.html | 546 +++++++++++ .../docs/reference/printer/uriworkermap.html | 377 ++++++++ .../docs/reference/printer/workers.html | 1000 +++++++++++++++++++ .../docs/reference/status.html | 547 +++++++++++ .../docs/reference/uriworkermap.html | 378 ++++++++ .../docs/reference/workers.html | 1001 +++++++++++++++++++ 10 files changed, 6533 insertions(+) create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/apache.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/iis.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/apache.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/iis.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/status.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/uriworkermap.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/workers.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/status.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/uriworkermap.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/workers.html (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/docs/reference') diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/apache.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/apache.html new file mode 100644 index 00000000..9e7a7aa5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/apache.html @@ -0,0 +1,1011 @@ +The Apache Tomcat Connector - Reference Guide - Configuring Apache

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Reference Guide

Configuring Apache

print-friendly
version +

Configuration Directives

+
+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. +
+
+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. +
+
+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: +
+
Directive Description
JkWorkersFile
+The name of a worker file for the Tomcat servlet containers. +
+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. +
JkWorkerProperty
+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. +
+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. +
JkShmFile
+Shared memory file name. Used only on unix platforms. +The shm file is used by balancer and status workers. +
+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. +
+
+The shared memory contains configuration and runtime information for load balancer +workers and their members. It is need in order that all apache children +
+
share the same status information for load balancing members (OK, ERROR, ...),
+
share the information about load taken by the individual workers,
+
share the information for the parts of the configuration, which are changeable +during runtime by status workers.
+
+
+
JkShmSize
+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. +
JkMountFile
+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. +
JkMountFileReload
+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. +
JkMount
+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. +
JkUnMount
+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. +
JkAutoAlias
+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. +
JkMountCopy
+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. +
JkWorkerIndicator
+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. +
JkWatchdogInterval
+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. +
JkLogFile
+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. +
JkLogLevel
+The Tomcat Connector module log level, can be debug, info, warn +error or trace. +
+The default value is info. +
JkLogStampFormat
+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] ". +
JkRequestLogFormat
+Request log format string. See detailed description below. +
+There is no default value. Without defining a value, the request logging +is turned off. +
JkExtractSSL
+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 JkCERTCHAINPrefixn) 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. +
+
JkHTTPSIndicator
+Name of the Apache environment variable that contains SSL indication. +
+The default value is "HTTPS". +
JkCERTSIndicator
+Name of the Apache environment variable that contains SSL client certificates. +
+The default value is "SSL_CLIENT_CERT". +
JkCIPHERIndicator
+Name of the Apache environment variable that contains SSL client cipher. +
+The default value is "SSL_CIPHER". +
JkCERTCHAINPrefix
+Name of the Apache environment (prefix) that contains SSL client chain certificates. +
+The default value is "SSL_CLIENT_CERT_CHAIN_". +
JkSESSIONIndicator
+Name of the Apache environment variable that contains SSL session. +
+The default value is "SSL_SESSION_ID". +
JkKEYSIZEIndicator
+Name of the Apache environment variable that contains SSL key size in use. +
+The default value is "SSL_CIPHER_USEKEYSIZE". +
JkLocalNameIndicator
+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. +
JkLocalPortIndicator
+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. +
JkRemoteHostIndicator
+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. +
JkRemoteAddrIndicator
+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. +
JkRemotePortIndicator
+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. +
JkRemoteUserIndicator
+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. +
JkAuthTypeIndicator
+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. +
JkOptions
+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. +
JkEnvVar
+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. +
JkStripSession
+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. +
+
+

Configuration Directives Types

+
+We'll discuss here the mod_jk directive types. +
+ +
Define workers
+
+JkWorkersFile specify the location where mod_jk will find the workers definitions. +Take a look at Workers documentation for detailed description. + +
+  JkWorkersFile     /etc/httpd/conf/workers.properties
+
+ +
+
+
+ +
+ +
Logging
+
+JkLogFile specify the location where mod_jk is going to place its log file. +
+ +
+  JkLogFile     /var/log/httpd/mod_jk.log
+
+ +
+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: +
+ +
+  JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
+
+ +
+JkLogLevel +set the log level between : +
+ +
+
+info log will contain standard mod_jk activity (default). +
+
+warn log will contain non fatal error reports. +
+
+error log will contain also error reports. +
+
+debug log will contain all information on mod_jk activity +
+
+trace log will contain all tracing information on mod_jk activity +
+
+ +
  
+  JkLogLevel    info
+
+ +
+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]" +
+ +
+  JkLogStampFormat "[%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: +
+ +
+
Options Description
%b Bytes sent, excluding HTTP headers (CLF format)
%B Bytes sent, excluding HTTP headers
%H The request protocol
%m The request method
%p The canonical Port of the server serving the request
%q The query string (prepended with a ? if a query string exists, otherwise an empty string)
%r First line of request
%s Request HTTP status code
%T Request duration, elapsed time to handle request in seconds '.' micro seconds
%U The URL path requested, not including any query string.
%v The canonical ServerName of the server serving the request
%V The server name according to the UseCanonicalName setting
%w Tomcat worker name
%R Real worker name
+ +
+  JkRequestLogFormat     "%w %V %T"
+
+ +
+
+
+ +
+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. +
+ +
+
Note Description
JK_WORKER_NAME Name of the worker selected by the URI mapping
JK_WORKER_TYPE Type of the worker selected by the URI mapping
JK_WORKER_ROUTE Actual worker name selected by the URI mapping (usually a member of the load balancer).
+ Before version 1.2.26 only available if JkRequestLogFormat is set.
JK_REQUEST_DURATION Request duration in seconds and microseconds.
+ Before version 1.2.26 only available if JkRequestLogFormat is set.
JK_LB_FIRST_NAME Load-Balancer: Name of the first worker tried
JK_LB_FIRST_TYPE Load-Balancer: Type of the first worker tried
JK_LB_FIRST_ACCESSED Load-Balancer: Access count for the first worker tried
JK_LB_FIRST_READ Load-Balancer: Bytes read for the first worker tried
JK_LB_FIRST_TRANSFERRED Load-Balancer: Bytes transferred for the first worker tried
JK_LB_FIRST_ERRORS Load-Balancer: Error count for the first worker tried
JK_LB_FIRST_BUSY Load-Balancer: Busy count for the first worker tried
JK_LB_FIRST_ACTIVATION Load-Balancer: Activation state for the first worker tried
JK_LB_FIRST_STATE Load-Balancer: Error state for the first worker tried
JK_LB_LAST_NAME Load-Balancer: Name of the last worker tried
JK_LB_LAST_TYPE Load-Balancer: Type of the last worker tried
JK_LB_LAST_ACCESSED Load-Balancer: Access count for the last worker tried
JK_LB_LAST_READ Load-Balancer: Bytes read for the last worker tried
JK_LB_LAST_TRANSFERRED Load-Balancer: Bytes transferred for the last worker tried
JK_LB_LAST_ERRORS Load-Balancer: Error count for the last worker tried
JK_LB_LAST_BUSY Load-Balancer: Busy count for the last worker tried
JK_LB_LAST_ACTIVATION Load-Balancer: Activation state for the last worker tried
JK_LB_LAST_STATE Load-Balancer: Error state for the last worker tried
+ +
+  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
+
+ +
+
+
+ +
+ +
Forwarding
+
+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. + +
+  JkOptions     +ForwardURIProxy
+
+ +
+
+
+ +
+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. + +
+  JkOptions     +ForwardURICompatUnparsed
+
+ +
+
+
+ +
+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. + +
+  JkOptions     +ForwardURICompat
+
+ +
+
+
+ +
+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     +ForwardURIEscaped
+
+ +
+
+
+ +
+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     +RejectUnsafeURI
+
+ +
+
+
+ +
+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     +ForwardDirectories
+
+
+
+
+ +
+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     +ForwardLocalAddress
+
+ +
+
+
+ +
+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     +FlushPackets
+
+ +
+
+
+ +
+JkOptions FlushHeader, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +
  
+  JkOptions     +FlushHeader
+
+ +
+
+
+ +
+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     +DisableReuse
+
+ +
+
+
+ +
+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     +ForwardKeySize
+
+ +
+
+
+ +
+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. +
  
+  JkOptions     +ForwardSSLCertChain
+
+ +
+
+
+ +
+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. + +
  
+  JkEnvVar     SSL_CLIENT_V_START     undefined
+
+
+
+
+ +
+ +
Assigning URLs to Tomcat
+
+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: +
+ +
  
+  JkMount [URL prefix] [Worker name]
+
+ +
+  # 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
+
+ +
+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. +
+
+  # send all requests ending with /servlet to worker1
+  JkMount /servlet/* worker1
+  # do not send requests ending with .gif to worker1
+  JkUnMount /servlet/*.gif worker1
+
+
+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: +
+
+  # 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
+
+
+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. +
+
+  # 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=*
+
+
+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. +
+
+  # enter the full path to the tomcat webapps directory
+  JkAutoAlias /opt/tomtact/webapps
+
+
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.
+ +
+  # 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
+
+
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. +
+
+  # 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   
+
+
+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. +
+
+  # Load mount points
+
+  JkMountFile conf/uriworkermap.properties
+
+
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. +
+
+  # Sample uriworkermap.properties file
+
+  /servlets-examples/*=ajp13w
+  # Do not map .jpeg files
+  !/servlets-examples/*.jpeg=ajp13w
+  # Make jsp examples initially disabled  
+  -/jsp-examples/*=ajp13w
+
+
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. +
+
+
+ +
+ +
Using SetHandler and Environment Variables
+
+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. +
+
+  # 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>
+
+
+Finally, starting with version 1.2.27 you can use the environment variable +JK_REPLY_TIMEOUT to dynamically set a reply timeout. +
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/iis.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/iis.html new file mode 100644 index 00000000..e767d281 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/iis.html @@ -0,0 +1,332 @@ +The Apache Tomcat Connector - Reference Guide - Configuring IIS

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Reference Guide

Configuring IIS

print-friendly
version +

Requirements

+
+The Tomcat redirector requires three entities: + +
+
+isapi_redirect.dll - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +
+
+uriworkermap.properties - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +
+
+
+ +
+The installation includes the following parts: + +
+
+Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +
+
+Adding more contexts to the configuration. +
+
+
+

Registry settings

+
+ISAPI redirector reads configuration from the registry, create a new registry key named : +
+
+"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" +
+
Key Name Description
extension_uri
+A string value pointing to the ISAPI extension /jakarta/isapi_redirect.dll +
log_file
+A value pointing to location where log file will be created. +(for example c:\tomcat\logs\isapi.log) +
If one of the log rotation settings (log_rotationtime or log_filesize) are specified then the actual log file name is based on this setting. +If the log file name includes any '%' characters, then it is treated as a format string for strftime(3), +e.g. c:\tomcat\logs\isapi-%Y-%m-%d-%H_%M_%S.log. Otherwise, the suffix .nnnnnnnnnn is automatically added and is the time in seconds. +A full list of format string substitutions can be found in the Apache rotatelogs documentation +
log_level
+A string value for log level +(can be debug, info, warn, error or trace).
+
This directive was added in version 1.2.31
+
log_rotationtime
+The time between log file rotations in seconds. +Setting this to 0 (the default) disables log rotation based on time.
+
This directive was added in version 1.2.31
+
log_filesize
+The maximum log file size in megabytes, after which the log file will be rotated. Setting this to 0 (the default) disables log rotation based on file size. +
The value can have an optional M suffix, i.e. both 5 and 5M will rotate the log file when it grows to 5MB. +
If log_rotationtime is specified, then this setting is ignored. +
worker_file
+A string value which is the full path to workers.properties file +(for example c:\tomcat\conf\workers.properties) +
worker_mount_file
+A string value which is the full path to uriworkermap.properties file +(for example c:\tomcat\conf\uriworkermap.properties) +
rewrite_rule_file
+A string value which is the full path to rewrite.properties file +(for example c:\tomcat\conf\rewrite.properties) +
shm_size
+A DWORD value size of the shared memory. Set this value to be +the number of all defined workers * 400. +(Set this value only if you have more then 64 workers) +
+
This directive has been added in version 1.2.20
+
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.
+
worker_mount_reload
+A DWORD value specifying the time in seconds upon which the +worker_mount_file will be reloaded. +
+
This directive has been added in version 1.2.20
+
strip_session
+A string value representing a boolean. If it is set to true, +URL session suffixes of the form ";jsessionid=..." get stripped of URLs, +even if the are served locally by the web server. +
+
+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +
+
This directive has been added in version 1.2.21
+
auth_complete
+A DWORD value representing "0" or "1". This is needed because +of minor incompatibilities with IIS 5.1. +
+
+By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE +event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS. +This might be needed for IIS 5.1 when handling requests using the +PUT HTTP method. +
+
This directive has been added in version 1.2.21
+
uri_select
+A string value which influences, how URIs are decoded and re-encoded +between IIS and Tomcat. You should leave this at it's default value, +unless you have a very good reason to change it. +
+
+If the value is "parsed", the forwarded URI +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 forwarding rules. +
+
+If the value is "unparsed", the forwarded URI +will be the original request URI. It's spec compliant and also +the safest option. Rewriting the URI and then forwarding the rewritten +URI will not work. +
+
+If the value is "escaped", the forwarded URI +will be the re-encoded form of the URI used by "parsed". +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs. +
+
+If the value is "proxy", the forwarded URI +will be a partially re-encoded form of the URI used by "parsed". +Explicit path components like ".." will already be resolved. +and problematic are re-encoded. +
+
The default value since version 1.2.24 is "proxy". Before it was "parsed".
+
reject_unsafe
+A string value representing a boolean. If it is set to true, +URLs containing percent signs '%' or backslashes '\' +after decoding will be rejected. +
+
+Most web apps do not use such URLs. By enabling "reject_unsafe" you +can block several well known URL encoding attacks. +
+
+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +
+
This directive has been added in version 1.2.24
+
watchdog_interval
+A DWORD value representing 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 watchdog_interval +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 has been added in version 1.2.27
+
error_page
+A string value representing the error page url redirection when +backend returns non-200 response. This directive can be used +to customise the error messages returned from backend server. +
+
The url must point to a valid server url and can contain +format string number (%d) that can be used to +separate the pages by error number. The redirect url in that +case is formatted by replacing %d from +error_page to returned error number. +
+
This directive has been added in version 1.2.27
+
enable_chunked_encoding
+A string value representing a boolean. If it is set to true, +chunked encoding is supported by the server. +
+
+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +
+
This option is considered experimental and its support +must be compile time enabled. Use isapi_redirect.dll +with chunked support enabled. +
+
This directive has been added in version 1.2.27
+
+

Using a properties file for configuration

+
+The ISAPI redirector can read it's configuration from a properties file instead of the registry. +This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server. +The redirector will check for the properties file during initialisation, and use it in preference to the registry if present. +
+
+Create a properties file in the same directory as the ISAPI redirector called isapi_redirect.properties i.e. with the same name as the ISAPI redirector DLL but with a .properties extension. A sample isapi_redirect.properties can be found under the conf directory. +
+
+The property names and values in the properties file are the same as for the registry settings described above. For example: +
+
+
+# Configuration file for the Jakarta ISAPI Redirector
+
+# The path to the ISAPI Redirector Extension, relative to the website
+# This must be in a virtual directory with execute privileges
+extension_uri=/jakarta/isapi_redirect.dll
+
+# Full path to the log file for the ISAPI Redirector
+log_file=c:\tomcat\logs\isapi_redirect.log
+
+# Log level (debug, info, warn, error or trace)
+log_level=info
+
+# Full path to the workers.properties file
+worker_file=c:\tomcat\conf\workers.properties
+
+# Full path to the uriworkermap.properties file
+worker_mount_file=c:\tomcat\conf\uriworkermap.properties
+
+
+
+ Notes: +
+
+ Back-slashes - '\' - are not escape characters. +
+
+ Comment lines begin with '#'. +
+
+
+
Starting with version 1.2.27 two environment variables are +dynamically added to the environment that can be used inside +.properties files. +
+
JKISAPI_PATH - Full path to the ISAPI Redirector. +
+
JKISAPI_NAME - Name of the ISAPI Redirector dll without extension +
+
+
+
+# Use the logs in the installation path of ISAPI Redirector
+log_file=$(ISAPI_PATH)\$(ISAPI_NAME).log
+
+

Log file rotation

+
+The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the +rotatelogs program provided with Apache HTTP Server. +
+
+To configure log rotation, configure a log_file, and one of the log_rotationtime or log_filesize options. +If both are specified, the log_rotationtime will take precedence, and log_filesize will be ignored. +
For example, to configure daily rotation of the log file: +
+
+# Configuration file for the Jakarta ISAPI Redirector
+...
+
+# Full path to the log file for the ISAPI Redirector
+log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log
+
+# Log level (debug, info, warn, error or trace)
+log_level=info
+
+# Rotate the log file every day
+log_rotationtime=86400
+
+...
+
+
+Or to configure rotation of the log file when it reaches 5MB in size: +
+
+# Configuration file for the Jakarta ISAPI Redirector
+...
+
+# Full path to the log file for the ISAPI Redirector
+log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log
+
+# Log level (debug, info, warn, error or trace)
+log_level=info
+
+# Rotate the log file at 5 MB
+log_filesize=5M
+
+...
+
+
+The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure + a log file name with strftime(3) format codes in it, then ensure it specifies the same granularity + as the rotation time configured, e.g. %Y-%m-%d if rotating daily (log_rotationtime=86400). +
See the rotatelogs documentation for more examples. +
+ +

Using a simple rewrite rules

+
+The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not +as powerful as Apache Httpd's mod_rewrite, it allows a simple exchange of request URIs +
+
+The rule is in the form original-url-prefix=forward-url-prefix. For example: +
+
+# Simple rewrite rules, making /jsp-examples
+# and /servlets-examples available under shorter URLs
+/jsp/=/jsp-examples/
+/servlets/=/servlets-examples/
+
+
+You can also use regular expressions, if you prefix the rule with a tilde ~: +
+
+# Complex rewrite rule, adding "-examples"
+# to the first path component of all requests
+~/([^/]*)=/$1-examples
+
+
+Note that uriworkermap.properties must use the URLs before rewriting. +
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/apache.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/apache.html new file mode 100644 index 00000000..6524e441 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/apache.html @@ -0,0 +1,1010 @@ +The Apache Tomcat Connector - Reference Guide - Configuring Apache

The Apache Tomcat Connector - Reference Guide

Configuring Apache

Configuration Directives

+
+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. +
+
+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. +
+
+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: +
+
Directive Description
JkWorkersFile
+The name of a worker file for the Tomcat servlet containers. +
+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. +
JkWorkerProperty
+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. +
+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. +
JkShmFile
+Shared memory file name. Used only on unix platforms. +The shm file is used by balancer and status workers. +
+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. +
+
+The shared memory contains configuration and runtime information for load balancer +workers and their members. It is need in order that all apache children +
+
share the same status information for load balancing members (OK, ERROR, ...),
+
share the information about load taken by the individual workers,
+
share the information for the parts of the configuration, which are changeable +during runtime by status workers.
+
+
+
JkShmSize
+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. +
JkMountFile
+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. +
JkMountFileReload
+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. +
JkMount
+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. +
JkUnMount
+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. +
JkAutoAlias
+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. +
JkMountCopy
+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. +
JkWorkerIndicator
+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. +
JkWatchdogInterval
+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. +
JkLogFile
+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. +
JkLogLevel
+The Tomcat Connector module log level, can be debug, info, warn +error or trace. +
+The default value is info. +
JkLogStampFormat
+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] ". +
JkRequestLogFormat
+Request log format string. See detailed description below. +
+There is no default value. Without defining a value, the request logging +is turned off. +
JkExtractSSL
+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 JkCERTCHAINPrefixn) 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. +
+
JkHTTPSIndicator
+Name of the Apache environment variable that contains SSL indication. +
+The default value is "HTTPS". +
JkCERTSIndicator
+Name of the Apache environment variable that contains SSL client certificates. +
+The default value is "SSL_CLIENT_CERT". +
JkCIPHERIndicator
+Name of the Apache environment variable that contains SSL client cipher. +
+The default value is "SSL_CIPHER". +
JkCERTCHAINPrefix
+Name of the Apache environment (prefix) that contains SSL client chain certificates. +
+The default value is "SSL_CLIENT_CERT_CHAIN_". +
JkSESSIONIndicator
+Name of the Apache environment variable that contains SSL session. +
+The default value is "SSL_SESSION_ID". +
JkKEYSIZEIndicator
+Name of the Apache environment variable that contains SSL key size in use. +
+The default value is "SSL_CIPHER_USEKEYSIZE". +
JkLocalNameIndicator
+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. +
JkLocalPortIndicator
+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. +
JkRemoteHostIndicator
+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. +
JkRemoteAddrIndicator
+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. +
JkRemotePortIndicator
+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. +
JkRemoteUserIndicator
+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. +
JkAuthTypeIndicator
+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. +
JkOptions
+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. +
JkEnvVar
+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. +
JkStripSession
+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. +
+
+

Configuration Directives Types

+
+We'll discuss here the mod_jk directive types. +
+ +
Define workers
+
+JkWorkersFile specify the location where mod_jk will find the workers definitions. +Take a look at Workers documentation for detailed description. + +
+  JkWorkersFile     /etc/httpd/conf/workers.properties
+
+ +
+
+
+ +
+ +
Logging
+
+JkLogFile specify the location where mod_jk is going to place its log file. +
+ +
+  JkLogFile     /var/log/httpd/mod_jk.log
+
+ +
+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: +
+ +
+  JkLogFile     "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400"
+
+ +
+JkLogLevel +set the log level between : +
+ +
+
+info log will contain standard mod_jk activity (default). +
+
+warn log will contain non fatal error reports. +
+
+error log will contain also error reports. +
+
+debug log will contain all information on mod_jk activity +
+
+trace log will contain all tracing information on mod_jk activity +
+
+ +
  
+  JkLogLevel    info
+
+ +
+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]" +
+ +
+  JkLogStampFormat "[%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: +
+ +
+
Options Description
%b Bytes sent, excluding HTTP headers (CLF format)
%B Bytes sent, excluding HTTP headers
%H The request protocol
%m The request method
%p The canonical Port of the server serving the request
%q The query string (prepended with a ? if a query string exists, otherwise an empty string)
%r First line of request
%s Request HTTP status code
%T Request duration, elapsed time to handle request in seconds '.' micro seconds
%U The URL path requested, not including any query string.
%v The canonical ServerName of the server serving the request
%V The server name according to the UseCanonicalName setting
%w Tomcat worker name
%R Real worker name
+ +
+  JkRequestLogFormat     "%w %V %T"
+
+ +
+
+
+ +
+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. +
+ +
+
Note Description
JK_WORKER_NAME Name of the worker selected by the URI mapping
JK_WORKER_TYPE Type of the worker selected by the URI mapping
JK_WORKER_ROUTE Actual worker name selected by the URI mapping (usually a member of the load balancer).
+ Before version 1.2.26 only available if JkRequestLogFormat is set.
JK_REQUEST_DURATION Request duration in seconds and microseconds.
+ Before version 1.2.26 only available if JkRequestLogFormat is set.
JK_LB_FIRST_NAME Load-Balancer: Name of the first worker tried
JK_LB_FIRST_TYPE Load-Balancer: Type of the first worker tried
JK_LB_FIRST_ACCESSED Load-Balancer: Access count for the first worker tried
JK_LB_FIRST_READ Load-Balancer: Bytes read for the first worker tried
JK_LB_FIRST_TRANSFERRED Load-Balancer: Bytes transferred for the first worker tried
JK_LB_FIRST_ERRORS Load-Balancer: Error count for the first worker tried
JK_LB_FIRST_BUSY Load-Balancer: Busy count for the first worker tried
JK_LB_FIRST_ACTIVATION Load-Balancer: Activation state for the first worker tried
JK_LB_FIRST_STATE Load-Balancer: Error state for the first worker tried
JK_LB_LAST_NAME Load-Balancer: Name of the last worker tried
JK_LB_LAST_TYPE Load-Balancer: Type of the last worker tried
JK_LB_LAST_ACCESSED Load-Balancer: Access count for the last worker tried
JK_LB_LAST_READ Load-Balancer: Bytes read for the last worker tried
JK_LB_LAST_TRANSFERRED Load-Balancer: Bytes transferred for the last worker tried
JK_LB_LAST_ERRORS Load-Balancer: Error count for the last worker tried
JK_LB_LAST_BUSY Load-Balancer: Busy count for the last worker tried
JK_LB_LAST_ACTIVATION Load-Balancer: Activation state for the last worker tried
JK_LB_LAST_STATE Load-Balancer: Error state for the last worker tried
+ +
+  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
+
+ +
+
+
+ +
+ +
Forwarding
+
+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. + +
+  JkOptions     +ForwardURIProxy
+
+ +
+
+
+ +
+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. + +
+  JkOptions     +ForwardURICompatUnparsed
+
+ +
+
+
+ +
+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. + +
+  JkOptions     +ForwardURICompat
+
+ +
+
+
+ +
+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     +ForwardURIEscaped
+
+ +
+
+
+ +
+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     +RejectUnsafeURI
+
+ +
+
+
+ +
+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     +ForwardDirectories
+
+
+
+
+ +
+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     +ForwardLocalAddress
+
+ +
+
+
+ +
+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     +FlushPackets
+
+ +
+
+
+ +
+JkOptions FlushHeader, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +
  
+  JkOptions     +FlushHeader
+
+ +
+
+
+ +
+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     +DisableReuse
+
+ +
+
+
+ +
+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     +ForwardKeySize
+
+ +
+
+
+ +
+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. +
  
+  JkOptions     +ForwardSSLCertChain
+
+ +
+
+
+ +
+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. + +
  
+  JkEnvVar     SSL_CLIENT_V_START     undefined
+
+
+
+
+ +
+ +
Assigning URLs to Tomcat
+
+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: +
+ +
  
+  JkMount [URL prefix] [Worker name]
+
+ +
+  # 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
+
+ +
+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. +
+
+  # send all requests ending with /servlet to worker1
+  JkMount /servlet/* worker1
+  # do not send requests ending with .gif to worker1
+  JkUnMount /servlet/*.gif worker1
+
+
+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: +
+
+  # 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
+
+
+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. +
+
+  # 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=*
+
+
+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. +
+
+  # enter the full path to the tomcat webapps directory
+  JkAutoAlias /opt/tomtact/webapps
+
+
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.
+ +
+  # 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
+
+
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. +
+
+  # 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   
+
+
+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. +
+
+  # Load mount points
+
+  JkMountFile conf/uriworkermap.properties
+
+
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. +
+
+  # Sample uriworkermap.properties file
+
+  /servlets-examples/*=ajp13w
+  # Do not map .jpeg files
+  !/servlets-examples/*.jpeg=ajp13w
+  # Make jsp examples initially disabled  
+  -/jsp-examples/*=ajp13w
+
+
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. +
+
+
+ +
+ +
Using SetHandler and Environment Variables
+
+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. +
+
+  # 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>
+
+
+Finally, starting with version 1.2.27 you can use the environment variable +JK_REPLY_TIMEOUT to dynamically set a reply timeout. +
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/iis.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/iis.html new file mode 100644 index 00000000..8405bcf5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/iis.html @@ -0,0 +1,331 @@ +The Apache Tomcat Connector - Reference Guide - Configuring IIS

The Apache Tomcat Connector - Reference Guide

Configuring IIS

Requirements

+
+The Tomcat redirector requires three entities: + +
+
+isapi_redirect.dll - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +
+
+workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +
+
+uriworkermap.properties - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +
+
+
+ +
+The installation includes the following parts: + +
+
+Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +
+
+Adding more contexts to the configuration. +
+
+
+

Registry settings

+
+ISAPI redirector reads configuration from the registry, create a new registry key named : +
+
+"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" +
+
Key Name Description
extension_uri
+A string value pointing to the ISAPI extension /jakarta/isapi_redirect.dll +
log_file
+A value pointing to location where log file will be created. +(for example c:\tomcat\logs\isapi.log) +
If one of the log rotation settings (log_rotationtime or log_filesize) are specified then the actual log file name is based on this setting. +If the log file name includes any '%' characters, then it is treated as a format string for strftime(3), +e.g. c:\tomcat\logs\isapi-%Y-%m-%d-%H_%M_%S.log. Otherwise, the suffix .nnnnnnnnnn is automatically added and is the time in seconds. +A full list of format string substitutions can be found in the Apache rotatelogs documentation +
log_level
+A string value for log level +(can be debug, info, warn, error or trace).
+
This directive was added in version 1.2.31
+
log_rotationtime
+The time between log file rotations in seconds. +Setting this to 0 (the default) disables log rotation based on time.
+
This directive was added in version 1.2.31
+
log_filesize
+The maximum log file size in megabytes, after which the log file will be rotated. Setting this to 0 (the default) disables log rotation based on file size. +
The value can have an optional M suffix, i.e. both 5 and 5M will rotate the log file when it grows to 5MB. +
If log_rotationtime is specified, then this setting is ignored. +
worker_file
+A string value which is the full path to workers.properties file +(for example c:\tomcat\conf\workers.properties) +
worker_mount_file
+A string value which is the full path to uriworkermap.properties file +(for example c:\tomcat\conf\uriworkermap.properties) +
rewrite_rule_file
+A string value which is the full path to rewrite.properties file +(for example c:\tomcat\conf\rewrite.properties) +
shm_size
+A DWORD value size of the shared memory. Set this value to be +the number of all defined workers * 400. +(Set this value only if you have more then 64 workers) +
+
This directive has been added in version 1.2.20
+
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.
+
worker_mount_reload
+A DWORD value specifying the time in seconds upon which the +worker_mount_file will be reloaded. +
+
This directive has been added in version 1.2.20
+
strip_session
+A string value representing a boolean. If it is set to true, +URL session suffixes of the form ";jsessionid=..." get stripped of URLs, +even if the are served locally by the web server. +
+
+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +
+
This directive has been added in version 1.2.21
+
auth_complete
+A DWORD value representing "0" or "1". This is needed because +of minor incompatibilities with IIS 5.1. +
+
+By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE +event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS. +This might be needed for IIS 5.1 when handling requests using the +PUT HTTP method. +
+
This directive has been added in version 1.2.21
+
uri_select
+A string value which influences, how URIs are decoded and re-encoded +between IIS and Tomcat. You should leave this at it's default value, +unless you have a very good reason to change it. +
+
+If the value is "parsed", the forwarded URI +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 forwarding rules. +
+
+If the value is "unparsed", the forwarded URI +will be the original request URI. It's spec compliant and also +the safest option. Rewriting the URI and then forwarding the rewritten +URI will not work. +
+
+If the value is "escaped", the forwarded URI +will be the re-encoded form of the URI used by "parsed". +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs. +
+
+If the value is "proxy", the forwarded URI +will be a partially re-encoded form of the URI used by "parsed". +Explicit path components like ".." will already be resolved. +and problematic are re-encoded. +
+
The default value since version 1.2.24 is "proxy". Before it was "parsed".
+
reject_unsafe
+A string value representing a boolean. If it is set to true, +URLs containing percent signs '%' or backslashes '\' +after decoding will be rejected. +
+
+Most web apps do not use such URLs. By enabling "reject_unsafe" you +can block several well known URL encoding attacks. +
+
+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +
+
This directive has been added in version 1.2.24
+
watchdog_interval
+A DWORD value representing 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 watchdog_interval +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 has been added in version 1.2.27
+
error_page
+A string value representing the error page url redirection when +backend returns non-200 response. This directive can be used +to customise the error messages returned from backend server. +
+
The url must point to a valid server url and can contain +format string number (%d) that can be used to +separate the pages by error number. The redirect url in that +case is formatted by replacing %d from +error_page to returned error number. +
+
This directive has been added in version 1.2.27
+
enable_chunked_encoding
+A string value representing a boolean. If it is set to true, +chunked encoding is supported by the server. +
+
+A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +
+
This option is considered experimental and its support +must be compile time enabled. Use isapi_redirect.dll +with chunked support enabled. +
+
This directive has been added in version 1.2.27
+
+

Using a properties file for configuration

+
+The ISAPI redirector can read it's configuration from a properties file instead of the registry. +This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server. +The redirector will check for the properties file during initialisation, and use it in preference to the registry if present. +
+
+Create a properties file in the same directory as the ISAPI redirector called isapi_redirect.properties i.e. with the same name as the ISAPI redirector DLL but with a .properties extension. A sample isapi_redirect.properties can be found under the conf directory. +
+
+The property names and values in the properties file are the same as for the registry settings described above. For example: +
+
+
+# Configuration file for the Jakarta ISAPI Redirector
+
+# The path to the ISAPI Redirector Extension, relative to the website
+# This must be in a virtual directory with execute privileges
+extension_uri=/jakarta/isapi_redirect.dll
+
+# Full path to the log file for the ISAPI Redirector
+log_file=c:\tomcat\logs\isapi_redirect.log
+
+# Log level (debug, info, warn, error or trace)
+log_level=info
+
+# Full path to the workers.properties file
+worker_file=c:\tomcat\conf\workers.properties
+
+# Full path to the uriworkermap.properties file
+worker_mount_file=c:\tomcat\conf\uriworkermap.properties
+
+
+
+ Notes: +
+
+ Back-slashes - '\' - are not escape characters. +
+
+ Comment lines begin with '#'. +
+
+
+
Starting with version 1.2.27 two environment variables are +dynamically added to the environment that can be used inside +.properties files. +
+
JKISAPI_PATH - Full path to the ISAPI Redirector. +
+
JKISAPI_NAME - Name of the ISAPI Redirector dll without extension +
+
+
+
+# Use the logs in the installation path of ISAPI Redirector
+log_file=$(ISAPI_PATH)\$(ISAPI_NAME).log
+
+

Log file rotation

+
+The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the +rotatelogs program provided with Apache HTTP Server. +
+
+To configure log rotation, configure a log_file, and one of the log_rotationtime or log_filesize options. +If both are specified, the log_rotationtime will take precedence, and log_filesize will be ignored. +
For example, to configure daily rotation of the log file: +
+
+# Configuration file for the Jakarta ISAPI Redirector
+...
+
+# Full path to the log file for the ISAPI Redirector
+log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log
+
+# Log level (debug, info, warn, error or trace)
+log_level=info
+
+# Rotate the log file every day
+log_rotationtime=86400
+
+...
+
+
+Or to configure rotation of the log file when it reaches 5MB in size: +
+
+# Configuration file for the Jakarta ISAPI Redirector
+...
+
+# Full path to the log file for the ISAPI Redirector
+log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log
+
+# Log level (debug, info, warn, error or trace)
+log_level=info
+
+# Rotate the log file at 5 MB
+log_filesize=5M
+
+...
+
+
+The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure + a log file name with strftime(3) format codes in it, then ensure it specifies the same granularity + as the rotation time configured, e.g. %Y-%m-%d if rotating daily (log_rotationtime=86400). +
See the rotatelogs documentation for more examples. +
+ +

Using a simple rewrite rules

+
+The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not +as powerful as Apache Httpd's mod_rewrite, it allows a simple exchange of request URIs +
+
+The rule is in the form original-url-prefix=forward-url-prefix. For example: +
+
+# Simple rewrite rules, making /jsp-examples
+# and /servlets-examples available under shorter URLs
+/jsp/=/jsp-examples/
+/servlets/=/servlets-examples/
+
+
+You can also use regular expressions, if you prefix the rule with a tilde ~: +
+
+# Complex rewrite rule, adding "-examples"
+# to the first path component of all requests
+~/([^/]*)=/$1-examples
+
+
+Note that uriworkermap.properties must use the URLs before rewriting. +
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/status.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/status.html new file mode 100644 index 00000000..56412d61 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/status.html @@ -0,0 +1,546 @@ +The Apache Tomcat Connector - Reference Guide - Status Worker Reference

The Apache Tomcat Connector - Reference Guide

Status Worker Reference

Introduction

+
+
+Tomcat Connectors has a special type of worker, the so-called status worker. +The status worker does not forward requests to Tomcat instances. Instead it allows +to retrieve status and configuration information at runtime, +and furthermore to change many configuration items dynamically. This can be done +via a simple embedded web interface. +
+
+The status worker is especially powerful, when used together with load balancing workers. +
+
+This document does not explain the HTML user interface of the status worker. +Until now it is very simple, so just go ahead and use it. This doc instead +tries to explain the less obvious features of the status worker. We also will give a +complete coverage of the various request parameters and their meaning, so that you can +include the status worker in your automation scripts. +
+
+The documentation of the status worker starts with jk 1.2.20 +
+

Usage Patterns

+
+
Actions
+
+
+The status worker knows about six actions. +
+
+list: lists the configurations and runtime information of all configured workers. +The output will be grouped by global information first (version data), then load balancer +information, after that AJP worker information and finally the legend. For load balancers, +there will be a summary part, and after that details for each member worker. For all workers, +we also include the URL mappings (forward definitions). +
+
+show: the same as list, but only shows data for one chosen worker +
+
+edit: produces a form to edit configuration data for a chosen worker. There is a +special subtype of "edit", that makes it easy to change one attribute for all members of +a load balancer, e.g. their activation state. +
+
+update: commit changes made in an edit form. Caution: the changes will not be +persisted to the configuration files. As soon as your restart your web server, all changes +made through the status worker will be lost! On the other hand, the changes done by the status +worker will be applied during runtime without a restart of the web server. +
+
+reset: reset all runtime statistics for a worker. +
+
+recover: Mark a member of a load balancer, that is in error state, for immediate recovery. +
+
+version: only show version information of the web server and the JK software +
+
+dump: list the original workers configuration. Caution: the dump will only contain +the configuration that was used during startup. Any changes applied later by the dynamic management +interface of the status worker itself will not be contained in this dump. +The dump action has been added in version 1.2.27. +
+
+
+
+ +
Output Format
+
+
+For most actions you can choose between 4 output formats. +
+
+HTML: Used interactively with a browser +
+
+XML: Mostly useful for automation, when your scripting environment is XML friendly. +This format has rich structure information, but does not work line based, so you would really +like to use it together with XML tools. +
+
+Properties: This format is a line based format, that conforms to the rules of Java +property files. Most structure information is contained in the hierarchical key. For information, +that is of configuration nature, the format should produce lines very similar to the ones you can +use in workers.properties. It will not produce a complete configuration file! +
+
+Text: A simple textual output format. +
+
+The "edit" action does only make sense for the HTML output type. +
+
+ +
User Interface Features
+
+
+In the HTML view, there is an automatic refresh feature, implemented via the meta refresh +option of HTML. Once you start the automatic refresh, the UI will will respect it for all actions +except edit, update and maintain. Even if you navigate through one of those, the automatic refresh +will start again as soon as you come back to one of the other actions. +
+
+Many parts of the HTML page can be minimised, if they are not interesting for you. There are a couple +of "Hide" links, which will collapse parts of the information. The feature exists for the following +blocks of information: +
+
+Legend: Do not show the legend for the information presented in "list" and "show" actions +
+
+URI mappings: Do not show the URI mapping for the workers +
+
+Load Balancing Workers: Do not show workers of type "lb" +
+
+AJP Workers: Do not show workers of type ajp +
+
+Balancer Members: Do not show detailed information concerning each member of load balancers +
+
+Load Balancer Configuration: Do not show configuration data for load balancers +
+
+Load Balancer Summary: Do not show status summary for load balancers +
+
+AJP Configuration: Do not show configuration data for ajp workers load balancer members +
+
+The last three minimisation features have been added in version 1.2.27. +
+
+ +
Special Considerations concerning URL Maps and Virtual Hosts
+
+
+Note: The following restriction has been removed starting with version 1.2.26. +
+
+The Apache module mod_jk makes use of the internal Apache httpd infrastructure concerning +virtual hosts. The downside of this is, that the status worker can only show URL maps, for +the virtual host it is defined in. It is not able to reach the configuration objects +for other virtual hosts. Of course you can define a status worker in any virtual host you +are using. All information presented apart from the URL maps will be the same, independent +of the virtual host the status worker has been called in. +
+
+ +
Logging
+
+
+The status worker will log changes made to the configuration with log level "info" to the usual +JK log file. Invalid requests will be logged with log level "warn". If you want to report some +broken behaviour, log file content of level "debug" or even "trace" will be useful. +
+
+ +

Configuration

+
+
Basic Configuration
+
+
+The basic configuration of a status worker is very similar to that of a usual ajp worker. +You need to specify a name for the worker, and the URLs you want to map to it. The first +part of the configuration happens in the workers.properties file. We define a worker named +mystatus of type status: +
+worker.list=mystatus
+worker.mystatus.type=status
+
+Then we define a URL, which should be mapped to this worker, i.e. the URL we use +to reach the functionality of the status worker. You can use any method mod_jk supports +for the web server of your choice. Possibilities are maps inside uriworkermap.properties, +an additional mount attribute in workers.properties, or in Apache JkMount. Here's an +example for a uriworkermap.properties line: +
+/private/admin/mystatus=mystatus
+
+The URI pattern is case sensitive. +
+
+As you will learn in the following sections, the status worker is very powerful. You should +use the usual authentication and authorisation methods of your web server to secure this URL. +
+
+You can also define multiple instances of the status worker, by using different names and URL mappings. +For instance you might want to configure them individually +and then allow special groups of people to use them +
+
+ +
Output Customisation
+
+
+There are a couple of attributes for the workers.properties entries, which allow to customise +various aspects of the output of the status worker. +
+
+The attribute css can be set to the URL of a stylesheet: +
+worker.mystatus.css=/private/admin/static/mystatus.css
+
+When writing HTML output, the status worker then includes the line +
+<link rel="stylesheet" type="text/css" href="/private/admin/static/mystatus.css" />
+
+There is no sample stylesheet included with the mod_jk release, and by default the attribute css +is empty, so no stylesheet reference will be included in the pages. The HTML code +of the status worker output pages does not include any class attributes. If you like to contribute a +stylesheet or improvements to the HTML layout, please contact us on the tomcat developers list. +
+
+The properties output format can be customised via the attribute prefix. The names of all +properties the status worker does output, will begin with this prefix. The default is "worker". +
+
+Several attributes influence the format when writing XML output. +The attribute ns allows to set a namespace prefix, that will be used for every status worker+element. +The default is "jk:". Setting it to "-" disables the namespace prefix. +
+
+With the attribute xmlns you can map the prefix to a namespace URL. The default value +is xmlns:jk="http://tomcat.apache.org". Setting it to "-" disables the output of the URL. +
+
+Finally you can specify an XML document type via the attribute doctype. The specified string will +be inserted at the beginning of the document, directly after the xml header. The default is empty. +
+
+ +
Securing Access
+
+
+We urge you to use the builtin access control features of your web server to control +access to the status worker URLs you have chosen. Nevertheless two configuration +attributes of status workers are helpful. The attribute "read_only" disables all features of +the status worker, that can be used to change configurations or runtime status of the other workers. +A read_only status worker will not allow access to the edit, update, reset or recover actions. +The default value is "False", ie. read/write. To enable read_only you need to set it to "True". +
+
+You could configure two status workers, one has read_only and will be made available to a larger +admin group, the other one will be used fully featured, but only by fewer people: +
+worker.list=jk-watch
+worker.jk-watch.type=status
+worker.jk-watch.read_only=True
+worker.jk-watch.mount=/user/status/jk
+worker.list=jk-manage
+worker.jk-manage.type=status
+worker.jk-manage.mount=/admin/status/jk
+
+Starting with version 1.2.21, a read/write status worker can also be switched temporarily +into read-only mode by the user via a link in the HTML GUI. The user can always switch it +back to read/write. Only a status worker configured as read-only via the "read_only" attribute +is completely safe from applying any changes. +
+
+The other attribute you can use is user. By default this list is empty, which means +no limit on the users. You can set "user" to a comma separated list of user names. If your +web server is configured such that it sends the user names with the request, the status worker +will check, if the name attached with the request is contained in it's "user" list. +
+
+The user list can be split over multiple occurrences of the "user" attribute. +
+
+By default, the user names are matched case sensitively. Starting with version 1.2.21 you can set +the attribute user_case_insensitive to "True". Then the comparison will be made case insensitive. +
+
+ +
Service Availability Rating
+
+
+For load balancing workers the status worker shows some interesting overview information. +It categorises the members of the load balancer into the classes "good", "bad" and degraded". +This feature can be combined with external escalation procedures. Depending on your global +system design and your operating practises your preferred categorisation might vary. +
+
+The categorisation is based on the activation state of the workers (active, disabled or stopped), +which is a pure configuration state, and the runtime state +(OK or ERR with possible substates idle, busy, recovering, probing, and forced recovery) +which only depends on the runtime situation. +
+
+The runtime substates have the following meaning: +
+
+OK (idle): This worker didn't receive any request since the last balancer +maintenance. By default balancer maintenance runs every 60 seconds. The +worker should be OK, but since we didn't have to use it for some time, we +can't be sure. This state has been called N/A before version 1.2.24. +
+
+OK (busy): All connections for this worker are in use for requests. +
+
+ERROR (recovering): The worker was in error state for some time and is now +marked for recovery. The next request suitable for this worker will use it. +
+
+ERROR (probing): After setting the worker to recovering, we received a request +suitable for this worker. This request is now using the worker. +
+
+ERROR (forced recovery): The worker is in error, but we don't have an alternative +worker, so we keep using it. +
+
+
+
+By default the status worker groups into "good" all members, that have activation "active" and +runtime state not equal to "error" with empty substate. +The "bad" group consists of the members, that have either activation +"stopped", or are in runtime state "error" with empty substate. +
+
+Workers that fit neither of the two groups, are considered to be "degraded". +
+
+You can define other rules for the grouping into good, bad and degraded. +The two attributes "good" and "bad" can be populated by a comma-separated list ob single characters or +dot-separated pairs. Each character stands for the first character of one of the possible states "active", +"disabled", "stopped", "ok", "idle", "busy", "recovering" and "error". The additional states "probing" +and "forced recovery" are always rated equivalent to "recovering". +Comma-separated entries will be combined +with logical "or", if you combine a configuration and a runtime state with a dot. the are combined with logical +"and". So the default value for "good" is "a.o,a.i,a.b,a.r", for "bad" it is "e,s". +
+
+The status worker first tries to match against the "bad" definitions, if this doesn't succeed +it tries to match against "good", and finally it chooses "degraded", if no "bad" or "good" match +can be found. +
+
+

Request Parameters

+
+
+This section should help you building automation scripts based on the jk status +management interface. This interface is stable in the sense, that we only expect +to add further parameters in the future. Existing parameters from previous versions +will keep their original semantics. We also expect the output formats XML, Properties +and Text to be kept stable. So please use those, if you want to parse status worker +output in your automation scripts. +
+
Actions
+
+
+The action is determined by the parameter cmd. It can have the values "list", "show", +"edit", "update", "reset", "recover", "version" and "dump". If you omit the cmd parameter, +the default "list" will be used. +All actions except for "list", "refresh", "version" and "dump" need additional parameters. +
+
+The action "dump" has been added in version 1.2.27. +
+
+
Output Format
+
+
+The format is determined by the parameter mime. It can have the values "html", "xml", +"txt" and "prop". If you omit the mime parameter, the default "html" +will be used. The action "edit" (the edit form) does only make sense for "mime=html". +
+
+
Worker Selection
+
+
+Actions that operate on a single worker need one or two additional parameters to select +this worker. The parameter w contains the name of the worker from the worker list. +If an action operates on a member (sub worker) of a load balancer, the parameter w +contains the name of the load balancer worker, and the additional parameter sw contains the +name of the sub worker. +
+
+
Automatic Refresh
+
+
+During automatic refresh, the parameter re contain the refresh interval in seconds. +If you omit this parameter, automatic refresh will be off. +
+
+
Hide Options
+
+
+The parameter opt contains a bit mask of activated options. The default is 0, so +by default no options are activated. The following options exist: +
+
+0x0001: hide members of lb workers +
+
+0x0002: hide URL maps +
+
+0x0004: hide the legend +
+
+0x0008: hide load balancer workers +
+
+0x0010: hide ajp workers +
+
+0x0020: only allow read_only actions for a read/write status worker. +
+
+0x0040: hide load balancer configuration +
+
+0x0080: hide load balancer status summary +
+
+0x0100: hide configuration for ajp and load balancer member workers +
+
+Values 0x0040-0x0100 have been added in version 1.2.27. +
+
+
Data Parameters for the standard Update Action
+
+
+You can use the edit action with a final click to the update button, to change settings of workers. +But you can also make direct calls to the update action. The following request parameters +contain the configuration information, you want to change. First the list for load balancer workers: +
+
+vlr: retries (number) +
+
+vlt: recover_time (seconds) +
+
+vlee: error_escalation_time (seconds) +
+
+vlx: max_reply_timeouts (number) +
+
+vls: sticky_session (0/f/n/off=off, 1/t/y/on=on; case insensitive) +
+
+vlf: sticky_session_force (0/f/n/off=off, 1/t/y/on=on; case insensitive) +
+
+vlm: method (0/r="Requests", 1/t="Traffic", 2/b="Busyness", 3/s="Sessions"; case insensitive, only first character is used) +
+
+vll: lock (0/o="Optimistic", 1/p="Pessimistic"; case insensitive, only first character is used) +
+
+And now the list of parameters you can use to change settings for load balancer members: +
+
+vwa: activation flag (0/a="active", 1/d="disabled", 2/s="stopped"; case insensitive, only first character is used) +
+
+vwf: load balancing factor (integer weight) +
+
+vwn: route for use with sticky sessions (string) +
+
+vwr: redirect to define simple failover rules (string) +
+
+vwc: domain to tell JK about your replication design (string) +
+
+vwd: distance to express preferences (integer) +
+
+Finally the list of parameters you can use to change settings for ajp workers and ajp load balancer members: +
+
+vahst: host (string) +
+
+vaprt: port (number) +
+
+vacpt: connection_pool_timeout (number) +
+
+vact: connect_timeout (number) +
+
+vapt: prepost_timeout (number) +
+
+vart: reply_timeout (number) +
+
+var: retries (number) +
+
+varo: recovery_options (number) +
+
+vamps: max_packet_size (number) +
+
+Note that changing the host name or port will only take effect for new connections. +Already established connections to the old address will still be used. +Nevertheless this feature is interesting, because you can provision load balancer +members with port "0", which will automatically be stopped during startup. Later +when you know the final names and ports, you can set them and they will be +automatically activated. +
+
+The leading character "v" has been added to the parameters in version 1.2.27. +Changing settings for ajp workers has also been introduced in version 1.2.27. +
+
+For the details of all parameters, we refer to the workers.properties Reference. +
+
+
Aspect Editing for Load Balancer Members
+
+
+You can use the edit action to edit all settings for a load balancer or for a +member of a load balancer respectively on one page. If you want to edit one +configuration aspect for all members of a load balancer simultaneously, this +will be triggered by the parameter att. The value of the parameter indicates, +which aspect you want to edit. The list is the same as in the previous section, +except for "vahst" and "vaprt": +"vwa", "vwf", "vwn", "vwr", "vwc", "vwd", "vacpt", "vact", "vapt", "vart", "var", +"varo" and "vamps". But here you +need to put the name into the parameter att, instead of using it as a request +parameter name. +
+
+The values of the common aspect for all the load balancer members will be given +in parameters named "val0", "val1", .... +
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/uriworkermap.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/uriworkermap.html new file mode 100644 index 00000000..3bc39256 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/uriworkermap.html @@ -0,0 +1,377 @@ +The Apache Tomcat Connector - Reference Guide - uriworkermap.properties configuration

The Apache Tomcat Connector - Reference Guide

uriworkermap.properties configuration

Introduction

+
+
+The forwarding of requests from the web server to tomcat gets configured by defining mapping rules. +Such a rule maps requests to workers. The request part of the map is described by a URI pattern, +the worker by it's worker name. +
+
+The so-called uriworkermap file is a mechanism of defining rules, +which works for all web servers. There exist also other web server specific configuration +options for defining rules, which will be mostly discussed on the reference pages for +configuring tomcat connectors for the individual web servers. +
+
+The name of the file is usually uriworkermap.properties, +although this is configurable in the web server. +Please consult the web server specific documentation pages on +how to enable the uriworkermap file. +
+
+The main features supported by the uriworkermap file are +
+
+Support for comments in the rule file. +
+
+Exact and wildchar matches, shortcuts to map a directory and all including content. +
+
+Exclusion rules, disabling of rules and rule priorities. +
+
+Rule extensions, modifying worker behaviour per rule. +
+
+Virtual host integration: uri mapping rules can be expressed per virtual host. +The details are web server specific though. +
+
+Dynamic reloading: The file gets checked periodically for changes. +New versions are automatically reloaded without web server restarts. +
+
+Integration with the status worker. +
+
+The following sections describe these aspects in more detail. +
+

Syntax

+
+
Line format
+
+
+The file has a line based format. There are no continuation characters, +so each rule needs to be defined on a single line. Each rule is a pair consisting +of a URI pattern and a worker name, combined by an equals sign '=': +
+  /myapp=myworker
+
+The URI pattern is case sensitive. +
+
+
Comments, white space
+
+
+All text after and including the character '#' gets ignored and can be used for comments. +Leading and trailing white space gets trimmed around the URI pattern and also around the worker name. +The following definitions are all equivalent: +
+  # This is a white space example
+  /myapp=myworker
+     /myapp=myworker
+  /myapp  =  myworker
+
+
+
+ +
URI patterns
+
+
+Inside the URI pattern three special characters can be used, '*', '?' and '|'. +The character '*' is a wildchar that matches any number of arbitrary characters +in the URI, '?' matches exactly one character. +Each URI pattern has to start with the character '/', or with '*' or with '?', +optionally prefixed by any combination of the modifiers '!' and '-' (see next section). +
+  # Mapping the URI /myapp1 and everything under /myapp1/:
+  /myapp1=myworker-a
+  /myapp1/*=myworker-a
+  # Mapping all URI which end with a common suffix:
+  *.jsp=myworker
+  *.do=myworker
+
+Since the first case of mapping a certain location and everything inside +it is very common, the character '|' gives a handy shortcut: +
+  # Mapping the URI /myapp1 and everything under /myapp1/:
+  /myapp1|/*=myworker-a
+
+The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'. +
+
+

Exclusion, Disabling and Priorities

+
+ +
Exclusions and rule disabling
+
+
+Exclusion rules allows to define exclusions from URI rules, which would forward +requests to tomcat. If the exclusion rule matches, the request will not be forwarded. +This is usually used to serve static content by the web server. +A rule is an exclusion rule, if it is suffixed with '!': +
+  # Mapping the URI /myapp and everything under /myapp/:
+  /myapp|/*=myworker
+  # Exclude the subdirectory static:
+  !/myapp/static|/*=myworker
+  # Exclude some suffixes:
+  !*.html=myworker
+
+An exclusion rule overrides a normal mapping rule only, if the worker names in the +normal rule and in the exclusion rule are the same. Starting with version 1.2.26 of JK +you can apply an exclusion rule to any worker, by using the star character '*' as +the worker name in the exclusion rule. +More complex patterns in exclusion worker names are not allowed. +
+  # Mapping the webapps /myapp1 and /myapp2:
+  /myapp1|/*=myworker1
+  /myapp2|/*=myworker2
+  # Exclude the all subdirectories static for all workers:
+  !/*/static|/*=*
+  # Exclude some suffixes for all workers:
+  !*.html=*
+
+
+
+Rule disabling comes into play, if your web server merges rules from various sources, +and you want to disable any rule defined previously. Since the uriworkermap file gets +reloaded dynamically, you can use this to temporarily disable request forwarding: +A rule gets disabled, if it is suffixed with '-': +
+  # We are not in maintenance.
+  # The maintenance rule got defined somewhere else.
+  -/*=maintenance
+
+Exclusion rules can get disabled as well, then the rule starts with '-!'. +
+
+ +
Mapping priorities
+
+
+The most restrictive URI pattern is applied first. More precisely the URI patterns are +sorted by the number of '/' characters in the pattern (highest number first), and +rules with equal numbers are sorted by their string length (longest first). +
+
+If both distinctions still do not suffice, then the defining source of the rule is considered. +Rules defined in uriworkermap.properties come first, before rules defined by JkMount (Apache) +and inside workers.properties using the mount attribute. +
+
+All disabled rules are ignored. Exclusion rules are applied after all normal rules +have been applied. +
+
+There is no defined behaviour, for the following configuration conflict: +using literally the same URI pattern in the same defining source but with +different worker targets. +
+
+

Rule extensions

+
+
+Rule extensions were added in version 1.2.27 and are not available in earlier versions. +
+
Syntax
+
+
+Rule extensions are additional attributes, that can be attached to any rule. +They are added at the end of the rule, each extension separated by a semicolon: +
+  # This is an extension example,
+  # setting a reply_timeout of 1 minute
+  # only for this mapping.
+  /myapp=myworker;reply_timeout=60000
+  #
+  # This is an example using multiple extensions
+  /myapp=myloadbalancer;reply_timeout=60000;stopped=member1
+
+Attributes set via rule extensions always overwrite conflicting +configurations in the worker definition file. +
+
+
Extension reply_timeout
+
+
+The extension reply_timeout sets a reply timeout for a single mapping rule. +
+  # Setting a reply_timeout of 1 minute
+  # only for this mapping.
+  /myapp=myworker;reply_timeout=60000
+
+It overrides any reply_timeout defined for the worker. The extension allows +to set a reasonable default reply timeout to the worker, and a more relaxed +reply timeout to URLs, which are known to start time intensive tasks. +For a general description of reply timeouts see the +timeouts documentation. +
+
+
Extensions active/disabled/stopped
+
+
+The extensions active, disabled, and stopped +can be used in a load balancer mapping rule to set selected members +of the load balancer into a special activation state. +
+  # Stop forwarding only for member1 of loadbalancer
+  /myapp=myloadbalancer;stopped=member1
+
+Multiple members must be separated by commas or white space: +
+  # Stop forwarding for member01 and member02 of loadbalancer
+  # Disable forwarding for member21 and member22 of loadbalancer
+  /myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22
+
+For the precise meaning of the activation states see the description of +activation. +
+
+
Extension fail_on_status
+
+
+The extension fail_on_status can be used in any rule: +
+  # Send 503 instead of 404 and 500,
+  # and if we get a 503 also set the worker to error
+  /myapp=myworker;fail_on_status=-404,-500,503
+
+Multiple status codes must be separated by commas. +For the precise meaning of the attribute see the description of +fail_on_status. +
+
+
Extension use_server_errors
+
+
+The extension use_server_errors allows to let the web server +send an error page, instead of the backend (e.g. Tomcat) error page. +This is useful, if one wants to send customized error pages, but those are +not part of all web applications. They can then be put onto the web server. +
+
+The value of use_server_errors is a positive number. +Any request send to the backend, that returns with an http status +code bigger or equal to use_server_errors, will +be answered to the client with the error page of the web server +for this status code. +
+  # Use web server error page for all errors
+  /myapp=myworker;use_server_errors=400
+  # Use web server error page only for technical errors
+  /myotherapp=myworker;use_server_errors=500
+
+
+
+

Virtual host integration

+
+ +
IIS
+
+
+When using IIS you can restrict individual rules to special virtual hosts +by prefixing the URI pattern with the virtual host information. +The rules is that the url must be prefixed with the host name. +
+  # Use www.foo.org as virtual host
+  /www.foo.org/myapp/*=myworker
+  # Use www.bar.org as virtual host
+  /www.bar.org/myapp/*=myworker
+  # Normal mapping
+  /mysecondapp/*=myworker
+
+
+
+Note that /mysecondapp/* will be mapped to all virtual hosts present. +In case one needs to prevent the mappings to some particular virtual host then +the exclusion rule must be used +
+  # Make sure the myapp is accessible by all virtual hosts
+  /myapp/*=myworker
+  # Disable mapping myapp for www.foo.org virtual host
+  !/www.foo.org/myapp/*=myworker
+
+
+
+ +
Apache httpd
+
+
+For Apache you can define individual uriworkermap files per virtual host. +The directive JkMountFile can be used in the main server and in each virtual host. +If a virtual host does not use JkMountfile, but JkMountCopy is set to 'On', +then it inherits the JkMountFile from the main server. If you want all vhost to inherit +mounts from the main server, you can set JkMountCopy to 'All' in the main server. +
+
+

Dynamic reloading

+
+
+When a request is being processed, tomcat connectors check the file modification time +of the uriworkermap file. To keep the performance penalty low, this happens only, +if the last check happened at least n seconds ago. +
+
+For Apache you can configure the interval "n" using the directive JkMountFileReload, +for IIS you would use the attribute worker_mount_reload. +The default value is 60 seconds. A value of "0" turns off the reloading. +
+
+If the file changed, it gets reloaded completely. If there exist rules coming +from other sources than the uriworkermap file (e.g. the workers.properties mount +attribute or JkMount with Apache httpd), the new uriworkermap file gets dynamically +merged with these ones exactly like when you do a web server restart. +
+
+Until version 1.2.19 reloading behaved slightly differently: it continuously added +the full contents of the uriworkermap file to the rule mapping. The merging rules +were, that duplicated got eliminated and old rules could be disabled, by defining the +rule as disabled in the new file. Rules never got deleted. +
+

Status worker integration

+
+
+The configuration view of the status worker also shows the various mapping rules. +After each worker's configuration, the rules are listed, that forward to this worker. +The list contains four columns: +
+
+the name of the virtual server +
+
+the URI pattern, prefixed with '-' for a disabled pattern and '!' for an exclusion pattern +
+
+the type of the rule: Exact or Wildchar +
+
+and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +
+
+
+
+Note: The following restriction has been removed starting with version 1.2.26. +
+For Apache httpd, there is an important subtlety: the request going to the status worker +gets executed in the context of some server (main or virtual). The status worker will only show the +mapping rules, that are defined for this server (main or virtual). +
+Until version 1.2.25 the list contained three columns: +
+
+the type of the rule: Exact or Wildchar, eventually prefixed with Disabled or Unmount (for exclusion rules) +
+
+the URI pattern +
+
+and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +
+
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/workers.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/workers.html new file mode 100644 index 00000000..b2f423a9 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/printer/workers.html @@ -0,0 +1,1000 @@ +The Apache Tomcat Connector - Reference Guide - workers.properties configuration

The Apache Tomcat Connector - Reference Guide

workers.properties configuration

Introduction

+
+
+A Tomcat worker is a Tomcat instance that is waiting to execute servlets or any other content +on behalf of some web server. For example, we can have a web server such as +Apache forwarding servlet requests to a Tomcat process (the worker) running behind it. +
+
+The scenario described above is a very simple one; +in fact one can configure multiple Tomcat workers to serve servlets on +behalf of a certain web server. +The reasons for such configuration can be: +
+
+
+We want different contexts to be served by different Tomcat workers to provide a +development environment where all the developers share the same web server but +own a Tomcat worker of their own. +
+
+We want different virtual hosts served by different Tomcat processes to provide a +clear separation between sites belonging to different companies. +
+
+We want to provide load balancing, meaning run multiple Tomcat workers each on a +machine of its own and distribute the requests between them. +
+
+ +
+There are probably more reasons for having multiple workers but I guess that this list is enough... +
+
+Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial +explains how to work with it. +
+

Configuration File Basics

+
+
Defining workers to the Tomcat web server plugin can be done using a properties file +(a sample file named workers.properties is available in the conf/ directory). +
+ +
Format, Comments, Whitespace
+
+
+The lines in the file define properties. The general format is +
+
<name>=<value>
+
+
+Dots are used as part of the name to represent a configuration hierarchy. +
+Invalid directives will be logged during web server startup and prevent the web server +from working properly. Some directives have been deprecated. Although they will +still work, you should replace them by their +successors. +
+
+Some directives are allowed multiple times. This will be explicitly +noted in the tables below. +
+
+Whitespace at the beginning and the end of a property name or value gets ignored. +Comments can be placed in any line and start with a hash sign '#'. +Any line contents behind the hash sign get ignored. +
+
+ +
Global Properties
+
+
+These directives have global scope. +
+
Directive Default Description
worker.list ajp13 +A comma separated list of workers names that the JK will use. When starting up, +the web server plugin will instantiate the workers whose name appears in the +worker.list property, these are also the workers to whom you can map requests. +
+This directive can be used multiple times. +
+
worker.maintain 60 +Worker connection pool maintain interval in seconds. If set to the positive +value JK will scan all connections for all workers specified in worker.list +directive and check if connections needs to be recycled. +
+Furthermore any load balancer does a global maintenance every worker.maintain +seconds. During global maintenance load counters are decayed and workers +in error are checked for recover_time. +
+
+This feature has been added in jk 1.2.13. +
+
+
+ +
Worker Properties
+
+
+Each worker configuration directive consists of three words separated by a dot: +
+
worker.<worker name>.<directive>=<value>
+
+The first word is always worker. +The second word is the worker name you can choose. In the case of load-balancing, +the worker name has an additional meaning. Please consult the +Load Balancer HowTo. +
+
+The name of the worker can contain only the alphanumeric characters +[a-z][A-Z][0-9][_\-] and is case sensitive. +
+
+ +
Variables, Environment Variables
+
+
+You can define and use variables in the workers.properties file. +To define a variable you use the syntax: +
+
<variable_name>=<value>
+
+Dots are allowed in the variable name, but you have to be careful +not to use variable names, that clash with standard directives. +Therefore variable names should never start with "worker.". +
+
+To use a variable, you can insert "$(variable_name)" at any place +on the value side of a property line. If a variable has not been +defined before its use, we will search the process environment for +a variable with the same name and use their value. +
+
+ +
Property Inheritance
+
+
Often one wants to use the same property values for various workers. +To reduce duplication of configuration lines and to ease the maintenance of +the file, you can inherit properties from one worker to another, or even +from a template to real workers. +
+
+The directive "reference" allows to copy configurations between workers +in a hierarchical way. If worker castor sets worker.castor.reference=worker.pollux +then it inherits all properties of pollux, except for the ones that +are explicitly set for castor. +
+
+Please note, that the value of the directive is not only the name of the referred worker, +but the complete prefix including "worker.". +
+
+To use a template worker simply define it like a real worker, but do not add it +to the "worker.list" or as a member to any load balancer. Such a template worker +does not have to contain mandatory directives. This approach is especially useful, +if one has a lot of balanced workers in a load balancer +and these workers share most of their properties. You can set all of these properties +in a template worker, e.g. using the prefix "worker.template1", and then simply +reference those common properties in all balanced workers. +
+
+References can be used to inherit properties over multiple hops in a hierarchical way. +
+
+This feature has been added in jk 1.2.19. +
+
+

List of All Worker Directives

+
+
Mandatory Directives
+
+
Mandatory directives are the one that each worker must contain. Without them the worker will +be unavailable or will misbehave. Those directives will be marked with a strong font in the following tables. +
+
Directive Default Description
type ajp13 +Type of the worker (can be one of ajp13, ajp14, jni, lb or status). The type of the worker +defines the directives that can be applied to the worker. +
AJP13 worker is the preferred worker type that JK uses for communication +between web server and Tomcat. This type of worker uses sockets as communication +channel. For detailed description of the AJP13 protocol stack browse to +AJPv13 protocol specification +
+
JNI workers have been deprecated. They will likely not work. Do not use them.
+
+
+ +
Connection Directives
+
+
Connection directives defines the parameters needed to connect and maintain +the connections pool of persistent connections between JK and remote Tomcat. +
+
Directive Default Description
host localhost +Host name or IP address of the backend Tomcat instance. The remote Tomcat must +support the ajp13 protocol stack. The host name can have a port number +embedded separated by the colon (':') character. +
port 8009 +Port number of the remote Tomcat instance listening for defined protocol requests. +The default value depends on the worker type. For AJP13 workers the default port is +8009, while for AJP14 type of worker that value is 8011. +
socket_timeout 0 +Socket timeout in seconds used for the communication channel between JK and remote host. +If the remote host does not respond inside the timeout specified, JK will generate an error, +and retry again. If set to zero (default) JK will wait for an infinite amount of time +on all socket operations. +
socket_connect_timeout socket_timeout*1000 +Socket connect timeout in milliseconds used for the communication channel between JK and remote host. +If the remote host does not respond inside the timeout specified, JK will generate an error, +and retry again. +
+Note that socket_timeout is in seconds, and +socket_connect_timeout in milliseconds, +so in absolute terms the default socket_connect_timeout is +equal to "socket_timeout. +
+
+This feature has been added in jk 1.2.27. +
+
socket_keepalive False +This directive should be used when you have a firewall between your webserver +and the Tomcat engine, who tend to drop inactive connections. This flag will tell the Operating System +to send KEEP_ALIVE messages on inactive connections (interval depend on global OS settings, +generally 120 minutes), and thus prevent the firewall to cut inactive connections. +To enable keepalive set this property value to True. +
+The problem with Firewall cutting inactive connections is that sometimes, neither webserver or Tomcat +have information about the cut and couldn't handle it. +
+
ping_mode - +This flag determines, under which conditions established +connections are probed to ensure they are still working. +The probe is done with an empty AJP13 packet (CPing) and +expects to receive an appropriate answer (CPong) within +some timeout. +
+The value of the flag can be any combination of the following +flags (multiple values are combined without any separators): +
+
C (connect): If set, the connection will +be probed once after connecting to the backend. The timeout +can be set by connect_timeout. If it is not set, +the value of ping_timeout will be used instead. +
+
P (prepost): If set, the connection will +be probed before sending each request to the backend. The timeout +can be set by prepost_timeout. If it is not set, +the value of ping_timeout will be used instead. +
+
I (interval): If set, the connection will +be probed during the regular internal maintenance cycle, +but only if it is idle longer than +connection_ping_interval. The timeout +can be set by ping_timeout. +
+
A If set, all of the above probes will be used. +
+
+This feature has been added in jk 1.2.27. Connect and +prepost probing were already available via connect_timeout +and prepost_timeout since version jk 1.2.6. +
+
ping_timeout 10000 +Timeout in milliseconds used when waiting for the CPong answer of a +CPing connection probe. The activation of the probes is done via +ping_mode. The timeouts for ping_mode +connect and prepost can be overwritten individually via +connect_timeout and prepost_timeout. +
+For compatibility reasons, CPing/CPong is also used, whenever +connect_timeout or prepost_timeout are set, +even if ping_mode is empty. +
+
+This feature has been added in jk 1.2.27. +
+
connection_ping_interval 0 / (ping_timeout/1000)*10 +When using interval connection probing, connections idle for longer than this +interval in seconds are probed by CPing packets whether they still work. +
Interval probing can be activated either by ping_mode, +or by setting connection_ping_interval to some value bigger +than zero. If you activate interval probing via ping_mode, +then the default value of connection_ping_interval is +(ping_timeout/1000) * 10. Note that ping_timeout +is in milliseconds, and connection_ping_interval in seconds, +so in absolute terms the default connection_ping_interval is +10 times ping_timeout. +
+
+This feature has been added in jk 1.2.27. +
+
connection_pool_size see text +This defines the number of connections made to the AJP backend that +are maintained as a connection pool. +It will limit the number of those connection that each web server child +process can made. +
+Connection pool size property is only used for multi threaded +web servers such as Apache, IIS and Netscape/Sun. The connection_pool_size property +needs to reflect the number of requests one web server process should +be able to send to a backend in parallel. Usually this is the same as +the number of threads per web server process. JK will discover +this number for the Apache web server automatically and set the pool size to +this value. For IIS the default value is 250 (before version 1.2.20: 10), +for Netscape/Sun the default value is 1. +
+
We strongly recommend adjusting this value for IIS and the Netscape/Sun +to the number of requests one web server process should +be able to send to a backend in parallel. You should measure how many connections +you need during peak activity without performance problems, and then add some +percentage depending on your growth rate. Finally you should check, +whether your web server processes are able to use at least as many threads, +as you configured as the pool size. +
+
Do not use connection_pool_size with values higher then 1 on Apache 2.x prefork or Apache 1.3.x!
+
connection_pool_minsize (pool+1)/2 +Minimum size of the connection pool that will be maintained. +
+Its default value is (connection_pool_size+1)/2. +
+
Do not use connection_pool_size with values higher then 1 on Apache 2.x prefork or Apache 1.3.x!
+
+This feature has been added in jk 1.2.16. +
+
connection_pool_timeout 0 +Cache timeout property should be used with connection_pool_minsize to specify how many seconds JK should keep +an inactive socket in cache before closing it. This property should be used to reduce the number of threads +on the Tomcat web server. The default value zero disables the closing (infinite timeout). +
+Each child could open an ajp13 connection if it has to forward a request to Tomcat, creating +a new ajp13 thread on Tomcat side. +
+
+The problem is that after an ajp13 connection is created, the child won't drop it +until killed. And since the webserver will keep its childs/threads running +to handle high-load, even it the child/thread handle only static contents, you could +finish having many unused ajp13 threads on the Tomcat side. +
+
+You should keep this time interval in sync with the connectionTimeout attribute +of your AJP connector in Tomcat's server.xml. Note however, that the value +for mod_jk is given in seconds, the one in server.xml has to use milliseconds. +
+
connection_acquire_timeout retries*retry_interval +Timeout the worker will wait for a free socket in cache before giving up. +
+Its default value is retries * retry_interval. +
+
+This feature has been added in jk 1.2.27. +
+
lbfactor 1 +Only used for a member worker of a load balancer. +
+The integer number lbfactor (load-balancing factor) is +how much we expect this worker to work, or +the worker's work quota. Load balancing factor is compared with other workers +that makes the load balancer. For example if one worker has lb_factor 5 times higher then +other worker, then it will receive five times more requests. +
+
+ +
+ +
Load Balancing Directives
+
+
Load balancer is a virtual worker that does not really communicate with Tomcat workers. +Instead it is responsible for the management of several "real" workers. +The worker is supposed to be a load balancer if it's worker type is lb. +See worker's type directive. +
+
Loadbalancer directives define the parameters needed to create the workers that are +connecting to a remote cluster of backend Tomcat servers. Each cluster node has to +have a worker defined. +
+
+Load balancer management includes: +
+ +
+
+Instantiating the workers in the web server. +
+
+Using the worker's load-balancing factor, perform weighed-round-robin load balancing where +high lbfactor means stronger machine (that is going to handle more requests) +
+
+Keeping requests belonging to the same session executing on the same Tomcat worker. +
+
+Identifying failed Tomcat workers, suspending requests to them and instead fall-backing on +other workers managed by the lb worker. +
+
+ +
+The overall result is that workers managed by the same lb worker are load-balanced +(based on their lbfactor and current user session) and also fall-backed so a single +Tomcat process death will not "kill" the entire site. +
+
+If you want to use session stickiness, you must set different jvmRoute attributes +in the Engine element in Tomcat's server.xml. Furthermore the names of the workers +which are managed by the balancer have to be equal to the jvmRoute of the Tomcat +instance they connect with. +
+
+The restriction on the worker names can be lifted, if you use the route attribute for the workers. +
+
+The following table specifies properties that the lb worker can accept: +
+ +
Directive Default Description
balance_workers - +A comma separated list of workers that the load balancer +need to manage. +
+This directive can be used multiple times for the same load balancer. +
+
+This directive replaces old balanced_workers directive and +can be used only with mod_jk versions 1.2.7 and up. +
+
As long as these workers should only be used via the load balancer worker, +there is no need to also put them into the worker.list property.
+
sticky_session True +Specifies whether requests with SESSION ID's should be routed back to the same +Tomcat worker. If sticky_session is set to True or 1 sessions are sticky, otherwise +sticky_session is set to False. Set sticky_session to False when Tomcat +is using a Session Manager which can persist session data across multiple +instances of Tomcat. +
sticky_session_force False +Specifies whether requests with SESSION ID's for workers that are in error state +should be rejected. If sticky_session_force is set to True or 1 +and the worker that matches that SESSION ID is in error state, client will +receive 500 (Server Error). If set to False or 0 failover on +another worker will be issued with loosing client session. This directive is +used only when you set sticky_session=True. +
+This feature has been added in jk 1.2.9. +
+
method Request +Specifies what method load balancer is using for electing the best worker. +Please note, that session stickiness and perfect load balancing are +conflicting targets, especially when the number +of sessions is small, or the usage of sessions is extremely varying +For huge numbers of sessions this usually is not a problem. +
+Some methods note, that they aggregate in a sliding time window. They add up +accesses, and on each run of the global maintain method, the load counters +get divided by 2. Usually this happens once a minute, depending on the +setting of worker.maintain. The value of the load counters can be inspected +using the status worker. +
+
+If method is set to R[equest] the balancer will use number of requests +to find the best worker. Accesses will be distributed according to the +lbfactor in a sliding time window. This is the default value and should be +working well for most applications. +
+
+If method is set to S[ession] the balancer will use number of sessions +to find the best worker. Accesses will be distributed according to the +lbfactor in a sliding time window. Because the balancer does not keep any state, +it actually does not know the number of sessions. Instead it counts each request +without a session cookie or URL encoding as a new session. This method will neither +know, when a session is being invalidated, nor will it correct its load numbers +according to session timeouts or worker failover. This method should be used, +if sessions are your limiting resource, e.g. when you only have limited memory +and your sessions need a lot of memory. +
+
+If set to T[raffic] the balancer will use +the network traffic between JK and Tomcat to find the best worker. +Accesses will be distributed according to the lbfactor in a sliding time window. +This method should be used, if network to and from the backends is your +limiting resource. +
+
+If set to B[usyness] the balancer will +pick the worker with the lowest current load, based on how many requests the +worker is currently serving. This number is divided by the workers lbfactor, +and the lowest value (least busy) worker is picked. This method is especially +interesting, if your request take a long time to process, like for a download +application. +
+
+This feature has been added in jk 1.2.9. +The Session method has been added in jk 1.2.20. +
+
lock Optimistic +Specifies what lock method the load balancer will use for synchronising +shared memory runtime data. +If lock is set to O[ptimistic] balancer will not use shared memory lock +to find the best worker. If set to P[essimistic] balancer will use +shared memory lock. The balancer will work more accurately in case of +Pessimistic locking, but can slow down the average response time. +
+This feature has been added in jk 1.2.13. +
+
retries 2 +
This directive also exists for normal workers. +For those it has a different meaning.
+If the load balancer can not get a valid member worker or in case of failover, +it will try again a number of times given by retries. +Before each retry, it will make a pause define by retry_interval directive. +
+Until version 1.2.16 the default value was 3. +
+
+ +
+ +
Status Worker Directives
+
+
+The status worker does not communicate with Tomcat. +Instead it is responsible for the load balancer management. +
+
Directive Default Description
css - +Specifies the url for cascading stylesheet to use. +
read_only False +A status worker with read_only=True will not allow any operations, +that change the runtime state or configuration of the other workers. +These are edit/update/reset/recover. +
+This feature has been added in jk 1.2.20. +
+
user - +It is a list of users +which gets compared to the user name authenticated by the web server. +If the name is not contained in this list, access is denied. Per +default the list is empty and then access is allowed to anybody. +
+This directive can be used multiple times. +
+
+This feature has been added in jk 1.2.20. +
+
user_case_insensitive False +By default, the user names are matched case sensitively. You can set +user_case_insensitive=True to make the comparison case insensitive. +This may be especially useful on the Windows platform. +
+This feature has been added in jk 1.2.21. +
+
good a.o,a.n,a.b,a.r +For every load balancer worker, the status worker shows a summary +of the state of its members. There are three such states, +"good", "bad" and "degraded". +
+These states are determined depending on the activation of the members +(active, disabled, stopped) and their runtime state +(ok, n/a, busy, recovering, probing, forced recovery, error). +By default, members are assumed to be "good", if their activation +is "active" and their runtime state is not "error". +
+
+You can change this mapping, by assigning a list of values to the +attribute "good". Each value gives a possible match for the members, +and one match suffices. Each value is either a single character, or two +characters combined with a dot ".". The single characters are the +first characters in the words "active", "disabled", "stopped", +"ok", "na", "busy", "recovering", "error". The additional states "probing" +and "forced recovery" are always rated equivalent to "recovering". +If a value consists only +of a single character, then all members with this activation or runtime +state will be assumed good. A combination of an activation and a runtime +state concatenated with a dot "." does only apply to a member, that has +exactly this activation and state. +
+
+Members of a load balancer will first be matched against the state "bad", +if they don't match, the state "good" will be tried, and if they +still don't match, their state will be "degraded". +
+
+This directive can be used multiple times. +
+
+This feature has been added in jk 1.2.20. +
+
bad s,e +See: "good". +
+By default, members are assumed to be "bad", if their activation +is "stopped" or their runtime state is "error". +
+
+This directive can be used multiple times. +
+
+This feature has been added in jk 1.2.20. +
+
prefix worker +The prefix, which will be used by the status worker +when producing properties output (mime=prop). +Each property key will be prefixed by this value. +
+This feature has been added in jk 1.2.20. +
+
ns jk: +This directive can be used to customise the XML output from the +status worker. If set to - no namespace will be used. +
+This feature has been added in jk 1.2.20. +
+
xmlns - +This directive can be used to customise the XML output from the +status worker. If set to - no xmlns will be used. +
+Default value is set to xmlns:jk="http://tomcat.apache.org" +
+
+This feature has been added in jk 1.2.20. +
+
doctype - +This directive can be used to customise the XML output from the +status worker. This value will be inserted to the output xml +after the xml header. +
+This feature has been added in jk 1.2.20. +
+
+
+ +
Advanced Worker Directives
+
+
+This table lists more advanced configuration options. Most of them only apply to +some types of workers. We use the abbreviations AJP for ajp13/ajp14 workers +used directly via the workers.list, LB for load balancer workers, +and SUB for the workers used indirectly in a load balancer worker +as a sub worker or member. +
+
Directive Worker Type Default Description
connect_timeout AJP,SUB 0 +Connect timeout property told webserver to send a PING request on ajp13 connection after +connection is established. The parameter is the delay in milliseconds to wait for the PONG reply. +The default value zero disables the timeout (infinite timeout). +
+This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and require ajp13 +ping/pong support which has been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+. +Disabled by default. +
+
prepost_timeout AJP,SUB 0 +Prepost timeout property told webserver to send a PING request on ajp13 connection before +forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply. +The default value zero disables the timeout (infinite timeout). +
+This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and require ajp13 +ping/pong support which has been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+. +Disabled by default. +
+
reply_timeout AJP,SUB 0 +The parameter is the number of milliseconds to wait for success during a read event. +So this is not a timeout for the complete answer time of a request, but only +for the maximum time between two packets received from Tomcat. Usually the longest +pause is between sending the request and getting the first packet of the response. +
+If the timeout passes without any data received from Tomcat, the webserver will +no longer wait for the rest of the response and send an error to the client (browser). +Usually this does not mean, that the request is also aborted on the Tomcat backend. +If the worker is a member of a load balancer, the load balancer might place the +worker into an error state and retry the request on another member. +See also max_reply_timeouts, retries and recovery_options. +
+
+By default (value zero) the webserver will wait forever which could be an issue for you. +If you set a reply_timeout, adjust it carefully if you have long running servlets. +
+
+The reply_timeout can be overwritten using the Apache httpd environment variable +JK_REPLY_TIMEOUT. +
+
+This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and works on all +servlet engines supporting ajp13. The variable JK_REPLY_TIMEOUT has been added in version 1.2.27. +
+
retries AJP,SUB 2 +
This directive also exists for load balancer workers. +For those it has a different meaning.
+The maximum number of times that the worker will send a request to Tomcat +in case of a communication error. Each retry will be done over another +connection. The first time already gets counted, so retries=2 means +one retry after error. Before a retry, the worker waits for a configurable +sleeping time. +
+See also the attribute recovery_options for a more fine-grained control +of retries and retry_interval for the sleep time configuration. +
+
+Until version 1.2.16 the default value was 3. +
+
retry_interval AJP,SUB 100 +The amount of time in milliseconds the worker sleeps before doing any retry. +
+This features has been added in jk 1.2.27. +
+
recovery_options AJP,SUB 0 +Recovery options influence, how we should handle retries, +in case we detect a problem with Tomcat. +How often we will retry is controlled by the attribute retries. +
+This attribute is a bit mask. The following bits are allowed:
+1: don't recover if Tomcat failed after getting the request
+2: don't recover if Tomcat failed after sending the headers to client
+4: close the connection to Tomcat, if we detect an error when writing back +the answer to the client (browser)
+8: always recover requests for HTTP method HEAD (even if Bits 1 or 2 are set)
+16: always recover requests for HTTP method GET (even if Bits 1 or 2 are set)
+
+
+This features has been added in jk 1.2.6. +Option 4 has been added in version 1.2.16, +options 8 and 16 in version 1.2.24. +
+
fail_on_status AJP,SUB 0 +Set this value to the HTTP status code that will cause a worker to fail +if returned from Servlet container. Use this directive to deal with +cases when the servlet container can temporary return non-200 responses +for a short amount of time, e.g during redeployment. +
+The error page, headers and status codes of the original response will not be send back +to the client. Instead the request will result in a 503 response. +If the worker is a member of a load balancer, the member will +be put into an error state. Request failover and worker recovery will be handled +with the usual load balancer procedures. +
+
+This feature has been added in jk 1.2.20. +
+
+Starting with jk 1.2.22 it is possible to define multiple +status codes separated by space or comma characters. +For example: worker.xxx.fail_on_status=500,503 +
+
+Starting with jk 1.2.25 you can also tell the load +balancer to not put a member into an error state, if a +response returned with one of the status codes in +fail_on_status. This feature gets enabled, by putting a minus sign in +front of those status codes. +For example: worker.xxx.fail_on_status=-404,-500,503 +
+
max_packet_size AJP,SUB 8192 +This attribute sets the maximal AJP packet size in Bytes. +The maximum value is 65536. If you change it from the default, +you must also change the packetSize attribute of your AJP +connector on the Tomcat side! The attribute packetSize is only available +in Tomcat 5.5.20+ and 6.0.2+. +
+Normally it is not necessary to change the maximum packet size. Problems +with the default value have been reported when sending certificates or +certificate chains. +
+
+This feature has been added in jk 1.2.19. +
+
mount AJP,LB - +Space delimited list of uri maps the worker should handle. It is only used, +if the worker is included in worker.list. +
+This directive can be used multiple times for the same worker. +
+
secret AJP,LB,SUB - +You can set a secret keyword on the Tomcat AJP Connector. Then only requests +from workers with the same secret keyword will be accepted. +
+Use request.secret="secret key word" in your Tomcat AJP Connector configuration. +
+
+If you set a secret on a load balancer, all its members will inherit this secret. +
+
+This feature has been added in jk 1.2.12. +
+
max_reply_timeouts LB 0 +If you use a reply_timeout for the members of a load balancer worker, +and you want to tolerate a few requests taking longer than reply_timeout, +you can set this attribute to some positive value. +
+Long running requests will still time out after reply_timeout milliseconds waiting for +data, but the corresponding member worker will only be put into an error state, +if more than max_reply_timeouts requests have timed out. +More precisely, the counter for those bad requests will be divided by two, +whenever the load balancer does its internal maintenance (by default every 60 +seconds). +
+
+This features has been added in jk 1.2.24 to make reply_timeout less +sensitive for sporadic long running requests. +
+
recover_time LB 60 +The recover time is the time in seconds the load balancer will not try +to use a worker, after it went into error state. Only after this time has passed, +a worker in error state will be marked as in recovering, so that it will be +tried for new requests. +
+This interval is not checked every time a request is being processed. +Instead it is being checked during global maintenance. The time between two +runs of global maintenance is controlled by worker.maintain. +
+
+Do not set recover_time to a very short time unless you understand the implications. +Every recovery attempt for a worker in error is done by a real request! +
+
error_escalation_time LB recover_time / 2 +Setting a member of a load balancer into an error state is quite serious. E.g. +it means that if you need stickyness, all access to the sessions of the +respective node is blocked. +
+Some types of error detection do not provide a precise information, whether +a node is completely broken or not. In those cases an LB will not immediately +put the node into the error state. Only when there have been no successful +responses for error_escalation_time seconds after such an error, +will the node be put into error state. +
+
+This features has been added in jk 1.2.28. +
+
activation SUB Active +Using this directive, a balanced worker of a load balancer +can be configured as disabled or stopped. A disabled worker only gets +requests, which belong to sessions for that worker. A stopped +worker does not get any requests. Users of a stopped worker will +loose their sessions, unless session replication via clustering is used. +
+Use d or D to disable and s or S to stop. +If this directive is not present the deprecated directives +"disabled" or "stopped" are used. +
+
+This flag can be changed at runtime using status worker. +
+
+This feature has been added in jk 1.2.19. +
+
route SUB worker name +Normally the name of a balanced worker in a load balancer is equal to the jvmRoute +of the corresponding Tomcat instance. If you want to include a worker corresponding +to a Tomcat instance into several load balancers with different balancing configuration +(e.g. disabled, stopped) you can use this attribute. +
+Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and +set the route attribute of the worker equal to the jvmRoute of the target Tomcat instance. +
+
+If this attribute is left empty, the name of the worker will be used. +
+
+This attribute can be changed at runtime using status worker. +
+
+If the route name contains a period, the part before the first period will be +used as domain name, unless domain is set explicitly. +
+
+This feature has been added in jk 1.2.16.
+The automatic domain rule has been added in jk 1.2.20.
+The attribute has been renamed from jvm_route to route in jk 1.2.20. +
+
distance SUB 0 +An integer number to express preferences between +the balanced workers of an lb worker. +A load balancer will never choose some balanced worker +in case there is another usable worker with lower distance. +
+Only in case all workers below a given distance are in error, disabled or stopped, +workers of a larger distance are eligible for balancing. +
+
+This feature has been added in jk 1.2.16. +
+
domain SUB - +Domain directive can be used only when the worker is a member of the load balancer. +Workers that share the same domain name are treated as single worker. If sticky_session +is used, then the domain name is used as session route. +
+This directive is used for large system with more then 6 Tomcats, to be able +to cluster the Tomcats in two groups and thus lowering the session replication +transfer between them. +
+
+This feature has been added in jk 1.2.8. +
+
redirect SUB - +Set to the name of the preferred failover worker. If worker matching +SESSION ID is in error state then the redirect worker will be used instead. +It will be used even if being disabled, thus offering hot standby. +
+If you explicitly set a route via the "route" attribute, you must set "redirect" +to this route of the preferred failover worker and not to its name. +
+
+This feature has been added in jk 1.2.9. +
+
session_cookie LB JSESSIONID +The name of the cookie that contains the routing identifier needed for session stickyness. +The routing identifier is everything after a "." character in the value of the cookie. +
+This feature has been added in jk 1.2.27. +
+
session_path LB ;jsessionid +The name of the path parameter that contains the routing identifier needed for +session stickyness. The routing identifier is everything after a "." character in the value +of the path parameter. +
+This feature has been added in jk 1.2.27. +
+
+
+ +
Deprecated Worker Directives
+
+
The following directives have been deprecated in the past. We include their documentation +in case you need to use an older version of mod_jk. We urge you to update and not use +them any more. Please migrate your existing configurations. +
+
Directive Successor Default Description
cachesize connection_pool_size see text +
This directive has been deprecated since 1.2.16.
+Cachesize defines the number of connections made to the AJP backend that +are maintained as a connection pool. +It will limit the number of those connection that each web server child +process can make. +
+Cachesize property is used only for multi threaded +web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property +should reflect the number of threads per child process. JK will discover +the number of threads per child process on Apache 2 web server with worker-mpm and set +its default value to match the ThreadsPerChild Apache directive. For IIS the default +value is 10. For other web servers than Apache or IIS this value has to be set manually. +
+
Do not use cachesize with values higher then 1 on Apache 2.x prefork or Apache 1.3.x!
+
cache_timeout connection_pool_timeout 0 +
This directive has been deprecated since 1.2.16.
+Cache timeout property should be used with cachesize to specify how to time JK should keep +an open socket in cache before closing it. This property should be used to reduce the number of threads +on the Tomcat web server. +
+Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating +a new ajp13 thread on Tomcat side. +
+
+The problem is that after an ajp13 connection is created, the child won't drop it +until killed. And since the webserver will keep its childs/threads running +to handle high-load, even it the child/thread handle only static contents, you could +finish having many unused ajp13 threads on the Tomcat side. +
+
recycle_timeout connection_pool_timeout 0 +
This directive has been deprecated since 1.2.16.
+The number of seconds that told webserver to cut an ajp13 connection after some time of +inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be +closed if it was not used for the configured time. +It's a good way to ensure that there won't too old threads living on Tomcat side, +with the extra cost you need to reopen the socket next time a request be forwarded. +This property is very similar to cache_timeout but works also in non-cache mode. +If set to value zero (default) no recycle will took place. +
balanced_workers balance_workers - +
This directive has been deprecated since 1.2.7.
+A comma separated list of workers that the load balancer +need to manage. +
disabled activation False +
This directive has been deprecated since 1.2.19.
+If set to True or 1 the worker will be disabled if member +of load balancer. This flag can be changed at runtime using status worker. +
+This feature has been added in jk 1.2.9. +
+
stopped activation False +
This directive has been deprecated since 1.2.19.
+If set to True or 1 the worker will be stopped if member +of load balancer. The flag is needed for stop complete traffic of a sticky session +worker. It is only useful, when you have a cluster that replicated the sessions. +This flag can be changed at runtime using status worker. +
+This feature has been added in jk 1.2.11. +
+
jvm_route route worker name +
This directive has been deprecated since 1.2.20.
+Normally the name of a balanced worker in a load balancer is equal to the jvmRoute +of the corresponding Tomcat instance. If you want to include a worker corresponding +to a Tomcat instance into several load balancers with different balancing configuration +(e.g. disabled, stopped) you can use this attribute. +
+Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and +set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance. +
+
+If this attribute is left empty, the name of the worker will be used. +
+
+This attribute can be changed at runtime using status worker. +
+
+This feature has been added in jk 1.2.16. +
+
+
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/status.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/status.html new file mode 100644 index 00000000..6754bc2a --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/status.html @@ -0,0 +1,547 @@ +The Apache Tomcat Connector - Reference Guide - Status Worker Reference

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Reference Guide

Status Worker Reference

print-friendly
version +

Introduction

+
+
+Tomcat Connectors has a special type of worker, the so-called status worker. +The status worker does not forward requests to Tomcat instances. Instead it allows +to retrieve status and configuration information at runtime, +and furthermore to change many configuration items dynamically. This can be done +via a simple embedded web interface. +
+
+The status worker is especially powerful, when used together with load balancing workers. +
+
+This document does not explain the HTML user interface of the status worker. +Until now it is very simple, so just go ahead and use it. This doc instead +tries to explain the less obvious features of the status worker. We also will give a +complete coverage of the various request parameters and their meaning, so that you can +include the status worker in your automation scripts. +
+
+The documentation of the status worker starts with jk 1.2.20 +
+

Usage Patterns

+
+
Actions
+
+
+The status worker knows about six actions. +
+
+list: lists the configurations and runtime information of all configured workers. +The output will be grouped by global information first (version data), then load balancer +information, after that AJP worker information and finally the legend. For load balancers, +there will be a summary part, and after that details for each member worker. For all workers, +we also include the URL mappings (forward definitions). +
+
+show: the same as list, but only shows data for one chosen worker +
+
+edit: produces a form to edit configuration data for a chosen worker. There is a +special subtype of "edit", that makes it easy to change one attribute for all members of +a load balancer, e.g. their activation state. +
+
+update: commit changes made in an edit form. Caution: the changes will not be +persisted to the configuration files. As soon as your restart your web server, all changes +made through the status worker will be lost! On the other hand, the changes done by the status +worker will be applied during runtime without a restart of the web server. +
+
+reset: reset all runtime statistics for a worker. +
+
+recover: Mark a member of a load balancer, that is in error state, for immediate recovery. +
+
+version: only show version information of the web server and the JK software +
+
+dump: list the original workers configuration. Caution: the dump will only contain +the configuration that was used during startup. Any changes applied later by the dynamic management +interface of the status worker itself will not be contained in this dump. +The dump action has been added in version 1.2.27. +
+
+
+
+ +
Output Format
+
+
+For most actions you can choose between 4 output formats. +
+
+HTML: Used interactively with a browser +
+
+XML: Mostly useful for automation, when your scripting environment is XML friendly. +This format has rich structure information, but does not work line based, so you would really +like to use it together with XML tools. +
+
+Properties: This format is a line based format, that conforms to the rules of Java +property files. Most structure information is contained in the hierarchical key. For information, +that is of configuration nature, the format should produce lines very similar to the ones you can +use in workers.properties. It will not produce a complete configuration file! +
+
+Text: A simple textual output format. +
+
+The "edit" action does only make sense for the HTML output type. +
+
+ +
User Interface Features
+
+
+In the HTML view, there is an automatic refresh feature, implemented via the meta refresh +option of HTML. Once you start the automatic refresh, the UI will will respect it for all actions +except edit, update and maintain. Even if you navigate through one of those, the automatic refresh +will start again as soon as you come back to one of the other actions. +
+
+Many parts of the HTML page can be minimised, if they are not interesting for you. There are a couple +of "Hide" links, which will collapse parts of the information. The feature exists for the following +blocks of information: +
+
+Legend: Do not show the legend for the information presented in "list" and "show" actions +
+
+URI mappings: Do not show the URI mapping for the workers +
+
+Load Balancing Workers: Do not show workers of type "lb" +
+
+AJP Workers: Do not show workers of type ajp +
+
+Balancer Members: Do not show detailed information concerning each member of load balancers +
+
+Load Balancer Configuration: Do not show configuration data for load balancers +
+
+Load Balancer Summary: Do not show status summary for load balancers +
+
+AJP Configuration: Do not show configuration data for ajp workers load balancer members +
+
+The last three minimisation features have been added in version 1.2.27. +
+
+ +
Special Considerations concerning URL Maps and Virtual Hosts
+
+
+Note: The following restriction has been removed starting with version 1.2.26. +
+
+The Apache module mod_jk makes use of the internal Apache httpd infrastructure concerning +virtual hosts. The downside of this is, that the status worker can only show URL maps, for +the virtual host it is defined in. It is not able to reach the configuration objects +for other virtual hosts. Of course you can define a status worker in any virtual host you +are using. All information presented apart from the URL maps will be the same, independent +of the virtual host the status worker has been called in. +
+
+ +
Logging
+
+
+The status worker will log changes made to the configuration with log level "info" to the usual +JK log file. Invalid requests will be logged with log level "warn". If you want to report some +broken behaviour, log file content of level "debug" or even "trace" will be useful. +
+
+ +

Configuration

+
+
Basic Configuration
+
+
+The basic configuration of a status worker is very similar to that of a usual ajp worker. +You need to specify a name for the worker, and the URLs you want to map to it. The first +part of the configuration happens in the workers.properties file. We define a worker named +mystatus of type status: +
+worker.list=mystatus
+worker.mystatus.type=status
+
+Then we define a URL, which should be mapped to this worker, i.e. the URL we use +to reach the functionality of the status worker. You can use any method mod_jk supports +for the web server of your choice. Possibilities are maps inside uriworkermap.properties, +an additional mount attribute in workers.properties, or in Apache JkMount. Here's an +example for a uriworkermap.properties line: +
+/private/admin/mystatus=mystatus
+
+The URI pattern is case sensitive. +
+
+As you will learn in the following sections, the status worker is very powerful. You should +use the usual authentication and authorisation methods of your web server to secure this URL. +
+
+You can also define multiple instances of the status worker, by using different names and URL mappings. +For instance you might want to configure them individually +and then allow special groups of people to use them +
+
+ +
Output Customisation
+
+
+There are a couple of attributes for the workers.properties entries, which allow to customise +various aspects of the output of the status worker. +
+
+The attribute css can be set to the URL of a stylesheet: +
+worker.mystatus.css=/private/admin/static/mystatus.css
+
+When writing HTML output, the status worker then includes the line +
+<link rel="stylesheet" type="text/css" href="/private/admin/static/mystatus.css" />
+
+There is no sample stylesheet included with the mod_jk release, and by default the attribute css +is empty, so no stylesheet reference will be included in the pages. The HTML code +of the status worker output pages does not include any class attributes. If you like to contribute a +stylesheet or improvements to the HTML layout, please contact us on the tomcat developers list. +
+
+The properties output format can be customised via the attribute prefix. The names of all +properties the status worker does output, will begin with this prefix. The default is "worker". +
+
+Several attributes influence the format when writing XML output. +The attribute ns allows to set a namespace prefix, that will be used for every status worker+element. +The default is "jk:". Setting it to "-" disables the namespace prefix. +
+
+With the attribute xmlns you can map the prefix to a namespace URL. The default value +is xmlns:jk="http://tomcat.apache.org". Setting it to "-" disables the output of the URL. +
+
+Finally you can specify an XML document type via the attribute doctype. The specified string will +be inserted at the beginning of the document, directly after the xml header. The default is empty. +
+
+ +
Securing Access
+
+
+We urge you to use the builtin access control features of your web server to control +access to the status worker URLs you have chosen. Nevertheless two configuration +attributes of status workers are helpful. The attribute "read_only" disables all features of +the status worker, that can be used to change configurations or runtime status of the other workers. +A read_only status worker will not allow access to the edit, update, reset or recover actions. +The default value is "False", ie. read/write. To enable read_only you need to set it to "True". +
+
+You could configure two status workers, one has read_only and will be made available to a larger +admin group, the other one will be used fully featured, but only by fewer people: +
+worker.list=jk-watch
+worker.jk-watch.type=status
+worker.jk-watch.read_only=True
+worker.jk-watch.mount=/user/status/jk
+worker.list=jk-manage
+worker.jk-manage.type=status
+worker.jk-manage.mount=/admin/status/jk
+
+Starting with version 1.2.21, a read/write status worker can also be switched temporarily +into read-only mode by the user via a link in the HTML GUI. The user can always switch it +back to read/write. Only a status worker configured as read-only via the "read_only" attribute +is completely safe from applying any changes. +
+
+The other attribute you can use is user. By default this list is empty, which means +no limit on the users. You can set "user" to a comma separated list of user names. If your +web server is configured such that it sends the user names with the request, the status worker +will check, if the name attached with the request is contained in it's "user" list. +
+
+The user list can be split over multiple occurrences of the "user" attribute. +
+
+By default, the user names are matched case sensitively. Starting with version 1.2.21 you can set +the attribute user_case_insensitive to "True". Then the comparison will be made case insensitive. +
+
+ +
Service Availability Rating
+
+
+For load balancing workers the status worker shows some interesting overview information. +It categorises the members of the load balancer into the classes "good", "bad" and degraded". +This feature can be combined with external escalation procedures. Depending on your global +system design and your operating practises your preferred categorisation might vary. +
+
+The categorisation is based on the activation state of the workers (active, disabled or stopped), +which is a pure configuration state, and the runtime state +(OK or ERR with possible substates idle, busy, recovering, probing, and forced recovery) +which only depends on the runtime situation. +
+
+The runtime substates have the following meaning: +
+
+OK (idle): This worker didn't receive any request since the last balancer +maintenance. By default balancer maintenance runs every 60 seconds. The +worker should be OK, but since we didn't have to use it for some time, we +can't be sure. This state has been called N/A before version 1.2.24. +
+
+OK (busy): All connections for this worker are in use for requests. +
+
+ERROR (recovering): The worker was in error state for some time and is now +marked for recovery. The next request suitable for this worker will use it. +
+
+ERROR (probing): After setting the worker to recovering, we received a request +suitable for this worker. This request is now using the worker. +
+
+ERROR (forced recovery): The worker is in error, but we don't have an alternative +worker, so we keep using it. +
+
+
+
+By default the status worker groups into "good" all members, that have activation "active" and +runtime state not equal to "error" with empty substate. +The "bad" group consists of the members, that have either activation +"stopped", or are in runtime state "error" with empty substate. +
+
+Workers that fit neither of the two groups, are considered to be "degraded". +
+
+You can define other rules for the grouping into good, bad and degraded. +The two attributes "good" and "bad" can be populated by a comma-separated list ob single characters or +dot-separated pairs. Each character stands for the first character of one of the possible states "active", +"disabled", "stopped", "ok", "idle", "busy", "recovering" and "error". The additional states "probing" +and "forced recovery" are always rated equivalent to "recovering". +Comma-separated entries will be combined +with logical "or", if you combine a configuration and a runtime state with a dot. the are combined with logical +"and". So the default value for "good" is "a.o,a.i,a.b,a.r", for "bad" it is "e,s". +
+
+The status worker first tries to match against the "bad" definitions, if this doesn't succeed +it tries to match against "good", and finally it chooses "degraded", if no "bad" or "good" match +can be found. +
+
+

Request Parameters

+
+
+This section should help you building automation scripts based on the jk status +management interface. This interface is stable in the sense, that we only expect +to add further parameters in the future. Existing parameters from previous versions +will keep their original semantics. We also expect the output formats XML, Properties +and Text to be kept stable. So please use those, if you want to parse status worker +output in your automation scripts. +
+
Actions
+
+
+The action is determined by the parameter cmd. It can have the values "list", "show", +"edit", "update", "reset", "recover", "version" and "dump". If you omit the cmd parameter, +the default "list" will be used. +All actions except for "list", "refresh", "version" and "dump" need additional parameters. +
+
+The action "dump" has been added in version 1.2.27. +
+
+
Output Format
+
+
+The format is determined by the parameter mime. It can have the values "html", "xml", +"txt" and "prop". If you omit the mime parameter, the default "html" +will be used. The action "edit" (the edit form) does only make sense for "mime=html". +
+
+
Worker Selection
+
+
+Actions that operate on a single worker need one or two additional parameters to select +this worker. The parameter w contains the name of the worker from the worker list. +If an action operates on a member (sub worker) of a load balancer, the parameter w +contains the name of the load balancer worker, and the additional parameter sw contains the +name of the sub worker. +
+
+
Automatic Refresh
+
+
+During automatic refresh, the parameter re contain the refresh interval in seconds. +If you omit this parameter, automatic refresh will be off. +
+
+
Hide Options
+
+
+The parameter opt contains a bit mask of activated options. The default is 0, so +by default no options are activated. The following options exist: +
+
+0x0001: hide members of lb workers +
+
+0x0002: hide URL maps +
+
+0x0004: hide the legend +
+
+0x0008: hide load balancer workers +
+
+0x0010: hide ajp workers +
+
+0x0020: only allow read_only actions for a read/write status worker. +
+
+0x0040: hide load balancer configuration +
+
+0x0080: hide load balancer status summary +
+
+0x0100: hide configuration for ajp and load balancer member workers +
+
+Values 0x0040-0x0100 have been added in version 1.2.27. +
+
+
Data Parameters for the standard Update Action
+
+
+You can use the edit action with a final click to the update button, to change settings of workers. +But you can also make direct calls to the update action. The following request parameters +contain the configuration information, you want to change. First the list for load balancer workers: +
+
+vlr: retries (number) +
+
+vlt: recover_time (seconds) +
+
+vlee: error_escalation_time (seconds) +
+
+vlx: max_reply_timeouts (number) +
+
+vls: sticky_session (0/f/n/off=off, 1/t/y/on=on; case insensitive) +
+
+vlf: sticky_session_force (0/f/n/off=off, 1/t/y/on=on; case insensitive) +
+
+vlm: method (0/r="Requests", 1/t="Traffic", 2/b="Busyness", 3/s="Sessions"; case insensitive, only first character is used) +
+
+vll: lock (0/o="Optimistic", 1/p="Pessimistic"; case insensitive, only first character is used) +
+
+And now the list of parameters you can use to change settings for load balancer members: +
+
+vwa: activation flag (0/a="active", 1/d="disabled", 2/s="stopped"; case insensitive, only first character is used) +
+
+vwf: load balancing factor (integer weight) +
+
+vwn: route for use with sticky sessions (string) +
+
+vwr: redirect to define simple failover rules (string) +
+
+vwc: domain to tell JK about your replication design (string) +
+
+vwd: distance to express preferences (integer) +
+
+Finally the list of parameters you can use to change settings for ajp workers and ajp load balancer members: +
+
+vahst: host (string) +
+
+vaprt: port (number) +
+
+vacpt: connection_pool_timeout (number) +
+
+vact: connect_timeout (number) +
+
+vapt: prepost_timeout (number) +
+
+vart: reply_timeout (number) +
+
+var: retries (number) +
+
+varo: recovery_options (number) +
+
+vamps: max_packet_size (number) +
+
+Note that changing the host name or port will only take effect for new connections. +Already established connections to the old address will still be used. +Nevertheless this feature is interesting, because you can provision load balancer +members with port "0", which will automatically be stopped during startup. Later +when you know the final names and ports, you can set them and they will be +automatically activated. +
+
+The leading character "v" has been added to the parameters in version 1.2.27. +Changing settings for ajp workers has also been introduced in version 1.2.27. +
+
+For the details of all parameters, we refer to the workers.properties Reference. +
+
+
Aspect Editing for Load Balancer Members
+
+
+You can use the edit action to edit all settings for a load balancer or for a +member of a load balancer respectively on one page. If you want to edit one +configuration aspect for all members of a load balancer simultaneously, this +will be triggered by the parameter att. The value of the parameter indicates, +which aspect you want to edit. The list is the same as in the previous section, +except for "vahst" and "vaprt": +"vwa", "vwf", "vwn", "vwr", "vwc", "vwd", "vacpt", "vact", "vapt", "vart", "var", +"varo" and "vamps". But here you +need to put the name into the parameter att, instead of using it as a request +parameter name. +
+
+The values of the common aspect for all the load balancer members will be given +in parameters named "val0", "val1", .... +
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/uriworkermap.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/uriworkermap.html new file mode 100644 index 00000000..f70ee475 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/uriworkermap.html @@ -0,0 +1,378 @@ +The Apache Tomcat Connector - Reference Guide - uriworkermap.properties configuration

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Reference Guide

uriworkermap.properties configuration

print-friendly
version +

Introduction

+
+
+The forwarding of requests from the web server to tomcat gets configured by defining mapping rules. +Such a rule maps requests to workers. The request part of the map is described by a URI pattern, +the worker by it's worker name. +
+
+The so-called uriworkermap file is a mechanism of defining rules, +which works for all web servers. There exist also other web server specific configuration +options for defining rules, which will be mostly discussed on the reference pages for +configuring tomcat connectors for the individual web servers. +
+
+The name of the file is usually uriworkermap.properties, +although this is configurable in the web server. +Please consult the web server specific documentation pages on +how to enable the uriworkermap file. +
+
+The main features supported by the uriworkermap file are +
+
+Support for comments in the rule file. +
+
+Exact and wildchar matches, shortcuts to map a directory and all including content. +
+
+Exclusion rules, disabling of rules and rule priorities. +
+
+Rule extensions, modifying worker behaviour per rule. +
+
+Virtual host integration: uri mapping rules can be expressed per virtual host. +The details are web server specific though. +
+
+Dynamic reloading: The file gets checked periodically for changes. +New versions are automatically reloaded without web server restarts. +
+
+Integration with the status worker. +
+
+The following sections describe these aspects in more detail. +
+

Syntax

+
+
Line format
+
+
+The file has a line based format. There are no continuation characters, +so each rule needs to be defined on a single line. Each rule is a pair consisting +of a URI pattern and a worker name, combined by an equals sign '=': +
+  /myapp=myworker
+
+The URI pattern is case sensitive. +
+
+
Comments, white space
+
+
+All text after and including the character '#' gets ignored and can be used for comments. +Leading and trailing white space gets trimmed around the URI pattern and also around the worker name. +The following definitions are all equivalent: +
+  # This is a white space example
+  /myapp=myworker
+     /myapp=myworker
+  /myapp  =  myworker
+
+
+
+ +
URI patterns
+
+
+Inside the URI pattern three special characters can be used, '*', '?' and '|'. +The character '*' is a wildchar that matches any number of arbitrary characters +in the URI, '?' matches exactly one character. +Each URI pattern has to start with the character '/', or with '*' or with '?', +optionally prefixed by any combination of the modifiers '!' and '-' (see next section). +
+  # Mapping the URI /myapp1 and everything under /myapp1/:
+  /myapp1=myworker-a
+  /myapp1/*=myworker-a
+  # Mapping all URI which end with a common suffix:
+  *.jsp=myworker
+  *.do=myworker
+
+Since the first case of mapping a certain location and everything inside +it is very common, the character '|' gives a handy shortcut: +
+  # Mapping the URI /myapp1 and everything under /myapp1/:
+  /myapp1|/*=myworker-a
+
+The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'. +
+
+

Exclusion, Disabling and Priorities

+
+ +
Exclusions and rule disabling
+
+
+Exclusion rules allows to define exclusions from URI rules, which would forward +requests to tomcat. If the exclusion rule matches, the request will not be forwarded. +This is usually used to serve static content by the web server. +A rule is an exclusion rule, if it is suffixed with '!': +
+  # Mapping the URI /myapp and everything under /myapp/:
+  /myapp|/*=myworker
+  # Exclude the subdirectory static:
+  !/myapp/static|/*=myworker
+  # Exclude some suffixes:
+  !*.html=myworker
+
+An exclusion rule overrides a normal mapping rule only, if the worker names in the +normal rule and in the exclusion rule are the same. Starting with version 1.2.26 of JK +you can apply an exclusion rule to any worker, by using the star character '*' as +the worker name in the exclusion rule. +More complex patterns in exclusion worker names are not allowed. +
+  # Mapping the webapps /myapp1 and /myapp2:
+  /myapp1|/*=myworker1
+  /myapp2|/*=myworker2
+  # Exclude the all subdirectories static for all workers:
+  !/*/static|/*=*
+  # Exclude some suffixes for all workers:
+  !*.html=*
+
+
+
+Rule disabling comes into play, if your web server merges rules from various sources, +and you want to disable any rule defined previously. Since the uriworkermap file gets +reloaded dynamically, you can use this to temporarily disable request forwarding: +A rule gets disabled, if it is suffixed with '-': +
+  # We are not in maintenance.
+  # The maintenance rule got defined somewhere else.
+  -/*=maintenance
+
+Exclusion rules can get disabled as well, then the rule starts with '-!'. +
+
+ +
Mapping priorities
+
+
+The most restrictive URI pattern is applied first. More precisely the URI patterns are +sorted by the number of '/' characters in the pattern (highest number first), and +rules with equal numbers are sorted by their string length (longest first). +
+
+If both distinctions still do not suffice, then the defining source of the rule is considered. +Rules defined in uriworkermap.properties come first, before rules defined by JkMount (Apache) +and inside workers.properties using the mount attribute. +
+
+All disabled rules are ignored. Exclusion rules are applied after all normal rules +have been applied. +
+
+There is no defined behaviour, for the following configuration conflict: +using literally the same URI pattern in the same defining source but with +different worker targets. +
+
+

Rule extensions

+
+
+Rule extensions were added in version 1.2.27 and are not available in earlier versions. +
+
Syntax
+
+
+Rule extensions are additional attributes, that can be attached to any rule. +They are added at the end of the rule, each extension separated by a semicolon: +
+  # This is an extension example,
+  # setting a reply_timeout of 1 minute
+  # only for this mapping.
+  /myapp=myworker;reply_timeout=60000
+  #
+  # This is an example using multiple extensions
+  /myapp=myloadbalancer;reply_timeout=60000;stopped=member1
+
+Attributes set via rule extensions always overwrite conflicting +configurations in the worker definition file. +
+
+
Extension reply_timeout
+
+
+The extension reply_timeout sets a reply timeout for a single mapping rule. +
+  # Setting a reply_timeout of 1 minute
+  # only for this mapping.
+  /myapp=myworker;reply_timeout=60000
+
+It overrides any reply_timeout defined for the worker. The extension allows +to set a reasonable default reply timeout to the worker, and a more relaxed +reply timeout to URLs, which are known to start time intensive tasks. +For a general description of reply timeouts see the +timeouts documentation. +
+
+
Extensions active/disabled/stopped
+
+
+The extensions active, disabled, and stopped +can be used in a load balancer mapping rule to set selected members +of the load balancer into a special activation state. +
+  # Stop forwarding only for member1 of loadbalancer
+  /myapp=myloadbalancer;stopped=member1
+
+Multiple members must be separated by commas or white space: +
+  # Stop forwarding for member01 and member02 of loadbalancer
+  # Disable forwarding for member21 and member22 of loadbalancer
+  /myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22
+
+For the precise meaning of the activation states see the description of +activation. +
+
+
Extension fail_on_status
+
+
+The extension fail_on_status can be used in any rule: +
+  # Send 503 instead of 404 and 500,
+  # and if we get a 503 also set the worker to error
+  /myapp=myworker;fail_on_status=-404,-500,503
+
+Multiple status codes must be separated by commas. +For the precise meaning of the attribute see the description of +fail_on_status. +
+
+
Extension use_server_errors
+
+
+The extension use_server_errors allows to let the web server +send an error page, instead of the backend (e.g. Tomcat) error page. +This is useful, if one wants to send customized error pages, but those are +not part of all web applications. They can then be put onto the web server. +
+
+The value of use_server_errors is a positive number. +Any request send to the backend, that returns with an http status +code bigger or equal to use_server_errors, will +be answered to the client with the error page of the web server +for this status code. +
+  # Use web server error page for all errors
+  /myapp=myworker;use_server_errors=400
+  # Use web server error page only for technical errors
+  /myotherapp=myworker;use_server_errors=500
+
+
+
+

Virtual host integration

+
+ +
IIS
+
+
+When using IIS you can restrict individual rules to special virtual hosts +by prefixing the URI pattern with the virtual host information. +The rules is that the url must be prefixed with the host name. +
+  # Use www.foo.org as virtual host
+  /www.foo.org/myapp/*=myworker
+  # Use www.bar.org as virtual host
+  /www.bar.org/myapp/*=myworker
+  # Normal mapping
+  /mysecondapp/*=myworker
+
+
+
+Note that /mysecondapp/* will be mapped to all virtual hosts present. +In case one needs to prevent the mappings to some particular virtual host then +the exclusion rule must be used +
+  # Make sure the myapp is accessible by all virtual hosts
+  /myapp/*=myworker
+  # Disable mapping myapp for www.foo.org virtual host
+  !/www.foo.org/myapp/*=myworker
+
+
+
+ +
Apache httpd
+
+
+For Apache you can define individual uriworkermap files per virtual host. +The directive JkMountFile can be used in the main server and in each virtual host. +If a virtual host does not use JkMountfile, but JkMountCopy is set to 'On', +then it inherits the JkMountFile from the main server. If you want all vhost to inherit +mounts from the main server, you can set JkMountCopy to 'All' in the main server. +
+
+

Dynamic reloading

+
+
+When a request is being processed, tomcat connectors check the file modification time +of the uriworkermap file. To keep the performance penalty low, this happens only, +if the last check happened at least n seconds ago. +
+
+For Apache you can configure the interval "n" using the directive JkMountFileReload, +for IIS you would use the attribute worker_mount_reload. +The default value is 60 seconds. A value of "0" turns off the reloading. +
+
+If the file changed, it gets reloaded completely. If there exist rules coming +from other sources than the uriworkermap file (e.g. the workers.properties mount +attribute or JkMount with Apache httpd), the new uriworkermap file gets dynamically +merged with these ones exactly like when you do a web server restart. +
+
+Until version 1.2.19 reloading behaved slightly differently: it continuously added +the full contents of the uriworkermap file to the rule mapping. The merging rules +were, that duplicated got eliminated and old rules could be disabled, by defining the +rule as disabled in the new file. Rules never got deleted. +
+

Status worker integration

+
+
+The configuration view of the status worker also shows the various mapping rules. +After each worker's configuration, the rules are listed, that forward to this worker. +The list contains four columns: +
+
+the name of the virtual server +
+
+the URI pattern, prefixed with '-' for a disabled pattern and '!' for an exclusion pattern +
+
+the type of the rule: Exact or Wildchar +
+
+and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +
+
+
+
+Note: The following restriction has been removed starting with version 1.2.26. +
+For Apache httpd, there is an important subtlety: the request going to the status worker +gets executed in the context of some server (main or virtual). The status worker will only show the +mapping rules, that are defined for this server (main or virtual). +
+Until version 1.2.25 the list contained three columns: +
+
+the type of the rule: Exact or Wildchar, eventually prefixed with Disabled or Unmount (for exclusion rules) +
+
+the URI pattern +
+
+and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +
+
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/workers.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/workers.html new file mode 100644 index 00000000..68b996a7 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/reference/workers.html @@ -0,0 +1,1001 @@ +The Apache Tomcat Connector - Reference Guide - workers.properties configuration

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Reference Guide

workers.properties configuration

print-friendly
version +

Introduction

+
+
+A Tomcat worker is a Tomcat instance that is waiting to execute servlets or any other content +on behalf of some web server. For example, we can have a web server such as +Apache forwarding servlet requests to a Tomcat process (the worker) running behind it. +
+
+The scenario described above is a very simple one; +in fact one can configure multiple Tomcat workers to serve servlets on +behalf of a certain web server. +The reasons for such configuration can be: +
+
+
+We want different contexts to be served by different Tomcat workers to provide a +development environment where all the developers share the same web server but +own a Tomcat worker of their own. +
+
+We want different virtual hosts served by different Tomcat processes to provide a +clear separation between sites belonging to different companies. +
+
+We want to provide load balancing, meaning run multiple Tomcat workers each on a +machine of its own and distribute the requests between them. +
+
+ +
+There are probably more reasons for having multiple workers but I guess that this list is enough... +
+
+Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial +explains how to work with it. +
+

Configuration File Basics

+
+
Defining workers to the Tomcat web server plugin can be done using a properties file +(a sample file named workers.properties is available in the conf/ directory). +
+ +
Format, Comments, Whitespace
+
+
+The lines in the file define properties. The general format is +
+
<name>=<value>
+
+
+Dots are used as part of the name to represent a configuration hierarchy. +
+Invalid directives will be logged during web server startup and prevent the web server +from working properly. Some directives have been deprecated. Although they will +still work, you should replace them by their +successors. +
+
+Some directives are allowed multiple times. This will be explicitly +noted in the tables below. +
+
+Whitespace at the beginning and the end of a property name or value gets ignored. +Comments can be placed in any line and start with a hash sign '#'. +Any line contents behind the hash sign get ignored. +
+
+ +
Global Properties
+
+
+These directives have global scope. +
+
Directive Default Description
worker.list ajp13 +A comma separated list of workers names that the JK will use. When starting up, +the web server plugin will instantiate the workers whose name appears in the +worker.list property, these are also the workers to whom you can map requests. +
+This directive can be used multiple times. +
+
worker.maintain 60 +Worker connection pool maintain interval in seconds. If set to the positive +value JK will scan all connections for all workers specified in worker.list +directive and check if connections needs to be recycled. +
+Furthermore any load balancer does a global maintenance every worker.maintain +seconds. During global maintenance load counters are decayed and workers +in error are checked for recover_time. +
+
+This feature has been added in jk 1.2.13. +
+
+
+ +
Worker Properties
+
+
+Each worker configuration directive consists of three words separated by a dot: +
+
worker.<worker name>.<directive>=<value>
+
+The first word is always worker. +The second word is the worker name you can choose. In the case of load-balancing, +the worker name has an additional meaning. Please consult the +Load Balancer HowTo. +
+
+The name of the worker can contain only the alphanumeric characters +[a-z][A-Z][0-9][_\-] and is case sensitive. +
+
+ +
Variables, Environment Variables
+
+
+You can define and use variables in the workers.properties file. +To define a variable you use the syntax: +
+
<variable_name>=<value>
+
+Dots are allowed in the variable name, but you have to be careful +not to use variable names, that clash with standard directives. +Therefore variable names should never start with "worker.". +
+
+To use a variable, you can insert "$(variable_name)" at any place +on the value side of a property line. If a variable has not been +defined before its use, we will search the process environment for +a variable with the same name and use their value. +
+
+ +
Property Inheritance
+
+
Often one wants to use the same property values for various workers. +To reduce duplication of configuration lines and to ease the maintenance of +the file, you can inherit properties from one worker to another, or even +from a template to real workers. +
+
+The directive "reference" allows to copy configurations between workers +in a hierarchical way. If worker castor sets worker.castor.reference=worker.pollux +then it inherits all properties of pollux, except for the ones that +are explicitly set for castor. +
+
+Please note, that the value of the directive is not only the name of the referred worker, +but the complete prefix including "worker.". +
+
+To use a template worker simply define it like a real worker, but do not add it +to the "worker.list" or as a member to any load balancer. Such a template worker +does not have to contain mandatory directives. This approach is especially useful, +if one has a lot of balanced workers in a load balancer +and these workers share most of their properties. You can set all of these properties +in a template worker, e.g. using the prefix "worker.template1", and then simply +reference those common properties in all balanced workers. +
+
+References can be used to inherit properties over multiple hops in a hierarchical way. +
+
+This feature has been added in jk 1.2.19. +
+
+

List of All Worker Directives

+
+
Mandatory Directives
+
+
Mandatory directives are the one that each worker must contain. Without them the worker will +be unavailable or will misbehave. Those directives will be marked with a strong font in the following tables. +
+
Directive Default Description
type ajp13 +Type of the worker (can be one of ajp13, ajp14, jni, lb or status). The type of the worker +defines the directives that can be applied to the worker. +
AJP13 worker is the preferred worker type that JK uses for communication +between web server and Tomcat. This type of worker uses sockets as communication +channel. For detailed description of the AJP13 protocol stack browse to +AJPv13 protocol specification +
+
JNI workers have been deprecated. They will likely not work. Do not use them.
+
+
+ +
Connection Directives
+
+
Connection directives defines the parameters needed to connect and maintain +the connections pool of persistent connections between JK and remote Tomcat. +
+
Directive Default Description
host localhost +Host name or IP address of the backend Tomcat instance. The remote Tomcat must +support the ajp13 protocol stack. The host name can have a port number +embedded separated by the colon (':') character. +
port 8009 +Port number of the remote Tomcat instance listening for defined protocol requests. +The default value depends on the worker type. For AJP13 workers the default port is +8009, while for AJP14 type of worker that value is 8011. +
socket_timeout 0 +Socket timeout in seconds used for the communication channel between JK and remote host. +If the remote host does not respond inside the timeout specified, JK will generate an error, +and retry again. If set to zero (default) JK will wait for an infinite amount of time +on all socket operations. +
socket_connect_timeout socket_timeout*1000 +Socket connect timeout in milliseconds used for the communication channel between JK and remote host. +If the remote host does not respond inside the timeout specified, JK will generate an error, +and retry again. +
+Note that socket_timeout is in seconds, and +socket_connect_timeout in milliseconds, +so in absolute terms the default socket_connect_timeout is +equal to "socket_timeout. +
+
+This feature has been added in jk 1.2.27. +
+
socket_keepalive False +This directive should be used when you have a firewall between your webserver +and the Tomcat engine, who tend to drop inactive connections. This flag will tell the Operating System +to send KEEP_ALIVE messages on inactive connections (interval depend on global OS settings, +generally 120 minutes), and thus prevent the firewall to cut inactive connections. +To enable keepalive set this property value to True. +
+The problem with Firewall cutting inactive connections is that sometimes, neither webserver or Tomcat +have information about the cut and couldn't handle it. +
+
ping_mode - +This flag determines, under which conditions established +connections are probed to ensure they are still working. +The probe is done with an empty AJP13 packet (CPing) and +expects to receive an appropriate answer (CPong) within +some timeout. +
+The value of the flag can be any combination of the following +flags (multiple values are combined without any separators): +
+
C (connect): If set, the connection will +be probed once after connecting to the backend. The timeout +can be set by connect_timeout. If it is not set, +the value of ping_timeout will be used instead. +
+
P (prepost): If set, the connection will +be probed before sending each request to the backend. The timeout +can be set by prepost_timeout. If it is not set, +the value of ping_timeout will be used instead. +
+
I (interval): If set, the connection will +be probed during the regular internal maintenance cycle, +but only if it is idle longer than +connection_ping_interval. The timeout +can be set by ping_timeout. +
+
A If set, all of the above probes will be used. +
+
+This feature has been added in jk 1.2.27. Connect and +prepost probing were already available via connect_timeout +and prepost_timeout since version jk 1.2.6. +
+
ping_timeout 10000 +Timeout in milliseconds used when waiting for the CPong answer of a +CPing connection probe. The activation of the probes is done via +ping_mode. The timeouts for ping_mode +connect and prepost can be overwritten individually via +connect_timeout and prepost_timeout. +
+For compatibility reasons, CPing/CPong is also used, whenever +connect_timeout or prepost_timeout are set, +even if ping_mode is empty. +
+
+This feature has been added in jk 1.2.27. +
+
connection_ping_interval 0 / (ping_timeout/1000)*10 +When using interval connection probing, connections idle for longer than this +interval in seconds are probed by CPing packets whether they still work. +
Interval probing can be activated either by ping_mode, +or by setting connection_ping_interval to some value bigger +than zero. If you activate interval probing via ping_mode, +then the default value of connection_ping_interval is +(ping_timeout/1000) * 10. Note that ping_timeout +is in milliseconds, and connection_ping_interval in seconds, +so in absolute terms the default connection_ping_interval is +10 times ping_timeout. +
+
+This feature has been added in jk 1.2.27. +
+
connection_pool_size see text +This defines the number of connections made to the AJP backend that +are maintained as a connection pool. +It will limit the number of those connection that each web server child +process can made. +
+Connection pool size property is only used for multi threaded +web servers such as Apache, IIS and Netscape/Sun. The connection_pool_size property +needs to reflect the number of requests one web server process should +be able to send to a backend in parallel. Usually this is the same as +the number of threads per web server process. JK will discover +this number for the Apache web server automatically and set the pool size to +this value. For IIS the default value is 250 (before version 1.2.20: 10), +for Netscape/Sun the default value is 1. +
+
We strongly recommend adjusting this value for IIS and the Netscape/Sun +to the number of requests one web server process should +be able to send to a backend in parallel. You should measure how many connections +you need during peak activity without performance problems, and then add some +percentage depending on your growth rate. Finally you should check, +whether your web server processes are able to use at least as many threads, +as you configured as the pool size. +
+
Do not use connection_pool_size with values higher then 1 on Apache 2.x prefork or Apache 1.3.x!
+
connection_pool_minsize (pool+1)/2 +Minimum size of the connection pool that will be maintained. +
+Its default value is (connection_pool_size+1)/2. +
+
Do not use connection_pool_size with values higher then 1 on Apache 2.x prefork or Apache 1.3.x!
+
+This feature has been added in jk 1.2.16. +
+
connection_pool_timeout 0 +Cache timeout property should be used with connection_pool_minsize to specify how many seconds JK should keep +an inactive socket in cache before closing it. This property should be used to reduce the number of threads +on the Tomcat web server. The default value zero disables the closing (infinite timeout). +
+Each child could open an ajp13 connection if it has to forward a request to Tomcat, creating +a new ajp13 thread on Tomcat side. +
+
+The problem is that after an ajp13 connection is created, the child won't drop it +until killed. And since the webserver will keep its childs/threads running +to handle high-load, even it the child/thread handle only static contents, you could +finish having many unused ajp13 threads on the Tomcat side. +
+
+You should keep this time interval in sync with the connectionTimeout attribute +of your AJP connector in Tomcat's server.xml. Note however, that the value +for mod_jk is given in seconds, the one in server.xml has to use milliseconds. +
+
connection_acquire_timeout retries*retry_interval +Timeout the worker will wait for a free socket in cache before giving up. +
+Its default value is retries * retry_interval. +
+
+This feature has been added in jk 1.2.27. +
+
lbfactor 1 +Only used for a member worker of a load balancer. +
+The integer number lbfactor (load-balancing factor) is +how much we expect this worker to work, or +the worker's work quota. Load balancing factor is compared with other workers +that makes the load balancer. For example if one worker has lb_factor 5 times higher then +other worker, then it will receive five times more requests. +
+
+ +
+ +
Load Balancing Directives
+
+
Load balancer is a virtual worker that does not really communicate with Tomcat workers. +Instead it is responsible for the management of several "real" workers. +The worker is supposed to be a load balancer if it's worker type is lb. +See worker's type directive. +
+
Loadbalancer directives define the parameters needed to create the workers that are +connecting to a remote cluster of backend Tomcat servers. Each cluster node has to +have a worker defined. +
+
+Load balancer management includes: +
+ +
+
+Instantiating the workers in the web server. +
+
+Using the worker's load-balancing factor, perform weighed-round-robin load balancing where +high lbfactor means stronger machine (that is going to handle more requests) +
+
+Keeping requests belonging to the same session executing on the same Tomcat worker. +
+
+Identifying failed Tomcat workers, suspending requests to them and instead fall-backing on +other workers managed by the lb worker. +
+
+ +
+The overall result is that workers managed by the same lb worker are load-balanced +(based on their lbfactor and current user session) and also fall-backed so a single +Tomcat process death will not "kill" the entire site. +
+
+If you want to use session stickiness, you must set different jvmRoute attributes +in the Engine element in Tomcat's server.xml. Furthermore the names of the workers +which are managed by the balancer have to be equal to the jvmRoute of the Tomcat +instance they connect with. +
+
+The restriction on the worker names can be lifted, if you use the route attribute for the workers. +
+
+The following table specifies properties that the lb worker can accept: +
+ +
Directive Default Description
balance_workers - +A comma separated list of workers that the load balancer +need to manage. +
+This directive can be used multiple times for the same load balancer. +
+
+This directive replaces old balanced_workers directive and +can be used only with mod_jk versions 1.2.7 and up. +
+
As long as these workers should only be used via the load balancer worker, +there is no need to also put them into the worker.list property.
+
sticky_session True +Specifies whether requests with SESSION ID's should be routed back to the same +Tomcat worker. If sticky_session is set to True or 1 sessions are sticky, otherwise +sticky_session is set to False. Set sticky_session to False when Tomcat +is using a Session Manager which can persist session data across multiple +instances of Tomcat. +
sticky_session_force False +Specifies whether requests with SESSION ID's for workers that are in error state +should be rejected. If sticky_session_force is set to True or 1 +and the worker that matches that SESSION ID is in error state, client will +receive 500 (Server Error). If set to False or 0 failover on +another worker will be issued with loosing client session. This directive is +used only when you set sticky_session=True. +
+This feature has been added in jk 1.2.9. +
+
method Request +Specifies what method load balancer is using for electing the best worker. +Please note, that session stickiness and perfect load balancing are +conflicting targets, especially when the number +of sessions is small, or the usage of sessions is extremely varying +For huge numbers of sessions this usually is not a problem. +
+Some methods note, that they aggregate in a sliding time window. They add up +accesses, and on each run of the global maintain method, the load counters +get divided by 2. Usually this happens once a minute, depending on the +setting of worker.maintain. The value of the load counters can be inspected +using the status worker. +
+
+If method is set to R[equest] the balancer will use number of requests +to find the best worker. Accesses will be distributed according to the +lbfactor in a sliding time window. This is the default value and should be +working well for most applications. +
+
+If method is set to S[ession] the balancer will use number of sessions +to find the best worker. Accesses will be distributed according to the +lbfactor in a sliding time window. Because the balancer does not keep any state, +it actually does not know the number of sessions. Instead it counts each request +without a session cookie or URL encoding as a new session. This method will neither +know, when a session is being invalidated, nor will it correct its load numbers +according to session timeouts or worker failover. This method should be used, +if sessions are your limiting resource, e.g. when you only have limited memory +and your sessions need a lot of memory. +
+
+If set to T[raffic] the balancer will use +the network traffic between JK and Tomcat to find the best worker. +Accesses will be distributed according to the lbfactor in a sliding time window. +This method should be used, if network to and from the backends is your +limiting resource. +
+
+If set to B[usyness] the balancer will +pick the worker with the lowest current load, based on how many requests the +worker is currently serving. This number is divided by the workers lbfactor, +and the lowest value (least busy) worker is picked. This method is especially +interesting, if your request take a long time to process, like for a download +application. +
+
+This feature has been added in jk 1.2.9. +The Session method has been added in jk 1.2.20. +
+
lock Optimistic +Specifies what lock method the load balancer will use for synchronising +shared memory runtime data. +If lock is set to O[ptimistic] balancer will not use shared memory lock +to find the best worker. If set to P[essimistic] balancer will use +shared memory lock. The balancer will work more accurately in case of +Pessimistic locking, but can slow down the average response time. +
+This feature has been added in jk 1.2.13. +
+
retries 2 +
This directive also exists for normal workers. +For those it has a different meaning.
+If the load balancer can not get a valid member worker or in case of failover, +it will try again a number of times given by retries. +Before each retry, it will make a pause define by retry_interval directive. +
+Until version 1.2.16 the default value was 3. +
+
+ +
+ +
Status Worker Directives
+
+
+The status worker does not communicate with Tomcat. +Instead it is responsible for the load balancer management. +
+
Directive Default Description
css - +Specifies the url for cascading stylesheet to use. +
read_only False +A status worker with read_only=True will not allow any operations, +that change the runtime state or configuration of the other workers. +These are edit/update/reset/recover. +
+This feature has been added in jk 1.2.20. +
+
user - +It is a list of users +which gets compared to the user name authenticated by the web server. +If the name is not contained in this list, access is denied. Per +default the list is empty and then access is allowed to anybody. +
+This directive can be used multiple times. +
+
+This feature has been added in jk 1.2.20. +
+
user_case_insensitive False +By default, the user names are matched case sensitively. You can set +user_case_insensitive=True to make the comparison case insensitive. +This may be especially useful on the Windows platform. +
+This feature has been added in jk 1.2.21. +
+
good a.o,a.n,a.b,a.r +For every load balancer worker, the status worker shows a summary +of the state of its members. There are three such states, +"good", "bad" and "degraded". +
+These states are determined depending on the activation of the members +(active, disabled, stopped) and their runtime state +(ok, n/a, busy, recovering, probing, forced recovery, error). +By default, members are assumed to be "good", if their activation +is "active" and their runtime state is not "error". +
+
+You can change this mapping, by assigning a list of values to the +attribute "good". Each value gives a possible match for the members, +and one match suffices. Each value is either a single character, or two +characters combined with a dot ".". The single characters are the +first characters in the words "active", "disabled", "stopped", +"ok", "na", "busy", "recovering", "error". The additional states "probing" +and "forced recovery" are always rated equivalent to "recovering". +If a value consists only +of a single character, then all members with this activation or runtime +state will be assumed good. A combination of an activation and a runtime +state concatenated with a dot "." does only apply to a member, that has +exactly this activation and state. +
+
+Members of a load balancer will first be matched against the state "bad", +if they don't match, the state "good" will be tried, and if they +still don't match, their state will be "degraded". +
+
+This directive can be used multiple times. +
+
+This feature has been added in jk 1.2.20. +
+
bad s,e +See: "good". +
+By default, members are assumed to be "bad", if their activation +is "stopped" or their runtime state is "error". +
+
+This directive can be used multiple times. +
+
+This feature has been added in jk 1.2.20. +
+
prefix worker +The prefix, which will be used by the status worker +when producing properties output (mime=prop). +Each property key will be prefixed by this value. +
+This feature has been added in jk 1.2.20. +
+
ns jk: +This directive can be used to customise the XML output from the +status worker. If set to - no namespace will be used. +
+This feature has been added in jk 1.2.20. +
+
xmlns - +This directive can be used to customise the XML output from the +status worker. If set to - no xmlns will be used. +
+Default value is set to xmlns:jk="http://tomcat.apache.org" +
+
+This feature has been added in jk 1.2.20. +
+
doctype - +This directive can be used to customise the XML output from the +status worker. This value will be inserted to the output xml +after the xml header. +
+This feature has been added in jk 1.2.20. +
+
+
+ +
Advanced Worker Directives
+
+
+This table lists more advanced configuration options. Most of them only apply to +some types of workers. We use the abbreviations AJP for ajp13/ajp14 workers +used directly via the workers.list, LB for load balancer workers, +and SUB for the workers used indirectly in a load balancer worker +as a sub worker or member. +
+
Directive Worker Type Default Description
connect_timeout AJP,SUB 0 +Connect timeout property told webserver to send a PING request on ajp13 connection after +connection is established. The parameter is the delay in milliseconds to wait for the PONG reply. +The default value zero disables the timeout (infinite timeout). +
+This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and require ajp13 +ping/pong support which has been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+. +Disabled by default. +
+
prepost_timeout AJP,SUB 0 +Prepost timeout property told webserver to send a PING request on ajp13 connection before +forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply. +The default value zero disables the timeout (infinite timeout). +
+This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and require ajp13 +ping/pong support which has been implemented on Tomcat 3.3.2+, 4.1.28+ and 5.0.13+. +Disabled by default. +
+
reply_timeout AJP,SUB 0 +The parameter is the number of milliseconds to wait for success during a read event. +So this is not a timeout for the complete answer time of a request, but only +for the maximum time between two packets received from Tomcat. Usually the longest +pause is between sending the request and getting the first packet of the response. +
+If the timeout passes without any data received from Tomcat, the webserver will +no longer wait for the rest of the response and send an error to the client (browser). +Usually this does not mean, that the request is also aborted on the Tomcat backend. +If the worker is a member of a load balancer, the load balancer might place the +worker into an error state and retry the request on another member. +See also max_reply_timeouts, retries and recovery_options. +
+
+By default (value zero) the webserver will wait forever which could be an issue for you. +If you set a reply_timeout, adjust it carefully if you have long running servlets. +
+
+The reply_timeout can be overwritten using the Apache httpd environment variable +JK_REPLY_TIMEOUT. +
+
+This features has been added in jk 1.2.6 to avoid problem with hung Tomcat's and works on all +servlet engines supporting ajp13. The variable JK_REPLY_TIMEOUT has been added in version 1.2.27. +
+
retries AJP,SUB 2 +
This directive also exists for load balancer workers. +For those it has a different meaning.
+The maximum number of times that the worker will send a request to Tomcat +in case of a communication error. Each retry will be done over another +connection. The first time already gets counted, so retries=2 means +one retry after error. Before a retry, the worker waits for a configurable +sleeping time. +
+See also the attribute recovery_options for a more fine-grained control +of retries and retry_interval for the sleep time configuration. +
+
+Until version 1.2.16 the default value was 3. +
+
retry_interval AJP,SUB 100 +The amount of time in milliseconds the worker sleeps before doing any retry. +
+This features has been added in jk 1.2.27. +
+
recovery_options AJP,SUB 0 +Recovery options influence, how we should handle retries, +in case we detect a problem with Tomcat. +How often we will retry is controlled by the attribute retries. +
+This attribute is a bit mask. The following bits are allowed:
+1: don't recover if Tomcat failed after getting the request
+2: don't recover if Tomcat failed after sending the headers to client
+4: close the connection to Tomcat, if we detect an error when writing back +the answer to the client (browser)
+8: always recover requests for HTTP method HEAD (even if Bits 1 or 2 are set)
+16: always recover requests for HTTP method GET (even if Bits 1 or 2 are set)
+
+
+This features has been added in jk 1.2.6. +Option 4 has been added in version 1.2.16, +options 8 and 16 in version 1.2.24. +
+
fail_on_status AJP,SUB 0 +Set this value to the HTTP status code that will cause a worker to fail +if returned from Servlet container. Use this directive to deal with +cases when the servlet container can temporary return non-200 responses +for a short amount of time, e.g during redeployment. +
+The error page, headers and status codes of the original response will not be send back +to the client. Instead the request will result in a 503 response. +If the worker is a member of a load balancer, the member will +be put into an error state. Request failover and worker recovery will be handled +with the usual load balancer procedures. +
+
+This feature has been added in jk 1.2.20. +
+
+Starting with jk 1.2.22 it is possible to define multiple +status codes separated by space or comma characters. +For example: worker.xxx.fail_on_status=500,503 +
+
+Starting with jk 1.2.25 you can also tell the load +balancer to not put a member into an error state, if a +response returned with one of the status codes in +fail_on_status. This feature gets enabled, by putting a minus sign in +front of those status codes. +For example: worker.xxx.fail_on_status=-404,-500,503 +
+
max_packet_size AJP,SUB 8192 +This attribute sets the maximal AJP packet size in Bytes. +The maximum value is 65536. If you change it from the default, +you must also change the packetSize attribute of your AJP +connector on the Tomcat side! The attribute packetSize is only available +in Tomcat 5.5.20+ and 6.0.2+. +
+Normally it is not necessary to change the maximum packet size. Problems +with the default value have been reported when sending certificates or +certificate chains. +
+
+This feature has been added in jk 1.2.19. +
+
mount AJP,LB - +Space delimited list of uri maps the worker should handle. It is only used, +if the worker is included in worker.list. +
+This directive can be used multiple times for the same worker. +
+
secret AJP,LB,SUB - +You can set a secret keyword on the Tomcat AJP Connector. Then only requests +from workers with the same secret keyword will be accepted. +
+Use request.secret="secret key word" in your Tomcat AJP Connector configuration. +
+
+If you set a secret on a load balancer, all its members will inherit this secret. +
+
+This feature has been added in jk 1.2.12. +
+
max_reply_timeouts LB 0 +If you use a reply_timeout for the members of a load balancer worker, +and you want to tolerate a few requests taking longer than reply_timeout, +you can set this attribute to some positive value. +
+Long running requests will still time out after reply_timeout milliseconds waiting for +data, but the corresponding member worker will only be put into an error state, +if more than max_reply_timeouts requests have timed out. +More precisely, the counter for those bad requests will be divided by two, +whenever the load balancer does its internal maintenance (by default every 60 +seconds). +
+
+This features has been added in jk 1.2.24 to make reply_timeout less +sensitive for sporadic long running requests. +
+
recover_time LB 60 +The recover time is the time in seconds the load balancer will not try +to use a worker, after it went into error state. Only after this time has passed, +a worker in error state will be marked as in recovering, so that it will be +tried for new requests. +
+This interval is not checked every time a request is being processed. +Instead it is being checked during global maintenance. The time between two +runs of global maintenance is controlled by worker.maintain. +
+
+Do not set recover_time to a very short time unless you understand the implications. +Every recovery attempt for a worker in error is done by a real request! +
+
error_escalation_time LB recover_time / 2 +Setting a member of a load balancer into an error state is quite serious. E.g. +it means that if you need stickyness, all access to the sessions of the +respective node is blocked. +
+Some types of error detection do not provide a precise information, whether +a node is completely broken or not. In those cases an LB will not immediately +put the node into the error state. Only when there have been no successful +responses for error_escalation_time seconds after such an error, +will the node be put into error state. +
+
+This features has been added in jk 1.2.28. +
+
activation SUB Active +Using this directive, a balanced worker of a load balancer +can be configured as disabled or stopped. A disabled worker only gets +requests, which belong to sessions for that worker. A stopped +worker does not get any requests. Users of a stopped worker will +loose their sessions, unless session replication via clustering is used. +
+Use d or D to disable and s or S to stop. +If this directive is not present the deprecated directives +"disabled" or "stopped" are used. +
+
+This flag can be changed at runtime using status worker. +
+
+This feature has been added in jk 1.2.19. +
+
route SUB worker name +Normally the name of a balanced worker in a load balancer is equal to the jvmRoute +of the corresponding Tomcat instance. If you want to include a worker corresponding +to a Tomcat instance into several load balancers with different balancing configuration +(e.g. disabled, stopped) you can use this attribute. +
+Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and +set the route attribute of the worker equal to the jvmRoute of the target Tomcat instance. +
+
+If this attribute is left empty, the name of the worker will be used. +
+
+This attribute can be changed at runtime using status worker. +
+
+If the route name contains a period, the part before the first period will be +used as domain name, unless domain is set explicitly. +
+
+This feature has been added in jk 1.2.16.
+The automatic domain rule has been added in jk 1.2.20.
+The attribute has been renamed from jvm_route to route in jk 1.2.20. +
+
distance SUB 0 +An integer number to express preferences between +the balanced workers of an lb worker. +A load balancer will never choose some balanced worker +in case there is another usable worker with lower distance. +
+Only in case all workers below a given distance are in error, disabled or stopped, +workers of a larger distance are eligible for balancing. +
+
+This feature has been added in jk 1.2.16. +
+
domain SUB - +Domain directive can be used only when the worker is a member of the load balancer. +Workers that share the same domain name are treated as single worker. If sticky_session +is used, then the domain name is used as session route. +
+This directive is used for large system with more then 6 Tomcats, to be able +to cluster the Tomcats in two groups and thus lowering the session replication +transfer between them. +
+
+This feature has been added in jk 1.2.8. +
+
redirect SUB - +Set to the name of the preferred failover worker. If worker matching +SESSION ID is in error state then the redirect worker will be used instead. +It will be used even if being disabled, thus offering hot standby. +
+If you explicitly set a route via the "route" attribute, you must set "redirect" +to this route of the preferred failover worker and not to its name. +
+
+This feature has been added in jk 1.2.9. +
+
session_cookie LB JSESSIONID +The name of the cookie that contains the routing identifier needed for session stickyness. +The routing identifier is everything after a "." character in the value of the cookie. +
+This feature has been added in jk 1.2.27. +
+
session_path LB ;jsessionid +The name of the path parameter that contains the routing identifier needed for +session stickyness. The routing identifier is everything after a "." character in the value +of the path parameter. +
+This feature has been added in jk 1.2.27. +
+
+
+ +
Deprecated Worker Directives
+
+
The following directives have been deprecated in the past. We include their documentation +in case you need to use an older version of mod_jk. We urge you to update and not use +them any more. Please migrate your existing configurations. +
+
Directive Successor Default Description
cachesize connection_pool_size see text +
This directive has been deprecated since 1.2.16.
+Cachesize defines the number of connections made to the AJP backend that +are maintained as a connection pool. +It will limit the number of those connection that each web server child +process can make. +
+Cachesize property is used only for multi threaded +web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property +should reflect the number of threads per child process. JK will discover +the number of threads per child process on Apache 2 web server with worker-mpm and set +its default value to match the ThreadsPerChild Apache directive. For IIS the default +value is 10. For other web servers than Apache or IIS this value has to be set manually. +
+
Do not use cachesize with values higher then 1 on Apache 2.x prefork or Apache 1.3.x!
+
cache_timeout connection_pool_timeout 0 +
This directive has been deprecated since 1.2.16.
+Cache timeout property should be used with cachesize to specify how to time JK should keep +an open socket in cache before closing it. This property should be used to reduce the number of threads +on the Tomcat web server. +
+Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating +a new ajp13 thread on Tomcat side. +
+
+The problem is that after an ajp13 connection is created, the child won't drop it +until killed. And since the webserver will keep its childs/threads running +to handle high-load, even it the child/thread handle only static contents, you could +finish having many unused ajp13 threads on the Tomcat side. +
+
recycle_timeout connection_pool_timeout 0 +
This directive has been deprecated since 1.2.16.
+The number of seconds that told webserver to cut an ajp13 connection after some time of +inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be +closed if it was not used for the configured time. +It's a good way to ensure that there won't too old threads living on Tomcat side, +with the extra cost you need to reopen the socket next time a request be forwarded. +This property is very similar to cache_timeout but works also in non-cache mode. +If set to value zero (default) no recycle will took place. +
balanced_workers balance_workers - +
This directive has been deprecated since 1.2.7.
+A comma separated list of workers that the load balancer +need to manage. +
disabled activation False +
This directive has been deprecated since 1.2.19.
+If set to True or 1 the worker will be disabled if member +of load balancer. This flag can be changed at runtime using status worker. +
+This feature has been added in jk 1.2.9. +
+
stopped activation False +
This directive has been deprecated since 1.2.19.
+If set to True or 1 the worker will be stopped if member +of load balancer. The flag is needed for stop complete traffic of a sticky session +worker. It is only useful, when you have a cluster that replicated the sessions. +This flag can be changed at runtime using status worker. +
+This feature has been added in jk 1.2.11. +
+
jvm_route route worker name +
This directive has been deprecated since 1.2.20.
+Normally the name of a balanced worker in a load balancer is equal to the jvmRoute +of the corresponding Tomcat instance. If you want to include a worker corresponding +to a Tomcat instance into several load balancers with different balancing configuration +(e.g. disabled, stopped) you can use this attribute. +
+Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and +set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance. +
+
+If this attribute is left empty, the name of the worker will be used. +
+
+This attribute can be changed at runtime using status worker. +
+
+This feature has been added in jk 1.2.16. +
+
+
+ +

\ No newline at end of file -- cgit 1.2.3-korg