InfoBroker_Server_____________________________ Administration Guide March 1998 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-Q5WNC-TE. Operating System: Digital UNIX Version 4.0A or higher Software Version: InfoBroker Server Version 2.2. InfoBroker Client Version 1.0A. Digital Equipment Corporation Maynard, Massachusetts __________________________________________________________ First Published, March 1994 Revised, December 1994 Revised, March 1995, Revised, March 1998 While Digital believes the information included in this publication is correct as of the date of publication, it is subject to change without notice. Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from Digital or an authorized sublicensor. Digital Equipment Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description. 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 1998. 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 in the United States and other countries, licensed exclusively by X/Open Company Ltd. 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-6 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-2 3.1.5 Register your Software License........... 3-3 3.2 Installation Procedure ...................... 3-3 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-4 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-7 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 3.8 Removing the InfoBroker Server and the Look-Up Daemon............................... 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 iv 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 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-5 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-8 5.3 Customizing Your Directory's Schema.......... 5-8 5.3.1 Assigning Object Identifiers to New Definitions.............................. 5-10 5.3.2 Adding Attribute and Class Definitions... 5-11 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 v 5.5.4 The Search Base and Other Directory Service Information...................... 5-22 5.6 What's Cool: the InfoBroker and a World Wide Web Server................................... 5-23 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 vi ldapErrorToText....................................LDAP-12 ldapExplodeDN......................................LDAP-13 ldapFirstAttribute.................................LDAP-15 ldapFirstEntry.....................................LDAP-17 ldapGetDN..........................................LDAP-19 ldapGetValues......................................LDAP-20 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-41 ldapSearchResult...................................LDAP-45 ldapSearchW........................................LDAP-47 ldapSearchWLim.....................................LDAP-51 ldapUnBind.........................................LDAP-55 ldapValueFree......................................LDAP-56 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 vii 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-5 C.1.6 deviceAlias.............................. C-5 C.1.7 groupOfNames............................. C-6 C.1.8 groupOfNamesAlias........................ C-7 C.1.9 locality................................. C-8 C.1.10 localityAlias............................ C-8 C.1.11 mhs-user................................. C-9 C.1.12 organization............................. C-10 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 viii 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 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 ix 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-6 6-1 Sample LDAP Application.................. 6-12 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-11 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 a Digital UNIX 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 a Digital UNIX 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. If a web browser is not already available on your system, you must obtain one. 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 xi a client 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. 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 Digital UNIX system managers with root permissions, who know Digital UNIX and its installation procedures, and who know PC networking and management. Parts I and II are intended for system managers. xii 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 Digital 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.) New InfoBroker Version 2.2 Features The only change from the previous version of InfoBroker is that InfoBroker is now Year 2000 compliant. 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. xiii __________________________________________________________ Target Title____________Audience____Provides_information_about... Digital X.500 Directory Managing Digital X.500 Directory service Directory Service. Services adminis- Managment trators 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. xiv __________________________________________________________ Chapter______Contents_____________________________________ 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. 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 Digital width UNIX 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. #______________Digital_UNIX_system_prompt.________________ xv 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 a Digital UNIX 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 a Digital UNIX 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. If a web browser is not available on your system, you must obtain one. 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. 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. InfoBroker Overview 1-3 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 applica- tion 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 a Digital UNIX system, which may be the same system running the server or another Digital UNIX 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. 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. 1-4 InfoBroker Overview 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). 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. InfoBroker Overview 1-5 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.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. 1-6 InfoBroker Overview 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". 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. InfoBroker Overview 1-7 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" 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. 1-8 InfoBroker Overview 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 Digital 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 1-10 InfoBroker Overview InfoBroker client, so that the users can search for and display the nonstandard information. If you are using a web browser to look up information, then you need to alter the look-up daemon's configura- tion 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. InfoBroker Overview 1-11 If you are using the InfoBroker in a small workgroup, and if your company has an existing X.500 implemen- tation 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 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. 1-12 InfoBroker Overview For More Information On LDAP (Chapter 6) InfoBroker Overview 1-13 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 configu- ration 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 Digital 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. If a web browser is not available on See the web your system, obtain one and install browser's it. documentation. Roadmaps Through This Document 2-3 __________________________________________________________ ____To_do_this...___________________________Read_this...__ 7. 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 Digital 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 users understand that they cannot on the modify or add entries to a workgroup InfoBroker directory using this client; they must icon. 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 Digital 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. Roadmaps Through This Document 2-11 __________________________________________________________ ____To_do_this..._____________________Read_this...________ 3. If your client users are using Section 3.5 web browsers, start the look-up daemon. 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 Digital 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 Digital 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. 2-12 Roadmaps Through This Document __________________________________________________________ ____To_do_this..._____________________Read_this...________ 6c. If your clients use your own Section 2.3, Steps LDAP client application, then 4-6 code, compile, link, and run your application. 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 then stop and then restart the 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 Digital 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) o Removing the server and the Look-Up Daemon (Section 3.8) 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/IBX220.release_ notes or IBX220_release_notes.ps. 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 Digital UNIX Version 4.0D, or later. Digital UNIX Version 4.0A may be used, provided you apply patch 123.00 (OSF405-400151). Digital UNIX V4.0B may be used, provided you apply patch 44.00 (OSF410-400151). Digital UNIX V4.0C may be used, provided you apply patch 70.00 (OSF415-400151). 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 DXDABASE (Digital X.500 Base) V3.1, or later. You do not need an 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 Digital UNIX system documentation for information about backing up your system. 3-2 Server Installation, Startup, and Termination 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. 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 Digital UNIX 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. Server Installation, Startup, and Termination 3-3 3.2.1 Step 1: Log in to the root Account Log in to the root account on the Digital UNIX 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 Digital UNIX 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.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.2 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. The following command examples show to delete the old kit. 3-4 Server Installation, Startup, and Termination Use the following command to find out which subsets are installed: # setld -i | grep IBX IBXLOOKUP212 installed InfoBroker Lookup Daemon for Digital UNIX Version V2.1A-2 IBXOAPI212 installed API: InfoBroker for Digital UNIX Version V2.1A-2 IBXOMAN212 installed Ref Pages: InfoBroker for Digital UNIX Version V2.1A-2 IBXOSERV212 installed InfoBroker Server for Digital UNIX Version V2.1A-2 Once you have identified which subsets are installed, you can delete them, for example: # setld -d IBXOSERV212 IBXOMAN212 IBXOAPI212 IBXLOOKUP212 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: # setld -l . 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. 1 API: InfoBroker for Digital UNIX Version V2.2-3) 2 InfoBroker Lookup Daemon for Digital UNIX Version V2.2-3) 3 InfoBroker Server for Digital UNIX Version V2.2-3) 4 Ref Pages: InfoBroker for Digital UNIX Version V2.2-3) Or you may choose one of the following options: 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): 5 Server Installation, Startup, and Termination 3-5 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 The InfoBroker server runtime, admin- Digital UNIX istration, and load tools. The server is ready to be started after the setld script is completed. 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. (continued on next page) 3-6 Server Installation, Startup, and Termination Table_3-1_(Cont.)_Optional_Subsets________________________ Subset___________Contents_and_Use_________________________ 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 IBXOAPI220 installed API: InfoBroker for Digital UNIX Version V2.2-3 IBXLOOKUP220 installed InfoBroker Lookup Daemon for Digital UNIX Version V2.2-3 IBXOSERV220 installed InfoBroker Server for Digital Unix Version V2.2-3 IBXOMAN220 installed Ref Pages: InfoBroker for Digital UNIX Version V2.2-3 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. Server Installation, Startup, and Termination 3-7 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, the X.500 DUA defaults file must be configured to point to an X.500 DSA. If you have already configured X.500 software for your system, you do not have to do it again. To configure the X.500 DUA defaults file, 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. For More Information On X.500 configuration (the Digital X.500 Directory Service Problem Solving guide) 3-8 Server Installation, Startup, and Termination 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 Digital 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. 3.8 Removing the InfoBroker Server and the Look-Up Daemon To permanently remove the InfoBroker server and the Look- Up Daemon, delete all the subsets. Use the following command to list all the installed subsets: # setld -i | grep IBX IBXLOOKUP212 installed InfoBroker Lookup Daemon for Digital UNIX Version V2.1A-2 IBXOAPI212 installed API: InfoBroker for Digital UNIX Version V2.1A-2 IBXOMAN212 installed Ref Pages: InfoBroker for Digital UNIX Version V2.1A-2 IBXOSERV212 installed InfoBroker Server for Digital UNIX Version V2.1A-2 Once you have identified which subsets are installed, you can delete them, for example: # setld -d IBXOSERV212 IBXOMAN212 IBXOAPI212 IBXLOOKUP212 Server Installation, Startup, and Termination 3-11 You should also permanently remove the data directory and the Look-Up Daemon configuration file: o Use the following command to permanently remove the data directory: # rm -r /var/ibx o Use the following command to permanently remove the Look-Up Daemon configuration file: # rm /etc/ibx.conf ________________________Note ________________________ Do not remove the data directory if you want to reinstall the InfoBroker server at a later date. _____________________________________________________ 3-12 Server Installation, Startup, and Termination 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. 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: http://hostname:8888/ Installing and Using Client Software 4-1 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. Installing and Using Client Software 4-3 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. 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-4 Installing and Using Client Software 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.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. Installing and Using Client Software 4-5 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: 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 Digital UNIX 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 Digital UNIX 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. Server Configuration and Customization 5-1 The Digital X.500 DSA must be configured and available (running) before you run the configuration utility and before you start the InfoBroker server. 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 Digital 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 (Digital 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 Server Configuration and Customization 5-3 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 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" 5-4 Server Configuration and Customization create entry /c=us/o=xyz/cn="Margaret Smith" attributes - objectClass=(Top, Person, OrganizationalPerson), - cn=("Margaret", "Margaret Smith"), - sn="Smith" 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" Server Configuration and Customization 5-5 Example 5-1 shows a sample workgroup-directory file. Example 5-1 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" (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="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" 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"