Configuring Apache

--- .../xdocs/reference/apache.xml | 1119 ------------------- .../xdocs/reference/iis.xml | 387 ------- .../xdocs/reference/project.xml | 81 -- .../xdocs/reference/status.xml | 584 ---------- .../xdocs/reference/uriworkermap.xml | 422 ------- .../xdocs/reference/workers.xml | 1155 -------------------- 6 files changed, 3748 deletions(-) delete mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml delete mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml delete mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml delete mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml delete mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml delete mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference') diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml deleted file mode 100644 index e4ad0360..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml +++ /dev/null @@ -1,1119 +0,0 @@ - - - -]> - - - &project; - - - Mladen Turk - Configuring Apache - - - - -

-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: -

- -

-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. -

-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. -

-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.

- -

-Size of the shared memory file name. -
-This directive is only allowed once. It must be put into -the global part of the configuration. -
-The default value depends on the platform. It is usually less than 64KB. -

Starting with version 1.2.27 the size of the shared memory is determined -automatically, even for large numbers of workers. This attribute is not -needed any longer.

-File containing multiple mappings from a context to a Tomcat worker. -It is usually called uriworkermap.properties. -
-For inheritance rules, see: JkMountCopy. -
-There is no default value. -

-This directive configures the reload check interval in seconds. -The JkMountFile is checked periodically for changes. -A changed file gets reloaded automatically. If you set -this directive to "0", reload checking is turned off. -
-The default value is 60 seconds. -
-This directive has been added in version 1.2.20 of mod_jk. -

-A mount point from a context to a Tomcat worker. -
-This directive is allowed multiple times. -It is allowed in the global configuration and in VirtualHost. -You can also use it inside Location with a different syntax. -Inside Location, one omits the first argument (path), -which gets inherited from the Location. -
-By default JkMount entries are not inherited from the global -server to other VirtualHosts or between VirtualHosts. -For the complete inheritance rules, see: JkMountCopy. -

-An exclusion mount point from a context to a Tomcat worker. -All exclusion mounts are checked after mapping a request -to a tomcat worker. If the request maps also to an exclusion, -it will not be forwarded to tomcat, and instead be served locally. -
-This directive is allowed multiple times. -It is allowed in the global configuration and in VirtualHost. -You can also use it inside Location with a different syntax. -Inside Location, one omits the first argument (path), -which gets inherited from the Location. -For inheritance rules, see: JkMountCopy. -
-This directive is available in jk1.2.7 version and later. -

-Automatically Alias webapp context directories into the Apache -document space. -
-Care should be taken to ensure that only static content is served via httpd as a -result of using this directive. Any static content served by httpd will bypass any -security constraints defined in the application's web.xml. -
-For inheritance rules, see: JkMountCopy. -
-There is no default value. -

-If this directive is set to "On" in some virtual server, -the mounts from the global server will be copied to this -virtual server, more precisely all mounts defined by JkMount -or JkUnMount. The Mounts defined by JkMountFile and JkAutoAlias -will only be inherited, if the VirtualHost does not define -it's own JkMountFile or JkAutoAlias. -
-If you want all vhost to inherit mounts from the main server, -you can set JkMountCopy to 'All' in the main server. -
-This directive is only allowed inside VirtualHost (with value "On") -and in the global server (with value "All"). -
-The default is Off, so no mounts will be inherited from the global -server to any VirtualHost. -
-Starting with version 1.2.26 you can also set it to "All" in the -global virtual server. This will switch the default to On. -

-Name of the Apache environment variable that can be used to set worker names -in combination with SetHandler jakarta-servlet. -
-This directive is only allowed once per virtual server. -It is allowed in the global configuration and in VirtualHost. -
-The default value is JK_WORKER_NAME. -

-This directive configures the watchdog thread interval in seconds. -The workers are maintained periodically by a background thread -running periodically every watchdog_interval seconds. Worker maintenance -checks for idle connections, corrects load status and is able -to detect backend health status. -
-The maintenance only happens, if since the last maintenance at -least worker.maintain -seconds have passed. So setting the JkWatchdogInterval -much smaller than worker.maintain is not useful. -
-The default value is 0 seconds, meaning the watchdog thread -will not be created, and the maintenance is done in combination -with normal requests instead. -
-This directive is only allowed once. It must be put into -the global part of the configuration. -
-This directive has been added in version 1.2.27 of mod_jk. -It is available only for httpd 2.x and above using APR libraries -including thread support. -

-Full or server relative path to the Tomcat Connector module log file. -It will also work with pipe, by using a value of the form "| ...". -
-The default value is logs/mod_jk.log. -
-Pipes are supported for Apache 1.3 only since version 1.2.16. -The default value exists only since version 1.2.20. -

-The Tomcat Connector module log level, can be debug, info, warn -error or trace. -
-The default value is info. -

-The Tomcat Connector module date log format, using an -extended strftime syntax. -This format will be used for the time stamps in the JkLogFile. -The maximum length of the format is 63 characters. -
-Starting with version 1.2.24 of mod_jk you can also use %Q -for adding milliseconds to the log and %q for microseconds. -These conversion specifiers are an extension to strftime. -They will only work on platforms with a gettimeofday() function. -You can use %Q and %q only once in the pattern and also not both -together in the same pattern. -
-The default value is "[%a %b %d %H:%M:%S %Y] " and beginning -with version 1.2.24 on platforms with a gettimeofday() -function it is "[%a %b %d %H:%M:%S.%Q %Y] ". -

-Request log format string. See detailed description below. -
-There is no default value. Without defining a value, the request logging -is turned off. -

-Turns on SSL processing and information gathering by mod_jk -
-The default value is On. -
-In order to make SSL data available for mod_jk in Apache, you need to -set SSLOptions +StdEnvVars. For the certificate information you also need -to add SSLOptions +ExportCertData. -

- Specifically, mod_jk will export the following environment variables from - Apache httpd to Tomcat under these request attributes as per the - Servlet Specification 3.0, section 3.8: -

- - - - - - - - - - - - - - - - - - - - - - - - - - -

Env Var	Request Attribute Name	Type	Example
SSL_CIPHER (or `JkKEYSIZEIndicator`)	javax.servlet.request.cipher_suite	java.lang.String	DHE-RSA-AES256-SHA
SSL_CIPHER_USEKEYSIZE (or `JkKEYSIZEIndicator`)	javax.servlet.request.key_size	java.lang.Integer	256
SSL_SESSION_ID (or `JkSESSIONIndicator`)	javax.servlet.request.ssl_session	java.lang.String	905...32E (a hex string)
SSL_CLIENT_CERT_CHAIN_n (or `JkCERTCHAINPrefix`n)	javax.servlet.request.X509Certificate	java.security.X509Certificate[]	(A chain of certs in ascending order of trust, the first one being - ths client's certificate, the second being the signer of that - certificate, and so on)

- For all other SSL-related variables, use JkEnvVar for each - variable you want. Please note that, like JkEnvVar, these - variables are available from the request attributes, not as - environment variables or as request headers. -

- -

-Name of the Apache environment variable that contains SSL indication. -
-The default value is "HTTPS". -

-Name of the Apache environment variable that contains SSL client certificates. -
-The default value is "SSL_CLIENT_CERT". -

-Name of the Apache environment variable that contains SSL client cipher. -
-The default value is "SSL_CIPHER". -

-Name of the Apache environment (prefix) that contains SSL client chain certificates. -
-The default value is "SSL_CLIENT_CERT_CHAIN_". -

-Name of the Apache environment variable that contains SSL session. -
-The default value is "SSL_SESSION_ID". -

-Name of the Apache environment variable that contains SSL key size in use. -
-The default value is "SSL_CIPHER_USEKEYSIZE". -

-Name of the Apache environment variable which can be used to overwrite -the forwarded local name. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_LOCAL_NAME". -
-This directive has been added in version 1.2.28 of mod_jk. -

-Name of the Apache environment variable which can be used to overwrite -the forwarded local port. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_LOCAL_PORT". -
-This directive has been added in version 1.2.28 of mod_jk. -

-Name of the Apache environment variable which can be used to overwrite -the forwarded remote (client) host name. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_REMOTE_HOST". -
-This directive has been added in version 1.2.28 of mod_jk. -

-Name of the Apache environment variable which can be used to overwrite -the forwarded remote (client) IP address. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_REMOTE_ADDR". -
-This directive has been added in version 1.2.28 of mod_jk. -

-Name of the Apache environment variable which can be used to overwrite -the forwarded remote (client) IP address. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_REMOTE_PORT". -
-This directive has been added in version 1.2.32 of mod_jk. -

-Name of the Apache environment variable which can be used to overwrite -the forwarded user name. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_REMOTE_USER". -
-This directive has been added in version 1.2.28 of mod_jk. -

-Name of the Apache environment variable which can be used to overwrite -the forwarded authentication type. -Use this only if you need to adjust the data (see the -proxy documentation). -
-The default value is "JK_AUTH_TYPE". -
-This directive has been added in version 1.2.28 of mod_jk. -

-Set one of more options to configure the mod_jk module. See below for -details about this directive. -
-This directive can be used multiple times per virtual server. -
-The default value is "ForwardURIProxy" since version 1.2.24. -It was "ForwardURICompatUnparsed" in version 1.2.23 and -"ForwardURICompat" until version 1.2.22. -

-Adds a name and an optional default value of environment variable -that should be sent to servlet-engine as a request attribute. -If the default value is not given explicitly, the variable -will only be send, if it is set during runtime. -
-The default is empty, so no additional variables will be sent. -
-This directive can be used multiple times per virtual server. -The settings will be merged between the global server and any -virtual server. -
-You can retrieve the variables on Tomcat as request attributes -via request.getAttribute(attributeName). Note that the variables -send via JkEnvVar will not be listed in request.getAttributeNames(). -
-Empty default values are supported since version 1.2.20. -Not sending variables with empty defaults and empty runtime value -has been introduced in version 1.2.21. -

-If this directive is set to On in some virtual server, -the session IDs ;jsessionid=... will be -removed for non matched URLs. -
-This directive is only allowed inside VirtualHost. -
-The default is Off. -
-This directive has been introduced in version 1.2.21. -
With version 1.2.27 and later this directive can have optional -session ID identifier. If not specified it defaults to -;jsessionid. -

- - - -

- -

-We'll discuss here the mod_jk directive types. -

- - -

-JkWorkersFile specify the location where mod_jk will find the workers definitions. -Take a look at Workers documentation for detailed description. - - - JkWorkersFile /etc/httpd/conf/workers.properties - - -
-
-

- - - - -

-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: -

- -

- - Bytes sent, excluding HTTP headers (CLF format) - Bytes sent, excluding HTTP headers - The request protocol - The request method - The canonical Port of the server serving the request - The query string (prepended with a ? if a query string exists, otherwise an empty string) - First line of request - Request HTTP status code - Request duration, elapsed time to handle request in seconds '.' micro seconds - The URL path requested, not including any query string. - The canonical ServerName of the server serving the request - The server name according to the UseCanonicalName setting - Tomcat worker name - 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. -

- -

- - Name of the worker selected by the URI mapping - Type of the worker selected by the URI mapping - 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. - Request duration in seconds and microseconds.
- Before version 1.2.26 only available if JkRequestLogFormat is set. - Load-Balancer: Name of the first worker tried - Load-Balancer: Type of the first worker tried - Load-Balancer: Access count for the first worker tried - Load-Balancer: Bytes read for the first worker tried - Load-Balancer: Bytes transferred for the first worker tried - Load-Balancer: Error count for the first worker tried - Load-Balancer: Busy count for the first worker tried - Load-Balancer: Activation state for the first worker tried - Load-Balancer: Error state for the first worker tried - Load-Balancer: Name of the last worker tried - Load-Balancer: Type of the last worker tried - Load-Balancer: Access count for the last worker tried - Load-Balancer: Bytes read for the last worker tried - Load-Balancer: Bytes transferred for the last worker tried - Load-Balancer: Error count for the last worker tried - Load-Balancer: Busy count for the last worker tried - Load-Balancer: Activation state for the last worker tried - 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 - - -
-
-

- - - - -

-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 - -
-
-

- - - - -

-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. -
-
-

- - - - -

-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. -

- -

- - diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml deleted file mode 100644 index 0539c454..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml +++ /dev/null @@ -1,387 +0,0 @@ - - - -]> - - - &project; - - - Mladen Turk - Configuring IIS - - - - -

-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. -

-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" -

- -

-A string value pointing to the ISAPI extension /jakarta/isapi_redirect.dll -

-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 -

-A string value for log level -(can be debug, info, warn, error or trace).

This directive was added in version 1.2.31

- -

-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

- -

-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. -

-A string value which is the full path to workers.properties file -(for example c:\tomcat\conf\workers.properties) -

-A string value which is the full path to uriworkermap.properties file -(for example c:\tomcat\conf\uriworkermap.properties) -

-A string value which is the full path to rewrite.properties file -(for example c:\tomcat\conf\rewrite.properties) -

-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.

- -

-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

- -

-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

- -

-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

- -

-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".

- -

-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. -

This directive has been added in version 1.2.24

- -

-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

- -

-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

- -

-A string value representing a boolean. If it is set to true, -chunked encoding is supported by the server. -

-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

- - -

-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 -

- -

-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. -

- -

-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. -

- - - diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml deleted file mode 100644 index f5d56447..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml +++ /dev/null @@ -1,81 +0,0 @@ - - - - - The Apache Tomcat Connector - Reference Guide - - - The Apache Tomcat Connector - Reference Guide - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml deleted file mode 100644 index 5c2a1f23..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml +++ /dev/null @@ -1,584 +0,0 @@ - - - -]> - - - &project; - - - Rainer Jung - Status Worker Reference - - - - -

-
-

-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 -

- -

-
- -
-

-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. -

- - - -
-

-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. -

- - - -
-

-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. -

- - - -
-

-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. -

- - - -
-

-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. -

- - -

- -

-
- -
-

-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 -

- - - -
-

-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. -

- - - -
-

-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. -

- - - -
-

-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. -

- -

-
-

-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. -

- -
-

-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. -

- - -
-

-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". -

- - -
-

-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. -

- - -
-

-During automatic refresh, the parameter re contain the refresh interval in seconds. -If you omit this parameter, automatic refresh will be off. -

- - -
-

-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. -

- - -
-

-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. -

- - -
-

-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", .... -

- -

- - - diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml deleted file mode 100644 index f9a83dea..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml +++ /dev/null @@ -1,422 +0,0 @@ - - - -]> - - - &project; - - - Rainer Jung - Mladen Turk - uriworkermap.properties configuration - - - - -

-
-

-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. -

- -

-
- -
-

-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. -

- - -
-

-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 - -

- - - -
-

-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 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 '-!'. -

- - - -
-

-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 were added in version 1.2.27 and are not available in earlier versions. -

- -
-

-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. -

- - -
-

-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. -

- - -
-

-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. -

- - -
-

-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. -

- - -
-

-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 - -

- -

-
- - -
-

-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 - -

- - - -
-

-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. -

- -

-
-

-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. -

- -

-
-

-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. -

- - - diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml deleted file mode 100644 index 543112cf..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml +++ /dev/null @@ -1,1155 +0,0 @@ - - - -]> - - - &project; - - - Mladen Turk - workers.properties configuration - - - - -

-
-

-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. -

- -

-
-

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). -

- - -
-

-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. -

- - - -
-

-These directives have global scope. -

- - -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 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. -

- - - - - -
-

-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. - - - - -
-

-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. -

- - - -
-

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. -

- -

-
- -
-

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. -

- - -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 defines the parameters needed to connect and maintain -the connections pool of persistent connections between JK and remote Tomcat. -

- - - -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 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 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 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. -

- - - -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. -

- - - -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. -

- - - -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. -

- - -The usage depend on the ping_mode flags used. -directive connection_ping_interval was not set, the -value of (ping_timeout/1000) * 10 will be used as -connection_ping_interval value. - - -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. -

- - - -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! - - - -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. -

- - - -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. -

- - - -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. -

- - - -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 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: -

- - - -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. - - - -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. - - - -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. -

- - - -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. -

- - - -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. -

- - - -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. -

- - - - - - - -
-

-The status worker does not communicate with Tomcat. -Instead it is responsible for the load balancer management. -

- - -Specifies the url for cascading stylesheet to use. - - -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. -

- - -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. -

- - -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. -

- - -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. -

- - -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. -

- - -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. -

- - -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. -

- - -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. -

- - -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. -

- - - - - - -
-

-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. -

- - -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 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. -

- - - -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. -

- - - -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. -

- - - -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 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. -

- - - -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 -

- - - -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. -

- - - -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. -

- - - -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. -

- - - -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. -

- - - -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! -

- - - -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. -

- - - -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. -

- - - -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. -

- - - -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 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. -

- - - -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. -

- - - -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. -

- - - -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. -

- - - - - - -
-

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. -

- - -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! - - - -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. -

- - - -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. - - - -This directive has been deprecated since 1.2.7. -A comma separated list of workers that the load balancer -need to manage. - - - -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. -

- - - -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. -

- - - -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. -

- - - - - -

- - - -- cgit 1.2.3-korg