3 Installing and Configuring the Oracle iPlanet Web Server Plug-In

This chapter describes how to install and configure the Oracle iPlanet Web Server plug-in. In previous releases, this plug-in was referred to as the Netscape Enterprise Server plug-in.

This chapter contains the following sections:

3.1 Overview of the Oracle iPlanet Web Server Plug-In

The Oracle iPlanet Web Server plug-in enables requests to be proxied from Oracle iPlanet Web Server to Oracle WebLogic Server. The plug-in enhances a Oracle iPlanet Web Server installation by allowing WebLogic Server to handle those requests that require the dynamic functionality of WebLogic Server.

The Oracle iPlanet Web Server plug-in is designed for an environment where Oracle iPlanet Web Server serves static pages, and an Oracle WebLogic Server instance (operating in a different process, possibly on a different machine) is delegated to serve dynamic pages, such as JSPs or pages generated by HTTP Servlets. The connection between WebLogic Server and the Oracle iPlanet Web 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 WebLogic Server can operate through the Oracle iPlanet Web Server plug-in, providing access to all WebLogic Server services (not just dynamic pages).

The Oracle iPlanet Web Server plug-in operates as a module within a Oracle iPlanet Web Server. The module is loaded at startup and later based on the configuration, certain HTTP requests are delegated to it.

For more information about Oracle iPlanet Web Server see, http://download.oracle.com/docs/cd/E18958_01/doc.70/e18789/chapter.htm

3.2 Installing and Configuring the Oracle iPlanet Web Server Plug-In

The following sections provide information pertaining to the installation prerequisites and configuring the Oracle iPlanet Web Server Plug-in.

3.2.1 Installation Prerequisites

Before you install the Oracle iPlanet Web Server plug-in, you must satisfy the following prerequisites:

  • Download the Oracle iPlanet Web Server plug-in, as described in Section 1.2, "Availability of Version 1.1 Plug-Ins."

  • Extract the plug-in zip distribution into the Web Server installation directory install-dir. Before extracting the plug-in zip distribution, rename the existing README.txt within install-dir.

  • Install JDK 6 if you want to use SSL. The JDK 6 installation is required for orapki utility. The orapki utility manages public key infrastructure (PKI) elements, such as wallets and certificate revocation lists, for use with SSL.

3.2.2 Installing Oracle iPlanet Web Server Plug-In

The Oracle iPlanet Web Server plug-in is distributed as a shared object (.so) for Unix platforms and a DLL for Windows.

  • Instruct Oracle iPlanet Web Server to load the native library (the mod_wl.so) file on Unix or mod_wl.dll file on Windows) as a module.

    Add the following line to the magnus.conf file.

    Init fn="load-modules" shlib="mod_wl.so"
    

These lines instruct Oracle iPlanet Web Server to load the native library (the mod_wl.so file on Unix or mod_wl.dll file on Windows) as a module. The magnus.conf file is located in the INSTANCE-DIR/config directory. Where INSTANCE-DIR is the web server instance directory. For more information, see

http://download.oracle.com/docs/cd/E19146-01/821-1827/821-1827.pdf

3.2.3 Configuring the Oracle iPlanet Web Server Plug-In

This section provides information about configuring the Oracle iPlanet Web Server plug-in.

Locate and open the obj.conf file

The default obj.conf file is located in the INSTANCE-DIR/config directory. Where INSTANCE-DIR is the web server instance directory.
For more information, see

http://download.oracle.com/docs/cd/E19146-01/821-1827/821-1827.pdf

There are different ways to configure obj.conf file.

Read guidelines for Section 3.2.4, "Guidelines for Modifying the obj.conf File". The obj.conf file defines which requests are proxied to WebLogic Server and other configuration information.

  • If you want to proxy requests by URL, (also called proxying by path.) create a separate <Object> tag for each URL that you want to proxy and define the PathTrim parameter. The following is an example of an <Object> tag that proxies a request containing the string */weblogic/*

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

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 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 Oracle iPlanet Web Server plug-in. For a complete list of plug-in parameters, see Section 8.2, Section 7.1, "General Parameters for Web Server Plug-Ins"

  • If you are proxying requests by MIME type, add any new MIME types referenced in the obj.conf file to the mime.types file. You can add MIME types by using the iPlanet server console or by editing the mime.types file directly.

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

type=text/jsp exts=jsp

Note:

iPlanet Web Server 7.0.9 and above, already defines the MIME type for JSPs. Change the existing MIME type from magnus-internal/jsp to text/jsp.

To edit the mime.types file in the iPlanet Administration console, see

http://download.oracle.com/docs/cd/E19146-01/821-1828/gdabr/index.html

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

For example, to proxy all JSPs to a WebLogic Server, the following Service directive should be added:

Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl-proxy WebLogicHost=myserver.com 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://myserver.com: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 Oracle iPlanet Web Server plug-in, the default Object definition will be similar to the following example:

<Object name="default">
AuthTrans fn="match-browser" browser="*MSIE*" ssl-unclean-shutdown="true"
NameTrans fn="pfx2dir" from="/mc-icons" dir="/export/home/ws/lib/icons" name="es-internal"
PathCheck fn="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|POST|PUT)" type="text/jsp" fn="wl-proxy" WebLogicHost="myweblogic.server.com" WebLogicPort="7100"
Service method="(GET|HEAD)" type="magnus-internal/directory" fn="index-common"
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
Service method="TRACE" fn="service-trace"
AddLog fn="flex-log"
</Object> 

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

For proxy-by-MIME to work properly you need to disable JAVA from the Oracle iPlanet Web Server otherwise, SUN One will try to serve all requests that end in *.jsp and will return a 404 error as it will fail to locate the resource under $doc_root.

To disable JAVA from the Oracle iPlanet Web Server, comment out the following in the obj.conf file under the name= "default"
#NameTrans fn="ntrans-j2ee" name="j2ee"
and restart the web server.

  • Optionally, if you are proxying by path, enable HTTP-tunneling.

    If you are using weblogic.jar and tunneling the t3 protocol, 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=myserver.com WebLogicPort=7001
    </Object>
    
  • If you are tunneling IIOP, which is the only protocol used by the WebLogic Server thin client, wlclient.jar, 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="*/iiop*">
    Service fn=wl-proxy WebLogicHost=myserver.com WebLogicPort=7001
    </Object>
    

To test the Oracle iPlanet Web Server plug-in:

  1. Start WebLogic Server.

  2. Start Oracle iPlanet Web Server. If Oracle iPlanet Web Server is already running, you must either restart or reconfigure the server.

  3. You can test the Oracle iPlanet Web Server plug-in using the following URL. It should bring up the default WebLogic Server HTML page, welcome file, or default servlet, as defined for the default Web Application as shown in this example

http://webserver_host:webserver_port/weblogic/

For information on how to create a default Web Application, see Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server

3.2.4 Guidelines for Modifying the obj.conf File

To use the Oracle iPlanet Web Server plug-in, you must make several modifications to the obj.conf file. For more information, see

http://download.oracle.com/docs/cd/E19146-01/821-1827/821-1827.pdf

3.2.5 Sample obj.conf File (Not Using a WebLogic Cluster)

Below is an example of lines that 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.

  • Proxy requests by URL

    ## --------------BEGIN SAMPLE obj.conf CONFIGURATION---------
    # (no cluster)
    # Configure which types of HTTP requests should be handled by the
    # iPlanet NSAPI plug-In (and, in turn, by WebLogic). This is done 
    # with one or more "<Object>" tags as shown below. 
    # Here we configure the iPlanet plug-In module to pass requests for
    # "/weblogic" to a WebLogic Server listening at port 7001 on
    # the host myweblogic.server.com.
    <Object 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=myweblogic.server.com WebLogicPort=7001
    </Object>
    ## -------------END SAMPLE obj.conf CONFIGURATION-------------------
    
  • Proxy requests by MIME type

    This Object directive works by file extension rather than
    # request path. To use this configuration, you must modify the existing line or add the following line to mime.types file.
    
    ## -----------BEGIN SAMPLE mime.types CONFIGURATION---------------------
    #
    # type=text/jsp exts=jsp
    ## ------------END SAMPLE mime.types CONFIGURATION----------------------
    
    ## -------------BEGIN SAMPLE obj.conf CONFIGURATION---------------------
    # 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:/Export/Home/ns-icons"
    NameTrans fn=pfx2dir from=/mc-icons dir="c://Export/Home/ns-icons"
    NameTrans fn="pfx2dir" from="/help" dir="c:/Export/Home/manual/https/ug"
    NameTrans fn=document-root root="c:/Export/Home/docs"
    Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl_proxy WebLogicHost=myweblogic.server.com 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 iPlanet plug-in.
    <Object name="tunnel" ppath="*/HTTPClnt*">
    Service fn=wl-proxy WebLogicHost=myweblogic.server.com WebLogicPort=7001
    </Object>
    #
    ## -------------END SAMPLE obj.conf CONFIGURATION---------------------
    

3.2.6 Sample obj.conf File (Using a WebLogic Cluster)

Below is an example of lines that 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.

  • Proxy requests by URL

    ## -------------BEGIN SAMPLE obj.conf CONFIGURATION-------------------
    # (using a WebLogic Cluster) 
    # 
    # Configure which types of HTTP requests should be handled by the
    # iPlanet module (and, in turn, by WebLogic). This is done 
    # with one or more "<Object>" tags as shown below. 
    # Here we configure the iPlanet module to pass requests for
    # "/weblogic" to a cluster of WebLogic Servers.
    <Object 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>
    ## ----------------END OF SAMPLE obj.conf CONFIGURATION------------------
    
  • Proxy requests by MIME types

    # This Object directive works by file extension rather than
    # request path. To use this configuration, you must modify the existing line or add the following line to mime.types file.:
    ## -----------------BEGIN SAMPLE mime.types FILE -------------------------
    # type=text/jsp exts=jsp
    # 
    ## --------------------END SAMPLE mime.types------------------------------
    
    ## -------------BEGIN SAMPLE obj.conf CONFIGURATION-----------------------
    # 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:/Export/Home/ns-icons"
    NameTrans fn=pfx2dir from=/mc-icons dir="c:/Export/Home/ns-icons"
    NameTrans fn="pfx2dir" from="/help" dir="c://Export/Home/manual/https/ug"
    NameTrans fn=document-root root="c://Export/Home/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 NES 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--------------------