BEA Logo BEA WebLogic Server Release 6.1

  Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy

   BEA WebLogic Server Administration Guide:   Previous topic   |   Next topic   |   Contents   |  Index

 

Installing and Configuring the Netscape Enterprise Server Plug-In (NSAPI)

 

The following sections describe how to install and configure the Netscape Enterprise Server Plug-In (NES) proxy plug-in:

Overview of the Netscape Enterprise Server Plug-In

The Netscape Enterprise Server Plug-In enables requests to be proxied from Netscape Enterprise Server (NES, also called iPlanet) to WebLogic Server. The plug-in enhances an NES installation by allowing WebLogic Server to handle those requests that require the dynamic functionality of WebLogic Server.

The Netscape Enterprise Server Plug-In is designed for an environment where Netscape Enterprise Server serves static pages, and a Weblogic Server (operating in a different process, possibly on a different host or hosts) is delegated to serve dynamic pages, such as JSPs or pages generated by HTTP Servlets. The connection between WebLogic Server and the Netscape Enterprise Server Plug-In is made using clear text or Secure Sockets Layer (SSL). To the end user-the browser-the HTTP requests delegated to WebLogic Server appear to come from the same source as the static pages. Additionally, the HTTP-tunneling facility of the WebLogic Server can operate through the Netscape Enterprise Server Plug-In, providing access to all WebLogic Server services (not just dynamic pages).

The Netscape Enterprise Server Plug-In operates as an NSAPI modulewithin a Netscape 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 a NSAPI module is written in code native to the platform.

For more information on supported versions of Netscape Enterprise Server and iPlanet servers, see the BEA WebLogic Server Platform Support Page.

Connection Pooling and Keep-Alive

The WebLogic Server NSAPI plug-in provides efficient performance by using a re-usable pool of connections from the plug-in to WebLogic Server. The NSAPI plug-in automatically implements "keep-alive" connections between the plug-in and WebLogic Server. If a connection is inactive for more than 30 seconds or a user-defined amount of time, the connection is closed.

Proxying Requests

The plug-in proxies requests to WebLogic Server based on a configuration that you specify. You can proxy requests either based on the URL of the request (or a portion of the URL). This is called proxying by path. You can also proxy request based on the MIME type of the requested file. You can also use a combination of both methods. If a request matches both criteria, the request is proxied by path. You can also specify additional parameters for each of these types of requests that define additional behavior of the plug-in. For more information, see the next section.

Installing and Configuring the Netscape Enterprise Server Plug-In

To install and configure the Netscape Enterprise Server Plug-In:

  1. Copy 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 Windows. These files are respectively located in the /lib or /bin directories of your WebLogic Server distribution.

    Choose the appropriate library file for your environment from the BEA WebLogic Server Platform Support Page.. and copy that file into the file system where NES is located.

  2. Modify the obj.conf file. The obj.conf file defines which requests are proxied to WebLogic Server and other configuration information. For details see Modifying the obj.conf File.

  3. If you are proxying requests by MIME type:

    1. Add the appropriate lines to the obj.conf file. For more information, see Modifying the obj.conf File.

    2. Add any new MIME types referenced in the obj.conf file to the MIME.types file. You can add MIME types by using the Netscape server console or by editing the MIME.types file directly.

      To directly edit the MIME.types file, open the file for edit and type the following line:

      type=text/jsp        exts=jsp

      Note: For NES 4.0 (iPlanet), instead of adding the MIME type for JSPs, change the existing MIME type from

      magnus-internal/jsp

      to

      text/jsp. 

      To use the Netscape console, select Manage Preferences--> Mime Types, and make the additions or edits.

  4. Deploy and test the Netscape Enterprise Server Plug-In

    1. Start WebLogic Server.

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

    3. To test the Netscape Enterprise Server Plug-In, open a browser and set the URL to the Enterprise Server + /weblogic/, which should bring up the default WebLogic Server HTML page, welcome file, or default servlet, as defined for the default Web Application on WebLogic Server, as shown in this example:

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

Modifying the obj.conf File

To use the Netscape Enterprise Server Plug-In, you must make several modifications to the NES obj.conf file. These modifications specify how requests are proxied to WebLogic Server. You can proxy requests by URL or by MIME type. The procedure for each is described later in this section.

The Netscape obj.conf file is very strict about the placement of text. To avoid problems, note the following regarding the obj.conf file:

To configure the obj.conf file:

  1. Locate and open obj.conf.

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

    NETSCAPE_HOME/https-INSTANCE_NAME/config/obj.conf

    Where NETSCAPE_HOME is the root directory of the NES installation, and INSTANCE_NAME is the particular "instance" or server configuration that you are using. For example, on a UNIX machine called myunixmachine, the obj.conf file would be found here:

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

  2. Instruct NES to load the native library as an NSAPI module

    Add the following lines to the beginning of the obj.conf file. These lines instruct NES to load the native library (the .so or .dll file) as an NSAPI module:

    Init fn="load-modules" funcs="wl_proxy,wl_init"\
    shlib=/usr/local/netscape/plugins/
    SHARED_LIBRARY
    Init fn="wl_init"

    Where SHARED_LIBRARY is the shared object or dll (for example libproxy.so) that you installed in step 1.under Installing and Configuring the Netscape Enterprise Server Plug-In. The function "load-modules" tags the shared library for loading when NES starts up. The values "wl_proxy" and "wl_init" identify the functions that the Netscape Enterprise Server Plug-In executes.

  3. If you want to proxy requests by URL, (Also called proxying by path. If you want to proxy requests by MIME type, see step 4.) create a separate <Object> tag for each URL that you want to proxy and define the PathTrim parameter. Proxying by path supersedes proxying by MIME type. The following is an example of an <Object> tag that proxies a request containing the string */weblogic/*.

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

    To create an <Object> tag to proxy requests by URL:

    1. Specify a name for this object (optional) inside the opening <Object> tag using the name attribute. The name attribute is informational only and is not used by the Netscape Enterprise Server Plug-In. For example

      <Object name=myObject ...>

    2. Specify the URL to be proxied within the <Object> tag, using the ppath attribute. For example:

      <Object name=myObject ppath="*/weblogic/*>

      The value of the ppath attribute can be any string that identifies requests intended for Weblogic Server. When you use a ppath, every request that contains that path is redirected. For example, a ppath of "*/weblogic/*" redirects every request that begins "http://enterprise.com/weblogic" to the Netscape Enterprise Server Plug-In, which sends the request to the specified Weblogic host or cluster.

    3. Add the Service directive within the <Object> and </Object> tags. In the Service directive you can specify any valid parameters as name=value pairs. Separate multiple name=value pairs with one and only one space. For example:

      Service fn=wl_proxy WebLogicHost=myserver.com\
       WebLogicPort=7001 PathTrim="/weblogic"

      For a complete list of parameters, see General Parameters for Web Server Plug-Ins. You must specify the following parameters:

      For a non-clustered WebLogic Server:
             The
      WebLogicHost and WebLogicPort parameters.

      For a cluster of WebLogic Server:
             The
      WebLogicCluster parameter.

      The Service directive should always begin with Service fn=wl_proxy, followed by valid name=value pairs of parameters.

      Here is an example of the object definitions for two separate ppaths that identify 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 Netscape Enterprise Server Plug-In. For a complete list of plug-in parameters, see

  4. If you want to proxy by MIME type, the MIME type must be listed in the MIME.types file. For instructions on modifying this file, see step 3.under Installing and Configuring the Netscape Enterprise Server Plug-In.

    All requests with a designated MIME type extension (for example, .jsp) can be proxied to the WebLogic Server, regardless of the URL.

    To proxy all requests of a certain file type to WebLogic Server:

    1. Add a Service directive to the existing default Object definition. (<Object name=default ...>).

      For example, to proxy all JSPs to a WebLogic Server, the following Service directive should be added after the last line that begins with:

      NameTrans fn=....

      and before the line that begins with:

      PathCheck.

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

      This Service directive proxies all files with the .jsp extension to the designated WebLogic Server, where they are served with a URL like this:

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

      The value of the PathPrepend parameter should correspond to the context root of a Web Application that is deployed on the WebLogic Server or cluster to which requests are proxied.

      After adding entries for the Netscape Enterprise Server Plug-In, the default Object definition will be similar to the following example, with the additions shown in bold:

      <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>

    2. Add a similar Service statement to the default object definition for all other MIME types that you want to proxy to WebLogic Server.

  5. If you want to enable HTTP-tunneling (optional):

    Add the following object definition to the obj.conf file, substituting the WebLogic Server host name and the WebLogic Server port number, or the name of a WebLogic Cluster that you wish to handle HTTP tunneling requests.

    <Object name="tunnel" ppath="*/HTTPClnt*">
    Service fn=wl_proxy WebLogicHost=192.192.1.4\  WebLogicPort=7001
    </Object>

Using SSL with the NSAPI Plug-In

You can use the Secure Sockets Layer (SSL) protocol to protect the connection between the Netscape Enterprise Server Plug-In, and WebLogic Server. The SSL protocol provides confidentiality and integrity to the data passed between the Netscape Enterprise Server Plug-In and WebLogic Server. In addition, the SSL protocol allows the WebLogic Server proxy plug-in to authenticate itself to the Netscape Enterprise Server to ensure that information is passed to a trusted principal.

The WebLogic Server proxy plug-in does not use the transport protocol (http or https) specified in the HTTP request (usually by the browser) to determine whether or not the SSL protocol will be used to protect the connection between the Netscape Enterprise Server Plug-In and WebLogic Server.

Note: You cannot configure a 2-way SSL between the Netscape Enterprise Server and WebLogic Server. The SSL protocol is a point-to-point connection, cyptographically sealed end-to-end. Therefore, any type of proxy or firewall cannot see into the SSL socket. The Netscape Enterprise Server acts as the server end-point in the SSL connection. The configuration is:

client-->2-way SSL-->NSAPI<--1-way SSL<--WebLogic Server

The Netscape Enterprise Server cannot use the digital certificate from the first SSL connection in the second SSL connection because it cannot use the client's private key.

To use the SSL protocol between Netscape Enterprise Server Plug-In and WebLogic Server:

  1. Configure WebLogic Server for SSL. For more information, see Configuring the SSL Protocol.

  2. Configure the WebLogic Server SSL listen port. For more information, see Configuring the Listen Port.

  3. Set the WebLogicPort parameter in the Service directive in the obj.conf file to the listen port configured in step 2.

  4. Set the SecureProxy parameter in the Service directive in the obj.conf file file to ON.

  5. Set additional parameters in the Service directive in the obj.conf file that define information about the SSL connection. For a complete list of parameters, see SSL Parameters for Web Server Plug-Ins.

Connection Errors and Clustering Failover

When the Netscape Enterprise Server Plug-In attempts to connect to WebLogic Server, the plug-in uses several configuration parameters to determine how long to wait for connections to the WebLogic Server host and, after a connection is established, how long the plug-in waits for a response. If the plug-in cannot connect or does not receive a response, the plug-in will attempt to connect and send the request to other WebLogic Servers in the cluster. If the connection fails or there is no response from any WebLogic Server in the cluster, an error message is sent.

Figure 11-1 demonstrates how the plug-in handles failover.

Connection Failures

Failure of the host to respond to a connection request could indicate possible problems with the host machine, networking problems, or other server failures.

Failure of WebLogic Server to respond, could indicate that WebLogic Server is not running or is unavailable, a hung server, a database problem, or other application failure.

Failover with a Single, Non-Clustered WebLogic Server

If you are running only a single WebLogic Server the same logic described here applies, except that the plug-in only attempts to connect to the server defined with the WebLogicHost parameter. If the attempt fails, an HTTP 503 error message is returned. The plug-in continues trying to connect to WebLogic Server until ConnectTimeoutSecs is exceeded.

The Dynamic Server List

When you specify a list of WebLogic Servers in the WebLogicCluster parameter, the plug-in uses that list as a starting point for load balancing among the members of the cluster. After the first request is routed to one of these servers, a dynamic server list is returned containing an updated list of servers in the cluster. The updated list adds any new servers in the cluster and deletes any that are no longer part of the cluster or that have failed to respond to requests. This list is updated automatically with the HTTP response when a change in the cluster occurs.

Failover, Cookies, and HTTP Sessions

When a request contains a session information stored in a cookie, in the POST data, or by URL encoding, the session ID contains a reference to the specific server in which the session was originally established (called the primary server) and a reference to an additional server where the original session is replicated (called the secondary server). A request containing a cookie attempts to connect to the primary server If that attempt fails, the request is routed to the secondary server. If both the primary and secondary servers fail, the session is lost and the plug-in attempts to make a fresh connection to another server in the dynamic cluster list. For more information see Figure 11-1 Connection Failover.

Figure 11-1 Connection Failover

*The Maximum number of retries allowed in the red loop is equal to
ConnectTimeoutSecs ÷ ConnectRetrySecs.

Failover Behavior When Using Firewalls and Load Directors

In most configurations, the Netscape Enterprise Server Plug-In sends a request to the primary instance of a cluster. When that instance is unavailable, the request fails over to the secondary instance. However, in some configurations that use combinations of firewalls and load-directors, any one of the servers (firewall or load-directors) can 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 is returned to the plug-in as "connection reset".

Requests running through combinations of firewalls (with or without load-directors) are handled by WebLogic Server. In other words, responses of connection reset fail over to a secondary instance of WebLogic Server. Because responses of connection reset fail over in these configurations, servlets must be idempotent. Otherwise duplicate processing of transactions may result.

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.

Note: Make sure that you do not include any extraneous white space in the obj.conf file. Copying and pasting from the samples below sometimes adds extra white space, which can create problems when reading the file.

You can read the full documentation on Enterprise Server configuration files in the Netscape Enterprise Server Plug-In documentation.

## ------------- 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 fails 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/" is 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" are 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 Server cluster. You can use this example as a template that you can modify to suit your environment and server. Lines beginning with # are comments.

Note: Make sure that you do not include any extraneous white space in the obj.conf file. Copying and pasting from the samples below sometimes adds extra white space, which can create problems when reading the file.

For more information, see the full documentation on Enterprise Server configuration files from 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 fails 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.

<Object name="weblogic" ppath="*/weblogic/*">
Service fn=wl_proxy \
 WebLogicCluster="myweblogic.com:7001,yourweblogic.com:7001,\
 theirweblogic.com:7001" PathTrim="/weblogic"
</Object>

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

<Object name="si" ppath="*/servletimages/*">
Service fn=wl_proxy \
WebLogicCluster="myweblogic.com:7001,yourweblogic.com:7001,\
 theirweblogic.com: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" is 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:7001,\
 theirweblogic.com: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 WebLogicCluster="myweblogic.com:7001,\
 yourweblogic.com:7001,theirweblogic.com:7001"
</Object>

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

 

Back to Top