Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Enterprise Edition 8 2004Q4 Beta Administration Guide 

Chapter 4
Configuring Load Balancing and Failover

This chapter describes how to set up load balancing of HTTP requests in the Sun Java System Application Server. It also explains how to configure failover between server instances controlled by the load balancer. In addition, it discusses RMI-IIOP load balancing and Failover.

It contains the following sections:

About HTTP Load Balancing and Failover

HTTP Load Balancing and Failover

The goal of load balancing is to evenly distribute the workload between multiple Sun Java System Application Server instances, standalone or clustered, thereby increasing the overall throughput of the system. Using a load balancer also enables requests to fail over from one server instance to another.

Use the asadmin tool, not the Admin Console to configure HTTP load balancing.

Requirements for HTTP Load Balancing

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

Load balancing configuration is extremely flexible:

Understanding Assigned Requests and Unassigned Requests

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

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

HTTP Load Balancing Algorithm

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

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

About the Sticky Round Robin Load Balancing Algorithm

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

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

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

Cookie-Based Method

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

Note

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

Explicit URL Rewriting Method

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

Overview of HTTP Load Balancing Setup

Use the asadmin tool to configure load balancing in your environment. Follow these steps:

  1. Complete the "Requirements for HTTP Load Balancing", including installing and configuring a web server and clustered instances.
  2. Create a load balancer configuration using the asadmin command create-http-lb-config.
  3. Add references to clusters and standalone server instances for the load balancer to manage using asadmin create-http-lb-ref.
  4. Enable the clusters or standalone server instances reference by the load balancer using asadmin enable-http-lb-server.
  5. Enable applications for load balancing using asadmin enable-http-lb-application.

    6. These applications must already be deployed and enabled for use on the clusters or standalone instances that the load balancer references. Enabling for load balancing is a separate step from enabling them for use.

  6. Create a health checker using asadmin create-health-checker.

    7. The health checker monitors unhealthy server instances so that when they become healthy again, the load balancer can send new requests to them.

  7. Generate the load balancer configuration file using asadmin export-http-lb-config.

    8. This command generates a configuration file to use with the load balancer plug-in shipped with the Sun Java System Application Server.

  8. Copy the load balancer configuration file to your web server config directory where the load balancer plug-in configuration files are stored.

For more information on these topics, see the Administration Guide.

Configuring Web Servers for HTTP Load Balancing

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

Modifications to Sun ONE Web Server

The installation program makes the following changes to the Sun ONE Web Server's configuration files:

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

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

    Init fn="init-passthrough"

    ##end addition for EE lb-plugin

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

    3. <Object name=default>

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

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

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

After installing, configure the load balancer as described in "Overview of HTTP Load Balancing Setup".

Modifications to Apache Web Server

Before installing the load balancer plug-in on Apache, see information on compiling and configuring Apache in Appendix A, "Compiling and Configuring Apache Web Server."

The load balancer plug-in installation program extracts the necessary files to the libexec (Apache 1.3) or modules (Apache 2.0) folder under the web server's root directory. It adds the following entries specific to the load balancer plug-in to the web server instance's httpd.conf file:

<VirtualHost machine_name:443>

##Addition for EE lb-plugin

LoadFile /usr/lib/libCstd.so.1

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

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

##END EE LB Plugin ParametersVersion 7

Note

  • Apache web server must be run in secure mode to ensure that it works well with the load balancer plug-in.
  • Create a directory called sec_db_files under apache_install_dir and copy <S1AS_installables_dir/sec_db_files/* to apache_install_dir/sec_db_files.
  • On Apache 1.3, when more than one Apache child processes runs, each process has its own load balancing round robin sequence.

    For example, if there are two Apache child processes running, and the load balancing plug-in load balances on to two application server instances, the first request is sent to instance #1 and the second request is also sent to instance #1. The third request is sent to instance #2 and the fourth request is sent to instance #2 again. This pattern is repeated (instance1, instance1, instance2, instance2, etc.)

    This behavior is different from what you might expect, that is, instance1, instance2, instance1, instance2, etc. In Sun Java System Application Server, the load balancing plug-in for Apache instantiates a load balancer instance for each Apache process, creating an independent load balancing sequence.
  • Apache 2.0 has multithreaded behavior if compiled with the --with-mpm=worker option.

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

Modifications to Microsoft IIS

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

Make these modifications after installing the Sun Java System Application Server.

  1. Open the Internet Services Manager.
  2. Select the web site for which you want to enable the plug-in. This web site is typically named the Default Web Site.
  3. Right click on the web site and select Properties to open the Properties notebook.
  4. To add a new ISAPI filter, open the ISAPI Filters tab, click Add, and follow the steps given below:
    1. In the Filter Name field, enter Application Server
    2. In the Executable field, type C:\Inetpub\wwwroot\sun-passthrough\sun-passthrough.dll
    3. Click OK, and close the Properties notebook.
  5. Create and configure a new virtual directory:
    1. Right click on the default web site, select New, and then Virtual Directory.

      2. The Virtual Directory Creation Wizard opens.

    2. In the Alias field, type sun-passthrough.
    3. In the Directory field, type C:\Inetpub\wwwroot\sun-passthrough
    4. Check the Execute Permission checkbox. Leave all other permission-related check boxes are left unchecked.
    5. Click Finish.
  6. Add the path of sun-passthrough.dll file and application_server_install_dir/bin to the system's PATH environment variable.
  7. Stop and start the web server for the new settings to take effect.

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

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

    http://webserver_name/web_application

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

The installer automatically configures the following properties in sun-passthrough.properties. You can change the default values.

Table 4-1 Automatically configured sun-passthrough.properties for Microsoft IIS

Property

Definition

Default Value

lb-config-file

Path to the load balancer configuration file

IIS_www_root\sun-passthrough\loadbalancer.xml

log-file

Path to the load balancer log file

IIS_www_root\sun-passthrough\lb.log

log-level

Log level for the web server

INFO

Configuring Multiple Web Server Instances

The Sun Java System Application Server installer doesn't 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.

  1. Configure the new web server instance to use the load balancer plug-in, as described in "Modifications to Sun ONE Web Server", "Modifications to Apache Web Server", or "Modifications to Microsoft IIS".
  2. Copy the sun-loadbalancer_1_1.dtd file from the existing web server instance's config directory to the new instance's config directory.
  3. To use the same load balancer configuration, copy the loadbalancer.xml file from the existing web server instance's config directory to the new instance's config directory.
  4. To use a different load balancer configuration:
    1. Create a new load balancer configuration using asadmin create-http-lb-config.
    2. Export your new configuration to a loadbalancer.xml file using asadmin export http-lb-config.
    3. Copy that loadbalancer.xml file to the new web server's config directory.

      4. For information on creating a load balancer configuration and exporting it to a loadbalancer.xml file, see "HTTP Load Balancer Configuration Tasks."

HTTP Load Balancer Configuration Tasks

Creating an HTTP Load Balancer Configuration

A load balancer configuration is a named configuration in the domain.xml file that defines a load balancer. Create it using the asadmin command create-http-lb-config. Specify the following parameters:

For more information see the documentation for create-http-lb-config, delete-http-lb-config, and list-http-lb-configs.

Creating an HTTP Load Balancer Reference

When you create a reference in the load balancer to a standalone server or cluster, the server or cluster is added to the list of 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.

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

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 enble-http-lb-application.

Disabling (Quiescing) a Server Instance or Cluster

Before you stop 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:

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

The load balancer uses the following policy for quiescing applications:

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.

To disable an application:

  1. Run asadmin disable-http-lb-application, specifying the timeout (in minutes) the name of the application to disable, and the 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.

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.

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

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.

Exporting the Load Balancer Configuration File

The load balancing 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 your load balancing environment, you must export it to a file:

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

    2. You export the loadbalancer.xml file for a particular load balancer configuration. You can specify a path and a different file name; the default file name is loadbalancer.xml. If you specify a path on Windows, you must use quotes around the path, for example, "c:\sun\AppServer\loadbalancer.xml".

  2. Copy the exported load balancer configuration file to the location of the load balancer plug-in's configuration files.

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

Changing Your HTTP Load Balancer Configuration

If you change your HTTP load balancer configuration by creating or deleting references to servers, enabling or disabling servers or applications, and so on, you must export your 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

When dynamic reconfiguration is enable, the load balancer plug-in periodically checks for an updated configuration. To enable dynamic reconfiguration:

Once you have changed these settings, export your load balancer configuration file again and copy it to your web server's config directory.

If you enable dynamic reconfiguration after it has previously been disabled, you also must restart the web server.

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 ONE Web Server' is at: web_server_install_dir/webserver_instance/logs/.

Configuring HTTP/S Session 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.

The following topics are discussed in this section:

About HTTPS Routing

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

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

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

Configuring HTTPS Routing

The 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. You can set it to true when you create a new load balancer configuration, or change it later using the asadmin set command.

Note

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

Known Issues in Load Balancing HTTP/HTTPS Requests

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

Configuring Idempotent URLs

To enhance the availability of deployed applications, configure your 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.

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.

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 the Developer's Guide.

Configuring HTML Error Pages

You can specify your own error page or a URL to an error page to be displayed to the end user. Specifying an error page, overrides all other mechanisms configured for error reporting.

Configure HTML error pages in the sun-web.xml file. When you export the load balancer configuration, HTML error page information is automatically added to the loadbalancer.xml file from the sun-web.xml file.

For more information on configuring HTML error pages, see the Developer's Guide.

Monitoring the HTTP Load Balancer Plug-in

Configuring Log Messages

The load balancer plug-in uses the web server's logging mechanism to write log messages. The default log level on the Application Server is set to the default logging level on Sun ONE 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.

Types of Log Messages

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

Load Balancer Configurator 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:

An output for error page URL configuration contains the following information:

CONFxxxx: Invalid error-url for web-module <web-module>

Request Dispatch and Runtime Log Messages

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

Configurator Error Messages

These errors appear if there are configuration problems, for example, if the custom error page referenced is missing.

Configuring Monitoring

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

  1. Set the logging options in the web server.
    1. From Sun ONE Web Server's admin console, go to the Magnus Editor tab.

      2. Set the Log Verbose option to On.

    2. For Apache Web Server, set the log level to DEBUG.
    3. For Microsoft IIS, set the log level to FINE in the sun-passthrough.properties file.
  2. Set the load balancer configuration's monitor option to true.

    3. 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 load balancer plug-in logs the following information:

Understanding Monitoring Messages

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

About RMI-IIOP Load Balancing and Failover

Requirements for RMI-IIOP Load Balancing and Failover

Sun Java™ System Application Server provides high availability of remote EJB references and name service objects over RMI-IIOP. Before you can use these features, your environment must meet the following requirements:

RMI-IIOP Failover Algorithm

Sun Java System Application Server employs a randomization and round-robin algorithm for load balancing of remote EJB references and name service objects on the RMI-IIOP path.

When an RMI-IIOP client first creates a new InitialContext object, the list of available Application Server IIOP endpoints is randomized for that client. For that InitialContext object, the load balancer directs lookup requests and other InitialContext operations to the first endpoint on the list. If the first endpoint is not available then the second endpoint in the list is used, and so on.

Each time the client subsequently creates a new InitialContext object, the endpoint list is rotated so that a different IIOP endpoint is used for InitialContext operations.

When you obtain or create beans from references obtained by an InitialContext object, those beans are created on the Application Server instance serving the IIOP endpoint assigned to the InitialContext object. The references to those beans contain the IIOP endpoint addresses of all Application Server instances in the cluster.

The primary endpoint is the bean endpoint corresponding to the InitialContext endpoint used to look up or create the bean. The other IIOP endpoints in the cluster are designated as alternate endpoints. If the bean's primary endpoint becomes unavailable, further requests on that bean fail over to one of the alternate endpoints.



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.