Using Director with IPlanet Web Server


Table of Contents

1. Installation
Files
Procedure for Unix Systems
Procedure for Windows NT
2. Configuring Director for IPlanet
3. 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.

Chapter 1. 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.

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

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

  • 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  

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

  • 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

Chapter 2. Configuring Director for IPlanet

  • Stop the Netscape Web Server - Run the 'stop' script in the

     '/usr/netscape/server4/<instance>'  
    or in
     'C:\Netscape\Server4\<instance>' 

  • Install the NSAPI extension. (Repeat as needed for multiple web sites).

  • Edit obj.conf and go the the lines where the '<Init...>' sections are located. This should be near the beginning of the file.

    • For Unix, add the following 'init' lines:

       Init fn="load-modules" 
       	funcs="edir_init,edir_nsapi_handler,edir_nsapi_name_trans" 
       	shlib= "/usr/netscape/EnhydraDirector/libedir.so"
       	Init fn= "edir_init"
       	conffile="/usr/netscape/server4/<Instance>/config/enhydra_director.conf"  

    • For Windows NT, add the following 'init' lines:

       Init fn="load-modules" 
       	funcs="edir_init,edir_nsapi_handler,edir_nsapi_name_trans" 
       	shlib="C:\Netscape\EnhydraDirector\EnhydraDirector.dll" 
       	Init fn= "edir_init"
       	conffile= "C:\Netscape\Server4\<Instance>\config\enhydra_director.conf"  

      Note: The above entries must consist of only two actual lines in the 'obj.conf' file. They are split to fit in the available horizontal space.

      Note: If your Netscape server is not installed in /usr/netscape, or you did not install the 'libedir.so' DLL in the recommended location,then edit the above lines accordingly.

      Note: Replace <Instance> with the webserver instance for which you are configuring.

  • 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= .....

  • Finally, just after the closing </Object> for <Objectname= default>, addthe section: <Object name= enhydra_director> Service fn="edir_nsapi_handler" method= (GET|HEAD|POST) </Object>

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

  • Start the Netscape server. Run the 'start' script in the

     '/usr/netscape/server4/<instance>'  
    or in
     'C:\Netscape\Server4\<instance>' 

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

  • Verify connectivity

    • 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 serious errors occur, they are logged to the server error log.

Chapter 3. Troubleshooting

Problem: The NSAPI extension fails to load when Netscape server is started.

  • Check that the 'obj.conf' configuration has the right path for the '.so' or '.DLL' file. This would be the 'Init ... shlib= ...' directive.

  • Check the Netscape server error log for errors.

  • Ensure that the enhydra_director.conf file exists and contains valid and syntactically correct configuration data. If the syntax is not valid, Enhydra Director will report the specific errors and line numbers to the Netscape server error log.

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

  • 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 NSAPI Enhydra Director extension 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.

Problem: The Netscape server crashes, hangs, or dies unexpectedly.

  • 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 elsewhere in Netscape.

  • Please report any bugs of this nature to the Enhydra.org folks, 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 can reproduce the bug consistently, please include the necessary steps to do so.