Previous      Contents      Index      Next
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Update 3 Administration Guide

Chapter 17
Configuring HTTP Load Balancing and Failover (Enterprise Edition)

This chapter describes how to setup load balancing and failover of HTTP/S requests.

This chapter includes the following topics:

About Load Balancing and Failover
Configuring HTTP Load Balancing and Failover
Administering HTTP Load Balancing and Failover
Monitoring the Load Balancer Plug-in
Known Issues in Load Balancing Requests

---

About Load Balancing and Failover

Sun Java™ System Application Server Enterprise Edition provides high availability of HTTP sessions. The goal of load balancing is to evenly distribute the workload between multiple Sun Java System Application Server instances, thereby increasing the overall throughput of the system.

This section discusses the following topics:

Requirements for Load Balancing
Using Third Party Load Balancers
Understanding Assigned Requests and Unassigned Requests
HTTP Load Balancing Algorithm
Migrating from Application Server 6.5 to Application Server 7 2004Q2

Requirements for Load Balancing

The following sections lists the requirements for load balancing HTTP requests.

You must meet the following requirements before you can use the load balancer plug-in:

Sun Java System Application Server Enterprise Edition is installed.
A web server is installed (Sun Java System Web Server 6.1 or Apache 1.23.29 or Apache 2 or Microsoft IIS).
At least two application server instances are created and HTTP listeners configured in a cluster.
Deployed your web applications to all application server instances that will participate in load balancing.

Note	The HTTP listeners and RMI/IIOP endpoints (if you are using RMI/IIOP load balancing) must be configured on the same cluster of Application Server instances. For more information on clusters, see Chapter 19, "Managing Clusters (Enterprise Edition)." For more information on RMI/IIOP load balancing, see Chapter 18, "Configuring RMI/IIOP Load Balancing and Failover (Enterprise Edition)."

Using Third Party Load Balancers

If you use a third party software or hardware load balancer instead of the bundled load balancer plug-in (between the web server and application server), you should configure the third party load balancer to support session affinity.

However, if the third party load balancer is configured to load balance requests to multiple web servers (the bundled load balancer plug-in continues to communicate between the web server and Application Server), there is no need to configure session affinity for the third party load balancer. In such a scenario, session affinity is managed by the bundled load balancer plug-in.

For a list of supported third party load balancers, see the Release Notes at the product’s documentation web site.

Understanding Assigned Requests and Unassigned Requests

When a request first comes in from a HTTP client to the load balancer, it is a request for a new session. A request for a new session is called an unassigned request. The load balancer routes this request to an application server instance in the cluster according to a round-robin algorithm. For more information, see HTTP Load Balancing Algorithm.

Once a session is created on an application server instance, the load balancer routes all subsequent requests for this session only to that particular instance. A request for an existing session is called an assigned or a sticky request.

HTTP Load Balancing Algorithm

The Sun Java System Application Server load balancer uses a sticky round robin algorithm to load balance incoming HTTP and HTTPS requests. This means that all requests for a given session are sent to the same application server instance. With a sticky load balancer, the session data can be cached on a single application server rather than having to be distributed to all instances in a cluster.

Therefore, the sticky round robin scheme provides significant performance benefits that normally override the benefits of a more evenly distributed load that can be obtained with pure round robin.

About Sticky Round Robin Load Balancing Algorithm

When a new HTTP request is sent to the load balancer plug-in, it’s forwarded to an application server instance based on a simple round robin scheme. Subsequently, this request is “stuck” to this particular application server instance, either by using cookies, or explicit URL rewriting.

From the sticky information, the load balancer plug-in first determines the instance to which the request was previously forwarded. If that instance is found to be healthy, the load balancer plug-in forwards the request to that specific application server instance. Therefore, all requests for a given session are sent to the same application server instance.

The load balancer plug-in uses the following methods to determine session stickiness:

Cookie Based Method
Explicit URL Rewriting Method

Cookie Based Method

In the cookie based method, the load balancer plug-in uses a separate cookie to record the route information.

Note	The HTTP client must support cookies to use the cookie based method.

Explicit URL Rewriting Method

In the explicit URL rewriting method, the sticky information is appended to the URL. This method works even if the HTTP client does not support cookies.

Migrating from Application Server 6.5 to Application Server 7 2004Q2

The context root used in Sun ONE Application Server Enterprise Edition 6.5 is hardcoded to /NASApp. Therefore, applications deployed on Application Server 6.5 must package, deploy, and maintain exactly the same context root.

To migrate such applications easily to Application Server 7 2004Q2, a new parameter has been added to the loadbalancer.xml file. The loadbalancer will now accept a new parameter called remove-string-from-context-root.

For example:

<property name="remove-string-from-context-root" value="/NASApp"/>

The context root should then be configured in the loadbalancer.xml as:

<web-module context-root="NASApp/clusterjsp" enabled="true" disable-timeout-in-minutes="60" error-url="sun-http-lberror.html"/>

where, clusterjsp is the application root.

If needed additional context roots can be configured without NASApp for clients which do not have NASApp in the URI.

For example:

<web-module context-root="clusterjsp" enabled="true" disable-timeout-in-minutes="60" error-url="sun-http-lberror.html"/>

When this new property is set, the loadbalancer will remove the string from the URI when it passes the request to the Application Server. When the loadbalancer receives the response, it examines all the cookies and modifies them to insert the string back in the path parameter of the cookie so that the browser is able to correctly store the cookies.

Additionally, the loadbalancer also modifies all absolute redirects (with the loadbalancer’s host and port in the URL) coming from the Application Server and inserts the string back, if the client has used the string in the original request. For the client, it would look like the usual Application Server 6.x behavior.

---

Configuring HTTP Load Balancing and Failover

The load balancer plug-in is an enhanced version of the HTTP reverse proxy plug-in used in Sun Java System Application Server, Standard Edition. For more information on the reverse proxy plug-in, see Chapter 12, "Configuring the Web Server Plug-in."

This section discusses the following topics:

Configuration Changes to Web Servers
Creating Load Balancer Configuration File
Configuring Multiple Web Server Instances

Configuration Changes to Web Servers

The load balancer plug-in installation program makes a few modifications to the web server’s configuration files. This section details the changes to the following web server’s configuration files:

Modifications to Sun Java System Web Server
Modifications to Apache Web Server
Modifications to Microsoft IIS

Note	The load balancer plug-in can be installed either along with Sun Java System Application Server Enterprise Edition, or separately, on a machine running the supported web server. For complete details on the installation procedure, see Sun Java System Application Server Installation Guide.

Modifications to Sun Java System Web Server

The installation program makes the following changes to the Sun Java System Web Server’s configuration files:

Adds the following load balancer plug-in specific entries to the web server instance’s magnus.conf file:

##EE lb-plugin
Init fn="load-modules" shlib="webserver_install_dir/plugins/lbplugin/bin/libpassthrough.so" funcs="init-passthrough,service-passthrough,name-trans-passthrough" Thread="no"

Init fn="init-passthrough"

##end addition for EE lb-plugin

Adds the following entries specific to the load balancer plug-in to the web server instance’s obj.conf file:

<Object name=default>

NameTrans fn="name-trans-passthrough" name="lbplugin" config-file="webserver_install_dir/webserver_instance/config/loadbalancer.xml"

<Object name="lbplugin">
ObjectType fn="force-type" type="magnus-internal/lbplugin"
PathCheck fn="deny-existence" path="*/WEB-INF/*"
Service type="magnus-internal/lbplugin" fn="service-passthrough"
Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"
</object>

lbplugin is a name that uniquely identifies the Object, and webserver_install_dir/webserver_instance/config/loadbalancer.xml is the location of the XML configuration file for the virtual server on which the load balancer is configured to run.

You must now configure the load balancing plug-in, by editing the loadbalancer.xml configuration file. For more information on editing the loadbalancer.xml file, see Creating Load Balancer Configuration File.

Modifications to Apache Web Server

Before installing the load balancer plug-in on Apache, see information on compiling and configuring Apache in Appendix C, "Compiling and Configuring Apache Web Server (Enterprise Edition)."

The load balancer plug-in installation program extracts the necessary files to the modules folder under the web server’s root directory.It adds the following entries specific to the load balancer plug-in to the web server instance’s httpd.conf file:

<VirtualHost machine_name:443>

##Addition for EE lb-plugin

LoadFile /usr/lib/libCstd.so.1

LoadModule apachelbplugin_module libexec/mod_loadbalancer.so
#AddModule mod_apachelbplugin.cpp
<IfModule mod_apachelbplugin.cpp>
  config-file webserver_instance/conf/loadbalancer.xml
locale en
</IfModule>

<VirtualHost machine_ip_address>
DocumentRoot "webserver_instance/htdocs"
ServerName server_name
</VirtualHost>

##END EE LB Plugin ParametersVersion 7

Note	Apache web server must be run in secure mode to ensure that it works well with the load balancer plug-in. The URL pattern should be set to a definite context root, such as /fortune to ensure that all requests are forwarded to the correct application. If the request cannot match any of the installed applications, then it will be redirected to the web server. Create a directory called sec_db_files under apache_install_dir and copy <S1AS_installables_dir/sec_db_files/* to apache_install_dir/sec_db_files. When more than one Apache child processes are running, each process will have its own load balancing round robin sequence. For example, if there are two Apache child processes running, and the load balancing plug-in load balances on to two application server instances, the first request will be sent to instance #1 and the second request will also be sent to instance #1. The third request will be sent to instance #2 and the fourth request will be sent to instance #2 again. This trend will repeat (instance1, instance1, instance2, instance2, etc.) This behavior is different from what the user would usually expect, that is, instance1, instance2, instance1, instance2 .... This behavior is due to the fact that in Sun Java System Application Server Enterprise Edition, the load balancing plug-in Apache would instantiate a load balancer instance for each apache process, thereby creating an independent load balancing sequence. This issues is seen only on Apache 1.3. Apache 2.0 has a multi threaded behaviour if compiled with the --with-mpm=worker option.

This completes the configuration of load balancer plug-in on Apache Web Server.

Note	If you are running Apache on Windows, set the environment variable NSPR_NATIVE_THREADS_ONLY=1, before starting Apache web server. Go to Start->Settings->Control Panel->System->Advanced->Environment Variables->System Variables->New, and enter the following name and value pair- name: NSPR_NATIVE_THREADS_ONLY value: 1

by clicking on

Start->Settings->Control Panel->System->Advanced->Environment Variables->System Variables->New

and enter the following for name and value

name NSPR_NATIVE_THREADS_ONLY

You must now configure the load balancing plug-in, by editing the loadbalancer.xml configuration file. For more information on editing the loadbalancer.xml file, see Creating Load Balancer Configuration File.

Modifications to Microsoft IIS

To configure IIS to use the load balancer plug-in, you need to modify certain properties in Windows Internet Services Manager. The Internet Services Manager is located in the Administrative Tools folder in the Control Panel folder.

After installing the load balancer plug-in, open the Internet Services Manager and perform the following tasks:

Select the web site for which you want to enable the plug-in. This web site is typically named the Default Web Site.
Right click on the web site and select Properties to open the Properties notebook.
To add a new ISAPI filter, open the ISAPI Filters tab, click Add, and follow the steps given below:
In the Filter Name field, enter Application Server
In the Executable field, type C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.dll
Click OK, and close the Properties notebook.
You now need to create and configure a new virtual directory. Follow the steps given below to create and configure a new virtual directory:
Right click on the default web site, select New, and then Virtual Directory. The Virtual Directory Creation Wizard opens.
In the Alias field, type sun-passthrough.
In the Directory field, type C:\Inetpub\wwwroot\sun-passthrough
Ensure that you check the Execute Permission checkbox and that all other permission-related check boxes are left unchecked.
Click Finish.
Add the path of sun-passthrough.dll file and appserver_install_dir to Application Server’s PATH environment variable.
Configure the following entries in the sun-passthrough.properties file:

> lb-config-file -> path to loadbalancer.xml (Default: wwwroot\sun-passthroughoadbalancer.xml)

> log-file - > path to the loadbalancer log file (Default: wwwroot\sun-passthrough\lb.log)

> log-level-> logging level (Default: INFO)

Stop and start the web server for the new settings to take effect.

To stop the web server, right click on the web site and select Stop. To start the web server, right click on the web site and select Start.

Next, type the following in a web browser to access the web application context root:

http://webservername/webapplication

where, webservername is the hostname or IP address of the web server and /webapplication is the context root that you listed in the C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.properties file to verify that the web server, load balancer plug-in, and Application Server are operating correctly.

Note	If you are using Basic Authentication on the Application Server, make sure to configure your IIS web server as described here: 1.  Open Internet Services Manager by clicking on Start-> Settings->Control Panel->Administrative Tools->Internet Services Manager. 2.  Navigate to the web site (usually named Default Web Site). 3.  Right click on sun-passthrough virtual directory. 4.  Select Properties. 5.  Select Directory Security. 6.  Select the Edit tab of Anonymous and Access Control section. 7.  Uncheck Integrated Windows authentication and Basic Authentication. 8.  Make sure the Anonymous Access checkbox is checked.

This completes the installation of load balancer plug-in on IIS.

You must now configure the load balancing plug-in, by editing the loadbalancer.xml configuration file. For more information on editing the loadbalancer.xml file, see Creating Load Balancer Configuration File.

Creating Load Balancer Configuration File

The loadbalancer.xml file should be created based on the sun-loadbalancer_1_1.dtd and loadbalancer.xml.example files installed during load balancer installation. These files are available in the following location:

On Sun Java System Web Server: webserver_install_dir/webserver_instance/config directory.
On Apache: webserver_install_dir/webserver_instance/conf directory.

For more information on the elements and their attributes, see Appendix E, "HTTP Load Balancer Configuration File."

Sample loadbalancer.xml file

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE loadbalancer PUBLIC "-//Sun Microsystems Inc.//DTD Sun Java System Web Server 6.0//EN" "file:///webserver_install_dir/webserver_instance/config/sun-loadbalancer_ 1_1.dtd">

<loadbalancer>

<cluster name="cluster1">

<instance name="server1" enabled="true" listeners="http://machine1.sun.com:80 https://http://machine1.sun.com:443"/>

<instance name="server2" enabled="true" disable-timeout-in-minutes="31" listeners="http://machine2.sun.com:80 https://machine2.sun.com:443"/>

<web-module context-root="webapps-simple" enabled="true" error-url="webserver_installdir/error/error1.html">

<idempotent-url-pattern url-pattern="/simple*" no-of-retries="10"/>

</web-module>
<health-checker url="/" interval-in-seconds="60" timeout-in-seconds="10"/>

</cluster>

<property name="response-timeout-in-seconds" value="120"/>

<property name="reload-poll-interval-in-seconds" value="180"/>

<property name="https-routing" value="true"/>

<property name="require-monitor-data" value="true"/>

</loadbalancer>

Note	The following requirements should be considered while configuring the load balancer plug-in: One load balancer instance cannot have two clusters with the same name. One cluster cannot have two instance elements with the same name. One cluster cannot have two web-module elements with the same context-root. Application Server instance names are unique across servers/clusters. The listeners attribute is a space-separated list of URLs of the application server instance’s listeners. Therefore, no server instance either in a cluster, or across clusters, can have the same listener URL. The listeners attribute should be in the following format: http://hostname.domain:port For example: http://austen.sun.com:80 In this example, http://austen.sun.com, is the address of the application server instance followed by it’s port number, 80. instance name, such as, server1, are variables and you can provide any appropriate name. For HTTPS routing, we recommend that you create a dedicated HTTPS listener under each application server instance. For example, listeners="http://austen.sun.com:80 https://austen.sun.com:443" In this example, https://austen.sun.com, is the address of the application server instance followed by it’s port number, 443. You must specify the exact context root in the web-module element. Do not use a very general context root such as /*.

Save the changes made to the loadbalancer.xml file and restart your web server.

Note	For Apache Web Server, the DTD file will be in the conf directory. Therefore, the target location of the DTD file should be specified as given in the following example: "file:///webserver_install_dir/webserver_instance/conf/sun-loadbalancer_1_1.dtd"> For more information on creating and configuring application server instances, see Chapter 4, "Using Sun Java System Application Server Instances." The response-timeout-in-seconds property specifies the timeout interval within which a response must be obtained for a request that is load balanced, or an error page will be displayed. For information on clustering, see Chapter 19, "Managing Clusters (Enterprise Edition)."

For more information on loadbalancer.xml, see Appendix E, "HTTP Load Balancer Configuration File."

Configuring Multiple Web Server Instances

The Sun Java System Application Server installer will not allow the installation of multiple load balancer plug-ins on a single machine. If you need to have multiple web servers (with the load balancer plug-in), on a single machine, in either a single cluster or multiple clusters, a few manual steps are required to configure the load balancer plug-in.

Follow the procedure listed in this section to configure the load balancer plug-in for multiple web server instances.

Configuring Multiple Sun Java System Web Server Instances
Configuring Multiple Apache Web Server Instances

Configuring Multiple Sun Java System Web Server Instances

Make the following changes to the magnus.conf file of the web server instance on which you want to configure the load balancer plug-in:

Init fn="load-modules" shlib="webserver_install_dir/plugins/lbplugin/bin/libpassthrough.so" funcs="init-passthrough,service-passthrough,name-trans-passthrough" Thread="no"

Init fn="init-passthrough"

Make the following changes to the obj.conf file of the web server instance on which you want to configure the load balancer plug-in:

<Object name=default>

NameTrans fn="name-trans-passthrough" name="lbplugin" config-file="webserver_install_dir/webserver_instance/config/loadbalancer.xml"

<Object name="lbplugin">
ObjectType fn="force-type" type="magnus-internal/lbplugin"
PathCheck fn="deny-existence" path="*/WEB-INF/*"
Service type="magnus-internal/lbplugin" fn="service-passthrough"
Error reason="Bad Gateway" fn="send-error" uri="$docroot/badgateway.html"
</object>

Copy the sun-loadbalancer_1_1.dtd and loadbalancer.xml file from the existing (which is configured with the load balancer plug-in) web server instance’ config directory to new, load balancer configured, instance’s config directory.
Edit the loadbalancer.xml file as described in Creating Load Balancer Configuration File.

Configuring Multiple Apache Web Server Instances

Add the following entries specific to the load balancer plug-in to the web server instance’s httpd.conf file:

<VirtualHost machine_name:443>

##Addition for EE lb-plugin

LoadFile /usr/lib/libCstd.so.1

LoadModule apachelbplugin_module libexec/mod_loadbalancer.so
#AddModule mod_apachelbplugin.cpp
<IfModule mod_apachelbplugin.cpp>
  config-file webserver_instance/conf/loadbalancer.xml
locale en
</IfModule>

<VirtualHost machine_ip_address>
DocumentRoot "webserver_instance/htdocs"
ServerName server_name
</VirtualHost>

##END EE LB Plugin Parameters

Copy the sun-loadbalancer_1_1.dtd and loadbalancer.xml file from the existing (which is configured with the load balancer plug-in) web server instance’ conf directory to new, load balancer configured, instance’s conf directory.
Edit the loadbalancer.xml file as described in Creating Load Balancer Configuration File.

---

Administering HTTP Load Balancing and Failover

After setting up HTTP load balancing as described in Configuring HTTP Load Balancing and Failover, you should configure the load balancing plug-in to suit your operating environment. In most cases, changes to the load balancer plug-in can be made without stopping or restarting Application Server instances.

Therefore, you can adjust the load balancer’s behavior depending on fluctuating, external factors such as hardware failures or increase in traffic volume. This section describes procedures to configure and manage the behavior of the load balancing plug-in. All changes are made in the load balancer plug-in’s configuration file, loadbalancer.xml.

This section describes the following tasks:

Enabling/Disabling Application Server Instances
Enabling Dynamic Reconfiguration
Configuring HTTP/S Session Failover
Configuring Response Timeout
Configuring Quiescence
Configuring The Health-Checker
Configuring Idempotent URL Requests
Configuring HTML Error Pages

Enabling/Disabling Application Server Instances

Even if you start an Application Server instance and add it to a cluster, the application server instance will not receive requests from the load balancer until you enable it.

To enable an Application Server instance that has been added to the cluster, set the value of the enabled attribute of the instance element to true in the loadbalancer.xml file.
To disable an Application Server instance which is part of a cluster, set the value of the enabled attribute of the instance element to false in the loadbalancer.xml file.

To disable an Application Server instance (or a web application) gracefully, that is, without affecting the requests it is currently processing, you must configure the quiescing time interval. For more information quiescing, see Configuring Quiescence.

Note	Enabling an application server instance is different from starting the Application Server instance. Similarly, disabling an Application Server instance is different from stopping the Application Server instance.

Restarting Application Server Instances

When you make configuration changes to an Application Server instance that requires a restart, you must follow the correct sequence of operations:

Disable the Application Server instance.

Set the value of the enabled attribute of the instance element to false in the loadbalancer.xml file.

Stop the Application Server instance.

Use either asadmin or the Admin Console, as described in Chapter 1, "Getting Started with Sun Java System Application Server Administration."

Start the Application Server instance.

Use either asadmin or the Admin Console, as described in Chapter 1, "Getting Started with Sun Java System Application Server Administration."

Enable the Application Server instance.

Set the value of the enabled attribute of the instance element to true in the loadbalancer.xml file.

For more information on such scenarios, see Reconfiguring an Application Server Instance in a Running Cluster.

Note	After you mark an application server instance in the loadbalancer.xml file as enabled or disabled, the instance is enabled or disabled when the load balancer next polls the loadbalancer.xml file. For more information, see Enabling Dynamic Reconfiguration.

Enabling Dynamic Reconfiguration

The load balancer plug-in detects changes to its configuration by examining the time stamp of the loadbalancer.xml file. If a change is detected, the load balancer automatically reconfigures itself based on the values specified in the reload-poll-interval-in-seconds property.

To set the duration after which time the load balancer will check for configuration changes, do the following:

Open the loadbalancer.xml file for editing.
Edit the value of the property reload-poll-interval-in-seconds property.

By default, this value is set to 0 seconds, which implies that dynamic reconfiguration is not enabled.

Change the value to, for example, 180 seconds.
Save the changes.

The load balancer will now check the loadbalancer file every 180 seconds for any changes.

Note that the reload poll interval has a direct bearing on the quiescing period. If the load balancer’s reload interval is less than the quiescing period, the load balancer reloads the entire configuration and starts the quiescing process again, before quiescing can be completed.

For more information on quiescing, see Configuring Quiescence.

Note	If the changes to the loadbalancer.xml file are not in the correct format, as specified by the sun-loadbalancer_1_0.dtd, the reconfigure operation will fail. The failure notice will be printed in the web server’s error log files. The load balancer will continue to use the old configuration that’s already loaded in memory. If the load balancer encounters a hard disk read error while attempting to reconfigure itself, then it uses the configuration that is currently in memory. The load balancer also ensures that the modified configuration data is complaint with the DTD before over writing the existing configuration. If a disk read error is encountered, a warning message will be logged to the web server’s error log file. Sun Java System Web Server’s error log file can be found at this location: webserver_install_dir/webserver_instance/logs/.

Configuring HTTP/S Session Failover

This section describes how to configure the load balancer plug-in to enable HTTP/HTTPS routing and session fail over between the web server and Sun Java System Application Server. The load balancer plug-in fails over HTTP /HTTPS sessions over to another application server instance if the original application server instance to which the session was connected becomes unavailable.

The following topics are discussed in this section:

About HTTPS Routing
Configuring HTTPS Routing
Configuring HTTP Header Redirects

About HTTPS Routing

All incoming requests, whether HTTP or HTTPS (secure HTTP), are routed by the load balancer plug-in to application server instances. However, if HTTPS routing is enabled, a HTTPS request will be forwarded by the load balancer plug-in to the application server using an HTTPS port only. Note that HTTPS routing is performed on both new and sticky requests.

If an HTTPS request is received and no session is in progress, then the load balancer plug-in selects an available application server instance with a configured HTTPS port, and forwards the request to that instance.

In an ongoing HTTP session, if a new HTTPS request for the same session is received, then the session and sticky information saved during the HTTP session is used to route the HTTPS request. The new HTTPS request is routed to the same server where the last HTTP request was served, but on the HTTPS port.

Configuring HTTPS Routing

The https-routing property controls whether HTTPS routing is turned on or off for all the application servers that are participating in load balancing. If this property is set to false, then all HTTP and HTTPS requests are forwarded as HTTP.

To configure HTTPS routing and failover, perform the following steps:

Change the value of the property https-routing to true.

For example, <property name="https-routing" value="true"/>.

The https-routing property controls whether HTTPS routing is turned on or off for all the application servers that are participating in load balancing. If this property is set to false, then all HTTP and HTTPS requests are forwarded as HTTP.

Note	For HTTPS routing to work, there should be one or more HTTPS listeners configured. If https-routing is set to true, and a new or a sticky request comes in where there are no healthy HTTPS listeners in the cluster, then that request generates an error.

Configuring HTTP Header Redirects

Sun Java System Application Server Enterprise Edition 7 2004 Q2 Update 3 adds a new property in the load balancer configuration file to better control the HTTP/HTTPS routing behaviour.

By default, the rewrite-location parameter is set to true to maintain backward compatibility with previous Application Server releases.

You must set the rewrite-location property with the following points in mind:

If https-routing is true, rewrite-location should be false because the Application Server will be aware of HTTPS connections from the client.
If https-routing is false, and auth-passthrough is enabled on the Application Server, then rewrite-location should be false because the Application Server will be aware of HTTPS connections from the client.
If https-routing is false and auth-passthrough is not enabled on the Application Server, set the rewrite-location property to true because the load balancer will modify the protocol part of rewrite location suitably. That is, if the client is sending HTTPS requests, then the load balancer will redirect the client to a HTTPS enabled server instance. Similarly for HTTP requests.

However, if the application needs to redirect HTTP to HTTPS or HTTPS to HTTP, you must set the rewrite-location parameter to false.

Configuring Response Timeout

The response-timeout-in-seconds property specifies the timeout interval within which a response must be obtained for a request that is load balanced, or an error page will be displayed. The default value is 60 seconds.

While configuring response-timeout-in-seconds, you must take into account the maximum time-outs for all the applications that are running. The value should be set to the maximum response time of all the applications.

Configuring Quiescence

Quiescing is the process of gracefully disabling an application server instance or web application. You can set a duration, called the quiescing period, during which time the load balancer plug-in fails over sticky requests to another healthy instance in the cluster.

If you want to stop an application server instance for any reason (for example to add a JDBC resource), you would want this instance to complete serving these requests before you stop it. Similarly, if you want to undeploy a web application from a cluster, you would want to this application to complete serving the requests before undeploying it. You can achieve this by using the quiescing process.

For detailed information on quiescence, see Chapter 19, "Managing Clusters (Enterprise Edition)."

You can choose to quiesce an application or an application server instance. These two options are described in the following sections:

Quiescing an Instance
Quiescing an Application

Quiescing an Instance

The load balancer uses the following policy for quiescing application server instances:

If an instance is disabled, and the time out has not expired, then sticky requests will continue to be delivered to that instance. New requests, however, will not be sent to the disabled instance.
When the time-out expires, the instance is disabled. The load balancer does not send any requests to this instance, even if all sessions sticking to this instance were not invalidated. All open connections from the load balancer to the instance are closed. Instead, the load balancer will fail over sticky requests to another healthy instance in the same cluster.

Follow these steps to quiesce an instance:

In the loadbalancer.xml file, set the enabled sub-element under the instance element to false.
Set an appropriate value for the disable-timeout-in-minutes sub-element.

The disable-timeout-in-minutes sub-element represents the elapsed time after which the load balancer will disable the specified instance. The default is 31 minutes.

Quiescing an Application

The load balancer uses the following policy for quiescing applications:

If an application is disabled, and the time out has not expired, new requests to the disabled applications will not be forwarded by the load balancer. These requests will be returned to the web server. Sticky requests will continue to be forwarded till the time-out expires.
When the time out expires, the application is disabled. The load balancer will not accept any requests for this application, including sticky requests.

	When you quiesce an application, the users of the disabled application will experience loss of service until the application is re-enabled.

Follow these steps to quiesce an application:

In the loadbalancer.xml file, set the enabled sub-element under the web-module element to false.
Set an appropriate value for the disable-timeout-in-minutes sub-element.

The disable-timeout-in-minutes sub-element represents the elapsed time after which the load balancer will disable the specified application. The default is 31 minutes.

Configuring The Health-Checker

The load balancer periodically checks all the configured Sun Java System Application Server instances that are marked as unhealthy, based on the values specified in the health-checker element. Enabling the health checker is optional. If the health-checker is not enabled, periodic health check of unhealthy instances will not be performed.

The load balancer’s health check mechanism communicates with the application server instance using HTTP. The health checker sends an HTTP request to the URL specified and waits for a response. The status code in the HTTP response header should be between 100 and 500 to consider the instance to be healthy.

To enable the health checker, edit the following properties in the loadbalancer.xml file:

url

Specifies the listener’s URL that the load balancer will check to determine its state of health.

interval-in-seconds

Specifies the interval at which health checks of instances occur. The default is 30 seconds.

timeout-in-seconds

Specifies the timeout interval within which a response must be obtained for a listener to be considered healthy. The default is 10 seconds.

If an application server instance is marked as unhealthy, the health checker polls the unhealthy instances to determine if the instance has become healthy. The health checker uses the url attribute to check all unhealthy application server instances to check if they have returned to the healthy state.

If the health checker finds that an unhealthy instance has become healthy, that instance is added to the list of healthy instances.

Configuring Idempotent URL Requests

To enhance the availability of your applications deployed on a Sun Java System Application Server cluster, configure the load balancer to retry failed idempotent HTTP requests on all the application server instances in a cluster. This option can be used for read-only requests, for example, to retry a search request.

This section describes the following topics:

Specifying an Idempotent URL
Characteristics of an Idempotent URL

Specifying an Idempotent URL

To configure idempotent URL response, specify the URLs that can be safely retried in the idempotent-url-pattern sub-element on the web-module element. For example:

<idempotent-url-pattern url-pattern="sun_java/*" no-of-retries="10"/>

Two attributes you need to specify are url-pattern and no-of-retries.

url-pattern     The URL pattern of the idempotent requests.

The idempotent URL can be specified as an URL pattern using wild cards. The URL pattern should conform to the mappings specified in the section, SRV 11.2, of the Servlet specification.

For example, /foo/bar/* (to retry URLs of the type /foo/bar/index.html) or *.jpg (to retry URLs of the type /gallery/racecar.jpg).

no-of-retries    

The number of retries the load balancer should perform on different Application Server instances.

The default is -1. This would ensure that in the event of a failure, all the listeners on instances that are configured to handle the application URL are tried for serving the idempotent request.

If none of the server instances can successfully serve the request, the error page as specified by the user will be returned. To configure custom error pages, see Configuring HTML Error Pages

Characteristics of an Idempotent URL

Since all requests for a given session are sent to the same application server instance, and if that Application Server instance is unreachable, the load balancer will return an error message. Normally, the request will not be retried on another Application Server instance. However, if the URL pattern matches that specified in loadbalancer.xml file, then the request will be implicitly retried on another Application Server instance in the cluster.

An idempotent request is one that does not cause any change or inconsistency in an application, when retried. In HTTP, some methods (such as GET) are idempotent, while other methods (such as POST) are not. In effect, retrying an idempotent URL should not cause values to change on the server or in the database. The only difference should be a change in the response received by the user.

Examples of idempotent requests include, search engine queries and database queries. The underlying principle is that the retry would not cause an update or modification of data.

A search engine, for example, will send HTTP requests with the same URL pattern to the load balancer. Specifying the URL pattern of the search request to the load balancer ensures that HTTP requests with the specified URL pattern will be implicitly retried on another Application Server instance.

For example, if the request URL sent to the Application Server is of the type /search/something.html, then the URL pattern can be specified as /search/*.

Examples of non-idempotent requests include banking transactions and online shopping. If you retry such requests, chances are that money will be transferred twice from your account or you might unwittingly place a second order for, say pizzas.

Configuring HTML Error Pages

A new sub-element, error-url has been added to the web-module element of the loadbalancer configuration file. This option allows you to specify your own error page or a URL to an error page to be displayed to the end-user.

<web-module context-root="webapps-simple" enabled="true" error-url="webserver_installdir/error/error1.html">

To specify a custom error page, use the error-url sub-element. If this sub-element is specified, it overrides all other mechanisms configured for error reporting.

Note	The URL should not point to an URL on the Application Server instance since it would not be possible to load the error-url if the server is down. Instead, you should specify a URL that points to a location on the Web Server. To use the default error page on Windows, change ./sun-http-lberror.html to sun-http-lberror.html in the error-url element of loadbalancer.xml.

Sun Java System Application Server provides the following options for specifying the error page.

You could specify the error-url to be either the name of an HTML page in the standard load balancer pug-in’s error pages directory, or an HTTP URL. If you specify an HTTP URL, the load balancer will forward the client request to the specified error URL.

You should not specify the location of the error page to an absolute path in the local file system. The location must be relative to the webserver_install_dir/plugins/lbplugin/errorpages directory.

If you do not specify the error-url sub-element in the loadbalancer.xml file, then a default error page, sun-http-lberror.html, is picked up from the standard error pages directory, errorpages, if present.

As part of the load balancer plug-in installation, a directory called errorpages is created in the Web Server installation directory.

Rules Applicable for Displaying Error Pages

The error page that is displayed on the following rules:

When an error is encountered for an application, the load balancer will try to identify the specific web-module entry in loadbalancer.xml, based on the request URL. The load balancer will first check if the error-url sub-element has been defined for the web-module. If it has been defined, it will read the URL attribute and load the user-specified error page.
If the error-url sub-element is missing or invalid, the load balancer will display the default error page, sun-http-lb-error.html, from the errorpages directory of the load balancer plug-in.
If the error-url has been defined for a web-module but if that page is missing, the load balancer will load the default error page, sun-http-lb-error.html.
If the default error page is missing, the error will be forwarded to the web server.

---

Monitoring the Load Balancer Plug-in

This section discusses the following topics:

Configuring Log Messages
Configuring Monitoring
Understanding Monitoring Messages

Configuring Log Messages

The load balancer plug-in uses the web server’s logging mechanism to write log messages. The default log level on the Application Server is set to the default logging level on Sun Java System Web Server (INFO), and Apache Web Server (WARN). The application server log levels - FINE, FINER, and FINEST map to the DEBUG level on the web server.

These log messages are written to the web server log files, and are in the form of raw data that can be parsed using scripts, or imported into spreadsheets to calculate the metrics you need.

The following table provides the mapping between load balancer log levels and the corresponding log level of the web server.

Table 17-1  Load Balancer log levels mapped to Sun Java System Web Server

Load Balancer log level	Sun Java System Web Server
FATAL	LOG_CATASTROPHE
ALERT	LOG_FAILURE
SEVERE	LOG_FAILURE
WARNING	LOG_WARN
INFO	LOG_INFORM
CONFIG	LOG_INFORM
MONITOR	LOG_VERBOSE
FINE	LOG_VERBOSE
FINER	LOG_VERBOSE
FINEST	LOG_VERBOSE

Table 17-2  

Load Balancer log level	Apache Web Server
FATAL	APLOG_EMERG
ALERT	APLOG_ALERT
SEVERE	APLOG_CRIT
WARNING	APLOG_WARNING
INFO	APLOG_NOTICE
CONFIG	LOG_INFORM
MONITOR	APLOG_INFO
FINE	APLOG_DEBUG
FINER	APLOG_DEBUG
FINEST	APLOG_DEBUG

Load Balancer log levels mapped to Apache Web Server

Types of Log Messages

The load balancer plug-in generates the following three different sets of log messages:

Load Balancer Configurator Log Messages
Types of Log Messages
Request Dispatch and Runtime Log Messages
Configurator Error Messages

Load Balancer Configurator Log Messages

These messages will be logged when the load balancer configurator parses loadbalancer.xml for idempotent URLs and error page settings.

An output for idempotent URL pattern configuration will contain the following:

When the log level is set to FINE:

CONFxxxx: IdempotentUrlPattern configured <url-pattern> <no-of-retries> for web-module : <web-module> {LEVEL = FINE}

When the log level is set to SEVERE:

CONFxxxx: Duplicate entry of Idempotent URL element <url-pattern> for webModule <web-module> in loadbalancer.xml." {LEVEL = SEVERE}

When the log level is set to WARN:

CONFxxxx: Invalid IdempotentUrlPatternData <url-pattern> for web-module <web-module> {LEVEL = WARN}

An output for error page URL configuration will contain the following information:

CONFxxxx: Invalid error-url for web-module <web-module> {LEVEL = WARN}

Request Dispatch and Runtime Log Messages

These log messages are generated while a request is being load balanced and dispatched.

An output for standard logging for each method start will contain the following information:

ROUTxxxx: Executing Router method <method_name> {LEVEL = FINE}

An output for router logs for each method start will contain the following information:

ROUTxxxx: Successfully Selected another ServerInstance for idempotent request <Request-URL> {LEVEL = INFO}

An output for runtime logs will contain the following information:

RNTMxxxx: Retrying Idempotent <GET/POST/HEAD> Request <Request-URL> {LEVEL = INFO}

Configurator Error Messages

ROUTxxxx: Non Idempotent Request <Request-URL> cannot be retried {LEVEL = INFO}

Example :: ROUTxxxx: Non Idempotent Request http://abc.com/addToDB?x=11&abc=2 cannot be retried

RNTMxxxx: Invalid / Missing Custom error-url / page: <error-url> for web-module: <web-module> {LEVEL = FINE}

Example :: RNTMxxxx: Invalid / Missing Custom error-url / page: myerror1xyz for web-module: test

Configuring Monitoring

Perform the following steps to turn on load balancer plug-in log messages:

From Sun ONE Web Server’s admin console, go to the Magnus Editor tab.
Set the Log Verbose option to On.

For Apache Web Server, set the log level to DEBUG.

Set the value of the require-monitor-data in loadbalancer.xml property to true.

For example: <property name="require-monitor-data" value="true" />

The load balancer plug-in logs record the following information:

Request start/stop information is logged for every request.
Failed over request information is logged when the request fails over from an unhealthy instance to a healthy instance.
List of unhealthy instances is logged at the end of every health check cycle.

Note	When logging is enabled on the load balancer plug-in, and if the web server logging level is set to DEBUG or to print verbose messages, the load balancer writes HTTP session IDs in the web server log files. Therefore, if the web server hosting the load balancer plug-in is in the DMZ, we recommend that you do not use the DEBUG or similar log level in production environments. If you must use the DEBUG logging level, then you should turn off load balancer logging by setting require-monitor-data property to false in loadbalancer.xml.

Understanding Monitoring Messages

The format of the load balancer plug-in log messages is as follows.

The start of an HTTP request contains the following information:

RequestStart Sticky(New) <req-id> <time-stamp> <URL>

The timestamp value is the number of milliseconds from January 1, 1970. For example:

RequestStart New 123456 602983 http://austen.sun.com/Webapps-simple/servlet/Example1

The end of an HTTP request contains the RequestExit message, as follows:

RequestExit Sticky(New) <req-id> <time-stamp> <URL> <listener-id> <response-time> Failure-<reason for error>(incase of a failure)

For example:

RequestExit New 123456 603001 http://austen.sun.com/Webapps-simple/servlet/Example1 http://austen:2222 18

Note	In the RequestExit message, <response-time> indicates the total request turn-around time in milliseconds, from the perspective of the load balancer plug-in.

The list of unhealthy instances, as follows:

UnhealthyInstances <cluster-id> <time-stamp> <listener-id>, <listener-id>...

For example:

UnhealthyInstances cluster1 701923 http://austen:2210, http://austen:3010    

A list of failed-over requests, as follows:

FailedoverRequest <req-id> <time-stamp> <URL> <session-id> <failed-over-listener-id> <unhealthy-listener-id>

For example:

FailedoverRequest 239496 705623 http://austen.sun.com/Apps/servlet/SessionTest 16dfdac3c7e80a40 http://austen:4044 http://austen:4045

---

Known Issues in Load Balancing Requests

The following list discusses the limitations in Load Balancer with respect to HTTP/HTTPS request processing.

If a session uses a combination of HTTP and HTTPS requests, then the first request has to be a HTTP Request. If the first request is an HTTPS request, it cannot be followed by an HTTP request. This is because the cookie associated with the HTTPS session is not returned by the browser. The browser interprets the two different protocols as two different servers, and initiates a new session.

This limitation is valid only if https-routing is set to true.

If a session has a combination of HTTP and HTTPS requests, then the application server instance has to be configured with both HTTP and HTTPS listeners.

This limitation is valid only if https-routing is set to true.

If a session has a combination of HTTP and HTTPS requests, then the application server instance has to be configured with HTTP and HTTPS listeners that use standard port numbers, that is, 80 for HTTP, and 443 for HTTPS.

This limitation is valid regardless of the value set for https-routing.

Previous      Contents      Index      Next

---

Copyright 2005 Sun Microsystems, Inc. All rights reserved.