Netscape logo Gateway Customization Guide
Netscape Directory Server
Previous      Contents      Index      DocHome      Next     

Chapter 1   Introduction


This chapter describes the gateway functionality of Netscape Directory Server (Directory Server). The chapter contains the following sections:

What is a Gateway?

A gateway is an HTTP-to-LDAP client that lives on an HTTP server. Using special directives embedded in HTML files, a gateway allows users to access user directory data using any kind of web browser. Using a gateway does not require login to the Netscape Console.

In Directory Server, many gateway instances can be defined on one HTTP server, providing access to any number of Directory Servers. A gateway instance consists of the following:

Gateways Installed with Directory Server

Two gateway instances are installed during Directory Server installation: the default gateway and Directory Express. Both gateways are configured to use the suffix set when the Directory Server was configured, and non-SSL (Secure Socket Layer) communications.





For more information, see Location of Gateway Files.

Default Gateway

The configuration file for the default gateway is at serverRoot/clients/dsgw/context/dsgw.conf.

Following Directory Server installation, the default gateway can be accessed from http://adminHost:adminPort/ or by directly using this URL:

http://adminHost:adminPort/clients/dsgw/bin/lang?context=dsgw

Directory Express

The configuration file for Directory Express is serverRoot/clients/dsgw/context/pb.conf.

During Directory Server installation, Directory Express is configured to use as its HTTP server the Netscape Administration Server installed with the directory.

Following Directory Server installation, Directory Express can be accessed from http://adminHost:adminPort/

or directly using this URL:

http://adminHost:adminPort/clients/dsgw/bin/lang?context=pb

HTTP Server Requirements for Gateways

A gateway instance requires an HTTP server that can communicate with Directory Server. For optimum performance and highest security, the gateway should be configured to run under a high-performance HTTP server, such as the Netscape Enterprise Server.

For more information, see HTTP Server Configuration.

Directory Express and Default Gateway

The following sections describe Directory Express and the Default Gateway in detail:

Directory Express (pb.conf)

Directory Express is a basic directory lookup tool that can be used out of the box.

Figure 1-1    Directory Express: Search Result

Figure 1-2    Directory Express: Extended Search Results

Default Gateway (dsgw.conf)

In addition to the standard search form, the default gateway provides an advanced search form, a Directory Server authentication form, and a form for adding and modifying entries.

Figure 1-3    Default Gateway

Support for Multiple Gateway Instances

Directory Server supports multiple gateway instances—that is, many gateways can access directory data from the same HTTP server without conflict.

The .conf files defining the configuration of gateway instances are stored in the serverRoot/clients/dsgw/context directory. Within the .conf file are two parameters specifying the path names for the HTML and template files for the gateway. The following lines show the HTML and configuration directories specified in the pb.conf file:

htmldir         ../pbhtml
configdir         ../pbconfig

Specifying Gateway Configuration to Gateway CGIs

Information about which .conf file to use is communicated in the QUERY STRING using a GET, and through a hidden variable on a POST.

GET Operations (GCONTEXT)

In a GET operation, gateway CGIs get the gateway context from the QUERY STRING in the URL.

Use the GCONTEXT directive in all URLs to gateway CGIs. Embed

<!--GCONTEXT -->

after the CGI name, as shown in the example that follows. This directive will be replaced by the current CGI's gateway context. The GCONTEXT directive is the only gateway directive that does not have to be at the beginning of the line. An example of embedding the GCONTEXT string in a link follows:

<a href=/clients/dsgw/bin/lang?<!-- GCONTEXT -->&file=auth.html>click</a>

Note  

Similar to Directory Server Gateway 4.x, in the 6.2 release, the CGIs pass their arguments using QUERY_STRING; QUERY_STRING is functionally equivalent to PATH_INFO.



POST Operations (PCONTEXT)

In a POST operation, the CGI posts to the gateway instance specified by a hidden variable on an HTML form. Each POST operation to a gateway CGI in an HTML form must use the PCONTEXT directive so that CGIs can pass the gateway instance to the next page and maintain the state.

For CGI invocations using a POST, put

<!-- PCONTEXT -->

at the beginning of a line. For example, you can specify PCONTEXT in an HTML form as follows:

<form method=post action=/clients/dsgw/bin/dosearch>
<input type=hidden name=dn value="">
<!-- PCONTEXT -->
</form>

For more information about content-related directives, see Context-Related Directives.

URLs for Gateway Access

The URL customers use to access a 6.2 gateway differs from the URL customers use to access a 4.x gateway.

To get to a 6.2 gateway, users enter the following URL:

http://adminHost:adminPort/clients/dsgw/bin/lang?context=<context>

To get to a 4.x gateway, users entered the following URL:

http://adminHost:adminPort/dsgw/bin/lang?context=<context>

In both the releases, the default gateway and Directory Express are available from the page for the Netscape Administration Server (http://adminHost:adminPort).

Anonymous and Non-Anonymous Searching

Similar to the 4.x release of the gateway, the 6.2 release of the gateway supports both anonymous and non-anonymous searching; anonymous searching provides basic permissions for accessing information in the user directory. A bind DN and bind password, stored in a binddnfile, can be set up for users to authenticate to the Directory Server. User permissions for directory access can be defined in the Netscape Console.

If the Directory Server contains authentication credentials for a user, these override the bind DN and bind password in the gateway's binndnfile parameter. When authentication credentials expire or are invalid, the gateway attempts to authenticate the user to the directory using the binddnfile. When no binddnfile is specified, the gateway instance binds anonymously.

binddnfile

The location of the binddnfile containing bind DNs and bind passwords for individual users and groups of users is specified in the gateway's .conf file.

Note  

The binddnfile contains highly sensitive information. Do not store the binddnfile under serverRoot/clients/dsgw or in any directory that is served up over HTTP (for instance, /bin/slapd/server is a good place to store the binddnfile).



Compatibility with Previous Releases of Gateway

Release 6.2 of the gateway is compatible with the 4.x release of the gateway. Although the HTML files and gateway CGIs are not interchangeable, a 6.2 gateway can access a 4.x Directory Server—a 6.2 gateway will be able to talk to a 4.x Directory Server provided the AIM presence related information is turned off in the gateway.

Note that in the 6.2 release of the gateway, the URLs have all changed. To use the 4.x HTML files with the 6.2 binaries, the files will need to be updated to use the new URL scheme. Similarly, to use the new HTML files with the 4.x binaries, the URLs will need to be changed to the old style in the HTML files. In addition, the AIM presence related information will need to removed from the HTML files.

Automatic Updates to Directory Configuration

A script that updates gateway instances with changes to Directory Server configuration, updatedsgw, is included with the Directory Server installation. This script searches serverRoot/clients/dsgw/context for gateway instances that match the Directory Server host and port.

The updatedsgw script runs automatically for gateways installed on the Netscape Administration Server managing the Directory Server instance. When the server port or root DN (or other settings, such as directory manager) for a Directory Server instance is changed, the Netscape Administration Server managing the Directory Server instance runs the updatedsgw script.

For more information, see Updating the Gateway with Changes to Directory Server Configuration.



Previous      Contents      Index      DocHome      Next     

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2003 Netscape Communications Corporation. All rights reserved.
Read the Full Copyright and Thrid-Party Acknowledgments.


Last Updated October 31, 2003