This chapter describes the HTTP load balancer plug-in. It includes the following topics:
For information on other types of load balancing, see Chapter 10, Java Message Service Load Balancing and Failoverand Chapter 11, RMI-IIOP Load Balancing and Failover.
This section discusses using the HTTP load balancing plug-in included with the Application Server. Another HTTP load balancing option is to use the Sun Secure Application Switch with the Application Server for a hardware-based load balancing solution. For a tutorial on configuring this solution, see the article Clustering and Securing Web Applications: A Tutorial.
In Sun Java System Application Server 9.1, the functionality of the load balancer is enhanced to provide increased flexibility and ease-of-use through the following features.
Application Server allows changes to the load balancer configuration made from the Admin Console to be automatically sent over the wire to the Web Server configuration directory. With previous versions of Application Server, the load balancer configuration had to be exported and then copied over to the web server configuration directory.
The load balancer enables improved distribution of HTTP requests. The administrator can use an attribute called 'weight' to specify how requests will be proportionately routed to an instance. For example, suppose a cluster has two instances, and the administrator has assigned a weight of 100 to instance x and a weight of 400 to instance y. Now, for every 100 requests, 20 will go to instance x and 80 will go to instance y.
Application Server enables the administrator to define a custom policy for distributing HTTP requests. A custom policy defines the load balancing algorithm that the load balancer plug-in must use. In other words, the Administrator can define which Application Server instance will handle an HTTP request. To use this feature, the administrator needs to develop a shared library, which can, for example, be used to evaluate the headers of incoming requests provided to it and in accordance to some criteria, select the instance that can serve the request. This shared library would be loaded by the load balancer.
The shared library must implement an interface as defined in loadbalancer.h, which is available under appserver_install_dir/lib/install/templates.
Application Server also bundles a sample module roundrobin.c that implements the basic round robin algorithm. The administrator can use this sample module as a template to build the shared library. This sample module is also available under appserver_install_dir/lib/install/templates.
Copy roundrobin.c from appserver_install_dir/lib/install/templates to a work directory (for example:/home/user/workspacelb).
Compile roundrobin.c with an ANSI C/C++ compiler (for example Sun Studio compiler or GCC). Be sure to build a dynamic shared library and not a static executable.
If you are using Sun Studio CC Compiler, use the following command to compile:
cc -G -I<appserver install dir>/lib/install/templates roundrobin.c -o roundrobin.so
If you are using GCC, compile the shared library with this command:
gcc -shared -I<appserver install dir>/lib/install/templates roundrobin.c -o roundrobin.so
If you encounter a relocation error, compile again using the option "-fPIC." The command will look like this:
gcc -shared -fPIC -I <appserver install dir>/lib/install/templates roundrobin.c -o roundrobin.so
On Microsoft Windows, download the Cygwin utility from http://www.redhat.com/services/custom/cygwin. This utility has GCC bundled with it. Use the following GCC command to create a dynamic link library (dll):
gcc -shared -I<appserver_install_dir>/lib/install/templates roundrobin.c -o roundrobin.dll
Change loadbalancer.xmlto point to the newly built module. This is how loadbalancer.xml will look after the edit.
<cluster name="cluster1" policy="user-defined" policy-module="home/user/workspacelb/roundrobin.so">
Copy roundrobin.so to the web server instance directory.
Start the web server if it is not running or wait till the load balancer is re-configured.
The load balancer attempts to evenly distribute the workload among multiple Application Server instances (either stand-alone or clustered), thereby increasing the overall throughput of the system.
The HTTP Load Balancer enables high availability of services deployed on Java EE Application Servers. While doing so, it fails over a session request to another server instance if the original servicing instance is detected to be unavailable or unhealthy to service a request. For HTTP session information to persist, you must be using the Cluster profile, have installed and set up the HADB, and configured HTTP session persistence. For more information, see Chapter 9, Configuring High Availability Session Persistence and Failover.
The load balancer does not handle URI/URLs that are greater than 8k.
The Sun Java System Application Server load balancer, by default, uses a sticky round robin algorithm to load balance incoming HTTP and HTTPS requests.
When a new HTTP request is sent to the load balancer plug-in, it is forwarded to an application server instance based on a simple round robin scheme. If the request is for a session-based application, then this also includes a request for a new session. Subsequent requests from the same client for the same session-based application are considered assigned or sticky requests and are routed by the load balancer to the same instance. Hence, the name sticky round robin. Requests to a non session-based application and the first request for a session-based application are called unassigned requests. Stickiness is achieved by using cookies, or explicit URL rewriting. The load balancer determines the method of stickiness automatically.
The load balancer plug-in uses the following methods to determine session stickiness:
Cookie Method: the load balancer plug-in uses a separate cookie to record the route information. The HTTP client (typically, the web browser) must support cookies to use the cookie based method. If the HTTP client is unable to accept cookies, the plug-in uses the following method.
Explicit URL Rewriting: the sticky information is appended to the URL. This method works even if the HTTP client does not support cookies.
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.
This section describes how to set up the load balancer plug-in and includes the following sections:
Before configuring your load balancer, you must:
Install a supported web server and configure it. For more information on configuring a supported web server, see Chapter 4, Configuring Web Servers for Load Balancing.
Install the load balancer plug-in.
For information on the installation procedure, see Sun Java System Application Server 9.1 Installation Guide.
Create Application Server clusters or server instances to participate in load balancing.
Deploy applications to these clusters or instances.
If you have a deployment scenario where the Application Server instances and the load balancer are installed on different network domains, then you must create the node agent by specifying the fully qualified domain name using the option, --agentproperties. For example, asadmin create-node-agent --agentproperties remoteclientaddress=machine1.server.example.com test-na. For more information about this command, see create-node-agent(1).
Use the Admin Console GUI or the asadmin tool to configure load balancing in your environment. The following sections provide you more information.
Create a load balancer configuration.
In the Admin Console, on the left frame, click HTTP Load Balancers and then click New. In the New HTTP Load Balancer page, provide the device details and also select the target cluster or instances.
Add a reference to a cluster or stand-alone server instance for the load balancer to manage.
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. Open the Targets tab, click Manage Targets and in the Manage Targets page, select the required target.
If you created the load balancer configuration with a target, and that target is the only cluster or stand-alone server instance the load balancer references, skip this step.
Enable the cluster or stand-alone server instance referenced by the load balancer.
To enable a stand-alone server instance 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 and in the Targets table, click the check box next to the instance you want to enable and click Enable.
To enable a server instance in a cluster, select the load balancer as explained above and in the Targets tab, click the desired cluster. Now open the Instances tab, select the desired instance, and from the Load Balancer Actions drop down list, select Enable Load Balancing.
The equivalent command to enable a cluster or a stand-alone instance is asadmin enable-http-lb-server.
Enable applications for load balancing.
To do this using the Admin Console, 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.
These applications must already be deployed and enabled for use on the clusters or stand-alone instances that the load balancer references. Enabling applications for load balancing is a separate step from enabling them for use.
Create a health checker.
To do this using the Admin Console, open the Targets tab for the load balancer as mentioned in the previous step and in the Targets table, click Edit Health Checker.
The health checker monitors unhealthy server instances so that when they become healthy again, the load balancer can send new requests to them.
If you are using Sun Java System Web Server (6.1 or 7.0), instead of performing steps 6 and 7, you can generate the load balancer configuration file and send the data over the wire to the Web Server in a single step.
To do this using the Admin Console, click the desired load balancer and then open the Export tab. In this tab, click Apply Changes Now. This sends the data to the Web Server configuration directory.
Generate the load balancer configuration file.
To do this using the Admin Console, click the load balancer and then open the Export tab. In this tab, click Export Now.
This command generates a configuration file to use with the load balancer plug-in shipped with the Sun Java System Application Server.
Copy the load balancer configuration file to your web server config directory where the load balancer plug-in configuration files are stored.
To generate the load balancer configuration file automatically and send the data over the wire to the Web Server in a single step, you need to configure Web server for SSL setup and import the DAS certificate. For information on configuring Sun Java System Web Server, see Configuring Sun Java System Web Server.
Create a load balancer configuration.
To do this, use the command, asadmin create-http-lb-config.
You can perform all the following steps (Step 2 through Step 7) using a single asadmin command, create-http-lb and its options. For more information about this command, see create-http-lb(1).
Add a reference to a cluster or stand-alone server instance for the load balancer to manage.
To do this, use the command, asadmin create-http-lb-ref. For more information about this command, see create-http-lb-ref(1).
If you created the load balancer configuration with a target, and that target is the only cluster or stand-alone server instance the load balancer references, skip this step.
Enable the cluster or stand-alone server instance referenced by the load balancer.
To do this, use the command asadmin enable-http-lb-server. For more information about this command, see enable-http-lb-server(1).
Enable applications for load balancing.
To do this, use the command asadmin enable-http-lb-application. For more information about this command, see enable-http-lb-application(1).
These applications must already be deployed and enabled for use on the clusters or stand-alone instances that the load balancer references. Enabling applications for load balancing is a separate step from enabling them for use.
Create a health checker.
To do this, use the command, asadmin create-http-health-checker. For more information about this command, see create-http-health-checker(1).
The health checker monitors unhealthy server instances so that when they become healthy again, the load balancer can send new requests to them.
If you are using Sun Java System Web Server (6.1 or 7.0), instead of performing steps 6 and 7, you can generate the load balancer configuration file and send the data over the wire to the Web Server in a single step.
To do this using the asadmin tool, set the --autoapplyenabled option of the create-http-lb command to true. For more information about this command, see create-http-lb(1).
Generate the load balancer configuration file.
To do this, use the command asadmin export-http-lb-config. For more information about this command, see export-http-lb-config(1). This command generates a configuration file to use with the load balancer plug-in shipped with the Sun Java System Application Server.
Copy the load balancer configuration file to your web server config directory where the load balancer plug-in configuration files are stored.
To generate the load balancer configuration file automatically and send the data over the wire to the Web Server in a single step, you need to configure Web server for SSL setup and import the DAS certificate. For information on configuring Sun Java System Web Server, see Configuring Sun Java System Web Server.
You can configure your load balancer in different ways, depending on your goals and environment, as described in the following sections:
The most common way to deploy the load balancer is with a cluster or clusters of server instances. By default all the instances in a cluster have the same configuration and the same applications deployed to them. The load balancer distributes the workload between the server instances and requests fail over from an unhealthy instance to a healthy one. If you’ve configured HTTP session persistence, session information persists when the request is failed over.
If you have multiple clusters, requests can be load balanced across clusters but are only failed over between the instances in a single cluster. Use multiple clusters in a load balancer to easily enable rolling upgrades of applications. For more information, see Upgrading Applications Without Loss of Availability.
Requests cannot be load balanced across clusters and stand-alone instances.
It is also possible to configure your load balancer to use multiple stand-alone instances, and load balance and failover requests between them. However, in this configuration, you must manually ensure that the stand-alone instances have homogenous environments and the same applications deployed to them. Because clusters automatically maintain a homogenous environment, for most situations it is better and easier to use clusters.
Load balancer configuration is maintained in the domain.xml file. Configuring a load balancer is extremely flexible:
A load balancer services only one domain, though a domain can have multiple load balancers associated with it.
Each load balancer configuration can have multiple load balancers associated with it, though each load balancer has only one load balancer configuration.
These sections describe, in more detail, how to create, modify, and use a load balancer configuration:
In Application Server 9.1, 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 create-http-lb, delete-http-lb, and list-http-lbs, see Sun Java System Application Server 9.1 Reference Manual.
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. See Sun Java System Application Server 9.1 Reference Manual for more information on the commands, 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. |
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 on these commands, see Sun Java System Application Server 9.1 Reference Manual.
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 on this command, see enable-http-lb-server(1).
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, see enable-http-lb-application(1).
If you deploy a new application, you must also enable it for load balancing and export the load balancer configuration again.
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 will not be able to determine when an unhealthy instance becomes healthy.
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.
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.
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 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 about the commands, see create-http-health-checker(1) and delete-http-health-checker(1).
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.
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 |
---|---|
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, the newly exported configuration won’t contain these properties. You must add these properties again to the newly exported configuration.
The load balancer plug-in available with Sun Java System Application 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.
Navigate to the HTTP Load Balancers node and expand it.
Click the desired load balancer.
All the load balancer configuration details are displayed in the General, Settings and Target tabs.
Open the Export tab and click Export now.
Copy the exported load balancer configuration file to the web server’s configuration directory.
Export a loadbalancer.xml file using the asadmin command export-http-lb-config. For more information on the command, see export-http-lb-config(1).
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" .
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.
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.
With dynamic reconfiguration, the load balancer plug-in periodically checks for an updated configuration.
To enable dynamic reconfiguration:
When creating a load balancer configuration, use the --reloadinterval option with asadmin create-http-lb. For more information on the command, see create-http-lb(1).
This option sets the amount of time between checks for changes to the load balancer configuration file loadbalancer.xml. A value of 0 disables dynamic reconfiguration. By default, dynamic reconfiguration is enabled, with a reload interval of 60 seconds.
If you have previously disabled it, or to change the reload interval, use the asadmin set command.
After changing the reload interval, export the load balancer configuration file again and copy it to the web server’s config directory, then restart the web server.
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/.
Before stopping an application 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 application server instances:
If an instance (either stand-alone or part of a cluster) is disabled, and the timeout has not expired, sticky requests continue to be delivered to that instance. New requests, however, are not sent to the disabled instance.
When the timeout expires, the instance is disabled. All open connections from the load balancer to the instance are closed. The load balancer does not send any requests to this instance, even if all sessions sticking to this instance were not invalidated. Instead, the load balancer fails over sticky requests to another healthy instance.
Run asadmin disable-http-lb-server, setting the timeout (in minutes). For more information on the command, see disable-http-lb-server(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the exported configuration to the web server config directory.
Stop the server instance or instances.
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:
If the timeout has not expired, the load balancer does not forward new requests to the application, but returns them to the web server. However, the load balancer continues to forward sticky requests until the timeout expires.
When the timeout expires, the load balancer does not accept any requests for the application, including sticky requests.
When you disable an application from every server instance or cluster the load balancer references, the users of the disabled application experience loss of service until the application is enabled again. If you disable the application from one server instance or cluster while keeping it enabled in another server instance or cluster, users can still access the application. For more information, see Upgrading Applications Without Loss of Availability.
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.
For more information on the command, see disable-http-lb-application(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the exported configuration to the web server config directory.
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.
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 an 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.
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.
For HTTPS routing to work, one or more HTTPS listeners must be 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.
The Load Balancer has the following limitations with HTTP/HTTPS request processing.
If a session uses a combination of HTTP and HTTPS requests, then the first request must be an 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 httpsrouting is set to true.
If a session has a combination of HTTP and HTTPS requests, then the application server instance must be configured with both HTTP and HTTPS listeners. This limitation is valid only if httpsrouting is set to true.
If a session has a combination of HTTP and HTTPS requests, then the application server instance must be configured with HTTP and HTTPS listeners that use standard port numbers, that is, 80 for HTTP, and 443 for HTTPS. This limitation applies regardless of the value set for httpsrouting.
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 Application 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.
When the Application 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 Application Server instance.
Set authPassthroughEnabled to true only if the Application 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 proxy handler for the Application 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 Application Server, and for making this information available to the web application (deployed on the Application Server) 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 on the Application Server 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 Application 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 Application Server reads and parses the SSL certificate chain from the request header. This allows a back-end application server 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 Application Server 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
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 Application Server releases.
The rewrite-location property is not available through the asadmin create-http-lb-config or asadmin set commands. To use the property, manually add it to the loadbalancer.xml file after exporting your load balancer configuration. For example, add the following to the exported loadbalancer.xml file:
<property name="rewrite-location" value="false"/>
Set the rewrite-location property with the following points in mind:
If httpsrouting is false and authPassthroughEnabled is not enabled on the Application Server, set the rewrite-location property to true. When authPassthroughEnabled is not enabled, the Application Server will not be aware of the protocol (HTTP or HTTPS) of the original request. By setting rewrite-location to true the load balancer modifies the protocol part of the rewrite location suitably. That is, if the client is sending HTTPS requests, then the load balancer redirects the client to a HTTPS-enabled listener port on the load balancer. The process is the same for HTTP requests.
If httpsrouting is false, and authPassthroughEnabled is enabled on the Application Server, then rewrite-location can be set to true or false because the Application Server is aware of whether the client request is HTTP or HTTPS. When authPassthroughEnabled is enabled, the Application Server modifies the protocol part of rewrite location suitably. If rewrite-location is set to false, the load balancer does not rewrite the location of the redirected URL. If set to true, it rewrites the location of the redirected URL. But this rewrite is not needed as the Application Server was aware of HTTPS connections from the client. Also, if the application needs to redirect HTTP to HTTPS or HTTPS to HTTP, you must set the rewrite-location parameter to false.
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 9.1 Developer’s Guide.
The Sun Java System Application Server installer does not allow the installation of multiple load balancer plug-ins on a single machine. 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.
Configure the new web server instance to use the load balancer plug-in.
For detailed instructions, see Configuring Sun Java System Web Server.
Copy the DTD file sun-loadbalancer_1_1.dtd from the existing web server instance’s config directory to the new instance’s config directory.
Set up the load balancer configuration file. Either:
Copy the existing load balancer configuration.
Use an existing load balancer configuration, copy the loadbalancer.xml file from the existing web server instance’s config directory to the new instance’s config directory.
Create a new load balancer configuration:
Use asadmin create-http-lb-config to create a new load balancer configuration.
Export the new configuration to a loadbalancer.xml file using asadmin export http-lb-config.
Copy that loadbalancer.xml file to the new web server’s config directory.
For information on creating a load balancer configuration and exporting it to a loadbalancer.xml file, see Configuring an HTTP Load Balancer on the DAS
Upgrading an application to a new version without loss of availability to users is called a rolling upgrade. Carefully managing the two versions of the application across the upgrade ensures that current users of the application complete their tasks without interruption, while new users transparently get the new version of the application. With a rolling upgrade, users are unaware that the upgrade occurs.
Rolling upgrades pose varying degrees of difficulty depending on the magnitude of changes between the two application versions.
If the changes are superficial, for example, changes to static text and images, the two versions of the application are compatible and can both run at once in the same cluster.
Compatible applications must:
Use the same session information
Use compatible database schemas
Have generally compatible application-level business logic
Use the same physical data source
You can perform a rolling upgrade of a compatible application in either a single cluster or multiple clusters. For more information, see Upgrading In a Single Cluster.
If the two versions of an application do not meet all the above criteria, then the applications are considered incompatible. Executing incompatible versions of an application in one cluster can corrupt application data and cause session failover to not function correctly. The problems depend on the type and extent of the incompatibility. It is good practice to upgrade an incompatible application by creating a “shadow cluster” to which to deploy the new version and slowly quiesce the old cluster and application. For more information, see Upgrading Incompatible Applications.
The application developer and administrator are the best people to determine whether application versions are compatible. If in doubt, assume that the versions are incompatible, since this is the safest approach.
You can perform a rolling upgrade of an application deployed to a single cluster, providing the cluster’s configuration is not shared with any other cluster.
Save an old version of the application or back up the domain.
To back up the domain use the asadmin backup-domain command. For more information on the command, see backup-domain(1).
Turn off dynamic reconfiguration (if enabled) for the cluster.
To do this with Admin Console:
Expand the Configurations node.
Click the name of the cluster’s configuration.
On the Configuration System Properties page, uncheck the Dynamic Reconfiguration Enabled box.
Click Save
Alternatively, use this command:
asadmin set --user user --passwordfile password-file cluster-name-config.dynamic-reconfiguration-enabled=false
Redeploy the upgraded application to the target domain.
If you redeploy using the Admin Console, the domain is automatically the target. If you use asadmin, specify the target domain. Because dynamic reconfiguration is disabled, the old application continues to run on the cluster.
Enable the redeployed application for the instances using asadmin enable-http-lb-application. For more information on the command, see enable-http-lb-application(1).
Quiesce one server instance in the cluster from the load balancer.
Follow these steps:
Disable the server instance using asadmin disable-http-lb-server.For more information on the command, see disable-http-lb-server(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the exported configuration file to the web server instance’s configuration directory.
For example, for Sun Java System Web Server, the location is web-server-install-dir/https-host-name/config/loadbalancer.xml. To ensure that the load balancer loads the new configuration file, be sure that dynamic reconfiguration is enabled by setting the reloadinterval in the load balancer configuration.
Wait until the timeout has expired.
Monitor the load balancer’s log file to make sure the instance is offline. If users see a retry URL, skip the quiescing period and restart the server immediately.
Restart the disabled server instance while the other instances in the cluster are still running.
Restarting causes the server to synchronize with the domain and update the application.
Test the application on the restarted server to make sure it runs correctly.
Re-enable the server instance in load balancer.
Follow these steps:
Enable the server instance using asadmin enable-http-lb-server. For more information on the command, see enable-http-lb-server(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the configuration file to the web server’s configuration directory.
Repeat steps 5 through 8 for each instance in the cluster.
When all server instances have the new application and are running, you can enable dynamic reconfiguration for the cluster again.
Save an old version of the application or back up the domain.
To back up the domain, use the asadmin backup-domain command. For more information on the command, see backup-domain(1).
Turn off dynamic reconfiguration (if enabled) for all clusters.
To do this with Admin Console:
Expand the Configurations node.
Click the name of one cluster’s configuration.
On the Configuration System Properties page, uncheck the Dynamic Reconfiguration Enabled box.
Click Save
Repeat for the other clusters
Alternatively, use this command:
asadmin set --user user --passwordfile password-file cluster-name-config.dynamic-reconfiguration-enabled=false
Redeploy the upgraded application to the target domain.
If you redeploy using the Admin Console, the domain is automatically the target. If you use asadmin, specify the target domain. Because dynamic reconfiguration is disabled, the old application continues to run on the clusters.
Enable the redeployed application for the clusters using asadmin enable-http-lb-application. For more information on the command, see enable-http-lb-application(1).
Quiesce one cluster from the load balancer
Disable the cluster using asadmin disable-http-lb-server. For more information on the command, see disable-http-lb-server(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the exported configuration file to the web server instance’s configuration directory.
For example, for Sun Java System Web Server, the location is web-server-install-dir/https-host-name/config/loadbalancer.xml. Dynamic reconfiguration must be enabled for the load balancer (by setting the reloadinterval in the load balancer configuration), so that the new load balancer configuration file is loaded automatically.
Wait until the timeout has expired.
Monitor the load balancer’s log file to make sure the instance is offline. If users see a retry URL, skip the quiescing period and restart the server immediately.
Restart the disabled cluster while the other clusters are still running.
Restarting causes the cluster to synchronize with the domain and update the application.
Test the application on the restarted cluster to make sure it runs correctly.
Enable the cluster in the load balancer:
Enable the cluster using asadmin enable-http-lb-server. For more information on the command, see enable-http-lb-server(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the configuration file to the web server’s configuration directory.
Repeat steps 5 through 8 for the other clusters.
When all server instances have the new application and are running, you can enable dynamic reconfiguration for all clusters again.
If the new version of the application is incompatible with the old version, use the following procedure. For information on what makes applications compatible, see Application Compatibility. Also, you must upgrade incompatible application in two or more clusters. If you have only one cluster, create a “shadow cluster” for the upgrade, as described below.
When upgrading an incompatible application:
Give the new version of the application a different name from the old version of the application. The steps below assume that the application is renamed.
If the data schemas are incompatible, use different physical data sources after planning for data migration.
Deploy the new version to a different cluster from the cluster where the old version is deployed.
Set an appropriately long timeout for the cluster running the old application before you take it offline, because the requests for the application won’t fail over to the new cluster. These user sessions will simply fail.
Save an old version of the application or back up the domain.
To back up the domain use the asadmin backup-domain command. For more information on the command, see backup-domain(1).
Create a “shadow cluster” on the same or a different set of machines as the existing cluster. If you already have a second cluster, skip this step.
Use the Admin Console to create the new cluster and reference the existing cluster’s named configuration.
Customize the ports for the new instances on each machine to avoid conflict with existing active ports.
For all resources associated with the cluster, add a resource reference to the newly created cluster using asadmin create-resource-ref. For more information on the command, see create-resource-ref(1).
Create a reference to all other applications deployed to the cluster (except the current redeployed application) from the newly created cluster using asadmin create-application-ref. For more information on the command, see create-application-ref(1).
Configure the cluster to be highly available using asadmin configure-ha-cluster. For more information on the command, see configure-ha-cluster(1).
Create reference to the newly-created cluster in the load balancer configuration file using asadmin create-http-lb-ref. For more information on the command, see create-http-lb-ref(1).
Give the new version of application a different name from the old version.
Deploy the new application with the new cluster as the target. Use a different context root or roots.
Enable the deployed new application for the clusters using asadmin enable-http-lb-application. For more information on the command, see enable-http-lb-application(1).
Start the new cluster while the other cluster is still running.
The start causes the cluster to synchronize with the domain and be updated with the new application.
Test the application on the new cluster to make sure it runs correctly.
Disable the old cluster from the load balancer using asadmin disable-http-lb-server. For more information on the command, see disable-http-lb-server(1).
Set a timeout for how long lingering sessions survive.
Enable the new cluster from the load balancer using asadmin enable-http-lb-server. For more information on the command, see enable-http-lb-server(1).
Export the load balancer configuration file using asadmin export-http-lb-config. For more information on the command, see export-http-lb-config(1).
Copy the exported configuration file to the web server instance’s configuration directory.
For example, for Sun Java System Web Server, the location is web-server-install-dir/https-host-name/config/loadbalancer.xml. Dynamic reconfiguration must be enabled for the load balancer (by setting the reloadinterval in the load balancer configuration), so that the new load balancer configuration file is loaded automatically.
After the timeout period expires or after all users of the old application have exited, stop the old cluster and delete the old application.
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), Apache Web Server (WARN) and Microsoft IIS (INFO). 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 required metrics.
The load balancer plug-in generates the following types of log messages:
These messages will be logged when you are using idempotent URLs and error page settings.
An output for idempotent URL pattern configuration contains the following information:
When the log level is set to FINE:
CONFxxxx: IdempotentUrlPattern configured <url-pattern> <no-of-retries> for web-module : <web-module>
When the log level is set to SEVERE:
CONFxxxx: Duplicate entry of Idempotent URL element <url-pattern> for webModule <web-module> in loadbalancer.xml."
When the log level is set to WARN:
CONFxxxx: Invalid IdempotentUrlPatternData <url-pattern> for web-module <web-module>
An output for error page URL configuration contains the following information (log level set to WARN):
CONFxxxx: Invalid error-url for web-module <web-module>
These log messages are generated while a request is being load balanced and dispatched.
An output for standard logging for each method start contains the following information (log level set to FINE):
ROUTxxxx: Executing Router method <method_name>
An output for router logs for each method start contains the following information (log level set to INFO):
ROUTxxxx: Successfully Selected another ServerInstance for idempotent request <Request-URL>
An output for runtime logs contains the following information (log level set to INFO):
RNTMxxxx: Retrying Idempotent <GET/POST/HEAD> Request <Request-URL>
These errors appear if there are configuration problems, for example, if the custom error page referenced is missing.
Log level set to INFO:
ROUTxxxx: Non Idempotent Request <Request-URL> cannot be retried
For example: ROUTxxxx: Non Idempotent Request http://sun.com/addToDB?x=11&abc=2 cannot be retried
Log level set to FINE:
RNTMxxxx: Invalid / Missing Custom error-url / page: <error-url> for web-module: <web-module>
For example: RNTMxxxx: Invalid / Missing Custom error-url / page: myerror1xyz for web-module: test
The load balancer plug-in logs the following information:
Request start/stop information for every request.
Failed-over request information when the request fails over from an unhealthy instance to a healthy instance.
List of unhealthy instances at the end of every health check cycle.
When load balancer logging is enabled, 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, do not use the DEBUG or similar log level in production environments.
If you must use the DEBUG logging level, turn off load balancer logging by setting require-monitor-data property to false in loadbalancer.xml.
Set the logging options in the web server. The procedure depends on the web server:
Set the load balancer configuration’s monitor option to true.
Use the asadmin create-http-lb-config command to set monitoring to true when you initially create the load balancer configuration, or use the asadmin set command to set it to true later. Monitoring is disabled by default.
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
In the RequestExit message, response-time indicates the total request turnaround 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