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
- Hardware: Intel 80386 or later CPU. (Pentium 200Mhz or faster recommended)
- Operating System: Windows NT 4.0, Service Pack 6 or later.
- Web servers:
- IPlanet/Netscape Enterprise Server version 4.0 or higher.
- Microsoft Internet Information Server, version 4.0 or later.
Solaris
- Hardware: Sparc-compatible system with 64 MB RAM (128 MB Recommended)
- Operating System: Sun Solaris version 2.6
- Web servers:
- IPlanet/Netscape Web Server version 4.0 or higher
- Apache Web Server version 1.3.9 or later
Linux
- Hardware:
- Intel 80386 or later CPU. (Pentium 200Mhz or faster recommended)
- Sparc-compatible system higher 64 MB RAM (128 MB Recommended)
- Operating System: Version 2.2 kernel or later with support for
recent versions of the glibc C library. (Redhat 6.1 recommended)
- Web servers:
- IPlanet/Netscape Web Server version 4.0 or higher
- Apache Web Server version 1.3.9 or later
Preparation
Before installing Enhydra Director,
determine the following:
- The machines on which you will be running Enhydra Multiserver.
- The applications you will be running on the Enhydra Multiservers.
- For each application:
- The name of the machine and the port number on which each instance of
the application will run. The port number is the 'port' used when
configuring a connection of type 'EnhydraDirector' using the Multiserver
Administration console.
- The URL prefix used to identify the application. (For example
'
/demoApp
')
- Whether the application requires session affinity. That is, whether
requests for the same session to an application should always be routed to
the application server instance that created the session. Unless your
application supports distribution of its sessions among other instances, you
should assume that session affinity is needed. If your application does not
use session information at all, you do NOT need session affinity.
- The name of the web server instance on which you wish to configure Enhydra
Director.
- The TCP port of the web server instance on which you intend to configure
Enhydra Director. By default, this is port 80.
- For Netscape, determine:
- The location of the
obj.conf
file for your web server
instances. On Windows NT, this is typically:
C:\Netscape\Server4\<instance>\config\obj.conf
On Unix this
is often /usr/netscape/server4/<instance>/config/obj.conf
.
- Where to install the EnhydraDirector files. On Windows NT, we recommend:
C:\Netscape\EnhydraDirector
On Unix, we recommend:
/usr/netscape/EnhydraDirector
- For Apache, determine:
- The location of the configuration files for Apache, typically
/usr/local/apache/conf
.
- The location of the executables directory for your Apache server,
typically
/usr/local/apache/bin
.
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.
- 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
, ./obj.conf.example
.
- 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
The
'obj.conf.example' file is just an example 'obj.conf' where the necessary
additions are highlighted in comments. You must edit your existing 'obj.conf'
file and place similar (but not identical) entries in the same places. This is
described in more detail later in this document.
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' and 'obj.conf.example'. 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
Configuring Director for IPlanet
- Stop the Netscape Web Server - Run the 'stop' script in the
'/usr/netscape/server4/<instance>' orin
'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="/enhydra.enhydra.org/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 theclosing
</Object>
for
<Objectname= default>
, addthe section: <Object
name= enhydra_director> Service fn="edir_nsapi_handler" method=
(GET|HEAD|POST) </Object>
The 'obj.conf.example
'
file gives an example of the 'obj.conf
' file for a fictitious
site.
- 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.
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 Lutris engineers.
- 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.
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.
- 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
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.
- 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.
Step 2: Install the filter (for a specific server)
- 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.
Step 3: Install the handler.
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.
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
- 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'.
Troubleshooting
Problem: EnhydraFilter.dll fails to load when IIS
is started.
- 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.
Problem: The Filter starts up OK but I can't connect to my
application.
- 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.
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.
- This is evidence of an error in the handler or filter DLL that needs the
attention of Lutris engineers.
- 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.
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
'enhydra3.0.tar.gz' or 'enhydra3.0.zip'. The Enhydra Director source archive is
in: enhydra3.0/director/enhydra-director1.0.tar.gz
or
enhydra3.0/director/enhydra-director1.0.zip
Change directory to
enhydra3.0/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: ./enhydra3.0/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.
- EnhydraDirectorConfigFile Specifies the full path to the
'enhydra_director.conf' file. By default this is 'enhydra_director.conf' in
the 'conf' subdirectory of your Apache installation.
- EnhydraDirectorLockFile Specifies the location of the file used for
'locking' the scoreboard during shared access. If you set this parameter, you
should not need to set the 'EnhydraDirectorData' option, unless you are a
developer or are porting to a strange platform, in which case you really know
what you are doing.
Setting this parameter may be necessary if you
installed EnhydraDirector on an NFS filesystem. Due to locking bugs in
many/most NFS implementations, EnhydraDirector will not work if the lock file
is located on an NFS file system.
By default, the lock file is located
under the 'logs' directory. In order to allow the load balancing code to run
as the Apache 'Child' user ID, the actual lock file is located under
'logs/edir', where 'edir' has permissions set to allow the child processes to
read and write. The permissions of the 'logs' directory are unaffected.
- EnhydraDirectorDataFile (Expert - Developers and Geeks Only) You
should not ever need to set this parameter unless you are a developer or are
experimenting with alternate shared memory modules (see edir_shmem.h). This
allows the scoreboard shared data file to be specified as a different file
than the lock file, or even as a Systme V IPC region.
By default, the
'mmap' shared memory module uses the same file as the 'filesys' mutex module.
(see edir_mutex.h). This means the locking and data sharing use the same file
on most modern unix implementations, including Solaris, Linux, and FreeBSD.
- EnhydraDirectorDaemonPath (Advanced) If you must install the
Enhydra Director daemon (edir_daemon) in a different location than the Apache
'bin' directory, this option can be used to specify the full path to the
daemon program.
- EnhydraDirectorDebug (Advanced) If you used '--enable-debugging'
when building Enhydra Director, then this option can be used to set the
debugging mask in the module. The debug mask is also propagated to the daemon
when it is started. See edir_debug.h or enhydra_director.conf.default for more
information on possible values. To enable full, highly voluminous debugging,
including hexdups of all communication between the module and Enhydra, specify
the value '0xffffffff'. Be forewarned that doing this will severely limit
Enhydra director's performance, and will dump hundreds of megabytes of logging
data to the Apache error log. This option is identical to <option
debug="0xNNNNNNNN"/> in enhydra_director.conf, except that it gets set much
earlier, and allows debugging of the code that loads the config file and
scoreboard, as well as the daemon launching code.
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.
- Open 'httpd.conf' in a text editor.
- Search to the last line in the file starting with 'LoadModule'. (The
default 'httpd.conf' should at least have a comment line, but if not even a
commented LoadModule line is found, just go to the end of the file.)
- Using the last component of the 'libexec' directory located in step 2, add
a line to the list of LoadModules directives (if any), that looks like:
LoadModule enhydra_director_module libexec/mod_enhydra_director.so
- If the last component of you Apache installation's 'libexec' path ends in
something else (say, 'modules'), then you would instead add the line:
LoadModule enhydra_director_module modules/mod_enhydra_director.so
- If there are other 'LoadModule' lines, they usually will contain the
correct path to the libexec path, so you can use the other directives as a
guide.
Note: If you are using 'mod_rewrite', then you should make
sure that the 'LoadModule rewrite_module ...' directive comes BEFORE the
'LoadModule enhydra_director_module ...' directive if you intend to use
'mod_rewrite' to redirect URLs to Enhydra Director. Also you should use the
'mod_rewrite' '[PT]' tag to force pass-through of redirected URLs.
- Now, search for the last line starting with 'AddModule'. Again, if such a
line does not even exist as a commented-out line, then just go to the end of
the file. Add the line:
AddModule mod_enhydra_director.c
- Add any desired Enhydra-specific directives such as 'EnhydraDirectorDebug'
to the 'httpd.conf' file. These directives are optional in almost all cases.
- Save the 'httpd.conf' file.
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.
- Use 'ps -aef' or 'ps -ax' (depending on your system) to make sure
'edir_daemon' is running.
- 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.
- 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.
- 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.
- If initialization errors occur within the module, the errors are reported
in the Apache error log.
Step 7: 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.
- Errors encountered while handling requests are reported in the Apache
error log.
Troubleshooting
Problem: The apache extension fails to load when
Apache is started.
- Check that the 'httpd.conf' for correct configuration of the module, as
described in the previous sections.
- Check the system log file for errors reported by the edir_daemon program.
- Check the Apache error log for errors reported by the Enhydra Director
module.
- 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 Apache 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 Apache 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: Apache child processes dump core. (crash)
- This is evidence of an error in the handler or filter DLL that needs the
attention of Lutris engineers.
- There's also the possibility that there is a bug elsewhere in Apache, or
in some other module. If possible, remove all unneeded modules from the
'httpd.conf' file to try to narrow the problem down to the Enhydra module.
- If you're an engineer and can give us stack traces from gdb, we would be
VERY appreciative. ESPECIALLY stack traces from '--enable-debugging'
compilations. :)
- 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 have a way to reproduce the bug consistently, Please include
the necessary steps to do so.
Configuring Your Application
The following
procedure assumes that you are using the Multiserver Administration console to
add the connections for the application.
- Create Enhydra Director connections for your application. - Bring up the
MultiServer Administration page for your Enhydra server instance.
- Select your application in the application list.
- Click on the 'Connections' tab to manage connections for your application
instance.
- Within the 'Connections' tab, click 'Create'. A 'new connection' dialog
box will appear.
- In the dialog box, check 'EnhydraDirector' as the connection type.
- 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'.
- 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.