From 9401f816dd0d9d550fe98a8507224bde51c4b847 Mon Sep 17 00:00:00 2001 From: hongbotian Date: Mon, 30 Nov 2015 02:41:33 -0500 Subject: upload tomcat JIRA: BOTTLENECK-7 Change-Id: I875d474869efd76ca203c30b60ebc0c3ee606d0e Signed-off-by: hongbotian --- .../docs/generic_howto/loadbalancers.html | 207 +++++++++++ .../docs/generic_howto/printer/loadbalancers.html | 206 +++++++++++ .../docs/generic_howto/printer/proxy.html | 312 ++++++++++++++++ .../docs/generic_howto/printer/quick.html | 130 +++++++ .../docs/generic_howto/printer/timeouts.html | 373 +++++++++++++++++++ .../docs/generic_howto/printer/workers.html | 408 ++++++++++++++++++++ .../docs/generic_howto/proxy.html | 313 ++++++++++++++++ .../docs/generic_howto/quick.html | 131 +++++++ .../docs/generic_howto/timeouts.html | 374 +++++++++++++++++++ .../docs/generic_howto/workers.html | 409 +++++++++++++++++++++ 10 files changed, 2863 insertions(+) create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/loadbalancers.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/loadbalancers.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/proxy.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/quick.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/timeouts.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/workers.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/proxy.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/quick.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/timeouts.html create mode 100644 rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/workers.html (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto') diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/loadbalancers.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/loadbalancers.html new file mode 100644 index 00000000..06a1ee5a --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/loadbalancers.html @@ -0,0 +1,207 @@ +The Apache Tomcat Connector - Generic HowTo - LoadBalancer HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Generic HowTo

LoadBalancer HowTo

print-friendly
version +

Introduction

+
+
A load balancer is a worker that does not directly communicate with Tomcat. +Instead it is responsible for the management of several "real" workers, +called members or sub workers of the load balancer.
+
+This management includes: +
+
+
+Instantiating the workers in the web server. +
+
+Using the worker's load-balancing factor, perform weighted load balancing +(distributing load according to defined strengths of the targets). +
+
+Keeping requests belonging to the same session executing on the same Tomcat +(session stickyness). +
+
+Identifying failed Tomcat workers, suspending requests to them and instead +falling-back on other workers managed by the load balancer. +
+
+Providing status and load metrics for the load balancer itself and all +members via the status worker interface. +
+
+Allowing to dynamically reconfigure load-balancing via the status worker +interface. +
+
+
+Workers managed by the same load balancer worker are load-balanced +(based on their configured balancing factors and current request or session load) +and also secured against failure by providing failover to other members of the same +load balancer. So a single Tomcat process death will not "kill" the entire site. +
+
Some of the features provided by a load balancer are even interesting, when +only working with a single member worker (where load balancing is not possible).
+ +
Basic Load Balancer Properties
+
A worker is configured as a load balancer by setting its worker type +to lb. +
+
+The following table specifies some properties used to configure a load balancer worker: +
+
+
balance_workers is a comma separated list of names of the member workers of the +load balancer. These workers are typically of type ajp13. The member workers do +not need to appear in the worker.list property themselves, adding the +load balancer to it suffices.
+
sticky_session specifies whether requests with SESSION ID's should be routed +back to the same Tomcat instance that created the session. You can set sticky_session to +False when Tomcat is using a session manager which can share session data across +multiple instances of Tomcat - or if your application is stateless. +By default sticky_session is set to True.
+
lbfactor can be added to each member worker to configure individual +strengths for the members. A higher lbfactor will lead to more +requests being balanced to that worker. The factors must be given by integers and the +load will be distributed proportional to the factors given. Higher factors lead to +more requests.
+
+ +
+  # The load balancer worker balance1 will distribute
+  # load to the members worker1 and worker2
+  worker.balance1.type=lb
+  worker.balance1.balance_workers=worker1, worker2
+  worker.worker1.type=ajp13
+  worker.worker1.host=myhost1
+  worker.worker1.port=8009
+  worker.worker2.type=ajp13
+  worker.worker1.host=myhost2
+  worker.worker1.port=8009
+
+ +
+Session stickyness is not implemented using a tracking table for sessions. +Instead each Tomcat instance gets an individual name and adds its name at +the end of the session id. When the load balancer sees a session id, it +finds the name of the Tomcat instance and sends the request via the correct +member worker. For this to work you must set the name of the Tomcat instances +as the value of the jvmRoute attribute in the Engine element of +each Tomcat's server.xml. The name of the Tomcat needs to be equal to the name +of the corresponding load balancer member. In the above example, Tomcat on host +"myhost1" needs jvmRoute="worker1", Tomcat on host "myhost2" +needs jvmRoute="worker2". +
+ +
For a complete reference of all load balancer configuration +attributes, please consult the worker reference. +
+
+ +
Advanced Load Balancer Worker Properties
+
The load balancer supports complex topologies and failover configurations. +Using the member attribute distance you can group members. +The load balancer will always send a request to a member of lowest distance. +Only when all of those are broken, it will balance to the members of the +next higher configured distance. This allows to define priorities between +Tomcat instances in different data center locations. +
+
When working with shared sessions, either by using session replication +or a persisting session manager (e.g. via a database), one often splits +up the Tomcat farm into replication groups. In case of failure of a member, +the load balancer needs to know, which other members share the session. +This is configured using the domain attribute. All workers +with the same domain are assumed to share the sessions.
+
For maintenance purposes you can tell the load balancer to not +allow any new sessions on some members, or even not use them at all. +This is controlled by the member attribute activation. +The value Active allows normal use of a member, disabled +will not create new sessions on it, but still allow sticky requests, +and stopped will no longer send any requests to the member. +Switching the activation from "active" to "disabled" some time before +maintenance will drain the sessions on the worker and minimize disruption. +Depending on the usage pattern of the application, draining will take from +minutes to hours. Switching the worker to stopped immediately before +maintenance will reduce logging of false errors by mod_jk.
+
Finally you can also configure hot spare workers by using +activation set to disabled in combination with +the attribute redirect added to the other workers:
+ +
+  # The advanced router LB worker
+  worker.list=router
+  worker.router.type=lb
+  worker.router.balance_workers=worker1,worker2
+
+  # Define the first member worker
+  worker.worker1.type=ajp13
+  worker.worker1.host=myhost1
+  worker.worker1.port=8009
+  # Define preferred failover node for worker1
+  worker.worker1.redirect=worker2
+
+  # Define the second member worker
+  worker.worker2.type=ajp13
+  worker.worker2.host=myhost2
+  worker.worker2.port=8009
+  # Disable worker2 for all requests except failover
+  worker.worker2.activation=disabled
+
+ +
+The redirect flag on worker1 tells the load balancer +to redirect the requests to worker2 in case that worker1 has a problem. +In all other cases worker2 will not receive any requests, thus acting +like a hot standby. +
+ +
A final note about setting activation to disabled: +The session id coming with a request is send either +as part of the request URL (;jsessionid=...) or via a cookie. +When using bookmarks or browsers that are running since a long time, +it is possible to send a request carrying an old and invalid session id +pointing at a disabled member. +Since the load balancer does not have a list of valid sessions, it will +forward the request to the disabled member. Thus draining takes longer than +expected. To handle such cases, you can add a Servlet filter to your web +application, which checks the request attribute JK_LB_ACTIVATION. +This attribute contains one of the strings "ACT", "DIS" or "STP". If you +detect "DIS" and the session for the request is no longer active, delete the +session cookie and redirect using a self-referential URL. The redirected +request will then no longer carry session information and thus the load +balancer will not send it to the disabled worker. The request attribute +JK_LB_ACTIVATION has been added in version 1.2.32.
+
+ +
Status Worker properties
+
+The status worker does not communicate with Tomcat. +Instead it is responsible for the worker management. It is +especially useful when combined with load balancer workers. +
+
+  # Add the status worker to the worker list
+  worker.list=jkstatus
+  # Define a 'jkstatus' worker using status
+  worker.jkstatus.type=status
+
+
Next thing is to mount the requests to the jkstatus worker. For Apache +web servers use the:
+
+  # Add the jkstatus mount point
+  JkMount /jkmanager/* jkstatus 
+
+
To obtain a higher level of security use the:
+
+  # Enable the JK manager access from localhost only
+ <Location /jkmanager/>
+    JkMount jkstatus
+    Order deny,allow
+    Deny from all
+    Allow from 127.0.0.1
+ </Location>
+
+ +
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/loadbalancers.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/loadbalancers.html new file mode 100644 index 00000000..22999c94 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/loadbalancers.html @@ -0,0 +1,206 @@ +The Apache Tomcat Connector - Generic HowTo - LoadBalancer HowTo

The Apache Tomcat Connector - Generic HowTo

LoadBalancer HowTo

Introduction

+
+
A load balancer is a worker that does not directly communicate with Tomcat. +Instead it is responsible for the management of several "real" workers, +called members or sub workers of the load balancer.
+
+This management includes: +
+
+
+Instantiating the workers in the web server. +
+
+Using the worker's load-balancing factor, perform weighted load balancing +(distributing load according to defined strengths of the targets). +
+
+Keeping requests belonging to the same session executing on the same Tomcat +(session stickyness). +
+
+Identifying failed Tomcat workers, suspending requests to them and instead +falling-back on other workers managed by the load balancer. +
+
+Providing status and load metrics for the load balancer itself and all +members via the status worker interface. +
+
+Allowing to dynamically reconfigure load-balancing via the status worker +interface. +
+
+
+Workers managed by the same load balancer worker are load-balanced +(based on their configured balancing factors and current request or session load) +and also secured against failure by providing failover to other members of the same +load balancer. So a single Tomcat process death will not "kill" the entire site. +
+
Some of the features provided by a load balancer are even interesting, when +only working with a single member worker (where load balancing is not possible).
+ +
Basic Load Balancer Properties
+
A worker is configured as a load balancer by setting its worker type +to lb. +
+
+The following table specifies some properties used to configure a load balancer worker: +
+
+
balance_workers is a comma separated list of names of the member workers of the +load balancer. These workers are typically of type ajp13. The member workers do +not need to appear in the worker.list property themselves, adding the +load balancer to it suffices.
+
sticky_session specifies whether requests with SESSION ID's should be routed +back to the same Tomcat instance that created the session. You can set sticky_session to +False when Tomcat is using a session manager which can share session data across +multiple instances of Tomcat - or if your application is stateless. +By default sticky_session is set to True.
+
lbfactor can be added to each member worker to configure individual +strengths for the members. A higher lbfactor will lead to more +requests being balanced to that worker. The factors must be given by integers and the +load will be distributed proportional to the factors given. Higher factors lead to +more requests.
+
+ +
+  # The load balancer worker balance1 will distribute
+  # load to the members worker1 and worker2
+  worker.balance1.type=lb
+  worker.balance1.balance_workers=worker1, worker2
+  worker.worker1.type=ajp13
+  worker.worker1.host=myhost1
+  worker.worker1.port=8009
+  worker.worker2.type=ajp13
+  worker.worker1.host=myhost2
+  worker.worker1.port=8009
+
+ +
+Session stickyness is not implemented using a tracking table for sessions. +Instead each Tomcat instance gets an individual name and adds its name at +the end of the session id. When the load balancer sees a session id, it +finds the name of the Tomcat instance and sends the request via the correct +member worker. For this to work you must set the name of the Tomcat instances +as the value of the jvmRoute attribute in the Engine element of +each Tomcat's server.xml. The name of the Tomcat needs to be equal to the name +of the corresponding load balancer member. In the above example, Tomcat on host +"myhost1" needs jvmRoute="worker1", Tomcat on host "myhost2" +needs jvmRoute="worker2". +
+ +
For a complete reference of all load balancer configuration +attributes, please consult the worker reference. +
+
+ +
Advanced Load Balancer Worker Properties
+
The load balancer supports complex topologies and failover configurations. +Using the member attribute distance you can group members. +The load balancer will always send a request to a member of lowest distance. +Only when all of those are broken, it will balance to the members of the +next higher configured distance. This allows to define priorities between +Tomcat instances in different data center locations. +
+
When working with shared sessions, either by using session replication +or a persisting session manager (e.g. via a database), one often splits +up the Tomcat farm into replication groups. In case of failure of a member, +the load balancer needs to know, which other members share the session. +This is configured using the domain attribute. All workers +with the same domain are assumed to share the sessions.
+
For maintenance purposes you can tell the load balancer to not +allow any new sessions on some members, or even not use them at all. +This is controlled by the member attribute activation. +The value Active allows normal use of a member, disabled +will not create new sessions on it, but still allow sticky requests, +and stopped will no longer send any requests to the member. +Switching the activation from "active" to "disabled" some time before +maintenance will drain the sessions on the worker and minimize disruption. +Depending on the usage pattern of the application, draining will take from +minutes to hours. Switching the worker to stopped immediately before +maintenance will reduce logging of false errors by mod_jk.
+
Finally you can also configure hot spare workers by using +activation set to disabled in combination with +the attribute redirect added to the other workers:
+ +
+  # The advanced router LB worker
+  worker.list=router
+  worker.router.type=lb
+  worker.router.balance_workers=worker1,worker2
+
+  # Define the first member worker
+  worker.worker1.type=ajp13
+  worker.worker1.host=myhost1
+  worker.worker1.port=8009
+  # Define preferred failover node for worker1
+  worker.worker1.redirect=worker2
+
+  # Define the second member worker
+  worker.worker2.type=ajp13
+  worker.worker2.host=myhost2
+  worker.worker2.port=8009
+  # Disable worker2 for all requests except failover
+  worker.worker2.activation=disabled
+
+ +
+The redirect flag on worker1 tells the load balancer +to redirect the requests to worker2 in case that worker1 has a problem. +In all other cases worker2 will not receive any requests, thus acting +like a hot standby. +
+ +
A final note about setting activation to disabled: +The session id coming with a request is send either +as part of the request URL (;jsessionid=...) or via a cookie. +When using bookmarks or browsers that are running since a long time, +it is possible to send a request carrying an old and invalid session id +pointing at a disabled member. +Since the load balancer does not have a list of valid sessions, it will +forward the request to the disabled member. Thus draining takes longer than +expected. To handle such cases, you can add a Servlet filter to your web +application, which checks the request attribute JK_LB_ACTIVATION. +This attribute contains one of the strings "ACT", "DIS" or "STP". If you +detect "DIS" and the session for the request is no longer active, delete the +session cookie and redirect using a self-referential URL. The redirected +request will then no longer carry session information and thus the load +balancer will not send it to the disabled worker. The request attribute +JK_LB_ACTIVATION has been added in version 1.2.32.
+
+ +
Status Worker properties
+
+The status worker does not communicate with Tomcat. +Instead it is responsible for the worker management. It is +especially useful when combined with load balancer workers. +
+
+  # Add the status worker to the worker list
+  worker.list=jkstatus
+  # Define a 'jkstatus' worker using status
+  worker.jkstatus.type=status
+
+
Next thing is to mount the requests to the jkstatus worker. For Apache +web servers use the:
+
+  # Add the jkstatus mount point
+  JkMount /jkmanager/* jkstatus 
+
+
To obtain a higher level of security use the:
+
+  # Enable the JK manager access from localhost only
+ <Location /jkmanager/>
+    JkMount jkstatus
+    Order deny,allow
+    Deny from all
+    Allow from 127.0.0.1
+ </Location>
+
+ +
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/proxy.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/proxy.html new file mode 100644 index 00000000..043fe48a --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/proxy.html @@ -0,0 +1,312 @@ +The Apache Tomcat Connector - Generic HowTo - Reverse Proxy HowTo

The Apache Tomcat Connector - Generic HowTo

Reverse Proxy HowTo

Introduction

+
+
The Apache module mod_jk and its ISAPI and NSAPI variants connect +a web server to a backend (typically Tomcat) using the AJP protocol. +The web server receives an HTTP(S) request and the module forwards +the request to the backend. This function is usually called a gateway +or a proxy, in the context of HTTP it is called a reverse proxy. +
+

Typical Problems

+
+
A reverse proxy is not totally transparent to the application on +the backend. For instance the host name and port the original client +(e.g. browser) needs to talk to belong to the web server and not to the +backend, so the reverse proxy talks to a different host name and port. +When the application on the backend returns content including +self-referential URLs using its own backend address and port, the +client will usually not be able to use these URLs. +
+
Another example is the client IP address, which for the web server is the +source IP of the incoming connection, whereas for the backend the +connection always comes from the web server. This can be a problem, when +the client IP is used by the backend application e.g. for security reasons. +
+

AJP as a Solution

+
+
Most of these problems are automatically handled by the AJP protocol +and the AJP connectors of the backend. The AJP protocol transports +this communication metadata and the backend connector presents this +metadata whenever the application asks for it using Servlet API methods. +
+
The following list contains the communication metadata handled by AJP +and the ServletRequest/HttpServletRequest API calls which can be used to retrieve them: +
+
local name: getLocalName() and getLocalAddr. +This is also equal to getServerName(), unless a Host header +is contained in the request. In this case the server name is taken from that header. +
+
local port: getLocalPort() +This is also equal to getServerPort(), unless a Host header +is contained in the request. In this case the server port is taken from that header +if it contains an explicit port, or is equal to the default port of the scheme used. +
+
client address: getRemoteAddr() +
+
client port: getRemotePort() +The remote port was initially not supported. It is available when using mod_jk 1.2.32 +with Apache or IIS (not for the NSAPI plugin) together with Tomcat version at least +5.5.28, 6.0.20 or 7.0.0. For older versions, getRemotePort() +will incorrectly return 0 or -1. As a workaround you can forward the remote port by setting +JkEnvVar REMOTE_PORT and then either using +request.getAttribute("REMOTE_PORT") instead of getRemotePort() +or wrapping the request using a filter and overriding getRemotePort() with +request.getAttribute("REMOTE_PORT"). +
+
client host: getRemoteHost() +
+
authentication type: getAuthType() +
+
remote user: getRemoteUser(), +if tomcatAuthentication="false" +
+
protocol: getProtocol() +
+
HTTP method: getMethod() +
+
URI: getRequestURI() +
+
HTTPS used: isSecure(), getScheme() +
+
query string: getQueryString() +
+
+The following additional SSL-related data will be made available by Apache and forwarded by mod_jk only +if you set SSLOptions +StdEnvVars. For the certificate information you also need +to set SSLOptions +ExportCertData. +
+
SSL cipher: getAttribute(javax.servlet.request.cipher_suite) +
+
SSL key size: getAttribute(javax.servlet.request.key_size). +Can be disabled using JkOptions -ForwardKeySize. +
+
SSL client certificate: getAttribute(javax.servlet.request.X509Certificate). +If you want the whole certificate chain, then you need to also set JkOptions ForwardSSLCertChain. +It is likely, that in this case you also need to adjust the maximal AJP packet size +using the worker attribute max_packet_size. +
+
SSL session ID: getAttribute(javax.servlet.request.ssl_session). +This is for Tomcat, it has not yet been standardized. +
+
+
+

Fine Tuning

+
+
In some situations this is not enough though. Assume there is another +less clever reverse proxy in front of your web server, for instance an +HTTP load balancer or similar device which also serves as an SSL accelerator. +
+
Then you are sure that all your clients use HTTPS, but your web server doesn't +know about that. All it can see is requests coming from the accelerator using +plain HTTP. +
+
Another example would be a simple reverse proxy in front of your web server, +so that the client IP address that your web server sees is always the IP address +of this reverse proxy, and not of the original client. Often such reverse proxies +generate an additional HTTP header, like X-Forwareded-for which +contains the original client IP address (or a list of IP addresses, if there are +more cascading reverse proxies in front). It would be nice, if we could use the +content of such a header as the client IP address to pass to the backend. +
+
So we might need to manipulate some of the data that AJP sends to the backend. +When using mod_jk inside Apache httpd you can use several httpd environment +variables to let mod_jk know, which data it should forward. These environment variables +can be set by the httpd directives SetEnv or SetEnvIf, but also in a very flexible +way using mod_rewrite (since httpd 2.x it can not only test against environment +variables, but also set them). +
+
The following list contains all environment variables mod_jk checks, before +sending data to the backend: +
+
JK_LOCAL_NAME: the local name +
+
JK_LOCAL_PORT: the local port +
+
JK_REMOTE_HOST: the client host +
+
JK_REMOTE_ADDR: the client address +
+
JK_AUTH_TYPE: the authentication type +
+
JK_REMOTE_USER: the remote user +
+
HTTPS: On (case-insensitive) to indicate, that HTTPS is used +
+
SSL_CIPHER: the SSL cipher +
+
SSL_CIPHER_USEKEYSIZE: the SSL key size +
+
SSL_CLIENT_CERT: the SSL client certificate +
+
SSL_CLIENT_CERT_CHAIN_: prefix of variable names, containing +the client cerificate chain +
+
SSL_SESSION_ID: the SSL session ID +
+
+
+
Remember: in general you don't need to set them. The module retrieves the data automatically +from the web server. Only in case you want to change this data, you can overwrite it by +using these variables. +
+
Some of these variables might also be used by other web server modules. All +variables whose name does not begin with "JK" are set directly by Apache httpd. +If you want to change the data, but do not want to negatively influence the behaviour +of other modules, you can change the names of all variables mod_jk uses to private ones. +For the details see the Apache reference page. +
+
All variables, that are not SSL-related have only been introduced in version 1.2.27. +
+
Finally there is a shortcut to forward the local IP of the web server as the remote IP. +This can be useful, e.g. when using the Tomcat remote address valve for allowing connections +only from registered Apache web servers. This feature is activated by setting +JkOptions ForwardLocalAddress. +
+

Tomcat AJP Connector Settings

+
+
As an alternative to using the environment variables described in the previous section +(which do only exist when using Apache httpd), you can also configure Tomcat to overwrite +some of the communications data forwarded by mod_jk. The AJP connector in Tomcat's server.xml +allows to set the following properties: +
+
proxyName: server name as returned by getServerName() +
+
proxyPort: server port as returned by getServerPort() +
+
scheme: protocol scheme as returned by getScheme() +
+
secure: set to "true", if you wish isSecure() to return "true". +
+
+Remember: in general you don't need to set those. AJP automatically handles all cases +where the web server running mod_jk knows the right data. +
+

URL Handling

+
+
URL Rewriting
+
Sometimes one want to change path components of the URLs under which an application +is available. Especially if a web application is deployed as some context, say /myapp, +marketing prefers short URLs, so want the application to be directly available under +http://www.mycompany.com/. Although you can deploy the application as the so-called +ROOT context, which will be directly available at "/", admins often prefer not to use +the ROOT context, e.g. because only one application can be the root context (per host). +
+
The procedure to change the URLs in the reverse proxy is tedious, because often +an application produces self-referential URLs, which then include the path components +which you tried to hide to the outside world. Nevertheless, if you absolutely need to do it, +here are the steps. +
+
Case A: You need to make the application available at a simple URL, but it is OK, if +users proceed using the more complex URLs, as long as they don't have to type them in. +That's the easy case, and if this suffices to you, you're lucky. Use a simply RedirectMatch +for Apache httpd: +
+
+RedirectMatch ^/$ http://www.mycompany.com/myapp/
+
+
Your application will then be available under http://www.mycompany.com/, +and each visitor will be immediately redirected to the real URL +http://www.mycompany.com/myapp/ +
+
Case B: You need to hide path components for all requests going to the application. +Here's the recipe for the case, where you want to hide the first path component +/myapp. More complex manipulations are left as an exercise to the reader. +First the solution for the case of Apache httpd: +
+
1. Use mod_rewrite +to add /myapp to all requests before forwarding to the backend: +
+
+# Don't forget the PT flag! (pass through)
+RewriteRule ^/(.*) http://www.mycompany.com/myapp/$1 [PT]
+
+
2. Use mod_headers +to rewrite any HTTP redirects your application might return. Such redirects typically contain +the path components you want to hide, because by the HTTP standard, redirects always need to include +the full URL, and your application is not aware of the fact, that your clients talk to it via +some shortened URL. An HTTP redirect is done with a special response header named Location. +We rewrite the Location headers of our responses: +
+
+# Keep protocol, server and port if present,
+# but insert our webapp name before the rest of the URL
+Header edit Location ^([^/]*//[^/]*)?/(.*)$ $1/myapp/$2 
+
+
3. Use mod_headers again, to rewrite the paths contained in any cookies, +your application might set. Such cookie paths again might contain +the path components you want to hide. +A cookie is set with the HTTP response header named Set-Cookie. +We rewrite the Set-Cookie headers of our responses: +
+
+# Fix the cookie path
+Header edit Set-Cookie "^(.*; Path=/)(.*)" $1/myapp/$2 
+
+
3. Some applications might contain hard coded absolute links. +In this case check, whether you find a configuration item for your web framework +to configure the base URL. If not, your only chance is to parse all response +content bodies and do search and replace. This is fragile and very resource intensive. +If you really need to do this, you can use +mod_proxy_html, +mod_substitute +or mod_sed +for this task. +
+
If you are using Microsoft IIS as a web server, the ISAPI plugin provides a way +of doing the first step with a builtin feature. You define a mapping file for simple prefix +changes like this: +
+
+# Add a context prefix to all requests ...
+/=/myapp/
+# ... or change some prefix ...
+/oldapp/=/myapp/
+
+
and then put the name of the file in the rewrite_rule_file entry of the registry or your +isapi_redirect.properties file. In you uriworkermap.properties file, you +still need to map the URLs as they are before rewriting! +
+
More complex rewrites can be done using the same file, but with regular expressions. A leading +tilde sign '~', indicates, that you are using a regular expression: +
+
+# Use a regular expression rewrite
+~/oldapps([0-9]*)/=/newapps$1/
+
+
There is no support for Steps 2 (rewriting redirect responses) or 3 (rewriting cookie paths). +
+
+
URL Encoding
+
Some types of problems are triggered by the use of encoded URLs +(see percent encoding). +For the same location there exist +a lot of different URLs which are equivalent. The reverse proxy needs to inspect the URL in order +to apply its own authentication rules and to decide, to which backend it should send the request +(or whether it should handle it itself). Therefore the request URL first is normalized: +percent encoded characters are decoded, /./ is replaced by /, +/XXX/../ is replaced by / and similar manipulations of the URL are done. +After that, the web server might apply rewrite rules to further change the URL in less obvious ways. +Finally there is no more way to put the resulting URL in an encoding, which is "similar" to +the one which was used for the original URL. +
+
+For historical reasons, there have been several alternatives, how mod_jk and the ISAPI +plugin encoded the resulting URL before sending it to the backend. They could be chosen via +JkOptions (Apache httpd) or uri_select (ISAPI). None of those historical +encodings are recommended, because they have either negative functionality implications or +pose a security risk. The default encoding since version 1.2.24 is ForwardURIProxy +(Apache httpd) or proxy (ISAPI) and it is strongly recommended to keep the default +and remove all old explicit settings. +
+
+

Request Attributes

+
+
+You can also add more attributes to any request you are forwarding when using Apache httpd. +For this use the JkEnvVar directive (for details see the +Apache reference page). Such request attributes can be +retrieved on the Tomcat side via request.getAttribute(attributeName). +Note that their names will not be listed in request.getAttributeNames()! +
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/quick.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/quick.html new file mode 100644 index 00000000..c9d95c9b --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/quick.html @@ -0,0 +1,130 @@ +The Apache Tomcat Connector - Generic HowTo - Quick Start HowTo

The Apache Tomcat Connector - Generic HowTo

Quick Start HowTo

Introduction

+
+ This document describes the configuration files used by JK on the + Web Server side for the 'impatient': +
+
+ workers.properties is a mandatory file used by the webserver and which + is the same for all JK implementations (Apache/IIS/NES). +
+
+ web server add-ons to be set on the webserver side. +
+
+
+
+ We'll give here minimum servers configuration and an example workers.properties + to be able to install and check quickly your configuration. +
+

Minimum workers.properties

+
+ Here is a minimum workers.properties, using just ajp13 to connect your Apache webserver + to the Tomcat engine, complete documentation is available in Workers HowTo. +
+
+
+
+  # Define 1 real worker using ajp13
+  worker.list=worker1
+  # Set properties for worker1 (ajp13)
+  worker.worker1.type=ajp13
+  worker.worker1.host=localhost
+  worker.worker1.port=8009
+
+
+
+

Minimum Apache web server configuration

+
+ Here is a minimum information about Apache configuration, a + more complete separate HowTo for Apache is available. +
+
+ You should first have mod_jk.so (unix) or mod_jk.dll (Windows) installed + in your Apache module directory (see your Apache documentation to locate it). +
+
+ Usual locations for modules directory on Unix: +
+
/usr/lib/apache/
+
/usr/lib/apache2/
+
/usr/local/apache/libexec/
+
+
+
+ Usual locations for modules directory on Windows : +
+
C:\Program Files\Apache Group\Apache\modules\
+
C:\Program Files\Apache Group\Apache2\modules\
+
+
+
+ You'll find a link to prebuilt binaries + here +
+
+ Here is the minimum which should be set in httpd.conf directly or + included from another file: +
+
+ Usual locations for configuration directory on Unix: +
+
/etc/httpd/conf/
+
/etc/httpd2/conf/
+
/usr/local/apache/conf/
+
+
+
+ Usual locations for configuration directory on Windows : +
+
C:\Program Files\Apache Group\Apache\conf\
+
C:\Program Files\Apache Group\Apache2\conf\
+
+
+
+
+
+  # Load mod_jk module
+  # Update this path to match your modules location
+  LoadModule    jk_module  libexec/mod_jk.so
+  # Declare the module for <IfModule directive> (remove this line on Apache 2.x)
+  AddModule     mod_jk.c
+  # Where to find workers.properties
+  # Update this path to match your conf directory location (put workers.properties next to httpd.conf)
+  JkWorkersFile /etc/httpd/conf/workers.properties
+  # Where to put jk shared memory
+  # Update this path to match your local state directory or logs directory
+  JkShmFile     /var/log/httpd/mod_jk.shm
+  # Where to put jk logs
+  # Update this path to match your logs directory location (put mod_jk.log next to access_log)
+  JkLogFile     /var/log/httpd/mod_jk.log
+  # Set the jk log level [debug/error/info]
+  JkLogLevel    info
+  # Select the timestamp log format
+  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+  # Send everything for context /examples to worker named worker1 (ajp13)
+  JkMount  /examples/* worker1
+
+
+
+

Minimum IIS web server configuration

+
+ A separate HowTo for the IIS web server is available. +
+
+ This paragraph has not been written yet, but you can contribute to it. +
+

Minimum NES/iPlanet/Sun web server configuration

+
+ A separate HowTo for the Netscape/iPlanet/Sun web server is available. +
+ This paragraph has not been written yet, but you can contribute to it. +
+
+

Test your configuration

+
+ (Re)start the web server and browse to the http://localhost/examples/ +
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/timeouts.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/timeouts.html new file mode 100644 index 00000000..17ab68fe --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/timeouts.html @@ -0,0 +1,373 @@ +The Apache Tomcat Connector - Generic HowTo - Timeouts HowTo

The Apache Tomcat Connector - Generic HowTo

Timeouts HowTo

Introduction

+
+
Setting communication timeouts is very important to improve the +communication process. They help to detect problems and stabilise +a distributed system. JK can use several different timeout types, which +can be individually configured. For historical reasons, all of them are +disabled by default. This HowTo explains their use and gives +hints how to find appropriate values. +
+
All timeouts can be configured in the workers.properties file. +For a complete reference of all worker configuration +items, please consult the worker reference. +This page assumes, that you are using at least version 1.2.16 of JK. +Dependencies on newer versions will be mentioned where necessary. +
+
+Do not set timeouts to extreme values. Very small timeouts will likely +be counterproductive. +
+
+Long Garbage Collection pauses on the backend do not make a good +fit with some timeouts. Try to optimise your Java memory and GC settings. +
+

JK Timeout Attributes

+
+
CPing/CPong
+
+CPing/CPong is our notion for using small test packets to check the +status of backend connections. JK can use such test packets directly after establishing +a new backend connection (connect mode) and also directly before each request gets +send to a backend (prepost mode). +Starting with version 1.2.27 it can also be used when a connection was idle +for a long time (interval mode). +The maximum waiting time (timeout) for a CPong answer to a CPing and the idle +time in interval mode can be configured. +
+
+The test packets will be answered by the backend very fast with a minimal amount of +needed processing resources. A positive answer tells us, that the backend can be reached +and is actively processing requests. It does not detect, if some context is deployed +and working. The benefit of CPing/CPong is a fast detection of a communication +problem with the backend. The downside is a slightly increased latency. +
+
+The worker attribute ping_mode can be set to a combination of characters +to determine, in which situations test packets are used: +
+
C: connect mode, timeout ping_timeout overwritten by connect_timeout
+
P: prepost mode, timeout ping_timeout overwritten by prepost_timeout
+
I: interval mode, timeout ping_timeout, idle time connection_ping_interval
+
A: all modes
+
+
+
+Multiple values must be concatenated without any separator characters. +We recommend using all CPing tests. If your application is very latency sensitive, then +you should only use the combination of connect and interval mode. +
+
+Activating the CPing probing via ping_mode has been added in version 1.2.27. +For older versions only the connect and prepost modes exist and must be activated by +explicitely setting connect_timeout and prepost_timeout. +
+
+The worker attribute ping_timeout sets the default wait timeout +in milliseconds for CPong for all modes. By default the value is "10000" +milliseconds. The value only gets used, if you activate CPing/Cpong probes +via ping_mode. The default value should be fine, except if you experience +very long Java garbage collection pauses. +Depending on your network latency and stability, good custom values +often are between 5000 and 15000 milliseconds. +You can overwrite the timeout used for connect and prepost mode with +connect_timeout and prepost_timeout. +Remember: don't use extremely small values. +
+
+The worker attribute connect_timeout sets the wait timeout +in milliseconds for CPong during connection establishment. You can use it +if you want to overwrite the general timeout set with ping_timeout. +To use connect mode CPing, you need to enable it via ping_mode. +Since JK usually uses persistent connections, opening new connections is a +rare event. We therefore recommend activating connect mode. +Depending on your network latency and stability, good values often +are between 5000 and 15000 milliseconds. +Remember: don't use extremely small values. +
+
+The worker attribute prepost_timeout sets the wait timeout +in milliseconds for CPong before request forwarding. You can use it +if you want to overwrite the general timeout set with ping_timeout. +To use prepost mode CPing, you need to enable it via ping_mode. +Activating this type of CPing/CPong adds a small latency to each +request. Usually this is small enough and the benefit of CPing/CPong is more important. +So in general we also recommend using prepost_timeout. +Depending on your network latency and stability, good values often +are between 5000 and 10000 milliseconds. +Remember: don't use extremely small values. +
+
+Until version 1.2.27 ping_mode and ping_timeout did not +exist and to enable connect or prepost mode CPing you had to set connect_timeout +respectively prepost_timeout to some reasonable positive value. +
+
+ +
Low-Level TCP Timeouts
+
+Some platforms allow to set timeouts for all operations on TCP sockets. +This is available for Linux and Windows, other platforms do not support this, +e.g. Solaris. If your platform supports TCP send and receive timeouts, +you can set them using the worker attribute socket_timeout. +You can not set the two timeouts to different values. +
+
+JK will accept this attribute even if your platform does not support +socket timeouts. In this case setting the attribute will have no effect. +By default the value is "0" and the timeout is disabled. +You can set the attribute to some seconds value (not: milliseconds). +JK will then set the send and the receive timeouts of the backend +connections to this value. The timeout is low-level, it is +used for each read and write operation on the socket individually. +
+
+Using this attribute will make JK react faster to some types of network problems. +Unfortunately socket timeouts have negative side effects, because for most +platforms, there is no good way to recover from such a timeout, once it fired. +For JK there is no way to decide, if this timeout fired because of real network +problems, or only because it didn't receive an answer packet from a backend in time. +So remember: don't use extremely small values. +
+
+For the general case of connection establishment you can use +socket_connect_timeout. It takes a millisecond value and works +on most platforms, even if socket_timeout is not supported. +We recommend using socket_connect_timeout because in some network +failure situations failure detection during connection establishment +can take several minutes due to TCP retransmits. Depending on the quality +of your network a timeout somewhere between 1000 and 5000 milliseconds +should be fine. Note that socket_timeout is in seconds, and +socket_connect_timeout in milliseconds. +
+
+ +
Connection Pools and Idle Timeouts
+
+JK handles backend connections in a connection pool per web server process. +The connections are used in a persistent mode. After a request completed +successfully we keep the connection open and wait for the next +request to forward. The connection pool is able to grow according +to the number of threads that want to forward requests in parallel. +
+
+Most applications have a varying load depending on the hour of the day +or the day of the month. Other reasons for a growing connection pool +would be temporary slowness of backends, leading to an increasing +congestion of the frontends like web servers. Many backends use a dedicated +thread for each incoming connection they handle. So usually one wants the +connection pool to shrink, if the load diminishes. +
+
+JK allows connections in the pool to get closed after some idle time. +This maximum idle time can be configured with the attribute +connection_pool_timeout which is given in units of seconds. +The default value is "0", which disables closing idle connections. +
+
+We generally recommend values around 10 minutes, so setting +connection_pool_timeout to 600 (seconds). If you use this attribute, +please also set the attribute connectionTimeout in the AJP +Connector element of your Tomcat server.xml configuration file to +an analogous value. Caution: connectionTimeout is in milliseconds. +So if you set JK connection_pool_timeout to 600, you should set Tomcat +connectionTimeout to 600000. +
+
+JK connections do not get closed immediately after the timeout passed. +Instead there is an automatic internal maintenance task +running every 60 seconds, that checks the idle status of all connections. +The 60 seconds interval +can be adjusted with the global attribute worker.maintain. We do not +recommend to change this value, because it has a lot of side effects. +Until version 1.2.26, the maintenance task only runs, if requests get +processed. So if your web server has processes that do not receive any +requests for a long time, there is no way to close the idle connections +in its pool. Starting with version 1.2.27 you can configure an independent +watchdog thread when using Apache 2.x with threaded APR or IIS. +
+
+The maximum connection pool size can be configured with the +attribute connection_pool_size. We generally do not recommend +to use this attribute in combination with Apache httpd. For +Apache httpd we automatically detect the number of threads per +process and set the maximum pool size to this value. For IIS we use +a default value of 250 (before version 1.2.20: 10), +for the Sun Web Server the default is "1". +We strongly recommend adjusting this value for IIS and the Sun Web Server +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 hours without performance problems, and then add some +percentage depending on your growth rate etc. 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. +
+
+The JK attribute connection_pool_minsize defines, +how many idle connections remain when the pool gets shrunken. +By default this is half of the maximum pool size. +
+
+ +
Firewall Connection Dropping
+
+One particular problem with idle connections comes from firewalls, that +are often deployed between the web server layer and the backend. +Depending on their configuration, they will silently drop +connections from their status table if they are idle for to long. +
+
+From the point of view of JK and of the web server, the other side +simply doesn't answer any traffic. Since TCP is a reliable protocol +it detects the missing TCP ACKs and tries to resend the packets for +a relatively long time, typically several minutes. +
+
+Many firewalls will allow connection closing, even if they dropped +the connection for normal traffic. Therefore you should always use +connection_pool_timeout and +connection_pool_minsize on the JK side +and connectionTimeout on the Tomcat side. +
+
+Furthermore using the boolean attribute socket_keepalive you can +set a standard socket option, that automatically sends TCP keepalive packets +after some idle time on each connection. By default this is set to "False". +If you suspect idle connection drops by firewalls you should set this to +"True". +
+
+Unfortunately the default intervals and algorithms for these packets +are platform specific. You might need to inspect TCP tuning options for +your platform on how to control TCP keepalive. +Often the default intervals are much longer than the firewall timeouts +for idle connections. Nevertheless we recommend talking to your firewall +administration and your platform administration in order to make them agree +on good configuration values for the firewall and the platform TCP tuning. +
+
+In case none of our recommendations help and you are definitively having +problems with idle connection drops, you can disable the use of persistent +connections when using JK together with Apache httpd. For this you set +"JkOptions +DisableReuse" in your Apache httpd configuration. +This will have a huge negative performance impact! +
+
+ +
Reply Timeout
+
+JK can also use a timeout on request replies. This timeout does not +measure the full processing time of the response. Instead it controls, +how much time between consecutive response packets is allowed. +
+
+In most cases, this is what one actually wants. Consider for example +long running downloads. You would not be able to set an effective global +reply timeout, because downloads could last for many minutes. +Most applications though have limited processing time before starting +to return the response. For those applications you could set an explicit +reply timeout. Applications that do not harmonise with reply timeouts +are batch type applications, data warehouse and reporting applications +which are expected to observe long processing times. +
+
+If JK aborts waiting for a response, because a reply timeout fired, +there is no way to stop processing on the backend. Although you free +processing resources in your web server, the request +will continue to run on the backend - without any way to send back a +result once the reply timeout fired. +
+
+JK uses the worker attribute reply_timeout to set reply timeouts. +The default value is "0" (timeout disabled) and you can set it to any +millisecond value. +
+
+In combination with Apache httpd, you can also set a more flexible reply_timeout +using an httpd environment variable. If you set the variable JK_REPLY_TIMEOUT +to some integer value, this value will be used instead of the value in +the worker configuration. This way you can set reply timeouts more flexible +with mod_setenvif and mod_rewrite depending on URI, query string etc. +If the environment variable JK_REPLY_TIMEOUT is not set, or is set to a +negative value, the default reply timeout of the worker will be used. If +JK_REPLY_TIMEOUT contains the value "0", then the reply timeout will be disabled +for the request. +
+
+In combination with a load balancing worker, JK will disable a member +worker of the load balancer if a reply timeout fires. The worker will then +no longer be used until it gets recovered during the next automatic +maintenance task. Starting with JK 1.2.24 you can improve this behaviour using +max_reply_timeouts. This +attribute will allow occasional long running requests without disabling the +worker. Only if those requests happen to often, the worker gets disabled by the +load balancer. +
+
+

Load Balancer Error Detection

+
+
Local and Global Error States
+
+A load balancer worker does not only have the ability to balance load. +It also handles stickyness and failover of requests in case of errors. +When a load balancer detects an error on one of its members, it needs to +decide, whether the error is serious, or only a temporary error or maybe +only related to the actual request that was processed. Temporary errors +are called local errors, serious errors will be called global errors. +
+
+If the load balancer decides that a backend should be put into the global error +state, then the web server will not send any more requests there. If no session +replication is used, this means that all user sessions located on the respective +backend are no longer available. The users will be send to another backend +and will have to login again. So the global error state is not transparent to the +users. The application is still available, but users might loose some work. +
+
+In some cases the decision between local error and global error is easy. +For instance if there is an error sending back the response to the client (browser), +then it is very unlikely that the backend is broken. +So this situation is a typical example of a local error. +
+
+Some situations are harder to decide though. If the load balancer can't establish +a new connection to a backend, it could be because of a temporary overload situation +(so no more free threads in the backend), or because the backend isn't alive any more. +Depending on the details, the right state could either be local error or global error. +
+
+
Error Escalation Time
+
+Until version 1.2.26 most errors were interpreted as global errors. +Starting with version 1.2.27 many errors which were previously interpreted as global +were switched to being local whenever the backend is still busy. Busy means, that +other concurrent requests are send to the same backend (successful or not). +
+
+In many cases there is no perfect way of making the decision +between local and global error. The load balancer simply doesn't have enough information. +In version 1.2.28 you can now tune, how fast the load balancer switches from local error to +global error. If a member of a load balancer stays in local error state for too long, +the load balancer will escalate it into global error state. +
+
+The time tolerated in local error state is controlled by the load balancer attribute +error_escalation_time (in seconds). The default value is half of recover_time, +so unless you changed recover_time the default is 30 seconds. +
+
+Using a smaller value for error_escalation_time will make the load balancer react +faster to serious errors, but also carries the risk of more often loosing sessions +in not so serious situations. You can lower error_escalation_time down to 0 seconds, +which means all local errors which are potentially serious are escalated to global errors +immediately. +
+
+Note that without good basic error detection the whole escalation procedure is useless. +So you should definitely use socket_connect_timeout and activate CPing/CPong +with ping_mode and ping_timeout before thinking about also tuning +error_escalation_time. +
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/workers.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/workers.html new file mode 100644 index 00000000..3e8c3570 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/printer/workers.html @@ -0,0 +1,408 @@ +The Apache Tomcat Connector - Generic HowTo - Workers HowTo

The Apache Tomcat Connector - Generic HowTo

Workers HowTo

Introduction

+
+A Tomcat worker is a Tomcat instance that is waiting to execute servlets 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. +
+ +
+This document was originally part of Tomcat: A Minimalistic User's Guide written by Gal Shachor, +but has been split off for organisational reasons. +
+

Defining Workers

+
+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 file contains entries of the following form: +
+ +
+worker.list=<a comma separated list of worker names> +
+ +
+  # the list of workers
+  worker.list= worker1, worker2
+
+ +
+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. The directive can be used multiple times. +
+ +
Workers Type
+
+Each named worker should also have a few entries to provide additional information on his behalf. +This information includes the worker's type and other related worker information. +Currently the following worker types that exists are (JK 1.2.5): +
+ + + + + + + + +
Type Description
ajp12 This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol.
ajp13 This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol.
jni DEPRECATED: This worker knows how to forward requests to in-process Tomcat workers using JNI.
lb This is a load-balancing worker; it knows how to provide round-robin based sticky load balancing with a certain level of fault-tolerance.
status This is a status worker for managing load balancers.
+ +
+Defining workers of a certain type should be done with the following property format: +
+ +
+worker.worker name.type=<worker type> +Where worker name is the name assigned to the worker and the worker type is one of the four types defined +in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]). +
+ +
+  # Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
+  worker.local.type=ajp12
+  # Defines a worker named "remote" that uses the ajpv13 protocol to forward requests to a Tomcat process.
+  worker.remote.type=ajp13
+  # Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
+  worker.loadbalancer.type=lb
+
+ +
+ +

Setting Worker Properties

+
+After defining the workers you can also specify properties for them. +Properties can be specified in the following manner: +
+ +
+worker.<worker name>.<property>=<property value> +
+ +Each worker has a set of properties that you can set as specified in the following subsections: + +
ajp12 Worker properties
+
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x and 5 and 5.5 and Tomcat 6. +
+
+The ajp12 typed workers forward requests to out-of-process Tomcat workers +using the ajpv12 protocol over TCP/IP sockets. +
+ +
+the ajp12 worker properties are : +
+ +
+host property sets the host where the Tomcat worker is listening for ajp12 requests. +
+ +
+port property sets the port where the Tomcat worker is listening for ajp12 requests +
+ +
+lbfactor property is used when working with a load balancer worker, this is the load-balancing factor for the worker. +We'll see more on this in the lb worker section. +
+ +
+  # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
+  worker.worker1.host=www.x.com
+  worker.worker1.port=8007
+  worker.worker1.lbfactor=2
+
+ +
+Notes: In the ajpv12 protocol, connections are created, used and then closed at each request. +The default port for ajp12 is 8007 +
+ +
+ +
ajp13 Worker properties
+
+The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets. +The main difference between ajpv12 and ajpv13 are that: +
+
+ajpv13 is a more binary protocol and it tries to compress some of the request data by coding +frequently used strings as small integers. +
+
+ajpv13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your +web server and Tomcat). +
+
+ajpv13 has special treatment for SSL information so that the container can implement +SSL related methods such as isSecure(). +
+
+ +
+ +
+You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6. +
+ + +
+  # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
+  worker.worker2.host=www2.x.com
+  worker.worker2.port=8009
+  worker.worker2.lbfactor=3
+  # worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
+  worker.worker2.connection_pool_timeout=600
+  # worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
+  worker.worker2.socket_keepalive=1
+  # mount can be used as an alternative to the JkMount directive
+  worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
+
+ +
+Notes: In the ajpv13 protocol, the default port is 8009 +
+ +
+ +
lb Worker properties
+
+The load-balancing worker does not really communicate with Tomcat workers. +Instead it is responsible for the management of several "real" workers. +This 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 falling-back 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. +The following table specifies some properties that the lb worker can accept: +
+
balance_workers is a comma separated list of workers that the load balancer need to manage. +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. +This directive can be used multiple times for the same load balancer.
+
sticky_session specifies whether requests with SESSION ID's should be routed back to the same +Tomcat worker. Set sticky_session to False when Tomcat is using a Session Manager which +can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.
+
+
+ +
+  # The worker balance1 while use "real" workers worker1 and worker2
+  worker.balance1.balance_workers=worker1, worker2
+
+ +
+ +
Status Worker properties
+
+The status worker does not communicate with Tomcat. +Instead it is responsible for the load balancer management. +
+
+  # Add the status worker to the worker list
+  worker.list=jkstatus
+  # Define a 'jkstatus' worker using status
+  worker.jkstatus.type=status
+
+
Next thing is to mount the requests to the jkstatus worker. For Apache +web servers use the:
+
+  # Add the jkstatus mount point
+  JkMount /jkmanager/* jkstatus 
+
+
To obtain a higher level of security use the:
+
+  # Enable the JK manager access from localhost only
+ <Location /jkmanager/>
+    JkMount jkstatus
+    Order deny,allow
+    Deny from all
+    Allow from 127.0.0.1
+ </Location>
+
+ +
+ +
Property file macros
+
+You can define "macros" in the property files. +These macros let you define properties and later on use them while +constructing other properties. +
+ +
+  # property example, like a network base address
+  mynet=194.226.31
+  # Using the above macro to simplify the address definitions
+  # for a farm of workers.
+  worker.node1.host=$(mynet).11
+  worker.node2.host=$(mynet).12
+  worker.node3.host=$(mynet).13
+
+ +
+ +
Hierarchical property configuration
+
+Workers can reference configurations of other workers. +If worker "x" references worker "y", then it inherits all +configuration parameters from "y", except for the ones +that have explicitly been set for "x". +
+ +
+  # worker toe defines some default settings
+  worker.toe.type=ajp13
+  worker.toe.socket_keepalive=true
+  worker.toe.connect_timeout=10000
+  worker.toe.recovery_options=7
+  # workers tic and tac inherit those values
+  worker.tic.reference=worker.toe
+  worker.tac.reference=worker.toe
+
+ +
+Please note, that the reference contains +the full prefix to the referenced configuration attributes, +not only the name of the referenced worker. +
+ +
+References can be nested. Be careful to avoid loops! +
+ +
+Attributes which are allowed multiple times for a single worker +can not be merged from a worker and a reference. An attribute +is only inherited from a reference, if it is not already set +for the referring worker. +
+ +
+References are especially useful, when configuring load balancers. +Try to understand the following two stage references: +
+ +
+  # We only use one load balancer
+  worker.list=lb
+  # Let's define some defaults
+  worker.basic.port=8009
+  worker.basic.type=ajp13
+  worker.basic.socket_keepalive=true
+  worker.basic.connect_timeout=10000
+  worker.basic.recovery_options=7
+  # And we use them in two groups
+  worker.lb1.domain=dom1
+  worker.lb1.distance=0
+  worker.lb1.reference=worker.basic
+  worker.lb2.domain=dom2
+  worker.lb2.distance=1
+  worker.lb2.reference=worker.basic
+  # Now we configure the load balancer
+  worker.lb.type=lb
+  worker.lb.method=B
+  worker.lb.balanced_workers=w11,w12,w21,w22
+  worker.w11.host=myhost11
+  worker.w11.reference=worker.lb1
+  worker.w12.host=myhost12
+  worker.w12.reference=worker.lb1
+  worker.w21.host=myhost21
+  worker.w21.reference=worker.lb2
+  worker.w22.host=myhost22
+  worker.w22.reference=worker.lb2
+
+ +
+ +

A sample worker.properties

+
+Since coping with worker.properties on your own is not an easy thing to do, +a sample worker.properties file is bundled along JK. +
+ +
+You could also find here a sample workers.properties defining : +
+ +
+
+An ajp12 worker that used the host localhost and the port 8007 +
+
+An ajp13 worker that used the host localhost and the port 8008 +
+
+An lb worker that load balance the ajp12 and ajp13 workers +
+
+ +
+  # Define 3 workers, 2 real workers using ajp12, ajp13, the last one being a loadbalancing worker 
+  worker.list=worker1, worker2, worker3
+  # Set properties for worker1 (ajp12)
+  worker.worker1.type=ajp12
+  worker.worker1.host=localhost
+  worker.worker1.port=8007
+  worker.worker1.lbfactor=1
+  # Set properties for worker2 (ajp13)
+  worker.worker2.type=ajp13
+  worker.worker2.host=localhost
+  worker.worker2.port=8009
+  worker.worker2.lbfactor=1
+  worker.worker2.connection_pool_timeout=600
+  worker.worker2.socket_keepalive=1
+  worker.worker2.socket_timeout=60
+  # Set properties for worker3 (lb) which use worker1 and worker2
+  worker.worker3.balance_workers=worker1,worker2
+
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/proxy.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/proxy.html new file mode 100644 index 00000000..01c82500 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/proxy.html @@ -0,0 +1,313 @@ +The Apache Tomcat Connector - Generic HowTo - Reverse Proxy HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Generic HowTo

Reverse Proxy HowTo

print-friendly
version +

Introduction

+
+
The Apache module mod_jk and its ISAPI and NSAPI variants connect +a web server to a backend (typically Tomcat) using the AJP protocol. +The web server receives an HTTP(S) request and the module forwards +the request to the backend. This function is usually called a gateway +or a proxy, in the context of HTTP it is called a reverse proxy. +
+

Typical Problems

+
+
A reverse proxy is not totally transparent to the application on +the backend. For instance the host name and port the original client +(e.g. browser) needs to talk to belong to the web server and not to the +backend, so the reverse proxy talks to a different host name and port. +When the application on the backend returns content including +self-referential URLs using its own backend address and port, the +client will usually not be able to use these URLs. +
+
Another example is the client IP address, which for the web server is the +source IP of the incoming connection, whereas for the backend the +connection always comes from the web server. This can be a problem, when +the client IP is used by the backend application e.g. for security reasons. +
+

AJP as a Solution

+
+
Most of these problems are automatically handled by the AJP protocol +and the AJP connectors of the backend. The AJP protocol transports +this communication metadata and the backend connector presents this +metadata whenever the application asks for it using Servlet API methods. +
+
The following list contains the communication metadata handled by AJP +and the ServletRequest/HttpServletRequest API calls which can be used to retrieve them: +
+
local name: getLocalName() and getLocalAddr. +This is also equal to getServerName(), unless a Host header +is contained in the request. In this case the server name is taken from that header. +
+
local port: getLocalPort() +This is also equal to getServerPort(), unless a Host header +is contained in the request. In this case the server port is taken from that header +if it contains an explicit port, or is equal to the default port of the scheme used. +
+
client address: getRemoteAddr() +
+
client port: getRemotePort() +The remote port was initially not supported. It is available when using mod_jk 1.2.32 +with Apache or IIS (not for the NSAPI plugin) together with Tomcat version at least +5.5.28, 6.0.20 or 7.0.0. For older versions, getRemotePort() +will incorrectly return 0 or -1. As a workaround you can forward the remote port by setting +JkEnvVar REMOTE_PORT and then either using +request.getAttribute("REMOTE_PORT") instead of getRemotePort() +or wrapping the request using a filter and overriding getRemotePort() with +request.getAttribute("REMOTE_PORT"). +
+
client host: getRemoteHost() +
+
authentication type: getAuthType() +
+
remote user: getRemoteUser(), +if tomcatAuthentication="false" +
+
protocol: getProtocol() +
+
HTTP method: getMethod() +
+
URI: getRequestURI() +
+
HTTPS used: isSecure(), getScheme() +
+
query string: getQueryString() +
+
+The following additional SSL-related data will be made available by Apache and forwarded by mod_jk only +if you set SSLOptions +StdEnvVars. For the certificate information you also need +to set SSLOptions +ExportCertData. +
+
SSL cipher: getAttribute(javax.servlet.request.cipher_suite) +
+
SSL key size: getAttribute(javax.servlet.request.key_size). +Can be disabled using JkOptions -ForwardKeySize. +
+
SSL client certificate: getAttribute(javax.servlet.request.X509Certificate). +If you want the whole certificate chain, then you need to also set JkOptions ForwardSSLCertChain. +It is likely, that in this case you also need to adjust the maximal AJP packet size +using the worker attribute max_packet_size. +
+
SSL session ID: getAttribute(javax.servlet.request.ssl_session). +This is for Tomcat, it has not yet been standardized. +
+
+
+

Fine Tuning

+
+
In some situations this is not enough though. Assume there is another +less clever reverse proxy in front of your web server, for instance an +HTTP load balancer or similar device which also serves as an SSL accelerator. +
+
Then you are sure that all your clients use HTTPS, but your web server doesn't +know about that. All it can see is requests coming from the accelerator using +plain HTTP. +
+
Another example would be a simple reverse proxy in front of your web server, +so that the client IP address that your web server sees is always the IP address +of this reverse proxy, and not of the original client. Often such reverse proxies +generate an additional HTTP header, like X-Forwareded-for which +contains the original client IP address (or a list of IP addresses, if there are +more cascading reverse proxies in front). It would be nice, if we could use the +content of such a header as the client IP address to pass to the backend. +
+
So we might need to manipulate some of the data that AJP sends to the backend. +When using mod_jk inside Apache httpd you can use several httpd environment +variables to let mod_jk know, which data it should forward. These environment variables +can be set by the httpd directives SetEnv or SetEnvIf, but also in a very flexible +way using mod_rewrite (since httpd 2.x it can not only test against environment +variables, but also set them). +
+
The following list contains all environment variables mod_jk checks, before +sending data to the backend: +
+
JK_LOCAL_NAME: the local name +
+
JK_LOCAL_PORT: the local port +
+
JK_REMOTE_HOST: the client host +
+
JK_REMOTE_ADDR: the client address +
+
JK_AUTH_TYPE: the authentication type +
+
JK_REMOTE_USER: the remote user +
+
HTTPS: On (case-insensitive) to indicate, that HTTPS is used +
+
SSL_CIPHER: the SSL cipher +
+
SSL_CIPHER_USEKEYSIZE: the SSL key size +
+
SSL_CLIENT_CERT: the SSL client certificate +
+
SSL_CLIENT_CERT_CHAIN_: prefix of variable names, containing +the client cerificate chain +
+
SSL_SESSION_ID: the SSL session ID +
+
+
+
Remember: in general you don't need to set them. The module retrieves the data automatically +from the web server. Only in case you want to change this data, you can overwrite it by +using these variables. +
+
Some of these variables might also be used by other web server modules. All +variables whose name does not begin with "JK" are set directly by Apache httpd. +If you want to change the data, but do not want to negatively influence the behaviour +of other modules, you can change the names of all variables mod_jk uses to private ones. +For the details see the Apache reference page. +
+
All variables, that are not SSL-related have only been introduced in version 1.2.27. +
+
Finally there is a shortcut to forward the local IP of the web server as the remote IP. +This can be useful, e.g. when using the Tomcat remote address valve for allowing connections +only from registered Apache web servers. This feature is activated by setting +JkOptions ForwardLocalAddress. +
+

Tomcat AJP Connector Settings

+
+
As an alternative to using the environment variables described in the previous section +(which do only exist when using Apache httpd), you can also configure Tomcat to overwrite +some of the communications data forwarded by mod_jk. The AJP connector in Tomcat's server.xml +allows to set the following properties: +
+
proxyName: server name as returned by getServerName() +
+
proxyPort: server port as returned by getServerPort() +
+
scheme: protocol scheme as returned by getScheme() +
+
secure: set to "true", if you wish isSecure() to return "true". +
+
+Remember: in general you don't need to set those. AJP automatically handles all cases +where the web server running mod_jk knows the right data. +
+

URL Handling

+
+
URL Rewriting
+
Sometimes one want to change path components of the URLs under which an application +is available. Especially if a web application is deployed as some context, say /myapp, +marketing prefers short URLs, so want the application to be directly available under +http://www.mycompany.com/. Although you can deploy the application as the so-called +ROOT context, which will be directly available at "/", admins often prefer not to use +the ROOT context, e.g. because only one application can be the root context (per host). +
+
The procedure to change the URLs in the reverse proxy is tedious, because often +an application produces self-referential URLs, which then include the path components +which you tried to hide to the outside world. Nevertheless, if you absolutely need to do it, +here are the steps. +
+
Case A: You need to make the application available at a simple URL, but it is OK, if +users proceed using the more complex URLs, as long as they don't have to type them in. +That's the easy case, and if this suffices to you, you're lucky. Use a simply RedirectMatch +for Apache httpd: +
+
+RedirectMatch ^/$ http://www.mycompany.com/myapp/
+
+
Your application will then be available under http://www.mycompany.com/, +and each visitor will be immediately redirected to the real URL +http://www.mycompany.com/myapp/ +
+
Case B: You need to hide path components for all requests going to the application. +Here's the recipe for the case, where you want to hide the first path component +/myapp. More complex manipulations are left as an exercise to the reader. +First the solution for the case of Apache httpd: +
+
1. Use mod_rewrite +to add /myapp to all requests before forwarding to the backend: +
+
+# Don't forget the PT flag! (pass through)
+RewriteRule ^/(.*) http://www.mycompany.com/myapp/$1 [PT]
+
+
2. Use mod_headers +to rewrite any HTTP redirects your application might return. Such redirects typically contain +the path components you want to hide, because by the HTTP standard, redirects always need to include +the full URL, and your application is not aware of the fact, that your clients talk to it via +some shortened URL. An HTTP redirect is done with a special response header named Location. +We rewrite the Location headers of our responses: +
+
+# Keep protocol, server and port if present,
+# but insert our webapp name before the rest of the URL
+Header edit Location ^([^/]*//[^/]*)?/(.*)$ $1/myapp/$2 
+
+
3. Use mod_headers again, to rewrite the paths contained in any cookies, +your application might set. Such cookie paths again might contain +the path components you want to hide. +A cookie is set with the HTTP response header named Set-Cookie. +We rewrite the Set-Cookie headers of our responses: +
+
+# Fix the cookie path
+Header edit Set-Cookie "^(.*; Path=/)(.*)" $1/myapp/$2 
+
+
3. Some applications might contain hard coded absolute links. +In this case check, whether you find a configuration item for your web framework +to configure the base URL. If not, your only chance is to parse all response +content bodies and do search and replace. This is fragile and very resource intensive. +If you really need to do this, you can use +mod_proxy_html, +mod_substitute +or mod_sed +for this task. +
+
If you are using Microsoft IIS as a web server, the ISAPI plugin provides a way +of doing the first step with a builtin feature. You define a mapping file for simple prefix +changes like this: +
+
+# Add a context prefix to all requests ...
+/=/myapp/
+# ... or change some prefix ...
+/oldapp/=/myapp/
+
+
and then put the name of the file in the rewrite_rule_file entry of the registry or your +isapi_redirect.properties file. In you uriworkermap.properties file, you +still need to map the URLs as they are before rewriting! +
+
More complex rewrites can be done using the same file, but with regular expressions. A leading +tilde sign '~', indicates, that you are using a regular expression: +
+
+# Use a regular expression rewrite
+~/oldapps([0-9]*)/=/newapps$1/
+
+
There is no support for Steps 2 (rewriting redirect responses) or 3 (rewriting cookie paths). +
+
+
URL Encoding
+
Some types of problems are triggered by the use of encoded URLs +(see percent encoding). +For the same location there exist +a lot of different URLs which are equivalent. The reverse proxy needs to inspect the URL in order +to apply its own authentication rules and to decide, to which backend it should send the request +(or whether it should handle it itself). Therefore the request URL first is normalized: +percent encoded characters are decoded, /./ is replaced by /, +/XXX/../ is replaced by / and similar manipulations of the URL are done. +After that, the web server might apply rewrite rules to further change the URL in less obvious ways. +Finally there is no more way to put the resulting URL in an encoding, which is "similar" to +the one which was used for the original URL. +
+
+For historical reasons, there have been several alternatives, how mod_jk and the ISAPI +plugin encoded the resulting URL before sending it to the backend. They could be chosen via +JkOptions (Apache httpd) or uri_select (ISAPI). None of those historical +encodings are recommended, because they have either negative functionality implications or +pose a security risk. The default encoding since version 1.2.24 is ForwardURIProxy +(Apache httpd) or proxy (ISAPI) and it is strongly recommended to keep the default +and remove all old explicit settings. +
+
+

Request Attributes

+
+
+You can also add more attributes to any request you are forwarding when using Apache httpd. +For this use the JkEnvVar directive (for details see the +Apache reference page). Such request attributes can be +retrieved on the Tomcat side via request.getAttribute(attributeName). +Note that their names will not be listed in request.getAttributeNames()! +
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/quick.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/quick.html new file mode 100644 index 00000000..68cad946 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/quick.html @@ -0,0 +1,131 @@ +The Apache Tomcat Connector - Generic HowTo - Quick Start HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Generic HowTo

Quick Start HowTo

print-friendly
version +

Introduction

+
+ This document describes the configuration files used by JK on the + Web Server side for the 'impatient': +
+
+ workers.properties is a mandatory file used by the webserver and which + is the same for all JK implementations (Apache/IIS/NES). +
+
+ web server add-ons to be set on the webserver side. +
+
+
+
+ We'll give here minimum servers configuration and an example workers.properties + to be able to install and check quickly your configuration. +
+

Minimum workers.properties

+
+ Here is a minimum workers.properties, using just ajp13 to connect your Apache webserver + to the Tomcat engine, complete documentation is available in Workers HowTo. +
+
+
+
+  # Define 1 real worker using ajp13
+  worker.list=worker1
+  # Set properties for worker1 (ajp13)
+  worker.worker1.type=ajp13
+  worker.worker1.host=localhost
+  worker.worker1.port=8009
+
+
+
+

Minimum Apache web server configuration

+
+ Here is a minimum information about Apache configuration, a + more complete separate HowTo for Apache is available. +
+
+ You should first have mod_jk.so (unix) or mod_jk.dll (Windows) installed + in your Apache module directory (see your Apache documentation to locate it). +
+
+ Usual locations for modules directory on Unix: +
+
/usr/lib/apache/
+
/usr/lib/apache2/
+
/usr/local/apache/libexec/
+
+
+
+ Usual locations for modules directory on Windows : +
+
C:\Program Files\Apache Group\Apache\modules\
+
C:\Program Files\Apache Group\Apache2\modules\
+
+
+
+ You'll find a link to prebuilt binaries + here +
+
+ Here is the minimum which should be set in httpd.conf directly or + included from another file: +
+
+ Usual locations for configuration directory on Unix: +
+
/etc/httpd/conf/
+
/etc/httpd2/conf/
+
/usr/local/apache/conf/
+
+
+
+ Usual locations for configuration directory on Windows : +
+
C:\Program Files\Apache Group\Apache\conf\
+
C:\Program Files\Apache Group\Apache2\conf\
+
+
+
+
+
+  # Load mod_jk module
+  # Update this path to match your modules location
+  LoadModule    jk_module  libexec/mod_jk.so
+  # Declare the module for <IfModule directive> (remove this line on Apache 2.x)
+  AddModule     mod_jk.c
+  # Where to find workers.properties
+  # Update this path to match your conf directory location (put workers.properties next to httpd.conf)
+  JkWorkersFile /etc/httpd/conf/workers.properties
+  # Where to put jk shared memory
+  # Update this path to match your local state directory or logs directory
+  JkShmFile     /var/log/httpd/mod_jk.shm
+  # Where to put jk logs
+  # Update this path to match your logs directory location (put mod_jk.log next to access_log)
+  JkLogFile     /var/log/httpd/mod_jk.log
+  # Set the jk log level [debug/error/info]
+  JkLogLevel    info
+  # Select the timestamp log format
+  JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+  # Send everything for context /examples to worker named worker1 (ajp13)
+  JkMount  /examples/* worker1
+
+
+
+

Minimum IIS web server configuration

+
+ A separate HowTo for the IIS web server is available. +
+
+ This paragraph has not been written yet, but you can contribute to it. +
+

Minimum NES/iPlanet/Sun web server configuration

+
+ A separate HowTo for the Netscape/iPlanet/Sun web server is available. +
+ This paragraph has not been written yet, but you can contribute to it. +
+
+

Test your configuration

+
+ (Re)start the web server and browse to the http://localhost/examples/ +
+ +

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/timeouts.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/timeouts.html new file mode 100644 index 00000000..67fcf90b --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/timeouts.html @@ -0,0 +1,374 @@ +The Apache Tomcat Connector - Generic HowTo - Timeouts HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Generic HowTo

Timeouts HowTo

print-friendly
version +

Introduction

+
+
Setting communication timeouts is very important to improve the +communication process. They help to detect problems and stabilise +a distributed system. JK can use several different timeout types, which +can be individually configured. For historical reasons, all of them are +disabled by default. This HowTo explains their use and gives +hints how to find appropriate values. +
+
All timeouts can be configured in the workers.properties file. +For a complete reference of all worker configuration +items, please consult the worker reference. +This page assumes, that you are using at least version 1.2.16 of JK. +Dependencies on newer versions will be mentioned where necessary. +
+
+Do not set timeouts to extreme values. Very small timeouts will likely +be counterproductive. +
+
+Long Garbage Collection pauses on the backend do not make a good +fit with some timeouts. Try to optimise your Java memory and GC settings. +
+

JK Timeout Attributes

+
+
CPing/CPong
+
+CPing/CPong is our notion for using small test packets to check the +status of backend connections. JK can use such test packets directly after establishing +a new backend connection (connect mode) and also directly before each request gets +send to a backend (prepost mode). +Starting with version 1.2.27 it can also be used when a connection was idle +for a long time (interval mode). +The maximum waiting time (timeout) for a CPong answer to a CPing and the idle +time in interval mode can be configured. +
+
+The test packets will be answered by the backend very fast with a minimal amount of +needed processing resources. A positive answer tells us, that the backend can be reached +and is actively processing requests. It does not detect, if some context is deployed +and working. The benefit of CPing/CPong is a fast detection of a communication +problem with the backend. The downside is a slightly increased latency. +
+
+The worker attribute ping_mode can be set to a combination of characters +to determine, in which situations test packets are used: +
+
C: connect mode, timeout ping_timeout overwritten by connect_timeout
+
P: prepost mode, timeout ping_timeout overwritten by prepost_timeout
+
I: interval mode, timeout ping_timeout, idle time connection_ping_interval
+
A: all modes
+
+
+
+Multiple values must be concatenated without any separator characters. +We recommend using all CPing tests. If your application is very latency sensitive, then +you should only use the combination of connect and interval mode. +
+
+Activating the CPing probing via ping_mode has been added in version 1.2.27. +For older versions only the connect and prepost modes exist and must be activated by +explicitely setting connect_timeout and prepost_timeout. +
+
+The worker attribute ping_timeout sets the default wait timeout +in milliseconds for CPong for all modes. By default the value is "10000" +milliseconds. The value only gets used, if you activate CPing/Cpong probes +via ping_mode. The default value should be fine, except if you experience +very long Java garbage collection pauses. +Depending on your network latency and stability, good custom values +often are between 5000 and 15000 milliseconds. +You can overwrite the timeout used for connect and prepost mode with +connect_timeout and prepost_timeout. +Remember: don't use extremely small values. +
+
+The worker attribute connect_timeout sets the wait timeout +in milliseconds for CPong during connection establishment. You can use it +if you want to overwrite the general timeout set with ping_timeout. +To use connect mode CPing, you need to enable it via ping_mode. +Since JK usually uses persistent connections, opening new connections is a +rare event. We therefore recommend activating connect mode. +Depending on your network latency and stability, good values often +are between 5000 and 15000 milliseconds. +Remember: don't use extremely small values. +
+
+The worker attribute prepost_timeout sets the wait timeout +in milliseconds for CPong before request forwarding. You can use it +if you want to overwrite the general timeout set with ping_timeout. +To use prepost mode CPing, you need to enable it via ping_mode. +Activating this type of CPing/CPong adds a small latency to each +request. Usually this is small enough and the benefit of CPing/CPong is more important. +So in general we also recommend using prepost_timeout. +Depending on your network latency and stability, good values often +are between 5000 and 10000 milliseconds. +Remember: don't use extremely small values. +
+
+Until version 1.2.27 ping_mode and ping_timeout did not +exist and to enable connect or prepost mode CPing you had to set connect_timeout +respectively prepost_timeout to some reasonable positive value. +
+
+ +
Low-Level TCP Timeouts
+
+Some platforms allow to set timeouts for all operations on TCP sockets. +This is available for Linux and Windows, other platforms do not support this, +e.g. Solaris. If your platform supports TCP send and receive timeouts, +you can set them using the worker attribute socket_timeout. +You can not set the two timeouts to different values. +
+
+JK will accept this attribute even if your platform does not support +socket timeouts. In this case setting the attribute will have no effect. +By default the value is "0" and the timeout is disabled. +You can set the attribute to some seconds value (not: milliseconds). +JK will then set the send and the receive timeouts of the backend +connections to this value. The timeout is low-level, it is +used for each read and write operation on the socket individually. +
+
+Using this attribute will make JK react faster to some types of network problems. +Unfortunately socket timeouts have negative side effects, because for most +platforms, there is no good way to recover from such a timeout, once it fired. +For JK there is no way to decide, if this timeout fired because of real network +problems, or only because it didn't receive an answer packet from a backend in time. +So remember: don't use extremely small values. +
+
+For the general case of connection establishment you can use +socket_connect_timeout. It takes a millisecond value and works +on most platforms, even if socket_timeout is not supported. +We recommend using socket_connect_timeout because in some network +failure situations failure detection during connection establishment +can take several minutes due to TCP retransmits. Depending on the quality +of your network a timeout somewhere between 1000 and 5000 milliseconds +should be fine. Note that socket_timeout is in seconds, and +socket_connect_timeout in milliseconds. +
+
+ +
Connection Pools and Idle Timeouts
+
+JK handles backend connections in a connection pool per web server process. +The connections are used in a persistent mode. After a request completed +successfully we keep the connection open and wait for the next +request to forward. The connection pool is able to grow according +to the number of threads that want to forward requests in parallel. +
+
+Most applications have a varying load depending on the hour of the day +or the day of the month. Other reasons for a growing connection pool +would be temporary slowness of backends, leading to an increasing +congestion of the frontends like web servers. Many backends use a dedicated +thread for each incoming connection they handle. So usually one wants the +connection pool to shrink, if the load diminishes. +
+
+JK allows connections in the pool to get closed after some idle time. +This maximum idle time can be configured with the attribute +connection_pool_timeout which is given in units of seconds. +The default value is "0", which disables closing idle connections. +
+
+We generally recommend values around 10 minutes, so setting +connection_pool_timeout to 600 (seconds). If you use this attribute, +please also set the attribute connectionTimeout in the AJP +Connector element of your Tomcat server.xml configuration file to +an analogous value. Caution: connectionTimeout is in milliseconds. +So if you set JK connection_pool_timeout to 600, you should set Tomcat +connectionTimeout to 600000. +
+
+JK connections do not get closed immediately after the timeout passed. +Instead there is an automatic internal maintenance task +running every 60 seconds, that checks the idle status of all connections. +The 60 seconds interval +can be adjusted with the global attribute worker.maintain. We do not +recommend to change this value, because it has a lot of side effects. +Until version 1.2.26, the maintenance task only runs, if requests get +processed. So if your web server has processes that do not receive any +requests for a long time, there is no way to close the idle connections +in its pool. Starting with version 1.2.27 you can configure an independent +watchdog thread when using Apache 2.x with threaded APR or IIS. +
+
+The maximum connection pool size can be configured with the +attribute connection_pool_size. We generally do not recommend +to use this attribute in combination with Apache httpd. For +Apache httpd we automatically detect the number of threads per +process and set the maximum pool size to this value. For IIS we use +a default value of 250 (before version 1.2.20: 10), +for the Sun Web Server the default is "1". +We strongly recommend adjusting this value for IIS and the Sun Web Server +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 hours without performance problems, and then add some +percentage depending on your growth rate etc. 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. +
+
+The JK attribute connection_pool_minsize defines, +how many idle connections remain when the pool gets shrunken. +By default this is half of the maximum pool size. +
+
+ +
Firewall Connection Dropping
+
+One particular problem with idle connections comes from firewalls, that +are often deployed between the web server layer and the backend. +Depending on their configuration, they will silently drop +connections from their status table if they are idle for to long. +
+
+From the point of view of JK and of the web server, the other side +simply doesn't answer any traffic. Since TCP is a reliable protocol +it detects the missing TCP ACKs and tries to resend the packets for +a relatively long time, typically several minutes. +
+
+Many firewalls will allow connection closing, even if they dropped +the connection for normal traffic. Therefore you should always use +connection_pool_timeout and +connection_pool_minsize on the JK side +and connectionTimeout on the Tomcat side. +
+
+Furthermore using the boolean attribute socket_keepalive you can +set a standard socket option, that automatically sends TCP keepalive packets +after some idle time on each connection. By default this is set to "False". +If you suspect idle connection drops by firewalls you should set this to +"True". +
+
+Unfortunately the default intervals and algorithms for these packets +are platform specific. You might need to inspect TCP tuning options for +your platform on how to control TCP keepalive. +Often the default intervals are much longer than the firewall timeouts +for idle connections. Nevertheless we recommend talking to your firewall +administration and your platform administration in order to make them agree +on good configuration values for the firewall and the platform TCP tuning. +
+
+In case none of our recommendations help and you are definitively having +problems with idle connection drops, you can disable the use of persistent +connections when using JK together with Apache httpd. For this you set +"JkOptions +DisableReuse" in your Apache httpd configuration. +This will have a huge negative performance impact! +
+
+ +
Reply Timeout
+
+JK can also use a timeout on request replies. This timeout does not +measure the full processing time of the response. Instead it controls, +how much time between consecutive response packets is allowed. +
+
+In most cases, this is what one actually wants. Consider for example +long running downloads. You would not be able to set an effective global +reply timeout, because downloads could last for many minutes. +Most applications though have limited processing time before starting +to return the response. For those applications you could set an explicit +reply timeout. Applications that do not harmonise with reply timeouts +are batch type applications, data warehouse and reporting applications +which are expected to observe long processing times. +
+
+If JK aborts waiting for a response, because a reply timeout fired, +there is no way to stop processing on the backend. Although you free +processing resources in your web server, the request +will continue to run on the backend - without any way to send back a +result once the reply timeout fired. +
+
+JK uses the worker attribute reply_timeout to set reply timeouts. +The default value is "0" (timeout disabled) and you can set it to any +millisecond value. +
+
+In combination with Apache httpd, you can also set a more flexible reply_timeout +using an httpd environment variable. If you set the variable JK_REPLY_TIMEOUT +to some integer value, this value will be used instead of the value in +the worker configuration. This way you can set reply timeouts more flexible +with mod_setenvif and mod_rewrite depending on URI, query string etc. +If the environment variable JK_REPLY_TIMEOUT is not set, or is set to a +negative value, the default reply timeout of the worker will be used. If +JK_REPLY_TIMEOUT contains the value "0", then the reply timeout will be disabled +for the request. +
+
+In combination with a load balancing worker, JK will disable a member +worker of the load balancer if a reply timeout fires. The worker will then +no longer be used until it gets recovered during the next automatic +maintenance task. Starting with JK 1.2.24 you can improve this behaviour using +max_reply_timeouts. This +attribute will allow occasional long running requests without disabling the +worker. Only if those requests happen to often, the worker gets disabled by the +load balancer. +
+
+

Load Balancer Error Detection

+
+
Local and Global Error States
+
+A load balancer worker does not only have the ability to balance load. +It also handles stickyness and failover of requests in case of errors. +When a load balancer detects an error on one of its members, it needs to +decide, whether the error is serious, or only a temporary error or maybe +only related to the actual request that was processed. Temporary errors +are called local errors, serious errors will be called global errors. +
+
+If the load balancer decides that a backend should be put into the global error +state, then the web server will not send any more requests there. If no session +replication is used, this means that all user sessions located on the respective +backend are no longer available. The users will be send to another backend +and will have to login again. So the global error state is not transparent to the +users. The application is still available, but users might loose some work. +
+
+In some cases the decision between local error and global error is easy. +For instance if there is an error sending back the response to the client (browser), +then it is very unlikely that the backend is broken. +So this situation is a typical example of a local error. +
+
+Some situations are harder to decide though. If the load balancer can't establish +a new connection to a backend, it could be because of a temporary overload situation +(so no more free threads in the backend), or because the backend isn't alive any more. +Depending on the details, the right state could either be local error or global error. +
+
+
Error Escalation Time
+
+Until version 1.2.26 most errors were interpreted as global errors. +Starting with version 1.2.27 many errors which were previously interpreted as global +were switched to being local whenever the backend is still busy. Busy means, that +other concurrent requests are send to the same backend (successful or not). +
+
+In many cases there is no perfect way of making the decision +between local and global error. The load balancer simply doesn't have enough information. +In version 1.2.28 you can now tune, how fast the load balancer switches from local error to +global error. If a member of a load balancer stays in local error state for too long, +the load balancer will escalate it into global error state. +
+
+The time tolerated in local error state is controlled by the load balancer attribute +error_escalation_time (in seconds). The default value is half of recover_time, +so unless you changed recover_time the default is 30 seconds. +
+
+Using a smaller value for error_escalation_time will make the load balancer react +faster to serious errors, but also carries the risk of more often loosing sessions +in not so serious situations. You can lower error_escalation_time down to 0 seconds, +which means all local errors which are potentially serious are escalated to global errors +immediately. +
+
+Note that without good basic error detection the whole escalation procedure is useless. +So you should definitely use socket_connect_timeout and activate CPing/CPong +with ping_mode and ping_timeout before thinking about also tuning +error_escalation_time. +
+
+

\ No newline at end of file diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/workers.html b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/workers.html new file mode 100644 index 00000000..37f32ee7 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/docs/generic_howto/workers.html @@ -0,0 +1,409 @@ +The Apache Tomcat Connector - Generic HowTo - Workers HowTo

Links

Docs Home

Reference Guide

Generic HowTo

Webserver HowTo

AJP Protocol Reference

Miscellaneous Documentation

News

The Apache Tomcat Connector - Generic HowTo

Workers HowTo

print-friendly
version +

Introduction

+
+A Tomcat worker is a Tomcat instance that is waiting to execute servlets 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. +
+ +
+This document was originally part of Tomcat: A Minimalistic User's Guide written by Gal Shachor, +but has been split off for organisational reasons. +
+

Defining Workers

+
+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 file contains entries of the following form: +
+ +
+worker.list=<a comma separated list of worker names> +
+ +
+  # the list of workers
+  worker.list= worker1, worker2
+
+ +
+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. The directive can be used multiple times. +
+ +
Workers Type
+
+Each named worker should also have a few entries to provide additional information on his behalf. +This information includes the worker's type and other related worker information. +Currently the following worker types that exists are (JK 1.2.5): +
+ + + + + + + + +
Type Description
ajp12 This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol.
ajp13 This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol.
jni DEPRECATED: This worker knows how to forward requests to in-process Tomcat workers using JNI.
lb This is a load-balancing worker; it knows how to provide round-robin based sticky load balancing with a certain level of fault-tolerance.
status This is a status worker for managing load balancers.
+ +
+Defining workers of a certain type should be done with the following property format: +
+ +
+worker.worker name.type=<worker type> +Where worker name is the name assigned to the worker and the worker type is one of the four types defined +in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]). +
+ +
+  # Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
+  worker.local.type=ajp12
+  # Defines a worker named "remote" that uses the ajpv13 protocol to forward requests to a Tomcat process.
+  worker.remote.type=ajp13
+  # Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
+  worker.loadbalancer.type=lb
+
+ +
+ +

Setting Worker Properties

+
+After defining the workers you can also specify properties for them. +Properties can be specified in the following manner: +
+ +
+worker.<worker name>.<property>=<property value> +
+ +Each worker has a set of properties that you can set as specified in the following subsections: + +
ajp12 Worker properties
+
+The ajp12 has been deprecated with Tomcat 3.3.x and you should use instead +ajp13 which is the only ajp protocol known by Tomcat 4.x and 5 and 5.5 and Tomcat 6. +
+
+The ajp12 typed workers forward requests to out-of-process Tomcat workers +using the ajpv12 protocol over TCP/IP sockets. +
+ +
+the ajp12 worker properties are : +
+ +
+host property sets the host where the Tomcat worker is listening for ajp12 requests. +
+ +
+port property sets the port where the Tomcat worker is listening for ajp12 requests +
+ +
+lbfactor property is used when working with a load balancer worker, this is the load-balancing factor for the worker. +We'll see more on this in the lb worker section. +
+ +
+  # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
+  worker.worker1.host=www.x.com
+  worker.worker1.port=8007
+  worker.worker1.lbfactor=2
+
+ +
+Notes: In the ajpv12 protocol, connections are created, used and then closed at each request. +The default port for ajp12 is 8007 +
+ +
+ +
ajp13 Worker properties
+
+The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets. +The main difference between ajpv12 and ajpv13 are that: +
+
+ajpv13 is a more binary protocol and it tries to compress some of the request data by coding +frequently used strings as small integers. +
+
+ajpv13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your +web server and Tomcat). +
+
+ajpv13 has special treatment for SSL information so that the container can implement +SSL related methods such as isSecure(). +
+
+ +
+ +
+You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6. +
+ + +
+  # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
+  worker.worker2.host=www2.x.com
+  worker.worker2.port=8009
+  worker.worker2.lbfactor=3
+  # worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
+  worker.worker2.connection_pool_timeout=600
+  # worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
+  worker.worker2.socket_keepalive=1
+  # mount can be used as an alternative to the JkMount directive
+  worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
+
+ +
+Notes: In the ajpv13 protocol, the default port is 8009 +
+ +
+ +
lb Worker properties
+
+The load-balancing worker does not really communicate with Tomcat workers. +Instead it is responsible for the management of several "real" workers. +This 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 falling-back 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. +The following table specifies some properties that the lb worker can accept: +
+
balance_workers is a comma separated list of workers that the load balancer need to manage. +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. +This directive can be used multiple times for the same load balancer.
+
sticky_session specifies whether requests with SESSION ID's should be routed back to the same +Tomcat worker. Set sticky_session to False when Tomcat is using a Session Manager which +can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.
+
+
+ +
+  # The worker balance1 while use "real" workers worker1 and worker2
+  worker.balance1.balance_workers=worker1, worker2
+
+ +
+ +
Status Worker properties
+
+The status worker does not communicate with Tomcat. +Instead it is responsible for the load balancer management. +
+
+  # Add the status worker to the worker list
+  worker.list=jkstatus
+  # Define a 'jkstatus' worker using status
+  worker.jkstatus.type=status
+
+
Next thing is to mount the requests to the jkstatus worker. For Apache +web servers use the:
+
+  # Add the jkstatus mount point
+  JkMount /jkmanager/* jkstatus 
+
+
To obtain a higher level of security use the:
+
+  # Enable the JK manager access from localhost only
+ <Location /jkmanager/>
+    JkMount jkstatus
+    Order deny,allow
+    Deny from all
+    Allow from 127.0.0.1
+ </Location>
+
+ +
+ +
Property file macros
+
+You can define "macros" in the property files. +These macros let you define properties and later on use them while +constructing other properties. +
+ +
+  # property example, like a network base address
+  mynet=194.226.31
+  # Using the above macro to simplify the address definitions
+  # for a farm of workers.
+  worker.node1.host=$(mynet).11
+  worker.node2.host=$(mynet).12
+  worker.node3.host=$(mynet).13
+
+ +
+ +
Hierarchical property configuration
+
+Workers can reference configurations of other workers. +If worker "x" references worker "y", then it inherits all +configuration parameters from "y", except for the ones +that have explicitly been set for "x". +
+ +
+  # worker toe defines some default settings
+  worker.toe.type=ajp13
+  worker.toe.socket_keepalive=true
+  worker.toe.connect_timeout=10000
+  worker.toe.recovery_options=7
+  # workers tic and tac inherit those values
+  worker.tic.reference=worker.toe
+  worker.tac.reference=worker.toe
+
+ +
+Please note, that the reference contains +the full prefix to the referenced configuration attributes, +not only the name of the referenced worker. +
+ +
+References can be nested. Be careful to avoid loops! +
+ +
+Attributes which are allowed multiple times for a single worker +can not be merged from a worker and a reference. An attribute +is only inherited from a reference, if it is not already set +for the referring worker. +
+ +
+References are especially useful, when configuring load balancers. +Try to understand the following two stage references: +
+ +
+  # We only use one load balancer
+  worker.list=lb
+  # Let's define some defaults
+  worker.basic.port=8009
+  worker.basic.type=ajp13
+  worker.basic.socket_keepalive=true
+  worker.basic.connect_timeout=10000
+  worker.basic.recovery_options=7
+  # And we use them in two groups
+  worker.lb1.domain=dom1
+  worker.lb1.distance=0
+  worker.lb1.reference=worker.basic
+  worker.lb2.domain=dom2
+  worker.lb2.distance=1
+  worker.lb2.reference=worker.basic
+  # Now we configure the load balancer
+  worker.lb.type=lb
+  worker.lb.method=B
+  worker.lb.balanced_workers=w11,w12,w21,w22
+  worker.w11.host=myhost11
+  worker.w11.reference=worker.lb1
+  worker.w12.host=myhost12
+  worker.w12.reference=worker.lb1
+  worker.w21.host=myhost21
+  worker.w21.reference=worker.lb2
+  worker.w22.host=myhost22
+  worker.w22.reference=worker.lb2
+
+ +
+ +

A sample worker.properties

+
+Since coping with worker.properties on your own is not an easy thing to do, +a sample worker.properties file is bundled along JK. +
+ +
+You could also find here a sample workers.properties defining : +
+ +
+
+An ajp12 worker that used the host localhost and the port 8007 +
+
+An ajp13 worker that used the host localhost and the port 8008 +
+
+An lb worker that load balance the ajp12 and ajp13 workers +
+
+ +
+  # Define 3 workers, 2 real workers using ajp12, ajp13, the last one being a loadbalancing worker 
+  worker.list=worker1, worker2, worker3
+  # Set properties for worker1 (ajp12)
+  worker.worker1.type=ajp12
+  worker.worker1.host=localhost
+  worker.worker1.port=8007
+  worker.worker1.lbfactor=1
+  # Set properties for worker2 (ajp13)
+  worker.worker2.type=ajp13
+  worker.worker2.host=localhost
+  worker.worker2.port=8009
+  worker.worker2.lbfactor=1
+  worker.worker2.connection_pool_timeout=600
+  worker.worker2.socket_keepalive=1
+  worker.worker2.socket_timeout=60
+  # Set properties for worker3 (lb) which use worker1 and worker2
+  worker.worker3.balance_workers=worker1,worker2
+
+ +

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