Proxying Requests to a WebLogic Cluster

 

The following sections discuss how to proxy HTTP requests to a cluster of WebLogic Servers:

• Overview

• New Version of the HttpClusterServlet

• Setting Up the HttpClusterServlet

• Sample Deployment Descriptors

• Verifying Your Configuration

 

---

Overview

The HttpClusterServlet provided with WebLogic Server proxies requests from a WebLogic Server acting as an HTTP server to server instances in a WebLogic Server cluster. The HttpClusterServlet provides load balancing and failover for the proxied HTTP requests. For additional information on servlets and clustering, see Understanding HTTP Session State Replication.

To proxy requests to a single server instance rather than to a cluster, use the HttpProxyServlet. For more information, see Proxying Requests to Another HTTP Server.

 

---

New Version of the HttpClusterServlet

A new version of the HttpClusterServlet was introduced in WebLogic Server 6.1 SP02. The older version is still available, but it is deprecated and will be removed from a future release. Differences between the older version and the new version are described in this document.

The WebLogic Server 6.1 SP02 HttpClusterServlet has the following features:

• Supports HTTP 1.1, including chunk-transfer and keep-alive.

• Uses connection pooling to improve performance.

• Uses a new set of parameters to define functionality. These parameters are the same as the parameters used for the Apache, Netscape, and Microsoft IIS plug-ins packaged with WebLogic Server.

• Uses a new Java package name. The full class name is: weblogic.servlet.proxy.HttpClusterServlet.

 

---

Setting Up the HttpClusterServlet

To use the HTTP Cluster Servlet, configure it as the default web application on your proxy server machine, as described in the steps below. For an introduction to web applications, see "Overview of Web Applications" in Assembling and Configuring Web Applications.

1. If you have not already done so, configure a separate, non-clustered Managed Server to host the HTTP Cluster Servlet.

2. If you have not already done so, create a directory for the web application, and a WEB-INF subdirectory within the web application directory. For more information, see "Directory Structure" in Assembling and Configuring Web Applications.

3. Create the web.xml deployment descriptor file for the servlet, under the WEB-INF directory of the Web application. Use any text editor. Sample deployment descriptors for the new and deprecated versions of the proxy servlet are provided in Sample Deployment Descriptors. For comprehensive instructions on writing a web.xml file, see "Writing Web Application Deployment Descriptors" in Assembling and Configuring Web Applications.

   1. Define the name and class for the servlet in the <servlet> element in web.xml. The servlet name is HttpClusterServlet for both versions of the servlet.

      The new servlet class is weblogic.servlet.proxy.HttpClusterServlet.The deprecated servlet class is weblogic.servlet.internal.HttpClusterServlet.

   2. Identify the clustered server instances to which the proxy servlet will direct requests in the <servlet> element in web.xml.

      If you are using the new version of HttpClusterServlet, define the WebLogicCluster parameter.

      If you are using the deprecated version of HttpClusterServlet, define the serverlist parameter.

   3. Create <servlet-mapping> stanzas to specify the the requests that the servlet will proxy to the cluster, using the <url-pattern> element to identify specific file extensions, for example *.jsp, or *.html. Defining each pattern in a separate <servlet-mapping> stanza.

      You can set the <url-pattern> to "/" to proxy any request that cannot be resolved by WebLogic Server to the remote server instance. If you do so, you must also specifically map the following extensions: *.jsp, *.html, and *.html, to proxy files ending with those extensions. For an example, see web.xml for HttpClusterServlet SP02.

   4. Define, as appropriate, any additional parameters as described in "Parameters for Web Server Plug-ins"in Using WebLogic Server with Plug-ins. Follow the syntax instructions in Syntax. See also Cluster Configuration and Proxy Plug-ins.

   5. Define, as appropriate, cluster configuration parameters that affect the behavior of HttpClusterServlet. For more information, see Cluster Configuration and Proxy Plug-ins.

4. In the Administration Console, assign the servlet as the default Web Application for the Managed Server on your proxy server machine. For instructions, see Designating a Default Web Application.

5. In the Administration Console, deploy the servlet to the Managed Server on your proxy server machine. For instructions, see Deploying Web Application Components.

 

---

Sample Deployment Descriptors

The subsections that follow contain sample deployments descriptor files (web.xml) for use with the new and deprecated versions of HttpClusterServlet.

Each sample web.xml defines a set of parameters that specify the location and behavior of the HTTP Cluster Servlet.

In both versions of the servlet:

• The DOCTYPE stanza specifies the DTD used by WebLogic Server to validate web.xml.

• The servlet stanza:

  • Specifies the location of the proxy plug-in servlet class. The file is located in the weblogic.jar in your WL_HOME/server/lib directory. You do not have to specify the servlet's full directory path in web.xml because weblogic.jar is put in your CLASSPATH when you start WebLogic Server.

  • Identifies the host name and list port of each Managed Servers in the cluster, using the WebLogicCluster parameter in the SP02 and later version, and the defaultServers parameter for deprecated version.

• The three servlet-mapping stanzas specify that the servlet will proxy URLs that end in '/', 'htm', 'html', or 'jsp' to the cluster.

web.xml for HttpClusterServlet SP02

This listing before is a sample web.xml for the HttpClusterServlet provided with WebLogic Server 6.1 SP02 and later. For parameter definitions see Proxy Servlet Deployment Parameters.

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.
//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>

<servlet>
   <servlet-name>HttpClusterServlet</servlet-name>
       <servlet-class>
           weblogic.servlet.proxy.HttpClusterServlet
       </servlet-class>

   <init-param>
       <param-name>WebLogicCluster</param-name>
       <param-value>
             myserver1:7736|myserver2:7736|myserver:7736
       </param-value>
   </init-param>

</servlet>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>/</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>*.jsp</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>*.htm</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>*.html</url-pattern>
</servlet-mapping>

</web-app>

web.xml for Deprecated HttpClusterServlet

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.
//DTD Web Application 2.2//EN"
"http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>

<servlet>
   <servlet-name>HttpClusterServlet</servlet-name>
       <servlet-class>
           weblogic.servlet.internal.HttpClusterServlet
       </servlet-class>

   <init-param>
       <param-name>defaultServers</param-name>
       <param-value>
             myserver1:7736:7737|myserver2:7736:7737|myserver:7736:7737
       </param-value>
   </init-param>

</servlet>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>/</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>*.jsp</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>*.htm</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>HttpClusterServlet</servlet-name>
   <url-pattern>*.html</url-pattern>
</servlet-mapping>

</web-app>

Proxy Servlet Deployment Parameters

Key parameters for configuring the behavior of the current version of the proxy servlet are listed in Table  10-1. Parameters for the deprecated proxy servlet are listed in Table  10-2.

Prior to WebLogic Server 6.1 SP02, the proxy servlet behavior was configured with its own parameter set. In SP02 and later, the parameters for the proxy servlet are renamed to match the those used to configure WebLogic Server plug-ins (for Apache, Microsoft, and Netscape web servers. For a complete list of parameters for configuring the proxy servlet and the plug-ins for third-party web servers see Parameters for Web Server Plug-ins.

The "Deprecated Equivalent" column of Table  10-1 lists the (deprecated) parameter that used for the previous version of the proxy servlet.

Syntax

The syntax for specifying the parameters, and the file where they are specified, is different for the proxy servlet and for each of the plug-ins.

For the proxy servlet, specify the parameters in web.xml, each in its own <init-param> stanza within the <servlet> stanza of web.xml. For example:

<init-param>
<param-name>ParameterName</param-name>
<param-value>ParameterValue</param-value>
</init-param>

Table 10-1 WLS 6.1 SP02 Proxy Servlet Deployment Parameters

Parameter in WLS 6.1 SP02 and Later	Usage	Deprecated Equivalent
WebLogicCluster	<init-param> <param-name>WebLogicCluster</param-name> <param-value>WLS1.com:port|WLS2.com:port </param-value> Where WLS1.com and WLS2.com are the host names of servers in the cluster, and port is a port where the host is listening for HTTP requests. If you are using SSL between the plug-in and WebLogic Server, set the port number to the SSL listen port (see Configuring the Listen Port) and set the SecureProxy parameter to ON.	defaultServers
SecureProxy	<init-param> <param-name>SecureProxy</param-name> <param-value>ParameterValue</param-value> </init-param> Valid values are ON and OFF. If you are using SSL between the plug-in and WebLogic Server, set the port number to the SSL listen port and set the SecureProxy parameter to ON.	secureProxy
DebugConfigInfo	<init-param> <param-name>Debug</param-name> <param-value>ParameterValue</param-value> </init-param> Valid values are ON and OFF. If set to ON, you can query the HttpClusterServlet for debugging information by adding a request parameter of ?__WebLogicBridgeConfig to any request. (Note: There are two underscore ( _ ) characters after the ?.) For security reasons, it is recommended that you set the DebugConfigInfo parameter to OFF in a production environment.	DebugConfig Info
ConnectRetry Secs	Interval in seconds that the the servlet will sleep between attempts to connect to a server instance. Assign a value less than ConnectTimeoutSecs. The number of connection attempts the servlet makes before returning an HTTP 503/Service Unavailable response to the client is ConnectTimeoutSecs divided by ConnectRetrySecs. Syntax: <init-param> <param-name>ConnectRetrySecs</param-name> <param-value>ParameterValue</param-value> </init-param>	numOfRetries
ConnectTimeout Secs	Maximum time in seconds that the servlet will attempt to connect to a server instance. Assign a value greater than ConnectRetrySecs. If ConnectTimeoutSecs expires before a successful connection, an HTTP 503/Service Unavailable response is sent to the client. Syntax: <init-param> <param-name>ConnectTimeoutSecs</param-name> <param-value>ParameterValue</param-value> </init-param>	connection Timeout
PathTrim	String trimmed by the plug-in from the beginning of the original URL, before the request is forwarded to the cluster. Syntax: <init-param> <param-name>PathTrim</param-name> <param-value>ParameterValue</param-value> </init-param> Example: If the URL http://myWeb.server.com/weblogic/foo is passed to the plug-in for parsing and if PathTrim has been set to /weblogic the URL forwarded to WebLogic Server is: http://myWeb.server.com:7001/foo	pathTrim
TrimExt	The file extension to be trimmed from the end of the URL. Syntax: <init-param> <param-name>TrimExt</param-name> <param-value>ParameterValue</param-value> </init-param>	trimExt
clientCertProxy	Specifies to trust client certificates in the WL-Proxy-Client-Cert header. Valid values are true and false. The default value is false. This setting is useful if user authentication is performed on the proxy server—setting clientCertProxy to true causes the proxy server to pass on the certs to the cluster in a special header, WL-Proxy-Client-Cert. The WL-Proxy-Client-Cert header can be used by any client with direct access to WebLogic Server. WebLogic Server takes the certificate information from that header, trusting that is came from a secure source (the plug-in) and uses that information to authenticate the user. If you set clientCertProxy to true, use a connection filter to ensure that WebLogic Server accepts connections only from the machine on which the plug-in is running. See "Filtering Network Connections" in Programming WebLogic Security.
PathPrepend	String that the servlet prepends to the original URL, after PathTrim is trimmed, before forwarding the URL to the cluster. <init-param> <param-name>PathPrepend</param-name> <param-value>ParameterValue</param-value> </init-param>	pathPrepend

Table 10-2 Parameters for Deprecated Proxy Servlet

Parameter Name	Parameter Value	Default
defaultServers	List of host names and associated plain and SSL listen ports for the Managed Servers in the cluster, separated by the | character. For example: host1:port:SSLport| host2:port:SSLport If you set the secureProxy parameter to ON , the HTTPS port uses SSL between the proxy server and the clustered servers. You must define the SSL ports, even if secureProxy is OFF.	None
secureProxy	ON/OFF. If set to ON, enables SSL between the HttpClusterServlet and the member of a WebLogic Server cluster.	OFF
DebugConfigInfo	ON/OFF. If set to ON, you can query the HttpClusterServlet for debugging information by adding a request parameter of ?__WebLogicBridgeConfig to any request. (Note: There are two underscore ( _ ) characters after the ?.) For security reasons, it is recommended that you set the DebugConfigInfo parameter to OFF in a production environment.	OFF
connectionTimeout	The amount of time, in seconds, that a socket waits in between reading chunks of data. If the timeout expires, a java.io.InterruptedIOException is thrown	0 = infinite timeout.
numOfRetries	Number of times HttpClusterServlet will attempt to retry a failed connection.	5
pathTrim	String to be trimmed from the beginning of the original URL.	None
trimExt	The file extension to be trimmed from the end of the URL.	None
pathPrepend	String to be prepended to the beginning of the original URL, after pathTrim has been trimmed, and before the request is forwarded to a WebLogic Server cluster member.	None

Cluster Configuration and Proxy Plug-ins

Two WebLogic Server configuration attributes can be set at the cluster level to control the behavior of the HttpClusterServlet.

• WeblogicPluginEnabled—If you set this attribute to true for a cluster that receives requests from the HttpClusterServlet, the servlet will respond to getRemoteAddr calls with the address of the browser client from the proprietary WL-Proxy-Client-IP header, instead of returning the web server address.

• ClientCertProxy Enabled—If you set this attribute to true for a cluster that receives requests from HttpClusterServlet, the plug-in sends client certs to the cluster in the special WL-Proxy-Client-Cert header, allowing user authentication to be performed on the proxy server.

For more information see help for the Cluster -->Configuration-->General page in Administration Console Online Help.

 

---

Verifying Your Configuration

To verify that your configuration of the HttpClusterServlet is functioning correctly:

1. Set the DebugConfigInfo parameter in web.xml to ON.

2. Use a Web browser to access the following URL:

   http://myServer:port/placeholder.jsp?__WebLogicBridgeConfig

   Where:

   myServer is the Managed Server on the proxy machine where HttpClusterServlet runs,

   port is the port number on that server that is listening for HTTP requests, and

   placeholder.jsp is a file that does not exist on the server.

   The plug-in gathers configuration information and run-time statistics and returns the information to the browser. For more information, see DebugConfigInfo.