Netscape Directory Server Gateway Customization Guide: Chapter 2 Setting Up the Gateway

Gateway Customization Guide
Netscape Directory Server

Chapter 2 Setting Up the Gateway

This chapter describes the planning decisions and tasks required to install and initially configure a gateway for access by end users. The chapter contains the following sections:

Gateway Installation Planning

HTTP Server Configuration

Creating a New Gateway Instance

Gateway .conf File Configuration

Configuring Gateway Clients

Gateway Installation Planning

The following sections describe the steps for planning your installation of the gateway:

Location of Gateway Files

Securing Gateway Configuration and Settings

Updating the Gateway with Changes to Directory Server Configuration

HTTP Server Recommendations for Directory Server Gateway

Location of Gateway Files

Table 2-1 and Table 2-2 show the locations of gateway files for releases 6.2 and 4.x respectively.

Gateway Release 6.2

Two gateway instances are installed during Directory Server 6.2 installation: Netscape Directory Express (Directory Express) and the default gateway. The configuration files (pb.conf and dsgw.conf) for the two instances are stored in the serverRoot/clients/dsgw/context directory. Additional gateways can be created by customizing Directory Express or the default gateway.

Table 2-1    Location of Gateway Files for Release 6.2

File Type

File Path

Default gateway configuration file

serverRoot/clients/dsgw/context/dsgw.conf

Default gateway (dsgw) HTML and template files

serverRoot/clients/dsgw/html
serverRoot/clients/dsgw/config

Directory Express configuration file

serverRoot/clients/dsgw/context/pb.conf

Directory Express (pb) HTML and template files

serverRoot/clients/dsgw/pbhtml
serverRoot/clients/dsgw/pbconfig

Gateway Release 4.x

Two gateway instances are installed during Directory Server 4.x installation: Directory Express and the default gateway. The configuration files (pb.conf and dsgw.conf) are stored in the serverRoot/dsgw/context directory. Additional gateways can be created by customizing Directory Express or the default gateway.

Table 2-2    Location of Gateway Files for Release 4.x

File Type

File Path

Default gateway configuration file

serverRoot/dsgw/context/dsgw.conf

Default gateway (dsgw) HTML and template files

serverRoot/dsgw/html
serverRoot/dsgw/config

Directory Express configuration file

serverRoot/dsgw/context/pb.conf

Directory Express (pb) HTML and template files

serverRoot/dsgw/pbhtml
serverRoot/dsgw/pbconfig

Gateway Cloning

Unique gateway instances may have unique HTML directories (for example, ..clients/dsgw/mythml) and template directories (for example, ..clients/dsgw/myconfig). However, gateways may also be cloned to use identical HTML and template directories while pointing to different Directory Servers or different suffixes on a Directory Server.

For more information on cloning the gateway, see Gateway Cloning.

Securing Gateway Configuration and Settings

The following sections describe procedure for protecting the configuration information of your gateway.

Protecting Bind DN and Password

Protecting Root Processes on UNIX Systems

Protecting Bind DN and Password

The gateway configuration files reference files that contain sensitive information, including the binddnfile parameter containing the bind DN and bind password used to permit non-anonymous searching of the directory. The binddnfile should not be stored under the gateway configuration directory (serverRoot/clients/dsgw) or in any directory that is served up over HTTP.

Protecting Root Processes on UNIX Systems

On UNIX systems, it is not advisable to run the gateway from a Netscape Administration Server that is also running a Netscape server process as root. This may expose sensitive information about the configuration of Netscape servers.

Updating the Gateway with Changes to Directory Server Configuration

Similar to the 4.x release of gateway, the 6.x release of Directory Server Gateway includes a script, updatedsgw, that can be used to update all gateway instances with changes to the Directory Server configuration, including changes to Directory Server port, host, suffix, and root DN (the ability to update the suffix is not available in the server administration console). The updatedsgw script is stored in the serverRoot/bin/slapd/admin/bin directory.

Changes made to the Directory Server configuration (dse.ldif) by the Netscape Console are posted to updatedsgw and the relevant gateway files are updated. These files will be updated only when the host and port for the gateway match the host and port of the Directory Server.

Note

The Directory Server's root DN (the Directory Server's superuser) must match the value of the gateway's dirmgr parameter.

HTTP Server Recommendations for Directory Server Gateway

The Netscape Administration Server is the default HTTP server for the two gateway clients that are installed with the Directory Server. Both Directory Express and the default gateway are preconfigured to run under the Administration Server without additional setup.

There are many factors affecting gateway performance on an HTTP server, including the following:

The number of users accessing the gateway at a given time

The complexity of the directory searches performed and the search results required

Whether the gateway is additionally to be used for authentication and login

The load from other processes managed by the host machine

The speed and performance of the computer hardware selected for the host computer

The speed and capacity of the network (network hardware and software)

In general, gateway performance on the Administration Server will begin to slow down when the number of users accessing the gateway throughout the enterprise reaches 6,000 people. (Note that this is a very general recommendation that does not take into account factors listed above, especially the speed of the host machine.)

Note

It is not advisable to run the gateway from a Administration Server that is also running a Netscape server process as root. This may expose sensitive information about the configuration of Netscape servers.

Running the Gateway in High-Usage Networks

Network administrators expecting high gateway usage may wish to move the gateway to a high-performance HTTP server that is dedicated to running the gateway.

Note

If you do decide to migrate the gateway's configuration files to a high-performance HTTP server, we recommend you use Netscape Enterprise Server.

HTTP Server Configuration

The following sections describe the steps for configuring an HTTP server:

Name Translation Mapping

Gateway Root Suffix

Configuring the Gateway for Web Servers

Name Translation Mapping

The HTTP server uses Name Translation mapping to translate a virtual path provided by a gateway client to a physical path used by an HTTP server. This Name Translation mapping specifies the gateway's HTML directory. The gateway's CGIs use this information to output the correct URL (HTTP redirection). The NameTrans mapping is specified in the gateway's configuration file using the gwnametrans parameter.

For more information on configuring the gwnametrans parameter, see gwnametrans.

Gateway Root Suffix

Directory Express and the default gateway are set to the root suffix specified during Directory Server installation. This suffix specifies the DN for the LDAP database and represents a root in the directory tree (for example, dc=example,dc=com). Multiple gateways can be set up on an HTTP server that provide access to directory entries that correspond to this root suffix.

When the Directory Server's suffix changes, it is necessary to run the updatedsgw script manually to propagate the change to all gateway instances.

Note

When the root suffix, directory manager, or port change, the gateway settings in dsgw.conf must be updated to reflect the changes (if they haven't been updated by Netscape Console).

Configuring the Gateway for Web Servers

Similar to the 4.x release, in the 6.2 release of the gateway, Directory Express and the default gateway are installed with the Directory Server and configured to run under the Netscape Administration Server, which is the default HTTP server for the gateway clients. No additional configuration is necessary. However, customers in high-usage networks may wish to move their gateways (or set up new gateways) on a high-performance HTTP server.

Setting up a gateway with a web server typically requires:

Changing all the host names and port numbers in the configuration files (config.txt, dsgw.conf, pb.conf, default.conf, and so on).

Adding the following CGI directories (under Program Management).

Prefix: /clients/dsgw/binCGI Directory: serverRoot/clients/dsgw/bin

(On Windows, add them as shell CGI directories.)

Adding an additional Document directory (under Content Management).

Prefix: /clientsDirectory: serverRoot/clients

Changing permissions of the cookie directory (required for UNIX only).

The configuration procedures outlined in this section assume that a Netscape Enterprise Server is installed and configured to communicate with Directory Server. For Netscape Enterprise Server documentation, check this site: http://enterprise.netscape.com/docs/enterprise/index.html

For configuring other HTTP servers, follow the documentation that came with the product.

To configure a 6.2 release of the gateway to work with Netscape Enterprise Server, follow the instructions below:

Add an additional CGI directory.

Adding an additional CGI directory is necessary to make the gateway's CGI programs available. For additional information, see http://enterprise.netscape.com/docs/enterprise/611/admin/esprgrm.htm#21309.

From the Class Manager for the Netscape Enterprise Server:

Select Programs > CGI Directory.

In the URL Prefix field, enter the URL prefix to use:

/clients/dsgw/bin

In the CGI Directory field, enter this (replace serverRoot with your installation directory):

serverRoot/clients/dsgw/bin

Click OK, then Save and Apply.

Add an additional document directory.

Adding an additional document directory is necessary to establish access to the gateway files. For additional information, see http://enterprise.netscape.com/docs/enterprise/611/admin/escontnt.htm#22280.

From the Class Manager for the Netscape Enterprise Server:

Select Content Management > Additional Document Directories.

In the URL Prefix field, enter this:

clients/dsgw

In the Map to Directory field, enter this (replace serverRoot with your installation directory):

serverRoot/clients/dsgw/

Click OK, then Save and Apply.

Change permissions of cookie directory (required for UNIX only).

To enable the gateway to store cookies on the HTTP server, the gateway must have write access to the HTTP server's cookie directory.

From the Class Manager for the Netscape Enterprise Server:

Select System Settings > View Server Settings and note the value set for the User field.

If this value is set to nobody, check to make sure that the server is not running as a named user. For example, on Solaris grep for the HTTP process:

ps -ef | grep http

The process listed identifies the name under which the HTTP process is running.

Log into the machine as root.

Go to the serverRoot/clients/dsgw directory and enter this:

# chown uid authck

where uid is the user name determined in step a.

Verify that the directory is accessible by opening this URL:

http://webserverHost:webserverPort/clients/dsgw/bin/search

where webserverHost is the HTTP server's hostname and webserverPort is the port number used by the server. When the HTTP server is using the standard HTTP port number (80), the port number does not need to be included in the URL.

Creating a New Gateway Instance

These instructions assume that the new gateway instance will run under the Netscape Administration Server or a similarly capable HTTP server.

Rename the dsgw.conf or pb.conf file to a new gateway context.

For example, clients/dsgw/context/dsgw.conf might become clients/dsgw/context/example.conf.

Set the gwnametrans parameter in the new gateway's .conf file to point to the HTML directory.

For example, the gwnametrans parameter setting for example.conf should point to /clients/dsgw/examplehtml.

To support non-anonymous searching (one individual user DN and password per directory instance) using the new gateway, set the binddnfile parameter in example.conf to point to the location of the file containing the bind DN and bind password that will be used to access information in the user directory.

The binddnfile contains sensitive information; for security purposes, do not store the binddnfile within the /clients/dsgw directory or within any directory served up over HTTP.

Create an HTML directory for the new gateway.

For example, to provide an HTML directory for example.conf, copy and rename an existing HTML directory (clients/dsgw/html or clients/dsgw/pbhtml) to /clients/dsgw/examplehtml.

Create a template directory containing object class templates and other configuration files.

For example, to provide a template directory for example.conf, copy and rename an existing template directory (/clients/dsgw/config or /clients/dsgw/pbconfig) to /clients/dsgw/exampleconfig.

Edit the htmldir and configdir parameters in example.conf to point to the new HTML and template directories.

To access the new gateway instance (in this example, example.conf) navigate the browser to this URL:

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

Gateway Cloning

The HTML and template directories for one gateway can serve as the HTML and template directory for many others. Maintaining the functionality of multiple gateways in a centralized /config and /html directories is useful when the only values that are likely to change are parameter setting in the .conf file. For example, the host and port specified by the baseurl parameter, the root DN specified by the dirmgr parameter, and the root suffix specified by the location-suffix parameter.

Gateway .conf File Configuration

The following sections describe the steps for configuring the gateway .conf file:

Changing the Default Port Setting

Setting Up a Directory Manager for the Gateway

Setting up the Suffix for Adding Entries

Setting Up SSL Support

Setting vCard Properties

Changing the Default Port Setting

The LDAP port is set during Directory Server installation. This value can be changed in the baseurl parameter. The following example shows the syntax used to specify a port number that is different than the default port number of 389. For example, the baseurl parameter in the LDAP port is changed to the following:

baseurl "ldaps://dirserver.example.com:3000/o%3Dexample.com"
Setting Up a Directory Manager for the Gateway

When Directory Server is installed, a default Directory Manager account (cn=Directory Manager) is setup with permissions to the root DN. The Directory Server installation requires a root DN. If no root DN was configured when the Directory Server was installed, then no default Directory Manager is configured for the gateway.

It is strongly recommended that you use a different directory manager account for the gateway, that is, an account other than cn=Directory Manager. Once you setup the new directory manager account (for example, cn=gateway manager,cn=config), use ACLs to restrict access to applicable sub suffixes and the user entries under those sub suffixes. This enables the gateway directory manager to change those users' passwords but prevents the entry from having complete control of the Directory Server.

Note

For security reasons, set the gateway Directory Manager to an entry other than cn=Directory Manager.

Configuring the Directory Manager DN

Use this procedure to configure the gateway Directory Manager to reference the correct DN:

Create an entry for the gateway Directory Manager, making sure to set a password for the entry.

Set the permissions for the Directory Manager so that it has read and write authority for the entries it will manage.

When necessary, change the dirmgr parameter to refer to the Directory Manager's distinguished name (DN).

Note

End users frequently forget their passwords, so give the gateway Directory Manager write access to the userPassword attribute for the entries it will manage.

The dirmgr parameter is described in dirmgr. Creating directory entries is described in the Netscape Directory Server Administrator's Guide.

Authenticating as Directory Manager

Figure 2-1 shows the authentication login screen for the default gateway. Administrators can use it to authenticate as the Directory Manager. The Authenticate as Directory Manager button is displayed only when a Directory Manager has been configured for the gateway.

The authlifetime parameter, which defines the number of seconds that a user may remain authenticated, is described in location.

Figure 2-1    Authenticating as Directory Manager

Setting up the Suffix for Adding Entries

The location-suffix parameter is defined in dsgw.conf, and identifies the suffix under which the gateway creates new entries in the directory. The location-suffix parameter can point to any suffix in a directory.

Setting the location-suffix parameter is described in include. The Netscape Directory Server Administrator's Guide describes the Suffix parameter and provides syntax examples. Setting the root suffix is also described in the Netscape Directory Server Installation Guide.

Setting Up SSL Support

When the Directory Server is installed, the gateway is configured to communicate with the Directory Server using a non-SSL host name and port number. This information is stored in the baseurl parameter.

Configuring the gateway to use SSL when communicating with the Directory Server requires modification of the securitypath and baseurl parameters in dsgw.conf.

Enabling SSL communications on the Directory Server is described in the Netscape Directory Server Administrator's Guide. Information about managing key and certificate databases is provided in Managing Servers with Netscape Console.

Configuring the Gateway to Use SSL

The securitypath parameter specifies the location of the certificate database. For example, you can specify the path to the certificate database as follows:

securitypath "/usr/netscape/servers/alias/slapd-testDir-cert8.db"
The following example shows the baseurl parameter configured to use ldaps (instead of ldap, the default) and standard SSL port number 636:

baseurl "ldaps://dirserver.example.com:636/o%3Dexample.com"

Note

Before configuring SSL, verify that the gateway's certificate database contains a server certificate or Certificate Authority (CA) certificate needed to communicate with the Directory Server.

For more information about the baseurl parameter, see baseurl.

Setting vCard Properties

Mappings between vCARD properties and LDAP attribute type are described in vcard-property.

Configuring Gateway Clients

The following sections describe how to configure clients of the gateway:

Language Support for HTTP Clients

Displaying a Non-English Alphabet

Configuring Netscape 7.x for Preferred Language

Customizing Communicator's LDAP Settings

Language Support for HTTP Clients

When a user accesses information in the directory from an HTTP client—through the gateway or another HTTP-based LDAP interface—the client provides the Directory Server with information indicating the optimal character set and collation order to use in transmitting information to the browser.

Unicode and Latin-1 Character Sets

When the user is using Netscape Communicator 4.7x or later versions of Netscape browsers, the Directory Server sends Unicode characters. Netscape Navigator 2.x and 3.x clients are not capable of displaying Unicode characters.

Displaying a Non-English Alphabet

To display directory content that uses a non-English alphabet, a font capable of displaying a non-English alphabet must be installed on the user's system.

The Directory Server can store any Unicode character, so Netscape Communicator or later versions of Netscape browser users should install a font that supports all of Unicode. Bitstream Cyberbit, which is bundled with Communicator, supports Unicode.

Users who are not using Communicator should use a font that supports Latin-1 (or Western) character sets. Most of the commonly used fonts (Courier, Times Roman, Helvetica) have a Latin-1 variant.

Configuring Netscape 7.x for Preferred Language

Install a font that supports Unicode.

In the browser window, go to Edit > Preferences > Appearance > Fonts.

From the Fonts For pull-down menu, select Unicode.

Set the appropriate font type, size, and display resolution.

Go to Edit > Preferences > Navigator > Languages/Content and configure the list of languages so that the best description of the user's language is first, followed by other acceptable languages.

For example, a speaker of British English who also reads Spanish might list English/United Kingdom [en-GB] first, followed by English [en] and then Spanish [es].

Customizing Communicator's LDAP Settings

Administrators can reconfigure Javascript preference settings in Communicator or later versions of Netscape browsers to allow users to interact with information stored in the user directory.

In the Address Book and Select Address dialog boxes (accessible from the mail composition window), users can enter one string of search criteria to search an LDAP directory for matching names.

In the Search Directory dialog, users can enter more complex query expressions to search an LDAP directory using native LDAP searches.

Users can enter LDAP URLs (beginning with the "ldap://" prefix) in Navigator (web browser) windows to search an LDAP directory.

Last Updated October 31, 2003

File Type	File Path
Default gateway configuration file	serverRoot/clients/dsgw/context/dsgw.conf
Default gateway (dsgw) HTML and template files	serverRoot/clients/dsgw/html serverRoot/clients/dsgw/config
Directory Express configuration file	serverRoot/clients/dsgw/context/pb.conf
Directory Express (pb) HTML and template files	serverRoot/clients/dsgw/pbhtml serverRoot/clients/dsgw/pbconfig


Note	The Directory Server's root DN (the Directory Server's superuser) must match the value of the gateway's `dirmgr` parameter.


Note	It is not advisable to run the gateway from a Administration Server that is also running a Netscape server process as `root`. This may expose sensitive information about the configuration of Netscape servers.


Note	If you do decide to migrate the gateway's configuration files to a high-performance HTTP server, we recommend you use Netscape Enterprise Server.


Note	When the root suffix, directory manager, or port change, the gateway settings in `dsgw.conf` must be updated to reflect the changes (if they haven't been updated by Netscape Console).


Note	For security reasons, set the gateway Directory Manager to an entry other than `cn=Directory Manager`.


Note	End users frequently forget their passwords, so give the gateway Directory Manager write access to the `userPassword` attribute for the entries it will manage.


Note	Before configuring SSL, verify that the gateway's certificate database contains a server certificate or Certificate Authority (CA) certificate needed to communicate with the Directory Server.