Page 1
Gateway Customization Guide
Red Hat Directory Server
V ersion 7.1
April 2005
Page 2
Red Hat, Inc.
1801 Varsity Drive
Raleigh NC 27606-207 2 US A
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588
Research Triangle Pa rk N C 27709 USA
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 by Red Hat, Inc. All rights reserved. This material may be distributed only subject to
the terms and conditions set forth in the Open Publicat ion Li cense, V1.0 or later (the latest version is presently availabl e at
http://www.opencontent.org/openpub/).
Distribution of substantive ly modified versions of this docum ent is prohibited without the expli c it permission of the copyright holder.
Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited unless prior permission
is obtained from the copyright holder.
Red Hat and the Red Hat "Shadow Man" logo are registere d tra de marks of Red Hat, Inc. in the Unite d States and other countrie s.
All other tradema r ks re ferenced herein are the property of their respective owners.
The GPG fingerprint of the security@redhat.com key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
Page 3
Contents
List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Prerequisite Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Conventions Used in This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
What Is a Gateway? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Gateways Installed with Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Default Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Directory Express . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
HTTP Server Requirements for Gateways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Directory Express and Default Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Directory Express (pb.conf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Default Gateway (dsgw.conf) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Support for Multiple Gateway Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Specifying Gateway Configuration to Gateway CGIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
GET Operations (GCONTEXT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
POST Operations (PCONTEXT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
URLs for Gateway Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Anonymous and Non-Anonymous Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
binddnfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Automatic Updates to Directory Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3
Page 4
Chapter 2 Setting Up the Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Gateway Installation Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Location of Gateway Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Gateway Cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Securing Gateway Configuration and Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Protecting Bind DN and Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Protecting Root Processes on UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Updating the Gateway with Changes to Directory Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 31
HTTP Server Recommendations for Directory Server Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Running the Gateway in High-Usage Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
HTTP Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Name Translation Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Gateway Root Suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Configuring the Gateway for Web Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Creating a New Gateway Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Gateway Cloning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Gateway .conf File Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Changing the Default Port Setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Setting Up a Directory Manager for the Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Configuring the Directory Manager DN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Authenticating as Directory Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Setting Up the Suffix for Adding Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Setting Up SSL Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Configuring the Gateway to Use SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Setting vCard Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Configuring Gateway Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Language Support for HTTP Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Unicode and Latin-1 Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Displaying a Non-English Alphabet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configuring Netscape 7.x for Preferred Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Customizing Communicator’s LDAP Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 3 Gateway Localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Unicode and Support for UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
How the Gateway Selects a Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
How the Gateway Selects from Multiple Requested Characters Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
HTTP Clients that Request UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
HTTP Clients that Do Not Request UTF-8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Non-Breaking Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Query Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Gateway Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Support for Multiple Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 5
Setting Up Locales for Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
dsgw-l10n.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Chapter 4 File Controlling Gateway Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Files Controlling Gateway Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Gateway .conf Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
dsgw.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
pb.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Gateway Search Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Object Class Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Gateway Script Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Gateway Search Result Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Banner Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Chapter 5 Editing Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Entry Types (Object Classes) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Parameters Controlling Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
newtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Considerations for Adding New Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Mapping Locations and Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Mapping Entry Types to Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Setting Up Organizational Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Configuring DN Formats for Entry Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
UID-Based DN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Modifying the Default DN Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Object Class Attributes in Template Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Default Gateway Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Templates and Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Entry-Related Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Adding Attributes to Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Deleting Attributes from Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Extending Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Adding a Template for a Child of a Parent Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Creating a New Parent Object Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Chapter 6 Search Attributes, Filters, and Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Search Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
dsgwsearchprefs.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
dsgwfilter.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Changing Search Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5
Page 6
Modifying Search Attributes for Advanced Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Standard and Advanced Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Specifying Search Attributes for Person . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Directory Express Search Support for User ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Adding Search Support for Additional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Adding Search Support for a New Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Extending Search Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Creating a New Search Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Modifying Default Search Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Search Filters for User Data Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Specifying a Search Filter for a New Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Customizing Search Result Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
How the Gateway Displays Search Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Search Result Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Modifying Search Result Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Adding Information to Search Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Removing Information from Search Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Chapter 7 Customizing Graphics and Color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Appearance of Gateway Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Banner Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Updating the Banner Image (title.gif) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Changing Dimensions of Banner Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Changing Filename of Banner Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Button Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Updating Button Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Color Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Files Controlling Colors on Gateway Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Changing Colors Using BODY Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Changing Colors Using Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Changing Table Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Specifying Color Names and Color Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Changing Color of Table Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Changing the Background Color of Table Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Appendix A Parameters Defined in the .conf File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
authlifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
baseurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
binddnfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 7
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
changeHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
charset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
configdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
dirmgr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
enable-aim-presence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
gwnametrans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
htmldir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
ignoreAcceptCharsetFrom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
include . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
location-suffix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
newtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
NLS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
orgchart-attrib-farleft-rdn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
7
Page 8
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
securitypath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
url-orgchart-base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
vcard-property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Appendix B Gateway Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Structure of an HTML Template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Structure of an HTML Template for Directory List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Context-Related Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
GCONTEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
PCONTEXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Entry-Related Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
DS_ENTRYBEGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
DS_ENTRYEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
DS_ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
DS_OBJECTCLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
DS_VIEW_SWITCHER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
DS_SORTENTRIES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
DS_SEARCHDESC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
8 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 9
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
DS_POSTEDVALUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
DS_EDITBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
DS_DELETEBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
DS_SAVEBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
DS_EDITASBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
DS_NEWPASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DS_CONFIRM_NEWPASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DS_OLDPASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DS_HELPBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
DS_CLOSEBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
DS_BEGIN_ENTRYFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
DS_END_ENTRYFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
DS_EMIT_BASE_HREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
DS_DNEDITBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
DS_BEGIN_DNSEARCHFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
DS_ATTRVAL_SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
IF/ ELSE/ ELIF/ ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Arguments for IF and ELIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9
Page 10
Arguments for ELSE and ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Miscellaneous Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
BODY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
COLORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
TITLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
ENDHTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
HELPBUTTON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
INCLUDECONFIG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
DS_LAST_OP_INFO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
DS_LOCATIONPOPUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
DS_GATEWAY_VERSION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
IF/ ELSE/ ELIF/ ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Appendix C CGI Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
auth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
lang . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
csearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
unauth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
dnedit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
doauth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 11
domodify . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
newentry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
dosearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11
Page 12
12 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 13
Preface
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. The preface contains the
following sections:
• Prerequisite Reading (page 17)
• Conventions Used in This Book (page 18)
• Related Information (page 18)
Prerequisite Reading
This guide explains Red Hat Directory Server Gateway and is intended for anyone who
needs to implement a simple gateway instance with basic directory lookup fun c tionality. 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. The guide does not describe
many of the basic directory and architectural concepts that you need to deploy, install, and
administer your directory service successfully. Tho se concepts are contained in the Red Hat
Directory Server Deployment Guid e an d Red Hat Directory Server Ad ministrator’s Guide.
You should read those books before continuing with this manual.
When you are familiar with Directory Server concepts and have done some preliminary
planning for your directory service, you can install the Directory Server. The instructions
for installing the various Directory Server components are contained in the Red Hat
Directory Server Installation Guide.
Also, Managing Servers wit h Red Hat Co nsole contains general backgroun d information on
how to use the Red Hat C ons ol e. Yo u s ho uld r ead and understand the concept s in th at bo ok
before you attempt to administer Directory Server.
17
Page 14
Conventions Used in This Book
Conventions Used in This Book
This section explains the conventions used in this book.
•
Monospaced font — This typeface is used for any text that appears on the
computer screen or text that you should type. It is also used for filenames, functions,
and examples.
• Notes and Cautions text boxes.
NOTE Notes and Cautions mark important information. Make sure you read the
information before continuing with a task.
• The greater than symbol (>) is used as a s eparator fo r successiv e menu se lections. For
example, Object > New > User means that you should pull down the Object menu,
drag the mouse down to highlight New, and drag the mouse across to the New
submenu in which you must select User.
• Throughout this book you will see path references of the form:
serverRoot
serverRoot
/usr/redhat/servers. On Windows, it is c:\redhat\servers. If you have
installed Directory Server in a different location, you should adapt the path
accordingly.
serverID is the ID or identifier you assigned to an instance of Directory Server when
you installed it. For example, if you gave the server an identifier of
the actual path would look like this:
/usr/redhat/servers/slapd-phonebook/. . .
• All paths specified in this manual are in UNIX format. If you are using a
Windows-based Directory Server, you should assume the equivalent file paths
whenever UNIX file paths are shown in this book.
• In examples/sample code, paths assume that the Directory Server is installed in the
default location
in a different location, adapt the paths accordingly.
/slapd-serverID/...
is the installation directory. The default installation directory for UNIX is
/usr/redhat/servers. If you have instal led your Dir ectory Server
Related Information
phonebook, then
The document set for Directory Server also contains the following guides:
18 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 15
Related Information
• Red Hat Directory Server Deployment Guide. Provides an overvie w for planning you r
deployment of the Directory Server. Includes deployment examples.
• Red Hat Directory Server Installation Gui de. Contains procedures for installing your
Directory Server as well as procedures for migrating your Directory Server.
• Red Hat Directory Server Administrator’s Guide. Contains procedures for the
day-to-day maintenance of you r directo ry service. In cludes informati on on confi guring
server-side plug-ins.
• Red Hat Directory Server Configuration, Command, and File Reference. Contains
information about using the command-line scripts shipped with Directory Server.
• Red Hat Directory Server Schema Reference. Contains information about the Di rectory
Server schema.
• Red Hat Directory Server Plug-in Programmer’s Guide. Describes how to w rite
server plug-ins in order to customize and extend the capabilities of Directory Server.
• Red Hat Directory Server Org Chart. Introduces the Red Hat Directory Server Org
Chart application and explains how to integrate it with an instance of Directory Server.
• Red Hat Directory Server DSML Gateway Guide. Introduces the Red Hat Directory
Server DSML Gateway function and explains how to customize it for use as an
independent gatewa y.
For a list of documentation installed with Directory Server, open the
serverRoot/manual/en/slapd/index.htm file.
For the latest information about Directory Se rver, includ ing cu rren t releas e notes , co mplete
product documentation, technical notes, and deployment information, check this site:
http://www.redhat.com/docs/manuals/dir-server/
Preface 19
Page 16
Relate d Information
20 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 17
Chapter 1
Introduction
This chapter descri bes the gateway functionality of Red Hat Direc tory Server (Director y
Server). The chapter contains the following sections:
• What Is a Gateway? (page 21)
• Directory Express and Default Gateway (page 23)
• Support for Multiple Gateway Instances (page 25)
• Anonymous and Non-Anonymous Searching (page 27)
• Automatic Updates to Directory Configuration (page 27)
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. Using a gateway does not require login to the Red Hat
Console.
In Directory Server, many gateway ins tances can be def ined on on e HTTP server, p roviding
access to any number of Directory Servers. A gateway instance consists of the following:
•A
• An HTML directory for object class templates and other files containing gateway
• A configuration directory for directory search, directory authentication, language files,
.conf file, stored in the serverRoot/clients/dsgw/context directory, defining
the context for gateway instance. For example,
instance.
directives used to communicate with Directory Server.
and gateway scripts.
dsgw.conf defines the dsgw gateway
21
Page 18
What Is a Gateway?
Gateways Installed with Directory Server
Two gateway instances are installed during Directory Server installation: the default
gateway and Directory Express. Both gateways are configured to use the suffix set when
the Directory Server was configured and non-SSL (Secure Socket Layer)
communications.
NOTE A Java gateway based on the DSML protocol is also installed with
Directory Server. For more information on using and configuring the
DSML gateway, refer to the Red Hat Directory Server DSML Gateway
Guide.
For more information, see “Location of Gateway Files,” on page 29.
Default Gateway
The configuration file for the default gateway is at
serverRoot/clients/dsgw/context/dsgw.conf.
Following Directory Server installation, the default gateway can be accessed from
http://adminHost:adminPort/
or by directly using this URL:
http://adminHost:adminPort/clients/dsgw/bin/lang?context=dsgw
22 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 19
Directory Express and Default Gateway
Directory Express
The configuration file for Directory Express is
serverRoot/clients/dsgw/context/pb.conf.
During Directory Server installation, Directory Express is configured to use the Red Hat
Administration Server installed with the directory as its HTTP server.
Following Directory Server installation, Directory Express can be accessed from
http://adminHost:adminPort/
or directly using this URL:
http://adminHost:adminPort/clients/dsgw/bin/lang?context=pb
HTTP Server Requirements for Gateways
A gateway instance requires an HTTP server that can communicate with Directory Server.
For optimum performance and highest security, the gateway should be configured to run
under a high-performance HTTP server, such as the Red Hat Enterprise Server.
For more information, see “HTTP Server Configuration,” on page 32.
Directory Express and Default Gateway
The following sections describe Directory Express and the Default Gateway in detail:
• Directory Express (pb.conf)
• Default Gateway (dsgw.conf)
Directory Express (pb.conf)
Directory Express is a basic directory lookup tool that can be used out of the box.
Chapter 1 Introduction 23
Page 20
Directory Express and Default Gateway
Figure 1-1 Directory Express: Search Result
Figure 1-2 Directory Express: Extended Search Result s
24 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 21
Support for Multiple Gateway Instances
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.
Figure 1-3 Default Gateway
Support for Multiple Ga teway I nstances
Directory Server supports multiple gateway instances — that is, many gateways can access
directory data from the same HTTP server without conflict.
The
.conf files defining the configuration of gateway instances are stored in the
serverRoot/clients/dsgw/context directory. Within the .conf file are two parameters
specifying the path names for the HTML and template files for the gateway. The following
lines show the HTML and configuration directories specified in the
htmldir ../pbhtml
configdir ../pbconfig
pb.conf file:
Chapter 1 Introduction 25
Page 22
Support for Multiple Gateway Instances
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 gatewa y context f rom 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 the example that follows. 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. An example of embedding
the
GCONTEXT string in a link follows:
<a href=/clients/dsgw/bin/lang?<!-- GCONTEXT
-->&file=auth.html>click</a>
POST Operations (PCONTEXT)
In a POST operation, the CGI posts to the gateway instance specified by a hidden variable
on an HTML form. Each
PCONTEXT directive so that CGIs can pass the gateway instance to the next page and
maintain the state.
For CGI invocations using a
<!-- PCONTEXT -->
at the beginning of a line. For example, you can specify
follows:
POST operation to a gateway C GI in an HTML for m must use the
POST, put
PCONTEXT in an HTML form as
<form method=post action=/clients/dsgw/bin/dosearch>
<input type=hidden name=dn value=””>
<!-- PCONTEXT -->
</form>
For more information about content-related directives, see “Context-Related Directives,”
on page 109.
URLs for Gateway Access
To access a gateway, users enter the following URL:
26 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 23
Anonymous and Non-Anonymous Searching
http://adminHost:adminPort/clients/dsgw/bin/lang?context=<context>
The default gateway and Directory Express are available from the page for the Red Hat
Administration Serve r (
http://adminHost:adminPort).
Anonymous and Non-Anonymous Searching
The gateway supports both anonymous and non-anonymous searching. Anonymous
searching provides basic per missions for acce ssing information in the user dir ectory. A bind
DN and bind password, st ored in a
the Directory Server. User permissions for directory access can be defined in the Red Hat
Console.
If the Directory Server contains authentication credentials for a user, these ov erride the bind
DN and bind password in the gateway’s
credentials expire or are invalid, the gateway attempts to authenticate the user to the
directory using t he
binds anonymously.
binddnfile. When no binddnfile is specified, the gateway ins tance
binddnfile, can be set up for users to authenticate to
binndnfile parameter. When authentication
binddnfile
The location of the binddnfile containing bind DNs and bind passwords for individual
users and groups of users is specified in the gateway’s
NOTE The
binddnfile contains highly sensitive information. Do not store the
binddnfile under serverRoot/clients/dsgw or in any directory that is
served up over HTTP (for instance,
to store the
binddnfile).
.conf file.
/bin/slapd/server is a good place
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
serverRoot/clients/dsgw/context for gateway instances that match the Directory
Server host and port.
Chapter 1 Introduction 27
Page 24
Automatic Updates to Directory Configuration
The updatedsgw script runs automatically for gateways installed on the Red Hat
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 Red Hat Administration Server managing the Directory Server instance runs
the
updatedsgw script.
For more information, see “Updating the Gateway with Changes to Directory Server
Configuration,” on page 31.
28 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 25
Chapter 2
Setting Up the Gateway
This chapter describes the planning decisions and tasks required to install and initially
configure a gateway for access by end users. The chapter contains the following sections:
• Gateway Installation Planning (page 29)
• HTTP Server Configuration (page 32)
• Creating a New Gateway Instance (page 36)
• Gateway .conf File Configuration (page 37)
• Configuring Gateway Clients (page 40)
Gateway Installation Planning
The following sections describe the steps for planning your installation of the gateway:
• Location of Gateway Files
• Securing Gateway Configuration and Settings
• Updating the Gateway with Changes to Directory Server Configuration
• HTTP Server Recommendations for Directory Server Gateway
Location of Gateway Files
Table 2-1 shows the locations of gateway files.
29
Page 26
Gateway Installation Planning
Two gateway instances are installed during Directory Server installation: Red Hat
Directory Express (Directory Express) and the default gateway. The configuration files
(
pb.conf and dsgw.conf) for the two instances are stored in the
serverRoot/clients/dsgw/context directory. Additional gateways can be created by
customizing Directory Express or the default gateway.
Table 2-1 Location of Gateway Files
File Type File Path
Default gatew ay configurati on
file
Default gateway (dsgw)
HTML and template files
Directory Express
configuration file
Directory Express (pb) HTML
and template files
serverRoot/clients/dsgw/context/dsgw.conf
serverRoot/clients/dsgw/html
serverRoot/clients/dsgw/config
serverRoot/clients/dsgw/context/pb.conf
serverRoot/clients/dsgw/pbhtml
serverRoot/clients/dsgw/pbconfig
Gateway Cloning
Unique gateway instances may have unique HTML directories (for example,
..clients/dsgw/mythml) and template directories (for example,
..clients/dsgw/myconfig). However, gateways may also be cloned to use identical
HTML and template directories while pointing to different Directory Servers or different
suffixes on a Directory Server.
For more information on cloning the gateway, see “Gateway Cloning,” on page 37.
Securing Gateway Configuration and Settings
The following sections describe procedure for protecting the configuration information of
your gateway.
• Protecting Bind DN and Password
• Protecting Root Processes on UNIX Systems
30 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 27
Gateway Installation Planning
Protecting Bind DN and Password
The gateway configuration files reference files that contain sensitive information, including
the
binddnfile parameter containing the bind DN and bind password used to permit
non-anonymous searchi ng of the directo ry. The
the gateway configurati on direct o ry (
served up over HTTP.
serverRoot/clients/dsgw) or in any directory that is
binddnfile should not be stored under
Protecting Root Processes on UNIX Systems
On UNIX systems, it is not advisable to run the gateway from a Red Hat Administration
Server that is also running a server process as
about the configuration of your Directory Servers.
root. This may expose sensitive information
Updating the Gateway with Changes to Directory
Server Configuration
Directory Server Gateway includes a script, updatedsgw, that can be used to update all
gateway instances with changes to the Directory Server configuration, including changes to
Directory Server port, host, suffix, and root DN (the ability to update the suffix is not
available in the server administration console). The
serverRoot/bin/slapd/admin/bin directory.
updatedsgw script is stored in the
Changes made to the Directory Server configuration (
are posted to
updated only when the host and port for the gateway match the host and port of the
Directory Server.
NOTE The Directory Server’s root DN (the Directory Server’s superuser) must
updatedsgw, and the relevant gateway files are updated. These files will be
match the value of the gateway’s
dse.ldif) by the Red Ha t Console
dirmgr parameter.
HTTP Server Recommendations for Directory Server
Gateway
The Red Hat Administration Server is the default HTTP server for the two gateway clients
that are installed with the Directory Server. Both Directory Express and the default gateway
are preconfigured to run under the Administration Server without additional setup.
Chapter 2 Setting Up the Gateway 31
Page 28
HTTP Server Configuration
NOTE It is not advisable to run the gateway from an Administration Server that is
There are many factors affecting gateway performance on an HTTP server, including the
following:
• The number of users accessing the gateway at a given time.
• The complexity of the directory searches performed and the search results required.
• Whether the gateway is additionally to be used for authentication and login.
• The load from other processes managed by the host machine.
• The speed and performance of the computer hardware selected for the host computer.
• The speed and capacity of the network (network hardware and software).
In general, gateway performance on the Administration Server will begin to slow down
when the number of users accessing the gateway throughout the enterprise reaches 6,000
people. (This is a very general recommendation that does not take into account factors
listed above, especially the speed of the host machine.)
also running a server process as
information about the configuration of your Directory Servers.
root. This may expose sensitive
Running the Gateway in High-Usage Networks
Network administrators expecting high gateway usage may wish to move the gateway to a
high-performance HTTP server that is dedicated to running the gateway.
HTTP Server Configuration
The following sections describe the steps for configuring an HTTP server:
• Name Translation Mapping
• Gateway Root Suffix
• Configuring the Gateway for Web Servers
32 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 29
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). The NameTrans mapping is specified in the
gateway’s configuration file using the
gwnametrans parameter.
For more information on configuring the
page 97.
gwnametrans parameter, see “gwnametrans,” on
Gateway Root Suffix
Directory Express and the default gateway are set to the root suffix specified during
Directory Server installation. This suffix specifies the DN for the LDAP database and
represents a root in the directory tree (for example,
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
manually to propagate the change to all gateway instances.
NOTE When the root suffix, directory manager, or port change, the gateway
settings in
haven’t been updated by Red Hat Console).
dsgw.conf must be updated to reflect the changes (if they
dc=example,dc=com). Multiple
updatedsgw script
Configuring the Gateway for Web Servers
Directory Express and the default gateway are installed with the Directory Server and
configured to run under the Red Hat Administration Server, which is the default HTTP
server for the gateway clients. No additional configuration is necessary. However,
customers in high-usage networks may wish to move their gateways (or set up new
gateways) on a high-performance HTTP server.
Setting up a gateway with a web server typically requires:
1. Changing all the host names and port number s in the configurati on files ( config.txt,
dsgw.conf, pb.conf, default.conf, and so on).
Chapter 2 Setting Up the Gateway 33
Page 30
HTTP Server Configuration
2. Adding the following CGI directories (under Program Management).
Prefix:
/clients/dsgw/bin
CGI Directory: serverRoot/clients/dsgw/bin
(On Windows, add them as shell CGI directories.)
3. Adding an additional Document directory (under Content Management).
Prefix:
/clients
Directory: serverRoot/clients
Changing permissions of the cookie directory (req ui red for UNI X only ).
4.
The configuration procedures outlined in this section assume that a Red Hat Enterprise
Server is installed and configured to communicate with Directory Server. For Red Hat
Enterprise Server documentation, check this site:
http://www.redhat.com/docs/manuals/dir-server/
For configuring other HTTP servers, follow the documentation that came with the
product.
To configure the gateway to work with Red Hat Enterprise Server, follow the instructions
below:
1. Add an additional CGI directory.
Adding an additional CGI direct ory is necessary to make the gat eway’s CGI prog rams
available. For additional information, see
http://enterprise.netscape.com/docs/enterprise/611/admin/esp
rgrm.htm#21309
.
From the Class Manager for the Red Hat Enterprise Server:
a. Select Programs > CGI Directory.
b. In the URL Prefix field, enter the URL prefix to use:
/clients/dsgw/bin
c.
In the CGI Directory field, enter this (replace serverRoot with your installation
directory):
serverRoot/clients/dsgw/bin
d.
Click OK, th en Save and Apply.
34 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 31
HTTP Server Configuration
2. Add an additional document directory.
Adding an additional document directory is necessary to establish access to the
gateway files. For additional information, see
http://enterprise.netscape.com/docs/enterprise/611/admin/esco
ntnt.htm#22280
.
From the Class Manager for the Red Hat Enterprise Server:
a. Select Content Management > Additional Document Directories.
b. In the URL Prefix field, enter this:
clients/dsgw
In the Map to Directory field, enter this (replace serverRoot with your installation
c.
directory):
serverRoot
d. Click O K, then Save and Apply.
3. Change permissions of cookie directory (required for UNIX only).
/clients/dsgw/
To enable the gateway to store cookies on the HTTP server, the gateway must have
write access to the HTTP server’s cookie directory.
From the Class Manager for the Red Hat Enterprise Server:
a. Select System Settings > View Server Settings, and note the value set for the User
field.
If this value is set to
nobody, check to make sure that the server is not run ning as a
named user. For example, on Solaris, grep for the HTTP process:
ps -ef | grep http
The process listed identifies the name under which the HTTP process is running.
b. Log into the machine as root.
c. Go to the serverRoot/clients/dsgw directory and enter this:
# chown uid authck
where uid is the user name determined in step a.
d. Verify that the directory is accessible by opening this URL:
Chapter 2 Setting Up the Gateway 35
Page 32
Creating a New Gateway Instance
http://webserverHost:webserverPort/clients/dsgw/bin/search
where webserverHost is the HTTP server’s hostname and webserverPort is the port
number used by the server. When the HTTP server is using the standard HTTP
port number (80), the port number does not need to be included in the URL.
Creating a New Gateway Instance
These instructions assume that the new gateway instance will run under the Red Hat
Administration Server or a similarly capable HTTP server.
1. Rename the dsgw.conf or pb.conf file to a new gateway context.
For example,
clients/dsgw/context/example.conf.
2. Set the gwnametrans parameter in the new gateway’s .conf file to point to the
clients/dsgw/context/dsgw.conf might become
HTML directory.
For example, the
/clients/dsgw/examplehtml.
3. To support non-anonymous searching (one individual user DN and password per
directory instance) using the new gateway, set the
example.conf to point to the location of the file containing the bind DN and bind
gwnametrans parameter setting for example.conf should poi nt to
binddnfile parameter in
password that will be used to access information in the user directory.
The
binddnfile contains sensitive information; for security purposes, do not store
the
binddnfile within the /clients/dsgw directory or within any directory
served up over HTTP.
4. Create an HTML directory for the new gateway.
For example, to provide an HTML directory for
existing HTML directory (
/clients/dsgw/examplehtml.
5. Create a template directory containing object class templates and other configuration
clients/dsgw/html or clients/dsgw/pbhtml) to
example.conf, copy and rename an
files.
For example, to provide a template directory f or
existing template directory (
/clients/dsgw/pbconfig) to /clients/dsgw/exampleconfig.
6. Edit the htmldir and configdir parameters in example.conf to point to the new
HTML and template directories.
36 Red Hat Directory Server Gateway Customization Guide • April 2005
example.conf, copy and rename an
/clients/dsgw/config or
Page 33
7. To access the new gateway instance (in this example, example.conf) navigate the
browser to this URL:
http://adminHost:adminPort/clients/dsgw/bin/lang?context=example
Gateway Cloning
The HTML and template directories for one gateway can serve as the HTML and template
directory for many others. Maintaining the functionality of multiple gateways in centralized
/config and /html directories is useful when the on ly values that ar e likely to chang e are
parameter settings in the
parameter, the root DN specified by the
the
location-suffix parameter.
.conf file, such as the host and port specified by the baseurl
dirmgr parameter, and the root suffix specified by
Gateway .conf File Configuration
The following sections describe the steps for configuring the gateway .conf file:
Gateway .conf File Configuration
• Changing the Default Port Setting
• Setting Up a Directory Manager for the Gateway
• Setting Up the Suffix for Adding Entries
• Setting Up SSL Support
• Setting vCard Properties
Changing the Default Port Setting
The LDAP port is set during Directory Server installation. This value can be changed in the
baseurl parameter. The following example shows the syntax used to specify a port
number that is different than the default port number of 389. For example, the
parameter in the LDAP port is changed to the following:
baseurl “ldaps://dirserver.example.com:3000/o%3Dexample.com”
baseurl
Setting Up a Directory Manager for the Gateway
When Directory Server is installed, a default Directory Manager account (cn=Directory
Manager
requires a root DN.
) is setup with permissions to the root DN. The Directory Server installation
Chapter 2 Setting Up the Gateway 37
Page 34
Gateway .conf File Configuration
It is strongly recommended that you use a different directory manager account for the
gateway, an account other than
directory manager account (for example,
ACLs to restrict access to applicable sub suffixes and the user entries under those sub
suffixes. This enables the gateway directory manager to change those users’ passwords but
prevents the entry from having complete control of the Directory Server.
NOTE For security reasons, set the gateway Directory Manager to an entry other
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 gateway Director y Manager, making su re to set a password fo r
2. Set the permissions for the Directory Manager so that it has read and write authority
cn=Directory Manager. Once you setup the new
than
cn=Directory Manager.
the entry.
for the entries it will manage.
cn=gateway manager,cn=config), use
3. When necessary, change the dirmgr parameter to refer to the Directory Manager’s
distingui shed name ( DN).
NOTE End users frequently for get their pass words, so giv e the gateway Director y
Manager write access to the
userPassword attribute for the entries it will
manage.
The
dirmgr parameter is described in “dirmgr,” on page 95. Creating directory entries is
described in the Red Hat Directory Server Administrator’s Guide.
Authenticating as Directory Manager
Figure 2-1 shows the authentication login screen for the default gateway. Administrators
can use it to authenticate as the Directory Manager. The Authenticate as Directory
Manager button is displayed only when a Dire ctory Manag er has been co nfigured for the
gateway.
The
authlifetime parameter, which defines the number of seconds that a user may
remain authenticated, is described in “location,” on page 98.
38 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 35
Figure 2-1 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
location-suffix parameter
can point to any suffix in a directory.
Setting the
Hat Directory Server Administrator’s Guide describes the
location-suffix parameter is described in “include,” on page 98. The Red
Suffix parameter and provides
syntax examples. Setting the root suffix is also described in the Red Hat Directory Server
Installation Guide.
Setting Up SSL Support
When the Directory Server is installed, the gateway is configured to communicate with the
Directory Server usin g a non-S SL host name and p ort nu mber. Thi s infor mation is stor ed in
the
baseurl parameter.
Configuring the gateway to use SSL when communicating with the Directory Server
requires modification of the
securitypath and baseurl parameters in dsgw.conf.
Chapter 2 Setting Up the Gateway 39
Page 36
Configuring Gateway Clients
Enabling SSL communications on the Directory Server is described in the Red Hat
Directory Server Administrator’s Guide. Information about managing key and certificate
databases is provided in Managing Servers with Red Hat Console.
Configuring the Gateway to Use SSL
The securitypath parameter specifies the location of the certificate database. For
example, you can specify the path to the certificate database as follows:
The following example shows the baseurl parameter configured to use ldaps (instead
of
NOTE Before configuring SSL, verify that the gateway’s certificate database
securitypath “/usr/redhat/servers/alias/slapd-testDir-cert8.db”
ldap, the default) and standard SSL port number 636:
baseurl “ldaps://dirserver.example.com:636/o%3Dexample.com”
contains a server certificate or Certificate Authority (CA) certificate
needed to communicate with the Directory Server.
For more information about the baseurl parameter, see “baseurl,” on page 92.
Setting vCard Properties
Mappings between vCARD properties and LDAP attribute type are described in
“vcard-property,” on page 103.
Configuring Gateway Clients
The following sections describe how to configure clients of the gateway:
• Language Support for HTTP Clients
• Display ing a Non-English Alphabet
• Configuring Netscape 7.x for Preferred Language
• Customizing Communicator’s LDAP Settings
40 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 37
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.
Unicode and Latin-1 Character Sets
When the user is using Netscape Communicator, the Directory Server sends Unicode
characters.
Displaying a Non-English Alphabet
To display directory content th at uses a non-En glish 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, s o user s of Netscape Co mmun icator
should install a font that supports all of Unicode. Bitstream Cyberbit, which is bundled with
Communicator, supports Unicode.
Users who are not using Communicato r should us e a font that s upports Lati n-1 (or Wester n)
character sets. Most of the commonly used fonts (Courier, Times R oman, Helvetica) have a
Latin-1 variant.
Configuring Netscape 7.x for Preferred Language
1. Install a font that supports Unicode.
2. In the browser window, go to Edit > Preferences > Appearance > Fonts.
3. From the Fonts For pull-down menu, se l ect Unicode.
4. Set the appropriate font type, size, and display resolution.
5. Go to Edit > Preferences > Navigator > Languages/Content, and configure the list of
languages so that the best description of the user’s language is first, followed by other
acceptable languages.
For example, a speaker of British English who also reads Spanish might list
English/United Kingdom [en-GB] first, followed by English [en], and then Spanish
[es].
Chapter 2 Setting Up the Gateway 41
Page 38
Configuring Gateway Clients
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
• In the Search Directory dialog, users can enter more complex query expressions to
composition window), users can enter one string of search criteria to sear ch an LDAP
directory for matching names.
search an LDAP directory using native LDAP searches.
• Users can enter LDAP URLs (beginning with the “
(web browser) windows to search an LDAP directory.
ldap://” prefix) i n Navigator
42 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 39
Chapter 3
Gateway Localization
This chapter describes gateway localization and identifies the tasks required to set up
additional gateway locales. The chapter contains the following sections:
• Unicode and Support for UTF-8 (page 43)
• How the Gateway Selects a Character Set (page 44)
• Special Characters (page 45)
• Gateway Locales (page 46)
• Setting Up Locales for Translation (page 46)
Unicode and Support for UTF-8
Unicode is a character set containing all the characters of all the world's major languages.
There are different standard methods to encode 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.
The Directory Server and associated applications use UTF-8 in versions 2 and 3 of LDAP.
Most software included in the Directory Server uses UTF-8 internally and at interfaces
other than LDAP (for example, in command-line parameters and LDIF files).
NOTE Netscape Communicator and Netscape browsers support UTF-8.
43
Page 40
How the Gateway Selects a Character Set
How the Gateway Selects a Character Set
The gateway can output web pages in man y character sets. The gateway se lects a character
set for each HTTP client based on a combination of input from the client and from the
gateway's configuration files. The gateway selects a character set for transmission
according to this priority:
• Character set defined in the client's
overridden for a particular browser using the
parameter).
• Character set defined in the client's
for Japanese, the charset would be defined as
.
.clients/dsgw/ja/dsgwcharset.conf).
• Character set defined in the gateway's
HTTP Accept-charset header. (This can be
ignoreAcceptCharsetFrom
HTTP Accept-language header. (For example,
.conf file by the charset parameter.
How the Gateway Selects from Multiple Requested
Characters 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)
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 and Intern et Explorer. The gateway
allows this preconfiguration to be overridden using the
parameter. For more information about this parameter, see “ignoreAcceptCharsetFrom,”
on page 97.
The conversion from UTF-8 to the gateway client's chosen character set is performed
shortly before output.
44 Red Hat Directory Server Gateway Customization Guide • April 2005
ignoreAcceptCharsetFrom
Page 41
Special Characters
HTTP Clients that Do Not Request UTF-8
For browsers that do not request UTF-8 by defau lt, the gateway s elects a character set from
the
Accept-Charset request header or from the Accept-Language 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 the
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 the following:
• Shift_JIS
•Big5
•EUC-KR
dsgw.conf file, the gateway uses Latin-1 (which is the default in HTTP).
Special Characters
The following sections describe how special characters are interpreted by the gateway:
• Non-Breaking Space
• Query Strings
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 charset conversion.
See the
Query Strings
When the gateway needs to embed a UTF-8 string in a URL, it encodes it in a query string
(the query string is the part of the URL that follows the question mark).
changeHTML directive (page 93) in the gateway configuration file dsgw.conf.
Chapter 3 Gateway Localization 45
Page 42
Gateway Locales
This works around a problem wi th Japanese NT, whic h garbles envi ronment variables that
are in UTF-8 (or any charset except
the gateway CGI programs in environment variables, but the query string environment
variable
of view, it's ASCII).
$QUERY_STRING is URL-encoded, so it can handle UTF-8 (from Windows' point
Gateway Locales
The gateway's default language is US English.
Support for Multiple Locales
A single gateway instance supports clients in multiple locales co ncu rrentl y.
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.
Shift_JIS). The Web server passes information to
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/de/search.html, the French translation is stored in
config/fr/search.html, and the Japanese translation is stored in
config/ja/search.html.
config/search.html is stored in
Setting Up Locales for Translation
The default gateway can be configured to support locales in addition to English (the
default locale), French, German, Spanish, 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 the
during Directory Server installation in the
serverRoot/clients/dsgw/config/lang
dsgw-l10n.conf file, which is stored
lang directory:
46 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 43
Setting Up Locales for Translation
dsgw-l10n.conf
dsgw-l10n.conf provides translation in the Search and Advanced Search pull-down
menus for the default gateway (
/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.
The following example shows how to create a new locale using Chinese as the language for
translation:
1. Create a zh directory in the serverRoot/clients/dsgw/context directory.
2. Copy the dsgw.conf file to the serverRoot/clients/dsgw/context/zh directory.
3. Open the gateway's .conf file in a text editor, and uncomment this line from the file:
include "../config/dsgw-l10n.conf"
4. Save your changes, and close the file.
5. Create a zh directory in the serverRoot/clients/dsgw/config directory.
dsgw.conf). If dsgw-l10n.conf is not present in the
6. Copy (or create) the dsgw-l10n.conf file (stored during gateway installation in
serverRoot/clients/dsgw/config/lang) to the
serverRoot/clients/dsgw/config/zh directory.
NOTE If you are using the US version of the gateway,
sample of
dsgw-l10n.conf.
dsgw.conf contains a
Chapter 3 Gateway Localization 47
Page 44
Setting Up Locales for Translation
48 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 45
Chapter 4
File Controlling Gateway Functionality
This chapter provides examples of customized gateways. The chapter contains the
following sections:
• Files Controlling Gateway Functionality (page 49)
• Gateway .conf Files (page 51)
• Gateway Search Configuration Files (page 51)
• Object Class Templates (page 52)
• Gateway Script Files (page 53)
• Gateway Search Result Templates (page 53)
• Banner Files (page 54)
Files Controlling Gateway Functionality
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 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:
• 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.
49
Page 46
Gateway .conf Files
Files that control gateway functionality are described in Table 4-1.
Table 4-1 Gateway File Types and Locations
Files Function Location
Gateway .conf
files
Gateway search
configuration files
Object class
templates
Gateway script files Contain scripts used to
Gateway search
result templates
Define basic configuration
parameters for the gateway
and specify the HTML and
template directory. (See
“Gateway .conf Files” on
page 51.)
Define how the gateway
performs searches in the
Directory. (See “Gateway
Search Configuration Files”
on page 51.)
Define object classes and
attributes for entry types.
(See “Object Class
Templates” on page 52.)
communicate instructions to
Directory Server over
the
HTTP. (See “Gateway
Script Files” on page 53.)
Define the filters used to
display search results to the
user. (See “Gateway Search
Result Templates” on
page 53.)
serverRoot/clients/dsgw/context
serverRoot/clients/dsgw/config
serverRoot/clients/dsgw/config
serverRoot/clients/dsgw/config
serverRoot/clients/dsgw/config
Banner files Define appearance of
Gateway .conf Files
A gateway’s configu rati on fi le (.conf file) describes an instance of the gateway. Th e file
controls the host, port, root suffix, and Directory Manager when communicating with the
Directory Server. The file also controls:
50 Red Hat Directory Server Gateway Customization Guide • April 2005
serverRoot/clients/dsgw/html
colors, backg round,
graphics on gateway f or ms.
(See “Banner Files” on
page 54.)
Page 47
Gateway Search Configuration Files
• 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
dsgw.conf is the configuration file for the default gateway. dsgw.conf is invoked at:
http://adminHost:adminPort/clients/dsgw/bin/lang?context=dsgw
pb.conf
pb.conf is the configuration file for Directory Express, a gateway customized as a
directory lookup tool.
http://adminHost:adminPort/clients/dsgw/bin/search?context=pb
Gateway configuration parameters are defined in Appendix A, “Parameters Defined in the
.conf File.”
pb.conf is invoked at:
Gateway Search Configuration Files
Gateway search configuration files determine how the gateway queries information in the
directory and returns search results to the users. Gateway search configuration files are
stored in the
Directory Server use these common search configuration files.
•
dsgwsearchprefs.conf
This file specifies the object classes and object class attributes than can be searched.
dsgwfilter.conf
•
This file specifies the search filters used to search for a particular object class. The
gateway uses this file when performing a standard search operation.
The
dsgwsearchprefs.conf and dsgwfilter.conf files are discussed in Chapter 6,
“Search Attributes, Filters, and Results.”
serverRoot/clients/dsgw/config directory. All gateway instances for a
Chapter 4 File Controlling Gateway Functional ity 51
Page 48
Object Class Templates
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.
Modifying template files is discussed in Chapter 5, “Editing Entry Types.”
Default gateway object class templates stored in the
serverRoot/clients/dsgw/config
director y are listed in Table 4 -2.
Table 4-2 Default Template Files and Related Object Classes
Template File Related Object Class
display-dc.html domain
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
Script files are used to generate HTML forms dynamically 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 stored in the
serverRoot/clients/dsgw/config directory and are identified in Table 4-3.
52 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 49
Table 4-3 Gateway Forms and Correspon ding 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 newentry.html
newentryType.html
newentryName.html
Gateway Search Result Templates
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
The default search result files installed in the
during Directory Server installation are shown in Table 4-4.
Table 4-4 De fault Sea rch Result Templates
Search Result Templa t e Related Object Class
list-Anything.html Anything
list-Auth.html Auth (internal)
listDomaincomponent.html Domain
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
dsgwsearchprefs.conf.
serverRoot/clients/dsgw/config directory
list-People.html People
Chapter 4 File Controlling Gateway Functional ity 53
Page 50
Banner Files
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 File Controls Appearance of Banner and Buttons in ...
maintitle.html Main form
authtitle.html Authentication form
csearchtitle.html Advanced search forms
newentrytitle.html New entry forms
searchtitle.html Standard search form
display-*.html View or edit entry forms
Chapter 7, “Customizing Graphics and Color,” describes how to alter the color schemes
and images appearing on gateway forms.
54 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 51
Chapter 5
Editing Entry Types
This chapter describes how entry type formats — defined by object classes and their
attributes — can be controlled by editing parameters in the
contains the following sections:
• Entry Types (Object Classes) (page 55)
• Mapping Locations and Entry Types (page 57)
dsgw.conf file. The chapter
• Object Class Attributes in Template Files (page 59)
Entry Types (Object Classes)
The following sections describe entry types in detail:
• Parameters Controlling Entry Types
• Considerations for Adding New Entry Types
Parameters Controlling Entry Types
The functionality of entry types appearing on gateway forms are controlled by parameters
stored in
• Template parameter settings determine the types of objects that can be created and the
• Newtype parameter settings determine the DN formats to be applied to new entries.
• Location parameter settings determine where in the directory new entries reside.
dsgw.conf:
attributes supported for object classes.
Parameters in the
.conf File.”
dsgw.conf file are described in Appendix A, “ Parameters Defined in the
55
Page 52
Entry Types (Object Classes)
template
The template parameter is used to map the gateway’s HTML templates for entry types
to the Directory Server’s LDAP object classes.
location
The location parameter is used to define points in the directory tree where new entries
can be added. The
definitions in the
newtype
Each entry type is described by a newtype parameter. The newtype template indicates
how the entry will be formatted and the location in the directory tree where the entry will
be created. Entry types for the default gateway, such as the Create New Entry form
(Figure 5-1), appear in the pop-up menu gateway forms,.
Figure 5-1 New Entry Form
location parameter definitions must precede newtype parameter
.conf file.
56 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 53
Mapping Locations and Entry Types
Considerations for Adding New Entry Types
Before adding support for a new entry type (object class), decide:
• Where will the new entry be created?
If a
location parameter is not set up to point to the location where the new entry type
will be created, add a new
• How will the new entry be formatted?
When the new object class has many attributes in common with an existing entry type,
update the corresponding template line in
When a new object class requires a new template, add a new
dsgw.conf.
newtype and location parameters are described in Appendix A, “Parameters
The
Defined in the .conf File.”
location parameter to the dsgw.conf file.
dsgw.conf to support the new object class.
template parameter to
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
directory shipped with the Directory Server. They are unlikely to match the structure of the
actual directory.
This section explains the following:
• Mapping Entry Types to Locations
• Configuring DN Formats for Entry Types
NOTE For simple directory structures, define locations that represent branch
points in the directory. For complex structures, define branch points for
the most commonly used directory branches only.
Mapping Entry Types to Locations
Each entry type must be mapped to a location where that type of entry can be placed. The
following example shows a mapping of locations and newtype parameters in
dsgw.conf are intended for the sample
dsgw.conf:
Chapter 5 Editing Entry Types 57
Page 54
Mapping Locations and Entry Types
location
location
location
location
location
location
location
location
newtype
newtype
newtype
newtype
newtype
country
org
groups
acct
hr
pay
pd
test
orgperson
NTperson
groupun
orgunit
org
"United States"
"This Organization"
"Organizational Groups"
"Accounting"
"Human Resources"
"Payroll"
"Product Development"
"Product Testing"
"Person"
"NT Person"
"Group"
"Organizational Unit"
"Organization"
"c=US#"
""
"ou=Groups"
"ou=Accounting"
"ou=Human Resources"
"ou=Payroll"
"ou=Product Development"
"ou=Product Testing"
cn acct hr pay pd test
cn acct hr pay pd test
cn groups
ou org
o country
In the example, locations defined in the newtype parameter (such as country, org, or
groups) correspond to handles defined in the location parameter. The friendly names
(in quotes) in the third column indicate the choices that will appear in pull-down menus on
gateway for ms.
NOTE Location parameter definitions in dsgw.conf must be listed before
newtype parameter definitions.
See “Entry Types (Object Classes),” on page 55, for more information.
Setting Up Organizational Units
Assuming that the root DN is set to o=example.com, the mappings in the following
example can be used to create people in the following organizational units:
ou=Accounting, o=example.com
ou=Human Resources, o=example.com
ou=Payroll, o=example.com
ou=Product Development, o=example.com
ou=Product Testing, o=example.com
Configuring DN Formats for Entry Types
The following sections describe how to configure entry type DNs depending upon the
format.
58 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 55
Object Class Attributes in Template Files
UID-Based DN
When a person or Windo ws p e rso n en try i s add ed t o the directory, the gatewa y p romp t s f or
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 frequen tly not unique within a n organization.
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
file:
dsgw.conf
newtype orgperson “Person” uid people special
to read as follows:
newtype orgperson “Person” cn people special
Object Class Attributes in Template Files
The following sections describe the object classes and attributes contained by the template
files:
• Default Gateway Object Classes
• Templates and Directives
• Adding Attributes to Object Classes
• Deleting Attributes from Object Classes
• Extending Object Classes
• Creating a New Parent Object Class
Chapter 5 Editing Entry Types 59
Page 56
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
domain component display-dc.html
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
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
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
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.
Appendix B, “Gateway Directives,” lists the possible arguments for the
directive.
<!-- GCONTEXT -->, which is
DS_ATTRIBUTE,
DS_ATTRIBUTE
60 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 57
Object Class Attributes in Template Files
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 the following example defines an
Initials attribute for the orgperson
object class:
<TR>
<TD VALIGN=
<TD VALIGN= “TOP” NOWRAP><B>
<!-- DS ATTRIBUTE
</B></TD>
<TD> </TD>
<TD> </TD>
</TR>
“TOP” NOWRAP>Initials</TD>
“attr=Initials” “syntax=cis” “cols=>16” -->
To complete the row, two null cells are added. This maintains the HTML table format. For
Asian character sets, substitute an ideographic space for the non-breaking space ( )
shown in the example.
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. The following example shows the steps
required to delete the mobile phone attribute from the
1. Open display-orgperson.html template, and delete the mobile phone
orgperson object class:
attribute-value pair.
<TR>
<TD VALIGN=
<TD VALIGN=
<!-- DS ATTRIBUTE
</B></TD>
<TD VALIGN=
<TD VALIGN=
<!-- DS ATTRIBUTE
</B></TD>
</TR>
“TOP” NOWRAP>Pager:</TD>
“TOP” NOWRAP><B>
“attr=pager” “syntax=tel” “cols=>16” -->
“TOP” NOWRAP>Mobile Phone:</TD>
“TOP” NOWRAP><B>
“attr=mobile” “syntax=tel” “cols=>16” -->
Chapter 5 Editing Entry Types 61
Page 58
Object Class Attributes in Template Files
2. Insert a null pair to replace the deleted attribute.
<TR>
<TD VALIGN=
<TD VALIGN=
<!-- DS ATTRIBUTE
</B></TD>
<TD> </TD>
<TD> </TD>
</TR>
NOTE When deleting a single attribute-value pair from a row, replace the two
Extending Object Classes
“TOP” NOWRAP>Pager:</TD>
“TOP” NOWRAP><B>
“attr=pager” “syntax=tel” “cols=>16” -->
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.
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, th e child should app ear below the
parent object class in the HTML file. Otherwise, the gateway cannot
correc t l y interpr e t the HTML syn ta x.
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. The following example shows the steps
required to add a template for a new object class,
adds two custom attributes,
dateOfBirth and preferredOS, to the inetOrgPerson
object class.
1. Copy the display-orgperson.html file, and rename it as
display-exampleperson.html.
examplePerson. The new template
62 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 59
Object Class Attributes in Template Files
2. Edit the third line in the template file to indicate the name of the new directory entry
type. Chan ge:
<!-- inet. organizational person directory entry -->
to
<!-- example person directory entry -->
3. Edit the DS_OBJECTCLASS directive to include the new object class. Change:
<!-- DS_OBJECTCLASS "value=person,inetOrgPerson" -->
to
<!-- DS_OBJECTCLASS "value=person,inetOrgPerson,
exampleperson" -->
Add the value for exampleperson to the input type.
4.
<!-- 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="exampleperson">
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 59.
Chapter 5 Editing Entry Types 63
Page 60
Object Class Attributes in Template Files
6. Define a template parameter in dsgw.conf for the object class examplePerson:
template exampleperson person inetorgperson exampleperson
This will instruct the gateway to display the exampleperson entry type according to
the template defined for the
(
display-exampleperson.html).
7. Update the Directory Server schema to include the examplePerson object class.
8. To allow users to add entries for exampleperson using the gateway, add an
additional
purposes only, no
See “Considerations for Adding New Entry Types,” on page 57, and “Extending Search
Preferences,” on page 74.
Creating a New Parent Object Class
These steps are required when the object class is not a child of an existing object class.
examplePerson object class
newtype parameter to the dsgw.conf file. If this entry type is for display
newtype parameter ne eds to be added.
1. Add a template parameter to dsgw.conf for the new object class.
template newobjectclass
This will instruct 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
only, no
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 will search for entries of this type.
5. Create a new search results form defining how the gateway will display search results
newtype parameter needs to be added.
dsgw.conf file. If the associated entry type is for display purposes
for the new object class.
NOTE Modify an existing search result form to create a new search results form.
See “Adding Information to Search Results,” on page 80, and “Removing
Information from Search Results,” on page 81.
64 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 61
Chapter 6
Search Attributes, Filters, and Results
This chapter describes the files that control how the gateway searches for objects and
describes how to add search support for a new object. The chapter contains the following
sections:
• Search Configuration Files (page 67)
• Changing Search Scope (page 68)
• Modifying Search Attributes for Advanced Searches (page 69)
• Adding Search Support for a New Object (page 74)
• Modifying Default Search Filters (page 76)
• Customizing Search Result Templates (page 78)
Search Configuration Files
The dsgwsearchprefs.conf and dsgwfilter.conf files are the search configuration
files that control the gateway’s search functionality. These files are stored in the gateway’s
template directory (
dsgwsearchprefs.conf
The dsgwsearchprefs.conf file specifies the preferences for searching object classes
defined i n the gateway. Each entry contains :
• The scope of the search within the Directory Server.
/config for the default gateway).
• The search filter to append to the search string (corresponding to the search filter entry
defined in
dsgwfilter.conf).
67
Page 62
Changing Search Scope
• 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.
NOTE Define new search preferences in
dsgwsearchprefs.conf whenever a
new object class with searchable attributes is added to the gateway.
dsgwfilter.conf
The dsgwfilter.conf file contains an entry for each search object defined in
dsgwsearchprefs.conf. Each entry defines the following:
• Pattern for which to search.
• Delimiters for the search pattern.
• LDAP filter for generating search results.
• Text to use in describing search results for the pattern.
• Scope of the search (not required).
The name of the search filter entry for a search object is identified in
dsgwsearchprefs.conf.
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
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
68 Red Hat Directory Server Gateway Customization Guide • April 2005
baseurl and all its children.
parameter but not to search in children of the entry.
Page 63
Modifying Search Attributes for Advanced Searches
Table 6-1 Valid Search Scopes (Continued)
Search Scope Tells the Gateway to...
onelevel Not to search in the entry specified in the baseurl parameter but
search in the most immediate children of the entry.
subtree Search the entry specified in the baseurl parameter and all of its
children. This is the default setting.
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. This section explains the following:
• Standard and Advanced Searches
• Specifying Search Attributes for Person
• Directory Express Search Support for User ID
• Adding Search Support for Additional Attributes
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 defau lt gateway, the Stand ard Sear ch f orm searches
on object classes defined for the gateway. The Advanced Search form allows users to also
search in specific object class attributes and to specify a matching pattern. Figure 6-1 shows
the Advanced Search form with search results.
Chapter 6 Search Attributes, Filters, and Res ults 69
Page 64
Modifying Search Attributes for Advanced Searches
Figure 6-1 Advanced Search Form: Search Results
The figures that follow show the matching patterns that can be selected in the Advanced
Search form.
Figure 6-2 shows the entry type pop-up menu on the Advanced Search form.
70 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 65
Modifying Search Attributes for Advanced Searches
Figure 6-2 Advanced Search Form: Entry Ty pe
Figure 6-3 shows the attribute pop-up menu on the Advanced Search form.
Figure 6-3 Advanced Search Form: Attribute
Figure 6-4 shows the matching filter pop-up menu on the Advanced Search form.
Chapter 6 Search Attributes, Filters, and Res ults 71
Page 66
Modifying Search Attributes for Advanced Searches
Figure 6-4 Advanced Search Form: Matching Filter
Specifying Search Attributes for Person
The dsgwsearchprefs.conf syntax in the following example specifies that the cn, sn,
telephoneNumber, mail, uid, and title attributes will be used in a search for person
entries:
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
The first column in the example specifies how the LDAP attribute shown in the second
column appears in the drop-down menu on the Advanced Search form.
72 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 67
Modifying Search Attributes for Advanced Searches
The third column contains a string of six bits . Each bit posi tion in th e string maps t o a match
type, as shown in Table 6-2. A value of 1 indicates that the match type is valid for the
associated attribute. A value of 0 indicates that the match type is not valid. In the example,
the bit position for the telephone number attribute is set to 0, indicating that the Directory
Server will 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
1 contains
2 ends with
3 starts with
4 sounds like
5 is not
6 is
The fourth and fifth columns in the search attributes contain empty strings required by the
gateway. These shou ld not be altered.
Directory Express Search Support for User ID
Directory Express does exact matches for user ID strings. It does not attempt to match user
ID substrings.
To configure substrin g matching for user IDs, su bstring inde x the
the appropriate lines in
pbconfig/dsgwfilter.conf, and comment out the
uid attribute, uncomment
corresponding lines.
Adding Search Support for Additional Attributes
The syntax in the following example specifies preferences for searching the
pagerTelephoneNumber attribute.
People
""
"Search for":
"(&(objectClass=person)
Chapter 6 Search Attributes, Filters, and Res ults 73
Page 68
Adding Search Support for a New Object
"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 will appear in the drop-down menu on the Advanced
Search form.
• The gateway will search the
pagerTelephoneNumber attribute of all entries within
the scope of the search.
• The gateway will look for values that contain, end with, start with, or are identical to
the search string entered by the user. It will not look for values that sound like the
search string entered by the user.
Adding Search Support for a New Object
There are two ways to add search support for a new object:
• Update entries in
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
object class. This method requires specifying preferences for searching object class
attributes and defining a filter to use in expressing search results.
Extending Search Preferences
dsgwsearchprefs.conf and dsgwfilter.conf with
dsgwsearchprefs.conf and dsgwfilter.conf for a new
The syntax in the following example shows the introduction of a new object,
examplePerson, and a new attribute, dateOfBirth, to the search preferences for the
person object class.
74 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 69
Adding Search Support for a New Object
People
""
"Search for":
"(&(objectClass=person)(objectClass=examplePerson)"
"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 syntax shown in the example:
• The gateway will include
•A
birthdate field will appear on the Advanced Search form.
• The gateway will search the
examplePerson entries in its search for persons.
dateofBirth attribute of all entries within the scope of
the search.
The syntax added to
values for the
"[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"
dsgwfilter.conf in the following example defines the search
dateOfBirth attribute:
Creating a New Search Object
Adding a new search object that is not similar to existing search objects requires:
• A new entry in
• A new entry in the dsgwfilter.conf.
• A new search results template.
dsgwsearchprefs.conf.
The syntax in the following example specifies that the search definition for
search the
"Org-Roles"
""
"Search For:"
"(&(objectClass=organizationalRole)
"dsgw-orgrole"
OrgRole will
cn, l, roleOccupant, description, and telephoneNumber attributes:
Chapter 6 Search Attributes, Filters, and Res ults 75
Page 70
Modifying Default Search Filters
The syntax in the above example specifies a list of filters for searching attributes in the
OrgRole object class.
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
This example creates a new
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"
dsgwfilter.conf entry for OrgRole:
Modifying search results forms is described in “Modifying Search Result Templates,” on
page 80.
Modifying Default Search Filters
The gateway uses dsgwflter.conf to map patter ns in search strings to a relevan t 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.
Modify existing search filters in
instead of creating new filters.
The sections that follow explain:
76 Red Hat Directory Server Gateway Customization Guide • April 2005
dsgwfilter.conf to support new user data patterns
Page 71
Modifying Default Search Filters
• Search Filters for User Data Patterns
• Specifying a Search Filter for a New Object
Search Filters for User Data Patterns
This example shows typical search filter syntax for any search string containing the @
symbol. In this example, the gateway will respond to search strings containing the @
symbol (the pattern) by searching the
the supplied value (the filter). The gateway will then return a message on the search results
form indicating the number of entries where the
address starts with"
"@" " ""(mail=%v))" "email address is"
"(mail=%v*))" "email address starts with"
the user-supplied value (the description).
NOTE Standard searches use only the filters associated with the first matching
pattern. Advanced searches use all filters defined for the entry.
mail attribute for values that are equal to or start with
"email address is" or "email
Specifying a Search Filter for a New Object
The syntax in the following example allows users to search person entries by birthday or
birth month:
[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 adding the line dateOfBirth=%v*))date of birth starts with to the
dsgw-people entry in dsgwfilter.conf, the gateway will also filter the dateofBirth
attribute for values that start with the supplied value (the filter). The gateway will return a
message on the search results form indicating the number of entries where the
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 will match many different
strings.
"date of
Chapter 6 Search Attributes, Filters, and Res ults 77
Page 72
Customizing Search Result Templates
Customizing Search Result Templates
The following sections describe how the gateway displays search results and contains
procedures for customizing the gateway search result templates:
• How the Gateway Displays Search Results
• Modifying Search Result Templates
How the Gateway Displays Search Results
When a user submits a standard search or advan ced s earch f rom 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 table reflects 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, User ID, Phone Number, E-Mail Address, and Group attributes.
78 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 73
Figure 6-5 Search Results
Customizing Search Result Template s
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
serverRoot/clients/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 Te mp late Used Search Result s Di s p la yed
Domain
Component
people list-People.html Name, phone numbe r, e-mail address,
NT-people list-NT-People.html Name, Windows domain, Windows
Groups list-Groups.html Group name and descrip tion.
NT-Groups list-NT-Groups.html LDAP gro up name, Windows domain
Organizations list-Organizations.html Organization name, desc r ip tion , an d
list-Domaincomponent.htmlOrganization na m e, description, an d
phone number.
and title.
username, and phone number.
name, Windows group name, and
description.
phone number.
Chapter 6 Search Attributes, Filters, and Res ults 79
Page 74
Customizing Search Result Templates
Table 6-3 Default Search Results for Search Objects (Continued)
Search Object Search Result Te mp late Used Search Result s Di s p la yed
Org-Units list-Org-Units.html Organizational unit name, description,
Anything list-Anything.html Name, phone numbe r, e-mail address,
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
This section covers:
• Adding Information to Search Results
and phone number.
and description.
• Removing Information from Search Results
Adding Information to Search Results
This example shows how additional information can be added to the search result by
modifying the corresponding search result template.
<TR>
<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>
80 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 75
Customizing Search Result Template s
<!-- DS_ATTRIBUTE "attr=title" --></TD>
<TD NOWRAP>
<!-- DS_ATTRIBUTE "attr=ou" "syntax=cis" --></TD>
</TR>
The additional HTML table heading syntax adds the Organizational Unit label to the
heading row of the table. The additional
body row of the table indicating that the information is stored in the
DS_ATTRIBUTE directive syntax adds a cell to 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
which labels 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 Windows Domain attribute from the
search results file, delete the
cell containing the
"syntax=ntdomain" -->
<!-- DS_ATTRIBUTE "attr=ntuserdomainid"
<TH NOWRAP>NT Domain tag from table heading. The table
directive would also need to be removed.
list-NT-People.html
Chapter 6 Search Attributes, Filters, and Res ults 81
Page 76
Customizing Search Result Templates
82 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 77
Chapter 7
Customizing Graphics and Color
This chapter describes how to change the appearance of default gateway forms. The chapter
contains the following sections:
• Appearance of Gateway Forms (page 83)
• Banner Image (page 83)
• Button Images (page 84)
• Color Schemes (page 86)
• Changing Table Colors (page 88)
Appearance of Gateway Forms
The default gateway installed during Directory Server installation matches the standard
appearance of Directory Server. The gateway Interface Templates can be modified to
customize the appearance of the following:
• Banner Image
• Button Images
• Color Schemes
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
clients/dsgw/html/title.gif.
83
Page 78
Button Images
Updating the Banner Ima ge (title.gif)
The following sections descri be how to change th e dimensions o f the banner im age as well
as how to change the banner image filename.
Changing Dimensions of Banner Image
The default banner image has a height of 40 pixels and a width of 530 pix els. When using
a banner image with a different pixel height and width, change the specifications of the
image in all files in
•
maintitle.html
•
authtitle.html
•
searchtitle.html
•
csearchtitle.html
•
newentrytitle.html
clients/dsgw/html where the image is referenced:
Changing Filename of Banner Image
Keep 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
Button Images
Buttons on gateway forms can be replaced by updating button image files stored in the
clients/dsgw/html directory. Table 7-1 describes the button image files stored in the
clients/dsgw/html directory.
Table 7-1 Bu tton Images
Button Image Description
stsearch_off.gif Used in the maintitle.html,
title.gif must be a true .gif image.
Images in other formats (PICT, EPS, BPX, TIFF) will not appear as
intended.
authtitle.html, csearchtitle.html, and
newentrytitle.html pages.
84 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 79
Table 7-1 Button Images (Continued)
Button Image Description
stsearch_on.gif Used on the searchtitle.html page.
adsearch_off.gif Used in the maintitle.html,
authtitle.html, searchtitle.html, and
newentrytitle.html pages.
adsearch_on.gif Used on the csearchtitle.html page.
newentry_off.gif Used in the maintitle.html,
authtitle.html, csearchtitle.html, and
searchtitle.html pages.
newentry_on.gif Used on the newentrytitle.html page.
authen_off.gif Used in the maintitle.html,
searchtitle.html, csearchtitle.html,
and newentrytitle.html pages.
authen_on.gif Used on the authtitle.html page.
Button Images
Updating Button Images
The default 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 the
•
maintitle.html
•
authtitle.html
•
searchtitle.html
•
csearchtitle.html
•
newentrytitle.html
Changing the default filename of a button
files where the image is referenced.
NOTE Any image used to replace button image must be a true .gif image.
clients/dsgw/html directory where the image is referenced:
.gif file requires updating the filename in all
Images in other formats (PICT, EPS, BPX, TIFF) will not appear as
intended.
Chapter 7 Customizing Graphics and Color 85
Page 80
Color Schemes
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
• Changing Colors Using BODY Tag
• Changing Colors Using Directives
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.
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
csearchString.html script
csearchType.html script
emptyFrame.html HTML
list-*.html search result
86 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 81
Table 7-2 Files Controlling Appearance of Gateway Forms (Continued)
To Change Colors on the ... Edit File Type
New entry forms newentrytitle.html banner
newentryType.html script
newentryName.html script
display-*.html template
View or edit entry forms display-*.html template
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
Color Schemes
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 ba ckground to aqu amarine and text to white, u se
<BODY BGCOLOR="#70DB93" TEXT="#9932CD">).
Changing Colors Using Directives
To change background colors in scri pt files, add a COLORS directive immediately before the
BODY tag. The syntax in the following example shows the use of the COLORS directive to
change text color to blue, background color to aqua, and the link color to red:
<!-- COLORS "attribute=color [attribute=color [...]]" -->
<!-- COLORS "TEXT=#0000FF BGCOLOR=#00FFFF LINK=#FF0000" >
DS_NEWENTRY_TYPE_BODY -->
Chapter 7 Customizing Graphics and Color 87
Page 82
Changing Table Colors
In the example, the attribute is a standard HTML %color attribute, and color is an RGB
color value in the form
#rrggbb (or a standard color name, such as aquamarine).
Changing Table Colors
The following sections describe procedures for customizing the color of tables:
• Specifying Color N ames and Color Codes
• Changi ng Color of T able Headings
• Changing the Background Color of Table Rows
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-green-blue
(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 He xadecimal Values
Color Name Hexadecimal Value
black #000000
silver #C0C0C0
gray #808080
white #FFFFFF
maroon #800000
red #FF0000
purple #80080
fuchsia #FF00FF
green #008000
lime #00FF00
88 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 83
Changing Table Colors
Table 7-4 Sixteen Standard Colors and Their Hexadecim al Values (Continued)
Color Name Hexadecimal Value
olive #808000
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:
<TR BGCOLOR=006666 COLSPAN=4><FONT FACE=ARIAL, HELVETICA
COLOR=WHITE>
so that the BGCOLOR value is an RGB color value in the form #RRGGBB or a standard color
name. 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:
<TABLE CELLSPACING="2" BORDER BGCOLOR=#F2F2F2 ...
so that the BGCOLOR attribute specifies the RGB color value in the form #RRGGBB or a
standard color name representing the new color.
Chapter 7 Customizing Graphics and Color 89
Page 84
Changing Table Colors
90 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 85
Appendix A
Parameters Defined in the .conf File
The dsgw.conf and pb.conf files are installed during Red Hat Directory Server
(Directory Server) installation. This appendix describes the configuration parameters
defined in these files. Associated directives are described in Appendix B, “Gateway
Directives.”
authlifetime
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.
For information on authenticating to the Directory Server using the gateway, see the online
documentation that is available through the gateway.
Format
authlifetime seconds
Example
The following example causes user authentication to expir e in two hou rs. This is the default
expiration time:
authlifetime 7200
91
Page 86
baseurl
baseurl
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]://dirHost:dirPort/searchBase
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.
dirHost. Indicates the host name of the machine where the Directory Server is installed.
dirPort. 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).
searchBase. Indicates the dis tingu ished na me (DN) represen ting the point in th e directory
from which all searches are performed. Normally,
suffix.
searchBase is set to the directory’s
Substitute the following hexadecimal values for the equal sign, space, and comma in the
search base:
• use %3D instead of equal sign (=)
• use %20 instead of space ( )
• use %2C instead of comma (,)
Example
The following example sets the base URL to use SSL communications to a server run ning
on the wel l -known LDAP security port (
o=example.com.
baseurl "ldaps://dirserver.example.com:636/o%3Dexample.com"
binddnfile
Specifies the location of the file where the bind DN and bind password are stored. This
file should be stored separately of the
binddnfile is used to authenticate to the server for non-anonymous searching.
636). The base search address is set to
.conf file for the gateway instance. The
92 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 87
Format
binddnfile binddn_filename
Example
binddnfile /export/TEST/binddnfile
changeHTML
Used by the gateway to substitute ideographic space for non-breaking space (nbsp) in Asian
character sets.
Format
changeHTML nbsp_from nbsp_to charset
Example
changeHTML <space character> <space charac ter> Shift_JIS
changeHTML
charset
Defines the default character set for communication with HTTP clients. The default is
UTF-8 (Unicode), which supports all the characters in the Directory Server. UTF-8 is the
preferred character set ; however, many browser s don’t su pport the UTF-8 ch arset or display
it poorly.
Some users may require a different character set than the one specified in using this
parameter. For these users, the
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.
For compatibility with HTTP clients that can’t handle an HTTP response with a
parameter in the content-type, comment out this parameter in the
the gateway from sending an explicit charset to gateway clients. When no
parameter is defined, the gateway by default transmits ISO-8859-1 (Latin-1).
The
charset parameter is ignored by current versions of Netscape Communicator and
Internet Explorer, which request the UTF-8 charset by default. Forcing these clien ts to use a
non-UTF-8 charset (su ch as Latin-1) r equires the
charset parameter setting may b e ov erridd en by creating a
charset
.conf file. This prevents
charset
ignoreAcceptCharsetFrom parameter.
Appendix A Parameters Defined in the .conf File 93
Page 88
configdir
configdir
More information: “ignoreAcceptCharsetFrom,” on page 97
Format
charset character_set
Example
charset UTF-8
For more information about charsets, see RFC 1345, which defines the syntax of charset
names.
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 generate HTML forms dynamically for the use r.
dirmgr
The configuration directory for the default gateway (
configuration directory for Directory Express (
dsgw.conf) is ../config. The
pb.conf) is ../pbconfig.
Format
configdir "configuration_directory"
Example
configdir "../exampleconfig"
Specifies the distinguished name of the Directory Manager. This is the DN used to bind to
the Directory Server when users authenticate as the Dir ectory Manager fro m the gateway.
Use 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.
For information on authenticating as the Directory Manager from the gateway, see the
online documentation that is available through the gateway.
Format
dirmgr "distinguished_name"
94 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 89
Example
dirmgr "cn=Directory Manager, o=example.com"
For information on the root DN and on setting permissions for the directory, see the Red
Hat Directory Server Administrator’s Guide.
enable-aim-presence
Specifies the AIM® presence (online or offline) of a user by displaying or hiding the AIM
icon in the Directory Server Gateway UI. If
the user being displayed is logged into the AIM service, the AIM icon show ups in the UI
when the full entry for a user is being displayed.
By default, the AIM icon won’t show up for lists of users because it would have adverse
affects on search performance. To see AIM presence for lists of users (or multiple search
results), the following files will need to be modified:
•
config/list-People.html
enable-aim-presence
enable-aim-presence is set to true and if
•
config/list-NT-People.html
•
pbconfig/list-People.html
The block of text that needs to be modified is shown below:
<SCRIPT LANGUAGE="JavaScript">
<!-- Hide from non-JavaScript-capable browsers
showAimIcon(
<!-- DS_ATTRIBUTE "attr=nsaimid" "options=quoted" -->
,
"" //<!-- DS_ATTRIBUTE "attr=nsaimstatustext" "options=quoted"
-->
);
//// Uncomment the above DS_ATTRIBUTE directive and remove the
////
//// double quotes to have aim presence in search results lists
////
The modified block of text is shown below (the "" and // removed from the sixth line):
<SCRIPT LANGUAGE="JavaScript">
<!-- Hide from non-JavaScript-capable browsers
showAimIcon(
<!-- DS_ATTRIBUTE "attr=nsaimid" "options=quoted" -->
Appendix A Parameters Defined in the .conf File 95
Page 90
gwnametrans
,
<!-- DS_ATTRIBUTE "attr=nsaimstatustext" "options=quoted" -->
);
//// Uncomment the above DS_ATTRIBUTE directive and remove the
////
//// double quotes to have aim presence in search r esults lists
////
Once this is done, listings of multiple users will show AIM presence for each user.
NOTE By default, nsaimid and nsaimstatustext are used for AIM ID and
AIM presence information, respectively. If you use different attributes, be
sure to change the HTML files.
Format
enable-aim-presence true | false
Example
enable-aim-presence true
gwnametrans
Used by the gateway CGI scripts to specify the URL to output for HTTP redirection. This
needs to be specified as
NameTrans set in the HTTP server, if any is being used.
Format
gwenametrans "HTTP_redirect"
Example
gwnametrans "/clients/dsgw/pbhtml/"
"/clients/dsgw/htmldir" and should be the same as the
96 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 91
htmldir
htmldir
Specifies the location of the HTML files for the gateway. These include the HTML files
controlling the appearance of gateway forms.
The HTML directory for the default gateway (
director y for Directory Express (
pb.conf) is ../pbhtml.
Format
htmldir "html_directory"
Example
htmldir "/exampleconfig"
ignoreAcceptCharsetFrom
Ignores request headers for the UTF-8 character set automatically sent by Netscape
Communicator and Internet Explorer browsers. Can be used together with the
parameter to transmit a charset other than Unicode to all gateway clients.
Format
ignoreAcceptCharsetFrom HTTP_ client_version_string
dsgw.conf) is ../html. The HTML
charset
include
Example
ignoreAcceptCharsetFrom Mozilla/4.01x-NSCP Mozilla/3
More information: “charset,” on page 93.
Specifies the location of another configuration file that should be read by the gateway.
Format
include "configuration_file"
Example
include "../config/dsgw-l10n.conf"
Appendix A Parameters Defined in the .conf File 97
Page 92
location
location
Defines the location choices selectable from the gateway when adding new entries. Each
location parameter represents a branch point in the directory tree below which new
entries can be added.
Format
location handle "friendly_name""dn"
handle. An arbitrary string used by the location-suffix parameter to map a type of
entry to the locations where the entry can be created. For more information, see
“location-suffix,” on page 99.
friendly_name. An arbitrary string that represents the location. This string should
describe the location because the gateway displays this string to users to represent the
location.
dn. The distinguished name (DN) representing this branch point in the directory. If this
value is not terminated with a pound sign, the value specified on the
is appended to this value to build the fully qualified distinguished name. If the DN is
terminated with a pound sign (#), the value represented here is assumed to be a fully
qualified distinguished name, and the pound sign is stripped from the distinguished name
before the DN is used by the gateway.
include parameter
For more information, see “include,” on page 98.
Example
The following example defines an entry creation location in a user directory. This location
corresponds to the Marketing organizational unit, and the remainder of the distinguished
name is built from the value set in the
location marketing "Marketing Organization" "ou=Marketing"
A slightly different example defines the same location but specifies the fully qualified
distingui shed name:
location marketing "Marketing Organization" "ou=Marketing,
o=example.com#"
For a more complete example of the location parameter, see “Mapping Locations and
Entry Types,” on page 57.
include parameter:
98 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 93
location-suffix
Identifies the directory suffix used to create new entries in the directory.
location-suffix
newtype
This value is appended to the DN field of the
create new entries in the directory.
NLS parameter when the gateway is used to
Format
location-suffix "suffix"
Example
location-suffix "o=example.com"
Defines the types of entries that can be added to the directory using the gateway. newtype
also defines the locations in the directory where an entry type can be added. For a user to
create the entry, the corresponding location must be defined using the
parameter.
location
Format
newtype template_name "friendly_name" rdnattr locations
template_name. The name of a display-template_name.html file that defines the object
class listed. Template files are stored in the
files to define how various types of entries are displayed when entries are being created or
viewed:
• orgperson — Corresponds to the
the gateway displays an entry of object class type
• groupun — Corresponds to the
gateway displays an entry of object class type
• orgunit — Corresponds to the
gateway displays an entry of object class type
• org — Corresponds to the
displays an entry of object class type
friendly_name. An arbitrary string that describes the entry. This string should be
reasonably descriptive of the entry type because the gateway displays this string to users
who are adding entries.
display-groupun.html template. Defines how the
display-orgunit.html template. Defines how the
display-org.html template. Defines how the gateway
../config directory. The gateway uses these
display-orgperson.html template. Defines how
inetOrgPerson.
groupOfUniqueNames.
organizationalUnit.
organization.
Appendix A Parameters Defined in the .conf File 99
Page 94
NLS
rdnattr. The attribute used to name entries of this type. For example, the default value for
the
rdnattr field for people entries is uid. This means that any people entries created
using the gateway will have DNs of the following format:
uid=string
The rdnattr field can be modified so that entries are named using a different attribute.
For example, to change the
people entries created using the gateway will have
UID-based DNs (the default setting).
locations. A space-separated list of the locations where this type of entry can be added.
The locations in this list must be identical to the handle specified on the corresponding
location parameter.
rdnattr of the newtype orgperson line from uid to cn,
cn-based DNs rather than the
Example
The following example allows persons to be added to the Marketing subtree using the
template for
newtype orgperson"Person"cn marketing
organizationalPerson:
For a more complete example of the newtype parameter, see “Mapping Locations and
Entry Types,” on page 57.
NLS
Identifies the libNLS data directory, which should contain a directory named “locales,”
containing the configuration files
supported language (locale).
Format
NLS libNLS_data_directory
Example
NLS ../../lib/nls
orgchart-attrib-farleft-rdn
LANG.ctx, LANG.col, and LANG.txt for each
Specifies the attribute to be used as the leftmost RDN for the DNs of user entries (in order
to enable the Org Chart application to search for entries).
100 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 95
The orgchart-attrib-farleft-rdn attribute is the same as the one included in the Org
Chart’s configuration file (
attribute value (
file.
Format
orgchart-attrib-farleft-rdn attribute
Example
orgchart-attrib-farleft-rdn uid
securitypath
Identifies the location of the certificate database used by the gateway when using SSL to
communicate with the Directory Server. The certificate database contains the Certificate
Authority issuing the certificate for the Directory Server.
securitypath
serverRoot/clients/orgchart/config.txt), and the
uid, cn, and so on) must match the values specified in the config.txt
template
Format
securitypath "/usr/redhat/servers/alias/cert.db"
Example
securitypath "/usr/redhat/servers/alias/pb-cert.db"
Maps specific object classes to internal gateway templates. These templates define how a
specific object class such as a person, a group, or an organizational unit is displayed in the
gateway. The
clients/dsgw/config/.
templatename identified has a corresponding HTML template stored in
Format
template template_name object_class
Example
The following example identifies orgperson as the template defining attributes for the
person and inetorgperson object classes:
Appendix A Parameters Defined in the .conf File 101
Page 96
url-orgchart-base
template orgperson person inetorgperson
url-orgchart-base
Points to the Org Chart application, providing a link to the Org Chart application from the
Directory Server Gatewa y UI pages . By defau lt, the D irector y Server installat ion pro gram
sets the base to use the Red Hat Administration Server as the web server. You can cha nge
the host name and port number to be that of a dedicated web server. (See “HTTP Server
Configuration,” on page 32.)
In the absence of the
the Org Chart application in the Directory Server Gateway UI.
The Org Chart application also has a similar URL which points to the Directory Server
Gateway (the
Org Chart link to the Phonebook or remove the
to the default gateway instance (
dsgw instance). You can chang e it to ..../lang?context=pb to have the
url-orgchart-base configuration field, there will be no link to
context=dsgw altogether and have it link
default.conf, which is the dsgw instance).
Format
url-orgchart-base
http://adminHost:adminPort/clients/orgchart/bin/org?context=dsgw&data=
adminHost. Specifies the host name of the machine on which the Red Hat Administration
Server is installed.
adminPort. Specifies the port number used by the Red Hat Administration Server.
Example
http://machine.example.com:24020/clients/orgchart/bin/org?context=
dsgw&data=
vcard-property
Directory Server Gateway allows users to view vCards for person and Windows person
directory entries. The vCard and LDAP specifications define different labels to access
information: vCards use properties, and LDAP uses attributes. Therefore, there must be a
way to map the vCard property names to the LDAP attribute names so that the Directory
Server can locate the information for the vCard d isplay. The
accomplishes mapping vCard property to LDAP attribute.
102 Red Hat Directory Server Gateway Customization Guide • April 2005
vcard-property parameter
Page 97
vcard-property
Format
vcard-property vcardprop syntax ldapattr [ldapattr2...]
vcardprop. The name of a vCard property. vCard properties that are currently mapped to
LDAP attributes are:
• FN — The Formatted Name property. All vCards must have an FN property. By
default, FN is mapped to the
cn attribute.
• N — The Name property. By default, N is mapped to the
sn and givenName attributes.
• ORG — The ORG property may refer to the organizational name and units of the
person or resource associated with the vCard. By default, ORG is mapped to the
ou attributes.
o and
• ROLE — The ROLE proper ty may ref er to the rol e, occup ation or bus iness categor y of
the person or resource described by the vCard. By default, ROLE is mapped to the
businessCategory attribute.
• ADR;WORK — The work address of the of the person or resource described by the
vCard. By default, ADR;WORK is mapped to the
postalAddress attribute.
• ADR;HOME — The home address of the of the person or resource described by the
vCard. By default, ADR;HOME is mapped to the
homePostalAddress attribute.
• EMAIL;INTERNET — The email address of the person or resource described by the
vCard. By default, EMAIL;INTERNET is mapped to the
mail attribute.
• TITLE — The TITLE property specifies the job title, functional position or function of
the person or resource described by the vCard. By default, TITLE is mapped to the
title attribute.
• TEL;WORK — The business teleph one number of the per son or r esource des cribe d by
the vCard. By default, TEL;WORK is mapped to the
telephoneNumber attribute.
• TEL;FAX — The fax number of the person or reso urce described by the vCard. By
default, TEL;FAX is mapped to the
• TEL;CELL — The cellular telephone number of the person or resource described by
the vCard. By default, TEL;CELL is mapped to the
• TEL;HOME — The residential telephone number of the person or resource described
by the vCard. By default, TEL;HOME is mapped to the
• NOTE — Provides any additional comments or information about the person or
resource described by the vCard. By default, NOTE is mapped to the
attribute.
facsimileTelephoneNumber attribute.
mobile attribute.
homePhone attribute.
description
Appendix A Parameters Defined in the .conf File 103
Page 98
vcard-property
syntax. A string that describes the nature of the vCard information. The following
syntaxes are supported:
• cis — used for simple strings, such as a person’s name or telephone number.
• mls — used for multi-line strings, such as a mailing address.
ldapattr [ldapattr2...]. The attribute(s) to be mapped to the vCard property. This is useful
when mapping a vCard property to a custom attribute.
Example
The following example changes the mapping of the NOTE property from the default
description attribute to a custom attribute named hobbies:
vcard-property NOTE mls hobbies
104 Red Hat Directory Server Gateway Customization Guide • April 2005
Page 99
Appendix B
Gateway Directives
This appendix describes directives used in gateway HTML object class and search result
templates. The appendix contains the following sections:
• Introduction (page 107)
• Context-Related Directives (page 109)
• Entry-Related Directives (page 110)
• Miscellaneous Directives (page 122)
Introduction
The display of LDAP directory information is controlled by HTML template files
containing directives. Directives are HTML comments that can be interpreted by the
gateway C GIs.
The most commonly used directive is
LDAP entries. Here are some other examples of directives:
<!-- DS_HELPBUTTON "topic=HELP-ME-NOW" -->
<!-- DS_ATTRIBUTE "attr=sn" "size=>20" -->
<!-- IF "BoundAsThisEntry" -->
<!-- ENDIF -->
NOTE With the exception of GCONTEXT and PCONTEXT, each directive must start
DS_ATTRIBUTE, used to display attributes present in
at the beginning of a line and be contained on a single line in the HTML
file. Most of the Directory Server Gateway directives begin with
DS_.
107
Page 100
Introduction
Structure of an HTML Template
Directory entry display, edit, and add templates generally have the following structure:
<HTML>
<HEAD>
<!-- DS_ENTRYBEGIN -->
<!-- DS_EMIT_BASE_HREF -->
<!-- BODY -->
<!-- DS_LAST_OP_INFO -->
<!-- DS_BEGIN_ENTRYFORM -->
<!-- attribute directives, e.g., -->
<!-- DS_ATTRIBUTE "attr=givenName" "size=>20" -->
<!-- DS_ATTRIBUTE "attr=sn" "size=>20" -->
<!-- etc. -->
<!-- DS_SAVEBUTTON "label= SAVE " -->
<!-- DS_END_ENTRYFORM -->
<!-- DS_ENTRYEND -->
<!-- ENDHTML -->
Structure of an HTML Template for Directory List
Directory entry list templates generally have the following structure:
<HTML>
<!-- TITLE "Search Results" -->
<!-- DS_SEARCHDESC -->
<!-- IF "FoundEntries" -->
<!-- DS_SORTENTRIES "attr=XXX" -->
<!-- DS_ENTRY_BEGIN -->
<!-- stuff that is repeated for each entry found, e.g., -->
<!-- DS_ATTRIBUTE "attr=dn" "syntax=dn" -->
<!-- etc. -->
<!-- DS_ENTRYEND -->
<!-- ELSE -->
<!-- stuff to be rendered if no entries were found, e.g.,-->
Please try a different search....
<!-- ENDIF -->
<!-- ENDHTML -->
108 Red Hat Directory Server Gateway Customization Guide • April 2005
Loading...