Red Hat Version4.1 User Manual
World Wide Web
Chat
URL
merchant system
Gateway Customization
security
community system
server
TCP/IP
HTML
Inter
Guide
Netscape Directory Server
SSL
Publishing
secure sockets layer
Internet
encryption
http://www
HTML
JavaScript
certificate
Proxy
Version 4.1
IStore
mail
electronic commerce
comp.sys
directory server
Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software
programs offered by Netscape (referred to herein as "Software") and related documentation. Use of the Software and
related documentation is governed by the license agreement accompanying the Software and applicable copyright
law.
Your right to copy this documentation is limited by copyright law. Making unauthorized copies, adaptations, or
compilation works is prohibited and constitutes a punishable violation of the law. Netscape may revise this
documentation from time to time without notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL
NETSCAPE BE LIABLE FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND
ARISING FROM ANY ERROR IN THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION ANY LOSS OR
INTERRUPTION OF BUSINESS, PROFITS, USE, OR DATA.
The Software and documentation are copyright ©1998 Netscape Communications Corporation. All rights reserved.
Netscape, Netscape Navigator, Netscape Certificate Server, Netscape DevEdge, Netscape FastTrack Server, Netscape
ONE, SuiteSpot, and the Netscape N and Ship’s Wheel logos are registered trademarks of Netscape Communications
Corporation in the United States and other countries. Other Netscape logos, product names, and service names are
also trademarks of Netscape Communications Corporation, which may be registered in other countries. Other product
and brand names are trademarks of their respective owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must
be in full compliance with all United States and other applicable laws and regulations. Any provision of Netscape
software or documentation to the U.S. Government is with restricted rights as described in the license agreement
accompanying Netscape software.
The Team
Writer: Doug Meier
Technical Editor, Gateway: Rob Powers
Technical Editor, Gateway Localization: Noriko Hosoi
Version 4.1
© Netscape Communications Corporation 1999. All Rights Reserved. Printed in USA
99 98 97 10 9 8 7 6 5 4 3 2 1
Netscape Communications Corporation 501 East Middlefield Road, Mountain View, CA 94043
The descriptions, instructions, and examples in this guide can be used to create
and modify a gateway instance to suit the needs of users in your organization.
Who Needs This Guide
This guide is for anyone who needs to implement a simple gateway instance
with basic directory lookup functionality. It is also for users who wish to
implement a more powerful gateway instance with directory authentication and
administration capability. This guide assumes the reader is familiar with HTML
file syntax and has a rudimentary understanding of how the LDAP directory
stores information.
Preface
What’s In This Guide
• Chapter 1, Gateway Features: Describes features and functionality of the
gateways installed with Directory Server 4.x. HTTP server recommendations
are also provided.
• Chapter 2, Setting Up the Gateway: Identifies the planning decisions and
tasks required to install and initially configure a gateway. Includes
instructions for HTTP server configuration, procedures for setting up a new
gateway instance, procedures for changing configuration settings on
existing gateways, and recommendations for configuring gateway clients.
• Chapter 3, Gateway Localization: Describes Netscape support for UTF-8,
explains how the gateway selects a character set, identifies the tasks
required to set up additional gateway locales, and explains how to set up
gateway locales for translation.
• Chapter 4, Files Controlling Gateway Functionality: Identifies gateway file
components, including search configuration files, object class templates,
script files, and search result templates.
iii
Related Information
• Chapter 5, Entry Types and Object Class Attributes: Provides examples of
entry types (objects) defined in the gateway’s .conf file, provides examples
of locations mapped to entry types, and discusses gateway directives.
• Chapter 6, Search Attributes, Filters, and Results: Provides examples for
modifying search attributes, adding search support for a new object,
modifying default search filters, and customizing search results.
• Chapter 7, Customizing Graphics and Color: Describes how to change the
appearance of default gateway forms.
• Appendix A, .conf Parameters: Describes, in alphabetical order, gateway
configuration parameters defined in dsgw.conf and pb.conf.
• Appendix B, Gateway Directives Reference: Describes directives used in
Gateway HTML object class and search result templates.
• Appendix C, CGI Usage: Provides regular expression-type descriptions of
the ways to invoke the CGIs in script files.
• Appendix D, Gateway User Help: Provides instructions for using the
Directory Server 4.0 gateway interface. The information supplied here is
intended to be repurposed as help topics that can be made available to
gateway users from the Help button on gateway forms.
Related Information
For more information about working with Directory Server, see these
documents:
• Netscape Directory Server Installation Guide, Version 4.0
• Netscape Directory Server Administration Guide, Version 4.0
• Netscape Directory Server Release Notes, Version 4.0
• Managing Servers with Netscape Console, Version 4.0
• Netscape Directory Server Deployment Guide, Version 3.0
• Customizing LDAP Settings for Communicator 4.0x
iv Netscape Directory Server Gateway Customization Guide
Contents
Preface ................................................................................................................ iii
Who Needs This Guide ....................................................................................... iii
What’s In This Guide ........................................................................................... iii
Related Information ..............................................................................................iv
Chapter 1 Gateway Features .......................................................................1
What Is a Gateway? ...............................................................................................1
HTTP Server Requirements for Gateways ............................................................2
Gateways Installed with Directory Server 4.0 ......................................................2
Default Gateway (dsgw.conf) ...........................................................................3
Directory Express (pb.conf) .............................................................................3
Support for Multiple Gateway Instances ..............................................................5
Specifying Gateway Configuration to Gateway CGIs .....................................6
GET Operations (GCONTEXT) ....................................................................6
POST Operations (PCONTEXT) ...................................................................7
URLs for Gateway Access .................................................................................7
Release 4.0 ....................................................................................................7
Release 3.x ....................................................................................................7
Gateway Localization ............................................................................................8
Gateway Locales ...............................................................................................8
Character Sets ....................................................................................................8
Non-Anonymous Searching ..................................................................................9
binddnfile ..........................................................................................................9
Do Not Server Up binddnfile over HTTP ...................................................9
Compatibility with Existing Gateways ................................................................10
Automatic Updates to Directory Configuration ..................................................10
Chapter 2 Setting Up the Gateway ..........................................................11
Gateway Installation Planning ............................................................................11
Location of Gateway Files ..............................................................................12
Contents v
Gateway Release 4.0 ..................................................................................12
Gateway Release 3.x .................................................................................. 13
Securing 4.0 Gateway Configuration and Settings ........................................ 13
Protecting Bind DN and Password ...........................................................13
Protecting Root Processes on UNIX Systems ...........................................13
Migrating 3.x default Gateways to Release 4.0 ............................................. 14
Location of migrated dsgw.conf file .........................................................14
Running the Gateway Migration Script ..................................................... 15
Updating the Gateway with Changes to Directory Server Configuration ... 15
HTTP Server Recommendations for Directory Server Gateway Release 4.0 15
Factors Affecting Gateway Usage ............................................................. 15
Running the Gateway in High-Usage Networks ......................................16
HTTP Server Configuration ................................................................................ 17
Name Translation Mapping ............................................................................17
Gateway Root Suffix ....................................................................................... 17
Configuring the Gateway for Enterprise or FastTrack Servers ..................... 18
Add an Additional Document Directory (4.0 Gateways) ......................... 20
Add an Additional Document Directory (3.x Gateways) .........................20
Add an Additional CGI Directory (for 3.x Gateways) ............................. 21
Change Permissions of Cookie Directory (UNIX only) ...........................21
Creating a New Gateway Instance (4.0 only) ....................................................22
Gateway Cloning .......................................................................................23
Gateway .conf File Configuration ...................................................................... 23
Changing the Default Port Setting .................................................................23
Setting Up the Directory Manager .................................................................24
Configuring the Directory Manager DN ................................................... 24
Authenticating as Directory Manager ........................................................24
Setting up the Suffix for Adding Entries ........................................................ 25
Setting Up SSL Support .................................................................................. 25
Configuring the Gateway to Use SSL ........................................................26
Setting Up Localization ..................................................................................26
Setting Locations and newtypes .................................................................... 27
Setting vCard Properties .................................................................................27
vi Netscape Directory Server Gateway Customization Guide
Configuring Gateway Clients ..............................................................................27
Language Support for HTTP Clients ..............................................................27
Unicode and Latin-1 Character Sets ..........................................................28
Displaying a Non-English Alphabet ...............................................................28
Configuring Communicator 4.x for Preferred Language ..............................28
Configuring Navigator 3.01 for Preferred Language .....................................29
Customizing Communicator’s LDAP Settings ................................................29
Chapter 3 Gateway Localization .............................................................31
Unicode and Netscape Support for UTF-8 ........................................................31
How the Gateway Selects a Character Set .........................................................32
How the Gateway Selects from Multiple Requested Character Sets ............32
HTTP Clients that Request UTF-8 ..................................................................33
HTTP Clients that Do Not Request UTF-8 .....................................................33
Special Characters ...............................................................................................34
Non-breaking Space ...................................................................................34
Query Strings ..............................................................................................34
Gateway Locales ..................................................................................................34
Support for Multiple Locales ..........................................................................34
Setting Up Locales for Translation .....................................................................35
dsgw-l10n.conf ................................................................................................35
Chapter 4 Files Controlling Gateway Functionality ........................37
An Overview of Gateway File Types .................................................................37
Gateway .conf Files .............................................................................................39
dsgw.conf ...................................................................................................39
pb.conf .......................................................................................................39
Gateway Search Configuration Files ..................................................................39
dsgwsearchprefs.conf ................................................................................40
dsgwfilter.conf ............................................................................................40
Contents vii
Object Class Templates ....................................................................................... 40
Gateway Script Files ............................................................................................ 41
Gateway Search Result Templates ..................................................................... 42
Banner Files ......................................................................................................... 43
Chapter 5 Entry Types and Object Class Attributes .........................45
Entry Types (Object Classes) .............................................................................. 45
Parameters Controlling Entry Types .............................................................. 45
template ...................................................................................................... 46
location ....................................................................................................... 46
newtype ...................................................................................................... 46
Considerations for Adding New Entry Types ...............................................47
Mapping Locations and Entry Types .................................................................. 48
Mapping Entry Types to Locations ................................................................ 48
Setting Up Organizational Units ................................................................49
Configuring DN Formats for Entry Types ..................................................... 49
UID-Based DN ........................................................................................... 49
Modifying the Default DN format ............................................................. 50
Object Class Attributes in Template Files ..........................................................50
Default Gateway Object Classes .................................................................... 50
Templates and Directives ............................................................................... 51
Entry-Related Directives ............................................................................ 51
Adding Attributes to Object Classes .............................................................. 51
Deleting Attributes from Object Classes ........................................................52
Extending Object Classes ...............................................................................53
Adding a Template for a Child of a Parent Class ..................................... 53
Creating a New Parent Object Class ..............................................................55
Chapter 6 Search Attributes, Filters, and Results .............................57
Search Configuration Files ..................................................................................57
dsgwsearchprefs.conf .....................................................................................58
dsgwfilter.conf ................................................................................................ 58
Changing Search Scope ......................................................................................59
Modifying Search Attributes for Advanced Searches ........................................59
Standard and Advanced Searches ..................................................................59
viii Netscape Directory Server Gateway Customization Guide
Specifying Search Attributes for Person ........................................................61
Directory Express Search Support for User ID .............................................63
Adding Search Support for Additional Attributes .........................................63
Adding Search Support for a New Object .........................................................64
Extending Search Preferences ........................................................................64
Creating a New Search Object .......................................................................65
Modifying Default Search Filters ........................................................................66
Search Filters for User Data Patterns .............................................................66
Specifying a Search Filter for a New Object ................................................. 67
Customizing Search Result Templates ................................................................68
How the Gateway Displays Search Results ...................................................68
Search Result Tables ..................................................................................68
Modifying Search Result Templates ...............................................................69
Adding Information to Search Results ......................................................69
Removing Information from Search Results .............................................70
Chapter 7 Customizing Graphics and Color ......................................71
Appearance of Gateway Forms ..........................................................................71
Updating the Banner Image ...............................................................................72
Changing Dimensions of Banner Image .......................................................72
Changing Filename of Banner Image ............................................................72
Updating Button Images .....................................................................................73
Color Schemes .....................................................................................................74
Files Controlling Colors on Gateway Forms .................................................74
Changing Colors Using BODY Tag ...............................................................76
Changing Colors Using Directives .................................................................76
Changing Table Colors .......................................................................................77
Specifying Color Names and Color Codes ....................................................77
Changing Color of Table Headings ...............................................................78
Changing the Background Color of Table Rows ..........................................78
Appendix A .conf Parameters ..................................................................79
authlifetime .....................................................................................................79
baseurl .............................................................................................................80
binddnfile ........................................................................................................81
Contents ix
changeHTML ................................................................................................... 81
charset .............................................................................................................81
configdir .......................................................................................................... 82
dirmgr ..............................................................................................................82
gwnametrans ................................................................................................... 83
htmldir .............................................................................................................83
ignoreAccetpCharsetFrom ..............................................................................83
include ............................................................................................................ 84
location ........................................................................................................... 84
location-suffix ................................................................................................. 85
newtype .......................................................................................................... 85
NLS .................................................................................................................. 86
securitypath ..................................................................................................... 86
template .......................................................................................................... 87
vcard-property ................................................................................................ 87
Appendix B Gateway Directives Reference ........................................91
Introduction .........................................................................................................91
Structure of an HTML Template ................................................................92
Structure of an HTML Template for Directory List ................................... 92
Context-Related Directives .................................................................................93
GCONTEXT ................................................................................................93
PCONTEXT .................................................................................................93
Entry-Related Directives ......................................................................................94
DS_ENTRYBEGIN ...................................................................................... 94
DS_ENTRYEND ..........................................................................................94
DS_ATTRIBUTE .........................................................................................94
DS_OBJECTCLASS ..................................................................................... 98
DS_VIEW_SWITCHER ................................................................................ 98
DS_SORTENTRIES ..................................................................................... 99
DS_SEARCHDESC .................................................................................... 100
DS_POSTEDVALUE ................................................................................. 100
DS_EDITBUTTON .................................................................................... 100
DS_DELETEBUTTON ............................................................................... 101
x Netscape Directory Server Gateway Customization Guide
DS_SAVEBUTTON ................................................................................... 101
DS_EDITASBUTTON ............................................................................... 102
DS_NEWPASSWORD ...............................................................................102
DS_CONFIRM_NEWPASSWORD ............................................................. 103
DS_OLDPASSWORD ................................................................................103
DS_HELPBUTTON ................................................................................... 103
DS_CLOSEBUTTON ................................................................................. 104
DS_BEGIN_ENTRYFORM ........................................................................104
DS_END_ENTRYFORM ............................................................................104
DS_EMIT_BASE_HREF ............................................................................. 105
DS_DNEDITBUTTON .............................................................................. 105
DS_BEGIN_DNSEARCHFORM ................................................................105
DS_END_DNSEARCHFORM ....................................................................106
DS_ATTRVAL_SET ................................................................................... 106
IF/ ELSE/ ELIF/ ENDIF ............................................................................ 106
Miscellaneous Directives ...................................................................................108
BODY ....................................................................................................... 108
COLORS ....................................................................................................108
TITLE ........................................................................................................ 109
ENDHTML ................................................................................................109
HELPBUTTON ..........................................................................................109
INCLUDE ..................................................................................................110
INCLUDECONFIG .................................................................................... 110
DS_LAST_OP_INFO ................................................................................. 110
DS_LOCATIONPOPUP ............................................................................111
DS_GATEWAY_VERSION ........................................................................111
IF/ ELSE/ ELIF/ ENDIF ............................................................................ 112
Appendix C CGI Usage ..............................................................................113
auth ........................................................................................................... 113
csearch ...................................................................................................... 113
dnedit ........................................................................................................ 114
doauth ....................................................................................................... 114
domodify ..................................................................................................114
Contents xi
dosearch ...................................................................................................114
edit ............................................................................................................ 115
lang ........................................................................................................... 115
newentry ..................................................................................................115
search ....................................................................................................... 115
unauth ...................................................................................................... 115
Appendix D Gateway User Help ........................................................... 117
Directory Tree Structure ................................................................................... 117
Distinguished Name Syntax .................................................................... 118
Unique Distinguished Names .................................................................. 118
Searching the Directory ....................................................................................118
Performing a Standard Search ..................................................................... 119
Name Search Functionality ...................................................................... 120
Name and Initial Search Functionality ....................................................120
Searching for Phone Numbers ................................................................121
Searching for Email Addresses ................................................................ 122
Using LDAP Search Filters ....................................................................... 122
Advanced Search ..........................................................................................122
Performing an Advanced Search ............................................................. 123
Viewing Search Results ................................................................................ 123
No matches .............................................................................................. 124
A Single match .........................................................................................124
Multiple matches ...................................................................................... 124
Search Tips ................................................................................................... 124
Numeric Values ........................................................................................ 124
Blank Spaces ............................................................................................ 124
Authentication ................................................................................................... 125
Access Control .............................................................................................. 125
Authenticating to the Directory ................................................................... 126
Maintaining Authentication Credentials ...................................................... 126
Logging Out of the Directory ...................................................................... 127
Troubleshooting Authentication Problems ..................................................127
xii Netscape Directory Server Gateway Customization Guide
Adding Entries Using the New Entry Form .....................................................128
Adding a Person Entry ................................................................................. 129
Adding an NT Person Entry .................................................................... 130
Adding a Group Entry ..................................................................................130
Adding an NT Group ............................................................................... 131
Adding an Organizational Unit Entry ..........................................................131
Adding an Organization Entry ..................................................................... 132
Index ................................................................................................................133
Contents xiii
xiv Netscape Directory Server Gateway Customization Guide
Tables
Location of gateway files for release 4.0 ............................................................12
Location of gateway files for release 3.x ............................................................13
Gateway File Types and Locations ....................................................................38
Default Template Files and Related Object Classes .........................................41
Gateway Forms and Corresponding Script Files ................................................42
Default Search Result Templates ........................................................................42
Banner Files Controlling Appearance of Gateway Forms .................................43
Default Object Classes .........................................................................................50
Valid Search Scopes .............................................................................................59
Bit Positions and Corresponding Search Match Types ......................................62
Default Search Results for Search Objects ..........................................................69
Button Images ......................................................................................................73
Files Controlling Appearance of Gateway Forms ..............................................75
Colors and Related Attributes for BODY tag .....................................................76
Sixteen Standard Colors and their Hexadecimal Values ....................................77
DS_ATTRIBUTE: Display of Syntax Argument ...................................................95
DS_ATTRIBUTE: Display of Type Argument .....................................................95
DS_ATTRIBUTE: Display of options Argument .................................................96
Conditions supported for ELSE and ENDI .......................................................107
Entry Types That Can Be Specified ..................................................................119
Advanced Search Attributes ..............................................................................123
Authentication Problems ...................................................................................128
xv
xvi Gateway Customization Guide
Examples
HTML and configuration directories specified in pb.conf ...................................6
Embedding GCONTEXT in a Link ........................................................................6
Specifying PCONTEXT in an HTML Form ............................................................7
Setting up .conf file and directories for new gateway instance ........................22
Changing LDAP port in the baseurl parameter ..................................................23
Specifying the Path for Certificate Database ......................................................26
Specifying SSL Communication ...........................................................................26
Creating a locale for Chinese (zh) translation ....................................................35
Mapping of Locations and Entry Types in dsgw.conf .......................................48
Adding Initials attribute to orgperson object class ............................................51
Deleting mobile phone attribute from orgperson object class .........................52
Adding template for subclass airiusPerson ........................................................53
Search Attributes for Person Entry ......................................................................61
Extending Search Preferences to Include Pager Number ..................................63
Editing dsgwsearchprefs.conf to Extend a Search Preference ..........................64
dsgw-people entry configured to search for dateofBirth values .......................65
Creating a new dsgwsearchprefs.conf entry for OrgRole ..................................65
Creating a new dsgwfilter.conf entry for orgrole ...............................................66
Search Filter for Email Address Searches ...........................................................67
Modifying a search filter pattern .........................................................................67
Adding OrgUnit to Search Results for People ....................................................69
Changing color settings using COLOR directives ..............................................76
xvii
xviii Writer’s Guide
Chapter
1
Chapter 1Gateway Features
This chapter describes the gateway features introduced with release 4.0 of the
Directory Server. Topics include:
• What Is a Gateway?
• HTTP Server Requirements for Gateways
• Gateways Installed with Directory Server 4.0
• Non-Anonymous Searching
• Compatibility with Existing Gateways
• Automatic Updates to Directory Configuration
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.
Chapter 1, Gateway Features 1
HTTP Server Requirements for Gateways
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:
• a .conf file, stored in <NSHOME>/dsgw/context, defining the context for a
gateway instance (for instance, dsgw.conf defines the dsgw gateway
instance).
• an HTML directory for object class templates and other files containing
gateway directives used to communicate with the LDAP server.
• a configuration directory for directory search, directory authentication,
language files, and gateway scripts.
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.
2 Netscape Directory Server Gateway Customization Guide
Gateways Installed with Directory Server 4.0
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.
Chapter 1, Gateway Features 3
Gateways Installed with Directory Server 4.0
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
4 Netscape Directory Server Gateway Customization Guide
Figure 1.3 Directory Express Extended Search Results
Support for Multiple Gateway Instances
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.
Chapter 1, Gateway Features 5
Support for Multiple Gateway Instances
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.
6 Netscape Directory Server Gateway Customization Guide
Support for Multiple Gateway Instances
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 93
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
Chapter 1, Gateway Features 7
Gateway Localization
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
8 Netscape Directory Server Gateway Customization Guide
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
Non-Anonymous Searching
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 Server 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).
Chapter 1, Gateway Features 9
Compatibility with Existing Gateways
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
10 Netscape Directory Server Gateway Customization Guide
Chapter
2
Chapter 2Setting 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
When preparing to deploy a gateway in the enterprise, consider the following
planning issues:
• 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
Chapter 2, Setting Up the Gateway 11
Gateway Installation Planning
• whether to migrate existing gateways to release 4.1 gateways or to let them
• how changes to Directory Server configuration and user directory will be
• which type of HTTP server best suits the needs of your enterprise
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.
co-exist
updated on the gateway
Table 2.1 Location of gateway files for release 4.0
File Type Location
default gateway .conf file <NSHOME>/dsgw/context/dsgw.conf
default gateway (dsgw)
HTML and template files
Directory Express .conf file <NSHOME>/dsgw/context/pb.conf
Directory Express (pb)
HTML and template files
<NSHOME>/dsgw/html
<NSHOME>/dsgw/config
<NSHOME>/dsgw/pbhtml
<NSHOME>/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.
12 Netscape Directory Server Gateway Customization Guide
Loading...