Installing the Netscape (proxy) plug-in

Background

Platform Support

Installing the library

Configuring the obj.conf file

Proxy by ppath

Proxy by file extension

Enable HTTP-tunneling

Modify the MIME.types file

Deploy and test the NSAPI plug-in

Supporting Documentation

Parameters

Sample obj.conf file

Notes on configuring a WebLogic Cluster

Notes on failover in a WebLogic Cluster

Sample obj.conf file using a WebLogic Cluster

Background

This document describes how to install and configure the Netscape Enterprise Server (NES) proxy plug-in. The plug-in, also known as NSAPI, integrates WebLogic's HTTP functionality into NES, and provides a way to access WebLogic's servlet engine transparently.

The plug-in is for an environment where NES serves static pages, and a Weblogic Server (operating in a different process, possibly on a different host) is delegated to serve dynamic pages (such as JSPs or pages generated by HTTP Servlets). The connection between WebLogic Server and the NSAPI plug-in is clear text http, not SSL. To the end user -- the browser -- the HTTP requests delegated to WebLogic appear to come from the same source as the static pages. In other words, WebLogic on the back-end is invisible. Additionally, the HTTP-tunneling facility of the WebLogic client-server protocol can operate through the plug-in, providing access to all WebLogic services (not just dynamic pages).

The WebLogic plug-in operates as an NSAPI module within an Enterprise Server. The NSAPI module is loaded by NES at startup, and then certain HTTP requests are delegated to it. NSAPI is similar to an HTTP (Java) servlet, except that an NSAPI module is in code native to the platform.

Platform Support

WebLogic NSAPI has been tested with Netscape Enterprise Server 3.0, 3.51, 3.60 and 4.0 (iPlanet). The following table summarizes NES version support for each of the supported platforms.

Platform	NES Version	Shared library
AIX	3.6	weblogic/lib/aix/libproxy.sl
HP-UX 10.20	3.6	weblogic/lib/hpux10/libproxy.sl
HP-UX 11.00	3.6	weblogic/lib/hpux11/libproxy.so
Solaris	3.0 3.5.1 3.6 4.0 (iPlanet)	weblogic/lib/solaris/libproxy.so weblogic/lib/solaris/libproxy.so weblogic/lib/solaris/libproxy.so weblogic/lib/solaris/libproxy.so (Requires service pack 6 or higher)
Windows NT	3.0 3.5.1 3.6 4.0 (iPlanet)	weblogic/bin/proxy30.dll weblogic/bin/proxy35.dll weblogic/bin/proxy36.dll weblogic/bin/proxy36.dll

There are four steps to installing the NSAPI plug-in:

1. Install the appropriate NSAPI library file in the filesystem where NES is located.

2. Modify the obj.conf configuration file for the NES instance.

3. Modify the mimes.types file in the NES configuration directory.

4. Deploy and test the NSAPI plug-in.

Step One: Install the library

The WebLogic NSAPI plug-in module is distributed as a shared object (.so) on UNIX platforms and as a dynamic-link library (.dll) on NT. These files are respectively located in the weblogic/lib and weblogic/bin directories of the distribution. Choose the appropriate library file for your environment from the platform support table. Then, copy that file into the filesystem where NES is located.

Step Two: Configure the obj.conf file

In order to use the NSAPI plug-in, you need to modify the NES obj.conf file. These modifications include:

• Code that instructs NES to load the native library as an NSAPI module
• Object definitions for each type of request that should be handled by the NSAPI plug-in
• Optional code that allows HTTP-tunneling of the WebLogic protocol through the NSAPI plug-in

Locate and Open obj.conf

The obj.conf file for your NES instance will be in the following location:

NETSCAPE_HOME/https-INSTANCE_NAME/config/obj.conf

/usr/local/netscape/enterprise-351/https-goldengate/config/obj.conf

Instruct NES to load the native library as an NSAPI module

Add the following lines of code at the beginning of the obj.conf file. This code instructs NES to load the native library (shared object or dll from the list above) as an NSAPI module.

Init fn="load-modules" funcs="wl-proxy,wl-init"\
	shlib=/usr/local/netscape/plugins/SHARED_LIBRARY
Init fn="wl-init"

Declare which requests should be handled by the NSAPI plug-in

All requests that will go through the NSAPI plug-in to WebLogic Server must be declared in an object definition that exists in the obj.conf file. These requests can be identified in two ways: by their MIME file extension, or by a specific string (called a ppath) in their URL.

Whether you are proxying by MIME or ppath, you must add parameters to the <Object> tag itself, as well as between the opening and closing <Object> tags. NES Parameters (between the < and >) include its name and, optionally, a ppath. Between the tags, the Service statement sets the WebLogic parameters that the module recognizes: WebLogicHost (required), WebLogicPort (required), PathTrim, PathPrepend, ConnectTimeoutSecs, ConnectRetrySecs, and StatPath. If a required parameter is missing, the object will issue an HTML error when invoked that notes the parameter that is missing from the configuration.

The Netscape obj.conf file is very strict about the placement of text. To avoid problems, please be certain that you follow these directions:

1. Eliminate extraneous leading and trailing white space.
2. If you must enter more characters than can be fit on one line, place a backslash "\" at the end of that line and continue typing on the following line. The backslash directly appends the end of the first line to the beginning of the following line. If a space is necessary between the words that end the first line and begin the second line, be certain to use one space, either at the end of the first line (before the backslash), or at the beginning of the second line.
3. Attributes must not be split across multiple lines. (For example, all of the servers in a cluster must be listed in the same line, following WebLogicCluster).

Proxy by ppath

To proxy by ppath, begin a new object defintion, by typing <Object name="insert_name">. Name it according to the service it proxies, and set the ppath in the <Object> tag. The ppath can be any string that identifies requests intended for the weblogic server. When you use a ppath, every request that contains that path is redirected. For example, a ppath of "/weblogic/*" would redirect every request that begins "http://enterprise.com/weblogic" to the NSAPI plug-in which will send the request to the specified Weblogic Host/Port or Cluster.

Each new Object definition (the code between the tags) begins with Service fn=wl-proxy, and must set two required parameters for WebLogic servers not in a cluster: WebLogicHost and WebLogicPort. For WebLogic servers in a cluster, only one parameter is required: WebLogicCluster.

Here is an example of the object definitions that would be added to obj.conf for two separate ppaths that indentify requests to be sent to different instances of WebLogic Server.

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=wl-proxy WebLogicHost=myserver.com\
   WebLogicPort=7001 PathTrim="/weblogic"
</Object>  

<Object name="si" ppath="*/servletimages/*">
Service fn=wl-proxy WebLogicHost=otherserver.com\
   WebLogicPort=7008
</Object>

Note: Parameters that are not required, such as PathTrim, can be used to further configure the way the ppath is passed through the NSAPI plug-in. All of the WebLogic NSAPI plug-in parameters are explained in the Parameters section of this document.

Proxy by file extension

To proxy all JSPs to a WebLogic Server, the following Service statement should be added after the last line that begins NameTrans fn=....and before the line that begins PathCheck.

Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl-proxy\
  WebLogicHost=192.1.1.4 WebLogicPort=7001 PathPrepend=/jspfiles

  http://WebLogic:7001/jspfiles/myfile.jsp

The value of PathPrepend should correspond to the WebLogic document root, which is where the JSPServlet searches for JSP files to compile in answer to a request. (Read the Developers Guide, Using WebLogic JSP, for more on JSP and automatic page compilation.)

After the addition, the default Object definition will be similar to the one below, with the additions shown in blue:

<Object name=default>
NameTrans fn=pfx2dir from=/ns-icons\
   dir="c:/Netscape/SuiteSpot/ns-icons"
NameTrans fn=pfx2dir from=/mc-icons\
   dir="c:/Netscape/SuiteSpot/ns-icons"
NameTrans fn="pfx2dir" from="/help" dir=\
  "c:/Netscape/SuiteSpot/manual/https/ug"
NameTrans fn=document-root root="c:/Netscape/SuiteSpot/docs"
Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl-proxy\
  WebLogicHost=localhost WebLogicPort=7001 PathPrepend=/jspfiles
PathCheck fn=nt-uri-clean
PathCheck fn="check-acl" acl="default"
PathCheck fn=find-pathinfo
PathCheck fn=find-index index-names="index.html,home.html"
ObjectType fn=type-by-extension
ObjectType fn=force-type type=text/plain
Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap
Service method=(GET|HEAD) \
  type=magnus-internal/directory fn=index-common
Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file
AddLog fn=flex-log name="access"
</Object>

A similar Service statement should be added to the default object definition for all other MIME types that you wish to proxy to WebLogic Server.

Enable HTTP-tunneling

If you wish to use HTTP-tunneling of the WebLogic Protocol through the NSAPI plug-in, you must add the following object definition to the obj.conf file, substituting the WebLogic Host and WebLogic Port, or WebLogic Cluster that you wish to use.

<Object name="tunnel" ppath="*/HTTPClnt*">
Service fn=wl-proxy WebLogicHost=192.192.1.4 WebLogicPort=7001
</Object>

Step Three: Modify the MIME.types file

If you set the NSAPI plug-in to proxy by MIME type as described above, you must add an identifier and extension of each MIME type to be proxied in your NES configuration directory. There are two ways to do this: through the console, or by directly editing the MIME.types file. To directly edit the MIME.types file, open the file for edit and type the following line:

  type=text/jsp        exts=jsp

/magnus-internal/jsp   to   text/jsp.

For all versions of NES, you may edit the MIME.types file manually, or you can use administration console. To use the console, click Manage --> Preferences --> Mime Types, and make the additions or edits.

Step Four: Deploy and test the NSAPI plug-in

1. Start WebLogic.

2. Start Netscape Enterprise Server. If NES is already running, you must either restart it, or apply the new settings from the console, for the new settings to take effect.

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

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

Parameters

The NSAPI module recognizes the following parameters. Parameter names have changed from version 4.0. While the deprecated "Tengah"-based names are still respected, we strongly recommend that you update your environment.

Note on configuring a WebLogic Cluster: If you will be using a WebLogic Cluster, note that you must use the WebLogicCluster parameter instead of the WebLogicHost and WebLogicPort parameters.

WebLogicHost=domain name

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

WebLogicPort=port (formerly TengahPort)

Required (If you are using a WebLogic Cluster, you should use the WebLogicCluster parameter instead.). Port at which the WebLogic 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:6999,theirweblogic.com:6001"

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. (If it can not find those, it will look for and use TengahHost and TengahPort.)

The plug-in does a simple round-robin between all available cluster members. When a member cannot be reached it is marked as "bad" (but is not forgotten), and another member is tried instead; after 10 skips, the member is tried again, and if successful, its status is changed.

The 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 URL, before the request is forwarded to WebLogic. Default is "".

The ppath regexp may be passed to WebLogic as part of the WebLogic URL, or may be stripped off, depending upon the setting of the PathTrim inside the Object tag. For example, a typical Object tag that proxies a request to WebLogic looks like this:

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=wl-proxy WebLogicHost=myweblogic.server.com\
  WebLogicPort=7001\
  PathTrim="/weblogic"
</Object>

The ppath setting means that a URL directed to Enterprise Server, such as:

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

will be passed to the WebLogic Server for parsing. Because the PathTrim has been set to strip off "/weblogic" before handing the URL to the WebLogic Server, the URL forwarded to WebLogic is:

http://myweblogic.server.com:7001/

PathPrepend=string

String to be prepended to the beginning of the original URL, after PathTrim has been trimmed, 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 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 host. Defaults to 2 seconds, and this number should always be less than the ConnectTimeoutSecs. The plug-in will try ConnectTimeoutSecs/ConnectRetrySecs times to connect before returning an HTTP 503/Service Unavailable response to the client. To never retry, set ConnectRetrySecs to equal ConnectTimeoutSecs.

StatPath=boolean

If set to true, the 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. Defaults to false. If the file does not 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 Enterprise Server to handle these responses will fulfill the body of the response. This option is really only useful if both the WebLogic servlet engine and Enterprise Server have the same document root.

ErrorPage=URL

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

CookieName=cname

If you change the name of the WebLogic session cookie in the WebLogic Server, you need to add this property to the obj.conf file. The name of the WebLogic session cookie is set in the weblogic.properties file using the weblogic.httpd.session.cookie.name property. For more details, see the Administrators Guide, Setting up WebLogic as an HTTP server.

Notes on failover in a WebLogic Cluster when using NSAPI

In most configurations, if the NSAPI plug-in sends a request to the primary instance of a cluster while it is unavailable, the request will failover to the secondary instance. However, in some configurations that use combinations of firewalls and load-directors, it is possible that any one of the servers (firewall or load-directors)will accept the request (and return a successful connection) while the primary instance of WebLogic Server is unavailable. After attempting to direct the request to the primary instance of WebLogic Server (which is unavailable), the request will be returned to the NSAPI plug-in as "connection reset".

In configurations of WebLogic Server 4.5.1 with service pack 7 or greater, NSAPI requests running through combinations of firewalls (with or without load-directors) will be handled by the WebLogic Server. In other words, responses of "connection reset" will failover to a secondary instance of WebLogic Server. Because responses of "connection reset" will failover in theses configurations, servlets must be idempotent.

For example, if the primary instance of WebLogic Server goes down while processing a transaction, a "connection reset" message is returned to the NSAPI plug-in. The NSAPI plug-in will redirect that request to a second instance of WebLogic Server, where it will be executed again. This can result in duplicate processing of transactions if servlets are not idempotent.

In configurations of Weblogic Server 4.5.1 with service pack 6 or lower, NSAPI requests returning a response of "connection reset" will not failover. This protects against duplicate transactions of non-idempotent servlets, but may not provide failover in cases of combined firewalls and/or load-directors.

Sample obj.conf file (not using a WebLogic Cluster)

Below is an example of lines which should be added to the obj.conf file if you are not using a cluster. You can use this example as a template that you can modify to suit your environment and server. Lines beginning with '#' are comments.

You can read the full documentation on Enterprise Server configuration files at Netscape.

## ------------- BEGIN SAMPLE OBJ.CONF CONFIGURATION  ---------
# (no cluster)
# 
# The following line locates the NSAPI library for loading at
# startup, and identifies which functions within the library are
# NSAPI functions.  Verify the path to the library (the value
# of the shlib=<...> parameter) and that the file is
# readable, or the server will fail to start.

Init fn="load-modules" funcs="wl-proxy,wl-init"\
  shlib=/usr/local/netscape/plugins/libproxy.so
Init fn="wl-init"

# Configure which types of HTTP requests should be handled by the
# NSAPI module (and, in turn, by WebLogic).  This is done 
# with one or more "<Object>" tags as shown below. 

# Here we configure the NSAPI module to pass requests for
# "/weblogic" to a WebLogic Server listening at port 7001 on
# the host myweblogic.server.com.

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=wl-proxy WebLogicHost=myweblogic.server.com\
  WebLogicPort=7001 PathTrim="/weblogic"
</Object>

# Here we configure the plug-in so that requests that
# match "/servletimages/" will be handled by the
# plug-in/WebLogic.

<Object name="si" ppath="*/servletimages/*">
Service fn=wl-proxy WebLogicHost=192.192.1.4 WebLogicPort=7001
</Object>

# This Object directive works by file extension rather than
# request path. To use this configuration, you must also add
# a line to the mime.types file:
#
# type=text/jsp             exts=jsp
# 
# This configuration means that any file with the extension
# ".jsp" will be proxied to WebLogic. Then you must add the
# Service line for this extension to the Object "default",
# which should already exist in your obj.conf file:

<Object name=default>
NameTrans fn=pfx2dir from=/ns-icons\
   dir="c:/Netscape/SuiteSpot/ns-icons"
NameTrans fn=pfx2dir from=/mc-icons\
   dir="c:/Netscape/SuiteSpot/ns-icons"
NameTrans fn="pfx2dir" from="/help" dir=\
  "c:/Netscape/SuiteSpot/manual/https/ug"
NameTrans fn=document-root root="c:/Netscape/SuiteSpot/docs"
Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl-proxy\
  WebLogicHost=localhost WebLogicPort=7001 PathPrepend=/jspfiles
PathCheck fn=nt-uri-clean
PathCheck fn="check-acl" acl="default"
PathCheck fn=find-pathinfo
PathCheck fn=find-index index-names="index.html,home.html"
ObjectType fn=type-by-extension
ObjectType fn=force-type type=text/plain
Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap
Service method=(GET|HEAD) \
  type=magnus-internal/directory fn=index-common
Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file
AddLog fn=flex-log name="access"
</Object>

# The following directive enables HTTP-tunneling of the 
# WebLogic protocol through the NSAPI plug-in.

<Object name="tunnel" ppath="*/HTTPClnt*">
Service fn=wl-proxy WebLogicHost=192.192.1.4 WebLogicPort=7001
</Object>

#
## ------------- END SAMPLE OBJ.CONF CONFIGURATION ---------

Sample obj.conf file (using a WebLogic Cluster)

Below is an example of lines which should be added to obj.conf if you are using a WebLogic Cluster. You can use this example as a template that you can modify to suit your environment and server. Lines beginning with '#' are comments.

You can read the full documentation on Enterprise Server configuration files at Netscape.

## ------------- BEGIN SAMPLE OBJ.CONF CONFIGURATION ---------
# (using a WebLogic Cluster) 
# 
# The following line locates the NSAPI library for loading at
# startup, and identifies which functions within the library are
# NSAPI functions.  Verify the path to the library (the value
# of the shlib=<...> parameter) and that the file is
# readable, or the server will fail to start.

Init fn="load-modules" funcs="wl-proxy,wl-init"\
  shlib=/usr/local/netscape/plugins/libproxy.so
Init fn="wl-init"

# Configure which types of HTTP requests should be handled by the
# NSAPI module (and, in turn, by WebLogic).  This is done 
# with one or more "<Object>" tags as shown below. 

# Here we configure the NSAPI module to pass requests for
# "/weblogic" to a cluster of WebLogic Servers listening at 
# various ports.

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=wl-proxy  WebLogicCluster="myweblogic.com:7001,
 yourweblogic.com:6999,theirweblogic.com:6001" PathTrim="/weblogic"
</Object>

# Here we configure the plug-in so that requests that
# match "/servletimages/" will be handled by the
# plug-in/WebLogic.

<Object name="si" ppath="*/servletimages/*">
Service fn=wl-proxy WebLogicCluster="myweblogic.com:7001,
 yourweblogic.com:6999,theirweblogic.com:6001"
</Object>

# This Object directive works by file extension rather than
# request path. To use this configuration, you must also add
# a line to the mime.types file:
#
# type=text/jsp             exts=jsp
# 
# This configuration means that any file with the extension
# ".jsp" will be proxied to WebLogic. Then you must add the
# Service line for this extension to the Object "default",
# which should already exist in your obj.conf file:

<Object name=default>
NameTrans fn=pfx2dir from=/ns-icons\
   dir="c:/Netscape/SuiteSpot/ns-icons"
NameTrans fn=pfx2dir from=/mc-icons\
   dir="c:/Netscape/SuiteSpot/ns-icons"
NameTrans fn="pfx2dir" from="/help" dir=\
  "c:/Netscape/SuiteSpot/manual/https/ug"
NameTrans fn=document-root root="c:/Netscape/SuiteSpot/docs"
Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl-proxy\
  WebLogicCluster="myweblogic.com:7001,yourweblogic.com:6999,
    theirweblogic.com:6001"  PathPrepend=/jspfiles
PathCheck fn=nt-uri-clean
PathCheck fn="check-acl" acl="default"
PathCheck fn=find-pathinfo
PathCheck fn=find-index index-names="index.html,home.html"
ObjectType fn=type-by-extension
ObjectType fn=force-type type=text/plain
Service method=(GET|HEAD) type=magnus-internal/imagemap fn=imagemap
Service method=(GET|HEAD) \
  type=magnus-internal/directory fn=index-common
Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file
AddLog fn=flex-log name="access"
</Object>

# The following directive enables HTTP-tunneling of the 
# WebLogic protocol through the NSAPI plug-in.

<Object name="tunnel" ppath="*/HTTPClnt*">
Service fn=wl-proxy WebLogicCluster="myweblogic.com:7001,\
 yourweblogic.com:6999,theirweblogic.com:6001"
</Object>

#
## ------------- END SAMPLE OBJ.CONF CONFIGURATION ---------

Copyright © 2000 BEA Systems, Inc. All rights reserved.
Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.
Last updated 06/24/1999