Sun GlassFish Enterprise Server v2.1.1 High Availability Administration Guide

Configuring the HTTP Load Balancer

Load balancer configuration is maintained in the domain.xml file. Configuring a load balancer is extremely flexible:

These sections describe, in more detail, how to create, modify, and use a load balancer configuration:

Configuring an HTTP Load Balancer on the DAS

You can create a load balancer configuration on the DAS using the Admin Console or the asadmin command create-http-lb. The following steps explain how you to do that. If you want more information about the asadmin commands, see the man pages or the Reference Manual for create-http-lb, delete-http-lb, and list-http-lbs.

In the Admin Console, scroll down the left frame, click the HTTP Load Balancers node and then in the HTTP Load balancers page on the right, click New. In the New HTTP Load Balancer page, provide the following details of the machine hosting the load balancer.

Field 

Description 

Name  

A name for the load balancer configuration. 

Enabled 

Click the Enabled check box to automatically push the load balancer configuration changes to the physical load balancer residing in the web server configuration directory. 

Host 

The server on which the web server instance is installed. 

Admin Port 

The secure HTTP listener port. 

Proxy Host 

The server on which the proxy server instance is installed. 

Proxy Port 

The port number used by the proxy server.  

You can also create a load balancer configuration using the asadmin command create-http-lb-config. Table 5–1 describes the parameters. For more information see the documentation for create-http-lb-config, delete-http-lb-config, and list-http-lb-configs.

Table 5–1 Load Balancer Configuration Parameters

Parameter 

Description 

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.

monitor 

Whether monitoring is enabled for the load balancer. 

routecookie 

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 

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

To create a reference using the Admin Console, on the left frame, click the HTTP Load Balancers node and then click the desired load balancer listed under the node. Open the Targets tab, click Manage Targets and in the Manage Targets page, select the required target. Alternatively, you can 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 HTTP 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. To do this using the Admin Console, on the left frame, click the HTTP Load Balancers node and then click the desired load balancer listed under the node. Now, open the Targets tab and in the Targets table, click the check box next to the instance you want to enable and click Enable.

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

Enabling Applications for HTTP 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.

To enable an application using the Admin Console, on the left frame, click the HTTP Load Balancers node and then click the desired load balancer listed under the node. Open the Targets tab as mentioned above and click the required cluster. Now, open the Applications tab, select the required application and from the More Actions drop-down list, and select Load Balancer Enable. If you want to do this from the command line, you can use the command asadmin enable-http-lb-application. For more information about the command, see the man pages.

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 Enterprise 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 will not be able to determine when an unhealthy instance becomes healthy.

The load balancer’s health check mechanism communicates with the 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.


Note –

If you have a deployment scenario where the load balancer is the front–end for a cluster that has instances using a secured port with client certificate authentication enabled, the health checker will not be able to perform a health check of the instances. Hence, those instances will always be marked unhealthy and no requests will be sent to them.


Creating a Health Checker

To specify the health checker properties, you can use the Admin Console or the asadmin create-http-health-checker command. To do this in the Admin Console, navigate to the HTTP Load Balancers node, expand it and select the load balancer. Then, open the Target tab, and in the Targets table, click the Edit Health Checker link for the desired target. Specify the following parameters.

Table 5–2 Health Checker Parameters

Parameter 

Description 

Default 

Load Balancer 

Click the Enabled check box to make the selected server available for load balancing. 

False/Disabled 

Disable Timeout 

The amount of time, in minutes, this server takes to reach a quiescent state after having been disabled . 

30 minutes 

url 

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

“/” 

interval 

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

30 seconds 

timeout 

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

10 seconds 

If an 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 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 5–3 Health-checker Manual Properties

Property 

Definition 

active-healthcheck-enabled

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. 

number-healthcheck-retries

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 using the asadmin set command. For example:

asadmin set domain.lb-configs.load-balancer-config.property.active-healthcheck-enabled=true

asadmin set domain.lb-configs.load-balancer-config.property.number-healthcheck-retries=5

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

Exporting the HTTP Load Balancer Configuration File

The load balancer plug-in available with Sun GlassFish Enterprise Server uses a configuration file called loadbalancer.xml. After configuring the load balancer, you can export the configuration details from domain.xml to the loadbalancer.xml file. You can do this using the Admin Console or the asadmin utility.

ProcedureTo Export the Load Balancer Configuration Using the Admin Console

  1. Navigate to the HTTP Load Balancers node and expand it.

  2. Click the desired load balancer.

    All the load balancer configuration details are displayed in the General, Settings and Target tabs.

  3. Open the Export tab and click Export now.

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

ProcedureTo Export the Load Balancer Configuration Using the asadmin tool

  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 domain-dir/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 usually is 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 HTTP 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 HTTP 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 reconfiguration, 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/web-server-instance/logs/.


Disabling (Quiescing) a Server Instance or Cluster

Before stopping the server for any reason, the instance should 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 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, the application should 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 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.

HTTPS Routing

The load balancer plug-in routes all incoming HTTP or HTTPS requests to instances. However, if HTTPS routing is enabled, an HTTPS request will be forwarded by the load balancer plug-in to a 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 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. If set to true, HTTPS are forwarded as HTTPS requests. Set HTTPS routing when creating a new load balancer configuration, or change it later using the asadmin set command.


Note –

Known Issues

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

Using Redirects with the HTTP Load Balancer

Use redirects to redirect a request from one URL to another URL. For example, use redirects to send users to a different web site (for example, redirecting from an old version of an application to a newer version) or from HTTP to HTTPS or from HTTPS to HTTP. Redirects can be enabled in a number of ways in the application (for example, servlet-based redirects, web.xml redirects). However, sending a redirect URL through the load balancer may require some additional configuration of the Enterprise Server or the load balancer. Note that redirects are different from requests that are forwarded using HTTPS Routing. When using redirects, set httpsrouting to false. If configuring HTTPS requests to be forwarded to HTTP, use HTTPS Routing.

The following properties affect redirects: the authPassthroughEnabled and proxyHandler properties of the HTTP service or HTTP listener, and the rewrite-location property in the loadbalancer.xml file.

The authPassthroughEnabled Property

When the Enterprise Server authPassthroughEnabled property is set to true, information about the original client request (such as client IP address, SSL keysize, and authenticated client certificate chain) is sent to the HTTP listeners using custom request headers. The authPassThroughEnabled property allows you to take advantage of a hardware accelerator for faster SSL authentication if you have one installed. It is easier to configure a hardware accelerator on the load balancer than on each clustered Enterprise Server instance.


Caution – Caution –

Set authPassthroughEnabled to true only if the Enterprise Server is behind a firewall.


Use the asadmin set command to set the authPassthroughEnabled property on the HTTP service or the individual HTTP listener. The setting for the individual HTTP listener takes precedence over the setting for the HTTP service.

To set the authPassthroughEnabled property on all HTTP/HTTPS listeners, use the following command:

asadmin set cluster-name-config.http-service.property.authPassthroughEnabled=true

To set it on an individual listener, use the following command:

asadmin set cluster-name-config.http-service.http-listener.listener-name.property.authPassthroughEnabled=true

The proxyHandler Property

The proxy handler for the Enterprise Server is responsible for retrieving information about the original client request that was intercepted by a proxy server (in this case, a load balancer) and forwarded to the server, and for making this information available to the deployed web application that is the target of the client request. If the intercepting proxy server is SSL-terminating, the proxy handler retrieves and makes available additional information about the original request, such as whether the original request was an HTTPS request, and whether SSL client authentication is enabled. Use the proxyHandler property only if authPassThroughEnabled is set to true.

The proxy handler inspects incoming requests for the custom request headers through which the proxy server conveys the information about the original client request, and makes this information available to the web application using standard ServletRequest APIs.

The proxy handler implementation is configurable, either globally at the HTTP service level or for individual HTTP listeners, with the proxyHandler property, whose value specifies the fully-qualified class name of an implementation of the com.sun.appserv.ProxyHandler abstract class. Configurable proxy handler implementations allow the server to work with any proxy server, as long as the proxy handler implementation knows about the HTTP request header names, and understands the format of their values, through which the proxy server conveys information about the original client request.

The proxy handler for the Enterprise Server reads and parses the SSL certificate chain from the request header. This allows a back-end instance to retrieve information about the original client request that was intercepted by an SSL-terminating proxy server (in this case, a load balancer). You can use the default proxy handler settings, or configure your own using the proxyHandler property of the HTTP service or HTTP/HTTPS listener. The proxyHandler property specifies the fully-qualified class name of a custom implementation of the com.sun.appserv.ProxyHandler abstract class used by the listener or all listeners.

An implementation of this abstract class inspects a given request for the custom request headers through which the proxy server communicates the information about the original client request to the instance, and returns that information to its caller. The default implementation reads the client IP address from an HTTP request header named Proxy-ip, the SSL keysize from an HTTP request header named Proxy-keysize, and the SSL client certificate chain from an HTTP request header named Proxy-auth-cert. The Proxy-auth-cert value must contain the BASE-64 encoded client certificate chain without the BEGIN CERTIFICATE and END CERTIFICATE boundaries and with \n replaced with % d% a.

You can only use this property if authPassThroughEnabled is set to true. If you set the proxyHandler property on an individual HTTP or HTTPS listener, it overrides the default setting for all listeners.

Use the asadmin set command to set the proxyHandler property on the HTTP service or the individual HTTP listener.

To set the proxyHandler property on all HTTP/HTTPS listeners, use the following command:


asadmin set cluster-name-config.http-service.property.proxyHandler=classname

To set it on an individual listener, use the following command:


asadmin set cluster-name-config.http-service.http-listener.listener-name.property.proxyHandler=classname

The rewrite-location Property

If set to true, the rewrite-location property rewrites the original request information and includes the protocol (HTTP or HTTPS), host, and port information By default, the rewrite-location property is set to true to maintain backward compatibility with previous Enterprise Server releases.

The rewrite-location property is not available through the asadmin create-http-lb-config. To use the property, use the asadmin set command as follows:

asadmin set domain.lb-configs.load-balancer-config.property.rewrite-location=false

Set the rewrite-location property with the following points in mind:

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 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 GlassFish Enterprise Server v2.1.1 Developer’s Guide.