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
Gateway Installation Planning
See Also
“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>).
Table 2.2 Location of gateway files for release 3.x
File Type Location
default gateway .conf file <NSHOME>/slapd-<server>/dsgw/dsgw.conf
default gateway HTML and
template files
<NSHOME>/slapd-<server>/html
<NSHOME>/slapd-<server>/config
Securing 4.0 Gateway Configuration and Settings
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.
Protecting Root Processes on UNIX Systems
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.
Chapter 2, Setting Up the Gateway 13
Gateway Installation Planning
Migrating 3.x default Gateways to Release 4.0
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.
An upgrade script, dsgwmig, is available which completes the migration of
dsgw.conf and its 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 <NSHOME>/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 /<NSHOME>/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
14 Netscape Directory Server Gateway Customization Guide
Gateway Installation Planning
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 <NSHOME>/bin/slapd/admin/bin.
Changes made to the Directory Server configuration (slapd.conf) through the
Netscape Console are posted to updatedsgw and the relevant gateway files are
updated. These files are updated 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 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.
Factors Affecting Gateway Usage
Many factors affect gateway performance on an HTTP server, including:
Chapter 2, Setting Up the Gateway 15
Gateway Installation Planning
• the number of users accessing the gateway at a given time
• the complexity of the directory searches performed and the search results
• 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
• the speed and capacity of the network (network hardware and software)
In general, gateway performance on the Netscape Administration Server begins
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 Netscape Administration server
that is also running a Netscape server process as root. This may expose
sensitive information about the configuration of Netscape servers.
required
computer
Running the Gateway in High-Usage Networks
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.
Note If you do decide to migrate the gateway’s configuration files to a high-
performance HTTP server, Netscape recommends Netscape Enterprise Server or
FastTrack Server.
See Also
“Name Translation Mapping” on page 17
16 Netscape Directory Server Gateway Customization Guide
HTTP Server Configuration
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).
See Also
“gwnametrans” on page 83
HTTP Server Configuration
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.
When the Directory Server’s suffix changes, it is necessary to run the
updatedsgw script manually in order to propagate the change to all gateway
instances.
See Also
“Updating the Gateway with Changes to Directory Server Configuration” on
page 15
Chapter 2, Setting Up the Gateway 17
HTTP Server Configuration
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 through the Netscape Console).
Configuring the Gateway for Enterprise or FastTrack Servers
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.
In release 4.0, 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, 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 Netscape FastTrack Server configuration screen used to
configure an additional document directory. Figure 2.2 shows the Netscape
Enterprise Manager configuration screen used to configure an additional CGI
directory.
18 Netscape Directory Server Gateway Customization Guide
Figure 2.1 Configuring an Additional Document Directory
Figure 2.2 Configuring an Additional CGI Directory
HTTP Server Configuration
Chapter 2, Setting Up the Gateway 19
HTTP Server Configuration
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
3. In the Map to Directory field, enter
4. Click OK, then Save and Apply.
Add an Additional Document Directory (3.x Gateways)
dsgw
<NSHOME>/dsgw/
where <NSHOME> is the Directory Server’s installation directory.
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:
<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.
Add an Additional CGI Directory (for 4.0 gateways)
20 Netscape Directory Server Gateway Customization Guide
HTTP Server Configuration
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:
<NSHOME>/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
<NSHOME>/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
Chapter 2, Setting Up the Gateway 21
Creating a New Gateway Instance (4.0 only)
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.
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 is running under the
Netscape Administration server or a similarly capable HTTP server.
Example 2.1 Setting up .conf file and directories for new gateway instance
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).
22 Netscape Directory Server Gateway Customization Guide
Gateway .conf File Configuration
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
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
Changing the Default Port Setting
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.
Example 2.2 Changing LDAP port in the baseurl parameter
baseurl “ldaps://dirserver.airius.com:3000/o%3Dairius.com”
Chapter 2, Setting Up the Gateway 23
Gateway .conf File Configuration
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, Netscape recommends setting 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 manages.
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 manages.
The dirmgr parameter is described in “dirmgr” on page 82. Creating directory
entries is described in the Netscape Directory Server Administrator’s Guide.
Authenticating as Directory Manager
Figure 2.3shows 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” on page 84.
24 Netscape Directory Server Gateway Customization Guide
Figure 2.3 Authenticating as Directory Manager
Gateway .conf File Configuration
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 locationsuffix parameter can point to any suffix in a directory.
Setting the location-suffix parameter is described in “include” on page 84. 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.
Chapter 2, Setting Up the Gateway 25
Gateway .conf File Configuration
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 Netscape Servers.
Configuring the Gateway to Use SSL
The syntax in Example 2.3 shows the securitypath parameter specifying the
location of the certificate database.
Example 2.3 Specifying the Path for Certificate Database
securitypath “/export/TEST/alias/cert.db”
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.
Example 2.4 Specifying SSL Communication
baseurl “ldaps://dir.airius.com:636/o%3Dairius.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.
See Also
“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 UTF8 poorly.
26 Netscape Directory Server Gateway Customization Guide
Configuring Gateway Clients
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 Locations and newtypes
See Also
“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 87.
Configuring Gateway Clients
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.
Chapter 2, Setting Up the Gateway 27
Configuring Gateway Clients
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 Netscape 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 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).
28 Netscape Directory Server Gateway Customization Guide
Configuring Gateway Clients
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 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].
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.
Chapter 2, Setting Up the Gateway 29
Configuring Gateway Clients
• In the Search Directory dialog, users can enter more complex query
• Users can enter LDAP URLs (beginning with the “ldap://” prefix) in
See Also
Customizing LDAP Settings for Communicator 4.0x
expressions to search an LDAP directory using native LDAP searches.
Navigator (web browser) windows to search an LDAP directory.
30 Netscape Directory Server Gateway Customization Guide
Chapter
3
Chapter 3Gateway Localization
This chapter describes gateway localization and identifies the tasks required to
set up additional gateway locales. Topics include:
• Unicode and Netscape Support for UTF-8
• How the Gateway Selects a Character Set
• Special Characters
• Gateway Locales
• Setting Up Locales for Translation
Unicode and Netscape Support for UTF-8
Unicode is a character set containing all the characters of all the world’s major
languages. There are different standard encodings of Unicode, including UCS-2,
which is NT’s Unicode version, and UTF-8, the version of Unicode specified by
version 3 of the LDAP protocol.
Netscape products use UTF-8 in versions 2 and 3 of LDAP. Most software
included in the Directory Server product uses UTF-8 internally, and at
interfaces other than LDAP (for example in command-line parameters and LDIF
files).
Chapter 3, Gateway Localization 31
How the Gateway Selects a Character Set
The NT Synchronization Server, installed with the Directory Server, converts
UTF-8 to and from NT’s Unicode representation (UCS-2).
Note Netscape Communicator 4.x supports UTF-8. Netscape Navigator 3.x does not.
How the Gateway Selects a Character Set
The gateway can output web pages in many character sets. The gateway selects
a character set for each HTTP client based on a combination of input from the
client and from the gateway’s configuration files. Releases 3.x and 4.0 of the
gateway select a character set for transmission according to this priority:
• character set defined in the client’s HTTP Accept-charset header (in release
4.0, this can be overridden for a particular browser using the
ignoreAcceptCharsetFrom parameter).
• character set defined in the client’s HTTP Accept-language header (for
instance, for Japanese, the character set would be defined as ../dsgw/ja/
dsgwcharset.conf)
• character set defined in the gateway’s .conf file by the charset parameter.
How the Gateway Selects from Multiple Requested Character Sets
When a client includes more than one character set in a request header, and the
gateway supports more than one of these, it selects a character set according to
this priority:
•UTF-8
• of the possible character sets, the character set with the highest Q value (for
example, “de;q=1, en;q=0.5, fr;q=0.7” would give German the highest Q
value)
• the character set that appears first in the request header.
• Latin-1 (ISO-8859-1)
32 Netscape Directory Server Gateway Customization Guide
How the Gateway Selects a Character Set
HTTP Clients that Request UTF-8
Browsers designed for localization are configured to request the UTF-8
character set by default. To support localization, the gateway is preconfigured
to transmit the UTF-8 character set to these clients: Netscape Communicator
version 4.0 and greater and to Internet Explorer version 4.0 and greater. Release
4.0 of the gateway allows this preconfiguration to be overridden using the
ignoreAcceptCharsetFrom parameter.
See Also
“ignoreAccetpCharsetFrom” on page 83
The conversion from UTF-8 to the Gateway client’s chosen character set is
performed shortly before output.
HTTP Clients that Do Not Request UTF-8
For browsers that do not request UTF-8 by default (including Netscape
Navigator 3.x and pre-4.0 releases of Internet Explorer), the Gateway selects a
character set from the Accept-Charset request header or from the AcceptLanguage request header, depending on the HTTP client.
Some HTTP clients don’t request any character set information. For these
clients, the Gateway’s charset parameter definition is the default. When the
charset parameter is not defined in dsgw.conf, the Gateway uses Latin-1 (which
is the default in HTTP).
In addition to UTF-8 and Latin-1, the Gateway can convert to and from several
national character sets, depending on the client’s needs and configuration,
including:
•Shift_JIS
•Big5
•EUC-KR
Chapter 3, Gateway Localization 33
Special Characters
Special Characters
Non-breaking Space
If the client’s character set lacks a character for non-breaking space, but has
ideographic space, non-breaking spaces are converted to ideographic spaces
before character set conversion.
See the changeHTML directive, in the Gateway configuration file dsgw.conf.
Query Strings
When the Gateway needs to embed a UTF-8 string in an URL, it encodes it in a
query string (the query string is the part of the URL that follows the question
mark).
This works around a problem with Japanese NT, which garbles environment
variables that are in UTF-8 (or any character set except Shift_JIS). The web
server passes information to the Gateway CGI programs in environment
variables, but the query string environment variable $QUERY_STRING is URLencoded, so it can handle UTF-8 (from NT’s point of view, it’s ASCII).
Gateway Locales
The Gateway’s default language is US English. Release 4.0 of the Directory
Server Gateway interface is also translated into the following locales:
• Japanese
•German
•French
Support for Multiple Locales
A single Gateway instance supports clients in multiple locales concurrently.
34 Netscape Directory Server Gateway Customization Guide
Setting Up Locales for Translation
Support for multiple locales is accomplished by translating documentation
(including online help), the string resource database, and the configuration and
HTML template files. A single copy of the compiled code handles all supported
locales.
Locale-dependent information is stored in translated files stored in
subdirectories identifying the locale name. These editable files are stored
separately from the Gateway code. For example, the German translation of
config/search.html is stored in config/de/search.html, the French translation is
stored in config/fr/search.html, and the Japanese translation is stored in config/
ja/search.html.
Setting Up Locales for Translation
The default gateway can be configured to support locales in addition to English
(the default locale), French, German, and Japanese. This is part of the overall
localization effort, which includes localizing all the configuration and HTML
files, including the online help and the string resource database.This is made
possible by including a pointer to the mapping table in dsgw-l10n.conf, which
is stored during Directory server installation in NS-HOME/dsgw/config/<lang>.
dsgw-l10n.conf
dsgw-l10n.conf provides translation in the Search and Advanced Search pulldown menus for the default Gateway (dsgw.conf). If dsgw-110n.conf is not
present in the /config/<lang> directory, translation of the UI does not occur and
English characters appear in the pull-down menus for Standard Search and
Advanced Search.
Example 3.1 shows how to create a new locale using Chinese as the language
for translation.
Example 3.1 Creating a locale for Chinese (zh) translation
1. Create a “zh” directory in NS-HOME/dsgw/context
2. Copy dsgw.conf to the NS-HOME/dsgw/context/zh
3. uncomment this line from the Gateway’s .conf file:
Chapter 3, Gateway Localization 35
Setting Up Locales for Translation
include “../config/dsgw-l10n.conf”
4. create a “zh” directory in NS-HOME/dsgw/config
5. Copy or create the file dsgw-l10n.conf, stored during Gateway installation
in NS-HOME/dsgw/config/<lang>, to NS_HOME/dsgw/config/zh
Note If you are using the US version of the Gateway, dsgw.conf contains a sample of
dsgw-l10n.conf.
36 Netscape Directory Server Gateway Customization Guide
Chapter
Chapter 4Files Controlling Gateway
Functionality
This chapter describes gateway components. Topics covered include:
• An Overview of Gateway File Types
4
• Gateway .conf Files
• Gateway Search Configuration Files
• Object Class Templates
• Gateway Script Files
• Gateway Search Result Templates
• Banner Files
An Overview of Gateway File Types
To the gateway user, the gateway is a set of HTML forms that can be accessed
from a web browser to communicate directly with the LDAP Directory Server
over HTTP.
To the gateway administrator, the gateway is controlled by a set of files
installed during Directory Server installation. These files can be edited to
Chapter 4, Files Controlling Gateway Functionality 37
An Overview of Gateway File Types
• create new gateway instances
• edit the object class attributes that define the entries users can add to the
Directory
• edit the search object class attributes that define how people search for and
view entries in the LDAP directory
• change the appearance of gateway forms
• update the gateway with changes to Directory Server configuration
Files that control gateway functionality are described in Table 4.1.
Table 4.1 Gateway File Types and Locations
File Types What They Do Location
Gateway .conf files Define basic configuration
parameters for the gateway
and specifies the HTML and
template directory.
Gateway search
configuration files
Gateway search
result templates
Object class
templates
Gateway script files Contain scripts used to
Banner files Define appearance of colors,
Define how the gateway
performs searches in the
Directory.
Define the filters used to
display search results to the
user.
Define object classes and
attributes for entry types.
communicate instructions to
the Directory Server over
HTTP.
background, graphics on
gateway forms.
<NSHOME>/dsgw/context
<NSHOME>/dsgw/config
<NSHOME>/dsgw/config
<NSHOME>/dsgw/config
<NSHOME>/dsgw/config
<NSHOME>/dsgw/html
38 Netscape Directory Server Gateway Customization Guide
Gateway .conf Files
A gateway’s .conf file describes the gateway’s instance. A gateway’s .conf file
controls the host, port, root suffix, and Directory Manager to use when
communicating with the Directory Server. It also controls
• the localization settings for the gateway
• the locations where new entries can be created within the directory
• the types of entries that can be created
• the search base
• whether the gateway uses SSL communications
dsgw.conf
The configuration file for the default gateway, dsgw.conf, is invoked at
http://<adminhost:adminport>/dsgw/bin/lang?context=dsgw
Gateway .conf Files
pb.conf
The configuration file for Directory Express, pb.conf, is a gateway customized
as a directory lookup tool. pb.conf is invoked at
http://<adminhost:adminport>/dsgw/bin/search?context=pb
See Also
Gateway configuration parameters are defined in Appendix A, “.conf Parameters.”
Gateway Search Configuration Files
Gateway search configuration files determine how the gateway queries
information in the Directory and returns search results to users. gateway search
configuration files are stored in the dsgw/config directory. All gateway
instances for a Directory Server use these common search configuration files.
Chapter 4, Files Controlling Gateway Functionality 39
Object Class Templates
dsgwsearchprefs.conf
The object classes and object class attributes than can be searched are specified
in dsgwsearchprefs.conf.
See Also
dsgwsearchprefs.conf is discussed in Chapter 6, “Search Attributes, Filters, and
Results.”
dsgwfilter.conf
The search filters used to search for a particular object class are specified in
dsgwfilter.conf. The gateway uses this file when performing a standard search
operation.
See Also
dsgwfilter.conf is discussed in Chapter 6, “Search Attributes, Filters, and Results.”
Object Class Templates
The gateway contains a template file for each object class defined in the
gateway. To modify how the gateway displays an entry type, edit the
corresponding template file. To add gateway support for a new object class,
create a new template file, or modify an existing one.
See Also
Modifying template files is discussed in Chapter 5, “Entry Types and Object Class
Attributes.”
Default gateway object class templates stored in the dsgw/conf directory are
listed in Table 4.2.
40 Netscape Directory Server Gateway Customization Guide
Table 4.2 Default Template Files and Related Object Classes
Template File Related Object Class
display-country.html country
display-group.html groupOfNames
display-groupun.html groupOfUniqueNames
display-ntgroup.html ntGroup
display-ntperson.html ntUser
display-org.html organization
display-orgperperson.html inetOrgPerson
display-orgunit.html organizationalUnit
display-person.html person
Gateway Script Files
Gateway Script Files
Script files are used to dynamically generate HTML forms for the user, based on
information supplied by the user and information retrieved from the Directory
Server. Script files contain directives the gateway uses to construct the HTML
for a page.
Script files can be modified to change the appearance of text that appears in
fields, buttons, and prompts on gateway forms.
Script files used to modify the information provided on gateway forms are
identified in Table 4.3.
Chapter 4, Files Controlling Gateway Functionality 41
Gateway Search Result Templates
Table 4.3 Gateway Forms and Corresponding Script Files
Set of forms Corresponding script files
authentication forms authPassword.html
authSearch.html
standard search forms searchString.html
advanced search forms csearchAttr.html
csearchBase.html
csearchMatch.html
csearchString.html
csearchType.html
newentry forms newentryType.html
newentryName.html
Gateway Search Result Templates
Search result templates control how the results of a standard or advanced
search are displayed when more than one entry is found. A separate search
result file exists for each search object defined in dsgwsearchprefs.conf.
The default search result files installed in the dsgw/config directory during
Directory Server installation are shown in Table 4.4.
Table 4.4 Default Search Result Templates
Search Result Template Related Object Class
list-Anything.html Anything
list-Auth.html Auth (internal)
list-Groups.html Groups
list-NT-Groups.html NT-Groups
list-NT-People.html NT-People
list-Org-Units.html Org-Units
list-Organizations.html Organization
list-People.html People
42 Netscape Directory Server Gateway Customization Guide
See Also
Chapter 6, “Search Attributes, Filters, and Results,” describes how search result
templates can be edited to modify the display of search results.
Banner Files
Banner files identified in Table 4.5 are used to specify the banner and button
images that appear in gateway forms.
Table 4.5 Banner Files Controlling Appearance of Gateway Forms
Banner Files Controls Appearance of Banner and Buttons in
maintitle.html main form
authtitle.html authentication form
csearchtitle.html advanced search forms
Banner Files
newentrytitle.html new entry forms
searchtitle.html standard search form
display-*.html view or edit entry forms
See Also
Chapter 7, “Customizing Graphics and Color,” describes how to alter the color
schemes and images appearing on gateway forms.
Chapter 4, Files Controlling Gateway Functionality 43
Banner Files
44 Netscape Directory Server Gateway Customization Guide
Chapter
5
Chapter 5Entry Types and Object Class
Attributes
This chapter describes how entry type formats—defined by object classes and
their attributes—are controlled by parameters in the dsgw.conf file. Topics
include:
• Entry Types (Object Classes)
• Mapping Locations and Entry Types
• Object Class Attributes in Template Files
Entry Types (Object Classes)
Parameters Controlling Entry Types
The functionality of entry types appearing on gateway forms are controlled by
parameters stored in dsgw.conf, including:
• template parameter settings that determine the types of objects that can be
created and the attributes supported for object classes.
• newtype parameter settings that determine the DN formats to be applied to
new entries.
Chapter 5, Entry Types and Object Class Attributes 45
Entry Types (Object Classes)
• location parameter settings that determine where in the directory new
See Also
Parameters in the dsgw.conf file are described in Appendix A, “.conf Parameters.”
template
The template parameter maps the gateway’s HTML templates for entry types to
the Directory Server’s LDAP object classes.
location
The location parameter defines points in the directory tree where new entries
can be added. The location parameter definitions must precede newtype
parameter definitions in the .conf file.
entries reside.
newtype
Each entry type is described by a newtype parameter. The newtype template
indicates how new entries will be formatted and where in the directory tree
entries new entries will appear. Entry types for the default gateway appear in
the pull-down menu on gateway forms (for instance, the Create New Entry
form, Figure 5.1).
46 Netscape Directory Server Gateway Customization Guide
Figure 5.1 New Entry Form
Entry Types (Object Classes)
Considerations for Adding New Entry Types
Before adding support for a new entry type (object class), decide where in the
directory tree the entry type should appear and how the entry type should be
formatted.
Deciding where the new entry appears
If a location parameter is not set up to point to the location where the new
entry type appears, add a new location parameter to the dsgw.conf file.
Chapter 5, Entry Types and Object Class Attributes 47
Mapping Locations and Entry Types
Deciding how the new entry is formatted
When the new object class has many attributes in common with an existing
entry type, update the corresponding template line in dsgw.conf to support the
new object class. When a new object class requires a new template, add a new
template parameter to dsgw.conf.
See Also
The newtype and location parameters are described in Appendix A, “.conf
Parameters”
Mapping Locations and Entry Types
The location parameter is used to define points in the directory tree where new
entries can be added. The default locations defined in dsgw.conf are intended
for the sample directory shipped with the Directory Server. They are unlikely to
match the structure of the actual directory.
Note For simple directory structures, define locations that represent branch points in
the directory. For complex structures, define branch points for only the most
commonly used directory branches.
Mapping Entry Types to Locations
Each Entry type must be mapped to a location where that type of entry can be
placed. Example 5.1 shows a mapping of locations and newtype parameters in
dsgw.conf.
Example 5.1 Mapping of Locations and Entry Types in dsgw.conf
location country "United States" "c=US#"
location org "This Organization" ""
location groups “Organizational Groups" "ou=Groups"
location acct "Accounting" "ou=Accounting"
location hr "Human Resources" "ou=Human Resources"
location pay "Payroll" "ou=Payroll"
location pd "Product Development" "ou=Product Development"
location test "Product Testing" "ou=Product Testing"
48 Netscape Directory Server Gateway Customization Guide
Mapping Locations and Entry Types
newtype orgperson "Person" cn acct hr pay pd test
newtype NTperson "NT Person" cn acct hr pay pd test
newtype groupun "Group" cn groups
newtype orgunit "Organizational Unit"ou org
newtype org "Organization" o country
In Example 5.1, locations defined in the newtype parameter (boldfaced)
correspond to handles defined in the location parameter (also boldfaced). The
friendly names (in quotes) in the third column indicate the choices that appear
in pull-down menus on gateway forms.
Note location parameter definitions in dsgw.conf must be listed before newtype
parameter definitions.
See Also
“Entry Types (Object Classes)” on page 45
Setting Up Organizational Units
Assuming that the root DN is set to o=airius.com, the mappings in Example 5.1
can be used to create people in the following organizational units:
ou=Accounting, o=airius.com
ou=Human Resources, o=airius.com
ou=Payroll, o=airius.com
ou=Product Development, o=airius.com
ou=Product Testing, o=airius.com
Configuring DN Formats for Entry Types
UID-Based DN
When a person or NT person entry is added to the directory, the gateway
prompts for a unique DN. The unique DN is typically the user ID of a person in
the organization.
Although DN formats can be based on the common names of employees in the
organization, common names are frequently not unique within an organization.
Chapter 5, Entry Types and Object Class Attributes 49
Object Class Attributes in Template Files
Note UID-based DN formats are recommended because they are by nature unique
and can prevent naming collisions within the directory.
Modifying the Default DN format
The default DN format can be modified by editing the rdnattr variable within
the newtype parameter.
To change the gateway configuration so that person entries are created using
common name-based DNs rather than user ID-based DNs, edit the following
line in the dsgw.conf file
newtype orgperson “Person” uid people special
to read
newtype orgperson “Person” cn people special
Object Class Attributes in Template Files
Default Gateway Object Classes
The default gateway supports the object classes listed in Table 5.1.
Table 5.1 Default Object Classes
Default Gateway Object Class Related Template File
groupOfNames display-group.html
groupOfUniqueNames display-groupun.html
ntGroup display-ntgroup.html
organization display-org.html
organizationalUnit display-orgunit.html
person display-person.html
inetOrgPerson display-orgperson.html
ntUser display-ntuser.html
country display-country.html
50 Netscape Directory Server Gateway Customization Guide
Object Class Attributes in Template Files
Templates and Directives
Object class attributes associated with an entry type are defined by directives
contained in gateway template files. Directives are instructions, written as
HTML comments, that are interpreted by the gateway’s CGI scripts. Each
directive is an independent, single line of HTML in a template file (with the
exception of <!-- GCONTEXT -->, which is embedded within an URL).
Entry-Related Directives
Entry-related directives are responsible for how the gateway displays, edits,
adds, and lists directory entries. The most commonly used entry-related
directive is DS_ATTRIBUTE, which determines how attributes in LDAP entries
are displayed on gateway forms.
DS_ATTRIBUTE directives begin with a DS_ENTRYBEGIN tag and close with a
DS_ENTRYEND tag.
See Also
Appendix B, “Gateway Directives Reference” lists the possible arguments for the
DS=ATTRIBUTE directive.
Adding Attributes to Object Classes
Adding an attribute to an object class requires adding an additional row to the
HTML table in the template file where the object class is defined.
The syntax in Example 5.2defines an Initials attribute for the orgperson object
class.
Example 5.2 Adding Initials attribute to orgperson object class
<TR>
<TD VALIGN= ”TOP” NOWRAP>Initials</TD>
<TD VALIGN= ”TOP” NOWRAP><B>
<!-- DS ATTRIBUTE “attr=Initials“ “syntax=cis“ “cols=>16“ -->
</B></TD>
<TD> </TD>
<TD> </TD>
Chapter 5, Entry Types and Object Class Attributes 51
Object Class Attributes in Template Files
</TR>
To complete the row, two null cells are added. This maintains the HTML table
format. For Asian character sets, substitute an ideograhpic space for the nonbreaking space ( ) shown in Example 5.2
Note Attribute values are added in pairs. When adding a single attribute to an object
class, remember to complete the table row.
Deleting Attributes from Object Classes
Deleting an attribute from an object class requires deleting a complete row or
part of a row from the HTML table where the object is defined. Example 5.3
shows the steps required to delete the mobile phone attribute from the
orgperson object class.
Example 5.3 Deleting mobile phone attribute from orgperson object class
1. Open display-orgperson.html template and delete the mobile phone
attribute-value pair (boldfaced text below)
<TR>
<TD VALIGN=”TOP” NOWRAP>Pager:</TD>
<TD VALIGN=”TOP” NOWRAP><B>
<!-- DS ATTRIBUTE “attr=pager” “syntax=tel” “cols=>16”
-->
</B></TD>
<TD VALIGN=”TOP” NOWRAP>Mobile Phone:</TD>
<TD VALIGN=”TOP” NOWRAP><B>
<!-- DS ATTRIBUTE “attr=mobile” “syntax=tel” “cols=>16”
-->
</B></TD>
</TR>
2. Insert a null pair to replace the deleted attribute (boldfaced below).
<TR>
<TD VALIGN=”TOP” NOWRAP>Pager:</TD>
<TD VALIGN=”TOP” NOWRAP><B>
<!-- DS ATTRIBUTE “attr=pager” “syntax=tel” “cols=>16”
-->
</B></TD>
52 Netscape Directory Server Gateway Customization Guide
Object Class Attributes in Template Files
<TD> </TD>
<TD> </TD>
</TR>
Note When deleting a single attribute-value pair from a row, replace the two deleted
cells with two cells containing the non-breaking space character. This maintains
the table width and ensures that the background colors are rendered correctly.
Extending Object Classes
The gateway can be extended to support additional object classes. This requires
changing information in an existing object class template so that the gateway
displays the associated entry type.
Note When extending object class definitions, the child should appear below the
parent object class in the HTML file. Otherwise, the gateway cannot correctly
interpret the HTML syntax.
Adding a Template for a Child of a Parent Class
The easiest way to create a new object class is to extend an existing object class
template, adding and deleting attributes as necessary. Example 5.4 shows the
steps required to add a template for a new object class, airiusPerson, which
adds two custom attributes—dateOfBirth and preferredOS—to the
inetOrgPerson object class.
Example 5.4 Adding template for subclass airiusPerson
1. Copy the display-orgperson.html file and rename it as display-
airiusperson.html.
2. Edit the third line in the template file to indicate the name of the new
directory entry type. Change:
<!-- inet. organizational person directory entry -->
to
<!-- airius person directory entry -->
3. Edit the DS_OBJECTCLASS directive to include the new object class.
Change:
Chapter 5, Entry Types and Object Class Attributes 53
Object Class Attributes in Template Files
<!-- DS_OBJECTCLASS "value=person,inetOrgPerson" -->
to
<!-- DS_OBJECTCLASS "value=person,inetOrgPerson,
airiusperson" -->
4. Add the value for airiusperson to the input type.
<!-- IF "Adding" -->
<INPUT TYPE="hidden" NAME="add_objectClass"
VALUE="top">
<INPUT TYPE="hidden" NAME="add_objectClass"
VALUE="person">
<INPUT TYPE="hidden" NAME="add_objectClass"
VALUE="organizationalPerson">
<INPUT TYPE="hidden" NAME="add_objectClass"
VALUE="inetOrgPerson">
<INPUT TYPE=”hidden” NAME=”add_objectClass”
VALUE=”airiusperson”>
Be sure to add the line immediately before the ENDIF directive:
<!-- ENDIF // Adding -->
5. Add a new table row containing the dateOfBirth and preferredOS attribute-
value pairs.
<TR>
<TD VALIGN="TOP">Date of Birth:</TD>
<TD VALIGN="TOP"><B>
<!-- DS_ATTRIBUTE "attr=dateOfBirth" "cols=>8" -->
</B></TD>
<TD VALIGN="TOP">Preferred OS</TD>
<TD VALIGN="TOP"><B>
<!-- DS_ATTRIBUTE "attr=preferredOS" "cols=>6" -->
</B></TD></TR>
For more information on adding attributes, see “Object Class Attributes in
Template Files” on page 50.
6. Define a template parameter in dsgw.conf for the object class airiusPerson:
54 Netscape Directory Server Gateway Customization Guide
Object Class Attributes in Template Files
template Airiusperson person inetorgperson
airiusperson
This instructs the gateway to display the Airiusperson entry type according
to the template defined for the airiusPerson object class (displayairiusperson.html).
7. Update the Directory Server schema to include the airiusPerson object class.
8. To allow users to add entries for Airiusperson using the gateway, add an
additional newtype parameter to the dsgw.conf file. If this entry type is for
display purposes only, no newtype parameter needs to be added.
See Also
See “Considerations for Adding New Entry Types” on page 47, and “Extending
Search Preferences” on page 64.
Creating a New Parent Object Class
These steps are required when the object class is not a child of an existing
object class.
1. Add a template parameter to dsgw.conf for the new object class.
template <newobjectclass>
This instructs the gateway to display the associated entry type according to
the template defined for the new object class.
2. To allow gateway users to add entries for the entry type, add an additional
newtype parameter to the dsgw.conf file. If the associated entry type is for
display purposes only, no newtype parameter needs to be added.
3. Update the Directory Server schema to include the new object class.
4. Add a search object entry to dsgwsearchprefs.conf and update
dsgwfilter.conf so that the gateway searches for entries of this type.
5. Create a new search results form defining how the gateway displays search
results for the new object class.
Chapter 5, Entry Types and Object Class Attributes 55
Object Class Attributes in Template Files
Note Netscape recommends modifying an existing search result form to create a new
search results form.
See Also
See “Adding Information to Search Results” on page 69 and “Removing
Information from Search Results” on page 70.
56 Netscape Directory Server Gateway Customization Guide
Chapter
6
Chapter 6Search Attributes, Filters, and Results
This chapter describes the files that control how the gateway searches for
objects and how to add search support for a new object. Topics include:
• Search Configuration Files
• Changing Search Scope
• Modifying Search Attributes for Advanced Searches
• Adding Search Support for a New Object
• Modifying Default Search Filters
• Customizing Search Results Templates
Search Configuration Files
The search configuration files that control the gateway’s search functionality
are dsgwsearchprefs.conf and dsgwfilter.conf. These files are stored in the
gateway’s template directory (/config for the default gateway).
Chapter 6, Search Attributes, Filters, and Results 57
Search Configuration Files
Note Define new search preferences in dsgwsearchprefs.conf whenever a new object
dsgwsearchprefs.conf
Preferences for searching object classes defined in the gateway are specified in
dsgwsearchprefs.conf. Each entry contains
• the scope of the search within the Directory Server
• the search filter to append to the search string (corresponding to the search
filter entry defined in dsgwfilter.conf)
• the label of the search attribute as it is displayed in the Find drop-down list
on the search form
• the object class attribute to search on
• match types to use in search results
class with searchable attributes is added to the gateway.
dsgwfilter.conf
dsgwfilter.conf contains an entry for each search object defined in
dsgwsearchprefs.conf. Each entry defines:
• the pattern to search for
• the delimiters for the search pattern
• the LDAP filter for generating search results
• the text to use in describing search results for the pattern
• the scope of the search (not required)
The name of the search filter entry for a search object is identified in
dsgwsearchprefs.conf.
58 Netscape Directory Server Gateway Customization Guide
Changing Search Scope
Search object entries in dsgwsearchprefs.conf define the search scope used in
searches for the corresponding object class. The default scope for gateway
search objects, subtree, specifies the baseurl and all its children.
The scope of a search object can be changed by editing the corresponding line
in dsgwsearchprefs.conf. Valid search scopes are shown in Table 6.1.
Table 6.1 Valid Search Scopes
Search Scope Tells the Gateway to
base Search the Directory Server for the entry specified in the baseurl
parameter but do not search in children of the entry.
onelevel Do not search in the entry specified in baseurl, but search in the
most immediate children of the entry.
subtree Search the entry specified in the baseurl parameter and all of it’s
children. This is the default setting.
Changing Search Scope
Modifying Search Attributes for Advanced Searches
Each search object entry in dsgwsearchprefs.conf has a list of attributes that can
be modified for advanced searches.
Standard and Advanced Searches
An advanced search differs from a standard search in that users are provided
with a pull-down menu of search types. In the default gateway, the standard
search form is used to search on object classes defined for the gateway. The
advanced search form allows users to search object class attributes and to
specify matching patterns (Figure 6.1 shows the entry types that can be
selected, Figure 6.2 shows the specific attributes that can be searched on for
person entries, and Figure 6.3 shows the matching types that can be specified).
Chapter 6, Search Attributes, Filters, and Results 59
Modifying Search Attributes for Advanced Searches
Figure 6.1 Entry Type Pull-Down Menu for Advanced Search Form
Figure 6.2 Attribute Pull-Down Menu on Advanced Search Form
60 Netscape Directory Server Gateway Customization Guide
Modifying Search Attributes for Advanced Searches
Figure 6.3 Matching Type Pull-Down on Advanced Search Form
Specifying Search Attributes for Person
The dsgwsearchprefs.conf syntax in Example 6.1 specifies that the cn, sn,
telephoneNumber, mail, uid, and title attributes are used in a search for person
entries.
Example 6.1 Search Attributes for Person Entry
People
““
“Search for”:
“(&(objectClass=person)”
“dsgw-people”
subtree
"full name" cn 111111 "" ""
"last name" sn 111111 "" ""
"phone number" "telephoneNumber" 111011 "" ""
"e-mail address" "mail" 111111 "" ""
"user id" "uid" 111111 "" ""
"title" title 111111 "" ""
END
"is" "(%a=%v))"
"is not" "(!(%a=%v)))"
"sounds like" "(%a~=%v))"
"starts with" "(%a=%v*))"
"ends with" "(%a=*%v))"
"contains" "(%a=*%v*))"
END
Chapter 6, Search Attributes, Filters, and Results 61
Modifying Search Attributes for Advanced Searches
The first column in Example 6.1 specifies how the LDAP attribute shown in the
second column appears in the pull-down menu on the Advanced Search form.
Choose one term form menu, or leave out.
The third column contains a string of six bits. Each bit position in the string
maps to a match type, as shown in Table 6.2. A value of 1 in the bit position
indicates that the match type is valid for the associated attribute. A value of 0
indicates that the match type is not valid. In Example 6.1, the bit position for
the telephone number attribute is set to 0, so the Directory Server does not
search for sounds like match types for phone number entries on the Advanced
Search form.
Table 6.2 Bit Positions and Corresponding Search Match Types
Bit position Match type Type of Search Performed
1 contains Substring search for entries having attributes
2 ends with Substing search for entries having attribgutes
with values ending wih the specified search
sting.
with values ending with the sspecified search
string.
3 starts with Substing search for entries having attributes
with values starting with the specified search
string.
4 sounds like Approximate search for phonetic matches.
5 is not Equality search for all the entries with attribute
value that does not match exactly.
6 is Equality search for all entries having value that
matches exactly.
The fourth and fifth columns in the search attributes contain empty strings
required by the gateway. These should not be altered.
62 Netscape Directory Server Gateway Customization Guide
Modifying Search Attributes for Advanced Searches
Directory Express Search Support for User ID
Directory Express looks for matches for user ID strings. It does not attempt to
match user ID substrings.
To configure substring matching for user IDs, substring index the uid attribute
and uncomment the appropriate lines in pbconfig/dsgwfilter.conf.
Adding Search Support for Additional Attributes
The boldface syntax in Example 6.2 shows the addition of preferences for
searching the pagerTelephoneNumber attribute.
Example 6.2 Extending Search Preferences to Include Pager Number
People
““
“Search for”:
“(&(objectClass=person)
“dsgw-people”
subtree
"full name" cn 111111 "" ""
"last name" sn 111111 "" ""
"phone number" "telephoneNumber" 111011 "" ""
"e-mail address" "mail" 111111 "" ""
"user id" "uid" 111111 "" ""
"title" title 111111 "" ""
“pager number” pagerTelephoneNumber 111011 "" ""
As a result of adding this syntax to dsgwsearchprefs.conf:
• A pager number selection appears in the pull-down menu on the Advanced
Search form.
• The gateway searches the pagerTelephoneNumber attribute of all entries
within the scope of the search.
• The gateway looks for values that contain, end with, start with, or are
identical to the search string entered by the user. It does not look for values
that sound like the search string entered by the user.
Chapter 6, Search Attributes, Filters, and Results 63
Adding Search Support for a New Object
Adding Search Support for a New Object
There are two ways to add search support for a new object:
• Update entries in dsgwsearchprefs.conf and dsgwfilter.conf with definitions
of search attributes for the new object. Use this method to add search
support for an object that is a child of another object.
• Create new entries in dsgwsearchprefs.conf and desgwfilter.conf for a new
object class. This method requires setting preferences for searching object
class attributes and defining a filter to use in expressing search results.
Extending Search Preferences
The boldface syntax in Example 6.3 shows the introduction of a new object,
airiusPerson, and a new attribute, dateOfBirth, to the search preferences for the
person object class.
Example 6.3 Editing dsgwsearchprefs.conf to Extend a Search Preference
People
““
“Search for”:
“(&(objectClass=person)(objectClass=airiusPerson)”
“dsgw-people”
subtree
"full name" cn 111111 "" ""
"last name" sn 111111 "" ""
"phone number" "telephoneNumber" 111011 "" ""
"e-mail address" "mail" 111111 "" ""
"user id" "uid" 111111 "" ""
"title" title 111111 "" ""
“birthdate” dateOfBirth 111011 “ “ “ “
As a result of adding the airiusPerson object class in Example 6.3:
• The gateway includes airiusPerson entries in its search for persons.
• A “birthdate” field appears on the advanced search form.
• The gateway searches the dateofBirth attribute of all entries within the
scope of the search.
64 Netscape Directory Server Gateway Customization Guide
Adding Search Support for a New Object
The syntax added to dsgwfilter.conf in Example 6.4 defines the search values
for the dateOfBirth attribute.
Example 6.4 dsgw-people entry configured to search for dateofBirth values
“[0-9][0-9]/[0-9][0-9]/[0-9]0-9]” “ “ “
(dateOfBirth=%v))” “date of birth is”
(dateOfBirth=%v*))” “date of birth starts with”
Creating a New Search Object
To add a new search object that differs from existing search objects:
• add a new entry in dsgwsearchprefs.conf
• add a new entry in dsgwfilter.conf
• add a new search results template
The syntax in Example 6.5 specifies that the search definition for OrgRole
searches the cn, l, roleOccupant, description, and telephoneNumber attributes.
Example 6.5 Creating a new dsgwsearchprefs.conf entry for OrgRole
“Org-Roles”
""
"Search For:"
"(&(objectClass=organizationalRole)
"dsgw-orgrole"
not-used-by-dsgw
not-used-by-dsgw
subtree
"name" “cn” 111111 "" ""
"location" "l" 111111 "" ""
"occupant" "roleOccupant" 111111 "" ""
"description" “description” 111011 "" ""
"phone number" "telephoneNumber" 111011 "" ""
END
"is" “(%a=%v))"
"is not" “(!(%a=%v)))"
"sounds like" “(%a~=%v))"
"starts with" “(%a=%v*))"
"ends with" “(%a=*%v))"
"contains" “(%a=*%v*))"
END
Chapter 6, Search Attributes, Filters, and Results 65
Modifying Default Search Filters
The syntax in Example 6.6 specifies a list of filters for searching attributes in the
orgRole object class.
Example 6.6 Creating a new dsgwfilter.conf entry for orgrole
dsgwfilter.conf:
dsgw-orgrole"
"=" " " "(%v))" "LDAP filter is"
"^[+]*[0-9][ 0-9-]*$" " " "(telephoneNumber=*%v))" "phone number ends
with"
"^\*$" " " "(cn=*))" "name is"
".*" ". _" "(cn=%v1-))" "name is"
"(cn=*%v1-*))" "name contains"
"(cn~=%v1-))" "name sounds like"
See Also
Modifying search results forms is described in “Modifying Search Result
Templates” on page 69
Modifying Default Search Filters
The gateway uses dsgwflter.conf to map patterns in search strings to a relevant
search filter and search result description (a search pattern is a grep-style
regular expression). dsgwwfilter.conf can be optimized to respond to common
user data patterns.
Netscape recommends modifying existing search filters in dsgwfilter.conf to
support new user data patterns, instead of creating new filters.
Search Filters for User Data Patterns
Example 6.7 shows typical search filter syntax for any search string containing
the at (@) symbol. In this example, the gateway responds to search strings
containing the @ symbol (the pattern) by searching the mail attribute for values
that are equal to or start with the supplied value (the filter). The gateway
returns a message on the search results form indicating the number of entries
where the “email address is” or “email address starts with” the user-supplied
value (the description).
66 Netscape Directory Server Gateway Customization Guide
Modifying Default Search Filters
Example 6.7 Search Filter for Email Address Searches
"@" " ""(mail=%v))" "email address is"
"(mail=%v*))" "email address starts with"
Note Standard searches use the filters associated with the first matching pattern only.
Advanced searches use all filters defined for the entry.
Specifying a Search Filter for a New Object
The syntax in Example 6.8 allows users to search person entries by birthday or
birth month.
Example 6.8 Modifying a search filter pattern
[0-9][0-9]/[0-9][0-9]/[0-9]0-9](dateOfBirth=%v))date of birth is
dateOfBirth=%v*))date of birth starts with
As a result of the adding the boldface syntax in Example 6.8 to the dsgwpeople entry in dsgwfilter.conf, the gateway also filters the dateofBirth attribute
for values that start with the supplied value (the filter). The gateway returns a
message on the search results form indicating the number of entries where the
“date of birth is” or “date of birth starts with” the user-supplied value (the
description).
Note Make sure to place new patterns near the top of the pattern definitions for a
given object. For example, in the dsgw-people entry, place customized patterns
before the pattern that begins with the @ symbol. Patterns near the end of the
entry are more general, and match many different strings.
Chapter 6, Search Attributes, Filters, and Results 67
Customizing Search Result Templates
Customizing Search Result Templates
How the Gateway Displays Search Results
When a user submits a standard search or advanced search from the gateway,
the gateway constructs a search string and filter for the corresponding search
object and queries the Directory Server. The Directory Server responds with
matching entries in the LDAP database. The gateway uses a search result
template to display the entries returned by the Directory Server.
Search Result Tables
Search results are displayed as tabular data. Headings in each result tables
reflect the object attributes identified in the search result template.
For example, the heading row on the search results form for a People search
displays the Name, Phone Number, E-Mail Address, and Title attributes.
Figure 6.4 Search Results
68 Netscape Directory Server Gateway Customization Guide
Customizing Search Result Templates
Table 6.3 lists the default gateway search objects and the information displayed
on the search results list. Search results templates are stored in the dsgw/config
directory and use the list-<search object>.html file naming convention.
Table 6.3 Default Search Results for Search Objects
Search object Search result template used Search results displayed
people list-People.html name, phone number, e-mail
address, and title
NT-people list-NT-People.html name, NT domain, NT
username, and phone number
Groups list-Groups.html group name and description
NT-Groups list-NT-Groups.html LDAP group name, NT
domain name, NT group
name, and description
Organizations list-Organizations.html organization name,
description, and phone
number
Org-Units list-Org-Units.html organizational unit name,
description, and phone
number
Anything list-Anything.html name, phone number, e-mail
address, and description
A new search result template is required for each new object class that is not a
child of another object class.
Modifying Search Result Templates
Adding Information to Search Results
The boldface text in Example 6.9 shows how additional information can be
added to the search result by modifying the corresponding search result
template.
Example 6.9 Adding OrgUnit to Search Results for People
<TR>
Chapter 6, Search Attributes, Filters, and Results 69
Customizing Search Result Templates
<TH NOWRAP>Name<TH NOWRAP>Phone Number<TH NOWRAP>E-Mail Address<TH
NOWRAP>Title<TH NOWRAP>Organizational Unit
</TR>
<TR>
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=dn" "syntax=dn" "label=" -->
onMouseOver="window.status=’Click here to view this entry in detail’;
return true">
<!-- DS_ATTRIBUTE "attr=cn" "numfields=0" "defaultvalue=name"
"options=readonly" -->
</A>
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=telephoneNumber" "syntax=tel" -->
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=mail" "syntax=mail" -->
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=title" --></TD>
<TD NOWRAP>
<!-- DS_ATTRIBUTE “attr=ou” “syntax=cis” --></TD>
</TR>
In Example 6.9, the additional HTML table heading syntax adds the
Organizational Unit label to the heading row of the table. The additional
DS_ATTRIBUTE directive syntax adds a cell to the body row of the table
indicating that the information is stored in the ou attribute of the entry and the
string is case insensitive.
Removing Information from Search Results
To remove information from a search result, remove the tag that creates the
table head cell labeling the attribute and the tag that creates the Directory
Server call for the corresponding attribute value from the corresponding list<search object>.html file.
For example, to remove the NT Domain attribute from the list-NT-People.html
search results file, delete the <TH NOWRAP>NT Domain tag from table
heading. The table cell containing the <!-- DS_ATTRIBUTE
“attr=ntuserdomainid” “syntax=ntdomain” --> directive would also need to be
removed.
70 Netscape Directory Server Gateway Customization Guide
Chapter
7
Chapter 7Customizing Graphics and Color
This chapter describes how to change the appearance of default gateway
forms. Topics include:
• Updating the Banner Image
• Updating Button Images
• Color Schemes
• Changing Table Colors
Appearance of Gateway Forms
The default gateway installed during Directory Server installation matches the
standard appearance of Netscape products. The gateway Interface Templates
can be modified to customize the appearance of:
• the banner image
• buttons
• background color
•text color
Chapter 7, Customizing Graphics and Color 71
Updating the Banner Image
• link color
Updating the Banner Image
The default gateway banner image that appears at the top of the gateway forms
is title.gif. This image can be replaced by a different banner image stored as
dsgw/html/title.gif.
Changing Dimensions of Banner Image
The default Netscape banner image has a height of 40 pixels and a width of 530
pixels. When using a banner image with a different pixel height and width,
change the specifications of the image in all files in dsgw/html where the image
is referenced:
• maintitle.html
• authtitle.html
• searchtitle.html
• csearchtitle.html
• newentrytitle.html
Changing Filename of Banner Image
Netscape recommends maintaining the default filename—title.gif—for the
banner image. Changing the default filename of the banner image requires
updating the filename in all files where the image is referenced.
Note Any image used to replace title.gif must be a true gif image. Images in other
formats (PICT, EPS, BPX, TIFF) will not appear as intended.
72 Netscape Directory Server Gateway Customization Guide
Updating Button Images
Buttons on gateway forms can be replaced by updating button image files
stored in the dsgw/html directory. Table x describes the button image files
stored in the dsgw/html directory:
Table 7.1 Button Images
Button Image Description
stsearch_off.gif used in the maintitle.html, authtitle.html,
csearchtitle.html, and newentrytitle.html
pages
stsearch_on.gif
used on the searchtitle.html page
Updating Button Images
adsearch_off.gif
used in the maintitle.html, authtitle.html,
searchtitle.html, and newentrytitle.html
pages
adsearch_on.gif
newentry_off.gif
used on the csearchtitle.html page
used in the maintitle.html, authtitle.html,
csearchtitle.html, and searchtitle.html
pages
newentry_on.gif
authen_off.gif
used on the newentrytitle.html page
used in the maintitle.html,
searchtitle.html, csearchtitle.html, and
newentrytitle.html pages
authen_on.gif
used on the authtitle.html page
The default Netscape button images have a height of 24 pixels and a width of
122 pixels. If the new button image uses a different pixel height and width,
these specifications must be changed in all files in dsgw/html where the image
is referenced:
• maintitle.html
• authtitle.html
• searchtitle.html
• csearchtitle.html
Chapter 7, Customizing Graphics and Color 73
Color Schemes
• newentrytitle.html
Changing the default filename of a button .gif file requires updating the
filename in all files where the image is referenced.
Any image used to replace a button image must be a true gif image. Images in
other formats (PICT, EPS, BPX, TIFF) will not appear as intended.
Color Schemes
Changing the color schemes for a form requires editing the files that make up a
gateway form. The procedure for changing colors depends on the gateway file
type.
Files Controlling Colors on Gateway Forms
Table 7.2 describes the gateway files that control the appearance of gateway
forms. These files may need to be updated when changing the appearance of
the banner image, button images, or background and body colors.
74 Netscape Directory Server Gateway Customization Guide
Table 7.2 Files Controlling Appearance of Gateway Forms
To Change Colors on the Edit File Type
authentication forms authtitle.html banner
authPassword.html script
authSearch.html script
standard search forms searchtitle.html banner
searchString.html script
greeting.html HTML
list-*.html search result
advanced search forms csearchtitle.html banner
csearchAttr.html script
csearchBase.html script
csearchMatch.html script
Color Schemes
csearchString.html script
csearchType.html script
emptyFrame.html HTML
list-*.html search result
new entry forms newentrytitle.html banner
newentryType.html script
newentryName.html script
display-*.html template
view or edit entry forms display-*.html template
Chapter 7, Customizing Graphics and Color 75
Color Schemes
Changing Colors Using BODY Tag
Table 7.3 lists the five standard color attributes that can be changed.
Table 7.3 Colors and Related Attributes for BODY tag
Color Using Attribute
text color TEXT
background color BGCOLOR
link color LINK
visited link color VLINK
selected link color ALINK
To adjust background colors in the banner files and other standard HTML files,
edit the HTML to change the color associated with the BGCOLOR and TEXT
attributes to a different RGB color value (for example, to change background to
aquamarine and text to white, use <BODY BGCOLOR="#70DB93"
TEXT="#9932CD">)
Changing Colors Using Directives
To change background colors in script files, add a COLORS directive
immediately before the BODY tag. The syntax in Example 7.1 shows the use of
the COLORS directive to change text color to blue, background color to aqua,
and the link color to red.
Example 7.1 Changing color settings using COLOR directives
<!-- COLORS “attribute=color [attribute=color [...]]” -->
<!-- COLORS “TEXT=#0000FF BGCOLOR=#00FFFF LINK=#FF0000” >
DS_NEWENTRY_TYPE_BODY -->
In Example 7.1, attribute is a standard HTML %color attribute and color is an
RGB color value in the form #rrggbb (or a standard color name, for example,
aquamarine).
76 Netscape Directory Server Gateway Customization Guide
Changing Table Colors
Specifying Color Names and Color Codes
There are two ways to specify colors:
• Use a color value, a six-digit hexadecimal number known as the red-greenblue (RGB) triplet. The RGB triplet always begins with a hash mark (#)
followed by 3 2-digit codes that represent the amount of red, green, and
blue that make up the color (#rrggbb). There are over 16 million RGB color
codes.
• Use a color name. There are sixteen standard case-insensitive color names.
Table 7.4 lists the sixteen standard color names and their equivalent RGB
values
Table 7.4 Sixteen Standard Colors and their Hexadecimal Values
Changing Table Colors
Color Name Hexadecimal Value
black #000000
silver #C0C0C0
gray #808080
white #FFFFFF
maroon #800000
red #FF0000
purple #80080
fuchsia #FF00FF
green #008000
lime #00FF00
olive #808000
Chapter 7, Customizing Graphics and Color 77
Changing Table Colors
Table 7.4 Sixteen Standard Colors and their Hexadecimal Values
Color Name Hexadecimal Value
yellow #FFFF00
navy #000080
blue #0000FF
teal #008080
aqua #00FFFF
Changing Color of Table Headings
To change the color of table heading text, edit the following lines within the
template file, so that the BGCOLOR value is an RGB color value in the form
#RRGGBB or a standard color name:
<TR BGCOLOR=006666 COLSPAN=4><FONT FACE=ARIAL, HELVETICA COLOR=WHITE>
The font color can be changed from white to another color using the same
method. Within a single template file there may be multiple tables and
consequently multiple table head rows that need to be modified to maintain a
consistent color scheme.
Changing the Background Color of Table Rows
To change the color of the table body rows, edit the following line for each
table within the template file so that the BGCOLOR attribute specifies the RGB
color value in the form #rrggbb or a standard color name representing the new
color:
<TABLE CELLSPACING=”2” BORDER BGCOLOR=#F2F2F2 ...
78 Netscape Directory Server Gateway Customization Guide
Appendix
A
.conf Parameters
This appendix describes, in alphabetical order, gateway configuration
parameters. Parameters are defined in dsgw.conf and pb.conf, installed during
Directory Server installation.
Associated directives are described in Appendix B, “Gateway Directives
Reference.”
authlifetime
Description Specifies the amount of time in seconds before a user’s authentication expires
in the gateway. When authenticating to the Directory from the gateway, the
gateway retains authentication credentials for the amount of time specified in
this parameter. Once authentication credentials have expired, the gateway
prompts the user to re-authenticate.
Format authlifetime <seconds>
Example The following example causes user authentication to expire in two hours. This
is the default expiration time:
authlifetime 7200
Appendix A, .conf Parameters 79
baseurl
Description Specifies the host name and port number used to contact the Directory Server.
This parameter also determines the search base used for searches performed
from the gateway, and whether the gateway uses SSL to communicate with the
Directory Server.
Format baseurl [ldap | ldaps]://<host>:<port>/<search base>
ldap | ldaps . Use ldap to have the gateway communicate the Directory Server
without using SSL. Use ldaps to have the gateway communicate with the
Directory Server using SSL.
<host>. Indicates the host name of the device where the Directory Server is
installed.
<port>. Indicates the port number used by the Directory Server. Always specify
a port number even when using standard ldap or ldaps port numbers (389 and
636, respectively).
<search base> . Indicates the distinguished name representing the point in the
directory from which all searches are performed. Normally, the search base is
set to the directory’s suffix.
Netscape recommends substituting the following hexadecimal values for the
equal sign, space, and comma in the search base:
• use %3D instead of an equal sign (=)
• use %20 instead of a space ( )
• use %2C instead of a comma (,)
Example The following example sets the base URL to use SSL communications to a
server running on the well-known LDAP security port (636). The base search
address is set to o=airius.com:
baseurl “ldaps://dirserver.airius.com:636/o%3Dairius.com”
80 Netscape Directory Server Gateway Customization Guide
binddnfile
Description Specifies the location of the file where the bind DN and bind password are
stored. This file is used to authenticate to the server for non-anonymous
searching.
The binddnfile contains two lines, the first specifying the dn with which to
bind, and the second specifying the bind password. For example:
binddn “<dn>”
bindpw <password>
This file should be stored separately of the .conf file for the gateway instance.
Format binddnfile <filename>
Example binddnfile /export/TEST/bindfile
changeHTML
Description Used by the gateway to substitute ideographic space for nonbreaking space
( ) in Asian character sets.
Format changeHTML <nbsp_from> <nbsp_to> <charset>
Example changeHTML <space character> <space character> Shift_JIS
charset
Description Defines the default character set for communication with HTTP clients. The
default is UTF-8 (Unicode), which supports all the characters in the Netscape
Directory. UTF-8 is the preferred character set, however many browsers don’t
support the UTF-8 charset, or display it poorly.
Some users may require a different character set than the one specified using
this parameter. For these users, the charset parameter setting may be
overridden by creating a <LANG>/dsgw/charset.conf file which contains the
charset name. However, to receive the correct language, users will have to
configure their browsers to send the appropriate accept-language headers.
Appendix A, .conf Parameters 81
For compatibility with HTTP clients that can’t handle an HTTP response with a
charset parameter in the content-type, comment out this parameter in the.conf
file. this prevents the gateway from sending an explicit charset to gateway
clients. When no charset parameter is defined, the gateway by default transmits
ISO-8859-1 (Latin-1).
The charset parameter is ignored by Netscape Communicator 4.0 and Internet
Explorer 4.0 and greater clients, which request the UTF-8 charset by default.
Forcing these clients to use a non-UTF-8 charset (such as Latin-1) requires the
ignoreAcceptCharsetFrom parameter, introduced in Directory Server 4.0.
Format charset <charset>
Example charset UTF-8
For more information about charsets, see RFC 1345, which defines the syntax of
charset names.
configdir
Description Specifies the location of the configuration directory of the gateway. These
include the object class templates, search configuration files, search result
templates, and script files used to dynamically generate HTML forms for the
user.
The configuration directory for the default gateway (dsgw.conf) is ../config. The
configuration directory for Directory Express (pb.conf) is ../pbconfig.
Format configdir “<configuration directory>”
Example configdir “../airiusconfig”
dirmgr
Description Specifies the distinguished name of the directory manager. This is the DN used
to bind to the Directory Server when users authenticate as the directory
manager from the gateway. Netscape recommends using a DN other than the
root DN for this purpose. It is intended that the DN specified here has read and
write authority for the subtree that the gateway sees.
Format dirmgr “<distinguished name>”
82 Netscape Directory Server Gateway Customization Guide
Loading...