This document describes how to configure ZXTM to manage the traffic to a cluster of BEA WebLogic Servers.

It's also available as a White Paper (pdf).

Contents

• Prerequisites
• Example architecture
• Basic configuration
• Passing the client IP address
• Session persistence
• Load balancing algorithms
• SSL offload
• Traffic routing (separation of static and dynamic content)

Prerequisites

Software versions:

• ZXTM: ZXTM version 4.0 or later is required
• BEA Weblogic Server: ZXTM may be used to manage traffic to all versions of Weblogic Server. This document refers particularly to versions 8.x and 9.x.

It is assumed that the reader has followed the instructions in the ZXTM Getting Started Guide to install ZXTM on one or more machines in front of a cluster of Weblogic Servers. The installation and configuration of BEA Weblogic Server are outside the scope of this document - please refer to the Weblogic Server documentation available from edocs.bea.com for your version of BEA WebLogic.

Example Architecture

The diagram below shows a typical deployment of ZXTM with Weblogic. A pair of ZXTM servers have been installed in front of two application server clusters and a pair of web servers that serve static content.

The ZXTM servers are shown operating in active-active mode, using a pair of Traffic IP addresses (x.x.x.10 and x.x.x.20). The DNS for the sites hosted by this architecture would list two A records (one for x.x.x.10 and one for x.x.x.20) for each website hostname. Were ZXTM configured to operate in active-passive mode, only a single IP address (x.x.x.10, for example) would be required for each hostname.

Although two application server clusters have been shown here in order to demonstrate request routing, ZXTM can be deployed in front of a single cluster. Similarly, a separate web-server cluster for static content is not essential, although it is recommended in many deployments since it reduces the load on the application servers.

The examples given in the rest of this document will refer to this diagram, and will use the IP addresses specified in it.

Basic Configuration

To prepare ZXTM for load balancing traffic across a WebLogic cluster, you must perform the following tasks:

1. Create a traffic IP group
2. Create a pool for each WebLogic Server cluster, containing all the servers in the cluster
3. Create a virtual server, bound to the traffic IP group, that will listen on the appropriate port and send traffic to the pool
4. Start the virtual server

Begin by logging in to the ZXTM administration server.

Creating the Traffic IP Group

Go to Services -> Traffic IP Group, and create a new traffic IP group, containing the external IP address(es) to which the hostnames of your websites resolve. The example group is named "weblogic_example".

Creating pools

To create a new pool for your WebLogic servers, go to Services -> Pool, and enter a name for the pool. Then enter a space separated list of nodes. Each node is defined as "hostname:port" where the hostname is the hostname or IP address of the node, and the port is the number of the TCP/UDP port to which traffic should be sent (e.g. "10.10.0.56:80" or "apps-1.localdomain:443").

Finally, set the monitor to "Full HTTP", and click "Create Pool". The screenshot shows this being done for the two nodes in Apps Server Cluster A, which are listening on port 80.

Repeat this step for each pool of application servers and web servers you wish to load balance. With the example architecture, two further pools would be configured as follows:

  Pool Name: cluster_b
  Nodes    : 10.59.1.61:80 10.59.1.62:80
  Monitor  : Full HTTP

  Pool Name: web_servers
  Nodes    : 10.59.1.31:80 10.59.1.32:80
  Monitor  : Full HTTP

Creating the virtual server

Go to Services -> Virtual Servers. In the "Create a New Virtual Server" dialog, choose a name for the virtual server, set the protocol to HTTP, and the port to 80 (this is the port that ZXTM will listen on for incoming traffic). Choose a default pool to send traffic to (in the example, this has been set to the "cluster_a" pool), and click "Create Virtual Server".

Once the virtual server has been created, you must edit it to make it use the traffic IP group you created earlier. Click on the edit link to the right of the new virtual server's name. Under "Basic Settings", click the "Traffic IP Groups" radio button, and select the Traffic IP Group you've already created.

Starting the virtual server

To start the virtual server, return to the ZXTM admin server home page, and click the play icon next to your newly created virtual server:

As created, this virtual server will load balance requests across the nodes in your WebLogic cluser using a round robin algorithm. You should be able to test this by visiting one of the traffic IP addresses in your browser. You can use ZXTM's activity graph to confirm that the load balancing is happening correctly.

Note, however, that since you haven't yet enabled session persistence, applications which maintain server-side state won't work correctly. Enabling session persistence is discussed later.

Passing the Client IP address to WebLogic Server

Since ZXTM is a proxy, all requests it sends to WebLogic will appear to come from the ZXTM server's internal IP address (10.59.1.20 and 10.59.1.30 in the example). If the application needs to know the true client IP address, ZXTM can pass it to WebLogic in an extra HTTP header. For WebLogic version 6.0 and later, this header must be called "WL-Proxy-Client-IP"; for earlier versions, the header is called "X-Forwarded-For".

First, configure Weblogic to use the extra HTTP header by turning on the "Weblogic Plugin Enabled" setting in the Weblogic administration server. If you are not sure how to do this, please refer to the documentation for your version of Weblogic Server.

Having done this, create a new TrafficScript rule in ZXTM to add the extra header, and enable it in the virtual server for your Weblogic cluster as follows:

Go to Services -> Virtual Servers -> [your_weblogic_virtual_server], and click on the "Rules" link. Under "Add new request rule", click "Manage Rules in Catalog". You will be shown the "Create new rule" dialog. Give the rule a name, such as "WebLogic_plugin", select the "Use TrafficScript language" radio button, make sure that the "and associate it with ..." tickbox is ticked, and click "Create Rule".

Cut and paste the rule below that corresponds to the version of WebLogic Server you are using into the rule box, and click "Update" to create the rule.

WebLogic 6.x, 7.x, 8.x and 9.x

$client_ip = request.remoteIP();
http.setheader("WL-Proxy-Client-IP", $client_ip);

Weblogic 5.x and earlier

$client_ip = request.remoteIP();
http.setheader("X-Forwarded-For", $client_ip);

The rule will take effect immediately, and your Java applications that call HttpRequest.getRemoteAddr() will be given the true client IP address.

Enabling Session Persistence

Before most applications will work correctly, it is necessary to enable session persistence; this causes the second and subsequent requests from a client to be sent to the same back-end server as the first, which prevents server side session state being lost. More recent versions of WebLogic Server share session state automatically between servers in a cluster; with these versions, enabling session persistence increases the performance of the application by reducing the number of times session data must be replicated between machines in a cluster.

There are three different types of session persistence that are appropriate for use with WebLogic Server:

• Transparent Session Affinity. With this method, ZXTM simply inserts a cookie into the response header, and uses this cookie to ensure that future requests received from the same client are sent to the same server as the first. This method has the advantage that it is trivial to configure, but the disadvantage that the application has no control over the cookie (and so cannot unset it when the user logs out, for example).
• Monitor Application Cookie. ZXTM can be set to monitor the JSESSIONID cookie that is set by WebLogic. This has the advantage that the application retains full control of the cookie.
• URL Rewriting. Both of the previous methods rely on the client's browser supporting HTTP cookies. Since not all browsers support cookies, and some users disable cookies as a privacy measure, WebLogic Server can be configured to add the JSESSIONID to the end of URLs in links generated by the application, when it detects that the user's browser is refusing cookies. ZXTM can extract the JSESSIONID from the requested URL, and use this as its session persistence key. Persistence on rewritten URLs can be combined with Monitor Application Cookie persistence to ensure that sessions are persistent regardless of whether the clients support cookies or not.

The combination of the "Monitor Application Cookies" and "URL Rewriting" methods is recommended for general purpose use with WebLogic Server, but all three methods are documented below for reference.

When using the Monitor Application Cookies or Transparent Session Affinity methods, session persistence must be enabled for each of the pools that send traffic to WebLogic Server. In the example, therefore, it would be enabled for pools "cluster_a" and "cluster_b".

Monitor Application Cookies

Go to Services -> Pools -> [your_weblogic_pool] and click on the "Session Persistence" link. Click the "Create New Session Persistence Class" link, and create a class named "weblogic_cookie".

Set this class to "Monitor Application Cookies" and set the cookie name to "JSESSIONID".

Leave the failure mode set to "choose a new node to use". This will cause ZXTM to send the request to a different node if the persistent node isn't available; in this circumstance, the chosen Weblogic server will recover a replica of the session state from a secondary server; the end user should not notice that a failure has occurred.

As soon as you click "Update", session persistence will be enabled for this pool. You can verify that it is working by looking at the current activity graph as you browse one of the hosted websites. You should see that all the requests in a session are sent to the same backend node. The recent connections page (Activity -> Connections) can also be used to check that persistence is working correctly.

URL Rewriting Persistence

Configuring URL Rewriting Persistence is a two stage process. First, a persistence class using "Universal Session Persistence" must be created, and then two TrafficScript rules written that detect a rewritten URL, extract the JSESSIONID from it and persist on this ID.

To create the session persistence class, go to Catalogs -> Persistence and create a new class called "url_rewriting". Set this class to use the "Universal Session Persistence" method and failure mode of "choose a new node to use", and click "Update" to finish. (Note that you should not associate the url_rewriting class with any particular pool - the TrafficScript rule below will associate it with a request as and when it is required.)

Now, go to Services -> Virtual Servers -> [your_weblogic_virtual_server] -> Rules and click the "Manage Rules in Catalog" link in the "Add New Request Rule" section. Create a new TrafficScript rule called "url_rewriting_persistence", and cut and paste the following into the rule's text box, and click "Update". Note that the argument to connection.setPersistence must match the name of the persistence class you created above.

# Don't need to do this if we can persist on a cookie
$cookie = http.getCookie( "JSESSIONID" );
if( $cookie ) break; 

$url = http.getpath();
if (string.regexmatch($url, ".*;JSESSIONID=([\\w.]*).*", "i")) {
        $sessionid = $1;
        connection.setPersistence( "url_rewriting" );
        connection.setPersistenceKey( $sessionid );
}

Finally, create a new response rule. Go to Services -> Virtual Servers -> [your_weblogic_virtual_server] -> Rules and click the "Manage Rules in Catalog" link in the "Add New Response Rule" section. Create a new TrafficScript rule called "url_rewriting_response", cut and paste the following into the rule's text box, and click "Update".

# We're only interested in intercepting html responses
$contenttype = http.getResponseHeader( "Content-Type" );
if( ! string.startsWith( $contenttype, "text/html" ) ) break;

# Don't need to do this if the client accepted the cookie
$cookie = http.getCookie( "JSESSIONID" );
if( $cookie ) break; 

# Weblogic will try to set the cookie on every request, so
# even if the client rejects it we can still persist on it.
$cookie = http.getResponseCookie( "JSESSIONID" );
if ( $cookie ) {
  connection.setPersistence( "url_rewriting" );
  connection.setPersistenceKey( $cookie );
}

As mentioned above, you can safely use (and we recommend that you use) the Monitor Application Cookies and URL Rewriting methods together to ensure that session persistence works regardless of whether or not clients have cookies enabled.

If you have correctly enabled both session persistence methods, your ZXTM config summary (Services -> Config Summary) should look similar to the screenshot below (the port numbers and the names of your virtual servers and pools may vary):

Transparent Session Affinity

To enable Transparent Session Affinity, create a new session persistence class named "transparent", of type "Transparent Session Affinity", and set this as your pool's persistence class. If you haven't created any session persistence classes already, the procedure is similar to that described in Monitor Application Cookie section above. If you've already created a class, then you must create the new class from the Catalogs -> Persistence page, and then go to Services -> Pool -> [your_weblogic_pool] -> Session Persistence to set the new class as your pool's session persistence class.

Load Balancing Algorithms

By default, a newly created pool will use a simple round robin algorithm. This takes no account of the load on the back-end servers, and so it is recommended that one of the more sophisticated algorithms is used. The optimal choice will depend on the application being run. See section 5.2.1 of the ZXTM User Manual for details of each algorithm.

The perceptive algorithm is a sensible default for a typical WebLogic deployment; set it on the Services -> Pool -> [Your Weblogic Pool] -> Load Balancing page.

SSL Offload

ZXTM can decrypt SSL requests and send the resultant decrypted (plain HTTP) requests to WebLogic. This reduces the load on the WebLogic servers, and permits ZXTM's session persistence and advanced content inspection and rewriting features to be used with SSL traffic.

To enable SSL offload, you must first upload your SSL certificate and private key to ZXTM, and then configure SSL decryption for the virtual server concerned. Finally, you must add a TrafficScript rule that will tell WebLogic that the connection to the client was encrypted, so that applications can correctly test wthether or not SSL was enabled, and WebLogic can generate correct absolute links (beginning https://) where necessary.

Uploading your SSL private key and certificate to ZXTM

If you have an existing SSL private key and public certificate, you can upload these files to ZXTM from the Catalogs -> SSL -> SSL Certificates Catalog -> Import Certificate page. Simply enter a name for the certificate pair (the combination of private key and public certificate) and the paths to each of the files, as shown on the right.

If you don't have an existing SSL certificate, you can create a new private key, self-signed certificate and certificate signing request from the Catalogs -> SSL -> SSL Certificates Catalog -> Create Self Signed Certificate page. Please refer to chapter 9 of the ZXTM User Manual for details.

Configuring SSL Decryption

To enable SSL Decryption go to the virtual server configuration page for the virtual server concerned (e.g. Services -> Virtual Servers -> weblogic_example). First make sure that the port and internal protocol are correct. The internal protocol specifies the protocol after SSL decryption and so should be set to HTTP (the HTTPS protocol is used only when ZXTM is passing unencrypted SSL traffic through to the back-end nodes). The port should be set as required; 443 being the standard HTTPS port. Update the configuration if necessary.

Then click the "SSL Decryption" link. Set "ssl_decrypt" to yes, and choose an SSL certificate. Finally, click the "Update" button at the bottom of this page. Your virtual server should now be SSL enabled.

Notifying WebLogic that the connection was encrypted

Add the following rule to the virtual server. This sets the WL-Proxy-SSL header, which tells WebLogic whether or not the original connection between client and ZXTM was encrypted. It's important to explicitly remove this header when the connection isn't encrypted, so that remote clients can't trick WebLogic by adding the header themselves.

# Tell WebLogic if the connection to the client was encrypted
# and remove the Wl-Proxy-SSL header if not
if ( ssl.isSSL() ) {
        http.setheader("WL-Proxy-SSL", "true");
} else {
        http.removeheader("WL-Proxy-SSL");
}

Running both HTTP and HTTPS versions of a website

If you wish to run both an HTTP (unencrypted) and HTTPS (encrypted) version of your website, simply create two virtual servers that use the same default pool, one set to listen to port 443, with SSL Decryption enabled as described in the preceding section, and the other set to listen to port 80 with SSL decryption disabled. Remember to enable the TrafficScript rules for URL Rewriting Persistence and Client IP Address Passthrough for both virtual servers.

Traffic Routing (Separation of static and dynamic content)

You can use TrafficScript to distinguish requests for static content from those for dynamic content, sending the former to your web servers (.31 and .32 in the example architecture diagram) and the latter to one or more of your application server clusters.

The principle is straightforward - you write a TrafficScript rule that reads details of the request (usually the requested URL or Host header) and uses these to decide which pool to send the requests to. Since the precise details of the rule will vary from application to application, the following is given by way of example only. To use this rule, you would first create new pools called "cluster_b" and "static_servers", containing the WebLogic servers in Application Cluster B (10.59.1.61:80 and 10.59.1.62:80) and your static web servers (10.59.1.31:80 and 10.59.32:80) respectively. Session persistence for "cluster_b" would be enabled as for "cluster_a"; session persistence is not normally needed for static content. Then add the rule below as the final request rule for the "weblogic_example" virtual server. The comments in the rule explain which requests will be sent where.

# URLs beginning /news/ /search/ or /cart/, and those ending .jsp and .do 
# are dynamic, everything else is static.
$regex = "(/(news|search|cart)/|(.jsp|.do)$)";
$path = http.getPath();

# Send requests for anything other than dynamic content to the static cluster
if (! string.regexmatch($path, $regex)) {
    pool.use("static_servers");
}

# Split dynamic requests between the two application clusters, according 
# to the host header - requests for www.example.com and sales.example.com 
# are sent to cluster_a, all other requests to cluster_b.
$host = http.getHeader("Host");
if (string.regexmatch($host, "^(www|sales).example.com$")) {
    pool.use("cluster_a");
} else {
    # Everything else to the second application server cluster
    pool.use("cluster_b");
}

Julian [Zeus Dev Team] 30 April 2006   3 comments