ShowTable of Contents
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.
In order to proceed with the steps below, you will need the IBM WebSphere Application Server plug-in for IIS. Beginning with Domino 8.0, the WebSphere Application Server plugins no longer ship with the Domino server and must be downloaded from the WebSphere Application Support site. For more information, please refer to the following IBM technote:
How can I find a 64 bit or 32 bit iisWASPlugin_http.dll to setup IIS to work with Domino?
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);
2) After downloading the appropriate WebSphere Application Server plugin files using Technote 1367202
mentioned above, 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 the WebSphere bin directory (C:\WebSphere\AppServer\bin). 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 and select the IIS instance. Then, double-click on "ISAPI and CGI Restrictions" and verify that the ISAPI you created in Step 11 was automatically added 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 WebSphere\AppServer\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 frontend Web server.
Modifying the plugin-cfg.xml
1) Open plugin-cfg.xml in Notepad.
2) Modify the 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 backend server's HTTP task. For example:
<!-- Server groups provide a mechanism of grouping servers together. -->
<!-- The transport defines the hostname and port value that the web server
plugin will use to communicate with the application server. -->
<Transport Hostname="mydomino.server.com" Port="81" Protocol="http"/>
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:
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
WebSphere Application Server Information Center (Configuring Web server plug-ins > plugin-cfg.xml file)
Configuring the Domino server to work with Microsoft IIS
On the backend Domino server, add the following line to NOTES.INI:
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.