Table of Contents
Table of Contents
Three files are important: EnhydraFilter.dll, EnhydraHandler.dll, and enhydra_director.conf. These are described below.
This is an ISAPI header preprocessing filter that reroutes Enhydra application URLs to the Enhydra Director ISAPI Handler application. It may be configured either as a global ISAPI filter or as a local filter on a particular web server instance. If configured as a local web server instance, it will only route Enhydra URLs for the configured web server. If the filter is applied globally, then it will reroute Enhydra URLs for all IIS web servers on the system. See below for details on configuring the filter.
This is an ISAPI extension DLL that does the actual work of forwarding an Enhydra request to the correct Enhydra application server. It must be installed on each IIS web server instance that will serve your application's URL prefix. For example, if you have configured IIS to enable the web server 'www.myhost.com', and you want your application to be located at
'http://www.myhost.com/myApp',then you must enable the EnhydraHandler.dll extension on the www.myhost.com Web server instance. See below for details on configuring the handler.
This file contains the configuration for Enhydra Director. If you configured EnhydraFilter.dll as a global filter, then there will only be one instance of this file system-wide that controls the configuration for all IIS web server instances on the system. If the filter was configured for specific servers, then a different instance of this file will exist for each server. The configuration file must be located in the same directory as the EnhydraFilter.dll.
These instructions assume that you will install the EnhydraDirector files into 'C:\EnhydraDirector'. If you wish to install the files in some other location, replace 'C:\EnhydraDirector' with your own installation directory in all of the following steps.
Obtain the Enhydra Director files. Download the ISAPI Enhydra Director ZIP file or build the DLLs from the source code.
Install the Enhydra Director files. If you downloaded the ZIP file, extract its contents into the directory 'C:\EnhydraDirector'. If you built the files from the source code, copy the necessary files to this directory. After building from source, you would copy these files to 'C:\EnhydraDirector': '.../isapi/EnhydraFilter/<Config>/EnhydraFilter.dll'
'.../isapi/EnhydraHandler/<Config>/EnhydraHandler.dll'
'.../isapi/enhydra_director.conf.default'
The'<Config>' token should be replaced with 'Debug' or 'Release', depending upon which configuration you used when building from the source.
When you are finished extracting or copying the files, the directory 'C:\EnhydraDirector' will contain the following files: EnhydraFilter.dll EnhydraHandler.dll enhydra_director.conf.default
Table of Contents
Open the 'Services' dialog from the Control Panel, Start->Settings->Control Panel, then double click 'Services'. - Find the entry for 'World Wide Web Publishing Service' and select it. - Click 'Stop' to stop the 'World Wide Web Publishing Service'. This will stop IIS.
If you are installing the filter globally, follow this procedure. If you are installing for a specific server, see the next section.
Start the IIS InternetServiceManager program:Start->Programs->Windows NT 4.0 Option Pack-> Microsoft Internet Information Server-> Internet Service Manager
In the tree-view pane containing the folder 'Console Root', expand the sub-folder 'Internet Information Server' if it has not already been expanded. You should see a small computer icon next to the name of your machine.
Right click on the name of your machine. (NOT 'Default Web Site'!) You should now see a pop-up menu with a number of choices, including 'Properties'.
Click the 'Properties' menu item. This will bring you to the dialog box '* <YourServerName> Properties'.
In the 'Master Properties' frame, Select 'WWW Service' in the selection box, and then click 'Edit' to edit the master IIS properties for your machine. This will bring up the 'WWW Service Master Properties for <YourServerName>' dialog box.
Select the 'ISAPI Filters' tab in this dialog box.
If the 'EnhydraFilter' filter is already installed, remove it.
Click 'Add...'. This brings you to the 'Filter Properties' dialog box.
For the 'Filter Name' property, enter 'EnhydraFilter'.
For the 'Executable' property, type in or browse for the file 'C:\EnhydraDirector\EnhydraFilter.dll'.
Click 'OK' to accept the filter name and executable.
Back in the 'WWW Service Master Properties' dialog box, click 'Apply' to add the filter. The filter will NOT become active until IIS is restarted. (later)
Click 'OK' in the 'WWW Service Master Properties' dialog box to dismiss it.
The filter is now installed and will become active when IIS is restarted.
Start the IIS Internet Service Managerprogram:Start->Programs->Windows NT 4.0 Option Pack-> Microsoft Internet Information Server-> Internet Service Manager
In the tree-view pane containing the folder 'Console Root', expand the sub-folder 'Internet Information Server' if it has not already been expanded. You should see a small computer icon next to the name of your machine.
Right click on the entry for your web site instance, or on 'Default Web Site' for the IIS default web site instance. You should now see a pop-up menu with a number of choices, including 'Properties'.
Click the 'Properties' menu item. This will bring you to the dialog box 'Default Web Site Properties'.
Select the 'ISAPI Filters' tab in this dialog box.
If the 'EnhydraFilter' filter is already installed, remove it.
Click 'Add...'. This brings you to the 'Filter Properties' dialog box.
For the 'Filter Name' property, enter 'EnhydraFilter'.
For the 'Executable' property, type in or browse for the file 'C:\EnhydraDirector\EnhydraFilter.dll'.
Click 'OK' to accept the filter name and executable. - Back in the 'Default Web Site Properties' dialog box, click 'Apply' to add the filter.
Click 'OK' in the 'Default Web Site Properties' dialog box to dismiss it.
Repeat as needed for multiple IIS web sites.
Start the IIS Internet Service Managerprogram:Start->Programs->Windows NT 4.0 Option Pack-> Microsoft Internet Information Server-> Internet Service Manager
In the tree-view pane containing the folder 'Console Root', expand the sub-folder 'Internet Information Server' if it has not already been expanded. You should see a small computer icon next to the name of your machine. Underneath this, you should see entries for your web site(s). If you only have one web site on this system, it will usually be set up as 'Default Web Site'. - Expand the sub-tree for the web site.
If a virtual directory called 'EnhydraDirector' already exists, remove it.
Right click 'Default Web Site' (or the name of analternate web site) and select'New->Virtual Directory' from the pop-up menu. This will Bring you to the 'New Virtual Directory Wizard'.
The 'alias' to use for the virtual directory MUST be 'EnhydraDirector'. Case is important!
Click 'Next' in the wizard.
For the physical path, type in or browse, and enter 'C:\EnhydraDirector'.
Click 'Next' in the wizard.
For the permissions, check the 'Allow Execute Access' and uncheck all other permissions. The 'execute' permission MUST be checked in order for the handler to work properly.
Click 'Finish' to add the new Virtual Directory.
The handler is now installed for the selected WWW server instance. Repeat Step 3 for each WWW server on which you intend to use Enhydra Director.
Create the file 'C:\EnhydraDirector\enhydra_director.conf'. The easiest way to do this is to copy the 'enhydra_director.conf.default' file to 'enhydra_director.conf'. The full description of the syntax and all of the directives available in the configuration file is beyond the scope of this document. However, the default file contains several useful examples that can be easily copied to match your site setup. The comments within the default file also describe most of the available options. An important thing to note is that the configuration file is based on an XML DTD (EnhydraDirectorConfig.dtd) and is strictly validated. This means the the file MUST contain valid XML, and it MUST follow the format defined in the DTD. Case is important in all section and property names, and order is important among different sections.
Open the 'Services'dialogfromtheControlPanel.Start->Settings->Control Panel, then double click 'Services'. - Find the entry for 'World Wide Web Publishing Service' and select it. - Click 'Start' to start the 'World Wide Web Publishing Service'. - IIS should now be running.
Run the 'EventViewer'Start->Programs->AdministrativeTools(Common)->Event Viewer. - Check the 'Application' log for EnhydraFilter events. You should see an event from the filter indicating that it processed the configuration file successfully.
Start up a web browser.
If you have configured a <Status> section in the configuration, you can connect to its URL prefix to ensure that the handler is functioning. See the default configuration file for more information on the <Status> section.
Connect to one of your configured application prefixes.
If connection errors occur, they are logged to the Application event log and can be viewed with the 'Event Viewer'.
Table of Contents
Check that the IIS configuration has the right path for the filter DLL.
Check the 'Application' event log for errors reported by the filter or by IIS.
Ensure that the enhydra_director.conf file exists and contains valid and syntactically correct configuration data. If the syntax is not valid, the filter should report the specific errors and line numbers to the Application event log.
Check the application event log for EnhydraHandler error reports.
If you configured the <Status> section, check the status prefix for connection failures to your back-end Enhydra servers.
Make sure that the prefixes configured in enhydra_director.conf match the prefixes configured for your application on the Enhydra server. The prefixes MUST match EXACTLY, including case! Trailing slashes in the prefix are not significant and are ignored.
Make sure that the application servers and ports in the enhydra_director.conf file refer to valid and running instances of your application.
Make sure your application is running on the Enhydra server.
You application must use the 'EnhydraDirector' connection method on ports that the IIS handler will dispatch requests to.
It is highly recommended to configure the '<Status>' section in the configuration file so you can examine the runtime state and configuration of the handler.
This a Windows NT problem that happens right after you first install an application that registers itself with the event logger. If you reboot Windows NT this problem goes away.
You are trying to run a 'Debug' compiled version of the filter or handler, and do not have the Debug runtime libraries installed. These libraries come with Microsoft Visual C++.
This is evidence of an error in the handler or filter DLL that needs the attention of the Together company.
There's also the possibility that there is a bug in IIS.
Please report any bugs of this nature at www.enhydra.org. The more details you can provide about what led to the failure, the better. Also, machine state information and configuration information is helpful.
If you have a way to reproduce the bug consistently, PLEASE include the necessary steps to do so if it is at all possible.