JBoss Enterprise Application Platform 5

Transcription

1 JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide Edition HTTP load-balancing for JBoss Enterprise Application Platform Last Updated:

2

3 JBoss Enterprise Application Platform 5 HTTP Connectors Load Balancing Guide HTTP load-balancing for JBoss Enterprise Application Platform Edition Jared Morgan Joshua Wulf Laura Bailey Samuel Mendenhall James Livingston Jim Tyrell Edited by Eva Kopalova Petr Penicka Russell Dickenson Scott Mumford

4 Legal Notice Copyright 2012 Red Hat, Inc. This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. Node.js is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project. The OpenStack Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community. All other trademarks are the property of their respective owners. Abstract Read this guide to install and configure the supported HTTP connectors for use with JBoss Enterprise Application Platform and JBoss Enterprise Web Server. This guide covers the Apache Tomcat Connector (mod_jk), JBoss HTTP Connector (mod_cluster), Internet Server API (ISAPI) and Netscape Server API (NSAPI), and discusses clustering and load-balancing with regard to each.

5 Table of Contents Table of Contents. PREFACE FILE NAME CONVENTIONS 3. PART I.. APACHE TOMCAT CONNECTOR (MOD_JK) CHAPTER OVERVIEW CHAPTER DOWNLOAD AND INSTALL CHAPTER CONFIGURE LOAD BALANCING USING APACHE HTTP SERVER AND..... MOD_JK CONFIGURE WORKER NODES IN MOD_JK CONFIGURING JBOSS TO WORK WITH MOD_JK 9. CHAPTER TROUBLESHOOTING AND OPTIMIZING MOD_JK COMMON PROBLEMS GENERAL DIAGNOSTICS GETTING FURTHER HELP 18. PART II... JBOSS HTTP CONNECTOR (MOD_CLUSTER) CHAPTER OVERVIEW KEY FEATURES COMPONENTS LIMITATIONS 21. CHAPTER INSTALL PROXY SERVER COMPONENTS APACHE HTTP SERVER MODULES mod_manager.so mod_proxy_cluster.so mod_advertise.so INSTALL PROXY SERVER COMPONENTS 27. CHAPTER CONFIGURE BASIC PROXY SERVER BASIC PROXY CONFIGURATION OVERVIEW CONFIGURE A LOAD-BALANCING PROXY USING THE HTTP CONNECTOR 29. CHAPTER INSTALL NODE WITH..... BASIC CONFIGURATION WORKER NODE REQUIREMENTS INSTALL AND CONFIGURE A WORKER NODE 32. CHAPTER ADVANCED CONFIGURATION STATIC PROXY CONFIGURATION CLUSTERED NODE OPERATION 37. CHAPTER JAVA PROPERTIES CONFIGURATION PROPERTIES Proxy Discovery Configuration Proxy Configuration SSL Configuration HA Configuration Load Configuration 44. CHAPTER LOAD METRICS SERVER-SIDE LOAD METRICS WEB CONTAINER METRICS 46 1

6 HTTP Connectors Load Balancing Guide SYSTEM/JVM METRICS OTHER METRICS CHAPTER LOAD BALANCING DEMONSTRATION SET UP THE DEMONSTRATION CONFIGURE THE DEMO CLIENT INTERACT WITH THE DEMONSTRATION Generate artificial load 55. PART III.... INTERNET SERVER API.... (ISAPI) CHAPTER OVERVIEW WHAT IS INTERNET SERVER API 58. CHAPTER CONFIGURING THE..... ISAPI CONNECTOR ON... WINDOWS PREREQUISITES AND CONFIGURATION ASSUMPTIONS CONFIGURE SERVER INSTANCE AS A WORKER NODE MICROSOFT IIS 6 INITIAL CLUSTERING CONFIGURATION MICROSOFT IIS 7 INITIAL CLUSTERING CONFIGURATION CONFIGURE A BASIC CLUSTER WITH ISAPI CONFIGURE A LOAD-BALANCING CLUSTER WITH ISAPI 67. PART IV.... NETSCAPE SERVER API....(NSAPI) CHAPTER WHAT IS... NETSCAPE SERVER API? CHAPTER CONFIGURING THE.... NSAPI CONNECTOR ON.... SOLARIS PREREQUISITES AND CONFIGURATION ASSUMPTIONS CONFIGURE SERVER INSTANCE AS A WORKER NODE INITIAL CLUSTERING CONFIGURATION CONFIGURE A BASIC CLUSTER WITH NSAPI CONFIGURE A LOAD-BALANCED CLUSTER WITH NSAPI 76. PART V... COMMON LOAD BALANCING TASKS CHAPTER HTTP SESSION STATE REPLICATION ENABLING SESSION REPLICATION IN YOUR APPLICATION HTTPSESSION PASSIVATION AND ACTIVATION Configuring HttpSession passivation CONFIGURE THE JBOSS CACHE INSTANCE USED FOR SESSION STATE REPLICATION 85. CHAPTER HIGH-AVAILABILITY WEB..... SESSIONS DATASOURCEPERSISTENTMANAGER CONFIGURATION ATTRIBUTES 89. CHAPTER USING CLUSTERED SINGLE SIGN-ON (SSO) CONFIGURATION SSO BEHAVIOR LIMITATIONS CONFIGURING THE COOKIE DOMAIN 95. CHAPTER COMPLETE WORKING EXAMPLE APPENDIX A.... REFERENCE: WORKERS.PROPERTIES APPENDIX B.... REFERENCE: JAVA PROPERTIES B.1. PROXY CONFIGURATION 101. APPENDIX C... REVISION HISTORY

7 PREFACE PREFACE 1. FILE NAME CONVENTIONS The following naming conventions are used in file paths for readability. Each convention is styled so that it stands out from the rest of text: JBOSS_EAP_DIST The installation root of the JBoss Enterprise Application Platform instance. This folder contains the main folders that comprise the server such as /jboss-as, /seam, and /resteasy. JBOSS_EWP_DIST The installation root of the JBoss Enterprise Web Platform instance. This folder contains the main folders that comprise the server such as /jboss-as-web, /seam, and /resteasy. JBOSS_EWS_DIST The installation root of the JBoss Enterprise Web Server instance. This folder contains the main folders that comprise the server such as /extras, /httpd, and the /tomcat6 folders. NATIVE The installation root of the JBoss Native zip, extracted to the same directory level as JBOSS_EAP_DIST. SJWS The installation root of the Sun Java Web Server instance. The default file locations for this naming convention are: for Solaris 10 x86 or SPARC 64: /opt/sunwwbsrv70/ HTTPD_DIST The installation root of the Apache HTTP Server. This folder contains the main folders that comprise the server such as /conf, /webapps, and /bin. The JBoss Enterprise Web Server JBOSS_EWS_DIST directory contains the root installation of HTTPD_DIST. PROFILE The name of the server profile you use as part of your testing or production configuration. The server profiles reside in JBOSS_EAP_DIST/jboss-as/server or JBOSS_EWP_DIST/jboss-asweb/server. 3

8 HTTP Connectors Load Balancing Guide PART I. APACHE TOMCAT CONNECTOR (MOD_JK) 4

9 CHAPTER 1. OVERVIEW CHAPTER 1. OVERVIEW Apache HTTP Server ("Apache") is a well-known web server which can be extended using plug-ins. The Apache Tomcat Connector mod_jk is a plug-in designed to allow request forwarding from Apache HTTP Server to a servlet container. The module also supports load-balancing HTTP calls to a set of servlet containers while maintaining sticky sessions. HTTP session replication is used to replicate the state associated with web client sessions to other nodes in a cluster. If one node becomes unavailable, another node in the cluster continues to service the failed node's requests. This involves two distinct operations: Session state replication Load-balancing HTTP Requests Session state replication is handled by JBoss per application, providing the application is configured to make use of this feature (refer to Section 17.1, Enabling session replication in your application ). Load balancing must be handled externally to JBoss, via either hardware or software. A cost-effective way of enabling load balancing is to set up a software load balancer using Apache HTTP Server and the Apache Tomcat Connector (mod_jk). 5

10 HTTP Connectors Load Balancing Guide CHAPTER 2. DOWNLOAD AND INSTALL Apache HTTP Server is included in the JBoss Enterprise Web Server binary you download from Apache mod_jk is included in the native installation binaries for JBoss Enterprise Application Platform and JBoss Enterprise Web Server. Follow the procedures in the JBoss Enterprise Application Platform or JBoss Enterprise Web Server Installation Guide to download and install the correct platform and native binaries. 6

11 CHAPTER 3. CONFIGURE LOAD BALANCING USING APACHE HTTP SERVER AND MOD_JK CHAPTER 3. CONFIGURE LOAD BALANCING USING APACHE HTTP SERVER AND MOD_JK Follow the tasks in this chapter to correctly configure load balancing using Apache HTTP Server and the mod_jk connector. Task: Configure Apache HTTP Server to Load mod_jk Complete this task to configure Apache HTTP Server to load mod_jk. Prerequisites Apache HTTP Server and mod_jk installed (Refer to Chapter 2, Download and install). 1. Open HTTPD_DIST/conf/httpd.conf and add the following text at the end of the file. # Include mod_jk's specific configuration file Include conf/mod-jk.conf 2. Create a new file named HTTPD_DIST/conf/mod-jk.conf 3. Add the following configuration block to mod-jk.conf. # Load mod_jk module # Specify the filename of the mod_jk lib LoadModule jk_module modules/mod_jk.so # Where to find workers.properties JkWorkersFile conf/workers.properties # Where to put jk logs JkLogFile logs/mod_jk.log # Set the jk log level [debug/error/info] JkLogLevel info # Select the log format JkLogStampFormat "[%a %b %d %H:%M:%S %Y]" # JkOptions indicates to send SSK KEY SIZE JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories # JkRequestLogFormat JkRequestLogFormat "%w %V %T" # Mount your applications JkMount /application/* loadbalancer # Add shared memory. # This directive is present with and # later versions of mod_jk, and is needed for # for load balancing to work properly JkShmFile logs/jk.shm 7

12 HTTP Connectors Load Balancing Guide # Add jkstatus for managing runtime data <Location /jkstatus/> JkMount status Order deny,allow Deny from all Allow from </Location> 4. Confirm that the LoadModule directive references the right path for the mod_jk library. If not, edit the path. 5. The default configuration specifies that static content is served directly by Apache HTTP Server and all requests with URL path /application/* are sent to the load balancer. If mod_jk is only to be used as a load balancer, change the directive to /*. 6. Optional: JKMountFile Directive In addition to the JkMount directive, you can use the JkMountFile directive to specify a mount point's configuration file. The configuration file contains multiple Tomcat forwarding URL mappings. a. Navigate to HTTPD_DIST/conf. b. Create a file named uriworkermap.properties. c. Specify the URL whose requests are to be forwarded and the name of the worker node to which they are to be forwarded, using the following syntax example as a guide. The example block will configure mod_jk to forward requests to /jmx-console and /web-console to Apache HTTP Server. The syntax required takes the form /url=worker_name. # Simple worker configuration file # Mount the Servlet context to the ajp13 worker /jmx-console=loadbalancer /jmx-console/*=loadbalancer /web-console=loadbalancer /web-console/*=loadbalancer d. In HTTPD_DIST/conf/mod-jk.conf, append the following directive. # You can use external file for mount points. # It will be checked for updates each 60 seconds. # The format of the file is: /url=worker # /examples/*=loadbalancer JkMountFile conf/uriworkermap.properties 3.1. CONFIGURE WORKER NODES IN MOD_JK 8 Task: Configure mod_jk Worker Nodes Complete this task to configure two mod_jk worker node definitions in a weighted round-robin configuration with sticky sessions active between two servlet containers.

13 CHAPTER 3. CONFIGURE LOAD BALANCING USING APACHE HTTP SERVER AND MOD_JK Prerequisites Understand the format of the workers.properties directives, as specified in Appendix A, Reference: workers.properties. 1. Navigate to HTTPD_DIST/conf/. 2. Create a file named workers.properties. 3. Append the following information to workers.properties. # Define list of workers that will be used # for mapping requests worker.list=loadbalancer,status # Define Node1 # modify the host as your host IP or DNS name. worker.node1.port=8009 worker.node1.host=node1.mydomain.com worker.node1.type=ajp13 worker.node1.ping_mode=a worker.node1.lbfactor=1 # Define Node2 # modify the host as your host IP or DNS name. worker.node2.port=8009 worker.node2.host=node2.mydomain.com worker.node2.type=ajp13 worker.node2.ping_mode=a worker.node2.lbfactor=1 # Load-balancing behavior worker.loadbalancer.type=lb worker.loadbalancer.balance_workers=node1,node2 worker.loadbalancer.sticky_session=1 # Status worker for managing load balancer worker.status.type=status 3.2. CONFIGURING JBOSS TO WORK WITH MOD_JK Task: Configure JBoss Enterprise Application Platform to Operate Using mod_jk Complete this task to correctly prepare a JBoss Enterprise Application Platform instance on a clustered node to receive forwarded requests from the mod_jk load balancer. Repeat this task for each server instance you require, observing the warnings at each step. Prerequisites Complete Task: Configure mod_jk Worker Nodes. 1. Navigate to the location of the clustered server instance. 9

14 HTTP Connectors Load Balancing Guide 2. Open JBOSS_EAP_DIST/jbossas/server/PROFILE/deploy/jbossweb.sar/server.xml. 3. Specify the node name by appending the jvmroute attribute to the <Engine> element in server.xml. The jvmroute attribute value is the node name defined in HTTPD_DIST/conf/workers.properties. <!--Preceeding syntax removed for readability --> <Engine name="jboss.web" defaulthost="localhost" jvmroute="node1"> <!--Proceeding syntax removed for readability --> </Engine> IMPORTANT If you intend to configure more than one server node in a cluster, ensure you change the jvmroute attribute value to a unique name each time you repeat this step. 4. In server.xml, ensure the AJP protocol <connector> element is enabled (uncommented). The element is uncommented by default in new installations. <Connector protocol="ajp/1.3" port="8009" address="${jboss.bind.address}" redirectport="8443" /> 5. You now have a correctly configured Apache HTTP Server with mod_jk load balancer, which balances calls to the servlet containers in the cluster, and ensures clients will always use the same servlet container (sticky sessions). NOTE For supplementary information about using mod_jk with JBoss, refer to the JBoss wiki page at 10

15 CHAPTER 4. TROUBLESHOOTING AND OPTIMIZING MOD_JK CHAPTER 4. TROUBLESHOOTING AND OPTIMIZING MOD_JK While optimizing the configuration in Apache HTTP Server, mod_jk, mod_proxy, mod_cluster and JBoss Enterprise Application Platform typically resolves any and all problems and errors in load balancing, there are exceptions (such as long running servlets that require additional optimization). In most cases, a correctly tuned configuration is the catch all for mod_jk issues. This section discusses some problems and how the configuration can be improved to avoid them. Optimization Considerations Ensure you are on the latest supported component versions. Ensure the relevant configurations are tuned correctly. The Red Hat Global Support Services staff can use interactive tools to assist you with tailored configuration settings. Find the appropriate contact details at If optimizing the configuration does not resolve the issue the problem is most likely on the JBoss/JVM side. Refer to Procedure 4.5, JBoss/JVM Problems for advice about these issues COMMON PROBLEMS The list below outlines some common configuration problems. Ensuring your implementation is not subject to one of these may assist to resolve your issue. Specific errors and general performance issues are discussed later in this section. Common Configuration Issues JkShmFile on a NFS share Placing the JkShmFile on a NFS share can cause unexplained pauses in mod_jk and odd behavior. It is strongly recommended that the JkShmFile always be placed on local storage to avoid problems. A firewall between Apache HTTP Server and JBoss Enterprise Application Platform If there is a firewall between Apache HTTP Server and JBoss Enterprise Application Platform and no socket_keepalive parameter is set, the firewall can close connections unexpectedly. MaxClients higher than maxthreads Setting the MaxClients parameter in Apache HTTP Server higher than the maxthreads setting in JBoss (with a high load on the server) will result in Apache HTTP Server overwhelming the JBoss instance with threads which will cause hung and/or dropped connections. No connectiontimeout parameter set The connectiontimeout parameter set in JBoss is required for proper maintenance of old connections. No CPing/CPong set The CPing/CPong property in mod_jk is the most important worker property setting, allowing mod_jk to test and detect faulty connections. Not setting this parameter can lead to bad connections not being detected as quickly which can lead to web requests behaving as if 'hung'. 11

16 HTTP Connectors Load Balancing Guide Running an old version of mod_jk. There are known issues with sticky sessions in versions prior to mod_jk Running an older version of EAP. There is a bug in EAP 4.2 base and EAP 4.2 CP01 which causes sockets to be left in the CLOSE_WAIT state, thus causing the appearance of hung requests again. This issue has been reported and fixed Unresponsive back end server java.lang.outofmemoryerror errors or high pause times can cause the back end server to become unresponsive. All of the problems listed above are typically resolved after optimizing the configuration in Apache HTTP Server, mod_jk, and JBoss. Common Errors "CPing/CPong" Errors Presents with errors like the following: [info] ajp_handle_cping_cpong::jk_ajp_common.c (865): timeout in reply cpong... [error] ajp_connect_to_endpoint::jk_ajp_common.c (957): (nodea) cping/cpong after connecting to the backend server failed (errno=110) [error] ajp_send_request::jk_ajp_common.c (1507): (nodea) connecting to backend failed. Tomcat is probably not started or is listening on the wrong port (errno=110) These CPing/CPong messages do not indicate a problem with mod_jk at all, they indicate that JBoss did not respond in the defined CPing/CPong time. This is seen many times when there is high load on the JVM JBoss is running on causing high garbage collection or potentially thread contention. It could also be that the JBoss instance is overloaded, or even that a firewall is blocking the connection or there are network issues. The following workflow may assist to correct these type of issues: Procedure 4.1. Resolving "CPing/CPong" Errors 1. Optimize your Apache HTTP Server and JBoss Enterprise Application Platform configuration. You can contact Red Hat's Global Support Services for assistance with this. If this does not resolve the issue, proceed to Step 2 2. Confirm that there is no firewall blocking or dropping the AJP connections. "Tomcat is down" Errors Presents with errors like the following: 12

17 CHAPTER 4. TROUBLESHOOTING AND OPTIMIZING MOD_JK 1. [error] ajp_get_reply::jk_ajp_common.c (2020): (node1) Timeout with waiting reply from tomcat. Tomcat is down, stopped or network problems (errno=110) The above error means that JBoss did not respond in the configured reply_timeout time. The solution can be one (or both) of the following: 1. Increase the reply_timeout. 2. Verify there are no garbage collection issues/long pause times in JBoss that may prevent the request from responding thus causing that error. 2. [Fri May 25 11:53: ][11159: ] [debug] init_ws_service::mod_jk.c (977): Service protocol=http/1.1 method=post ssl=false host=(null) addr= name=localhost port=80 auth=(null) user=(null) laddr= raddr= uri=/foo/bar... [Fri May 25 11:58: ][11159: ] [debug] jk_shutdown_socket::jk_connect.c (681): About to shutdown socket 17 [Fri May 25 11:58: ][11159: ] [debug] jk_shutdown_socket::jk_connect.c (689): Failed sending SHUT_WR for socket 17 [Fri May 25 11:58: ][11159: ] [info] ajp_connection_tcp_get_message::jk_ajp_common.c (1150): (node1) can not receive the response header message from tomcat, network problems or tomcat ( :8009) is down (errno=104) [Fri May 25 11:58: ][11159: ] [error] ajp_get_reply::jk_ajp_common.c (1962): (node1) Tomcat is down or refused connection. No response has been sent to the client (yet) The above error likely means that JBoss Enterprise Application Platform did not respond within the configured core Apache HTTP Server timeout period. Note that with these messages the [11159: ] portion of the message serves as an identifier for the connection/request in question. Therefore tracing back from the point of the error in logs can help clarify the activity around the connection/request that lead to the error. In this case, that helps clarify that the error was experienced five minutes after the response was sent to JBoss, which likely points to a five minute timeout (this is Apache HTTP Server's Timeout directive default if not specified). If the Timeout is interrupting mod_jk requests, then it should be increased from the current value to allow for the maximum acceptable response time. Procedure 4.2. Resolving "Tomcat is down" Errors 1. Optimize your Apache HTTP Server and JBoss Enterprise Application Platform configuration. You can contact Red Hat's Global Support Services for assistance with this. If this does not resolve the issue, proceed to Step 2 2. Confirm that there is no firewall blocking or dropping the AJP connections. 13

18 HTTP Connectors Load Balancing Guide General Performance Issues Presents with errors like the following: ERROR [org.apache.coyote.ajp.ajpmessage] (ajp ) Invalid message received with signature The above exception when using mod_jk in JBoss Web typically indicates a non AJP request sent to the AJP connector. Workflows that may assist in resolving these kinds of issues is below: Procedure 4.3. General Performance Problems 1. Optimize your Apache HTTP Server and JBoss Enterprise Application Platform configuration. You can contact Red Hat's Global Support Services for assistance with this. If this does not resolve the issue, proceed to Step 2 2. Gather garbage collection logs for analysis. If the logs show long garbage collection pause times then you should optimize the Java Virtual Machine to reduce the garbage collection pauses and gather/recheck updated logs. Refer to (Red Hat account required) for more information. If this is not the case, or did not resolve the issue, try Step 3, Step 4 and/or Step 5 until your issue is resolved. 3. Determine how long the longest request should take. Factor in transaction times. You may need to increase the reply_timeout to resolve the problem. If this does not resolve the issue, continue to Step Determine if your current environment can handle the given load. If not, you may need to upgrade or add more machines. If this does not resolve the issue, continue to Step Confirm that there is no firewall blocking or dropping the AJP connections. Procedure Errors 1. Optimize your Apache HTTP Server and JBoss Enterprise Application Platform configuration. You can contact Red Hat's Global Support Services for assistance with this. If this does not resolve the issue, proceed to Step 2 2. Gather garbage collection logs for analysis. If the logs show long garbage collection pause times then you should optimize the Java Virtual Machine to reduce the garbage collection pauses and gather/recheck updated logs. Refer to (Red Hat account required) for more information. If this is not the case, or does not resolve the issue, continue to Step 3 14

19 CHAPTER 4. TROUBLESHOOTING AND OPTIMIZING MOD_JK 3. Determine how long the longest request should take. Factor in transaction times. You may need to increase the reply_timeout to resolve the issue. If this does not resolve the issue, move on to Step Determine if your current environment can handle the given load. If not, you may need to upgrade or add more machines. JBoss/JVM-related Issues May present with errors like: [error] service::jk_lb_worker.c (1473): All tomcat instances failed, no more workers left If Apache HTTP Server and JBoss Enterprise Application Platform are optimized and you still receive "no more workers left" this typically indicates an issue on the JBoss/JVM side. A number of JVM-related problems could lead to mod_jk not being able to get a connection to JBoss in the configured timeouts, thus causing the worker to go into the error state and producing this message. Procedure 4.5. JBoss/JVM Problems 1. Enable garbage collection logging. a. For UNIX based systems, the options should be placed in run.conf, not run.sh. The run.conf in the server configuration directory (e.g. <JBOSS_HOME>/server/<PROFILE>/run.conf) takes precedence over the run.conf in the <JBOSS_HOME>/bin directory (except in JBoss EAP due to a regression fixed in version 5.0.1). b. For Windows, the options need to be added to run.bat, as it does not read run.conf. c. Check boot.log to see the value of the user.dir environment variable (e.g. <JBOSS_HOME>/bin), the default location for garbage collection logging when no path is provided. If you are running multiple instances of JBoss against the same directory like so:./run.sh -c node1 -b Djboss.messaging.ServerPeerID=1./run.sh -c node2 -b Djboss.messaging.ServerPeerID=2 -Djboss.service.binding.set=ports-01 d. Then for the gc.log files to be properly separated you will need to make sure each <PROFILE> has a unique run.conf with the JVM_OPTS specific to that <PROFILE>. For example node1 will contain a <JBOSS_HOME>/server/node1/run.conf with contents: JAVA_OPTS="$JAVA_OPTS -verbose:gc -Xloggc:gc_node1.log - XX:+PrintGCDetails -XX:+PrintGCDateStamps" e. And <JBOSS_HOME>/server/node2/run.conf with contents: 15

20 HTTP Connectors Load Balancing Guide JAVA_OPTS="$JAVA_OPTS -verbose:gc -Xloggc:gc_node2.log - XX:+PrintGCDetails -XX:+PrintGCDateStamps" IMPORTANT gc.log is recreated every time JBoss starts. Be sure to back up gc.log if you are restarting the server. Alternatively you may be able to add a timestamp to the file name depending on the OS and/or shell. For example, with OpenJDK or Oracle/Sun JDK on Linux: -Xloggc:gc.log.`date +%Y%m%d%H%M%S`. f. On Windows, you can use for /f "tokens=2-4 delims=/ " %%a in ('date /t') do (set mydate=%%c-%%a-%%b) for /f "tokens=1-2 delims=/:" %%a in ("%TIME%") do (set mytime=%%a%%b) set "JAVA_OPTS=%JAVA_OPTS% - Xloggc:C:/log/gv.log.%mydate%_%mytime% 2. For the time period when there are slowdowns, hangs, or errors, gather the following data: Garbage collection logs. Follow Procedure 4.5, JBoss/JVM Problems. High CPU data coupled with thread dumps (depending upon platform): The links below can assist in gathering Java thread data. A Red Hat subscription is required. CPU utilization by Java threads on Linux/Solaris: CPU utilization by Java threads on Windows: For cases where the Java application is an application server, gather log files: In JBoss: <JBOSS_HOME>/server/<PROFILE>/log/server.log <JBOSS_HOME>/server/<PROFILE>/log/boot.log In Tomcat: catalina.out 3. Determine if the CPU utilization is caused by the JVM (Java application). Here, you want to validate that a Java process is indeed using an unexpected amount of CPU. The Java thread data gathered in the first step should help identify this. 4. Assuming a Java process is identified as the cause of high CPU, the most common cause is java Garbage collection. Determine if the high CPU is caused by Java garbage collection by 16

21 CHAPTER 4. TROUBLESHOOTING AND OPTIMIZING MOD_JK analyzing the garbage collection for long pause times and/or low throughput overall at the time of the issue. To find the garbage collection logging related to the issue, it is necessary to determine the number of seconds after JVM startup that the issue happens (that is the typical format of garbage collection logging timestamps). To determine the time elapsed, you can use the first timestamp in the high CPU data gathered and the first timestamp in the console log, boot.log (JBoss), server.log (JBoss), or catalina.out (Tomcat.) If you see long pause times and/or low throughput overall, refer to the following Knowledge Base article (Red Hat subscription required) 5. If Garbage collection is not responsible for the high CPU, use the thread dump information gathered when validating CPU information to identify the threads. One area that is not a direct consequence of an unoptimized mod_jk configuration but can still cause issues with mod_jk is JVM and garbage collection related problems. When there are high pause times and the JVM is not optimized for the app server, the pause times can cause mod_jk issues even when mod_jk is tuned GENERAL DIAGNOSTICS 1. Verify the back end server is responsive by making a direct request to it. 2. Monitor high load using one of the following methods: Twiddle 1. Locate the appropriate Twiddle script for your environment ( twiddle.sh, twiddle.bat or twiddle.jar) in the <JBOSS_HOME>/bin/ directory. 2. Run the following command: <TWIDDLE> -u admin -p password get "jboss.web:name=ajp ,type=ThreadPool" Use the script appropriate to your operating system and environment. Twiddle may need to be modified for each specific environment, but the above will work in a default JBoss instance where no ports have been changed and JBoss is starting on the localhost. JMX Console 1. Navigate to 2. Find the jboss.web section. 3. Click on name=ajp-localhost/ ,type=threadpool (or whichever AJP ThreadPool matches your environment) 4. Investigate the currentthreadsbusy attribute. If this attribute is reaching the maxthreads there will be a problem as JBoss Web is reaching the defined ThreadPool capacity. 17

22 HTTP Connectors Load Balancing Guide 4.3. GETTING FURTHER HELP If none of the above information resolves your issue you can contact the Global Support Services staff for assistance. You can find the appropriate contact details at Please gather the following information prior to your call. JBoss EAP boot.log. Apache HTTP Server's httpd.conf and the httpd-mpm.conf file (if it exists). mod_jk's workers.properties. mod_jk's mod_jk.conf. <JBOSS_HOME>/server/<PROFILE>/deploy/JBOSSWEB/server.xml <JBOSS_HOME>/server/<PROFILE>/deploy/JBOSSWEB/META-INF/jbossservice.xml The output of running httpd -V on Apache HTTP Server ( httpd -V > httpd.out, for example). Note the capital "V". A lowercase " v" will not produced the desired output. Version of Apache HTTP Server or the JBoss Enterprise Web Server. /etc/sysconfig/httpd 18

23 PART II. JBOSS HTTP CONNECTOR (MOD_CLUSTER) PART II. JBOSS HTTP CONNECTOR (MOD_CLUSTER) 19

24 HTTP Connectors Load Balancing Guide CHAPTER 5. OVERVIEW The JBoss HTTP Connector mod_cluster is a reduced-configuration, intelligent load-balancing solution for JBoss Enterprise Application Platform, based on technology originally developed by the JBoss mod_cluster community project. The JBoss HTTP connector load-balances HTTP requests to JBoss Enterprise Application Platform and JBoss Enterprise Web Server worker nodes, using Apache HTTP Server as the proxy server KEY FEATURES Apache HTTP Server-based The JBoss HTTP Connector mod-cluster uses Apache HTTP Server as the proxy server. Real-time load-balancing calculation The JBoss HTTP Connector mod_cluster creates a feedback network between the worker nodes and the proxy server. The mod_cluster service is deployed on each of the worker nodes. This service feeds real-time load information to the proxy server. The proxy server then makes intelligent decisions about where to allocate work, based on the current load on each worker node. This real-time adaptive load distribution results in increased optimization of resources. The information that is reported by the worker nodes and the load-balancing policy used by the proxy are both customizable. Routing based on real-time application life-cycle The JBoss HTTP Connector mod_cluster service deployed on the worker nodes relays application life-cycle events to the proxy server. This allows the server to dynamically update its routing table. When an application is undeployed on a node, the proxy server no longer routes traffic for that application to that node. Automatic Proxy Discovery The proxy server can be configured to announce its presence via UDP multicast. New worker nodes discover the proxy server and add themselves to the load-balancing cluster automatically. This greatly reduces the configuration and maintenance needed. When UDP multicast is not available or is undesirable, worker nodes are configured with a static list of proxies. Multiple Protocol Support The JBoss HTTP Connector mod_cluster can use HTTP, HTTPS, or Apache JServ Protocol (AJP) for communication between the proxy and the worker nodes COMPONENTS Proxy Server On the proxy server, the JBoss HTTP Connector, mod-cluster, consists of four Apache HTTP Server modules. Shared Memory Manager module: mod_slotmem.so The Shared Memory Manager module, mod_slotmem, makes the real-time worker node information available to multiple Apache HTTP Server server processes. 20

25 CHAPTER 5. OVERVIEW Cluster Manager module: mod_manager.so The Cluster Manager module, mod_manager, receives and acknowledges messages from nodes, including worker node registrations, worker node load data, and worker node application life-cycle events. Proxy Balancer module: mod_proxy_cluster.so The Proxy Balancer module, mod_proxy_cluster, handles the routing of requests to cluster nodes. The Proxy Balancer selects the appropriate node to forward the request to, based on application location in the cluster, current state of each of the cluster nodes, and the Session ID (if a request is part of an established session). Proxy Advertisement module: mod_advertise.so The Proxy Advertisement module, mod_advertise.so, broadcasts the existence of the proxy server via UDP multicast messages. The server advertisement messages contain the IP address and port number on which the proxy is listening for responses from nodes that wish to join the loadbalancing cluster. NOTE Refer to Section 6.1, Apache HTTP Server modules for detailed information about the available modules including user-configurable parameters. Worker Node Components The JBoss HTTP Connector client service, mod-cluster.sar, is deployed on each worker node. Worker node service: mod-cluster.sar This service provides the proxy with real-time information on the worker node's state and sends notification of application life-cycle events; as well as allowing the node to discover and register itself with any proxies running on the same network LIMITATIONS The JBoss HTTP Connector mod_cluster uses shared memory to keep the nodes description, the shared memory is created at the startup of httpd and the structure of each item is fixed. Therefore, when defining proxy server and worker node properties, make sure to follow these character limits: Maximum Alias length: 100 characters (Alias corresponds to the network name of the respective virtual host; the name is defined in the Host element) Maximum context length: 40 characters (for example, if myapp.war is deployed in /myapp, then /myapp is the context) Maximum balancer name length: 40 characters (the balancer property in MBean) Maximum JVMRoute string length: 80 character (JVMRoute in the <Engine> element) Maximum domain name length: 20 characters (the domain property in MBean) Maximum hostname length for a node: 64 characters (hostname address in the <Connector> element) 21

26 HTTP Connectors Load Balancing Guide Maximum port length for a node: 7 characters (8009 is 4 characters, the port property in the <Connector> element) Maximum scheme length for a node: 6 characters (possible values are http, https, ajp, the protocol of the connector) Maximum cookie name length: 30 characters (the header cookie name for session ID default value: JSESSIONID from org.apache.catalina.globals.session_cookie_name) Maximum path name length: 30 characters (the parameter name for the session ID default value: JSESSIONID from org.apache.catalina.globals.session_parameter_name) Maximum length of a session ID: 120 characters (session ID resembles the following: BE81FAA969BF64C8EC2B EAAAA.node01) 22

27 CHAPTER 6. INSTALL PROXY SERVER COMPONENTS CHAPTER 6. INSTALL PROXY SERVER COMPONENTS Read this chapter to install the JBoss HTTP Connector, mod_cluster, on a proxy server APACHE HTTP SERVER MODULES Read this section for expanded definitions of the Apache HTTP Server proxy server modules discussed in Section 5.2, Components. You specify these modules as part of Task: Install Proxy Server Components mod_manager.so The Cluster Manager module, mod_manager, receives and acknowledges messages from nodes, including worker node registrations, worker node load data, and worker node application life-cycle events. LoadModule manager_module modules/mod_manager.so You can also define the following related directives in the <VirtualHost> element: MemManagerFile Defines the location for the files in which mod_manager stores configuration details. mod_manager also uses this location to store generated keys for shared memory and lock files. This must be an absolute path name. It is recommended that this path be set explicitly and on a local drive, not an NFS share. The default value is platform/httpd specific. Valid paths are: HP-UX: HTTPD_HOME/cache/mod_cluster Red Hat Enterprise Linux: /var/cache/mod_cluster Maxcontext The maximum number of contexts JBoss mod_cluster will use. The default value is 100. Maxnode The maximum number of worker nodes JBoss mod_cluster will use. The default value is 20. Maxhost The maximum number of hosts (aliases) JBoss mod_cluster will use. This is also the maximum number of load balancers. The default value is 10. Maxsessionid The maximum number of active session identifiers stored. A session is considered inactive when no information is received from that session within five minutes. The default value is 0, which disables this logic. ManagerBalancerName 23

28 HTTP Connectors Load Balancing Guide The name of the load balancer to use when the worker node does not provide a load balancer name. The default value is mycluster. PersistSlots When set to on, nodes, aliases and contexts are persisted in files. The default value is off. CheckNonce When set to on, session identifiers are checked to ensure that they are unique, and have not occurred before. The default is on. WARNING Setting this directive to off can leave your server vulnerable to replay attacks. SetHandler Defines a handler to display information about worker nodes in the cluster. This is defined in the Location element: <Location $LOCATION> SetHandler mod_cluster-manager Order deny,allow Deny from all Allow from </Location> When accessing the $LOCATION defined in the Location element in your browser, you will see something like the following. (In this case, $LOCATION was also defined as mod_clusterhandler.) 24

29 CHAPTER 6. INSTALL PROXY SERVER COMPONENTS Figure 6.1. mod_cluster Status Transferred corresponds to the POST data sent to the worker node. Connected corresponds to the number of requests that had been processed when this status page was requested. Sessions corresponds to the number of active sessions. This field is not present when Maxsessionid is mod_proxy_cluster.so The Proxy Balancer module, mod_proxy_cluster, handles the routing of requests to cluster nodes. The Proxy Balancer selects the appropriate node to forward the request to, based on application location in the cluster, current state of each of the cluster nodes, and the Session ID (if a request is part of an established session). LoadModule proxy_cluster_module modules/mod_proxy_cluster.so You can also define the following related directives in the <VirtualHost> element to change loadbalancing behavior. mod_proxy_cluster directives CreateBalancers Defines how load balancers are created in the Apache HTTP Server virtual hosts. The following values are valid in CreateBalancers : 0 Create load balancers in all virtual hosts defined in Apache HTTP Server. Remember to configure the load balancers in the ProxyPass directive. 1 Do not create balancers. When using this value, you must also define the load balancer name in the ProxyPass or ProxyPassMatch. 2 Create only the main server. This is the default value for CreateBalancers. 25

30 HTTP Connectors Load Balancing Guide UseAlias Defines whether to check that the defined Alias corresponds to the following values are valid for UseAlias : ServerName. The 0 Ignore Alias information from worker nodes. This is the default value for UseAlias. 1 Verify that the defined alias corresponds to a worker node's server name. LBstatusRecalTime Defines the interval in seconds between the proxy calculating the status of a worker node. The default interval is 5 seconds. ProxyPassMatch; ProxyPass ProxyPass maps remote servers into the local server namespace. If the local server has an address then the following ProxyPass directive would convert a local request for into a proxy request for ProxyPass /requested/ ProxyPassMatch uses Regular Expressions to match local paths to which the proxied URL should apply. For either directive,! indicates that a specified path is local, and a request for that path should not be routed to a remote server. For example, the following directive specifies that.gif files should be served locally. ProxyPassMatch ^(/.*\.gif)$! mod_advertise.so The Proxy Advertisement module, mod_advertise.so, broadcasts the existence of the proxy server via UDP multicast messages. The server advertisement messages contain the IP address and port number where the proxy is listening for responses from nodes that wish to join the load-balancing cluster. This module must be defined alongside mod_manager in the VirtualHost element. Its identifier in the following code snippet is advertise_module. LoadModule advertise_module modules/mod_advertise.so mod_advertise also takes the following directives: ServerAdvertise Enables or disables the advertising mechanism. When set to On, the advertising mechanism is used to tell worker nodes to send status information to this proxy. When set to Off, the advertising mechanism is disabled. 26

31 CHAPTER 6. INSTALL PROXY SERVER COMPONENTS You can also specify a hostname and port with the following syntax: ServerAdvertise On This is only required when using a name-based virtual host, or when a virtual host is not defined. The default value is Off but it is automatically enabled if any Advertise directive is specified in defining a VirtualHost. AdvertiseGroup Defines the multicast address to advertise on. The syntax is AdvertiseGroup address:port, where address should correspond to AdvertiseGroupAddress, and port should correspond to AdvertisePort in your worker nodes. If your worker node is JBoss Enterprise Application Platform-based, and the -u switch is used at startup, the default AdvertiseGroupAddress is the value passed via the -u switch. The default value is : If port is not specified, the default port used is AdvertiseFrequency The interval (in seconds) between multicast messages advertising the IP address and port. The default value is 10. AdvertiseSecurityKey Defines a string used to identify the JBoss HTTP Connector mod_cluster in JBoss Web. By default this directive is not set and no information is sent. AdvertiseManagerUrl Defines the URL that the worker node should use to send information to the proxy server. By default this directive is not set and no information is sent. AdvertiseBindAddress Defines the address and port over which to send multicast messages. The syntax is AdvertiseBindAddress address:port. This allows an address to be specified on machines with multiple IP addresses. The default value is : INSTALL PROXY SERVER COMPONENTS Task: Install Proxy Server Components Follow this task to install the JBoss HTTP Connector. The native components are specific to particular operating system and processor architectures. Refer to the JBoss Enterprise Application Platform Installation Guide to download the correct native components package for your server operating system and processor architecture. Prerequisites An installed Web Server distribution, such as JBoss Enterprise Web Server or HPWS installed (designated by HTTPD_HOME in this documentation). JBoss Enterprise Application Platform 5 Native components downloaded. 27

32 HTTP Connectors Load Balancing Guide 1. Extract Apache HTTP Server modules from Native Components download Extract the four modules mod_advertise.so, mod_manager.so, mod_proxy_cluster.so, mod_slotmem.so from the appropriate Native Components package directory for your processor architecture: either native/lib/httpd/modules or native/lib64/httpd/modules. 2. Copy Apache HTTP Server modules to HTTPD_HOME Copy the JBoss HTTP Connector modules to the HTTPD_HOME/httpd/modules directory of the JBoss Enterprise Web Server. 3. Disable the mod_proxy_balancer module Edit the HTTPD configuration file HTTPD_HOME/httpd/conf/httpd.conf and mark the following line as a comment by adding a # character at the start: LoadModule proxy_balancer_module modules/mod_proxy_balancer.so This module is incompatible with the JBoss HTTP Connector. 4. Configure the server to load the JBoss HTTP Connector modules a. Create HTTPD_HOME/httpd/conf/JBoss_HTTP.conf. b. Add the following lines to HTTPD_HOME/httpd/conf/JBoss_HTTP.conf: LoadModule slotmem_module HTTPD_HOME/modules/mod_slotmem.so LoadModule manager_module HTTPD_HOME/modules/mod_manager.so LoadModule proxy_cluster_module HTTPD_HOME/modules/mod_proxy_cluster.so LoadModule advertise_module HTTPD_HOME/modules/mod_advertise.so 5. Restart the HTTPD service Refer to HTTPD-specific documentation for detailed instructions. 28

33 CHAPTER 7. CONFIGURE BASIC PROXY SERVER CHAPTER 7. CONFIGURE BASIC PROXY SERVER Follow the instructions in this chapter to configure an HTTPD to use the JBoss HTTP Connector (mod_cluster) BASIC PROXY CONFIGURATION OVERVIEW Configuration of the proxy server consists of one mandatory and one optional portion: 1. Configure a proxy server listener to receive worker node connection requests and worker node feedback. 2. Optional: Disable server advertisement. Server Advertisement The proxy server can advertise itself using UDP multicast. When UDP multicast is available on the network between the proxy server and the worker nodes server advertisement allows you to add worker nodes with no further configuration required on the proxy server, and minimal configuration on the worker nodes. If UDP multicast is not available or undesirable, configure the worker nodes with a static list of proxy servers, as detailed in Section 9.1, Static proxy configuration. There is no need in either case to configure the proxy server with a list of worker nodes CONFIGURE A LOAD-BALANCING PROXY USING THE HTTP CONNECTOR Read this section to configure a load balancing proxy that uses the JBoss HTTP Connector. Task: Configure a Proxy Server Listener Follow this task to configure the Apache HTTP Server service to act as a load-balancing proxy using the JBoss HTTP Connector. Prerequisites An installed Web Server distribution, such as JBoss Enterprise Web Server or HPWS installed (designated by HTTPD_HOME in this documentation). JBoss HTTP Connector modules. Refer to Chapter 6, Install proxy server components for details. 1. Create a listen directive for the proxy server Edit the configuration file HTTPD_HOME/httpd/conf/JBoss_HTTP.conf and add the following: Listen IP_ADDRESS:PORT_NUMBER Where IP_ADDRESS is the IP address of a server network interface to communicate with the worker nodes, and PORT_NUMBER is the port on that interface to listen on. 29

34 HTTP Connectors Load Balancing Guide NOTE The port PORT_NUMBER must be open on the server firewall for incoming TCP connections. Example 7.1. Example Listen Directive Listen : Create Virtual Host Add the following <VirtualHost> block to HTTPD_HOME/httpd/conf/JBoss_HTTP.conf: <VirtualHost IP_ADDRESS:PORT_NUMBER> <Location /> Order deny,allow Deny from all Allow from PARTIAL_IP_ADDRESS </Location> KeepAliveTimeout 60 MaxKeepAliveRequests 0 ManagerBalancerName mycluster AdvertiseFrequency 5 </VirtualHost> IP_ADDRESS and PORT_NUMBER match the values from the Listen directive. PARTIAL_IP_ADDRESS is the first 1 to 3 bytes of an IP address, to restrict access to a specific subnet , for example. 3. Configure SELinux to allow proxy traffic Enter the following commands as a root-equivalent user to modify the SELinux configuration to allow the proxy traffic: #semanage port -a -t http_port_t -p tcp 8079 #add port to the Apache port list to enable the next command to work #setsebool -P httpd_can_network_relay 1 #for mod_proxy to work 4. Optional: Disable Server Advertisement The presence of the AdvertiseFrequency directive, which is set to five seconds here, causes the server to periodically send server advertisement messages via UDP multicast. These server advertisement messages contain the IP_ADDRESS and PORT_NUMBER specified in the VirtualHost definition. Worker nodes that are configured to respond to server advertisements use this information to register themselves with the proxy server. To disable server advertisement, add the following directive to the VirtualHost definition: ServerAdvertise Off 30

35 CHAPTER 7. CONFIGURE BASIC PROXY SERVER If server advertisements are disabled, or UDP multicast is not available on the network between the proxy server and the worker nodes, you must configure worker nodes with a static list of proxy servers. Refer to Section 9.1, Static proxy configuration for directions. 5. Restart the JBoss Enterprise Web Server Apache service Refer to HTTPD-specific documentation for detailed instructions. 31

36 HTTP Connectors Load Balancing Guide CHAPTER 8. INSTALL NODE WITH BASIC CONFIGURATION Read this chapter to install the JBoss HTTP Connector on a worker node, and implement basic configuration for the node to begin immediate operation WORKER NODE REQUIREMENTS Supported Worker Node types JBoss Enterprise Platform 5 JBoss Web component JBoss Enterprise Web Server Tomcat service NOTE JBoss Enterprise Platform worker nodes support all JBoss HTTP Connector functionality. JBoss Enterprise Web Server Tomcat worker nodes support a subset of JBoss HTTP Connector functionality. JBoss HTTP Connector Enterprise Web Server Node Limitations Non-clustered mode only. Only one load metric can be used at a time when calculating the load balance factor INSTALL AND CONFIGURE A WORKER NODE This section contains a number of tasks. Follow the appropriate task to install and configure a worker node on JBoss Enterprise Application Platform, or JBoss Enterprise Web Server. NOTE Make sure your configuration definition meets the following character limits: Maximum JVMRoute string length: 80 character (JVMRoute in the <Engine> element) Maximum hostname length for a node: 64 characters (hostname address in the <Connector> element) Maximum port length for a node: 7 characters (8009 is 4 characters, the port property in the <Connector> element) Maximum scheme length for a node: 6 characters (possible values are http, https, ajp, the protocol of the connector) Task: Install and Configure a JBoss Enterprise Application Platform Worker Node Follow this procedure to install JBoss HTTP Connector on a JBoss Enterprise Application Platform instance and configure it for non-clustered operation. Prerequisites 32

37 CHAPTER 8. INSTALL NODE WITH BASIC CONFIGURATION Install a supported JBoss Enterprise Application Platform. Understand the Proxy Configuration parameters discussed in Appendix B, Reference: Java properties 1. Deploy the worker node service Copy mod-cluster.sar from the JBOSS_EAP_DIST/mod_cluster directory to jbossas/server/profile/deploy. 2. Add a Listener to JBoss Web Add the following Listener element beneath the other Listeners in JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy/jbossweb.sar/server.xml: <Listener classname="org.jboss.web.tomcat.service.deployers.microcontainerinte grationlifecyclelistener" delegatebeanname="modclusterservice"/> 3. Configure the service dependency Add the following depends element beneath the other depends elements in JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy/jbossweb.sar/META- INF/jboss-beans.xml: <depends>modclusterservice</depends> 4. Give the worker a unique identity Edit JBOSS_EAP_DIST/jbossas/server/PROFILE/deploy/jbossweb.sar/server.xml and add a attribute and value to the Engine element, as shown: jvmroute <Engine name="jboss.web" defaulthost="localhost" jvmroute="worker01"> Use a unique jvmroute value for each node. 5. Optional: Configure firewall to receive multicast Proxy Server advertisements A proxy server using the JBoss HTTP Connector can advertise itself via UDP multicast. To enable the worker node to dynamically discover proxy servers, open port for UDP connections on the worker node's firewall. Use the following command on Red Hat Enterprise Linux to achieve this: /sbin/iptables -A INPUT -m state --state NEW -m udp -p udp --dport j ACCEPT -m comment --comment "receive mod_cluster proxy server advertisements" /sbin/iptables save If you are not using Automatic Proxy Discovery (see Automatic Proxy Discovery), configure worker nodes with a static list of proxies. Refer to Section 9.1, Static proxy configuration for directions. In this case you can safely ignore the following warning message: [warning] mod_advertise: ServerAdvertise Address or Port not defined, Advertise disabled!!! 33

38 HTTP Connectors Load Balancing Guide IMPORTANT If your nodes are on different machines that run Red Hat Enterprise Linux, they may not acknowledge each other automatically. JBoss Clustering relies on the UDP (User Datagram Protocol) multicasting provided by jgroups. Red Hat Enterprise Linux blocks these packets by default. To allow the packets, modify the iptables rules (as root). The following commands apply to an IP address that matches x: /sbin/iptables -I RH-Firewall-1-INPUT 5 -p udp -d /24 -j ACCEPT /sbin/iptables -I RH-Firewall-1-INPUT 5 -p udp -d /4 -j ACCEPT /sbin/iptables -I RH-Firewall-1-INPUT 9 -p udp -s /24 -j ACCEPT /sbin/iptables -I RH-Firewall-1-INPUT 10 -p tcp -s /24 -j ACCEPT /etc/init.d/iptables save Task: Install and Configure a JBoss Enterprise Web Server Worker Node Follow this procedure to install the JBoss HTTP Connector on a JBoss Enterprise Web Server node and configure it for non-clustered operation. Prerequisites Install a supported JBoss Enterprise Web Server. Understand the Proxy Configuration parameters discussed in Appendix B, Reference: Java properties 1. Deploy worker node service Copy all of the library files in the JBOSS_EAP_DIST/mod_cluster/JBossWeb-Tomcat/lib directory. Move these files to JBOSS_EWS_DIST/tomcat6/lib/ 2. Add a Listener to Tomcat Add the following Listener element beneath the other Listener elements in JBOSS_EWS_DIST/tomcat6/conf/server.xml. <Listener classname="org.jboss.modcluster.modclusterlistener" advertise="true" stickysession="true" stickysessionforce="false" stickysessionremove="true"/> 3. Give this worker a unique identity Edit JBOSS_EWS_DIST/tomcat6/conf/server.xml and add a value to the <Engine> element, as shown: jvmroute attribute and <Engine name="catalina" defaulthost="localhost" jvmroute="worker01"> 4. Optional: Configure firewall to receive Proxy Server advertisements A proxy server using the JBoss HTTP Connector can advertise itself via UDP multicast. To receive these multicast messages, open port for UDP connections on the worker node's 34

39 CHAPTER 8. INSTALL NODE WITH BASIC CONFIGURATION firewall. For Linux users: /sbin/iptables -A INPUT -m state --state NEW -m udp -p udp --dport j ACCEPT -m comment -comment "receive mod_cluster proxy server advertisements" If you are not using Automatic Proxy Discovery (see Automatic Proxy Discovery), configure worker nodes with a static list of proxies. Refer to Section 9.1, Static proxy configuration for directions. In this case you can safely ignore the following warning message: [warning] mod_advertise: ServerAdvertise Address or Port not defined, Advertise disabled!!! 35

40 HTTP Connectors Load Balancing Guide CHAPTER 9. ADVANCED CONFIGURATION Read this chapter to configure advanced features of the JBoss HTTP Connector STATIC PROXY CONFIGURATION Server advertisement allows worker nodes to dynamically discover and register themselves with proxy servers. If UDP broadcast is not available or server advertisement is disabled then worker nodes must be configured with a static list of proxy server addresses and ports. NOTE Make sure your configuration definition meets the following character limits: Maximum Alias length: 100 character (for example, if myapp.war is deployed in /myapp, then/myapp is the context) Maximum balancer name length: 40 (thebalancer property in MBean) Maximum domain name length: 20 (thedomain property in MBean) Task: Configure Application Platform Worker Node with Static Proxy List Follow this task to configure a JBoss Enterprise Application Platform worker node to operate with a static list of proxy servers. Prerequisites JBoss Enterprise Application Platform worker node configured. Refer to Chapter 8, Install node with basic configuration for directions. 1. Disable dynamic proxy discovery Edit the file JBOSS_EAP_DIST/jboss-as/server/PROFILE/mod-cluster.sar/META- INF/mod-cluster-jboss-beans.xml and set the advertise property to false: <property name="advertise">false</property> 2. Choose, and implement, one of the following static proxy options: Option 1: Create a static proxy server list Edit JBOSS_EAP_DIST/jboss-as/server/PROFILE/mod-cluster.sar/META- INF/mod-cluster-jboss-beans.xml and add a comma separated list of proxies in the form of IP_ADDRESS:PORT in the proxylist property. Example 9.1. Example Static Proxy List <property name="proxylist"> :6666, :6666</property> Option 2: Start the worker node with a static proxy list as a parameter a. Edit JBOSS_EAP_DIST/server/PROFILE/mod-cluster.sar/META-INF/mod- 36

41 CHAPTER 9. ADVANCED CONFIGURATION cluster-jboss-beans.xml b. Add the following line: <property name="domain">${jboss.modcluster.domain:}</property> c. Add a comma-separated list of proxies in the form of IP_ADDRESS:PORT as the jboss.modcluster.proxylist parameter when starting the node. Example 9.2. Example Static Proxy List Parameter -Djboss.modcluster.domain= :6666, :6666 Task: Configure Web Server Worker Node with Static Proxy List Follow this procedure to configure a JBoss Enterprise Web Server worker node to operate with a static list of proxy servers. Prerequisites JBoss Enterprise Web Server worker node configured. Refer to Chapter 8, Install node with basic configuration for directions. Understand the Proxy Configuration parameters discussed in Appendix B, Reference: Java properties 1. Disable dynamic proxy discovery Edit JBOSS_EWS_DIST/tomcat6/conf/server.xml. and set the advertise property of the ModClusterListener to false: 2. Define a mod_cluster listener Add a <Listener> element to server.xml. <Listener classname="org.jboss.modcluster.modclusterlistener" advertise="false" stickysession="true" stickysessionforce="false" stickysessionremove="true"/> 3. Create a static proxy server list Add a comma separated list of proxies in the form of IP_ADDRESS:PORT as the proxylist property of the ModClusterListener <Listener> element. Example 9.3. Example Static Proxy List <Listener classname="org.jboss.modcluster.modclusterlistener" advertise="false" stickysession="true" stickysessionforce="false" stickysessionremove="true" proxylist=" :6666, :6666"/> 9.2. CLUSTERED NODE OPERATION The JBoss HTTP Connector can operate in either clustered or non-clustered mode. 37

42 HTTP Connectors Load Balancing Guide NOTE Only JBoss Enterprise Application Platform nodes support clustered operation with the JBoss HTTP Connector. JBoss Enterprise Web Server nodes support non-clustered operation only. JBoss HTTP Connector non-clustered operation In non-clustered mode each worker node communicates directly with the proxy. JBoss HTTP Connector clustered operation In clustered mode multiple worker nodes form a JBoss HA (High Availability) cluster domain. A single worker node communicates with the proxy on behalf of the other nodes in the cluster domain. 38

43 CHAPTER 10. JAVA PROPERTIES CHAPTER 10. JAVA PROPERTIES CONFIGURATION PROPERTIES The tables below enumerate the configuration properties available to an application server node. The location for these properties depends on how mod_cluster is configured Proxy Discovery Configuration The list of proxies from which an application expects to receive AJP connections is either defined statically, via the addresses defined in the proxylist configuration property; or discovered dynamically via the advertise mechanism. Using a special mod_advertise module, proxies can advertise their existence by periodically broadcasting a multicast message containing its address/port. This functionality is enabled via the advertise configuration property. If configured to listen, a server can learn of the proxy's existence, then notify that proxy of its own existence, and update its configuration accordingly. This frees both the proxy and the server from having to define static, environment-specific configuration values. Table Proxy Discovery Attribute Default Description proxylist None Defines a comma-separated list of httpd proxies with which this node will initially communicate. Value should be of the form: address1:port1,address2 :port2 Using the default configuration, this property can by manipulated via the jboss.modcluster.proxyl ist system property. excludedcontexts ROOT,adminconsole,invoker,jbossws,jmxconsole,juddi,web-console List of contexts to exclude from httpd registration, of the form: host1:context1,host2:co ntext2,host3:context3 If no host is indicated, it is assumed to be the default host of the server (e.g. localhost). "ROOT" indicates the root context. Using the default configuration, this property can by manipulated via the jboss.modcluster.exclud edcontexts system property. 39

44 HTTP Connectors Load Balancing Guide Attribute Default Description autoenablecontexts True If false, the contexts are registered disabled in httpd, they need to be enabled via the enable() MBean method or via mod_cluster_manager. stopcontexttimeout 10 The number of seconds to wait for clean shutdown of a context,. This could be the completion of all pending requests for a distributable context or the destruction/expiration of active sessions for a non-distributable context. proxyurl None If defined, this value will be prepended to the URL of MCMP commands. sockettimeout Number of milliseconds to wait for a response from an httpd proxy to MCMP commands before timing out and flagging the proxy as in error. advertise This is true if proxylist is undefined, false otherwise. If enabled, httpd proxies will be auto-discovered via multicast announcements. This can be used either in concert or in place of a static proxylist. advertisegroupaddress The UDP address on which to listen for httpd proxy multicast advertisements. advertiseport The UDP port on which to listen for httpd proxy multicast advertisements. advertisesecuritykey None If specified, httpd proxy advertisements checksums will be verified using this value as a salt Proxy Configuration The following configuration values are sent to proxies during server startup, when a proxy is detected via the advertise mechanism, or during the resetting of a proxy's configuration during error recovery. Table Proxy Configuration 40

45 CHAPTER 10. JAVA PROPERTIES Attribute Default Description stickysession true Indicates whether subsequent requests for a given session should, if possible, be routed to the same node. stickysessionremove false Indicates whether the httpd proxy should remove session stickiness in the event that the balancer is unable to route a request to the node to which it is stuck. This property is ignored if stickysession is false. stickysessionforce true Indicates whether the httpd proxy should return an error in the event that the balancer is unable to route a request to the node to which it is stuck. This property is ignored if stickysession is false. workertimeout -1 Number of seconds to wait for a worker to become available to handle a request. When all the workers of a balancer are unusable, mod_cluster will retry after a specified period (workertimeout/100) to find a usable worker. A value of -1 indicates that the httpd will not wait for a worker to be available and will return an error if none is available. maxattempts 1 Number of times an httpd proxy will attempt to send a given request to a worker before giving up. The minimum value is 1, meaning try only once. Note that mod_proxy default is also 1: no retry. flushpackets false Enables/disables packet flushing. flushwait -1 Time to wait before flushing packets. A value of -1 means wait forever. ping 10 seconds Time to wait for an answer to a ping. 41

46 HTTP Connectors Load Balancing Guide Attribute Default Description smax Determined by httpd configuration. Soft maximum idle connection count (that is the smax in worker mod_proxy documentation). The maximum value depends on the httpd thread configuration (ThreadsPerChild or 1). ttl 60 seconds Time to live (in seconds) for idle connections above smax. nodetimeout -1 (none) Timeout (in seconds) for proxy connections to a node. That is the time mod_cluster will wait for the back-end response before returning an error. This corresponds to timeout in the worker mod_proxy documentation. Note that mod_cluster always uses a CPing/CPong before forwarding a request and the connectiontimeout value used by mod_cluster is the ping value. balancer mycluster The balancer name. domain None If specified, load will be balanced among jvmroutes with the same domain. This is primarily used in conjunction with partitioned session replication (e.g. buddy replication). Note: When nodetimeout is not defined the ProxyTimeout directive Proxy is used. If ProxyTimeout is not defined the server timeout (Timeout) is used (default 300 seconds). nodetimeout, ProxyTimeout or Timeout is set at the socket level SSL Configuration The communication channel between application servers and httpd proxies uses HTTP by default. This channel can be secured using HTTPS by setting the ssl parameter to true. Note: This HTTP/HTTPS channel should not be confused with the processing of HTTP/HTTPS client requests. Table SSL Configuration 42

47 CHAPTER 10. JAVA PROPERTIES Attribute Default Description ssl false Should connection to proxy use a secure socket layer. sslciphers The default JSSE cipher suites Overrides the cipher suites used to init an SSL socket ignoring any unsupported ciphers. sslprotocol TLS Overrides the default SSL socket protocol. sslcertificateencodinga lgorithm The default JSSE key manager algorithm. The algorithm of the key manager factory. sslkeystore System.getProperty("use r.home") + "/.keystore" The location of the key store containing client certificates. sslkeystorepass changeit The password granting access to the key store. sslkeystoretype JKS The type of key store. sslkeystoreprovider The default JSSE security provider. The key store provider. ssltrustalgorithm The default JSSE trust manager algorithm. The algorithm of the trust manager factory. sslkeyalias The alias of the key holding the client certificates in the key store. sslcrlfile Certificate revocation list. ssltrustmaxcertlength 5 The maximum length of a certificate held in the trust store. ssltruststore System.getProperty("jav ax.net.ssl.truststorepa ssword") The location of the file containing the trust store. ssltruststorepassword System.getProperty("jav ax.net.ssl.truststore") The password granting access to the trust store. ssltruststoretype System.getProperty("jav ax.net.ssl.truststorety pe") The trust store type. ssltruststoreprovider System.getProperty("jav ax.net.ssl.truststorepr ovider") The trust store provider. 43

48 HTTP Connectors Load Balancing Guide HA Configuration Additional configuration properties when mod_cluster is configured in clustered mode. Table HA Configuration Attribute Default Description masterperdomain false If the domain directive is used, should HA partition use a singleton master per domain Load Configuration Additional configuration properties used when mod_cluster is configured in JBoss Web standalone or Tomcat. Table Load Configuration Attribute Default Description loadmetricclass org.jboss.modcluster.lo ad.metric.impl.busyconn ectorsloadmetric Class name of an object implementing org.jboss.load.metric.l oadmetric. loadmetriccapacity 1 The capacity of the load metric defined via the loadmetricclass property. loadhistory 9 The number of historic load values to consider in the load balance factor computation. loaddecayfactor 2 The factor by which a historic load values should degrade in significance. 44

49 CHAPTER 11. LOAD METRICS CHAPTER 11. LOAD METRICS SERVER-SIDE LOAD METRICS A major feature of mod_cluster is the ability to use server-side load metrics to determine how best to balance requests. The DynamicLoadBalanceFactorProvider bean computes the load balance factor of a node from a defined set of load metrics. <bean name="dynamicloadbalancefactorprovider" class="org.jboss.modcluster. load.impl.dynamicloadbalancefactorprovider" mode="on Demand"> <annotation>@org.jboss.aop.microcontainer.aspects.jmx.jmx(name="jboss.we b:service=loadbalancefactorprovider",exposedinterface=org.jboss.modcluster.load.impl.dynamicloadbalancefactorprovidermbean.class)</annotation> <constructor> <parameter> <set elementclass="org.jboss.modcluster.load.metric.loadmetric"> <inject bean="busyconnectorsloadmetric"/> <inject bean="heapmemoryusageloadmetric"/> </set> </parameter> </constructor> <property name="history">9</property> <property name="decayfactor">2</property> </bean> Load metrics can be configured with an associated weight and capacity: 1. The weight (default is 1) indicates the significance of a metric with respect to the other metrics. For example, a metric of weight 2 will have twice the impact on the overall load factor than a metric of weight The capacity of a metric serves 2 functions: Each load metric contributes a value to the overall load factor of a node. The load factors from each metric are aggregated according to their weights. In general, the load factor contribution of given metric is: (load capacity) weight total weight The DynamicLoadBalanceFactorProvider applies a time decay function to the loads returned by each metric. The aggregate load, with respect to previous load values, can be expressed by the following formula: L = (L0 + L1 D + L2 D2 + L3 D LH DH) (1 + D + D2 + D DH)... or more concisely as: H H L = Li/Di * Di i=0 i=0 45

50 HTTP Connectors Load Balancing Guide... where D = decayfactor and H = history. Setting history = 0 effectively disables the time decay function and only the current load for each metric will be considered in the load balance factor computation. The mod_cluster proxy module expects the load factor to be an integer between 0 and 100, where 0 indicates max load and 100 indicates zero load. Therefore, the final load balance factor sent to the proxy is: (L 100) While you are free to write your own load metrics, the following LoadMetrics are available out of the box: WEB CONTAINER METRICS 1. ActiveSessionsLoadMetric Requires an explicit capacity. Uses SessionLoadMetricSource to query session managers Analogous to method=s in mod_jk For example: <bean name="activesessionsloadmetric" class="org.jboss.modcluster.lo ad.metric.impl.activesessionsloadmetric" mode="on Demand"> <annotation>@org.jboss.aop.microcontainer.aspects.jmx.jmx(name="jb oss.web:service=activesessionsloadmetric",exposedinterface=org.jboss.modcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter><inject bean="sessionloadmetricsource"/></parameter> </constructor> <property name="capacity">1000</property> </bean> <bean name="sessionloadmetricsource" class="org.jboss.modcluster.loa d.metric.impl.sessionloadmetricsource" mode="on Demand"> <constructor> <parameter class="javax.management.mbeanserver"><inject bean="jm XKernel" property="mbeanserver"/></parameter> </constructor> </bean> 2. BusyConnectorsLoadMetric Returns the percentage of connector threads from the thread pool that are busy servicing requests Uses ThreadPoolLoadMetricSource to query connector thread pools Analogous to method=b in mod_jk For example: 46

51 CHAPTER 11. LOAD METRICS <bean name="busyconnectorsloadmetric" class="org.jboss.modcluster.lo ad.metric.impl.busyconnectorsloadmetric" mode="on Demand"> oss.web:service=busyconnectorsloadmetric",exposedinterface=org.jboss.modcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter><inject bean="threadpoolloadmetricsource"/></paramete r> </constructor> </bean> <bean name="threadpoolloadmetricsource" class="org.jboss.modcluster. load.metric.impl.threadpoolloadmetricsource" mode="on Demand"> <constructor> <parameter class="javax.management.mbeanserver"><inject bean="jm XKernel" property="mbeanserver"/></parameter> </constructor> </bean> 3. ReceiveTrafficLoadMetric Returns the incoming request traffic in KB/sec Requires an explicit capacity Uses RequestProcessorLoadMetricSource to query request processors Analogous to method=t in mod_jk For example: <bean name="receivetrafficloadmetric" class="org.jboss.modcluster.lo ad.metric.impl.receivetrafficloadmetric" mode="on Demand"> oss.web:service=receivetrafficloadmetric",exposedinterface=org.jboss.modcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter class="org.jboss.modcluster.load.metric.impl.requestp rocessorloadmetricsource"><inject bean="requestprocessorloadmetricso urce"/></parameter> </constructor> <property name="capacity">1024</property> </bean> <bean name="requestprocessorloadmetricsource" class="org.jboss.modcl uster.load.metric.impl.requestprocessorloadmetricsource" mode="on De mand"> <constructor> <parameter class="javax.management.mbeanserver"><inject bean="jm XKernel" property="mbeanserver"/></parameter> </constructor> </bean> 4. SendTrafficLoadMetric Returns the outgoing request traffic in KB/sec Requires an explicit capacity 47

52 HTTP Connectors Load Balancing Guide Uses RequestProcessorLoadMetricSource to query request processors Analogous to method=t in mod_jk For example: <bean name="sendtrafficloadmetric" class="org.jboss.modcluster.load. metric.impl.sendtrafficloadmetric" mode="on Demand"> oss.web:service=sendtrafficloadmetric",exposedinterface=org.jboss.mo dcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter class="org.jboss.modcluster.load.metric.impl.requestp rocessorloadmetricsource"><inject bean="requestprocessorloadmetricso urce"/></parameter> </constructor> <property name="capacity">512</property> </bean> 5. RequestCountLoadMetric Returns the number of requests/sec Requires an explicit capacity Uses RequestProcessorLoadMetricSource to query request processors Analogous to method=r in mod_jk For example: <bean name="requestcountloadmetric" class="org.jboss.modcluster.load.metric.impl.requestcountloadmetric" mode="on Demand"> oss.web:service=requestcountloadmetric",exposedinterface=org.jboss.m odcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter class="org.jboss.modcluster.load.metric.impl.requestp rocessorloadmetricsource"><inject bean="requestprocessorloadmetricso urce"/></parameter> </constructor> <property name="capacity">1000</property> </bean> SYSTEM/JVM METRICS 1. AverageSystemLoadMetric Returns CPU load Requires Java Uses OperatingSystemLoadMetricSource to generically read attributes For example: 48

53 CHAPTER 11. LOAD METRICS <bean name="averagesystemloadmetric" class="org.jboss.modcluster.loa d.metric.impl.averagesystemloadmetric" mode="on Demand"> oss.web:service=averagesystemloadmetric",exposedinterface=org.jboss. modcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter><inject bean="operatingsystemloadmetricsource"/></par ameter> </constructor> </bean> <bean name="operatingsystemloadmetricsource" class="org.jboss.modclu ster.load.metric.impl.operatingsystemloadmetricsource" mode="on Dema nd"> </bean> 2. SystemMemoryUsageLoadMetric Returns system memory usage Requires com.sun.management.operatingsystemmxbean (available in Sun's JDK or OpenJDK) Uses OperatingSystemLoadMetricSource to generically read attributes For example: <bean name="systemmemoryusageloadmetric" class="org.jboss.modcluster.load.metric.impl.systemmemoryusageloadmetric" mode="on Demand"> oss.web:service=systemmemoryusageloadmetric",exposedinterface=org.jb oss.modcluster.load.metric.loadmetricmbean.class)</annotation> <constructor> <parameter><inject bean="operatingsystemloadmetricsource"/></par ameter> </constructor> </bean> 3. HeapMemoryUsageLoadMetric Returns the heap memory usage as a percentage of max heap size For example: <bean name="heapmemoryusageloadmetric" class="org.jboss.modcluster.l oad.metric.impl.heapmemoryusageloadmetric" mode="on Demand"> <annotation>@org.jboss.aop.microcontainer.aspects.jmx.jmx(name="jb oss.web:service=heapmemoryusageloadmetric",exposedinterface=org.jbos s.modcluster.load.metric.loadmetricmbean.class)</annotation> </bean> OTHER METRICS 1. ConnectionPoolUsageLoadMetric 49

54 HTTP Connectors Load Balancing Guide Returns the percentage of connections from a connection pool that are in use. Uses ConnectionPoolLoadMetricSource to query JCA connection pools For example: <bean name="connectionpoolusagemetric" class="org.jboss.modcluster.load.me tric.impl.connectionpoolusageloadmetric" mode="on Demand"> <annotation>@or g.jboss.aop.microcontainer.aspects.jmx.jmx(name="jboss.web:service=connect ionpoolusageloadmetric",exposedinterface=org.jboss.modcluster.load.metric. LoadMetricMBean.class)</annotation> <constructor> <parameter><inject bean="connectionpoolloadmetricsource"/></parameter> </constructor> </bean> <bean name="connectionpoolloadmetricsource" class="org.jboss.modcluster.lo ad.metric.impl.connectionpoolloadmetricsource" mode="on Demand"> <constructor> <parameter class="javax.management.mbeanserver"><inject bean="jmxkerne l" property="mbeanserver"/></parameter> </constructor> </bean> 50

55 CHAPTER 12. LOAD BALANCING DEMONSTRATION CHAPTER 12. LOAD BALANCING DEMONSTRATION The JBoss HTTP Connector includes a load balancing demonstration to show how different server-side scenarios affect the client request routing performed by the load balancing proxy server. The required configuration is located in the JBOSS_EAP_DIST/mod_cluster/demo directory. The application consists of two primary components: /server/load-demo.war A WAR file to be deployed in JBoss Enterprise Application Platform or JBoss Enterprise Web Server. This WAR includes a number of servlets. /client/lib/mod-cluster-demo.jar A web application that lets users launch a pool of threads, by sending requests through the load balancer to the application's primary servlet. The application displays information about which servers are handling the requests. It can also send separate requests to the application's loadgeneration servlets, allowing the user to see how certain load conditions affect request load balancing. This application can be used to demonstrate how different worker-side scenarios impact the routing decisions of the proxy server. IMPORTANT If running the demonstration on JBoss Enterprise Web Server, the only metrics available will be System, and JVM metrics. The demonstration application is not designed to interact with any other metrics in Tomcat 6. NOTE The demonstration application does not show the maximum load a cluster configuration can handle SET UP THE DEMONSTRATION The following procedure summarizes how to set up and start the demonstration. These steps will then be explained in further detail. Once the demonstration is running, refer to Section 12.3, Interact with the demonstration. Task: Start the Demo Complete this task to set up the base requirements of the demonstration. Prerequisites Install and Configure the Worker Node. Refer to Section 8.2, Install and configure a worker node Install and Configure the Proxy Server. Refer to Section 9.1, Static proxy configuration 1. Start the Proxy Server Navigate to HTTPD_DIST/sbin and start the proxy server. 51

56 HTTP Connectors Load Balancing Guide [sbin]$ apachectl start 2. Start the Worker Node In a terminal, execute the following command: For JBoss Enterprise Web Server: [home]$./jboss_ews_dist/tomcat6/bin/startup.sh For JBoss Enterprise Application Platform: [home]$./jboss_eap_dist/bin/run.sh 3. On JBoss Enterprise Web Server, specify the Catalina Service Name Tomcat 6 only: In $JBOSS_EWS_DIST/mod_cluster/src/demo/resources/web.xml, under the <web-app> element, append a <context-param> directive, which specifies Catalina as a service. <context-param> <param-name>service-name</param-name> <param-value>catalina</param-value> </context-param> 4. Deploy Demo Web Archive to Worker Node Copy load-demo.war from JBOSS-EAP_DIST/mod_cluster/demo/server into one of the following directories: For JBoss Enterprise Web Server: JBOSS_EWS_DIST/tomcat6/webapps For JBoss Enterprise Application Platform: JBOSS_EAP_DIST/jboss-as/server/PROFILE/deploy 5. Start the Demonstration Navigate to JBOSS_EAP_DIST/mod_cluster/demo/client/, and start the demonstration. [client]$./run-demo.sh Result The demonstration starts, and the Load Balancing Demonstration window opens. Proceed to Task: Configure Client Control Tab Fields 52

57 CHAPTER 12. LOAD BALANCING DEMONSTRATION CONFIGURE THE DEMO CLIENT You must configure the demonstration's Client Control parameters to ensure the client operates as expected throughout the demonstration. Task: Configure Client Control Tab Fields Complete this task to configure the Client Control tab of the Load Balancing Demonstration. Terms Proxy Hostname Hostname of the load-balancing proxy server, or the IP address on which the proxy server is listening for requests. The default value for this field is localhost, or determined by the mod_cluster.proxy.host system property, if set. Edit the -Dmod_cluster.proxy.host=localhost value in run-demo.sh to avoid re-setting this value each time you use the demo. Proxy Port Port on which the load-balancing proxy server listens for requests. The default value is 8000, or determined by the mod_cluster.proxy.port property, if set. Edit the -Dmod_cluster.proxy.port=8000 value in run-demo.sh to avoid re-setting this value each time you use the demo. Context Path The part of the request URL that specifies the request is for load-demo.war. Session Life 53