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:
Section 3.1, "Overview of the Oracle iPlanet Web Server Plug-In"
Section 3.2, "Installing and Configuring 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
The following sections provide information pertaining to the installation prerequisites and configuring the Oracle iPlanet Web Server Plug-in.
Before you install the Oracle iPlanet Web Server plug-in, do the following:
Create a plug-in zip extract location (PLUGIN_HOME; for example, /home/myhome/weblogic-plugins-1.1/)
Downloaded 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. This distribution contains these files:
Table 3-1 Files Included in the Oracle iPlanet Web Server Plug-in Zip
| (path)/filename | Description |
|---|---|
|
README.txt |
information specific to the distribution, late-breaking updates, and other errata. |
|
bin/orapki.bat |
orapki tool for configuring Oracle wallets |
|
jlib/*.jar |
orapki helper Java libraries |
|
lib/mod_wl.so(.dll on Windows) |
WebLogic proxy module |
|
lib/*.so(.dll) |
Helper libraries |
Installed JDK 6 if you want to use SSL. You must have a JDK 6 installation if you want to use the orapki utility. The orapki utility manages public key infrastructure (PKI) elements, such as wallets and certificate revocation lists, for use with SSL.
Created a supported Oracle iPlanet Web Server installation (7.0.9 or later) installed on IPLANET_HOME; that is, iPlanet server listening on iplanet-host:iplanet-port.
The version 1.1 plug-in is supported on the Oracle iPlanet Web Server platforms described in: http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html
Created an iPlanet instance location (INSTANCE-DIR; for example, ${IPLANET_HOME}/https-foo.
Created a supported version of WebLogic Server is configured and running on a target system. Note that this server does not need to run on the system to which you extracted the plug-in zip distribution. For the supported WebLogic Server versions, see:
http://www.oracle.com/technology/software/products/ias/files/fusion_certification.html
The Oracle iPlanet Web Server plug-in is distributed as a shared object (.so) for Unix platforms and as a DLL (.dll) for Windows.
To instruct Oracle iPlanet Web Server to load the native library (mod_wl.so on Unix or mod_wl.dll on Windows) as a module, add the following line to the magnus.conf file.
Init fn="load-modules" shlib="mod_wl.so"
or
Init fn="load-modules" shlib="mod_wl.dll"
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
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.5, "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
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
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.
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" and restart the web server. Optionally,
#NameTrans fn="ntrans-j2ee" name="j2ee"
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:
Start WebLogic Server.
Start Oracle iPlanet Web Server. If Oracle iPlanet Web Server is already running, you must either restart or reconfigure the server.
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
The following example demonstrates basic instructions for quickly setting up the iPlanet plug-in to proxy requests to a backend WebLogic Server (WLS).
Edit %IPLANET_INSTANCE_HOME%\config\magnus.conf file and add the following:
... Init fn="load-modules" shlib="%PLUGIN_HOME%\lib\mod_wl.dll" ...
Open the %IPLANET_INSTANCE_HOME%\config\<vs-obj.conf> file (the default is %IPLANET_INSTANCE_HOME%\config\obj.conf) and add the following code:
... <Object name="weblogic" ppath="*/wls/*"> Service fn="wl-proxy" WebLogicHost=<wls-host> WebLogicPort=<wls-port> Debug="ALL" WLLogFile="C:\Temp\wl-proxy.log" DebugConfigInfo="ON" PathTrim="/wls" </Object> ...
For more information on configuring the contents of obj.conf, see Section 3.2.6, "Sample obj.conf File (Not Using a WebLogic Cluster)" and Section 3.2.7, "Sample obj.conf File (Using a WebLogic Cluster)".
At the prompt, include the %PLUGIN_HOME%\lib in the PATH by entering:
set PATH=C:\myhome\weblogic-plugin-1.1\lib:...
Note:
You can also update the PATH by copying the 'lib' contents to IPLANET_HOME\lib or editing the IPLANET_INSTANCE_HOME\bin\startserv.
At the prompt, start the iPlanet server by entering:
%IPLANET_INSTANCE_HOME%\bin\startserv
Send a request to http://iplanet-host:iplanet-port/mywebapp/my.jsp from the browser and validate the response.
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
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---------------------
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--------------------