BEA Logo BEA WebLogic Server Release 5.0

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

Installing the Microsoft-IIS (proxy) Plug-in (ISAPI)

Installing the library
Modifying the IIS setup to proxy to WebLogic
Creating the iisproxy.ini file
Proxying by file extension
Proxying by path
Sample .ini file
Proxying servlets from IIS to the WebLogic Server
Testing the installation
Change history

Described here is how to install and configure the WebLogic plug-in to a Microsoft Internet Information Server. The plug-in allows a smooth integration of WebLogic's HTTP functionality into Microsoft IIS. Using the WebLogic-to-IIS plug-in enhances an existing Microsoft installation by providing a way to access WebLogic's servlet engine transparently.

The plug-in is intended for use in an environment where an IIS 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 still appear to be coming from the same source; WebLogic on the back-end is invisible. The HTTP-tunneling facility of the WebLogic client-server protocol may also operate through the plug-in, providing access to all WebLogic services, not only HTTP servlets.

For the latest support information concerning the WebLogic ISAPI plug-in, see our Platform Support page. Note that the WebLogic ISAPI plug-in does not support virtual hosting.

Installing the library

WebLogic ISAPI is distributed as the dynamic-link library "iisproxy.dll" for NT. This file is located in the weblogic/bin directory of the distribution.

To install the ISAPI plug-in:

  1. Start WebLogic.
  2. Start IIS.
  3. Modify the IIS setup according to the instructions below.
  4. Create an initialization file.
  5. Test the installation.

Modifying the IIS setup to proxy to WebLogic

You will need to configure your IIS installation for use with WebLogic ISAPI.

  1. Start the IIS Internet Service Manager by selecting it in the Microsoft IIS Start menu.

  2. In the left panel of the Service Manager, select your website (the default is "Default Web Site").

    IIS Service Manager

  3. Click the "Play" arrow in the toolbar to start.

  4. Open the properties for the selected website by holding the right mouse button down over the website selection in the left panel. In the Properties panel, select the Home Directory tab, and click the Configuration button in the Applications Settings section.

    Home Directory tab

  5. On the App Mappings tab, click the Add button to add file types and configure them to be proxied to WebLogic.

    Adding a file type for proxying

  6. In the dialog box, browse to find the "iisproxy.dll" file. By default, this file is located in the WebLogic distribution in the weblogic/bin directory. Set the Extension to the type of file that you want to proxy to WebLogic. Unclick the "Script engine" check box. Unclick the "Check that file exists" check box. Set the Method exclusions to suit your installation's security practices.

    Setting up file types for proxy

    When you have finished, click the OK button to save the configuration. Repeat this process for each file type you want to proxy to WebLogic.

    Note that, unlike the NSAPI plug-in that can be configured to serve files based on directory structure, the ISAPI plug-in can only be configured to serve files based on file type (file extension). In general, you will most likely want to configure IIS to proxy files with JHTML and JSP extensions.

    JHTML and JSP configured for proxy

    When you have finished configuring file types, click the OK button to close the Properties panel.

Creating the iisproxy.ini file

You must create an .ini file for the iisproxy.dll. WebLogic Server searches for the iisproxy.ini file by looking in the following directories in the following order:

  1. The same directory where iisproxy.dll is located.

  2. The home directory of the most recent version of WebLogic Server that is referenced in the Windows Registry. If WebLogic Server does not find the iisproxy.ini file there, it continues looking in the Windows Registry for older versions of WebLogic Server and looks for the iisproxy.ini file in the home directories of those installations.

  3. c:\weblogic

The initialization file contains name=value pairs for these variables:

WebLogicHost=domain name
WebLogic host to which HTTP requests should be forwarded. For example, "WebLogicHost=localhost".

Port at which WebLogic host is listening for WebLogic connection requests. For example, "WebLogicPort=7001".

WebLogicCluster=cluster list
List of WebLogic Servers that can be used in a cluster for simple load-balancing. The cluster list is a comma-delimited list of host:port entries, for example ",".

The plug-in will do simple round-robining 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.

Additionally, the plug-in will direct HTTP requests that contain a cookie to the server in the cluster that originally created the cookie.

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. For example, "ConnectTimeoutSecs=20".

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. For example, "ConnectRetrySecs=5".

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

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

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

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

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:, 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.

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.

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.

If wlForwardPath is blank all requests are forwarded to iis.proxy. To forward any requests starting with a particular string, you need to set wlForwardPath. For example: setting wlForwardPath to /weblogic will forward all requests starting with /weblogic to the weblogic server. The default value is "".

Proxying by file extension

The ISAPI module can only proxy files that correspond to the types registered for proxying in the Internet Service Manager. If you have registered types ".jhtml" and ".jsp" for proxying, all requests with the extension ".jhtml" or ".jsp" will be proxied to WebLogic.

Whatever other path information you add to the URL after the server and port is passed directly to WebLogic. For example, if you request a file from IIS with the URL "", it will be proxied to WebLogic with a URL such as:


Proxying by path

To proxy by path use the following steps:

1. Place iisforward.dll in the same directory as iisproxy.dll and add iisforward.dll as a filter service in IIS (WebSite "Properties" -> "ISAPI Filters" tab -> "Add" the iisforward dll).

2. Register .wlforward as a special file type to be handled by iisproxy.dll.

3. Add a property "WlForwardPath" to iisproxy.ini, i.e: WlForwardPath=/weblogic

4. The PathTrim parameter is needed for trimming off the WlForwardPath when necessary. For example, using WlForwardPath=/weblogic, PathTrim=/weblogic will trim a request from IIS to weblogic server and /weblogic/session will become /session.

5. The DefaultFileName parameter should be used if the user wants to have proxied to weblogic server directly.

6. To change the parameters, especially DefaultFileName, Debug, PathTrim, PathPrepend, and WlForwardPath, the user has to restart the "IIS Admin Service" (Under NT services, in the control panel).

7. A "c:\tmp\iisforward.log" will be generated for debugging purpose when "Debug ON" is used in iisproxy.ini.

Sample .ini file

Here is a sample iisproxy.ini file without clustering. Comment lines are denoted with the "#" (hatch) character.

# This file contains initialization name/value pairs
# for the IIS/WebLogic plug-in.

WebLogicHost=localhost WebLogicPort=7001 ConnectTimeoutSecs=20 ConnectRetrySecs=2

Here is a sample iisproxy.ini file with clustering. Comment lines are denoted with the "#" (hatch) character.
# This file contains initialization name/value pairs
# for the IIS/WebLogic plug-in.

WebLogicHost=localhost, ConnectTimeoutSecs=20 ConnectRetrySecs=2

Proxying servlets from IIS to the WebLogic Server

There are three additional steps you must take to proxy servlets to the WebLogic Server:

  1. Register an arbitrary file type (extension) with IIS to proxy the request to the WebLogic Server, as described above under Modifying the IIS setup to proxy to WebLogic.

  2. Register the servlet in the file. For example,
    where virtualName is the virtual name for the servlet and examples.servlets.myServlet is the full package name of the class file to be invoked. For more information on registering servlets, see Registering user-written servlets.

  3. Invoke your servlet with a URL formed according to this pattern:
    where virtualName is the virtual name associated with the servlet in the file. and ext is a file type (extension) registered with IIS for proxying to the WebLogic server. The anyfile part of the URL will be ignored in this context.


    • You must also proxy all image links called from the servlet by registering the appropriate file types (e.g. .gif and .jpg) with IIS.

    • If the servlet being proxied has links that call other servlets, then these links must also conform to the pattern shown above.

Testing the installation

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

  1. Make sure WebLogic and IIS are running.

  2. To test the ISAPI plug-in, save a JSP file into your document root (defaults to weblogic/myserver/public_html). Then open a browser and set the URL to the IIS + filename.jsp as shown in this example:

Change history

Release 4.0.1

Fixed a problem with iisproxy.dll so that it uses the correct WebLogic registry key to locate its configuration file.

Release 4.0.0

Added functionality for simple load-balancing. The configuration information for both can now take an additional parameter, "WebLogicCluster," the value of which is a comma-delimited list of host:port entries, for example ",,". The plug-ins will do simple round-robining between all available cluster members (in this release there is static support only, no dynamic updating of the cluster list is done). 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.

Changed some configuration parameter names for the NSAPI obj.conf and ISAPI iisproxy.ini files from "Tengah" to "WebLogic". This shouldn't require any changes in your code, although we do recommend that you update your development environment. As always, changes are backwards compatible.

Release 3.1.2

First release.


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 04/05/1999