Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

Configuring the Load Balancer

A load balancer configuration is a named configuration in the domain.xml file. Load balancer configuration is extremely flexible:

This section describes how to create, modify, and use a load balancer configuration, including the following topics:

Creating an HTTP Load Balancer Configuration

Create a load balancer configuration using the asadmin command create-http-lb-config. Creating an HTTP Load Balancer Configuration describes the parameters. For more information see the documentation for create-http-lb-config, delete-http-lb-config, and list-http-lb-configs.

Table 4–1 Load Balancer Configuration Parameters



response timeout 

Time in seconds within which a server instance must return a response. If no response is received within the time period, the server is considered unhealthy. The default is 60. 

HTTPS routing

Whether HTTPS requests to the load balancer result in HTTPS or HTTP requests to the server instance. For more information, see Configuring HTTPS Routing.

reload interval 

Interval between checks for changes to the load balancer configuration file loadbalancer.xml. When the check detects changes, the configuration file is reloaded. A value of 0 disables reloading.For more information, see Enabling Dynamic Reconfiguration


Whether monitoring is enabled for the load balancer. 


Name of the cookie the load balancer plug-in uses to record the route information. The HTTP client must support cookies. If your browser is set to ask before storing a cookie, the name of the cookie is JROUTE. 


Target for the load balancer configuration. If you specify a target, it is the same as adding a reference to it. Targets can be clusters or stand-alone instances.

Creating an HTTP Load Balancer Reference

When you create a reference in the load balancer to a stand-alone server or cluster, the server or cluster is added to the list of target servers and clusters the load balancer controls. The referenced server or cluster still needs to be enabled (using enable-http-lb-server) before requests to it are load balanced. If you created the load balancer configuration with a target, that target is already added as a reference.

Create a reference using create-http-lb-ref. You must supply the load balancer configuration name and the target server instance or cluster.

To delete a reference, use delete-http-lb-ref. Before you can delete a reference, the referenced server or cluster must be disabled using disable-http-lb-server .

For more information, see the documentation for create-http-lb-ref and delete-http-lb-ref.

Enabling Server Instances for Load Balancing

After creating a reference to the server instance or cluster, enable the server instance or cluster using enable-http-lb-server . If you used a server instance or cluster as the target when you created the load balancer configuration, you must enable it.

For more information, see the documentation for enable-http-lb-server .

Enabling Applications for Load Balancing

All servers managed by a load balancer must have homogenous configurations, including the same set of applications deployed to them. Once an application is deployed and enabled for access (this happens during or after the deployment step) you must enable it for load balancing. If an application is not enabled for load balancing, requests to it are not load balanced and failed over, even if requests to the servers the application is deployed to are load balanced and failed over.

When enabling the application, specify the application name and target. If the load balancer manages multiple targets (for example, two clusters), enable the application on all targets.

For more information, see the online help for enable-http-lb-application .

If you deploy a new application, you must also enable it for load balancing and export the load balancer configuration again.

Creating the HTTP Health Checker

The load balancer’s health checker periodically checks all the configured Application Server instances that are marked as unhealthy. A health checker is not required, but if no health checker exists, or if the health checker is disabled, the periodic health check of unhealthy instances is not 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. A status code in the HTTP response header between 100 and 500 means the instance is healthy.

Creating a Health Checker

To create the health checker, use the asadmin create-http-health-checke r command. Specify the following parameters:

Table 4–2 Health Checker Parameters





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



Specifies the interval in seconds at which health checks of instances occur. Specifying 0 disables the health checker. 

30 seconds 


Specifies the timeout interval in seconds within which a response must be obtained for a listener to be considered healthy.  

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 specified URL to check all unhealthy application server instances to determine 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.

For more information see the documentation for create-http-health-checker and delete-http-health-checker.

Additional Health Check Properties for Healthy Instances

The health checker created by create-http-health-checker only checks unhealthy instances. To periodically check healthy instances set some additional properties in your exported loadbalancer.xml file.

Note –

These properties can only be set by manually editing loadbalancer.xml after you’ve exported it. There is no equivalent asadmin command to use.

To check healthy instances, set the following properties:

Table 4–3 Health-checker Manual Properties




True/false flag indicating whether to ping healthy server instances to determine whether they are healthy. To ping server instances, set the flag to true. 


Specifies how many times the load balancer’s health checker pings an unresponsive server instance before marking it unhealthy. Valid range is between 1 and 1000. A default value to set is 3. 

Set the properties by editing the loadbalancer.xml file. For example:

<property name="active-healthcheck-enabled" value="true"/>
<property name="number-healthcheck-retries" value="3"/>

If you add these properties, then subsequently edit and export the loadbalancer.xml file again, you must add these properties to the file again, since the newly exported configuration won’t contain them.

Exporting the Load Balancer Configuration File

The load balancer plug-in shipped with Sun Java System Application Server uses a configuration file called loadbalancer.xml. Use the asadmin tool to create a load balancer configuration in the domain.xml file. After configuring the load balancing environment, export it to a file.

ProcedureTo export the load balancer configuration

  1. Export a loadbalancer.xml file using the asadmin command export-http-lb-config.

    Export the loadbalancer.xml file for a particular load balancer configuration. You can specify a path and a different file name. If you don’t specify a file name, the file is named loadbalancer.xml. load_balancer_config_name. If you don’t specify a path, the file is created in the application_server_install_dir /domains/domain_name /generated directory.

    To specify a path on Windows, use quotes around the path. For example, "c:\sun\AppServer\loadbalancer.xml" .

  2. Copy the exported load balancer configuration file to the web server’s configuration directory.

    For example, for the Sun Java System Web Server, that location might be web_server_root/config .

    The load balancer configuration file in the web server’s configuration directory must be named loadbalancer.xml. If your file has a different name, such as loadbalancer.xml. load_balancer_config_name, you must rename it.

Changing the Load Balancer Configuration

If you change a load balancer configuration by creating or deleting references to servers, deploying new applications, enabling or disabling servers or applications, and so on, export the load balancer configuration file again and copy it to the web server’s config directory. For more information, see Exporting the Load Balancer Configuration File

The load balancer plug-in checks for an updated configuration periodically based on the reload interval specified in the load balancer configuration. After the specified amount of time, if the load balancer discovers a new configuration file, it starts using that configuration.

Enabling Dynamic Reconfiguration

With dynamic reconfiguration, the load balancer plug-in periodically checks for an updated configuration.

To enable dynamic reconfiguration:

Note –

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 compliant with the DTD before over writing the existing configuration.

If a disk read error is encountered, a warning message is logged to the web server’s error log file.

The error log for Sun Java System Web Server’ is at: web_server_install_dir/webserver_instance /logs/.

Disabling (Quiescing) a Server Instance or Cluster

Before stopping an application server for any reason, you want the instance to complete serving requests. The process of gracefully disabling a server instance or cluster is called quiescing.

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

ProcedureTo disable a server instance or cluster

  1. Run asadmin disable-http-lb-server, setting the timeout (in minutes).

  2. Export the load balancer configuration file using asadmin export-http-lb-config.

  3. Copy the exported configuration to the web server config directory.

  4. Stop the server instance or instances.

Disabling (Quiescing) an Application

Before you undeploy a web application, you want to the application to complete serving requests. The process of gracefully disabling an application is called quiescing. When you quiesce an application, you specify a timeout period. Based on the timeout period, the load balancer uses the following policy for quiescing applications:

ProcedureTo disable an application

  1. Use asadmin disable-http-lb-application, specifying the following:

    • Timeout (in minutes).

    • Name of the application to disable.

    • Target cluster or instance on which to disable it.

  2. Export the load balancer configuration file using asadmin export-http-lb-config.

  3. Copy the exported configuration to the web server config directory.

Configuring HTTP and HTTPS Failover

The load balancer plug-in fails over HTTP/HTTPS sessions to another application server instance if the original application server instance to which the session was connected becomes unavailable. This section describes how to configure the load balancer plug-in to enable HTTP/HTTPS routing and session failover.

This section discusses the following topics:

HTTPS Routing

The HTTP Secure (HTTPS) protocol uses Secure Sockets Layer (SSL) to provide encryption an decryption of HTTP requests for secure communication. For HTTPS routing to work, one or more HTTPS listeners must be configured.

The load balancer plug-in routes all incoming HTTP or HTTPS requests to application server instances. However, if HTTPS routing is enabled, an HTTPS request will be forwarded by the load balancer plug-in to the application server using an HTTPS port only. 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 httpsrouting option of the create-http-lb-config command controls whether HTTPS routing is turned on or off for all the application servers that are participating in load balancing. If this option is set to false, all HTTP and HTTPS requests are forwarded as HTTP. Set it to true when creating a new load balancer configuration, or change it later using the asadmin set command.

Note –

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.

Known Issues

The Load Balancer has the following limitations with HTTP/HTTPS request processing.

Configuring Idempotent URLs

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. Retrying an idempotent URL must not cause values to change on the server or in the database. The only difference is 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 does not cause an update or modification of data.

To enhance the availability of deployed applications, configure the environment to retry failed idempotent HTTP requests on all the application server instances serviced by a load balancer. This option is used for read-only requests, for example, to retry a search request.

Configure idempotent URLs in the sun-web.xml file. When you export the load balancer configuration, idempotent URL information is automatically added to the loadbalancer.xml file.

For more information on configuring idempotent URLs, see Configuring Idempotent URL Requests in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer’s Guide.