Complete Contents
Preface
Chapter 1 Gateway Features
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, Features, and Results
Chapter 7 Customizing Color and Graphics
Appendix A .conf Parameters
Appendix B Gateway Directives Reference
Appendix C CGI Usage
Appendix D Gateway User Help
Previous Next Contents Index


Chapter 1 Gateway Features

This chapter describes the gateway features 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.

A gateway can be used to perform directory lookup, or to authenticate to the directory and complete a database administration task, without logging in to Netscape Console.

 In Version 4.0 of 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:


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

See Also

"HTTP Server Configuration" on page 17


Gateways Installed with Directory Server 4.0
Two gateway instances are installed during Directory Server installation: the default gateway and Directory Express. The default gateway provides search, authentication, and entry modification capability. Directory Express is a customized version designed specifically for use as a corporate phonebook.

 The two gateway instances provided with Directory Server are configured to use the suffix set when the Directory Server was configured, and non-SSL (Secure Socket Layer) communications. Either can serve as a framework for a building a more sophisticated gateway instance.

See Also

"Location of Gateway Files" on page 12


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.

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

Figure 1.1 Default Gateway

Directory Express (pb.conf)

Directory Express is designed for use out of the box as a corporate phonebook. 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

Figure 1.2 Directory Express Search Result

Figure 1.3 Directory Express Extended Search Results


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, 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 34
"Configuring Gateway Clients" on page 27

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 32


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 file named 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 81

Do Not Serve Up binddnfile over HTTP

The binddnfile contains highly sensitive information. Do not store it 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 14.

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 Administration server managing the Directory Server instance runs the updatedsgw script.

See Also

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

 

© Copyright 1999 Netscape Communications Corporation