13/17

# 8 Configuring HTTP Load Balancing

This chapter describes how to configure HTTP load balancing on GlassFish Server 3.1.2.

The following topics are addressed here:

- How the HTTP Load Balancer Works

- Setting Up HTTP Load Balancing

- Configuring the HTTP Load Balancer

- Monitoring the GlassFish Loadbalancer Plug-In

For information on other types of load balancing, see Configuring Java Message Service High Availability and RMI-IIOP Load Balancing and Failover.

## How the HTTP Load Balancer Works

This section discusses using the GlassFish Loadbalancer Plug-In.

The load balancer attempts to evenly distribute the workload among multiple instances (either standalone 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 more information, see Configuring High Availability Session Persistence and Failover.

The following topics are addressed here:

- Installing the Loadbalancer Plug-In

- HTTP Load Balancing Algorithm

- Features of the GlassFish Loadbalancer Plug-In

### Installing the Loadbalancer Plug-In

The GlassFish Loadbalancer Plug-In is available for separate download for customers who are using Oracle GlassFish Server 3.1.2. Note that the Loadbalancer Plug-In is not available for GlassFish Server Open Source Edition 3.1.2.

The Plug-In is installed by means of a graphical GlassFish Loadbalancer Configurator. The Configurator automatically configures most of settings that are required to use the Loadbalancer Plug-In with your web server. However, depending on your particular web server, there may be some manual configuration procedures that you need to perform before or after you run the Configurator.

For complete instructions on installing the Loadbalancer Plug-In, see Configuring Web Servers for HTTP Load Balancing.

### HTTP Load Balancing Algorithm

The HTTP 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 Loadbalancer Plug-In, it is forwarded to an instance based on a simple round robin scheme. If the request is for a session-based application, and a new session is created, then subsequent requests that are part of the same session are considered to be 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 Loadbalancer Plug-In uses the following methods to determine session stickiness:

- Cookie Method

  The Loadbalancer 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. To implement explicit URL rewriting, the application developer must use `HttpResponse.encodeURL()` and `encodeRedirectURL()` calls to ensure that any URLs in the application have the session information appended to them.

From the sticky information, the Loadbalancer Plug-In first determines the instance to which the request was previously forwarded. If that instance is found to be healthy, the Loadbalancer Plug-In forwards the request to that specific instance. If the instance is unavailable, a new instance is chosen and the subsequence requests are routed to the new instance.

### Features of the GlassFish Loadbalancer Plug-In

The load balancer provides increased flexibility and ease-of-use through the following features:

- Auto Apply

- Weighted Round Robin

- User-Defined Load Balancing

#### Auto Apply

GlassFish Server enables changes made to a configuration through the Administration Console or from the command line with the `apply-http-lb-changes` subcommand to be automatically sent over the wire to the web server configuration directory.

#### Weighted Round Robin

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.

#### User-Defined Load Balancing

GlassFish Server enables administrators to define custom policies for distributing HTTP requests. A custom policy defines the load balancing algorithm that the Loadbalancer Plug-In must use. In other words, an administrator can define which instance will handle an HTTP request. To use this feature, the administrator needs to develop a shared library, which must implement an interface called `loadbalancer.h`. The shared library 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 `loadbalancer.h` interface is available in webserver-install-dir`/glassfish-lbplugin/lib/install/templates`. A sample implementation, named `roundrobin.c`, is provided in this same directory. Administrators can use `roundrobin.c` as a template to build custom shared libraries.

##### To Build the Sample User-Defined Load Balancing Algorithm on Solaris

Build the `roundrobin.c` sample on Solaris using one of the following compilers:

- The `gcc` compiler.

  Enter the following command on a single line.

      % gcc -m64 -shared -Iwebserver-install-dir/glassfish-lbplugin/lib/install/templates roundrobin.c -o roundrobin.so

  If you get relocation errors, add the `-fPIC` option after the `-shared` option.

- The `cc` compiler, version 4.0.4 or later

  Enter the following command on a single line.

      % cc -m64 -G -Iwebserver-install-dir/glassfish-lbplugin/lib/install/templates roundrobin.c -o roundrobin.so

  If you get relocation errors, add the `-xcode=pic32` option after the `-G` option.

##### To Build the Sample User-Defined Load Balancing Algorithm on Windows

Build the `roundrobin.c` sample on Windows using MSVC++ 2008 Express Edition, available at `http://www.microsoft.com/express/download/`. Before compiling the sample, ensure that the system environment variables related to MSVC are set:

- `INCLUDE=`msvc-install-dir`/VC/include`

- `LIB=`msvc-install-dir`/VC/lib;`microsoft-sdk-lib-dir

Additonally, ensure that the `PATH` system environment variable includes these directories:

- msvc-install-dir`/VC/bin`

- msvc-install-dir`/Common7/IDE`

To compile the sample, enter the following command on a single line.

    D:\> cl /D_WINDOWS /Iwebserver-install-dir/glassfish-lbplugin/lib/install/templates /LD roundrobin.c

## Setting Up HTTP Load Balancing

This section describes how to set up load balancing for GlassFish Server.

The following topics are addressed here:

- Prerequisites for Setting Up HTTP Load Balancing

- Procedure for Setting Up HTTP Load Balancing

- HTTP Load Balancer Deployments

### Prerequisites for Setting Up HTTP Load Balancing

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 Configuring Web Servers for HTTP Load Balancing.

- Install the Loadbalancer Plug-In.

  For complete instructions on installing the Loadbalancer Plug-In, see Configuring Web Servers for HTTP Load Balancing.

- Create GlassFish Server clusters or server instances to participate in load balancing.

- Deploy applications to these clusters or instances.

### Procedure for Setting Up HTTP Load Balancing

There are several `asadmin` subcommands that enable you to set up and use HTTP load balancing in your GlassFish Server and web server environment.

#### To Set Up Load Balancing Using the `asadmin` Tool

Most of the required load balancing configuration settings can be performed in a single step with the `asadmin create-http-lb` subcommand, as described in this procedure. After performing this procedure, or if you choose to not perform all configuration steps with one subcommand, you can set individual load balancing options using several other subcommands. Information about configuring individual load balancing options is provided after this procedure, in Configuring the HTTP Load Balancer.

1. Create and configure a load balancer.

   Use the `asadmin create-http-lb` subcommand.

   For the purposes of this procedure, the `create-http-lb` subcommand can be used to perform the following load balancing tasks. Other options are available but are not included in this example. For more information, see `create-http-lb`.

   - Specify a target cluster or standalone server instance for the load balancer to manage (`--target`). This task can also be performed at a later time with the `create-http-lb-ref` subcommand.

   - Enable (activate) load balancing on the specified target (`--lbenableallinstances`). This task can also be performed at a later time with the `enable-http-lb-server` subcommand. Note that load balancing is enabled by default for all instances.

   - Enable load balancing for the applications that run on the specified target. The applications must already be deployed and enabled for use on the clusters or standalone instances that the load balancer references (`--lbenableallapplications`). This task can also be performed at a later time with the `enable-http-lb-application` subcommand. Note that load balancing is enabled by default for all applications.

   - Create a health checker for the load balancer. A health checker monitors unhealthy server instances so that when they become healthy again, the load balancer can send new requests to them (`--healthcheckerurl`). This task can also be performed at a later time with the `create-http-health-checker` subcommand.

   - Generate a load balancer configuration file. This file can be used with the Loadbalancer Plug-In and exported to other targets. (load_balancer_name). This task can also be performed at a later time with the `export-http-lb-config` subcommand.

2. Copy the load balancer configuration file to your web server `config` directory where the Loadbalancer Plug-In configuration files are stored.

   Note:

   To generate the load balancer configuration file and send the data over the wire to the web server in a single step, you need to configure the web server for SSL setup and import the DAS certificate. The load balancer configuration file can then be pushed using the `apply-http-lb-changes` subcommand. For information on configuring web servers for HTTP load balancing, see Configuring Web Servers for HTTP Load Balancing.

Example 8-1 Creating a Load Balancer

The following example creates a load balancer on a host named `host1` using port `5555`. A cluster named `c1` is the target. A healthchecker is enabled for the load balancer, and a load balancer configuration file named `mylb` is generated. The following command should be entered on a single line.

    asadmin> create-http-lb --devicehost host1 --deviceport 55555 --target c1
    --healthcheckerinterval 10 mylb

### HTTP Load Balancer Deployments

You can configure your load balancer in different ways, depending on your goals and environment, as described in the following sections:

- Using Clustered Server Instances

- Using Multiple Standalone Instances

#### Using Clustered Server Instances

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.

Note:

Requests cannot be load balanced across clusters and standalone instances.

#### Using Multiple Standalone Instances

It is also possible to configure your load balancer to use multiple standalone instances, and load balance and failover requests between them. However, in this configuration, you must manually ensure that the standalone 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.

Tip:

Load balancing across multiple standalone instances only provides failover for requests, and any associated HTTP session data will not be failed over. This is another reason why using a cluster, which can provide session failover, is a more desirable load balancing configuration.

## Configuring the HTTP Load Balancer

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.

- Configuring an HTTP Load Balancer on the DAS

- Creating an HTTP Load Balancer Reference

- Enabling Server Instances for HTTP Load Balancing

- Enabling Applications for HTTP Load Balancing

- Creating the HTTP Health Checker

- Changing the HTTP Load Balancer Configuration

- Disabling (Quiescing) a Server Instance or Cluster

- Disabling (Quiescing) an Application

- Configuring HTTP and HTTPS Failover

- Using Redirects with the HTTP Load Balancer

- Configuring Idempotent URLs

### Configuring an HTTP Load Balancer on the DAS

You can create a load balancer configuration on the DAS using the `asadmin create-http-lb` subcommand . See Setting Up HTTP Load Balancing for instructions. Refer to `create-http-lb`(1) for complete information about the options for this subcommand.

### 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 target servers and clusters the load balancer controls. If you created the load balancer configuration with a target, that target is already added as a reference.

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

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

### Enabling Server Instances for HTTP Load Balancing

After creating a reference to the server instance or cluster, enable the server instance or cluster using the `asadmin enable-http-lb-server` subcommand. If you specified a server instance or cluster as the target when you created the load balancer configuration, load balancing is enabled for that target by default. Refer to `enable-http-lb-server`(1) for complete information about the options for this subcommand.

### 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), load balancing is enabled for the application by default. 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.

Use the `asadmin enable-http-lb-application` subcommand to enable load balancing for one or more applications. Refer to `enable-http-lb-application`(1) complete information about the options for this subcommand.

### Creating the HTTP Health Checker

The load balancer's health checker periodically checks all the configured GlassFish 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.

The following topics are addressed here:

- Creating a Health Checker

- Additional Health Check Properties for Healthy Instances

#### Creating a Health Checker

To specify the health checker properties use the `asadmin create-http-health-checker` subcommand. 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.

Use the `delete-http-health-checker` subcommand to delete health checkers.

Refer to `create-http-health-checker`(1) and `delete-http-health-checker`(1) for complete information about the options for these subcommands.

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

To check healthy instances, set the following properties in `loadbalancer.xml`.

Table 8-1 Manual Health-Checker Properties in `loadbalancer.xml`

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

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

Alternatively, you can generate the load balancer configuration file and send the data over the wire to the web server in a single step. For more information, see To Export the Load Balancer Configuration Using the `apply-http-lb-changes` Subcommand.

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

The following topics are addressed here:

- Exporting the HTTP Load Balancer Configuration File

- Enabling Dynamic Reconfiguration

#### Exporting the HTTP Load Balancer Configuration File

The Loadbalancer Plug-In that is available for Oracle GlassFish Server 3.1.2 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. To do this, use the `asadmin export-http-lb-config` subcommand.

Alternatively, you can use the `apply-http-lb-changes` subcommand to generate the load balancer configuration file and send the data over the wire to the web server in a single step.

The following topics are addressed here:

- To Export the Load Balancer Configuration Using the `export-http-lb-config` Subcommand

- To Export the Load Balancer Configuration Using the `apply-http-lb-changes` Subcommand

##### To Export the Load Balancer Configuration Using the `export-http-lb-config` Subcommand

Follow this procedure.

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

   Refer to `export-http-lb-config`(1) for complete information about the options for this subcommand.

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

   For example, for the Oracle iPlanet Web Server, that location usually is web-server-instance-dir`/config` .

   Note:

   The load balancer configuration file in the web server's configuration directory must be named `loadbalancer.xml`.

##### To Export the Load Balancer Configuration Using the `apply-http-lb-changes` Subcommand

This procedure explains how to generate the load balancer configuration file and send the data over the wire to the web server in a single step.

1. Configure the web server for SSL setup and import the DAS certificate.

   See Configuring Web Servers for HTTP Load Balancing for configuration instructions for your particular web server.

2. Use the `apply-http-lb-changes` subcommand to generate and push the load balancer configuration file to the web server.

   See `apply-http-lb-changes`(1) for complete subcommand usage instructions.

#### Enabling Dynamic Reconfiguration

With dynamic reconfiguration, the Loadbalancer Plug-In periodically checks for an updated configuration.

##### To Enable Dynamic Reconfiguration

Follow this procedure.

1. When creating a load balancer configuration, use the `--reloadinterval` option with the `create-http-lb` subcommand.

   This option sets the amount of time between checks for changes to the load balancer `loadbalancer.xml` configuration file. By default, dynamic reconfiguration is enabled, with a reload interval of 60 seconds. Refer to `create-http-lb`(1) for complete information about this subcommand.

2. If you have previously disabled the `--reloadinterval` option, 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.

   For example:

   1. Determine the configuration name for your load balancer.

      In this case, the load balancer configuration name is `mylb`.

          asadmin> get load-balancers.load-balancer.mylb.lb-config-name
          load-balancers.load-balancer.mylb.lb-config-name=mylb_LB_CONFIG
          Command get executed successfully.

   2. Next, change the reload interval.

      Enter the following command on a single line:

          asadmin> set
          lb-configs.lb-config.mylb_LB_CONFIG.reload-poll-interval-in-seconds=30
          Command set executed successfully.

   Note:

   If `--reloadinterval` is set to `0`, then any updates to `load-balancer.xml` are not picked up. In this case, dynamic changes can only be pushed by using the `apply-http-lb-changes` subcommand. See To Export the Load Balancer Configuration Using the `apply-http-lb-changes` Subcommand.

   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 Oracle iPlanet Web Server is in 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:

- If an instance (either standalone 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.

#### To Quiesce 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 the `asadmin export-http-lb-config` command.

3. Copy the exported configuration to the web server's `config` directory.

   Alternatively, to export the load balancer configuration file and send the data over the wire to the web server in a single step, you can configure the web server for SSL setup and import the DAS certificate. The load balancer configuration file can then be pushed using the `apply-http-lb-changes` subcommand. For information on configuring web servers for HTTP load balancing, see Configuring Web Servers for HTTP Load Balancing.

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:

- If the timeout has not expired, the load balancer does not forward new requests to the application, but returns them from the web server itself. 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.

#### To Quiesce an Application

1. Use the `asadmin disable-http-lb-application` subcommand.

   Specify the following options:

   - Timeout (in minutes)

   - Name of the application to disable

   - Target cluster or instance on which to disable application

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

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

   Alternatively, to export the load balancer configuration file and send the data over the wire to the web server in a single step, you can configure the web server for SSL setup and import the DAS certificate. The load balancer configuration file can then be pushed using the `apply-http-lb-changes` subcommand. For information on configuring web servers for HTTP load balancing, see Configuring Web Servers for HTTP Load Balancing.

### Configuring HTTP and HTTPS Failover

The Loadbalancer 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 Loadbalancer Plug-In to enable HTTP/HTTPS routing and session failover.

The following topics are addressed here:

- HTTPS Routing

- Configuring HTTPS Routing

- Known Issues

#### HTTPS Routing

The Loadbalancer 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 Loadbalancer 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 Loadbalancer 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 for the `create-http-lb` subcommand 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:

Note the following limitations:

- For HTTPS routing to work, one or more HTTPS listeners must be configured.

- If `--httpsrouting` is set to `true`, and a new or a sticky request comes in where there are no healthy HTTPS listeners in the cluster, then that request generates an error.

#### Known Issues

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

- In cases where a web browser does not share cookies between HTTP and HTTPS requests, 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 cookies associated with the HTTPS session are not returned by the browser. The browser interprets the two different protocols as two different servers, and initiates a new session. This limitation only exists if `--httpsrouting` is set to true and the client web browser does not share cookies between HTTP and HTTPS requests.

- If a session has a combination of HTTP and HTTPS requests, then the 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 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`. This limitation is due to redirection, and nonstandard ports cannot be handled correctly.

### 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 GlassFish 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 settings affect redirects: the `auth-pass-through-enabled` attribute of an HTTP type protocol, the `proxyHandler` property of the HTTP service, and the `rewrite-location` property in the `loadbalancer.xml` file.

#### The `auth-pass-through-enabled` Attribute

When the GlassFish Server `auth-pass-through-enabled` attribute 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 type network listeners using custom request headers. The `auth-pass-through-enabled` attribute 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 GlassFish Server instance.

Caution:

Set `auth-pass-through-enabled` to true only if the GlassFish Server is behind a firewall.

Use the `asadmin set` command to set the `auth-pass-through-enabled` attribute on an HTTP type protocol, which is referenced by an HTTP type network listener. Be sure to enter this command on a single line.

    asadmin> set cluster-name-config.network-config.protocols.protocol-name.http.auth-pass-through-enabled=true

#### The `proxyHandler` Property

The proxy handler for the GlassFish 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 `auth-pass-through-enabled` 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 globally at the HTTP service level 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.

Note:

If the `proxyHandler` property is not set and the `auth-pass-through-enabled` attribute is set to true, then the default implementation that works with the Loadbalancer Plug-In is enabled.

The proxy handler for the GlassFish 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 `auth-pass-through-enabled` 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.

    asadmin> set cluster-name-config.http-service.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 GlassFish Server releases.

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

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

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

- If `httpsrouting` is false and `auth-pass-through-enabled` is not enabled on the GlassFish Server, set the `rewrite-location` property to true. When `auth-pass-through-enabled` is not enabled, the GlassFish 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 `auth-pass-through-enabled` is enabled on the GlassFish Server, then `rewrite-location` can be set to true or false because the GlassFish Server is aware of whether the client request is HTTP or HTTPS. When `auth-pass-through-enabled` is enabled, the GlassFish 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 GlassFish 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` property to false.

### 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 request must 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 Oracle GlassFish Server Application Development Guide.

## Monitoring the GlassFish Loadbalancer Plug-In

- Configuring Log Messages

- Types of Log Messages

- Enabling HTTP Load Balancer Logging

- Understanding Monitoring Messages

### Configuring Log Messages

The Loadbalancer Plug-In uses the web server's logging mechanism to write log messages. The default log level is set to the default logging level on Sun Java System Web Server (`INFO`), Apache Web Server (`WARN`) and Microsoft IIS `(INFO)`. The 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 Loadbalancer Plug-In generates the following types of log messages:

- Load Balancer Configurator Log Messages

- Request Dispatch and Runtime Log Messages

- Configurator Error 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:

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

#### Request Dispatch and Runtime Log Messages

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

- An output for standard logging for each method start 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>`

#### Configurator Error Messages

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://oracle.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

### Enabling HTTP Load Balancer Logging

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

Note:

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

#### To Turn on HTTP Load Balancer Logging

1. Set the logging options in the web server. The procedure depends on the web server:

   - With Oracle iPlanet Web Server

     In the server's Admin console, go to the `Magnus Editor` tab and set the `Log Verbose` option to `On`.

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

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

   Use the `asadmin create-http-lb-config` subcommand 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.

### Understanding Monitoring Messages

The format of the Loadbalancer 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.oracle.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.oracle.com/Webapps-simple/servlet/Example1 http://austen:2222 18

  Note:

  In the `RequestExit` message, response-time indicates the total request turnaround time in milliseconds, from the perspective of the Loadbalancer 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.oracle.com/Apps/servlet/SessionTest \
      16dfdac3c7e80a40 http://austen:4044 http://austen:4045