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

Gateway Installation Planning

---

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

Location of Gateway Files

Table 2-1 and Table 2-2 show the locations of gateway files for release 4.0 and release 3.x.

Gateway Release 4.0

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.

Table 2-1    Location of gateway files for release 4.0

File type	Gateway release 4.0
default gateway .conf file	/usr/iplanet/servers/dsgw/context/dsgw.conf
default gateway (dsgw) HTML and template files	/usr/iplanet/servers/dsgw/html /usr/iplanet/servers/dsgw/config
Directory Express .conf file	/usr/iplanet/servers/dsgw/context/pb.conf
Directory Express (pb) HTML and template files	/usr/iplanet/servers/dsgw/pbhtml /usr/iplanet/servers/dsgw/pbconfig

Gateway Cloning
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.

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

Gateway Release 3.x

One gateway is installed for each instantiation of the directory server. The .conf file is stored in /dsgw (under slapd-serverID).

Table 2-2    Location of gateway files for release 3.x

File types	Gateway release 3.x
default gateway .conf file	/usr/iplanet/servers/slapd-serverID/dsgw/dsgw.conf
default gateway HTML and template files	/usr/iplanet/servers/slapd-serverID/html /usr/iplanet/servers/slapd-serverID/config

Securing 4.0 Gateway Configuration and Settings

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

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 (/usr/iplanet/servers/dsgw), or in any directory that is served up over HTTP.

Protecting Root Processes on UNIX Systems

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

Migrating 3.x Default Gateways to Release 4.0

The 3.x gateway will not be able to co-exist with 4.0 gateways unless it is first migrated to the 4.0 gateway structure.

An upgrade script, dsgwmig, is available which completes the migration of dsgw.conf and it's relevant files. The script does not overwrite the existing 3.x gateway, but renames it as a new gateway instance (dsgw-30.conf) that runs from the 4.0 /dsgw installation directory. The 3.x gateway will continue to work with the 3.x directory server installation.

The migration script is installed in /usr/iplanet/servers/bin/slapd/admin/bin during directory server installation. The script makes the following changes to the 3.x gateway.

• 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 /usr/iplanet/servers/dsgw/context and renames it dsgw-30.conf.

• Changes PATH_INFO to QUERY_STRING

Location of migrated dsgw.conf file

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

http://<host>:<port>/dsgw/bin/lang?context=dsgw-30

Running the Gateway Migration Script

The dsgwmig script runs automatically during the 3.x -> 4.0 directory server migration process.

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

Updating the Gateway with Changes to Directory Server Configuration

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 /usr/iplanet/servers/bin/slapd/admin/bin.

Changes made to the directory server configuration (slapd.conf) by the iPlanet 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 Release 4.0

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

There are many factors affecting 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)

In general, gateway performance on the iPlanet 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 iPlanet Administration server that is also running a iPlanet server process as root. This may expose sensitive information about the configuration of iPlanet 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 recommends iPlanet Enterprise Server or FastTrack Server.

---

HTTP Server Configuration

---

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

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

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

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=siroe.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.

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.

---

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 iPlanet Console).

---

Configuring the Gateway for Enterprise or FastTrack Servers

The configuration procedures provided in this section assume that a iPlanet Web Server, FastTrack or Enterprise edition, is installed and configured to communicate with the iPlanet LDAP directory server.

In release 4.0, Directory Express and the default gateway are installed with the directory server and configured to run under the iPlanet 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, following the procedures provided in this section.

In release 3.x, the gateway must be configured to communicate with the LDAP directory server, following the procedures provided in this section. The 3.x gateway allows one instance of the gateway per HTTP server.

Figure 2-1 shows the iPlanet FastTrack Server configuration screen used to configure an additional document directory. Figure 2-2shows the iPlanet Enterprise Manager configuration screen used to configure an additional CGI directory.

Figure 2-1    Configuring an Additional Document Directory

Figure 2-2    Configuring an Additional CGI Directory

Add an Additional Document Directory (4.0 Gateways)

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

   /usr/iplanet/servers/dsgw/

4. Click OK, then Save and Apply.

Add an Additional Document Directory (3.x Gateways)

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

From the server manager for the Enterprise Server:

1. Go to Content Mgmt | Additional Document Directories.

2. In the URL prefix field, enter dshtml.

3. In the Map to Directory field, enter:

   /usr/iplanet/server/slapd-serverID/dsgw/html

   where serverID is the directory server's identifier.

4. Click OK, then Save and Apply.

Add an Additional CGI Directory (for 4.0 Gateways)

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

   /dsgw/bin

3. In the CGI directory field, enter:

   /usr/iplanet/servers/dsgw/bin

4. Click OK, then Save and Apply.

Add an Additional CGI Directory (for 3.x Gateways)

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:

   /usr/iplanet/servers/slapd-serverID/dsgw/bin

4. Click OK, then Save and Apply.

Change Permissions of Cookie Directory (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 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 /usr/iplanet/servers/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 hostname, and port is the port number used by the server.

   
   

   ---

   Note	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 (4.0 only)

---

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

1. Rename dsgw.conf or pb.conf to a new gateway context. For example, dsgw/context/dsgw.conf might become dsgw/context/siroe.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 siroe.conf should point to /dsgw/siroehtml.

3. To support non-anonymous searching (one individual user DN and password per directory instance) using the new gateway, set the binddnfile parameter in siroe.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 /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 siroe.conf, copy and rename an existing HTML directory (dsgw/html or dsgw/pbhtml) to /dsgw/siroehtml.

5. Create a template directory containing object class templates and other configuration files. For example, to provide a template directory for siroe.conf, copy and rename an existing template directory (/dsgw/config or /dsgw/pbconfig) to /dsgw/siroeconfig.

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

7. To access the new gateway instance--in this example, siroe.conf--navigate the browser to

   http://admin:port/dsgw/bin/lang?context=siroe

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 dirmgr, 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

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.siroe.com:3000/o%3Dsiroe.com"

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.

---

Note	For security reasons, set the Directory Manager to an entry other than the root DN.

---

Configuring the Directory Manager DN

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 will manage.

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

   
   

   ---

   Note	End users frequently forget their passwords, so give the 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 iPlanet Directory Server Administrator's Guide.

Authenticating as Directory Manager
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 authlifetime parameter, which defines the number of seconds that a user may remain authenticated, is described in location.

Figure 2-3    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 iPlanet Directory Server Administrator's Guide describes the Suffix parameter and provides syntax examples. Setting the root suffix is also described in the iPlanet 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 hostname 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 iPlanet Directory Server Administrator's Guide. Information about managing key and certificate databases is provided in Managing iPlanet Servers.

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 "/export/TEST/alias/cert.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://dir.siroe.com:636/o%3Dsiroe.com"

---

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.

---

For more information about the baseurl parameter, see baseurl.

Setting Up Localization

There are two considerations for configuring the gateway character set: what the directory contains, and the HTTP clients. The ideal character set supports all the characters in the directory, and will be 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.

If a single character set works well for most gateway users, define it using the charset parameter in the gateway's .conf file. For users who require a character set that supports another language, create the appropriate ../dsgw/LANG/dsgwcharset.conf file (where LANG represents a language, such as "en" or "fr") and configure the HTTP clients for these users to specify their language in the HTTP Accept-language header.

Setting the language and character set for communication with HTTP clients is described in Chapter 3 "Gateway Localization."

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

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.x, the directory server sends Unicode characters. Netscape Navigator 2.x and 3.x clients are not capable of displaying Unicode characters.

When the user is using Netscape Navigator 3.x and lower, the directory server sends Latin-1 characters unless the charset parameter has been configured in the gateway's .conf file. The Latin-1 character set includes most Western languages, including German, French, English, and Spanish.

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 Communicator 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 Communicator 4.x for Preferred Language

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 list, select a Unicode font set (for example, Bitstream Cyberbit).

5. From the Fixed Width Font pull-down list, 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].

Configuring Navigator 3.01 for Preferred Language

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 list, 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].

Customizing Communicator's LDAP Settings

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.