Web Server Plug-ins

Let us now examine the scenario where an industry-strength web server is configured as the primary HTTP server, proxying certain client requests (usually requests for servlets and JSPs) through to WebLogic Server. WebLogic implements this configuration by providing web server plug-ins that augment the primary server with proxying logic. As mentioned in Chapter 2, a proxy plug-in enhances the web server by allowing it to delegate requests for dynamic content to WebLogic Server. Currently, WebLogic supports plug-ins for three web servers: the Apache HTTP Server, IIS, and NES.

The web server continues to serve static content, such as HTML pages, images, text files, and other web resources, and uses the plug-in to redirect requests for servlets and JSPs to WebLogic Server, which may be running on a different process, or may even be located on a different host. This internal delegation of requests for dynamic content to WebLogic Server occurs transparently. The client browser remains unaware of the existence of WebLogic Server. Configuring the proxy plug-in is a two-stage process:

1. First, the proxy plug-in has to be installed on the web server. Refer to the WebLogic documentation for more information on how to install the plug-in on your web server. After that, you need to specify the conditions under which the web server will delegate client requests to the plug-in.
2. Second, the proxy plug-in itself has to be configured. You must supply a list of name-value pairs that define the behavior of the web server plug-in.

Let us now look at some of the issues you need to consider when configuring proxy plug-ins on web servers.

3.5.1 Installing a Proxy

The rest of this section looks at how to use a proxy plug-in in general. In particular, we discuss how to configure the plug-in for the popular Apache 2.0 HTTP Server. The same configuration issues apply to proxy plug-ins for other well-known web servers. The only major change lies in how you set up the plug-ins on these servers. For instance, Apache's web server requires you to simply edit its configuration file, while Microsoft's IIS provides a GUI Console to establish the plug-in configuration. Though the exact syntax and configuration mechanism may differ, the overall intent and functionality remain unaltered. Refer to WebLogic's documentation for more information on how to install and configure the proxy plug-in on other supported web servers.

To install the proxy plug-in for Apache 2.0, you simply need to copy the proxy plug-in implementation into the modules subdirectory of your Apache installation. The Apache plug-in library is in fact included within your WebLogic installation, and is located at WL_HOME/server/bin/mod_wl_20.so. After this, you need to include the following line in the configuration file, httpd.conf:

LoadModule weblogic_module modules/mod_wl_20.so

That's it your Apache web server is now equipped with WebLogic's proxy plug-in. The same configuration file also holds any changes to the plug-in's configuration.

3.5.2 Types of Proxying

You can configure the web server to proxy requests in two ways:

Proxying by path

It can use a portion of the request URL.

Proxying by file extension

It can use the MIME type of the web resource requested.

Proxying by path involves instructing the web server to pass to WebLogic Server any requests that begin with a particular path. For instance, you could set up the Apache plug-in to proxy by path by adding the following to Apache's configuration file:

 WebLogicHost wl.oreilly.com 
 WebLogicPort 7001


 SetHandler weblogic-handler

In this case, a request URL such as http://www.servername.com/dynamic/myservlet will get passed on to WebLogic Server, which then invokes myservlet on the target web application dynamic on the host running at w1.oreilly.com:7001. Once the servlet has completed servicing the request, WebLogic Server feeds the response back to the proxy on the web server, which in turn feeds it back to the client.

Proxying by MIME type or extension involves having the web server proxy through to WebLogic Server all requests that map to a particular extension. The following example shows how to set up the Apache plug-in to proxy all requests for .jsp and .xyz through to WebLogic:

 WebLogicHost wl.oreilly.com 
 WebLogicPort 7001
 MatchExpression *.jsp
 MatchExpression *.xyz

As you would expect, requests for JSPs would go through to the server at w1.oreilly.com:7001, and WebLogic will fetch and then process the required JSP file. .xyz is an arbitrary file extension that you could use to proxy requests for servlets through to WebLogic Server. For instance, you could invoke myservlet using a URL such as http://www.servername.com/myservlet/foo.xyz.

If a request URL matches both criteria, the request is proxied by path. Later, we will examine additional parameters that you can define to customize the behavior of the web server plug-in.

3.5.3 Connection Pools and Keep-Alive Connections

The web server plug-ins support a reusable pool of HTTP connections to the WebLogic Server. The plug-in uses HTTP 1.1 keep-alive connections to the WebLogic Server behind it. It reuses the same connection from the pool for subsequent requests from the same client. You can set the duration that a connection is kept alive by setting the KeepAliveSecs parameter. By default, an inactive connection is reclaimed by the plug-in after 30 seconds and returned to the pool. You can disable this feature by setting the KeepAliveEnabled parameter to false.

3.5.4 Proxying to a Cluster

A proxy plug-in really comes into its own when it is placed before a bank of WebLogic instances. Figure 3-1 describes this scenario where incoming requests to a web server are then distributed between two WebLogic instances, Server A and Server B.

Figure 3-1. Proxying to a cluster

In this case, the plug-in not only proxies requests through, but also load-balances these requests and avoids servers that may become unavailable. Such a front-tier architecture is discussed in more detail in Chapter 14. The following configuration shows how to set up the Apache proxy plug-in when it sits in front of a WebLogic cluster:

 WebLogicCluster 10.0.10.10:7003,10.0.10.10:7005
 MatchExpression *.jsp

In this case, we have instructed the plug-in to proxy/load-balance JSP requests between two servers in a cluster, running on the same machine, 10.0.10.10, on ports 7003 and 7005.

3.5.5 Connection Failures

The web server plug-in uses the ConnectTimeoutSecs parameter to determine how long it has to wait for connections to WebLogic Server. Once connected, it uses the HungServerRecoverSecs parameter to determine how long to wait for a response from WebLogic Server. If the plug-in doesn't receive a response within the specified duration, it marks the server as dead. If the plug-in fails to connect or doesn't receive a server response, it will try connecting to another server in the cluster.

The ConnectRetrySecs parameter determines how long the plug-in sleeps before trying to connect to another member in the cluster. If no member of a WebLogic cluster responds to the connection request, the plug-in returns an HTTP 503 (Service Unavailable) error response. The number of times WebLogic tries to connect before returning a 503 response is determined by the value of (ConnectTimeoutSecs)/(ConnectRetrySecs).

3.5.6 Dynamic Server List

Even though you can specify the members of a WebLogic cluster sitting behind the web server, this list of WebLogic Servers is only a starting point. Once a request is redirected to one of the servers, a new dynamic server list is returned with an updated list of servers in the cluster. These updates occur automatically with the HTTP response as changes to the cluster occur. The updated list includes any new servers that may have joined the cluster, and removes any servers that are no longer part of the cluster or may not have responded to the web server plug-in. The plug-in then load-balances among the members of this dynamic list of servers, unless, of course, the request is sticky.

By default, the proxy plug-in automatically uses the dynamic server list for load-balancing requests among the members of the cluster. If you set the DynamicServerList parameter to OFF, the plug-in ignores any changes to the WebLogic cluster at runtime and sticks to the original static definition of the servers in the cluster.

We've already discussed how WebLogic provides HTTP session failover by keeping track of the primary server and the secondary server that replicates the session state. If the proxy fails to connect to the primary server, it attempts to connect to the secondary server. If both primary and secondary servers fail to respond, the session information is lost and the proxy plug-in chooses a new server from the dynamic server list.

3.5.7 SSL and Web Server Plug-ins

You may use SSL to protect the connections used between the web server plug-in and WebLogic Server. Using HTTPS connections between the plug-in and WebLogic guarantees security and confidentiality. The SSL protocol allows the web server proxy to authenticate itself to WebLogic Server so that only trusted principals are accessing WebLogic Server. In order to use secure proxies, you need to do the following:

1. Configure SSL on WebLogic Server (and the SSL listen port).
2. Specify two additional parameters for the proxy plug-in:
   1. Enable secure proxies by setting the SecureProxy parameter to ON.
   2. Using the TrustedCAFile parameter, specify the file that contains the digital certificates for trusted CAs for the plug-in.

3.5.8 Configuration Parameters

Once you have configured which URLs the proxy plug-in should respond to, you are in a position to specify where and how the plug-in should redirect incoming requests. As mentioned earlier, you need to specify a list of name-value pairs in order to configure the proxy plug-in. For instance, in order to configure WebLogic's plug-in for Apache's Web Server, you can include the following in the server's configuration file:

 WebLogicHost wl.oreilly.com 
 WebLogicPort 7001
 MatchExpression *.jsp
 MatchExpression *.xyz

Let us consider the important configuration parameters:

WebLogicHost

This must be set when the web server needs to proxy to a single host, not a cluster. In this case, you must supply the hostname or virtual hostname of the server that will handle the request.

WebLogicPort

This specifies the port number of WebLogic Server (server or virtual host) that will handle proxied requests.

WebLogicCluster

This specifies the cluster address that will handle requests redirected by the proxy plug-in. This parameter will be a comma-delimited list of host:port entries.

PathTrim

This specifies a string that is to be trimmed from the beginning of the original URI, before the request is passed on to WebLogic. Imagine you have configured a default web application for your WebLogic deployment. This means you can access the web application without a context-path. Then, if you set the value of the PathTrim parameter to /dynamic, the plug-in will redirect the modified request to WebLogic after having removed /dynamic. For instance, a request to the URL http://www.servername.com/dynamic/myservlet could then be forwarded to http://weblogic.servername.com:7001/myservlet.

PathPrepend

This specifies a string that should be prefixed to the URI after it has been trimmed. For instance, this approach can be used to ensure that certain requests are routed to a particular web application, by specifying the context path for the web application as the path prefix.

Debug

This determines the level of logging. It can take one of the values discussed in the following list.

OFF

Debugging is disabled (this is the default value).

ON

Log info and error messages.

HFC

Logs headers from client, in addition to usual debugging info.

HTC

Logs headers sent to client, in addition to usual debugging info.

HFW

Logs headers from WebLogic Server, in addition to usual debugging info.

HTW

Logs headers sent to WebLogic Server, in addition to usual debugging info.

ALL

Logs all headers, in addition to usual debugging info.

WLLogFile

This specifies the path and name of the log file to be used, when debugging is switched on.

DebugConfigInfo

This can be set to either OFF or ON. If ON, any request that is proxied to WebLogic and that also includes the query parameter _ _WebLogicBridgeConfig retrieves the configuration data and runtime statistics from the configured proxy plug-in. Typically, you will enable this parameter for debugging purposes only.

CookieName

This is set to the cookie name that you have configured for your web application. This defaults to JSESSIONID, which is also the default for a web application.

Clearly, a proxy plug-in is very useful for transparently integrating a WebLogic Server (or a cluster) with a commercial web server.

3.5.9 Example Configurations

Let's take a closer look at sample plug-in configurations that also let you debug. Here is an example configuration that enables logging of debug information when the configured proxy is used:

 WebLogicHost 10.0.10.10 
 WebLogicPort 7001
 MatchExpression *.jsp
 Debug ON
 WLLogFile weblogic.log

As the proxy plug-in is used, you will see a lot of debug information being placed into the log. This includes your SSL configuration, the dynamic server lists, cookies, and more. The next configuration shows how to support dynamic queries for the plug-in's setup and runtime statistics:

 WebLogicHost 10.0.10.10 
 WebLogicPort 7001
 MatchExpression *.jsp
 DebugConfigInfo ON

You can then retrieve the plug-in's configuration and runtime statistics by pointing your browser to a URL, similar to http://webserver/a.jsp?__WebLogicBridgeConfig.

If you need to set up the plug-in to proxy to a WebLogic cluster using file extensions, consider the following configuration:

 WebLogicCluster 10.0.10.10:7003,10.0.10.10:7005
 MatchExpression *.jsp

You can achieve quite complex things if you use the full expression language syntax. You also may combine proxying by path with a cluster using the following setup:

 SetHandler weblogic-handler
 PathTrim /dynamic


 WebLogicCluster 10.0.10.10:7003,10.0.10.10:7005

In this case, all requests that include /dynamic in their paths are then sent through to the default web application configured for the servers within the cluster. The following example instructs the plug-in to proxy requests for .jsp and .asp files to separate clusters:

 MatchExpression *.jsp WebLogicCluster=10.0.10.10:7003,10.0.10.10:7005
 MatchExpression *.asp WebLogicCluster=10.0.10.11:7003,10.0.10.11:7005

The web server in turn allows you to configure many more advanced scenarios. For instance, you can benefit from exciting web server features such as virtual hosting, path matching using regular expressions, and more.