InfoBroker_Server___________________________________ Administration Guide AA-Q5WNC-TE March 1995 This document explains how to install, configure, and manage the InfoBroker server and how to use the Lightweight Directory Access Protocol (LDAP) API to create client applications. Revision/Update Information: This document supersedes InfoBroker Server Administration Guide, part number AA-Q5WNB-TE. Operating System: DEC OSF/1 AXP Version 3.0 or higher Software Version: InfoBroker Server Version 2.1. InfoBroker Client Version 1.0A. Digital Equipment Corporation Maynard, Massachusetts ________________________________________________________________ First Published, March 1994 Revised, December 1994 Revised, March 1995 The information in this document is subject to change without notice and should not be construed as a commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital Equipment Corporation or its affiliated companies. Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013. © Digital Equipment Corporation 1995. All Rights Reserved. The following trademarks are registered by Digital Equipment Corporation: Alpha AXP, AXP, DEC, DECnet, Digital, the DIGITAL logo, InfoBroker, MAILbus, MailWorks, and PATHWORKS. The following are third-party trademarks: cc:Mail is a registered trademark of cc:Mail, Inc. Microsoft and MS are registered trademarks, and Windows is a trademark of Microsoft Corporation. NFS is a registered trademark of Sun Microsystems, Inc. Novell is a registered trademark of Novell, Inc. OSF/1 is a registered trademark of the Open Software Foundation, Inc. PC-NFS is a registered trademark of Sun Microsystems, Inc. PC/TCP is a registered trademark of FTP Software, Inc. Sun is a registered trademark of Sun Microsystems, Inc. UNIX is a registered trademark of UNIX System Laboratories, Inc. a wholly owned subsidiary of Novell, Inc. The Graphics Interchange Format (C) is the Copyright property of CompuServe Incorporated. GIF (sm) is a Service Mark property of CompuServe Incorporated. This document is available on CD-ROM. This document was prepared using VAX DOCUMENT, Version 2.1. _________________________________________________________________ Contents Preface................................................... xi Part I Product Overview 1 InfoBroker Overview 1.1 The InfoBroker Components..................... 1-2 1.2 Overview of the Name-Service Databases........ 1-5 1.2.1 Directory Syntax and Structure Rules (Schema).................................. 1-7 1.2.2 InfoBroker Installation and Configuration Issues.................................... 1-10 1.3 LDAP and Client Support....................... 1-12 2 Roadmaps Through This Document 2.1 Roadmap: A Workgroup Directory and Web-Browser Clients....................................... 2-3 2.2 Roadmap: A Workgroup Directory and the InfoBroker Client Version 1.0A................ 2-5 2.3 Roadmap: A Workgroup Directory and Your Own LDAP Client Application....................... 2-6 2.4 Roadmap: X.500 with Standard Schema........... 2-7 2.5 Roadmap: Workgroup Directory and X.500........ 2-9 2.6 Roadmap: Customized Schema.................... 2-11 2.7 Roadmap: Workgroup Directory to X.500 Migration..................................... 2-14 iii Part II Installation and Start Up 3 Server Installation, Startup, and Termination 3.1 Preparing to Install InfoBroker............... 3-1 3.1.1 Check the Software Distribution Kit ...... 3-1 3.1.2 Read the Release Notes ................... 3-1 3.1.3 System Requirements....................... 3-2 3.1.4 Backup.................................... 3-3 3.1.5 Register your Software License............ 3-3 3.2 Installation Procedure ....................... 3-4 3.2.1 Step 1: Log in to the root Account ....... 3-4 3.2.2 Step 2: Mount the CD ..................... 3-4 3.2.3 Step 3: Delete the Files from the Old Kit....................................... 3-5 3.2.4 Step 4: Start the Installation ........... 3-5 3.2.5 Step 5: Choose the Optional Subsets ...... 3-5 3.2.6 Step 6: Complete the Installation ........ 3-7 3.3 Postinstallation Procedure ................... 3-7 3.4 Starting the InfoBroker Server................ 3-8 3.4.1 Starting the InfoBroker Server with a Workgroup Directory....................... 3-8 3.4.2 Starting the InfoBroker Server with X.500..................................... 3-8 3.4.3 Starting the InfoBroker Server with both a Workgroup Directory and X.500............. 3-9 3.5 Starting the InfoBroker Look-Up Daemon........ 3-9 3.6 Stopping the InfoBroker Server and the Look-Up Daemon........................................ 3-11 3.7 Restarting the InfoBroker Server after Customization................................. 3-11 4 Installing and Using Client Software 4.1 Using a Web Browser to Look Up People......... 4-1 4.2 Installing and Using the Version 1.0A Client........................................ 4-2 4.2.1 Prerequisites for the InfoBroker Client Version 1.0A.............................. 4-2 4.2.1.1 Software ............................... 4-3 4.2.1.2 Disk Space and Memory .................. 4-3 4.2.1.3 Information ............................ 4-3 iv 4.2.2 Installing and Configuring the InfoBroker Client ................................... 4-4 4.2.2.1 InfoBroker Client Setup ................ 4-4 4.2.2.2 Reconfigurations ....................... 4-4 4.2.3 Tips for Running the InfoBroker client ... 4-5 4.2.3.1 Connection Problems .................... 4-5 4.2.3.2 Changing the TCP/IP Client Port Number ........................................ 4-5 4.2.3.3 Changing the DECnet Client Task Name ... 4-6 5 Server Configuration and Customization 5.1 Configuring the InfoBroker For Use with X.500......................................... 5-1 5.1.1 Configuring InfoBroker for a Digital DSA....................................... 5-2 5.1.2 Configuring InfoBroker for a Non-Digital DSA....................................... 5-3 5.2 Planning for your Workgroup Directory......... 5-3 5.2.1 Creating Entries in Your Workgroup Directory................................. 5-4 5.2.2 Migrating the Workgroup Directory to an X.500 Directory........................... 5-7 5.3 Customizing Your Directory's Schema........... 5-8 5.3.1 Assigning Object Identifiers to New Definitions............................... 5-9 5.3.2 Adding Attribute and Class Definitions.... 5-10 5.3.3 Compiling Your Customized Schema.......... 5-14 5.4 Customizing the InfoBroker Client Version 1.0A Interface..................................... 5-14 5.5 Configuring the HTML Page and the Look-Up Daemon........................................ 5-15 5.5.1 Specifying Search Filters................. 5-16 5.5.2 Searching for and Modifying Attributes.... 5-19 5.5.3 Changing the Default Header and File Specifications............................ 5-21 5.5.4 The Search Base and Other Directory Service Information....................... 5-21 5.6 What's Cool: the InfoBroker and a World Wide Web Server.................................... 5-23 v Part III Using the LDAP API 6 Developing Client Applications with the LDAP API 6.1 Introducing the LDAP API...................... 6-1 6.2 Programming Environment Information........... 6-2 6.2.1 Programming Language Information.......... 6-2 6.2.2 Platform and Linking Information.......... 6-4 6.3 Information About Name Service Directories.... 6-4 6.3.1 Restrictions on Modifying and Creating Entries................................... 6-5 6.3.2 Specifying Relative Distinguished Names... 6-5 6.4 Client Development Process.................... 6-6 6.4.1 Synchronous Searches...................... 6-7 6.4.2 Asynchronous Searches..................... 6-8 6.4.3 Reading Binary Attribute Values........... 6-9 6.4.4 Directory Entry Modification.............. 6-9 6.5 Sample LDAP Client Application................ 6-11 Part IV LDAP API Reference ldapAbandon......................................... LDAP-3 ldapAddW............................................ LDAP-4 ldapBind............................................ LDAP-6 ldapCountEntries.................................... LDAP-8 ldapDelete.......................................... LDAP-9 ldapDeleteDNW.......................................LDAP-10 ldapErrorToText.....................................LDAP-12 ldapExplodeDN.......................................LDAP-13 ldapFirstAttribute..................................LDAP-15 ldapFirstEntry......................................LDAP-17 ldapGetDN...........................................LDAP-19 ldapGetValues.......................................LDAP-20 vi ldapGetValuesLen....................................LDAP-22 ldapModifyW.........................................LDAP-24 ldapModrdnW.........................................LDAP-26 ldapMsgFree.........................................LDAP-28 ldapNextAttribute...................................LDAP-29 ldapNextEntry.......................................LDAP-31 ldapOpen............................................LDAP-33 ldapPoll............................................LDAP-35 ldapSearchReqst.....................................LDAP-36 ldapSearchReqstLim..................................LDAP-40 ldapSearchResult....................................LDAP-44 ldapSearchW.........................................LDAP-46 ldapSearchWLim......................................LDAP-50 ldapUnBind..........................................LDAP-54 ldapValueFree.......................................LDAP-55 A Files Created by Installation A.1 InfoBroker server Files ...................... A-1 A.2 InfoBroker Client Version 1.0A Files.......... A-5 A.2.1 Files Installed to \X500C ................ A-6 A.2.2 Files Installed to \WINDOWS .............. A-6 A.2.3 Files Installed to \X500C\SDK ............ A-7 B Troubleshooting Tips for the InfoBroker Server C Default Structure Rules for the Workgroup Directory C.1 Object Classes................................ C-2 C.1.1 alias..................................... C-2 C.1.2 country................................... C-3 C.1.3 countryAlias.............................. C-3 C.1.4 decMailUser............................... C-4 C.1.5 device.................................... C-4 C.1.6 deviceAlias............................... C-5 C.1.7 groupOfNames.............................. C-6 C.1.8 groupOfNamesAlias......................... C-7 C.1.9 locality.................................. C-7 C.1.10 localityAlias............................. C-8 C.1.11 mhs-user.................................. C-9 vii C.1.12 organization.............................. C-9 C.1.13 organizationAlias......................... C-11 C.1.14 organizationalPerson...................... C-11 C.1.15 organizationalPersonAlias................. C-12 C.1.16 organizationalRole........................ C-13 C.1.17 organizationalRoleAlias................... C-14 C.1.18 organizationalUnit........................ C-15 C.1.19 organizationalUnitAlias................... C-16 C.1.20 residentialPerson......................... C-17 C.1.21 residentialPersonAlias.................... C-18 C.1.22 top....................................... C-18 C.2 Attribute Types............................... C-19 C.2.1 aliasedObjectName......................... C-19 C.2.2 businessCategory.......................... C-20 C.2.3 commonName................................ C-20 C.2.4 countryName............................... C-21 C.2.5 description............................... C-22 C.2.6 decMailWorksUserName...................... C-22 C.2.7 decMRaddress.............................. C-23 C.2.8 decPMAddress.............................. C-23 C.2.9 decPreferredMailAddress................... C-23 C.2.10 destinationIndicator...................... C-24 C.2.11 facsimileTelephoneNumber.................. C-24 C.2.12 generationQualifier....................... C-25 C.2.13 givenName................................. C-25 C.2.14 initials.................................. C-26 C.2.15 internationaliSDNNumber................... C-26 C.2.16 localityName.............................. C-27 C.2.17 member.................................... C-27 C.2.18 mhsORAddresses............................ C-28 C.2.19 objectClass............................... C-28 C.2.20 organizationName.......................... C-29 C.2.21 organizationalUnitName.................... C-29 C.2.22 owner..................................... C-30 C.2.23 physicalDeliveryOfficeName................ C-30 C.2.24 postalAddress............................. C-31 C.2.25 postalCode................................ C-32 C.2.26 postOfficeBox............................. C-33 C.2.27 preferredDeliveryMethod................... C-33 C.2.28 registeredAddress......................... C-34 C.2.29 rfc822Mailbox............................. C-35 C.2.30 roleOccupant.............................. C-35 C.2.31 seeAlso................................... C-35 viii C.2.32 serialNumber.............................. C-36 C.2.33 stateOrProvinceName....................... C-36 C.2.34 streetAddress............................. C-37 C.2.35 supportedApplicationContext............... C-37 C.2.36 surname................................... C-38 C.2.37 telephoneNumber........................... C-38 C.2.38 teletexTerminalIdentifier................. C-38 C.2.39 telexNumber............................... C-39 C.2.40 title..................................... C-40 C.2.41 userPassword.............................. C-40 C.2.42 x121Address............................... C-41 C.3 X.500 Attribute Value Syntaxes................ C-41 C.3.1 countryNameSyntax......................... C-41 C.3.2 distinguishedNameSyntax................... C-42 C.3.3 ORAddress................................. C-42 C.3.4 numericStringSyntax....................... C-42 C.3.5 objectIdentifierSyntax.................... C-42 C.3.6 postalAddressSyntax....................... C-43 C.3.7 printableStringSyntax..................... C-43 C.3.8 stringSyntax.............................. C-43 C.3.9 telephoneNumberSyntax..................... C-43 C.3.10 userPasswordSyntax........................ C-43 D LDAP Predefined Constants D.1 LDAP Error Processing......................... D-1 D.1.1 The InfoBroker Log Files.................. D-1 D.1.2 LDAP Return Values........................ D-2 D.2 Modification Constants........................ D-10 D.3 Network-Transport Constants................... D-10 D.4 Search-Scope Constants........................ D-11 Index Examples 5-1 Sample Workgroup Directory File........... 5-5 6-1 Sample LDAP Application................... 6-11 ix Figures 1-1 How InfoBroker Works...................... 1-3 1-2 The Hierarchical Structure of the Directory Information Tree................ 1-7 1-3 A Distinguished Name...................... 1-8 6-1 Entry Modification Data Structures........ 6-10 Tables 3-1 Optional Subsets ......................... 3-6 A-1 Files Installed on the Server ............ A-1 A-2 Client Directory Files ................... A-6 A-3 Windows Directory Files .................. A-6 A-4 SDK Directory Files ...................... A-7 x _________________________________________________________________ Preface The InfoBroker is a client/server product that looks up information about people (telephone numbers, electronic Mail addresses, office numbers and so forth) across a network. The InfoBroker server runs on an OSF/1 system. There are three interfaces you can use to look up a name using the InfoBroker server: an HTML page viewed on a web browser, any LDAP-compliant client, or the InfoBroker Client Version 1.0A (which runs on a PC, under Windows Version 3.1 or higher). To look up a name using a web browser, a client user specifies a name on the main InfoBroker HTML page. Across a TCP/IP network, the InfoBroker look-up daemon-which runs on an OSF/1 system-receives the look-up request from the browser and passes it to the InfoBroker server. The server searches one or several name-service directories to locate the information, and then relays the requested information through the look-up daemon and back to the client user's web browser. This product does not provide a web browser; you must obtain one separately. (For more information, see the Obtaining a Web Browser section in this Preface.) Once you have a web browser, and once you have installed the InfoBroker server and look-up daemon, you have everything you need to look-up names; you do not need a World-Wide Web server or a connection to the Internet. The InfoBroker server can also return information to clients that use the Lightweight Directory Application Protocol (LDAP) API. You can use any LDAP-compliant client- including the InfoBroker Client Version 1.0A or a client xi that you create yourself using the LDAP API-to look up information. As mentioned, the InfoBroker looks up information in name- service directories, which are databases that contain entries; an entry contains information about a person, a place, an organization, a device, and so forth. The InfoBroker can look up information in two types of name- service directories: the X.500 Directory Service, and the workgroup directory (a text file of entries located on the InfoBroker server's system). Chapter 1 and Chapter 5 contain detailed information on directory concepts and on these two types of directories. This document describes how to install, configure, and manage the InfoBroker server; how to install and configure the look-up daemon for use with web browsers; how to write LDAP-compliant clients; and how to install the InfoBroker Client Version 1.0A. Obtaining a Web Browser You can use a web browser based on the NCSA Mosaic freeware, which was developed by the National Center for Supercomputing Applications at the University of Illinois at Urbana-Champaign. Or, you can use any other web browser that can communicate with World Wide Web servers. At this writing, all web browsers require a TCP/IP connection to the InfoBroker look-up daemon. Finally, the look-up daemon includes software that translates JPEG photographs to GIF art files; so, you can use a web browser that supports either JPEG or GIF files. If you choose, you can purchase a web browser at your favorite, local software store. As another alternative, if you have access to the Internet and if you can use anonymous FTP, you can obtain freeware browsers in the Digital gateway, which is on the host machine gatekeeper.dec.com. To obtain a listing of the browsers currently available in the Digital gateway, read this file: gatekeeper.dec.com:/pub/net/infosys/README.Mosaic xii At this writing, the gateway contains both NCSA and Netscape browsers. Both of these browsers run on the OSF /1 operating system. The Netscape browser is available for only a limited time. The NCSA browser is currently in this directory in the gateway: gatekeeper.dec.com:/pub/net/infosys/NCSA/Web/Mosaic The Netscape browser is currently in this directory in the gateway: gatekeeper.dec.com:/pub/net/infosys/Netscape/unix If your clients are using DECwindows Motif Version 1.2- 3 or higher on OpenVMS, then they have an NCSA Mosaic viewer available to them. DECwindows Motif provides the NCSA Mosaic viewer software without additional charge as sample software, and on an "as is" basis. Since the NCSA Mosaic viewer that ships with this release is only a sample implementation, Digital places Mosaic with the other sample software in the DECW$UTILS directory; it is not a part of the DECwindows Motif product and Digital assumes no liability for its use. Digital plans to replace this sample NCSA Mosaic viewer implementation in a future release. When your client users are ready to run the browser on their system, they need to issue this OpenVMS command before running the browser: $ SET DISPLAY/NODE=nodename/TRANSPORT=TCP/CREATE If your InfoBroker clients are running on a PC with an installed version of PATHWORKS Version 5.1 or higher, then you can use the Mosaic from Digital product (formerly called PATHWORKS Mosaic). If Mosaic from Digital is not installed on your system even though you are running PATHWORKS, you can run this file, which is on your PATHWORKS server, to install the browser: \\server_machine_name\KITS\PWMOSAIC\DISK1\SETUP.EXE xiii Ordering the InfoBroker Client Version 1.0A The following are order numbers for the InfoBroker Client Version 1.0A: ___________________________________________________________ Order_Number__Type_of_License______________________________ QM-2VJAA-AA Software license only. QB-2VJAA-SA Software license, media, and this book. QM-2VJAA-LD Software license only, 60-day loan. QB-2VJAA-LD Sofware license, media, and this book; 60-day ______________loan.________________________________________ Audience This manual has two audiences. The first audience is experienced DEC OSF/1 system managers with root permissions, who know DEC OSF/1 and its installation procedures, and who know PC networking and management. Parts I and II are intended for system managers. The second audience is experienced client/server programmers who are familiar with X.500 and with C programming. Chapter 1, and Parts III and IV are intended for programmers. To use the InfoBroker, you need to understand basic X.500 concepts and syntax; this manual provides you with enough background information to use the InfoBroker with a workgroup directory, which uses the default Digital X.500 schema. (For more information on X.500 syntax and the X.500 schema, see Chapter 1.) If you want to use a customized schema or if you want to use the InfoBroker in conjunction with an X.500 directory service, then you might want to refer to the DEC X.500 Directory Service Management manual, and you may need to work with a system administrator who understands X.500 configuration issues. (Section 5.2 and 5.3 describe the contents of a workgroup directory and how to customize the schema, but they do not discuss advanced X.500 schema- customization issues.) xiv New InfoBroker Version 2.1 Features The following are changes from the last version of the InfoBroker: o The InfoBroker now supports information look-up using a web browser. The InfoBroker still supports look-ups from the InfoBroker Client Version 1.0A. o Digital now ships the LDAP API for use on OSF/1 systems, Version 3.0 or higher. You can use the LDAP API to create a customized client that makes requests of the InfoBroker server (or any LDAP-compliant server). o The InfoBroker server now supports the ldapAddW, ldapDelete*, and ldapModify* functions for additions and modifications to X.500 entries. The server does not support these functions for additions and modifications to workgroup-directory entries; you must edit the workgroup-directory using a text editor. Related Information The following documents may be helpful when installing, configuring, and managing the InfoBroker: ___________________________________________________________ Target Title____________Audience____Provides_information_about..._ InfoBroker InfoBroker Important information Release Notes server about changes made to the system InfoBroker. You should read adminis- the InfoBroker Release Notes trator before installing or using the InfoBroker. Digital X.500 Directory Managing Digital X.500 Directory service Directory Service. Services adminis- Managment trators xv ___________________________________________________________ Target Title____________Audience____Provides_information_about..._ DEC MailWorks DEC Configuration changes to the Server for MailWorks DEC MailWorks system that OSF/1 AXP system you need to implement so that Workgroup adminis- it works properly with the /System trators InfoBroker server. Adminstration______________________________________________ Structure and Organization This document provides the following information: ___________________________________________________________ Chapter______Contents______________________________________ PART 1 Chapter 1 An overview of the InfoBroker product. Chapter 2 A roadmap through this document for different audiences. PART 2 Chapter 3 A description of server installation, startup, and termination. Chapter 4 A description of how to use a web browser to look up information. Chapter 5 A description of server configuration, specifying which database to search and specifying how to customize the structure rules of the stored data. PART 3 Chapter 6 An overview of program-development issues for those who wish to create their own LDAP- compliant clients. PART 4 A section containing reference information on LDAP routines. Appendix A A list of the files created by the server. Appendix B A list of troubleshooting tips for common problems encountered when using the InfoBroker. xvi ___________________________________________________________ Chapter______Contents______________________________________ Appendix C A reference section for the X.500 default schema, listing legal classes and attributes, and listing the legal relationship between classes. Appendix D A list of the predefined LDAP constants in the _____________libldap.h_file._______________________________ Conventions Used in this Guide These are the conventions used in this document. ___________________________________________________________ When you see..._________It_represents...____________________________ Colored text Information that you need to enter as shown, in examples and in dialog boxes. constant Case-sensitive attribute names, and DEC width OSF/1 commands and file names, which you need to enter as shown in the text; also, routines, language keywords, and .h files, in the LDAP API reference section; also, URLs. FILE.TXT PC file names. bold Screen buttons and menu options. replace-this Placeholders for information specific to your configuration that you need to provide in examples, dialog boxes, or syntax descriptions; also, parameters in the LDAP API reference section. > OSF/1 system prompts. #__________________________________________________________ xvii Part I _________________________________________________________________ Product Overview This part contains general information about the InfoBroker product, and provides alternative roadmaps through this book for different audiences (system administrators who will use the InfoBroker with only an X.500 Directory Service, with only the workgroup directory, and so forth). 1 _________________________________________________________________ InfoBroker Overview The InfoBroker is a client/server product that looks up information about people (telephone numbers, electronic Mail addresses, office numbers and so forth) across a network. The InfoBroker server runs on an OSF/1 system. There are three interfaces you can use to look up a name using the InfoBroker server: an HTML page viewed on a web browser, any LDAP-compliant client, or the InfoBroker Client Version 1.0A (which runs on a PC, under Windows Version 3.1 or higher). To look up a name using a web browser, a client user specifies a name on the main InfoBroker HTML page. Across a TCP/IP network, the InfoBroker look-up daemon-which runs on an OSF/1 system-receives the look-up request from the browser and passes it to the InfoBroker server. The server searches one or several name-service directories to locate the information, and then relays the requested information through the look-up daemon and back to the client user's web browser. This product does not provide a web browser; you must obtain one separately. (For more information, see the Obtaining a Web Browser section in the Preface.) Once you have a web browser, and once you have installed the InfoBroker server and look-up daemon, you have everything you need to look-up names; you do not need a World-Wide Web server or a connection to the Internet. The InfoBroker server can also receive calls from clients that use the Lightweight Directory Application Protocol (LDAP) API. You can use any LDAP-compliant client-including the InfoBroker Client Version 1.0A or a client that you create yourself using the LDAP API-to look up information. application.) InfoBroker Overview 1-1 Name-service directories are databases that contain entries; an entry contains information on a person, a place, an organization, a device, and so forth. The needs of your workgroup and your company will determine how you configure the InfoBroker, and you may be able to save significant time and effort by planning ahead. The remaining sections of this chapter provide you with background information on the InfoBroker product, and Chapter 2 helps you to plan ahead and to navigate this book efficiently. This chapter includes the following sections: o The InfoBroker Components (Section 1.1) o Overview of the Name-Service Databases (Section 1.2) 1.1 The InfoBroker Components Figure 1-1 illustrates the InfoBroker components. The numbers in the figure correspond to the numbers in the list that follows the figure. 1-2 InfoBroker Overview Figure 1-1 How InfoBroker Works 1 You can use a web browser to look up a name. A web browser is an application that helps people to access and read information easily across a network and across various operating system platforms. To make requests of the InfoBroker server, you can use a browser based on the NCSA Mosaic freeware, which was developed by the National Center for Supercomputing Applications at the University of Illinois at Urbana-Champaign. Or, you can use any other web browser that can communicate with World Wide Web servers. (For more information on obtaining a web browser, see the Obtaining a Web Browser section in the Preface of this manual.) InfoBroker Overview 1-3 In the web browser, the user opens a Universal Resource Locator (URL), which is the network address of the InfoBroker's look-up daemon. Each browser has its own method for the user open an URL. However, most browsers include an Open URL item in its File menu. Note: If you are using a web browser to look up names, you cannot use DECnet as a network transport; you must use TCP/IP. When you use the browser to open the InfoBroker URL, the browser brings up a HyperText Mark-up Language (HTML) page that allows you to look up names. HTML is the device-independent source code for pages that web browsers use to format information for display; it is a subset of the Standard Generic Mark-Up Language (SGML) formatting tag set. Chapter 4 provides additional information about the look-up daemon's URL. For more information on using the InfoBroker HTML page, click on the "Help" hypertext hotspot, which is located on the main InfoBroker HTML page, under the Find command line and the "Advanced search" hotspot. 2 The InfoBroker look-up daemon receives requests from web browsers, and relays information to and from the InfoBroker server. The InfoBroker look-up daemon is a dedicated application that receives look-up requests from InfoBroker HTML pages and relays those requests and other information to and from the InfoBroker server. This application runs on an OSF/1 system, which may be the same system running the server or another OSF/1 system. You can specify either DECnet or TCP/IP as the network protocol between these two applications. The look-up daemon configuration file, located on the same system as the look-up daemon, controls the default look-up behavior of the InfoBroker HTML page and specifies to the server which directory-entry attributes to search. (Section 1.2.1 provides more information about directory entries and attributes.) Section 5.5 provides more information on altering the default values in the look-up daemon's configuration file. 1-4 InfoBroker Overview 3 You can install and run the InfoBroker Client Version 1.0A, and use it to look up a name. If you are using the InfoBroker Client Version 1.0A or a client that you have developed yourself using Digital's LDAP API functions, then you can use either DECnet or TCP/IP as your network transport. 4 You can use a non-Digital, LDAP-compliant client to look up a name. If you are using an LDAP-compliant client other than the InfoBroker Client Version 1.0A or a client that uses the Digital LDAP API functions, then you cannot use DECnet as your network transport; you must use TCP/IP. 5 If you configured it to do so, the server passes the look-up request to an X.500 DUA, which runs on the same system as the server, and the X.500 DUA initiates the look-up in the X.500 system. Section 1.2 provides more information about X.500. 6 If you configured it to do so, the server searches in the workgroup directory. The workgroup directory is a text file that you create and maintain, which contains directory entries using the X.500 directory-entry syntax. You can name the workgroup-directory file any legal file name. The workgroup directory resides on the same system as the InfoBroker server. Section 1.2 provides more information about workgroup directorys. 1.2 Overview of the Name-Service Databases When the person using the InfoBroker client requests information, the server looks in a directory to locate the requested information. A directory is a type of database that contains a collection of entries. Each entry corresponds to an object that you wish to represent, such as a person, a place, an organization, or a device (a computer or printer). InfoBroker Overview 1-5 The InfoBroker supports two types of directories: the X.500 directory service and the workgroup directory. You can configure the InfoBroker server to search in either directory or in both. If you specify both, the InfoBroker searches the workgroup directory first and then the X.500 directory. In general, if you want the InfoBroker to search through a relatively small number of names (perhaps you are running the InfoBroker in a small, workgroup environment), then you probably want to create and use a workgroup directory. The InfoBroker workgroup directory is a text file that resides on the OSF/1 system running the InfoBroker server. Therefore, if you need a very large directory (as would a medium-sized corporation or a multinational organization, for example), then you probably want the InfoBroker to search through a new or an existing X.500 directory. The X.500 product is a distributed directory service that is based on the international standard, ISO X.500, and that provides a single, scalable directory service across a potentially large network. X.500 also locates directory data on multiple machines so that the information is accessible if one of the machines becomes unavailable. It also locates directory information close to where it is needed, maintains the directory data, and uses mechanisms to improve the look-up time for user requests, which are features useful for very large enterprises and for enterprises that require that the data be very accessible. The X.500 standard specifies a syntax for directory entries and a set of structure rules for defining unambiguous names. The InfoBroker's workgroup directory must comply with this standard set of rules. When configuring the InfoBroker, you need to know the format for creating entries in the databases, and you need to know the syntax for specifying a unique name in the database ("Joan Smith" in Sales, as opposed to "Joan Smith" in Marketing, for example). The following sections provide you with this information. 1-6 InfoBroker Overview 1.2.1 Directory Syntax and Structure Rules (Schema) In general, before creating directory entries, you need to organize your name data in a hierarchical tree. Figure 1-2 illustrates such an organizational hierarchy, where the top of the hierarchy might be the company name, the middle might be divisions within the company, and the bottom would be the names of the individuals in the divisions. The amount of effort in creating such a tree varies depending on which database you use. For example, if you are using an existing X.500 database, then ask the X.500 system administrator to provide you with the existing hierarchy, and add the new information to that organizational structure. If you are configuring a new X.500 implementation, then you need to take the time to develop an organizational structure that is scalable and easy to update. If you are creating a workgroup directory in a small department or workgroup setting, we recommend that you designate as few divisions as possible (marketing, writing, engineering) and then align all of your people under those divisions. In a very small department, you may want to align all of the people under one division. Once you have a hierarchy to work from, you need to determine the X.500 syntax for representing each directory entry (sometimes called a node or a leaf) in your hierarchy tree. For example, each entry in the directory tree corresponds to a physical directory entry in the database, and the entry is of a certain class, which determines the types of legal entries. Each entry also has a set of attribute names, which provide more specific details for an entry. For example, if there exists an entry for a person who works for a company (an entry whose class type is organizationalPerson), then it may be a good idea to have attributes names for the different names that a person would have. So, for example, the organizationalPerson class has two attribute names, called commonName and surname, whose attribute values might be "Margaret" and "Smith". InfoBroker Overview 1-7 Every entry has a distinguished name, which is composed of a sequence of attribute names and values that form the path through the hierarchical tree to the individual person. For example, it is this distinguished name that specifies the difference between "Joan Smith" in Sales and "Joan Smith" in Marketing. Figure 1-3 shows how a distinguished name maps onto an organizational hierarchy. Figure 1-3 A Distinguished Name The following is the distinguished name in Figure 1-3: /c=US/o="Abacus Company"/ou=Sales/cn="Joan Smith" 1-8 InfoBroker Overview The X.500 standard specifies a set of rules, called a schema, that predefines a set of classes, attributes, and the relationship between classes. For example, the schema requires that the country's name come before the company's name in the distinguished name. The X.500 Directory Service allows implementations to add classes and attributes to the schema; Digital's X.500 product defines additional classes and attributes. The schema rules establish a logical and consistent ordering for directory entries. After you have determined your organization's hierarchy, and have determined which classes and attributes are appropriate for each directory entry in your hierarchy, you can create physical entries in the directory's database. If you are creating or updating an X.500 directory, then you use X.500 utilities to add or modify entries. If you are creating a workgroup directory, then you can use a text editor to create a file (it can have any legal file name that you choose) that could contain the following entries: create entry /c=us attributes - objectClass=(top, country), - description="United States of America" create entry /c=us/o=xyz attributes - objectClass=(top, organization), - description="XYZ Corporation" create entry /c=us/o=xyz/cn="Margaret Smith" attributes - objectClass=(Top, Person, OrganizationalPerson), - cn=("Margaret", "Margaret Smith"), - sn="Smith" These create entry directives create entries for the country of the United States (/c=US), for the XYZ corporation (/c=us/o=xyz), and for Margaret Smith, who works at that company (/c=us/o=xyz/cn="Margaret Smith"). The following section discusses the implications for your InfoBroker configuration and provide suggestions for ways to proceed. For More Information On creating the workgroup directory (Section 5.2) On X.500 syntax and schema (Appendix C) InfoBroker Overview 1-9 1.2.2 InfoBroker Installation and Configuration Issues Here is a list of issues that affect how you install and configure the InfoBroker: o As a first step for anyone or for small-group needs, you can create simple entries in the database without much prior planning. To keep the process as simple as possible and to ensure an easy migration path to X.500, we recommend that you use the workgroup directory, that you use the standard classes and attributes provided with Digital's X.500 product, and that you create distinguished names for people that include only the country, the company, the department, and the person's name, as follows: /c=US/o=your-company/ou=a-division/cn=person o If your department or company is large, and if you are using the InfoBroker with an existing or new X.500 implementation, then we recommend that you take time to plan a scalable organizational hierarchy. A scalable organizational hierarchy is a tree structure that meets your needs yet makes it easy to add new branches to the tree. The DEC X.500 Directory Service Management guide provides examples of possible organizational hierarchies. o If you customize the schema of your workgroup directory, then the InfoBroker needs to understand that customized schema. If your entries in either X.500 or the workgroup directory use only the classes and attributes defined by the X.500 standard and by the Digital X.500 product, then you are using the standard schema. In this case, you do not have to perform additional tasks in order for the InfoBroker to understand the entries in your database. If you use newly defined classes or optional attributes to hold extra information in your directory entries, then you are using a customized schema. In this case, you need to edit files so that the InfoBroker understands your schema, and you need to customize the InfoBroker client, so that the users can search for and display the nonstandard information. 1-10 InfoBroker Overview If you are using a web browser to look up information, then you need to alter the look-up daemon's configuration file to reflect the new schema; the configuration file controls the attribute values on which the client users can conduct a search and the information that the InfoBroker HTML page displays by default upon completion of a search. If you are using the InfoBroker Client Version 1.0A, you need to use the Add Attribute item in the Options menu to change the attributes that the user searches for or that the client displays upon completion of a search. The InfoBroker requires the use of only one schema; if you use both a workgroup directory and an X.500 Directory Service, both must adhere to the same schema. If it is a customized schema, then the InfoBroker requires additional information to be able to understand these new classes and attributes. o The attributes you define in your workgroup-directory entries determine the search criteria for the InfoBroker client users. If you customize your schema, you must customize the client so that it can recognize the new classes and attributes, and so it can display the nonstandard information to the user. As mentioned, depending on the client that you are using, you either have to edit the look-up daemon's configuration file, or you need to use the Add Attributes item in the Options menu of the InfoBroker Client Version 1.0A. o If you are using a workgroup directory, we recommend that you do not customize the schema. If you customize the schema, it makes it more difficult to migrate the data entries from the workgroup directory to a new or existing X.500 directory service. We recommend keeping the structure of the workgroup directory simple. If you are using the InfoBroker in a small workgroup, and if your company has an existing X.500 implementation that you do not currently want to use with the InfoBroker, you may want to use the same customized schema in your workgroup directory that the X.500 directory uses. If, in the future, your company requires InfoBroker Overview 1-11 you to migrate your workgroup directory to the larger X.500 directory, the migration will be easy. If you customize the schema of your workgroup directory for this reason, we recommend that you stay in contact with the X.500 system administrator so that you can update your workgroup directory's schema, over time, in accordance with any subsequent changes made to the X.500 directory's schema. If you do customize the schema to store and display additional types of information that is of use to your workgroup, then we recommend keeping the customizations as simple as possible (for example, use auxiliary classes instead of new structure classes), so that migration to X.500 will not be overly difficult. For More Information On InfoBroker installation and configuration decisions (Chapter 2) On creating the workgroup directory (Section 5.2) On customizing a schema and on auxiliary classes (Section 5.3) On customizing the Version 1.0A client interface (Section 5.4) On customizing the HTML page (Section 5.5) 1.3 LDAP and Client Support The InfoBroker server communicates with most client applications using the LDAP standard protocol. It is possible to use another (possibly non-Digital) LDAP client with the InfoBroker server. You can also write your own LDAP client software for use with the InfoBroker server. Also, the InfoBroker Client Version 1.0A should be able to communicate with any LDAP-compliant server. For More Information On LDAP (Chapter 6) 1-12 InfoBroker Overview 2 _________________________________________________________________ Roadmaps Through This Document Preexisting environments and policies in your workgroup, organization, or company may place requirements on how you install, configure, and use the InfoBroker. For example, your choice of a client and your use of X.500 and a workgroup directory may affect how you install and configure this software. The remaining sections in this chapter provide a unique list of installation and configuration tasks-and pointers to the sections in this book that you need-for these different needs: o A workgroup directory and InfoBroker web-browser clients (Section 2.1) If you want to create or modify a workgroup directory and if your client users are using web browsers, then you need to perform the tasks listed in this section. o A workgroup directory and the InfoBroker Client Version 1.0A (Section 2.2) If you want to create or modify a workgroup directory and if your client users are using the InfoBroker Client Version 1.0A, then you need to perform the tasks listed in this section. o A workgroup directory and your own LDAP Client (Section 2.3) If you want to create or modify a workgroup directory and if your client users are using a client that you developed using the Digital LDAP functions, then you need to perform the tasks listed in this section. o X.500 with standard schema (Section 2.4) Roadmaps Through This Document 2-1 If you want the InfoBroker server to use only an existing X.500 directory, then you need to perform the tasks listed in this section. o Workgroup directory and X.500 (Section 2.5) If you want the InfoBroker to search through both a workgroup directory and an existing X.500 directory, then you need to perform the tasks listed in this section. o Customized schema (Section 2.6) If you want the InfoBroker server and client to understand a customized schema of either a workgroup directory, an existing X.500 directory, or both, then you need to perform the tasks listed in this section. o Workgroup directory to X.500 Migration (Section 2.7) If you want to migrate an existing InfoBroker configuration for a workgroup directory to a configuration that uses X.500 (or to a configuration that uses both), then you need to perform the tasks listed in this section. 2-2 Roadmaps Through This Document 2.1 Roadmap: A Workgroup Directory and Web-Browser Clients The following is a roadmap through this book for people who want to create or modify a workgroup directory, and whose client users access directory information using web browsers: ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 1. Using a text editor, create or modify Section 5.2 directory entries for each person in your directory. Optional background reading: The DEC X.500 Directory Service Management guide 2. Install the prerequisite software, Section 3.1.3 install the server, and install the Section 3.2 look-up daemon. 3. Start the server. Section 3.4.1 4. Start the look-up daemon, and provide Section 3.5 the associated URL to the web-browser users. 5. Modify the search and display Section 5.6 characteristics of the look-up daemon and the InfoBroker HTML page; inform the web-browser users of the changes you make. 6. Obtain a web browser. the Preface 7. Install and run the web browser. See the web browser's documentation. Roadmaps Through This Document 2-3 ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 8. Open the look-up daemon's URL. Make See the web sure that your users understand that browser's they cannot modify or add entries documentation. to a workgroup directory using a web browser; they must edit the workgroup directory using a text editor. ___________________________________________________________ 2-4 Roadmaps Through This Document 2.2 Roadmap: A Workgroup Directory and the InfoBroker Client Version 1.0A The following is a roadmap through this book for people who want to create or modify a workgroup directory, and whose client users are accessing directory information using the InfoBroker Client Version 1.0A: ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 1. Using a text editor, create directory Section 5.2 entries for each person in your directory. Optional background reading: The DEC X.500 Directory Service Management guide 2. Install the prerequisite software, and Section 3.1.3 install the server. Section 3.2 3. Start the server. Section 3.4.1 4. Install the prerequisite software, and Section 4.2.1.1 install the client. Section 4.2.2 5. Start the client. Make sure that your Double click on users understand that they cannot the InfoBroker modify or add entries to a workgroup icon. directory using this client; they must edit the workgroup directory using a text editor. ___________________________________________________________ Roadmaps Through This Document 2-5 2.3 Roadmap: A Workgroup Directory and Your Own LDAP Client Application The following is a roadmap through this book for people who want to create or modify a workgroup directory, and whose client users are accessing directory information using an application that you wrote using Digital's LDAP library of functions: ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 1. Using a text editor, create directory Section 5.2 entries for each person in your directory. Optional background reading: The DEC X.500 Directory Service Management guide 2. Install the prerequisite software, and Section 3.1.3 install the server. Section 3.2 3. Start the server. Section 3.4.1 4. Write the LDAP code for your client Section 6.4 application. Section 6.5 Part IV 5. Compile and link your code. Section 6.2 6. Run your application. Make sure that your users understand that they cannot modify or add entries to a workgroup directory using your application; they must edit the workgroup directory using a text editor. ___________________________________________________________ 2-6 Roadmaps Through This Document 2.4 Roadmap: X.500 with Standard Schema The following is a roadmap through this book for people who want the InfoBroker server search an existing X.500 directory that uses a standard schema: ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 1a. If you want the InfoBroker to use a Section 5.1.1 Digital X.500 service, then you need to invoke the configuration utility and modify the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 1b. If you want the InfoBroker to use a Section 5.1.2 non-Digital X.500 service, then you need to create a new defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 2a. If your clients are not using web Section 3.1.3 browsers, install the prerequisite Section 3.2 software, and then install the server. 2b. If your client users are using web Section 3.1.3 browsers, install the prerequisite Section 3.2 software, install the server, and install the look-up daemon. 3. Start the server. Section 3.4.2 4. If your client users are using web Section 3.5 browsers, start the look-up daemon, and provide the associated URL to the web-browser users. Roadmaps Through This Document 2-7 ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 5. If your clients use web browsers, Section 5.6 modify the search and display characteristics of the look-up daemon and the InfoBroker HTML page; inform the web-browser users of the changes you make. 6a. If your clients use web browsers, then Section 2.1, obtain, install, start, and use a web Steps 6-8 browser. 6b. If your clients use the InfoBroker Section 2.2, Client Version 1.0A, then install and Steps 4 and 5 start the client. 6c. If your clients use your own Section 2.3, LDAP client application, then Steps 4-6 code, compile, link, and run your application. ___________________________________________________________ 2-8 Roadmaps Through This Document 2.5 Roadmap: Workgroup Directory and X.500 The following is a roadmap through this book for people who want the InfoBroker server to look in both the workgroup directory and an existing X.500 directory: ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 1a. If you want the InfoBroker to use a Section 5.1.1 Digital X.500 service, then you need to invoke the configuration utility and modify the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 1b. If you want the InfoBroker to use a Section 5.1.2 non-Digital X.500 service, then you need to create the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 2. Use a text editor to create directory Section 5.2 entries in the workgroup directory for each person in your directory. 3a. If your client users are not using Section 3.1.3 web browsers, then install the Section 3.2 prerequisite software, and install the server. 3b. If your client users are using Section 3.1.3 web browsers, then install the Section 3.2 prerequisite software, install the server, and install the look-up daemon. 4. Start the server. Section 3.4.2 Roadmaps Through This Document 2-9 ___________________________________________________________ ____To_do_this...___________________________Read_this...___ 5. If your client users are using web Section 3.5 browsers, start the look-up daemon, and provide the associated URL to the web-browser users. 6. If your clients use web browsers, Section 5.6 modify the search and display characteristics of the look-up daemon and the InfoBroker HTML page; inform the web-browser users of the changes you make. 7a. If your clients use web browsers, then Section 2.1, obtain, install, start, and use a web Steps 6-8 browser. 7b. If your clients use the InfoBroker Section 2.2, Client Version 1.0A, then install and Steps 4 and 5 start the client. 7c. If your clients use your own Section 2.3, LDAP client application, then Steps 4-6 code, compile, link, and run your application. ___________________________________________________________ 2-10 Roadmaps Through This Document 2.6 Roadmap: Customized Schema The following is a roadmap through this book for people who want the InfoBroker server to understand an customized schema of either a workgroup directory or an existing X.500 directory (or both): ___________________________________________________________ ____To_do_this..._____________________Read_this..._________ 1a. If you want the InfoBroker to Section 5.1.1 use a Digital X.500 service, then you need to invoke the configuration utility and modify the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 1b. If you want the InfoBroker to Section 5.1.2 use a non-Digital X.500 service, then you need to create the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 2a. If your client users are not Section 3.1.3 using web browsers, then install Section 3.2 the prerequisite software, and install the server. 2b. If your client users are using Section 3.1.3 web browsers, then install the Section 3.2 prerequisite software, install the server, and install the look-up daemon. 3. If your client users are using Section 3.5 web browsers, start the look-up daemon. Roadmaps Through This Document 2-11 ___________________________________________________________ ____To_do_this..._____________________Read_this..._________ 4. Either plan the new classes Section 5.3 and attributes you need, and then modify the .sc files that identify additional classes and attributes to the InfoBroker server, or copy the X.500 directory's customized .sc files to the system running the InfoBroker server. Optional background reading: The DEC X.500 Directory Service Management guide 5. Using a text editor, create Section 5.2 directory entries that use the customized schema, for each person in your directory. Optional background reading: The DEC X.500 Directory Service Management guide 6a. If your clients use web Section 2.1, Steps browsers, then obtain, install, 6-8 start, and use a web browser. 6b. If your clients use the Section 2.2, Steps 4 InfoBroker Client Version and 5 1.0A, then install and start the client. 6c. If your clients use your own Section 2.3, Steps LDAP client application, then 4-6 code, compile, link, and run your application. 2-12 Roadmaps Through This Document ___________________________________________________________ ____To_do_this..._____________________Read_this..._________ 7. Make sure that your client Web browser: understands and can display Section 5.6; the additional classes and V1.0A: Section 5.4 attributes. 8a. If using only the workgroup Section 3.4.1 directory, start the server. 8b. If using only X.500, start the Section 3.4.2 server. 8c. If using both the workgroup Section 3.4.3 directory and X.500, start the server. 7b. If your clients use the Exit, and then InfoBroker Client Version 1.0A, double click on the then stop and then restart the InfoBroker icon. client. 7c. If your clients use your own LDAP client application, then stop and then restart your client. ___________________________________________________________ Roadmaps Through This Document 2-13 2.7 Roadmap: Workgroup Directory to X.500 Migration The following is a roadmap through this book for people currently using a workgroup directory who want to migrate to an X.500-only configuration or to a configuration that uses both a workgroup directory and an X.500 directory. ___________________________________________________________ ____To_do_this..._____________________Read_this..._________ 1a. If you want the InfoBroker to Section 5.1.1 use a Digital X.500 service, then you need to invoke the configuration utility and modify the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 1b. If you want the InfoBroker to Section 5.1.2 use a non-Digital X.500 service, then you need to create the defaults file (if an X.500 system administrator has not done this on your InfoBroker server's system already). 2. Copy the X.500 directory's Section 5.3 customized .sc files to the system running the InfoBroker server, and make sure that the entries in the workgroup directory use this customized schema. Optional background reading: The DEC X.500 Directory Service Management guide 2-14 Roadmaps Through This Document ___________________________________________________________ ____To_do_this..._____________________Read_this..._________ 3. Make sure that the clients Web browsers: understand and can display Section 5.6; the additional classes and V1.0A: Section 5.4 attributes. (For the V1.0A client, exit and then reenter Windows for the changes to take effect.) 4. Stop the server. Section 3.6 5a. If using only X.500, load the Section 5.2.2 workgroup directory data into Section 3.4.2 X.500 using standard X.500 utilities like dxim, and then restart the InfoBroker server. 5b. If using both the workgroup Section 3.4.3 directory and X.500, restart the server. 6. If your client users are using Section 3.5 web browsers, start the look- up daemon, and provide the associated URL to the web- browser users. 7a. If your clients use web Section 2.1, Steps browsers, then obtain, install, 6-8 start, and use a web browser. 7b. If your clients use the Section 2.2, Steps 4 InfoBroker Client Version and 5 1.0A, then install and start the client. Roadmaps Through This Document 2-15 ___________________________________________________________ ____To_do_this..._____________________Read_this..._________ 7c. If your clients use your own Section 2.3, Steps LDAP client application, then 4-6 code, compile, link, and run your application. ___________________________________________________________ 2-16 Roadmaps Through This Document Part II _________________________________________________________________ Installation and Start Up This part contains information on installing and running the InfoBroker server and client. 3 _________________________________________________________________ Server Installation, Startup, and Termination This chapter describes the following: o Preparation for installing the InfoBroker server (Section 3.1) o The server's installation procedure (Section 3.2) o The server's postinstallation procedure (Section 3.3) o Starting the server (Section 3.4) o Stopping the server (Section 3.6) o Restarting the server after customization (Section 3.7) 3.1 Preparing to Install InfoBroker Before you install the InfoBroker server software, you need to make the preparations described in the following sections. 3.1.1 Check the Software Distribution Kit Use the Bill of Materials (BOM) to check the contents of your InfoBroker software distribution kit. If your software distribution kit is damaged or incomplete, contact your Digital representative or local authorized reseller. 3.1.2 Read the Release Notes The release notes may contain important information about changes made to the software or the installation and configuration procedures. We strongly recommend that you read them. After you install the InfoBroker server, you can find the release notes here: /usr/doc/ibx.release_notes. Server Installation, Startup, and Termination 3-1 3.1.3 System Requirements Make sure you have the following on the server's system: o A CDROM drive for the distribution media. Determine the device name for the CDROM drive. o DEC OSF/1 AXP Version 3.0 or higher. o A network transport. If your users request look-ups with the InfoBroker Client Version 1.0A or with a client that uses the Digital LDAP API functions, then the client can connect using either a DECnet or a TCP/IP network connection. If your users request look-ups with the InfoBroker HTML page or with any non-Digital, LDAP-compliant client, then you must have a TCP/IP network. If you plan on your clients using the InfoBroker HTML page, then you need to specify whether the server and look-up daemon communicate using DECnet or TCP/IP. o Installation of these subsets in the following order: 1. CXXSHRDA132 (the C++ Run-Time Library) 2. DNANETMAN300 (DECnet Network Management) 3. One of the following subsets: - DNARFC1006300 (DECnet RFC1006) installation only, if you are using only the workgroup directory. If you are not familiar with this subset, please ask your X.500 system administrator to assist you. - DNARFC1006300 (DECnet RFC1006) installation and configuration, if you want to connect to an X.500 DSA using the RFC1006 transport. If you are not familiar with this subset, please ask your X.500 system administrator to assist you. - DNABASE300, if you want to connect to an X.500 DSA using the OSI CLNS transport. 4. DXDABASE200 (X.500 Base Kit). 3-2 Server Installation, Startup, and Termination You do not need a DECnet, X.500, or C++ license to install these subsets. You must install the X.500 base kit regardless of your use of an existing X.500 directory. o 2.5 MB of disk space on the file system where you will install the server software. To check the amount of disk space you have available, use the df command. 3.1.4 Backup Digital recommends that you back up your system before starting the installation procedure for this or any other layered product. Refer to your DEC OSF/1 system documentation for information about backing up your system. 3.1.5 Register your Software License You can run the InfoBroker server if you have installed a Product Authorization Key (PAK) for any one of these products: DEC MailWorks, InfoBroker Server, or X.500. The PAK name for the InfoBroker Server is DIRECTORY-ASSISTANT. To register your license use the License Management Facility (LMF): 1. Make sure you have your PAK. 2. Log in to your system as a superuser. 3. Issue an lmfsetup command. The system returns the following prompt: # Register PAK (type q or quit to exit) [template] 4. Press . The LMF utility prompts you to answer a series of questions that correspond to the fields on your PAK form. Use the information from your PAK to reply to each question. After you answer all the questions, you should receive a completion message: PAK registered for template successfully. Server Installation, Startup, and Termination 3-3 5. Leave lmfsetup by answering quit at the register prompt, as follows: # Register PAK (type q or quit to exit) [template] quit 6. Issue an lmf reset command. 7. Issue an lmf list command to verify your registration. For more information on using LMF or obtaining licenses and PAKs, refer to the DEC OSF/1 Guide to Software License Management. You can also refer to the man pages for lmf and lmf setup. 3.2 Installation Procedure Perform the following steps to install the InfoBroker server. 3.2.1 Step 1: Log in to the root Account Log in to the root account on the OSF/1 system, as follows: login: root password: 3.2.2 Step 2: Mount the CD 1. Determine the directory containing the InfoBroker files. Refer to the Master Index table in the DEC OSF/1 Guide to Software License Management for the name of the directory on the CD that contains the InfoBroker files. The Master Index Table refers to this product as "InfoBroker." 2. Insert the disk into the drive and determine the device name for the drive. Use the following command to list available disk devices. You use either disk RRD40 or RRD42. # file /dev/rrz*c 3. Mount the disk, using your device's name and the following command: # mount -r -d /dev/device_name /mnt 3-4 Server Installation, Startup, and Termination 3.2.3 Step 3: Delete the Files from the Old Kit If you installed the previous version of the InfoBroker server, make sure that you delete the files from the old kit. Note: The Version 2.1 installation process automatically moves Version 1.0 oidtable.* files, if they exist, to the /var/ibx directory to prevent them from being deleted by mistake. If you customized your schema when using the InfoBroker Server Version 1.0 or 2.0, then you can use the information from the /var/ibx/oidtable.* files as a guide when customizing your schema for use with the InfoBroker Version 2.1. To delete the old kit, use these commands: # setld -d DAX0SERV100 DAX0SERV110 DAX0MAN100 DAX0MAN110 3.2.4 Step 4: Start the Installation Use the following setld command to run the installation procedure: # setld -l /mnt/IBX-subset_directory_name 3.2.5 Step 5: Choose the Optional Subsets The procedure asks you which installation subsets you want to install, as follows: *** Enter Subset Selections *** The subsets listed below are optional: There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. There may be more optional subsets than can be presented on a single screen. If this is the case, you can choose subsets screen by screen or all at once on the last screen. All of the choices you make will be collected for your confirmation before any subsets are installed. 1 API: InfoBroker Server (OSF/1) ) 2 InfoBroker Lookup Daemon for OSF/1 AXP version V2.1.0) 3 InfoBroker Server for OSF/1 AXP version V2.1.0 ) 4 Ref Pages: InfoBroker Server (OSF/1)) Or you may choose one of the following options: Server Installation, Startup, and Termination 3-5 5 ALL of the above ) 6 CANCEL selections and redisplay menus) 7 EXIT without installing any subsets ) Enter your choices or press RETURN to redisplay menus. Choices (for example, 1 2 4-6): You are installing the following optional subsets: [The procedure displays your choices, here...] Is this correct? (y/n): y [The procedure displays copyright information for each subset, here...] [If you install the look-up daemon, then you need to answer the following two questions. The default value of the first question is the machine on which you are running this script. The second question asks about the network transport that the server and the look-up daemon use to communicate with each other:] What is the name of your InfoBroker or other LDAP compliant server machine? [localhost]: machine_name Which transport do you want to use ? 1. TCP/IP 2. DECnet Your choice (1 or 2)? [1]: 2 Table 3-1 describes the optional subsets. Table_3-1_Optional_Subsets_________________________________ Subset___________Contents_and_Use__________________________ Server for OSF The InfoBroker server runtime, /1 AXP administration, and load tools. The server is ready to be started after the setld script is completed. (continued on next page) 3-6 Server Installation, Startup, and Termination Table_3-1_(Cont.)_Optional_Subsets_________________________ Subset___________Contents_and_Use__________________________ Look-Up Daemon The software required to detect requests from web browsers across a TCP/IP network, and the online documentation for the web- browser InfoBroker interface. LDAP API The run-time library and the .h file needed to create your own LDAP-compliant client. Ref Pages The server man pages and online _________________documentation_files_for_the_server._______ 3.2.6 Step 6: Complete the Installation After you confirm the subset selections, the system checks for adequate file system space and begins loading the files. This process takes approximately 5 to 15 minutes, depending on your hardware configuration and the subsets you selected. You can leave the installation unattended. For a list of installed files, refer to Appendix A, Files Created by Installation. 3.3 Postinstallation Procedure After completing the installation, you should verify the installation and read the release notes: /usr/doc /ibx.release_notes. Verify that the installation completed successfully by running the setld procedure with the -i option: # setld -i | grep IBX IBXOAPI210 installed API: InfoBroker Server (OSF/1) IBXLOOKUP210 installed InfoBroker Lookup Daemon for OSF/1 AXP version V2.1.0 IBXOSERV210 installed InfoBroker Server for OSF/1 AXP version V2.1.0 IBXOMAN210 installed Ref Pages: InfoBroker (OSF/1) Server Installation, Startup, and Termination 3-7 3.4 Starting the InfoBroker Server The following sections describe how to start the InfoBroker server, depending on where you want the server to search for information. After a system failure or shutdown, you do not have to restart the InfoBroker server; the system automatically restarts it upon system startup, using the same options and parameters specified the last time it was started. If you installed the look-up daemon, then you need to start the server first, then start the daemon. 3.4.1 Starting the InfoBroker Server with a Workgroup Directory To start the InfoBroker server so that it searches in a workgroup directory, enter the following command: >/usr/sbin/start_ibxd.osf name-of-workgroup-file In this example, replace name-of-workgroup-file with the file specification for your workgroup directory. 3.4.2 Starting the InfoBroker Server with X.500 Before you run the server, X.500 software must be configured and running on your system. If you have already configured X.500 software for your system, you do not have to do it again. To configure the X.500 software, enter the following command: # /var/dxd/scripts/dua_configure When the utility prompts you, enter the name of an X.500 DSA to which the InfoBroker server should connect when seeking directory information. When you have finished configuring the X.500 software, start the InfoBroker server, as follows: > /usr/sbin/start_ibxd.osf -x If your network administrator changes the underlying network protocol after you have configured the X.500 software and after you have started the InfoBroker server, you may have to run the X.500 create_templates utility. This utility enables the server to use the new transport connections to the DSA. 3-8 Server Installation, Startup, and Termination For More Information On X.500 configuration (the DEC X.500 Directory Service Problem Solving guide) 3.4.3 Starting the InfoBroker Server with both a Workgroup Directory and X.500 Before you run the server, there must be X.500 DUA software configured and running on your system. If someone has already configured X.500 DUA software for your system, you do not have to do it again. To configure the X.500 DUA, enter the following command: # /var/dxd/scripts/dua_configure When the utility prompts you, enter the name of an X.500 DSA to which the InfoBroker server should connect when seeking directory information. When you have finished configuring the X.500 software, start the InfoBroker server, as follows: > /usr/sbin/start_ibxd.osf -x name-of-workgroup-file If your network administrator changes the underlying network protocol after you have configured the X.500 software and after you have started the InfoBroker server, you may have to run the X.500 create_templates utility. This utility enables the server to use the new transport connections to the DSA. For More Information On X.500 configuration (the DEC X.500 Directory Service Problem Solving guide) 3.5 Starting the InfoBroker Look-Up Daemon To start the look-up daemon, execute the following script: > /usr/sbin/start_ibxlookupd.osf When you start the look-up daemon using the previous command, the look-up daemon uses the default port (8888). If you would like to run the daemon on another port, start the daemon using this command: > /usr/sbin/ibxlookupd -p port_number Server Installation, Startup, and Termination 3-9 After you install the look-up daemon, you need to tell your client users its network address in the form of an Universal Resource Locator (URL). In their web browsers, the users open the InfoBroker URL, which brings up the main InfoBroker HTML page in their browser windows. By default, and in most cases, the URL has the following format: http://daemon_hostname:8888/ If the machine running your look-up daemon is fido, then the URL is: http://fido:8888/. If your client users are not located within the same TCP /IP domain as the look-up daemon or if their web browsers do not support URLs composed of only a host name, then you need to provide the complete TCP/IP domain address in place of daemon_hostname. For instance, the format for an URL that contains the TCP/IP domain name is: http:/ /daemon_hostname.office_location.company.com:8888/ Also for example, the Digital Gateway directory is located at the TCP/IP domain address: gatekeeper.dec.com. (In large companies, there may be a location portion of the name in between the host name and the company name.) If you choose, you can use the look-up daemon's default configuration settings. The online Help for the InfoBroker HTML page describes to the client user the format for the names they need to enter in the Find command line, how the server looks up information, and how the look-up daemon displays the search result back to their browser window. If you edit the /etc/ibx.conf configuration file to change the default search and display characteristics of the InfoBroker HTML page, then you need to inform your client users that the HTML page will work differently than the way it is described in the online Help. If you or someone in your group has experience working with HTML files (HTML is a subset of the Standard Generic Mark-Up Language [SGML], which is a standard formatting language for documents), then you can edit the online Help file directly (/usr/lib /ibxwwwgw.help), explaining to the client users how to enter names on the Find command line and how to conduct Advanced Searches. 3-10 Server Installation, Startup, and Termination Finally, if you edit the look-up daemon's configuration file, be sure to stop and then restart the look-up daemon for the changes to take effect. For More Information On altering the look-up daemon's configuration file (Section 5.5) 3.6 Stopping the InfoBroker Server and the Look-Up Daemon To stop the InfoBroker server or the look-up daemon, execute one or both of the following scripts: > /usr/sbin/stop_ibxlookupd.osf > /usr/sbin/stop_ibxd.osf 3.7 Restarting the InfoBroker Server after Customization After you specify a customized schema to InfoBroker by altering and compiling the .sc files, you must stop and restart the InfoBroker server for the customizations to take effect. Be sure to stop any running server before starting a new server. You do not have to stop and then restart the look-up daemon; you can leave that image running. Server Installation, Startup, and Termination 3-11 4 _________________________________________________________________ Installing and Using Client Software This chapter describes the following: o Using a Web Browser to Look Up People (Section 4.1) o Installing and Using the Version 1.0A Client (Section 4.2) 4.1 Using a Web Browser to Look Up People The InfoBroker server, through the InfoBroker look-up daemon, supports look-up requests from web browsers. You can use a browser based on the NCSA Mosaic freeware, which was developed by the National Center for Supercomputing Applications at the University of Illinois at Urbana- Champaign. Or, you can use any other web browser that can communicate with World Wide Web servers. For information on obtaining web browsers, see the Obtaining a Web Browser section in the preface of this manual. Once you have a web browser, once you have a TCP/IP connection, and once you have installed the InfoBroker server and look-up daemon, you have everything you need to look up names; you do not need a World-Wide Web server or a connection to the Internet. To use the main InfoBroker HTML page to look up names, use your web browser to open the InfoBroker's Universal Resource Locator (URL). (In the File menu of most browsers, there is an Open URL menu item or icon.) An URL is a network address of a file or service which resides somewhere on your TCP/IP network. In general, the system manager who installed the InfoBroker look-up daemon should provide you with the complete, correct URL. Most InfoBroker URLs have this format: Installing and Using Client Software 4-1 http://hostname:8888/ The hostname is the name of the machine on which the look- up daemon is running. The number 8888 is the default port number for the look-up daemon process; the system manager who installed the look-up daemon should tell you if you need to specify a nondefault port number. Once you specify the URL to the browser, the main InfoBroker HTML page appears in the browser's window, and you can specify names for the InfoBroker server to look up. To look up a name, type the name in the Find command line, and then click on the Find button. (For more information on the main InfoBroker HTML page, click on the "Help" hotspot, which is located just below the Find command line and the "Advanced search" hotspot.) For more information On altering the look-up daemon's configuration file (Section 5.5) 4.2 Installing and Using the Version 1.0A Client If you choose, you can use the InfoBroker Client Version 1.0A with this version of the InfoBroker server. This section describes the following: o Prerequisites for the InfoBroker Client Version 1.0A (Section 4.2.1) o Installing and Configuring the InfoBroker Client (Section 4.2.2) o Tips for Running the InfoBroker client (Section 4.2.3) 4.2.1 Prerequisites for the InfoBroker Client Version 1.0A Make sure you have the following before installing the InfoBroker client: o Required software o Sufficient disk space and memory o Required information The following sections describe these requirements in more detail. 4-2 Installing and Using Client Software 4.2.1.1 Software The InfoBroker Client Version 1.0A runs on a PC under Microsoft Windows Version 3.1 or higher. You must have Windows installed on your PC before you install the InfoBroker client. To install and use the InfoBroker client, your PC must have a network transport installed and configured. This transport must also be running on the InfoBroker server. InfoBroker supports the following transports: o DECnet (with PATHWORKS for DOS Version 4.n and PATHWORKS Version 5.n for DOS and Windows) o Most TCP/IP implementations with a WINSOCK interface (including PATHWORKS V5.n for DOS and Windows) o Additional popular TCP/IP implementations, including PATHWORKS for DOS Version 4.n Read the release notes for more information on TCP/IP implementations tested with this product. 4.2.1.2 Disk Space and Memory The InfoBroker client software requires 2 MB of disk space on the PC. The client PC must have at least 4 MB of RAM to run Windows and the InfoBroker client. 4.2.1.3 Information You will need the following information to configure the InfoBroker client: o The transport interface you are using (WINSOCK, PATHWORKS, or other). o The machine name of the InfoBroker server host. o If you are using TCP/IP, the TCP/IP server endpoint (port number) of the InfoBroker server process running on your server. If the server uses the default port, the client should use the TCP/IP endpoint of 389. o If you are using DECnet, the DECnet task name of the InfoBroker server process running on your server. If the server uses default settings, then the DECnet task name for the server process is LDAP_SERVER. Installing and Using Client Software 4-3 4.2.2 Installing and Configuring the InfoBroker Client The InfoBroker Client Version 1.0A is shipped on a diskette, labeled "InfoBroker Client Disk 1 of 1." (The client is also shipped on the CDROM containing PATHWORKS Version 5.1.) Use the Setup utility on this diskette to both install the client on your PC and to configure it for use. 4.2.2.1 InfoBroker Client Setup To set up your InfoBroker client: 1. Start Windows. 2. Insert Disk 1 in the diskette drive on your PC. 3. Run SETUP.EXE from Disk 1. 4. Specify a directory location for the client software. The default is C:\X500C. 5. Select a transport. If you are using a transport in the "Other TCP/IP" list, refer to the release notes for more information. 6. Verify the TCP/IP port number or the DECnet task name that the client uses to access the server. The dialog box varies to match the transport you selected above. The default values are 389 and LDAP_SERVER, respectively. Note: If you are the system administrator for the InfoBroker server, inform your users if you change the default value of the TCP/IP port number or the DECnet task name on the server so that they can complete this step correctly. This installation automatically creates a Windows program group and an icon for the InfoBroker client. Refer to Appendix A, Files Created by Installation, for a list of files created by this installation procedure. 4.2.2.2 Reconfigurations If you change the network transport used by your PC, you must also reconfigure the InfoBroker client to use this new transport. To reconfigure the client, run Setup again and choose the correct transport. Reboot the PC, so that all changes take effect. 4-4 Installing and Using Client Software 4.2.3 Tips for Running the InfoBroker client The following sections provide information about matching server and client settings, and solving connection problems between the InfoBroker server and client. 4.2.3.1 Connection Problems If you have problems connecting to the server: o If you have a TCP/IP configuration, make sure the server is in the host database. o If you have a DECnet configuration, make sure the node database (decnode.dat) contains information about the server. If it does not, use NCP to define the server, as follows: C:\> NCP DEFINE NODE n.nnn NAME name MS-NET The identifier n.nnn is the node number and the identifier name is the node name. Note: If there is insufficient table space for the newly defined node, it may be necessary to reboot your PC to adjust the table size after defining the node. 4.2.3.2 Changing the TCP/IP Client Port Number The TCP/IP port number is the application port, or software "location" on the server, where the InfoBroker server process can be accessed. In accordance with the LDAP standard, Digital's InfoBroker server and client are set by default to use and access port 389. If you want to change the port number on the server (for instance, if you want to run multiple instances of the server), remember to change the port number on your clients. To change the client port number setting, you can reconfigure the software (you are asked to confirm the port number during configuration) or manually edit your Windows WIN.INI file, where the port number information is placed during configuration. To change your port number setting by editing your WIN.INI file, search for the following line in the [XTI Transports] section: Installing and Using Client Software 4-5 LDAP$SERVER=TCPIP:[389] Change the value, as follows: LDAP$SERVER=TCPIP:[your_port_number]. Exit and restart windows for this change to take effect. 4.2.3.3 Changing the DECnet Client Task Name The DECnet task name is the software process on the server that the InfoBroker client accesses. Digital's InfoBroker server and client are set by default to use and access the task name LDAP_SERVER. If you want to change the server process name on the server (for instance, to run multiple instances of the server), you must also change it on your clients. To change the client process name setting, you can reconfigure the software (you are asked to confirm the server process name during configuration) or manually edit your Windows WIN.INI file, where the process name information is placed during configuration. To change your process name setting by editing your WIN.INI file, search for the following line in the [XTI Transports] section: LDAP_SERVER=LDAP_SERVER Change the value, as follows: LDAP_SERVER=your_DECnet_task_name Note: The DECnet task name is case sensitive. Exit and restart windows, for this change to take effect. 4-6 Installing and Using Client Software 5 _________________________________________________________________ Server Configuration and Customization This chapter discusses the following: o Configuring the InfoBroker For Use with X.500 (Section 5.1) o Planning for your Workgroup Directory (Section 5.2) o Customizing Your Directory's Schema (Section 5.3) o Customizing the InfoBroker Client Version 1.0A Interface (Section 5.4) o Configuring the HTML Page and the Look-Up Daemon (Section 5.5) 5.1 Configuring the InfoBroker For Use with X.500 In order for the InfoBroker server to request information from an X.500 directory, it needs to connect to a daemon called the X.500 Directory Service Agent (DSA). The DSA can run on the same OSF/1 system on which the InfoBroker server runs, or it can run on another system on the network. To locate the DSA, the InfoBroker server must read a defaults file that specifies an X.500 DSA to which the server can connect. The defaults file is as follows: /etc /dua.defaults. If a valid, up-to-date defaults file exists on the OSF/1 system running the InfoBroker server, then you may run the InfoBroker server without performing any prerequisite tasks. If the defaults file does not exist (because you have not yet configured the X.500 software on your system), or if you need to alter an out-of-date defaults file, you need to run the X.500 configuration utility. The Digital X.500 DSA must be configured and available (running) before you run the configuration utility and before you start the InfoBroker server. Server Configuration and Customization 5-1 Note: The X.500 defaults file is a shared resource. You should consult with the administrator of the existing X.500 directory and any other DSA users before making changes to an existing X.500 defaults file. The Digital X.500 Directory Service requires either DECnet /OSI or RFC1006 network services with TCP/IP. For More Information On the requirements of Digital's X.500 product (the DEC X.500 Directory Service Management guide) 5.1.1 Configuring InfoBroker for a Digital DSA Before you run the server, X.500 software must be configured and running on your system. If you have already configured X.500 software for your system, you do not have to do it again. To configure the X.500 software, enter the following command: # /var/dxd/scripts/dua_configure When the utility prompts you, enter the name of an X.500 DSA to which the InfoBroker server should connect when seeking directory information. The utility writes the information to /etc/dua.defaults, displays a success message, and exits. If your network administrator changes the underlying network protocol after you have configured the X.500 software and after you have started the InfoBroker server, you may have to run the X.500 create_templates utility. This utility enables the server to use the new transport connections to the DSA. For More Information On X.500 configuration (DEC X.500 Directory Service Problem Solving guide) 5-2 Server Configuration and Customization 5.1.2 Configuring InfoBroker for a Non-Digital DSA For a non-Digital DSA, you must manually create your own defaults file. Also, the target X.500 DSA must be configured and available before you edit the defaults file. Use a text editor to create the file /etc/dua.defaults, and enter the following information: DUA.KnownDSAs.paddr="DSA"/"DSA"/"DSA"/RFC1006+dsanode.sales.xyz.com,rfc1006 DUA.KnownDSAs.ae_title = /c=us/o=xyz/ou=sales/cn=purpledsa DUA.DomainRoot = /c=us DUA.InitialEntry = /c=us Ask your X.500 administrator to check the following items in the default file, and make any changes to the file that are appropriate for your particular X.500 configuration: paddr This may need to be changed. See your X.500 administrator for this information. dsanode.sales.xyz.complace this with the proper node specification. "/c=us/o=xyz Replace this with the proper ae_title. /ou=sales /cn=yourdsa /c=us Replace this with the top level entry of your DIT tree. 5.2 Planning for your Workgroup Directory If you are working in a small workgroup environment, then you can create entries in the workgroup directory without significant planning and without complicating a future migration to X.500. Use the standard schema, and create distinguished names for people that include only the country, the company, the department, and the person's name, as follows: /c=US/o=your-company/ou=a-division/cn=person Even though the workgroup-directory file can contain 5,000 entries, once your workgroup directory contains more than a few thousand entries, the response time of the InfoBroker server may slow down significantly, and the workgroup- directory file may become very difficult to edit and Server Configuration and Customization 5-3 maintain. We recommend that, if you have more than 2,000 entries for your workgroup directory, then you should use X.500 instead of a workgroup directory. If your department/company is large, or if you are using the InfoBroker with an existing or new X.500 implementation, then we recommend that you take time to plan a scalable organizational hierarchy. If you take the time to plan well upfront, it will save time when your organization or company grows and you need to add to the organizational hierarchy and to the directory database. Also, prior planning and communication should prevent numerous organizations in your company from using many different customized schemas that need to be (painfully) merged into one, at some point in the future. The rest of this section provides additional detail about creating a workgroup directory using the standard schema. If you follow the advice in this section, any future migration of your workgroup-directory entries to an X.500 Directory Service will be fairly straightforward. 5.2.1 Creating Entries in Your Workgroup Directory Use the following syntax to create a directory entry: create [entry] // attributes = For example, to create subordinate entries that establish an entry for the person /c=us/o=xyz/cn="Margaret Smith" (for Margaret Smith, who works in the XYZ company, which is in the United States of America), create the following entries in your workgroup directory: create entry /c=us attributes - objectClass=(top, country), - description="United States of America" create entry /c=us/o=xyz attributes - objectClass=(top, organization), - description="XYZ Corporation" create entry /c=us/o=xyz/cn="Margaret Smith" attributes - objectClass=(Top, Person, OrganizationalPerson), - cn=("Margaret", "Margaret Smith"), - sn="Smith" 5-4 Server Configuration and Customization If your organization is located in more than one country or has multiple units, begin your workgroup directory with /o=big-xyz as the root entry. (Your organization will not have a leading countryName entry.) As another example, to create entries for the Jim Jones at a multinational organization called Big-XYZ Corporation, enter the following: create entry /o=big-xyz attributes - objectClass=(top, organization), - description="Big-XYZ Corporation" create entry /o=big-xyz/cn="Jim Jones" attributes - objectClass=(Top, Person, OrganizationalPerson), - cn=("Jim", "Jim Jones"), - sn="Jones" When you specify the syntax element of the create directive (for example, /o=big-xyz/cn="Jim Jones", in the last entry of the previous example), be aware that the attribute type you use for naming the entry might allow multiple attribute values. In this case, specify the one value that will be the entry's name as part of the argument. Specify any other values of that attribute type as part of the attribute list. For example, if an organization has two values for the organizationName attribute, one of which forms part of the distinguished name and one of which is an attribute value, then the following is a valid database entry: create entry /c=us/organizationName=xyz - attributes organizationName="XYZ Organization" Example 5-1 shows a sample workgroup-directory file. Example 5-1 Sample Workgroup Directory File (continued on next page) Server Configuration and Customization 5-5 Example 5-1 (Cont.) Sample Workgroup Directory File create entry /c=us attributes - object class=(top, country), - description="United States of America" create entry /c=us/o=xyz attributes - object class=(top, organization), - description="XYZ Corporation" create entry /c=us/o=xyz/ou=sales attributes - object class=(top, organizationalUnit), - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=xyz/ou=writing attributes - object class=(top, organizationalUnit), - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=xyz/ou=engineering attributes - object class=(top, organizationalUnit), - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=dec/ou=writing/cn="Diana Farbler" attr - object class=(top, organizationalPerson), - cn=("Diana", "Diana Sarlet", "Diana S Farbler"), - sn=("Farbler"), - telephoneNumber="508/555-1397", - title="Technical Writer", - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=dec/ou=engineering/cn="Fred Fernbuckle" attr - object class=(top, organizationalPerson), - cn=("Fred", "Frederick L"), - sn=("Fernbuckle"), - telephoneNumber="(508) 555-2996", - title="Engineering Manager", - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=dec/ou=engineering/cn="Peter Keebles" attr - object class=(top, organizationalPerson), - cn=("Peter"), - sn=("Keebles"), - telephoneNumber="508/555-5581", - title="Software Engineer", - description="110 Kent Street, Smalltown, MA USA" (continued on next page) 5-6 Server Configuration and Customization Example 5-1 (Cont.) Sample Workgroup Directory File create entry /c=us/o=dec/ou=engineering/cn="Laura Holliday" attr - object class=(top, organizationalPerson), - telephoneNumber="508/555-3499", - title="Software Engineer", - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=dec/ou=engineering/cn="Mike Pikoniat" attr - object class=(top, organizationalPerson), - cn=("Michael"), - sn=("Pikoniat"), - telephoneNumber="508/555-7433", - title="Test Engineer", - description="110 Kent Street, Smalltown, MA USA" create entry /c=us/o=dec/ou=sales/cn="Larry Augustin" attr - object class=(top, organizationalPerson), - telephoneNumber="508/555-1679", - title="Sales Director", - description="110 Kent Street, Smalltown, MA USA" You can name the workgroup-directory file any legal file name. When you start the InfoBroker, specify the name of the workgroup-directory file in the start-up command line. For More Information Complete information on the X.500 syntax and schema (the DEC X.500 Directory Service Management guide) 5.2.2 Migrating the Workgroup Directory to an X.500 Directory As long as the schema of your workgroup directory is identical to the schema of an X.500 directory to which you want to migrate, the migration process is simple. To load the workgroup directory information into an X.500 directory, make sure that X.500 is properly installed and configured, and then invoke this command: # dxim -c < workgroup-directory-name Server Configuration and Customization 5-7 5.3 Customizing Your Directory's Schema By default, the InfoBroker expects either the workgroup directory, an X.500 directory, or both to use the standard X.500 schema as defined by Digital's X.500 product. These schema rules define the following: o The object classes you can use to create entries When you customize the schema, you can create auxiliary classes, which enable you to increase the range of attributes that you can store in an entry of a standard class. You can also create structural classes, which enable you to represent objects for which no standard class is closely suitable. o The attribute types that apply to each object class o The permitted relationships between entries of different object classes You can create new attributes and auxiliary classes at any time, either before or after you create directory entries. You can make an entry a member of an auxiliary class at any time. However, you cannot change an entry's structural class once you have created the entry. You may need to customize your schema for one of the following reasons: o To meet the information needs of your InfoBroker workgroup directory users that are not met by the standard schema o To use the InfoBroker with an existing X.500 directory that uses a customized schema o To anticipate a future migration from a workgroup directory to an existing X.500 directory with a customized schema To customize a schema, you need to edit possibly more more than one .sc file in the /var/dxd directory. The dxd_ schema.sc file is the master schema file that includes other schema definitions. If you choose, you can place your schema changes in the dxd_schema.sc file, or you can have the master file include an additional file that specifies the changes. 5-8 Server Configuration and Customization Schema files are case sensitive, and schema keywords are in uppercase. The order of the class and attribute definitions in the file does not matter. If you would like to add a comment to the schema file, place two hyphens (- -) in the left margin, and the schema compiler ignores the rest of the line. Finally, we highly recommend that you keep records of the changes that you make to the schema. If your customized schema interferes with the default schema definitions in any way (for instance, some of the schema definitions are in place to facilitate the communication of Digital products such as MAILbus 400 MTA and X.500), then you need to remove your customizations or to reinstall X.500 (which reinstalls the default schema definitions) so that you can redo your customizations. Here is an example of an attribute definition: commonName ATTRIBUTE WITH ATTRIBUTE-SYNTAX stringSyntax (SIZE(1..64)) EQUALITY MATCHING RULE caseIgnoreStringMatch ORDERING MATCHING RULE caseIgnoreStringMatch SUBSTRING MATCHING RULE caseIgnoreSubstringMatch STORE NORMALIZED ::= {attributeType 3} The sections that follow describe how to customize your schema: o Assigning Object Identifiers to New Definitions (Section 5.3.1) o Adding Attribute and Class Definitions (Section 5.3.2) o Compiling Your Customized Schema (Section 5.3.3) 5.3.1 Assigning Object Identifiers to New Definitions New attribute definitions, class definitions, and name forms require object identifiers. An object identifier (OID) is a unique integer identifier that represents a structure definition rule. If you do not ensure that your organization uses unique object identifiers, there is a possibility that your definitions can clash with those of other organizations. Most companies or organizations contact a Directory Service Server Configuration and Customization 5-9 naming authority, already established in their country or region, to obtain a unique object-identifier preface. Then, organizations within the company who wish to customize the schema can use the company's assigned OID as a prefix, as follows: dec-osi-directory OBJECT-IDENTIFIER ::= { n, nn, nnn, nnnn} . . . customerSQMfacility OBJECT-IDENTIFIER ::= {dec-osi-directory 10} myorgAttributeType OBJECT-IDENTIFIER ::= {dec-osi-directory 11} . . . Once you have defined the OID, you can use the descriptive name of the OID in the schema definition, as follows: employeeNumber ATTRIBUTE WITH ATTRIBUTE-SYNTAX numericSyntax EQUALITY MATCHING RULE numericStringMatch SUBSTRING MATCHING RULE numericSubstringMatch STORE NORMALIZED ::= { myorgAttributeType 1 } The next section describes how to create new class and attribute definitions. 5.3.2 Adding Attribute and Class Definitions Once you have created OIDs for the new attributes and classes you need, you can add the definitions to the dxd_ schema.sc file. If the attributes of an existing class almost satisfy your information-storage needs, then you can define an auxiliary class, which defines additional attributes for an existing class. If no standard class comes close to meeting your needs, you can define a new structural class. To create an auxiliary class, you should determine a structural class that has some of the attributes that meet your needs, and then you need to determine which additional attributes you need to add. The following is the syntax for an auxiliary-class definition: 5-10 Server Configuration and Customization classname OBJECT CLASS SUBCLASS OF top AUXILIARY [ MUST CONTAIN { attribute [, attribute, ...]} ] [ MAY CONTAIN { attribute [, attribute, ...]} ] ::= { object-identifier n } In the previous syntax definition, classname is the name of the new auxiliary class, attribute is the name of the attribute type, and object-identifier uniquely identifies the new class. Each of the attribute identifiers must be defined in the schema. Here is an example of an auxiliary-class definition: mycompanyEmployee OBJECT-CLASS SUBCLASS OF top AUXILIARY MUST CONTAIN { employeeNumber } MAY CONTAIN { birthDate, hireDate, tmServer } ::= { mycompanyClassType 1 } The following is the syntax for a structural-class definition: classname OBJECT CLASS SUBCLASS OF superclass STRUCTURAL [ MUST CONTAIN { attribute [, attribute, ...]} ] [ MAY CONTAIN { attribute [, attribute, ...]} ] ::= { object-identifier n } In the previous syntax, classname is the name of the new structural class, superclass is the name of a defined structural class on which this one is based, attribute is the name of a defined attribute type, and object-identifier uniquely identifies the class type. Note: Defining a new structural class is the most complicated of the possible schema customizations, requiring a detailed understanding of the X.500 model of information. For ease of implementation, it is better to use an auxiliary class to extend the usefulness of a standard structural class, if possible. Server Configuration and Customization 5-11 The following is an example of a structural-class definition: dog OBJECT-CLASS SUBCLASS OF top STRUCTURAL MUST CONTAIN { commonName, breed } MAY CONTAIN { birthDate, handler } ::= { mycompanyClassType 16 } The following is the syntax description for an attribute definition: attributeName ATTRIBUTE WITH ATTRIBUTE-SYNTAX syntaxName [ constraint ] [ EQUALITY MATCHING RULE matchingRuleName ] [ ORDERING MATCHING RULE matchingRuleName ] [ SUBSTRING MATCHING RULE matchingRuleName ] [ APPROXIMATE MATCHING RULE matchingRuleName ] [ SINGLE VALUED ] STORE NORMALIZED | STORE ORIGINAL ::= { attributeType n } The following table describes the syntax elements for an attribute-name definition: attribute_name The name of the new attribute. syntaxName The name of the syntax to be used for the attribute. constraint The statement of a constraint on the size or range of a value. (For example, if a string can be no more than 10 characters, then the constraint can be (SIZE(1..10)).) 5-12 Server Configuration and Customization matchingRuleName The name of a rule, for matching like values, that is supported for the specified syntax. It can be one of the following: equality, substring, ordering, or approximate. (For example, an appropriate equality matching rule for stringSyntax is caseIgnoreStringMatch, and an appropriate substring matching rule is caseIgnoreSubstringMatch.) SINGLE VALUED An identifier that means the attribute can have only one value. STORE An identifier that means that the NORMALIZED DSA should normalize the values of STORE ORIGINAL this attribute. Normalizing involves optimizing its values so as to improve the performance of matching functions. For example, the DSA can eliminate multiple spaces between a names and use only a single space ("John Smith", normalized to "John Smith"). Specify either STORE NORMALIZED or STORE ORIGINAL. The following is an example of an attribute definition: commonName ATTRIBUTE WITH ATTRIBUTE-SYNTAX stringSyntax ( SIZE[1..64] ) EQUALITY MATCHING RULE caseIgnoreStringMatch ORDERING MATCHING RULE caseIgnoreStringMatch SUBSTRING MATCHING RULE caseIgnoreSubstringMatch APPROXIMATE MATCHING RULE initialWordApproximateMatch STORE NORMALIZED ::= { myorgAttributeType 23 } The previous sections provide you with basic customization information that most users of the workgroup directory need to know in order to implement a routine schema customization. The X.500 standard defines a broader set of rules for schema customization, and we recommend that you use these other customization rules only if you are working with an X.500 directory. Server Configuration and Customization 5-13 For More Information On schema rules and identifiers (Appendix C) On X.500 schema rules (the DEC X.500 Directory Service Management guide) 5.3.3 Compiling Your Customized Schema Once you have modified the X.500 schema files, /var/dxd /*.sc, then you need to recompile the schema using the following commands as superuser: # cd /var/dxd # /usr/sbin/dxd_sc 5.4 Customizing the InfoBroker Client Version 1.0A Interface After modifying the InfoBroker server's schema, you need to make corresponding modifications available to the systems running the InfoBroker Client Version 1.0A. On a PC running the InfoBroker client software, choose Add Attribute from the Options menu to display the Add Attribute dialog box. Type the requested information in the dialog fields, as follows: 1. The attribute name and default user label. 2. The oidvalue associated with the attribute type. In the Object Identifier field, type the oidvalue in its numeric format. For example, enter 0.9.2342. 3. The attribute type. For example, enter myorgAttributeType or customerSQMFacility. Use the Add button to add the attribute. This saves the new attribute type to the X500C.INI file on the InfoBroker client system. (X500C.INI will be located in the directory where you installed Microsoft Windows.) After making modifications to the InfoBroker client configuration files, you should modify the InfoBroker client search screens as well. You can make these modifications on the client systems using the CREATE /EDIT Display screens. Modifications to the display made through the CREATE/EDIT DISPLAY menu are also written to the X500C.INI file. 5-14 Server Configuration and Customization After modification, distribute the resulting X500C.INI file with the client software. Exit and then reenter Windows for the changes to take effect. For More Information On customizing the InfoBroker HTML page (Section 5.5.1 and Section 5.5.2) 5.5 Configuring the HTML Page and the Look-Up Daemon The InfoBroker look-up daemon uses a global configuration file to control searches and to control the format of information displayed to the client user. When you install the InfoBroker look-up daemon, the installation script creates this global configuration file: /etc/ibx.conf. A configuration file controls the default search and display characteristics of all the web browsers that use that daemon. The configuration file controls the following: o The way that the InfoBroker interprets the names entered by the client users; and the way it searches for matching directory entries, which is done through the use of search filters (Section 5.5.1). o The types of directory-entry information that can be displayed on the HTML page after a search is complete, and the types of attributes that the client users are allowed to modify in an X.500 directory service (Section 5.5.2). o The web browser's file and header specifications (Section 5.5.3). o Other directory-service information, including specification of the search base (Section 5.5.4). The configuration file is not case sensitive. If you alter the default values, you can use any combination of lowercase and uppercase letters. However, we recommend that you enter all attribute names in their correct case. Server Configuration and Customization 5-15 The following sections provide more detail on altering the configuration file. For additional information, the configuration file itself contains detailed comments in each of its sections. The configuration file refers to its line items as "resources." 5.5.1 Specifying Search Filters By default, a client user can enter one or two names in the Find command line. The look-up daemon takes the name or names and incorporates them into a search filter string, which tells the server how to compare the names to directory-entry attribute values. (We will describe the structure of the default filters in more detail later in this section.) Here is the format for a search filter: searchFilter = number: (operator (expression) (expression)) You can add spaces in between identifiers and operators, but you cannot add carriage returns; the filter definition must be on a single line of the configuration file. The number field is a unique integer. The numbers for search filters must be contiguous. For instance, you cannot define only these three search filters: SearchFilter = 1, SearchFilter= 62, and SearchFilter = 12. You must define these three search filters: SearchFilter = 1, SearchFilter = 2, and SearchFilter = 3. The operator field is one of the following logical operators: ___________________________________________________________ OperatoName________Description_____________________________ | OR True, if either expression is True. & AND True, if both expressions are True. !______NOT_________True,_if_the_expression_is_not_True.____ Here is the format for the expression in the previous format description: attribute_name operator2 "%num_entered_string" 5-16 Server Configuration and Customization The attribute_name field is an attribute name defined in the schema, and the num_entered_string field is the number of the entered name. For example, "%1" is a name parameter that the look-up daemon replaces with the first name entered by the user. The operator2 item can be one of the following operators: ___________________________________________________________ operator2me________Description_____________________________ = Equals If the attribute's value exactly matches the entered name, then the expression returns TRUE. ~= Approximate If the attribute's value approximately matches the entered string, then the expression returns TRUE. =* Present The existence of the attribute name in the directory entry returns True. For example, (surname=*) evaluates to True for every directory entry that has a surname attribute name, regardless of ___________________the_attribute's_value.__________________ Here are the two default search filters defined in the configuration file. This example places carriage returns within the filter definitions so that they are easier to read and to understand. When you work with search filters in the configuration file, remember to keep the whole filter on one line. For example: searchFilter = 1: ( | ( surname="%1" ) ( surname="%1*" )) searchFilter = 2: ( | ( & ( | ( givenName="%1" ) ( givenName="%1*" )) ( | ( surname="%2" ) ( surname="%2*" ))) ( cn="%1 %2" )) When the client user enters only one name on the Find command line, the look-up daemon and the server use the first default search filter. For example, consider this string entered by the client user: Find: Smith Server Configuration and Customization 5-17 The look-up daemon replaces the characters %1 in the first search filter with the string "Smith". The search returns all directory entries whose surname attribute values match "Smith"*, where the asterisk (*) is a wildcard character. For instance, the server returns both of these names: "Smith" and "Smithfield". When the client user enters two names on the Find command line, the look-up daemon and the server use the second default search filter. For example, consider this string entered by the client user: Find: Jo Smith The look-up daemon replaces the characters %1 in the second search filter with the string "Jo" and the characters %2 with the string "Smith". The search returns all directory entries whose givenName attribute values match "Jo"* and whose surname values match "Smith"*. For instance, the server returns these names: "Jo Smith", "Jo Smithfield", "Joe Smith", and "Joe Smithfield". By default, if the server fails to find an exact match between any of the entry's attribute values and the entered names, then the look-up daemon automatically initiates another search for all attribute values that approximately match the entered strings. (In other words, if the first search does not produce a match, then the look-up daemon replaces each instance of the Equals operator in your filters with an Approximate operator and runs a second search.) You can define additional search filters that conduct searches on various attribute values. There is no limit on the number of user-defined search filters. However, since the main InfoBroker HTML page provides access to an Advanced Search Page for complex look-ups, we recommend that you keep the number of search filters to minimum, and that your users go to the Advanced Search Page to look-up attribute values other than a surname or a givenName. As a restriction, you can define only one search filter for a given number of search parameters. (For instance, you can define only one filter that contains only the "%1" parameter, you can define only one filter that contains only the "%1" and "%2" parameters, and so forth.) 5-18 Server Configuration and Customization If the client user enters more names than the number of name parameters in any defined search filter, then the look-up daemon uses the filter with the most parameters and assumes that all of the extra substrings are parts of the last parameter defined by the search filter. For example, consider this string entered by the client user: Find: Jim Van Der Waal Given the default search filters, the look-up daemon replaces the characters %1 with the string "Jim" and the characters %2 with the string "Van Der Waal". The server assumes that the strings "Der" and "Waal" are parts of the string ("Van") that corresponds to the last replacement parameter (%2) in searchFilter 2. The server returns all directory entries whose givenName value matches "Jim"* and whose surname value matches "Van Der Waal"*. 5.5.2 Searching for and Modifying Attributes The second section of the configuration file is a table that controls the following: o Which attributes the InfoBroker page displays upon completion of a search. o Whether a client user can perform an Advanced Search based on a certain attribute name (on the InfoBroker's main HTML page, there is an "Advanced search" hotspot just below the Find command line). o Whether a user can modify an attribute in an X.500 Directory Service. o How the main HTML page labels the attribute when it is displayed to the user upon completion of a search. The contents of this table must correspond to the attribute-name definitions in the schema. Each table row has this format: attribute = att_name: search: display_brief: modify: label The att_name field is an attribute name in a directory entry, which is defined in the schema. Server Configuration and Customization 5-19 The search item is a true or false value that indicates whether the user can conduct an Advanced Search based on this attribute. If this field has a true value, then, when the client user clicks on the Advanced Search hotspot, the resulting HTML page provides a form line; the form line's title is the label, and the client user can specify an attribute value for which the server can search. The display_brief field has the same true/false format as the previous field, and it indicates whether the HTML page displays this attribute in the default display (also called the "brief display") shown to the user at the completion of the look-up. The modify field indicates whether a user can modify an attribute. Note: A web-browser user can only modify attribute values in an X.500 directory; she or he cannot modify entry attributes in a workgroup directory. The modify field can accept one of the following values: ___________________________________________________________ Values_Value_Name_____Definition___________________________ F False The user cannot modify this attribute. MV, MultipleValues These attributes can have zero or or more values. T MR MultipleRequireThe attribute can have one or more values. SV SingleValue The attribute can have zero or one value. SR_____SingleRequired_The_attribute_must_have_one_value.___ The label field provides a title used when the web page displays the attribute value upon completion of the look- up. Here is an example of a few rows in the default configuration file's attribute table: attribute = commonName: T: T: F: Common Name attribute = Title: T: F: SV: Title 5-20 Server Configuration and Customization The user can search for a commonName attribute value, the attribute is part of the default display, users cannot modify this attribute, and the label in the display is "Common Name". The user can search for a Title attribute value, the attribute is not part of the default display, users can modify this attribute and can specify no value or one value, and the label in the display is "Title". 5.5.3 Changing the Default Header and File Specifications The web browser looks for certain files and certain header images in default directories and file names. These files and header images construct the user interface. The configuration file contains the following lines: wwwHeader =
wwwFootnote =

(c)1995 Digital Equipment Corporation preFix = The wwwHeader line designates the art file (head.gif) that the web browser places at the top of the page. The wwwFooter line designates a tag line and another art file that the browser places at the bottom of the page. The preFix line indicates the text string that the browser uses in error messages and in the online Help hyperlink hotspot. For example, if there is a string associated with preFix (for example, "preFix = Look-Up Service"), then the online Help hotspot is "Help on Look-Up Service"). By default, preFix is undefined, and the Help hotspot is "Help." 5.5.4 The Search Base and Other Directory Service Information The configuration file contains information that the look- up daemon can pass to the InfoBroker server in regard to accessing directory entries. The default configuration file contains the following information: Server Configuration and Customization 5-21 searchBase = o=organization_name objectClass = objectClass=organizationalPerson portNumber = 389 transport = TCPIP searchTimeout = 30 maxFetchEntries = 150 The following table explains these lines: ___________________________________________________________ Leading Identifier_______Description_______________________________ searchBase This line indicates at which entry in the directory tree to begin the search. If the InfoBroker needs to search through a very large X.500 database, you should probably limit the scope of the search to entries within your own company or your own organization. By default, this line is commented out, and the search will start at the root of your directory tree. objectClass This line specifies for which type of entry the InfoBroker searches (people). portNumber This line specifies the port number of the InfoBroker server. If the look-up daemon and the server are on different machines and if they communicate using a TCP/IP connection, then the portNumber is the TCP/IP port number; if the look-up daemon and the server communicate using a DECnet connection, then the portNumber is the identifier LDAP_SERVER. transport This line specifies the transport that the look-up daemon uses to communicate with the server. searchTimeout This line specifies the number of seconds after which, if the server has not completed the search, it abandons the request. 5-22 Server Configuration and Customization ___________________________________________________________ Leading Identifier_______Description_______________________________ maxFetchEntries This line specifies the maximum number of entries that the server can fetch for a _________________single_search.____________________________ 5.6 What's Cool: the InfoBroker and a World Wide Web Server If you use your web browser with a World Wide Web server, then you can configure the InfoBroker to take advantage of the easy access provided by hyperlink hotspots. For example, you can store a hyperlink hotspot as a special attribute value in a directory entry (in either the workgroup directory or an X.500 Directory Service); you can also place an InfoBroker hyperlink hotspot into an HTML document. We will look at both of these features from the client user's perspective. First, when looking up a person's name with the InfoBroker, the client user normally sees the person's name, a telephone number, an office number, a Mail address, and maybe a picture of the person. Similarly, in environments that use the World Wide Web, it is getting increasingly common for people to write and update their own look-up information, to place it in what is sometimes called a Personal HTML page, and to make it available for other World Wide Web users to look up (by telling people the URL of the Personal Page). If people are using web browsers and the InfoBroker to look up names, it would be helpful if the search results provide hyperlink hotspots to that person's Personal Page. Then, in the displayed search result, the client user click on the URL to see that person's Personal Page. To provide URL hyperlink hotspots in the InfoBroker search results, you need to define an attribute in your directory's schema. The attribute's name must be "URL", and the attribute's type must be a string-based type. Then, when you create or modify directory entries, you can place the URL string for an individual's Personal Page into the Server Configuration and Customization 5-23 directory entry. Before displaying the URL in the search- display page with the rest of the information, the look-up daemon adds the HTML code necessary to display the URL as a hyperlink hotspot. The URL does not have to point to an individual's Personal Page; it can be any valid URL. However, the attribute name must be "URL", and it must be a string-valued attribute type. As long as you meet those two criteria, you can use the InfoBroker to store and display URLs that point to anything in the World Wide Web. Since directory entries can point into the World Wide Web, it makes sense that documents on the World Wide Web can point into the InfoBroker. For example, imagine an HTML marketing plan, organizational chart, or a memo that contains a hyperlink hotspot labeled "Telephone Number /Mail Address", with an associated URL that invokes the InfoBroker and displays that person's directory entry in a search result. So, when reading that HTML plan or memo or organizational chart, a person can click on a hyperlink hotspot to view that person's directory information. To look up a person by clicking on a hyperlink hotspot, you first need to obtain the URL associated with displaying that person's directory entry. To do this, enter the person's name in the Find command line on the InfoBroker's main page, and then click on the Find button. When the look-up daemon displays the person's directory entry, the browser displays the associated URL in either a section of the browser or in the browser's History list. In most cases, you can use the window interface to cut the URL from the browser's window and paste it into an editor. If that does not work or is not possible, sometimes you can use the Export feature within a History list to write the URL code to a file. Finally, if all else fails, write the URL down on a piece of paper. Given the default search filters, the URL for displaying a directory entry often looks like this: http://host-or-domain:8888/S?F=joe+smith To test the URL, use the browser's menu items or icons to open that URL and see if it displays the correct person's directory entry. 5-24 Server Configuration and Customization Once you have the correct URL, you can place it into HTML hyperlink code that looks like this: Joe Smith's Telephone Number and Mail Address Within the displayed HTML document, when the user clicks on the hyperlink hotspot "Joe Smith's Telephone Number and Mail Address", the browser displays Joe Smith's directory entry in the browser window. Server Configuration and Customization 5-25 Part III _________________________________________________________________ Using the LDAP API This part provides pointers on how to develop LDAP- compliant client code on various operating-system platforms. 6 _________________________________________________________________ Developing Client Applications with the LDAP API This chapter describes the following: o Introducing the LDAP API (Section 6.1) o Programming Environment Information (Section 6.2) o Information About Name Service Directories (Section 6.3) o Client Development Process (Section 6.4) o Sample LDAP Client Application (Section 6.5) Note: This chapter and the reference section that follows it describe the LDAP API shipped by Digital Equipment Corporation. The description in this chapter may not completely match the behavior of LDAP APIs shipped by other institutions and corporations. 6.1 Introducing the LDAP API The Lightweight Directory Access Protocol (LDAP) application programming interface (API) enables communication between a client and server that are working with an X.500-based directory service. The Internet X.500 task force developed LDAP to allow applications access to X.500 without the larger overhead incurred with using the X.500 Directory Access Protocol. LDAP is particularly useful for personal-computer clients that cannot afford the overhead of a larger API. The InfoBroker server is an LDAP-compliant server that can receive requests from clients that use LDAP. For example, the InfoBroker Client Version 1.0A is written using LDAP functions. Since an LDAP-compliant client can ask the InfoBroker server to search through a workgroup directory, this LDAP documentation refers to "directory trees" and "directory entries," which can exist either in an X.500 directory service or in a workgroup directory. Developing Client Applications with the LDAP API 6-1 Digital supports the LDAP API for use on the OSF/1 operating system, Version 3.0 or higher. Therefore, you can create your own client that can request look-ups from the InfoBroker server. Also, since LDAP is a standard protocol (RFC 1487), your LDAP-compliant client can communicate with LDAP-compliant servers other than the InfoBroker server. 6.2 Programming Environment Information This section describes the following: o Platform and Linking Information (Section 6.2.2) o Programming Language Information (Section 6.2.1) 6.2.1 Programming Language Information Since the LDAP API functions are written in C, it is easiest to write your client in C or C++. Digital provides the header file libldap.h that you must include in your code in order to call the LDAP routines. In addition, some of the LDAP functions create data structures, described later in this section, whose memory you need to free after using the data structures. (The function descriptions in Part IV specify whether you need to free memory as a result of calling the function.) It is easiest to free this type of memory using C library functions. If you are programming in a language other than C or C++, use the C calling conventions, translate the .h file to an include file supported in your language, and be sure that your language supports some method of freeing the memory used to store LDAP data structures. When writing your code, you will need to declare some of your variables using data types defined in the libldap.h file. In most cases, you need only to define the variable and then pass it as a parameter. However, it is helpful to know the purpose of these data types. Here are the types defined in libldap.h that you will use most often: 6-2 Developing Client Applications with the LDAP API ___________________________________________________________ Data_Type__Description_____________________________________ LDAP_t An LDAP handle Variables of this data type contain an encapsulated context for the LDAP session, which includes information about the client and server systems, the network transport, the network endpoints, and so forth. LDAPM_t A directory entry Variables of this data type contain information about a single entry in the directory tree and information required to access the information. A variable of this type includes information such as the distinguished name of the entry, its attribute names, and so forth. For instance, when you call one of the search functions, it often returns a pointer to a chain of structures of this type. Other function parameters and return values are of this data type. LDAPBE_t An attribute value Variables of this data type contain an attribute value and information needed to access it. Most often, an LDAP function will return or require an array of pointers to attribute values; the array of pointers ends with a NULL address. Developing Client Applications with the LDAP API 6-3 ___________________________________________________________ Data_Type__Description_____________________________________ LDAPMod Information used to modify or create a directory entry Variables of this data type contain information used to modify an entry in the directory tree. This is the only data type that you need to initialize in your code before passing it to one of the LDAP functions. Most often, you need to create a linked list, each link of which is a structure of this data type. The information included in the structure includes a specification about how you want to modify the directory entry (add, delete, replace), information about the attribute value that you are altering, and a pointer to the next structure (or a NULL address to end the linked ___________list).__________________________________________ For More Information On modifying directory entries (Section 6.4.4) 6.2.2 Platform and Linking Information The LDAP API runs on only one platform: OSF/1 Version 3.0 or higher. After you have finished coding your application in C, you can compile and link your application using the following command: > cc -o my_app my_app.c -ldax The -ldax option links your code with the LDAP libraries, which are located in these directories: /usr/shlib /libdax.so and /usr/lib/libdax.a. 6.3 Information About Name Service Directories This section contains information about working with different types of name-service directories. The InfoBroker server supports two name-service directories: the X.500 Directory Service, and the workgroup directory. 6-4 Developing Client Applications with the LDAP API This section contains the following information: o Restrictions on Modifying and Creating Entries (Section 6.3.1) o Specifying Relative Distinguished Names (Section 6.3.2) 6.3.1 Restrictions on Modifying and Creating Entries If you create a client that works with the InfoBroker server, then your client can request that the InfoBroker server create or modify directory entries in an X.500 Directory Service. However, your client cannot request that the InfoBroker server create or modify entries in a workgroup directory. If you attempt to modify or create entries in a workgroup directory, the function call returns the LDAP_UNWILLING_TO_PERFORM error. This restriction affects the following LDAP functions: ldapAddW, ldapDeleteDNW, ldapModifyW, and ldapModrdnW. If you want to create or modify entries in a workgroup directory, you need to edit the workgroup-directory file using a text editor; then, stop and restart the server for the changes to take effect. 6.3.2 Specifying Relative Distinguished Names Some functions in the LDAP API require that you pass a string containing a distinguished name or a relative distinguished name. Within the string, this API requires that you specify the name in a format that differs from the format used in the rest of this manual, an example of which looks like this: /c=US/o="Abacus Company"/ou=Sales/cn="Joan Smith". The LDAP format for distinguished names requires that you enclose the names in parentheses, that you first specify the relative distinguished name of the directory entry that you want to affect, that you separate the relative distinguished names with commas, and that you end the string with the root entry. The following is a distinguished name that is LDAP compliant: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) Developing Client Applications with the LDAP API 6-5 6.4 Client Development Process This section contains information on the order in which you need to call LDAP functions to accomplish common tasks. All LDAP client applications perform these tasks, in order: 1. Call ldapOpen. This call initializes the LDAP handle and establishes a connection between the LDAP client and server. 2. Call ldapBind. This call establishes a context between the LDAP client and server, which includes optionally specifying information such as account usernames; X.500 passwords; and X.500 authentication (security), if the client user needs privileges to access information stored in the directory. 3. Perform searching or modification tasks. 4. Call ldapUnbind. This call disassociates a client from a server, disconnects the client and server, and releases resources (for example, memory) that were allocated to establish the connection and association. If a call to this function fails, call the ldapDelete function, which performs cleanup operations. In general, your client can either ask a server to search through a directory tree or to make some kind of modification (modify, add, delete) to a entry in the tree. When you ask a server to perform a search for you, you can invoke one of two types of searches: synchronous or asynchronous. A synchronous search stops execution of your client code until the search terminates. An asynchronous search places the request with the server, and then returns control to your client code, allowing you to perform additional tasks; when the search is complete, your client code can retrieve the results of the search. When you invoke an asynchronous search using one handle (which corresponds to one connection between a particular client and server), do not invoke a second asynchronous search request using that same handle until the first request terminates. Otherwise, you cannot determine which 6-6 Developing Client Applications with the LDAP API call returns values first. However, your client code can make simultaneous asynchronous calls using different handles, involving different client/server pairings. The remaining subsections describe the following: o Synchronous Searches (Section 6.4.1) o Asynchronous Searches (Section 6.4.2) o Directory Entry Modification (Section 6.4.4) 6.4.1 Synchronous Searches To perform a synchronous search, perform the following additional tasks: 1. Call ldapSearchW or ldapSearchWLim. These functions provide a pointer to a chain of directory entries (each entry is of the data type LDAPM_ t) that meet the search criteria. The ldapSearchWLim function is identical to the ldapSearchW function, except that it places a time limit and a size limit on the search. Note that all functions that perform their tasks synchronously end with the letter "W." 2. Call ldapFirstEntry, which sets a pointer to the first directory entry in the chain. 3. Create a loop to read all of the entries in the chain, as follows: 1. Call ldapFirstAttribute, which returns a pointer to a string that contains the data type of the first attribute. If the entry has no attributes, a call to this function returns a NULL address. 2. Create a loop to read all of the attribute values, as follows: 1. Call the ldapGetValues function to create the array of pointers whose pointers point to the attribute values. This array of pointers ends with a NULL address. 2. Create a loop that reads all of the attribute values. Developing Client Applications with the LDAP API 6-7 3. Call the ldapValueFree function to free the memory used to store the array of pointers and the attribute-value strings. 4. Call ldapNextAttribute to obtain a pointer to a string containing the data type of the directory entry's next attribute. If the function returns NULL, then the directory entry has no more attributes. 3. Call ldapNextEntry, which sets a pointer to the next directory entry in the chain. This function returns NULL, if there are no more directory entries in the chain. 4. Call ldapMsgFree to free the memory used to store the chain of directory entries. 6.4.2 Asynchronous Searches When you perform asynchronous searches, you loop through the entries and attribute values in the same manner as with synchronous searches. However, you way you initiate and terminate the search is different. Initiate and terminate an asynchronous search as follows: 1. Call either ldapSearchReqst or ldapSearchReqstLim to initiate the asynchronous search. The ldapSearchReqstLim function is identical to the ldapSearchReqst function, except that it places a time limit and a size limit on the search. 2. Call the ldapPoll function periodically to see if the asynchronous call completed. This function returns a TRUE value if the call to the search function is complete, and a FALSE value if the call has not completed. To terminate the asynchronous search for any reason, call the ldapAbandon function. 3. When the search is complete, call the ldapSearchResult function to obtain the chain of directory entries that met the criteria of the search. 4. Use the same functions as the synchronous search to access the entries and attribute values and to free system resources. 6-8 Developing Client Applications with the LDAP API 6.4.3 Reading Binary Attribute Values When you call either the ldapFirstAttribute or the ldapNextAttribute functions and if either of these functions return a binary data type, you need to take extra steps to read the binary values. The attribute name determines if an attribute value is binary. For instance, a jpegPhoto attribute is binary by definition. If the attribute name is a binary type, then do the following: 1. After the call to either ldapFirstAttribute or ldapNextAttribute, you then call the ldapGetValuesLen function. This function returns a vector whose pointers point to structures of the type LDAPBerval. Each structure contains two members, the first being the length in bytes of the binary data and the second being a pointer to the binary data itself. 2. Loop through the vector until you encounter a NULL pointer. 3. Call the ldapValueFree to free the memory used to contain the vector, its data structures, and the binary data. 6.4.4 Directory Entry Modification You can modify directory entries in an X.500 Directory Service, but you cannot modify entries in a workgroup directory. If you want to modify a directory entry in an X.500 Directory Service by modifying an attribute, deleting an attribute, or adding an attribute, create a linked list, and pass a pointer to the list as a parameter to either the ldapModifyW or the ldapAddW function. The structures in the linked list are of type LDAPMod, which has four members, as follows: o A constant that specifies the presence of binary data and what type of modification you want to perform, as follows: LDAP_MOD_ADD Add an attribute value to the entry. Developing Client Applications with the LDAP API 6-9 LDAP_MOD_DELETE Delete an attribute value from the entry. LDAP_MOD_REPLACE Replace an existing attribute value in the entry with another attribute value. LDAP_MOD_BVALUES The attribute value in the entry is binary data. If you are passing binary data, you can perform a logical OR operation (|) on the binary-data constant (LDAP_MOD_BVALUES) and on one other constant for the first member of the structure. o The name of the attribute you want to modify. o A pointer to the data structure, of type LDAPBerval, containing the length of the binary data and a pointer to the data. o Either a pointer to the next ldapMod structure in the linked list, or NULL, which signifies the end of the linked list. Figure 6-1 shows an example of a linked list of modification data. The numbers in the figure correspond to the numbers in the list that follows the figure. Figure 6-1 Entry Modification Data Structures 1 This structure specifies that X.500 should add the names "Fred" and "Frederick" to the current commonName 6-10 Developing Client Applications with the LDAP API attribute values of the directory entry. The last member of this structure points to the next structure. 2 This structure specifies that X.500 should delete the name "Smith" from the current surname attribute value of the directory entry. 3 This structure specifies that X.500 should add two binary values to the current jpegPhoto attribute value of the directory entry. The last member of this structure is NULL, which designates the end of the linked list. 4 This is an array of pointers that determines how many pieces of binary data exist; keep reading pointers until you read NULL. Each pointer in this array points to a structure that specifies the length of the binary data, in bytes, and a pointer to the actual binary data (in this example, photographs). For more information on the data types used to construct this linked list, see the libldap.h file. 6.5 Sample LDAP Client Application Example 6-1 shows a sample LDAP application; it tests whether a filter and a single-entry base return only the base directory entry. The numbers in the example correspond to the numbers in the list that follows the example. Example 6-1 Sample LDAP Application (continued on next page) Developing Client Applications with the LDAP API 6-11 Example 6-1 (Cont.) Sample LDAP Application /* **++ ** ** MODULE: ** ** ldap_search ** ** ABSTRACT: ** ** Test that a search with a scope of baseobject will return only the ** baseobject (assuming the filter matches!). ** **-- **/ /*---------------------------------------------------* * Include Files * *---------------------------------------------------*/ #include #include #include 1 #include "libldap.h" /*---------------------------------------------------* * Defines * *---------------------------------------------------*/ #define TRUE 1 #define FALSE 0 /* Search parameters */ #define FILTER "sn=smith" #define BASE "c=us" /* Bind parameters */ #define NODENAME "fido" 2 #define NAME "cn=Marshal Crenshaw,ou=Manufacturing,o=Acme,c=us" #define PASSWORD "x500x500" /* Expected result */ #define EXPECTED_DN "cn=Edgar Smith, ou=Manufacturing, o=Acme, c=us" (continued on next page) 6-12 Developing Client Applications with the LDAP API Example 6-1 (Cont.) Sample LDAP Application /*---------------------------------------------------* * Caseless compare routine * * * * Returns true if strings are equal and false * * otherwise. Case is ignored. * *---------------------------------------------------*/ int CaseComp(char *str1, char *str2) { int i = 0; while ((str1[i] != '\0') && (str2[i] != '\0')) { if (toupper(str1[i]) != toupper(str2[i])) { break; } i++; } return((str1[i] == '\0') && (str2[i] == '\0')); } /*---------------------------------------------------* * Main Routine * *---------------------------------------------------*/ main(int argc, char **argv) { int ret; /* Return status */ char *attrs[10]; /* Attribute list */ char *dn; /* Dn string returned */ LDAP_t *ldap_handle; /* LDAP Handle */ LDAPM_t *res_chain; /* Result chain */ LDAPM_t *ret_mess; /* Message from result chain */ /*---------------------------------------------------* * Initialise the LDAP handle. * *---------------------------------------------------*/ ret = ldapOpen(&ldap_handle, LDAP_TCPIP, NODENAME, LDAP_TCPIP_SERVER); (continued on next page) Developing Client Applications with the LDAP API 6-13 Example 6-1 (Cont.) Sample LDAP Application /* * Test the return status from ldapOpen */ if (ret != LDAP_SUCCESS) { printf("ldapOpen Failed\n"); return (0); } /*---------------------------------------------------* * Bind to the Ldap Server. * *---------------------------------------------------*/ ret = ldapBind(ldap_handle, NAME, PASSWORD, LDAP_AUTH_SIMPLE); if (ret != LDAP_SUCCESS) { printf("ldapBind Failed\n"); return (0); } /*---------------------------------------------------* * Perform a search such that only one entry should * * be returned. * *---------------------------------------------------*/ attrs[0] = "cn"; attrs[1] = NULL; ret = ldapSearchWLim(ldap_handle, /* LDAP handle */ BASE, /* Base */ LDAP_SCOPE_SUBTREE, /* Scope */ FILTER, /* Filter */ attrs, /* List of attrs */ FALSE, /* Attr values not returned */ 0, /* Size Limit */ 0, /* Time Limit */ &res_chain); /* Result chain */ if (ret != LDAP_SUCCESS) { printf("Call to ldapSearchW has failed"); return (0); } (continued on next page) 6-14 Developing Client Applications with the LDAP API Example 6-1 (Cont.) Sample LDAP Application /*---------------------------------------------------* * Check that only one entry was returned. * *---------------------------------------------------*/ ret = ldapCountEntries(ldap_handle, res_chain); if (ret < 0 ) { /* An error has resulted from the ldapCountEntries function */ printf("An error was returned from ldapCountEntries"); return (0); } else if (ret != 1) { /* Wrong number of entries returned */ printf("Wrong number of entries have been returned"); return (0); } /*---------------------------------------------------* * Check that the correct entry has been returned. * *---------------------------------------------------*/ /* Acquire the first entry from the returned message chain */ ret_mess = ldapFirstEntry(ldap_handle, res_chain); if (ret == NULL) { /* This should never happen */ printf("ldapFirstEntry has returned NULL"); return (0); } /* Get the DN of the entry found */ dn = ldapGetDN(ldap_handle, ret_mess); if (dn == NULL) { free(dn); printf("ldapGetEntry has returned NULL"); return (0); } (continued on next page) Developing Client Applications with the LDAP API 6-15 Example 6-1 (Cont.) Sample LDAP Application /* Check that the DN matches what was expected */ if (!CaseComp(dn, EXPECTED_DN)) { free(dn); printf("ldapGetEntry has returned an unexpected DN"); return (0); } free(dn); /*---------------------------------------------------* * Unbind from the server * *---------------------------------------------------*/ ret = ldapUnBind(ldap_handle); if (ret != LDAP_SUCCESS) { printf("Call to ldapUnBind has failed"); return (0); } /*---------------------------------------------------* * Test must have succeeded, report a successful * * completion. * *---------------------------------------------------*/ printf("Expected entry returned\n"); return (1); } 1 Be sure to include the libldap.h include file. 2 This is the username and the password that the program uses to bind to the X.500 DSA. 6-16 Developing Client Applications with the LDAP API Part IV _________________________________________________________________ LDAP API Reference This part contains a description of each LDAP routine. ldapAbandon _________________________________________________________________ ldapAbandon Abandons an asynchronous search request. Synopsis #include int ldapAbandon( LDAP_t *ldap_handle ); Parameters ldap_handle (input) The address of an LDAP handle. Description The ldapAbandon function abandons an asynchronous search initiated by either the ldapSearchReqst or the ldapSearchReqstLim function. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapPoll, ldapSearchReqst, ldapSearchReqstLim LDAP-3 ldapAddW _________________________________________________________________ ldapAddW Adds an entry to a directory tree. Synopsis #include int ldapAddW( LDAP_t *ldap_handle , char *distinguished_name , LDAPMod *modifications_list ); Parameters ldap_handle (input) The address of an LDAP handle. distinguished_name (input) The distinguished name of the entry that you want to add to the directory tree. The following is an example of an LDAP-compliant distinguished name: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) modifications_list (input) Address of the first structure in a NULL-terminated linked list of structures. The structure's first member is often NULL. Since the purpose of this function is to add an entry and its new attributes, it automatically assumes the value LDAP_MOD_ADD as the value of the first member. If the value of the new entry's attribute is binary, then specify LDAP_ MOD_BVALUES instead of NULL. The structure's second member provides the name of the new entry's attribute, and its last member provides a pointer to a NULL-terminated list of pointers; the pointers in the list point to the new entry's attribute values. (For more information on constructing this linked list, see Section 6.4.4.) LDAP-4 ldapAddW Description The ldapAddW function performs its task synchronously. This function works only with an X.500 Directory Service; you cannot use this function to add entries to the InfoBroker workgroup directory. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapDeleteDNW, ldapModifyW LDAP-5 ldapBind _________________________________________________________________ ldapBind Creates an association between an LDAP client application and an LDAP-compliant server, and optionally provides identification information about the user requesting the look-up. Synopsis #include int ldapBind( LDAP_t *ldap_handle , char *distinguished_name , char *password , int auth_level ); Parameters ldap_handle (input) The address of an LDAP handle. distinguished_name (input) The address of a buffer containing the distinguished name of a user who is requesting the look up, or a NULL address, if you want the client to bind with the server using a default user name. The following is an example of an LDAP- compliant distinguished name: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) password (input) The address of a buffer containing the X.500 password for the distinguished_name user, or NULL if you want to bind using a default password or if you want to bind allowing access only to world readable directory entries. auth_level (input) The X.500 authentication level for the user's access. (You must specify the LDAP_AUTH_SIMPLE constant. For more information on unsupported constants that represent authorization levels, see the libldap.h file.) LDAP-6 ldapBind Description Call the ldapBind function after you have initialized the LDAP handle with a call to the ldapOpen function. If the user issues look-up commands that require a check on the person's X.500 privileges (such as a system administrator who may be allowed to change entry attributes that most users are not allowed to change), then you need to specify the person's distinguished name, password, and authentication level. Otherwise, to use default privileges, which usually allow people access to world readable directory attributes, pass NULL addresses to these parameters. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapOpen, ldapUnBind LDAP-7 ldapCountEntries _________________________________________________________________ ldapCountEntries Counts and returns the number of directory entries in an entry chain created by a call to the ldapSearchW function. Synopsis #include int ldapCountEntries( LDAP_t *ldap_handle , LDAPM_t *entry_chain ); Parameters ldap_handle (input) An address of an LDAP handle. entry_chain (input) A chain of directory entries initialized by a call to the ldapSearchReqst, the ldapSearchReqstLim, the ldapSearchW, or the ldapSearchWLim function. Returns The number of entries in the entry_chain. Related Information Functions: ldapSearchReqst, ldapSearchReqstLim, ldapSearchW, ldapSearchWLim LDAP-8 ldapDelete _________________________________________________________________ ldapDelete Frees memory and removes any remaining context after an unsuccessful call to the ldapUnBind function. Synopsis #include void ldapDelete( LDAP_t *ldap_handle ); Parameters ldap_handle (input) The address of an LDAP handle. Description The ldapDelete disassociates any remaining context stored by the ldap_handle structure. Call this function only if a call to ldapUnBind fails. Related Information Functions: ldapUnBind LDAP-9 ldapDeleteDNW _________________________________________________________________ ldapDeleteDNW Deletes an entry from a directory tree by deleting its distinguished name. Synopsis #include int ldapDeleteDNW( LDAP_t *ldap_handle , char *distinguished_name ); Parameters ldap_handle (input) The address of an LDAP handle. distinguished_name (input) The address of a string containing the distinguished name of the directory entry you want to delete. The following is an example of an LDAP-compliant distinguished name: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) Description The ldapDeleteDNW function performs its operation synchronously. This function works only with an X.500 Directory Service; you cannot use this function to delete an entry in the InfoBroker workgroup directory. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. LDAP-10 ldapDeleteDNW Related Information Functions: ldapAddW, ldapModify, ldapModrdnW LDAP-11 ldapErrorToText _________________________________________________________________ ldapErrorToText Converts the numerical value of the last encountered error to a NULL-terminated character string. Synopsis #include void ldapErrorToText( LDAP_t *ldap_handle , char **outstring ); Parameters ldap_handle (input) The address of an LDAP handle. outstring (output) A pointer to a character-string buffer, which contains the returned string. Description After you are finished using the character string containing the numeric error, you must free the memory allocated to the string. (C users can call the free function.) LDAP-12 ldapExplodeDN _________________________________________________________________ ldapExplodeDN Returns a pointer to a character string containing the relative distinguished name of the directory entry. Synopsis #include char ** ldapExplodeDN( char *distinguished_name , int no_entry ); Parameters distinguished_name (input) The address of a character string containing the directory entry's distinguished name, which was returned by a call to the ldapGetDN function. The following is an example of an LDAP-compliant distinguished name: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) no_entry (input) An unused parameter; pass any integer. Description When you are finished using the ldapExplodeDN function, you need to free the memory used to store the relative distinguished name. (C users can call the free function.) Returns A pointer that points to the character string containing the relative distinguished name (which is embedded in the distinguished name), or NULL, if the function encountered an error. LDAP-13 ldapExplodeDN Related Information Functions: ldapGetDN LDAP-14 ldapFirstAttribute _________________________________________________________________ ldapFirstAttribute Returns the address of a character string that contains the the first attribute's name from a directory entry's attribute list. Synopsis #include char * ldapFirstAttribute( LDAP_t *ldap_handle , LDAPM_t *directory_entry , LDAPBE_t **encoding ); Parameters ldap_handle (input) The address of an LDAP handle. directory_entry (input) The address of a directory entry returned by a call to either the ldapFirstEntry or ldapNextEntry function. encoding (output) The address of an array of pointers to attribute names. Description The ldapFirstAttribute function returns the address of a character string that contains the name of the first attribute in a directory entry's attribute list. Do not alter this character string; pass it untouched as a parameter to the ldapGetValues function to access the attribute's value or values. If necessary, make successive calls to the ldapNextAttribute function until you have read all of the entry's attribute names. Returns The address of a character string, which contains the entry's first attribute name, or NULL, if the entry contains no attributes. LDAP-15 ldapFirstAttribute Related Information Functions: ldapFirstEntry, ldapGetValues, ldapNextAttribute, ldapNextEntry LDAP-16 ldapFirstEntry _________________________________________________________________ ldapFirstEntry Returns the address of the first entry from an initialized chain of directory entries. Synopsis #include LDAPM_t * ldapFirstEntry( LDAP_t *ldap_handle , LDAPM_t *entry_chain ); Parameters ldap_handle (modified) The address of an LDAP handle; this call modifies the handle so that a subsequent call to the ldapNextEntry function succeeds. entry_chain (input) A chain of directory entries initialized by a call to the ldapSearchReqst, the ldapSearchReqstLim, the ldapSearchW, or the ldapSearchWLim function. Description Call one of the ldapSearch functions to initialize a chain of directory entries. Then, obtain the address of the first entry in the chain by calling the ldapFirstEntry function. Finally, call the ldapNextEntry function as often as necessary to obtain the addresses of the remaining entries in the chain. Returns The address of the first directory entry in the chain, or NULL, if there are no entries in the chain. LDAP-17 ldapFirstEntry Related Information Functions: ldapFirstAttribute, ldapNextEntry, ldapSearchReqst, ldapSearchReqstLim, ldapSearchW, ldapSearchWLim LDAP-18 ldapGetDN _________________________________________________________________ ldapGetDN Returns the address of a directory entry's distinguished name. Synopsis #include char * ldapGetDN( LDAP_t *ldap_handle , LDAPM_t *directory_entry ); Parameters ldap_handle (input) The address of an LDAP handle. directory_entry (input) The address of a directory entry returned by a call to either the ldapFirstEntry or ldapNextEntry function. Returns The address of a character string containing the distinguished name of directory_entry. Related Information Functions: ldapFirstEntry, ldapNextEntry LDAP-19 ldapGetValues _________________________________________________________________ ldapGetValues Returns an array of pointers (a vector) that point to attribute-value strings. Synopsis #include char ** ldapGetValues( LDAP_t *ldap_handle , LDAPM_t *directory_entry , char *attribute_name ); Parameters ldap_handle (input) The address of an LDAP handle. directory_entry (input) The address a directory entry, which was returned by a call to either the ldapFirstEntry or ldapNextEntry function. attribute_name (input) A pointer to an attribute name, which was returned by a call to either the ldapFirstAttribute or ldapNextAttribute function. Description The ldapGetValues function returns an array of pointers to attribute-value strings. Search through these strings until you encounter a NULL address in the array of pointers. When you are finished reading the values, free the memory used by the array of pointers by calling the ldapValueFree function. Returns An array of pointers whose pointers point to character strings of attribute values, the last of which is the NULL address; or NULL, if the directory entry has no attribute values. LDAP-20 ldapGetValues Related Information Functions: ldapFirstAttribute, ldapNextAttribute, ldapFirstEntry, ldapNextEntry LDAP-21 ldapGetValuesLen _________________________________________________________________ ldapGetValuesLen Returns an array of pointers (a vector) that point to structures that contain the length and content of binary attribute values. Synopsis #include LDAPBerval ** ldapGetValuesLen( LDAP_t *ldap_handle , LDAPM_t *directory_entry , char *attribute_name ); Parameters ldap_handle (input) The address of an LDAP handle. directory_entry (input) The address of a directory entry, which was returned by a call to either the ldapFirstEntry or ldapNextEntry function. attribute_name (input) A pointer to an attribute name, which was returned by a call to either the ldapFirstAttribute or ldapNextAttribute function. Description The ldapGetValuesLen obtains attribute values for binary data. Since binary data does not end with a NULL pointer, you need to know the length of the data in order to read it. LDAP stores binary data (such as jpegPhoto photographs) in structures, whose two members are the length of the binary data in bytes and a pointer to the data itself. (For more information on working with the attribute values of binary data types, see Section 6.4.4.) LDAP-22 ldapGetValuesLen Search through these pointers and access the binary data until you encounter a NULL address in the array of pointers. When you are finished reading the values, free the memory used by the array of pointers by calling the ldapValueFree function. Returns An array of pointers whose pointers point to structures. These structures have two members that contain the length of the binary data and a pointer to the actual data. The last item in the array of pointers is the NULL address. If the directory entry has no attribute values, this function returns NULL. Related Information Functions: ldapFirstAttribute, ldapGetValues, ldapNextAttribute, ldapValueFree LDAP-23 ldapModifyW _________________________________________________________________ ldapModifyW Modifies an entry in a directory tree. Synopsis #include int ldapModifyW( LDAP_t *ldap_handle , char *distinguished_name , LDAPMod *modifications_list ); Parameters ldap_handle (input) The address of an LDAP handle. distinguished_name (input) The address of a string containing the distinguished name of the entry in the directory tree that you want to modify. The following is an example of an LDAP-compliant distinguished name: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) modifications_list (input) Pointer to the first structure in a NULL-terminated linked list of structures, each of which provides information about the type of modification, the attribute name whose value or values are to change, and a pointer to a NULL- terminated list of pointers that point to the new attribute values. (For more information on constructing this linked list, see Section 6.4.4.) In the first member of a structure, you can specify constants that designate the type of modification to be made. If you are specifying binary data, you can perform a logical OR operation (|) on the binary-data constant (LDAP_ MOD_BVALUES) and on one other constant. Here are the valid constants for the first member of the structure: LDAP_MOD_ADD Add an attribute value to the entry. LDAP-24 ldapModifyW LDAP_MOD_DELETE Delete an attribute value from the entry. LDAP_MOD_REPLACE Replace an existing attribute value in the entry with another attribute value. LDAP_MOD_BVALUES The attribute value in the entry is binary data. Description The ldapModifyW function performs its task synchronously. This function works only with an X.500 Directory Service; you cannot use this function to modify entries in the InfoBroker workgroup directory. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapAddW, ldapDeleteDNW LDAP-25 ldapModrdnW _________________________________________________________________ ldapModrdnW Modifies a relative distinguished name. Synopsis #include int ldapModrdnW( LDAP_t *ldap_handle , char *dist_name , char *relative_dist_name ); Parameters ldap_handle (input) The address of an LDAP handle. dist_name (input) The address of the string containing the distinguished name that you want to modify. LDAP expects relative distinguished names to be separated with commas and to go, in order, from the directory entry in the tree to the root, as in the following example: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) relative_dist_name (input) The address of a string containing the new relative distinguished name (for instance, "cn="Joan A. Smith"") to be included in the distinguished name. Description The ldapModrdnW function performs its operation synchronously. This function works only with an X.500 Directory Service; you cannot use this function to modify a relative distinguished name in the InfoBroker workgroup directory. LDAP-26 ldapModrdnW Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapAddW, ldapDeleteDNW, ldapModifyW LDAP-27 ldapMsgFree _________________________________________________________________ ldapMsgFree Frees the memory used to store the chain of directory entries. Synopsis #include int ldapMsgFree( LDAPM_t entry_chain ); Parameters entry_chain (input) A chain of directory entries initialized by a call to the ldapSearchReqst, the ldapSearchReqstLim, the ldapSearchW, or the ldapSearchWLim function. Description When you are finished reading all of the directory entries and their attributes in entry_chain (the last entry in the chain is NULL), then use the ldapMsgFree function to release the entry chain's memory. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapFirstEntry, ldapNextEntry LDAP-28 ldapNextAttribute _________________________________________________________________ ldapNextAttribute Returns the address of a character string, which contains the next attribute name from a directory entry's attribute list. Synopsis #include char * ldapNextAttribute( LDAP_t *ldap_handle , LDAPM_t *directory_entry , LDAPBE_t *encoding ); Parameters ldap_handle (input) The address of an LDAP handle. directory_entry (input) The address of a directory entry returned by a call to either the ldapFirstEntry or ldapNextEntry function. encoding (output) The address of the next name in the entry's list of attribute names. Description The ldapNextAttribute function returns the address of a character string, which contains the next attribute name in the directory entry's attribute list. Do not alter this character string; pass it as a parameter to the ldapGetValues function to access the attribute's value or values. If necessary, make successive calls to the ldapNextAttribute function until you have read all of the entry's attributes. LDAP-29 ldapNextAttribute Returns The address of a character string, which contains the next attribute name in an entry, or NULL, if the entry contains no more attributes. Related Information Functions: ldapFirstAttribute, ldapGetValues LDAP-30 ldapNextEntry _________________________________________________________________ ldapNextEntry Returns the address of the next entry in the chain of directory entries. Synopsis #include LDAPM_t * ldapNextEntry( LDAP_t *ldap_handle , LDAPM_t **entry_chain ); Parameters ldap_handle (modified) The address of an LDAP handle; this call modifies the handle so that a subsequent call to ldapNextEntry succeeds. entry_chain (input) A chain of directory entries initialized by a call to the ldapSearchReqst, the ldapSearchReqstLim, the ldapSearchW, or the ldapSearchWLim function. Description Call one of the ldapSearch functions to initialize a chain of directory entries. Obtain the address of the first message by calling the ldapFirstEntry function. After you have called the ldapFirstAttribute, ldapGetValues, and ldapNextAttribute functions to read the first entry's attributes, call the ldapNextEntry function as often as necessary to obtain pointers to subsequent entries. Repeat this process until you have read all of the entries in the entry chain. Returns The address of the next entry in the chain of directory entries, or NULL, if there are no more entries in the chain. LDAP-31 ldapNextEntry Related Information Functions: ldapFirstAttribute, ldapFirstEntry, ldapSearchReqst, ldapSearchReqstLim, ldapSearchW, ldapSearchWLim LDAP-32 ldapOpen _________________________________________________________________ ldapOpen Initializes an LDAP handle, and, if successful, establishes a network connection to an LDAP-compliant server. Synopsis #include int ldapOpen( LDAP_t *ldap_handle , unsigned int transport , char *server_name , char *endpoint ); Parameters ldap_handle (output) The address of an LDAP handle. transport (input) One of the following constants, which indicates the network transport to use for client/server communications: LDAP_DECNET A DECnet network. LDAP_TCPIP A TCP/IP network. server_name (input) The address of a character string that specifies the name of the machine running the server. endpoint (input) The address of a character string that contains the name of the network endpoint for the process that runs the server. The default endpoint names for the InfoBroker server are as follows: LDAP_DECNET_SERVER Endpoint name for DECnet, whose value is "LDAP_SERVER". LDAP_TCPIP_SERVER Endpoint for TCP/IP, whose value translates to the port number "389". LDAP-33 ldapOpen Description If a call to ldapOpen fails, call ldapDelete to free the ldap_handle. After you initialize the LDAP handle with a call to ldapOpen, call the ldapBind function to bind the client and server. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapDelete LDAP-34 ldapPoll _________________________________________________________________ ldapPoll Determines whether an asynchronous request has completed. Synopsis #include int ldapPoll( LDAP_t *ldap_handle ); Parameters ldap_handle (input) The address of an LDAP handle. Description The ldapPoll function determines whether the asynchronous search (a call to ldapSearchReqst or ldapSearchReqstLim) is complete. When it is complete, call ldapSearchResult to read the directory-entry chain. Returns TRUE, if the asychronous call is complete, and FALSE, if the call is not complete. Example See the ldapSearchReqst function. Related Information Functions: ldapSearchReqst, ldapSearchReqstLim, ldapSearchResult LDAP-35 ldapSearchReqst _________________________________________________________________ ldapSearchReqst Conducts an asynchronous search through a directory tree. Synopsis #include int ldapSearchReqst( LDAP_t *ldap_handle , char *base , int scope , char *filter , char **attribute_names , int no_attributes_flag ); Parameters ldap_handle (modified) An address of an LDAP handler; this call modifies the handle so that a subsequent call to the ldapFirstEntry function succeeds. base (input) The address of a string containing a distinguished name. This name is the entry in the directory tree with which to begin the search. scope (input) One of the following LDAP_SCOPE_constraint constants that constrain the area of the tree in which to search: LDAP_SCOPE_BASE Search only the directory entry specified by the base parameter; this is also called the "search base." LDAP_SCOPE_ Search the base and one level down in ONELEVEL the tree. LDAP_SCOPE_SUBTREE Search the whole subtree that begins with the search-base directory entry. LDAP-36 ldapSearchReqst filter (input) An address of a string containing an expression. When evaluated against an attribute in a directory entry, the expression must evaluate to TRUE in order for the search to return a given entry. A search filter has the following format: (operator (expression) (expression)) The operator field is one of the following logical operators: ___________________________________________________________ OperatoName________Description_____________________________ | OR True, if either expression is True. & AND True, if both expressions are True. !______NOT_________True,_if_the_expression_is_not_True.____ Here is the format for the expression in the previous format description: attribute_name operator2 attribute_value The attribute_name field is an attribute name defined in the schema. The attribute_value field is the attribute value for which the server searches. The operator2 item can be one of the following operators: ___________________________________________________________ operator2me________Description_____________________________ = Equals The server returns directory entries whose attribute values exactly match the attribute_value in the search filter. For example, (commonName=Pete) results in the server returning entries with the commonName attribute value "Pete". ~= Approximate The server returns directory entries whose attribute values "approximately match" the attribute_value in the search filter. For example, (surname~=Olson) results in the server returning entries with the surname attribute values "Olson" or "Olsen". LDAP-37 ldapSearchReqst ___________________________________________________________ operator2me________Description_____________________________ =* Present The server returns all directory entries that have the attribute_name specified in the filter. For example, (surname=*) results in the server returning entries that have a surname attribute name, ___________________regardless_of_the_attribute's_value.____ To see how the InfoBroker uses a similar kind of search filter in a configuration file, see Section 5.5.1. attribute_names (input) An array of strings containing the list of attribute names that you would like returned in entry_chain. The search returns only the requested attributes names. Also, the search may not return the names in the order in which you specified them in this parameter. If you specify an invalid attribute name, the server ignores it. no_attributes_flag (input) An integer that, if TRUE, indicates that ldapSearchReqst should return only the attribute names, and, if FALSE, indicates that this function should return both the names and the values. Description After you call ldapSearchReqst, call ldapPoll periodically to determine whether the asynchronous search is complete. When it is complete, call the ldapSearchResult function to read the directory-entry chain. Since you cannot be certain of the order in which the server will be able to respond to your asynchronous requests, you should make only one asynchronous search request at a time for a given LDAP handle. Once the request completes (or once you abandon the request), you can make another asynchronous search request on that handle. LDAP-38 ldapSearchReqst Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Example #include LDAP_t *ldap_handle; char base[] = "(ou=Sales,ou=NY_Sales,o=your_ company,c=US)"; int scope = LDAP_SCOPE_ SUBTREE; /* Search the whole subtree */ char filter[] = "(sn~=Olson)"; /* Approximately "Olson" */ char attr_ names[4][] = { "title", /* Attributes to search for */ "cn", "postaladdress", "\0" }; int no_att_ flag = 0; /* Return attribute names */ LDAPM_t **result_chain; int done_yet = FALSE; int status; status = ldapSearchReqst(ldap_ handle, base, scope, filter, attr_names, no_att_flag); while (done_yet == FALSE) done_yet = ldapPoll(ldap_handle); status = ldapSearchResult(ldap_handle, result_chain); Related Information Functions: ldapAbandon, ldapFirstEntry, ldapPoll, ldapSearchResult, ldapSearchW LDAP-39 ldapSearchReqstLim _________________________________________________________________ ldapSearchReqstLim Conducts an asynchronous search through a directory tree, and sets limitations on the search time and on the number of entries returned. Synopsis #include int ldapSearchReqstLim( LDAP_t *ldap_handle , char *base , int scope , char *filter , char **attribute_names , int no_attributes_flag , int size_limit , int time_limit ); Parameters ldap_handle (modified) An address of an LDAP handler; this call modifies the handle so that a subsequent call to the ldapFirstEntry function succeeds. base (input) The address of a string containing a distinguished name. This name is the entry in the directory tree with which to begin the search. scope (input) One of the following LDAP_SCOPE_constraint constants that constrain the area of the tree in which to search: LDAP_SCOPE_BASE Search only the directory entry specified by the base parameter; this is also called the "search base." LDAP_SCOPE_ Search the base and one level down in ONELEVEL the tree. LDAP-40 ldapSearchReqstLim LDAP_SCOPE_SUBTREE Search the whole subtree that begins with the search-base directory entry. filter (input) An address of a string containing an expression. When evaluated against a directory entry, the expression must evaluate to TRUE in order for the search to return a given entry. A search filter has the following format: (operator (expression) (expression)) The operator field is one of the following logical operators: ___________________________________________________________ OperatoName________Description_____________________________ | OR True, if either expression is True. & AND True, if both expressions are True. !______NOT_________True,_if_the_expression_is_not_True.____ Here is the format for the expression in the previous format description: attribute_name operator2 attribute_value The attribute_name field is an attribute name defined in the schema. The attribute_value field is the attribute value for which the server searches. The operator2 item can be one of the following operators: ___________________________________________________________ operator2me________Description_____________________________ = Equals The server returns directory entries whose attribute values exactly match the attribute_value in the search filter. For example, (commonName=Pete) results in the server returning entries with the commonName attribute value "Pete". LDAP-41 ldapSearchReqstLim ___________________________________________________________ operator2me________Description_____________________________ ~= Approximate The server returns directory entries whose attribute values "approximately match" the attribute_value in the search filter. For example, (surname~=Olson) results in the server returning entries with the surname attribute values "Olson" or "Olsen". =* Present The server returns all directory entries that have the attribute_name specified in the filter. For example, (surname=*) results in the server returning entries that have a surname attribute name, ___________________regardless_of_the_attribute's_value.____ To see how the InfoBroker uses a similar kind of search filter in a configuration file, see Section 5.5.1. attribute_names (input) An array of strings containing the list of attribute names that you would like returned in entry_chain. The search returns only the requested attributes names. Also, the search may not return the names in the order in which you specified them in this parameter. If you specify an invalid attribute name, the server ignores it. no_attributes_flag (input) An integer that, if TRUE, indicates that ldapSearchReqstLim should return only the attribute names, and, if FALSE, indicates that this function should return both the names and the values. size_limit (input) An integer that specifies the maximum number of entries to return. time_limit (input) An integer that specifies the maximum number of seconds for the search. LDAP-42 ldapSearchReqstLim Description After you call ldapSearchReqstLim, you can either call ldapPoll periodically or wait until the time_limit has expired to determine whether the asynchronous search is complete. When it is complete, call the ldapSearchResult function to read the directory-entry chain. Since you cannot be certain of the order in which the server will be able to respond to your asynchronous requests, you should make only one asynchronous search request at a time for a given LDAP handle. Once the request completes (or once you abandon the request), you can make another asynchronous search request on that handle. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Example See the ldapSearchWLim function. Related Information Functions: ldapAbandon, ldapFirstEntry, ldapPoll, ldapSearchReqst, ldapSearchResult, ldapSearchWLim LDAP-43 ldapSearchResult _________________________________________________________________ ldapSearchResult Provides a chain of directory entries that met the search specification of an asynchronous search. Synopsis #include int ldapSearchResult( LDAP_t *ldap_handle , char **entry_chain ); Parameters ldap_handle (modified) An address of an LDAP handler; this call modifies the handle so that a subsequent call to the ldapFirstEntry function succeeds. entry_chain (output) The address of a chain of directory entries. Description If you called the ldapSearchReqst function, call the ldapPoll function periodically to determine if the search is complete, yet. When it is complete, call the ldapSearchResult function to retrieve the entry_chain. If you called the ldapSearchReqstLim function, you can either call the ldapPoll function periodically, or you can wait for time_limit to expire. Then, call this function to retrieve the entry_chain. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. LDAP-44 ldapSearchResult Example See the ldapSearchReqst function. Related Information Functions: ldapFirstEntry, ldapOpen, ldapSearchReqst, ldapSearchReqstLim. LDAP-45 ldapSearchW _________________________________________________________________ ldapSearchW Conducts a synchronous search through a directory tree. Synopsis #include int ldapSearchW( LDAP_t *ldap_handle , char *base , int scope , char *filter , char **attribute_names , int no_attributes_flag , char **entry_chain ); Parameters ldap_handle (modified) An address of an LDAP handler; this call modifies the handle so that a subsequent call to the ldapFirstEntry function succeeds. base (input) The address of a string containing a distinguished name. This name is the entry in the directory tree with which to begin the search. scope (input) One of the following LDAP_SCOPE_constraint constants that constrain the area of the tree in which to search: LDAP_SCOPE_BASE Search only the directory entry specified by the base parameter; this is also called the "search base." LDAP_SCOPE_ Search the base and one level down in ONELEVEL the tree. LDAP_SCOPE_SUBTREE Search the whole subtree that begins with the search-base directory entry. LDAP-46 ldapSearchW filter (input) An address of a string containing an expression. When evaluated against a directory entry, the expression must evaluate to TRUE in order for the search to return a given entry. A search filter has the following format: (operator (expression) (expression)) The operator field is one of the following logical operators: ___________________________________________________________ OperatoName________Description_____________________________ | OR True, if either expression is True. & AND True, if both expressions are True. !______NOT_________True,_if_the_expression_is_not_True.____ Here is the format for the expression in the previous format description: attribute_name operator2 attribute_value The attribute_name field is an attribute name defined in the schema. The attribute_value field is the attribute value for which the server searches. The operator2 item can be one of the following operators: ___________________________________________________________ operator2me________Description_____________________________ = Equals The server returns directory entries whose attribute values exactly match the attribute_value in the search filter. For example, (commonName=Pete) results in the server returning entries with the commonName attribute value "Pete". ~= Approximate The server returns directory entries whose attribute values "approximately match" the attribute_value in the search filter. For example, (surname~=Olson) results in the server returning entries with the surname attribute values "Olson" or "Olsen". LDAP-47 ldapSearchW ___________________________________________________________ operator2me________Description_____________________________ =* Present The server returns all directory entries that have the attribute_name specified in the filter. For example, (surname=*) results in the server returning entries that have a surname attribute name, ___________________regardless_of_the_attribute's_value.____ To see how the InfoBroker uses a similar kind of search filter in a configuration file, see Section 5.5.1. attribute_names (input) An array of strings containing the list of attribute names to search for and to return. The search returns only the requested attribute names, but they may not be returned in the order in which you request them. If you specify an attribute name that is not supported by the LDAP-compliant server, a call to ldapSearchW ignores it. no_attributes_flag (input) An integer that, if TRUE, indicates that ldapSearchW should return only the attribute names, and, if FALSE, indicates that this function should return both the names and the values. entry_chain (output) The address of a chain of directory entries. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. LDAP-48 ldapSearchW Example #include LDAP_t *ldap_handle; char base[] = "(ou=Sales,ou=NY_Sales,o=your_ company,c=US)"; int scope = LDAP_SCOPE_ SUBTREE; /* Search the whole subtree */ char filter[] = "(sn~=Olson)"; /* Approximately "Olson" */ char attr_ names[4][] = { "title", /* Attributes to search for */ "cn", "postaladdress", "\0" }; int no_att_ flag = 0; /* Return attribute names */ LDAPM_t **result_chain; int status; status = ldapSearchW(ldap_ handle, base, scope, filter, attr_names, no_att_flag, result_chain); Related Information Functions: ldapFirstEntry, ldapSearchReqst, ldapSearchWLim LDAP-49 ldapSearchWLim _________________________________________________________________ ldapSearchWLim Conducts a synchronous search through a directory tree, and sets limitations on the search time and on the number of entries returned. Synopsis #include int ldapSearchW( LDAP_t *ldap_handle , char *base , int scope , char *filter , char **attribute_names , int no_attributes_flag , int size_limit , int time_limit , char **entry_chain ); Parameters ldap_handle (modified) An address of an LDAP handler; this call modifies the handle so that a subsequent call to the ldapFirstEntry function succeeds. base (input) The address of a string containing a distinguished name. This name is the entry in the directory tree with which to begin the search. scope (input) One of the following LDAP_SCOPE_constraint constants that constrain the area of the tree in which to search: LDAP_SCOPE_BASE Search only the directory entry specified by the base parameter; this is also called the "search base." LDAP-50 ldapSearchWLim LDAP_SCOPE_ Search the base and one level down in ONELEVEL the tree. LDAP_SCOPE_SUBTREE Search the whole subtree that begins with the search-base directory entry. filter (input) An address of a string containing an expression. When evaluated against a directory entry, the expression must evaluate to TRUE in order for the search to return a given entry. A search filter has the following format: (operator (expression) (expression)) The operator field is one of the following logical operators: ___________________________________________________________ OperatoName________Description_____________________________ | OR True, if either expression is True. & AND True, if both expressions are True. !______NOT_________True,_if_the_expression_is_not_True.____ Here is the format for the expression in the previous format description: attribute_name operator2 attribute_value The attribute_name field is an attribute name defined in the schema. The attribute_value field is the attribute value for which the server searches. The operator2 item can be one of the following operators: ___________________________________________________________ operator2me________Description_____________________________ = Equals The server returns directory entries whose attribute values exactly match the attribute_value in the search filter. For example, (commonName=Pete) results in the server returning entries with the commonName attribute value "Pete". LDAP-51 ldapSearchWLim ___________________________________________________________ operator2me________Description_____________________________ ~= Approximate The server returns directory entries whose attribute values "approximately match" the attribute_value in the search filter. For example, (surname~=Olson) results in the server returning entries with the surname attribute values "Olson" or "Olsen". =* Present The server returns all directory entries that have the attribute_name specified in the filter. For example, (surname=*) results in the server returning entries that have a surname attribute name, ___________________regardless_of_the_attribute's_value.____ To see how the InfoBroker uses a similar kind of search filter in a configuration file, see Section 5.5.1. attribute_names (input) An array of strings containing the list of attribute names to search for and to return. The search returns only the requested attribute names, but they will not necessarily be returned in the order in which you request them. If you specify an attribute name that is not supported by the LDAP-compliant server, a call to ldapSearchW ignores it. no_attributes_flag (input) An integer that, if TRUE, indicates that ldapSearchWLim should return only the attribute names, and, if FALSE, indicates that this function should return both the names and the values. size_limit (input) An integer that specifies the maximum number of entries to return. time_limit (input) An integer that specifies the maximum number of seconds for the search. entry_chain (output) The address of a chain of directory entries. LDAP-52 ldapSearchWLim Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Example #include LDAP_t *ldap_handle; char base[] = "(ou=Sales,ou=NY_Sales,o=your_ company,c=US)"; int scope = LDAP_SCOPE_ SUBTREE; /* Search the whole subtree */ char filter[] = "(sn~=Olson)"; /* Approximately "Olson" */ char attr_ names[4][] = { "title", /* Attributes to search for */ "cn", "postaladdress", "\0" }; int no_att_ flag = 0; /* Return attribute names */ int size_ limit = 20; /* No more than 20 "Olson"s */ int time_ limit = 300; /* Search for 5 minutes */ LDAPM_t **result_chain; int status; status = ldapSearchWLim(ldap_ handle, base, scope, filter, attr_names, no_att_flag, size_limit, time_ limit, result_chain); Related Information Functions: ldapFirstEntry, ldapSearchReqstLim, ldapSearchW LDAP-53 ldapUnBind _________________________________________________________________ ldapUnBind Ends an association between and LDAP client and and LDAP- compliant server. Synopsis #include int ldapUnBind( LDAP_t *ldap_handle ); Parameters ldap_handle (input) The address of an LDAP handle. After a call to ldapUnBind, you cannot reuse ldap_handle. Description The ldapUnBind function disconnects the client and server, and returns to the system all resources that had been allocated to the user account. If this function fails, call the ldapDelete function to return system resources. Returns One of the LDAP standard return values: LDAP_message. For more information on the standard return values, see Section D.1.2. Related Information Functions: ldapBind, ldapDelete, ldapOpen LDAP-54 ldapValueFree _________________________________________________________________ ldapValueFree Frees the memory used to contain the array of pointers whose pointers point to attribute values. Synopsis #include void ldapValueFree( char **attribute_values ); Parameters attribute_values (input) The address of the array of pointers, whose pointers point to attribute values, which was created by a call to either the ldapGetValues or the ldapGetValuesLen function. Related Information Functions: ldapGetValues, ldapGetValuesLen LDAP-55 A _________________________________________________________________ Files Created by Installation This appendix lists the files created when you install InfoBroker. A.1 InfoBroker server Files The InfoBroker server subsets install several files to various locations on the server. Refer to Chapter 3 for more information about the installation process. The files listed in Table A-1 are installed on the OSF/1 server. Table_A-1_Files_Installed_on_the_Server____________________ Installed Filename__________to..._________Description________________ ibxlookupd subset ibxlookupd /usr/sbin The look-up daemon stop_ /usr/sbin Script to stop the look-up ibxlookupd.osf daemon start_ /usr/sbin Script to start the look-up ibxlookupd.osf daemon ibxlookup /sbin/init.d The look-up daemon's startup file djpeg /bin Code that translates jpeg to GIF mods.c /usr Sample LDAP program that /examples modifies attributes (continued on next page) Files Created by Installation A-1 Table_A-1_(Cont.)_Files_Installed_on_the_Server____________ Installed Filename__________to..._________Description________________ search.c /usr Sample LDAP program that /examples conducts a simple search ibxwwwgw.help /usr/lib HTML Help Page S70.1ibxlookup /sbin/rc3.d Automatic startup file decnet.conf /var/ibx DECnet configuration file /lookup (whose name changes to ibx.conf) tcpip.conf /var/ibx TCP/IP configuration file /lookup (whose name changes to ibx.conf) head.gif /var/ibx Art file for the main HTML /lookup page foot.gif /var/ibx Art file for the main HTML /lookup page asrchfrm.gif /var/ibx Art file for the HTML Help /lookup page declogo.gif /var/ibx Art file for the HTML Help /lookup page enpsswrd.gif /var/ibx Art file for the HTML Help /lookup page fndsmith.gif /var/ibx Art file for the HTML Help /lookup page fndvandr.gif /var/ibx Art file for the HTML Help /lookup page hlpasrch.gif /var/ibx Art file for the HTML Help /lookup page hlpfoot.gif /var/ibx Art file for the HTML Help /lookup page hlplogo.gif /var/ibx Art file for the HTML Help /lookup page modatts.gif /var/ibx Art file for the HTML Help /lookup page (continued on next page) A-2 Files Created by Installation Table_A-1_(Cont.)_Files_Installed_on_the_Server____________ Installed Filename__________to..._________Description________________ modhspts.gif /var/ibx Art file for the HTML Help /lookup page pswrdfrm.gif /var/ibx Art file for the HTML Help /lookup page srchrslt.gif /var/ibx Art file for the HTML Help /lookup page srchrst2.gif /var/ibx Art file for the HTML Help /lookup page ibxoserv subset S70ibx /sbin/rc3.d Automatic startup file ibx /sbin/init.d Automatic startup file ibxd /usr/sbin InfoBroker daemon ibx.release_ /usr/doc Release notes notes start_ibxd.osf /usr/sbin Script to start ibxd stop_ibxd.osf /usr/sbin Script to stop ibxd x500-load.txt /var/ibx Sample workgroup directory ibxoapi subset libldap.h /usr/include LDAP include file libdax.so /usr/shlib Shared dynamic library libdax.a /usr/lib/ Static library ibxoman subset man pages ldapAbandon.3ibx /usr/share /man/man3 ldapAddW.3ibx /usr/share /man/man3 (continued on next page) Files Created by Installation A-3 Table_A-1_(Cont.)_Files_Installed_on_the_Server____________ Installed Filename__________to..._________Description________________ ldapBind.3ibx /usr/share /man/man3 ldapCountEntries.3/usr/share /man/man3 ldapDelete.3ibx /usr/share /man/man3 ldapDeleteDNW.3ibx/usr/share /man/man3 ldapErrorToText.3i/usr/share /man/man3 ldapExplodeDN.3ibx/usr/share /man/man3 ldapFirstAttribute/usr/share /man/man3 ldapFirstEntry.3ib/usr/share /man/man3 ldapGetDN.3ibx /usr/share /man/man3 ldapGetValues.3ibx/usr/share /man/man3 ldapGetValuesLen.3/usr/share /man/man3 ldapModifyW.3ibx /usr/share /man/man3 ldapModrdnW.3ibx /usr/share /man/man3 ldapMsgFree.3ibx /usr/share /man/man3 ldapNextAttribute./usr/share /man/man3 ldapNextEntry.3ibx/usr/share /man/man3 (continued on next page) A-4 Files Created by Installation Table_A-1_(Cont.)_Files_Installed_on_the_Server____________ Installed Filename__________to..._________Description________________ ldapOpen.3ibx /usr/share /man/man3 ldapPoll.3ibx /usr/share /man/man3 ldapSearchReqst.3i/usr/share /man/man3 ldapSearchReqstLim/usr/share /man/man3 ldapSearchResult.3/usr/share /man/man3 ldapSearchW.3ibx /usr/share /man/man3 ldapSearchWLim.3ib/usr/share /man/man3 ldapUnBind.3ibx /usr/share /man/man3 ldapValueFree.3ibx/usr/share /man/man3 ibxd.8 /usr/share /man/man8 ibxlookupd.8 /usr/share __________________/man/man8________________________________ A.2 InfoBroker Client Version 1.0A Files The InfoBroker client Version 1.0A Setup copies several files to various locations on your hard disk. Refer to Chapter 4 for information about installation and choosing a location for the files. This section assumes that the default location was used. Files Created by Installation A-5 A.2.1 Files Installed to \X500C After Setup completes, the files listed in Table A-2 are installed to the \X500C directory (or other directory name you specified): Table_A-2_Client_Directory_Files___________________________ Filename____Description____________________________________ libdax.dll LDAP protocol routines SDK Advanced development kit for InfoBroker directory wsockets.dllNetworking routines x500c.exe InfoBroker client executable file x500c.hlp___InfoBroker_client_Windows_help_file____________ A.2.2 Files Installed to \WINDOWS The files listed in Table A-3 are installed to your Windows directory. Table_A-3_Windows_Directory_Files__________________________ Filename____Description____________________________________ director.grpWindows program group for the client application infovbx.dll Windows display routines infovbx.vbx Windows display routines m3open.exe Networking routines m3open.dll Networking routines mbw.exe Networking routines mftp.exe Networking routines mhparpa.dll Networking routines mnetone.exe Networking routines mnovlwp.dll Networking routines mpcnfs.exe Networking routines (continued on next page) A-6 Files Created by Installation Table_A-3_(Cont.)_Windows_Directory_Files__________________ Filename____Description____________________________________ mpcnfs2.exe Networking routines mpcnfs4.dll Networking routines mpathway.dllNetworking routines msocklib.dllNetworking routines vsl.ini Networking routines x500c.ini Client initialization file xtiasw.dll Networking routines xtidnw.dll Networking routines xtijsb.dll Networking routines xtilib.dll Networking routines xtiwins.dll_Networking_routines____________________________ A.2.3 Files Installed to \X500C\SDK The files listed in Table A-4 are installed to your \X500C\SDK directory. Table_A-4_SDK_Directory_Files______________________________ Filename____Description____________________________________ daxapi.h Header file for C or C++ readme.sdk Documentation for the advanced development kit VCEXMPLE Contains various files as an example of using directory___the_advanced_development_kit___________________ Note: The InfoBroker product does not support this software development kit (SDK); it is not documented in this manual. Files Created by Installation A-7 B _________________________________________________________________ Troubleshooting Tips for the InfoBroker Server Consult the following list to resolve any problems with the InfoBroker Server: o Check to see that the InfoBroker PAK is properly registered. See the DEC OSF/1 Guide to Software License Management for more information. You can also refer to the man pages for lmf and lmf setup. o If after starting the server, you are unable to contact it, check to ensure that it is still running and listening over DECnet and/or TCP/IP. - If the server is not running, check the /var/ibxd /ibxd.log file to see whether it contains any information that might explain the problem. - If the ibxd.log file does not help, try running the server at your terminal: > /usr/sbin/ibxd -f name-of-your-local-file > /usr/sbin/ibxd -x > /usr/sbin/ibxd -x -f name-of-your-local-file -B The first command specifies that the InfoBroker server uses only the workgroup directory. The second command specifies that the server uses only X.500. The third command specifies that the server searches both the workgroup directory and an existing X.500 directory (the server always searches in the workgroup directory first before searching in X.500). - See whether any error messages explain the problem. Troubleshooting Tips for the InfoBroker Server B-1 o If you can connect to the server, but you cannot return any entries: - If you are using a local file, make sure that you specified the correct file name when you started the server. - Make sure that you specified the correct search base for your lookup. - If you are using X.500, make sure that your server system is configured to the correct machine running the appropriate X.500 software (the correct X.500 DSA). Check for a dua.defaults file in the "/" directory. (This file will override the system default file in the /etc directory.) - Make sure you are able to reach the X.500 server from your InfoBroker server system. You can use the Digital X.500 administration utilities to do this. (Although you can use X.500 administration utilities with the InfoBroker server, they are not required to run InfoBroker.) If the adminstration utilities subset is not installed on your server system, you will have to install it to perform the procedures described here. Run /usr/bin/dxim on your InfoBroker server system to see whether you can lookup the entry in the DSA. The format of the command you could use might look something like the following: /usr/sbin/dxim -c dxim> bind dxim> search /c=us where sn=einstein In this example, /c=us and sn=einstein are strings that would depend on your X.500 DIT. o If the bind fails, your X.500 DSA may not be running, or your InfoBroker server system might not be properly configured for X.500. o If the search command fails, then your search base (/c=us in the example) might be incorrect, the entry you are looking for might not be in the DSA, or you might be configured to the wrong DSA. B-2 Troubleshooting Tips for the InfoBroker Server o If these commands succeed, then your system is connected to the X.500 DSA. See DEC X.500 Directory Service Problem Solving and DEC X.500 Directory Service Management for more tips on how to troubleshoot problems with either the bind or the search command. o If you are using a Local Directory file and you are unable to display some attributes from some entries, make sure that the attribute type names are spelled correctly and that you are using a valid alias. o If you restart your server to load a new Local Directory file and you cannot see any of the new entries, make sure you stopped the previous server before starting the new one. Use the /usr/sbin/stopd_ibxd.osf file to stop a running server. o If you are using X.500, the following file may contain error messages from an X.500 request: /var/ibx/ibxd_nnnn.log, where nnnn is a four digit number. o If you cannot resolve a problem with the server and if you need to contact Digital Support, start the server with the following command: > /usr/sbin/start_ibxd.osf -d -1 This command creates a log of messages that you can give to Digital Support to assist them in diagnosing the problem. Troubleshooting Tips for the InfoBroker Server B-3 C _________________________________________________________________ Default Structure Rules for the Workgroup Directory The InfoBroker Server provides a default set of structure rules for its workgroup directory which includes some definitions agreed to by the international standards organizations. These rules also include some definitions required by Digital's X.500 Directory Service and other applications, including Digital's MailWorks product. Take care not to modify these definitions. Modifying the definitions can interfere with the operation of the InfoBroker Server or the other applications. You can, however, customize the standard directory rules for compatibility with an X.500 DSA with a customized schema or in order to better represent the information- storage needs of your own organization. See Section 5.3 for information on customizing the standard schema. This appendix describes the standard schema. These directory rules define the object classes you can use to create entries in your workgroup directory, the attributes associated with each object class, and the syntax associated with each attribute value. The rules also define some permitted relationships between entries of different object classes: for example, the rule that an entry of the country class cannot be subordinate to an entry of the organizationalPerson class. Note that since you can customize the standard rules, the structure of your directory might not be exactly as described in this appendix. Default Structure Rules for the Workgroup Directory C-1 C.1 Object Classes The following subsections each describe an object class defined in one of the /var/dxd/*.sc files. (The dxd_ schema.sc file contains some definitions and contains pointers to the other schema files that are included before schema compilation.) You can use this set of object classes to describe the directory entries typically found in an organization's directory hierarchy. Each of the following subsections: o Describes an object class and the type of entries it can be used to define. o Lists all mandatory and optional attributes for the class. o Specifies the attribute that should be used to name the entry. o Specifies where the entry can occur in the hierarchy of the defined workgroup-directory entries; it specifies what classes can occur above and below an entry of each class. C.1.1 alias The alias class forms the basis of schema definitions for specific alias classes. You cannot create entries of the alias class. Instead use one of the alias subclasses. For example, to create an alias entry for a device, use the deviceAlias class. Each alias subclass specifies the use of an appropriate naming attribute so that you can create aliases that have names similar to those of other classes. Mandatory Attributes objectClass aliasedObjectName Optional Attributes None. C-2 Default Structure Rules for the Workgroup Directory Naming Rules You cannot create an entry of the alias class itself. Therefore, there are no naming rules for this object class. Each subclass of the alias class specifies a naming rule. Structure Rules You cannot create an entry of the alias class itself. Therefore, there are no structure rules for this object class. Each subclass of the alias class specifies a structure rule. C.1.2 country The country structural object class is used to define workgroup-directory entries that represent countries. Mandatory Attributes objectClass countryName Optional Attributes description Naming Rules Use the countryName attribute for naming. Structure Rules A country entry must be immediately beneath the logical root of the workgroup directory. It cannot be subordinate to an entry of any other class. C.1.3 countryAlias The countryAlias alias object class is used to define alias entries that represent countries. Mandatory Attributes objectClass countryName aliasedObjectName Optional Attributes None. Naming Rules Use the countryName attribute for naming. Default Structure Rules for the Workgroup Directory C-3 Structure Rules A countryAlias entry must be immediately beneath the logical root of the workgroup directory. It cannot be subordinate to an entry of any other class. C.1.4 decMailUser This auxiliary object class can be used with directory entries to enable them to represent Digital mail users. You can modify any directory entry to add this auxiliary object class. This object class may be used as an alternative to or in addition to the the mhs-user auxiliary object class. The optional attributes of the decMailUser class become optional for the entry. Mandatory Attributes None. Optional Attributes mhs-or-addresses rfc822mailbox decMRAddress decPMAddress decPreferredMailAddress decMAILworksUserName Naming Rules Auxiliary object classes do not have naming rules. The naming rule of the entry's structural class applies. Structure Rules Auxiliary object classes do not have structure rules. The structure rules of the entry's structural class apply. The decMailUser auxiliary object class can be added to an entry in any position in the workgroup directory. For example, you can modify an organizationalPerson entry to make it a member of the decMailUser class. The optional attributes of the decMailUser class become optional for the entry. C.1.5 device The device object class is used to define entries that represent hardware devices, such modems or disk drives. C-4 Default Structure Rules for the Workgroup Directory Mandatory Attributes objectClass commonName Optional Attributes description localityName organizationName organizationalUnitName owner seeAlso serialNumber Naming Rules Use the commonName attribute for naming. Structure Rules The device entries must have an immediately superior entry of one of the following object classes: organization organizationalUnit locality A device entry is not permitted immediately beneath the root of the workgroup directory. C.1.6 deviceAlias The deviceAlias alias object class is used to define alias entries that represent hardware devices, such as modems or disk drives. Mandatory Attributes objectClass commonName aliasedObjectName Optional Attributes None. Naming Rules Use the commonName attribute for naming. Default Structure Rules for the Workgroup Directory C-5 Structure Rules The deviceAlias entries must have an immediately superior entry of one of the following object classes: organization organizationalUnit locality A deviceAlias entry is not permitted immediately beneath the root of the workgroup directory. C.1.7 groupOfNames The groupOfNames object class is used to define entries that represent an unordered set of directory names that are grouped for some purpose. Each name represents either an individual entry or is the name of another group. The group of names can be reduced to a set of individual entry names by replacing each group with its membership. This can be carried out recursively until all constituent group names have been eliminated, and only the names of individual entries remain. You can create an entry of this object class to describe any set or group of objects that is connected in a significant way, for example, committees, teams, or distribution lists. Mandatory Attributes objectClass commonName member Optional Attributes businessCategory description organizationName organizationalUnitName owner seeAlso Naming Rules Use the commonName attribute for naming. C-6 Default Structure Rules for the Workgroup Directory Structure Rules A directory entry of the object class groupOfNames must have an immediately superior entry of one of the following object classes: locality organization organizationalUnit A groupOfNames entry is not permitted immediately beneath the root of the workgroup directory. C.1.8 groupOfNamesAlias The groupOfNamesAlias alias object class is used to define alias entries that represent aliases for groupOfNames entries. Mandatory Attributes objectClass commonName aliasedObjectName Optional Attributes None. Naming Rules Use the commonName attribute for naming. Structure Rules A directory entry of the object class groupOfNamesAlias must have an immediately superior entry of one of the following object classes: locality organization organizationalUnit A groupOfNamesAlias entry is not permitted immediately beneath the root of the workgroup directory. C.1.9 locality The locality entries represent a geographical locality, such as a state, a province, a city, or a building. You can use locality entries to represent the geographical, political, or geopolitical subdivisions of your organization. Default Structure Rules for the Workgroup Directory C-7 Mandatory Attributes objectClass Optional Attributes description localityName stateOrProvinceName seeAlso streetAddress Naming Rules Use the localityName attribute for naming. Therefore, although this attribute is optional according to the class definition, it is, in effect, mandatory. For example, /c=us /s=nh/1=Brookline attr objectclass=locality effectively creates a locality attribute. Structure Rules A locality entry must have an immediately superior entry that is one of the following object classes: country locality organization organizationalUnit A locality entry is also permitted immediately beneath the root of the workgroup directory. C.1.10 localityAlias The localityAlias alias object class is used to define alias entries that represent localities or regions. Mandatory Attributes objectClass aliasedObjectName Optional Attributes localityName stateOrProvinceName Naming Rules Use the localityName attribute for naming. C-8 Default Structure Rules for the Workgroup Directory Structure Rules A localityAlias entry must have an immediately superior entry that is one of the following object classes: country locality organization organizationalUnit A localityAlias entry can also be immediately beneath the logical root of the workgroup directory. C.1.11 mhs-user This auxiliary object class can be used with directory entries to enable them to contain X.400 messaging information. You can modify any directory entry to add this auxiliary object class. The mandatory attribute of this class then becomes mandatory for the entry. Mandatory Attributes mhsORAddresses Optional Attributes None. Naming Rules Auxiliary object classes do not have naming rules. The naming rule of the entry's structural class applies. Structure Rules Auxiliary object classes do not have structure rules. The structure rules of the entry's structural class apply. The mhs-user auxiliary class can be added to an entry in any position in the hierarchy of the workgroup- directory entries. For example, you can modify an organizationalPerson entry to make it a member of the mhs- user class. The mandatory attribute of the mhs-user class becomes mandatory for the entry. C.1.12 organization The organization object class is used to define entries that represent organizations. Default Structure Rules for the Workgroup Directory C-9 Mandatory Attributes objectClass organizationName Optional Attributes businessCategory description seeAlso userPassword localityName stateOrProvinceName streetAddress physicalDeliveryOfficeName postalAddress postalCode postOfficeBox streetAddress destinationIndicator facsimileTelephoneNumber internationaliSDNNumber preferredDeliveryMethod registeredAddress telephoneNumber teletexTerminalIdentifier telexNumber x121Address Naming Rules Use the organizationName attribute for naming. Structure Rules An organization entry does not need to have any superior entry. However, if it does, then the immediately superior entry must be of one of the following object classes: country locality An organization entry is also permitted immediately beneath the root of the workgroup directory. C-10 Default Structure Rules for the Workgroup Directory C.1.13 organizationAlias The organizationAlias alias object class is used to define alias entries that represent organizations. Mandatory Attributes objectClass aliasedObjectName Optional Attributes None. Naming Rules Use the organizationName attribute for naming. Structure Rules An organizationAlias entry can have an immediately superior entry that is one of the following object classes: country locality organization organizationalUnit An organizationAlias entry can also be immediately beneath the logical root of the workgroup directory. C.1.14 organizationalPerson The organizationalPerson object class is used to define entries that represent people employed by, or associated with, an organization. Digital recommends that you use the organizationalPerson class as the basis of entries representing your employees. When you create an entry of the organizationalPerson class, you must specify the objectClass as follows: ... objectClass=(organizationalPerson) Mandatory Attributes objectClass commonName surname Default Structure Rules for the Workgroup Directory C-11 Optional Attributes description organizationalUnitName seeAlso telephoneNumber title userPassword localityName stateOrProvinceName streetAddress physicalDeliveryOfficeName postalAddress postalCode postOfficeBox destinationIndicator facsimileTelephoneNumber internationaliSDNNumber preferredDeliveryMethod registeredAddress teletexTerminalIdentifier telexNumber x121Address Naming Rules Use the commonName attribute for naming. Structure Rules The organizationalPerson entries must have an immediately superior entry of one of the following object classes: organization organizationalUnit locality An organizationalPerson entry is not permitted immediately beneath the root of the workgroup directory. C.1.15 organizationalPersonAlias The organizationalPersonAlias alias object class is used to define alias entries that represent people within an organization. C-12 Default Structure Rules for the Workgroup Directory Mandatory Attributes objectClass commonName aliasedObjectName Optional Attributes None. Naming Rules Use the commonName attribute for naming. Structure Rules An organizationalPersonAlias entry must have an immediately superior entry that is one of the following object classes: organization organizationalUnit locality An organizationalPersonAlias entry cannot be immediately beneath the logical root of the workgroup directory. C.1.16 organizationalRole The organizationalRole object class is used to define entries in the workgroup directory that represent a position or a role within an organization. An organizational role is normally considered to be filled by a particular person or a software application, but over its lifetime the role could be filled by many different people or applications in succession. Mandatory Attributes objectClass commonName Optional Attributes description organizationalUnitName seeAlso preferredDeliveryMethod roleOccupant localityName stateOrProvinceName streetAddress physicalDeliveryOfficeName Default Structure Rules for the Workgroup Directory C-13 postalAddress postalCode postOfficeBox destinationIndicator facsimileTelephoneNumber internationaliSDNNumber registeredAddress telephoneNumber teletexTerminalIdentifier telexNumber x121Address Naming Rules Use the commonName attribute for naming. Structure Rules A directory entry of the object class organizationalRole must have an immediately superior entry of one of the following object classes: organization organizationalUnit An organizationalRole entry is not permitted immediately beneath the root of the workgroup directory. C.1.17 organizationalRoleAlias The organizationalRoleAlias alias object class is used to define alias entries that represent organizational roles within an organization. For example, the entry might be used to provide an alias for an entry representing a team leader or manager. Mandatory Attributes objectClass commonName aliasedObjectName Optional Attributes None. Naming Rules Use the commonName for naming. C-14 Default Structure Rules for the Workgroup Directory Structure Rules An organizationalRoleAlias entry must have an immediately superior entry that is one of the following object classes: locality organization organizationalUnit An organizationalRoleAlias entry cannot be immediately beneath the logical root of the workgroup directory. C.1.18 organizationalUnit The organizationalUnit object class is used to define entries that represent subdivisions of organizations, such as departments, offices, or branches. For more information, see organization object class. Mandatory Attributes objectClass organizationalUnitName Optional Attributes businessCategory description seeAlso userPassword localityName stateOrProvinceName streetAddress physicalDeliveryOfficeName postalAddress postalCode postOfficeBox destinationIndicator facsimileTelephoneNumber internationaliSDNNumber registeredAddress telephoneNumber teletexTerminalIdentifier telexNumber x121Address Naming Rules Use the organizationalUnitName for naming. Default Structure Rules for the Workgroup Directory C-15 Structure Rules A directory entry of the object class organizationalUnit must have an immediately superior entry of one of the following object classes: locality organization organizationalUnit An organizationalUnit entry is not permitted as an immediate subordinate of the root of the workgroup directory. C.1.19 organizationalUnitAlias The organizationalUnitAlias alias object class is used to define alias entries that represent organizational units within an organization. Mandatory Attributes objectClass organizationalUnitName aliasedObjectName Optional Attributes None. Naming Rules Use the organizationalUnitName attribute for naming. Structure Rules An organizationalUnitAlias entry must have an immediately superior entry that is one of the following object classes: locality organization organizationalUnit An organizationalUnitAlias entry cannot be immediately beneath the logical root of the workgroup directory. C-16 Default Structure Rules for the Workgroup Directory C.1.20 residentialPerson The residentialPerson object class is used to define entries that represent people in the residential environment, such as the resident of a particular address. When you create an entry of the residentialPerson class, you must specify the objectClass as follows: ... objectClass=(residentialPerson) For more information, see organizationalPerson object class. Mandatory Attributes objectClass commonName surname localityName Optional Attributes businessCategory description preferredDeliveryMethod seeAlso telephoneNumber userPassword localityName stateOrProvinceName streetAddress physicalDeliveryOfficeName postalAddress postalCode postOfficeBox destinationIndicator facsimileTelephoneNumber internationaliSDNNumber registeredAddress telephoneNumber teletexTerminalIdentifier telexNumber x121Address Naming Rules Use the commonName attribute for naming. You can also use the streetAddress attribute for naming. Default Structure Rules for the Workgroup Directory C-17 Structure Rules The residentialPerson entries must have an immediately superior entry of the locality object class. A residentialPerson entry is not permitted immediately beneath the root of the workgroup directory. C.1.21 residentialPersonAlias The residentialPersonAlias alias object class is used to define alias entries that represent people in a residential or domestic context as the residents of a locality. Mandatory Attributes objectClass commonName aliasedObjectName Optional Attributes seeAlso Naming Rules Use the commonName attribute for naming. The streetAddress attribute can be used as an optional second naming attribute. Structure Rules A residentialPersonAlias entry must have an immediately superior entry of the locality object class. A residentialPersonAlias entry cannot be immediately beneath the logical root of the workgroup directory. C.1.22 top The top class is an abstract object class. You do not create entries of the top class itself. It is a superclass of other object class definitions. This means that other object classes inherit the mandatory attribute objectClass. Mandatory Attributes objectClass C-18 Default Structure Rules for the Workgroup Directory C.2 Attribute Types The following subsections each describe an attribute type defined in one of the /var/dxd*.sc files. Attributes are used to associate specific pieces of information with the object classes defined in Section C.1. Each attribute definition specifies an attribute name, and associates with it an X.500 attribute syntax and one or more descriptive labels. The .sc files define the attribute types and associates with each an attribute name and, optionally, one or more abbreviations or labels, and the X.500 syntax used for the attribute value. Not all of the attributes in the .sc files are documented. Specifically, attributes defined quipu and cosine are likely to be relevant only if you interoperate with those implementations. In that case, refer to the documentation provided with those implementations. C.2.1 aliasedObjectName Every alias entry has an aliasedObjectName attribute. The attribute specifies the name of the directory entry for which this alias entry provides an alias name. Attribute Syntax The syntax for this attribute type is distinguishedNameSyntax. For example: aliasedObjectName="/C=US/O=Abacus/OU=Sales" The value of this attribute should be the distinguished name of an entry in the workgroup directory. The InfoBroker Server does not verify that the distinguished name actually exists in the workgroup directory until a user tries to use the alias name. If the alias name does not resolve to the distinguished name of an entry, the InfoBroker Server returns an error. Note: Do not specify the name of another alias entry as the value of the aliasedObjectName attribute. Default Structure Rules for the Workgroup Directory C-19 Labels aliasedObjectName For example: aliasedObjectName=/c=US/o=ACME C.2.2 businessCategory This attribute specifies information concerning the occupation or field of interest of an object such as a person or organization. A businessCategory can be up to 128 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, businessCategory="Retail". This attribute specifies that it supports matching rules that are not case sensitive. Labels businessCategory For example: businessCategory=Retail C.2.3 commonName This attribute specifies a name by which an object is usually known. For example, the common name of a person might be John Smith. A common name should follow the conventions of the culture of the object represented. For example, you can use characters such as ö, à, é, and ß if they usually form part of a name for an object. Similarly, a person's family name may be placed first or last, according to the conventions usually applied to that person's name. A commonName can be up to 64 characters long. C-20 Default Structure Rules for the Workgroup Directory Attribute Syntax The syntax for this attribute type is stringSyntax, for example, commonName ="John Smith". This attribute specifies that it supports matching rules that are not case sensitive. For example, a search for commonName="John Smith" would succeed in finding an entry called commonName="john smith". Labels cn commonName For example: cn="John Smith" C.2.4 countryName This attribute specifies the international code that represents a country's name. The list of codes supported by this product is as follows: AD AE AF AG AL AN AO AQ AR AS AT AU BB BD BE BG BH BI BJ BM BN BO BR BS BT BU BV BW BY BZ CA CC CF CG CH CI CK CL CM CN CO CR CS CT CU CV CX CY DD DE DJ DK DM DO DZ EC EG EH ES ET FI FJ FK FO FR GA GB GD GF GH GI GL GM GN GP GQ GR GT GU GW GY HK HM HN HT HU HV ID IE IL IN IO IQ IR IS IT JM JO JP JT KE KH KI KM KN KP KR KW KY LA LB LC LI LK LR LS LU LY MA MC MG MI ML MN MO MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NQ NR NT NU NZ OM PA PC PE PF PG PH PK PL PM PN PR PT PU PY QA RE RO RW SA SB SC SD SE SG SH SJ SL SM SN SO SR ST SU SV SY SZ TC TD TG TH TK TN TO TP TR TT TV TW TZ UA UG US UY VA VC VE VG VI VN VU WF WK WS YD YE YU ZA ZM ZR ZS ZW Attribute Syntax The value of the countryName attribute must be a two-letter code chosen from International Standard 3166. For example, the value US is the correct code for the United States of America. It does not matter whether the country code is specified in uppercase or lowercase. Default Structure Rules for the Workgroup Directory C-21 Labels c country countryName For example: c=US C.2.5 description Use the description attribute to provide descriptive information about an object. The description can be up to 1024 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax. For example, an entry representing a distribution list could have the associated description, "distribution list for sales figures, forecasts, and quarterly reports." This attribute specifies it supports matching rules that are not case sensitive. For example, description=BIG matches description=Big. Labels description For example: description=Big C.2.6 decMailWorksUserName This attribute specifies the MailWorks user name for a person. For example, the MAILworks user name for Bob Adams might be adams. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, decMailWorksUserName = "adams", . Labels decMailWorksUserName C-22 Default Structure Rules for the Workgroup Directory C.2.7 decMRaddress This attribute specifies the Message Router mail address. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, decMRaddress = "adams@zko", . Labels decMRaddress C.2.8 decPMAddress This attribute specifies the DEC MAILbus Postmaster address. Attribute Syntax The syntax for this attribute type is StringSyntax. Labels decPMAddress C.2.9 decPreferredMailAddress This attribute specifies the preferred mail address for a person. Attribute Syntax The syntax for this attribute type is objectIdentifierSyntax. This entry is an object identifier (OID) number that points to a mail address as follows: 1.3.24.10.1.1 decMRaddress 2.6.5.2.6 mhsORAddresses 0.9.2342.19200300.100.rfc822Mailbox 1.3.24.10.1.3 decMailWorksUserName An OID can also have the format of {1 3 24 10 1 1}, where spaces replace the periods and the OID number is enclosed in braces. Labels decPreferredMailAddress Default Structure Rules for the Workgroup Directory C-23 C.2.10 destinationIndicator This attribute specifies the country and city associated with the named object, the addressee, required to provide the Public Telegram Service, according to CCITT Recommendations F.1 and F.3. Attribute Syntax The syntax for this attribute type is a string of alphabetical characters from the printableString character set. Labels dest destinationIndicator For example: destinationIndicator=abc C.2.11 facsimileTelephoneNumber This attribute specifies a telephone number for a facsimile terminal associated with the named object. Attribute Syntax The syntax for this attribute type is a string of numeric characters from the printableString character set. The standard format for facsimile telephone numbers should include some optional G3 Facsimiletex Non-Basic Parameters. However, this product does not support the optional parameters; this attribute is, in effect, the same as the telephoneNumber attribute. Labels faxno facsimileTelephoneNumber fax For example: facsimileTelephoneNumber="+81 3 347 9999" C-24 Default Structure Rules for the Workgroup Directory C.2.12 generationQualifier This attribute specifies a person's generational qualifier. For example, you could use this attribute to specify "Senior," "Junior," or "III." A generationQualifier can be up to 64 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, generationQualifier=Junior. This attribute specifies that it supports matching rules that are not case sensitive. For example, a search for generationQualifier=Junior would succeed in finding an entry with generationQualifier=junior. Labels generationQualifier For example: generationQualifier=Junior C.2.13 givenName The attribute specifies a given name. A given name should follow the conventions of the culture of the object represented. For example, you can use characters such as ö, à, é, and ß if they usually form part of a name for an object. A givenName can be up to 64 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, givenName=John. This attribute specifies that it supports matching rules that are not case sensitive. For example, a search for givenName=John would succeed in finding an entry with givenName=john. Default Structure Rules for the Workgroup Directory C-25 Labels givenName gn For example: givenName=John C.2.14 initials This attribute specifies the initials of a person's names. For example, as person called John Irvin Scott might have an initials attribute with the value J.I. If you use periods (.) to punctuate the initials, you must use quotation marks around the value. For example, initials="J.I.". Attribute Syntax The syntax for this attribute type is stringSyntax. This attribute specifies that it supports matching rules that are not case sensitive. Labels initials For example: initials="J.I." C.2.15 internationaliSDNNumber This attribute specifies an International ISDN Number associated with the named object. An international ISDN number can be up to 16 characters long. Attribute Syntax The syntax for this attribute type is numericStringSyntax, and should comply with the internationally agreed format for ISDN addresses, CCITT Recommendation E.164. C-26 Default Structure Rules for the Workgroup Directory Labels isdnno internationaliSDNnumber For example: ISDNno=12344321 C.2.16 localityName This attribute specifies the name of a locality or region, such as a city or county. A locality name can be up to 128 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, localityName="New York". This attribute specifies that it supports matching rules that are not case sensitive. For example, localityName="New York" matches localityName="new york". Labels l loc locality localityName For example: l="New York" C.2.17 member This attribute specifies a name or names associated with the entry of which this is an attribute. For example, an entry representing a committee could have a member attribute containing the names of the committee members. Note that there is no connection between a directory entry and any member attributes that specify that entry's distinguished name. For example, if you delete an entry or rename it, the member attribute is not updated. Attribute Syntax The syntax for this attribute type is distinguishedNameSyntax. Each distinguished name should be the name of a directory entry. Default Structure Rules for the Workgroup Directory C-27 Labels member For example: member="/c=FR/o=Reco/cn="Per Lebrun" C.2.18 mhsORAddresses This attribute specifies an X.400 messaging originator /recipient addresses. Attribute Syntax The syntax for this attribute type is mhs-or-address- syntax. For example: mhsORAddresses="C=US; A=Admin; P=Abacus; G=David; S=Townsend; OU1=Sales" Labels mhsORAddresses mhs-or-addresses For example: mhsORAddresses="C=US; A=Admin; P=Abacus; G=David; S=Townsend; OU1=Sales" C.2.19 objectClass This attribute specifies the object class and superclasses of the entry of which this is an attribute. This attribute must be present in every directory entry so that the Directory Service knows what rules to apply to an entry. Attribute Syntax The syntax for this attribute type is objectIdentifierSyntax, for example, {2 5 6 1}. The local directory uses user-friendly labels for input and output purposes, rather than object identifiers. For example, the local directory displays and allows you to use the label organization rather than its object identifier. For example, the local directory uses the label organization on menus, rather than displaying an object identifier. C-28 Default Structure Rules for the Workgroup Directory Labels objectClass For example: objectClass=organization C.2.20 organizationName This attribute specifies the name of an organization. Attribute values are strings chosen by the organization. An organizationName can be up to 64 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, organizationName="Acme Shoe Company". This attribute specifies that it supports matching rules that are not case sensitive. For example, organizationName="Acme Shoe Company" matches organizationName="ACME shoe company". Labels o orgname organizationName For example: o="ACME Shoe Company" C.2.21 organizationalUnitName This attribute specifies the name of an organizational unit, such as a team, group, department, or committee. This attribute can be used to name an entry, for example, an entry that represents a committee. It can also be used within an entry as background information, for example, a person entry could include an organizationalUnitName attribute that specifies what team they work for. An organizationalUnitName can be up to 64 characters long. Default Structure Rules for the Workgroup Directory C-29 Attribute Syntax The syntax for this attribute type is stringSyntax, for example, organizationalUnitName=Sales. This attribute specifies that it supports matching rules that are not case sensitive. For example, organizationalUnitName=Sales matches organizationalUnitName=sales. Labels ou organizationalUnitName ouname For example: ou=sales C.2.22 owner This attribute specifies the name of the owner of the object represented by the entry that contains this attribute. For example, an entry representing a computer could have an owner attribute that specifies the name of its system manager. Attribute Syntax The syntax for this attribute type is distinguishedNameSyntax. The distinguished name should be the name of a directory entry. Labels owner For example: owner="/c=NZ/o=THKS/cn=Jerry Thomson" C.2.23 physicalDeliveryOfficeName This attribute specifies the name of the city, town, or village where the physical delivery office is situated. An office name can be up to 128 characters long. C-30 Default Structure Rules for the Workgroup Directory Attribute Syntax The syntax for this attribute type is stringSyntax. For example, physicalDeliveryOfficeName="Hartman House". This attribute specifies that it supports matching rules that are not case sensitive. For example, physicalDeliveryOfficeName="Hartman House" matches physicalDeliveryOfficeName="hartman house". Labels pdoff physicalDeliveryOfficeName For example: physicalDeliveryOfficeName=Auckland See also postalAddress attribute, postalCode attribute, and postOfficeBox attribute. C.2.24 postalAddress This attribute specifies the address information required for the physical delivery of postal messages by the postal authority of the named object. An attribute value is limited to a maximum of 6 lines of no more than 30 characters each. The information contained in this address normally includes an addressee's name, street address, city, state or province name, and a postal code. A Post Office Box number could also be included. Attribute Syntax The syntax for this attribute type is postalAddressSyntax. Each line of the postal address is a printable string. Each line of the address ends with a comma. If you want a particular line to actually contain a comma, then use the single quotation marks to enclose that particular line. Labels Postaddr postalAddress postaddress Default Structure Rules for the Workgroup Directory C-31 For example: postalAddress="F.Burn, 3 Oak St, Bram, OHIO" The above example is an address containing four lines. The value is quoted, to clarify that this is one value. The following example is an address containing four lines, where the second line contains a comma: postalAddress="F.Burn, '3, Oak St', Bram, OHIO" If '3, Oak St' were not enclosed in single quotation marks, the local directory would treat the address as having five lines because of the presence of the comma after the 3. The quotation marks clarify that that comma is part of the value, rather than a separator between values. See also postalCode attribute, physicalDeliveryOfficeName attribute, and postOfficeBox attribute. C.2.25 postalCode This attribute specifies a postal code or zip code. If this attribute value is present, then it forms part of the object's postal address. A postal code can be up to 40 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, postalCode="PO21 4TG". This attribute specifies that it supports matching rules that are not case sensitive. For example, postalCode="PO21 4TG" matches postalCode="po21 4tg". Labels postcode postalCode For example: postalcode="PO21 4TG" See also postalAddress attribute, physicalDeliveryOfficeName attribute, and postOfficeBox attribute. C-32 Default Structure Rules for the Workgroup Directory C.2.26 postOfficeBox This attribute specifies the Post Office Box by which the object receives physical postal delivery. If this attribute value is present, then it is part of the object's postal address. A post office box can be up to 40 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, postOfficeBox="PO Box 13". This attribute specifies that it supports matching rules that are not case sensitive. For example, postOfficeBox="PO BOX 13" matches postOfficeBox="po box 13". Labels pobox postOfficeBox postbox For example: postOfficeBox="PO box 13" See also postalAddress attribute, postalCode attribute, and physicalDeliveryOfficeName attribute. C.2.27 preferredDeliveryMethod This attribute specifies preferred methods of physical message delivery. The attribute can be multivalued, with the most preferred method of delivery being the first value. A preferred delivery method value can be up to 9 characters long. Attribute Syntax The syntax for this attribute type is a sequence of single- digit integer values, for example, "3, 4, 1, 8". These values correspond to the different delivery methods as follows: 0 refers to any-delivery-method. 1 refers to mhs-delivery. 2 refers to physical-delivery. 3 refers to telex-delivery. Default Structure Rules for the Workgroup Directory C-33 4 refers to teletex-delivery. 5 refers to g3-facsimile-delivery. 6 refers to g4-facsimile-delivery. 7 refers to ia5-terminal-delivery. 8 refers to videotex-delivery. 9 refers to telephone-delivery. Labels prefdel preferredDeliveryMethod pdm For example: preferredDeliveryMethod=0 See also facsimileTelephoneNumber attribute, postalAddress attribute, telephoneNumber attribute, telexNumber attribute, and teletexTerminalIdentifier attribute. C.2.28 registeredAddress This attribute specifies an address associated with an object at a particular city location. The address is registered in the country in which the city is situated, and is used in the provision of the Public Telegram Service, according to CCITT Recommendation F.1. Attribute Syntax The syntax for this attribute type is postalAddressSyntax. Each line of the registered address is either a printable string or a T.61 string, up to 30 characters long. Each line of the address ends with a comma. If a particular line of the address includes a comma character, quote that line. Refer to postalAddressSyntax for further details. Labels regaddr registeredAddress For example: regesteredAddress=(3 Park Road, Littletown, Downshire, LT5 6SP) C-34 Default Structure Rules for the Workgroup Directory C.2.29 rfc822Mailbox This attribute specifies the Internet mail address. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, rfc822Mailbox = "adams@nodea.dec.com", . Labels mail rfc822Mailbox C.2.30 roleOccupant This attribute specifies the distinguished name of an entry that represents the occupant of an organizational role. For example, an organizationalRole entry representing a Sales Manager could have a roleOccupant attribute which specifies the name of the current sales manager. Attribute Syntax The syntax for this attribute type is distinguishedNameSyntax. The distinguished name should be the name of a directory entry. Labels role roleOccupant For example: roleOccupant=/c=AU/o=Schmessel/cn="Wolf Bayer" C.2.31 seeAlso This attribute specifies the names of other directory entries that are in some way related to the entry of which this is an attribute. For example, an entry representing a team could include a seeAlso attribute that specifies the names of related teams or team leaders. Attribute Syntax The syntax for this attribute type is distinguishedNameSyntax. The distinguished names should be the names of directory entries. Default Structure Rules for the Workgroup Directory C-35 Labels seeAlso For example: seeAlso=/c=GH/o=Health/cn="Greta Green" C.2.32 serialNumber This attribute specifies a serial number. For example, an entry representing a device such as a modem could have a serial number. A serialNumber can be up to 64 characters long. Attribute Syntax The syntax for this attribute type is printableStringSyntax, for example, serialNumber=BN315-803. Labels serialNumber For example: serialNumber=1342 C.2.33 stateOrProvinceName This attribute specifies the name of a state or province. For example, an entry representing a person can have a stateOrProvinceName attribute indicating what state a person lives or works in. A stateOrProvinceName can be up to 128 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, stateOrProvinceName=Ohio. This attribute specifies that it supports matching rules that are not case sensitive. For example, stateOrProvinceName=Ohio matches stateOrProvinceName=OHIO. Labels st state province stateOrProvinceName C-36 Default Structure Rules for the Workgroup Directory For example: stateOrProvinceName=Alaska C.2.34 streetAddress This attribute specifies a site for the local distribution and physical delivery in a postal address, road name, and house number. A streetAddress can be up to 128 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, "32, The Street". This attribute specifies that it supports matching rules that are not case sensitive. For example, "32, The Street" matches "32, the street" Labels addr streetAddress For example: streetAddress="4 Nuthatch, Banley" C.2.35 supportedApplicationContext This attribute specifies the object identifier of an application context. For example, an application entity could have a supportedApplicationContext attribute that specifies the contexts that the application entity supports. Attribute Syntax The syntax for this attribute type is objectIdentifierSyntax, for example, {2 13 3 19}. Labels context supportedApplicationContext For example: supportedApplicationContext={2 5 3 2} Default Structure Rules for the Workgroup Directory C-37 C.2.36 surname Specifies the surname, or family name, of a person. A surname can be up to 64 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, surname=Stevenson or surname=Müller. This attribute specifies that it supports matching rules that are not case sensitive. For example, surname=Stevenson matches surname=STEVENSON. Labels surname sn For example: surname=Bloggs C.2.37 telephoneNumber This attribute specifies a telephone number. Attribute Syntax The syntax for this attribute type is telephoneNumberSyntax, for example, telephoneNumber="+44 582 10101". The string should comply with the internationally agreed format for showing international telephone numbers. Labels tel telephoneNumber For example: telephoneNumber="+44 583 10101" C.2.38 teletexTerminalIdentifier This attribute specifies the teletex terminal identifier for a teletex terminal. Optionally, this attribute type can also specify the teletex terminal parameters. C-38 Default Structure Rules for the Workgroup Directory Attribute Syntax The syntax for this attribute type is a string of numeric characters from the printable string character set optionally followed by the value of the TeletexNonBasicParameters. An attribute value for the TeletexTerminalIdentifier attribute is a string that complies with CCITT Recommendation F.200, and an optional set that complies with CCITT Recommendation T.62. Labels ttxid teletexTerminalIdentifier For example: teletexTerminalIdentifier="12345" C.2.39 telexNumber This attribute specifies the telex number, country code, and answerback code of a telex terminal. Attribute Syntax The syntax for this attribute type is a sequence of three strings of characters from the printable string character set. The strings correspond to the following: Telex number Answerback Country code For example, "12434 ABACUS US". Labels telexno telexNumber telex For example: telexNumber="12434 ABACUS US" Default Structure Rules for the Workgroup Directory C-39 C.2.40 title This attribute specifies a position, function, or occupational qualification of an object. For example, a person could have a title of "manager" or "chief designer," and a device could have a title such as "disk drive." A title can be up to 64 characters long. Attribute Syntax The syntax for this attribute type is stringSyntax, for example, title="Sales Manager". This attribute specifies that it supports matching rules that are not case sensitive. For example, title="Sales Manager" matches title="SALES MANAGER". Labels title For example: title=Boss C.2.41 userPassword This attribute specifies a password. Directory applications use the userPassword attribute to authenticate users to DSAs, and DSAs use passwords to verify each other's identities. A userPassword can be up to 128 characters long. Attribute Syntax The syntax for this attribute type is userPasswordSyntax. User passwords are stored as octet strings. A password can be up to 128 characters long. Usually, passwords are protected by access controls, so that values are not displayed. However, if there are no such controls, passwords can be displayed as text or as an octet string, depending on the application that is displaying them. C-40 Default Structure Rules for the Workgroup Directory Labels password userPassword pwd For example: userPassword=tribblet C.2.42 x121Address This attribute specifies a network address of the named object. An X121Address can be up to 15 characters long. Attribute Syntax The syntax for this attribute type is a string of numeric characters that complies with CCITT Recommendation X.121. Labels x121Address For example: x121Address="234273412345" C.3 X.500 Attribute Value Syntaxes The following subsections describe the X.500 attribute value syntaxes referenced in Section C.2. C.3.1 countryNameSyntax Values of this syntax must be alphabetic country codes defined in ISO 3166. Each country code is two letters long. For example, GB and US. ISO 3166 is sometimes revised to reflect political changes. The list of codes supported by the Digital DSA is as follows: Default Structure Rules for the Workgroup Directory C-41 AD AE AF AG AL AN AO AQ AR AS AT AU BB BD BE BG BH BI BJ BM BN BO BR BS BT BU BV BW BY BZ CA CC CF CG CH CI CK CL CM CN CO CR CS CT CU CV CX CY DD DE DJ DK DM DO DZ EC EG EH ES ET FI FJ FK FO FR GA GB GD GF GH GI GL GM GN GP GQ GR GT GU GW GY HK HM HN HT HU HV ID IE IL IN IO IQ IR IS IT JM JO JP JT KE KH KI KM KN KP KR KW KY LA LB LC LI LK LR LS LU LY MA MC MG MI ML MN MO MQ MR MS MT MU MV MW MX MY MZ NA NC NE NF NG NI NL NO NP NQ NR NT NU NZ OM PA PC PE PF PG PH PK PL PM PN PR PT PU PY QA RE RO RW SA SB SC SD SE SG SH SJ SL SM SN SO SR ST SU SV SY SZ TC TD TG TH TK TN TO TP TR TT TV TW TZ UA UG US UY VA VC VE VG VI VN VU WF WK WS YD YE YU ZA ZM ZR ZS ZW Refer to ISO 3166 for details of what each code stands for. C.3.2 distinguishedNameSyntax This allows the attribute value to have the syntax of a distinguished name. For example: /countryName=US/organizationName=ACME/organizationalUnitName=Sales C.3.3 ORAddress This allows an attribute value to have the syntax of an X.400 originator/recipient address, for example: "C=US; A=Admin; P=Abacus; O=Abacus; G=David; S=Townsend; OU1=Legal" C.3.4 numericStringSyntax This allows the attribute value to have the syntax of a string of numeric characters, for example, "85 14 7 40 243". C.3.5 objectIdentifierSyntax This allows the attribute value to have the syntax of an object identifier. An object identifier is an ordered sequence of integers in braces. For example, {2 5 6 2} is the object identifier for the country object class. C-42 Default Structure Rules for the Workgroup Directory C.3.6 postalAddressSyntax This syntax allows the representation of a postal address of up to six lines. Each line of the address can contain up to 30 characters of the printable string or T.61 string character sets. The DXIM external representation of the address uses the comma character to separate lines. For example; "The Wicket, 14 Ace Avenue, Lower Dingle, nr Tatton, Hampshire, England" C.3.7 printableStringSyntax This allows the attribute value to have the syntax of a string of characters from the printable string character set. C.3.8 stringSyntax This syntax allows you to represent a string using the printable character set or the T.61 character set. The T.61 character set includes characters such as é and ç. C.3.9 telephoneNumberSyntax This allows the attribute value to have the syntax of a string of numeric characters from the printable string character set. C.3.10 userPasswordSyntax This syntax allows the representation of user passwords. Default Structure Rules for the Workgroup Directory C-43 D _________________________________________________________________ LDAP Predefined Constants This appendix lists the following types of LDAP predefined constants: o LDAP Error Processing (Section D.1) o Modification Constants (Section D.2) o Network-Transport Constants (Section D.3) D.1 LDAP Error Processing This section contains information on the following: o The InfoBroker Log Files (Section D.1.1) o LDAP Return Values (Section D.1.2) D.1.1 The InfoBroker Log Files If the LDAP functions return error messages that you do not understand, the following information may help to solve the problem: o If the problem appears to have originated in the X.500 Directory Service (many of the LDAP error messages are translations of X.500 error messages), then see the DEC X.500 Directory Service Problem Solving manual for more information. o Check the /var/ibx/ibx.log and the /var/ibx/ibx_xxxx.log files. o Run the server at your terminal with error logging turned on. For More Information On log files and running the server at your terminal (Appendix B) LDAP Predefined Constants D-1 D.1.2 LDAP Return Values These are the standard return values for the LDAP functions (for more information on the numeric values of these constants, see the libldap.h file): LDAP_SUCCESS Explanation: The function executed successfully. LDAP_ALIAS_DEREF_PROBLEM LDAP_ALIAS_PROBLEM Explanation: There was a problem in an alias referenced by the user's request. User Action: Notify your X.500 system administrator, and provide the name of the directory entry that you were trying to access. LDAP_ALREADY_EXISTS Explanation: The user attempted to create an entry that already exists in the DIT. User Action: Check with an X.500 DSA regarding preexisting distinguished names. LDAP_AUTH_METHOD_NOT_SUPPORTED Explanation: The X.500 Directory Service could not perform the action because the request was not signed. User Action: Try either of the following actions: o Try the call to ldapBind again, and pass parameters for an X.500 username and password. o Report this error to your X.500 administrator. LDAP_BUSY Explanation: The X.500 DSA is busy. User Action: Try the function call later. If the problem persists for a long period of time, report the problem to your X.500 administrator. D-2 LDAP Predefined Constants LDAP_CONSTRAINT_VIOLATION Explanation: An attribute name or value does not conform to the constraints placed on it. User Action: Check the attribute's syntax in the directory's schema. Make sure that you have the correct spelling of the attribute name, and make sure that you have used the correct syntax for specifying a value for that attribute. LDAP_DECODING_ERROR Explanation: o The client library was unable to parse the response sent from the InfoBroker server. o The DSA returned an unknown error. o A filter in a search request contained an invalid type field. User Action: Try either of the following actions: o Make sure that the InfoBroker server and the client are using the same version of LDAP. (The InfoBroker server supports Versions 1 and 2 [V1 and V2] of the protocol.) You can find LDAP version information in the /var/ibx /ibx.log and /var/ibx/ibx_xxxx.log files. If you are comfortable with digging deeper into the underlying LDAP code, you can stop and then start the server with logging turned on, and then examine the contents of the protocol buffer, which is displayed as part of the debugging information. If you do not feel comfortable digging deeper into the underlying LDAP code, call your Digital support person for help. o Check the /var/ibx/ibx.log and the /var/ibx/ibx_xxxx.log files for a clearer explanation in an error produced by the DSA. If you can reproduce the problem, stop and then start the InfoBroker server with debugging turned on and observer the error occurring. For more information, see the DEC X.500 Directory Service Problem Solving manual. LDAP Predefined Constants D-3 LDAP_ENCODING_ERROR Explanation: o The client library was unable to encode your request into a valid LDAP request. o The client library ran out of memory while trying to allocate a buffer for your request. User Action: Try either of these actions: o Check the parameters in your LDAP call and make sure that they are specified in the correct order. o Increase your swap space on the client system. LDAP_INAPPROPRIATE_AUTH Explanation: You do not have sufficient access to the DSA to perform the action. User Action: Call the ldapBind function again, specifying the a username and password that has sufficient access privileges. If the problem persists, consult your X.500 administrator. LDAP_INAPPROPRIATE_MATCHING Explanation: The match rule is undefined for this attribute type. User Action: Check the directory's schema for the exact syntax of the attribute name. (An example of an action that would generate this error: trying to perform an approximate- match operation on a jpegPhoto attribute value, which does not support matching operations.) LDAP_INSUFFICIENT_ACCESS Explanation: You do not have access to perform the requested action. User Action: Call the ldapBind function again, specifying the a username and password that has sufficient access privileges. If the problem persists, consult your X.500 administrator. D-4 LDAP Predefined Constants LDAP_INVALID_CREDENTIALS Explanation: Your supplied credentials are invalid. User Action: Call the ldapBind function again, specifying the a username and password that has sufficient access privileges. If the problem persists, consult your X.500 administrator. LDAP_INVALID_DN_SYNTAX Explanation: Your supplied distinguished name is invalid. User Action: Check the syntax of the distinguished name that you provided. LDAP requires that distinguished names be in this format: (cn="Joan Smith", ou=marketing, o="Big Corporation", c=us) LDAP_INVALID_SYNTAX Explanation: The attribute value does not conform to the attribute name's syntax as defined in the schema. User Action: Check the directory's schema for the attribute type. (As an example, you generate this error if you attempt to assign a string to a jpegPhoto attribute.) LDAP_LOCAL_ERROR Explanation: The client library was unable to allocate memory to build your request. User Action: Either increase the memory on your client system, or reduce the memory required to run your client application. LDAP_LOOP_DETECT Explanation: The X.500 DSA detected a loop. User Action: Report this error to your X.500 administrator. LDAP_NAMING_VIOLATION Explanation: Your requested modification would leave the DIT improperly structured. User Action: Report this error to your X.500 administrator. LDAP Predefined Constants D-5 LDAP_NO_OBJECT_CLASS_MODS Explanation: Modifications to an entry's object class are not allowed. User Action: Call the LDAP modify function again, but do not attempt to modify an object class. LDAP_NO_SUCH_ATTRIBUTE Explanation: You requested that an attribute be returned that does not exist in the returned directory entry. User Action: Call the LDAP search function again, but use existing attribute names. LDAP_NO_SUCH_OBJECT Explanation: Your requested entry does not exist. User Action: Try any of the following actions: o Check the search base to make sure that you are searching the correct subtree. o Check the spelling of the attribute values in the search filters. o Try using wildcard characters in the attribute values in your search filters. (For example, instead of "sn=Crenshaw", try "sn=Crenshaw*".) o Try specifying approximate matches in your filters instead of exact matches. (For example, try "sn~=Crenshaw".) LDAP_NOT_ALLOWED_ON_NONLEAF Explanation: You attempted to modify an internal entry in the DIT, which is illegal. User Action: Report this error to your X.500 administrator. LDAP_NOT_ALLOWED_ON_RDN Explanation: Your modification would alter an RDN in the entry's distinguished name. User Action: Make sure that you use only the ldapModifyRDN function to modify an entry's relative distinguished name. D-6 LDAP Predefined Constants LDAP_OBJECT_CLASS_VIOLATION Explanation: Your modification would leave the entry inconsistent with its object-class definition. User Action: Check the entry's object class or classes, and check the directory's schema to determine the legal attribute names for a given object class. LDAP_OPERATIONS_ERROR Explanation: The InfoBroker server ran out of resources. User Action: Usually, this error means that the server ran out of memory. Try any of the following actions: o Check the error logs to determine the exact resource problem. o Increase the swap space on the InfoBroker server. (See your InfoBroker system administrator.) o Increase the process slots on the InfoBroker server. (See your InfoBroker system administrator.) LDAP_OTHER Explanation: X.500 returned one of these errors: DS_E_ AFFECTS_MULTIPLE_DSA, DS_E_INVALID_REF, or DS_E_UNAVAILABLE_ CRIT_EXT. User Action: Report this error to your X.500 administrator. LDAP_PROTOCOL_ERROR Explanation: The InfoBroker server was unable to parse the request. User Action: Try either of the following actions: o Check the error logs to see which field in the request failed. o Make sure that your client and server are using the same version of the LDAP protocol; the InfoBroker server currently supports Versions 1 and 2 (V1 and V2) of the protocol. LDAP Predefined Constants D-7 LDAP_SERVER_DOWN Explanation: The InfoBroker server not running. User Action: Either the InfoBroker server is not running, or one of the parameters to ldapBind is incorrect. In the call to ldapBind, check that the host name, the transport, and the port or task name are correct. LDAP_SIZELIMIT_EXCEEDED Explanation: There are more entries than were returned that matched the requested search filter(s). User Action: The server attaches this message to the chain of directory entries returned as the result of a search operation. Try any of the following actions: o In your call to one of the search functions, increase the size-limit parameter to allow more entries to be returned. o Modify the dua.defaults file on the InfoBroker server to increase the number of entries to be returned. o Narrow your search so that fewer entries are returned by specifying a filter that would remove some of the entries or by narrowing the search base (starting lower in the tree). LDAP_TIMELIMIT_EXCEEDED Explanation: The X.500 DSA was unable to complete the search in the allotted time. User Action: Try either of the following actions: o Increase the amount of time specified in a parameter of the search function or in the dua.defaults file on the server's system. o Use the filter or the base to narrow the search parameters or the area of the tree you are searching. D-8 LDAP Predefined Constants LDAP_TYPE_OR_VALUE_EXISTS Explanation: The attribute name and/or value pair already exist in the entry the user attempted to modify. User Action: Try either of the following actions: o Verify the distinguished name of the directory entry, so that you make sure that you are modifying the correct one. o Remove the bad attribute name and value pair, and try the modification again. LDAP_UNAVAILABLE Explanation: The bind to the X.500 DSA was unsuccessful. User Action: Try any of the following actions: o Check that the DSA is up and running. o Check the dua.defaults file on the InfoBroker's system, to verify that the DSA information is correct. o Run the X.500 utility dxim on the InfoBroker server's system to see if you can connect to a DSA. o Check the /var/ibx/ibx.log and the /var/ibx/ibx_xxxx.log files. o Report the error to your X.500 administrator. LDAP_UNDEFINED_TYPE Explanation: The attribute type is undefined. User Action: Try any of the following actions: o Check your spelling of the attribute type. o Check the schema to make sure that you are attempting to access or specify a valid type. o Remove the illegal attribute name and type from the request. LDAP Predefined Constants D-9 LDAP_UNWILLING_TO_PERFORM Explanation: o You attempted to modify the InfoBroker server's workgroup directory. o Your requested modification would require more resources than the DSA has. o LDAP is having a Bad Hair Day. User Action: To change entries in a workgroup directory, please edit the workgroup-directory file using a text editor. You cannot use LDAP functions to alter this file. If the X.500 DSA does not have the resources to complete the modification, then contact your X.500 administrator. Or, change its brand of hair spray. D.2 Modification Constants You can specify these constants as a parameter to the ldapModifyW function: LDAP_MOD_ADD Add an attribute value to the entry. LDAP_MOD_DELETE Delete an attribute value from the entry. LDAP_MOD_REPLACE Replace an existing attribute value in the entry with another attribute value. LDAP_MOD_BVALUES The attribute value in the entry is binary data. D.3 Network-Transport Constants You can specify these constants as parameters to the ldapOpen function: LDAP_DECNET A DECnet network. LDAP_DECNET_SERVER Endpoint name for DECnet, whose value is "LDAP_SERVER". LDAP_TCPIP A TCP/IP network. D-10 LDAP Predefined Constants LDAP_TCPIP_SERVER Endpoint for TCP/IP, whose value translates to the port number "389". D.4 Search-Scope Constants You can specify these search-scope constants as a parameter to the ldapSearchReqst, ldapSearchReqstLim, ldapSearchW, or ldapSearchWLim function: LDAP_SCOPE_BASE Search only the directory entry specified by the base parameter; this is also called the "search base." LDAP_SCOPE_ Search the base and one level down in ONELEVEL the tree. LDAP_SCOPE_SUBTREE Search the whole subtree that begins with the search-base directory entry. LDAP Predefined Constants D-11 _________________________________________________________________ Index A configuration, web browsers, _______________________________ 5-15 to 5-23 Applications, LDAP Constants, LDAP See LDAP applications See LDAP constants attribute customized schema, 5-8 to 5-21 creating, 5-12 attribute definition, example, 5-9 creating, 5-12 defined, 1-7 attribute definition, example auxiliary class , 5-9 defined, 5-8 class definition, creating, C 5-10 to 5-14 _______________________________ compiling, 5-14 class defined, 1-10 creating, 5-10 to 5-14 implications of, 1-10 examples, 5-11 installation roadmap, 2-11 defined, 1-7 object identifier, defined, client, V1.0A 5-9 installing and configuring, propagating changes to the 4-2 to 4-4 client, 5-14 Client, V1.0A .sc files, defined, 5-8 See V1.0A client configuration D______________________________ fun hyperlinks, 5-23 DECnet configuration, InfoBroker installation requirement, for use with X.500, 5-1 to V1.0A client, 4-3 5-3 server task, changing, V1.0A network requirements of X.500 client, 4-6 , 5-2 directory using non-Digital X.500, 5-3 conceptual overview, 1-5 to configuration, look-up daemon, 1-12 5-15 to 5-23 defined, 1-5 Index-1 Directory Service Agent (DSA) defined, 5-1 I______________________________ disk space InfoBroker required, InfoBroker server See InfoBroker, overview of installation, 3-3 See installing InfoBroker required, V1.0A client server installation, 4-3 distinguished name See installing V1.0A client defined, 1-8 InfoBroker client V1.0A figure, 1-8 installation roadmap, 2-5 DSA InfoBroker, configuration of See Directory Service Agent with X.500, 5-1 to 5-3 (DSA) InfoBroker, overview of, 1-1 dxim X.500 command, 5-7 to 1-12 dxim X.500 utility, 5-7 distinguished name, figure, 1-8 E entries, hierarchical _______________________________ organization of, figure, entry 1-7 attribute, defined, 1-7 LDAP, introducing, 1-12 class, defined, 1-7 product components, figure, creation of, 5-4 to 5-7 1-2 defined, 1-5 schema, defined, 1-9 distinguished name X.500, defined, 1-6 defined, 1-8 installing InfoBroker server, figure, 1-8 3-1 to 3-7 hierarchical organization of, disk-space requirement, 3-3 1-7, 5-3 hardware requirements, 3-2 schema, defined, 1-9 InfoBroker subsets, 3-6 syntax of, 5-4 oidtable.* files saved, 3-5 postinstallation procedure, F______________________________ 3-7 Functions, LDAP preparing for, 3-1 See LDAP functions procedure, 3-4 to 3-7 software requirements, 3-2 H subsets, preinstallation _______________________________ requirements, 3-2 hardware verifying installation, 3-7 required, InfoBroker server installing the look-up daemon, installation, 3-2 3-4 to 3-7 installing V1.0A client, 4-4 disk-space requirements, 4-3 information requirements, 4-3 memory requirements, 4-3 Index-2 installing V1.0A client LDAP functions (cont'd) (cont'd) ldapGetValuesLen, LDAP-22 network requirements, 4-3 ldapModifyW, LDAP-24 reconfiguration after network ldapModrdnW, LDAP-26 change, 4-4 ldapMsgFree, LDAP-28 software requirements, 4-3 ldapNextAttribute, LDAP-29 installing, V1.0A client ldapNextEntry, LDAP-31 preparing for, 4-2 ldapOpen, LDAP-33 ldapPoll, LDAP-35 L______________________________ ldapSearchReqst, LDAP-36 LDAP ldapSearchReqstLim, LDAP-40 introducing, 1-12 ldapSearchResult, LDAP-44 LDAP applications ldapSearchW, LDAP-46 asynchronous searches, 6-8 ldapSearchWLim, LDAP-50 compiling and linking, 6-4 ldapUnbind, LDAP-54 creating and modifying ldapValueFree, LDAP-55 look-up daemon entries, 6-5 attributes, default display directory entries, modifying, of, 5-19 6-9 installing, 3-4 to 3-7 example, 6-11 introducing, 1-4 installation roadmap, 2-6 search base, 5-21 program development, 6-1 to search filters, 5-16 6-16 starting, 3-9 programming languages, 6-2 stopping, 3-11 reading binary attribute URL for browsers to open, values, 6-9 4-1 return values, D-1 to D-10 synchronous searches, 6-7 M______________________________ LDAP constants, D-1 to D-11 memory LDAP functions, LDAP-3 to required, V1.0A client LDAP-55 installation, 4-3 , A-1 Microsoft Windows ldapAbandon, LDAP-3 version required by V1.0A ldapAddW, LDAP-4 client, 4-3 ldapBind, LDAP-6 migration ldapCountEntries, LDAP-8 workgroup directory to X.500, ldapDelete, LDAP-9 ldapDeleteDNW, LDAP-10 5-7 ldapErrorToText, LDAP-12 workgroup directory to X.500, ldapExplodeDN, LDAP-13 installation roadmap, 2-14 ldapFirstAttribute, LDAP-15 ldapFirstEntry, LDAP-17 ldapGetDN, LDAP-19 ldapGetValues, LDAP-20 Index-3 server, InfoBroker (cont'd) O______________________________ restarting after schema object identifier (OID) customizatation, 3-11 defined, 5-9 starting, 3-8 to 3-9 OID with a workgroup directory See object identifier (OID) , 3-8 oidtable.* files with a workgroup directory saved during installation, and X.500, 3-9 3-5 with X.500, 3-8 OSF/1 stopping, 3-11 version required by troubleshooting, B-1 to B-3 InfoBroker, 3-2 software required, InfoBroker server R installation, 3-2 _______________________________ required, V1.0A client Return values, LDAP installation, 4-3 See LDAP constants standard schema defined, 1-10 S______________________________ using with X.500, .sc files installation roadmap, defined, 5-8 2-7 schema starting, InfoBroker server, See also customized schema 3-8 to 3-9 customized, 5-8 to 5-21 See also server, InfoBroker customized, installation after schema customization, roadmap, 2-11 3-11 customizing, implications of, starting, the look-up daemon, 1-10 3-9 defined, 1-9 stopping, InfoBroker server, standard, defined, 1-10 3-11 standard, installation stopping, look-up daemon, 3-11 roadmap, 2-7 structural class Search base defined, 5-8 look-up daemon, configuring, subsets 5-21 of the InfoBroker, 3-6 Search filters required, InfoBroker server look-up daemon, configuring, installation, 3-2 5-16 syntaxes server, InfoBroker reference material, C-41 files installed, A-1 installing, 3-1 to 3-7 release notes, location of, 3-1 Index-4 workgroup directory (cont'd) T______________________________ class, defined, 1-7 TCP/IP creating entries, 5-4 to 5-7 installation requirement, creation, installation V1.0A client, 4-3 roadmap, 2-5, 2-6 server port, changing, V1.0A creation, installation client, 4-5 roadmaps, 2-3 to 2-6 troubleshooting, InfoBroker customized schema, 5-8 to server, B-1 to B-3 5-21 customized schema, U______________________________ installation roadmap, URL 2-11 look-up daemon's, 4-1 distinguished name defined, 1-8 V figure, 1-8 _______________________________ entry V1.0A client defined, 1-5 files installed, A-5 example, 1-9 V1.0A client, running, 4-5 to hierarchical organization 4-6 of, 1-7 connection problems, solving, syntax, 5-4 4-5 example, 5-5 default DECnet task name, maximum number of entries, changing, 4-6 5-3 default TCP/IP port number, migrating to X.500, 5-7 changing, 4-5 installation roadmap, 2-14 W______________________________ overview, 1-5 to 1-12 web browser planning entry hierarchy, hyperlinks, fun configuration 5-3 of, 5-23 schema, defined, 1-9 installation roadmap, 2-3 standard classes, reference, using, 4-1 to 4-2 C-2 to C-18 Web browser starting the InfoBroker introducing, 1-3 server, 3-8 obtaining, xii web browsers X______________________________ configuration, 5-15 to 5-23 X.500 workgroup directory See also customized schema See also customized schema and workgroup directory and X.500 together, together, installation installation roadmap, roadmap, 2-9 2-9 attribute, defined, 1-7 attribute, defined, 1-7 Index-5 X.500 (cont'd) hierarchical organization auxiliary class, defined, of, 1-7 5-8 InfoBroker server, starting, class, defined, 1-7 3-8 configuring InfoBroker for migrating from workgroup use with, 5-1 to 5-3 directory, 5-7 customized schema, 5-8 to installation roadmap, 5-21 2-14 customized schema, network requirements of, 5-2 installation roadmap, non-Digital, configuration 2-11 issues, 5-3 defined, 1-6 schema, defined, 1-9 distinguished name structural class, defined, defined, 1-8 5-8 figure, 1-8 terminology overview, 1-5 to entry 1-12 defined, 1-5 using a standard schema, installation roadmap, 2-7 Index-6