10 Setting up WebLogic Clusters
6. Select Advanced
10.2.9 Configure Proxy Plug-Ins
10.2.9.1 Set 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 "Understanding Web Applications, Servlets, and JSPs" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
1. If you have not already done so, configure a separate, non-clustered Managed Server to host the HTTP Cluster Servlet.
2. Create the web.xml deployment descriptor file for the servlet. This file must reside in the \WEB-INF subdirectory of the Web application directory. A sample deployment descriptor for the proxy servlet is provided in Section 10.2.9.1.1,
"Sample web.xml." For more information on web.xml, see "Understanding Web Applications, Servlets, and JSPs" in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
a. Define the name and class for the servlet in the <servlet> element in web.xml. The servlet name is HttpClusterServlet. The servlet class is weblogic.servlet.proxy.HttpClusterServlet.
b. Identify the clustered server instances to which the proxy servlet will direct requests in the <servlet> element in web.xml, by defining the
WebLogicCluster parameter.
c. Optionally, define the following <KeyStore> initialization parameters to use two-way SSL with your own identity certificate and key. If no <KeyStore> is specified in the deployment descriptor, the proxy will assume one-way SSL.
– <KeyStore>—The key store location in your Web application.
– <KeyStoreType>—The key store type. If it is not defined, the default type will be used instead.
– <PrivateKeyAlias>—The private key alias.
– <KeyStorePasswordProperties>—A property file in your Web application that defines encrypted passwords to access the key store and private key alias. The file contents looks like this:
KeyStorePassword={AES}yWv/i0qhfM4/IvzoghzjHj/xpJUkQPF8OWuSfh0f0Ss=
Note: Each Web server that proxies requests to a cluster must have an identically configured plug-in.
You must use the weblogic.security.Encrypt command-line utility to encrypt the password. For more information on the Encrypt utility, as well as the CertGen, and der2pem utilities, see "Using the Oracle WebLogic Server Java Utilities" in the Command Reference for Oracle WebLogic Server.
d. Create <servlet-mapping> stanzas to specify 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. Define 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 Section 10.2.9.1.1, "Sample web.xml."
e. Define, as appropriate, any additional parameters. See Table 10–1 for a list of key parameters. See "Parameters for Web Server Plug-ins" in Using Web Server Plug-Ins with WebLogic Server for a complete list. Follow the syntax instructions in Section 10.2.9.1.3, "Proxy Servlet Deployment Parameters."
3. Create the weblogic.xml deployment descriptor file for the servlet. This file must reside in the \WEB-INF subdirectory of the Web application directory.
Assign the proxy servlet as the default Web application for the Managed Server on the proxy machine by setting the <context-root> element to a forward slash character (/) in the <weblogic-web-app> stanza. For an example, see
Section 10.2.9.1.2, "Sample weblogic.xml."
4. In the Administration Console, deploy the servlet to the Managed Server on your proxy server machine. For instructions, see "Deploy applications and modules" in Oracle WebLogic Server Administration Console Help.
10.2.9.1.1 Sample web.xml This section contains a sample deployment descriptor file (web.xml) for HttpClusterServlet.
web.xml defines parameters that specify the location and behavior of the proxy servlet: 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 (either DNS name or IP address) and listen port of each Managed Servers in the cluster, using the WebLogicCluster parameter.
– Identifies the key store initialization parameters to use two-way SSL with your own identity certificate and key.
■ The three servlet-mapping stanzas specify that the servlet will proxy URLs that end in '/', 'htm', 'html', or 'jsp' to the cluster.
For parameter definitions see Section 10.2.9.1.3, "Proxy Servlet Deployment Parameters."
Cluster Implementation Procedures
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.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>hostname1:7736|hostname2:7736|hostname:7736</param-value>
</init-param>
10.2.9.1.2 Sample weblogic.xml This section contains a sample weblogic.xml file. The
<context-root> deployment parameter is set to "/". This makes the proxy servlet the default Web application for the proxy server.
<!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 9.1//EN" "http://www.bea.com/servers/wls810/dtd/weblogic
810-web-jar.dtd">
<weblogic-web-app>
<context-root>/</context-root>
10.2.9.1.3 Proxy Servlet Deployment Parameters Key parameters for configuring the behavior of the proxy servlet in web.xml are listed in Table 10.1.
The parameters for the proxy servlet are the same as 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-part Web servers see "Parameters for Web Server Plug-ins" in Using Web Server Plug-Ins with WebLogic Server.
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 Proxy Servlet Deployment Parameter
Parameter Usage
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.
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 (see "Configuring the Listen Port") and set the SecureProxy parameter to ON.
DebugConfigInfo <init-param>
<param-name>DebugConfigInfo</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.
Cluster Implementation Procedures
ConnectRetrySecs Interval in seconds that 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>
ConnectTimeoutSecs 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>
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
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>
Table 10–1 (Cont.) Proxy Servlet Deployment Parameter
Parameter Usage
10.2.9.1.4 Accessing Applications Via the Proxy Server Ensure that applications clients will access via the proxy server are deployed to your cluster. Address client requests to the listen address and listen port of the proxy server.
If you have problems:
■ Make sure all servers instances have unique address/port combinations
Each of the server instances in the configuration must have a unique combination of listen address and listen port.
■ Make sure that the proxy servlet is the default application for the proxy server If you get a page not found error when you try to your application, make sure that weblogic.xml is in \WEB-INF for the application and that it sets the
context-root deployment parameter to "/".
■ When all else fails, restart
If you are having problems try rebooting all your servers, some of the changes you made while configuring your setup may not have been persisted to the
configuration file.
■ Verify Your Configuration
To verify the configuration of the HttpClusterServlet:
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.
For this reason, 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 "Using Network Connection Filters" in Programming Security for Oracle WebLogic Server.
PathPrepend String that the servlet prepends to the original URL, after PathTrim is trimmed, before forwarding the URL to the cluster.
<init-param>
Extends the proxy servlet to support Web service cluster routing. For more information, see
"Managing Web Services in a Cluster" in Programming Advanced Features of JAX-WS Web Services for Oracle WebLogic Server.
<init-param>
<param-name>RoutingHandlerClassName</param-name>
<param-value>
weblogic.wsee.jaxws.cluster.proxy.SOAPRoutingHandler </param-value>
</init-param>
Table 10–1 (Cont.) Proxy Servlet Deployment Parameter
Parameter Usage
Cluster Implementation Procedures
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 "Parameters for Web Server Plug-ins" in Using Web Server Plug-ins With WebLogic Server.