Using Enhydra Director

This document describes the steps required to install and configure Enhydra Director. For the most up-to-date information on Director, see the Enhydra Director Working Group.

System Requirements

Director runs on Windows NT, Solaris, and Linux.  Additionally, if you build Enhydra from the open source distribution, the Director module should compile and run on most Unix systems supported by Netscape/IPlanet web servers.

Note: Enhydra Director requires TCP/IP networking support.  If you have not already done so, configure TCP/IP on at least one of your system's network interfaces.

Windows NT

Solaris

Linux

Preparation

Before installing Enhydra Director, determine the following:

Using Director with IPlanet Web Server

Installation

Installation of this module follows the same general procedure as with any other NSAPI extension to a Netscape Web server, so the Netscape online documentation at http://www.iplanet.com may be useful as well.

Files

NSAPI Extension: libedir.so (Unix versions) or NSAPI Extension: EnhydraDirector.dll (Windows NT version)
This is an NSAPI extension DLL that does the actual work of forwarding an Enhydra request to the correct Enhydra application server. It must be installed on each IPlanet web server instance that will serve your application's URL prefix. For example, if you have set up IPlanet 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 EnhydraDirector.dll extension in the 'obj.conf' configuration for the the www.myhost.com Web server instance. See below for details on configuring this module.

Enhydra Director Configuration File: enhydra_director.conf This file contains the configuration for Enhydra Director. One of the required settings in 'obj.conf' is the location of this file.

Procedure for Unix Systems

These instructions assume that you will install the EnhydraDirector files into '/usr/netscape/EnhydraDirector'. If you wish to install the files in some other location, replace '/usr/netscape/EnhydraDirector' with your own installation directory in all of the following steps.
 
  1. Download the NSAPI Enhydra Director 'tar.gz' source code archive and build the extension shared object '.so' file.
    The build uses a GNU 'automake' environment, so you begin building by running the 'configure' script. Type 'configure --help' to get a list of supported options.
    If you have installed Netscape Server in a non-standard directory you will need to use the '--with-netscape-plugins-dir' option to specify where the include 'plugins' directory is for your server. Also, the '--enable-debugging' option may be used to add full verbose debugging macros to the build.
    When you are finished building, you should have the following files: ./.libs/libedir.so, ./enhydra_director.conf.default.
  2. Install the Enhydra Director files.
    Assuming you have chosen the recommend directory '/opt/netscape/EnhydraDirector', install the files you built above as: /opt/netscape/EnhydraDirector/libedir.so /opt/netscape/EnhydraDirector/enhydra_director.conf.default

Procedure for Windows NT

These instructions assume that you will install the EnhydraDirector files into 'C:\Netscape\EnhydraDirector'. If you wish to install the files in some other location, replace 'C:\Netscape\EnhydraDirector' with your own installation directory in all of the following steps.
  1. Obtain and build the Enhydra Director files. *OR* Download precompiled binaries. Download the NSAPI Enhydra Director 'zip' source code archive and build the extension shared object '.so' file. If you don't have Microsoft Visual C++ 6.0 or later, you should obtain the precompiled NSAPI extension DLL from your Enhydra distribution or from the Enhydra.org web site. To build the Windows NT version of the NSAPI module, start Visual Studio, and open the Enhydra Director NSAPI workspace: <EnhydraSrc>/modules/EnhydraDirector/src/nsapi/EnhydraDirector.dsw
  2. Set 'EnhydraDirector' as the active project, then set the active configuration to 'Debug' or 'Release' according to your needs. If you installed Netscape server in a non-default location, you also need to edit the build settings (C Preprocessor) to set the correct 'include' directories for the netscape header files. At this point, just do a 'Build All' and rebuild the DLL. In the same directory as the workspace, there is a copy of 'enhydra_director.conf.default'. The newly built DLL will be found in the 'Debug' or 'Release' subdirectory, according to the usual Visual Studio convention.
  3. Install the Enhydra Director files. Regardless of how you obtain the final DLL and files, install: C:\EnhydraDirector\EnhydraDirector.dll C:\EnhydraDirector\enhydra_director.conf.default

Configuring Director for IPlanet

  1. Stop the Netscape Web Server - Run the 'stop' script in the '/usr/netscape/server4/<instance>' or in 'C:\Netscape\Server4\<instance>'.
  2. Install the NSAPI extension. (Repeat as needed for multiple web sites).
  3. Edit obj.conf and go the the lines where the '<Init...>' sections are located. This should be near the beginning of the file.
  4. Now, in the '<Objectname= default>'section,add the line: NameTrans fn= edir_nsapi_name_trans. The above line must go immediately before: NameTrans fn= document-root root= .....
  5. Finally, just after theclosing </Object> for <Objectname= default>, addthe section: <Object name= enhydra_director> Service fn="edir_nsapi_handler" method= (GET|HEAD|POST) </Object>
  6. Create the configuration file. The Enhydra Director configuration file for NSAPI is the file indicated by the "conffile=..." directive in the 'Init' lines described above. There can be multiple instances of Enhydra Director on a machine, with one instance per configured Web server instance. Each Enhydra Director instance should be assigned a different configuration file. 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 file 'enhydra_director.conf.default' 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.
  7. Start the Netscape server.  Run the 'start' script in the '/usr/netscape/server4/<instance>' or in'C:\Netscape\Server4\<instance>'.
  8. Verify correct startup. Make sure the Netscape server started correctly and is running. Check the Netscape server error log for errors that might have occured while loading the Enhydra Director DLL. Also check for Enhydra Director errors.
  9. Verify connectivity

Troubleshooting

Problem: The NSAPI extension fails to load when Netscape server is started. Problem: Enhydra Director starts up OK, but I can't connect to my application. Problem: The Netscape server crashes, hangs, or dies unexpectedly.

Using Director with Internet Information Server

Installation

Three files are important: EnhydraFilter.dll, EnhydraHandler.dll, and enhydra_director.conf.  These are described below.

ISAPI Filter: EnhydraFilter.dll

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.

ISAPI Handler Extension: EnhydraHandler.dll

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.

Enhydra Director Configuration File: enhydra_director.conf

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.

Procedure

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.
  1. Obtain the Enhydra Director files. Download the ISAPI Enhydra Director ZIP file or build the DLLs from the source code.
  2. 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

Configuring Director for IIS

Step One: Stop IIS

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.

Step Two: Install the filter (global)

If you are installing the filter globally, follow this procedure.  If you are installing for a specific server, see the next section.

Step 2: Install the filter (for a specific server)

Step 3: Install the handler.

Repeat as needed for multiple IIS web sites.
 

Step 4: Create the configuration file.

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.

Step 5: Start IIS

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.

Step 6: Verify correct startup.

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.

Step 7: Verify connectivity

Troubleshooting

Problem: EnhydraFilter.dll fails to load when IIS is started.


Problem: The Filter starts up OK but I can't connect to my application.

Problem: The Event Log messages contain no new lines.
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.

Problem: MSVCRTD.DLL not found
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++.

Problem: IIS crashes with "Unhandled Exception", or the Web Application Manager reports that the handler is dying.

Using Director with Apache

Files

This section describes the files you use with Apache.

Apache extension module

 The Apache extension module is mod_enhydra_director.so. It is in the Apache libexec directory and is loaded with the AddModule and LoadModule directives in httpd.conf. It does the work of forwarding application requests to the Enhydra server and of forwarding the server response to the client.

Enhydra Director Configuration File

This file, enhydra_director.conf, contains the configuration for Enhydra Director. By default, the Apache extension module described above looks for this file in the same directory as the httpd.conf file.

The Enhydra Director Daemon

This program, edir_daemon, runs in the background and monitors the state of the shared memory region that is used by child instances of the module to coordinate load balancing. This is needed in Apache because it uses many separate processes to allow multithreading of simultaneous requests. The daemon is automatically launched when Apache starts, and automatically cleans up the shared memory and exits when Apache is stopped.

The Enhydra Director Status Utility

This utility, edir_status, directly reads the shared memory region used by the Enhydra Director module. It reports the current state of each configured application and Enhydra server.

Enhydra Director Scoreboard

The scoreboard, enhydra_director.ipc, contains the shared memory data used by all of the apache child processes when they are handling Enhydra Director requests. Normally, the contents of this file are kept in memory as an mmap( ) based shared memory region. This file also serves as the scoreboard lock file, using fcntl() based locking. Its normal home ins in edir subdirectory of the Apache logs directory. It is normally only accessible to the Apache child user id.

Apache Error Log

The standard error log for the apache server is typically called error_log. Enhydra Director handler logs all errors encountered while handling requests to this file. Certain startup messages are also logged to this file, however the Enhydra Director Daemon logs most startup errors to the system log.

System Log

The system log is typically in /var/log/messages or /var/adm/messages. If the daemon encounters errors while it is initializing it has no access to the Apache error log, so it logs the error to the system log using the 'daemon' logging channel.

Procedure

These instructions assume that you will install the Enhydra Director files into your Apache installation directories. To build, you must first obtain, build, and install Apache 1.3.9 or later. You must configure Apache so that DSO support (mod_dso) is enabled. The build scripts use the Apache 'apxs' utility to automatically obtain the correct installation directories for the Enhydra Director components, so you should take not of where this utility is installed. Finally, you should make sure that Perl 5 is installed, since apxs is a perl script.

Step 1: Get Enhydra Director source code

The Enhydra Director source code is available under the Enhydra Public License (EPL) and is included with the full Enhydra source distribution. A smaller source distribution containing only the source code of Enhydra Director is included with the pre-built distributions of Enhydra 3.0. Obtain the Enhydra Director source code from either of the above sources and extract it into a working directory.

If you are using the Enhydra full source tree: Extract 'enhydra-src3.0.tar.gz' into the current directory. You will find the Enhydra Director source in: Enhydra/modules/EnhydraDirector/src/

If you are using the Enhydra pre-built distribution: Extract 'lutris-enhydra3.0.tar.gz' or 'lutris-enhydra3.0.zip'. The Enhydra Director source archive is in: ./director/enhydra-director1.0.tar.gz or ./director/enhydra-director1.0.zip Change directory to ./director and extract one of the above archives into the current directory.

The extracted source code will be in: ./enhydra-director1.0 From where you extracted the Enhydra distribution: ./director/enhydra-director1.0

Now, change directory to the newly extracted Enhydra Director source code directory root. This is the directory named 'src' that contains the subdirectories 'common', 'apache', 'nsapi, etc. From this point on we will call this directory '$SRCROOT'

Step 2: Build the Enhydra Director Apache module

If you installed Apache in the default location on either Solaris or Linux, this step should be easy. Just run the './configure' script with no arguments:
cd $SRCROOT/apache ./configure make make install

This will build the Enhydra Director Apache module and install the 'mod_enhydra_director.so' file into the 'libexec' directory for your Apache distribution.

Option for 'configure': --with-apxs=/full/path/to/program/apxs This option allows the location of the Apache 'apxs' script to be specified if the default configure script cannot find it.

Option for 'configure': --enable-debugging Adds debugging messages to the build. This allows the 'EnhydraDirectorDebug' option to be specified in 'httpd.conf', or <Options debug="0xNNNNNN"/> to be specified in 'enhydra_director.conf' Enabling debugging can be useful if you experience problems with setting up the module.

After running 'make install', you will find 'mod_enhydra_director.so' in your Apache installation's 'libexec' directory. You will also find the file 'enhydra_director.conf.default' in the 'conf' directory.

Note: If you like doing things the hard way:  Install the 'edir_daemon', 'edir_status', and 'enhydra_director.conf' files wherever you like. Install the 'mod_enhydra_director.so' file in the 'libexec' directory for your Apache installation. The 'libexec' directory may not be named 'libexec' on all installations. It's much easier to just './configure' and 'make install', using the --with-apxs if necessary to locate the 'apxs' script.

Use the following 'httpd.conf' options to specify the locations of Enhydra Director configuration and data files.

Configuring Enhydra Director

Step One

Find out where 'httpd.conf' is located for your Apache installation. Usually this is something like '/usr/local/apache/conf/httpd.conf'. However, Apache is very flexible in how it can be installed, so this may differ. The build scripts use 'apxs' to automatically install the compiled module and programs into the recommended locations.

Step Two

Determine where Apache stores its DSO modules. This is usually 'libexec' under the Apache installation root. For example, on many Apache installations, the DSO module directory is '/usr/local/apache/libexec'. Take note of the 'libexec' part. This may be something else like 'sbin' or 'modules'. You will need this when configuring the 'LoadModule' line in 'httpd.conf'.

Step Three

Add the Enhydra Director module to the Apache configuration.

Step 4

Create the Enhydra Director configuration file. The Enhydra Director configuration file for Apache is normally located in the same directory as 'httpd.conf'. However, you can specify the 'EnhydraDirectorConfigFile' directive in httpd.conf to specify a different file.

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 file 'enhydra_director.conf.default' 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.
 

Step 5: Restart the Apache server.

Use the 'apachectl' script, or your own script, to restart the apache server. The easy way is 'apachectl restart'.
 

Step 6: Verify correct startup.

  1. Use 'ps -aef' or 'ps -ax' (depending on your system) to make sure 'edir_daemon' is running.
  2. In the Apache logs directory, there should be a subdirectory called 'edir' that should contain the file 'enhydra_director.ipc'. This file is the lock and scoreboard file.
  3. In the Apache 'bin' directory, where 'httpd' is located, run 'edir_status'. This should dump out the configuration in 'enhydra_director.conf' If this succeeds, Enhydra Director is running.
  4. If errors occur withing the 'edir_daemon' process, the errors are logged to the system log using 'syslog()'. The 'daemon' channel is used. Normally the messages go to the 'messages' file, which is '/var/adm/messages' on Solaris, and '/var/log/messages' on Linux.
  5. If initialization errors occur within the module, the errors are reported in the Apache error log.
Step 7: Verify connectivity
  1. Start up a web browser.
  2. 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.
  3. Connect to one of your configured application prefixes.
  4. Errors encountered while handling requests are reported in the Apache error log.

Troubleshooting

Problem: The apache extension fails to load when Apache is started.


Problem: Enhydra Director starts up OK but I can't connect to my application.


Problem: Apache child processes dump core. (crash)

Configuring Your Application

The following procedure assumes that you are using the Multiserver Administration console to add the connections for the application.
  1. Create Enhydra Director connections for your application. - Bring up the MultiServer Administration page for your Enhydra server instance.
  2. Select your application in the application list.
  3. Click on the 'Connections' tab to manage connections for your application instance.
  4. Within the 'Connections' tab, click 'Create'. A 'new connection' dialog box will appear.
  5. In the dialog box, check 'EnhydraDirector' as the connection type.
  6. Fill in the URL prefix and port. Also, if session affinity is NOT to be enabled, change the session affinity box from 'true' to 'false'.
  7. Click 'OK' to accept the new connection.
    In the main MultiServer admin page, click the 'Save State' floppy-disk icon to save your changes to the MultiServer configuration file. Click 'OK' to accept the rewrite of the configuration file.