Configuring Domino and the WebSphere Plugin for Microsoft IIS 7.0 or 7.5 

In many environments, it is necessary to use an existing Microsoft IIS server as the front-end Web server for transparently forwarding HTTP requests to a back-end Domino web server, effectively allowing users to access Domino databases through IIS. This is a common scenario when the IIS server is externally accessible and Domino is located in a DMZ or only accessible on the intranet.

Since Domino 6.0, IBM has provided the ability to accomplish this type of configuration by installing the WebSphere Application Server plug-in for IIS on the Microsoft IIS Server. Beginning with Lotus Domino 8.5, IBM now supports Windows Server 2008 and Domino 8.5.2 offers support for Windows Server 2008 R2. These operating systems use the Microsoft IIS 7.0 and 7.5 releases respectively, and the administrative interface for these versions of IIS are significantly different from previous releases. Therefore, this article attempts to organize and demonstrate the steps for setting up the WebSphere Plugin and configuring Domino to work with Microsoft IIS 7.0 or 7.5.

Prerequisites

In order to proceed with the steps below, you will need the IBM WebSphere Application Server Plugin for IIS. Due to the frequency of updates for the WebSphere Plugin, it is no longer possible to provide the latest version with each Domino maintenance release. Therefore, this file no longer ships with Domino servers and must be downloaded from the WebSphere Application Support site.

The easiest method to obtain the plugin is to extract the file from the latest Fix Pack for WebSphere Application Server, which is available for download from the following technote:

Latest fix packs for WebSphere Application Server
http://www-01.ibm.com/support/docview.wss?uid=swg27009661

From the technote above, select the link for the WebSphere Application Server (WAS) version appropriate to your environment. Then, on the subsequent webpage, scroll down to find the table in the download section and select the Windows operating system to see the downloads available. Download the "Plug-ins" package applicable to your processor (i.e. the package titled "32-bit x86 AMD/Intel Plug-ins" or "64-bit x86 AMD/Intel Plug-ins")

You may notice that this Fix Pack was saved as a .pak file, but this file can be extracted in the same manner as a .zip archive. So, after download, expand the file and navigate the folders contained within to find the the plugin applicable to your OS. For example, the WebSphere Plugin for 64-bit Windows can be found using the following path within the Fix Pack:
..\plg.webserverplugins.FP[#].pak\repository\plugins.http\bin\64bits\iisWASPlugin_http.dll

Installing the WebSphere plug-in and configuring an IIS 7.0 or 7.5 server

Do the following to install the WebSphere plug-in on the IIS server and enable it for a Web site.
1) Create the following directory structure on the IIS machine (you may use any drive);

• C:\WebSphere\AppServer\bin
• C:\WebSphere\AppServer\config
• C:\WebSphere\AppServer\etc
• C:\WebSphere\AppServer\logs

2) After downloading the appropriate WebSphere Application Server plugin files using the instructions above (or from this technote), navigate to the appropriate folder to find the needed files for your 32 or 64 bit Windows operating system and copy these files to the IIS server:

• Copy plugin-cfg.xml to C:\WebSphere\AppServer\config
• Copy iisWASPlugin_http.dll to C:\WebSphere\AppServer\bin

3) Create a text file named plugin-cfg.loc in the same directory as the plugin (i.e. C:\WebSphere\AppServer\bin). The plugin-cfg.loc file simply identifies the path to the plugin-cfg.xml file, so you will need to add a line in the plugin-cfg.loc file to point to this location (i.e. C:\WebSphere\config\plugin-cfg.xml). Note: There should only be two lines in the .loc file -- the location of the config file and a blank line (carriage return).

** At this point, you may find it easier to complete the tasks in Configuring the WebSphere plugin below, then begin again with Step 4 in this topic so that the plug-in configuration is complete before you configure IIS. **

4) Open the Internet Information Services (IIS) Manager by navigating to Administrative Tools in the Start menu or by opening the Server Manger and expanding Roles > Web Server (IIS)



5) Create a new Virtual Directory for the Web site instance you want to work with the WebSphere plugin. To do this with a default installation, expand the tree in IIS Manager until you see "Default Web Site." Right click on "Default Web Site" and select "Add Virtual Directory". This opens a dialog for adding a Virtual Directory. IIS normally uses virtual directories to present and access real directories on other machines or outside a service's home directory. In this case, you use a virtual directory to connect IIS to the WebSphere plug-in.

6) In the Add Virtual Directory dialog, enter "sePlugins" in the Alias field (Note: You must use the name sePlugins as the alias; it is the only name that works successfully). In the Physical Directory field, browse to the WebSphere bin directory (C:\WebSphere\AppServer\bin). Click OK and a virtual directory titled "sePlugins" will be added to your default Web site.



7) Verify that the account under which the IIS Admin Service is running has appropriate security permissions to access all of the files in each subdirectory under the WebSphere AppServer directory (C:\WebSphere\AppServer). Otherwise, you will need to select "Connect as" in the Virtual Directory properties and choose an account which does have the appropriate permissions.

8) Select the Web Site instance you are working with from the tree and double-click on "Authentication". Verify that authentication settings are configured to allow anonymous access (Domino will be handling authentication to resources served from the back-end server).






9) Select the Web Site instance you are working with from the tree and double-click on "ISAPI Filters". Click "Add" to open the dialog for adding an ISAPI filter. In the "Filter name" field, enter "iisWASPlugin" and in the "Executable" field, browse to the WebSphere plugin (C:\WebSphere\AppServer\bin\iisWASPlugin_http.dll). Click OK and the ISAPI filter will be added to your default Web site.







10) Select the Web Site instance you are working with from the tree and double-click on "Handler Mappings". Select the ISAPI-dll mapping and, if it is not already enabled, click "Edit Feature Permissions" to open the permissions dialog. Enable the "Execute" checkbox and click OK to activate appropriate permissions for ISAPI filters under this Web Site.





11) To enable the plug-in for additional Web sites, repeat Steps 5 through 10.

12) Navigate to the top of the IIS Manager tree, select the IIS instance, and double-click on "ISAPI and CGI Restrictions". Click "Add" to open the dialog for adding a ISAPI or CGI Restriction. In the "ISAPI or CGI path" field, browse to the WebSphere plugin (i.e. C:\WebSphere\AppServer\bin\iisWASPlugin_http.dll). Make sure that the field "Allow extension path to execute" is checked/enabled and click OK to add the ISAPI filter to the list of "Allowed" ISAPI and CGI extensions.







13) Finally, open the Services Management Console (services.msc) for the machine and restart the "IIS Admin Service" and "World Wide Web Publishing Service" to confirm that all of the above changes have been committed.

Configuring the WebSphere plugin

The WebSphere configuration file (C:\WebSphere\config\plugin-cfg.xml) controls the operation of the plug-in. In order for the plug-in to relay requests to the target Domino server, you must add directives to plugin-cfg.xml to define a transport route to the server, and pattern rules for the URL namespaces that identify requests which are to be relayed to Domino. The plug-in will only relay requests that match a namespace rule. All other requests will be handled by the front-end Web server.

Modifying the plugin-cfg.xml

1) Open plugin-cfg.xml in Notepad.

2) Modify the <Transport> element to target the appropriate Domino server. To do this, change the Hostname and Port parameters to the proper values required for the plug-in to reach your back-end server's HTTP task. For example:

3) Verify the following directives are listed in the "UriGroup" section. These directives specify common URL patterns needed for accessing Domino Web applications. Note: Directives in the URIGroup section are case sensitive.

If your Domino application requires additional namespaces, you can create "Uri Name" directives for those patterns also. For illustration, the following plugin-cfg.xml file from a working environment is available to compare with your current configuration:
Example plugin-cfg.xml

Note: WebSphere plugins automatically reload the configuration file once a minute to pick up changes. If you make a change and do not want to wait that long, you will need to reload the IIS Web server by restarting the World Wide Web Publishing Service from the Windows services control panel, then start the Web site from the IIS Manager. Just stopping and restarting the Web site by itself won't work because the plug-in will not be reloaded.

See the following documentation for other approaches to configuring the plugin-cfg.xml file and additional elements/attributes which can be used to expand the capabilities of the plugin beyond the scope of this article:

Configuring plugin-cfg.xml file for Domino and Domino Web Access to display applets correctly
http://www.ibm.com/support/docview.wss?rs=899&uid=swg21202700

WebSphere Application Server Information Center (Configuring Web server plug-ins > plugin-cfg.xml file)
http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1/topic/com.ibm.websphere.base.doc/info/aes/ae/rwsv_plugin.html

Configuring the Domino server to work with Microsoft IIS

On the backend Domino server, add the following line to NOTES.INI:
HTTPEnableConnectorHeaders=1

This setting enables the Domino HTTP task to process the special headers added by the plug-in to requests. These headers include information about the frontend server's configuration and user authentication status. As a security measure, the HTTP task ignores these headers if the setting is not enabled. This prevents an attacker from mimicking a plug-in.

Other Domino changes:
1) If Domino and IIS share the same machine, you may wish to change the default HTTP port for Domino to an alternate number (for example, 8080) since IIS may be using the default HTTP port of 80. To do so, in the Server document, go to the Ports > Internet Ports > Web section and specify the TCP/IP port number that the Domino HTTP stack should use. If Domino and IIS are on separate, dedicated machines, Domino can use port 80 on its own system and no change in the Server document is needed.

2) Examine the Server document (Internet Protocols > Domino Web Engine tab) and determine if the "Generating References" section should be modified. The information in this section is used by other Domino servers to generate URLs to this server (for example, doclinks and search results). If you would prefer for the IIS hostname, protocol and port to be used when generating these references, you will need to configure this section appropriately. For Domino 6 and later, the setting "Does this server use IIS?" is not used.

Verifying the Configuration

To test the configuration, do the following:

1) Enter the URL for the IIS Web server in your Web browser, for example, http://<servername>.com
2) Verify that the IIS server's home page loads.
3) Append homepage.nsf to the URL in the address bar. If the Domino home page loads, the configuration is successful.