Complete Contents
Preface
Chapter 1 Introduction
Chapter 2 Setting up the Gateway
Chapter 3 Gateway Localization
Chapter 4 Files Controlling Gateway Functionality
Chapter 5 Entry Types and Object Class Attributes
Chapter 6 Search Attributes, Filters, and Results
Chapter 7 Customizing Graphics and Color
Appendix A .conf Parameters
Appendix B Directives Reference
Appendix C CGI Usage
Previous Next Contents Index Bookshelf


Chapter 1 Introduction

This chapter describes the gateway functionality introduced with release 4.0 of the directory server. Topics include:


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 release 4.0 of the Netscape 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:

Gateways Installed with Directory Server 4.0

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.


See Also

"Location of Gateway Files" on page 13

Default Gateway

The configuration file for the default gateway is at <NSHOME>/dsgw/context/dsgw.conf.

During Netscape directory server 4.0 installation, the default gateway is configured to use as its HTTP server the Netscape Administration server installed with the directory.

Following directory server installation, the default gateway can be accessed from http://adminhost:adminport/ or directly using this URL:

http://adminhost:adminport/dsgw/bin/search?context=dsgw

Directory Express

The configuration file for Directory Express is <NSHOME>/dsgw/context/pb.conf.

During Netscape directory server 4.0 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/dsgw/bin/lang?context=pb

HTTP Server Requirements for Gateways

A gateway instance requires an HTTP server capable of communicating with the LDAP 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 or FastTrack servers.


See Also

"HTTP Server Configuration" on page 18


Default Gateway and Directory Express
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
Release 4.0 of the directory server supports multiple gateway instances. 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 <NSHOME>/dsgw/context. Within the .conf file are two parameters specifying the path names for the HTML and template files for the gateway (see Example 1.1).

Example 1.1 HTML and configuration directories specified in pb.conf

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 Example 1.2. 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.

Example 1.2 Embedding GCONTEXT in a Link

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

Gateway 3.x Note

In release 3.x, CGIs passed their arguments using PATH_INFO. In 4.0, PATH_INFO is replaced by the QUERY_STRING, which works better with the Japanese version of Windows NT, and is functionally equivalent.

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, as shown in Example 1.3.

Example 1.3 Specifying PCONTEXT in an HTML Form

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


See Also

"Context-Related Directives" on page 95

URLs for Gateway Access

The URL customers use to access a 4.0 gateway differs from the URL customers use to access a 3.x gateway.

Release 4.0

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

http://adminhost:adminport/dsgw/bin/lang?context=<context>

The default gateway and Directory Express are available from the page for the Netscape Administration server (http://host:port)

Release 3.x

To get to a 3.x gateway, users enter the following URL:

http://host:port/dshtml


Gateway Localization
The gateway is designed to allow support for clients in multiple locales.

Gateway Locales

Release 4.0 of the Directory gateway is localized for English, Japanese, French, Spanish, and German. Language files are stored in <NSHOME>/dsgw/html/<lang> and <NSHOME>dsgw/config/<lang>, where <lang> is defined in RFC1766 (for example, language files for Japanese are stored in /usr/netscape/dsgw/html/ja and /usr/netscsape/dgw/config/ja[true]). The gateway can be configured to support additional locales.

Support for the character sets necessary to render a particular locale (language) must be available in the browser's configuration. Netscape Communicator provides support for multiple languages and multiple characters sets.


See Also

"Gateway Locales" on page 36
"Configuring Gateway Clients" on page 29

Character Sets

Release 4.0 of the gateway supports Unicode (specifically, the UTF-8 character set), the character set containing all of the world's languages. However, Unicode or any character set specified in the gateway's .conf file, can be overridden by the HTTP Accept-charset header sent by the gateway client or by a character set created for a specific language.


See Also

"How the Gateway Selects a Character Set" on page 34


Non-Anonymous Searching
Release 3.0 of the gateway allows anonymous searching only. This provides only the most basic permissions for accessing information in the user directory.

The release 4.0 gateway provides the same functionality but in addition supports non-anonymous searching. 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 authentication credentials exist for a user on the directory server, these override the bind DN and bind password in the gateway's binndnfile. 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.


See Also

"binddnfile" on page 83

Do Not Server Up binddnfile over HTTP

The binddnfile contains highly sensitive information. Do not store the binddnfile under <NSHOME>/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 Existing Gateways
Release 4.0 of the directory server is compatible with previous versions of the gateway, including release 3.x. Although the HTML files and gateway CGIs are not interchangeable, a 3.x gateway can access a 4.0 directory server, and a 4.0 gateway can access a 3.x directory server.

It is not necessary to upgrade a 3.x gateway to release 4.0, however a script is available to complete this task. On UNIX and NT systems, this migration occurs automatically when a directory server is migrated from release 3.x to release 4.0.

The gateway migration script is described in "Migrating 3.x default Gateways to Release 4.0" on page 15.

Directory server migration is described in the Release Notes for Directory Server 4.0


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 <NSHOME>/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 Adminstration server managing the directory server instance runs the updatedsgw script.


See Also

"Updating the Gateway with Changes to Directory Server Configuration" on page 17

 

© Copyright 1998 Netscape Communications Corporation