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. Topics include:

• Gateway Installation Planning
• HTTP Server Configuration
• Creating a New Gateway Instance (4.0 only)
• Gateway .conf File Configuration
• Configuring Gateway Clients

• where to store gateway configuration and HTML files
• how to securely store gateway bind DNs and bind passwords
• how to protect root processes on the HTTP server running the gateway
• whether to migrate existing gateways to release 4.1 gateways or to let them co-exist
• how changes to Directory Server configuration and user directory will be updated on the gateway
• which type of HTTP server best suits the needs of your enterprise

Table 2.1 and Table 2.2 show the locations of gateway files for release 4.0 and release 3.x.

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

Unique gateway instances may have unique HTML directories (for example, ..dsgw/mythml) and template directories (/for example, ..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.

"Gateway Cloning" on page 23

Gateway Release 3.x

One gateway is installed for each instantiation of the Directory Server. The .conf file is stored in /dsgw (under slapd-<instance>).

Protecting Bind DN and Password

Release 4.0 gateway .conf files reference files that contain sensitive information, including the binddnfile 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 (<NSHOME>/dsgw), or in any directory that is served up over HTTP.

On UNIX systemsm, 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.

Release 4.0 of the Netscape Directory server supports 3.x gateways, so it is not necessary to modify a 3.x gateway in order for it to access a 4.0 directory. However, a 3.x gateway can not co-exist with 4.0 gateways unless it is first migrated to the 4.0 gateway structure.

• Replaces /ds with /dsgw/bin in the gateway's URLs.
• Changes gateway HTML file syntax to support the GCONTEXT and PCONTEXT directives.
• Adds parameters to the dsgw .conf file--including htmldir, configdir, gwnametrans--that support multiple gateway instances.
• Adds localization parameters to dsgw.conf to support the UTF-8 character set and to support older browsers that are not aware of UTF-8.
• Moves dsgw.conf to /<NSHOME>/dsgw/context and renames it dsgw-30.conf.
• Changes PATH_INFO to QUERY_STRING

When the migration script finishes, the migrated 3.x dsgw.conf file can be accessed from:

Running the Gateway Migration Script

The dsgwmig script runs automatically during the 3.x -> 4.0 Directory Server migration process.

Release 4.0 of the Directory Server provides 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 <NSHOME>/bin/slapd/admin/bin.

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

Many factors affect gateway performance on an HTTP server, including:

• 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)

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

"Name Translation Mapping" on page 17

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). In release 4.0 of the gateway, the NameTrans mapping is specified in the gateway's .conf file using the gwnametrans parameter.In release 3.x, the NameTrans mappings are hard-coded (the binary files stored in /dsgw/bin are mapped to /dshtml and the HTML files stored in /dsgw/html are mapped to /ds).

"gwnametrans" on page 84

Gateway Root Suffix

In release 4.0, 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, o=airius.com). Multiple gateways can be set up on an HTTP server that provide access to directory entries that correspond to this root suffix.

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

In release 3.x, to access a different suffix, another HTTP server and another gateway must be configured on the host where the Directory Server is installed.

The configuration procedures provided in this section assume that a Netscape FastTrack (or Enterprise) HTTP server is installed and configured to communicate with the Netscape LDAP Directory server.

Adding an additional document directory is necessary to establish access to the gateway files. From the server manager for the FastTrack or Enterprise Server:

1. Go to Content Mgmt | Additional Document Directories.
2. In the URL prefix field, enter
dsgw
3. In the Map to Directory field, enter
<NSHOME>/dsgw/

where <NSHOME> is the Directory Server's installation directory.

4. Click OK, then Save and Apply.

Adding an additional document directory is necessary to establish access to the gateway files.

1. Go to Content Mgmt | Additional Document Directories.
2. In the URL prefix field, enter dshtml.
3. In the Map to Directory field, enter:
<NSHOME>/slapd-<serverID>/dsgw/html

where <NSHOME> is the Directory Server's installation directory, and <serverID> is the Directory Server's identifier.

4. Click OK, then Save and Apply.

1. Go to Programs | CGI Directory.
2. In the URL prefix field, enter
/dsgw/bin
3. In the CGI directory field, enter:
<NSHOME>/dsgw/bin
4. Click OK, then Save and Apply.

Adding an additional CGI directory is necessary to make the gateway's CGI programs available. From the server manager for the HTTP server:

1. Go to Programs | CGI Directory.
2. In the URL prefix field, enter ds.
3. In the CGI directory field, enter
<NSHOME>/slapd-<serverID>/dsgw/bin
4. Click OK, then Save and Apply.

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 server manager for the HTTP server:

1. Go to 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.

2. Log into the machine as root.
3. Go to the <NSHOME>/dsgw and enter:
# chown <uid> authck

where <uid> is the user name determined in step 1.

4. Verify that the directory is accessible by opening the URL:
http://<webserver-host>:<port>/ds/search

where <webserver-host> is the HTTP server's host name, and <port> is the port number used by the server.

1. Rename dsgw.conf or pb.conf to a new gateway context. For example, dsgw/context/dsgw.conf might become dsgw/context/airius.conf.
2. Set the gwnametrans parameter in the new gateway's .conf file to point to the HTML directory. For example, the gwnametrans parameter setting for airius.conf should point to /dsgw/airiushtml.
3. To support non-anonymous searching (one individual user DN and password per directory instance) using the new gateway, set the binddnfile parameter in airius.conf to point to the location of the file containing the bind DN and bind password be used to access information in the user directory (the binddnfile contains sensitive information; for security purposes, do not store the binddnfile within the /dsgw directory or within any directory served up over HTTP).
4. Create an HTML directory for the new gateway: For example, to provide an HTML directory for airius.conf, copy and rename an existing HTML directory (dsgw/html or dsgw/pbhtml) to /dsgw/airiushtml.
5. Create a template directory containing object class templates and other configuration files. For example, to provide a template directory for airius.conf, copy and rename an existing template directory (/dsgw/config or /dsgw/pbconfig) to /dsgw/airiusconfig.
6. Edit the htmldir and configdir parameters in airius.conf to point to the new HTML and template directories.
7. To access the new gateway instance--in this example, airius.conf--navigate the browser to
http://admin:port/dsgw/bin/lang?context=airius

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 dirmgr, and the root suffix specified by the location-suffix parameter).

The LDAP port is set during Directory server installation. This value can be changed in the baseurl parameter. Example 2.2 shows the syntax used to specify a port number that is different than the default port number of 389.

Setting Up the Directory Manager

When the Directory server is installed, the Directory Manager is by default set to the root DN. The Directory Server 4.0 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.

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

1. Create an entry for the Directory Manager, making sure to set a password for the entry.
2. Set the permissions for the Directory Manager so that it has read and write authority for the entries it manages.
3. When necessary, change the dirmgr parameter to refer to the Directory Manager's distinguished name.

Figure 2.3 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 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.

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.

The syntax in Example 2.3 shows the securitypath parameter specifying the location of the certificate database.

The syntax in Example 2.4 shows the baseurl parameter configured to use ldaps (instead of ldap, the default) and standard SSL port number 636.

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

"baseurl" on page 80

Setting Up Localization

There are two considerations for configuring the gateway character set: the directory contents and the HTTP clients. The ideal character set supports all the characters in the directory, and is displayed properly by all HTTP clients. UTF-8 best supports the Directory Server's internal character (which is UTF-8). However, HTTP clients that are not designed for localization may display UTF-8 poorly.

"Mapping Locations and Entry Types" on page 48

Setting vCard Properties

Mappings between VCARD properties and LDAP attribute type are described in "vcard-property" on page 90.

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.

When the user is using Netscape Communicator 4.x, the Directory server sends Unicode characters. Netscape Navigator 2.x and 3.x clients are not capable of displaying Unicode characters.

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.

1. Install a font that supports Unicode.
2. Go to Edit | Preferences | Appearance | Fonts.
3. From the For the Encoding pull-down menu, select Unicode.
4. From the Variable Width Font pull-down menu, select a Unicode font set (for example, Bitstream Cyberbit).
5. From the Fixed Width Font pull-down menu, select a Unicode font set (for example, Bitstream Cyberbit).
6. Go to Edit | Preferences | Navigator | Languages 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].

1. Install a font that supports Unicode.
2. Go to Options | General Preferences | Fonts.
3. From the For the Encoding pull-down menu, select (on NT) Latin-1 or (on UNIX) Western (ISO-8559-1).
4. For Use the Proportional Font, select a Latin-1 font set.
5. From the Fixed Font pull-down menu, select a Latin-1 font set.
6. Go to Options | General Preferences| Languages and configure the list of languages so that the best description of the user's language is first, followed by less-exact descriptions and 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].

Administrators can reconfigure Javascript preference settings in Communicator 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.