Installing the Apache-WebLogic Server Plug-in

 

Overview

Platform Support

Installing the library

Configuring the httpd.conf file

Proxy by URL

Proxy by MIME file type

Parameters for the Apache-WebLogic Server plug-in

Issues with SSL-Apache Configuration

Sample httpd.conf file

Sample weblogic.conf files

Example using WebLogic Clusters

Example without WebLogic Clusters

Example configuring Virtual Hosting

Deploying the Apache-WebLogic Server plug-in

Overview

This document describes how to install and configure the Apache-WebLogic Server plug-in. The plug-in allows a smooth integration of WebLogic Server's HTTP functionality into the Apache Server. Using the Apache-WebLogic Server plug-in enhances an existing Apache installation by providing a way to access WebLogic Server's servlet engine transparently.

The plug-in is intended for use in an environment where an Apache Server serves static pages, and another part of the document tree (dynamic pages best generated by HTTP Servlets) is delegated to a WebLogic Server operating in a different process, possibly on a different host. To the end user - the browser - the HTTP requests delegated to WebLogic Server still appear to be coming from the same source; WebLogic Server on the back-end is invisible. The HTTP-tunneling facility of the WebLogic Server client-server protocol may also operate through the plug-in, providing access to all WebLogic Server services, not only HTTP servlets.

The Apache-WebLogic Server plug-in operates as an Apache module within an Apache Server. An Apache module is loaded by an Apache Server at startup, and then certain HTTP requests are delegated to it. Apache modules are similar to HTTP (Java) servlets, except that an Apache module is in code native to the platform. For the latest Apache plug-in support information see our Platform Support page.

Platform Support

The Apache-WebLogic Server plug-in is supported on Linux, Solaris and HPUX11 platforms. The plug-in can be used with Apache Server 1.3.9 or Apache Server 1.3.12.

Installing the library

The Apache plug-in is distributed as a shared object (.so) for use on Solaris, Linux, and HPUX11 platforms. These files are located in the weblogic/lib directory.

The .so for Solaris is shipped in the weblogic/lib/solaris directory as the files:

mod_wl.so
mod_wl_ssl.so (available beginning with Service Pack 4)
mod_wl_ssl_raven.so (available beginning with Service Pack 4)

The .so for Linux is shipped in the weblogic/lib/linux directory as the files:

mod_wl.so (available beginning with Service Pack 3)
mod_wl_ssl.so (available beginning with Service Pack 5)
mod_wl_ssl_raven.so (available beginning with Service Pack 5)

The .so for HPUX11 is shipped in the weblogic/lib/hpux11 directory as the files:

mod_wl.so (available beginning with Service Pack 5)
mod_wl_ssl.so (available beginning with Service Pack 5)

The mod_wl.so is a shared object for standard Apache (non EAPI). The file mod_wl_ssl.so is used for Apache + SSL/EAPI installations (Stronghold, modssl etc). For Apache+Raven installations the mod_wl_ssl_raven.so is used. The mod_wl_ssl_raven.so file was required because Raven applies frontpage patches which makes it incompatible with mod_wl_ssl.so.

• Use mod_wl_ssl.so for Apache configured to listen for SSL:

       http/https                        http
  Client -------> Apache Server ---> plugin-------> Weblogic 5.1

• Use mod_wl.so for standard Apache not configured to listen for SSL:

         http                          http
  Client -----> Apache Server ---> plugin-------> Weblogic 5.1

These binaries have been certified against C2Net's Stronghold/3.0 (Apache/1.3.12) and Covalent's Raven/1.4.3 (Apache/1.3.12).

The Apache plug-in is installed as an Apache DSO (Dynamic Shared Object). DSO support in Apache is based on a module named mod_so.c which needs to be enabled before mod_wl.so is loaded. If you installed Apache with the supplied script for Solaris, or with the Windows NT installshield, mod_so.c should be enabled. To be certain that mod_so.c is enabled, run:

APACHE_HOME/bin/httpd -l

This command lists all of the enabled modules, if mod_so.c is listed, follow the 6 numbered steps at the end of this section. If mod_so.c is not listed, follow the instructions included with the distribution of Apache to manually configure Apache with the following parameters:

./configure --prefix=<destination directory>

  --enable-module=so

  --enable-rule=SHARED_CORE   

Continue following the Apache installation instructions to make and install the product.

After Apache installation is complete with the mod_so.c enabled. The Apache plug-in is installed with a support program named apxs (APache eXtenSion) that builds DSO based modules outside of the Apache source tree, and will add the AddModule mod_so.c line to the httpd.conf file. To install the Apache-WebLogic Server plug-in follow these 6 steps:

1. cd to weblogic/lib/PLATFORM directory that applies to your configuration and activate the weblogic_module by issuing this command (note that you must have perl installed to run this perl script):

   perl APACHE_HOME/bin/apxs -i -a -n weblogic mod_wl.so

2. This copies the mod_wl.so file to the APACHE_HOME/libexec directory. It also adds two lines of instructions for weblogic_module in Apache's file and activates the module. Verify that the following lines were added to your APACHE_HOME/conf/httpd.conf file:

   LoadModule weblogic_module
   AddModule mod_weblogic.c  (not always added)

3. Verify the syntax of the APACHE_HOME/conf/httpd.conf file with the following command:

   APACHE_HOME/bin/apachectl start

4. Configure Apache's httpd.conf configuration file as described in the next section.

5. Start Weblogic Server.

6. Start Apache.

Configuring the httpd.conf file

After you install the libraries, you will need to modify the httpd.conf file to configure the Apache plug-in. Modifying the httpd.conf file informs the Apache web server that it should load the native library for the plug-in as an Apache module, and also describes exactly which requests should be handled by the module. The correct file for Apache will be located in APACHE_HOME/conf/httpd.conf (where APACHE_HOME is the root directory of Apache installation).

To set up the WebLogic Apache plug-in on Apache, you will need the following information in the httpd.conf file:

• The two lines for the weblogic_module (added by apxs utility):

  LoadModule weblogic_module    libexec/mod_wl.so
  AddModule mod_weblogic.c  (not always added)

• Code that identifies the type of HTTP requests that should be handed to WebLogic via the Apache plug-in. You can proxy for the type of request by URL or MIME file extension type. These options are discussed below.

Proxy by URL

If you choose to proxy by URL, the location block and SetHandler will be used. SetHandler specifies the handler for the Weblogic module as shown below.

<Location URL> 
  SetHandler weblogic-handler
</Location>

For example:

<Location /weblogic>
  SetHandler weblogic-handler
</Location>

<Location /servletimages>
  SetHandler weblogic-handler
</Location>

In this manner, URLs directed to Apache at the specified location will be passed to the WebLogic Server for parsing. Because the PathTrim has been set to strip /weblogic from the URL, the URL forwarded to the WebLogic Server will be:

http://myenterprise.server.com:7001

A singular Virtual Host cannot be configured to proxy requests to multiple WebLogic Clusters. If you need support for multiple clusters, that can be accomplished using multipleVirtual Hosts. A singular Virtual Host can point to only one cluster. Requests that match any of the URLs specified in the location blocks will be forwarded to the same cluster.

Proxy by MIME file type

To proxy requests by MIME type, add a MatchExpression line to the IfModule block. (You can also proxy requests by path. Proxying by path takes precedence over proxying by MIME type.) For example, the following IfModule block for a non-clustered WebLogic Server specifies that all files with MIME type .jsp are proxied:

     
         WebLogicHost myweblogic.server.com
         WebLogicPort 7001
         MatchExpression *.jsp
     

You can also use multiple MatchExpressions, for example:

     
         WebLogicHost myweblogic.server.com
         WebLogicPort 7001
         MatchExpression *.jsp
         MatchExpression *.xyz
     

To proxy requests by MIME type to a cluster of WebLogic Servers, use the WebLogicCluster parameter instead of the WebLogicHost and WebLogicPort parameters. For example:

     
         WebLogicCluster w1s1.com:7001,w1s2.com:7001,w1s3.com:7001
         MatchExpression *.jsp
         MatchExpression *.xyz
     

Parameters for the Apache-WebLogic Server plug-in

The Weblogic Module for Apache recognizes the following parameters. To modify the properties of your Apache-WebLogic Server plug-in, these parameters can be placed in the IfModule or a Weblogic.conf file that is included in the IfModule.

<IfModule mod_weblogic.c>
  # Config file for WebLogic which defines the parameters
  Include conf/weblogic.conf 
</IfModule>

or

<IfModule mod_weblogic.c>
  # define your parameters here.
</IfModule>

Please note that each parameter should go in a new line, and there should not be an `=' between the parameter and its value. For Example:

PARAM_1 value1
PARAM_2 value2
PARAM_3 value3

WebLogicHost domain name

Required (If you are using a WebLogic Cluster, use the WebLogicCluster parameter instead). WebLogic Server host to which HTTP requests should be forwarded.

WebLogicPort port

Required (If you are using a WebLogic Cluster, use the WebLogicCluster parameter instead). Port at which the WebLogic Server host is listening for WebLogic connection requests.

WebLogicCluster cluster list

Required (If you are using a WebLogic Cluster). List of WebLogic Servers that can be used in a cluster for load-balancing. The cluster list is a comma-delimited list of host:port entries. For example:

WebLogicCluster myweblogic.com:7001,
yourweblogic.com:7001,theirweblogic.com:7001

This parameter should be used instead of the WebLogicHost and WebLogicPort parameters. The WebLogic Server will look first for the WebLogicCluster parameter. If not found, it will look for and use WebLogicHost and WebLogicPort.

The Apache plug-in does a simple round-robin between all available cluster members. The cluster list specified in this property is a starting point for the dynamic cluster list that the server and plug-in maintain. WebLogic Server and the plug-in work together to automatically update the cluster list with new, failed, and recovered cluster members.

The Apache plug-in will direct HTTP requests containing a cookie to the server in the cluster that originally created the cookie.

PathTrim string

String to be trimmed from the beginning of the original.

PathPrepend string

String to be prepended to the beginning of the original URL, after PathTrim has been trimmed, and before the request is forwarded to WebLogic. Default is "".

ConnectTimeoutSecs seconds

Maximum interval (in seconds) that the module should attempt to connect to the WebLogic Server host. Defaults to 10 seconds, and should be greater than ConnectRetrySecs. If ConnectTimeoutSecs expires without a successful connection, even after the appropriate retries (see ConnectRetrySecs) an HTTP 503/Service Unavailable response is sent to the client.

ConnectRetrySecs seconds

Interval (in seconds) that the module should sleep between attempts to connect to the WebLogic Server host. Defaults to 2 seconds, and this number should always be less than ConnectTimeoutSecs. Before returning an HTTP 503/Service Unavailable Response to the client, the Apache plug-in will attempt to connect every ConnectRetrySecs before ConnectTimeoutSecs. If ConnectRetrySecs is set equal to ConnectTimeoutSecs, only one attempt to connect will be made.

Debug ON/OFF

"Debug" will log the following messages to c:\tmp\wlproxy.log on NT and /tmp/wlproxy.log on UNIX.

--All headers coming in from the client/browser
--All headers sent to WebLogic
--All headers returned by WebLogic
--All headers returned back to the browser/client
--Dynamic Cluster List
--Connection info
--Other informational, warning and error messages

The default value is set to "OFF".

DebugConfigInfo ON/OFF

This parameter is used to enable the magic query parameter "__WebLogicBridgeConfig". This is used to get details about configuration parameters from the plugin.

For example, if you enable "__WebLogicBridgeConfig" by setting DebugConfigInfo=ON and then send a request like: http://www.mywebserver.com:8000/weblogic/foo.jsp?__WebLogicBridgeConfig, then the plug-in will gather the configuration information and return it back to the browser. Note that it will not connect to the WebLogic Server in this case.

This parameter is strictly for debugging and the format of the output message can change with releases. For security purposes it is advised to keep this parameter turned OFF in production systems.

DynamicServerList ON/OFF

When set to OFF, the plug-in ignores the dynamic cluster list used for load balancing requests proxied from the plug-in and only uses the static list specified with the WebLogicCluster parameter. Normally this parameter should remain set to ON. There are some implications for setting this parameter to ON:

• If one or more servers in the static list fails, the plug-in could waste time trying to connect to a dead server, resulting in decreased performance.

• If you add a new server to the cluster, the plug-in cannot proxy requests to the new server unless you redefine this parameter. WebLogic Server automatically adds new servers to the dynamic server list when they become part of the cluster.

StatPath boolean

If set to true, the Apache-WebLogic Server plug-in will check the existence and readability permissions of the translated path ("Proxy-Path-Translated") of the request before forwarding the request to WebLogic Server.

Defaults to false. If the file doesn't exist, an HTTP 404/Not Found response will be returned to the client. If the file exists but is not world-readable, an HTTP 403/Forbidden response will be returned to the client. In either case, the default mechanism for Apache Server to handle these responses will fulfill the body of the response. This option is useful if both the WebLogic Server servlet engine and Apache Server have the same document root.

ErrorPage URL

You may create your own error page that will be displayed when Apache Server is unable to forward requests to WebLogic Server. Set the URL to the location of your error page.

HungServerRecoverSecs seconds

This implementation takes care of the hung or unresponsive servers in the cluster. The plug-in waits for HungServerRecoverSecs for the server to respond and then declares that server dead, failing over to the next server. The minimum value for this setting is 10 and the maximum value is 600. The default is set at 300. It should be set to a very large value. If it is less than the time the servlets take to process, then you will see unexpected results.

Idempotent ON/OFF

This is a URL level flag. By default it will be "ON". This means that if the servers do not respond within HungServerRecoverSecs, the plug-ins will failover. If set to "OFF" the plug-ins will not failover. It can be set differently for different URL's or Mime types.

CookieName cname

If you change the name of the WebLogic session cookie in the WebLogic Server, you need to change the CookieName parameter in the plug-in to the same value. The name of the WebLogic session cookie is set in the weblogic.properties file using the weblogic.httpd.session.cookie.name property.

DefaultFileName filename

If the URI is "/" then the default filename will be appended to the URI. This prevents redirects from the WebLogic Server. The DefaultFileName should be set to the default welcome page of the WebLogic Server. If the DefaultFileName is set to welcome.html, a http request like "http://somehost/weblogic" will become "http://somehost/weblogic/welcome.html". For this parameter to function, the same file must be specified in the weblogic properties file. For example, in this case, the weblogic properties file must be set to weblogic.httpd.initArgs.file=defaultfilename=welcome.html.

QueryFromRequest ON/OFF

When set to "ON", specifies that the Apache plug-in use(request_rec *)r->the request to pass the query string to WebLogic Server. (For more information, see your Apache documentation.) This behavior is desirable when a Netscape version 4.x browser makes requests that contain spaces in the query string or if you are using Raven Apache 1.5.2 on HP. When set to "OFF", the Apache plug-in uses (request_rec *)r->args to pass the query string to WebLogic Server.

Issues with SSL-Apache Configuration

There are two known issues with the Apache plug-in when configured to use SSL.

1. PathTrim has to be used inside the <Location> tag. The following configuration is incorrect:

<Location /weblogic>
 SetHandler weblogic-handler 
</Location> 

<IfModule mod_weblogic.c>
 WebLogicHost localhost
 WebLogicPort 7001

 PathTrim /weblogic 
</IfModule> 

Below is the correct setup:

<Location /weblogic>
  SetHandler weblogic-handler
  PathTrim /weblogic
</Location>

2. Include directive does not work with apache SSL. Try to avoid using the following in apache SSL:

<IfModule mod_weblogic.c> 
Include weblogic.conf 
</IfModule> 

Sample httpd.conf file

Below is an example httpd.conf file. You can use this example as a template that you can modify to suit your environment and server. Lines beginning with # are comments. Please note that Apache is not case sensitive, and that the LoadModule and AddModule lines will be automatically added by the apxs utility.

####################################################

APACHE-HOME/conf/httpd.conf file
####################################################

LoadModule weblogic_module         libexec/mod_wl.so

<Location /weblogic>
  SetHandler weblogic-handler
  PathTrim /weblogic 
  ErrorPage http://myerrorpage1.mydomain.com
  </Location>

<Location /servletimages>
  SetHandler weblogic-handler
  PathTrim /something
  ErrorPage http://myerrorpage1.mydomain.com
</Location>

MatchExpression *.jsp

<IfModule mod_weblogic.c>
  Include conf/weblogic.conf
</IfModule>

# The following line is not always added:

AddModule mod_weblogic.c

Sample weblogic.conf files

Instead of defining Weblogic Parameters in the location block of your httpd.conf file, if you prefer, you can use a weblogic.conf file that is loaded by the IfModule in the httpd.conf file. Either of the following examples may be used as templates that you can modify to suit your environment and server. Lines beginning with `#' are comments.

Example using WebLogic Clusters

# These parameters are common for all URLs which are 
# directed to the current module.  If you want to override
# these parameters for each URL, you can set them again in
# the <Location> or <Files> blocks (except WebLogicHost,
# WebLogicPort, WebLogicCluster, and CookieName; as the
# plug-in doesn't support multiple clusters.)

WebLogicCluster  w1s1.com:7001,w1s2.com:7001,w1s3.com:7001
ErrorPage http://myerrorpage.mydomain.com
MatchExpression *.jsp
####################################################

Example without WebLogic Clusters

# These parameters are common for all URLs which are 
# directed to the current module.  If you want to override
# these parameters for each URL, you can set them again in
# the <Location> or <Files> blocks (except WebLogicHost,
# WebLogicPort, WebLogicCluster, and CookieName; as the
# plug-in doesn't currently support multiple clusters.)

WebLogicHost myweblogic.server.com
WebLogicPort 7001
MatchExpression *.jsp

Example configuring Virtual Hosting

NameVirtualHost 172.17.8.1
<VirtualHost goldengate.domain1.com>
  WebLogicCluster tehama1:4736,tehama2:4736,tehama:4736
  PathTrim /x1
  ConnectTimeoutSecs 30
</VirtualHost> 
<VirtualHost goldengate.domain2.com>     
  WeblogicCluster green1:4736,green2:4736,green3:4736        
  PathTrim /y1
  ConnectTimeoutSecs 20 
</VirtualHost> 
 

Deploying the Apache-WebLogic Server plug-in

Once you have installed and configured the Apache-WebLogic Server plug-in, follow these steps for deployment and testing:

1. Start Weblogic Server.

2. If your Apache Server is already running, you must restart it order for the new settings to effect.

3. To test the Apache plug-in, open a browser and set the URL to the Apache Server + "/weblogic/", which should bring up the default WebLogic HTTP servlet, as shown in this example:

   http://myenterprise.server.com/weblogic/